@hypercli.com/cli 0.0.0-stage → 0.9.2

package/dist/commands/agents.js

@@ -0,0 +1,2026 @@
+/**
+ * `hyper agents` — manage hosted agents (deployments).
+ *
+ * Golden-pattern duties carried by this group:
+ *   - <id> arguments accept an unambiguous id prefix (list + prefix match,
+ *     ambiguous -> UsageError listing candidates). Later groups copy this.
+ *   - Records render as label/value blocks and curated JSON bags; gateway
+ *     tokens, jwt tokens, and secret-shaped values are redacted to last-4.
+ *
+ * Substitutions against the original spec (records.ts / Commands.adopt do not
+ * exist in the frozen core, so this module ships local equivalents):
+ *   - adopt(ctx) resolves the lazy SDK client (ctx.client()) once per call.
+ *   - routines ride client.routines (RoutinesAPI), not d.routines.
+ *   - activate calls client.agent.redeemGrantCode (agent.ts), not a
+ *     deployments method.
+ *   - token calls d.createScopedKey(id, name); the SDK has no typed scopes
+ *     field, so repeated --scope values are joined into the key name.
+ */
+import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { AGENT_EXEC_STDIN_MAX_BYTES, APIError, applySessionReactionOperation, newerSessionMessageMeta, sessionReactionDisplay, getAgentsApiBaseUrl, } from '@hypercli.com/sdk';
+import { parseCommandArgs } from '../core/argv.js';
+import { cmdAgentsLogin } from './agent-login.js';
+import { capturedLogRenderer } from '../core/captured-logs.js';
+import { CliError, UsageError } from '../core/errors.js';
+import { renderGroupHelp } from '../core/help.js';
+export const name = 'agents';
+export const summary = 'Manage hosted agents (deployments, shells, logs, files, routines).';
+export const usage = [
+    'hyper agents ls [--state X]',
+    'hyper agents status <id> [--verbose]',
+    'hyper agents wait <id> [--state X] [--timeout S] [--interval S]',
+    'hyper agents create <name> --runtime openclaw|hermes|generic|goose|opencode|codex|claude-code|kimi-code|pi|buzz [--model M] [--plan P] [--size S] [--env K=V ...] [--param k=v ...] [--secret K=V ...] [--image IMG] [--sh SCRIPT] [--sync-root P] [--sync-include P ... | --sync-exclude G ...] [--registry-url U --registry-username U --registry-password P] [--restart | --no-restart] [--runner-tags a,b] [--runner-id UUID] [--executor process|docker] [--cwd RUNNER_HOST_PATH] [--dry-run] [-- CMD [ARGS...]]',
+    'hyper agents start <id>',
+    'hyper agents set runtime <id> <runtime>  (resets the launch image to the runtime default)',
+    'hyper agents chat <id> <prompt...> [-s|--session NAME] [--cwd PATH] [--mcp-servers FILE|-] [--permissions auto|none] [--timeout S] [--stream]',
+    'hyper agents messages <session-id> [--cursor CURSOR] [--limit N] [--follow] (read-only; follow emits current snapshots)',
+    'hyper agents stop <id> [--yes]',
+    'hyper agents delete <id> [--yes]',
+    'hyper agents exec <id> [--] CMD [ARGS...]',
+    'hyper agents login <id> [--flow F] [--provider X] [--session SECS] [--key-stdin] [--from-host-creds]',
+    'hyper agents shell <id>',
+    'hyper agents logs <id> [-f|--follow] [-n LINES] [--source both|stdout|stderr] [--generation current|previous] [--max-bytes N] [--max-lines N]',
+    'hyper agents cp <src> <dst>   (exactly one side must be <id>:<path>; remote path may be sync-root-relative, /absolute, or ~/…)',
+    'hyper agents activate <code> [--extend-existing]',
+    'hyper agents routines list [--agent ID]',
+    'hyper agents routines create (--cron EXPR | --run-at ISO) --prompt TEXT [--agent ID] [--name N] [--session ID] [--disabled]',
+    'hyper agents routines delete <routine-id> [--yes]',
+];
+/** Hidden commands work but stay out of the help listing. */
+const HIDDEN = ['archive', 'restore', 'token', 'config', 'routes', 'models'];
+/** CLI --runtime name → SDK runtime label; everything rides the flat createAgent. */
+const RUNTIME_LABELS = new Map([
+    ['openclaw', 'openclaw_acp'],
+    ['openclaw_acp', 'openclaw_acp'],
+    ['hermes', 'hermes_acp'],
+    ['hermes_acp', 'hermes_acp'],
+    ['generic', 'generic'],
+    ['goose', 'goose'],
+    ['opencode', 'opencode'],
+    ['codex', 'codex'],
+    ['claude-code', 'claude-code'],
+    ['kimi-code', 'kimi-code'],
+    ['pi', 'pi'],
+    ['buzz', 'buzz-agent'],
+]);
+/** desktop/src/agent-utils parity: only these runtimes get the token ceremony. */
+const OPENCLAW_SET = new Set(['openclaw_acp']);
+const HERMES_SET = new Set(['hermes_acp']);
+/** Agent family: chat rides the pod-side ACP bridge, never a gateway. */
+const ACP_SET = new Set(['opencode', 'goose', 'codex', 'claude-code', 'kimi-code', 'pi', 'buzz-agent']);
+const OPENCLAW_RUNTIMES = OPENCLAW_SET;
+const HERMES_RUNTIMES = HERMES_SET;
+const ACP_RUNTIMES = ACP_SET;
+const KNOWN_COMMANDS = new Set([
+    'ls', 'list', 'status', 'wait', 'create', 'start', 'chat', 'stop', 'delete', 'exec',
+    'shell', 'logs', 'cp', 'activate', 'routines', 'set', 'login', 'messages', ...HIDDEN,
+]);
+const MANAGED_RUNTIMES = new Set([
+    'generic', ...OPENCLAW_SET, ...HERMES_SET, ...ACP_SET,
+]);
+// Backend-folded legacy wire spellings (launch_contract.py
+// LEGACY_RUNTIME_MIGRATIONS): existing DB rows may still serve them and users
+// still type them, so the CLI folds them to canonical at the read/display
+// boundary instead of rejecting legacy payloads.
+const LEGACY_RUNTIME_FOLD = {
+    openclaw: 'openclaw_acp',
+    'hermes-agent': 'hermes_acp',
+};
+/** Map a stored or user-supplied legacy runtime spelling to its canonical name. */
+export function canonicalRuntimeName(runtime) {
+    return LEGACY_RUNTIME_FOLD[runtime.toLowerCase()] ?? runtime;
+}
+// ---------------------------------------------------------------------------
+// record helpers (local stand-ins for the records.ts contract)
+// ---------------------------------------------------------------------------
+function shortId(id) {
+    return id.length > 12 ? id.slice(0, 12) : id;
+}
+/** Label/value block (ut-style): two columns, labels left-padded. */
+function recordLabelValue(rows) {
+    const width = Math.max(0, ...rows.map(([key]) => key.length));
+    return rows.map(([key, value]) => `${key.padEnd(width)}  ${value}`.trimEnd()).join('\n');
+}
+const SENSITIVE_KEY = /(secret|token|api[-_]?key|password|credential|jwt)/i;
+function maskSecret(value) {
+    return value.length > 4 ? `...${value.slice(-4)}` : '****';
+}
+/** Deep-copy a record bag, masking any string stored under a secret-shaped key. */
+function redactRecord(value, key) {
+    if (typeof value === 'string')
+        return key && SENSITIVE_KEY.test(key) ? maskSecret(value) : value;
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value))
+        return value.map((item) => redactRecord(item));
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, redactRecord(v, k)]));
+    }
+    return value;
+}
+/** Launch configs arrive with secrets already stripped; env can still carry tokens. */
+function redactLaunchConfig(config) {
+    if (!config)
+        return null;
+    const copy = { ...config };
+    delete copy.secrets;
+    delete copy.registry_auth;
+    return redactRecord(copy);
+}
+function iso(value) {
+    return value instanceof Date && Number.isFinite(value.getTime()) ? value.toISOString() : null;
+}
+/** The JSON record bag for an Agent. Never carries jwt or full tokens. */
+function recordJsonRecord(agent, dashboard) {
+    const bag = {
+        id: agent.id,
+        name: agent.name,
+        display_name: agent.displayName,
+        handle: agent.handle,
+        runtime: agent.runtime,
+        state: agent.state,
+        hostname: agent.hostname,
+        dashboard: dashboard ?? null,
+        public_url: agent.publicUrl ?? null,
+        desktop_url: agent.desktopUrl ?? null,
+        shell_url: agent.shellUrl ?? null,
+        size: agent.requestedSize,
+        cpu: agent.cpu,
+        memory: agent.memory,
+        tags: agent.tags,
+        launch_epoch: agent.launchEpoch,
+        agent_slot_id: agent.agentSlotId,
+        cluster_id: agent.clusterId,
+        created_at: iso(agent.createdAt),
+        updated_at: iso(agent.updatedAt),
+        started_at: iso(agent.startedAt),
+        stopped_at: iso(agent.stoppedAt),
+        archived_at: iso(agent.archivedAt),
+        routes: redactRecord(agent.routes),
+        launch_config: redactLaunchConfig(agent.launchConfig),
+        meta: agent.meta ? redactRecord(agent.meta) : null,
+    };
+    return bag;
+}
+function dashboardBase() {
+    return getAgentsApiBaseUrl() === 'https://api.dev.hypercli.com/agents'
+        ? 'https://console.dev.hypercli.com' : 'https://console.hypercli.com';
+}
+// ---------------------------------------------------------------------------
+// error mapping — bare catches convert to CliError with API status detail
+// ---------------------------------------------------------------------------
+/**
+ * The control plane's structured AGENT_SLOT_EXHAUSTED contract names its own
+ * clean message beside HTTP `detail`. Prefer it over whatever intermediate
+ * layers wrapped into `detail`, and never re-print the admin-style inventory
+ * dump a legacy proxy may carry.
+ */
+function slotExhaustionMessage(err) {
+    const text = err.responseText;
+    if (typeof text !== 'string' || !text)
+        return null;
+    let payload;
+    try {
+        payload = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    const wire = payload?.error;
+    if (!wire || typeof wire !== 'object')
+        return null;
+    const record = wire;
+    if (record.code !== 'AGENT_SLOT_EXHAUSTED')
+        return null;
+    return typeof record.message === 'string' && record.message ? record.message : null;
+}
+function describeFailure(err) {
+    if (err instanceof APIError) {
+        const slotMessage = slotExhaustionMessage(err);
+        if (slotMessage)
+            return `HTTP ${err.statusCode}: ${slotMessage}`;
+        return `HTTP ${err.statusCode}: ${err.detail}`;
+    }
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+/** Wrap one SDK call: UsageError/CliError pass through, everything else -> CliError. */
+async function api(what, call) {
+    try {
+        return await call();
+    }
+    catch (err) {
+        if (err instanceof CliError)
+            throw err;
+        throw new CliError(`${what} failed: ${describeFailure(err)}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// adopt + agent reference resolution (the golden id-prefix pattern)
+// ---------------------------------------------------------------------------
+/** Resolve the deployments API through the lazy client. */
+async function adopt(ctx) {
+    const client = await ctx.client();
+    return { client, d: client.deployments };
+}
+const FULL_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Resolve a user-typed <id> reference to a full agent id.
+ *
+ *   hyper agents status a1b2      — prefix of exactly one id/name/handle/hostname
+ *   ambiguous                      — UsageError (exit 2) listing candidates
+ *   no match                       — CliError (exit 1)
+ *
+ * Exported for `hyper routines` (routines.ts) so --agent resolves identically.
+ */
+export async function resolveAgentRef(d, ref) {
+    const raw = String(ref ?? '').trim();
+    if (!raw)
+        throw new UsageError('missing agent id. See hyper agents --help.');
+    if (FULL_UUID.test(raw))
+        return raw;
+    const agents = await api('list agents', () => d.list());
+    const fields = (a) => [a.id, a.name, a.handle, a.hostname]
+        .filter((v) => typeof v === 'string' && v.length > 0);
+    const exact = agents.filter((a) => fields(a).some((v) => v === raw));
+    if (exact.length === 1)
+        return exact[0].id;
+    const matches = exact.length > 1
+        ? exact
+        : agents.filter((a) => fields(a).some((v) => v.startsWith(raw)));
+    if (matches.length === 1)
+        return matches[0].id;
+    if (matches.length > 1) {
+        const lines = matches
+            .slice(0, 10)
+            .map((a) => `  ${a.id}  ${a.displayName ?? a.name ?? ''}  ${a.state}`)
+            .join('\n');
+        throw new UsageError(`ambiguous agent reference '${raw}':\n${lines}`);
+    }
+    throw new CliError(`no agent matches '${raw}'`);
+}
+// ---------------------------------------------------------------------------
+// shared argv helpers
+// ---------------------------------------------------------------------------
+function onePositional(parsed, what) {
+    if (parsed.positionals.length === 0)
+        throw new UsageError(`missing ${what}`);
+    if (parsed.positionals.length > 1) {
+        throw new UsageError(`unexpected extra arguments: ${parsed.positionals.slice(1).join(' ')}`);
+    }
+    return parsed.positionals[0];
+}
+function str(parsed, key) {
+    const value = parsed.values[key];
+    return typeof value === 'string' ? value : undefined;
+}
+function strList(parsed, key) {
+    const value = parsed.values[key];
+    if (typeof value === 'string')
+        return [value];
+    if (Array.isArray(value))
+        return value.filter((v) => typeof v === 'string');
+    return [];
+}
+/** Parse a seconds flag to milliseconds; bad input -> UsageError. */
+function secondsFlag(parsed, key, fallback) {
+    const raw = str(parsed, key);
+    if (raw === undefined)
+        return Math.round(fallback * 1000);
+    const seconds = Number(raw);
+    if (!Number.isFinite(seconds) || seconds <= 0) {
+        throw new UsageError(`--${key} must be a positive number of seconds (got '${raw}')`);
+    }
+    return Math.round(seconds * 1000);
+}
+/** Repeated --param k=v pairs into a flat map of strings. */
+function parseParams(items) {
+    const out = {};
+    for (const item of items) {
+        const eq = item.indexOf('=');
+        if (eq <= 0)
+            throw new UsageError(`--param '${item}' must be KEY=VALUE with a nonempty key`);
+        out[item.slice(0, eq)] = item.slice(eq + 1);
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// confirmation gate — only when interactive stdout, no --yes, not --json
+// ---------------------------------------------------------------------------
+function needsConfirmation(ctx, yes) {
+    return !yes && ctx.format !== 'json' && process.stdout.isTTY === true;
+}
+async function confirm(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return /^\s*y(es)?\s*$/i.test(await rl.question(question));
+    }
+    finally {
+        rl.close();
+    }
+}
+// ---------------------------------------------------------------------------
+// ls
+// ---------------------------------------------------------------------------
+async function cmdLs(ctx, args) {
+    const parsed = parseCommandArgs(args, { state: { type: 'string' } });
+    if (parsed.help)
+        return printHelp();
+    const { d } = await adopt(ctx);
+    const state = str(parsed, 'state');
+    const agents = await api('list agents', () => d.list(state ? { state } : {}));
+    const counts = new Map();
+    for (const agent of agents) {
+        const key = String(agent.state ?? 'unknown').toUpperCase();
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    const breakdown = [...counts.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([stateName, n]) => `${stateName} ${n}`)
+        .join(', ');
+    ctx.output.info(`total ${agents.length}${breakdown ? ` (${breakdown})` : ''}`);
+    ctx.output.result(agents.map((agent) => recordJsonRecord(agent, `${dashboardBase()}/agents/${agent.id}`)), agents.length === 0
+        ? 'No agents found.'
+        : {
+            columns: ['ID', 'NAME', 'RUNTIME', 'STATE'],
+            rows: agents.map((agent) => [
+                shortId(agent.id),
+                agent.displayName ?? agent.name ?? '',
+                agent.runtime ?? '',
+                agent.state,
+            ]),
+        });
+}
+// ---------------------------------------------------------------------------
+// status
+// ---------------------------------------------------------------------------
+const PLAN_META_KEY = /plan|entitlement/i;
+async function cmdStatus(ctx, args) {
+    const parsed = parseCommandArgs(args, { verbose: { type: 'boolean', default: false } });
+    if (parsed.help)
+        return printHelp();
+    const ref = onePositional(parsed, 'agent id');
+    const { d } = await adopt(ctx);
+    const agent = await api('get agent', async () => d.get(await resolveAgentRef(d, ref)));
+    const dashboard = `${dashboardBase()}/agents/${agent.id}`;
+    const record = recordJsonRecord(agent, dashboard);
+    const rows = [
+        ['id', agent.id],
+        ['name', agent.displayName ?? agent.name ?? ''],
+        ['handle', agent.handle ?? ''],
+        ['runtime', agent.runtime ?? ''],
+        ['state', agent.state],
+        ['dashboard', dashboard],
+        ['hostname', agent.hostname ?? ''],
+        ['size', agent.requestedSize ?? (agent.cpu ? `${agent.cpu}c/${agent.memory}G` : '')],
+        ['launch_epoch', String(agent.launchEpoch)],
+        ['agent_slot_id', agent.agentSlotId ?? ''],
+        ['created_at', iso(agent.createdAt) ?? ''],
+        ['started_at', iso(agent.startedAt) ?? ''],
+        ['stopped_at', iso(agent.stoppedAt) ?? ''],
+    ];
+    // plan/entitlement fields, as returned on the record meta bag
+    if (agent.meta) {
+        for (const [key, value] of Object.entries(agent.meta)) {
+            if (!PLAN_META_KEY.test(key))
+                continue;
+            rows.push([key, typeof value === 'string' ? value : JSON.stringify(value)]);
+        }
+        const status = agent.meta.status;
+        if (status && status.status === 'error') {
+            rows.push(['error', [status.reason, status.message].filter(Boolean).join(': ') || 'error']);
+        }
+    }
+    let table = recordLabelValue(rows.filter(([, value]) => value !== ''));
+    if (parsed.values.verbose === true) {
+        table += `\n\n${JSON.stringify(record, null, 2)}`;
+    }
+    ctx.output.result(record, table);
+}
+// ---------------------------------------------------------------------------
+// wait
+// ---------------------------------------------------------------------------
+async function cmdWait(ctx, args) {
+    const parsed = parseCommandArgs(args, {
+        state: { type: 'string' },
+        timeout: { type: 'string' },
+        interval: { type: 'string' },
+    });
+    if (parsed.help)
+        return printHelp();
+    const ref = onePositional(parsed, 'agent id');
+    const target = (str(parsed, 'state') ?? 'RUNNING').toUpperCase();
+    const timeoutMs = secondsFlag(parsed, 'timeout', 300);
+    const intervalMs = secondsFlag(parsed, 'interval', 5);
+    const { d } = await adopt(ctx);
+    const id = await resolveAgentRef(d, ref);
+    ctx.output.info(`waiting for agent ${shortId(id)} to reach ${target} (timeout ${timeoutMs / 1000}s)`);
+    let agent;
+    try {
+        agent = target === 'RUNNING'
+            ? await d.waitRunning(id, timeoutMs, intervalMs)
+            : await d.waitForState(id, [target], timeoutMs, ['FAILED', 'DELETED'].filter((s) => s !== target), undefined, intervalMs);
+    }
+    catch (err) {
+        if (err instanceof CliError)
+            throw err;
+        throw new CliError(`wait failed: ${describeFailure(err)}`);
+    }
+    ctx.output.result(recordJsonRecord(agent, `${dashboardBase()}/agents/${agent.id}`), `agent ${shortId(agent.id)} reached ${agent.state}`);
+}
+// ---------------------------------------------------------------------------
+// create
+// ---------------------------------------------------------------------------
+/**
+ * Launch-contract flags shared by every runtime (--image, --sh, trailing
+ * `--` command argv, --secret, --sync-root/--sync-include/--sync-exclude,
+ * --registry-*, --restart). They map straight onto the SDK create options
+ * bag (BuildAgentConfigOptions), which every create entry honors; the
+ * Backend rejects combinations a runtime does not support.
+ */
+function launchOptionsFromCreateFlags(parsed, commandArgv) {
+    const image = str(parsed, 'image');
+    const shScript = str(parsed, 'sh');
+    if (commandArgv.length > 0 && shScript !== undefined) {
+        throw new UsageError('pass only one of --sh SCRIPT or the command argv after --');
+    }
+    const syncRoot = str(parsed, 'sync-root');
+    const syncInclude = strList(parsed, 'sync-include');
+    const syncExclude = strList(parsed, 'sync-exclude');
+    if (syncInclude.length > 0 && syncExclude.length > 0) {
+        throw new UsageError('pass only one of --sync-include or --sync-exclude');
+    }
+    const registryUrl = str(parsed, 'registry-url');
+    const registryUsername = str(parsed, 'registry-username');
+    const registryPassword = str(parsed, 'registry-password');
+    if ((registryUsername === undefined) !== (registryPassword === undefined)) {
+        throw new UsageError('--registry-username and --registry-password must be given together');
+    }
+    const restartFlag = parsed.values.restart === true;
+    const noRestart = parsed.values['no-restart'] === true;
+    if (restartFlag && noRestart) {
+        throw new UsageError('pass only one of --restart or --no-restart');
+    }
+    const secrets = parseParams(strList(parsed, 'secret'));
+    const launch = {};
+    if (image)
+        launch.image = image;
+    if (commandArgv.length > 0)
+        launch.command = commandArgv;
+    if (shScript !== undefined)
+        launch.command = ['sh', '-c', shScript];
+    if (Object.keys(secrets).length > 0)
+        launch.secrets = secrets;
+    if (syncRoot)
+        launch.syncRoot = syncRoot;
+    if (syncInclude.length > 0)
+        launch.syncInclude = syncInclude;
+    if (syncExclude.length > 0)
+        launch.syncExclude = syncExclude;
+    if (registryUrl)
+        launch.registryUrl = registryUrl;
+    if (registryUsername !== undefined && registryPassword !== undefined) {
+        launch.registryAuth = { username: registryUsername, password: registryPassword };
+    }
+    if (noRestart)
+        launch.restart = false;
+    if (restartFlag)
+        launch.restart = true;
+    return launch;
+}
+/** Dry-run prints the resolved payload; secrets and registry passwords never print. */
+function maskCreatePayloadSecrets(payload) {
+    const masked = { ...payload };
+    if (masked.secrets && typeof masked.secrets === 'object') {
+        masked.secrets = Object.fromEntries(Object.keys(masked.secrets).map((key) => [key, '****']));
+    }
+    if (masked.registryAuth && typeof masked.registryAuth === 'object') {
+        const auth = masked.registryAuth;
+        masked.registryAuth = { ...auth, password: '****' };
+    }
+    return masked;
+}
+/** Runner create accepts --cwd PATH as an absolute path on the Runner host. */
+async function cmdCreate(ctx, args) {
+    const parsed = parseCommandArgs(args, {
+        runtime: { type: 'string' },
+        model: { type: 'string' },
+        plan: { type: 'string' },
+        size: { type: 'string' },
+        env: { type: 'string', multiple: true },
+        param: { type: 'string', multiple: true },
+        secret: { type: 'string', multiple: true },
+        image: { type: 'string' },
+        sh: { type: 'string' },
+        'sync-root': { type: 'string' },
+        'sync-include': { type: 'string', multiple: true },
+        'sync-exclude': { type: 'string', multiple: true },
+        'registry-url': { type: 'string' },
+        'registry-username': { type: 'string' },
+        'registry-password': { type: 'string' },
+        restart: { type: 'boolean', default: false },
+        'no-restart': { type: 'boolean', default: false },
+        'runner-tags': { type: 'string' },
+        'runner-id': { type: 'string' },
+        executor: { type: 'string' },
+        cwd: { type: 'string' },
+        'dry-run': { type: 'boolean', default: false },
+    });
+    if (parsed.help)
+        return printHelp();
+    // `hyper agents create <name> [flags] [-- CMD [ARGS...]]` — the argv after
+    // the agent name (typically after --) is the pod command, mirroring
+    // `agents exec <id> -- CMD`.
+    const [agentName, ...commandArgv] = parsed.positionals;
+    if (!agentName)
+        throw new UsageError('missing agent name');
+    const runtime = str(parsed, 'runtime')?.toLowerCase();
+    if (!runtime) {
+        throw new UsageError(`--runtime is required (one of: ${[...RUNTIME_LABELS.keys()].join(', ')})`);
+    }
+    const runtimeLabel = RUNTIME_LABELS.get(runtime);
+    if (!runtimeLabel) {
+        throw new UsageError(`unknown runtime '${runtime}' (expected one of: ${[...RUNTIME_LABELS.keys()].join(', ')})`);
+    }
+    const model = str(parsed, 'model');
+    const plan = str(parsed, 'plan');
+    const size = str(parsed, 'size');
+    const env = parseParams(strList(parsed, 'env'));
+    const params = parseParams(strList(parsed, 'param'));
+    const dryRun = parsed.values['dry-run'] === true;
+    // The openclaw family strips the generic config bag in createAgent, so a
+    // model there would be silently dropped; refuse instead of pretending.
+    if (model && OPENCLAW_SET.has(runtimeLabel)) {
+        throw new UsageError(`--model is not supported for runtime '${runtime}' at create time; `
+            + 'configure the model after launch with hyper agents config set <id> --param ...');
+    }
+    // The SDK create contract has no plan field; --plan rides as a visible tag.
+    const tags = plan ? [`plan:${plan}`] : undefined;
+    // Self-hosted runner placement (monorepo acp/hyper-runner/RUNNER.md): --runner-tags is a
+    // comma list; --runner-id pins one runner when tags are ambiguous.
+    const runnerTagsRaw = str(parsed, 'runner-tags');
+    const runnerId = str(parsed, 'runner-id') || undefined;
+    const runnerTags = runnerTagsRaw
+        ? runnerTagsRaw.split(',').map((tag) => tag.trim()).filter(Boolean)
+        : [];
+    if (runnerTagsRaw && runnerTags.length === 0) {
+        throw new UsageError('--runner-tags must name at least one tag when given');
+    }
+    const runner = (runnerTags.length > 0 || runnerId)
+        ? { ...(runnerTags.length > 0 ? { tags: runnerTags } : {}), ...(runnerId ? { runnerId } : {}) }
+        : undefined;
+    // Runner executor choice (rulings: required at create for runner placements,
+    // forbidden for hosted agents; the Backend owns both rejections).
+    const executor = str(parsed, 'executor')?.toLowerCase();
+    const cwd = str(parsed, 'cwd');
+    if (cwd !== undefined && !runner) {
+        throw new UsageError('--cwd requires runner placement');
+    }
+    if (executor && executor !== 'process' && executor !== 'docker') {
+        throw new UsageError("--executor must be 'process' or 'docker'");
+    }
+    // The openclaw family strips the generic config bag in createAgent, so
+    // --param rides env there; the other runtimes carry a free-form config bag.
+    const mergedEnv = { ...env, ...(OPENCLAW_SET.has(runtimeLabel) ? params : {}) };
+    const configBag = OPENCLAW_SET.has(runtimeLabel) ? {} : { ...(model ? { model } : {}), ...params };
+    // Coding runtimes own their pod boot command; a caller command there would
+    // replace the ACP entrypoint silently. openclaw/generic/hermes honor it.
+    if (commandArgv.length > 0 && ACP_SET.has(runtimeLabel)) {
+        throw new UsageError(`a command argv is not supported for coding runtime '${runtime}'; the runtime owns its boot command`);
+    }
+    const launch = launchOptionsFromCreateFlags(parsed, commandArgv);
+    const payload = {
+        name: agentName,
+        ...(size ? { size } : {}),
+        ...(tags ? { tags } : {}),
+        ...(runner ? { runner } : {}),
+        ...(executor ? { executor } : {}),
+        ...(cwd !== undefined ? { cwd } : {}),
+        ...launch,
+        ...(Object.keys(mergedEnv).length > 0 ? { env: mergedEnv } : {}),
+        ...(Object.keys(configBag).length > 0 ? { config: configBag } : {}),
+        dryRun,
+    };
+    if (dryRun) {
+        // Print the resolved payload, call nothing (not even ctx.client()).
+        const printable = { runtime, method: 'createAgent', options: maskCreatePayloadSecrets(payload) };
+        ctx.output.result(printable, JSON.stringify(printable, null, 2));
+        return;
+    }
+    const { d } = await adopt(ctx);
+    const created = await api('create agent', async () => d.createAgent(runtimeLabel, payload));
+    ctx.output.result(recordJsonRecord(created, `${dashboardBase()}/agents/${created.id}`), recordLabelValue([
+        ['created', shortId(created.id)],
+        ['name', created.displayName ?? created.name ?? ''],
+        ['runtime', created.runtime ?? runtime],
+        ['state', created.state],
+    ]));
+    ctx.output.info(runner
+        ? 'runner launch requested'
+        : `start it with: hyper agents start ${shortId(created.id)}`);
+}
+// ---------------------------------------------------------------------------
+// start — runtime dispatch (desktop/src/api.ts startAgent parity)
+// ---------------------------------------------------------------------------
+/**
+ * The start shared by `agents start` and `agents chat`: every runtime starts
+ * the Backend-stored launch config without rewriting it.
+ */
+async function startAgentForRuntime(d, agent) {
+    return api('start agent', () => d.start(agent.id));
+}
+async function cmdStart(ctx, args) {
+    const parsed = parseCommandArgs(args);
+    if (parsed.help)
+        return printHelp();
+    const ref = onePositional(parsed, 'agent id');
+    const { d } = await adopt(ctx);
+    const agent = await api('get agent', async () => d.get(await resolveAgentRef(d, ref)));
+    const started = await startAgentForRuntime(d, agent);
+    ctx.output.result(recordJsonRecord(started, `${dashboardBase()}/agents/${started.id}`), `starting ${shortId(started.id)} (${started.state})`);
+}
+// ---------------------------------------------------------------------------
+// set — mutate one field on an existing agent
+// ---------------------------------------------------------------------------
+/**
+ * Mirror of the backend's lifecycle_admission.py ACTIVE_OPERATION_STATES: a
+ * runtime change is only safe while the agent is fully at rest.
+ */
+const ACTIVE_OPERATION_STATES = new Set([
+    'CREATING', 'STARTING', 'RUNNING', 'STOPPING', 'RESTORING', 'UPGRADING',
+]);
+/** The actionable stop/set/start recovery sequence for a running-agent refusal. */
+function runtimeChangeRecovery(id, runtime) {
+    return 'run:\n'
+        + `  hyper agents stop ${shortId(id)}\n`
+        + `  hyper agents set runtime ${shortId(id)} ${runtime}\n`
+        + `  hyper agents start ${shortId(id)}`;
+}
+async function cmdSet(ctx, args) {
+    const [field, ...rest] = args;
+    if (!field || field === '--help' || field === '-h')
+        return printHelp();
+    if (field !== 'runtime') {
+        throw new UsageError(`unknown agents set field '${field}' (expected: runtime)`);
+    }
+    const parsed = parseCommandArgs(rest, {});
+    if (parsed.help)
+        return printHelp();
+    if (parsed.positionals.length < 2)
+        throw new UsageError('missing agent id or runtime');
+    if (parsed.positionals.length > 2) {
+        throw new UsageError(`unexpected extra arguments: ${parsed.positionals.slice(2).join(' ')}`);
+    }
+    const [ref, runtimeInput] = parsed.positionals;
+    const runtime = canonicalRuntimeName(runtimeInput);
+    if (!MANAGED_RUNTIMES.has(runtime)) {
+        throw new UsageError(`unknown runtime '${runtime}' (expected one of: ${[...MANAGED_RUNTIMES].join(', ')})`);
+    }
+    const { d } = await adopt(ctx);
+    const id = await resolveAgentRef(d, ref);
+    // The backend 409s a runtime PATCH against an active agent; refuse early with
+    // the same recovery sequence instead of paying for the failing round-trip.
+    const agent = await api('get agent', () => d.get(id));
+    if (ACTIVE_OPERATION_STATES.has(agent.state.toUpperCase())) {
+        throw new CliError(`cannot change the runtime of a running agent (state=${agent.state})\n${runtimeChangeRecovery(id, runtime)}`);
+    }
+    let updated;
+    try {
+        // The backend resets the launch image to the new runtime's platform
+        // default on a runtime change; resetImage is ignored server-side.
+        updated = await d.update(id, { runtime: runtime });
+    }
+    catch (err) {
+        // Backstop for races: the agent may have started between the get and the PATCH.
+        if (err instanceof APIError
+            && err.statusCode === 409
+            && /runtime/i.test(err.detail)
+            && /stop/i.test(err.detail)) {
+            throw new CliError(`update agent failed: HTTP 409: ${err.detail}\n${runtimeChangeRecovery(id, runtime)}`);
+        }
+        throw new CliError(`update agent failed: ${describeFailure(err)}`);
+    }
+    ctx.output.result(recordJsonRecord(updated, `${dashboardBase()}/agents/${updated.id}`), `updated ${shortId(id)} runtime=${updated.runtime}`
+        + (runtime === 'generic' ? '' : ` (launch image reset to the ${runtime} default)`));
+}
+// ---------------------------------------------------------------------------
+// stop / delete / archive / restore
+// ---------------------------------------------------------------------------
+async function cmdStop(ctx, args) {
+    const parsed = parseCommandArgs(args, { yes: { type: 'boolean', short: 'y', default: false } });
+    if (parsed.help)
+        return printHelp();
+    const ref = onePositional(parsed, 'agent id');
+    const { d } = await adopt(ctx);
+    const id = await resolveAgentRef(d, ref);
+    if (needsConfirmation(ctx, parsed.values.yes === true)) {
+        if (!(await confirm(`Stop agent ${shortId(id)}? [y/N] `))) {
+            ctx.output.info('aborted');
+            return;
+        }
+    }
+    const stopped = await api('stop agent', () => d.stop(id));
+    ctx.output.result(recordJsonRecord(stopped, `${dashboardBase()}/agents/${stopped.id}`), stopped.state.toUpperCase() === 'STOPPED'
+        ? `stopped ${shortId(id)}`
+        : `stopping ${shortId(id)} (${stopped.state}); cleanup may still be in progress`);
+}
+async function cmdDelete(ctx, args) {
+    const parsed = parseCommandArgs(args, { yes: { type: 'boolean', short: 'y', default: false } });
+    if (parsed.help)
+        return printHelp();
+    const ref = onePositional(parsed, 'agent id');
+    const { d } = await adopt(ctx);
+    const id = await resolveAgentRef(d, ref);
+    if (needsConfirmation(ctx, parsed.values.yes === true)) {
+        if (!(await confirm(`Permanently delete agent ${shortId(id)}? [y/N] `))) {
+            ctx.output.info('aborted');
+            return;
+        }
+    }
+    await api('delete agent', () => d.delete(id));
+    ctx.output.result({ deleted: id }, `deleted ${shortId(id)}`);
+}
+async function cmdArchiveRestore(ctx, args, verb) {
+    const parsed = parseCommandArgs(args);
+    if (parsed.help)
+        return printHelp();
+    const ref = onePositional(parsed, 'agent id');
+    const { d } = await adopt(ctx);
+    const id = await resolveAgentRef(d, ref);
+    const agent = await api(`${verb} agent`, () => (verb === 'archive' ? d.archive(id) : d.restore(id)));
+    ctx.output.result(recordJsonRecord(agent, `${dashboardBase()}/agents/${agent.id}`), `${verb === 'archive' ? 'archiving' : 'restoring'} ${shortId(id)} (${agent.state})`);
+}
+// ---------------------------------------------------------------------------
+// exec
+// ---------------------------------------------------------------------------
+/**
+ * Piped stdin collector for cmdExec. A TTY keeps exec strictly one-shot:
+ * stdin stays untouched and the pod command sees no stdin attachment at all.
+ * A pipe is drained to EOF and forwarded; an unbounded pipe is a caller error,
+ * exactly like `kubectl exec -i` on a never-closing stream.
+ */
+async function readPipedExecStdin() {
+    const stdin = process.stdin;
+    if (stdin.isTTY === true)
+        return undefined;
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of stdin) {
+        const data = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk;
+        total += data.byteLength;
+        if (total > AGENT_EXEC_STDIN_MAX_BYTES) {
+            throw new CliError(`agents exec stdin exceeds the ${AGENT_EXEC_STDIN_MAX_BYTES}-byte limit`);
+        }
+        chunks.push(data);
+    }
+    return Buffer.concat(chunks);
+}
+/** Test seam: tests replace `collect` instead of piping process.stdin. */
+export const execStdin = { collect: readPipedExecStdin };
+async function cmdExec(ctx, args) {
+    const parsed = parseCommandArgs(args, { timeout: { type: 'string' } });
+    if (parsed.help) {
+        printHelp();
+        return 0;
+    }
+    const [ref, ...command] = parsed.positionals;
+    if (!ref)
+        throw new UsageError('missing agent id');
+    const timeoutRaw = str(parsed, 'timeout');
+    let timeout = 30;
+    if (timeoutRaw !== undefined) {
+        timeout = Number(timeoutRaw);
+        if (!Number.isInteger(timeout) || timeout < 1 || timeout > 300) {
+            throw new UsageError('--timeout must be an integer from 1 through 300');
+        }
+    }
+    if (command.length === 0) {
+        throw new UsageError(`usage: hyper agents exec <id> [--] CMD [ARGS...]`);
+    }
+    const { d } = await adopt(ctx);
+    const id = await resolveAgentRef(d, ref);
+    const stdin = await execStdin.collect();
+    const result = await api('exec', () => d.exec(id, command, { timeout, ...(stdin !== undefined ? { stdin } : {}) }));
+    if (ctx.format === 'json') {
+        ctx.output.result(result);
+    }
+    else {
+        if (result.stdout)
+            ctx.output.result({}, result.stdout.replace(/\n$/, ''));
+        if (result.stderr)
+            ctx.output.info(result.stderr.replace(/\n$/, ''));
+    }
+    return result.exitCode;
+}
+// ---------------------------------------------------------------------------
+// shell — raw-mode passthrough over the SDK shell WebSocket (no node-pty)
+// ---------------------------------------------------------------------------
+async function cmdShell(ctx, args) {
+    const parsed = parseCommandArgs(args, { shell: { type: 'string' } });
+    if (parsed.help) {
+        printHelp();
+        return 0;
+    }
+    const ref = onePositional(parsed, 'agent id');
+    // No half-broken TTY: without a real terminal we refuse, pointing at exec.
+    if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
+        throw new UsageError('agents shell needs an interactive TTY; use hyper agents exec <id> -- CMD for non-interactive runs');
+    }
+    const { d } = await adopt(ctx);
+    const id = await resolveAgentRef(d, ref);
+    ctx.output.info(`connecting to shell on ${shortId(id)} (Ctrl+] to disconnect)`);
+    const ws = await api('open shell', () => d.shellConnect(id, str(parsed, 'shell')));
+    return await new Promise((resolve, reject) => {
+        const stdin = process.stdin;
+        const stdout = process.stdout;
+        let settled = false;
+        const sendResize = () => {
+            try {
+                ws.send(`\x1b[8;${stdout.rows ?? 24};${stdout.columns ?? 80}t`);
+            }
+            catch {
+                // A socket already closing needs no resize.
+            }
+        };
+        const finish = (error, code = 0) => {
+            if (settled)
+                return;
+            settled = true;
+            stdin.setRawMode(false);
+            stdin.pause();
+            stdin.removeListener('data', onData);
+            process.removeListener('SIGWINCH', sendResize);
+            try {
+                ws.close();
+            }
+            catch {
+                // Peer already closed the socket.
+            }
+            if (error)
+                reject(error);
+            else
+                resolve(code);
+        };
+        const onData = (chunk) => {
+            if (chunk.includes(0x1d)) {
+                finish();
+                return;
+            }
+            try {
+                ws.send(chunk.toString('utf8'));
+            }
+            catch {
+                finish();
+            }
+        };
+        ws.onmessage = (event) => {
+            const data = event.data;
+            if (typeof data === 'string')
+                stdout.write(data);
+            else if (data instanceof ArrayBuffer)
+                stdout.write(Buffer.from(data));
+            else if (ArrayBuffer.isView(data))
+                stdout.write(Buffer.from(data.buffer, data.byteOffset, data.byteLength));
+        };
+        ws.onclose = () => {
+            ctx.output.info('disconnected');
+            finish();
+        };
+        ws.onerror = () => finish(new CliError('shell connection failed'));
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.on('data', onData);
+        process.on('SIGWINCH', sendResize);
+        sendResize();
+    });
+}
+// ---------------------------------------------------------------------------
+// logs
+// ---------------------------------------------------------------------------
+async function cmdLogs(ctx, args) {
+    const parsed = parseCommandArgs(args, {
+        follow: { type: 'boolean', short: 'f', default: false },
+        lines: { type: 'string', short: 'n' },
+        container: { type: 'string' },
+        source: { type: 'string' },
+        generation: { type: 'string' },
+        'max-bytes': { type: 'string' },
+        'max-lines': { type: 'string' },
+    });
+    if (parsed.help) {
+        printHelp();
+        return 0;
+    }
+    const ref = onePositional(parsed, 'agent id');
+    const follow = parsed.values.follow === true;
+    const linesRaw = str(parsed, 'lines');
+    let tailLines = 100;
+    if (linesRaw !== undefined) {
+        tailLines = Number(linesRaw);
+        if (!Number.isInteger(tailLines) || tailLines < 0) {
+            throw new UsageError('--lines must be a non-negative integer');
+        }
+    }
+    const source = str(parsed, 'source');
+    const generation = str(parsed, 'generation');
+    if (source !== undefined && source !== 'both' && source !== 'stdout' && source !== 'stderr')
+        throw new UsageError('--source must be both, stdout or stderr');
+    if (generation !== undefined && generation !== 'current' && generation !== 'previous')
+        throw new UsageError('--generation must be current or previous');
+    const bound = (key, max) => {
+        const raw = str(parsed, key);
+        if (raw === undefined)
+            return undefined;
+        const value = Number(raw);
+        if (!Number.isInteger(value) || value < 1 || value > max)
+            throw new UsageError(`--${key} must be an integer from 1 through ${max}`);
+        return value;
+    };
+    const maxBytes = bound('max-bytes', 65536);
+    const maxLines = bound('max-lines', 1000);
+    const { d } = await adopt(ctx);
+    const id = await resolveAgentRef(d, ref);
+    const container = str(parsed, 'container');
+    const captureOptions = { source, generation, maxBytes, maxLines };
+    const unavailable = (snapshot) => snapshot.unavailable ?? snapshot.captures.find(c => c.unavailable)?.unavailable;
+    if (!follow) {
+        // One-shot: history only, promise resolves at history_end.
+        const lines = [];
+        let captured;
+        await api('read logs', () => d.subscribeLogs(id, (line) => { lines.push(line); }, {
+            follow: false,
+            tailLines,
+            ...captureOptions,
+            onCapturedLogs: (snapshot) => { captured = snapshot; },
+            ...(container ? { container } : {}),
+        }));
+        if (captured) {
+            if (ctx.format === 'json')
+                ctx.output.result(captured);
+            else
+                capturedLogRenderer(text => process.stdout.write(text), text => ctx.output.info(text))(captured);
+            const reason = unavailable(captured);
+            if (reason) {
+                ctx.output.info(`runner logs unavailable: ${reason}`);
+                return 1;
+            }
+        }
+        else
+            ctx.output.result(lines, lines.length ? lines.join('\n') : '(no logs)');
+        return 0;
+    }
+    // Follow: stream lines verbatim; reconnect OFF (SDK default). SIGINT aborts
+    // and exits 130.
+    const controller = new AbortController();
+    let interrupted = false;
+    const onSigint = () => {
+        interrupted = true;
+        controller.abort();
+    };
+    process.once('SIGINT', onSigint);
+    const renderCaptured = capturedLogRenderer(text => process.stdout.write(text), text => ctx.output.info(text));
+    let previousSnapshot;
+    try {
+        await api('stream logs', () => d.subscribeLogs(id, (line) => {
+            process.stdout.write(`${ctx.format === 'json' ? JSON.stringify(line) : line}\n`);
+        }, {
+            follow: true,
+            tailLines,
+            signal: controller.signal,
+            ...captureOptions,
+            onCapturedLogs: (snapshot) => {
+                const serialized = JSON.stringify(snapshot);
+                if (serialized === previousSnapshot)
+                    return;
+                previousSnapshot = serialized;
+                if (ctx.format === 'json') {
+                    ctx.output.result(snapshot);
+                    const reason = unavailable(snapshot);
+                    if (reason)
+                        ctx.output.info(`runner logs unavailable: ${reason}`);
+                }
+                else
+                    renderCaptured(snapshot);
+            },
+            ...(container ? { container } : {}),
+        }));
+    }
+    finally {
+        process.removeListener('SIGINT', onSigint);
+    }
+    return interrupted ? 130 : 0;
+}
+// ---------------------------------------------------------------------------
+// cp
+// ---------------------------------------------------------------------------
+function parseCpTarget(value) {
+    // A Windows drive path ("C:\dir\file") is never a remote target.
+    if (/^[A-Za-z]:[\\/]/.test(value))
+        return { path: value };
+    const colon = value.indexOf(':');
+    if (colon < 0)
+        return { path: value };
+    const head = value.slice(0, colon);
+    // A path separator before the colon means it was a local relative path.
+    if (head.includes('/') || head.includes('\\'))
+        return { path: value };
+    const remotePath = value.slice(colon + 1);
+    if (!head || !remotePath) {
+        throw new UsageError(`remote targets must use <id>:<path> (got '${value}')`);
+    }
+    return { agentRef: head, path: remotePath };
+}
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KiB`;
+    return `${(n / (1024 * 1024)).toFixed(1)} MiB`;
+}
+// Debug note: the Reef file API behind Deployments.cpTo/cpFrom only accepts
+// paths relative to the agent's sync root (ts-sdk resolveSyncRootFilePath
+// rejects a leading '/'). Pod-side absolute paths and '~' therefore ride the
+// exec channel instead: base64 piped through sh, chunked well under exec's
+// 65_536-byte argv cap, with the local mode re-applied via chmod.
+/** '~' on the pod expands to the conventional coding/openclaw home. */
+const CP_POD_HOME = '/home/node';
+/** Raw bytes per exec chunk: 24 KiB -> 32_768 base64 chars, far under the argv cap. */
+const CP_EXEC_CHUNK_BYTES = 24 * 1024;
+/** File transfers may outlive the interactive 30s exec default; use the exec max. */
+const CP_EXEC_TIMEOUT = 300;
+/** Pod-side paths the sync-root-relative Reef file API cannot serve. */
+function needsExecTransfer(podPath) {
+    return podPath.startsWith('/') || podPath === '~' || podPath.startsWith('~/');
+}
+function expandPodPath(podPath) {
+    if (podPath === '~')
+        return CP_POD_HOME;
+    if (podPath.startsWith('~/'))
+        return `${CP_POD_HOME}/${podPath.slice(2)}`;
+    return podPath;
+}
+/** POSIX-shell single-quote of one argument. */
+function shQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function podDirname(path) {
+    const index = path.lastIndexOf('/');
+    return index <= 0 ? '/' : path.slice(0, index);
+}
+async function execOrThrow(d, id, argv, what) {
+    const result = await api(what, () => d.exec(id, argv, { timeout: CP_EXEC_TIMEOUT }));
+    if (result.exitCode !== 0) {
+        const detail = (result.stderr || result.stdout).trim();
+        throw new CliError(`${what} failed on the agent (exit ${result.exitCode})${detail ? `: ${detail}` : ''}`);
+    }
+}
+/** Upload via exec: mkdir -p, chunked base64 decode appends, chmod preserved. */
+async function cpUpViaExec(d, id, localPath, podPath) {
+    const remote = expandPodPath(podPath);
+    const content = readFileSync(localPath);
+    let mode;
+    try {
+        mode = statSync(localPath).mode & 0o777;
+    }
+    catch {
+        mode = undefined;
+    }
+    await execOrThrow(d, id, ['mkdir', '-p', podDirname(remote)], 'mkdir on agent');
+    for (let offset = 0, first = true; first || offset < content.length; first = false) {
+        const chunk = content.subarray(offset, offset + CP_EXEC_CHUNK_BYTES);
+        offset += chunk.length;
+        const redirect = first ? '>' : '>>';
+        await execOrThrow(d, id, ['sh', '-c', `printf %s ${shQuote(chunk.toString('base64'))} | base64 -d ${redirect} ${shQuote(remote)}`], 'copy up');
+    }
+    if (mode !== undefined) {
+        await execOrThrow(d, id, ['chmod', mode.toString(8), remote], 'chmod on agent');
+    }
+}
+/** Download via exec: base64 the pod file into exec stdout, decode locally. */
+async function cpDownViaExec(d, id, podPath, localPath) {
+    const remote = expandPodPath(podPath);
+    const result = await api('copy down', () => d.exec(id, ['sh', '-c', `base64 < ${shQuote(remote)}`], { timeout: CP_EXEC_TIMEOUT }));
+    if (result.exitCode !== 0) {
+        const detail = (result.stderr || result.stdout).trim();
+        throw new CliError(`copy down failed on the agent (exit ${result.exitCode})${detail ? `: ${detail}` : ''}`);
+    }
+    const content = Buffer.from(result.stdout.replace(/\s+/g, ''), 'base64');
+    const parent = dirname(localPath);
+    if (parent && parent !== '.')
+        mkdirSync(parent, { recursive: true });
+    writeFileSync(localPath, content);
+    return localPath;
+}
+async function cmdCp(ctx, args) {
+    const parsed = parseCommandArgs(args);
+    if (parsed.help)
+        return printHelp();
+    if (parsed.positionals.length !== 2) {
+        throw new UsageError('usage: hyper agents cp <src> <dst> (exactly one side must be <id>:<path>)');
+    }
+    const src = parseCpTarget(parsed.positionals[0]);
+    const dst = parseCpTarget(parsed.positionals[1]);
+    if ((src.agentRef === undefined) === (dst.agentRef === undefined)) {
+        throw new UsageError('exactly one side of cp must be remote (<id>:<path>)');
+    }
+    const { d } = await adopt(ctx);
+    if (dst.agentRef) {
+        const id = await resolveAgentRef(d, dst.agentRef);
+        if (needsExecTransfer(dst.path)) {
+            await cpUpViaExec(d, id, src.path, dst.path);
+        }
+        else {
+            await api('copy up', () => d.cpTo(id, src.path, dst.path));
+        }
+        let bytes = 0;
+        try {
+            bytes = statSync(src.path).size;
+        }
+        catch {
+            bytes = 0;
+        }
+        ctx.output.info(`copied ${formatBytes(bytes)} up to ${shortId(id)}:${dst.path}`);
+        ctx.output.result({ direction: 'up', agent_id: id, local: src.path, remote: dst.path, bytes }, `copied ${src.path} -> ${shortId(id)}:${dst.path}`);
+        return;
+    }
+    const id = await resolveAgentRef(d, src.agentRef);
+    const destination = needsExecTransfer(src.path)
+        ? await cpDownViaExec(d, id, src.path, dst.path)
+        : await api('copy down', () => d.cpFrom(id, src.path, dst.path));
+    let bytes = 0;
+    try {
+        bytes = statSync(destination).size;
+    }
+    catch {
+        bytes = 0;
+    }
+    ctx.output.info(`copied ${formatBytes(bytes)} down from ${shortId(id)}:${src.path}`);
+    ctx.output.result({ direction: 'down', agent_id: id, remote: src.path, local: destination, bytes }, `copied ${shortId(id)}:${src.path} -> ${destination}`);
+}
+// ---------------------------------------------------------------------------
+// activate
+// ---------------------------------------------------------------------------
+async function cmdActivate(ctx, args) {
+    const parsed = parseCommandArgs(args, {
+        'extend-existing': { type: 'boolean', default: false },
+    });
+    if (parsed.help)
+        return printHelp();
+    const code = onePositional(parsed, 'code');
+    const { client } = await adopt(ctx);
+    const result = await api('redeem code', () => client.agent.redeemGrantCode(code, {
+        extendExisting: parsed.values['extend-existing'] === true,
+    }));
+    printActivation(ctx, result);
+}
+function printActivation(ctx, result) {
+    const { grant, entitlement } = result;
+    const rows = [
+        ['code', grant.code ?? ''],
+        ['plan', entitlement.planName || entitlement.planId || grant.planId],
+        ['plan_id', entitlement.planId || grant.planId],
+        ['starts_at', iso(entitlement.startsAt) ?? ''],
+        ['expires_at', iso(entitlement.expiresAt) ?? ''],
+        ['tags', (entitlement.tags.length ? entitlement.tags : grant.tags).join(', ')],
+        ['entitlement', entitlement.id],
+    ];
+    ctx.output.result(result, ['Code activated', recordLabelValue(rows.filter(([, v]) => v !== ''))].join('\n'));
+}
+// ---------------------------------------------------------------------------
+// routines
+// ---------------------------------------------------------------------------
+function routineJson(routine) {
+    return {
+        id: routine.id,
+        name: routine.name,
+        agent_id: routine.agentId,
+        cron: routine.cron,
+        run_at: routine.runAt,
+        session_id: routine.sessionId,
+        next_run_at: routine.nextRunAt,
+        prompt: routine.prompt,
+        enabled: routine.enabled,
+        created_at: routine.createdAt,
+        updated_at: routine.updatedAt,
+    };
+}
+function routineSchedule(routine) {
+    if (routine.cron)
+        return `cron: ${routine.cron}`;
+    if (routine.runAt)
+        return `once: ${routine.runAt}`;
+    return '';
+}
+async function cmdRoutines(ctx, args) {
+    const [verb = 'list', ...rest] = args;
+    switch (verb) {
+        case 'list': {
+            const parsed = parseCommandArgs(rest, { agent: { type: 'string' } });
+            if (parsed.help)
+                return printHelp();
+            const { client } = await adopt(ctx);
+            const agentFilter = str(parsed, 'agent');
+            const routines = await api('list routines', () => client.routines.list(agentFilter ? { agentId: agentFilter } : {}));
+            ctx.output.info(`total ${routines.length}`);
+            ctx.output.result(routines.map(routineJson), routines.length === 0
+                ? 'No routines found.'
+                : {
+                    columns: ['NAME', 'SCHEDULE', 'ENABLED', 'ID'],
+                    rows: routines.map((r) => [
+                        r.name ?? '',
+                        routineSchedule(r),
+                        r.enabled ? 'yes' : 'no',
+                        r.id,
+                    ]),
+                });
+            return;
+        }
+        case 'create': {
+            const parsed = parseCommandArgs(rest, {
+                name: { type: 'string' },
+                cron: { type: 'string' },
+                'run-at': { type: 'string' },
+                prompt: { type: 'string' },
+                agent: { type: 'string' },
+                session: { type: 'string' },
+                disabled: { type: 'boolean', default: false },
+            });
+            if (parsed.help)
+                return printHelp();
+            if (parsed.positionals.length > 0) {
+                throw new UsageError(`unexpected arguments: ${parsed.positionals.join(' ')}`);
+            }
+            const prompt = str(parsed, 'prompt');
+            if (!prompt)
+                throw new UsageError('--prompt is required');
+            const cron = str(parsed, 'cron');
+            const runAt = str(parsed, 'run-at');
+            if ((cron === undefined) === (runAt === undefined)) {
+                throw new UsageError('exactly one of --cron or --run-at is required');
+            }
+            const agentRef = str(parsed, 'agent');
+            const { client, d } = await adopt(ctx);
+            const body = {
+                ...(agentRef ? { agentId: await resolveAgentRef(d, agentRef) } : {}),
+                prompt,
+                ...(cron !== undefined ? { cron } : {}),
+                ...(runAt !== undefined ? { runAt } : {}),
+                ...(str(parsed, 'name') ? { name: str(parsed, 'name') } : {}),
+                ...(str(parsed, 'session') ? { sessionId: str(parsed, 'session') } : {}),
+                enabled: parsed.values.disabled !== true,
+            };
+            const routine = await api('create routine', () => client.routines.create(body));
+            ctx.output.result(routineJson(routine), recordLabelValue([
+                ['created', routine.id],
+                ['name', routine.name ?? ''],
+                ['schedule', routineSchedule(routine)],
+                ['agent', routine.agentId],
+                ['next_run_at', routine.nextRunAt ?? ''],
+            ]));
+            return;
+        }
+        case 'delete': {
+            const parsed = parseCommandArgs(rest, { yes: { type: 'boolean', short: 'y', default: false } });
+            if (parsed.help)
+                return printHelp();
+            const routineId = onePositional(parsed, 'routine id');
+            if (needsConfirmation(ctx, parsed.values.yes === true)) {
+                if (!(await confirm(`Delete routine ${routineId}? [y/N] `))) {
+                    ctx.output.info('aborted');
+                    return;
+                }
+            }
+            const { client } = await adopt(ctx);
+            await api('delete routine', () => client.routines.delete(routineId));
+            ctx.output.result({ deleted: routineId }, `deleted ${routineId}`);
+            return;
+        }
+        // Hidden: works, stays out of the help listing.
+        case 'update': {
+            const parsed = parseCommandArgs(rest, {
+                name: { type: 'string' },
+                cron: { type: 'string' },
+                'run-at': { type: 'string' },
+                prompt: { type: 'string' },
+                enable: { type: 'boolean', default: false },
+                disable: { type: 'boolean', default: false },
+                agent: { type: 'string' },
+                session: { type: 'string' },
+            });
+            if (parsed.help)
+                return printHelp();
+            const routineId = onePositional(parsed, 'routine id');
+            const body = {};
+            if (parsed.values.enable === true && parsed.values.disable === true) {
+                throw new UsageError('pass only one of --enable or --disable');
+            }
+            if (parsed.values.enable === true)
+                body.enabled = true;
+            if (parsed.values.disable === true)
+                body.enabled = false;
+            if (str(parsed, 'name') !== undefined)
+                body.name = str(parsed, 'name');
+            if (str(parsed, 'cron') !== undefined)
+                body.cron = str(parsed, 'cron');
+            if (str(parsed, 'run-at') !== undefined)
+                body.runAt = str(parsed, 'run-at');
+            if (str(parsed, 'prompt') !== undefined)
+                body.prompt = str(parsed, 'prompt');
+            const session = str(parsed, 'session');
+            if (session !== undefined)
+                body.sessionId = session === 'null' ? '' : session;
+            if (Object.keys(body).length === 0) {
+                throw new UsageError('nothing to update; pass --name, --cron, --run-at, --prompt, --session, --enable or --disable');
+            }
+            const { client } = await adopt(ctx);
+            const routine = await api('update routine', () => client.routines.update(routineId, body));
+            ctx.output.result(routineJson(routine), `updated ${routine.id}`);
+            return;
+        }
+        default:
+            throw new UsageError(`unknown routines command '${verb}' (expected: list, create, delete)`);
+    }
+}
+// ---------------------------------------------------------------------------
+// token (hidden)
+// ---------------------------------------------------------------------------
+async function cmdToken(ctx, args) {
+    const parsed = parseCommandArgs(args, { scope: { type: 'string', multiple: true } });
+    if (parsed.help)
+        return printHelp();
+    const ref = onePositional(parsed, 'agent id');
+    const scopes = strList(parsed, 'scope');
+    if (scopes.some((scope) => !scope.trim()))
+        throw new UsageError('--scope must not be empty');
+    const { d } = await adopt(ctx);
+    const id = await resolveAgentRef(d, ref);
+    // The SDK signs the request body with an optional key name only; repeated
+    // scopes are carried as that name until createScopedKey grows a scopes field.
+    const record = await api('create token', () => d.createScopedKey(id, scopes.length > 0 ? scopes.join(',') : undefined));
+    const key = ['key', 'api_key', 'apiKey', 'token']
+        .map((field) => record[field])
+        .find((value) => typeof value === 'string' && value.length > 0);
+    ctx.output.info('this key is shown once and is not stored; save it now');
+    if (ctx.format !== 'json') {
+        // Table mode: the key is the single line on stdout — once, never embedded
+        // in a record table.
+        if (!key)
+            throw new CliError('create token failed: the response carried no key value');
+        ctx.output.result({ id, agent_id: id }, key);
+        return;
+    }
+    ctx.output.result({ ...record, agent_id: record.agent_id ?? id });
+}
+// ---------------------------------------------------------------------------
+// config (hidden)
+// ---------------------------------------------------------------------------
+async function cmdConfig(ctx, args) {
+    const [verb, ...rest] = args;
+    if (verb === 'set') {
+        throw new UsageError('hyper agents config is read-only: it dumps the launch config applied at agent start. '
+            + 'Mutate it with hyper agents routes add|remove or the deployments env API.');
+    }
+    const parsed = parseCommandArgs(verb === 'get' ? rest : args);
+    if (parsed.help)
+        return printHelp();
+    const ref = onePositional(parsed, 'agent id');
+    const { d } = await adopt(ctx);
+    const agent = await api('get agent', async () => d.get(await resolveAgentRef(d, ref)));
+    // launch_config IS the agent config: the complete contract applied once at
+    // launch. It arrives with secrets already stripped; redact defense-in-depth.
+    const config = redactLaunchConfig((agent.launchConfig && typeof agent.launchConfig === 'object'
+        ? agent.launchConfig
+        : {}));
+    ctx.output.result(config, JSON.stringify(config, null, 2));
+}
+function catalogModelFromJson(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const record = value;
+    if (typeof record.id !== 'string' || record.id.length === 0)
+        return null;
+    return {
+        id: record.id,
+        name: typeof record.name === 'string' ? record.name : null,
+        context_window: typeof record.contextWindow === 'number' ? record.contextWindow : null,
+        reasoning: typeof record.reasoning === 'boolean' ? record.reasoning : null,
+    };
+}
+/** The openclaw model catalog lives in the pod config (under the sync root). */
+const OPENCLAW_CONFIG_PATH = '.openclaw/openclaw.json';
+/**
+ * The openclaw family keeps its provider model catalog in
+ * ~/.openclaw/openclaw.json (models.providers.<name>.models). The Reef file
+ * API serves sync-root-relative reads from the stored volume, so this works
+ * on STOPPED agents and needs no exec or RUNNING gate.
+ */
+async function cmdModels(ctx, args) {
+    const parsed = parseCommandArgs(args);
+    if (parsed.help)
+        return printHelp();
+    const ref = onePositional(parsed, 'agent id');
+    const { d } = await adopt(ctx);
+    const agent = await api('get agent', async () => d.get(await resolveAgentRef(d, ref)));
+    if (!OPENCLAW_SET.has(canonicalRuntimeName(agent.runtime ?? ''))) {
+        throw new CliError(`agents models is openclaw-only: agent ${shortId(agent.id)} runs '${agent.runtime ?? 'unknown'}'`);
+    }
+    let openclawConfig;
+    try {
+        openclawConfig = JSON.parse(await d.fileRead(agent.id, OPENCLAW_CONFIG_PATH));
+    }
+    catch (err) {
+        if (err instanceof SyntaxError) {
+            throw new CliError(`${OPENCLAW_CONFIG_PATH} on ${shortId(agent.id)} is not valid JSON`);
+        }
+        throw new CliError(`read ${OPENCLAW_CONFIG_PATH} failed: ${describeFailure(err)}`);
+    }
+    const modelsSection = (openclawConfig && typeof openclawConfig === 'object'
+        ? openclawConfig.models
+        : undefined);
+    const providerMap = (modelsSection && typeof modelsSection === 'object'
+        ? modelsSection.providers
+        : undefined) ?? {};
+    const catalog = {};
+    for (const [provider, providerConfig] of Object.entries(providerMap)) {
+        const models = (providerConfig && typeof providerConfig === 'object'
+            ? providerConfig.models
+            : undefined);
+        catalog[provider] = (Array.isArray(models) ? models : [])
+            .map(catalogModelFromJson)
+            .filter((model) => model !== null);
+    }
+    const rows = Object.entries(catalog)
+        .flatMap(([provider, models]) => models.map((model) => [provider, model.id]));
+    ctx.output.result({ agent_id: agent.id, providers: catalog }, rows.length === 0
+        ? `No models configured on ${shortId(agent.id)}.`
+        : { columns: ['PROVIDER', 'MODEL'], rows });
+}
+function requireChatRuntime(runtime) {
+    const normalized = canonicalRuntimeName(runtime);
+    const supported = [...OPENCLAW_RUNTIMES, ...HERMES_RUNTIMES, ...ACP_RUNTIMES];
+    if (supported.some((r) => r === normalized))
+        return runtime;
+    throw new CliError(`chat is not supported on runtime '${runtime || 'unknown'}' ` + `(supported: ${supported.join(', ')})`);
+}
+/** Text of one ACP content block (or block array); non-text blocks fold to ''. */
+function acpContentText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content))
+        return content.map(acpContentText).join('');
+    if (content && typeof content === 'object') {
+        const block = content;
+        if (block.type === 'text' && typeof block.text === 'string')
+            return block.text;
+    }
+    return '';
+}
+async function readChatMcpServers(file) {
+    let value;
+    try {
+        let text;
+        if (file === '-') {
+            const chunks = [];
+            for await (const chunk of process.stdin)
+                chunks.push(Buffer.from(chunk));
+            text = Buffer.concat(chunks).toString('utf8');
+        }
+        else
+            text = readFileSync(file, 'utf8');
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new UsageError('--mcp-servers: could not read JSON array');
+    }
+    const object = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+    const pairs = (v) => Array.isArray(v) && v.every((entry) => object(entry) && typeof entry.name === 'string' && typeof entry.value === 'string');
+    if (!Array.isArray(value) || !value.every((server) => {
+        if (!object(server) || typeof server.name !== 'string')
+            return false;
+        if (server.type === 'http' || server.type === 'sse') {
+            return typeof server.url === 'string' && pairs(server.headers);
+        }
+        return server.type === undefined && typeof server.command === 'string'
+            && Array.isArray(server.args) && server.args.every((arg) => typeof arg === 'string')
+            && pairs(server.env);
+    })) {
+        throw new UsageError('--mcp-servers must be a JSON array of ACP MCP servers (stdio command/args/env or http/sse url/headers)');
+    }
+    return value;
+}
+async function cmdChat(ctx, args) {
+    const parsed = parseCommandArgs(args, {
+        session: { type: 'string', short: 's' },
+        timeout: { type: 'string' },
+        stream: { type: 'boolean', default: false },
+        permissions: { type: 'string' },
+        cwd: { type: 'string' },
+        'mcp-servers': { type: 'string' },
+    });
+    if (parsed.help)
+        return printHelp();
+    const permissions = str(parsed, 'permissions');
+    if (permissions === 'ask') {
+        throw new UsageError('--permissions ask requires an interactive permission UI, which agents chat does not support');
+    }
+    if (permissions !== undefined && permissions !== 'auto' && permissions !== 'none') {
+        throw new UsageError('--permissions must be auto or none');
+    }
+    const [ref, ...promptParts] = parsed.positionals;
+    if (!ref)
+        throw new UsageError('missing agent id');
+    const promptText = promptParts.join(' ').trim();
+    if (!promptText)
+        throw new UsageError('missing prompt: hyper agents chat <id> <prompt...>');
+    const sessionName = str(parsed, 'session');
+    if (sessionName !== undefined && !sessionName.trim())
+        throw new UsageError('--session must not be empty');
+    const stream = parsed.values.stream === true;
+    const timeoutMs = secondsFlag(parsed, 'timeout', 120);
+    const cwd = str(parsed, 'cwd');
+    const mcpFile = str(parsed, 'mcp-servers');
+    const mcpServers = mcpFile === undefined ? undefined : await readChatMcpServers(mcpFile);
+    const { client, d } = await adopt(ctx);
+    const resolved = await api('get agent', async () => d.get(await resolveAgentRef(d, ref)));
+    requireChatRuntime(resolved.runtime ?? '');
+    let stage = 'start';
+    let lastCompletedStage;
+    let stageError;
+    const activeOperations = new Map();
+    let timedOut = false;
+    // The SDK's prompt path takes no AbortSignal; cancel the turn before
+    // closing the connection, with a bounded cleanup deadline.
+    let closeActive;
+    let cancelActive;
+    let terminalError;
+    let terminalPermissionError;
+    const controller = new AbortController();
+    const startedAt = Date.now();
+    const remainingMs = () => Math.max(1, timeoutMs - (Date.now() - startedAt));
+    const evidence = () => ({ elapsedMs: Date.now() - startedAt, timeoutMs,
+        deadlineAt: startedAt + timeoutMs, lastCompletedStage, timedOut,
+        ...(stageError ? { error: stageError } : {}) });
+    const onDiagnostic = (event) => {
+        if (event.stage !== 'transport' && !timedOut) {
+            if (event.phase === 'started') {
+                activeOperations.set(event.operationId, event.stage);
+                stage = event.stage;
+                stageError = undefined;
+            }
+            else {
+                activeOperations.delete(event.operationId);
+                if (event.phase === 'failed') {
+                    stage = event.stage;
+                    stageError = event.error;
+                }
+                else {
+                    lastCompletedStage = event.stage;
+                    stage = [...activeOperations.values()].at(-1) ?? event.stage;
+                }
+            }
+        }
+        ctx.output.info(`chat diagnostic: ${JSON.stringify({ ...event, chat: evidence() })}`);
+    };
+    let rejectGuard;
+    const stop = (error, cancelOwnedPrompt = true) => {
+        if (terminalError)
+            return;
+        terminalError = error;
+        void (async () => {
+            // Cancellation is a standard ACP notification. Bound cleanup even if
+            // delivery stalls; a socket close alone does not cancel the native turn.
+            let cleanupTimer;
+            try {
+                await Promise.race([
+                    Promise.resolve().then(() => {
+                        if (cancelOwnedPrompt && !terminalPermissionError)
+                            return cancelActive?.();
+                    }).catch(() => { }),
+                    new Promise((resolve) => { cleanupTimer = setTimeout(resolve, 250); }),
+                ]);
+            }
+            finally {
+                clearTimeout(cleanupTimer);
+                controller.abort();
+                closeActive?.();
+                rejectGuard(error);
+            }
+        })();
+    };
+    const onSigint = () => stop(new CliError('chat interrupted', 130));
+    let timer;
+    const guard = new Promise((_, reject) => {
+        rejectGuard = reject;
+        timer = setTimeout(() => {
+            timedOut = true;
+            ctx.output.info(`chat diagnostic: ${JSON.stringify({ stage, phase: 'timeout', ...evidence() })}`);
+            stop(new CliError(`chat: ${stage} stage failed: timed out after ${timeoutMs / 1000}s (${JSON.stringify(evidence())})`));
+        }, timeoutMs);
+        if (typeof timer.unref === 'function')
+            timer.unref();
+    });
+    process.on('SIGINT', onSigint);
+    const atStage = async (name, fn) => {
+        stage = name;
+        try {
+            if (terminalError)
+                throw terminalError;
+            const result = await fn();
+            if (terminalError)
+                throw terminalError;
+            return result;
+        }
+        catch (err) {
+            // Pairing callbacks retag the stage while a connect awaits approval.
+            const failure = new CliError(`chat: ${stage} stage failed: ${describeFailure(err)} (${JSON.stringify(evidence())})`);
+            failure.cause = err;
+            throw failure;
+        }
+    };
+    const runAll = async () => {
+        let agent = resolved;
+        if (agent.state.toUpperCase() !== 'RUNNING') {
+            const started = await atStage('start', () => startAgentForRuntime(d, agent));
+            ctx.output.info(`started agent ${shortId(agent.id)} (${started.state})`);
+            // waitRunning resolves with the RUNNING hydration or throws (timeout /
+            // terminal state), so the state needs no recheck here.
+            agent = await atStage('wait', () => d.waitRunning(agent.id, remainingMs(), 5_000));
+        }
+        const runtime = agent.runtime ?? resolved.runtime ?? '';
+        let reply = '';
+        let streamedText = '';
+        let sessionId = '';
+        // acpConnect resumes the selected session before returning.
+        let sessionResumed = false;
+        // --stream deltas go to stdout in table mode; under --json stdout belongs
+        // to the result bag, so deltas ride stderr there instead.
+        const emitDelta = (text) => {
+            streamedText += text;
+            if (!stream)
+                return;
+            if (ctx.format === 'json')
+                process.stderr.write(text);
+            else
+                process.stdout.write(text);
+        };
+        // ACP is the single chat surface for every supported runtime: the flat
+        // Agent owns acpConnect and call-time gates on the runtime label (a
+        // non-ACP label throws rather than dialing). The dial rides the backend
+        // session proxy (/ws/acp) by default; --session awaits native v1 resume
+        // inside acpConnect. A refusal fails attachment without a replacement.
+        const acp = await atStage('connect', () => agent.acpConnect({
+            ...(cwd !== undefined ? { cwd } : {}),
+            ...(mcpServers !== undefined ? { mcpServers } : {}),
+            signal: controller.signal,
+            onDiagnostic,
+            clientInfo: { name: 'hypercli-cli' },
+            onPermissionRequest: () => {
+                ctx.output.info('chat diagnostic: {"stage":"permission","phase":"pending","resolution":"cancelled","reason":"interactive UI unavailable"}');
+                const error = new CliError('chat: permission required, but agents chat has no interactive permission UI; the request was cancelled');
+                // Abstain locally. Another observer may answer this shared request;
+                // inability to answer must never cancel the shared native turn.
+                setImmediate(() => stop(error, false));
+                terminalPermissionError = error;
+                return { outcome: { outcome: 'cancelled' } };
+            },
+            ...(sessionName !== undefined ? { sessionId: sessionName } : {}),
+            onUpdate: (notification) => {
+                if (terminalError || terminalPermissionError)
+                    return;
+                const update = notification.update;
+                if (update.sessionUpdate !== 'agent_message_chunk')
+                    return;
+                const text = acpContentText(update.content);
+                if (!text)
+                    return;
+                reply += text;
+                emitDelta(text);
+            },
+        }));
+        try {
+            closeActive = () => acp.close();
+            if (terminalError)
+                throw terminalError;
+            sessionId = sessionName ?? (await atStage('connect', () => acp.newSession())).sessionId;
+            sessionResumed = sessionName !== undefined;
+            ctx.output.info(`session opened ${sessionId}`);
+            if (permissions !== undefined) {
+                await atStage('policy', () => client.sessions.setMode(sessionId, permissions));
+            }
+            try {
+                // Only this command's submitted prompt makes it eligible to cancel.
+                // Attaching or waiting for policy does not confer turn ownership.
+                cancelActive = () => acp.cancel(sessionId);
+                await atStage('prompt', () => acp.prompt(sessionId, promptText));
+                cancelActive = undefined;
+            }
+            catch (error) {
+                if (terminalPermissionError) {
+                    stop(terminalPermissionError, false);
+                    await guard;
+                }
+                throw error;
+            }
+            if (terminalPermissionError) {
+                stop(terminalPermissionError, false);
+                await guard;
+            }
+            if (!reply)
+                throw new Error('the turn ended without an assistant reply');
+        }
+        finally {
+            cancelActive = undefined;
+            closeActive = undefined;
+            acp.close();
+        }
+        const payload = {
+            reply,
+            session_id: sessionId,
+            session: { id: sessionId, resumed: sessionResumed },
+            runtime,
+            agent_id: agent.id,
+        };
+        if (ctx.format === 'json') {
+            ctx.output.result(payload);
+            return;
+        }
+        if (stream && streamedText) {
+            if (!streamedText.endsWith('\n'))
+                process.stdout.write('\n');
+            // The deltas already showed the reply; reprint only when replace events
+            // made the final text differ from what was streamed.
+            ctx.output.result(payload, reply === streamedText ? '' : reply);
+            return;
+        }
+        ctx.output.result(payload, reply);
+    };
+    const work = runAll();
+    // The timeout guard can win the race while work is still in flight — mark
+    // that rejection handled so it never surfaces as an unhandled rejection.
+    work.catch(() => { });
+    try {
+        await Promise.race([work, guard]);
+    }
+    catch (err) {
+        if (terminalError)
+            throw terminalError;
+        if (err instanceof CliError)
+            throw err;
+        throw new CliError(`chat: ${stage} stage failed: ${describeFailure(err)} (${JSON.stringify(evidence())})`);
+    }
+    finally {
+        clearTimeout(timer);
+        process.removeListener('SIGINT', onSigint);
+    }
+}
+// ---------------------------------------------------------------------------
+// routes (hidden)
+// ---------------------------------------------------------------------------
+function routesTable(state) {
+    const entries = Object.entries(state.routes);
+    if (entries.length === 0)
+        return `No routes on ${state.agentId}.`;
+    return {
+        columns: ['NAME', 'PORT', 'PREFIX', 'AUTH', 'DNS'],
+        rows: entries.map(([routeName, route]) => [
+            routeName,
+            String(route.port),
+            route.prefix ?? '',
+            route.auth === undefined ? '' : route.auth ? 'yes' : 'no',
+            String(state.routeStatuses[routeName]?.dns_state ?? ''),
+        ]),
+    };
+}
+function routesJson(state) {
+    return {
+        agent_id: state.agentId,
+        routes: state.routes,
+        cors: state.cors,
+        route_statuses: state.routeStatuses,
+    };
+}
+async function cmdRoutes(ctx, args) {
+    const [verb, ...rest] = args;
+    switch (verb) {
+        case 'list': {
+            const parsed = parseCommandArgs(rest);
+            if (parsed.help)
+                return printHelp();
+            const ref = onePositional(parsed, 'agent id');
+            const { d } = await adopt(ctx);
+            const id = ref.trim().toLowerCase() === 'self' ? 'self' : await resolveAgentRef(d, ref);
+            const state = await api('list routes', () => d.getRoutes(id));
+            ctx.output.result(routesJson(state), routesTable(state));
+            return;
+        }
+        case 'add': {
+            const parsed = parseCommandArgs(rest, {
+                port: { type: 'string' },
+                prefix: { type: 'string' },
+                auth: { type: 'boolean', default: false },
+                'no-auth': { type: 'boolean', default: false },
+            });
+            if (parsed.help)
+                return printHelp();
+            const [ref, routeName] = parsed.positionals;
+            if (!ref || !routeName || parsed.positionals.length > 2) {
+                throw new UsageError('usage: hyper agents routes add <id> <name> --port N [--prefix P] [--no-auth]');
+            }
+            const portRaw = str(parsed, 'port');
+            if (!portRaw)
+                throw new UsageError('--port is required');
+            const port = Number(portRaw);
+            if (!Number.isInteger(port) || port < 1 || port > 65535) {
+                throw new UsageError(`--port must be an integer from 1 through 65535 (got '${portRaw}')`);
+            }
+            if (parsed.values.auth === true && parsed.values['no-auth'] === true) {
+                throw new UsageError('pass only one of --auth or --no-auth');
+            }
+            const route = { port };
+            const prefix = str(parsed, 'prefix');
+            if (prefix !== undefined)
+                route.prefix = prefix;
+            if (parsed.values.auth === true)
+                route.auth = true;
+            if (parsed.values['no-auth'] === true)
+                route.auth = false;
+            const { d } = await adopt(ctx);
+            const id = ref.trim().toLowerCase() === 'self' ? 'self' : await resolveAgentRef(d, ref);
+            const state = await api('add route', () => d.setRoute(id, routeName, route));
+            ctx.output.result(routesJson(state), routesTable(state));
+            return;
+        }
+        case 'remove': {
+            const parsed = parseCommandArgs(rest);
+            if (parsed.help)
+                return printHelp();
+            const [ref, routeName] = parsed.positionals;
+            if (!ref || !routeName || parsed.positionals.length > 2) {
+                throw new UsageError('usage: hyper agents routes remove <id> <name>');
+            }
+            const { d } = await adopt(ctx);
+            const id = ref.trim().toLowerCase() === 'self' ? 'self' : await resolveAgentRef(d, ref);
+            const state = await api('remove route', () => d.removeRoute(id, routeName));
+            ctx.output.result(routesJson(state), routesTable(state));
+            return;
+        }
+        default:
+            throw new UsageError(`unknown routes command '${verb ?? ''}' (expected: list, add, remove)`);
+    }
+}
+// ---------------------------------------------------------------------------
+// help + dispatch
+// ---------------------------------------------------------------------------
+async function cmdMessages(ctx, args) {
+    const parsed = parseCommandArgs(args, { cursor: { type: 'string' }, limit: { type: 'string' }, follow: { type: 'boolean', short: 'f' } });
+    if (parsed.help)
+        return printHelp();
+    const sessionId = onePositional(parsed, 'session id');
+    const limit = Number(str(parsed, 'limit') ?? 20);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 200)
+        throw new UsageError('--limit must be an integer from 1 through 200');
+    const client = await ctx.client();
+    const state = await client.sessions.getSession(sessionId);
+    const agents = new Set(state.participants.filter(p => p.kind === 'agent').map(p => p.participantId));
+    let previousSnapshot;
+    let page;
+    const render = (type) => {
+        if (!page)
+            return;
+        // Receipts are native removal evidence, not display data. Retain counts,
+        // completeness and scoped actors in both JSON and human snapshots.
+        const result = { ...page, items: page.items.map(row => ({ ...row,
+                ...(row.meta ? { meta: { ...row.meta, reactions: Object.fromEntries(Object.entries(row.meta.reactions).map(([key, group]) => [key, { ...group,
+                                actors: Object.fromEntries(Object.entries(group.actors).map(([id, actor]) => [id, { isBot: actor.isBot }])),
+                            }])) } } : {}),
+            })) };
+        const snapshot = JSON.stringify(result);
+        if (parsed.values.follow && snapshot === previousSnapshot)
+            return;
+        previousSnapshot = snapshot;
+        if (ctx.format === 'json' && parsed.values.follow)
+            process.stdout.write(`${JSON.stringify({ ...result, ...(type ? { type } : {}) })}\n`);
+        else
+            ctx.output.result(result, { columns: ['SEQ', 'MESSAGE', 'ROLE', 'REACTIONS'], rows: result.items.map(row => [row.seq, row.messageId ?? '', row.role,
+                    row.meta ? Object.entries(row.meta.reactions).map(([key, group]) => `${sessionReactionDisplay(key)}: ${group.count ?? '?'} (${Object.keys(group.actors).join(', ')}${group.actorsComplete ? '' : '; actors incomplete'})`).join(' · ') : 'unknown',
+                ]) });
+    };
+    const read = async () => {
+        const fresh = await client.sessions.getMessages(sessionId, { cursor: str(parsed, 'cursor'), limit });
+        const items = fresh.items.map(row => {
+            const prior = page?.items.find(prior => prior.sessionId === row.sessionId && prior.seq === row.seq && prior.messageId === row.messageId);
+            const meta = newerSessionMessageMeta(prior?.meta, row.meta);
+            return meta === row.meta ? row : { ...row, meta };
+        });
+        page = { ...fresh, items };
+        render();
+    };
+    if (!parsed.values.follow)
+        return read();
+    const controller = new AbortController();
+    const onSigint = () => controller.abort();
+    process.once('SIGINT', onSigint);
+    try {
+        await client.deployments.subscribe(async (event) => {
+            if ((event.type === 'addReaction' || event.type === 'removeReaction') && agents.has(event.agent_id) && event.session_id === sessionId) {
+                if (page) {
+                    const items = applySessionReactionOperation(page.items, event);
+                    if (items !== page.items) {
+                        page = { ...page, items };
+                        render(event.type);
+                    }
+                }
+            }
+        }, { signal: controller.signal, onReady: read });
+    }
+    finally {
+        process.removeListener('SIGINT', onSigint);
+    }
+    return controller.signal.aborted ? 130 : 0;
+}
+function printHelp() {
+    process.stdout.write(`${renderGroupHelp({ name, summary, usage, run })}\n`);
+    process.stdout.write('Chat permissions: omission preserves the mode of an existing session; new sessions default to ask.\n'
+        + 'Explicit auto/none updates the session mode over HTTP before prompting and persists until changed.\n'
+        + 'ask needs an interactive permission UI and is unsupported; unanswered requests are cancelled.\n');
+    process.stdout.write('Runner logs are bounded replacement snapshots, not a continuous stream. JSON follow emits one snapshot per line with capture metadata.\n'
+        + 'Human follow prints verified append suffixes; ambiguous truncation reports lost continuity. Bounds are per source: max-bytes 1..65536, max-lines 1..1000.\n');
+}
+export async function run(ctx, args) {
+    const [subcommand, ...rest] = args;
+    if (!subcommand) {
+        printHelp();
+        return;
+    }
+    if (subcommand === '--help' || subcommand === '-h') {
+        printHelp();
+        return;
+    }
+    if (subcommand.startsWith('-')) {
+        // e.g. bare `hyper agents --json` with no command
+        const parsed = parseCommandArgs(args);
+        if (parsed.help) {
+            printHelp();
+            return;
+        }
+        throw new UsageError('missing command. See hyper agents --help.');
+    }
+    if (!KNOWN_COMMANDS.has(subcommand)) {
+        throw new UsageError(`unknown agents command '${subcommand}'. See hyper agents --help.`);
+    }
+    switch (subcommand) {
+        case 'ls':
+        case 'list':
+            return cmdLs(ctx, rest);
+        case 'status':
+            return cmdStatus(ctx, rest);
+        case 'wait':
+            return cmdWait(ctx, rest);
+        case 'create':
+            return cmdCreate(ctx, rest);
+        case 'start':
+            return cmdStart(ctx, rest);
+        case 'set':
+            return cmdSet(ctx, rest);
+        case 'chat':
+            return cmdChat(ctx, rest);
+        case 'messages':
+            return cmdMessages(ctx, rest);
+        case 'stop':
+            return cmdStop(ctx, rest);
+        case 'delete':
+            return cmdDelete(ctx, rest);
+        case 'archive':
+            return cmdArchiveRestore(ctx, rest, 'archive');
+        case 'restore':
+            return cmdArchiveRestore(ctx, rest, 'restore');
+        case 'exec':
+            return cmdExec(ctx, rest);
+        case 'login':
+            return cmdAgentsLogin(ctx, rest);
+        case 'shell':
+            return cmdShell(ctx, rest);
+        case 'logs':
+            return cmdLogs(ctx, rest);
+        case 'cp':
+            return cmdCp(ctx, rest);
+        case 'activate':
+            return cmdActivate(ctx, rest);
+        case 'routines':
+            return cmdRoutines(ctx, rest);
+        case 'token':
+            return cmdToken(ctx, rest);
+        case 'config':
+            return cmdConfig(ctx, rest);
+        case 'models':
+            return cmdModels(ctx, rest);
+        case 'routes':
+            return cmdRoutes(ctx, rest);
+        default:
+            throw new UsageError(`unknown agents command '${subcommand}'. See hyper agents --help.`);
+    }
+}
+//# sourceMappingURL=agents.js.map