@hypercli.com/sdk 2026.6.21 → 2026.7.31

package/dist/agents.js

@@ -6,17 +6,404 @@ 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';
 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';
-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 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_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_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_CODING_AGENT_SYNC_ROOT = '/home/node';
+export const DEFAULT_CODING_AGENT_IMAGES = {
+    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_BUZZ_CODING_AGENT_IMAGES = {
+    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(['opencode', 'codex', 'claude-code', 'goose', 'kimi-code']);
+const BUZZ_RUNTIME_COMMANDS = {
+    opencode: {
+        command: '/usr/local/bin/opencode',
+        args: ['acp'],
+        mcpCommand: '/usr/local/bin/buzz-dev-mcp',
+    },
+    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_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',
+    OPENCLAW_MEMORY_SEARCH_SYNC_ON_SEARCH: '0',
+    OPENCLAW_MEMORY_SEARCH_SYNC_WATCH: '0',
+    OPENCLAW_MEMORY_SEARCH_SYNC_WATCH_DEBOUNCE_MS: '30000',
+    OPENCLAW_MEMORY_SEARCH_SYNC_INTERVAL_MINUTES: '0',
+};
+export const OPENCLAW_WORKSPACES_SYNC_ENV_DEFAULTS = {
+    HYPER_WORKSPACES_BOOT_SYNC: '1',
+    HYPER_WORKSPACES_DIR: '/home/node/workspaces',
+    HYPER_WORKSPACES_SYNC_READY_ONLY: '1',
+};
+const LAUNCH_CONFIG_KEYS = new Set([
+    'image',
+    'env',
+    'routes',
+    'ports',
+    'command',
+    'entrypoint',
+    'sync_root',
+    'sync_enabled',
+    'sync_uid',
+    'sync_gid',
+    'registry_url',
+    'registry_auth',
+    'restart',
+]);
 const DEFAULT_OPENCLAW_SYNC_ROOT = '/home/node';
-export const AGENT_FILE_MAX_BYTES = 50 * 1024 * 1024;
+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 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_PRIVATE_KEY: buzz.privateKeyNsec,
+        NOSTR_PRIVATE_KEY: buzz.privateKeyNsec,
+        BUZZ_RELAY_URL: buzz.relayUrl,
+        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 (buzz.rustLog)
+        env.RUST_LOG = buzz.rustLog;
+    const optional = {
+        BUZZ_AUTH_TAG: buzz.authTag,
+        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;
+    }
+    return env;
+}
+/** 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);
+}
+/** 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),
+        });
+    }
+}
 function parseDate(value) {
     if (typeof value !== 'string' || !value)
         return null;
@@ -43,6 +430,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;
@@ -50,6 +439,133 @@ 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 portsHaveDesktop(ports) {
+    return Array.isArray(ports) && ports.some((port) => isPlainRecord(port) && Number(port.port) === 3000);
+}
+export function launchConfigHasDesktop(launchConfig) {
+    if (!isPlainRecord(launchConfig))
+        return false;
+    if (isTruthyEnv(getLaunchConfigValue(launchConfig, 'env.OPENCLAW_DESKTOP_ENABLED')))
+        return true;
+    if (routesHaveDesktop(getLaunchConfigValue(launchConfig, 'routes')))
+        return true;
+    return portsHaveDesktop(getLaunchConfigValue(launchConfig, 'ports'));
+}
+export function agentConfigHasDesktop(source) {
+    if (!source)
+        return false;
+    return (launchConfigHasDesktop(source.launchConfig ?? source.launch_config) ||
+        routesHaveDesktop(source.routes) ||
+        portsHaveDesktop(source.ports));
+}
+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;
+    if (launchConfigHasDesktop(launchConfig)) {
+        return true;
+    }
+    const image = String(launchConfig.image ?? '');
+    return image.includes('hypercli-openclaw:pro') || image.endsWith('-pro');
+}
 function isDirectoryListingPayload(value) {
     if (!value || typeof value !== 'object')
         return false;
@@ -141,12 +657,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);
@@ -169,6 +751,16 @@ function agentStateFromDict(data) {
         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,
@@ -210,15 +802,18 @@ 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;
+    let gatewayToken = '';
+    if (options.injectGatewayToken !== false) {
+        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 prepared = {};
@@ -248,6 +843,8 @@ export function buildAgentConfig(config = {}, options = {}) {
         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;
     return { config: prepared, gatewayToken };
 }
 function defaultOpenClawImage(image) {
@@ -255,6 +852,208 @@ function defaultOpenClawImage(image) {
         return image;
     return DEFAULT_OPENCLAW_IMAGE;
 }
+function defaultOpenClawProImage(image) {
+    if (image !== undefined && image !== null)
+        return image;
+    return DEFAULT_OPENCLAW_PRO_IMAGE;
+}
+function productApiBaseFromAgentsApiBase(apiBase) {
+    const normalized = apiBase.replace(/\/+$/, '');
+    const agentsSuffix = '/agents';
+    return normalized.endsWith(agentsSuffix) ? normalized.slice(0, -agentsSuffix.length) : normalized;
+}
+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) {
@@ -264,7 +1063,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,
@@ -273,6 +1072,61 @@ export function buildOpenClawRoutes(options = {}) {
     }
     return routes;
 }
+function envBool(value) {
+    return value ? '1' : '0';
+}
+function envNonNegativeInteger(name, value) {
+    const integer = Number(value);
+    if (!Number.isInteger(integer) || integer < 0) {
+        throw new Error(`${name} must be a non-negative integer`);
+    }
+    return String(integer);
+}
+export function buildOpenClawMemoryIndexEnv(memoryIndex = null) {
+    if (!memoryIndex)
+        return {};
+    const env = { ...OPENCLAW_MEMORY_SEARCH_ENV_DEFAULTS };
+    if (memoryIndex.enabled !== undefined && memoryIndex.enabled !== null) {
+        env.OPENCLAW_MEMORY_SEARCH_ENABLED = envBool(memoryIndex.enabled);
+    }
+    if (memoryIndex.onSessionStart !== undefined && memoryIndex.onSessionStart !== null) {
+        env.OPENCLAW_MEMORY_SEARCH_SYNC_ON_SESSION_START = envBool(memoryIndex.onSessionStart);
+    }
+    if (memoryIndex.onSearch !== undefined && memoryIndex.onSearch !== null) {
+        env.OPENCLAW_MEMORY_SEARCH_SYNC_ON_SEARCH = envBool(memoryIndex.onSearch);
+    }
+    if (memoryIndex.watch !== undefined && memoryIndex.watch !== null) {
+        env.OPENCLAW_MEMORY_SEARCH_SYNC_WATCH = envBool(memoryIndex.watch);
+    }
+    if (memoryIndex.watchDebounceMs !== undefined && memoryIndex.watchDebounceMs !== null) {
+        env.OPENCLAW_MEMORY_SEARCH_SYNC_WATCH_DEBOUNCE_MS = envNonNegativeInteger('watchDebounceMs', memoryIndex.watchDebounceMs);
+    }
+    if (memoryIndex.intervalMinutes !== undefined && memoryIndex.intervalMinutes !== null) {
+        env.OPENCLAW_MEMORY_SEARCH_SYNC_INTERVAL_MINUTES = envNonNegativeInteger('intervalMinutes', memoryIndex.intervalMinutes);
+    }
+    return env;
+}
+export function 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.outputDir) {
+        env.HYPER_WORKSPACES_DIR = options.outputDir;
+    }
+    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');
 }
@@ -287,6 +1141,16 @@ export class Agent {
     podName;
     state;
     name;
+    handle;
+    displayName;
+    avatarUrl;
+    displayIdentity;
+    runtime;
+    managed;
+    isLaunchable;
+    gatewayId;
+    runtimeKeyAlias;
+    relayKey;
     cpu;
     memory;
     hostname;
@@ -313,6 +1177,16 @@ export class Agent {
         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;
@@ -360,6 +1234,11 @@ 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');
     }
@@ -369,6 +1248,13 @@ export class Agent {
     get isRunning() {
         return this.state.toLowerCase() === 'running';
     }
+    get hasDesktop() {
+        return agentConfigHasDesktop({
+            launchConfig: this.launchConfig,
+            routes: this.routes,
+            ports: this.ports,
+        });
+    }
     requireDeployments() {
         if (!this._deployments) {
             throw new Error('Agent is not bound to a Deployments client');
@@ -407,23 +1293,45 @@ export class Agent {
     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);
@@ -431,8 +1339,346 @@ 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 = {
+    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;
+    output = '';
+    verificationUrl = null;
+    userCode = null;
+    interactiveRequired = false;
+    exitCode = null;
+    marker;
+    completion;
+    ready;
+    complete;
+    markReady;
+    constructor(authClient, socket, command) {
+        this.authClient = authClient;
+        this.socket = socket;
+        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) {
+        const socket = await authClient.agent.shellConnect();
+        const session = new RuntimeLoginSession(authClient, socket, command);
+        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.output += stripTerminalCodes(chunk);
+        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"'<>]+/)?.[0] ?? null;
+        this.userCode ??= this.output.match(/(?:user|device|verification|one[- ]time)?\s*code\s*(?:is|:)?\s*([A-Z0-9][A-Z0-9-]{3,})/i)?.[1] ?? null;
+        this.interactiveRequired ||= /\b(select|choose)\b.*\b(provider|login method)\b/i.test(this.output);
+        if (this.verificationUrl || this.userCode || 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);
+                }),
+            ]);
+        }
+        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() {
+        if (this.socket.readyState === WebSocket.OPEN)
+            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);
+        return RuntimeLoginSession.start(this, command, options.challengeTimeoutMs);
+    }
+    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 {
+    get auth() {
+        return new RuntimeAuthClient(this);
+    }
+}
+export class OpenCodeAgent extends CodingAgent {
+    static fromDict(data) {
+        return new OpenCodeAgent(agentStateFromDict(data));
+    }
+}
+export class CodexAgent extends CodingAgent {
+    static fromDict(data) {
+        return new CodexAgent(agentStateFromDict(data));
+    }
+}
+export class ClaudeCodeAgent extends CodingAgent {
+    static fromDict(data) {
+        return new ClaudeCodeAgent(agentStateFromDict(data));
+    }
+}
+export class GooseAgent extends CodingAgent {
+    static fromDict(data) {
+        return new GooseAgent(agentStateFromDict(data));
+    }
+}
+export class KimiCodeAgent extends CodingAgent {
+    static fromDict(data) {
+        return new KimiCodeAgent(agentStateFromDict(data));
     }
 }
 export class OpenClawAgent extends Agent {
@@ -446,7 +1692,7 @@ export class OpenClawAgent extends Agent {
     static fromDict(data) {
         return new OpenClawAgent({
             ...agentStateFromDict(data),
-            gatewayUrl: null,
+            gatewayUrl: this.gatewayUrlFromHostname(data.hostname),
             gatewayToken: data.gateway_token ?? null,
         });
     }
@@ -475,6 +1721,15 @@ export class OpenClawAgent extends Agent {
      * token from `OPENCLAW_GATEWAY_TOKEN` in the agent env route.
      */
     async waitForGatewayContext(options = {}) {
+        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();
         if (this.gatewayToken && this.gatewayUrl) {
             return {
                 agent_id: this.id,
@@ -487,29 +1742,98 @@ export class OpenClawAgent extends Agent {
         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;
-                    this.gatewayUrl = gatewayUrl;
-                    return { agent_id: this.id, gateway_token: gatewayToken, hostname };
+        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),
+                };
+                const requests = [];
+                if (!this.gatewayUrl) {
+                    requests.push(deployments.get(this.id, requestOptions).then((refreshed) => {
+                        const gatewayUrl = OpenClawAgent.gatewayUrlFromHostname(refreshed.hostname);
+                        if (gatewayUrl)
+                            this.gatewayUrl = gatewayUrl;
+                    }));
                 }
-                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');
+                if (!this.gatewayToken) {
+                    requests.push(deployments.env(this.id, requestOptions).then((envData) => {
+                        const gatewayToken = envData.env?.OPENCLAW_GATEWAY_TOKEN?.trim() || null;
+                        if (gatewayToken)
+                            this.gatewayToken = gatewayToken;
+                    }));
+                }
+                const results = await runWithAbort(Promise.allSettled(requests));
+                const rejected = results.find((result) => result.status === 'rejected');
+                if (this.gatewayToken && this.gatewayUrl) {
+                    return {
+                        agent_id: this.id,
+                        hostname: this.currentGatewayHostname(),
+                        gateway_token: this.gatewayToken,
+                    };
+                }
+                lastError = rejected?.reason ?? new Error('missing gateway context');
+                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() {
@@ -541,6 +1865,7 @@ export class OpenClawAgent extends Agent {
             onHello: options.onHello,
             onClose: options.onClose,
             onGap: options.onGap,
+            onProtocolError: options.onProtocolError,
             onPairing: options.onPairing,
         });
     }
@@ -552,6 +1877,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 {
@@ -603,6 +1969,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 {
@@ -630,6 +2054,15 @@ 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 *chatSend(message, sessionKey, options = {}) {
         const client = await this.connect(options);
         try {
@@ -644,7 +2077,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();
@@ -679,12 +2130,49 @@ export class OpenClawAgent extends Agent {
             return await client.webLoginWait({
                 timeoutMs: options.timeoutMs,
                 accountId: options.accountId,
+                currentQrDataUrl: options.currentQrDataUrl,
             });
         }
         finally {
             client.close();
         }
     }
+    async integrationsAuthStart(params, options = {}) {
+        const client = await this.connect(options);
+        try {
+            return await client.integrationsAuthStart(params);
+        }
+        finally {
+            client.close();
+        }
+    }
+    async integrationsAuthStatus(params, options = {}) {
+        const client = await this.connect(options);
+        try {
+            return await client.integrationsAuthStatus(params);
+        }
+        finally {
+            client.close();
+        }
+    }
+    async integrationsStatus(params = {}, options = {}) {
+        const client = await this.connect(options);
+        try {
+            return await client.integrationsStatus(params);
+        }
+        finally {
+            client.close();
+        }
+    }
+    async integrationsDisconnect(params, options = {}) {
+        const client = await this.connect(options);
+        try {
+            return await client.integrationsDisconnect(params);
+        }
+        finally {
+            client.close();
+        }
+    }
     async workspaceFiles(options = {}) {
         const client = await this.connect(options);
         try {
@@ -743,7 +2231,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();
@@ -886,6 +2374,42 @@ 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: this.gatewayUrlFromHostname(data.hostname),
+            gatewayToken: data.gateway_token ?? null,
+        });
+    }
 }
 export class Deployments {
     http;
@@ -893,12 +2417,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;
@@ -907,13 +2432,79 @@ export class Deployments {
         return this.apiBase;
     }
     hydrateAgent(data) {
-        const agent = isOpenClawHydrationData(data)
-            ? OpenClawAgent.fromDict(data)
-            : Agent.fromDict(data);
+        let agent;
+        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)) {
+            agent = OpenClawAgent.fromDict(data);
+        }
+        else {
+            agent = Agent.fromDict(data);
+        }
         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.podName, agent.hostname];
+            if (values.some((value) => String(value || '') === raw)) {
+                matches.push(agent);
+                continue;
+            }
+            if (values.some((value) => String(value || '').startsWith(raw))) {
+                matches.push(agent);
+            }
+        }
+        if (matches.length === 0) {
+            throw new Error(`Agent not found: ${raw}`);
+        }
+        if (matches.length > 1) {
+            throw new Error(`Agent reference is ambiguous: ${raw} (${matches.slice(0, 5).map((agent) => agent.id).join(', ')})`);
+        }
+        return this.getById(matches[0].id, requestOptions);
+    }
+    async resolveAgentId(agentIdOrName, requestOptions = {}) {
+        const raw = String(agentIdOrName || '').trim();
+        if (!raw) {
+            throw new Error('agentIdOrName is required');
+        }
+        if (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 ?? {});
@@ -942,18 +2533,25 @@ export class Deployments {
         return response;
     }
     async create(options = {}) {
-        const { config, gatewayToken } = buildAgentConfig(options.config ?? {}, options);
+        const { config, gatewayToken } = 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];
+        if (options.runtime)
+            body.runtime = options.runtime;
         const data = await this.agentHttp.post(DEPLOYMENTS_API_PREFIX, body);
         const agent = this.hydrateAgent(data);
         if (agent instanceof OpenClawAgent) {
@@ -965,8 +2563,13 @@ export class Deployments {
         return agent;
     }
     async createOpenClaw(options = {}) {
-        const effectiveOptions = { ...options };
-        effectiveOptions.env = { ...(options.env ?? {}) };
+        const effectiveOptions = { ...options, runtime: options.runtime ?? 'openclaw' };
+        effectiveOptions.env = {
+            HYPER_API_BASE: productApiBaseFromAgentsApiBase(this.apiBase),
+            ...buildOpenClawWorkspacesSyncEnv(options.workspacesSync ?? null),
+            ...buildOpenClawMemoryIndexEnv(options.memoryIndex),
+            ...(options.env ?? {}),
+        };
         if (options.routes === undefined) {
             effectiveOptions.routes = buildOpenClawRoutes(options.openClawRoutes ?? {});
         }
@@ -977,42 +2580,229 @@ export class Deployments {
             effectiveOptions.syncEnabled = true;
         return this.create(effectiveOptions);
     }
+    async createOpenClawPro(options = {}) {
+        return this.createOpenClaw({
+            ...options,
+            runtime: 'openclaw-pro',
+            env: { OPENCLAW_DESKTOP_ENABLED: '1', ...(options.env ?? {}) },
+            image: defaultOpenClawProImage(options.image),
+            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 = {
+            HYPER_API_BASE: productApiBaseFromAgentsApiBase(this.apiBase),
+            ...buildOpenClawWorkspacesSyncEnv(options.workspacesSync ?? null),
+            ...(options.env ?? {}),
+        };
+        if (options.buzz) {
+            for (const key of BUZZ_RESERVED_ENV_KEYS)
+                delete effectiveEnv[key];
+            Object.assign(effectiveEnv, buildBuzzLaunchEnv(runtime, options.buzz, options.name));
+        }
+        if (buzzLaunch) {
+            effectiveEnv.RUST_LOG ??= DEFAULT_BUZZ_RUST_LOG;
+        }
+        const effectiveOptions = {
+            ...options,
+            runtime,
+            size: buzzLaunch ? 'large' : options.size,
+            injectGatewayToken: false,
+            env: effectiveEnv,
+            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,
+            syncEnabled: options.syncEnabled ?? true,
+            syncUid: options.syncUid ?? 1000,
+            syncGid: options.syncGid ?? 1000,
+            restart: buzzLaunch
+                ? options.restart ?? options.buzz?.restart ?? false
+                : options.restart,
+        };
+        return await this.create(effectiveOptions);
+    }
+    async createOpenCode(options = {}) {
+        return await this.createCodingAgent('opencode', 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);
+    async list(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 items = Array.isArray(data) ? data : data.items ?? [];
         return items.map((item) => this.hydrateAgent(item));
     }
-    async get(agentId) {
-        const data = await this.agentHttp.get(`${DEPLOYMENTS_API_PREFIX}/${agentId}`);
+    async get(agentIdOrName, requestOptions = {}) {
+        const raw = String(agentIdOrName || '').trim();
+        if (!raw)
+            throw new Error('agentIdOrName is required');
+        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 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 waitRunning(agentIdOrName, timeoutMs = 300_000, pollIntervalMs = 5_000) {
+        const agentId = await this.resolveAgentId(agentIdOrName);
         const deadline = Date.now() + timeoutMs;
         let lastState = '';
+        let lastAgent = null;
+        const diagnostics = (agent) => {
+            if (!agent)
+                return '';
+            const details = [];
+            if (agent.lastError)
+                details.push(`lastError=${JSON.stringify(agent.lastError)}`);
+            if (agent.updatedAt && !Number.isNaN(agent.updatedAt.getTime())) {
+                details.push(`updatedAt=${agent.updatedAt.toISOString()}`);
+            }
+            return details.length ? `, ${details.join(', ')}` : '';
+        };
         while (Date.now() < deadline) {
             const agent = await this.get(agentId);
+            lastAgent = agent;
             lastState = String(agent.state || '');
             if (lastState.toLowerCase() === 'running') {
                 return agent;
             }
-            if (lastState.toLowerCase() === 'failed' || lastState.toLowerCase() === 'error') {
-                throw new Error(`Agent entered ${lastState} while waiting for RUNNING`);
+            if (['failed', 'error', 'restore_failed', 'sync_failed'].includes(lastState.toLowerCase())) {
+                throw new Error(`Agent entered ${lastState} while waiting for RUNNING${diagnostics(agent)}`);
             }
             await sleep(pollIntervalMs);
         }
-        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 RUNNING (last=${lastState || 'unknown'}${diagnostics(lastAgent)})`);
     }
-    async start(agentId, options = {}) {
+    async start(agentIdOrName, options = {}) {
         const { config, gatewayToken } = buildAgentConfig(options.config ?? {}, options);
         const body = { ...config };
         if (options.dryRun)
             body.dry_run = true;
+        const agentId = await this.resolveAgentId(agentIdOrName);
         const data = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/start`, body);
         const agent = this.hydrateAgent(data);
         if (agent instanceof OpenClawAgent) {
@@ -1023,9 +2813,14 @@ export class Deployments {
         agent.entrypoint = [...(config.entrypoint ?? [])];
         return agent;
     }
-    async startOpenClaw(agentId, options = {}) {
+    async startOpenClaw(agentIdOrName, options = {}) {
         const effectiveOptions = { ...options };
-        effectiveOptions.env = { ...(options.env ?? {}) };
+        effectiveOptions.env = {
+            HYPER_API_BASE: productApiBaseFromAgentsApiBase(this.apiBase),
+            ...buildOpenClawWorkspacesSyncEnv(options.workspacesSync ?? null),
+            ...buildOpenClawMemoryIndexEnv(options.memoryIndex),
+            ...(options.env ?? {}),
+        };
         if (options.routes === undefined) {
             effectiveOptions.routes = buildOpenClawRoutes(options.openClawRoutes ?? {});
         }
@@ -1034,38 +2829,71 @@ export class Deployments {
             effectiveOptions.syncRoot = DEFAULT_OPENCLAW_SYNC_ROOT;
         if (effectiveOptions.syncEnabled === undefined)
             effectiveOptions.syncEnabled = true;
-        return this.start(agentId, effectiveOptions);
+        return this.start(agentIdOrName, effectiveOptions);
+    }
+    async startOpenClawPro(agentIdOrName, options = {}) {
+        return this.startOpenClaw(agentIdOrName, {
+            ...options,
+            env: { OPENCLAW_DESKTOP_ENABLED: '1', ...(options.env ?? {}) },
+            image: defaultOpenClawProImage(options.image),
+            openClawRoutes: { includeDesktop: true, ...(options.openClawRoutes ?? {}) },
+        });
     }
-    async update(agentId, 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;
+        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) {
+    /**
+     * 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);
         const data = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/stop`);
         return this.hydrateAgent(data);
     }
-    async delete(agentId) {
+    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 = {}) {
@@ -1088,14 +2916,19 @@ 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 exec(target, command, options = {}) {
-        const agentId = this.agentIdFor(target);
+        const agentId = await this.agentIdFor(target);
         const payload = {
             command,
             timeout: options.timeout ?? 30,
@@ -1121,20 +2954,20 @@ export class Deployments {
         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 {
@@ -1149,19 +2982,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,
@@ -1172,12 +3010,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) {
@@ -1196,7 +3038,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;
@@ -1218,32 +3061,92 @@ 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);
+                };
             });
         };
         if (shell) {
@@ -1252,7 +3155,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');
         }
     }