@hypercli.com/sdk 0.9.1

package/dist/agents.js

@@ -0,0 +1,4022 @@
+/**
+ * HyperClaw agents API - typed agent lifecycle, files, and exec. Agent chat
+ * and sessions are driven over ACP (see acp.ts) through the backend /ws
+ * bridge; the SDK no longer talks to runtime-internal gateway processes.
+ */
+import { randomFillSync } from 'node:crypto';
+import NodeWebSocket from 'ws';
+import { sessionMessageMetaFromWire } from './sessions.js';
+import { DEFAULT_PERSONA_SOUL_PATH, DEFAULT_PERSONA_USER_PATH, } from './agent-persona.js';
+// undici's native WebSocket (Node 18+) drops a permessage-deflate frame when
+// the peer's close frame and FIN land in the same TCP chunk, surfacing as a
+// 1006 with the final message lost. In Node always use the `ws` package;
+// everywhere else use the native implementation. Resolved per connection (not
+// module-load), and an overridden globalThis.WebSocket (e.g. a test stub) is
+// honored in every runtime.
+function preferredWebSocket() {
+    const global = globalThis.WebSocket;
+    if (typeof process !== 'undefined' && typeof process.versions?.node === 'string' && global !== undefined) {
+        // Node's built-in WebSocket is `class _WebSocket extends EventTarget`
+        // (undici); anything else is a deliberate override.
+        if (Function.prototype.toString.call(global).startsWith('class _WebSocket')) {
+            return NodeWebSocket;
+        }
+        return global;
+    }
+    return global ?? NodeWebSocket;
+}
+export { preferredWebSocket };
+import { agentSlotFromDict, parseAgentSlotSize, } from './agent-slots.js';
+export { agentSlotFromDict, parseAgentSlotSize, } from './agent-slots.js';
+import { defaultAcpProxyWsUrl, defaultAgentsWsUrl, defaultHyperAcpWsUrl, resolveAgentsApiBase, } from './agent-urls.js';
+import { getAgentsApiBaseUrl } from './config.js';
+export { parseControlUiAllowedOrigins, } from './openclaw-control-ui-origin.js';
+import { subscribeBuzzActivity, subscribeBuzzActivityRoute, } from './buzz-activity.js';
+import { CodingAgentAcpClient, } from './acp.js';
+import { CodingAgentAcpPool } from './acp-pool.js';
+import { AcpTurnDriver } from './acp-driver.js';
+export { CodingAgentAcpClient, CodingAgentAcpConnectionError, CodingAgentAcpRequestError, CodingAgentAcpAttachmentError, CodingAgentAcpUnavailableError, ACP_RECONNECT_DELAYS_MS, } from './acp.js';
+export { AcpTurnDriver, } from './acp-driver.js';
+export { CodingAgentAcpPool } from './acp-pool.js';
+// Activity-transport error classes, re-exported here so consumers can classify
+// failures without pulling the SDK root entry into their bundle.
+export { BuzzActivityGapError, BuzzActivityRouteUnavailableError, } from './buzz-activity.js';
+import { APIError } from './errors.js';
+import { HTTPClient } from './http.js';
+import { normalizeSlackRelayBaseUrl } from './channels.js';
+const DEPLOYMENTS_API_PREFIX = '/deployments';
+export const DEFAULT_OPENCLAW_IMAGE = 'ghcr.io/hypercli/hypercli-openclaw:prod';
+export const DEFAULT_HERMES_AGENT_IMAGE = 'ghcr.io/hypercli/hypercli-hermes:latest';
+export const DEFAULT_OPENCODE_IMAGE = 'ghcr.io/hypercli/hypercli-opencode:latest';
+export const DEFAULT_CODEX_IMAGE = 'ghcr.io/hypercli/hypercli-codex:latest';
+export const DEFAULT_CLAUDE_CODE_IMAGE = 'ghcr.io/hypercli/hypercli-claude:latest';
+export const DEFAULT_GOOSE_IMAGE = 'ghcr.io/hypercli/hypercli-goose:latest';
+export const DEFAULT_KIMI_CODE_IMAGE = 'ghcr.io/hypercli/hypercli-kimi-code:latest';
+export const DEFAULT_PI_IMAGE = 'ghcr.io/hypercli/hypercli-pi:latest';
+export const DEFAULT_BUZZ_AGENT_IMAGE = 'ghcr.io/hypercli/hypercli-buzz-agent:latest';
+export const DEFAULT_BUZZ_OPENCODE_IMAGE = DEFAULT_OPENCODE_IMAGE;
+export const DEFAULT_BUZZ_CODEX_IMAGE = DEFAULT_CODEX_IMAGE;
+export const DEFAULT_BUZZ_CLAUDE_CODE_IMAGE = DEFAULT_CLAUDE_CODE_IMAGE;
+export const DEFAULT_BUZZ_GOOSE_IMAGE = DEFAULT_GOOSE_IMAGE;
+export const DEFAULT_BUZZ_KIMI_CODE_IMAGE = DEFAULT_KIMI_CODE_IMAGE;
+export const DEFAULT_AGENT_RUNTIME_SCOPES = Object.freeze([
+    'agents:none',
+    'files:*',
+    'flows:*',
+    'models:*',
+    'voice:*',
+    'web:*',
+    'workspaces:*',
+]);
+export const DEFAULT_CODING_AGENT_SYNC_ROOT = '/home/node';
+// Runner-docker bind-mount cap; matches the Backend wire model
+// (AssignmentDockerOptions.volumes max_length).
+export const MAX_DOCKER_VOLUMES = 64;
+// Compatibility export: runtime configuration roots are selected on the host.
+export const DEFAULT_PI_ENV = Object.freeze({});
+export const DEFAULT_CODING_AGENT_IMAGES = {
+    'buzz-agent': DEFAULT_BUZZ_AGENT_IMAGE,
+    opencode: DEFAULT_OPENCODE_IMAGE,
+    codex: DEFAULT_CODEX_IMAGE,
+    'claude-code': DEFAULT_CLAUDE_CODE_IMAGE,
+    goose: DEFAULT_GOOSE_IMAGE,
+    'kimi-code': DEFAULT_KIMI_CODE_IMAGE,
+    pi: DEFAULT_PI_IMAGE,
+};
+export const DEFAULT_CODING_AGENT_SYNC_INCLUDES = {
+    'buzz-agent': null,
+    opencode: [
+        DEFAULT_PERSONA_USER_PATH, DEFAULT_PERSONA_SOUL_PATH,
+        '.config/opencode',
+        '.local/share/opencode',
+        '.local/state/opencode',
+        '.cache/opencode',
+    ],
+    codex: ['.codex', DEFAULT_PERSONA_USER_PATH, DEFAULT_PERSONA_SOUL_PATH],
+    'claude-code': ['.claude', '.claude.json', DEFAULT_PERSONA_USER_PATH, DEFAULT_PERSONA_SOUL_PATH],
+    goose: ['.goose', DEFAULT_PERSONA_USER_PATH, DEFAULT_PERSONA_SOUL_PATH],
+    'kimi-code': ['.kimi-code', DEFAULT_PERSONA_USER_PATH, DEFAULT_PERSONA_SOUL_PATH],
+    // Native agent state and pi-acp metadata (~/.pi/pi-acp).
+    pi: ['.pi', DEFAULT_PERSONA_USER_PATH, DEFAULT_PERSONA_SOUL_PATH],
+};
+export const DEFAULT_BUZZ_CODING_AGENT_IMAGES = {
+    'buzz-agent': DEFAULT_BUZZ_AGENT_IMAGE,
+    opencode: DEFAULT_BUZZ_OPENCODE_IMAGE,
+    codex: DEFAULT_BUZZ_CODEX_IMAGE,
+    'claude-code': DEFAULT_BUZZ_CLAUDE_CODE_IMAGE,
+    goose: DEFAULT_BUZZ_GOOSE_IMAGE,
+    'kimi-code': DEFAULT_BUZZ_KIMI_CODE_IMAGE,
+    pi: DEFAULT_PI_IMAGE,
+};
+const BUZZ_RUNTIME_COMMANDS = {
+    'buzz-agent': {
+        command: '/usr/local/bin/buzz-agent',
+        args: [],
+    },
+    opencode: {
+        command: '/opt/hypercli/bin/opencode',
+        args: ['acp'],
+    },
+    codex: {
+        command: '/opt/hypercli/bin/codex-acp',
+        args: [],
+    },
+    'claude-code': {
+        command: '/opt/hypercli/bin/claude-agent-acp',
+        args: [],
+    },
+    goose: {
+        command: '/usr/local/bin/goose',
+        args: ['acp'],
+    },
+    'kimi-code': {
+        command: '/opt/hypercli/bin/kimi',
+        args: ['acp'],
+    },
+    pi: {
+        command: '/opt/hypercli/bin/pi-acp',
+        args: [],
+    },
+};
+export const DEFAULT_BUZZ_RUST_LOG = 'hyper_acp=info,buzz_acp=info,pool::prompt=info,acp::stream=off';
+// Sync direction: this set mirrors the provider's AUTHORITATIVE_ENV_KEYS
+// (acp/buzz-backend-provider) — the boundary enforcer — and rs-sdk
+// BUZZ_RESERVED_ENV; a provider-side parity test asserts the three key sets
+// are identical. Keys the provider deliberately passes through as caller
+// policy (BUZZ_ACP_MODEL
+// — typed buzz config mints overwrite caller
+// values) are excluded on purpose: they remain caller-settable launch policy
+// at the boundary.
+const BUZZ_RESERVED_ENV_KEYS = new Set([
+    'HYPER_AGENTS_API_KEY',
+    'BUZZ_PRIVATE_KEY',
+    'NOSTR_PRIVATE_KEY',
+    'BUZZ_AUTH_TAG',
+    'BUZZ_API_TOKEN',
+    'BUZZ_ACP_PRIVATE_KEY',
+    'BUZZ_ACP_API_TOKEN',
+    'BUZZ_RELAY_URL',
+    'BUZZ_ACP_AGENT_OWNER',
+    'BUZZ_ACP_AGENT_COMMAND',
+    'BUZZ_ACP_AGENT_ARGS',
+    'BUZZ_ACP_MCP_COMMAND',
+    'BUZZ_ACP_MULTIPLE_EVENT_HANDLING',
+    'BUZZ_ACP_RELAY_OBSERVER',
+    'BUZZ_ACP_RESPOND_TO',
+    'BUZZ_ACP_RESPOND_TO_ALLOWLIST',
+    'BUZZ_ACP_SETUP_PAYLOAD',
+    'BUZZ_MANAGED_AGENT',
+    'BUZZ_MANAGED_AGENT_START_NONCE',
+    // No longer minted anywhere (dead: nothing reads them); kept listed so
+    // caller-supplied values are stripped.
+    'BUZZ_ACP_DISPLAY_NAME',
+    'BUZZ_ACP_TEXT_MENTIONS',
+    'BUZZ_ACP_REQUIRE_REPLY',
+    'BUZZ_AGENT_REQUIRE_REPLY',
+    'BUZZ_ACP_SYSTEM_PROMPT',
+    'BUZZ_ACP_SYSTEM_PROMPT_FILE',
+    'HYPER_ACP_WS_LISTEN',
+    'HYPER_ACP_LOG',
+    'HYPER_ACP_WS_TOKEN',
+    'HYPER_ACP_WS_URL',
+    'HYPER_ACP_AGENT_COMMAND',
+    'HYPER_ACP_AGENT_ARGS',
+    'HYPER_ACP_PERMISSIONS',
+    'HYPER_ACP_PERMISSION_MODE',
+    'HYPER_ACP_AUTO_APPROVE_PERMISSION',
+    'HYPER_ACP_TRACE_DB',
+    'HYPER_ACP_CORS_ORIGIN',
+    'CLAUDE_CODE_EXECUTABLE',
+    'HYPER_WORKSPACES_BOOT_SYNC',
+    'HYPER_WORKSPACES_SYNC_READY_ONLY',
+    'HYPER_WORKSPACES_SYNC_WORKSPACE',
+]);
+export const OPENCLAW_MEMORY_SEARCH_ENV_DEFAULTS = {
+    OPENCLAW_MEMORY_SEARCH_ENABLED: '1',
+    OPENCLAW_MEMORY_SEARCH_SYNC_ON_SESSION_START: '0',
+    OPENCLAW_MEMORY_SEARCH_SYNC_ON_SEARCH: '0',
+    OPENCLAW_MEMORY_SEARCH_SYNC_WATCH: '0',
+    OPENCLAW_MEMORY_SEARCH_SYNC_WATCH_DEBOUNCE_MS: '30000',
+    OPENCLAW_MEMORY_SEARCH_SYNC_INTERVAL_MINUTES: '0',
+};
+export const WORKSPACES_SYNC_ENV_DEFAULTS = {
+    HYPER_WORKSPACES_BOOT_SYNC: '1',
+    HYPER_WORKSPACES_DIR: '/home/node/shared',
+    HYPER_WORKSPACES_SYNC_READY_ONLY: '1',
+};
+export const OPENCLAW_CRON_ENV_DEFAULTS = {
+    OPENCLAW_CRON_ENABLED: '1',
+};
+export const HERMES_CRON_ENV_DEFAULTS = {
+    HERMES_CRON_ENABLED: '1',
+};
+const DEFAULT_OPENCLAW_SYNC_EXCLUDE = [
+    'shared/**',
+    '.openclaw/npm/**/node_modules/**',
+    '.openclaw/agents/**/agent/*.sqlite.memory-reindex-*',
+    '.openclaw/agents/**/agent/*.sqlite.reindex-lock.sqlite*',
+    '.openclaw/browser/**/Code Cache/**',
+    '.openclaw/browser/**/GPUCache/**',
+    '.openclaw/browser/**/ShaderCache/**',
+    '.openclaw/browser/**/GrShaderCache/**',
+    '.openclaw/browser/**/optimization_guide_model_store/**',
+];
+const LAUNCH_CONFIG_KEYS = new Set([
+    'image',
+    'env',
+    'secrets',
+    'routes',
+    'command',
+    'entrypoint',
+    'sync_root',
+    'sync_include',
+    'sync_exclude',
+    'sync_uid',
+    'sync_gid',
+    'registry_url',
+    'registry_auth',
+    'restart',
+    'runtime_scopes',
+    'executor',
+    'cwd',
+    'docker',
+]);
+const DEFAULT_OPENCLAW_SYNC_ROOT = '/home/node';
+export const DEFAULT_HERMES_AGENT_SYNC_ROOT = '/home/hermes';
+export const DEFAULT_HERMES_AGENT_SYNC_EXCLUDE = ['shared/**'];
+export const DEFAULT_HERMES_AGENT_SYNC_UID = 10000;
+export const DEFAULT_HERMES_AGENT_SYNC_GID = 10000;
+export const AGENT_FILE_MAX_BYTES = 250 * 1024 * 1024;
+// Reef file writes traverse the Cloudflare-proxied agent hostname
+// (https://<agent>.hypercli.app/_reef/...), whose edge rejects request bodies
+// above 100 MB. Enforced client-side so oversized writes fail fast with a
+// clear error instead of an opaque edge `413 Payload Too Large`.
+export const AGENT_FILE_WRITE_MAX_BYTES = 100 * 1024 * 1024;
+export const AGENT_FILE_TRANSFER_CHUNK_BYTES = 64 * 1024;
+export const AGENT_FILE_OPERATION_TIMEOUT_MS = 300_000;
+/** Buffered exec stdin cap, mirrored by the backend exec protocol. */
+export const AGENT_EXEC_STDIN_MAX_BYTES = 262_144;
+function shellAbortError() {
+    const error = new Error('Shell connection cancelled');
+    error.name = 'AbortError';
+    return error;
+}
+function runShellOperation(operation, signal, timeoutMs, timeoutMessage) {
+    return new Promise((resolve, reject) => {
+        const controller = new AbortController();
+        let settled = false;
+        const cleanup = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', abortOperation);
+        };
+        const finish = (error, value) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            if (error)
+                reject(error);
+            else
+                resolve(value);
+        };
+        const abortOperation = () => {
+            controller.abort(signal?.reason);
+            finish(shellAbortError());
+        };
+        const timer = setTimeout(() => {
+            controller.abort();
+            finish(new Error(timeoutMessage));
+        }, timeoutMs);
+        if (signal?.aborted) {
+            abortOperation();
+            return;
+        }
+        signal?.addEventListener('abort', abortOperation, { once: true });
+        void operation(controller.signal).then((value) => finish(undefined, value), (error) => {
+            if (error instanceof Error && error.name === 'AbortError' && !signal?.aborted) {
+                finish(new Error(timeoutMessage));
+            }
+            else {
+                finish(error);
+            }
+        });
+    });
+}
+export class AgentCapturedLogsError extends APIError {
+    snapshot;
+    constructor(error, snapshot) {
+        super(error.statusCode, error.detail, error.method, error.url, error.responseText, error.retryAfterSeconds);
+        this.snapshot = snapshot;
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = 'AgentCapturedLogsError';
+        this.cause = error;
+    }
+}
+function isCapturedLogsSnapshot(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const snapshot = value;
+    return snapshot.transport === 'runner' && typeof snapshot.agent_id === 'string'
+        && (typeof snapshot.logs === 'string' || snapshot.logs === null)
+        && (snapshot.unavailable === null || typeof snapshot.unavailable === 'string')
+        && Array.isArray(snapshot.captures);
+}
+function agentLogQuery(options) {
+    return {
+        ...(options.source !== undefined ? { source: options.source } : {}),
+        ...(options.generation !== undefined ? { generation: options.generation } : {}),
+        ...(options.maxBytes !== undefined ? { max_bytes: options.maxBytes } : {}),
+        ...(options.maxLines !== undefined ? { max_lines: options.maxLines } : {}),
+    };
+}
+export function parseAgentLogFrame(raw) {
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    }
+    catch {
+        return { kind: 'log', line: raw };
+    }
+    if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+        return { kind: 'log', line: raw };
+    }
+    const frame = payload;
+    if (typeof frame.event !== 'string')
+        return { kind: 'log', line: raw };
+    switch (frame.event) {
+        case 'captured_logs':
+            return isCapturedLogsSnapshot(payload)
+                ? { kind: 'capturedLogs', snapshot: payload }
+                : { kind: 'error', detail: 'Invalid captured logs snapshot' };
+        case 'log':
+            return {
+                kind: 'log',
+                line: typeof frame.log === 'string' ? frame.log : String(frame.log ?? ''),
+            };
+        case 'history_end':
+            return { kind: 'historyEnd' };
+        case 'error':
+            return {
+                kind: 'error',
+                detail: typeof frame.detail === 'string' && frame.detail
+                    ? frame.detail
+                    : 'Log stream failed',
+            };
+        default:
+            return { kind: 'ignore' };
+    }
+}
+function routeConfigBody(route) {
+    const body = { port: route.port };
+    if (route.auth !== undefined)
+        body.auth = route.auth;
+    if (route.prefix !== undefined)
+        body.prefix = route.prefix;
+    if (route.remove_headers?.length)
+        body.remove_headers = route.remove_headers;
+    return body;
+}
+function routesConfigBody(routes) {
+    return Object.fromEntries(Object.entries(routes ?? {}).map(([name, route]) => [name, routeConfigBody(route)]));
+}
+const REQUIRED_START_LAUNCH_CONFIG_KEYS = [
+    'image',
+    'env',
+    'secrets',
+    'routes',
+    'command',
+    'entrypoint',
+    'restart',
+    'sync_root',
+    'sync_uid',
+    'sync_gid',
+    'registry_url',
+    'registry_auth',
+    'runtime_scopes',
+];
+const OPENCLAW_SECRET_ONLY_ENV_KEYS = [
+    'SLACK_BOT_TOKEN',
+    'SLACK_APP_TOKEN',
+    'SLACK_USER_TOKEN',
+    'SLACK_SIGNING_SECRET',
+    'SLACK_RELAY_AUTH_TOKEN',
+];
+function rejectOpenClawSecretOnlyEnv(env, noun = 'env') {
+    const matches = OPENCLAW_SECRET_ONLY_ENV_KEYS.filter((key) => Object.prototype.hasOwnProperty.call(env, key));
+    if (matches.length > 0) {
+        throw new Error(`${matches.join(', ')} must be supplied through secrets, not ${noun}`);
+    }
+}
+function cloneCompleteLaunchConfig(value) {
+    if (!isPlainRecord(value))
+        throw new Error('launchConfig must be a complete object');
+    const missing = REQUIRED_START_LAUNCH_CONFIG_KEYS.filter((key) => !Object.prototype.hasOwnProperty.call(value, key));
+    if (missing.length > 0) {
+        throw new Error(`launchConfig is incomplete; missing: ${missing.join(', ')}`);
+    }
+    if (Object.prototype.hasOwnProperty.call(value, 'sync_include')
+        && Object.prototype.hasOwnProperty.call(value, 'sync_exclude')) {
+        throw new Error('launchConfig cannot carry both sync policies');
+    }
+    if (Array.isArray(value.sync_include) && value.sync_include.length === 0) {
+        throw new Error('syncInclude must contain at least one path; omit it to sync all');
+    }
+    if (Array.isArray(value.sync_exclude) && (value.sync_exclude.includes('*') || value.sync_exclude.includes('**'))) {
+        throw new Error('syncExclude cannot exclude the entire sync root; omit it to sync all');
+    }
+    if (typeof value.restart !== 'boolean') {
+        throw new Error('launchConfig restart must be a boolean');
+    }
+    const executor = value.executor;
+    if (executor !== undefined && executor !== null && executor !== 'process' && executor !== 'docker') {
+        throw new Error("launchConfig executor must be 'process' or 'docker'");
+    }
+    if (executor === 'process' && value.docker != null) {
+        throw new Error('docker launch options require the docker executor');
+    }
+    return structuredClone(value);
+}
+export const OPENCLAW_TRUSTED_PROXIES_ENV = 'OPENCLAW_TRUSTED_PROXIES';
+const DEFAULT_OPENCLAW_MODEL_ENV = Object.freeze({
+    HYPER_MODELS: 'default-anthropic',
+    HYPER_EMBEDDING_MODELS: 'qwen3-embedding-4b',
+});
+const DEFAULT_HERMES_MODEL_ENV = DEFAULT_OPENCLAW_MODEL_ENV;
+export function buildOpenClawTrustedProxiesEnv(trustedProxies) {
+    const proxies = (trustedProxies ?? []).map((proxy) => proxy.trim()).filter(Boolean);
+    return proxies.length > 0 ? { [OPENCLAW_TRUSTED_PROXIES_ENV]: proxies.join(',') } : {};
+}
+function droppedLaunchConfigKeys(data) {
+    const warnings = Array.isArray(data.warnings) ? data.warnings : [];
+    return warnings
+        .filter((warning) => (Boolean(warning) && typeof warning === 'object'))
+        .filter((warning) => warning.code === 'unsupported_launch_config_keys_dropped')
+        .flatMap((warning) => (Array.isArray(warning.dropped_keys) ? warning.dropped_keys.map(String) : []));
+}
+function buildBuzzLaunchEnv(runtime, buzz) {
+    if (!buzz.privateKeyNsec.trim())
+        throw new Error('buzz.privateKeyNsec is required');
+    if (!buzz.relayUrl.trim())
+        throw new Error('buzz.relayUrl is required');
+    const harness = BUZZ_RUNTIME_COMMANDS[runtime];
+    const env = {
+        BUZZ_RELAY_URL: buzz.relayUrl,
+        BUZZ_ACP_AGENT_COMMAND: harness.command,
+        BUZZ_ACP_AGENT_ARGS: harness.args.join(','),
+    };
+    if (runtime === 'claude-code') {
+        env.CLAUDE_CODE_EXECUTABLE = '/opt/hypercli/bin/claude';
+    }
+    if (buzz.rustLog)
+        env.RUST_LOG = buzz.rustLog;
+    const optional = {
+        BUZZ_ACP_MODEL: buzz.model,
+        BUZZ_ACP_RESPOND_TO: buzz.respondTo,
+        BUZZ_ACP_RESPOND_TO_ALLOWLIST: buzz.respondToAllowlist?.length
+            ? buzz.respondToAllowlist.join(',')
+            : undefined,
+    };
+    for (const [key, value] of Object.entries(optional)) {
+        if (value)
+            env[key] = value;
+    }
+    return env;
+}
+function buildBuzzLaunchSecrets(buzz) {
+    if (!buzz.privateKeyNsec.trim())
+        throw new Error('buzz.privateKeyNsec is required');
+    const secrets = {
+        BUZZ_PRIVATE_KEY: buzz.privateKeyNsec,
+    };
+    // The NIP-OA attestation is a bearer credential: keep it in the k8s-backed
+    // secrets projection (unrolled to env at launch) rather than plaintext env.
+    if (buzz.authTag)
+        secrets.BUZZ_AUTH_TAG = buzz.authTag;
+    return secrets;
+}
+/** Construct the Buzz-owned launch fields for create or a stopped deployment update.
+ * Callers retain all other stored launch fields. No network or identity generation.
+ */
+export function buildBuzzLaunchConfig(runtime, buzz, apiBase, stored = {}) {
+    if (!Object.prototype.hasOwnProperty.call(BUZZ_RUNTIME_COMMANDS, runtime)) {
+        throw new Error('Buzz requires a coding runtime');
+    }
+    const env = { ...(stored.env ?? {}) };
+    const secrets = { ...(stored.secrets ?? {}) };
+    if (buzz) {
+        for (const key of BUZZ_RESERVED_ENV_KEYS) {
+            delete env[key];
+            delete secrets[key];
+        }
+        Object.assign(env, buildBuzzLaunchEnv(runtime, buzz));
+        Object.assign(secrets, buildBuzzLaunchSecrets(buzz));
+    }
+    env.RUST_LOG ??= DEFAULT_BUZZ_RUST_LOG;
+    for (const key of [
+        'HYPER_ACP_WS_LISTEN', 'HYPER_ACP_LOG', 'HYPER_ACP_WS_TOKEN',
+        'BUZZ_ACP_RELAY_OBSERVER', 'HYPER_ACP_AGENT_COMMAND', 'HYPER_ACP_AGENT_ARGS',
+        'HYPER_ACP_AUTO_APPROVE_PERMISSION', 'HYPER_ACP_PERMISSIONS', 'HYPER_ACP_PERMISSION_MODE',
+    ]) {
+        delete env[key];
+        delete secrets[key];
+    }
+    env.HYPER_ACP_WS_URL = defaultHyperAcpWsUrl(apiBase);
+    return { ...stored, env, secrets, routes: {}, restart: false,
+        command: [stored.executor === 'process' ? 'hyper-acp' : '/usr/local/bin/hyper-acp'] };
+}
+/** Whether the runtime has a Buzz coding harness launch mapping. */
+export function supportsBuzzRuntime(runtime) {
+    return typeof runtime === 'string' && Object.prototype.hasOwnProperty.call(BUZZ_RUNTIME_COMMANDS, runtime);
+}
+/** Maximum decoded bytes for the native runner file transport. */
+export const RUNNER_FILE_MAX_BYTES = 50 * 1024 * 1024;
+function nativeFilePath(path) {
+    if (!path || encodeUtf8(path).byteLength > 4096 || /[\\:\0]/.test(path)
+        || path.split('/').some((part) => !part || part === '.' || part === '..' || /[ .]$/.test(part))) {
+        throw new Error('Runner file paths must be portable paths relative to the assignment root');
+    }
+    return path;
+}
+function resolveSyncRootFilePath(path) {
+    const normalized = path.replace(/\\/g, '/');
+    if (normalized.startsWith('/') || /^[a-z]:/i.test(normalized) || normalized.includes('\0')) {
+        throw new Error('agent file paths must be relative to the sync root');
+    }
+    const parts = normalized.split('/');
+    if (parts.includes('..')) {
+        throw new Error('agent file paths must stay within the sync root');
+    }
+    return parts.filter((part) => part && part !== '.').join('/');
+}
+function normalizeWritableBackendFilePath(path) {
+    return resolveSyncRootFilePath(path);
+}
+function isUuidRef(value) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value.trim());
+}
+function isDirectAgentIdRef(value) {
+    const raw = value.trim();
+    return isUuidRef(raw) || /^[0-9a-f]{6,}$/i.test(raw) || /^(agent|external)[-_:]/i.test(raw);
+}
+function isSelfAgentRef(value) {
+    return value.trim().toLowerCase() === 'self';
+}
+function agentRoutesStateFromData(data) {
+    return {
+        agentId: String(data.agent_id ?? ''),
+        routes: structuredClone(data.routes ?? {}),
+        cors: data.cors === null || data.cors === undefined ? null : structuredClone(data.cors),
+        routeStatuses: structuredClone(data.route_statuses ?? {}),
+    };
+}
+function agentAccessIdentityFromData(data) {
+    const payload = data ?? {};
+    const agentId = payload.agent_id ? String(payload.agent_id) : null;
+    return {
+        userId: String(payload.user_id ?? ''),
+        authType: String(payload.auth_type ?? ''),
+        agentId,
+        tags: (payload.tags ?? []).map((tag) => String(tag)),
+        capabilities: (payload.capabilities ?? []).map((item) => String(item)),
+        keyId: payload.key_id ? String(payload.key_id) : null,
+        keyName: payload.key_name ? String(payload.key_name) : null,
+        teamId: payload.team_id ? String(payload.team_id) : null,
+        planId: payload.plan_id ? String(payload.plan_id) : null,
+        isAgentRuntimeKey: Boolean(agentId),
+    };
+}
+/** Backend-discovered file access scoped to an agent's retained storage root. */
+export class AgentFiles {
+    agent;
+    deployments;
+    constructor(agent, deployments) {
+        this.agent = agent;
+        this.deployments = deployments;
+    }
+    async list(path = '') {
+        return this.deployments.filesList(this.agent, path);
+    }
+    async readBytes(path, options) {
+        return this.deployments.fileReadBytes(this.agent, path, options);
+    }
+    async readBytesWithMetadata(path, options) {
+        return this.deployments.fileReadBytesWithMetadata(this.agent, path, options);
+    }
+    async read(path, options) {
+        return this.deployments.fileRead(this.agent, path, options);
+    }
+    async writeBytes(path, content, options = {}) {
+        return this.deployments.fileWriteBytes(this.agent, path, content, options);
+    }
+    async write(path, content) {
+        return this.deployments.fileWrite(this.agent, path, content);
+    }
+    async delete(path, options = {}) {
+        return this.deployments.fileDelete(this.agent, path, options);
+    }
+}
+/** Canonical states understood by this SDK. AgentState remains forward-open. */
+export const CANONICAL_AGENT_STATES = [
+    'CREATING',
+    'STARTING',
+    'RESTORING',
+    'RUNNING',
+    'STOPPING',
+    'STOPPED',
+    'ARCHIVING',
+    'ARCHIVED',
+    'FAILED',
+    'NO_NAMESPACE',
+    'DELETED',
+];
+export const AGENT_TRANSITIONAL_STATES = new Set([
+    'CREATING',
+    'STARTING',
+    'RESTORING',
+    'STOPPING',
+    'ARCHIVING',
+]);
+export const AGENT_RUNTIME_INACTIVE_STATES = new Set([
+    'STOPPED',
+    'ARCHIVING',
+    'ARCHIVED',
+    'FAILED',
+    'NO_NAMESPACE',
+    'DELETED',
+]);
+export function isAgentTransitionalState(state) {
+    return AGENT_TRANSITIONAL_STATES.has(state.toUpperCase());
+}
+export function isAgentRuntimeInactiveState(state) {
+    return AGENT_RUNTIME_INACTIVE_STATES.has(state.toUpperCase());
+}
+function parseDate(value) {
+    if (typeof value !== 'string' || !value)
+        return null;
+    return new Date(value.replace('Z', '+00:00'));
+}
+function metaStatusFromDict(data) {
+    if (!isPlainRecord(data))
+        return null;
+    const observed = data.observed_state === 'RUNNING' || data.observed_state === 'STOPPED'
+        ? data.observed_state
+        : null;
+    return {
+        status: typeof data.status === 'string' ? data.status : '',
+        clusterId: typeof data.cluster_id === 'string' ? data.cluster_id : null,
+        namespace: typeof data.namespace === 'string' ? data.namespace : null,
+        observedState: observed,
+        reason: typeof data.reason === 'string' ? data.reason : null,
+        message: typeof data.message === 'string' ? data.message : null,
+        observedAt: typeof data.observed_at === 'string' ? data.observed_at : null,
+    };
+}
+function agentMetaFromDict(data) {
+    if (!isPlainRecord(data))
+        return null;
+    const meta = structuredClone(data);
+    if (Object.prototype.hasOwnProperty.call(data, 'status')) {
+        meta.status = metaStatusFromDict(data.status);
+    }
+    return meta;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isTruthyEnv(value) {
+    return ['1', 'true', 'yes', 'on', 'enabled'].includes(String(value ?? '').trim().toLowerCase());
+}
+function isFalseyEnv(value) {
+    return ['0', 'false', 'no', 'off', 'disabled'].includes(String(value ?? '').trim().toLowerCase());
+}
+function isPlainRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function flattenConfigValue(value, prefix, out) {
+    if (!prefix) {
+        if (isPlainRecord(value)) {
+            for (const [key, child] of Object.entries(value)) {
+                flattenConfigValue(child, key, out);
+            }
+            return;
+        }
+        out[''] = value;
+        return;
+    }
+    out[prefix] = value;
+    if (Array.isArray(value)) {
+        value.forEach((child, index) => flattenConfigValue(child, `${prefix}[${index}]`, out));
+        return;
+    }
+    if (isPlainRecord(value)) {
+        for (const [key, child] of Object.entries(value)) {
+            flattenConfigValue(child, `${prefix}.${key}`, out);
+        }
+    }
+}
+export function flattenLaunchConfig(launchConfig) {
+    const flat = {};
+    if (!isPlainRecord(launchConfig))
+        return flat;
+    flattenConfigValue(launchConfig, '', flat);
+    return flat;
+}
+function pathParts(path) {
+    if (Array.isArray(path))
+        return path;
+    const parts = [];
+    for (const part of path.replace(/\[(\d+)\]/g, '.$1').split('.')) {
+        if (!part)
+            continue;
+        parts.push(/^\d+$/.test(part) ? Number(part) : part);
+    }
+    return parts;
+}
+export function getLaunchConfigValue(launchConfig, path) {
+    let current = launchConfig;
+    for (const part of pathParts(path)) {
+        if (typeof part === 'number') {
+            if (!Array.isArray(current))
+                return undefined;
+            current = current[part];
+            continue;
+        }
+        if (!isPlainRecord(current))
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+export function routesHaveDesktop(routes) {
+    if (!isPlainRecord(routes))
+        return false;
+    if (isPlainRecord(routes.desktop))
+        return true;
+    return Object.values(routes).some((route) => isPlainRecord(route) && route.prefix === 'desktop');
+}
+export function launchConfigHasDesktop(launchConfig) {
+    if (!isPlainRecord(launchConfig))
+        return false;
+    const desktopEnabled = getLaunchConfigValue(launchConfig, 'env.HYPER_DESKTOP_ENABLED');
+    if (isFalseyEnv(desktopEnabled))
+        return false;
+    if (isTruthyEnv(desktopEnabled))
+        return true;
+    return routesHaveDesktop(getLaunchConfigValue(launchConfig, 'routes'));
+}
+export function agentConfigHasDesktop(source) {
+    if (!source)
+        return false;
+    const launchConfig = source.launchConfig ?? source.launch_config;
+    const desktopEnabled = getLaunchConfigValue(launchConfig, 'env.HYPER_DESKTOP_ENABLED');
+    if (isFalseyEnv(desktopEnabled))
+        return false;
+    return (launchConfigHasDesktop(launchConfig) ||
+        routesHaveDesktop(source.routes));
+}
+function browserDesktopRedirectPath(options = {}) {
+    const redirect = (options.redirect ?? 'vnc_lite.html').trim() || 'vnc_lite.html';
+    if (redirect.includes('\\')) {
+        throw new Error('Desktop redirect must be a relative path');
+    }
+    const base = 'https://desktop.local';
+    const parsed = new URL(redirect, `${base}/`);
+    if (parsed.origin !== base) {
+        throw new Error('Desktop redirect must be a relative path');
+    }
+    if (options.resize !== null) {
+        const resize = options.resize ?? 'scale';
+        if (resize.trim()) {
+            // vnc_lite.html (the default viewer) takes `scale=true`; the full vnc.html
+            // UI takes `resize=scale`. Emit the parameter for whichever page the
+            // redirect targets.
+            const targetsLite = (parsed.pathname.endsWith('vnc_lite.html') || parsed.pathname.endsWith('vnc_auto.html'));
+            if (targetsLite)
+                parsed.searchParams.set('scale', resize === 'scale' ? 'true' : resize);
+            else
+                parsed.searchParams.set('resize', resize);
+        }
+    }
+    const pathname = parsed.pathname.replace(/^\/+/, '') || 'vnc_lite.html';
+    return `${pathname}${parsed.search}${parsed.hash}`;
+}
+export function buildBrowserDesktopUrl(desktopBaseUrl, token, options = {}) {
+    const jwt = token.trim();
+    if (!jwt)
+        throw new Error('Desktop token is required');
+    const url = new URL('/_jwt_auth', desktopBaseUrl);
+    url.searchParams.set('jwt', jwt);
+    url.searchParams.set('redirect', browserDesktopRedirectPath(options));
+    return url.toString();
+}
+function isDirectoryListingPayload(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const payload = value;
+    return (payload.type === 'directory' &&
+        Array.isArray(payload.directories) &&
+        Array.isArray(payload.files));
+}
+export { defaultAcpProxyWsUrl, defaultHyperAcpWsUrl, resolveAgentsApiBase } from './agent-urls.js';
+function randomHexToken(bytes) {
+    const buffer = new Uint8Array(bytes);
+    if (globalThis.crypto?.getRandomValues) {
+        globalThis.crypto.getRandomValues(buffer);
+    }
+    else {
+        randomFillSync(bytes ? buffer.subarray(0, bytes) : buffer);
+    }
+    return Array.from(buffer, (value) => value.toString(16).padStart(2, '0')).join('');
+}
+function encodeFilePath(path) {
+    return path
+        .replace(/^\/+/, '')
+        .split('/')
+        .filter(Boolean)
+        .map((part) => encodeURIComponent(part))
+        .join('/');
+}
+function decodeUtf8(content) {
+    return new TextDecoder().decode(content);
+}
+function encodeUtf8(content) {
+    return new TextEncoder().encode(content);
+}
+function encodeBase64(data) {
+    if (typeof Buffer !== 'undefined') {
+        return Buffer.from(data).toString('base64');
+    }
+    // Browser fallback: btoa over chunked binary string (avoids arg-limit blowups)
+    let binary = '';
+    const CHUNK = 0x8000;
+    for (let i = 0; i < data.length; i += CHUNK) {
+        binary += String.fromCharCode(...data.subarray(i, i + CHUNK));
+    }
+    return btoa(binary);
+}
+function fileReadLimitError(path, maxBytes) {
+    return new Error(`File ${path} exceeds the ${maxBytes / 1024 / 1024} MiB read limit`);
+}
+async function readResponseBytes(response, path, maxBytes) {
+    if (maxBytes === undefined)
+        return new Uint8Array(await response.arrayBuffer());
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {
+        throw new RangeError('maxBytes must be a non-negative safe integer');
+    }
+    const contentLength = Number(response.headers.get('content-length'));
+    if (Number.isFinite(contentLength) && contentLength > maxBytes) {
+        await response.body?.cancel();
+        throw fileReadLimitError(path, maxBytes);
+    }
+    if (!response.body) {
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        if (bytes.byteLength > maxBytes)
+            throw fileReadLimitError(path, maxBytes);
+        return bytes;
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let totalBytes = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            totalBytes += value.byteLength;
+            if (totalBytes > maxBytes) {
+                await reader.cancel();
+                throw fileReadLimitError(path, maxBytes);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(totalBytes);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
+function toUint8Array(content) {
+    if (typeof content === 'string')
+        return encodeUtf8(content);
+    if (content instanceof Uint8Array)
+        return content;
+    return new Uint8Array(content);
+}
+function execResultFromDict(data) {
+    return {
+        exitCode: data.exit_code ?? -1,
+        stdout: data.stdout || '',
+        stderr: data.stderr || '',
+    };
+}
+function ownKeysEqual(value, expected) {
+    const keys = Object.keys(value).sort();
+    return keys.length === expected.length
+        && keys.every((key, index) => key === [...expected].sort()[index]);
+}
+function validateAgentWsToken(value, agentId, purpose, shell) {
+    const base = purpose === 'shell'
+        ? ['agent_id', 'expires_at', 'shell', 'ws_url']
+        : ['agent_id', 'expires_at', 'ws_url'];
+    const invalid = () => new Error(`Backend returned an invalid Agent ${purpose} token response`);
+    if (!isPlainRecord(value))
+        throw invalid();
+    if (!ownKeysEqual(value, [...base, 'token']) || typeof value.token !== 'string' || !value.token) {
+        throw invalid();
+    }
+    if (value.agent_id !== agentId
+        || typeof value.expires_at !== 'string'
+        || !value.expires_at
+        || typeof value.ws_url !== 'string'
+        || !value.ws_url
+        || (purpose === 'shell' && value.shell !== shell)) {
+        throw invalid();
+    }
+    let parsed;
+    try {
+        parsed = new URL(value.ws_url);
+    }
+    catch {
+        throw invalid();
+    }
+    if (!['ws:', 'wss:'].includes(parsed.protocol)
+        || !parsed.hostname
+        || parsed.username
+        || parsed.password
+        || parsed.search
+        || parsed.hash
+        || !parsed.pathname.endsWith(`/ws/${purpose}/${agentId}`)) {
+        throw invalid();
+    }
+    return value;
+}
+function validateDeploymentEventToken(value) {
+    const invalid = () => new Error('Backend returned an invalid deployment event token response');
+    if (!isPlainRecord(value) || !ownKeysEqual(value, ['token', 'ws_url']))
+        throw invalid();
+    if (typeof value.token !== 'string' || !value.token || typeof value.ws_url !== 'string' || !value.ws_url) {
+        throw invalid();
+    }
+    let parsed;
+    try {
+        parsed = new URL(value.ws_url);
+    }
+    catch {
+        throw invalid();
+    }
+    if (!['ws:', 'wss:'].includes(parsed.protocol) || !parsed.hostname || parsed.search || parsed.hash) {
+        throw invalid();
+    }
+    return { token: value.token, ws_url: value.ws_url };
+}
+function validateAgentLogsToken(value) {
+    const invalid = () => new Error('Backend returned an invalid Agent logs token response');
+    if (!isPlainRecord(value))
+        throw invalid();
+    if (!ownKeysEqual(value, ['agent_id', 'expires_at', 'token', 'ws_url']))
+        throw invalid();
+    if (typeof value.token !== 'string' || !value.token)
+        throw invalid();
+    if (typeof value.agent_id !== 'string' || !value.agent_id)
+        throw invalid();
+    if (typeof value.expires_at !== 'string' || !value.expires_at)
+        throw invalid();
+    if (typeof value.ws_url !== 'string' || !value.ws_url)
+        throw invalid();
+    if (typeof value.ws_url === 'string') {
+        let parsed;
+        try {
+            parsed = new URL(value.ws_url);
+        }
+        catch {
+            throw invalid();
+        }
+        if (!['ws:', 'wss:'].includes(parsed.protocol) || !parsed.hostname || parsed.search || parsed.hash) {
+            throw invalid();
+        }
+    }
+    return value;
+}
+function validateAgentMetricsResult(value) {
+    if (!isPlainRecord(value) || value.event !== 'agent_metrics_result') {
+        throw new Error('Agent metrics WebSocket returned an invalid result frame');
+    }
+    if (value.ok === false && ownKeysEqual(value, ['error', 'event', 'ok'])
+        && typeof value.error === 'string' && value.error) {
+        throw new Error(value.error);
+    }
+    if (value.ok !== true
+        || !ownKeysEqual(value, ['cpu', 'event', 'memory', 'ok', 'timestamp'])
+        || typeof value.cpu !== 'string'
+        || typeof value.memory !== 'string'
+        || !Number.isInteger(value.timestamp)) {
+        throw new Error('Agent metrics WebSocket returned an invalid result frame');
+    }
+    return value;
+}
+function validateAgentExecResult(value) {
+    if (!isPlainRecord(value) || value.event !== 'agent_exec_result') {
+        throw new Error('Agent exec WebSocket returned an invalid result frame');
+    }
+    if (value.ok === false && ownKeysEqual(value, ['error', 'event', 'ok'])
+        && typeof value.error === 'string' && value.error) {
+        throw new Error(value.error);
+    }
+    if (value.ok !== true
+        || !ownKeysEqual(value, ['event', 'exit_code', 'ok', 'stderr', 'stdout'])
+        || !Number.isInteger(value.exit_code)
+        || typeof value.stdout !== 'string'
+        || typeof value.stderr !== 'string') {
+        throw new Error('Agent exec WebSocket returned an invalid result frame');
+    }
+    return execResultFromDict(value);
+}
+function agentStateFromDict(data) {
+    const launchConfig = isPlainRecord(data.launch_config) ? structuredClone(data.launch_config) : null;
+    if (launchConfig) {
+        delete launchConfig.secrets;
+    }
+    return {
+        id: data.id ?? '',
+        userId: data.user_id ?? '',
+        state: data.state ?? 'unknown',
+        name: data.name ?? null,
+        handle: data.handle ?? null,
+        displayName: data.display_name ?? data.name ?? null,
+        avatarUrl: data.avatar_url ?? null,
+        avatarAudioUrl: data.avatar_audio_url ?? null,
+        displayIdentity: data.display_identity ? structuredClone(data.display_identity) : null,
+        runtime: data.runtime ?? null,
+        managed: data.managed ?? null,
+        isLaunchable: data.is_launchable ?? data.managed !== false,
+        gatewayId: data.gateway_id ?? null,
+        relayKey: data.relay_key ?? null,
+        cpu: data.cpu ?? 0,
+        memory: data.memory ?? 0,
+        requestedSize: data.requested_size == null
+            ? null
+            : parseAgentSlotSize(data.requested_size, 'Agent requested_size'),
+        hostname: data.hostname ?? null,
+        tags: Array.isArray(data.tags) ? data.tags : [],
+        jwtToken: data.jwt_token ?? null,
+        jwtExpiresAt: parseDate(data.jwt_expires_at),
+        startedAt: parseDate(data.started_at),
+        stoppedAt: parseDate(data.stopped_at),
+        archivedAt: parseDate(data.archived_at),
+        // Independently nullable from archivedAt: SPEC has a new Agent with
+        // neither, an ARCHIVED Agent with both, and a restored Agent with a
+        // prefix but no archivedAt. Dropping it made that tri-state unreadable.
+        archivePrefix: typeof data.archive_prefix === 'string' ? data.archive_prefix : null,
+        deletedAt: parseDate(data.deleted_at),
+        disconnectedAt: parseDate(data.disconnected_at),
+        agentSlotId: typeof data.agent_slot_id === 'string' ? data.agent_slot_id : null,
+        clusterId: data.cluster_id ?? null,
+        runner: isPlainRecord(data.runner)
+            ? {
+                tags: Array.isArray(data.runner.tags) ? data.runner.tags.map(String) : [],
+                runnerId: typeof data.runner.runner_id === 'string' ? data.runner.runner_id : null,
+            }
+            : null,
+        launchEpoch: data.launch_epoch ?? 0,
+        createdAt: parseDate(data.created_at),
+        updatedAt: parseDate(data.updated_at),
+        launchConfig,
+        meta: agentMetaFromDict(data.meta),
+        routes: data.routes ?? (isPlainRecord(launchConfig?.routes)
+            ? launchConfig.routes
+            : {}),
+        command: data.command ?? (Array.isArray(launchConfig?.command) ? launchConfig.command : []),
+        entrypoint: data.entrypoint ?? (Array.isArray(launchConfig?.entrypoint) ? launchConfig.entrypoint : []),
+        dryRun: Boolean(data.dry_run),
+    };
+}
+function normalizeExecutor(executor) {
+    // undefined/null leaves the stored executor alone; the Backend treats
+    // pre-existing runner rows without one as docker.
+    if (executor === undefined || executor === null)
+        return undefined;
+    if (executor !== 'process' && executor !== 'docker') {
+        throw new Error("executor must be 'process' or 'docker'");
+    }
+    return executor;
+}
+function normalizeDockerOptions(docker) {
+    // undefined leaves stored runner docker options alone; null (or an empty
+    // volumes list) clears them, because the Backend treats provided-but-empty
+    // docker as absent on a replacement write.
+    if (docker === undefined)
+        return undefined;
+    if (docker === null)
+        return null;
+    if (!isPlainRecord(docker))
+        throw new Error('docker accepts only a volumes list');
+    const extra = Object.keys(docker).filter((key) => key !== 'volumes');
+    if (extra.length > 0)
+        throw new Error(`Unsupported docker settings: ${extra.sort().join(', ')}`);
+    const volumes = docker.volumes ?? [];
+    if (!Array.isArray(volumes) || volumes.some((volume) => typeof volume !== 'string')) {
+        throw new Error('docker volumes must be a list of strings');
+    }
+    if (volumes.length > MAX_DOCKER_VOLUMES) {
+        throw new Error(`docker volumes accept at most ${MAX_DOCKER_VOLUMES} entries`);
+    }
+    for (const volume of volumes) {
+        const segments = volume.split(':');
+        if (segments.length < 2 || segments.length > 3) {
+            throw new Error(`docker volume must be source:target[:ro]: ${volume}`);
+        }
+        const [source, target] = segments;
+        if (!source || !target || volume.includes('\0')) {
+            throw new Error(`docker volume paths must be non-empty and NUL-free: ${volume}`);
+        }
+        if (!source.startsWith('/') || !target.startsWith('/')) {
+            throw new Error(`docker volume source and target must be absolute: ${volume}`);
+        }
+        if (segments.length === 3 && segments[2] !== 'ro') {
+            throw new Error(`docker volume mode must be ro or omitted: ${volume}`);
+        }
+    }
+    if (volumes.length === 0)
+        return null;
+    return { volumes: [...volumes] };
+}
+export function buildAgentConfig(config = {}, options = {}) {
+    const preparedConfig = structuredClone(config);
+    const nestedLaunchKeys = Object.keys(preparedConfig).filter((key) => LAUNCH_CONFIG_KEYS.has(key));
+    if (nestedLaunchKeys.length) {
+        throw new Error(`Launch settings must be top-level fields, not nested under config: ${nestedLaunchKeys.join(', ')}`);
+    }
+    const env = { ...(options.env ?? {}) };
+    const secrets = { ...(options.secrets ?? {}) };
+    const collidingKeys = Object.keys(env).filter((key) => Object.prototype.hasOwnProperty.call(secrets, key));
+    if (collidingKeys.length > 0) {
+        throw new Error(`Launch keys cannot appear in both env and secrets: ${collidingKeys.join(', ')}`);
+    }
+    const normalizeSyncOwner = (value, field) => {
+        if (value === undefined || value === null)
+            return undefined;
+        if (!Number.isSafeInteger(value) || value < 0 || value > 4_294_967_294) {
+            throw new Error(`${field} must be an integer between 0 and 4294967294`);
+        }
+        return value;
+    };
+    const syncUid = normalizeSyncOwner(options.syncUid, 'syncUid');
+    const syncGid = normalizeSyncOwner(options.syncGid, 'syncGid');
+    let registryAuth = {};
+    if (options.registryAuth !== undefined && options.registryAuth !== null) {
+        const keys = Object.keys(options.registryAuth).sort();
+        if (keys.length !== 2 || keys[0] !== 'password' || keys[1] !== 'username') {
+            throw new Error('registryAuth requires exactly username and password');
+        }
+        const username = options.registryAuth.username.trim();
+        if (!username)
+            throw new Error('registryAuth username must be non-empty');
+        if (!options.registryAuth.password)
+            throw new Error('registryAuth password must be non-empty');
+        registryAuth = { username, password: options.registryAuth.password };
+    }
+    const prepared = {
+        image: options.image ?? null,
+        env,
+        secrets,
+        routes: routesConfigBody(options.routes),
+        command: [...(options.command ?? [])],
+        entrypoint: [...(options.entrypoint ?? [])],
+        restart: options.restart ?? false,
+        sync_root: options.syncRoot ?? null,
+        sync_uid: syncUid ?? null,
+        sync_gid: syncGid ?? null,
+        registry_url: options.registryUrl ?? null,
+        registry_auth: registryAuth,
+        runtime_scopes: [...(options.runtimeScopes ?? DEFAULT_AGENT_RUNTIME_SCOPES)],
+    };
+    if (Object.keys(preparedConfig).length > 0)
+        prepared.config = preparedConfig;
+    if (options.cors !== undefined)
+        prepared.cors = options.cors === null ? null : structuredClone(options.cors);
+    if (options.syncInclude !== undefined) {
+        if (options.syncInclude !== null && options.syncInclude.length === 0) {
+            throw new Error('syncInclude must contain at least one path; omit it to sync all');
+        }
+        prepared.sync_include = options.syncInclude === null ? null : [...options.syncInclude];
+    }
+    if (options.syncInclude === undefined && options.syncExclude !== undefined) {
+        if (options.syncExclude !== null && (options.syncExclude.includes('*') || options.syncExclude.includes('**'))) {
+            throw new Error('syncExclude cannot exclude the entire sync root; omit it to sync all');
+        }
+        prepared.sync_exclude = options.syncExclude === null ? null : [...options.syncExclude];
+    }
+    const docker = normalizeDockerOptions(options.docker);
+    const executor = normalizeExecutor(options.executor);
+    if (executor === 'process' && docker != null) {
+        throw new Error('docker launch options require the docker executor');
+    }
+    if (docker !== undefined)
+        prepared.docker = docker;
+    if (executor !== undefined)
+        prepared.executor = executor;
+    if (options.cwd !== undefined)
+        prepared.cwd = options.cwd;
+    return { config: prepared };
+}
+function buildAgentCreateConfig(config, options) {
+    const complete = buildAgentConfig(config, options).config;
+    const prepared = {};
+    if (complete.config && Object.keys(complete.config).length > 0)
+        prepared.config = complete.config;
+    if (Object.keys(complete.env).length > 0)
+        prepared.env = complete.env;
+    if (Object.keys(complete.secrets).length > 0)
+        prepared.secrets = complete.secrets;
+    if (options.routes !== undefined && options.routes !== null)
+        prepared.routes = complete.routes;
+    if (options.command !== undefined && options.command !== null)
+        prepared.command = complete.command;
+    if (options.entrypoint !== undefined && options.entrypoint !== null)
+        prepared.entrypoint = complete.entrypoint;
+    if (options.image !== undefined && options.image !== null)
+        prepared.image = complete.image;
+    if (options.syncRoot !== undefined && options.syncRoot !== null)
+        prepared.sync_root = complete.sync_root;
+    if (Object.prototype.hasOwnProperty.call(complete, 'sync_include')) {
+        prepared.sync_include = complete.sync_include;
+    }
+    else if (Object.prototype.hasOwnProperty.call(complete, 'sync_exclude')) {
+        prepared.sync_exclude = complete.sync_exclude;
+    }
+    if (options.syncUid !== undefined && options.syncUid !== null)
+        prepared.sync_uid = complete.sync_uid;
+    if (options.syncGid !== undefined && options.syncGid !== null)
+        prepared.sync_gid = complete.sync_gid;
+    if (options.registryUrl !== undefined && options.registryUrl !== null)
+        prepared.registry_url = complete.registry_url;
+    if (options.registryAuth !== undefined && options.registryAuth !== null)
+        prepared.registry_auth = complete.registry_auth;
+    if (Object.prototype.hasOwnProperty.call(complete, 'cors') && complete.cors != null) {
+        prepared.cors = complete.cors;
+    }
+    prepared.restart = complete.restart;
+    if (options.runtimeScopes !== undefined && options.runtimeScopes !== null)
+        prepared.runtime_scopes = complete.runtime_scopes;
+    if (complete.docker)
+        prepared.docker = complete.docker;
+    if (complete.executor !== undefined)
+        prepared.executor = complete.executor;
+    if (complete.cwd !== undefined)
+        prepared.cwd = complete.cwd;
+    return prepared;
+}
+export async function startSlackOAuth(options) {
+    const relayBaseUrl = normalizeSlackRelayBaseUrl(options.relayBaseUrl);
+    if (!relayBaseUrl)
+        throw new Error('Slack relay base URL is required');
+    if (!options.token)
+        throw new Error('Slack OAuth requires an app token');
+    const response = await fetch(`${relayBaseUrl}/slack/oauth/start`, {
+        method: 'GET',
+        headers: {
+            'Authorization': `Bearer ${options.token}`,
+        },
+    });
+    if (!response.ok) {
+        let detail = response.statusText || 'Slack OAuth start failed';
+        try {
+            const payload = await response.json();
+            if (typeof payload.detail === 'string' && payload.detail)
+                detail = payload.detail;
+        }
+        catch {
+            // Keep the HTTP status text when the error body is not JSON.
+        }
+        throw new APIError(response.status, detail);
+    }
+    const payload = await response.json();
+    const authorizeUrl = typeof payload.authorize_url === 'string' ? payload.authorize_url : '';
+    if (!authorizeUrl)
+        throw new Error('Slack OAuth start did not return an authorization URL');
+    return {
+        authorizeUrl,
+        expiresAt: typeof payload.expires_at === 'string' ? payload.expires_at : null,
+    };
+}
+export async function getSlackInstallStatus(options) {
+    const relayBaseUrl = normalizeSlackRelayBaseUrl(options.relayBaseUrl);
+    if (!relayBaseUrl)
+        throw new Error('Slack relay base URL is required');
+    if (!options.token)
+        throw new Error('Slack install status requires an app token');
+    const response = await fetch(`${relayBaseUrl}/slack/install`, {
+        method: 'GET',
+        headers: { 'Authorization': `Bearer ${options.token}` },
+    });
+    if (!response.ok) {
+        let detail = response.statusText || 'Slack install status failed';
+        try {
+            const payload = await response.json();
+            if (typeof payload.detail === 'string' && payload.detail)
+                detail = payload.detail;
+        }
+        catch {
+            // Keep the HTTP status text when the error body is not JSON.
+        }
+        throw new APIError(response.status, detail);
+    }
+    const payload = await response.json();
+    return {
+        connected: payload.connected === true,
+        teamId: typeof payload.team_id === 'string' ? payload.team_id : null,
+        teamName: typeof payload.team_name === 'string' ? payload.team_name : null,
+        botUserId: typeof payload.bot_user_id === 'string' ? payload.bot_user_id : null,
+        installerUserId: typeof payload.installer_user_id === 'string' ? payload.installer_user_id : null,
+        updatedAt: typeof payload.updated_at === 'string' ? payload.updated_at : null,
+    };
+}
+function slackRelayAuthorizedUrl(path, options) {
+    const relayBaseUrl = normalizeSlackRelayBaseUrl(options.relayBaseUrl);
+    if (!relayBaseUrl)
+        throw new Error('Slack relay base URL is required');
+    if (!options.token)
+        throw new Error('Slack directory lookup requires an app token');
+    const url = new URL(path, `${relayBaseUrl}/`);
+    if (options.cursor)
+        url.searchParams.set('cursor', options.cursor);
+    if (typeof options.limit === 'number' && Number.isFinite(options.limit)) {
+        url.searchParams.set('limit', String(Math.trunc(options.limit)));
+    }
+    return url;
+}
+export async function listSlackDirectoryConversations(options) {
+    const url = slackRelayAuthorizedUrl('/slack/directory/conversations', options);
+    if (options.types)
+        url.searchParams.set('types', options.types);
+    const response = await fetch(url.toString(), {
+        method: 'GET',
+        headers: { 'Authorization': `Bearer ${options.token}` },
+    });
+    if (!response.ok) {
+        let detail = response.statusText || 'Slack conversation lookup failed';
+        try {
+            const payload = await response.json();
+            if (typeof payload.detail === 'string' && payload.detail)
+                detail = payload.detail;
+        }
+        catch {
+            // Keep the HTTP status text when the error body is not JSON.
+        }
+        throw new APIError(response.status, detail);
+    }
+    const payload = await response.json();
+    const conversations = Array.isArray(payload.conversations) ? payload.conversations : [];
+    return {
+        conversations: conversations
+            .filter((item) => Boolean(item && typeof item === 'object' && !Array.isArray(item) && typeof item.id === 'string'))
+            .map((item) => ({
+            id: item.id,
+            name: typeof item.name === 'string' ? item.name : null,
+            isChannel: typeof item.is_channel === 'boolean' ? item.is_channel : null,
+            isGroup: typeof item.is_group === 'boolean' ? item.is_group : null,
+            isIm: typeof item.is_im === 'boolean' ? item.is_im : null,
+            isMpim: typeof item.is_mpim === 'boolean' ? item.is_mpim : null,
+            isMember: typeof item.is_member === 'boolean' ? item.is_member : null,
+            isPrivate: typeof item.is_private === 'boolean' ? item.is_private : null,
+        })),
+        nextCursor: typeof payload.next_cursor === 'string' ? payload.next_cursor : null,
+    };
+}
+export async function listSlackDirectoryUsers(options) {
+    const url = slackRelayAuthorizedUrl('/slack/directory/users', options);
+    const response = await fetch(url.toString(), {
+        method: 'GET',
+        headers: { 'Authorization': `Bearer ${options.token}` },
+    });
+    if (!response.ok) {
+        let detail = response.statusText || 'Slack user lookup failed';
+        try {
+            const payload = await response.json();
+            if (typeof payload.detail === 'string' && payload.detail)
+                detail = payload.detail;
+        }
+        catch {
+            // Keep the HTTP status text when the error body is not JSON.
+        }
+        throw new APIError(response.status, detail);
+    }
+    const payload = await response.json();
+    const users = Array.isArray(payload.users) ? payload.users : [];
+    return {
+        users: users
+            .filter((item) => Boolean(item && typeof item === 'object' && !Array.isArray(item) && typeof item.id === 'string'))
+            .map((item) => ({
+            id: item.id,
+            name: typeof item.name === 'string' ? item.name : null,
+            realName: typeof item.real_name === 'string' ? item.real_name : null,
+            teamId: typeof item.team_id === 'string' ? item.team_id : null,
+            isBot: typeof item.is_bot === 'boolean' ? item.is_bot : null,
+            deleted: typeof item.deleted === 'boolean' ? item.deleted : null,
+        })),
+        nextCursor: typeof payload.next_cursor === 'string' ? payload.next_cursor : null,
+    };
+}
+export async function attachSlackRelayAgent(options) {
+    const relayBaseUrl = normalizeSlackRelayBaseUrl(options.relayBaseUrl);
+    const agentId = options.agentId.trim();
+    if (!relayBaseUrl)
+        throw new Error('Slack relay base URL is required');
+    if (!options.token)
+        throw new Error('Slack relay attach requires an app token');
+    if (!agentId)
+        throw new Error('Slack relay attach requires an agent id');
+    const response = await fetch(`${relayBaseUrl}/slack/agents/${encodeURIComponent(agentId)}/relay`, {
+        method: 'POST',
+        headers: { 'Authorization': `Bearer ${options.token}` },
+    });
+    if (!response.ok) {
+        let detail = response.statusText || 'Slack relay attach failed';
+        try {
+            const payload = await response.json();
+            if (typeof payload.detail === 'string' && payload.detail)
+                detail = payload.detail;
+        }
+        catch {
+            // Keep the HTTP status text when the error body is not JSON.
+        }
+        throw new APIError(response.status, detail);
+    }
+    const payload = await response.json();
+    const agentIdValue = typeof payload.agent_id === 'string' ? payload.agent_id : '';
+    const gatewayIdValue = typeof payload.gateway_id === 'string' ? payload.gateway_id : '';
+    if (!agentIdValue || !gatewayIdValue)
+        throw new Error('Slack relay attach response is missing agent identity');
+    return {
+        connected: payload.connected === true,
+        agentId: agentIdValue,
+        gatewayId: gatewayIdValue,
+        restartRequired: payload.restart_required !== false,
+        teamId: typeof payload.team_id === 'string' ? payload.team_id : null,
+        teamName: typeof payload.team_name === 'string' ? payload.team_name : null,
+        botUserId: typeof payload.bot_user_id === 'string' ? payload.bot_user_id : null,
+    };
+}
+export function buildOpenClawDesktopRoute(options = {}) {
+    return {
+        desktop: {
+            port: options.desktopPort ?? 3000,
+            auth: options.desktopAuth ?? true,
+            prefix: options.desktopPrefix ?? 'desktop',
+        },
+    };
+}
+function envBool(value) {
+    return value ? '1' : '0';
+}
+function envNonNegativeInteger(name, value) {
+    const integer = Number(value);
+    if (!Number.isInteger(integer) || integer < 0) {
+        throw new Error(`${name} must be a non-negative integer`);
+    }
+    return String(integer);
+}
+export function buildOpenClawMemoryIndexEnv(memoryIndex = null) {
+    if (!memoryIndex)
+        return {};
+    const env = { ...OPENCLAW_MEMORY_SEARCH_ENV_DEFAULTS };
+    if (memoryIndex.enabled !== undefined && memoryIndex.enabled !== null) {
+        env.OPENCLAW_MEMORY_SEARCH_ENABLED = envBool(memoryIndex.enabled);
+    }
+    if (memoryIndex.onSessionStart !== undefined && memoryIndex.onSessionStart !== null) {
+        env.OPENCLAW_MEMORY_SEARCH_SYNC_ON_SESSION_START = envBool(memoryIndex.onSessionStart);
+    }
+    if (memoryIndex.onSearch !== undefined && memoryIndex.onSearch !== null) {
+        env.OPENCLAW_MEMORY_SEARCH_SYNC_ON_SEARCH = envBool(memoryIndex.onSearch);
+    }
+    if (memoryIndex.watch !== undefined && memoryIndex.watch !== null) {
+        env.OPENCLAW_MEMORY_SEARCH_SYNC_WATCH = envBool(memoryIndex.watch);
+    }
+    if (memoryIndex.watchDebounceMs !== undefined && memoryIndex.watchDebounceMs !== null) {
+        env.OPENCLAW_MEMORY_SEARCH_SYNC_WATCH_DEBOUNCE_MS = envNonNegativeInteger('watchDebounceMs', memoryIndex.watchDebounceMs);
+    }
+    if (memoryIndex.intervalMinutes !== undefined && memoryIndex.intervalMinutes !== null) {
+        env.OPENCLAW_MEMORY_SEARCH_SYNC_INTERVAL_MINUTES = envNonNegativeInteger('intervalMinutes', memoryIndex.intervalMinutes);
+    }
+    return env;
+}
+export function buildOpenClawCronEnv(enabled = null) {
+    return {
+        ...OPENCLAW_CRON_ENV_DEFAULTS,
+        ...(enabled !== null ? { OPENCLAW_CRON_ENABLED: envBool(enabled) } : {}),
+    };
+}
+export function buildHermesCronEnv(enabled = null) {
+    return {
+        ...HERMES_CRON_ENV_DEFAULTS,
+        ...(enabled !== null ? { HERMES_CRON_ENABLED: envBool(enabled) } : {}),
+    };
+}
+export function buildWorkspacesSyncEnv(workspacesSync = null) {
+    if (workspacesSync === false)
+        return { HYPER_WORKSPACES_BOOT_SYNC: '0' };
+    const options = typeof workspacesSync === 'object' && workspacesSync !== null ? workspacesSync : {};
+    if (options.enabled === false)
+        return { HYPER_WORKSPACES_BOOT_SYNC: '0' };
+    const env = { ...WORKSPACES_SYNC_ENV_DEFAULTS };
+    if (options.enabled !== undefined && options.enabled !== null) {
+        env.HYPER_WORKSPACES_BOOT_SYNC = envBool(options.enabled);
+    }
+    if (options.readyOnly !== undefined && options.readyOnly !== null) {
+        env.HYPER_WORKSPACES_SYNC_READY_ONLY = envBool(options.readyOnly);
+    }
+    if (options.workspace) {
+        env.HYPER_WORKSPACES_SYNC_WORKSPACE = options.workspace;
+    }
+    return env;
+}
+async function getFsPromises() {
+    return import('node:fs/promises');
+}
+function bindAgent(agent, deployments) {
+    agent._deployments = deployments;
+    return agent;
+}
+export class Agent {
+    id;
+    userId;
+    state;
+    name;
+    handle;
+    displayName;
+    avatarUrl;
+    avatarAudioUrl;
+    displayIdentity;
+    runtime;
+    managed;
+    isLaunchable;
+    gatewayId;
+    relayKey;
+    cpu;
+    memory;
+    requestedSize;
+    hostname;
+    tags;
+    jwtToken;
+    jwtExpiresAt;
+    startedAt;
+    stoppedAt;
+    archivedAt;
+    archivePrefix;
+    deletedAt;
+    disconnectedAt;
+    agentSlotId;
+    clusterId;
+    runner;
+    launchEpoch;
+    createdAt;
+    updatedAt;
+    launchConfig;
+    meta;
+    routes;
+    command;
+    entrypoint;
+    dryRun;
+    _deployments = null;
+    constructor(fields) {
+        this.id = fields.id;
+        this.userId = fields.userId;
+        this.state = fields.state;
+        this.name = fields.name ?? null;
+        this.handle = fields.handle ?? null;
+        this.displayName = fields.displayName ?? this.name;
+        this.avatarUrl = fields.avatarUrl ?? null;
+        this.avatarAudioUrl = fields.avatarAudioUrl ?? null;
+        this.displayIdentity = fields.displayIdentity ? structuredClone(fields.displayIdentity) : null;
+        this.runtime = fields.runtime ?? null;
+        this.managed = fields.managed ?? null;
+        this.isLaunchable = fields.isLaunchable ?? true;
+        this.gatewayId = fields.gatewayId ?? null;
+        this.relayKey = fields.relayKey ? structuredClone(fields.relayKey) : null;
+        this.cpu = fields.cpu;
+        this.memory = fields.memory;
+        this.requestedSize = fields.requestedSize ?? null;
+        this.hostname = fields.hostname ?? null;
+        this.tags = [...(fields.tags ?? [])];
+        this.jwtToken = fields.jwtToken ?? null;
+        this.jwtExpiresAt = fields.jwtExpiresAt ?? null;
+        this.startedAt = fields.startedAt ?? null;
+        this.stoppedAt = fields.stoppedAt ?? null;
+        this.archivedAt = fields.archivedAt ?? null;
+        this.archivePrefix = fields.archivePrefix ?? null;
+        this.deletedAt = fields.deletedAt ?? null;
+        this.disconnectedAt = fields.disconnectedAt ?? null;
+        this.agentSlotId = fields.agentSlotId ?? null;
+        this.clusterId = fields.clusterId ?? null;
+        this.runner = fields.runner ?? null;
+        this.launchEpoch = fields.launchEpoch ?? 0;
+        this.createdAt = fields.createdAt ?? null;
+        this.updatedAt = fields.updatedAt ?? null;
+        this.launchConfig = fields.launchConfig ?? null;
+        this.meta = fields.meta ? structuredClone(fields.meta) : null;
+        this.routes = { ...fields.routes };
+        this.command = [...fields.command];
+        this.entrypoint = [...fields.entrypoint];
+        this.dryRun = fields.dryRun;
+    }
+    static fromDict(data) {
+        return new Agent(agentStateFromDict(data));
+    }
+    get publicUrl() {
+        return this.hostname ? `https://${this.hostname}` : null;
+    }
+    routePrefix(routeName, defaultPrefix = null) {
+        const route = this.routes[routeName] ?? {};
+        const prefix = route.prefix;
+        if (typeof prefix === 'undefined' || prefix === null) {
+            return defaultPrefix;
+        }
+        return String(prefix);
+    }
+    routeUrl(routeName, defaultPrefix = null) {
+        if (!this.hostname)
+            return null;
+        const prefix = this.routePrefix(routeName, defaultPrefix);
+        if (prefix === null)
+            return null;
+        return prefix === '' ? `https://${this.hostname}` : `https://${prefix}-${this.hostname}`;
+    }
+    get desktopUrl() {
+        return this.routeUrl('desktop', 'desktop');
+    }
+    get vncUrl() {
+        return this.desktopUrl;
+    }
+    browserDesktopUrl(token, options = {}) {
+        if (!this.desktopUrl)
+            return null;
+        return buildBrowserDesktopUrl(this.desktopUrl, token, options);
+    }
+    get shellUrl() {
+        return this.routeUrl('shell');
+    }
+    get isRunning() {
+        return this.state.toLowerCase() === 'running';
+    }
+    get isTransitioning() {
+        return isAgentTransitionalState(this.state);
+    }
+    /** True when the agent is cold-restorable from its verified archive. */
+    get isArchived() {
+        return this.state.toUpperCase() === 'ARCHIVED';
+    }
+    /** True only for an explicitly included deletion tombstone. */
+    get isDeleted() {
+        return this.state.toUpperCase() === 'DELETED';
+    }
+    get hasDesktop() {
+        return agentConfigHasDesktop({
+            launchConfig: this.launchConfig,
+            routes: this.routes,
+        });
+    }
+    requireDeployments() {
+        if (!this._deployments) {
+            throw new Error('Agent is not bound to a Deployments client');
+        }
+        return this._deployments;
+    }
+    /** Runtime auth flows for this agent's pod (coding runtimes only). */
+    get auth() {
+        return new RuntimeAuthClient(this);
+    }
+    /**
+     * Connect to this agent's ACP surface through the backend session proxy.
+     *
+     * Default (`options.transport` unset): dials `/ws/acp` — the client-facing
+     * ACP session authority (sessions/README §14). The proxy owns the backend
+     * session record `{session_id → legs}`, fans runtime frames out to every
+     * attached session client, and answers `session/new` with the backend
+     * session id (backend-keyed, not the pod-side ACP id). Create-or-attach
+     * semantics key on `options.sessionId`:
+     *
+     * - omitted: the socket starts session-less; `newSession()` runs the
+     *   proxy's `session/new`, minting the backend session.
+     * - provided: the dial itself is session-less; AFTER the `initialize`
+     * handshake the client resumes the session over the connected socket
+     * (`session/resume` on v1), without replay. History uses the separate
+     * platform sessions API. A refused resume rejects acpConnect with the
+     * original error and closes its client; it never creates a replacement
+     * session.
+     *
+     * `transport: 'direct'` dials the agent-keyed `/ws` bridge instead
+     * (`?agent_id&token`), the pre-proxy path. Infra/debug only: `/ws` is
+     * being hardened to runtime + backend-service identities, and combining
+     * it with `sessionId` throws (the bridge has no session binding).
+     *
+     * The ACP `initialize` handshake offers protocol version 1 only
+     * (see `client.negotiatedProtocolVersion`). The proxy authority is
+     * v1-only and the client closes on any answered version other than 1.
+     * The `cwd` default comes from the runtime's validated launch-directory
+     * advertisement, never from the pod sync root or the caller's machine.
+      *
+      * Auth: the dial carries the client API key on the `token` query param;
+      * `options.token` overrides that credential.
+      */
+    async acpConnect(options = {}) {
+        const deployments = this.requireDeployments();
+        const transport = options.transport ?? 'proxy';
+        if (transport === 'direct' && options.sessionId) {
+            throw new Error("acpConnect: sessionId is a proxy-transport option; the direct /ws bridge " +
+                "has no session binding (drop sessionId or use the default 'proxy' transport)");
+        }
+        const url = new URL(transport === 'direct'
+            ? defaultHyperAcpWsUrl(deployments.agentApiBase)
+            : defaultAcpProxyWsUrl(deployments.agentApiBase));
+        url.searchParams.set('agent_id', this.id);
+        url.searchParams.set('token', options.token ?? deployments.agentApiKey);
+        const client = await CodingAgentAcpClient.connect({ url: url.toString(), token: '' }, { ...options,
+            resolveDefaultCwd: options.resolveDefaultCwd ?? (async () => (await deployments.runtimePaths(this.id, { signal: options.signal })).cwd),
+        });
+        if (options.sessionId) {
+            try {
+                await client.resumeSession(options.sessionId);
+            }
+            catch (error) {
+                client.close();
+                throw error;
+            }
+        }
+        return client;
+    }
+    acpPoolValue = null;
+    /**
+     * Lazily created connection pool for this agent's ACP surface. Two
+     * clients dialed to the same agent share one pod-side stdio session, so all
+     * ACP consumers (chat panes, session sweeps, turn drivers) must ride ONE
+     * pooled connection via leases instead of dialing their own — the bridge
+     * rejects a duplicate runtime attach. The pool closes the connection when
+     * the last lease releases, so a lease taken by a long-lived consumer (a
+     * turn driver) outlives callers that unmount (a chat pane) and vice versa.
+     *
+     * Under the default proxy transport the pooled connection dials session-less:
+     * prompting a session id the proxy has never seen (a stored id whose
+     * runtime was evicted backend-side) fails with an unknown-session error.
+     * Prompt against ids created through this proxy, or attach first with a
+     * dedicated `acpConnect({ sessionId })`.
+     */
+    get acpPool() {
+        if (this.acpPoolValue === null) {
+            this.acpPoolValue = new CodingAgentAcpPool({ connect: (_key, options) => this.acpConnect(options) });
+        }
+        return this.acpPoolValue;
+    }
+    /**
+     * Acquire a lease on this agent's pooled ACP connection and return a ready
+     * per-session {@link AcpTurnDriver} bound to it. `options.sessionId` is the
+     * pinned ACP session id (the id the app persists, e.g. under
+     * `localStorage["acp-session:<agentId>"]`); drivers are cheap — one per
+     * session, all sharing the same lease-held connection. The driver holds
+     * its lease until
+     * `driver.close()`; the pooled connection stays up for other leaseholders.
+     */
+    async acpTurnDriver(options) {
+        const lease = await this.acpPool.acquire(this.id);
+        try {
+            return new AcpTurnDriver(lease, options);
+        }
+        catch (error) {
+            lease.release();
+            throw error;
+        }
+    }
+    routeRequiresAuth(routeName, defaultValue = true) {
+        const route = this.routes[routeName];
+        if (!route || typeof route.auth === 'undefined') {
+            return defaultValue;
+        }
+        return Boolean(route.auth);
+    }
+    async refreshToken() {
+        const data = await this.requireDeployments().refreshToken(this.id);
+        this.jwtToken = data.token ?? null;
+        this.jwtExpiresAt = parseDate(data.expires_at);
+        return data;
+    }
+    async waitRunning(timeoutMs = 300_000, pollIntervalMs = 5_000) {
+        return this.requireDeployments().waitRunning(this.id, timeoutMs, pollIntervalMs, this.launchEpoch > 0 ? this.launchEpoch : undefined);
+    }
+    async update(options) {
+        return this.requireDeployments().update(this.id, options);
+    }
+    async resetRuntimeDefaults(options) {
+        return this.requireDeployments().resetRuntimeDefaults(this.id, options);
+    }
+    async resize(options) {
+        return this.requireDeployments().resize(this.id, options);
+    }
+    /** Accept background archival and return its transitional Agent projection. */
+    async archive(options) {
+        return this.requireDeployments().archive(this.id, options);
+    }
+    async env() {
+        const response = await this.requireDeployments().env(this.id);
+        if (response.launch_epoch < this.launchEpoch) {
+            throw new Error('agent env belongs to an older launch epoch');
+        }
+        return response.env;
+    }
+    async setEnv(key, value) {
+        return this.requireDeployments().setEnv(this.id, key, value);
+    }
+    async deleteEnv(key) {
+        return this.requireDeployments().deleteEnv(this.id, key);
+    }
+    async secretNames() {
+        const response = await this.requireDeployments().secretNames(this.id);
+        if (response.launch_epoch < this.launchEpoch) {
+            throw new Error('agent Secret names belong to an older launch epoch');
+        }
+        return response.names;
+    }
+    async secret(key) {
+        const response = await this.requireDeployments().secret(this.id, key);
+        if (response.launch_epoch < this.launchEpoch) {
+            throw new Error('agent Secret belongs to an older launch epoch');
+        }
+        return response.value;
+    }
+    async setSecret(key, value) {
+        return this.requireDeployments().setSecret(this.id, key, value);
+    }
+    async deleteSecret(key) {
+        return this.requireDeployments().deleteSecret(this.id, key);
+    }
+    async exec(command, options = {}) {
+        return this.requireDeployments().exec(this, command, options);
+    }
+    /** Reef-backed files scoped to this agent's configured sync root. */
+    get files() {
+        return new AgentFiles(this, this.requireDeployments());
+    }
+    async filesList(path = '') {
+        return this.files.list(path);
+    }
+    async fileReadBytes(path, options) {
+        return this.files.readBytes(path, options);
+    }
+    async fileReadBytesWithMetadata(path, options) {
+        return this.files.readBytesWithMetadata(path, options);
+    }
+    async fileRead(path, options) {
+        return this.files.read(path, options);
+    }
+    async fileWriteBytes(path, content) {
+        return this.files.writeBytes(path, content);
+    }
+    async fileWrite(path, content) {
+        return this.files.write(path, content);
+    }
+    async fileDelete(path, options = {}) {
+        return this.files.delete(path, options);
+    }
+    async cpTo(localPath, remotePath) {
+        return this.requireDeployments().cpTo(this, localPath, remotePath);
+    }
+    async cpFrom(remotePath, localPath) {
+        return this.requireDeployments().cpFrom(this, remotePath, localPath);
+    }
+    async shellConnect(shell, options) {
+        return this.requireDeployments().shellConnect(this.id, shell, options);
+    }
+}
+// Runtime auth surfaces are launch-shape data per runtime label, not class
+// behavior. openclaw/hermes-agent pods have no in-pod login flow and carry
+// no table entry.
+const RUNTIME_AUTH_CONFIG = {
+    'buzz-agent': {
+        agentCommand: ['buzz-agent'],
+        statusCommand: null,
+        logoutCommand: null,
+        nativeMethods: [],
+    },
+    opencode: {
+        agentCommand: ['opencode', 'acp'],
+        statusCommand: ['opencode', 'auth', 'list'],
+        logoutCommand: ['opencode', 'auth', 'logout'],
+        nativeMethods: [],
+    },
+    codex: {
+        agentCommand: ['codex-acp'],
+        statusCommand: ['codex', 'login', 'status'],
+        logoutCommand: ['codex', 'logout'],
+        nativeMethods: [{
+                id: 'device',
+                name: 'Device authentication',
+                description: 'Authenticate Codex with a device code.',
+                kind: 'native',
+                command: ['codex', 'login', '--device-auth'],
+                metadata: {},
+            }],
+    },
+    'claude-code': {
+        agentCommand: ['claude-agent-acp'],
+        statusCommand: ['claude', 'auth', 'status', '--json'],
+        logoutCommand: ['claude', 'auth', 'logout'],
+        nativeMethods: [
+            { id: 'claude-ai', name: 'Claude.ai', description: '', kind: 'native', command: ['claude', 'auth', 'login', '--claudeai'], metadata: {} },
+            { id: 'console', name: 'Anthropic Console', description: '', kind: 'native', command: ['claude', 'auth', 'login', '--console'], metadata: {} },
+            { id: 'sso', name: 'Enterprise SSO', description: '', kind: 'native', command: ['claude', 'auth', 'login', '--sso'], metadata: {} },
+        ],
+    },
+    goose: {
+        agentCommand: ['goose', 'acp'],
+        statusCommand: null,
+        logoutCommand: null,
+        nativeMethods: [],
+    },
+    'kimi-code': {
+        agentCommand: ['kimi', 'acp'],
+        statusCommand: null,
+        logoutCommand: null,
+        nativeMethods: [],
+    },
+    pi: {
+        agentCommand: ['pi-acp'],
+        statusCommand: null,
+        logoutCommand: null,
+        nativeMethods: [],
+    },
+};
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+function commandString(command) {
+    return command.map(shellQuote).join(' ');
+}
+// Terminal control-sequence matching intentionally includes ESC and BEL.
+/* eslint-disable no-control-regex */
+const TERMINAL_ESCAPE_PATTERN = new RegExp('\\x1B(?:\\[[0-?]*[ -/]*[@-~]|\\][^\\x07]*(?:\\x07|\\x1B\\\\))', 'g');
+/* eslint-enable no-control-regex */
+function stripTerminalCodes(value) {
+    return value.replace(TERMINAL_ESCAPE_PATTERN, '').replace(/\r/g, '');
+}
+async function websocketMessageText(data) {
+    if (typeof data === 'string')
+        return data;
+    if (data instanceof ArrayBuffer)
+        return decodeUtf8(new Uint8Array(data));
+    if (ArrayBuffer.isView(data))
+        return decodeUtf8(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
+    if (typeof Blob !== 'undefined' && data instanceof Blob)
+        return data.text();
+    return String(data ?? '');
+}
+export class RuntimeLoginSession {
+    authClient;
+    socket;
+    requiresDeviceChallenge;
+    output = '';
+    verificationUrl = null;
+    userCode = null;
+    interactiveRequired = false;
+    rawOutput = '';
+    exitCode = null;
+    marker;
+    completion;
+    ready;
+    complete;
+    markReady;
+    constructor(authClient, socket, command, requiresDeviceChallenge) {
+        this.authClient = authClient;
+        this.socket = socket;
+        this.requiresDeviceChallenge = requiresDeviceChallenge;
+        this.marker = `__HYPERCLI_AUTH_EXIT_${randomHexToken(12)}__=`;
+        this.completion = new Promise((resolve) => { this.complete = resolve; });
+        this.ready = new Promise((resolve) => { this.markReady = resolve; });
+        socket.onmessage = (event) => {
+            void websocketMessageText(event.data).then((chunk) => this.consume(chunk));
+        };
+        socket.onclose = () => {
+            this.markReady();
+            this.complete();
+        };
+        socket.send(`${commandString(command)}; _hypercli_auth_rc=$?; printf '\\n${this.marker}%s\\n' "$_hypercli_auth_rc"\n`);
+    }
+    static async start(authClient, command, challengeTimeoutMs = 45_000, requiresDeviceChallenge = false) {
+        const socket = await authClient.agent.shellConnect();
+        const session = new RuntimeLoginSession(authClient, socket, command, requiresDeviceChallenge);
+        let timer;
+        try {
+            await Promise.race([
+                session.ready,
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error('Timed out waiting for runtime login instructions')), challengeTimeoutMs);
+                }),
+            ]);
+            return session;
+        }
+        catch (error) {
+            session.cancel();
+            throw error;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    consume(chunk) {
+        this.rawOutput += chunk;
+        this.output = stripTerminalCodes(this.rawOutput);
+        const markerIndex = this.output.lastIndexOf(this.marker);
+        if (markerIndex >= 0) {
+            const match = this.output.slice(markerIndex + this.marker.length).match(/^(-?\d+)/);
+            if (match) {
+                this.exitCode = Number(match[1]);
+                this.markReady();
+                this.complete();
+            }
+        }
+        this.verificationUrl ??= this.output.match(/https?:\/\/[^\s"'<>]+(?=[\s"'<>])/)?.[0] ?? null;
+        this.userCode ??= this.output.match(/\b(?:user|device|verification|one[- ]time)\s+code\b\s*(?:is|:)?\s*(?:\([^\r\n)]*\)\s*)*((?!authorization\b)[A-Z0-9](?:[A-Z0-9-]*[A-Z0-9])?)(?=[\s.,;:)\]])/i)?.[1] ?? null;
+        this.interactiveRequired ||= /\b(select|choose)\b.*\b(provider|login method)\b/i.test(this.output);
+        const challengeReady = this.requiresDeviceChallenge
+            ? Boolean(this.verificationUrl && this.userCode)
+            : Boolean(this.verificationUrl || this.userCode);
+        if (challengeReady || this.interactiveRequired)
+            this.markReady();
+    }
+    send(text) {
+        this.socket.send(text.endsWith('\n') ? text : `${text}\n`);
+    }
+    async wait(timeoutMs = 600_000) {
+        let timer;
+        try {
+            await Promise.race([
+                this.completion,
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error('Runtime authentication timed out')), timeoutMs);
+                }),
+            ]);
+        }
+        catch (error) {
+            this.cancel();
+            throw error;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+        if (this.exitCode !== null && this.exitCode !== 0) {
+            throw new Error(`Runtime authentication failed (${this.exitCode}): ${this.output.trim()}`);
+        }
+        return this.authClient.status();
+    }
+    cancel() {
+        // The SDK supports Node runtimes where the socket is supplied by `ws` and
+        // no global WebSocket constructor exists. OPEN is the protocol state 1.
+        if (this.socket.readyState === 1)
+            this.socket.send('\x03');
+        this.socket.close();
+    }
+}
+export class RuntimeAuthClient {
+    agent;
+    config;
+    constructor(agent) {
+        this.agent = agent;
+        const config = RUNTIME_AUTH_CONFIG[agent.runtime];
+        if (!config) {
+            throw new Error(`Runtime authentication is not available for runtime '${agent.runtime ?? 'generic'}'`);
+        }
+        this.config = config;
+    }
+    async methods() {
+        const discovered = [];
+        if (this.agent.runtime === 'opencode' && discovered.length === 0) {
+            discovered.push({
+                id: 'provider',
+                name: 'Provider login',
+                description: '',
+                kind: 'native',
+                command: ['opencode', 'auth', 'login'],
+                metadata: {},
+            });
+        }
+        const seen = new Set(discovered.map((method) => method.id));
+        for (const method of this.config.nativeMethods) {
+            if (!seen.has(method.id))
+                discovered.push({ ...method, command: [...method.command], metadata: { ...method.metadata } });
+        }
+        return discovered;
+    }
+    async status() {
+        if (!this.config.statusCommand) {
+            throw new Error(`Runtime authentication status is unsupported for '${this.agent.runtime}'; use the runtime's native authentication interface`);
+        }
+        const result = await this.agent.exec([...this.config.statusCommand]);
+        const output = stripTerminalCodes([result.stdout, result.stderr].filter(Boolean).join('\n')).trim();
+        const detail = { exitCode: result.exitCode, output };
+        if (this.agent.runtime === 'claude-code') {
+            try {
+                const payload = JSON.parse(stripTerminalCodes(result.stdout));
+                Object.assign(detail, payload);
+                const loginMethod = payload.loginMethod ?? payload.authMethod;
+                return {
+                    authenticated: payload.loggedIn === true || payload.authenticated === true ||
+                        (typeof loginMethod === 'string' && loginMethod.toLowerCase() !== 'none'),
+                    provider: typeof (payload.subscriptionType ?? payload.provider ?? payload.apiProvider) === 'string'
+                        ? String(payload.subscriptionType ?? payload.provider ?? payload.apiProvider) : null,
+                    account: typeof payload.email === 'string' ? payload.email : null,
+                    method: typeof loginMethod === 'string' ? loginMethod : null,
+                    detail,
+                };
+            }
+            catch {
+                // Fall through to the generic status parser.
+            }
+        }
+        const negative = /\b(not logged|not authenticated|unauthenticated|no credentials|0 credentials)\b/i.test(output);
+        return { authenticated: result.exitCode === 0 && !negative, detail };
+    }
+    async login(options = {}) {
+        const methods = await this.methods();
+        const method = options.method
+            ? methods.find((candidate) => candidate.id === options.method)
+            : methods.find((candidate) => candidate.command.length > 0) ?? methods[0];
+        if (!method) {
+            throw new Error(options.method
+                ? `Unknown authentication method: ${options.method}`
+                : 'No authentication methods are available');
+        }
+        let command = [...method.command];
+        if (!command.length) {
+            throw new Error(`Authentication method '${method.id}' has no native login command`);
+        }
+        if (this.agent.runtime === 'opencode') {
+            if (options.provider)
+                command.push('--provider', options.provider);
+            if (options.providerMethod)
+                command.push('--method', options.providerMethod);
+        }
+        if (this.agent.runtime === 'claude-code' && options.email)
+            command.push('--email', options.email);
+        const requiresDeviceChallenge = method.kind === 'device'
+            || method.id === 'device'
+            || command.some((part) => part.toLowerCase().includes('device-auth'));
+        return RuntimeLoginSession.start(this, command, options.challengeTimeoutMs, requiresDeviceChallenge);
+    }
+    async logout(provider) {
+        if (this.config.logoutCommand === null) {
+            const reason = this.agent.runtime === 'goose'
+                ? 'uses its injected deployment credential'
+                : 'does not expose a noninteractive logout command';
+            throw new Error(`${this.agent.runtime} ${reason} and cannot log out`);
+        }
+        const command = [...this.config.logoutCommand];
+        if (this.agent.runtime === 'opencode' && provider)
+            command.push(provider);
+        const result = await this.agent.exec(command);
+        if (result.exitCode !== 0) {
+            throw new Error(`Runtime logout failed (${result.exitCode}): ${stripTerminalCodes(result.stderr || result.stdout).trim()}`);
+        }
+        return this.status();
+    }
+}
+const OPENCLAW_ACP_ROW = {
+    image: DEFAULT_OPENCLAW_IMAGE,
+    syncRoot: DEFAULT_OPENCLAW_SYNC_ROOT,
+    syncUid: 1000,
+    syncGid: 1000,
+    // Mirrors the openclaw image ENV (`openclaw` resolves via PATH on the
+    // runner host; the image pins it in ENV for the container instead).
+    agentCommand: ['openclaw', 'acp'],
+    env: DEFAULT_OPENCLAW_MODEL_ENV,
+    cronEnv: buildOpenClawCronEnv,
+    syncExclude: DEFAULT_OPENCLAW_SYNC_EXCLUDE,
+    workspacesSyncEnv: true,
+    stripConfigBag: true,
+    openclawControlUi: true,
+    openclawMemoryIndex: true,
+    // openclaw.json reseeds on boot; the openclaw.sqlite trio clears
+    // device_pairing_paired/device_auth_tokens/device_pairing_pending rows so a
+    // stale scope-capped pairing (operator.pairing-only → FORBIDDEN on
+    // operator.read/write) can never survive a runtime reset — the in-pod ACP
+    // client re-pairs on loopback with silent auto-approve (operator.admin).
+    // The sqlite holds only disposable metadata (audit/diagnostic events,
+    // boot-reseeded cron, config tables); chat history lives in the agent db.
+    resetFiles: [
+        '.openclaw/openclaw.json',
+        '.openclaw/state/openclaw.sqlite',
+        '.openclaw/state/openclaw.sqlite-wal',
+        '.openclaw/state/openclaw.sqlite-shm',
+    ],
+    // Legacy inert per-device pairing records (devices/*.json*); unknown names,
+    // so the whole directory goes.
+    resetDirs: ['.openclaw/devices'],
+};
+const ACP_RUNTIME_TABLE = {
+    openclaw_acp: OPENCLAW_ACP_ROW,
+    hermes_acp: {
+        image: DEFAULT_HERMES_AGENT_IMAGE,
+        syncRoot: DEFAULT_HERMES_AGENT_SYNC_ROOT,
+        syncUid: DEFAULT_HERMES_AGENT_SYNC_UID,
+        syncGid: DEFAULT_HERMES_AGENT_SYNC_GID,
+        // The hermes image ENV pins the venv absolute path; on the runner host
+        // the hermes-acp binary resolves via PATH instead.
+        agentCommand: ['hermes-acp'],
+        env: DEFAULT_HERMES_MODEL_ENV,
+        cronEnv: buildHermesCronEnv,
+        syncExclude: DEFAULT_HERMES_AGENT_SYNC_EXCLUDE,
+        resetFiles: ['.hermes/config.yaml', '.hermes/mem0.json'],
+    },
+    'buzz-agent': {
+        image: DEFAULT_BUZZ_AGENT_IMAGE,
+        syncRoot: DEFAULT_CODING_AGENT_SYNC_ROOT,
+        syncUid: 1000,
+        syncGid: 1000,
+        // Coding harnesses share their agent command with the runtime-auth table.
+        agentCommand: RUNTIME_AUTH_CONFIG['buzz-agent'].agentCommand,
+        workspacesSyncEnv: true,
+        codingHarness: true,
+    },
+    opencode: {
+        image: DEFAULT_OPENCODE_IMAGE,
+        syncRoot: DEFAULT_CODING_AGENT_SYNC_ROOT,
+        syncUid: 1000,
+        syncGid: 1000,
+        agentCommand: RUNTIME_AUTH_CONFIG.opencode.agentCommand,
+        workspacesSyncEnv: true,
+        codingHarness: true,
+    },
+    codex: {
+        image: DEFAULT_CODEX_IMAGE,
+        syncRoot: DEFAULT_CODING_AGENT_SYNC_ROOT,
+        syncUid: 1000,
+        syncGid: 1000,
+        agentCommand: RUNTIME_AUTH_CONFIG.codex.agentCommand,
+        workspacesSyncEnv: true,
+        codingHarness: true,
+    },
+    'claude-code': {
+        image: DEFAULT_CLAUDE_CODE_IMAGE,
+        syncRoot: DEFAULT_CODING_AGENT_SYNC_ROOT,
+        syncUid: 1000,
+        syncGid: 1000,
+        agentCommand: RUNTIME_AUTH_CONFIG['claude-code'].agentCommand,
+        workspacesSyncEnv: true,
+        codingHarness: true,
+    },
+    goose: {
+        image: DEFAULT_GOOSE_IMAGE,
+        syncRoot: DEFAULT_CODING_AGENT_SYNC_ROOT,
+        syncUid: 1000,
+        syncGid: 1000,
+        agentCommand: RUNTIME_AUTH_CONFIG.goose.agentCommand,
+        workspacesSyncEnv: true,
+        codingHarness: true,
+    },
+    'kimi-code': {
+        image: DEFAULT_KIMI_CODE_IMAGE,
+        syncRoot: DEFAULT_CODING_AGENT_SYNC_ROOT,
+        syncUid: 1000,
+        syncGid: 1000,
+        agentCommand: RUNTIME_AUTH_CONFIG['kimi-code'].agentCommand,
+        workspacesSyncEnv: true,
+        codingHarness: true,
+    },
+    pi: {
+        image: DEFAULT_PI_IMAGE,
+        syncRoot: DEFAULT_CODING_AGENT_SYNC_ROOT,
+        syncUid: 1000,
+        syncGid: 1000,
+        agentCommand: RUNTIME_AUTH_CONFIG.pi.agentCommand,
+        workspacesSyncEnv: true,
+        codingHarness: true,
+    },
+};
+export class Deployments {
+    apiKey;
+    apiBase;
+    agentsWsUrl;
+    agentHttp;
+    constructor(http, agentApiKey, agentApiBase, agentsWsUrl, requestTimeout) {
+        this.apiKey = agentApiKey || http.apiKey;
+        this.apiBase = resolveAgentsApiBase(agentApiBase || getAgentsApiBaseUrl(), true);
+        this.agentsWsUrl = agentsWsUrl || defaultAgentsWsUrl(this.apiBase);
+        const agentTimeout = requestTimeout ?? (http instanceof HTTPClient ? http.timeout : undefined);
+        this.agentHttp = http instanceof HTTPClient ? new HTTPClient(this.apiBase, this.apiKey, agentTimeout) : http;
+    }
+    get agentApiKey() {
+        return this.apiKey;
+    }
+    get agentApiBase() {
+        return this.apiBase;
+    }
+    /** Authoritative runtime-host launch directory, resolved by the platform. */
+    runtimePaths(agentId, requestOptions = {}) {
+        return this.agentHttp.get(`/deployments/${encodeURIComponent(agentId)}/runtime-paths`, undefined, requestOptions);
+    }
+    hydrateAgent(data) {
+        // One flat Agent for every runtime; the peer determines ACP availability.
+        return bindAgent(Agent.fromDict(data), this);
+    }
+    async getById(agentId, requestOptions = {}) {
+        const path = `${DEPLOYMENTS_API_PREFIX}/${agentId}`;
+        const data = Object.keys(requestOptions).length === 0
+            ? await this.agentHttp.get(path)
+            : await this.agentHttp.get(path, undefined, requestOptions);
+        return this.hydrateAgent(data);
+    }
+    async resolveAgent(agentIdOrName, requestOptions = {}) {
+        const raw = String(agentIdOrName || '').trim();
+        if (!raw) {
+            throw new Error('agentIdOrName is required');
+        }
+        if (isUuidRef(raw)) {
+            return this.getById(raw, requestOptions);
+        }
+        const matches = [];
+        for (const agent of await this.list(requestOptions)) {
+            const values = [agent.id, agent.name, agent.handle, agent.hostname];
+            if (values.some((value) => String(value || '') === raw)) {
+                matches.push(agent);
+                continue;
+            }
+            if (values.some((value) => String(value || '').startsWith(raw))) {
+                matches.push(agent);
+            }
+        }
+        if (matches.length === 0) {
+            throw new Error(`Agent not found: ${raw}`);
+        }
+        if (matches.length > 1) {
+            throw new Error(`Agent reference is ambiguous: ${raw} (${matches.slice(0, 5).map((agent) => agent.id).join(', ')})`);
+        }
+        return this.getById(matches[0].id, requestOptions);
+    }
+    async resolveAgentId(agentIdOrName, requestOptions = {}) {
+        const raw = String(agentIdOrName || '').trim();
+        if (!raw) {
+            throw new Error('agentIdOrName is required');
+        }
+        if (isSelfAgentRef(raw)) {
+            // An Agent introspects itself; it does not start, stop, or edit its own
+            // routes. Status is the only self operation, and it is served directly
+            // by GET /deployments/self -- nothing resolves a self reference to an id
+            // any more.
+            throw new Error('self is only supported for status');
+        }
+        if (isDirectAgentIdRef(raw)) {
+            return raw;
+        }
+        return (await this.resolveAgent(raw, requestOptions)).id;
+    }
+    async routesTarget(agentIdOrName) {
+        const raw = String(agentIdOrName || '').trim();
+        if (isSelfAgentRef(raw)) {
+            return 'self';
+        }
+        return this.resolveAgentId(raw);
+    }
+    async agentIdFor(target) {
+        return typeof target === 'string' ? this.resolveAgentId(target) : target.id;
+    }
+    async fetchRaw(path, init = {}) {
+        const headers = new Headers(init.headers ?? {});
+        headers.set('Authorization', `Bearer ${this.apiKey}`);
+        const contentType = headers.get('Content-Type');
+        const body = init.body && contentType?.includes('application/json') && typeof init.body !== 'string'
+            ? JSON.stringify(init.body)
+            : init.body;
+        const response = await fetch(`${this.apiBase}${path}`, {
+            ...init,
+            headers,
+            body,
+        });
+        if (!response.ok) {
+            let detail = response.statusText;
+            try {
+                const payload = await response.clone().json();
+                detail = typeof payload.detail === 'string' ? payload.detail : response.statusText;
+            }
+            catch {
+                const text = await response.text();
+                detail = text || response.statusText;
+            }
+            throw new APIError(response.status, detail);
+        }
+        return response;
+    }
+    async fileAccess(agentId, signal) {
+        const payload = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/files/token`, undefined, { redirect: 'error', ...(signal ? { signal } : {}) });
+        if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+            throw new Error('Backend returned an invalid Agent file token response');
+        }
+        const fields = 'transport' in payload ? ['transport', 'executor', 'max_bytes', 'chunk_bytes'] : ['url', 'token', 'expires_at'];
+        if (Object.keys(payload).length !== fields.length || fields.some((key) => !(key in payload))) {
+            throw new Error('Backend returned an invalid Agent file token response');
+        }
+        if ('transport' in payload) {
+            // Executor is informational and null until observed; the file operation determines availability.
+            if (payload.transport !== 'runner' || (payload.executor !== null && payload.executor !== 'process' && payload.executor !== 'docker') || !Number.isSafeInteger(payload.max_bytes) || payload.max_bytes <= 0) {
+                throw new Error('Backend returned an invalid runner file transport');
+            }
+            const chunkBytes = payload.chunk_bytes;
+            if (!Number.isSafeInteger(chunkBytes) || chunkBytes <= 0 || chunkBytes > payload.max_bytes) {
+                throw new Error('Backend returned an invalid runner chunk size');
+            }
+            return { transport: 'runner', maxBytes: Math.min(payload.max_bytes, RUNNER_FILE_MAX_BYTES), chunkBytes };
+        }
+        const token = typeof payload?.token === 'string' ? payload.token.trim() : '';
+        const expiresAt = typeof payload?.expires_at === 'string' ? payload.expires_at.trim() : '';
+        let url;
+        try {
+            url = new URL(typeof payload?.url === 'string' ? payload.url : '');
+        }
+        catch {
+            throw new Error('Backend returned an invalid Agent file token response');
+        }
+        if (url.protocol !== 'https:' ||
+            !url.hostname ||
+            url.username ||
+            url.password ||
+            url.search ||
+            url.hash ||
+            url.pathname !== '/_reef' ||
+            !token ||
+            !expiresAt) {
+            throw new Error('Backend returned an invalid Agent file token response');
+        }
+        return { url: url.toString().replace(/\/+$/, ''), token };
+    }
+    async fetchReef(access, path, init = {}) {
+        const headers = new Headers(init.headers ?? {});
+        headers.set('Authorization', `Bearer ${access.token}`);
+        const response = await fetch(`${access.url}${path}`, {
+            ...init,
+            headers,
+            redirect: 'error',
+        });
+        if (!response.ok) {
+            let detail = response.statusText;
+            try {
+                const payload = await response.clone().json();
+                detail = typeof payload.detail === 'string' ? payload.detail : response.statusText;
+            }
+            catch {
+                const text = await response.text();
+                detail = text || response.statusText;
+            }
+            throw new APIError(response.status, detail);
+        }
+        return response;
+    }
+    async create(options = {}) {
+        const config = buildAgentCreateConfig(options.config ?? {}, options);
+        const body = { ...config };
+        if (options.dryRun)
+            body.dry_run = true;
+        if (options.name)
+            body.name = options.name;
+        if (options.handle !== undefined)
+            body.handle = options.handle;
+        if (options.size)
+            body.size = options.size;
+        if (options.meta?.ui)
+            body.meta = { ui: structuredClone(options.meta.ui) };
+        if (options.meta?.integrations)
+            body.meta = { ...body.meta, integrations: structuredClone(options.meta.integrations) };
+        if (options.tags?.length)
+            body.tags = [...options.tags];
+        if (options.runner) {
+            body.runner = {
+                ...(options.runner.tags ? { tags: [...options.runner.tags] } : {}),
+                ...(options.runner.runnerId ? { runner_id: options.runner.runnerId } : {}),
+            };
+        }
+        if (options.runtime)
+            body.runtime = options.runtime;
+        const data = await this.agentHttp.post(DEPLOYMENTS_API_PREFIX, body, { retries: 1 });
+        return this.hydrateAgent(data);
+    }
+    /**
+     * Create a managed agent for a runtime in one call.
+     *
+     * `runtime` selects the launch defaults (image, sync root and
+     * include/exclude presets, uid/gid, env presets, routes, boot command) from
+     * the ACP_RUNTIME_TABLE data table; `options` folds the old per-runtime
+     * facade option types — each runtime reads the knobs it understands and
+     * ignores the rest. `create()` stays the raw generic entry; `createAgent`
+     * is the typed one. Every non-generic runtime boots behind hyper-acp;
+     * `buzz` switches to the Buzz launch (coding runtimes only).
+     */
+    async createAgent(runtime, options = {}) {
+        if (runtime === 'generic')
+            return this.create(options);
+        return this.createAcpAgentDeployment(runtime, options);
+    }
+    /**
+     * Create an ACP-fronted coding agent. All coding runtimes share one launch
+     * contract; `runtime` selects the default image and sync includes.
+     * Runtime configuration roots are selected on the runtime host.
+     *
+     * @deprecated Use {@link Deployments.createAgent} with the runtime label;
+     * the folded entry takes the same options bag.
+     */
+    async createCodingAgent(runtime, options = {}) {
+        return this.createAgent(runtime, options);
+    }
+    /**
+     * The one canonical ACP launch path: every non-generic runtime launches
+     * through here, with per-family differences read from ACP_RUNTIME_TABLE.
+     */
+    async createAcpAgentDeployment(runtime, options) {
+        const family = ACP_RUNTIME_TABLE[runtime];
+        const processExecutor = options.executor === 'process';
+        if (processExecutor && options.image !== undefined && options.image !== null) {
+            // Runner-process launch: the runner host executes `command` directly,
+            // so there is no image to pull. Mirrors the Backend's 400
+            // "image is only supported for the docker executor".
+            throw new Error('image requires the docker executor');
+        }
+        if (options.buzzEnabled && options.buzz) {
+            throw new Error('buzzEnabled cannot be combined with buzz');
+        }
+        if ((options.buzzEnabled || options.buzz) && options.command !== undefined && options.command !== null) {
+            throw new Error('Buzz launch cannot be combined with an explicit command');
+        }
+        if ((options.buzzEnabled || options.buzz) && !family.codingHarness) {
+            throw new Error(`Buzz launch is supported on coding-agent runtimes only, not '${runtime}'`);
+        }
+        const buzzLaunch = options.buzzEnabled || options.buzz !== undefined && options.buzz !== null;
+        if (buzzLaunch && options.size !== undefined && options.size !== 'large' && options.size !== 'medium') {
+            throw new Error("Buzz coding agents require size='large' or 'medium'");
+        }
+        rejectOpenClawSecretOnlyEnv({ ...(options.env ?? {}) });
+        const effectiveEnv = {
+            ...(family.workspacesSyncEnv ? buildWorkspacesSyncEnv(options.workspacesSync ?? null) : null),
+            ...(family.cronEnv ? family.cronEnv(options.cronEnabled ?? null) : null),
+            ...(family.openclawMemoryIndex ? buildOpenClawMemoryIndexEnv(options.memoryIndex) : null),
+            ...(family.env ?? null),
+            ...(options.env ?? {}),
+        };
+        if (family.openclawControlUi) {
+            // OpenClaw treats this env as a full replace for
+            // gateway.controlUi.allowedOrigins, and every HyperCLI surface (desktop,
+            // console) drives the control UI from dynamic origins. The only value
+            // that lands reliably is the wildcard — always write it.
+            effectiveEnv.OPENCLAW_CONTROL_UI_ALLOWED_ORIGIN = '*';
+            Object.assign(effectiveEnv, buildOpenClawTrustedProxiesEnv(options.trustedProxies));
+        }
+        if (options.permissionMode !== undefined) {
+            throw new Error('permissionMode launch presets are retired; select an advertised native session mode');
+        }
+        const effectiveSecrets = { ...(options.secrets ?? {}) };
+        if (family.codingHarness) {
+            for (const key of ['BUZZ_PRIVATE_KEY', 'NOSTR_PRIVATE_KEY']) {
+                const value = effectiveEnv[key];
+                if (value === undefined)
+                    continue;
+                delete effectiveEnv[key];
+                if (effectiveSecrets[key] !== undefined && effectiveSecrets[key] !== value) {
+                    throw new Error(`${key} conflicts between env and secrets`);
+                }
+                effectiveSecrets[key] = value;
+            }
+        }
+        // The process executor has no image: the runner host runs `command`,
+        // resolving the bare hyper-acp binary via the host's PATH. Hosted/docker
+        // launches keep the container path.
+        const resolvedImage = processExecutor ? undefined : options.image ?? family.image;
+        const hyperAcpBinary = processExecutor ? 'hyper-acp' : '/usr/local/bin/hyper-acp';
+        const buzzConfig = buzzLaunch ? buildBuzzLaunchConfig(runtime, options.buzz ?? null, this.apiBase, { env: effectiveEnv, secrets: effectiveSecrets,
+            executor: options.executor }) : null;
+        let syncInclude;
+        let syncExclude;
+        if (options.syncInclude !== undefined && options.syncInclude !== null) {
+            syncInclude = options.syncInclude;
+            syncExclude = undefined;
+        }
+        else if (options.syncExclude !== undefined) {
+            syncInclude = undefined;
+            syncExclude = options.syncExclude ?? undefined;
+        }
+        else if (options.syncInclude === null) {
+            syncInclude = undefined;
+            syncExclude = undefined;
+        }
+        else if (family.codingHarness) {
+            // Read live: tests and embedders may retarget the include presets.
+            const defaultInclude = DEFAULT_CODING_AGENT_SYNC_INCLUDES[runtime];
+            syncInclude = defaultInclude ?? undefined;
+            syncExclude = defaultInclude === null ? [] : undefined;
+        }
+        else if (family.syncExclude) {
+            syncExclude = [...family.syncExclude];
+        }
+        const defaultRoutes = options.openClawRoutes?.includeDesktop
+            ? buildOpenClawDesktopRoute(options.openClawRoutes) : {};
+        const effectiveOptions = {
+            ...options,
+            meta: buzzLaunch ? {
+                ...options.meta,
+                integrations: { ...options.meta?.integrations, buzz: { enabled: true } },
+            } : options.meta,
+            runtime,
+            size: buzzLaunch ? (options.size ?? 'large') : options.size,
+            env: buzzConfig?.env ?? effectiveEnv,
+            secrets: buzzConfig?.secrets ?? effectiveSecrets,
+            routes: buzzConfig?.routes ?? options.routes ?? defaultRoutes,
+            image: resolvedImage,
+            command: options.buzzEnabled || options.buzz
+                ? buzzConfig.command
+                // Runner-verbatim-spawn contract: the runner spawns
+                // launch_config.command exactly as stored, so the SDK constructs the
+                // full hyper-acp argv per runtime at create time — hyper-acp plus
+                // `--agent-command <runtime agent command>` and one repeated
+                // `--agent-arg` per extra agent argv element, mirroring the image's
+                // HYPER_ACP_AGENT_COMMAND/HYPER_ACP_AGENT_ARGS env split. There is no
+                // HYPER_ACP_AGENT_COMMAND env injection anywhere and no backend
+                // command map or runner fallback. ACP_RUNTIME_TABLE.agentCommand
+                // covers every runtime the process executor admits, so a bare
+                // hyper-acp (which would spawn a guaranteed-dead child-less bridge)
+                // can never ship. A caller-provided `command` override still wins.
+                // Container launches are unchanged: the image ENV/CMD already
+                // carries the agent command (openclaw/hermes images need no explicit
+                // command), so only coding-harness containers keep the bare
+                // container-path hyper-acp binary.
+                : options.command ?? (processExecutor
+                    ? [
+                        hyperAcpBinary,
+                        '--agent-command', family.agentCommand[0],
+                        ...family.agentCommand.slice(1).flatMap((arg) => ['--agent-arg', arg]),
+                    ]
+                    : family.codingHarness ? [hyperAcpBinary] : undefined),
+            syncRoot: options.syncRoot ?? family.syncRoot,
+            syncInclude,
+            syncExclude,
+            syncUid: options.syncUid ?? family.syncUid,
+            syncGid: options.syncGid ?? family.syncGid,
+            // Native process exit leaves hosted Buzz stopped; generic launch options
+            // cannot opt it back into automatic restart.
+            restart: buzzLaunch ? false : options.restart,
+            runtimeScopes: options.runtimeScopes ?? DEFAULT_AGENT_RUNTIME_SCOPES,
+        };
+        if (family.stripConfigBag) {
+            delete effectiveOptions.config;
+        }
+        const agent = await this.create(effectiveOptions);
+        if (agent.runtime !== runtime) {
+            throw new Error(`Deployment response did not identify runtime '${runtime}'`);
+        }
+        return agent;
+    }
+    async budget() {
+        return this.agentHttp.get(`${DEPLOYMENTS_API_PREFIX}/budget`);
+    }
+    async oneShotAgentWebSocket(agentId, purpose, request, timeoutMs = 45_000) {
+        const rawToken = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/${purpose}/token`);
+        const token = validateAgentWsToken(rawToken, agentId, purpose);
+        const parsed = new URL(token.ws_url);
+        parsed.searchParams.set('token', token.token);
+        const WebSocketImpl = preferredWebSocket();
+        let ws;
+        try {
+            ws = new WebSocketImpl(parsed.toString());
+        }
+        catch (error) {
+            throw new Error(`Agent ${purpose} WebSocket connection failed`, { cause: error });
+        }
+        return await new Promise((resolve, reject) => {
+            let opened = false;
+            let settled = false;
+            let socketError;
+            let result;
+            let resultCount = 0;
+            const timer = setTimeout(() => {
+                finish(new Error(`Agent ${purpose} WebSocket timed out`));
+                ws.close(1000, 'Client timeout');
+            }, timeoutMs);
+            const finish = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                if (error)
+                    reject(error);
+                else
+                    resolve(result);
+            };
+            ws.onopen = () => {
+                opened = true;
+                if (request !== undefined)
+                    ws.send(JSON.stringify(request));
+            };
+            ws.onmessage = (event) => {
+                const rejectFrame = (message, reason) => {
+                    const error = new Error(message);
+                    try {
+                        ws.close(1008, reason);
+                    }
+                    finally {
+                        finish(error);
+                    }
+                };
+                if (typeof event.data !== 'string') {
+                    rejectFrame(`Agent ${purpose} WebSocket returned a non-text result frame`, 'Invalid result frame');
+                    return;
+                }
+                resultCount += 1;
+                if (resultCount !== 1) {
+                    rejectFrame(`Agent ${purpose} WebSocket returned more than one result frame`, 'Too many result frames');
+                    return;
+                }
+                try {
+                    result = JSON.parse(event.data);
+                }
+                catch {
+                    rejectFrame(`Agent ${purpose} WebSocket returned invalid JSON`, 'Invalid result frame');
+                }
+            };
+            ws.onerror = (event) => {
+                const socketEvent = event;
+                const error = typeof socketEvent.error === 'object'
+                    && socketEvent.error instanceof Error
+                    ? socketEvent.error
+                    : undefined;
+                socketError = new Error(`Agent ${purpose} WebSocket connection failed`, { cause: error });
+            };
+            ws.onclose = (event) => {
+                if (socketError) {
+                    finish(socketError);
+                    return;
+                }
+                if (event.code !== 1000) {
+                    const reason = event.reason ? `: ${event.reason}` : '';
+                    finish(new Error(`Agent ${purpose} WebSocket closed with code ${event.code}${reason}`));
+                    return;
+                }
+                if (!opened || resultCount !== 1) {
+                    finish(new Error(`Agent ${purpose} WebSocket closed without one result frame`));
+                    return;
+                }
+                finish();
+            };
+        });
+    }
+    async metrics(agentIdOrName) {
+        const agentId = await this.resolveAgentId(agentIdOrName);
+        return validateAgentMetricsResult(await this.oneShotAgentWebSocket(agentId, 'metrics'));
+    }
+    async list(options = {}) {
+        return (await this.listWithCapacity(options)).items;
+    }
+    async listWithCapacity(options = {}) {
+        const params = {};
+        if (options.state)
+            params.state = options.state;
+        if (options.handle)
+            params.handle = options.handle;
+        if (options.name)
+            params.name = options.name;
+        if (options.query)
+            params.q = options.query;
+        if (options.includeDeleted !== undefined && options.includeDeleted !== null) {
+            params.include_deleted = options.includeDeleted ? 'true' : 'false';
+        }
+        const requestOptions = {
+            retries: options.retries,
+            backoff: options.backoff,
+            timeout: options.timeout,
+            signal: options.signal,
+            retryStatuses: options.retryStatuses,
+        };
+        const cleanRequestOptions = {};
+        for (const key of Object.keys(requestOptions)) {
+            const value = requestOptions[key];
+            if (value !== undefined) {
+                cleanRequestOptions[key] = value;
+            }
+        }
+        const data = await this.agentHttp.get(DEPLOYMENTS_API_PREFIX, Object.keys(params).length ? params : undefined, Object.keys(cleanRequestOptions).length ? cleanRequestOptions : undefined);
+        const payload = Array.isArray(data) ? { items: data } : data;
+        const items = (payload.items ?? []).map((item) => this.hydrateAgent(item));
+        const runningFallback = items.filter((agent) => !isAgentRuntimeInactiveState(agent.state)).length;
+        return {
+            items,
+            totalAgents: Number(payload.total_agents ?? items.length),
+            maxAgentsPerAccount: Number(payload.max_agents_per_account ?? 0),
+            runningAgents: Number(payload.running_agents ?? runningFallback),
+            slots: Object.fromEntries(Object.entries(payload.slots ?? {}).map(([size, raw]) => {
+                const inventory = raw;
+                return [size, {
+                        granted: Number(inventory.granted ?? 0),
+                        used: Number(inventory.used ?? inventory.occupied ?? 0),
+                        available: Number(inventory.available ?? 0),
+                    }];
+            })),
+            agentSlots: (payload.agent_slots ?? []).map(agentSlotFromDict),
+            pooledTpd: Number(payload.pooled_tpd ?? 0),
+        };
+    }
+    async get(agentIdOrName, requestOptions = {}) {
+        const raw = String(agentIdOrName || '').trim();
+        if (!raw)
+            throw new Error('agentIdOrName is required');
+        if (isSelfAgentRef(raw)) {
+            return this.getById('self', requestOptions);
+        }
+        if (!isDirectAgentIdRef(raw)) {
+            return this.resolveAgent(raw, requestOptions);
+        }
+        try {
+            return await this.getById(raw, requestOptions);
+        }
+        catch (error) {
+            if (!(error instanceof APIError) || ![404, 422].includes(error.statusCode) || isUuidRef(raw)) {
+                throw error;
+            }
+            return this.resolveAgent(raw, requestOptions);
+        }
+    }
+    async attachSlackRelayAgent(agentIdOrName, options) {
+        const agentId = await this.resolveAgentId(agentIdOrName);
+        return attachSlackRelayAgent({
+            relayBaseUrl: options.relayBaseUrl,
+            token: options.token || this.apiKey,
+            agentId,
+        });
+    }
+    async subscribe(handler, options = {}) {
+        const stableConnectionMs = 10_000;
+        let retryDelay = 250;
+        const waitBeforeReconnect = async () => {
+            let abortRetry = () => { };
+            const aborted = new Promise((resolve) => {
+                if (options.signal?.aborted)
+                    resolve();
+                else {
+                    abortRetry = resolve;
+                    options.signal?.addEventListener('abort', abortRetry, { once: true });
+                }
+            });
+            try {
+                await Promise.race([sleep(retryDelay), aborted]);
+            }
+            finally {
+                options.signal?.removeEventListener('abort', abortRetry);
+            }
+            retryDelay = Math.min(retryDelay * 2, 5_000);
+        };
+        while (!options.signal?.aborted) {
+            try {
+                const token = validateDeploymentEventToken(await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/events/token`, undefined, { signal: options.signal }));
+                const eventUrl = new URL(token.ws_url);
+                eventUrl.searchParams.set('token', token.token);
+                const WebSocketImpl = preferredWebSocket();
+                const ws = new WebSocketImpl(eventUrl.toString());
+                let readyAt = null;
+                let closedAt = null;
+                await new Promise((resolve, reject) => {
+                    let opened = false;
+                    let ready = false;
+                    let processing = Promise.resolve();
+                    const readyTimer = setTimeout(() => {
+                        ws.close(4002, 'Deployment event ready timed out');
+                        reject(new Error('Deployment event ready timed out'));
+                    }, 10_000);
+                    const abort = () => ws.close(1000, 'Subscription cancelled');
+                    options.signal?.addEventListener('abort', abort, { once: true });
+                    ws.addEventListener('open', () => { opened = true; });
+                    ws.addEventListener('message', (message) => {
+                        processing = processing.then(async () => {
+                            const frame = JSON.parse(await websocketMessageText(message.data));
+                            if (!ready) {
+                                if (frame.type !== 'ready') {
+                                    throw new Error('Deployment event socket did not send ready');
+                                }
+                                ready = true;
+                                readyAt = Date.now();
+                                clearTimeout(readyTimer);
+                                await options.onReady?.();
+                                return;
+                            }
+                            if (((frame.type === 'deployment.transition' || frame.type === 'deployment.import_status')
+                                && typeof frame.agent_id === 'string'
+                                && frame.agent_id.length > 0) || (frame.type === 'runner.presence'
+                                && typeof frame.runner_id === 'string'
+                                && frame.runner_id.length > 0) || ((frame.type === 'addReaction' || frame.type === 'removeReaction')
+                                && typeof frame.agent_id === 'string' && frame.agent_id.length > 0
+                                && typeof frame.session_id === 'string' && frame.session_id.length > 0
+                                && Number.isSafeInteger(frame.seq) && frame.seq > 0
+                                && typeof frame.message_id === 'string' && frame.message_id.length > 0)) {
+                                if (frame.type === 'addReaction' || frame.type === 'removeReaction') {
+                                    frame.meta = sessionMessageMetaFromWire(frame.meta ?? null, false);
+                                }
+                                await handler(frame);
+                            }
+                        }).catch((error) => {
+                            ws.close(4002, 'Invalid deployment event');
+                            reject(error);
+                        });
+                    });
+                    ws.addEventListener('error', () => reject(new Error('Deployment event WebSocket failed')));
+                    ws.addEventListener('close', () => {
+                        closedAt = Date.now();
+                        clearTimeout(readyTimer);
+                        options.signal?.removeEventListener('abort', abort);
+                        processing.then(resolve, reject);
+                    });
+                    if (options.signal?.aborted)
+                        abort();
+                    void opened;
+                });
+                if (!options.signal?.aborted) {
+                    // A `ready` frame followed by an immediate close is not a healthy
+                    // stream. Reset only after a useful stable interval so reconnects
+                    // and their authoritative REST resyncs retain exponential backoff.
+                    if (readyAt !== null
+                        && closedAt !== null
+                        && closedAt - readyAt >= stableConnectionMs) {
+                        retryDelay = 250;
+                    }
+                    await waitBeforeReconnect();
+                }
+            }
+            catch (error) {
+                if (options.signal?.aborted)
+                    break;
+                if (error instanceof TypeError && error.message === 'Invalid session reaction metadata')
+                    throw error;
+                if (error instanceof APIError && [401, 403].includes(error.statusCode))
+                    throw error;
+                if (error instanceof Error && error.message === 'Backend returned an invalid deployment event token response') {
+                    throw error;
+                }
+                await waitBeforeReconnect();
+                void error;
+            }
+        }
+    }
+    async waitForState(agentIdOrName, states, timeoutMs = 300_000, failureStates = [], minimumLaunchEpoch, pollIntervalMs = 5_000) {
+        if (!states.length)
+            throw new Error('states must not be empty');
+        if (minimumLaunchEpoch !== undefined && minimumLaunchEpoch < 0) {
+            throw new Error('minimumLaunchEpoch must be non-negative');
+        }
+        const agentId = await this.resolveAgentId(agentIdOrName);
+        const deadline = Date.now() + timeoutMs;
+        let lastState = '';
+        let wakePending = true;
+        let wake = null;
+        const controller = new AbortController();
+        const desired = new Set(states.map((state) => state.toLowerCase()));
+        const failures = new Set(failureStates.map((state) => state.toLowerCase()));
+        const effectivePollIntervalMs = Math.max(1, pollIntervalMs);
+        const stateLabel = states.join(', ');
+        let pendingFailureState = null;
+        const refresh = async (confirmFailure = false) => {
+            const agent = await this.get(agentId);
+            lastState = String(agent.state || '');
+            if (minimumLaunchEpoch !== undefined
+                && agent.launchEpoch < minimumLaunchEpoch)
+                return null;
+            const normalizedState = lastState.toLowerCase();
+            if (desired.has(normalizedState))
+                return agent;
+            if (failures.has(normalizedState)) {
+                // Accepting a lifecycle request publishes the new launch epoch a beat
+                // before the state leaves the previous terminal value, so a single
+                // terminal read under the accepted epoch is not proof of a terminal
+                // launch. Require it to survive one more observation.
+                if (!confirmFailure && pendingFailureState !== normalizedState) {
+                    pendingFailureState = normalizedState;
+                    return null;
+                }
+                throw new Error(`Agent entered ${lastState} while waiting for ${stateLabel}`);
+            }
+            pendingFailureState = null;
+            return null;
+        };
+        const subscription = this.subscribe((event) => {
+            if (event.type === 'deployment.transition' && event.agent_id === agentId) {
+                wakePending = true;
+                wake?.();
+            }
+        }, {
+            signal: controller.signal,
+            onReady: () => {
+                wakePending = true;
+                wake?.();
+            },
+        }).catch(() => {
+            // Lifecycle events reduce latency, but REST polling remains authoritative.
+            wakePending = true;
+            wake?.();
+        });
+        try {
+            while (Date.now() < deadline) {
+                if (wakePending) {
+                    wakePending = false;
+                    const agent = await refresh();
+                    if (agent)
+                        return agent;
+                    continue;
+                }
+                const remaining = deadline - Date.now();
+                if (remaining <= 0)
+                    break;
+                await Promise.race([
+                    new Promise((resolve) => { wake = resolve; }),
+                    sleep(Math.min(remaining, effectivePollIntervalMs)).then(() => {
+                        wakePending = true;
+                    }),
+                ]);
+                wake = null;
+            }
+            const finalAgent = await refresh(true);
+            if (finalAgent)
+                return finalAgent;
+        }
+        finally {
+            controller.abort();
+            await subscription;
+        }
+        throw new Error(`Timed out waiting for agent ${agentId} to reach ${stateLabel} (last=${lastState || 'unknown'})`);
+    }
+    async waitRunning(agentIdOrName, timeoutMs = 300_000, pollIntervalMs = 5_000, minimumLaunchEpoch) {
+        return this.waitForState(agentIdOrName, ['RUNNING'], timeoutMs, ['STOPPED', 'ARCHIVED', 'DELETED', 'FAILED', 'NO_NAMESPACE'], minimumLaunchEpoch, pollIntervalMs);
+    }
+    /**
+     * Read back every launch secret value the projection refuses to return.
+     *
+     * Agent projections list secret *names* and expose values only through the
+     * per-secret retrieval endpoint, so a complete `secrets` mapping has to be
+     * reassembled one key at a time. Every response is checked against
+     * `launchEpoch` so a rebuild never silently mixes values from an older
+     * launch generation into a new one.
+     */
+    async recoverRedactedSecrets(agentId, launchEpoch) {
+        const namesData = await this.secretNames(agentId);
+        if (Number(namesData.launch_epoch ?? 0) < launchEpoch) {
+            throw new Error('agent secret names belong to an older launch epoch');
+        }
+        const secrets = {};
+        for (const name of namesData.names ?? []) {
+            const secretData = await this.secret(agentId, String(name));
+            if (Number(secretData.launch_epoch ?? 0) < launchEpoch) {
+                throw new Error('agent secret belongs to an older launch epoch');
+            }
+            secrets[String(name)] = String(secretData.value ?? '');
+        }
+        return secrets;
+    }
+    /**
+     * Restore the two launch_config keys an Agent projection redacts.
+     *
+     * WHY THIS EXISTS — do not delete it as redundant validation sugar. The
+     * Backend's owner-facing Agent projection deliberately strips `secrets` and
+     * `registry_auth` before returning an Agent to a user-scoped caller
+     * (`hydrate_managed_agent` pops both), and this SDK's own hydrator drops
+     * `secrets` again. A caller that writes launch_config before start still
+     * needs a complete replacement object. Without this step the obvious round
+     * trip can never succeed, because the read side is structurally incapable of
+     * returning what the write side requires:
+     *
+     * ```ts
+     * const agent = await client.deployments.get(agentId);
+     * await client.deployments.update(agentId, { launchConfig: agent.launchConfig });
+     * // Error: launchConfig is incomplete; missing: secrets, registry_auth
+     * ```
+     *
+     * The fix is to complete the object honestly, never to weaken the
+     * completeness contract — launch_config writes are replacements, not merges.
+     *
+     * Only keys that are genuinely ABSENT are rebuilt. A caller-supplied
+     * `secrets` or `registry_auth` is honoured verbatim, including an explicit
+     * empty object, so "redacted by the projection" and "deliberately empty"
+     * remain distinguishable.
+     *
+     * `secrets` is recoverable because values can be read back one name at a
+     * time. `registry_auth` is NOT: it is caller-held, write-only, and never
+     * stored server-side. It therefore falls back to an explicitly supplied
+     * `registryAuth`, then to `{}` only when the configuration pulls from no
+     * `registry_url`; when a registry is configured an empty credential would
+     * silently break the image pull, so the caller is told to supply it instead.
+     */
+    async rehydrateRedactedLaunchConfig(resolvedAgentId, launchConfig, registryAuth) {
+        if (!isPlainRecord(launchConfig)) {
+            throw new Error('launchConfig must be a complete object');
+        }
+        const absent = REQUIRED_START_LAUNCH_CONFIG_KEYS.filter((key) => !Object.prototype.hasOwnProperty.call(launchConfig, key));
+        // Nothing missing, or missing more than the projection ever redacts: in
+        // both cases hand the object straight to the completeness gatekeeper. Only
+        // a config whose *sole* gaps are the two redacted keys is a projection
+        // round trip worth spending API calls to repair.
+        if (absent.length === 0 || absent.some((key) => key !== 'secrets' && key !== 'registry_auth')) {
+            return launchConfig;
+        }
+        const prepared = structuredClone(launchConfig);
+        if (absent.includes('secrets')) {
+            const agent = await this.getById(resolvedAgentId);
+            prepared.secrets = await this.recoverRedactedSecrets(resolvedAgentId, agent.launchEpoch);
+        }
+        if (absent.includes('registry_auth')) {
+            const registryUrl = String(prepared.registry_url ?? '').trim();
+            if (registryAuth) {
+                prepared.registry_auth = structuredClone(registryAuth);
+            }
+            else if (registryUrl) {
+                throw new Error(`Agent ${resolvedAgentId} pulls from registry_url ${JSON.stringify(registryUrl)} but `
+                    + 'launchConfig carries no registry_auth; registry_auth is caller-held and write-only, '
+                    + 'so the owner-facing projection can never return it and the SDK will not substitute '
+                    + 'an empty credential that would break the private-registry pull — pass registryAuth '
+                    + 'with the launch_config update');
+            }
+            else {
+                prepared.registry_auth = {};
+            }
+        }
+        return prepared;
+    }
+    /**
+     * Rebuild a complete replacement launch_config from
+     * nothing but the Agent's stored projection.
+     *
+     * This SDK starts stored config without reading it. This method is retained
+     * for callers that want to explicitly update stored launch_config;
+     * it is also the only place that canonicalizes the two legacy projection
+     * shapes the inline repair never sees, because the repair fills absent keys
+     * and touches nothing else:
+     * nullable `restart`, and a projection carrying both or neither sync policy.
+     *
+     * Reads the stored Agent projection, rehydrates redacted secrets through the
+     * per-secret retrieval endpoint, requires caller-held registry_auth whenever
+     * the stored config references a registry_url, normalizes those legacy
+     * shapes, and self-checks through the completeness gatekeeper.
+     */
+    async storedLaunchConfig(agentIdOrName, options = {}) {
+        const agent = await this.get(agentIdOrName);
+        if (!isPlainRecord(agent.launchConfig)) {
+            throw new Error(`Agent ${agent.id} has no stored launch_config projection`);
+        }
+        const launchConfig = structuredClone(agent.launchConfig);
+        // Legacy projections may still carry the old nullable restart
+        // representation; replacement writes receive one explicit boolean.
+        if ('restart' in launchConfig && launchConfig.restart === null) {
+            launchConfig.restart = false;
+        }
+        launchConfig.secrets = await this.recoverRedactedSecrets(agent.id, agent.launchEpoch);
+        const registryUrl = String(launchConfig.registry_url ?? '').trim();
+        if (registryUrl && !options.registryAuth) {
+            throw new Error(`Agent ${agent.id} pulls from registry_url ${JSON.stringify(registryUrl)}; `
+                + 'registry_auth is caller-held and never stored server-side, so it must '
+                + 'be supplied to rebuild a complete launch_config replacement');
+        }
+        launchConfig.registry_auth = options.registryAuth ? structuredClone(options.registryAuth) : {};
+        // Replacement writes require exactly one sync policy. Includes win when a legacy
+        // projection carries both; carrying neither canonicalizes to the
+        // explicit sync-everything exclusion list.
+        if (Object.prototype.hasOwnProperty.call(launchConfig, 'sync_include')) {
+            delete launchConfig.sync_exclude;
+        }
+        else if (!Object.prototype.hasOwnProperty.call(launchConfig, 'sync_exclude')) {
+            launchConfig.sync_exclude = [];
+        }
+        return cloneCompleteLaunchConfig(await this.rehydrateRedactedLaunchConfig(agent.id, launchConfig, options.registryAuth));
+    }
+    async start(agentIdOrName, options) {
+        const agentId = await this.resolveAgentId(agentIdOrName);
+        const suppliedOptions = options;
+        const mutationOptions = suppliedOptions
+            ? ['launchConfig', 'trustedProxies', 'registryAuth'].filter((key) => Object.prototype.hasOwnProperty.call(suppliedOptions, key))
+            : [];
+        if (mutationOptions.length > 0) {
+            throw new Error(`start no longer accepts launch mutation options: ${mutationOptions.join(', ')}; `
+                + 'update launchConfig before starting');
+        }
+        const body = {};
+        if (options?.dryRun)
+            body.dry_run = true;
+        const data = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/start`, Object.keys(body).length ? body : undefined, { retries: 1 });
+        return this.hydrateAgent(data);
+    }
+    async update(agentIdOrName, options = {}) {
+        // Only fields the backend UpdateAgentRequest accepts (it is extra="forbid"):
+        // name, handle, size, launch_config, runtime, reset_image, ui, integrations.
+        // refresh_from_lagoon/error are rejected.
+        const body = {};
+        if (options.name !== undefined)
+            body.name = options.name;
+        if (options.handle !== undefined)
+            body.handle = options.handle;
+        if (options.size !== undefined)
+            body.size = options.size;
+        if (options.launchConfig !== undefined)
+            body.launch_config = options.launchConfig;
+        if (options.runtime !== undefined)
+            body.runtime = options.runtime;
+        if (options.resetImage !== undefined)
+            body.reset_image = options.resetImage;
+        if (options.ui !== undefined)
+            body.ui = options.ui;
+        if (options.integrations !== undefined)
+            body.integrations = options.integrations;
+        const agentId = await this.resolveAgentId(agentIdOrName);
+        const data = await this.agentHttp.patch(`${DEPLOYMENTS_API_PREFIX}/${agentId}`, body);
+        return this.hydrateAgent(data);
+    }
+    /**
+     * Reset a deployment back to this runtime's platform defaults.
+     *
+     * The empty launch_config is intentional: Backend treats `{}` as "clear every
+     * mutable launch setting" while preserving protected launch identity and
+     * retained-storage fields. Runtime-specific files are deleted best-effort so
+     * the image can reseed its own config on the next boot.
+     */
+    async resetRuntimeDefaults(agentIdOrName, options) {
+        const agentId = await this.resolveAgentId(agentIdOrName);
+        const resetData = await this.agentHttp.patch(`${DEPLOYMENTS_API_PREFIX}/${agentId}`, {
+            runtime: options.runtime,
+            reset_image: true,
+            launch_config: {},
+        });
+        const droppedLaunchKeys = droppedLaunchConfigKeys(resetData);
+        const family = options.runtime === 'generic' ? undefined : ACP_RUNTIME_TABLE[options.runtime];
+        if (family?.openclawControlUi) {
+            await this.setEnv(agentId, 'OPENCLAW_CONTROL_UI_ALLOWED_ORIGIN', '*');
+        }
+        for (const file of family?.resetFiles ?? []) {
+            await this.fileDelete(agentId, file).catch(() => undefined);
+        }
+        for (const dir of family?.resetDirs ?? []) {
+            // Runner transport forbids recursive deletes; on reef it lands, elsewhere best-effort.
+            await this.fileDelete(agentId, dir, { recursive: true }).catch(() => undefined);
+        }
+        return { agent: await this.get(agentId), droppedLaunchKeys };
+    }
+    async uploadProfileImage(agentId, content, contentType) {
+        const resolvedAgentId = await this.resolveAgentId(agentId);
+        const resolvedContentType = contentType || (content instanceof Blob ? content.type : '') || 'image/png';
+        return this.agentHttp.postRaw(`${DEPLOYMENTS_API_PREFIX}/${resolvedAgentId}/profile-image`, content, resolvedContentType);
+    }
+    async deleteProfileImage(agentId) {
+        const resolvedAgentId = await this.resolveAgentId(agentId);
+        return this.agentHttp.delete(`${DEPLOYMENTS_API_PREFIX}/${resolvedAgentId}/profile-image`);
+    }
+    async resize(agentId, options) {
+        return this.update(agentId, options);
+    }
+    /**
+     * Request an agent stop.
+     *
+     * The returned agent remains `STOPPING` while runtime cleanup is in
+     * progress. Fetch it again until it becomes `STOPPED` before treating its
+     * deployment slot as released.
+     *
+     * With `dryRun: true` the Backend only validates the request and returns
+     * the current Agent unchanged -- nothing mutates and no stop is started.
+     */
+    async stop(agentIdOrName, options) {
+        const agentId = await this.resolveAgentId(agentIdOrName);
+        const body = {};
+        if (options?.dryRun)
+            body.dry_run = true;
+        const data = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/stop`, Object.keys(body).length ? body : undefined, { retries: 1 });
+        return this.hydrateAgent(data);
+    }
+    /**
+     * Archive durable storage without launching the agent.
+     *
+     * With `dryRun: true` the Backend only validates the request and returns
+     * the current Agent unchanged -- nothing mutates and no archive is started.
+     */
+    async archive(agentIdOrName, options) {
+        const agentId = await this.resolveAgentId(agentIdOrName);
+        const body = {};
+        if (options?.dryRun)
+            body.dry_run = true;
+        const data = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/archive`, Object.keys(body).length ? body : undefined, { retries: 1 });
+        return this.hydrateAgent(data);
+    }
+    /**
+     * Restore durable storage. The accepted snapshot is `RESTORING`; completion is `STOPPED`.
+     *
+     * With `dryRun: true` the Backend only validates the request and returns
+     * the current Agent unchanged -- nothing mutates and no restore is started.
+     */
+    async restore(agentIdOrName, options) {
+        const agentId = await this.resolveAgentId(agentIdOrName);
+        const body = {};
+        if (options?.dryRun)
+            body.dry_run = true;
+        const data = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/restore`, Object.keys(body).length ? body : undefined, { retries: 1 });
+        return this.hydrateAgent(data);
+    }
+    /**
+     * Resolve who the presented credential is, per the Backend
+     * (`GET /deployments/auth/me`).
+     *
+     * Answers the three questions a credential should be able to ask about
+     * itself: which Agent it is (`agentId`, set only for an Agent runtime key),
+     * which account owns it (`userId`, `teamId`, `planId`), and what it may do
+     * (`tags`, `capabilities`). It returns only what the credential already
+     * carries, so it is unscoped and safe for any caller.
+     *
+     * Distinct from the product-wide `client.user.authMe()`: this is the agent
+     * product's own introspection and is the only one that reports `agentId`.
+     */
+    async accessIdentity(requestOptions = {}) {
+        const path = `${DEPLOYMENTS_API_PREFIX}/auth/me`;
+        const data = Object.keys(requestOptions).length === 0
+            ? await this.agentHttp.get(path)
+            : await this.agentHttp.get(path, undefined, requestOptions);
+        return agentAccessIdentityFromData(data);
+    }
+    async getRoutes(agentIdOrName, options = {}) {
+        const agentId = await this.routesTarget(agentIdOrName);
+        const path = `${DEPLOYMENTS_API_PREFIX}/${agentId}/routes`;
+        const data = Object.keys(options).length > 0
+            ? await this.agentHttp.get(path, undefined, options)
+            : await this.agentHttp.get(path);
+        return agentRoutesStateFromData(data);
+    }
+    async setRoutes(agentIdOrName, routes, options = {}) {
+        const agentId = await this.routesTarget(agentIdOrName);
+        const body = {
+            routes: Object.fromEntries(Object.entries(routes).map(([name, route]) => [name, routeConfigBody(route)])),
+        };
+        if (Object.prototype.hasOwnProperty.call(options, 'cors') && options.cors !== undefined) {
+            body.cors = options.cors === null ? null : structuredClone(options.cors);
+        }
+        const data = await this.agentHttp.put(`${DEPLOYMENTS_API_PREFIX}/${agentId}/routes`, body);
+        return agentRoutesStateFromData(data);
+    }
+    async setRoute(agentIdOrName, name, route) {
+        const agentId = await this.routesTarget(agentIdOrName);
+        const body = routeConfigBody(route);
+        const data = await this.agentHttp.put(`${DEPLOYMENTS_API_PREFIX}/${agentId}/routes/${encodeURIComponent(name)}`, body);
+        return agentRoutesStateFromData(data);
+    }
+    async removeRoute(agentIdOrName, name) {
+        const agentId = await this.routesTarget(agentIdOrName);
+        const data = await this.agentHttp.delete(`${DEPLOYMENTS_API_PREFIX}/${agentId}/routes/${encodeURIComponent(name)}`);
+        return agentRoutesStateFromData(data);
+    }
+    /**
+     * Delete a deployment.
+     *
+     * With `dryRun: true` the Backend only validates the request and returns
+     * the current Agent record unchanged -- nothing mutates and the deployment
+     * is not deleted.
+     */
+    async delete(agentIdOrName, options) {
+        // HTTP 200 accepts the durable soft delete. Cluster-local cleanup continues
+        // in the background and is not proven complete by this response.
+        const agentId = await this.resolveAgentId(agentIdOrName);
+        const path = `${DEPLOYMENTS_API_PREFIX}/${agentId}`;
+        const result = options?.dryRun
+            ? await this.agentHttp.delete(path, { dry_run: true })
+            : await this.agentHttp.delete(path);
+        return result;
+    }
+    async refreshToken(agentIdOrName) {
+        const agentId = await this.resolveAgentId(agentIdOrName);
+        return this.agentHttp.get(`${DEPLOYMENTS_API_PREFIX}/${agentId}/token`);
+    }
+    /**
+     * Signed URL for the agent's VNC desktop. Requires a running agent with the
+     * `desktop` route enabled; throws otherwise.
+     */
+    async desktopUrl(agentIdOrName, options = {}) {
+        const agentId = await this.resolveAgentId(agentIdOrName);
+        const [token, agent] = await Promise.all([
+            this.refreshToken(agentId),
+            this.getById(agentId),
+        ]);
+        const jwt = (token.token ?? '').trim();
+        if (!jwt)
+            throw new Error('Desktop token is missing');
+        if (!agent.isRunning)
+            throw new Error('Start the agent to open its desktop');
+        const base = agent.desktopUrl;
+        if (!base)
+            throw new Error('Desktop route is not enabled for this agent');
+        const url = buildBrowserDesktopUrl(base, jwt, {
+            redirect: 'vnc_lite.html',
+            resize: 'scale',
+            ...options,
+        });
+        return { url, expiresAt: parseDate(token.expires_at), viewport: token.desktop_viewport ?? null };
+    }
+    async createScopedKey(agentIdOrName, name) {
+        const payload = {};
+        if (name)
+            payload.name = name;
+        const agentId = await this.resolveAgentId(agentIdOrName);
+        return this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/keys`, Object.keys(payload).length ? payload : undefined);
+    }
+    async webSearch(query, options = {}) {
+        const params = {
+            q: query,
+            count: options.count ?? 5,
+        };
+        if (options.country)
+            params.country = options.country;
+        if (options.searchLang)
+            params.search_lang = options.searchLang;
+        if (options.uiLang)
+            params.ui_lang = options.uiLang;
+        if (options.freshness)
+            params.freshness = options.freshness;
+        const headers = { 'X-Subscription-Token': this.apiKey };
+        if (this.agentHttp instanceof HTTPClient) {
+            return this.agentHttp.getWithHeaders('/brave/res/v1/web/search', params, headers);
+        }
+        const response = await this.fetchRaw(`/brave/res/v1/web/search?${new URLSearchParams(Object.fromEntries(Object.entries(params).map(([key, value]) => [key, String(value)]))).toString()}`, { headers });
+        return (await response.json());
+    }
+    async logsToken(agentIdOrName) {
+        const agentId = await this.resolveAgentId(agentIdOrName);
+        return validateAgentLogsToken(await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/logs/token`));
+    }
+    async env(agentIdOrName, requestOptions = {}) {
+        const agentId = await this.resolveAgentId(agentIdOrName, requestOptions);
+        const path = `${DEPLOYMENTS_API_PREFIX}/${agentId}/env`;
+        return Object.keys(requestOptions).length === 0
+            ? this.agentHttp.get(path)
+            : this.agentHttp.get(path, undefined, requestOptions);
+    }
+    async setEnv(agentIdOrName, key, value) {
+        if (!key)
+            throw new Error('env key is required');
+        const agentId = await this.resolveAgentId(agentIdOrName);
+        return this.agentHttp.patch(`${DEPLOYMENTS_API_PREFIX}/${agentId}/env/${encodeURIComponent(key)}`, { value });
+    }
+    async deleteEnv(agentIdOrName, key) {
+        if (!key)
+            throw new Error('env key is required');
+        const agentId = await this.resolveAgentId(agentIdOrName);
+        return this.agentHttp.delete(`${DEPLOYMENTS_API_PREFIX}/${agentId}/env/${encodeURIComponent(key)}`);
+    }
+    async secretNames(agentIdOrName, requestOptions = {}) {
+        const agentId = await this.resolveAgentId(agentIdOrName, requestOptions);
+        const path = `${DEPLOYMENTS_API_PREFIX}/${agentId}/secrets`;
+        return Object.keys(requestOptions).length === 0
+            ? this.agentHttp.get(path)
+            : this.agentHttp.get(path, undefined, requestOptions);
+    }
+    async secret(agentIdOrName, key, requestOptions = {}) {
+        const agentId = await this.resolveAgentId(agentIdOrName, requestOptions);
+        const path = `${DEPLOYMENTS_API_PREFIX}/${agentId}/secrets/${encodeURIComponent(key)}`;
+        return Object.keys(requestOptions).length === 0
+            ? this.agentHttp.get(path)
+            : this.agentHttp.get(path, undefined, requestOptions);
+    }
+    async setSecret(agentIdOrName, key, value) {
+        if (!key)
+            throw new Error('secret key is required');
+        const agentId = await this.resolveAgentId(agentIdOrName);
+        const result = await this.agentHttp.patch(`${DEPLOYMENTS_API_PREFIX}/${agentId}/secrets/${encodeURIComponent(key)}`, { value });
+        return result;
+    }
+    async deleteSecret(agentIdOrName, key) {
+        if (!key)
+            throw new Error('secret key is required');
+        const agentId = await this.resolveAgentId(agentIdOrName);
+        const result = await this.agentHttp.delete(`${DEPLOYMENTS_API_PREFIX}/${agentId}/secrets/${encodeURIComponent(key)}`);
+        return result;
+    }
+    async exec(target, command, options = {}) {
+        if (!Array.isArray(command)
+            || command.length < 1
+            || command.some((argument) => typeof argument !== 'string')
+            || command[0].length === 0
+            || command.some((argument) => argument.includes('\0'))
+            || command.reduce((size, argument) => size + encodeUtf8(argument).byteLength, 0) > 65_536) {
+            throw new Error('command must be a nonempty argv list of strings with a nonempty executable, at most 65536 UTF-8 bytes, and no NUL');
+        }
+        command = [...command];
+        const timeout = options.timeout ?? 30;
+        if (!Number.isInteger(timeout) || timeout < 1 || timeout > 300) {
+            throw new Error('timeout must be an integer from 1 through 300');
+        }
+        let stdin;
+        if (options.stdin !== undefined) {
+            const bytes = typeof options.stdin === 'string'
+                ? encodeUtf8(options.stdin)
+                : options.stdin;
+            if (!(bytes instanceof Uint8Array) || bytes.byteLength > AGENT_EXEC_STDIN_MAX_BYTES) {
+                throw new Error(`stdin must be a string or Uint8Array of at most ${AGENT_EXEC_STDIN_MAX_BYTES} bytes`);
+            }
+            stdin = encodeBase64(bytes);
+        }
+        const agentId = await this.agentIdFor(target);
+        const payload = {
+            command,
+            timeout,
+            dry_run: options.dryRun ?? false,
+            ...(stdin !== undefined ? { stdin } : {}),
+        };
+        return validateAgentExecResult(await this.oneShotAgentWebSocket(agentId, 'exec', payload, (timeout + 10) * 1_000));
+    }
+    /**
+     * Wait until the Agent file API is serving. Native assignments use a bounded
+     * file read; hosted assignments use the Reef readiness checks below.
+     *
+     * Probing the Agent hostname alone cannot answer this. The Agent domain is a
+     * wildcard, so a host with no route still resolves and the edge answers a
+     * plain-text `404 page not found` — byte for byte what a route that has not
+     * converged yet returns. A caller polling the hostname therefore cannot tell
+     * "not ready" from "never will be", and will retry until its deadline against
+     * a host that was never going to work.
+     *
+     * So ask the API for the authoritative Agent state first: a deleted or failed
+     * Agent rejects immediately with that state rather than timing out. Then
+     * require consecutive successful reads, because one success only proves the
+     * route answered once — the next request can still 404 while the edge settles.
+     */
+    async waitForFileApiReady(target, options = {}) {
+        const timeoutMs = options.timeoutMs ?? 90_000;
+        const consecutive = options.consecutive ?? 2;
+        const pollMs = options.pollMs ?? 1_000;
+        const agentId = await this.agentIdFor(target);
+        const deadline = Date.now() + timeoutMs;
+        let streak = 0;
+        let lastError = null;
+        let lastState = '';
+        for (;;) {
+            const agent = await this.get(agentId);
+            lastState = String(agent.state ?? '').toUpperCase();
+            if (lastState === 'DELETED' || lastState === 'FAILED' || lastState === 'NO_NAMESPACE') {
+                throw new Error(`Agent ${agentId} is ${lastState}; its Reef file API will not serve. Waiting longer cannot help.`);
+            }
+            try {
+                await this.filesList(agentId, '');
+                streak += 1;
+                if (streak >= consecutive)
+                    return;
+            }
+            catch (error) {
+                if (error instanceof APIError && error.statusCode === 501)
+                    throw error;
+                lastError = error;
+                streak = 0;
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`Agent ${agentId} Reef file API did not serve ${consecutive} consecutive reads within ` +
+                    `${Math.round(timeoutMs / 1000)}s (agent state=${lastState || 'unknown'}, last error=${String(lastError)})`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollMs));
+        }
+    }
+    async filesList(target, path = '') {
+        const resolvedPath = resolveSyncRootFilePath(path);
+        const agentId = await this.agentIdFor(target);
+        const access = await this.fileAccess(agentId);
+        let payload;
+        if ('transport' in access) {
+            payload = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/files/list`, { path: resolvedPath ? nativeFilePath(resolvedPath) : '' }, { redirect: 'error' });
+        }
+        else {
+            const suffix = resolvedPath ? `/${encodeFilePath(resolvedPath)}` : '';
+            const response = await this.fetchReef(access, `/directories${suffix}`);
+            payload = (await response.json());
+        }
+        if (!isDirectoryListingPayload(payload)) {
+            throw new Error('Reef returned an invalid directory listing');
+        }
+        return [...(payload.directories ?? []), ...(payload.files ?? [])];
+    }
+    async fileReadBytesWithMetadata(target, path, options) {
+        // Preserve absolute runtime addresses for the existing runner read command.
+        // Relative callers retain workspace semantics; hosted reads remain sync-root relative.
+        const absolute = path.startsWith('/') || /^[a-z]:[\\/]/i.test(path) || path.startsWith('\\\\');
+        const resolvedPath = absolute ? path : resolveSyncRootFilePath(path);
+        if (!resolvedPath)
+            throw new Error('agent file path is required');
+        const agentId = await this.agentIdFor(target);
+        const access = await this.fileAccess(agentId, options?.signal);
+        if ('transport' in access) {
+            const maxBytes = Math.min(options?.maxBytes ?? access.maxBytes, access.maxBytes);
+            if (!Number.isInteger(maxBytes) || maxBytes < 0)
+                throw new Error('maxBytes must be a nonnegative integer');
+            const query = new URLSearchParams({ path: absolute ? resolvedPath : nativeFilePath(resolvedPath), max_bytes: String(maxBytes) });
+            return this.agentHttp.getStream(`${DEPLOYMENTS_API_PREFIX}/${agentId}/files/stream?${query}`, async (response) => {
+                const content = await readResponseBytes(response, path, maxBytes);
+                const length = response.headers.get('content-length');
+                if (length === null || Number(length) !== content.byteLength)
+                    throw new Error('Incomplete runner file stream');
+                return { content };
+            }, { signal: options?.signal });
+        }
+        if (absolute)
+            resolveSyncRootFilePath(path); // Hosted transport has no runtime-absolute address space.
+        const response = await this.fetchReef(access, `/files/${encodeFilePath(resolvedPath)}`, {
+            signal: options?.signal,
+        });
+        const maxBytes = options?.maxBytes === undefined
+            ? AGENT_FILE_MAX_BYTES
+            : Math.min(options.maxBytes, AGENT_FILE_MAX_BYTES);
+        const bytes = await readResponseBytes(response, path, maxBytes);
+        const contentType = response.headers.get('content-type') || '';
+        return { content: bytes, mimeType: contentType || undefined };
+    }
+    async fileReadBytes(target, path, options) {
+        return (await this.fileReadBytesWithMetadata(target, path, options)).content;
+    }
+    async fileRead(target, path, options) {
+        // ignoreBOM means treat the BOM as content, matching Python/Rust UTF-8 readers.
+        return new TextDecoder('utf-8', { ignoreBOM: true }).decode(await this.fileReadBytes(target, path, options));
+    }
+    /**
+     * Write bytes to a relative path through Reef or the native runner transport.
+     *
+     * Per-file writes are limited to 100 MiB (`AGENT_FILE_WRITE_MAX_BYTES`,
+     * the Cloudflare edge request-body cap on the agent hostname). Larger data
+     * should be split across files or synced via the agent's own tooling.
+     * Native runner files are limited to 100 MiB under the retained assignment root.
+     */
+    async fileWriteBytes(target, path, content, options = {}) {
+        path = normalizeWritableBackendFilePath(path);
+        if (!path)
+            throw new Error('agent file path is required');
+        const encodedPath = encodeFilePath(path);
+        const bytes = toUint8Array(content);
+        if (bytes.byteLength > AGENT_FILE_WRITE_MAX_BYTES) {
+            throw new Error(`Agent file writes are limited to ${AGENT_FILE_WRITE_MAX_BYTES / 1024 / 1024} MiB `
+                + '(Cloudflare request-body cap on the agent hostname); '
+                + 'split larger data or sync it via the agent\'s own tooling');
+        }
+        const agentId = await this.agentIdFor(target);
+        const access = await this.fileAccess(agentId, options.signal);
+        if ('transport' in access) {
+            if (bytes.byteLength > access.maxBytes)
+                throw new Error(`Runner files are limited to ${access.maxBytes} bytes by this backend`);
+            const runnerPath = nativeFilePath(path);
+            const transferId = crypto.randomUUID();
+            let offset = 0;
+            const command = async (action, body = new Uint8Array(0), signal = options.signal) => {
+                const query = new URLSearchParams({ transfer_id: transferId, action, total: String(bytes.byteLength),
+                    offset: String(offset), path: action === 'open_write' ? runnerPath : '' });
+                const receipt = await this.agentHttp.postRaw(`${DEPLOYMENTS_API_PREFIX}/${agentId}/files/transfer?${query}`, body, 'application/octet-stream', { signal, retries: 1, redirect: 'error', ...(action === 'abort' ? { timeout: 1000 } : {}) });
+                const expected = offset + body.byteLength;
+                if (receipt.ok !== true || receipt.transfer_id !== transferId || receipt.offset !== expected || receipt.total !== bytes.byteLength) {
+                    throw new Error('Invalid runner file receipt');
+                }
+                offset = expected;
+                return receipt;
+            };
+            try {
+                await command('open_write');
+                while (offset < bytes.byteLength) {
+                    await command('write', bytes.subarray(offset, Math.min(offset + access.chunkBytes, bytes.byteLength)));
+                }
+                await command('commit');
+                return { ok: true };
+            }
+            catch (error) {
+                // Abort is cleanup, never replay of an uncertain write or commit.
+                await command('abort', new Uint8Array(0), new AbortController().signal).catch(() => undefined);
+                throw error;
+            }
+        }
+        const response = await this.fetchReef(access, `/files/${encodedPath}`, {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/octet-stream' },
+            body: bytes,
+        });
+        return (await response.json());
+    }
+    /**
+     * Write a UTF-8 text file to an agent.
+     *
+     * Subject to the 100 MiB per-file write limit; see `fileWriteBytes`.
+     */
+    async fileWrite(target, path, content) {
+        return this.fileWriteBytes(target, path, content);
+    }
+    async fileDelete(target, path, options = {}) {
+        path = normalizeWritableBackendFilePath(path);
+        if (!path)
+            throw new Error('agent file path is required');
+        const encodedPath = encodeFilePath(path);
+        const params = new URLSearchParams();
+        if (options.recursive)
+            params.set('recursive', 'true');
+        const suffix = params.toString() ? `?${params.toString()}` : '';
+        const agentId = await this.agentIdFor(target);
+        const access = await this.fileAccess(agentId);
+        if ('transport' in access) {
+            if (options.recursive)
+                throw new Error('Runner file deletion is never recursive');
+            // Backend POST performs exactly one attempt; an uncertain delete is never replayed.
+            const receipt = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/files/delete`, { path: nativeFilePath(path) }, { redirect: 'error' });
+            if (receipt?.status !== 'deleted' || receipt?.path !== path)
+                throw new Error('Invalid runner file receipt');
+            return receipt;
+        }
+        const response = await this.fetchReef(access, `/files/${encodedPath}${suffix}`, { method: 'DELETE' });
+        return (await response.json());
+    }
+    async cpTo(target, localPath, remotePath) {
+        const fs = await getFsPromises();
+        const content = await fs.readFile(localPath);
+        return this.fileWriteBytes(target, remotePath, new Uint8Array(content));
+    }
+    async cpFrom(target, remotePath, localPath) {
+        const fs = await getFsPromises();
+        const content = await this.fileReadBytes(target, remotePath);
+        const destination = new URL(`file://${localPath}`).pathname;
+        const parts = destination.split('/');
+        parts.pop();
+        const parent = parts.join('/') || '/';
+        await fs.mkdir(parent, { recursive: true });
+        await fs.writeFile(destination, content);
+        return destination;
+    }
+    /** One bounded display/capture read. All-unavailable capture errors retain their metadata. */
+    async getLogs(agentIdOrName, options = {}) {
+        const agentId = await this.resolveAgentId(agentIdOrName);
+        try {
+            return await this.agentHttp.get(`${DEPLOYMENTS_API_PREFIX}/${agentId}/logs`, agentLogQuery(options));
+        }
+        catch (error) {
+            if (error instanceof APIError) {
+                let snapshot;
+                try {
+                    snapshot = JSON.parse(error.detail);
+                }
+                catch { /* Ordinary HTTP error. */ }
+                if (isCapturedLogsSnapshot(snapshot))
+                    throw new AgentCapturedLogsError(error, snapshot);
+            }
+            throw error;
+        }
+    }
+    async logsConnect(agentIdOrName, options = {}) {
+        return this.connectLogs(agentIdOrName, options);
+    }
+    async connectLogs(agentIdOrName, options, onConnected) {
+        options.signal?.throwIfAborted();
+        const agentId = await this.resolveAgentId(agentIdOrName);
+        const tokenData = await this.logsToken(agentId);
+        options.signal?.throwIfAborted();
+        const container = options.container ?? 'reef';
+        const tailLines = options.tailLines ?? 100;
+        const wsUrl = `${this.agentsWsUrl}/logs/${agentId}` +
+            `?token=${encodeURIComponent(tokenData.token)}` +
+            `&container=${encodeURIComponent(container)}` +
+            `&tail_lines=${encodeURIComponent(String(tailLines))}`;
+        const url = new URL(wsUrl);
+        for (const [name, value] of Object.entries(agentLogQuery(options)))
+            url.searchParams.set(name, String(value));
+        const Socket = preferredWebSocket();
+        const ws = new Socket(url.toString());
+        return await new Promise((resolve, reject) => {
+            let settled = false;
+            const cleanup = () => {
+                clearTimeout(timer);
+                options.signal?.removeEventListener('abort', onAbort);
+                ws.onopen = null;
+                ws.onerror = null;
+                ws.onclose = null;
+            };
+            const fail = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                // Node ws emits an error when close aborts an unfinished handshake.
+                // Keep that owned teardown error handled until the socket closes.
+                ws.onerror = () => { };
+                ws.onclose = () => { ws.onerror = null; ws.onclose = null; };
+                try {
+                    ws.close();
+                }
+                catch { /* Already closed. */ }
+                reject(error);
+            };
+            const onAbort = () => fail(new Error('Agent logs connection aborted'));
+            const timer = setTimeout(() => fail(new Error('Agent logs connection timed out')), 30_000);
+            options.signal?.addEventListener('abort', onAbort, { once: true });
+            ws.onopen = () => {
+                if (settled)
+                    return;
+                cleanup();
+                try {
+                    // Install subscription handlers in the open callback, before the first
+                    // backend snapshot can arrive (not after an await in subscribeLogs).
+                    onConnected?.(ws);
+                    settled = true;
+                    resolve(ws);
+                }
+                catch (error) {
+                    fail(error instanceof Error ? error : new Error('Agent logs setup failed'));
+                }
+            };
+            ws.onerror = () => fail(new Error('WebSocket connection failed'));
+            ws.onclose = (event) => fail(new Error(`Agent logs connection closed (${event.code ?? 1006})`));
+            if (options.signal?.aborted)
+                onAbort();
+        });
+    }
+    /**
+     * Cluster logs replay history then stream lines. Runner logs instead deliver
+     * bounded replacement snapshots to onCapturedLogs, without history_end.
+     *
+     * One mechanism rather than a REST read plus a separate subscribe. The two-step
+     * form leaves a seam between the two calls that no server change can close,
+     * because the fetch and the subscribe share no lock; the backend takes the
+     * history snapshot and registers the subscriber under a single lock, so a line
+     * arriving mid-replay is delivered exactly once.
+     *
+     * Deliberately does not reconnect. A reconnect replays history again, which
+     * would duplicate lines into a consumer that has already rendered them;
+     * reconnect policy belongs to the caller, which knows whether it is resuming
+     * or restarting the view.
+     */
+    async subscribeLogs(agentIdOrName, handler, options = {}) {
+        const follow = options.follow ?? true;
+        return await new Promise((resolve, reject) => {
+            void this.connectLogs(agentIdOrName, options, (ws) => {
+                let settled = false;
+                const finish = (error) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    options.signal?.removeEventListener('abort', onAbort);
+                    ws.onmessage = null;
+                    ws.onclose = null;
+                    ws.onerror = null;
+                    try {
+                        ws.close();
+                    }
+                    catch { /* Already closed by the peer. */ }
+                    if (error)
+                        reject(error);
+                    else
+                        resolve();
+                };
+                function onAbort() { finish(); }
+                if (options.signal?.aborted) {
+                    finish();
+                    return;
+                }
+                options.signal?.addEventListener('abort', onAbort, { once: true });
+                let queue = Promise.resolve();
+                const enqueue = (callback) => {
+                    queue = queue.then(() => { if (!settled)
+                        return callback(); }).catch(error => {
+                        finish(error instanceof Error ? error : new Error('Agent logs callback failed'));
+                    });
+                };
+                enqueue(() => options.onReady?.());
+                ws.onmessage = (event) => {
+                    const raw = typeof event.data === 'string' ? event.data : Buffer.isBuffer(event.data) ? event.data.toString() : '';
+                    if (!raw)
+                        return;
+                    const frame = parseAgentLogFrame(raw);
+                    enqueue(async () => {
+                        switch (frame.kind) {
+                            case 'log':
+                                await handler(frame.line);
+                                return;
+                            case 'capturedLogs':
+                                if (!options.onCapturedLogs)
+                                    throw new Error('Runner log snapshots require an onCapturedLogs replacement handler');
+                                await options.onCapturedLogs(frame.snapshot);
+                                if (!follow)
+                                    finish();
+                                return;
+                            case 'historyEnd':
+                                await options.onHistoryEnd?.();
+                                if (!follow)
+                                    finish();
+                                return;
+                            case 'error':
+                                finish(new Error(frame.detail));
+                                return;
+                            default:
+                                return;
+                        }
+                    });
+                };
+                ws.onclose = (event) => {
+                    enqueue(async () => {
+                        await options.onClose?.({ code: event?.code ?? 1006, reason: event?.reason ?? '' });
+                        finish();
+                    });
+                };
+                ws.onerror = () => finish(new Error('WebSocket connection failed'));
+            }).catch(reject);
+        });
+    }
+    /**
+     * Buzz-backed agents publish observer telemetry to a Nostr relay (kind
+     * 24200, NIP-44-v2-encrypted to the owner). This subscribes the relay
+     * directly and decrypts locally; see {@link subscribeBuzzActivity}.
+     */
+    async subscribeBuzzActivity(agentIdOrName, handlers) {
+        return subscribeBuzzActivity(this, agentIdOrName, handlers);
+    }
+    /**
+     * Legacy Buzz activity through an agent `hyper-acp` WS route. Hosted Buzz
+     * launches no longer provision this route; the raw ACP path is outbound
+     * `HYPER_ACP_WS_URL`. See {@link subscribeBuzzActivityRoute}.
+     */
+    async subscribeBuzzActivityRoute(agentIdOrName, handlers) {
+        return subscribeBuzzActivityRoute(this, agentIdOrName, handlers);
+    }
+    async shellToken(agentIdOrName, shell, requestOptions = {}) {
+        const selectedShell = shell ?? '/bin/bash';
+        const agentId = await this.resolveAgentId(agentIdOrName, requestOptions);
+        const path = `${DEPLOYMENTS_API_PREFIX}/${agentId}/shell/token`;
+        const rawToken = Object.keys(requestOptions).length === 0
+            ? await this.agentHttp.post(path, { shell: selectedShell })
+            : await this.agentHttp.post(path, { shell: selectedShell }, requestOptions);
+        return validateAgentWsToken(rawToken, agentId, 'shell', selectedShell);
+    }
+    async shellConnect(agentIdOrName, shell, options = {}) {
+        if (options.signal?.aborted)
+            throw shellAbortError();
+        const tokenTimeoutMs = options.tokenTimeoutMs ?? 15_000;
+        const openTimeoutMs = options.openTimeoutMs ?? 10_000;
+        const tokenDeadline = Date.now() + tokenTimeoutMs;
+        const remainingTokenTime = () => Math.max(0, tokenDeadline - Date.now());
+        const runBeforeTokenDeadline = (operation) => {
+            const remaining = remainingTokenTime();
+            if (remaining <= 0)
+                return Promise.reject(new Error('Shell token request timed out'));
+            return runShellOperation(operation, options.signal, remaining, 'Shell token request timed out');
+        };
+        const agentId = await runBeforeTokenDeadline((signal) => this.resolveAgentId(agentIdOrName, { signal }));
+        const connectWithShell = async (requestedShell) => {
+            const remaining = remainingTokenTime();
+            if (remaining <= 0)
+                throw new Error('Shell token request timed out');
+            const requestOptions = {
+                retries: 3,
+                timeout: Math.max(500, Math.floor((tokenTimeoutMs - 3_000) / 3)),
+                retryStatuses: [429, 502, 503, 504],
+            };
+            const tokenData = await runBeforeTokenDeadline((signal) => {
+                requestOptions.signal = signal;
+                return this.shellToken(agentId, requestedShell, requestOptions);
+            });
+            const parsed = new URL(tokenData.ws_url);
+            parsed.searchParams.set('token', tokenData.token);
+            parsed.searchParams.set('shell', tokenData.shell);
+            const WebSocketImpl = preferredWebSocket();
+            const ws = new WebSocketImpl(parsed.toString());
+            ws.binaryType = 'arraybuffer';
+            return await new Promise((resolve, reject) => {
+                let settled = false;
+                const abortConnection = () => finish(shellAbortError());
+                const openTimer = setTimeout(() => finish(new Error('Shell connection timed out')), openTimeoutMs);
+                const cleanup = () => {
+                    clearTimeout(openTimer);
+                    options.signal?.removeEventListener('abort', abortConnection);
+                };
+                const finish = (error) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    cleanup();
+                    if (error) {
+                        try {
+                            ws.close();
+                        }
+                        catch {
+                            // The browser may have already finalized a failed socket.
+                        }
+                        reject(error);
+                    }
+                    else {
+                        resolve(ws);
+                    }
+                };
+                if (options.signal?.aborted) {
+                    finish(shellAbortError());
+                    return;
+                }
+                options.signal?.addEventListener('abort', abortConnection, { once: true });
+                ws.onopen = () => {
+                    finish();
+                };
+                ws.onerror = () => undefined;
+                ws.onclose = (event) => {
+                    const reason = event.reason ? `: ${event.reason}` : '';
+                    const error = new Error(`WebSocket closed before opening${reason}`);
+                    error.closeCode = event.code;
+                    error.closeReason = event.reason;
+                    finish(error);
+                };
+            });
+        };
+        return connectWithShell(shell ?? '/bin/bash');
+    }
+}
+//# sourceMappingURL=agents.js.map