@pellux/goodvibes-agent 0.1.0

package/src/input/commands/remote-runtime-setup.ts

@@ -0,0 +1,199 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { getDefaultAcpAgentCommand } from '@pellux/goodvibes-sdk/platform/acp';
+import type { CommandContext, RemoteCommandService } from '../command-registry.ts';
+import type { RemoteSessionBundle } from '@/runtime/index.ts';
+import { requireShellPaths } from './runtime-services.ts';
+
+type RemoteRegistryLike = Pick<RemoteCommandService, 'listContracts' | 'exportSessionBundle' | 'importSessionBundle'>;
+
+type ActiveConnectionLike = {
+  agentId: string;
+  transportState: string;
+  messageCount: number;
+  errorCount: number;
+  label: string;
+};
+
+export function inspectRemoteSessionBundle(bundle: RemoteSessionBundle): string {
+  return [
+    'Remote Session Bundle Review',
+    `  session: ${bundle.sessionId}`,
+    `  exportedAt: ${new Date(bundle.exportedAt).toISOString()}`,
+    `  active connections: ${bundle.activeConnectionIds.length}`,
+    `  pools: ${bundle.pools.length}`,
+    `  contracts: ${bundle.contracts.length}`,
+    `  artifacts: ${bundle.artifacts.length}`,
+  ].join('\n');
+}
+
+export async function handleRemoteSetupCommand(
+  args: string[],
+  ctx: CommandContext,
+  activeConnections: ActiveConnectionLike[],
+  remoteRegistry: RemoteRegistryLike,
+): Promise<boolean> {
+  const subcommand = args[0]?.toLowerCase() ?? 'show';
+  if (subcommand === 'setup') {
+    const command = getDefaultAcpAgentCommand();
+    const danger = ctx.platform.configManager.getCategory('danger');
+    const lines = [
+      'Remote Setup Review',
+      `  acp agent command: ${command.join(' ')}`,
+      `  daemon enabled: ${danger.daemon ? 'yes' : 'no'}`,
+      `  http listener enabled: ${danger.httpListener ? 'yes' : 'no'}`,
+      `  remote runner contracts: ${remoteRegistry.listContracts().length}`,
+      `  active acp connections: ${activeConnections.length}`,
+      '',
+      '  guidance:',
+      '    - set ACP_AGENT_CMD to override the spawned remote agent command',
+      '    - use /remote env to export a reusable shell snippet',
+      '    - enable danger.daemon / danger.httpListener only when you actually need those remote surfaces',
+    ];
+    if (args[1]?.toLowerCase() === 'export') {
+      const pathArg = args[2];
+      if (!pathArg) {
+        ctx.print('Usage: /remote setup export <path>');
+        return true;
+      }
+      const shellPaths = requireShellPaths(ctx);
+      const targetPath = shellPaths.resolveWorkspacePath(pathArg);
+      mkdirSync(dirname(targetPath), { recursive: true });
+      writeFileSync(targetPath, `${JSON.stringify({
+        exportedAt: Date.now(),
+        acpAgentCommand: command,
+        daemonEnabled: Boolean(danger.daemon),
+        httpListenerEnabled: Boolean(danger.httpListener),
+        remoteRunnerContracts: remoteRegistry.listContracts().length,
+      }, null, 2)}\n`, 'utf-8');
+      ctx.print(`Exported remote setup bundle to ${targetPath}`);
+      return true;
+    }
+    ctx.print(lines.join('\n'));
+    return true;
+  }
+
+  if (subcommand === 'env') {
+    const command = getDefaultAcpAgentCommand();
+    const shellSnippet = [
+      `export ACP_AGENT_CMD='${command.join(' ')}'`,
+      `export GOODVIBES_REMOTE_SESSION='${ctx.session.runtime.sessionId}'`,
+    ].join('\n');
+    if (args[1]?.toLowerCase() === 'export') {
+      const pathArg = args[2];
+      if (!pathArg) {
+        ctx.print('Usage: /remote env export <path>');
+        return true;
+      }
+      const shellPaths = requireShellPaths(ctx);
+      const targetPath = shellPaths.resolveWorkspacePath(pathArg);
+      mkdirSync(dirname(targetPath), { recursive: true });
+      writeFileSync(targetPath, `${shellSnippet}\n`, 'utf-8');
+      ctx.print(`Exported remote environment snippet to ${targetPath}`);
+      return true;
+    }
+    ctx.print(['Remote Environment', shellSnippet].join('\n'));
+    return true;
+  }
+
+  if (subcommand === 'tunnel') {
+    const mode = args[1]?.toLowerCase() ?? 'review';
+    const lines = [
+      'Remote Tunnel Review',
+      '  transport: self-hosted ACP / daemon relay',
+      `  session: ${ctx.session.runtime.sessionId}`,
+      `  active remote connections: ${activeConnections.length}`,
+      '  guidance: forward ACP agent traffic through your chosen self-hosted tunnel or SSH transport',
+    ];
+    if (mode === 'export') {
+      const pathArg = args[2];
+      if (!pathArg) {
+        ctx.print('Usage: /remote tunnel export <path>');
+        return true;
+      }
+      const shellPaths = requireShellPaths(ctx);
+      const targetPath = shellPaths.resolveWorkspacePath(pathArg);
+      mkdirSync(dirname(targetPath), { recursive: true });
+      writeFileSync(targetPath, `${lines.join('\n')}\n`, 'utf-8');
+      ctx.print(`Exported remote tunnel review to ${targetPath}`);
+      return true;
+    }
+    ctx.print(lines.join('\n'));
+    return true;
+  }
+
+  if (subcommand === 'bootstrap') {
+    const mode = args[1]?.toLowerCase() ?? 'export';
+    const payload = {
+      exportedAt: Date.now(),
+      sessionId: ctx.session.runtime.sessionId,
+      acpAgentCommand: getDefaultAcpAgentCommand(),
+      env: {
+        ACP_AGENT_CMD: getDefaultAcpAgentCommand().join(' '),
+        GOODVIBES_REMOTE_SESSION: ctx.session.runtime.sessionId,
+      },
+      links: [
+        'goodvibes://open/remote',
+        'goodvibes://open/cockpit?target=remote',
+      ],
+    };
+    if (mode === 'inspect') {
+      const pathArg = args[2];
+      if (!pathArg) {
+        ctx.print('Usage: /remote bootstrap inspect <path>');
+        return true;
+      }
+      const shellPaths = requireShellPaths(ctx);
+      const targetPath = shellPaths.resolveWorkspacePath(pathArg);
+      const parsed = JSON.parse(readFileSync(targetPath, 'utf-8')) as typeof payload;
+      ctx.print([
+        'Remote Bootstrap Bundle Review',
+        `  session: ${parsed.sessionId}`,
+        `  acp agent command: ${parsed.acpAgentCommand.join(' ')}`,
+        `  links: ${parsed.links.length}`,
+      ].join('\n'));
+      return true;
+    }
+    const pathArg = args[2] ?? args[1];
+    if (!pathArg || mode !== 'export') {
+      ctx.print('Usage: /remote bootstrap export <path> | /remote bootstrap inspect <path>');
+      return true;
+    }
+    const shellPaths = requireShellPaths(ctx);
+    const targetPath = shellPaths.resolveWorkspacePath(pathArg);
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeFileSync(targetPath, `${JSON.stringify(payload, null, 2)}\n`, 'utf-8');
+    ctx.print(`Exported remote bootstrap bundle to ${targetPath}`);
+    return true;
+  }
+
+  if (subcommand === 'session') {
+    const mode = args[1]?.toLowerCase();
+    const pathArg = args[2];
+    if (!mode || !pathArg) {
+      ctx.print('Usage: /remote session <export|inspect|import> <path>');
+      return true;
+    }
+    const shellPaths = requireShellPaths(ctx);
+    const targetPath = shellPaths.resolveWorkspacePath(pathArg);
+    if (mode === 'export') {
+      const exported = await remoteRegistry.exportSessionBundle(targetPath);
+      ctx.print(`Exported remote session bundle ${exported.bundle.sessionId} to ${exported.path}`);
+      return true;
+    }
+    if (mode === 'inspect') {
+      const bundle = JSON.parse(readFileSync(targetPath, 'utf-8')) as RemoteSessionBundle;
+      ctx.print(inspectRemoteSessionBundle(bundle));
+      return true;
+    }
+    if (mode === 'import') {
+      const bundle = await remoteRegistry.importSessionBundle(targetPath);
+      ctx.print(`Imported remote session bundle ${bundle.sessionId} with ${bundle.contracts.length} contracts.`);
+      return true;
+    }
+    ctx.print('Usage: /remote session <export|inspect|import> <path>');
+    return true;
+  }
+
+  return false;
+}

package/src/input/commands/remote-runtime.ts

@@ -0,0 +1,431 @@
+import { resolve } from 'node:path';
+import type { CommandRegistry, CommandContext } from '../command-registry.ts';
+import { AGENT_TEMPLATES } from '@pellux/goodvibes-sdk/platform/tools';
+import { handleRemoteSetupCommand } from './remote-runtime-setup.ts';
+import { handleRemotePoolCommand } from './remote-runtime-pool.ts';
+import { requireAgentManager, requireAcpManager, requirePeerClient } from './runtime-services.ts';
+
+type RemoteConnectionLike = { agentId: string };
+type RemoteCancelContext = Pick<CommandContext, 'print'>;
+type RemoteCancelAgentManager = Pick<ReturnType<typeof requireAgentManager>, 'cancel'>;
+type RemoteCancelAcpManager = Pick<ReturnType<typeof requireAcpManager>, 'cancel'>;
+
+function printRemoteDelegationBoundary(ctx: Pick<CommandContext, 'print'>, requestedAction: string): void {
+  ctx.print([
+    'GoodVibes Agent does not dispatch remote/local coding runners from this surface.',
+    `  requested: ${requestedAction}`,
+    '  policy: keep ordinary work serial in the main assistant conversation',
+    '  build/fix/review: delegate one request to GoodVibes TUI through the public shared-session/build-delegation contract',
+    '  preserve: full original user ask and executionIntent; let TUI own runner/WRFC topology when explicitly requested',
+  ].join('\n'));
+}
+
+export function handleRemoteCancelCommand(
+  agentId: string | undefined,
+  activeConnections: RemoteConnectionLike[],
+  ctx: RemoteCancelContext,
+  agentManager: RemoteCancelAgentManager,
+  acpManager?: RemoteCancelAcpManager,
+): void {
+  if (!agentId) {
+    ctx.print('Usage: /remote cancel <agentId>');
+    return;
+  }
+  const connection = activeConnections.find((entry) => entry.agentId === agentId);
+  if (!connection) {
+    ctx.print(`Unknown remote connection: ${agentId}`);
+    return;
+  }
+  const localAgentCancelled = agentManager.cancel(agentId);
+  if (localAgentCancelled) {
+    ctx.print(`Cancelled remote agent ${agentId}.`);
+    return;
+  }
+  if (!acpManager) {
+    ctx.print(`Remote agent ${agentId} could not be cancelled in this runtime.`);
+    return;
+  }
+  void acpManager.cancel(agentId);
+  ctx.print(`Cancellation requested for remote runner ${agentId}.`);
+}
+
+export function registerRemoteRuntimeCommands(registry: CommandRegistry): void {
+  registry.register({
+    name: 'remote',
+    aliases: [],
+    description: 'Inspect, dispatch, and review self-hosted remote runners and artifacts',
+    usage: '[list | show [agentId] | supervisor [runnerId] | capabilities [runnerId] | recover [runnerId] | setup [export <path>] | env [export <path>] | tunnel [review|export <path>] | bootstrap [export <path>|inspect <path>] | session <export|inspect|import> <path> | pool <list|show|create|assign|unassign> ... | dispatch [template] <description> | dispatch-pool <pool> [template] <description> | contract [agentId] | cancel <agentId> | export <agentId> [path] | artifact list | artifact show <id> | artifact export <id> [path] | review <id> | rerun-local <id> | import <path>]',
+    async handler(args, ctx) {
+      if (args.length === 0) {
+        if (ctx.openRemotePanel) {
+          ctx.openRemotePanel();
+          return;
+        }
+        ctx.print('Remote panel is not available in this runtime.');
+        return;
+      }
+
+      let peerClient;
+      try {
+        peerClient = requirePeerClient(ctx);
+      } catch {
+        ctx.print('Remote runtime services are not available in this runtime.');
+        return;
+      }
+      const peerSnapshot = peerClient.getSnapshot();
+      const remoteRunners = peerClient.runners;
+      const activeConnections = [...peerSnapshot.acp.activeConnections];
+      const subcommand = args[0]?.toLowerCase() ?? 'show';
+
+      if (await handleRemoteSetupCommand(args, ctx, activeConnections, {
+        listContracts: () => remoteRunners.listContracts(),
+        exportSessionBundle: (path) => remoteRunners.exportSessionBundle(path),
+        importSessionBundle: (path) => remoteRunners.importSessionBundle(path),
+      })) {
+        return;
+      }
+
+      if (subcommand === 'list') {
+        const supervisor = peerSnapshot.supervisor;
+        const contracts = peerSnapshot.runners.contracts;
+        const pools = peerSnapshot.runners.pools;
+        const artifacts = peerSnapshot.runners.artifacts;
+        const lines = [
+          'Remote Control Surface',
+          `  active connections: ${activeConnections.length}`,
+          `  runner contracts: ${contracts.length}`,
+          `  runner pools: ${pools.length}`,
+          `  review artifacts: ${artifacts.length}`,
+          `  supervisor sessions: ${supervisor.sessions.length}`,
+          `  degraded sessions: ${supervisor.degradedConnections}`,
+        ];
+        if (activeConnections.length > 0) {
+          lines.push('  connections:');
+          for (const connection of activeConnections.slice(0, 12)) {
+            lines.push(`    ${connection.agentId}  ${connection.transportState}  msgs=${connection.messageCount} errs=${connection.errorCount}  ${connection.label}`);
+          }
+        }
+        if (contracts.length > 0) {
+          lines.push('  contracts:');
+          for (const contract of contracts.slice(0, 12)) {
+            lines.push(`    ${contract.runnerId}  ${contract.template}  ${contract.transport.state}  ${contract.capabilityCeiling.executionProtocol}/${contract.capabilityCeiling.reviewMode}`);
+          }
+        }
+        ctx.print(lines.join('\n'));
+        return;
+      }
+
+      if (subcommand === 'supervisor') {
+        const snapshot = peerSnapshot.supervisor;
+        const runnerId = args[1];
+        const selected = runnerId
+          ? snapshot.sessions.find((entry) => entry.runnerId === runnerId)
+          : snapshot.sessions[0];
+        if (!selected) {
+          ctx.print(runnerId ? `Unknown remote supervisor session: ${runnerId}` : 'No remote supervisor sessions are currently tracked.');
+          return;
+        }
+        ctx.print([
+          `Remote Supervisor ${selected.runnerId}`,
+          `  label: ${selected.label}`,
+          `  transport: ${selected.transportState}`,
+          `  heartbeat: ${selected.heartbeat.status}`,
+          `  heartbeat detail: ${selected.heartbeat.detail}`,
+          `  executionProtocol: ${selected.negotiation.executionProtocol}`,
+          `  reviewMode: ${selected.negotiation.reviewMode}`,
+          `  communicationLane: ${selected.negotiation.communicationLane}`,
+          `  trustClass: ${selected.negotiation.trustClass}`,
+          `  taskId: ${selected.taskId ?? 'n/a'}`,
+          `  messageCount: ${selected.messageCount}`,
+          `  errorCount: ${selected.errorCount}`,
+          ...(selected.lastError ? [`  lastError: ${selected.lastError}`] : []),
+          '  capabilities:',
+          ...selected.capabilities.map((capability) => `    ${capability.id}: ${capability.supported ? 'yes' : 'no'} (${capability.detail})`),
+          '  recovery:',
+          ...selected.recovery.map((action) => `    ${action.command} — ${action.reason}`),
+        ].join('\n'));
+        return;
+      }
+
+      if (subcommand === 'capabilities') {
+        const snapshot = peerSnapshot.supervisor;
+        const runnerId = args[1];
+        const selected = runnerId
+          ? snapshot.sessions.find((entry) => entry.runnerId === runnerId)
+          : snapshot.sessions[0];
+        if (!selected) {
+          ctx.print(runnerId ? `Unknown remote runner: ${runnerId}` : 'No remote supervisor sessions are currently tracked.');
+          return;
+        }
+        ctx.print([
+          `Remote Capabilities ${selected.runnerId}`,
+          `  label: ${selected.label}`,
+          `  transport: ${selected.transportState}`,
+          `  executionProtocol: ${selected.negotiation.executionProtocol}`,
+          `  reviewMode: ${selected.negotiation.reviewMode}`,
+          `  communicationLane: ${selected.negotiation.communicationLane}`,
+          `  trustClass: ${selected.negotiation.trustClass}`,
+          '  capabilities:',
+          ...selected.capabilities.map((capability) => (
+            `    ${capability.id}: ${capability.supported ? 'supported' : 'missing'} — ${capability.detail}`
+          )),
+        ].join('\n'));
+        return;
+      }
+
+      if (subcommand === 'recover') {
+        const snapshot = peerSnapshot.supervisor;
+        const runnerId = args[1];
+        const selected = runnerId
+          ? snapshot.sessions.find((entry) => entry.runnerId === runnerId)
+          : snapshot.sessions.find((entry) => entry.recovery.length > 0) ?? snapshot.sessions[0];
+        if (!selected) {
+          ctx.print(runnerId ? `Unknown remote runner: ${runnerId}` : 'No remote supervisor sessions are currently tracked.');
+          return;
+        }
+        const nextSteps = selected.recovery.length > 0
+          ? selected.recovery
+          : [{
+              id: 'show',
+              label: 'Review remote runtime',
+              command: `/remote show ${selected.runnerId}`,
+              reason: 'Inspect the current remote session before deciding on recovery.',
+            }];
+        ctx.print([
+          `Remote Recovery ${selected.runnerId}`,
+          `  label: ${selected.label}`,
+          `  transport: ${selected.transportState}`,
+          `  heartbeat: ${selected.heartbeat.status}`,
+          `  detail: ${selected.heartbeat.detail}`,
+          ...(selected.lastError ? [`  lastError: ${selected.lastError}`] : []),
+          ...(selected.taskId ? [`  bound task: ${selected.taskId}`] : []),
+          '  actions:',
+          ...nextSteps.map((action) => `    ${action.command} — ${action.reason}`),
+        ].join('\n'));
+        return;
+      }
+
+      if (handleRemotePoolCommand(args, ctx, remoteRunners)) {
+        return;
+      }
+
+      if (subcommand === 'show') {
+        const agentId = args[1];
+        const connection = agentId
+          ? activeConnections.find((entry) => entry.agentId === agentId)
+          : activeConnections[0];
+        if (!connection) {
+          ctx.print(agentId ? `Unknown remote connection: ${agentId}` : 'No active remote connections.');
+          return;
+        }
+        const contract = remoteRunners.upsertContractForAgent(connection.agentId);
+        ctx.print([
+          `Remote connection ${connection.agentId}`,
+          `  label: ${connection.label}`,
+          `  transport: ${connection.transportState}`,
+          `  completing: ${connection.completing ? 'yes' : 'no'}`,
+          `  connectedAt: ${connection.connectedAt ? new Date(connection.connectedAt).toISOString() : 'n/a'}`,
+          `  messageCount: ${connection.messageCount}`,
+          `  errorCount: ${connection.errorCount}`,
+          `  taskId: ${connection.taskId ?? 'n/a'}`,
+          `  lastError: ${connection.lastError ?? 'n/a'}`,
+          `  contract: ${contract?.id ?? 'n/a'}`,
+          `  pool: ${contract?.poolId ?? 'n/a'}`,
+          `  executionProtocol: ${contract?.capabilityCeiling.executionProtocol ?? 'n/a'}`,
+          `  reviewMode: ${contract?.capabilityCeiling.reviewMode ?? 'n/a'}`,
+          `  communicationLane: ${contract?.capabilityCeiling.communicationLane ?? 'n/a'}`,
+        ].join('\n'));
+        return;
+      }
+
+      if (subcommand === 'dispatch') {
+        let template = 'general';
+        let descriptionArgs = args.slice(1);
+        if (descriptionArgs.length > 0 && descriptionArgs[0] in AGENT_TEMPLATES) {
+          template = descriptionArgs[0]!;
+          descriptionArgs = descriptionArgs.slice(1);
+        }
+        const description = descriptionArgs.join(' ').trim();
+        if (description.length === 0) {
+          ctx.print('Usage: /remote dispatch [template] <description>');
+          return;
+        }
+        printRemoteDelegationBoundary(ctx, `/remote dispatch ${template} ${description}`);
+        return;
+      }
+
+      if (subcommand === 'dispatch-pool') {
+        const poolId = args[1];
+        if (!poolId) {
+          ctx.print('Usage: /remote dispatch-pool <pool> [template] <description>');
+          return;
+        }
+        const pool = remoteRunners.getPool(poolId);
+        if (!pool) {
+          ctx.print(`Unknown remote runner pool: ${poolId}`);
+          return;
+        }
+        let template = pool.preferredTemplate ?? 'general';
+        let descriptionArgs = args.slice(2);
+        if (descriptionArgs.length > 0 && descriptionArgs[0] in AGENT_TEMPLATES) {
+          template = descriptionArgs[0]!;
+          descriptionArgs = descriptionArgs.slice(1);
+        }
+        const description = descriptionArgs.join(' ').trim();
+        if (description.length === 0) {
+          ctx.print('Usage: /remote dispatch-pool <pool> [template] <description>');
+          return;
+        }
+        printRemoteDelegationBoundary(ctx, `/remote dispatch-pool ${pool.id} ${template} ${description}`);
+        return;
+      }
+
+      if (subcommand === 'contract') {
+        const agentId = args[1] ?? activeConnections[0]?.agentId;
+        if (!agentId) {
+          ctx.print('No remote runner contracts are available yet.');
+          return;
+        }
+        const contract = remoteRunners.upsertContractForAgent(agentId);
+        if (!contract) {
+          ctx.print(`Unknown remote runner: ${agentId}`);
+          return;
+        }
+        ctx.print([
+          `Remote runner contract ${contract.id}`,
+          `  runnerId: ${contract.runnerId}`,
+          `  label: ${contract.label}`,
+          `  pool: ${contract.poolId ?? '(none)'}`,
+          `  trustClass: ${contract.trustClass}`,
+          `  template: ${contract.template}`,
+          `  transport: ${contract.transport.state}`,
+          `  tools: ${contract.capabilityCeiling.allowedTools.join(', ') || '(none)'}`,
+          `  ceiling: ${contract.capabilityCeiling.capabilityCeilingTools.join(', ') || '(none)'}`,
+          `  protocol: ${contract.capabilityCeiling.executionProtocol}`,
+          `  reviewMode: ${contract.capabilityCeiling.reviewMode}`,
+          `  communicationLane: ${contract.capabilityCeiling.communicationLane}`,
+          `  writeScope: ${contract.capabilityCeiling.writeScope.join(', ') || '(none)'}`,
+        ].join('\n'));
+        return;
+      }
+
+      if (subcommand === 'cancel') {
+        if (!ctx.ops.agentManager) {
+          ctx.print('Agent manager is not available in this runtime.');
+          return;
+        }
+        handleRemoteCancelCommand(
+          args[1],
+          activeConnections,
+          ctx,
+          requireAgentManager(ctx),
+          ctx.ops.acpManager ? requireAcpManager(ctx) : undefined,
+        );
+        return;
+      }
+
+      if (subcommand === 'export') {
+        const agentId = args[1];
+        if (!agentId) {
+          ctx.print('Usage: /remote export <agentId> [path]');
+          return;
+        }
+        const artifact = remoteRunners.captureArtifactForRunner(agentId);
+        if (!artifact) {
+          ctx.print(`Remote artifact export failed for ${agentId}.`);
+          return;
+        }
+        const exported = await remoteRunners.exportArtifact(artifact.id, args[2]);
+        if (!exported) {
+          ctx.print(`Remote artifact export failed for ${agentId}.`);
+          return;
+        }
+        ctx.print(`Exported remote review artifact ${exported.artifact.id} to ${exported.path}`);
+        return;
+      }
+
+      if (subcommand === 'artifact') {
+        const mode = args[1]?.toLowerCase() ?? 'list';
+        if (mode === 'list') {
+          const artifacts = remoteRunners.listArtifacts();
+          if (artifacts.length === 0) {
+            ctx.print('No remote review artifacts captured yet.');
+            return;
+          }
+          ctx.print([
+            `Remote Review Artifacts (${artifacts.length})`,
+            ...artifacts.slice(0, 12).map((artifact) => (
+              `  ${artifact.id}  ${artifact.runnerId}  ${artifact.task.status}  ${artifact.task.summary}`
+            )),
+          ].join('\n'));
+          return;
+        }
+        if (mode === 'show') {
+          const artifactId = args[2];
+          if (!artifactId) {
+            ctx.print('Usage: /remote artifact show <artifactId>');
+            return;
+          }
+          const summary = remoteRunners.buildReviewSummary(artifactId);
+          ctx.print(summary ?? `Unknown remote artifact: ${artifactId}`);
+          return;
+        }
+        if (mode === 'export') {
+          const artifactId = args[2];
+          if (!artifactId) {
+            ctx.print('Usage: /remote artifact export <artifactId> [path]');
+            return;
+          }
+          const exported = await remoteRunners.exportArtifact(artifactId, args[3]);
+          if (!exported) {
+            ctx.print(`Unknown remote artifact: ${artifactId}`);
+            return;
+          }
+          ctx.print(`Exported remote review artifact ${exported.artifact.id} to ${exported.path}`);
+          return;
+        }
+        ctx.print(`Unknown remote artifact subcommand: ${mode}`);
+        return;
+      }
+
+      if (subcommand === 'review') {
+        const artifactId = args[1];
+        if (!artifactId) {
+          ctx.print('Usage: /remote review <artifactId>');
+          return;
+        }
+        const summary = remoteRunners.buildReviewSummary(artifactId);
+        ctx.print(summary ?? `Unknown remote artifact: ${artifactId}`);
+        return;
+      }
+
+      if (subcommand === 'rerun-local') {
+        const artifactId = args[1];
+        if (!artifactId) {
+          ctx.print('Usage: /remote rerun-local <artifactId>');
+          return;
+        }
+        const artifact = remoteRunners.getArtifact(artifactId);
+        if (!artifact) {
+          ctx.print(`Unknown remote artifact: ${artifactId}`);
+          return;
+        }
+        printRemoteDelegationBoundary(ctx, `/remote rerun-local ${artifactId}`);
+        return;
+      }
+
+      if (subcommand === 'import') {
+        const path = args[1];
+        if (!path) {
+          ctx.print('Usage: /remote import <path>');
+          return;
+        }
+        const artifact = await remoteRunners.importArtifact(path);
+        ctx.print(`Imported remote review artifact ${artifact.id} for runner ${artifact.runnerId}.`);
+        return;
+      }
+
+      ctx.print(`Unknown remote subcommand: ${subcommand}`);
+    },
+  });
+}

package/src/input/commands/replay-runtime.ts

@@ -0,0 +1,18 @@
+import type { CommandRegistry } from '../command-registry.ts';
+import { handleReplayCommand } from '@pellux/goodvibes-sdk/platform/core';
+import { requireReplayEngine } from './runtime-services.ts';
+
+export function registerReplayRuntimeCommands(registry: CommandRegistry): void {
+  registry.register({
+    name: 'replay',
+    aliases: ['rep'],
+    description: 'Deterministic replay: load, step, seek, diff, and export recorded runs',
+    usage: '[load [runId] | step [n] | seek <rev> | diff | export <path>]',
+    argsHint: '[load|step|seek|diff|export]',
+    handler(args, ctx) {
+      const replayEngine = requireReplayEngine(ctx);
+      const result = handleReplayCommand({ replayEngine }, args[0] ?? 'help', args.slice(1));
+      ctx.print(result.output);
+    },
+  });
+}