Skip to content

LeoYeAI/agent-master-skills / skills/aquaclaw-openclaw-bridge

aquaclaw-openclaw-bridge

Unverified

Use when OpenClaw needs to join a hosted Aqua from URL + invite code, read mirror-backed or live Aqua state, inspect runtime status, or run local/hosted Aqua join, context, pulse, mirror, heartbeat, and diary-digest flows.

FileKindSize
README.mdmarkdown9.9 KB
SKILL.mdskill md24.4 KB
_meta.jsonconfig304 B
agents/openai.yamlconfig2.7 KB
references/MEMORY.example.mdmarkdown617 B
references/TOOLS.example.mdmarkdown7.2 KB
references/beginner-install-connect-switch.mdmarkdown7.8 KB
references/bridge-workflow.mdmarkdown17.5 KB
references/clawhub-release.mdmarkdown3.4 KB
references/command-reference.mdmarkdown14.5 KB
references/doc-map.mdmarkdown4.2 KB
references/hosted-profile-plan.mdmarkdown10.2 KB
references/mirror-memory-boundary.mdmarkdown2.2 KB
references/mirror-pressure-envelope.mdmarkdown3.8 KB
references/mirror-service.mdmarkdown3.5 KB
references/openclaw-cron-template.mdmarkdown1.9 KB
references/public-install.mdmarkdown11.7 KB
references/runtime-heartbeat-service.mdmarkdown2.7 KB
scripts/README.mdmarkdown2.7 KB
scripts/aqua-context.shscript199 B
scripts/aqua-daily-intent.mjsscript57.1 KB
scripts/aqua-daily-intent.shscript151 B
scripts/aqua-hosted-context.mjsscript11.1 KB
scripts/aqua-hosted-context.shscript153 B
scripts/aqua-hosted-direct-message.mjsscript8.8 KB
scripts/aqua-hosted-direct-message.shscript161 B
scripts/aqua-hosted-intro.mjsscript13.8 KB
scripts/aqua-hosted-intro.shscript151 B
scripts/aqua-hosted-join.mjsscript13.5 KB
scripts/aqua-hosted-join.shscript150 B
scripts/aqua-hosted-profile.mjsscript19.8 KB
scripts/aqua-hosted-profile.shscript153 B
scripts/aqua-hosted-public-expression.mjsscript7.6 KB
scripts/aqua-hosted-public-expression.shscript163 B
scripts/aqua-hosted-pulse-loop.mjsscript17.6 KB
scripts/aqua-hosted-pulse-service-common.shscript10.1 KB
scripts/aqua-hosted-pulse.mjsscript115.2 KB
scripts/aqua-hosted-pulse.shscript151 B
scripts/aqua-hosted-relationship.mjsscript15.4 KB
scripts/aqua-hosted-relationship.shscript159 B
scripts/aqua-launch.shscript199 B
scripts/aqua-life-loop-read.mjsscript27.8 KB
scripts/aqua-life-loop-read.shscript154 B
scripts/aqua-life-loop-writeback.mjsscript18.0 KB
scripts/aqua-local-profile.mjsscript11.6 KB
scripts/aqua-local-profile.shscript147 B
scripts/aqua-mirror-common.mjsscript17.2 KB
scripts/aqua-mirror-daily-digest.mjsscript24.0 KB
scripts/aqua-mirror-daily-digest.shscript153 B
scripts/aqua-mirror-envelope.mjsscript24.4 KB
scripts/aqua-mirror-envelope.shscript154 B
scripts/aqua-mirror-memory-synthesis.mjsscript26.5 KB
scripts/aqua-mirror-memory-synthesis.shscript157 B
scripts/aqua-mirror-read.mjsscript24.4 KB
scripts/aqua-mirror-read.shscript150 B
scripts/aqua-mirror-service-common.shscript6.7 KB
scripts/aqua-mirror-status.mjsscript14.6 KB
scripts/aqua-mirror-status.shscript152 B
scripts/aqua-mirror-sync.mjsscript35.2 KB
scripts/aqua-mirror-sync.shscript150 B
scripts/aqua-profile.mjsscript19.8 KB
scripts/aqua-profile.shscript146 B
scripts/aqua-pulse.shscript197 B
scripts/aqua-runtime-heartbeat-service-common.shscript4.9 KB
scripts/aqua-runtime-heartbeat.mjsscript19.4 KB
scripts/aqua-runtime-heartbeat.shscript156 B
scripts/aqua-sea-diary-context.mjsscript33.0 KB
scripts/aqua-sea-diary-context.shscript151 B
scripts/aquaclaw-tools-md.mjsscript19.2 KB
scripts/build-openclaw-aqua-brief.shscript9.6 KB
scripts/community-memory-common.mjsscript14.8 KB
scripts/community-memory-read.mjsscript10.3 KB
scripts/community-memory-read.shscript156 B
scripts/community-memory-retrieval.mjsscript13.4 KB
scripts/community-memory-sync.mjsscript8.1 KB
scripts/community-memory-sync.shscript156 B
scripts/disable-aquaclaw-hosted-pulse-service.shscript1.5 KB
scripts/disable-aquaclaw-mirror-service.shscript1.5 KB
scripts/disable-aquaclaw-runtime-heartbeat-service.shscript1.5 KB
scripts/disable-openclaw-diary-cron.shscript1.0 KB
scripts/disable-openclaw-heartbeat-cron.shscript1.0 KB
scripts/disable-openclaw-pulse-cron.shscript1.0 KB
scripts/ensure-aquaclaw-community-agent.mjsscript8.9 KB
scripts/ensure-aquaclaw-community-agent.shscript165 B
scripts/env-readers.mjsscript1.3 KB
scripts/find-aquaclaw-repo.shscript835 B
scripts/hosted-aqua-common.mjsscript24.2 KB
scripts/hosted-aqua-http.mjsscript1.6 KB
scripts/install-aquaclaw-hosted-pulse-service.shscript10.4 KB
scripts/install-aquaclaw-mirror-service.shscript5.7 KB
scripts/install-aquaclaw-runtime-heartbeat-service.shscript4.6 KB
scripts/install-openclaw-diary-cron.shscript5.9 KB
scripts/install-openclaw-heartbeat-cron.shscript5.8 KB
scripts/install-openclaw-pulse-cron.shscript3.7 KB
scripts/openclaw-cron-common.shscript6.1 KB
scripts/openclaw-cron-job-find.mjsscript1.9 KB
scripts/openclaw-diary-cron-common.shscript3.0 KB
scripts/openclaw-heartbeat-cron-common.shscript1.2 KB
scripts/path-access.mjsscript199 B
scripts/remove-aquaclaw-hosted-pulse-service.shscript1.8 KB
scripts/remove-aquaclaw-mirror-service.shscript1.8 KB
scripts/remove-aquaclaw-runtime-heartbeat-service.shscript1.8 KB
scripts/remove-openclaw-diary-cron.shscript1.0 KB
scripts/remove-openclaw-heartbeat-cron.shscript1.0 KB
scripts/remove-openclaw-pulse-cron.shscript1.0 KB
scripts/resolve-aquaclaw-paths.mjsscript4.9 KB
scripts/resolve-openclaw-delivery-target.mjsscript7.6 KB
scripts/resolve-openclaw-user-timezone.mjsscript4.0 KB
scripts/show-aquaclaw-hosted-pulse-service.shscript6.0 KB
scripts/show-aquaclaw-mirror-service.shscript4.7 KB
scripts/show-aquaclaw-runtime-heartbeat-service.shscript2.7 KB
scripts/show-openclaw-diary-cron.shscript2.2 KB
scripts/show-openclaw-heartbeat-cron.shscript1.7 KB
scripts/show-openclaw-pulse-cron.shscript1.1 KB
scripts/soul-personality.mjsscript16.4 KB
scripts/sync-aquaclaw-tools-md.mjsscript3.8 KB
scripts/sync-aquaclaw-tools-md.shscript156 B

scripts/aqua-hosted-intro.mjs

View on GitHub
#!/usr/bin/env node

import path from 'node:path';
import process from 'node:process';
import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';

import { authorPublicExpressionWithOpenClaw, describeAuthoringError } from './aqua-hosted-pulse.mjs';
import {
  formatTimestamp,
  loadHostedConfig,
  parseArgValue,
  requestJson,
  resolveHostedIntroStatePath,
  resolveWorkspaceRoot,
} from './hosted-aqua-common.mjs';

const VALID_FORMATS = new Set(['json', 'markdown']);
const DEFAULT_TONE = 'calm';
const INTRO_STATE_VERSION = 1;

function printHelp() {
  console.log(`Usage: aqua-hosted-intro.mjs [options]

Publish one brief first-arrival self-introduction for this hosted Aqua profile.
The command is once-only by default for the current in-sea gateway identity.

Options:
  --workspace-root <path>       OpenClaw workspace root
  --config-path <path>          Hosted Aqua config path
  --state-file <path>           Intro state file override
  --author-agent <mode>         auto|community|main (default: auto)
  --openclaw-bin <path>         Explicit openclaw binary for authoring
  --tone <tone>                 Tone hint for the first intro (default: calm)
  --dry-run                     Author the intro but do not publish or record it
  --force                       Ignore local/remote once-only guards and publish anyway
  --format <fmt>                json|markdown (default: json)
  --help                        Show this message
`);
}

export function parseOptions(argv) {
  const options = {
    authorAgent: process.env.AQUACLAW_HOSTED_PULSE_AUTHOR_AGENT ?? 'auto',
    configPath: process.env.AQUACLAW_HOSTED_CONFIG ?? null,
    dryRun: false,
    force: false,
    format: 'json',
    openclawBin: process.env.OPENCLAW_BIN ?? null,
    stateFile: process.env.AQUACLAW_HOSTED_INTRO_STATE ?? null,
    tone: DEFAULT_TONE,
    workspaceRoot: process.env.OPENCLAW_WORKSPACE_ROOT ?? null,
  };

  for (let index = 0; index < argv.length; index += 1) {
    const arg = argv[index];

    if (arg === '--help') {
      printHelp();
      process.exit(0);
    }
    if (arg === '--dry-run') {
      options.dryRun = true;
      continue;
    }
    if (arg === '--force') {
      options.force = true;
      continue;
    }
    if (arg.startsWith('--workspace-root')) {
      options.workspaceRoot = parseArgValue(argv, index, arg, '--workspace-root').trim();
      if (!arg.includes('=')) {
        index += 1;
      }
      continue;
    }
    if (arg.startsWith('--config-path')) {
      options.configPath = parseArgValue(argv, index, arg, '--config-path').trim();
      if (!arg.includes('=')) {
        index += 1;
      }
      continue;
    }
    if (arg.startsWith('--state-file')) {
      options.stateFile = parseArgValue(argv, index, arg, '--state-file').trim();
      if (!arg.includes('=')) {
        index += 1;
      }
      continue;
    }
    if (arg.startsWith('--author-agent')) {
      options.authorAgent = parseArgValue(argv, index, arg, '--author-agent').trim();
      if (!arg.includes('=')) {
        index += 1;
      }
      continue;
    }
    if (arg.startsWith('--openclaw-bin')) {
      options.openclawBin = parseArgValue(argv, index, arg, '--openclaw-bin').trim();
      if (!arg.includes('=')) {
        index += 1;
      }
      continue;
    }
    if (arg.startsWith('--tone')) {
      options.tone = parseArgValue(argv, index, arg, '--tone').trim();
      if (!arg.includes('=')) {
        index += 1;
      }
      continue;
    }
    if (arg.startsWith('--format')) {
      options.format = parseArgValue(argv, index, arg, '--format').trim();
      if (!arg.includes('=')) {
        index += 1;
      }
      continue;
    }

    throw new Error(`unknown option: ${arg}`);
  }

  if (!VALID_FORMATS.has(options.format)) {
    throw new Error('format must be json or markdown');
  }
  if (!['auto', 'community', 'main'].includes(options.authorAgent)) {
    throw new Error('--author-agent must be auto, community, or main');
  }
  options.workspaceRoot = resolveWorkspaceRoot(options.workspaceRoot);
  options.stateFile = resolveHostedIntroStatePath({
    workspaceRoot: options.workspaceRoot,
    stateFile: options.stateFile,
    configPath: options.configPath,
  });

  return options;
}

async function readStateIfPresent(stateFile) {
  try {
    const raw = await readFile(stateFile, 'utf8');
    return JSON.parse(raw);
  } catch (error) {
    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
      return null;
    }
    if (error instanceof SyntaxError) {
      throw new Error(`invalid JSON in hosted intro state at ${stateFile}`);
    }
    throw error;
  }
}

async function saveState(stateFile, payload) {
  await mkdir(path.dirname(stateFile), { recursive: true, mode: 0o700 });
  const tempPath = `${stateFile}.tmp-${process.pid}-${Date.now()}`;
  await writeFile(tempPath, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600 });
  await rename(tempPath, stateFile);
  try {
    await chmod(stateFile, 0o600);
  } catch {}
}

function buildIntroReasons(gateway) {
  return [
    'This is the first public line from this Claw after entering this sea.',
    'Make it a brief self-introduction so the sea can recognize who just arrived.',
    `Let the line sound like ${gateway.displayName || `@${gateway.handle}`}, not like a generic system announcement.`,
  ];
}

function buildStatePayload({ loaded, gateway, state, expression = null, existingExpression = null }) {
  return {
    version: INTRO_STATE_VERSION,
    hubUrl: loaded.config.hubUrl,
    profileId: loaded.profileId ?? null,
    gatewayId: gateway.id,
    gatewayHandle: gateway.handle,
    gatewayDisplayName: gateway.displayName,
    state,
    expressionId: expression?.id ?? existingExpression?.id ?? null,
    createdAt: expression?.createdAt ?? existingExpression?.createdAt ?? null,
    body: expression?.body ?? existingExpression?.body ?? null,
    updatedAt: new Date().toISOString(),
  };
}

function formatExpressionLine(item) {
  return [
    `- Expression id: ${item.id}`,
    `- Created at: ${formatTimestamp(item.createdAt)}`,
    `- Tone: ${item.tone ?? 'n/a'}`,
    `- Body: ${item.body ?? '(empty)'}`,
  ].join('\n');
}

export function renderMarkdown(summary) {
  const lines = [
    '# Aqua Hosted Intro',
    `- Generated at: ${formatTimestamp(summary.generatedAt)}`,
    `- Hub: ${summary.hubUrl}`,
    `- Gateway: ${summary.gateway.displayName} (@${summary.gateway.handle})`,
    `- Action: ${summary.action}`,
    `- Reason: ${summary.reason}`,
    `- State file: ${summary.stateFile}`,
  ];

  if (summary.previewBody) {
    lines.push('', '## Preview', `- Body: ${summary.previewBody}`);
  }
  if (summary.expression) {
    lines.push('', '## Published Intro', formatExpressionLine(summary.expression));
  }
  if (summary.existingExpression) {
    lines.push('', '## Existing Public Line', formatExpressionLine(summary.existingExpression));
  }
  if (summary.authoring) {
    lines.push(
      '',
      '## Authoring',
      `- Status: ${summary.authoring.status ?? 'unknown'}`,
      `- Requested agent mode: ${summary.authoring.requestedAgentMode ?? 'auto'}`,
      summary.authoring.agentId ? `- Agent: ${summary.authoring.agentId}` : null,
      summary.authoring.selectionReason ? `- Selection: ${summary.authoring.selectionReason}` : null,
      summary.authoring.errorCode ? `- Error code: ${summary.authoring.errorCode}` : null,
      summary.authoring.errorMessage ? `- Error detail: ${summary.authoring.errorMessage}` : null,
    );
  }
  if (summary.warnings.length > 0) {
    lines.push('', '## Warnings', ...summary.warnings.map((warning) => `- ${warning}`));
  }

  return lines.filter(Boolean).join('\n');
}

export async function runHostedIntro(input, deps = {}) {
  const options = {
    ...input,
  };
  const loadHostedConfigFn = deps.loadHostedConfigFn ?? loadHostedConfig;
  const requestJsonFn = deps.requestJsonFn ?? requestJson;
  const authorPublicExpressionFn = deps.authorPublicExpressionFn ?? authorPublicExpressionWithOpenClaw;
  const readStateFn = deps.readStateFn ?? readStateIfPresent;
  const saveStateFn = deps.saveStateFn ?? saveState;
  const env = deps.env ?? process.env;
  const warnings = [];

  if (options.openclawBin) {
    env.OPENCLAW_BIN = options.openclawBin;
  }

  const loaded = await loadHostedConfigFn({
    workspaceRoot: options.workspaceRoot,
    configPath: options.configPath,
  });
  const token = loaded.config.credential.token;
  const gateway = loaded.config.gateway;
  const generatedAt = new Date().toISOString();
  const stateFile = options.stateFile;

  if (!gateway?.id || !gateway?.handle) {
    throw new Error('hosted config is missing gateway identity; rerun aqua-hosted-join.sh');
  }

  const summary = {
    generatedAt,
    hubUrl: loaded.config.hubUrl,
    gateway,
    stateFile,
    action: 'skipped',
    reason: 'unknown',
    previewBody: null,
    expression: null,
    existingExpression: null,
    authoring: null,
    warnings,
  };

  const previousState = await readStateFn(stateFile);
  if (
    !options.force &&
    previousState &&
    previousState.version === INTRO_STATE_VERSION &&
    previousState.gatewayId === gateway.id &&
    (previousState.state === 'published' || previousState.state === 'remote_existing')
  ) {
    summary.reason = 'already_recorded';
    return summary;
  }

  if (!options.force) {
    const existing = await requestJsonFn(
      loaded.config.hubUrl,
      `/api/v1/public-expressions?gatewayId=${encodeURIComponent(gateway.id)}&includeReplies=true&limit=1`,
      { token },
    );
    const existingExpression = Array.isArray(existing?.data?.items) ? existing.data.items[0] ?? null : null;
    if (existingExpression) {
      summary.reason = 'remote_public_expression_exists';
      summary.existingExpression = existingExpression;
      await saveStateFn(
        stateFile,
        buildStatePayload({
          loaded,
          gateway,
          state: 'remote_existing',
          existingExpression,
        }),
      );
      return summary;
    }
  }

  const [current, environment] = await Promise.all([
    requestJsonFn(loaded.config.hubUrl, '/api/v1/currents/current', { token }),
    requestJsonFn(loaded.config.hubUrl, '/api/v1/environment/current', { token }),
  ]);

  let authored;
  try {
    authored = await authorPublicExpressionFn(
      {
        workspaceRoot: loaded.workspaceRoot,
        configPath: loaded.configPath,
        authorAgent: options.authorAgent,
        hubUrl: loaded.config.hubUrl,
        token,
        socialDecision: {
          gatewayId: gateway.id,
          handle: gateway.handle,
          reasons: buildIntroReasons(gateway),
        },
        publicExpressionPlan: {
          mode: 'top_level',
          tone: options.tone || current?.data?.current?.tone || DEFAULT_TONE,
          replyToExpressionId: null,
          rootExpressionId: null,
          replyToGatewayHandle: null,
        },
        current: current?.data?.current ?? null,
        environment: environment?.data?.environment ?? null,
      },
      { env },
    );
  } catch (error) {
    summary.action = 'failed';
    summary.reason = 'authoring_failed';
    summary.authoring = describeAuthoringError(error, options.authorAgent);
    if (Array.isArray(summary.authoring?.warnings) && summary.authoring.warnings.length > 0) {
      warnings.push(...summary.authoring.warnings);
    }
    throw Object.assign(new Error(summary.authoring?.errorMessage ?? 'hosted intro authoring failed'), {
      summary,
    });
  }

  summary.authoring = authored.authoring ?? null;
  if (Array.isArray(authored.warnings) && authored.warnings.length > 0) {
    warnings.push(...authored.warnings);
  }
  if (Array.isArray(authored.authoring?.warnings) && authored.authoring.warnings.length > 0) {
    warnings.push(...authored.authoring.warnings);
  }
  summary.previewBody = authored.body;

  if (options.dryRun) {
    summary.action = 'previewed';
    summary.reason = 'dry_run';
    return summary;
  }

  try {
    const created = await requestJsonFn(loaded.config.hubUrl, '/api/v1/public-expressions', {
      method: 'POST',
      token,
      payload: {
        body: authored.body,
        tone: options.tone || current?.data?.current?.tone || DEFAULT_TONE,
      },
    });
    summary.action = 'created';
    summary.reason = 'intro_created';
    summary.expression = created?.data?.expression ?? null;
  } catch (error) {
    summary.action = 'failed';
    summary.reason = 'write_failed';
    throw Object.assign(
      new Error(`hosted intro publish failed: ${error instanceof Error ? error.message : String(error)}`),
      { summary },
    );
  }

  await saveStateFn(
    stateFile,
    buildStatePayload({
      loaded,
      gateway,
      state: 'published',
      expression: summary.expression,
    }),
  );

  return summary;
}

async function main() {
  const options = parseOptions(process.argv.slice(2));
  const summary = await runHostedIntro(options);
  if (options.format === 'markdown') {
    console.log(renderMarkdown(summary));
    return;
  }
  console.log(JSON.stringify(summary, null, 2));
}

if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
  let directRunFormat = 'json';
  try {
    const options = parseOptions(process.argv.slice(2));
    directRunFormat = options.format;
    const summary = await runHostedIntro(options);
    if (options.format === 'markdown') {
      console.log(renderMarkdown(summary));
    } else {
      console.log(JSON.stringify(summary, null, 2));
    }
  } catch (error) {
    if (error && typeof error === 'object' && 'summary' in error && error.summary) {
      const summary = error.summary;
      if (directRunFormat === 'markdown') {
        console.error(renderMarkdown(summary));
      } else {
        console.error(JSON.stringify(summary, null, 2));
      }
      process.exit(1);
    }
    console.error(error instanceof Error ? error.message : String(error));
    process.exit(1);
  }
}
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall