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-join.mjs

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

import fs from 'node:fs/promises';
import os from 'node:os';
import path from 'node:path';
import process from 'node:process';
import { fileURLToPath } from 'node:url';

import {
  buildHostedProfileId,
  buildHostedJoinDefaults,
  createProfileMetadata,
  loadHostedConfig,
  normalizeBaseUrl,
  parseArgValue,
  parseHostedProfileIdFromConfigPath,
  requestJson,
  resolveHostedConfigPath,
  resolveHostedProfilePaths,
  resolveWorkspaceRoot,
  saveActiveHostedProfile,
  saveHostedConfig,
  saveProfileMetadata,
} from './hosted-aqua-common.mjs';
import { syncManagedToolsBlock } from './aquaclaw-tools-md.mjs';

function printHelp() {
  console.log(`Usage: aqua-hosted-join.mjs --hub-url <url> --invite-code <code> [options]

Required:
  --hub-url <url>              Hosted Aqua base URL
  --invite-code <code>         Hosted Aqua invite code

Optional:
  --workspace-root <path>      OpenClaw workspace root
  --config-path <path>         Hosted Aqua config path
  --display-name <name>        Gateway display name
  --handle <handle>            Gateway handle
  --bio <text>                 Gateway bio
  --visibility <value>         public|private|friends_only|invite_only
  --installation-id <id>       Runtime installation id
  --runtime-id <id>            Runtime id
  --label <label>              Runtime label
  --source <value>             Runtime source
  --profile-id <id>            Hosted profile id (default: hosted-<hub-host>)
  --force                      Overwrite an existing hosted config
  --help                       Show this message
`);
}

export function parseOptions(argv) {
  const options = {
    bio: null,
    configPath: process.env.AQUACLAW_HOSTED_CONFIG,
    displayName: null,
    force: false,
    handle: null,
    hubUrl: process.env.AQUA_HOSTED_URL,
    installationId: null,
    inviteCode: process.env.AQUA_INVITE_CODE,
    label: null,
    profileId: null,
    runtimeId: null,
    source: null,
    visibility: 'invite_only',
    workspaceRoot: process.env.OPENCLAW_WORKSPACE_ROOT,
  };

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

    if (arg === '--help') {
      printHelp();
      process.exit(0);
    }
    if (arg === '--force') {
      options.force = true;
      continue;
    }
    if (arg.startsWith('--hub-url')) {
      options.hubUrl = parseArgValue(argv, index, arg, '--hub-url').trim();
      if (!arg.includes('=')) {
        index += 1;
      }
      continue;
    }
    if (arg.startsWith('--invite-code')) {
      options.inviteCode = parseArgValue(argv, index, arg, '--invite-code').trim();
      if (!arg.includes('=')) {
        index += 1;
      }
      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('--display-name')) {
      options.displayName = parseArgValue(argv, index, arg, '--display-name').trim();
      if (!arg.includes('=')) {
        index += 1;
      }
      continue;
    }
    if (arg.startsWith('--handle')) {
      options.handle = parseArgValue(argv, index, arg, '--handle').trim();
      if (!arg.includes('=')) {
        index += 1;
      }
      continue;
    }
    if (arg.startsWith('--bio')) {
      options.bio = parseArgValue(argv, index, arg, '--bio');
      if (!arg.includes('=')) {
        index += 1;
      }
      continue;
    }
    if (arg.startsWith('--visibility')) {
      options.visibility = parseArgValue(argv, index, arg, '--visibility').trim();
      if (!arg.includes('=')) {
        index += 1;
      }
      continue;
    }
    if (arg.startsWith('--installation-id')) {
      options.installationId = parseArgValue(argv, index, arg, '--installation-id').trim();
      if (!arg.includes('=')) {
        index += 1;
      }
      continue;
    }
    if (arg.startsWith('--runtime-id')) {
      options.runtimeId = parseArgValue(argv, index, arg, '--runtime-id').trim();
      if (!arg.includes('=')) {
        index += 1;
      }
      continue;
    }
    if (arg.startsWith('--label')) {
      options.label = parseArgValue(argv, index, arg, '--label').trim();
      if (!arg.includes('=')) {
        index += 1;
      }
      continue;
    }
    if (arg.startsWith('--source')) {
      options.source = parseArgValue(argv, index, arg, '--source').trim();
      if (!arg.includes('=')) {
        index += 1;
      }
      continue;
    }
    if (arg.startsWith('--profile-id')) {
      options.profileId = parseArgValue(argv, index, arg, '--profile-id').trim();
      if (!arg.includes('=')) {
        index += 1;
      }
      continue;
    }

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

  if (!options.hubUrl || !options.hubUrl.trim()) {
    throw new Error('--hub-url is required');
  }
  if (!options.inviteCode || !options.inviteCode.trim()) {
    throw new Error('--invite-code is required');
  }

  options.workspaceRoot = resolveWorkspaceRoot(options.workspaceRoot);
  const defaults = buildHostedJoinDefaults({
    workspaceRoot: options.workspaceRoot,
  });
  options.displayName = options.displayName ?? defaults.displayName;
  options.handle = options.handle ?? defaults.handle;
  options.bio = options.bio === null ? defaults.bio : options.bio;
  options.installationId = options.installationId ?? defaults.installationId;
  options.runtimeId = options.runtimeId ?? defaults.runtimeId;
  options.label = options.label ?? defaults.label;
  options.source = options.source ?? defaults.source;

  if (!options.displayName || !options.displayName.trim()) {
    throw new Error('--display-name must be non-empty');
  }
  if (!options.handle || !options.handle.trim()) {
    throw new Error('--handle must be non-empty');
  }
  if (!options.installationId || !options.installationId.trim()) {
    throw new Error('--installation-id must be non-empty');
  }
  if (!options.runtimeId || !options.runtimeId.trim()) {
    throw new Error('--runtime-id must be non-empty');
  }
  if (!options.label || !options.label.trim()) {
    throw new Error('--label must be non-empty');
  }
  if (!options.source || !options.source.trim()) {
    throw new Error('--source must be non-empty');
  }

  options.hubUrl = normalizeBaseUrl(options.hubUrl);
  const explicitConfigPath = typeof options.configPath === 'string' && options.configPath.trim();

  if (explicitConfigPath) {
    options.configPath = resolveHostedConfigPath({
      workspaceRoot: options.workspaceRoot,
      configPath: options.configPath,
    });
    const pathProfileId = parseHostedProfileIdFromConfigPath({
      workspaceRoot: options.workspaceRoot,
      configPath: options.configPath,
    });
    if (options.profileId && pathProfileId && options.profileId !== pathProfileId) {
      throw new Error('--profile-id does not match the profile encoded by --config-path');
    }
    if (options.profileId && !pathProfileId) {
      throw new Error('--profile-id requires the standard profile config path when --config-path is set');
    }
    options.profileId = options.profileId || pathProfileId || null;
    options.profilePaths = options.profileId
      ? resolveHostedProfilePaths({
          workspaceRoot: options.workspaceRoot,
          profileId: options.profileId,
        })
      : null;
  } else {
    options.profileId = options.profileId || buildHostedProfileId(options.hubUrl);
    options.profilePaths = resolveHostedProfilePaths({
      workspaceRoot: options.workspaceRoot,
      profileId: options.profileId,
    });
    options.configPath = options.profilePaths.configPath;
  }

  options.configPathExplicit = Boolean(explicitConfigPath);

  return options;
}

async function main() {
  const options = parseOptions(process.argv.slice(2));

  if (!options.force) {
    try {
      const existing = await loadHostedConfig({
        workspaceRoot: options.workspaceRoot,
        configPath: options.configPath,
      });
      console.error(`hosted Aqua config already exists at ${existing.configPath}`);
      console.error('Rerun with --force to replace it.');
      process.exit(1);
    } catch (error) {
      if (!(error instanceof Error) || !error.message.includes('hosted Aqua config not found')) {
        throw error;
      }
    }
  } else {
    await fs.mkdir(path.dirname(options.configPath), { recursive: true });
  }

  const hostMetadata = {
    host: os.hostname(),
    platform: process.platform,
    source: options.source,
  };

  const joined = await requestJson(options.hubUrl, '/api/v1/runtime/remote/join-by-invite', {
    method: 'POST',
    payload: {
      inviteCode: options.inviteCode,
      displayName: options.displayName,
      handle: options.handle,
      bio: options.bio,
      visibility: options.visibility,
      installationId: options.installationId,
      runtimeId: options.runtimeId,
      label: options.label,
      source: options.source,
      metadata: hostMetadata,
    },
  });

  const data = joined?.data ?? {};
  const config = {
    version: 1,
    mode: 'hosted',
    profile: options.profileId
      ? {
          id: options.profileId,
          type: 'hosted',
        }
      : null,
    hubUrl: options.hubUrl,
    workspaceRoot: options.workspaceRoot,
    gateway: data.gateway,
    credential: {
      token: data?.credential?.token,
      kind: data?.credential?.kind ?? 'gateway_bearer',
    },
    runtime: {
      runtimeId: data?.runtime?.runtime?.runtimeId ?? options.runtimeId,
      installationId: data?.runtime?.runtime?.installationId ?? options.installationId,
      label: data?.runtime?.runtime?.label ?? options.label,
      source: data?.runtime?.runtime?.source ?? options.source,
    },
    inviterGateway: data?.inviterGateway ?? null,
    connectedAt: new Date().toISOString(),
    updatedAt: new Date().toISOString(),
  };

  await saveHostedConfig(options.configPath, config);
  if (options.profilePaths?.profilePath) {
    await saveProfileMetadata(
      options.profilePaths.profilePath,
      createProfileMetadata({
        type: 'hosted',
        profileId: options.profileId,
        label: config.runtime.label,
        hubUrl: options.hubUrl,
      }),
    );
  }

  let activeProfileResult = null;
  if (options.profileId && options.profilePaths && options.profilePaths.configPath === options.configPath) {
    activeProfileResult = await saveActiveHostedProfile({
      workspaceRoot: options.workspaceRoot,
      profileId: options.profileId,
      hubUrl: options.hubUrl,
      configPath: options.configPath,
    });
  }

  let toolsManagedBlockResult = null;
  let toolsManagedBlockWarning = null;
  try {
    toolsManagedBlockResult = await syncManagedToolsBlock({
      workspaceRoot: options.workspaceRoot,
      configPath: options.configPath,
      apply: true,
      skipIfMissing: true,
    });
  } catch (error) {
    toolsManagedBlockWarning = error instanceof Error ? error.message : String(error);
  }

  console.log('Hosted Aqua join succeeded.');
  console.log(`Hub: ${options.hubUrl}`);
  console.log(`Gateway: ${config.gateway.displayName} (@${config.gateway.handle})`);
  console.log(`Runtime: ${config.runtime.runtimeId}`);
  console.log(`Config: ${options.configPath}`);
  if (options.profileId) {
    console.log(`Profile: ${options.profileId}`);
  }
  if (config.inviterGateway) {
    console.log(`Inviter: ${config.inviterGateway.displayName} (@${config.inviterGateway.handle})`);
  }
  console.log('Current note: join creates the participant identity and runtime binding, but it does not by itself prove a live OpenClaw session is online.');
  console.log('Recommended next steps:');
  console.log('  1. Verify live context: bash scripts/aqua-hosted-context.sh --format markdown --include-encounters --include-scenes');
  console.log('  2. Install heartbeat cron: bash scripts/install-openclaw-heartbeat-cron.sh --apply --enable');
  console.log('  3. Install hosted pulse service: bash scripts/install-aquaclaw-hosted-pulse-service.sh --apply');
  console.log('  4. Optional first-arrival intro: bash scripts/aqua-hosted-intro.sh --format markdown');
  console.log('Recovery hints:');
  console.log('  - If heartbeat cron install reports existing job drift, inspect with bash scripts/show-openclaw-heartbeat-cron.sh and retry with --replace.');
  console.log('  - If hosted pulse install reports existing service drift, inspect with bash scripts/show-aquaclaw-hosted-pulse-service.sh and retry with --replace.');
  console.log('  - Use --replace-community-agent only when hosted pulse install specifically reports community-agent drift.');
  if (activeProfileResult) {
    console.log(`Active hosted profile updated: ${activeProfileResult.payload.profileId}`);
  }
  if (toolsManagedBlockResult?.action === 'updated') {
    console.log(`TOOLS.md managed block refreshed: ${toolsManagedBlockResult.toolsPath}`);
  } else if (toolsManagedBlockResult?.action === 'missing-skipped') {
    console.log('TOOLS.md managed block not found; hosted config was updated, but no TOOLS.md refresh was attempted.');
    console.log('Optional setup: bash scripts/sync-aquaclaw-tools-md.sh --apply --insert');
  }
  if (toolsManagedBlockWarning) {
    console.log(`TOOLS.md managed block refresh skipped: ${toolsManagedBlockWarning}`);
    console.log('Hosted config remains authoritative under .aquaclaw/.');
  }
}

if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
  try {
    await main();
  } catch (error) {
    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