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/hosted-aqua-common.mjs

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

import { randomBytes } from 'node:crypto';
import { readFileSync } from 'node:fs';
import { chmod, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
import os from 'node:os';
import path from 'node:path';
import process from 'node:process';
import { deriveGatewayBioFromSoul, deriveGatewayDisplayNameFromSoul } from './soul-personality.mjs';
export { requestJson } from './hosted-aqua-http.mjs';

export const DEFAULT_WORKSPACE_ROOT = path.join(os.homedir(), '.openclaw', 'workspace');
export const DEFAULT_AQUACLAW_STATE_RELATIVE_DIR = '.aquaclaw';
export const DEFAULT_HOSTED_CONFIG_FILE_NAME = 'hosted-bridge.json';
export const DEFAULT_HOSTED_PULSE_STATE_FILE_NAME = 'hosted-pulse-state.json';
export const DEFAULT_HOSTED_INTRO_STATE_FILE_NAME = 'hosted-intro-state.json';
export const DEFAULT_HEARTBEAT_STATE_FILE_NAME = 'runtime-heartbeat-state.json';
export const DEFAULT_MIRROR_DIR_NAME = 'mirror';
export const DEFAULT_COMMUNITY_MEMORY_DIR_NAME = 'community-memory';
export const DEFAULT_ACTIVE_PROFILE_FILE_NAME = 'active-profile.json';
export const DEFAULT_PROFILE_METADATA_FILE_NAME = 'profile.json';
export const DEFAULT_LOCAL_PROFILE_ID = 'local-default';
export const ACTIVE_PROFILE_POINTER_VERSION = 1;
export const ACTIVE_HOSTED_PROFILE_POINTER_VERSION = ACTIVE_PROFILE_POINTER_VERSION;
const DEFAULT_HOSTED_CONFIG_RELATIVE_PATH = path.join(
  DEFAULT_AQUACLAW_STATE_RELATIVE_DIR,
  DEFAULT_HOSTED_CONFIG_FILE_NAME,
);
const DEFAULT_HOSTED_PULSE_STATE_RELATIVE_PATH = path.join(
  DEFAULT_AQUACLAW_STATE_RELATIVE_DIR,
  DEFAULT_HOSTED_PULSE_STATE_FILE_NAME,
);
const DEFAULT_HOSTED_INTRO_STATE_RELATIVE_PATH = path.join(
  DEFAULT_AQUACLAW_STATE_RELATIVE_DIR,
  DEFAULT_HOSTED_INTRO_STATE_FILE_NAME,
);
const DEFAULT_HEARTBEAT_STATE_RELATIVE_PATH = path.join(
  DEFAULT_AQUACLAW_STATE_RELATIVE_DIR,
  DEFAULT_HEARTBEAT_STATE_FILE_NAME,
);
const DEFAULT_MIRROR_RELATIVE_DIR = path.join(DEFAULT_AQUACLAW_STATE_RELATIVE_DIR, DEFAULT_MIRROR_DIR_NAME);
const DEFAULT_COMMUNITY_MEMORY_RELATIVE_DIR = path.join(
  DEFAULT_AQUACLAW_STATE_RELATIVE_DIR,
  DEFAULT_COMMUNITY_MEMORY_DIR_NAME,
);
const DEFAULT_ACTIVE_PROFILE_RELATIVE_PATH = path.join(
  DEFAULT_AQUACLAW_STATE_RELATIVE_DIR,
  DEFAULT_ACTIVE_PROFILE_FILE_NAME,
);
const DEFAULT_PROFILES_RELATIVE_DIR = path.join(DEFAULT_AQUACLAW_STATE_RELATIVE_DIR, 'profiles');

export function parseArgValue(argv, index, current, label) {
  if (current.includes('=')) {
    return current.slice(current.indexOf('=') + 1);
  }

  const next = argv[index + 1];
  if (!next || next.startsWith('--')) {
    throw new Error(`${label} requires a value`);
  }

  return next;
}

export function normalizeBaseUrl(raw) {
  const url = new URL(String(raw).trim());
  url.pathname = '';
  url.search = '';
  url.hash = '';
  return url.toString().replace(/\/$/, '');
}

export function resolveWorkspaceRoot(raw = process.env.OPENCLAW_WORKSPACE_ROOT) {
  const value = typeof raw === 'string' && raw.trim() ? raw.trim() : DEFAULT_WORKSPACE_ROOT;
  return path.resolve(value);
}

export function resolveAquaclawStateRoot(workspaceRoot = process.env.OPENCLAW_WORKSPACE_ROOT) {
  return path.join(resolveWorkspaceRoot(workspaceRoot), DEFAULT_AQUACLAW_STATE_RELATIVE_DIR);
}

export function resolveActiveHostedProfilePath({
  workspaceRoot = process.env.OPENCLAW_WORKSPACE_ROOT,
} = {}) {
  return path.join(resolveWorkspaceRoot(workspaceRoot), DEFAULT_ACTIVE_PROFILE_RELATIVE_PATH);
}

export function resolveHostedProfilesRoot({
  workspaceRoot = process.env.OPENCLAW_WORKSPACE_ROOT,
} = {}) {
  return path.join(resolveWorkspaceRoot(workspaceRoot), DEFAULT_PROFILES_RELATIVE_DIR);
}

export function slugifySegment(value, fallback) {
  const normalized = String(value || '')
    .trim()
    .toLowerCase()
    .replace(/[^a-z0-9]+/g, '-')
    .replace(/^-+|-+$/g, '');

  return normalized || fallback;
}

export function buildHostedProfileId(baseUrl) {
  const host = new URL(normalizeBaseUrl(baseUrl)).host;
  return `hosted-${slugifySegment(host, 'hosted-default')}`;
}

export function resolveHostedProfilePaths({
  workspaceRoot = process.env.OPENCLAW_WORKSPACE_ROOT,
  profileId,
} = {}) {
  if (typeof profileId !== 'string' || !profileId.trim()) {
    throw new Error('profileId is required');
  }

  const resolvedWorkspaceRoot = resolveWorkspaceRoot(workspaceRoot);
  const resolvedProfileId = profileId.trim();
  const profileRoot = path.join(
    resolveHostedProfilesRoot({ workspaceRoot: resolvedWorkspaceRoot }),
    resolvedProfileId,
  );

  return {
    workspaceRoot: resolvedWorkspaceRoot,
    profileId: resolvedProfileId,
    profileRoot,
    profilePath: path.join(profileRoot, DEFAULT_PROFILE_METADATA_FILE_NAME),
    configPath: path.join(profileRoot, DEFAULT_HOSTED_CONFIG_FILE_NAME),
    pulseStatePath: path.join(profileRoot, DEFAULT_HOSTED_PULSE_STATE_FILE_NAME),
    introStatePath: path.join(profileRoot, DEFAULT_HOSTED_INTRO_STATE_FILE_NAME),
    heartbeatStatePath: path.join(profileRoot, DEFAULT_HEARTBEAT_STATE_FILE_NAME),
    mirrorRoot: path.join(profileRoot, DEFAULT_MIRROR_DIR_NAME),
    communityMemoryRoot: path.join(profileRoot, DEFAULT_COMMUNITY_MEMORY_DIR_NAME),
    activeProfilePath: resolveActiveHostedProfilePath({ workspaceRoot: resolvedWorkspaceRoot }),
  };
}

function readJsonFileSyncIfPresent(filePath) {
  try {
    const raw = readFileSync(filePath, '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 at ${filePath}`);
    }
    throw error;
  }
}

function normalizeActiveProfilePointer(pointer, pointerPath) {
  if (!pointer || typeof pointer !== 'object') {
    throw new Error(`invalid active hosted profile pointer at ${pointerPath}`);
  }
  if (pointer.version !== ACTIVE_PROFILE_POINTER_VERSION) {
    throw new Error(`unsupported active hosted profile pointer version at ${pointerPath}`);
  }
  if (pointer.type !== 'hosted' && pointer.type !== 'local') {
    throw new Error(`invalid active profile pointer type at ${pointerPath}`);
  }
  if (typeof pointer.profileId !== 'string' || !pointer.profileId.trim()) {
    throw new Error(`missing profileId in active hosted profile pointer at ${pointerPath}`);
  }

  return {
    version: ACTIVE_PROFILE_POINTER_VERSION,
    type: pointer.type,
    profileId: pointer.profileId.trim(),
    hubUrl: typeof pointer.hubUrl === 'string' && pointer.hubUrl.trim() ? pointer.hubUrl.trim() : null,
    configPath:
      typeof pointer.configPath === 'string' && pointer.configPath.trim() ? path.resolve(pointer.configPath) : null,
    updatedAt: typeof pointer.updatedAt === 'string' && pointer.updatedAt.trim() ? pointer.updatedAt.trim() : null,
  };
}

export function loadActiveProfileSync({
  workspaceRoot = process.env.OPENCLAW_WORKSPACE_ROOT,
} = {}) {
  const pointerPath = resolveActiveHostedProfilePath({ workspaceRoot });
  const pointer = readJsonFileSyncIfPresent(pointerPath);
  if (pointer === null) {
    return {
      pointer: null,
      pointerPath,
    };
  }

  return {
    pointer: normalizeActiveProfilePointer(pointer, pointerPath),
    pointerPath,
  };
}

export function loadActiveHostedProfileSync({
  workspaceRoot = process.env.OPENCLAW_WORKSPACE_ROOT,
} = {}) {
  const active = loadActiveProfileSync({ workspaceRoot });
  return {
    pointer: active.pointer?.type === 'hosted' ? active.pointer : null,
    pointerPath: active.pointerPath,
  };
}

export function parseHostedProfileIdFromConfigPath({
  workspaceRoot = process.env.OPENCLAW_WORKSPACE_ROOT,
  configPath,
} = {}) {
  if (typeof configPath !== 'string' || !configPath.trim()) {
    return null;
  }

  const resolvedConfigPath = path.resolve(configPath);
  const profilesRoot = resolveHostedProfilesRoot({ workspaceRoot });
  const relative = path.relative(profilesRoot, resolvedConfigPath);
  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
    return null;
  }

  const parts = relative.split(path.sep).filter(Boolean);
  if (parts.length === 2 && parts[1] === DEFAULT_HOSTED_CONFIG_FILE_NAME) {
    return parts[0];
  }

  return null;
}

export function resolveHostedConfigSelection({
  workspaceRoot = process.env.OPENCLAW_WORKSPACE_ROOT,
  configPath = process.env.AQUACLAW_HOSTED_CONFIG,
} = {}) {
  const resolvedWorkspaceRoot = resolveWorkspaceRoot(workspaceRoot);
  const explicit = typeof configPath === 'string' && configPath.trim() ? path.resolve(configPath.trim()) : null;

  if (explicit) {
    const profileId = parseHostedProfileIdFromConfigPath({
      workspaceRoot: resolvedWorkspaceRoot,
      configPath: explicit,
    });
    const profilePaths = profileId
      ? resolveHostedProfilePaths({ workspaceRoot: resolvedWorkspaceRoot, profileId })
      : null;
    return {
      workspaceRoot: resolvedWorkspaceRoot,
      configPath: explicit,
      profileId,
      profileRoot: profilePaths?.profileRoot ?? null,
      selectionKind: 'explicit',
      activePointer: null,
      activeProfilePath: resolveActiveHostedProfilePath({ workspaceRoot: resolvedWorkspaceRoot }),
    };
  }

  const active = loadActiveHostedProfileSync({ workspaceRoot: resolvedWorkspaceRoot });
  if (active.pointer?.profileId) {
    const profilePaths = resolveHostedProfilePaths({
      workspaceRoot: resolvedWorkspaceRoot,
      profileId: active.pointer.profileId,
    });
    return {
      workspaceRoot: resolvedWorkspaceRoot,
      configPath: profilePaths.configPath,
      profileId: profilePaths.profileId,
      profileRoot: profilePaths.profileRoot,
      selectionKind: 'active-profile',
      activePointer: active.pointer,
      activeProfilePath: active.pointerPath,
    };
  }

  return {
    workspaceRoot: resolvedWorkspaceRoot,
    configPath: path.join(resolvedWorkspaceRoot, DEFAULT_HOSTED_CONFIG_RELATIVE_PATH),
    profileId: null,
    profileRoot: null,
    selectionKind: 'legacy',
    activePointer: active.pointer,
    activeProfilePath: active.pointerPath,
  };
}

export function resolveHostedConfigPath({
  workspaceRoot = process.env.OPENCLAW_WORKSPACE_ROOT,
  configPath = process.env.AQUACLAW_HOSTED_CONFIG,
} = {}) {
  return resolveHostedConfigSelection({
    workspaceRoot,
    configPath,
  }).configPath;
}

export function resolveHostedPulseStatePath({
  workspaceRoot = process.env.OPENCLAW_WORKSPACE_ROOT,
  stateFile = process.env.AQUACLAW_HOSTED_PULSE_STATE,
} = {}) {
  const explicit = typeof stateFile === 'string' && stateFile.trim() ? stateFile.trim() : null;
  if (explicit) {
    return path.resolve(explicit);
  }

  const selection = resolveHostedConfigSelection({
    workspaceRoot,
  });

  if (selection.profileId) {
    return resolveHostedProfilePaths({
      workspaceRoot: selection.workspaceRoot,
      profileId: selection.profileId,
    }).pulseStatePath;
  }

  return path.join(selection.workspaceRoot, DEFAULT_HOSTED_PULSE_STATE_RELATIVE_PATH);
}

export function resolveHostedIntroStatePath({
  workspaceRoot = process.env.OPENCLAW_WORKSPACE_ROOT,
  stateFile = process.env.AQUACLAW_HOSTED_INTRO_STATE,
  configPath = process.env.AQUACLAW_HOSTED_CONFIG,
} = {}) {
  const explicit = typeof stateFile === 'string' && stateFile.trim() ? stateFile.trim() : null;
  if (explicit) {
    return path.resolve(explicit);
  }

  const selection = resolveHostedConfigSelection({
    workspaceRoot,
    configPath,
  });

  if (selection.profileId) {
    return resolveHostedProfilePaths({
      workspaceRoot: selection.workspaceRoot,
      profileId: selection.profileId,
    }).introStatePath;
  }

  return path.join(selection.workspaceRoot, DEFAULT_HOSTED_INTRO_STATE_RELATIVE_PATH);
}

function resolveLocalProfileStatePaths({ workspaceRoot, profileId }) {
  return resolveHostedProfilePaths({
    workspaceRoot,
    profileId,
  });
}

export function resolveHeartbeatStatePath({
  workspaceRoot = process.env.OPENCLAW_WORKSPACE_ROOT,
  stateFile = process.env.AQUACLAW_HEARTBEAT_STATE_FILE,
  mode = 'auto',
} = {}) {
  const explicit = typeof stateFile === 'string' && stateFile.trim() ? stateFile.trim() : null;
  if (explicit) {
    return path.resolve(explicit);
  }

  const resolvedWorkspaceRoot = resolveWorkspaceRoot(workspaceRoot);
  const active = loadActiveProfileSync({ workspaceRoot: resolvedWorkspaceRoot }).pointer;
  if (mode === 'local') {
    if (active?.type === 'local') {
      return resolveLocalProfileStatePaths({
        workspaceRoot: resolvedWorkspaceRoot,
        profileId: active.profileId,
      }).heartbeatStatePath;
    }
    return path.join(resolvedWorkspaceRoot, DEFAULT_HEARTBEAT_STATE_RELATIVE_PATH);
  }

  if (mode === 'auto' && active?.type === 'local') {
    return resolveLocalProfileStatePaths({
      workspaceRoot: resolvedWorkspaceRoot,
      profileId: active.profileId,
    }).heartbeatStatePath;
  }

  const selection = resolveHostedConfigSelection({
    workspaceRoot: resolvedWorkspaceRoot,
  });

  if (selection.profileId) {
    return resolveHostedProfilePaths({
      workspaceRoot: resolvedWorkspaceRoot,
      profileId: selection.profileId,
    }).heartbeatStatePath;
  }

  return path.join(resolvedWorkspaceRoot, DEFAULT_HEARTBEAT_STATE_RELATIVE_PATH);
}

export function resolveMirrorRootPath({
  workspaceRoot = process.env.OPENCLAW_WORKSPACE_ROOT,
  configPath = process.env.AQUACLAW_HOSTED_CONFIG,
  mirrorDir = process.env.AQUACLAW_MIRROR_DIR,
  mode = 'auto',
} = {}) {
  const explicit = typeof mirrorDir === 'string' && mirrorDir.trim() ? mirrorDir.trim() : null;
  if (explicit) {
    return path.resolve(explicit);
  }

  const resolvedWorkspaceRoot = resolveWorkspaceRoot(workspaceRoot);
  const active = loadActiveProfileSync({ workspaceRoot: resolvedWorkspaceRoot }).pointer;
  if (mode === 'local') {
    if (active?.type === 'local') {
      return resolveLocalProfileStatePaths({
        workspaceRoot: resolvedWorkspaceRoot,
        profileId: active.profileId,
      }).mirrorRoot;
    }
    return path.join(resolvedWorkspaceRoot, DEFAULT_MIRROR_RELATIVE_DIR);
  }

  if (mode === 'auto' && active?.type === 'local') {
    return resolveLocalProfileStatePaths({
      workspaceRoot: resolvedWorkspaceRoot,
      profileId: active.profileId,
    }).mirrorRoot;
  }

  const selection = resolveHostedConfigSelection({
    workspaceRoot: resolvedWorkspaceRoot,
    configPath,
  });

  if (selection.profileId) {
    return resolveHostedProfilePaths({
      workspaceRoot: resolvedWorkspaceRoot,
      profileId: selection.profileId,
    }).mirrorRoot;
  }

  return path.join(resolvedWorkspaceRoot, DEFAULT_MIRROR_RELATIVE_DIR);
}

export function resolveCommunityMemoryRootPath({
  workspaceRoot = process.env.OPENCLAW_WORKSPACE_ROOT,
  communityMemoryDir = process.env.AQUACLAW_COMMUNITY_MEMORY_DIR,
  configPath = process.env.AQUACLAW_HOSTED_CONFIG,
} = {}) {
  const explicit = typeof communityMemoryDir === 'string' && communityMemoryDir.trim() ? communityMemoryDir.trim() : null;
  if (explicit) {
    return path.resolve(explicit);
  }

  const resolvedWorkspaceRoot = resolveWorkspaceRoot(workspaceRoot);
  const active = loadActiveProfileSync({ workspaceRoot: resolvedWorkspaceRoot }).pointer;
  if (active?.type === 'local') {
    return resolveLocalProfileStatePaths({
      workspaceRoot: resolvedWorkspaceRoot,
      profileId: active.profileId,
    }).communityMemoryRoot;
  }
  const selection = resolveHostedConfigSelection({
    workspaceRoot: resolvedWorkspaceRoot,
    configPath,
  });

  if (selection.profileId) {
    return resolveHostedProfilePaths({
      workspaceRoot: resolvedWorkspaceRoot,
      profileId: selection.profileId,
    }).communityMemoryRoot;
  }

  return path.join(resolvedWorkspaceRoot, DEFAULT_COMMUNITY_MEMORY_RELATIVE_DIR);
}

function assertHostedConfigShape(config, configPath) {
  if (!config || typeof config !== 'object') {
    throw new Error(`invalid hosted Aqua config at ${configPath}`);
  }
  if (config.version !== 1) {
    throw new Error(`unsupported hosted Aqua config version at ${configPath}`);
  }
  if (config.mode !== 'hosted') {
    throw new Error(`invalid hosted Aqua mode at ${configPath}`);
  }
  if (typeof config.hubUrl !== 'string' || !config.hubUrl.trim()) {
    throw new Error(`missing hubUrl in hosted Aqua config at ${configPath}`);
  }
  if (typeof config?.credential?.token !== 'string' || !config.credential.token.trim()) {
    throw new Error(`missing gateway token in hosted Aqua config at ${configPath}`);
  }
  if (typeof config?.runtime?.runtimeId !== 'string' || !config.runtime.runtimeId.trim()) {
    throw new Error(`missing runtimeId in hosted Aqua config at ${configPath}`);
  }
}

export async function loadHostedConfig({
  workspaceRoot = process.env.OPENCLAW_WORKSPACE_ROOT,
  configPath = process.env.AQUACLAW_HOSTED_CONFIG,
} = {}) {
  const selection = resolveHostedConfigSelection({
    workspaceRoot,
    configPath,
  });
  const resolvedWorkspaceRoot = selection.workspaceRoot;
  const resolvedConfigPath = selection.configPath;

  let raw;
  try {
    raw = await readFile(resolvedConfigPath, 'utf8');
  } catch (error) {
    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
      throw new Error(`hosted Aqua config not found at ${resolvedConfigPath}. Run aqua-hosted-join.sh first.`);
    }
    throw error;
  }

  let config;
  try {
    config = JSON.parse(raw);
  } catch {
    throw new Error(`invalid JSON in hosted Aqua config at ${resolvedConfigPath}`);
  }

  assertHostedConfigShape(config, resolvedConfigPath);

  return {
    config,
    configPath: resolvedConfigPath,
    workspaceRoot: resolvedWorkspaceRoot,
    profileId: selection.profileId ?? config?.profile?.id ?? null,
    profileRoot: selection.profileRoot ?? null,
    selectionKind: selection.selectionKind,
  };
}

export async function saveHostedConfig(configPath, config) {
  const directory = path.dirname(configPath);
  await mkdir(directory, { recursive: true, mode: 0o700 });
  const tempPath = `${configPath}.tmp-${process.pid}-${Date.now()}`;
  const payload = JSON.stringify(config, null, 2) + '\n';

  await writeFile(tempPath, payload, { mode: 0o600 });
  await rename(tempPath, configPath);
  try {
    await chmod(configPath, 0o600);
  } catch {}
}

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

export async function saveActiveProfile({
  workspaceRoot = process.env.OPENCLAW_WORKSPACE_ROOT,
  type = 'hosted',
  profileId,
  hubUrl = null,
  configPath = null,
} = {}) {
  if (typeof profileId !== 'string' || !profileId.trim()) {
    throw new Error('profileId is required');
  }
  if (type !== 'hosted' && type !== 'local') {
    throw new Error('type must be hosted or local');
  }

  const pointerPath = resolveActiveHostedProfilePath({ workspaceRoot });
  const payload = {
    version: ACTIVE_PROFILE_POINTER_VERSION,
    type,
    profileId: profileId.trim(),
    hubUrl: typeof hubUrl === 'string' && hubUrl.trim() ? normalizeBaseUrl(hubUrl) : null,
    configPath: typeof configPath === 'string' && configPath.trim() ? path.resolve(configPath) : null,
    updatedAt: new Date().toISOString(),
  };

  await saveJsonFileAtomically(pointerPath, payload);

  return {
    pointerPath,
    payload,
  };
}

export async function saveActiveHostedProfile({
  workspaceRoot = process.env.OPENCLAW_WORKSPACE_ROOT,
  profileId,
  hubUrl = null,
  configPath = null,
} = {}) {
  return saveActiveProfile({
    workspaceRoot,
    type: 'hosted',
    profileId,
    hubUrl,
    configPath,
  });
}

export async function saveActiveLocalProfile({
  workspaceRoot = process.env.OPENCLAW_WORKSPACE_ROOT,
  profileId = DEFAULT_LOCAL_PROFILE_ID,
} = {}) {
  return saveActiveProfile({
    workspaceRoot,
    type: 'local',
    profileId,
    hubUrl: null,
    configPath: null,
  });
}

export async function clearActiveProfile({
  workspaceRoot = process.env.OPENCLAW_WORKSPACE_ROOT,
} = {}) {
  const pointerPath = resolveActiveHostedProfilePath({ workspaceRoot });
  try {
    await unlink(pointerPath);
  } catch (error) {
    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
      return {
        pointerPath,
        removed: false,
      };
    }
    throw error;
  }

  return {
    pointerPath,
    removed: true,
  };
}

export async function clearActiveHostedProfile({
  workspaceRoot = process.env.OPENCLAW_WORKSPACE_ROOT,
} = {}) {
  return clearActiveProfile({ workspaceRoot });
}

function readWorkspaceSoulTextSync(workspaceRoot = process.env.OPENCLAW_WORKSPACE_ROOT) {
  const soulPath = path.join(resolveWorkspaceRoot(workspaceRoot), 'SOUL.md');
  try {
    return readFileSync(soulPath, 'utf8');
  } catch (error) {
    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
      return '';
    }
    throw error;
  }
}

export function buildHostedJoinDefaults({
  workspaceRoot = process.env.OPENCLAW_WORKSPACE_ROOT,
  hostname = os.hostname() || 'host',
  suffix = randomBytes(3).toString('hex'),
  soulText,
} = {}) {
  const hostSlug = slugifySegment(hostname, 'host');
  const runtimeSlug = `${hostSlug}-${suffix}`;
  const resolvedSoulText = typeof soulText === 'string' ? soulText : readWorkspaceSoulTextSync(workspaceRoot);
  const displayName = deriveGatewayDisplayNameFromSoul(resolvedSoulText);

  return {
    displayName,
    handle: `claw-${suffix}`,
    bio: deriveGatewayBioFromSoul(resolvedSoulText),
    installationId: `openclaw-${hostSlug}`,
    runtimeId: `openclaw-${runtimeSlug}`,
    label: displayName,
    source: 'openclaw_skill_hosted',
  };
}

export function createProfileMetadata({
  type,
  profileId,
  label = null,
  hubUrl = null,
} = {}) {
  if (type !== 'hosted' && type !== 'local') {
    throw new Error('profile metadata type must be hosted or local');
  }
  if (typeof profileId !== 'string' || !profileId.trim()) {
    throw new Error('profile metadata profileId is required');
  }

  return {
    version: 1,
    type,
    profileId: profileId.trim(),
    label: typeof label === 'string' && label.trim() ? label.trim() : null,
    hubUrl: typeof hubUrl === 'string' && hubUrl.trim() ? normalizeBaseUrl(hubUrl) : null,
    updatedAt: new Date().toISOString(),
  };
}

export async function saveProfileMetadata(profilePath, metadata) {
  await saveJsonFileAtomically(profilePath, metadata);
}

export function formatTimestamp(value) {
  if (!value) {
    return 'n/a';
  }

  const parsed = new Date(value);
  return Number.isNaN(parsed.getTime()) ? String(value) : parsed.toISOString();
}

export function formatGatewayHandleLabel(value) {
  if (typeof value === 'string' && value.trim()) {
    return `@${value.trim().replace(/^@+/, '')}`;
  }

  if (!value || typeof value !== 'object') {
    return null;
  }

  if (typeof value.handle === 'string' && value.handle.trim()) {
    return `@${value.handle.trim().replace(/^@+/, '')}`;
  }

  if (typeof value.displayName === 'string' && value.displayName.trim()) {
    return value.displayName.trim();
  }

  return null;
}

export function formatPublicExpressionSpeakerLabel(value) {
  if (typeof value?.speakerTrail === 'string' && value.speakerTrail.trim()) {
    return value.speakerTrail.trim();
  }

  const actor = formatGatewayHandleLabel(value?.gateway ?? value?.gatewayHandle ?? null);
  const replyTarget = formatGatewayHandleLabel(
    value?.replyToGateway ?? value?.replyToGatewayHandle ?? value?.metadata?.replyToGatewayHandle ?? null,
  );

  if (actor && replyTarget) {
    return `${actor} -> ${replyTarget}`;
  }
  if (actor) {
    return actor;
  }
  if (replyTarget) {
    return `reply -> ${replyTarget}`;
  }
  return null;
}

export function formatSeaEventSummaryLine(value) {
  const type = typeof value?.type === 'string' && value.type.trim() ? value.type.trim() : 'unknown';
  const summary = typeof value?.summary === 'string' && value.summary.trim() ? value.summary.trim() : 'no summary';

  if (type === 'public_expression.created' || type === 'public_expression.replied') {
    const speaker = formatPublicExpressionSpeakerLabel(value);
    if (speaker) {
      return `${type} - ${speaker}: ${summary}`;
    }
  }

  return `${type} - ${summary}`;
}

export function parsePositiveInt(value, label) {
  const parsed = Number.parseInt(String(value), 10);
  if (!Number.isFinite(parsed) || parsed < 1) {
    throw new Error(`${label} must be a positive integer`);
  }
  return parsed;
}
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