@hypercli.com/sdk 2026.6.26 → 2026.8.11

package/dist/agents.js

@@ -2,17 +2,139 @@
  * HyperClaw agents API - typed agent lifecycle, files, exec, and OpenClaw access.
  */
 import { randomFillSync } from 'node:crypto';
+import NodeWebSocket from 'ws';
+import { agentSlotFromDict, } from './agent-slots.js';
+export { agentSlotFromDict, } from './agent-slots.js';
 import { getAgentsApiBaseUrl, getConfigValue } from './config.js';
 import { APIError } from './errors.js';
 import { HTTPClient } from './http.js';
 import { GatewayClient, } from './openclaw/gateway.js';
+import { normalizeSlackRelayBaseUrl } from './channels.js';
+import { HermesApiClient } from './hermes/gateway.js';
 const AGENTS_API_BASE = 'https://api.hypercli.com/agents';
 const DEV_AGENTS_API_BASE = 'https://api.dev.hypercli.com/agents';
 const DEPLOYMENTS_API_PREFIX = '/deployments';
 const AGENTS_WS_URL = 'wss://api.agents.hypercli.com/ws';
 const DEV_AGENTS_WS_URL = 'wss://api.agents.dev.hypercli.com/ws';
-export const DEFAULT_OPENCLAW_IMAGE = 'ghcr.io/hypercli/hypercli-openclaw:prod';
-export const DEFAULT_OPENCLAW_PRO_IMAGE = 'ghcr.io/hypercli/hypercli-openclaw:pro-prod';
+export const DEFAULT_OPENCLAW_IMAGE = 'ghcr.io/hypercli/hypercli-openclaw:pro-latest';
+export const DEFAULT_OPENCLAW_PRO_IMAGE = 'ghcr.io/hypercli/hypercli-openclaw:pro-latest';
+export const DEFAULT_HERMES_AGENT_IMAGE = 'ghcr.io/hypercli/hypercli-hermes-agent: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-code: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_BUZZ_AGENT_IMAGE = 'ghcr.io/hypercli/hypercli-buzz-agent:latest';
+export const DEFAULT_BUZZ_OPENCODE_IMAGE = 'ghcr.io/hypercli/hypercli-buzz-opencode:latest';
+export const DEFAULT_BUZZ_CODEX_IMAGE = 'ghcr.io/hypercli/hypercli-buzz-codex:latest';
+export const DEFAULT_BUZZ_CLAUDE_CODE_IMAGE = 'ghcr.io/hypercli/hypercli-buzz-claude:latest';
+export const DEFAULT_BUZZ_GOOSE_IMAGE = 'ghcr.io/hypercli/hypercli-buzz-goose:latest';
+export const DEFAULT_BUZZ_KIMI_CODE_IMAGE = 'ghcr.io/hypercli/hypercli-buzz-kimi-code:latest';
+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';
+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,
+};
+export const DEFAULT_CODING_AGENT_SYNC_INCLUDES = {
+    'buzz-agent': [],
+    opencode: [
+        '.config/opencode',
+        '.local/share/opencode',
+        '.local/state/opencode',
+        '.cache/opencode',
+    ],
+    codex: ['.codex'],
+    'claude-code': ['.claude', '.claude.json'],
+    goose: ['.goose'],
+    'kimi-code': ['.kimi-code'],
+};
+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,
+};
+const CODING_AGENT_RUNTIMES = new Set(['buzz-agent', 'opencode', 'codex', 'claude-code', 'goose', 'kimi-code']);
+const BUZZ_RUNTIME_COMMANDS = {
+    'buzz-agent': {
+        command: '/usr/local/bin/buzz-agent',
+        args: [],
+        mcpCommand: '/usr/local/bin/buzz-dev-mcp',
+    },
+    opencode: {
+        command: '/usr/local/bin/opencode',
+        args: ['acp'],
+        mcpCommand: '',
+    },
+    codex: {
+        command: '/usr/local/bin/codex-acp',
+        args: [],
+        mcpCommand: '/usr/local/bin/buzz-dev-mcp',
+    },
+    'claude-code': {
+        command: '/usr/local/bin/claude-agent-acp',
+        args: [],
+        mcpCommand: '',
+    },
+    goose: {
+        command: '/usr/local/bin/goose',
+        args: ['acp'],
+        mcpCommand: '',
+    },
+    'kimi-code': {
+        command: '/usr/local/bin/kimi',
+        args: ['acp'],
+        mcpCommand: '',
+    },
+};
+export const DEFAULT_BUZZ_RUST_LOG = 'buzz_acp=info,pool::prompt=info,acp::stream=off';
+const BUZZ_RESERVED_ENV_KEYS = new Set([
+    '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_LAZY_POOL',
+    'BUZZ_ACP_RELAY_OBSERVER',
+    'BUZZ_ACP_DISPLAY_NAME',
+    'BUZZ_ACP_TEXT_MENTIONS',
+    'BUZZ_ACP_REQUIRE_REPLY',
+    'CLAUDE_CODE_EXECUTABLE',
+    'BUZZ_ACP_SESSION_TITLE',
+    'BUZZ_ACP_SYSTEM_PROMPT',
+    'BUZZ_ACP_MODEL',
+    'BUZZ_ACP_IDLE_TIMEOUT',
+    'BUZZ_ACP_MAX_TURN_DURATION',
+    'BUZZ_ACP_AGENTS',
+    'BUZZ_ACP_RESPOND_TO',
+    'BUZZ_ACP_RESPOND_TO_ALLOWLIST',
+    'BUZZ_ACP_MULTIPLE_EVENT_HANDLING',
+    'BUZZ_ACP_DEDUP',
+    'BUZZ_ACP_SETUP_PAYLOAD',
+    'BUZZ_MANAGED_AGENT',
+    'BUZZ_MANAGED_AGENT_START_NONCE',
+]);
 export const OPENCLAW_MEMORY_SEARCH_ENV_DEFAULTS = {
     OPENCLAW_MEMORY_SEARCH_ENABLED: '1',
     OPENCLAW_MEMORY_SEARCH_SYNC_ON_SESSION_START: '0',
@@ -21,11 +143,400 @@ export const OPENCLAW_MEMORY_SEARCH_ENV_DEFAULTS = {
     OPENCLAW_MEMORY_SEARCH_SYNC_WATCH_DEBOUNCE_MS: '30000',
     OPENCLAW_MEMORY_SEARCH_SYNC_INTERVAL_MINUTES: '0',
 };
-const LAUNCH_CONFIG_KEYS = new Set(['image', 'env', 'routes', 'ports', 'command', 'entrypoint', 'sync_root', 'sync_enabled', 'sync_uid', 'sync_gid', 'registry_url', 'registry_auth']);
+export const OPENCLAW_WORKSPACES_SYNC_ENV_DEFAULTS = {
+    HYPER_WORKSPACES_BOOT_SYNC: '1',
+    HYPER_WORKSPACES_DIR: '/home/node/shared',
+    HYPER_WORKSPACES_SYNC_READY_ONLY: '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',
+]);
 const DEFAULT_OPENCLAW_SYNC_ROOT = '/home/node';
-export const AGENT_FILE_MAX_BYTES = 50 * 1024 * 1024;
+export const DEFAULT_HERMES_AGENT_SYNC_ROOT = '/opt/data';
+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;
 export const AGENT_FILE_TRANSFER_CHUNK_BYTES = 64 * 1024;
 export const AGENT_FILE_OPERATION_TIMEOUT_MS = 300_000;
+function stringifyOpenClawOperationsFailure(reason) {
+    if (reason instanceof Error)
+        return reason.message || reason.name || 'Error';
+    if (typeof reason === 'string')
+        return reason;
+    try {
+        const serialized = JSON.stringify(reason);
+        if (serialized !== undefined)
+            return serialized;
+    }
+    catch {
+        // Fall back to String for non-serializable rejection values.
+    }
+    try {
+        return String(reason);
+    }
+    catch {
+        return 'Unknown error';
+    }
+}
+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);
+            }
+        });
+    });
+}
+function buildBuzzLaunchEnv(runtime, buzz, defaultSessionTitle) {
+    if (!buzz.privateKeyNsec.trim())
+        throw new Error('buzz.privateKeyNsec is required');
+    if (!buzz.relayUrl.trim())
+        throw new Error('buzz.relayUrl is required');
+    const parallelism = buzz.parallelism ?? 1;
+    if (!Number.isInteger(parallelism) || parallelism < 1 || parallelism > 32) {
+        throw new Error('buzz.parallelism must be between 1 and 32');
+    }
+    const harness = BUZZ_RUNTIME_COMMANDS[runtime];
+    const env = {
+        BUZZ_RELAY_URL: buzz.relayUrl,
+        BUZZ_MANAGED_AGENT_START_NONCE: randomHexToken(16),
+        BUZZ_ACP_AGENT_COMMAND: harness.command,
+        BUZZ_ACP_AGENT_ARGS: harness.args.join(','),
+        BUZZ_ACP_MCP_COMMAND: harness.mcpCommand,
+        BUZZ_ACP_LAZY_POOL: 'true',
+        BUZZ_ACP_RELAY_OBSERVER: 'true',
+        BUZZ_ACP_AGENTS: String(parallelism),
+        BUZZ_ACP_MULTIPLE_EVENT_HANDLING: 'steer',
+        BUZZ_ACP_DEDUP: 'queue',
+    };
+    if (runtime === 'claude-code') {
+        env.CLAUDE_CODE_EXECUTABLE = '/usr/local/bin/claude';
+    }
+    if (buzz.rustLog)
+        env.RUST_LOG = buzz.rustLog;
+    const optional = {
+        BUZZ_AUTH_TAG: buzz.authTag,
+        BUZZ_ACP_DISPLAY_NAME: buzz.displayName,
+        BUZZ_ACP_SESSION_TITLE: buzz.sessionTitle || defaultSessionTitle,
+        BUZZ_ACP_SYSTEM_PROMPT: buzz.systemPrompt,
+        BUZZ_ACP_MODEL: buzz.model,
+        BUZZ_ACP_IDLE_TIMEOUT: buzz.idleTimeoutSeconds == null
+            ? undefined
+            : String(buzz.idleTimeoutSeconds),
+        BUZZ_ACP_MAX_TURN_DURATION: buzz.maxTurnDurationSeconds == null
+            ? undefined
+            : String(buzz.maxTurnDurationSeconds),
+        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;
+    }
+    if (buzz.textMentions)
+        env.BUZZ_ACP_TEXT_MENTIONS = 'true';
+    if (buzz.requireReply)
+        env.BUZZ_ACP_REQUIRE_REPLY = 'true';
+    return env;
+}
+function buildBuzzLaunchSecrets(buzz) {
+    if (!buzz.privateKeyNsec.trim())
+        throw new Error('buzz.privateKeyNsec is required');
+    return {
+        BUZZ_PRIVATE_KEY: buzz.privateKeyNsec,
+        NOSTR_PRIVATE_KEY: buzz.privateKeyNsec,
+    };
+}
+/** The agent's sync root and workspace, owned by the SDK so paths are unambiguous. */
+export const OPENCLAW_SYNC_ROOT = '/home/node';
+export const OPENCLAW_WORKSPACE_PREFIX = '.openclaw/workspace';
+/** Map the friendly `agent`/`backup` names to their on-the-wire `pod`/`s3` values. */
+export function toWireFileSource(source) {
+    switch (source) {
+        case 'agent': return 'pod';
+        case 'backup': return 's3';
+        default: return source; // 'auto' | 'pod' | 's3'
+    }
+}
+const GATEWAY_FILE_SOURCES = new Set(['gateway']);
+const FULL_FS_FILE_SOURCES = new Set(['agent', 'pod']);
+/**
+ * Resolve a caller path to the deployment HTTP files path (sync-root relative).
+ * Workspace-relative by default (prefixed with the workspace); an absolute `/…`
+ * path is read-only full-fs and only valid for the `agent` source.
+ */
+function resolveBackendFilePath(path, source) {
+    if (path.startsWith('/')) {
+        if (!FULL_FS_FILE_SOURCES.has(source)) {
+            throw new Error(`absolute paths need the 'agent' source (full pod filesystem); ` +
+                `'${source}' is scoped to ${source === 'backup' || source === 's3' ? 'the sync root' : 'the workspace'}.`);
+        }
+        return path; // full-fs path, passed through to source=pod
+    }
+    const rel = stripRelPrefix(path);
+    return rel ? `${OPENCLAW_WORKSPACE_PREFIX}/${rel}` : OPENCLAW_WORKSPACE_PREFIX;
+}
+function normalizeWritableBackendFilePath(path) {
+    const normalized = path.replace(/\\/g, '/');
+    if (normalized.startsWith('/')) {
+        const parts = normalized.split('/');
+        const resolved = [];
+        for (const part of parts) {
+            if (!part || part === '.')
+                continue;
+            if (part === '..') {
+                resolved.pop();
+                continue;
+            }
+            resolved.push(part);
+        }
+        const absolute = `/${resolved.join('/')}`;
+        const prefix = `${OPENCLAW_SYNC_ROOT}/`;
+        if (!absolute.startsWith(prefix)) {
+            throw new Error(`absolute write paths must stay within the sync root (${OPENCLAW_SYNC_ROOT}).`);
+        }
+        return absolute.slice(prefix.length);
+    }
+    if (normalized.split('/').includes('..')) {
+        throw new Error("paths containing '..' are not writable; writes and deletes must stay within the sync root.");
+    }
+    return stripRelPrefix(normalized);
+}
+/** Strip leading `./` segments and slashes without eating a dotfile's dot. */
+function stripRelPrefix(path) {
+    return path.replace(/^(?:\.\/)+/, '').replace(/^\/+/, '');
+}
+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 ?? {}),
+        routeStatuses: structuredClone(data.route_statuses ?? {}),
+    };
+}
+/** Strip a workspace prefix so gateway (name-addressed) sees the bare name. */
+function resolveGatewayFileName(path) {
+    if (path.startsWith('/')) {
+        throw new Error("absolute paths are not valid for the 'gateway' source (scoped to the workspace).");
+    }
+    const rel = stripRelPrefix(path);
+    return rel.startsWith(`${OPENCLAW_WORKSPACE_PREFIX}/`)
+        ? rel.slice(OPENCLAW_WORKSPACE_PREFIX.length + 1)
+        : rel;
+}
+/**
+ * ONE client wrapping all three agent file-access paths behind a single `source`
+ * switch (`agent` | `backup` | `gateway`, plus `auto`). The SDK owns the roots,
+ * so a workspace-relative path is the same file on every source; `agent` also
+ * takes absolute `/…` paths for read-only full-filesystem browsing. The
+ * underlying APIs are left as-is — this only wraps them.
+ */
+export class AgentFiles {
+    agent;
+    deployments;
+    gatewayHooks;
+    constructor(agent, deployments, gatewayHooks) {
+        this.agent = agent;
+        this.deployments = deployments;
+        this.gatewayHooks = gatewayHooks;
+    }
+    requireGateway() {
+        if (!this.gatewayHooks) {
+            throw new Error('gateway file source requires an OpenClaw agent with a gateway URL/token.');
+        }
+        return this.gatewayHooks;
+    }
+    async list(path = '', source = 'auto') {
+        if (!GATEWAY_FILE_SOURCES.has(source)) {
+            return this.deployments.filesList(this.agent, resolveBackendFilePath(path, source), toWireFileSource(source));
+        }
+        const gw = this.requireGateway();
+        const name = resolveGatewayFileName(path);
+        const files = await gw.withGateway(async (c) => c.filesList(await gw.resolveAgentId(c)));
+        return (files ?? [])
+            .map((f) => ({ name: f.name, path: f.name, type: 'file', size: f.size }))
+            .filter((f) => !name || f.name === name || f.name.startsWith(name.endsWith('/') ? name : `${name}/`));
+    }
+    async readBytes(path, source = 'auto', options) {
+        if (!GATEWAY_FILE_SOURCES.has(source)) {
+            const resolvedPath = resolveBackendFilePath(path, source);
+            const wireSource = toWireFileSource(source);
+            return options
+                ? this.deployments.fileReadBytes(this.agent, resolvedPath, wireSource, options)
+                : this.deployments.fileReadBytes(this.agent, resolvedPath, wireSource);
+        }
+        return (await this.readBytesWithMetadata(path, source, options)).content;
+    }
+    async readBytesWithMetadata(path, source = 'auto', options) {
+        if (!GATEWAY_FILE_SOURCES.has(source)) {
+            return this.deployments.fileReadBytesWithMetadata(this.agent, resolveBackendFilePath(path, source), toWireFileSource(source), options);
+        }
+        if (options?.signal?.aborted) {
+            const error = new Error('File read cancelled');
+            error.name = 'AbortError';
+            throw error;
+        }
+        const content = encodeUtf8(await this.read(path, source));
+        if (options?.maxBytes !== undefined && content.byteLength > options.maxBytes) {
+            throw fileReadLimitError(path, options.maxBytes);
+        }
+        return { content, mimeType: 'text/plain' };
+    }
+    async read(path, source = 'auto', options) {
+        if (!GATEWAY_FILE_SOURCES.has(source)) {
+            return decodeUtf8(await this.readBytes(path, source, options));
+        }
+        const gw = this.requireGateway();
+        return gw.withGateway(async (c) => c.fileGet(await gw.resolveAgentId(c), resolveGatewayFileName(path)));
+    }
+    async writeBytes(path, content, source = 'auto') {
+        if (!GATEWAY_FILE_SOURCES.has(source)) {
+            const writablePath = normalizeWritableBackendFilePath(path);
+            const resolvedPath = path.startsWith('/')
+                ? writablePath
+                : resolveBackendFilePath(writablePath, source);
+            return this.deployments.fileWriteBytes(this.agent, resolvedPath, content, toWireFileSource(source));
+        }
+        return this.write(path, coerceToUtf8String(content), source);
+    }
+    async write(path, content, source = 'auto') {
+        if (!GATEWAY_FILE_SOURCES.has(source)) {
+            const writablePath = normalizeWritableBackendFilePath(path);
+            const resolvedPath = path.startsWith('/')
+                ? writablePath
+                : resolveBackendFilePath(writablePath, source);
+            return this.deployments.fileWrite(this.agent, resolvedPath, content, toWireFileSource(source));
+        }
+        const gw = this.requireGateway();
+        const name = resolveGatewayFileName(path);
+        const agentId = await gw.withGateway(async (c) => {
+            const aid = await gw.resolveAgentId(c);
+            await c.fileSet(aid, name, content);
+            return aid;
+        });
+        return { name, source: 'gateway', agentId };
+    }
+    async delete(path, options = {}) {
+        const source = options.source ?? 'auto';
+        if (GATEWAY_FILE_SOURCES.has(source)) {
+            throw new Error('delete is not supported over the gateway file source; use the agent/backup source.');
+        }
+        const writablePath = normalizeWritableBackendFilePath(path);
+        const resolvedPath = path.startsWith('/')
+            ? writablePath
+            : resolveBackendFilePath(writablePath, source);
+        return this.deployments.fileDelete(this.agent, resolvedPath, {
+            recursive: options.recursive,
+            source: toWireFileSource(source),
+        });
+    }
+}
+/** Canonical states understood by this SDK. AgentState remains forward-open. */
+export const CANONICAL_AGENT_STATES = [
+    'CREATING',
+    'STARTING',
+    'RESTORING',
+    'RUNNING',
+    'STOPPING',
+    'STOPPED',
+    'ARCHIVING',
+    'ARCHIVED',
+    'FAILED',
+    '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',
+    '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;
@@ -52,6 +563,8 @@ function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
 function isOpenClawHydrationData(data) {
+    if (data.runtime === 'openclaw' || data.runtime === 'openclaw-pro')
+        return true;
     const routes = data.routes;
     if (routes && typeof routes === 'object' && !Array.isArray(routes) && routes.openclaw) {
         return true;
@@ -59,15 +572,122 @@ function isOpenClawHydrationData(data) {
     const launchRoutes = data.launch_config?.routes;
     return !!(launchRoutes && typeof launchRoutes === 'object' && !Array.isArray(launchRoutes) && launchRoutes.openclaw);
 }
+function isCodingAgentRuntime(runtime) {
+    return typeof runtime === 'string' && CODING_AGENT_RUNTIMES.has(runtime);
+}
 function isTruthyEnv(value) {
     return ['1', 'true', 'yes', 'on', 'enabled'].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;
+    if (isTruthyEnv(getLaunchConfigValue(launchConfig, 'env.OPENCLAW_DESKTOP_ENABLED')))
+        return true;
+    return routesHaveDesktop(getLaunchConfigValue(launchConfig, 'routes'));
+}
+export function agentConfigHasDesktop(source) {
+    if (!source)
+        return false;
+    return (launchConfigHasDesktop(source.launchConfig ?? source.launch_config) ||
+        routesHaveDesktop(source.routes));
+}
+function browserDesktopRedirectPath(options = {}) {
+    const redirect = (options.redirect ?? 'vnc.html').trim() || 'vnc.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())
+            parsed.searchParams.set('resize', resize);
+    }
+    const pathname = parsed.pathname.replace(/^\/+/, '') || 'vnc.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 isOpenClawProHydrationData(data) {
     const launchConfig = data.launch_config;
     if (!launchConfig || typeof launchConfig !== 'object' || Array.isArray(launchConfig))
         return false;
-    const env = launchConfig.env;
-    if (env && typeof env === 'object' && !Array.isArray(env) && isTruthyEnv(env.OPENCLAW_DESKTOP_ENABLED)) {
+    if (launchConfigHasDesktop(launchConfig)) {
         return true;
     }
     const image = String(launchConfig.image ?? '');
@@ -164,12 +784,78 @@ function encodeFilePath(path) {
         .map((part) => encodeURIComponent(part))
         .join('/');
 }
+function deploymentFileReadRequest(path, source) {
+    const params = new URLSearchParams({ source });
+    if (path.startsWith('/')) {
+        if (source !== 'pod') {
+            throw new Error("absolute paths require source='pod'.");
+        }
+        params.set('absolute_path', path);
+        return { suffix: '', params };
+    }
+    const encodedPath = encodeFilePath(path);
+    return { suffix: encodedPath ? `/${encodedPath}` : '', params };
+}
 function decodeUtf8(content) {
     return new TextDecoder().decode(content);
 }
 function encodeUtf8(content) {
     return new TextEncoder().encode(content);
 }
+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;
+}
+/** Coerce write content to a string for the gateway (text-only) file source. */
+function coerceToUtf8String(content) {
+    if (typeof content === 'string')
+        return content;
+    const bytes = content instanceof Uint8Array ? content : new Uint8Array(content);
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+}
 function toUint8Array(content) {
     if (typeof content === 'string')
         return encodeUtf8(content);
@@ -185,13 +871,25 @@ function execResultFromDict(data) {
     };
 }
 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 ?? '',
-        podId: data.pod_id ?? '',
-        podName: data.pod_name ?? '',
         state: data.state ?? 'unknown',
         name: data.name ?? null,
+        handle: data.handle ?? null,
+        displayName: data.display_name ?? data.name ?? null,
+        avatarUrl: data.avatar_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,
+        runtimeKeyAlias: data.runtime_key_alias ?? null,
+        relayKey: data.relay_key ?? null,
         cpu: data.cpu ?? 0,
         memory: data.memory ?? 0,
         hostname: data.hostname ?? null,
@@ -200,15 +898,18 @@ function agentStateFromDict(data) {
         jwtExpiresAt: parseDate(data.jwt_expires_at),
         startedAt: parseDate(data.started_at),
         stoppedAt: parseDate(data.stopped_at),
-        lastError: data.last_error ?? null,
+        archivedAt: parseDate(data.archived_at),
+        clusterId: data.cluster_id ?? null,
+        launchEpoch: data.launch_epoch ?? 0,
         createdAt: parseDate(data.created_at),
         updatedAt: parseDate(data.updated_at),
-        launchConfig: data.launch_config ?? null,
+        launchConfig,
         meta: data.meta?.ui ? { ui: structuredClone(data.meta.ui) } : null,
-        routes: data.routes ?? {},
-        command: data.command ?? [],
-        entrypoint: data.entrypoint ?? [],
-        ports: data.ports ?? [],
+        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),
     };
 }
@@ -233,24 +934,48 @@ export function buildAgentConfig(config = {}, options = {}) {
         preparedConfig.agents = agentsConfig;
     }
     const env = { ...(options.env ?? {}) };
-    let gatewayToken = options.gatewayToken?.trim() || env.OPENCLAW_GATEWAY_TOKEN?.trim() || '';
-    if (!gatewayToken) {
-        gatewayToken = randomHexToken(32);
-    }
-    env.OPENCLAW_GATEWAY_TOKEN = gatewayToken;
-    if (options.controlUiOriginLock !== false && !env.OPENCLAW_CONTROL_UI_ALLOWED_ORIGIN?.trim()) {
-        const controlUiOrigin = defaultControlUiAllowedOrigin();
-        if (controlUiOrigin) {
-            env.OPENCLAW_CONTROL_UI_ALLOWED_ORIGIN = controlUiOrigin;
+    const secrets = { ...(options.secrets ?? {}) };
+    if (Object.prototype.hasOwnProperty.call(env, 'OPENCLAW_GATEWAY_TOKEN')) {
+        throw new Error('OPENCLAW_GATEWAY_TOKEN is a Secret; pass it through secrets or gatewayToken, not env');
+    }
+    let gatewayToken = null;
+    if (options.injectGatewayToken !== false) {
+        const explicitGatewayToken = options.gatewayToken?.trim() || null;
+        const secretGatewayToken = secrets.OPENCLAW_GATEWAY_TOKEN?.trim() || null;
+        if (explicitGatewayToken && secretGatewayToken && explicitGatewayToken !== secretGatewayToken) {
+            throw new Error('gatewayToken conflicts with secrets.OPENCLAW_GATEWAY_TOKEN');
+        }
+        gatewayToken = explicitGatewayToken ?? secretGatewayToken;
+        if (gatewayToken)
+            secrets.OPENCLAW_GATEWAY_TOKEN = gatewayToken;
+        if (options.controlUiOriginLock !== false && !env.OPENCLAW_CONTROL_UI_ALLOWED_ORIGIN?.trim()) {
+            const controlUiOrigin = defaultControlUiAllowedOrigin();
+            if (controlUiOrigin) {
+                env.OPENCLAW_CONTROL_UI_ALLOWED_ORIGIN = controlUiOrigin;
+            }
         }
     }
+    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');
     const prepared = {};
     if (Object.keys(preparedConfig).length > 0)
         prepared.config = preparedConfig;
     if (Object.keys(env).length > 0)
         prepared.env = env;
-    if (options.ports !== undefined && options.ports !== null)
-        prepared.ports = options.ports;
+    if (Object.keys(secrets).length > 0)
+        prepared.secrets = secrets;
     if (options.routes !== undefined && options.routes !== null)
         prepared.routes = options.routes;
     if (options.command !== undefined && options.command !== null)
@@ -261,16 +986,25 @@ export function buildAgentConfig(config = {}, options = {}) {
         prepared.image = options.image;
     if (options.syncRoot !== undefined && options.syncRoot !== null)
         prepared.sync_root = options.syncRoot;
-    if (options.syncEnabled !== undefined && options.syncEnabled !== null)
-        prepared.sync_enabled = options.syncEnabled;
-    if (options.syncUid !== undefined && options.syncUid !== null)
-        prepared.sync_uid = options.syncUid;
-    if (options.syncGid !== undefined && options.syncGid !== null)
-        prepared.sync_gid = options.syncGid;
+    if (options.syncInclude !== undefined) {
+        prepared.sync_include = options.syncInclude === null ? null : [...options.syncInclude];
+    }
+    if (options.syncInclude === undefined && options.syncExclude !== undefined) {
+        prepared.sync_exclude = options.syncExclude === null ? null : [...options.syncExclude];
+    }
+    if (syncUid !== undefined)
+        prepared.sync_uid = syncUid;
+    if (syncGid !== undefined)
+        prepared.sync_gid = syncGid;
     if (options.registryUrl !== undefined && options.registryUrl !== null)
         prepared.registry_url = options.registryUrl;
     if (options.registryAuth !== undefined && options.registryAuth !== null)
         prepared.registry_auth = options.registryAuth;
+    if (options.restart !== undefined && options.restart !== null)
+        prepared.restart = options.restart;
+    if (options.runtimeScopes !== undefined && options.runtimeScopes !== null) {
+        prepared.runtime_scopes = [...options.runtimeScopes];
+    }
     return { config: prepared, gatewayToken };
 }
 function defaultOpenClawImage(image) {
@@ -283,6 +1017,210 @@ function defaultOpenClawProImage(image) {
         return image;
     return DEFAULT_OPENCLAW_PRO_IMAGE;
 }
+function defaultHermesAgentImage(image) {
+    if (image !== undefined && image !== null)
+        return image;
+    return DEFAULT_HERMES_AGENT_IMAGE;
+}
+function resolveHermesApiServerKey(explicit, env) {
+    const supplied = explicit?.trim() || env?.API_SERVER_KEY?.trim() || '';
+    const key = supplied || randomHexToken(32);
+    if (key.length < 32)
+        throw new Error('Hermes API_SERVER_KEY must be at least 32 characters');
+    return key;
+}
+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,
+        config: payload.config && typeof payload.config === 'object' && !Array.isArray(payload.config) ? payload.config : {},
+        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 buildOpenClawRoutes(options = {}) {
     const routes = {};
     if (options.includeGateway ?? true) {
@@ -292,7 +1230,7 @@ export function buildOpenClawRoutes(options = {}) {
             prefix: options.gatewayPrefix ?? '',
         };
     }
-    if (options.includeDesktop ?? true) {
+    if (options.includeDesktop ?? false) {
         routes.desktop = {
             port: options.desktopPort ?? 3000,
             auth: options.desktopAuth ?? true,
@@ -301,6 +1239,15 @@ export function buildOpenClawRoutes(options = {}) {
     }
     return routes;
 }
+export function buildHermesAgentRoutes(options = {}) {
+    return {
+        hermes: {
+            port: options.port ?? 8642,
+            auth: options.auth ?? false,
+            prefix: options.prefix ?? '',
+        },
+    };
+}
 function envBool(value) {
     return value ? '1' : '0';
 }
@@ -335,6 +1282,24 @@ export function buildOpenClawMemoryIndexEnv(memoryIndex = null) {
     }
     return env;
 }
+export function buildOpenClawWorkspacesSyncEnv(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 = { ...OPENCLAW_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');
 }
@@ -345,10 +1310,18 @@ function bindAgent(agent, deployments) {
 export class Agent {
     id;
     userId;
-    podId;
-    podName;
     state;
     name;
+    handle;
+    displayName;
+    avatarUrl;
+    displayIdentity;
+    runtime;
+    managed;
+    isLaunchable;
+    gatewayId;
+    runtimeKeyAlias;
+    relayKey;
     cpu;
     memory;
     hostname;
@@ -357,7 +1330,9 @@ export class Agent {
     jwtExpiresAt;
     startedAt;
     stoppedAt;
-    lastError;
+    archivedAt;
+    clusterId;
+    launchEpoch;
     createdAt;
     updatedAt;
     launchConfig;
@@ -365,16 +1340,23 @@ export class Agent {
     routes;
     command;
     entrypoint;
-    ports;
     dryRun;
     _deployments = null;
     constructor(fields) {
         this.id = fields.id;
         this.userId = fields.userId;
-        this.podId = fields.podId;
-        this.podName = fields.podName;
         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.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.runtimeKeyAlias = fields.runtimeKeyAlias ?? null;
+        this.relayKey = fields.relayKey ? structuredClone(fields.relayKey) : null;
         this.cpu = fields.cpu;
         this.memory = fields.memory;
         this.hostname = fields.hostname ?? null;
@@ -383,7 +1365,9 @@ export class Agent {
         this.jwtExpiresAt = fields.jwtExpiresAt ?? null;
         this.startedAt = fields.startedAt ?? null;
         this.stoppedAt = fields.stoppedAt ?? null;
-        this.lastError = fields.lastError ?? null;
+        this.archivedAt = fields.archivedAt ?? null;
+        this.clusterId = fields.clusterId ?? null;
+        this.launchEpoch = fields.launchEpoch ?? 0;
         this.createdAt = fields.createdAt ?? null;
         this.updatedAt = fields.updatedAt ?? null;
         this.launchConfig = fields.launchConfig ?? null;
@@ -391,7 +1375,6 @@ export class Agent {
         this.routes = { ...fields.routes };
         this.command = [...fields.command];
         this.entrypoint = [...fields.entrypoint];
-        this.ports = [...fields.ports];
         this.dryRun = fields.dryRun;
     }
     static fromDict(data) {
@@ -422,15 +1405,34 @@ export class Agent {
     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 executorUrl() {
-        return this.shellUrl;
-    }
     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');
@@ -451,7 +1453,7 @@ export class Agent {
         return data;
     }
     async waitRunning(timeoutMs = 300_000, pollIntervalMs = 5_000) {
-        return this.requireDeployments().waitRunning(this.id, timeoutMs, pollIntervalMs);
+        return this.requireDeployments().waitRunning(this.id, timeoutMs, pollIntervalMs, this.launchEpoch > 0 ? this.launchEpoch : undefined);
     }
     async update(options) {
         return this.requireDeployments().update(this.id, options);
@@ -460,32 +1462,68 @@ export class Agent {
         return this.requireDeployments().resize(this.id, options);
     }
     async env() {
-        const data = await this.requireDeployments().env(this.id);
-        return data.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 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 exec(command, options = {}) {
         return this.requireDeployments().exec(this, command, options);
     }
-    async health() {
-        return this.requireDeployments().health(this);
+    /**
+     * The gateway file writer a subclass supplies — the seam that enables the
+     * `gateway` source. The base agent has none (gateway calls throw); an agent
+     * type that speaks a gateway file protocol (e.g. OpenClaw's `agents.files.*`)
+     * overloads this. Kept on the base so the *calling* is standardized through
+     * the superclass even though each agent's gateway differs.
+     */
+    gatewayFileHooks() {
+        return undefined;
+    }
+    /**
+     * The single file client for this agent — one `source` switch (`agent` |
+     * `backup` | `gateway`) routes to the three underlying APIs (pod sidecar / S3
+     * backup / gateway), with the SDK owning the roots. One implementation; a
+     * subclass only supplies its gateway via {@link gatewayFileHooks}.
+     */
+    get files() {
+        return new AgentFiles(this, this.requireDeployments(), this.gatewayFileHooks());
     }
     async filesList(path = '', source = 'auto') {
-        return this.requireDeployments().filesList(this, path, source);
+        return this.files.list(path, source);
+    }
+    async fileReadBytes(path, source = 'auto', options) {
+        return this.files.readBytes(path, source, options);
     }
-    async fileReadBytes(path, source = 'auto') {
-        return this.requireDeployments().fileReadBytes(this, path, source);
+    async fileReadBytesWithMetadata(path, source = 'auto', options) {
+        return this.files.readBytesWithMetadata(path, source, options);
     }
-    async fileRead(path, source = 'auto') {
-        return decodeUtf8(await this.fileReadBytes(path, source));
+    async fileRead(path, source = 'auto', options) {
+        return this.files.read(path, source, options);
     }
     async fileWriteBytes(path, content, destination = 'auto') {
-        return this.requireDeployments().fileWriteBytes(this, path, content, destination);
+        return this.files.writeBytes(path, content, destination);
     }
     async fileWrite(path, content, destination = 'auto') {
-        return this.requireDeployments().fileWrite(this, path, content, destination);
+        return this.files.write(path, content, destination);
     }
     async fileDelete(path, options = {}) {
-        return this.requireDeployments().fileDelete(this, path, options);
+        return this.files.delete(path, options);
     }
     async cpTo(localPath, remotePath) {
         return this.requireDeployments().cpTo(this, localPath, remotePath);
@@ -493,8 +1531,434 @@ export class Agent {
     async cpFrom(remotePath, localPath) {
         return this.requireDeployments().cpFrom(this, remotePath, localPath);
     }
-    async shellConnect(shell) {
-        return this.requireDeployments().shellConnect(this.id, shell);
+    async shellConnect(shell, options) {
+        return this.requireDeployments().shellConnect(this.id, shell, options);
+    }
+}
+const RUNTIME_AUTH_CONFIG = {
+    'buzz-agent': {
+        agentCommand: ['buzz-agent'],
+        statusCommand: ['buzz-acp', 'models', '--agent-command', 'buzz-agent', '--json'],
+        logoutCommand: null,
+        nativeMethods: [],
+    },
+    opencode: {
+        agentCommand: ['opencode', 'acp'],
+        statusCommand: ['buzz-acp', 'models', '--agent-command', 'opencode', '--agent-args', 'acp', '--json'],
+        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: ['buzz-acp', 'models', '--agent-command', 'goose', '--agent-args', 'acp', '--json'],
+        logoutCommand: null,
+        nativeMethods: [],
+    },
+    'kimi-code': {
+        agentCommand: ['kimi', 'acp'],
+        statusCommand: ['buzz-acp', 'models', '--agent-command', 'kimi', '--agent-args', 'acp', '--json'],
+        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, '');
+}
+function authMethodFromPayload(value) {
+    if (!isPlainRecord(value))
+        return null;
+    const id = typeof value.id === 'string' ? value.id : '';
+    if (!id)
+        return null;
+    const metadata = isPlainRecord(value._meta) ? { ...value._meta } : {};
+    let command = [];
+    const terminal = isPlainRecord(metadata['terminal-auth']) ? metadata['terminal-auth'] : null;
+    const source = terminal ?? value;
+    if (Array.isArray(source.command) && source.command.every((part) => typeof part === 'string')) {
+        command = [...source.command];
+    }
+    else if (typeof source.command === 'string') {
+        const args = Array.isArray(source.args) ? source.args.filter((part) => typeof part === 'string') : [];
+        command = [source.command, ...args];
+    }
+    if (id === 'claude-login' && command.length > 0 && !command.includes('login')) {
+        command.push('auth', 'login');
+    }
+    return {
+        id,
+        name: typeof value.name === 'string' ? value.name : id,
+        description: typeof value.description === 'string' ? value.description : '',
+        kind: typeof value.kind === 'string' ? value.kind : 'acp',
+        command,
+        metadata,
+    };
+}
+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;
+        this.config = RUNTIME_AUTH_CONFIG[agent.runtime];
+    }
+    async methods() {
+        const [agentCommand, ...agentArgs] = this.config.agentCommand;
+        const command = ['buzz-acp', 'auth-methods', '--agent-command', agentCommand];
+        if (agentArgs.length)
+            command.push('--agent-args', agentArgs.join(','));
+        command.push('--json');
+        const result = await this.agent.exec(commandString(command));
+        const discovered = [];
+        if (result.exitCode === 0) {
+            try {
+                const payload = JSON.parse(stripTerminalCodes(result.stdout));
+                const values = isPlainRecord(payload) && Array.isArray(payload.methods) ? payload.methods : [];
+                for (const value of values) {
+                    const method = authMethodFromPayload(value);
+                    if (method)
+                        discovered.push(method);
+                }
+            }
+            catch {
+                // Native fallbacks still make authentication available.
+            }
+        }
+        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() {
+        const result = await this.agent.exec(commandString(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) {
+            const [agentCommand, ...agentArgs] = this.config.agentCommand;
+            command = ['buzz-acp', 'authenticate', '--agent-command', agentCommand];
+            if (agentArgs.length)
+                command.push('--agent-args', agentArgs.join(','));
+            command.push('--method-id', method.id);
+        }
+        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(commandString(command));
+        if (result.exitCode !== 0) {
+            throw new Error(`Runtime logout failed (${result.exitCode}): ${stripTerminalCodes(result.stderr || result.stdout).trim()}`);
+        }
+        return this.status();
+    }
+}
+export class CodingAgent extends Agent {
+    static defaultSyncInclude = null;
+    get auth() {
+        return new RuntimeAuthClient(this);
+    }
+}
+export class BuzzAgent extends CodingAgent {
+    static defaultSyncInclude = DEFAULT_CODING_AGENT_SYNC_INCLUDES['buzz-agent'];
+    static fromDict(data) {
+        return new BuzzAgent(agentStateFromDict(data));
+    }
+}
+export class OpenCodeAgent extends CodingAgent {
+    static defaultSyncInclude = DEFAULT_CODING_AGENT_SYNC_INCLUDES.opencode;
+    static fromDict(data) {
+        return new OpenCodeAgent(agentStateFromDict(data));
+    }
+}
+export class CodexAgent extends CodingAgent {
+    static defaultSyncInclude = DEFAULT_CODING_AGENT_SYNC_INCLUDES.codex;
+    static fromDict(data) {
+        return new CodexAgent(agentStateFromDict(data));
+    }
+}
+export class ClaudeCodeAgent extends CodingAgent {
+    static defaultSyncInclude = DEFAULT_CODING_AGENT_SYNC_INCLUDES['claude-code'];
+    static fromDict(data) {
+        return new ClaudeCodeAgent(agentStateFromDict(data));
+    }
+}
+export class GooseAgent extends CodingAgent {
+    static defaultSyncInclude = DEFAULT_CODING_AGENT_SYNC_INCLUDES.goose;
+    static fromDict(data) {
+        return new GooseAgent(agentStateFromDict(data));
+    }
+}
+export class KimiCodeAgent extends CodingAgent {
+    static defaultSyncInclude = DEFAULT_CODING_AGENT_SYNC_INCLUDES['kimi-code'];
+    static fromDict(data) {
+        return new KimiCodeAgent(agentStateFromDict(data));
+    }
+}
+const CODING_AGENT_CLASSES = {
+    'buzz-agent': BuzzAgent,
+    opencode: OpenCodeAgent,
+    codex: CodexAgent,
+    'claude-code': ClaudeCodeAgent,
+    goose: GooseAgent,
+    'kimi-code': KimiCodeAgent,
+};
+export class HermesAgent extends Agent {
+    apiUrl;
+    openaiBaseUrl;
+    /** Available only on the instance returned by createHermesAgent/startHermesAgent. */
+    apiServerKey;
+    constructor(fields) {
+        super(fields);
+        this.apiUrl = fields.apiUrl ?? this.routeUrl('hermes', '');
+        this.openaiBaseUrl = this.apiUrl ? `${this.apiUrl.replace(/\/+$/, '')}/v1` : null;
+        this.apiServerKey = fields.apiServerKey ?? null;
+    }
+    static fromDict(data) {
+        const fields = agentStateFromDict(data);
+        if (fields.launchConfig?.env && typeof fields.launchConfig.env === 'object') {
+            fields.launchConfig = structuredClone(fields.launchConfig);
+            delete fields.launchConfig.env.API_SERVER_KEY;
+        }
+        return new HermesAgent({
+            ...fields,
+            // Never recover API_SERVER_KEY from launch_config or process env.
+            apiServerKey: null,
+        });
+    }
+    /** Create a client for this agent's authenticated Hermes API. */
+    get api() {
+        if (!this.apiUrl || !this.apiServerKey)
+            return null;
+        return new HermesApiClient(this.apiUrl, { apiKey: this.apiServerKey });
+    }
+    /** Require a ready URL and the one-time SDK-retained API server key. */
+    apiClient() {
+        const client = this.api;
+        if (!client) {
+            throw new Error('Hermes API context is unavailable; use the HermesAgent returned by createHermesAgent/startHermesAgent after its hostname is attached');
+        }
+        return client;
+    }
+    async waitRunning(timeoutMs = 300_000, pollIntervalMs = 5_000) {
+        const ready = await super.waitRunning(timeoutMs, pollIntervalMs);
+        if (!(ready instanceof HermesAgent)) {
+            throw new Error("Running deployment did not identify runtime 'hermes-agent'");
+        }
+        ready.apiServerKey = this.apiServerKey;
+        return ready;
     }
 }
 export class OpenClawAgent extends Agent {
@@ -508,70 +1972,132 @@ export class OpenClawAgent extends Agent {
     static fromDict(data) {
         return new OpenClawAgent({
             ...agentStateFromDict(data),
-            gatewayUrl: null,
-            gatewayToken: data.gateway_token ?? null,
+            gatewayUrl: this.gatewayUrlFromHostname(data.hostname),
+            gatewayToken: null,
         });
     }
     static gatewayUrlFromHostname(hostname) {
         const trimmed = String(hostname ?? '').trim();
         return trimmed ? `wss://${trimmed}` : null;
     }
-    currentGatewayHostname() {
-        if (this.hostname)
-            return this.hostname;
-        if (!this.gatewayUrl)
-            return null;
-        try {
-            return new URL(this.gatewayUrl).hostname || null;
-        }
-        catch {
-            return this.gatewayUrl.replace(/^wss?:\/\//, '').split('/')[0] || null;
-        }
-    }
-    /**
-     * Resolve gateway context through the deployment record plus `/env`.
-     *
-     * Agent startup is eventually consistent: the deployment record may lag
-     * behind hostname attachment, and runtime env can lag behind both. The SDK
-     * derives the gateway URL from the attached hostname and reads the gateway
-     * token from `OPENCLAW_GATEWAY_TOKEN` in the agent env route.
-     */
+    /** Resolve OpenClaw connection context from the generic Agent and Secret APIs. */
     async waitForGatewayContext(options = {}) {
-        if (this.gatewayToken && this.gatewayUrl) {
-            return {
-                agent_id: this.id,
-                hostname: this.currentGatewayHostname(),
-                gateway_token: this.gatewayToken,
-            };
-        }
+        const callerAbortError = () => {
+            if (options.signal?.reason instanceof Error)
+                return options.signal.reason;
+            const error = new Error('OpenClaw gateway context wait cancelled');
+            error.name = 'AbortError';
+            return error;
+        };
+        if (options.signal?.aborted)
+            throw callerAbortError();
         const timeoutMs = options.timeoutMs ?? 30_000;
         const retryIntervalMs = options.retryIntervalMs ?? 1_000;
         const deployments = this.requireDeployments();
         const deadline = Date.now() + timeoutMs;
         let lastError = null;
-        while (true) {
-            try {
-                const refreshed = await deployments.get(this.id);
-                const hostname = refreshed.hostname ?? null;
-                const gatewayUrl = OpenClawAgent.gatewayUrlFromHostname(hostname);
-                const envData = await deployments.env(this.id);
-                const gatewayToken = envData.env?.OPENCLAW_GATEWAY_TOKEN?.trim() || null;
-                if (gatewayToken && gatewayUrl) {
-                    this.gatewayToken = gatewayToken;
+        const timeoutError = () => {
+            return lastError instanceof Error
+                ? lastError
+                : new Error('Timed out waiting for OpenClaw gateway context');
+        };
+        const controller = new AbortController();
+        const forwardAbort = () => controller.abort(callerAbortError());
+        options.signal?.addEventListener('abort', forwardAbort, { once: true });
+        const timeoutId = setTimeout(() => controller.abort(timeoutError()), Math.max(0, timeoutMs));
+        const waitAbortError = () => {
+            return controller.signal.reason instanceof Error ? controller.signal.reason : callerAbortError();
+        };
+        const runWithAbort = (operation) => {
+            if (controller.signal.aborted)
+                return Promise.reject(waitAbortError());
+            return new Promise((resolve, reject) => {
+                const abortOperation = () => {
+                    cleanup();
+                    reject(waitAbortError());
+                };
+                const cleanup = () => controller.signal.removeEventListener('abort', abortOperation);
+                controller.signal.addEventListener('abort', abortOperation, { once: true });
+                operation.then((value) => {
+                    cleanup();
+                    resolve(value);
+                }, (error) => {
+                    cleanup();
+                    reject(error);
+                });
+            });
+        };
+        const waitForRetry = (delayMs) => {
+            if (controller.signal.aborted)
+                return Promise.reject(waitAbortError());
+            return new Promise((resolve, reject) => {
+                const finish = () => {
+                    controller.signal.removeEventListener('abort', abortWait);
+                    resolve();
+                };
+                const timer = setTimeout(finish, delayMs);
+                const abortWait = () => {
+                    clearTimeout(timer);
+                    controller.signal.removeEventListener('abort', abortWait);
+                    reject(waitAbortError());
+                };
+                controller.signal.addEventListener('abort', abortWait, { once: true });
+            });
+        };
+        try {
+            while (true) {
+                const remainingMs = deadline - Date.now();
+                if (remainingMs <= 0)
+                    throw timeoutError();
+                const requestOptions = {
+                    signal: controller.signal,
+                    timeout: Math.max(1, remainingMs),
+                };
+                try {
+                    const refreshed = await runWithAbort(deployments.get(this.id, requestOptions));
+                    if (refreshed.launchEpoch < this.launchEpoch) {
+                        throw new Error('gateway Agent belongs to an older launch epoch');
+                    }
+                    if (refreshed.state.toUpperCase() !== 'RUNNING') {
+                        throw new Error(`gateway Agent is ${refreshed.state}, not RUNNING`);
+                    }
+                    const secret = await runWithAbort(deployments.secret(this.id, 'OPENCLAW_GATEWAY_TOKEN', requestOptions));
+                    if (secret.launch_epoch !== refreshed.launchEpoch) {
+                        throw new Error('gateway Secret and Agent belong to different launch epochs');
+                    }
+                    const gatewayToken = secret.value.trim();
+                    if (!gatewayToken)
+                        throw new Error('OPENCLAW_GATEWAY_TOKEN is empty');
+                    const confirmed = await runWithAbort(deployments.get(this.id, requestOptions));
+                    if (confirmed.launchEpoch !== refreshed.launchEpoch
+                        || confirmed.state.toUpperCase() !== 'RUNNING') {
+                        throw new Error('gateway Agent changed while its Secret was resolved');
+                    }
+                    const gatewayUrl = OpenClawAgent.gatewayUrlFromHostname(confirmed.hostname);
+                    if (!gatewayUrl)
+                        throw new Error('gateway Agent has no hostname');
                     this.gatewayUrl = gatewayUrl;
-                    return { agent_id: this.id, gateway_token: gatewayToken, hostname };
+                    this.gatewayToken = gatewayToken;
+                    return {
+                        agent_id: this.id,
+                        gateway_url: gatewayUrl,
+                        gateway_token: gatewayToken,
+                        launch_epoch: refreshed.launchEpoch,
+                    };
                 }
-                lastError = new Error('missing gateway context');
-            }
-            catch (error) {
-                lastError = error;
-            }
-            if (Date.now() >= deadline) {
-                if (lastError instanceof Error)
-                    throw lastError;
-                throw new Error('Timed out waiting for OpenClaw gateway context');
+                catch (error) {
+                    lastError = error;
+                }
+                const remainingAfterRequestMs = deadline - Date.now();
+                if (remainingAfterRequestMs <= 0)
+                    throw timeoutError();
+                const retryDelayMs = Math.min(Math.max(0, retryIntervalMs), remainingAfterRequestMs);
+                await waitForRetry(retryDelayMs);
             }
-            await new Promise((resolve) => setTimeout(resolve, retryIntervalMs));
+        }
+        finally {
+            clearTimeout(timeoutId);
+            options.signal?.removeEventListener('abort', forwardAbort);
         }
     }
     async resolveGatewayToken() {
@@ -603,6 +2129,7 @@ export class OpenClawAgent extends Agent {
             onHello: options.onHello,
             onClose: options.onClose,
             onGap: options.onGap,
+            onProtocolError: options.onProtocolError,
             onPairing: options.onPairing,
         });
     }
@@ -614,6 +2141,47 @@ export class OpenClawAgent extends Agent {
         await client.connect();
         return client;
     }
+    /** Run a fn against a connected gateway client, then close it. */
+    async withGateway(fn) {
+        const client = await this.connect();
+        try {
+            return await fn(client);
+        }
+        finally {
+            client.close();
+        }
+    }
+    _gatewayAgentId;
+    /**
+     * The in-gateway agent id for `agents.files.*` — NOT the deployment id. A
+     * deployment's gateway hosts an agent named `main` (or a named agent);
+     * matches the existing fileGet/fileSet/workspaceFiles convention.
+     */
+    async resolveGatewayAgentId(client) {
+        if (this._gatewayAgentId)
+            return this._gatewayAgentId;
+        let agents = [];
+        try {
+            agents = await client.agentsList();
+        }
+        catch {
+            // fall through to the canonical default
+        }
+        const resolved = agents[0]?.id ?? 'main';
+        this._gatewayAgentId = resolved;
+        return resolved;
+    }
+    /**
+     * Overload the base gateway seam with OpenClaw's `agents.files.*` — the actual
+     * OpenClaw gateway file methods. The base `files`/`fileX` calling surface is
+     * inherited unchanged; only the gateway writer is supplied here.
+     */
+    gatewayFileHooks() {
+        return {
+            withGateway: (fn) => this.withGateway(fn),
+            resolveAgentId: (c) => this.resolveGatewayAgentId(c),
+        };
+    }
     async gatewayStatus(options = {}) {
         const client = await this.connect(options);
         try {
@@ -665,6 +2233,64 @@ export class OpenClawAgent extends Agent {
             client.close();
         }
     }
+    async configureSlackRelay(options, gatewayOptions = {}) {
+        const { accountId, ...connectOptions } = gatewayOptions;
+        const client = await this.connect(connectOptions);
+        try {
+            if ('relay' in options) {
+                await client.configureSlackRelay(options, accountId);
+            }
+            else {
+                await client.configureSlackRelay({
+                    ...options,
+                    gatewayId: options.gatewayId ?? this.gatewayId ?? `agent:${this.id}`,
+                });
+            }
+        }
+        finally {
+            client.close();
+        }
+    }
+    async configureSlackSocket(config, options = {}) {
+        const { accountId, ...gatewayOptions } = options;
+        const client = await this.connect(gatewayOptions);
+        try {
+            await client.configureSlackSocket(config, accountId);
+        }
+        finally {
+            client.close();
+        }
+    }
+    async configureSlackHttp(config, options = {}) {
+        const { accountId, ...gatewayOptions } = options;
+        const client = await this.connect(gatewayOptions);
+        try {
+            await client.configureSlackHttp(config, accountId);
+        }
+        finally {
+            client.close();
+        }
+    }
+    async configureTelegram(config, options = {}) {
+        const { accountId, ...gatewayOptions } = options;
+        const client = await this.connect(gatewayOptions);
+        try {
+            await client.configureTelegram(config, accountId);
+        }
+        finally {
+            client.close();
+        }
+    }
+    async configureWhatsapp(config, options = {}) {
+        const { accountId, ...gatewayOptions } = options;
+        const client = await this.connect(gatewayOptions);
+        try {
+            await client.configureWhatsapp(config, accountId);
+        }
+        finally {
+            client.close();
+        }
+    }
     async configApply(config, options = {}) {
         const client = await this.connect(options);
         try {
@@ -692,6 +2318,44 @@ export class OpenClawAgent extends Agent {
             client.close();
         }
     }
+    async sessionsListResult(options = {}) {
+        const client = await this.connect(options);
+        try {
+            return await client.sessionsListResult();
+        }
+        finally {
+            client.close();
+        }
+    }
+    async operationsSnapshot(options = {}) {
+        if (!this.gatewayUrl || (!this.gatewayToken && !options.gatewayToken)) {
+            await this.waitForGatewayContext({ timeoutMs: options.timeout });
+        }
+        const client = this.gateway(options);
+        try {
+            await client.connect();
+            const [sessionsResult, cronResult] = await Promise.allSettled([
+                client.sessionsListResult(),
+                client.cronList(),
+            ]);
+            const failures = {};
+            if (sessionsResult.status === 'rejected') {
+                failures.sessions = stringifyOpenClawOperationsFailure(sessionsResult.reason);
+            }
+            if (cronResult.status === 'rejected') {
+                failures.cron = stringifyOpenClawOperationsFailure(cronResult.reason);
+            }
+            return {
+                sessions: sessionsResult.status === 'fulfilled' ? sessionsResult.value : null,
+                cronJobs: cronResult.status === 'fulfilled' ? cronResult.value : null,
+                failures,
+                capturedAt: Date.now(),
+            };
+        }
+        finally {
+            client.close();
+        }
+    }
     async *chatSend(message, sessionKey, options = {}) {
         const client = await this.connect(options);
         try {
@@ -706,7 +2370,25 @@ export class OpenClawAgent extends Agent {
     async channelsStatus(options = {}) {
         const client = await this.connect(options);
         try {
-            return await client.channelsStatus(options.probe ?? false, options.timeoutMs);
+            return await client.channelsStatus(options.probe ?? false, options.timeoutMs, options.channel);
+        }
+        finally {
+            client.close();
+        }
+    }
+    async channelsStart(channel, accountId, options = {}) {
+        const client = await this.connect(options);
+        try {
+            return await client.channelsStart(channel, accountId);
+        }
+        finally {
+            client.close();
+        }
+    }
+    async channelsStop(channel, accountId, options = {}) {
+        const client = await this.connect(options);
+        try {
+            return await client.channelsStop(channel, accountId);
         }
         finally {
             client.close();
@@ -741,6 +2423,7 @@ export class OpenClawAgent extends Agent {
             return await client.webLoginWait({
                 timeoutMs: options.timeoutMs,
                 accountId: options.accountId,
+                currentQrDataUrl: options.currentQrDataUrl,
             });
         }
         finally {
@@ -841,7 +2524,7 @@ export class OpenClawAgent extends Agent {
     async chatSendMessage(message, options = {}) {
         const client = await this.connect(options);
         try {
-            return await client.sendChat(message, options.sessionKey ?? 'main', options.agentId, options.attachments);
+            return await client.sendChat(message, options.sessionKey, options.agentId, options.attachments);
         }
         finally {
             client.close();
@@ -984,13 +2667,40 @@ export class OpenClawAgent extends Agent {
             client.close();
         }
     }
+    async cronAdd(job, options = {}) {
+        const client = await this.connect(options);
+        try {
+            return await client.cronAdd(job);
+        }
+        finally {
+            client.close();
+        }
+    }
+    async cronRemove(jobId, options = {}) {
+        const client = await this.connect(options);
+        try {
+            await client.cronRemove(jobId);
+        }
+        finally {
+            client.close();
+        }
+    }
+    async cronRun(jobId, options = {}) {
+        const client = await this.connect(options);
+        try {
+            return await client.cronRun(jobId);
+        }
+        finally {
+            client.close();
+        }
+    }
 }
 export class OpenClawProAgent extends OpenClawAgent {
     static fromDict(data) {
         return new OpenClawProAgent({
             ...agentStateFromDict(data),
-            gatewayUrl: null,
-            gatewayToken: data.gateway_token ?? null,
+            gatewayUrl: this.gatewayUrlFromHostname(data.hostname),
+            gatewayToken: null,
         });
     }
 }
@@ -1000,12 +2710,13 @@ export class Deployments {
     apiBase;
     agentsWsUrl;
     agentHttp;
-    constructor(http, agentApiKey, agentApiBase, agentsWsUrl) {
+    constructor(http, agentApiKey, agentApiBase, agentsWsUrl, requestTimeout) {
         this.http = http;
         this.apiKey = agentApiKey || http.apiKey;
         this.apiBase = resolveAgentsApiBase(agentApiBase || getAgentsApiBaseUrl());
         this.agentsWsUrl = normalizeAgentsWsUrl(agentsWsUrl || getConfigValue('AGENTS_WS_URL') || defaultAgentsWsUrl(this.apiBase));
-        this.agentHttp = http instanceof HTTPClient ? new HTTPClient(this.apiBase, this.apiKey) : http;
+        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;
@@ -1015,7 +2726,28 @@ export class Deployments {
     }
     hydrateAgent(data) {
         let agent;
-        if (isOpenClawProHydrationData(data)) {
+        if (data.runtime === 'hermes-agent') {
+            agent = HermesAgent.fromDict(data);
+        }
+        else if (data.runtime === 'buzz-agent') {
+            agent = BuzzAgent.fromDict(data);
+        }
+        else if (data.runtime === 'opencode') {
+            agent = OpenCodeAgent.fromDict(data);
+        }
+        else if (data.runtime === 'codex') {
+            agent = CodexAgent.fromDict(data);
+        }
+        else if (data.runtime === 'claude-code') {
+            agent = ClaudeCodeAgent.fromDict(data);
+        }
+        else if (data.runtime === 'goose') {
+            agent = GooseAgent.fromDict(data);
+        }
+        else if (data.runtime === 'kimi-code') {
+            agent = KimiCodeAgent.fromDict(data);
+        }
+        else if (data.runtime === 'openclaw-pro' || isOpenClawProHydrationData(data)) {
             agent = OpenClawProAgent.fromDict(data);
         }
         else if (isOpenClawHydrationData(data)) {
@@ -1026,8 +2758,57 @@ export class Deployments {
         }
         return bindAgent(agent, this);
     }
-    agentIdFor(target) {
-        return typeof target === 'string' ? target : target.id;
+    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 = {}, allowSelf = false) {
+        const raw = String(agentIdOrName || '').trim();
+        if (!raw) {
+            throw new Error('agentIdOrName is required');
+        }
+        if (isSelfAgentRef(raw)) {
+            if (allowSelf)
+                return 'self';
+            throw new Error('self is only supported for status, start, stop, and routes');
+        }
+        if (isDirectAgentIdRef(raw)) {
+            return raw;
+        }
+        return (await this.resolveAgent(raw, requestOptions)).id;
+    }
+    async agentIdFor(target) {
+        return typeof target === 'string' ? this.resolveAgentId(target) : target.id;
     }
     async fetchRaw(path, init = {}) {
         const headers = new Headers(init.headers ?? {});
@@ -1056,146 +2837,654 @@ export class Deployments {
         return response;
     }
     async create(options = {}) {
-        const { config, gatewayToken } = buildAgentConfig(options.config ?? {}, options);
+        const { config } = buildAgentConfig(options.config ?? {}, {
+            ...options,
+            injectGatewayToken: options.injectGatewayToken ?? !isCodingAgentRuntime(options.runtime),
+        });
         const body = { ...config, start: options.start ?? true };
         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.tags?.length)
             body.tags = [...options.tags];
-        const data = await this.agentHttp.post(DEPLOYMENTS_API_PREFIX, body);
-        const agent = this.hydrateAgent(data);
-        if (agent instanceof OpenClawAgent) {
-            agent.gatewayToken = gatewayToken;
-        }
-        agent.launchConfig = config;
-        agent.command = [...(config.command ?? [])];
-        agent.entrypoint = [...(config.entrypoint ?? [])];
-        return agent;
+        if (options.runtime)
+            body.runtime = options.runtime;
+        const data = await this.agentHttp.post(DEPLOYMENTS_API_PREFIX, body, { retries: 1 });
+        return this.hydrateAgent(data);
     }
     async createOpenClaw(options = {}) {
-        const effectiveOptions = { ...options };
-        effectiveOptions.env = { ...buildOpenClawMemoryIndexEnv(options.memoryIndex), ...(options.env ?? {}) };
+        const effectiveOptions = { ...options, runtime: options.runtime ?? 'openclaw' };
+        effectiveOptions.env = {
+            ...buildOpenClawWorkspacesSyncEnv(options.workspacesSync ?? null),
+            ...buildOpenClawMemoryIndexEnv(options.memoryIndex),
+            ...(options.env ?? {}),
+        };
+        if (effectiveOptions.env.HYPER_WORKSPACES_BOOT_SYNC !== '0') {
+            effectiveOptions.env.HYPER_WORKSPACES_DIR = '/home/node/shared';
+        }
         if (options.routes === undefined) {
             effectiveOptions.routes = buildOpenClawRoutes(options.openClawRoutes ?? {});
         }
         effectiveOptions.image = defaultOpenClawImage(options.image);
         if (effectiveOptions.syncRoot === undefined)
             effectiveOptions.syncRoot = DEFAULT_OPENCLAW_SYNC_ROOT;
-        if (effectiveOptions.syncEnabled === undefined)
-            effectiveOptions.syncEnabled = true;
+        if (options.syncInclude === undefined && options.syncExclude === undefined) {
+            effectiveOptions.syncExclude = DEFAULT_OPENCLAW_SYNC_EXCLUDE;
+        }
         return this.create(effectiveOptions);
     }
+    async createHermesAgent(options = {}) {
+        const apiServerKey = resolveHermesApiServerKey(options.apiServerKey, options.env);
+        const env = {
+            ...(options.env ?? {}),
+            API_SERVER_ENABLED: 'true',
+            API_SERVER_HOST: '0.0.0.0',
+            API_SERVER_KEY: apiServerKey,
+        };
+        delete env.OPENCLAW_GATEWAY_TOKEN;
+        const effectiveOptions = {
+            ...options,
+            runtime: 'hermes-agent',
+            env,
+            image: defaultHermesAgentImage(options.image),
+            runtimeScopes: options.runtimeScopes ?? DEFAULT_AGENT_RUNTIME_SCOPES,
+            injectGatewayToken: false,
+            syncRoot: options.syncRoot ?? DEFAULT_HERMES_AGENT_SYNC_ROOT,
+            syncUid: options.syncUid ?? DEFAULT_HERMES_AGENT_SYNC_UID,
+            syncGid: options.syncGid ?? DEFAULT_HERMES_AGENT_SYNC_GID,
+            routes: options.routes === undefined
+                ? buildHermesAgentRoutes(options.hermesRoute ?? {})
+                : options.routes,
+        };
+        const agent = await this.create(effectiveOptions);
+        if (!(agent instanceof HermesAgent)) {
+            throw new Error("Hermes deployment response did not identify runtime 'hermes-agent'");
+        }
+        agent.apiServerKey = apiServerKey;
+        if (agent.launchConfig?.env && typeof agent.launchConfig.env === 'object') {
+            agent.launchConfig = structuredClone(agent.launchConfig);
+            delete agent.launchConfig.env.API_SERVER_KEY;
+        }
+        return agent;
+    }
     async createOpenClawPro(options = {}) {
         return this.createOpenClaw({
             ...options,
+            runtime: 'openclaw-pro',
             env: { OPENCLAW_DESKTOP_ENABLED: '1', ...(options.env ?? {}) },
             image: defaultOpenClawProImage(options.image),
+            runtimeScopes: options.runtimeScopes ?? DEFAULT_AGENT_RUNTIME_SCOPES,
             openClawRoutes: { includeDesktop: true, ...(options.openClawRoutes ?? {}) },
         });
     }
+    async createCodingAgent(runtime, options) {
+        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');
+        }
+        const buzzLaunch = options.buzzEnabled || options.buzz !== undefined && options.buzz !== null;
+        if (buzzLaunch && options.size !== undefined && options.size !== 'large') {
+            throw new Error("Buzz coding agents require size='large'");
+        }
+        const effectiveEnv = {
+            ...buildOpenClawWorkspacesSyncEnv(options.workspacesSync ?? null),
+            ...(options.env ?? {}),
+        };
+        const effectiveSecrets = { ...(options.secrets ?? {}) };
+        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;
+        }
+        if (effectiveEnv.HYPER_WORKSPACES_BOOT_SYNC !== '0') {
+            effectiveEnv.HYPER_WORKSPACES_DIR = '/home/node/shared';
+        }
+        if (options.buzz) {
+            for (const key of BUZZ_RESERVED_ENV_KEYS)
+                delete effectiveEnv[key];
+            Object.assign(effectiveEnv, buildBuzzLaunchEnv(runtime, options.buzz, options.name));
+            Object.assign(effectiveSecrets, buildBuzzLaunchSecrets(options.buzz));
+        }
+        if (buzzLaunch) {
+            effectiveEnv.RUST_LOG ??= DEFAULT_BUZZ_RUST_LOG;
+        }
+        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 {
+            syncInclude = CODING_AGENT_CLASSES[runtime].defaultSyncInclude;
+            syncExclude = undefined;
+        }
+        const effectiveOptions = {
+            ...options,
+            runtime,
+            size: buzzLaunch ? 'large' : options.size,
+            injectGatewayToken: false,
+            env: effectiveEnv,
+            secrets: effectiveSecrets,
+            routes: options.routes ?? {},
+            image: options.image ?? (buzzLaunch
+                ? DEFAULT_BUZZ_CODING_AGENT_IMAGES[runtime]
+                : DEFAULT_CODING_AGENT_IMAGES[runtime]),
+            command: options.buzzEnabled || options.buzz
+                ? ['/usr/local/bin/buzz-acp']
+                : options.command,
+            syncRoot: options.syncRoot ?? DEFAULT_CODING_AGENT_SYNC_ROOT,
+            syncInclude,
+            syncExclude,
+            syncUid: options.syncUid ?? 1000,
+            syncGid: options.syncGid ?? 1000,
+            // Hosted Buzz shutdown is process-driven; generic launch options cannot
+            // opt it back into automatic restart.
+            restart: buzzLaunch ? false : options.restart,
+            runtimeScopes: options.runtimeScopes ?? DEFAULT_AGENT_RUNTIME_SCOPES,
+        };
+        return await this.create(effectiveOptions);
+    }
+    async createOpenCode(options = {}) {
+        return await this.createCodingAgent('opencode', options);
+    }
+    async createBuzzAgent(options = {}) {
+        return await this.createCodingAgent('buzz-agent', options);
+    }
+    async createCodex(options = {}) {
+        return await this.createCodingAgent('codex', options);
+    }
+    async createClaudeCode(options = {}) {
+        return await this.createCodingAgent('claude-code', options);
+    }
+    async createGoose(options = {}) {
+        return await this.createCodingAgent('goose', options);
+    }
+    async createKimiCode(options = {}) {
+        return await this.createCodingAgent('kimi-code', options);
+    }
     async budget() {
         return this.agentHttp.get(`${DEPLOYMENTS_API_PREFIX}/budget`);
     }
-    async metrics(agentId) {
+    async bootstrapInference(messages, responseFormat = { type: 'json_object' }, requestOptions = {}) {
+        return this.agentHttp.post('/bootstrap', {
+            messages,
+            response_format: responseFormat,
+        }, requestOptions);
+    }
+    async metrics(agentIdOrName) {
+        const agentId = await this.resolveAgentId(agentIdOrName);
         return this.agentHttp.get(`${DEPLOYMENTS_API_PREFIX}/${agentId}/metrics`);
     }
-    async list() {
-        const data = await this.agentHttp.get(DEPLOYMENTS_API_PREFIX);
-        const items = Array.isArray(data) ? data : data.items ?? [];
-        return items.map((item) => this.hydrateAgent(item));
+    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 createExternalAgent(options) {
+        const body = {
+            name: options.name,
+            runtime: options.runtime ?? 'openclaw',
+            status: options.status ?? 'active',
+        };
+        if (options.displayName !== undefined)
+            body.display_name = options.displayName;
+        if (options.handle !== undefined)
+            body.handle = options.handle;
+        if (options.meta !== undefined)
+            body.meta = options.meta;
+        const data = await this.agentHttp.post('/external-agents', body);
+        return this.hydrateAgent(data);
+    }
+    async updateExternalAgent(externalAgentId, options) {
+        const body = {};
+        if (options.name !== undefined)
+            body.name = options.name;
+        if (options.displayName !== undefined)
+            body.display_name = options.displayName;
+        if (options.handle !== undefined)
+            body.handle = options.handle;
+        if (options.runtime !== undefined)
+            body.runtime = options.runtime;
+        if (options.status !== undefined)
+            body.status = options.status;
+        if (options.meta !== undefined)
+            body.meta = options.meta;
+        const data = await this.agentHttp.patch(`/external-agents/${externalAgentId}`, body);
+        return this.hydrateAgent(data);
     }
-    async get(agentId) {
-        const data = await this.agentHttp.get(`${DEPLOYMENTS_API_PREFIX}/${agentId}`);
+    async getExternalAgent(externalAgentId) {
+        const data = await this.agentHttp.get(`/external-agents/${externalAgentId}`);
         return this.hydrateAgent(data);
     }
-    async waitRunning(agentId, timeoutMs = 300_000, pollIntervalMs = 5_000) {
+    async uploadExternalAgentProfileImage(externalAgentId, content, contentType) {
+        const resolvedContentType = contentType || (content instanceof Blob ? content.type : '') || 'image/png';
+        return this.agentHttp.postRaw(`/external-agents/${externalAgentId}/profile-image`, content, resolvedContentType);
+    }
+    async deleteExternalAgentProfileImage(externalAgentId) {
+        return this.agentHttp.delete(`/external-agents/${externalAgentId}/profile-image`);
+    }
+    async rotateExternalAgentKey(agentIdOrName) {
+        const agentId = await this.resolveAgentId(agentIdOrName);
+        return this.agentHttp.post(`/external-agents/${agentId}/keys/rotate`);
+    }
+    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 = {}) {
+        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 = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/events/token`, undefined, { signal: options.signal });
+                const WebSocketImpl = globalThis.WebSocket ?? NodeWebSocket;
+                const ws = new WebSocketImpl(token.ws_url);
+                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.send(JSON.stringify({ type: 'auth', token: token.token }));
+                    });
+                    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;
+                                clearTimeout(readyTimer);
+                                await options.onReady?.();
+                                retryDelay = 250;
+                                return;
+                            }
+                            if (frame.type === 'deployment.transition'
+                                && typeof frame.agent_id === 'string'
+                                && frame.agent_id.length > 0) {
+                                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', () => {
+                        clearTimeout(readyTimer);
+                        options.signal?.removeEventListener('abort', abort);
+                        processing.then(resolve, reject);
+                    });
+                    if (options.signal?.aborted)
+                        abort();
+                    void opened;
+                });
+                if (!options.signal?.aborted)
+                    await waitBeforeReconnect();
+            }
+            catch (error) {
+                if (options.signal?.aborted)
+                    break;
+                if (error instanceof APIError && [401, 403].includes(error.statusCode))
+                    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 = '';
-        while (Date.now() < deadline) {
+        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(', ');
+        const refresh = async () => {
             const agent = await this.get(agentId);
             lastState = String(agent.state || '');
-            if (lastState.toLowerCase() === 'running') {
+            if (minimumLaunchEpoch !== undefined
+                && agent.launchEpoch < minimumLaunchEpoch)
+                return null;
+            if (desired.has(lastState.toLowerCase()))
                 return agent;
+            if (failures.has(lastState.toLowerCase())) {
+                throw new Error(`Agent entered ${lastState} while waiting for ${stateLabel}`);
+            }
+            return null;
+        };
+        const subscription = this.subscribe((event) => {
+            if (event.type === 'deployment.transition' && event.agent_id === agentId) {
+                wakePending = true;
+                wake?.();
             }
-            if (lastState.toLowerCase() === 'failed' || lastState.toLowerCase() === 'error') {
-                throw new Error(`Agent entered ${lastState} while waiting for RUNNING`);
+        }, {
+            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;
             }
-            await sleep(pollIntervalMs);
+            const finalAgent = await refresh();
+            if (finalAgent)
+                return finalAgent;
+        }
+        finally {
+            controller.abort();
+            await subscription;
         }
-        throw new Error(`Timed out waiting for agent ${agentId} to reach RUNNING (last=${lastState})`);
+        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'], minimumLaunchEpoch, pollIntervalMs);
     }
-    async start(agentId, options = {}) {
-        const { config, gatewayToken } = buildAgentConfig(options.config ?? {}, options);
+    async start(agentIdOrName, options = {}) {
+        if (isSelfAgentRef(agentIdOrName)) {
+            const provided = Object.keys(options).filter((key) => options[key] !== undefined);
+            if (provided.length > 0) {
+                throw new Error(`start self uses the backend-stored launch configuration and does not accept launch overrides: ${provided.join(', ')}`);
+            }
+            const data = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/self/start`, {}, { retries: 1 });
+            return this.hydrateAgent(data);
+        }
+        const provided = Object.keys(options).filter((key) => options[key] !== undefined);
+        const agentId = await this.resolveAgentId(agentIdOrName, {}, true);
+        if (provided.length === 0) {
+            const data = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/start`, {}, { retries: 1 });
+            return this.hydrateAgent(data);
+        }
+        const { config } = buildAgentConfig(options.config ?? {}, options);
         const body = { ...config };
         if (options.dryRun)
             body.dry_run = true;
-        const data = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/start`, body);
-        const agent = this.hydrateAgent(data);
-        if (agent instanceof OpenClawAgent) {
-            agent.gatewayToken = gatewayToken;
-        }
-        agent.launchConfig = config;
-        agent.command = [...(config.command ?? [])];
-        agent.entrypoint = [...(config.entrypoint ?? [])];
-        return agent;
+        const data = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/start`, body, { retries: 1 });
+        return this.hydrateAgent(data);
     }
-    async startOpenClaw(agentId, options = {}) {
+    async startOpenClaw(agentIdOrName, options = {}) {
         const effectiveOptions = { ...options };
-        effectiveOptions.env = { ...buildOpenClawMemoryIndexEnv(options.memoryIndex), ...(options.env ?? {}) };
-        if (options.routes === undefined) {
-            effectiveOptions.routes = buildOpenClawRoutes(options.openClawRoutes ?? {});
+        if (options.workspacesSync !== undefined || options.memoryIndex !== undefined) {
+            effectiveOptions.env = {
+                ...(options.workspacesSync !== undefined
+                    ? buildOpenClawWorkspacesSyncEnv(options.workspacesSync ?? null)
+                    : {}),
+                ...(options.memoryIndex !== undefined
+                    ? buildOpenClawMemoryIndexEnv(options.memoryIndex)
+                    : {}),
+                ...(options.env ?? {}),
+            };
         }
-        effectiveOptions.image = defaultOpenClawImage(options.image);
-        if (effectiveOptions.syncRoot === undefined)
-            effectiveOptions.syncRoot = DEFAULT_OPENCLAW_SYNC_ROOT;
-        if (effectiveOptions.syncEnabled === undefined)
-            effectiveOptions.syncEnabled = true;
-        return this.start(agentId, effectiveOptions);
+        if (options.routes === undefined && options.openClawRoutes !== undefined) {
+            effectiveOptions.routes = buildOpenClawRoutes(options.openClawRoutes ?? undefined);
+        }
+        return this.start(agentIdOrName, effectiveOptions);
     }
-    async startOpenClawPro(agentId, options = {}) {
-        return this.startOpenClaw(agentId, {
+    async startHermesAgent(agentIdOrName, options = {}) {
+        const apiServerKey = resolveHermesApiServerKey(options.apiServerKey, options.env);
+        const env = {
+            ...(options.env ?? {}),
+            API_SERVER_ENABLED: 'true',
+            API_SERVER_HOST: '0.0.0.0',
+            API_SERVER_KEY: apiServerKey,
+        };
+        delete env.OPENCLAW_GATEWAY_TOKEN;
+        const effectiveOptions = {
             ...options,
-            env: { OPENCLAW_DESKTOP_ENABLED: '1', ...(options.env ?? {}) },
-            image: defaultOpenClawProImage(options.image),
-            openClawRoutes: { includeDesktop: true, ...(options.openClawRoutes ?? {}) },
-        });
+            env,
+            image: defaultHermesAgentImage(options.image),
+            runtimeScopes: options.runtimeScopes ?? DEFAULT_AGENT_RUNTIME_SCOPES,
+            injectGatewayToken: false,
+            syncRoot: options.syncRoot ?? DEFAULT_HERMES_AGENT_SYNC_ROOT,
+            syncUid: options.syncUid ?? DEFAULT_HERMES_AGENT_SYNC_UID,
+            syncGid: options.syncGid ?? DEFAULT_HERMES_AGENT_SYNC_GID,
+            routes: options.routes === undefined
+                ? buildHermesAgentRoutes(options.hermesRoute ?? {})
+                : options.routes,
+        };
+        const agent = await this.start(agentIdOrName, effectiveOptions);
+        if (!(agent instanceof HermesAgent)) {
+            throw new Error("Hermes deployment response did not identify runtime 'hermes-agent'");
+        }
+        agent.apiServerKey = apiServerKey;
+        return agent;
     }
-    async update(agentId, options = {}) {
+    async startOpenClawPro(agentIdOrName, options = {}) {
+        return this.startOpenClaw(agentIdOrName, options);
+    }
+    async update(agentIdOrName, options = {}) {
         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.refreshFromLagoon !== undefined)
             body.refresh_from_lagoon = options.refreshFromLagoon;
-        if (options.lastError !== undefined)
-            body.last_error = options.lastError;
+        if (options.error !== undefined)
+            body.error = options.error;
+        const agentId = await this.resolveAgentId(agentIdOrName);
         const data = await this.agentHttp.patch(`${DEPLOYMENTS_API_PREFIX}/${agentId}`, body);
         return this.hydrateAgent(data);
     }
+    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);
     }
-    async stop(agentId) {
-        const data = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/stop`);
+    /**
+     * 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.
+     */
+    async stop(agentIdOrName) {
+        const agentId = await this.resolveAgentId(agentIdOrName, {}, true);
+        const data = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/stop`, undefined, { retries: 1 });
+        return this.hydrateAgent(data);
+    }
+    /** Restore durable storage. The accepted snapshot is `RESTORING`; completion is `STOPPED`. */
+    async restore(agentIdOrName) {
+        const agentId = await this.resolveAgentId(agentIdOrName);
+        const data = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/restore`, undefined, { retries: 1 });
         return this.hydrateAgent(data);
     }
-    async delete(agentId) {
+    async getRoutes(agentIdOrName) {
+        const agentId = await this.resolveAgentId(agentIdOrName, {}, true);
+        const data = await this.agentHttp.get(`${DEPLOYMENTS_API_PREFIX}/${agentId}/routes`);
+        return agentRoutesStateFromData(data);
+    }
+    async setRoutes(agentIdOrName, routes) {
+        const agentId = await this.resolveAgentId(agentIdOrName, {}, true);
+        const body = { routes: structuredClone(routes) };
+        const data = await this.agentHttp.put(`${DEPLOYMENTS_API_PREFIX}/${agentId}/routes`, body);
+        return agentRoutesStateFromData(data);
+    }
+    async setRoute(agentIdOrName, name, route) {
+        const agentId = await this.resolveAgentId(agentIdOrName, {}, true);
+        const body = { port: route.port };
+        if (route.auth !== undefined)
+            body.auth = route.auth;
+        if (route.prefix !== undefined)
+            body.prefix = route.prefix;
+        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.resolveAgentId(agentIdOrName, {}, true);
+        const data = await this.agentHttp.delete(`${DEPLOYMENTS_API_PREFIX}/${agentId}/routes/${encodeURIComponent(name)}`);
+        return agentRoutesStateFromData(data);
+    }
+    async delete(agentIdOrName) {
+        const agentId = await this.resolveAgentId(agentIdOrName);
         return this.agentHttp.delete(`${DEPLOYMENTS_API_PREFIX}/${agentId}`);
     }
-    async refreshToken(agentId) {
+    async refreshToken(agentIdOrName) {
+        const agentId = await this.resolveAgentId(agentIdOrName);
         return this.agentHttp.get(`${DEPLOYMENTS_API_PREFIX}/${agentId}/token`);
     }
-    async createScopedKey(agentId, name) {
+    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 = {}) {
@@ -1218,14 +3507,33 @@ export class Deployments {
         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(agentId) {
+    async logsToken(agentIdOrName) {
+        const agentId = await this.resolveAgentId(agentIdOrName);
         return this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/logs/token`);
     }
-    async env(agentId) {
-        return this.agentHttp.get(`${DEPLOYMENTS_API_PREFIX}/${agentId}/env`);
+    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 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 exec(target, command, options = {}) {
-        const agentId = this.agentIdFor(target);
+        const agentId = await this.agentIdFor(target);
         const payload = {
             command,
             timeout: options.timeout ?? 30,
@@ -1235,36 +3543,21 @@ export class Deployments {
         const data = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/exec`, payload);
         return execResultFromDict(data);
     }
-    async health(target) {
-        if (!target.executorUrl) {
-            throw new Error('Agent has no executor URL');
-        }
-        const headers = {};
-        if (target.jwtToken) {
-            headers.Authorization = `Bearer ${target.jwtToken}`;
-            headers.Cookie = `${target.podName}-token=${target.jwtToken}`;
-        }
-        const response = await fetch(`${target.executorUrl}/health`, { headers });
-        if (!response.ok) {
-            throw new Error(`Agent health failed: ${response.status} ${response.statusText}`);
-        }
-        return (await response.json());
-    }
     async filesList(target, path = '', source = 'auto') {
-        const encodedPath = encodeFilePath(path);
-        const suffix = encodedPath ? `/${encodedPath}` : '';
-        const params = new URLSearchParams({ source });
-        const response = await this.fetchRaw(`${DEPLOYMENTS_API_PREFIX}/${this.agentIdFor(target)}/files${suffix}?${params.toString()}`);
+        const { suffix, params } = deploymentFileReadRequest(path, source);
+        const agentId = await this.agentIdFor(target);
+        const response = await this.fetchRaw(`${DEPLOYMENTS_API_PREFIX}/${agentId}/files${suffix}?${params.toString()}`);
         const payload = (await response.json());
         return [...(payload.directories ?? []), ...(payload.files ?? [])];
     }
-    async fileReadBytes(target, path, source = 'auto') {
-        const encodedPath = encodeFilePath(path);
-        const params = new URLSearchParams({ source });
-        const response = await this.fetchRaw(`${DEPLOYMENTS_API_PREFIX}/${this.agentIdFor(target)}/files/${encodedPath}?${params.toString()}`, {
+    async fileReadBytesWithMetadata(target, path, source = 'auto', options) {
+        const { suffix, params } = deploymentFileReadRequest(path, source);
+        const agentId = await this.agentIdFor(target);
+        const response = await this.fetchRaw(`${DEPLOYMENTS_API_PREFIX}/${agentId}/files${suffix}?${params.toString()}`, {
             redirect: 'follow',
+            signal: options?.signal,
         });
-        const bytes = new Uint8Array(await response.arrayBuffer());
+        const bytes = await readResponseBytes(response, path, options?.maxBytes);
         const contentType = response.headers.get('content-type') || '';
         if (contentType.includes('application/json')) {
             try {
@@ -1279,19 +3572,24 @@ export class Deployments {
                 }
             }
         }
-        return bytes;
+        return { content: bytes, mimeType: contentType || undefined };
     }
-    async fileRead(target, path, source = 'auto') {
-        return decodeUtf8(await this.fileReadBytes(target, path, source));
+    async fileReadBytes(target, path, source = 'auto', options) {
+        return (await this.fileReadBytesWithMetadata(target, path, source, options)).content;
+    }
+    async fileRead(target, path, source = 'auto', options) {
+        return decodeUtf8(await this.fileReadBytes(target, path, source, options));
     }
     async fileWriteBytes(target, path, content, destination = 'auto') {
+        path = normalizeWritableBackendFilePath(path);
         const encodedPath = encodeFilePath(path);
         const params = new URLSearchParams({ destination });
         const bytes = toUint8Array(content);
         if (bytes.byteLength > AGENT_FILE_MAX_BYTES) {
             throw new Error(`Agent file writes are limited to ${AGENT_FILE_MAX_BYTES / 1024 / 1024} MiB`);
         }
-        const response = await this.fetchRaw(`${DEPLOYMENTS_API_PREFIX}/${this.agentIdFor(target)}/files/${encodedPath}?${params.toString()}`, {
+        const agentId = await this.agentIdFor(target);
+        const response = await this.fetchRaw(`${DEPLOYMENTS_API_PREFIX}/${agentId}/files/${encodedPath}?${params.toString()}`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/octet-stream' },
             body: bytes,
@@ -1302,12 +3600,16 @@ export class Deployments {
         return this.fileWriteBytes(target, path, content, destination);
     }
     async fileDelete(target, path, options = {}) {
+        path = normalizeWritableBackendFilePath(path);
         const encodedPath = encodeFilePath(path);
         const params = new URLSearchParams();
         if (options.recursive)
             params.set('recursive', 'true');
+        if (options.source && options.source !== 'auto')
+            params.set('source', options.source);
         const suffix = params.toString() ? `?${params.toString()}` : '';
-        const response = await this.fetchRaw(`${DEPLOYMENTS_API_PREFIX}/${this.agentIdFor(target)}/files/${encodedPath}${suffix}`, { method: 'DELETE' });
+        const agentId = await this.agentIdFor(target);
+        const response = await this.fetchRaw(`${DEPLOYMENTS_API_PREFIX}/${agentId}/files/${encodedPath}${suffix}`, { method: 'DELETE' });
         return (await response.json());
     }
     async cpTo(target, localPath, remotePath) {
@@ -1326,7 +3628,8 @@ export class Deployments {
         await fs.writeFile(destination, content);
         return destination;
     }
-    async logsConnect(agentId, options = {}) {
+    async logsConnect(agentIdOrName, options = {}) {
+        const agentId = await this.resolveAgentId(agentIdOrName);
         const tokenData = await this.logsToken(agentId);
         const container = options.container ?? 'reef';
         const tailLines = options.tailLines ?? 100;
@@ -1348,31 +3651,91 @@ export class Deployments {
             };
         });
     }
-    async shellToken(agentId, shell, dryRun = false) {
+    async shellToken(agentIdOrName, shell, dryRun = false, requestOptions = {}) {
         const selectedShell = shell ?? '/bin/bash';
         const payload = { shell: selectedShell };
         if (dryRun)
             payload.dry_run = true;
-        return this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/shell/token`, payload);
-    }
-    async shellConnect(agentId, shell) {
+        const agentId = await this.resolveAgentId(agentIdOrName, requestOptions);
+        const path = `${DEPLOYMENTS_API_PREFIX}/${agentId}/shell/token`;
+        if (Object.keys(requestOptions).length === 0)
+            return this.agentHttp.post(path, payload);
+        return this.agentHttp.post(path, payload, requestOptions);
+    }
+    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 tokenData = await this.shellToken(agentId, 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, false, requestOptions);
+            });
             const baseUrl = `${this.agentsWsUrl}/shell/${agentId}`;
             const separator = baseUrl.includes("?") ? "&" : "?";
             const wsUrl = `${baseUrl}${separator}jwt=${encodeURIComponent(tokenData.jwt)}` +
                 `&shell=${encodeURIComponent(tokenData.shell || requestedShell)}`;
             const ws = new WebSocket(wsUrl);
+            ws.binaryType = 'arraybuffer';
             return await new Promise((resolve, reject) => {
                 let settled = false;
-                ws.onopen = () => {
-                    settled = true;
-                    resolve(ws);
+                const abortConnection = () => finish(shellAbortError());
+                const openTimer = setTimeout(() => finish(new Error('Shell connection timed out')), openTimeoutMs);
+                const cleanup = () => {
+                    clearTimeout(openTimer);
+                    options.signal?.removeEventListener('abort', abortConnection);
                 };
-                ws.onerror = () => {
-                    if (!settled) {
-                        reject(new Error('WebSocket connection failed'));
+                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);
                 };
             });
         };
@@ -1382,7 +3745,14 @@ export class Deployments {
         try {
             return await connectWithShell('/bin/bash');
         }
-        catch {
+        catch (error) {
+            if (options.signal?.aborted)
+                throw error;
+            const detail = error instanceof APIError ? error.detail : error instanceof Error ? error.message : '';
+            const bashUnavailable = /(\/bin\/bash|\bbash\b)/i.test(detail)
+                && /(not found|no such file|missing|unavailable|unsupported)/i.test(detail);
+            if (!bashUnavailable)
+                throw error;
             return connectWithShell('/bin/sh');
         }
     }