@hypercli.com/sdk 2026.7.31 → 2026.8.11

package/dist/agents.js

@@ -2,11 +2,15 @@
  * HyperClaw agents API - typed agent lifecycle, files, exec, and OpenClaw access.
  */
 import { randomFillSync } from 'node:crypto';
+import NodeWebSocket from 'ws';
+import { agentSlotFromDict, } from './agent-slots.js';
+export { agentSlotFromDict, } from './agent-slots.js';
 import { getAgentsApiBaseUrl, getConfigValue } from './config.js';
 import { APIError } from './errors.js';
 import { HTTPClient } from './http.js';
 import { GatewayClient, } from './openclaw/gateway.js';
 import { normalizeSlackRelayBaseUrl } from './channels.js';
+import { HermesApiClient } from './hermes/gateway.js';
 const AGENTS_API_BASE = 'https://api.hypercli.com/agents';
 const DEV_AGENTS_API_BASE = 'https://api.dev.hypercli.com/agents';
 const DEPLOYMENTS_API_PREFIX = '/deployments';
@@ -14,37 +18,68 @@ 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:pro-latest';
 export const DEFAULT_OPENCLAW_PRO_IMAGE = 'ghcr.io/hypercli/hypercli-openclaw:pro-latest';
+export const DEFAULT_HERMES_AGENT_IMAGE = 'ghcr.io/hypercli/hypercli-hermes-agent:latest';
 export const DEFAULT_OPENCODE_IMAGE = 'ghcr.io/hypercli/hypercli-opencode:latest';
 export const DEFAULT_CODEX_IMAGE = 'ghcr.io/hypercli/hypercli-codex:latest';
 export const DEFAULT_CLAUDE_CODE_IMAGE = 'ghcr.io/hypercli/hypercli-claude-code:latest';
 export const DEFAULT_GOOSE_IMAGE = 'ghcr.io/hypercli/hypercli-goose:latest';
 export const DEFAULT_KIMI_CODE_IMAGE = 'ghcr.io/hypercli/hypercli-kimi-code:latest';
+export const DEFAULT_BUZZ_AGENT_IMAGE = 'ghcr.io/hypercli/hypercli-buzz-agent:latest';
 export const DEFAULT_BUZZ_OPENCODE_IMAGE = 'ghcr.io/hypercli/hypercli-buzz-opencode:latest';
 export const DEFAULT_BUZZ_CODEX_IMAGE = 'ghcr.io/hypercli/hypercli-buzz-codex:latest';
 export const DEFAULT_BUZZ_CLAUDE_CODE_IMAGE = 'ghcr.io/hypercli/hypercli-buzz-claude:latest';
 export const DEFAULT_BUZZ_GOOSE_IMAGE = 'ghcr.io/hypercli/hypercli-buzz-goose:latest';
 export const DEFAULT_BUZZ_KIMI_CODE_IMAGE = 'ghcr.io/hypercli/hypercli-buzz-kimi-code:latest';
+export const DEFAULT_AGENT_RUNTIME_SCOPES = Object.freeze([
+    'agents:none',
+    'files:*',
+    'flows:*',
+    'models:*',
+    'voice:*',
+    'web:*',
+    'workspaces:*',
+]);
 export const DEFAULT_CODING_AGENT_SYNC_ROOT = '/home/node';
 export const DEFAULT_CODING_AGENT_IMAGES = {
+    'buzz-agent': DEFAULT_BUZZ_AGENT_IMAGE,
     opencode: DEFAULT_OPENCODE_IMAGE,
     codex: DEFAULT_CODEX_IMAGE,
     'claude-code': DEFAULT_CLAUDE_CODE_IMAGE,
     goose: DEFAULT_GOOSE_IMAGE,
     'kimi-code': DEFAULT_KIMI_CODE_IMAGE,
 };
+export const DEFAULT_CODING_AGENT_SYNC_INCLUDES = {
+    'buzz-agent': [],
+    opencode: [
+        '.config/opencode',
+        '.local/share/opencode',
+        '.local/state/opencode',
+        '.cache/opencode',
+    ],
+    codex: ['.codex'],
+    'claude-code': ['.claude', '.claude.json'],
+    goose: ['.goose'],
+    'kimi-code': ['.kimi-code'],
+};
 export const DEFAULT_BUZZ_CODING_AGENT_IMAGES = {
+    'buzz-agent': DEFAULT_BUZZ_AGENT_IMAGE,
     opencode: DEFAULT_BUZZ_OPENCODE_IMAGE,
     codex: DEFAULT_BUZZ_CODEX_IMAGE,
     'claude-code': DEFAULT_BUZZ_CLAUDE_CODE_IMAGE,
     goose: DEFAULT_BUZZ_GOOSE_IMAGE,
     'kimi-code': DEFAULT_BUZZ_KIMI_CODE_IMAGE,
 };
-const CODING_AGENT_RUNTIMES = new Set(['opencode', 'codex', 'claude-code', 'goose', 'kimi-code']);
+const CODING_AGENT_RUNTIMES = new Set(['buzz-agent', 'opencode', 'codex', 'claude-code', 'goose', 'kimi-code']);
 const BUZZ_RUNTIME_COMMANDS = {
+    'buzz-agent': {
+        command: '/usr/local/bin/buzz-agent',
+        args: [],
+        mcpCommand: '/usr/local/bin/buzz-dev-mcp',
+    },
     opencode: {
         command: '/usr/local/bin/opencode',
         args: ['acp'],
-        mcpCommand: '/usr/local/bin/buzz-dev-mcp',
+        mcpCommand: '',
     },
     codex: {
         command: '/usr/local/bin/codex-acp',
@@ -82,6 +117,10 @@ const BUZZ_RESERVED_ENV_KEYS = new Set([
     'BUZZ_ACP_MCP_COMMAND',
     'BUZZ_ACP_LAZY_POOL',
     'BUZZ_ACP_RELAY_OBSERVER',
+    'BUZZ_ACP_DISPLAY_NAME',
+    'BUZZ_ACP_TEXT_MENTIONS',
+    'BUZZ_ACP_REQUIRE_REPLY',
+    'CLAUDE_CODE_EXECUTABLE',
     'BUZZ_ACP_SESSION_TITLE',
     'BUZZ_ACP_SYSTEM_PROMPT',
     'BUZZ_ACP_MODEL',
@@ -106,28 +145,64 @@ export const OPENCLAW_MEMORY_SEARCH_ENV_DEFAULTS = {
 };
 export const OPENCLAW_WORKSPACES_SYNC_ENV_DEFAULTS = {
     HYPER_WORKSPACES_BOOT_SYNC: '1',
-    HYPER_WORKSPACES_DIR: '/home/node/workspaces',
+    HYPER_WORKSPACES_DIR: '/home/node/shared',
     HYPER_WORKSPACES_SYNC_READY_ONLY: '1',
 };
+const DEFAULT_OPENCLAW_SYNC_EXCLUDE = [
+    'shared/**',
+    '.openclaw/npm/**/node_modules/**',
+    '.openclaw/agents/**/agent/*.sqlite.memory-reindex-*',
+    '.openclaw/agents/**/agent/*.sqlite.reindex-lock.sqlite*',
+    '.openclaw/browser/**/Code Cache/**',
+    '.openclaw/browser/**/GPUCache/**',
+    '.openclaw/browser/**/ShaderCache/**',
+    '.openclaw/browser/**/GrShaderCache/**',
+    '.openclaw/browser/**/optimization_guide_model_store/**',
+];
 const LAUNCH_CONFIG_KEYS = new Set([
     'image',
     'env',
+    'secrets',
     'routes',
-    'ports',
     'command',
     'entrypoint',
     'sync_root',
-    'sync_enabled',
+    'sync_include',
+    'sync_exclude',
     'sync_uid',
     'sync_gid',
     'registry_url',
     'registry_auth',
     'restart',
+    'runtime_scopes',
 ]);
 const DEFAULT_OPENCLAW_SYNC_ROOT = '/home/node';
+export const DEFAULT_HERMES_AGENT_SYNC_ROOT = '/opt/data';
+export const DEFAULT_HERMES_AGENT_SYNC_UID = 10000;
+export const DEFAULT_HERMES_AGENT_SYNC_GID = 10000;
 export const AGENT_FILE_MAX_BYTES = 250 * 1024 * 1024;
 export const AGENT_FILE_TRANSFER_CHUNK_BYTES = 64 * 1024;
 export const AGENT_FILE_OPERATION_TIMEOUT_MS = 300_000;
+function stringifyOpenClawOperationsFailure(reason) {
+    if (reason instanceof Error)
+        return reason.message || reason.name || 'Error';
+    if (typeof reason === 'string')
+        return reason;
+    try {
+        const serialized = JSON.stringify(reason);
+        if (serialized !== undefined)
+            return serialized;
+    }
+    catch {
+        // Fall back to String for non-serializable rejection values.
+    }
+    try {
+        return String(reason);
+    }
+    catch {
+        return 'Unknown error';
+    }
+}
 function shellAbortError() {
     const error = new Error('Shell connection cancelled');
     error.name = 'AbortError';
@@ -185,9 +260,8 @@ function buildBuzzLaunchEnv(runtime, buzz, defaultSessionTitle) {
     }
     const harness = BUZZ_RUNTIME_COMMANDS[runtime];
     const env = {
-        BUZZ_PRIVATE_KEY: buzz.privateKeyNsec,
-        NOSTR_PRIVATE_KEY: buzz.privateKeyNsec,
         BUZZ_RELAY_URL: buzz.relayUrl,
+        BUZZ_MANAGED_AGENT_START_NONCE: randomHexToken(16),
         BUZZ_ACP_AGENT_COMMAND: harness.command,
         BUZZ_ACP_AGENT_ARGS: harness.args.join(','),
         BUZZ_ACP_MCP_COMMAND: harness.mcpCommand,
@@ -197,10 +271,14 @@ function buildBuzzLaunchEnv(runtime, buzz, defaultSessionTitle) {
         BUZZ_ACP_MULTIPLE_EVENT_HANDLING: 'steer',
         BUZZ_ACP_DEDUP: 'queue',
     };
+    if (runtime === 'claude-code') {
+        env.CLAUDE_CODE_EXECUTABLE = '/usr/local/bin/claude';
+    }
     if (buzz.rustLog)
         env.RUST_LOG = buzz.rustLog;
     const optional = {
         BUZZ_AUTH_TAG: buzz.authTag,
+        BUZZ_ACP_DISPLAY_NAME: buzz.displayName,
         BUZZ_ACP_SESSION_TITLE: buzz.sessionTitle || defaultSessionTitle,
         BUZZ_ACP_SYSTEM_PROMPT: buzz.systemPrompt,
         BUZZ_ACP_MODEL: buzz.model,
@@ -219,8 +297,20 @@ function buildBuzzLaunchEnv(runtime, buzz, defaultSessionTitle) {
         if (value)
             env[key] = value;
     }
+    if (buzz.textMentions)
+        env.BUZZ_ACP_TEXT_MENTIONS = 'true';
+    if (buzz.requireReply)
+        env.BUZZ_ACP_REQUIRE_REPLY = 'true';
     return env;
 }
+function buildBuzzLaunchSecrets(buzz) {
+    if (!buzz.privateKeyNsec.trim())
+        throw new Error('buzz.privateKeyNsec is required');
+    return {
+        BUZZ_PRIVATE_KEY: buzz.privateKeyNsec,
+        NOSTR_PRIVATE_KEY: buzz.privateKeyNsec,
+    };
+}
 /** The agent's sync root and workspace, owned by the SDK so paths are unambiguous. */
 export const OPENCLAW_SYNC_ROOT = '/home/node';
 export const OPENCLAW_WORKSPACE_PREFIX = '.openclaw/workspace';
@@ -287,6 +377,16 @@ function isDirectAgentIdRef(value) {
     const raw = value.trim();
     return isUuidRef(raw) || /^[0-9a-f]{6,}$/i.test(raw) || /^(agent|external)[-_:]/i.test(raw);
 }
+function isSelfAgentRef(value) {
+    return value.trim().toLowerCase() === 'self';
+}
+function agentRoutesStateFromData(data) {
+    return {
+        agentId: String(data.agent_id ?? ''),
+        routes: structuredClone(data.routes ?? {}),
+        routeStatuses: structuredClone(data.route_statuses ?? {}),
+    };
+}
 /** Strip a workspace prefix so gateway (name-addressed) sees the bare name. */
 function resolveGatewayFileName(path) {
     if (path.startsWith('/')) {
@@ -404,6 +504,39 @@ export class AgentFiles {
         });
     }
 }
+/** Canonical states understood by this SDK. AgentState remains forward-open. */
+export const CANONICAL_AGENT_STATES = [
+    'CREATING',
+    'STARTING',
+    'RESTORING',
+    'RUNNING',
+    'STOPPING',
+    'STOPPED',
+    'ARCHIVING',
+    'ARCHIVED',
+    'FAILED',
+    'DELETED',
+];
+export const AGENT_TRANSITIONAL_STATES = new Set([
+    'CREATING',
+    'STARTING',
+    'RESTORING',
+    'STOPPING',
+    'ARCHIVING',
+]);
+export const AGENT_RUNTIME_INACTIVE_STATES = new Set([
+    'STOPPED',
+    'ARCHIVING',
+    'ARCHIVED',
+    'FAILED',
+    'DELETED',
+]);
+export function isAgentTransitionalState(state) {
+    return AGENT_TRANSITIONAL_STATES.has(state.toUpperCase());
+}
+export function isAgentRuntimeInactiveState(state) {
+    return AGENT_RUNTIME_INACTIVE_STATES.has(state.toUpperCase());
+}
 function parseDate(value) {
     if (typeof value !== 'string' || !value)
         return null;
@@ -510,24 +643,18 @@ export function routesHaveDesktop(routes) {
         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'));
+    return routesHaveDesktop(getLaunchConfigValue(launchConfig, 'routes'));
 }
 export function agentConfigHasDesktop(source) {
     if (!source)
         return false;
     return (launchConfigHasDesktop(source.launchConfig ?? source.launch_config) ||
-        routesHaveDesktop(source.routes) ||
-        portsHaveDesktop(source.ports));
+        routesHaveDesktop(source.routes));
 }
 function browserDesktopRedirectPath(options = {}) {
     const redirect = (options.redirect ?? 'vnc.html').trim() || 'vnc.html';
@@ -744,11 +871,13 @@ function execResultFromDict(data) {
     };
 }
 function agentStateFromDict(data) {
+    const launchConfig = isPlainRecord(data.launch_config) ? structuredClone(data.launch_config) : null;
+    if (launchConfig) {
+        delete launchConfig.secrets;
+    }
     return {
         id: data.id ?? '',
         userId: data.user_id ?? '',
-        podId: data.pod_id ?? '',
-        podName: data.pod_name ?? '',
         state: data.state ?? 'unknown',
         name: data.name ?? null,
         handle: data.handle ?? null,
@@ -769,15 +898,18 @@ function agentStateFromDict(data) {
         jwtExpiresAt: parseDate(data.jwt_expires_at),
         startedAt: parseDate(data.started_at),
         stoppedAt: parseDate(data.stopped_at),
-        lastError: data.last_error ?? null,
+        archivedAt: parseDate(data.archived_at),
+        clusterId: data.cluster_id ?? null,
+        launchEpoch: data.launch_epoch ?? 0,
         createdAt: parseDate(data.created_at),
         updatedAt: parseDate(data.updated_at),
-        launchConfig: data.launch_config ?? null,
+        launchConfig,
         meta: data.meta?.ui ? { ui: structuredClone(data.meta.ui) } : null,
-        routes: data.routes ?? {},
-        command: data.command ?? [],
-        entrypoint: data.entrypoint ?? [],
-        ports: data.ports ?? [],
+        routes: data.routes ?? (isPlainRecord(launchConfig?.routes)
+            ? launchConfig.routes
+            : {}),
+        command: data.command ?? (Array.isArray(launchConfig?.command) ? launchConfig.command : []),
+        entrypoint: data.entrypoint ?? (Array.isArray(launchConfig?.entrypoint) ? launchConfig.entrypoint : []),
         dryRun: Boolean(data.dry_run),
     };
 }
@@ -802,13 +934,20 @@ export function buildAgentConfig(config = {}, options = {}) {
         preparedConfig.agents = agentsConfig;
     }
     const env = { ...(options.env ?? {}) };
-    let gatewayToken = '';
+    const secrets = { ...(options.secrets ?? {}) };
+    if (Object.prototype.hasOwnProperty.call(env, 'OPENCLAW_GATEWAY_TOKEN')) {
+        throw new Error('OPENCLAW_GATEWAY_TOKEN is a Secret; pass it through secrets or gatewayToken, not env');
+    }
+    let gatewayToken = null;
     if (options.injectGatewayToken !== false) {
-        gatewayToken = options.gatewayToken?.trim() || env.OPENCLAW_GATEWAY_TOKEN?.trim() || '';
-        if (!gatewayToken) {
-            gatewayToken = randomHexToken(32);
-        }
-        env.OPENCLAW_GATEWAY_TOKEN = gatewayToken;
+        const explicitGatewayToken = options.gatewayToken?.trim() || null;
+        const secretGatewayToken = secrets.OPENCLAW_GATEWAY_TOKEN?.trim() || null;
+        if (explicitGatewayToken && secretGatewayToken && explicitGatewayToken !== secretGatewayToken) {
+            throw new Error('gatewayToken conflicts with secrets.OPENCLAW_GATEWAY_TOKEN');
+        }
+        gatewayToken = explicitGatewayToken ?? secretGatewayToken;
+        if (gatewayToken)
+            secrets.OPENCLAW_GATEWAY_TOKEN = gatewayToken;
         if (options.controlUiOriginLock !== false && !env.OPENCLAW_CONTROL_UI_ALLOWED_ORIGIN?.trim()) {
             const controlUiOrigin = defaultControlUiAllowedOrigin();
             if (controlUiOrigin) {
@@ -816,13 +955,27 @@ export function buildAgentConfig(config = {}, options = {}) {
             }
         }
     }
+    const collidingKeys = Object.keys(env).filter((key) => Object.prototype.hasOwnProperty.call(secrets, key));
+    if (collidingKeys.length > 0) {
+        throw new Error(`Launch keys cannot appear in both env and secrets: ${collidingKeys.join(', ')}`);
+    }
+    const normalizeSyncOwner = (value, field) => {
+        if (value === undefined || value === null)
+            return undefined;
+        if (!Number.isSafeInteger(value) || value < 0 || value > 4_294_967_294) {
+            throw new Error(`${field} must be an integer between 0 and 4294967294`);
+        }
+        return value;
+    };
+    const syncUid = normalizeSyncOwner(options.syncUid, 'syncUid');
+    const syncGid = normalizeSyncOwner(options.syncGid, 'syncGid');
     const prepared = {};
     if (Object.keys(preparedConfig).length > 0)
         prepared.config = preparedConfig;
     if (Object.keys(env).length > 0)
         prepared.env = env;
-    if (options.ports !== undefined && options.ports !== null)
-        prepared.ports = options.ports;
+    if (Object.keys(secrets).length > 0)
+        prepared.secrets = secrets;
     if (options.routes !== undefined && options.routes !== null)
         prepared.routes = options.routes;
     if (options.command !== undefined && options.command !== null)
@@ -833,18 +986,25 @@ export function buildAgentConfig(config = {}, options = {}) {
         prepared.image = options.image;
     if (options.syncRoot !== undefined && options.syncRoot !== null)
         prepared.sync_root = options.syncRoot;
-    if (options.syncEnabled !== undefined && options.syncEnabled !== null)
-        prepared.sync_enabled = options.syncEnabled;
-    if (options.syncUid !== undefined && options.syncUid !== null)
-        prepared.sync_uid = options.syncUid;
-    if (options.syncGid !== undefined && options.syncGid !== null)
-        prepared.sync_gid = options.syncGid;
+    if (options.syncInclude !== undefined) {
+        prepared.sync_include = options.syncInclude === null ? null : [...options.syncInclude];
+    }
+    if (options.syncInclude === undefined && options.syncExclude !== undefined) {
+        prepared.sync_exclude = options.syncExclude === null ? null : [...options.syncExclude];
+    }
+    if (syncUid !== undefined)
+        prepared.sync_uid = syncUid;
+    if (syncGid !== undefined)
+        prepared.sync_gid = syncGid;
     if (options.registryUrl !== undefined && options.registryUrl !== null)
         prepared.registry_url = options.registryUrl;
     if (options.registryAuth !== undefined && options.registryAuth !== null)
         prepared.registry_auth = options.registryAuth;
     if (options.restart !== undefined && options.restart !== null)
         prepared.restart = options.restart;
+    if (options.runtimeScopes !== undefined && options.runtimeScopes !== null) {
+        prepared.runtime_scopes = [...options.runtimeScopes];
+    }
     return { config: prepared, gatewayToken };
 }
 function defaultOpenClawImage(image) {
@@ -857,10 +1017,17 @@ function defaultOpenClawProImage(image) {
         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;
+function defaultHermesAgentImage(image) {
+    if (image !== undefined && image !== null)
+        return image;
+    return DEFAULT_HERMES_AGENT_IMAGE;
+}
+function resolveHermesApiServerKey(explicit, env) {
+    const supplied = explicit?.trim() || env?.API_SERVER_KEY?.trim() || '';
+    const key = supplied || randomHexToken(32);
+    if (key.length < 32)
+        throw new Error('Hermes API_SERVER_KEY must be at least 32 characters');
+    return key;
 }
 export async function startSlackOAuth(options) {
     const relayBaseUrl = normalizeSlackRelayBaseUrl(options.relayBaseUrl);
@@ -1072,6 +1239,15 @@ export function buildOpenClawRoutes(options = {}) {
     }
     return routes;
 }
+export function buildHermesAgentRoutes(options = {}) {
+    return {
+        hermes: {
+            port: options.port ?? 8642,
+            auth: options.auth ?? false,
+            prefix: options.prefix ?? '',
+        },
+    };
+}
 function envBool(value) {
     return value ? '1' : '0';
 }
@@ -1116,9 +1292,6 @@ export function buildOpenClawWorkspacesSyncEnv(workspacesSync = null) {
     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);
     }
@@ -1137,8 +1310,6 @@ function bindAgent(agent, deployments) {
 export class Agent {
     id;
     userId;
-    podId;
-    podName;
     state;
     name;
     handle;
@@ -1159,7 +1330,9 @@ export class Agent {
     jwtExpiresAt;
     startedAt;
     stoppedAt;
-    lastError;
+    archivedAt;
+    clusterId;
+    launchEpoch;
     createdAt;
     updatedAt;
     launchConfig;
@@ -1167,14 +1340,11 @@ export class Agent {
     routes;
     command;
     entrypoint;
-    ports;
     dryRun;
     _deployments = null;
     constructor(fields) {
         this.id = fields.id;
         this.userId = fields.userId;
-        this.podId = fields.podId;
-        this.podName = fields.podName;
         this.state = fields.state;
         this.name = fields.name ?? null;
         this.handle = fields.handle ?? null;
@@ -1195,7 +1365,9 @@ export class Agent {
         this.jwtExpiresAt = fields.jwtExpiresAt ?? null;
         this.startedAt = fields.startedAt ?? null;
         this.stoppedAt = fields.stoppedAt ?? null;
-        this.lastError = fields.lastError ?? null;
+        this.archivedAt = fields.archivedAt ?? null;
+        this.clusterId = fields.clusterId ?? null;
+        this.launchEpoch = fields.launchEpoch ?? 0;
         this.createdAt = fields.createdAt ?? null;
         this.updatedAt = fields.updatedAt ?? null;
         this.launchConfig = fields.launchConfig ?? null;
@@ -1203,7 +1375,6 @@ export class Agent {
         this.routes = { ...fields.routes };
         this.command = [...fields.command];
         this.entrypoint = [...fields.entrypoint];
-        this.ports = [...fields.ports];
         this.dryRun = fields.dryRun;
     }
     static fromDict(data) {
@@ -1242,17 +1413,24 @@ export class Agent {
     get shellUrl() {
         return this.routeUrl('shell');
     }
-    get executorUrl() {
-        return this.shellUrl;
-    }
     get isRunning() {
         return this.state.toLowerCase() === 'running';
     }
+    get isTransitioning() {
+        return isAgentTransitionalState(this.state);
+    }
+    /** True when the agent is cold-restorable from its verified archive. */
+    get isArchived() {
+        return this.state.toUpperCase() === 'ARCHIVED';
+    }
+    /** True only for an explicitly included deletion tombstone. */
+    get isDeleted() {
+        return this.state.toUpperCase() === 'DELETED';
+    }
     get hasDesktop() {
         return agentConfigHasDesktop({
             launchConfig: this.launchConfig,
             routes: this.routes,
-            ports: this.ports,
         });
     }
     requireDeployments() {
@@ -1275,7 +1453,7 @@ export class Agent {
         return data;
     }
     async waitRunning(timeoutMs = 300_000, pollIntervalMs = 5_000) {
-        return this.requireDeployments().waitRunning(this.id, timeoutMs, pollIntervalMs);
+        return this.requireDeployments().waitRunning(this.id, timeoutMs, pollIntervalMs, this.launchEpoch > 0 ? this.launchEpoch : undefined);
     }
     async update(options) {
         return this.requireDeployments().update(this.id, options);
@@ -1284,15 +1462,29 @@ export class Agent {
         return this.requireDeployments().resize(this.id, options);
     }
     async env() {
-        const data = await this.requireDeployments().env(this.id);
-        return data.env ?? {};
+        const response = await this.requireDeployments().env(this.id);
+        if (response.launch_epoch < this.launchEpoch) {
+            throw new Error('agent env belongs to an older launch epoch');
+        }
+        return response.env;
+    }
+    async secretNames() {
+        const response = await this.requireDeployments().secretNames(this.id);
+        if (response.launch_epoch < this.launchEpoch) {
+            throw new Error('agent Secret names belong to an older launch epoch');
+        }
+        return response.names;
+    }
+    async secret(key) {
+        const response = await this.requireDeployments().secret(this.id, key);
+        if (response.launch_epoch < this.launchEpoch) {
+            throw new Error('agent Secret belongs to an older launch epoch');
+        }
+        return response.value;
     }
     async exec(command, options = {}) {
         return this.requireDeployments().exec(this, command, options);
     }
-    async health() {
-        return this.requireDeployments().health(this);
-    }
     /**
      * The gateway file writer a subclass supplies — the seam that enables the
      * `gateway` source. The base agent has none (gateway calls throw); an agent
@@ -1344,6 +1536,12 @@ export class Agent {
     }
 }
 const RUNTIME_AUTH_CONFIG = {
+    'buzz-agent': {
+        agentCommand: ['buzz-agent'],
+        statusCommand: ['buzz-acp', 'models', '--agent-command', 'buzz-agent', '--json'],
+        logoutCommand: null,
+        nativeMethods: [],
+    },
     opencode: {
         agentCommand: ['opencode', 'acp'],
         statusCommand: ['buzz-acp', 'models', '--agent-command', 'opencode', '--agent-args', 'acp', '--json'],
@@ -1442,19 +1640,22 @@ async function websocketMessageText(data) {
 export class RuntimeLoginSession {
     authClient;
     socket;
+    requiresDeviceChallenge;
     output = '';
     verificationUrl = null;
     userCode = null;
     interactiveRequired = false;
+    rawOutput = '';
     exitCode = null;
     marker;
     completion;
     ready;
     complete;
     markReady;
-    constructor(authClient, socket, command) {
+    constructor(authClient, socket, command, requiresDeviceChallenge) {
         this.authClient = authClient;
         this.socket = socket;
+        this.requiresDeviceChallenge = requiresDeviceChallenge;
         this.marker = `__HYPERCLI_AUTH_EXIT_${randomHexToken(12)}__=`;
         this.completion = new Promise((resolve) => { this.complete = resolve; });
         this.ready = new Promise((resolve) => { this.markReady = resolve; });
@@ -1467,9 +1668,9 @@ export class RuntimeLoginSession {
         };
         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) {
+    static async start(authClient, command, challengeTimeoutMs = 45_000, requiresDeviceChallenge = false) {
         const socket = await authClient.agent.shellConnect();
-        const session = new RuntimeLoginSession(authClient, socket, command);
+        const session = new RuntimeLoginSession(authClient, socket, command, requiresDeviceChallenge);
         let timer;
         try {
             await Promise.race([
@@ -1490,7 +1691,8 @@ export class RuntimeLoginSession {
         }
     }
     consume(chunk) {
-        this.output += stripTerminalCodes(chunk);
+        this.rawOutput += chunk;
+        this.output = stripTerminalCodes(this.rawOutput);
         const markerIndex = this.output.lastIndexOf(this.marker);
         if (markerIndex >= 0) {
             const match = this.output.slice(markerIndex + this.marker.length).match(/^(-?\d+)/);
@@ -1500,10 +1702,13 @@ export class RuntimeLoginSession {
                 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.verificationUrl ??= this.output.match(/https?:\/\/[^\s"'<>]+(?=[\s"'<>])/)?.[0] ?? null;
+        this.userCode ??= this.output.match(/\b(?:user|device|verification|one[- ]time)\s+code\b\s*(?:is|:)?\s*(?:\([^\r\n)]*\)\s*)*((?!authorization\b)[A-Z0-9](?:[A-Z0-9-]*[A-Z0-9])?)(?=[\s.,;:)\]])/i)?.[1] ?? null;
         this.interactiveRequired ||= /\b(select|choose)\b.*\b(provider|login method)\b/i.test(this.output);
-        if (this.verificationUrl || this.userCode || this.interactiveRequired)
+        const challengeReady = this.requiresDeviceChallenge
+            ? Boolean(this.verificationUrl && this.userCode)
+            : Boolean(this.verificationUrl || this.userCode);
+        if (challengeReady || this.interactiveRequired)
             this.markReady();
     }
     send(text) {
@@ -1519,6 +1724,10 @@ export class RuntimeLoginSession {
                 }),
             ]);
         }
+        catch (error) {
+            this.cancel();
+            throw error;
+        }
         finally {
             if (timer)
                 clearTimeout(timer);
@@ -1529,7 +1738,9 @@ export class RuntimeLoginSession {
         return this.authClient.status();
     }
     cancel() {
-        if (this.socket.readyState === WebSocket.OPEN)
+        // The SDK supports Node runtimes where the socket is supplied by `ws` and
+        // no global WebSocket constructor exists. OPEN is the protocol state 1.
+        if (this.socket.readyState === 1)
             this.socket.send('\x03');
         this.socket.close();
     }
@@ -1632,7 +1843,10 @@ export class RuntimeAuthClient {
         }
         if (this.agent.runtime === 'claude-code' && options.email)
             command.push('--email', options.email);
-        return RuntimeLoginSession.start(this, command, options.challengeTimeoutMs);
+        const requiresDeviceChallenge = method.kind === 'device'
+            || method.id === 'device'
+            || command.some((part) => part.toLowerCase().includes('device-auth'));
+        return RuntimeLoginSession.start(this, command, options.challengeTimeoutMs, requiresDeviceChallenge);
     }
     async logout(provider) {
         if (this.config.logoutCommand === null) {
@@ -1652,35 +1866,101 @@ export class RuntimeAuthClient {
     }
 }
 export class CodingAgent extends Agent {
+    static defaultSyncInclude = null;
     get auth() {
         return new RuntimeAuthClient(this);
     }
 }
+export class BuzzAgent extends CodingAgent {
+    static defaultSyncInclude = DEFAULT_CODING_AGENT_SYNC_INCLUDES['buzz-agent'];
+    static fromDict(data) {
+        return new BuzzAgent(agentStateFromDict(data));
+    }
+}
 export class OpenCodeAgent extends CodingAgent {
+    static defaultSyncInclude = DEFAULT_CODING_AGENT_SYNC_INCLUDES.opencode;
     static fromDict(data) {
         return new OpenCodeAgent(agentStateFromDict(data));
     }
 }
 export class CodexAgent extends CodingAgent {
+    static defaultSyncInclude = DEFAULT_CODING_AGENT_SYNC_INCLUDES.codex;
     static fromDict(data) {
         return new CodexAgent(agentStateFromDict(data));
     }
 }
 export class ClaudeCodeAgent extends CodingAgent {
+    static defaultSyncInclude = DEFAULT_CODING_AGENT_SYNC_INCLUDES['claude-code'];
     static fromDict(data) {
         return new ClaudeCodeAgent(agentStateFromDict(data));
     }
 }
 export class GooseAgent extends CodingAgent {
+    static defaultSyncInclude = DEFAULT_CODING_AGENT_SYNC_INCLUDES.goose;
     static fromDict(data) {
         return new GooseAgent(agentStateFromDict(data));
     }
 }
 export class KimiCodeAgent extends CodingAgent {
+    static defaultSyncInclude = DEFAULT_CODING_AGENT_SYNC_INCLUDES['kimi-code'];
     static fromDict(data) {
         return new KimiCodeAgent(agentStateFromDict(data));
     }
 }
+const CODING_AGENT_CLASSES = {
+    'buzz-agent': BuzzAgent,
+    opencode: OpenCodeAgent,
+    codex: CodexAgent,
+    'claude-code': ClaudeCodeAgent,
+    goose: GooseAgent,
+    'kimi-code': KimiCodeAgent,
+};
+export class HermesAgent extends Agent {
+    apiUrl;
+    openaiBaseUrl;
+    /** Available only on the instance returned by createHermesAgent/startHermesAgent. */
+    apiServerKey;
+    constructor(fields) {
+        super(fields);
+        this.apiUrl = fields.apiUrl ?? this.routeUrl('hermes', '');
+        this.openaiBaseUrl = this.apiUrl ? `${this.apiUrl.replace(/\/+$/, '')}/v1` : null;
+        this.apiServerKey = fields.apiServerKey ?? null;
+    }
+    static fromDict(data) {
+        const fields = agentStateFromDict(data);
+        if (fields.launchConfig?.env && typeof fields.launchConfig.env === 'object') {
+            fields.launchConfig = structuredClone(fields.launchConfig);
+            delete fields.launchConfig.env.API_SERVER_KEY;
+        }
+        return new HermesAgent({
+            ...fields,
+            // Never recover API_SERVER_KEY from launch_config or process env.
+            apiServerKey: null,
+        });
+    }
+    /** Create a client for this agent's authenticated Hermes API. */
+    get api() {
+        if (!this.apiUrl || !this.apiServerKey)
+            return null;
+        return new HermesApiClient(this.apiUrl, { apiKey: this.apiServerKey });
+    }
+    /** Require a ready URL and the one-time SDK-retained API server key. */
+    apiClient() {
+        const client = this.api;
+        if (!client) {
+            throw new Error('Hermes API context is unavailable; use the HermesAgent returned by createHermesAgent/startHermesAgent after its hostname is attached');
+        }
+        return client;
+    }
+    async waitRunning(timeoutMs = 300_000, pollIntervalMs = 5_000) {
+        const ready = await super.waitRunning(timeoutMs, pollIntervalMs);
+        if (!(ready instanceof HermesAgent)) {
+            throw new Error("Running deployment did not identify runtime 'hermes-agent'");
+        }
+        ready.apiServerKey = this.apiServerKey;
+        return ready;
+    }
+}
 export class OpenClawAgent extends Agent {
     gatewayUrl;
     gatewayToken;
@@ -1693,33 +1973,14 @@ export class OpenClawAgent extends Agent {
         return new OpenClawAgent({
             ...agentStateFromDict(data),
             gatewayUrl: this.gatewayUrlFromHostname(data.hostname),
-            gatewayToken: data.gateway_token ?? null,
+            gatewayToken: null,
         });
     }
     static gatewayUrlFromHostname(hostname) {
         const trimmed = String(hostname ?? '').trim();
         return trimmed ? `wss://${trimmed}` : null;
     }
-    currentGatewayHostname() {
-        if (this.hostname)
-            return this.hostname;
-        if (!this.gatewayUrl)
-            return null;
-        try {
-            return new URL(this.gatewayUrl).hostname || null;
-        }
-        catch {
-            return this.gatewayUrl.replace(/^wss?:\/\//, '').split('/')[0] || null;
-        }
-    }
-    /**
-     * Resolve gateway context through the deployment record plus `/env`.
-     *
-     * Agent startup is eventually consistent: the deployment record may lag
-     * behind hostname attachment, and runtime env can lag behind both. The SDK
-     * derives the gateway URL from the attached hostname and reads the gateway
-     * token from `OPENCLAW_GATEWAY_TOKEN` in the agent env route.
-     */
+    /** Resolve OpenClaw connection context from the generic Agent and Secret APIs. */
     async waitForGatewayContext(options = {}) {
         const callerAbortError = () => {
             if (options.signal?.reason instanceof Error)
@@ -1730,13 +1991,6 @@ export class OpenClawAgent extends Agent {
         };
         if (options.signal?.aborted)
             throw callerAbortError();
-        if (this.gatewayToken && this.gatewayUrl) {
-            return {
-                agent_id: this.id,
-                hostname: this.currentGatewayHostname(),
-                gateway_token: this.gatewayToken,
-            };
-        }
         const timeoutMs = options.timeoutMs ?? 30_000;
         const retryIntervalMs = options.retryIntervalMs ?? 1_000;
         const deployments = this.requireDeployments();
@@ -1799,31 +2053,41 @@ export class OpenClawAgent extends Agent {
                     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;
-                    }));
-                }
-                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) {
+                try {
+                    const refreshed = await runWithAbort(deployments.get(this.id, requestOptions));
+                    if (refreshed.launchEpoch < this.launchEpoch) {
+                        throw new Error('gateway Agent belongs to an older launch epoch');
+                    }
+                    if (refreshed.state.toUpperCase() !== 'RUNNING') {
+                        throw new Error(`gateway Agent is ${refreshed.state}, not RUNNING`);
+                    }
+                    const secret = await runWithAbort(deployments.secret(this.id, 'OPENCLAW_GATEWAY_TOKEN', requestOptions));
+                    if (secret.launch_epoch !== refreshed.launchEpoch) {
+                        throw new Error('gateway Secret and Agent belong to different launch epochs');
+                    }
+                    const gatewayToken = secret.value.trim();
+                    if (!gatewayToken)
+                        throw new Error('OPENCLAW_GATEWAY_TOKEN is empty');
+                    const confirmed = await runWithAbort(deployments.get(this.id, requestOptions));
+                    if (confirmed.launchEpoch !== refreshed.launchEpoch
+                        || confirmed.state.toUpperCase() !== 'RUNNING') {
+                        throw new Error('gateway Agent changed while its Secret was resolved');
+                    }
+                    const gatewayUrl = OpenClawAgent.gatewayUrlFromHostname(confirmed.hostname);
+                    if (!gatewayUrl)
+                        throw new Error('gateway Agent has no hostname');
+                    this.gatewayUrl = gatewayUrl;
+                    this.gatewayToken = gatewayToken;
                     return {
                         agent_id: this.id,
-                        hostname: this.currentGatewayHostname(),
-                        gateway_token: this.gatewayToken,
+                        gateway_url: gatewayUrl,
+                        gateway_token: gatewayToken,
+                        launch_epoch: refreshed.launchEpoch,
                     };
                 }
-                lastError = rejected?.reason ?? new Error('missing gateway context');
+                catch (error) {
+                    lastError = error;
+                }
                 const remainingAfterRequestMs = deadline - Date.now();
                 if (remainingAfterRequestMs <= 0)
                     throw timeoutError();
@@ -2063,6 +2327,35 @@ export class OpenClawAgent extends Agent {
             client.close();
         }
     }
+    async operationsSnapshot(options = {}) {
+        if (!this.gatewayUrl || (!this.gatewayToken && !options.gatewayToken)) {
+            await this.waitForGatewayContext({ timeoutMs: options.timeout });
+        }
+        const client = this.gateway(options);
+        try {
+            await client.connect();
+            const [sessionsResult, cronResult] = await Promise.allSettled([
+                client.sessionsListResult(),
+                client.cronList(),
+            ]);
+            const failures = {};
+            if (sessionsResult.status === 'rejected') {
+                failures.sessions = stringifyOpenClawOperationsFailure(sessionsResult.reason);
+            }
+            if (cronResult.status === 'rejected') {
+                failures.cron = stringifyOpenClawOperationsFailure(cronResult.reason);
+            }
+            return {
+                sessions: sessionsResult.status === 'fulfilled' ? sessionsResult.value : null,
+                cronJobs: cronResult.status === 'fulfilled' ? cronResult.value : null,
+                failures,
+                capturedAt: Date.now(),
+            };
+        }
+        finally {
+            client.close();
+        }
+    }
     async *chatSend(message, sessionKey, options = {}) {
         const client = await this.connect(options);
         try {
@@ -2407,7 +2700,7 @@ export class OpenClawProAgent extends OpenClawAgent {
         return new OpenClawProAgent({
             ...agentStateFromDict(data),
             gatewayUrl: this.gatewayUrlFromHostname(data.hostname),
-            gatewayToken: data.gateway_token ?? null,
+            gatewayToken: null,
         });
     }
 }
@@ -2433,7 +2726,13 @@ export class Deployments {
     }
     hydrateAgent(data) {
         let agent;
-        if (data.runtime === 'opencode') {
+        if (data.runtime === 'hermes-agent') {
+            agent = HermesAgent.fromDict(data);
+        }
+        else if (data.runtime === 'buzz-agent') {
+            agent = BuzzAgent.fromDict(data);
+        }
+        else if (data.runtime === 'opencode') {
             agent = OpenCodeAgent.fromDict(data);
         }
         else if (data.runtime === 'codex') {
@@ -2476,7 +2775,7 @@ export class Deployments {
         }
         const matches = [];
         for (const agent of await this.list(requestOptions)) {
-            const values = [agent.id, agent.name, agent.handle, agent.podName, agent.hostname];
+            const values = [agent.id, agent.name, agent.handle, agent.hostname];
             if (values.some((value) => String(value || '') === raw)) {
                 matches.push(agent);
                 continue;
@@ -2493,11 +2792,16 @@ export class Deployments {
         }
         return this.getById(matches[0].id, requestOptions);
     }
-    async resolveAgentId(agentIdOrName, requestOptions = {}) {
+    async resolveAgentId(agentIdOrName, requestOptions = {}, allowSelf = false) {
         const raw = String(agentIdOrName || '').trim();
         if (!raw) {
             throw new Error('agentIdOrName is required');
         }
+        if (isSelfAgentRef(raw)) {
+            if (allowSelf)
+                return 'self';
+            throw new Error('self is only supported for status, start, stop, and routes');
+        }
         if (isDirectAgentIdRef(raw)) {
             return raw;
         }
@@ -2533,7 +2837,7 @@ export class Deployments {
         return response;
     }
     async create(options = {}) {
-        const { config, gatewayToken } = buildAgentConfig(options.config ?? {}, {
+        const { config } = buildAgentConfig(options.config ?? {}, {
             ...options,
             injectGatewayToken: options.injectGatewayToken ?? !isCodingAgentRuntime(options.runtime),
         });
@@ -2552,40 +2856,71 @@ export class Deployments {
             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) {
-            agent.gatewayToken = gatewayToken;
-        }
-        agent.launchConfig = config;
-        agent.command = [...(config.command ?? [])];
-        agent.entrypoint = [...(config.entrypoint ?? [])];
-        return agent;
+        const data = await this.agentHttp.post(DEPLOYMENTS_API_PREFIX, body, { retries: 1 });
+        return this.hydrateAgent(data);
     }
     async createOpenClaw(options = {}) {
         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 (effectiveOptions.env.HYPER_WORKSPACES_BOOT_SYNC !== '0') {
+            effectiveOptions.env.HYPER_WORKSPACES_DIR = '/home/node/shared';
+        }
         if (options.routes === undefined) {
             effectiveOptions.routes = buildOpenClawRoutes(options.openClawRoutes ?? {});
         }
         effectiveOptions.image = defaultOpenClawImage(options.image);
         if (effectiveOptions.syncRoot === undefined)
             effectiveOptions.syncRoot = DEFAULT_OPENCLAW_SYNC_ROOT;
-        if (effectiveOptions.syncEnabled === undefined)
-            effectiveOptions.syncEnabled = true;
+        if (options.syncInclude === undefined && options.syncExclude === undefined) {
+            effectiveOptions.syncExclude = DEFAULT_OPENCLAW_SYNC_EXCLUDE;
+        }
         return this.create(effectiveOptions);
     }
+    async createHermesAgent(options = {}) {
+        const apiServerKey = resolveHermesApiServerKey(options.apiServerKey, options.env);
+        const env = {
+            ...(options.env ?? {}),
+            API_SERVER_ENABLED: 'true',
+            API_SERVER_HOST: '0.0.0.0',
+            API_SERVER_KEY: apiServerKey,
+        };
+        delete env.OPENCLAW_GATEWAY_TOKEN;
+        const effectiveOptions = {
+            ...options,
+            runtime: 'hermes-agent',
+            env,
+            image: defaultHermesAgentImage(options.image),
+            runtimeScopes: options.runtimeScopes ?? DEFAULT_AGENT_RUNTIME_SCOPES,
+            injectGatewayToken: false,
+            syncRoot: options.syncRoot ?? DEFAULT_HERMES_AGENT_SYNC_ROOT,
+            syncUid: options.syncUid ?? DEFAULT_HERMES_AGENT_SYNC_UID,
+            syncGid: options.syncGid ?? DEFAULT_HERMES_AGENT_SYNC_GID,
+            routes: options.routes === undefined
+                ? buildHermesAgentRoutes(options.hermesRoute ?? {})
+                : options.routes,
+        };
+        const agent = await this.create(effectiveOptions);
+        if (!(agent instanceof HermesAgent)) {
+            throw new Error("Hermes deployment response did not identify runtime 'hermes-agent'");
+        }
+        agent.apiServerKey = apiServerKey;
+        if (agent.launchConfig?.env && typeof agent.launchConfig.env === 'object') {
+            agent.launchConfig = structuredClone(agent.launchConfig);
+            delete agent.launchConfig.env.API_SERVER_KEY;
+        }
+        return agent;
+    }
     async createOpenClawPro(options = {}) {
         return this.createOpenClaw({
             ...options,
             runtime: 'openclaw-pro',
             env: { OPENCLAW_DESKTOP_ENABLED: '1', ...(options.env ?? {}) },
             image: defaultOpenClawProImage(options.image),
+            runtimeScopes: options.runtimeScopes ?? DEFAULT_AGENT_RUNTIME_SCOPES,
             openClawRoutes: { includeDesktop: true, ...(options.openClawRoutes ?? {}) },
         });
     }
@@ -2601,24 +2936,57 @@ export class Deployments {
             throw new Error("Buzz coding agents require size='large'");
         }
         const effectiveEnv = {
-            HYPER_API_BASE: productApiBaseFromAgentsApiBase(this.apiBase),
             ...buildOpenClawWorkspacesSyncEnv(options.workspacesSync ?? null),
             ...(options.env ?? {}),
         };
+        const effectiveSecrets = { ...(options.secrets ?? {}) };
+        for (const key of ['BUZZ_PRIVATE_KEY', 'NOSTR_PRIVATE_KEY']) {
+            const value = effectiveEnv[key];
+            if (value === undefined)
+                continue;
+            delete effectiveEnv[key];
+            if (effectiveSecrets[key] !== undefined && effectiveSecrets[key] !== value) {
+                throw new Error(`${key} conflicts between env and secrets`);
+            }
+            effectiveSecrets[key] = value;
+        }
+        if (effectiveEnv.HYPER_WORKSPACES_BOOT_SYNC !== '0') {
+            effectiveEnv.HYPER_WORKSPACES_DIR = '/home/node/shared';
+        }
         if (options.buzz) {
             for (const key of BUZZ_RESERVED_ENV_KEYS)
                 delete effectiveEnv[key];
             Object.assign(effectiveEnv, buildBuzzLaunchEnv(runtime, options.buzz, options.name));
+            Object.assign(effectiveSecrets, buildBuzzLaunchSecrets(options.buzz));
         }
         if (buzzLaunch) {
             effectiveEnv.RUST_LOG ??= DEFAULT_BUZZ_RUST_LOG;
         }
+        let syncInclude;
+        let syncExclude;
+        if (options.syncInclude !== undefined && options.syncInclude !== null) {
+            syncInclude = options.syncInclude;
+            syncExclude = undefined;
+        }
+        else if (options.syncExclude !== undefined) {
+            syncInclude = undefined;
+            syncExclude = options.syncExclude ?? undefined;
+        }
+        else if (options.syncInclude === null) {
+            syncInclude = undefined;
+            syncExclude = undefined;
+        }
+        else {
+            syncInclude = CODING_AGENT_CLASSES[runtime].defaultSyncInclude;
+            syncExclude = undefined;
+        }
         const effectiveOptions = {
             ...options,
             runtime,
             size: buzzLaunch ? 'large' : options.size,
             injectGatewayToken: false,
             env: effectiveEnv,
+            secrets: effectiveSecrets,
             routes: options.routes ?? {},
             image: options.image ?? (buzzLaunch
                 ? DEFAULT_BUZZ_CODING_AGENT_IMAGES[runtime]
@@ -2627,18 +2995,23 @@ export class Deployments {
                 ? ['/usr/local/bin/buzz-acp']
                 : options.command,
             syncRoot: options.syncRoot ?? DEFAULT_CODING_AGENT_SYNC_ROOT,
-            syncEnabled: options.syncEnabled ?? true,
+            syncInclude,
+            syncExclude,
             syncUid: options.syncUid ?? 1000,
             syncGid: options.syncGid ?? 1000,
-            restart: buzzLaunch
-                ? options.restart ?? options.buzz?.restart ?? false
-                : options.restart,
+            // Hosted Buzz shutdown is process-driven; generic launch options cannot
+            // opt it back into automatic restart.
+            restart: buzzLaunch ? false : options.restart,
+            runtimeScopes: options.runtimeScopes ?? DEFAULT_AGENT_RUNTIME_SCOPES,
         };
         return await this.create(effectiveOptions);
     }
     async createOpenCode(options = {}) {
         return await this.createCodingAgent('opencode', options);
     }
+    async createBuzzAgent(options = {}) {
+        return await this.createCodingAgent('buzz-agent', options);
+    }
     async createCodex(options = {}) {
         return await this.createCodingAgent('codex', options);
     }
@@ -2665,6 +3038,9 @@ export class Deployments {
         return this.agentHttp.get(`${DEPLOYMENTS_API_PREFIX}/${agentId}/metrics`);
     }
     async list(options = {}) {
+        return (await this.listWithCapacity(options)).items;
+    }
+    async listWithCapacity(options = {}) {
         const params = {};
         if (options.state)
             params.state = options.state;
@@ -2692,13 +3068,33 @@ export class Deployments {
             }
         }
         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));
+        const payload = Array.isArray(data) ? { items: data } : data;
+        const items = (payload.items ?? []).map((item) => this.hydrateAgent(item));
+        const runningFallback = items.filter((agent) => !isAgentRuntimeInactiveState(agent.state)).length;
+        return {
+            items,
+            totalAgents: Number(payload.total_agents ?? items.length),
+            maxAgentsPerAccount: Number(payload.max_agents_per_account ?? 0),
+            runningAgents: Number(payload.running_agents ?? runningFallback),
+            slots: Object.fromEntries(Object.entries(payload.slots ?? {}).map(([size, raw]) => {
+                const inventory = raw;
+                return [size, {
+                        granted: Number(inventory.granted ?? 0),
+                        used: Number(inventory.used ?? inventory.occupied ?? 0),
+                        available: Number(inventory.available ?? 0),
+                    }];
+            })),
+            agentSlots: (payload.agent_slots ?? []).map(agentSlotFromDict),
+            pooledTpd: Number(payload.pooled_tpd ?? 0),
+        };
     }
     async get(agentIdOrName, requestOptions = {}) {
         const raw = String(agentIdOrName || '').trim();
         if (!raw)
             throw new Error('agentIdOrName is required');
+        if (isSelfAgentRef(raw)) {
+            return this.getById('self', requestOptions);
+        }
         if (!isDirectAgentIdRef(raw)) {
             return this.resolveAgent(raw, requestOptions);
         }
@@ -2767,77 +3163,240 @@ export class Deployments {
             agentId,
         });
     }
-    async waitRunning(agentIdOrName, timeoutMs = 300_000, pollIntervalMs = 5_000) {
+    async subscribe(handler, options = {}) {
+        let retryDelay = 250;
+        const waitBeforeReconnect = async () => {
+            let abortRetry = () => { };
+            const aborted = new Promise((resolve) => {
+                if (options.signal?.aborted)
+                    resolve();
+                else {
+                    abortRetry = resolve;
+                    options.signal?.addEventListener('abort', abortRetry, { once: true });
+                }
+            });
+            try {
+                await Promise.race([sleep(retryDelay), aborted]);
+            }
+            finally {
+                options.signal?.removeEventListener('abort', abortRetry);
+            }
+            retryDelay = Math.min(retryDelay * 2, 5_000);
+        };
+        while (!options.signal?.aborted) {
+            try {
+                const token = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/events/token`, undefined, { signal: options.signal });
+                const WebSocketImpl = globalThis.WebSocket ?? NodeWebSocket;
+                const ws = new WebSocketImpl(token.ws_url);
+                await new Promise((resolve, reject) => {
+                    let opened = false;
+                    let ready = false;
+                    let processing = Promise.resolve();
+                    const readyTimer = setTimeout(() => {
+                        ws.close(4002, 'Deployment event ready timed out');
+                        reject(new Error('Deployment event ready timed out'));
+                    }, 10_000);
+                    const abort = () => ws.close(1000, 'Subscription cancelled');
+                    options.signal?.addEventListener('abort', abort, { once: true });
+                    ws.addEventListener('open', () => {
+                        opened = true;
+                        ws.send(JSON.stringify({ type: 'auth', token: token.token }));
+                    });
+                    ws.addEventListener('message', (message) => {
+                        processing = processing.then(async () => {
+                            const frame = JSON.parse(await websocketMessageText(message.data));
+                            if (!ready) {
+                                if (frame.type !== 'ready') {
+                                    throw new Error('Deployment event socket did not send ready');
+                                }
+                                ready = true;
+                                clearTimeout(readyTimer);
+                                await options.onReady?.();
+                                retryDelay = 250;
+                                return;
+                            }
+                            if (frame.type === 'deployment.transition'
+                                && typeof frame.agent_id === 'string'
+                                && frame.agent_id.length > 0) {
+                                await handler(frame);
+                            }
+                        }).catch((error) => {
+                            ws.close(4002, 'Invalid deployment event');
+                            reject(error);
+                        });
+                    });
+                    ws.addEventListener('error', () => reject(new Error('Deployment event WebSocket failed')));
+                    ws.addEventListener('close', () => {
+                        clearTimeout(readyTimer);
+                        options.signal?.removeEventListener('abort', abort);
+                        processing.then(resolve, reject);
+                    });
+                    if (options.signal?.aborted)
+                        abort();
+                    void opened;
+                });
+                if (!options.signal?.aborted)
+                    await waitBeforeReconnect();
+            }
+            catch (error) {
+                if (options.signal?.aborted)
+                    break;
+                if (error instanceof APIError && [401, 403].includes(error.statusCode))
+                    throw error;
+                await waitBeforeReconnect();
+                void error;
+            }
+        }
+    }
+    async waitForState(agentIdOrName, states, timeoutMs = 300_000, failureStates = [], minimumLaunchEpoch, pollIntervalMs = 5_000) {
+        if (!states.length)
+            throw new Error('states must not be empty');
+        if (minimumLaunchEpoch !== undefined && minimumLaunchEpoch < 0) {
+            throw new Error('minimumLaunchEpoch must be non-negative');
+        }
         const agentId = await this.resolveAgentId(agentIdOrName);
         const deadline = Date.now() + timeoutMs;
         let lastState = '';
-        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) {
+        let wakePending = true;
+        let wake = null;
+        const controller = new AbortController();
+        const desired = new Set(states.map((state) => state.toLowerCase()));
+        const failures = new Set(failureStates.map((state) => state.toLowerCase()));
+        const effectivePollIntervalMs = Math.max(1, pollIntervalMs);
+        const stateLabel = states.join(', ');
+        const refresh = async () => {
             const agent = await this.get(agentId);
-            lastAgent = agent;
             lastState = String(agent.state || '');
-            if (lastState.toLowerCase() === 'running') {
+            if (minimumLaunchEpoch !== undefined
+                && agent.launchEpoch < minimumLaunchEpoch)
+                return null;
+            if (desired.has(lastState.toLowerCase()))
                 return agent;
+            if (failures.has(lastState.toLowerCase())) {
+                throw new Error(`Agent entered ${lastState} while waiting for ${stateLabel}`);
+            }
+            return null;
+        };
+        const subscription = this.subscribe((event) => {
+            if (event.type === 'deployment.transition' && event.agent_id === agentId) {
+                wakePending = true;
+                wake?.();
             }
-            if (['failed', 'error', 'restore_failed', 'sync_failed'].includes(lastState.toLowerCase())) {
-                throw new Error(`Agent entered ${lastState} while waiting for RUNNING${diagnostics(agent)}`);
+        }, {
+            signal: controller.signal,
+            onReady: () => {
+                wakePending = true;
+                wake?.();
+            },
+        }).catch(() => {
+            // Lifecycle events reduce latency, but REST polling remains authoritative.
+            wakePending = true;
+            wake?.();
+        });
+        try {
+            while (Date.now() < deadline) {
+                if (wakePending) {
+                    wakePending = false;
+                    const agent = await refresh();
+                    if (agent)
+                        return agent;
+                    continue;
+                }
+                const remaining = deadline - Date.now();
+                if (remaining <= 0)
+                    break;
+                await Promise.race([
+                    new Promise((resolve) => { wake = resolve; }),
+                    sleep(Math.min(remaining, effectivePollIntervalMs)).then(() => {
+                        wakePending = true;
+                    }),
+                ]);
+                wake = null;
             }
-            await sleep(pollIntervalMs);
+            const finalAgent = await refresh();
+            if (finalAgent)
+                return finalAgent;
         }
-        throw new Error(`Timed out waiting for agent ${agentId} to reach RUNNING (last=${lastState || 'unknown'}${diagnostics(lastAgent)})`);
+        finally {
+            controller.abort();
+            await subscription;
+        }
+        throw new Error(`Timed out waiting for agent ${agentId} to reach ${stateLabel} (last=${lastState || 'unknown'})`);
+    }
+    async waitRunning(agentIdOrName, timeoutMs = 300_000, pollIntervalMs = 5_000, minimumLaunchEpoch) {
+        return this.waitForState(agentIdOrName, ['RUNNING'], timeoutMs, ['STOPPED', 'ARCHIVED', 'DELETED', 'FAILED'], minimumLaunchEpoch, pollIntervalMs);
     }
     async start(agentIdOrName, options = {}) {
-        const { config, gatewayToken } = buildAgentConfig(options.config ?? {}, options);
+        if (isSelfAgentRef(agentIdOrName)) {
+            const provided = Object.keys(options).filter((key) => options[key] !== undefined);
+            if (provided.length > 0) {
+                throw new Error(`start self uses the backend-stored launch configuration and does not accept launch overrides: ${provided.join(', ')}`);
+            }
+            const data = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/self/start`, {}, { retries: 1 });
+            return this.hydrateAgent(data);
+        }
+        const provided = Object.keys(options).filter((key) => options[key] !== undefined);
+        const agentId = await this.resolveAgentId(agentIdOrName, {}, true);
+        if (provided.length === 0) {
+            const data = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/start`, {}, { retries: 1 });
+            return this.hydrateAgent(data);
+        }
+        const { config } = buildAgentConfig(options.config ?? {}, options);
         const body = { ...config };
         if (options.dryRun)
             body.dry_run = true;
-        const 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) {
-            agent.gatewayToken = gatewayToken;
-        }
-        agent.launchConfig = config;
-        agent.command = [...(config.command ?? [])];
-        agent.entrypoint = [...(config.entrypoint ?? [])];
-        return agent;
+        const data = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/start`, body, { retries: 1 });
+        return this.hydrateAgent(data);
     }
     async startOpenClaw(agentIdOrName, options = {}) {
         const effectiveOptions = { ...options };
-        effectiveOptions.env = {
-            HYPER_API_BASE: productApiBaseFromAgentsApiBase(this.apiBase),
-            ...buildOpenClawWorkspacesSyncEnv(options.workspacesSync ?? null),
-            ...buildOpenClawMemoryIndexEnv(options.memoryIndex),
+        if (options.workspacesSync !== undefined || options.memoryIndex !== undefined) {
+            effectiveOptions.env = {
+                ...(options.workspacesSync !== undefined
+                    ? buildOpenClawWorkspacesSyncEnv(options.workspacesSync ?? null)
+                    : {}),
+                ...(options.memoryIndex !== undefined
+                    ? buildOpenClawMemoryIndexEnv(options.memoryIndex)
+                    : {}),
+                ...(options.env ?? {}),
+            };
+        }
+        if (options.routes === undefined && options.openClawRoutes !== undefined) {
+            effectiveOptions.routes = buildOpenClawRoutes(options.openClawRoutes ?? undefined);
+        }
+        return this.start(agentIdOrName, effectiveOptions);
+    }
+    async startHermesAgent(agentIdOrName, options = {}) {
+        const apiServerKey = resolveHermesApiServerKey(options.apiServerKey, options.env);
+        const env = {
             ...(options.env ?? {}),
+            API_SERVER_ENABLED: 'true',
+            API_SERVER_HOST: '0.0.0.0',
+            API_SERVER_KEY: apiServerKey,
         };
-        if (options.routes === undefined) {
-            effectiveOptions.routes = buildOpenClawRoutes(options.openClawRoutes ?? {});
+        delete env.OPENCLAW_GATEWAY_TOKEN;
+        const effectiveOptions = {
+            ...options,
+            env,
+            image: defaultHermesAgentImage(options.image),
+            runtimeScopes: options.runtimeScopes ?? DEFAULT_AGENT_RUNTIME_SCOPES,
+            injectGatewayToken: false,
+            syncRoot: options.syncRoot ?? DEFAULT_HERMES_AGENT_SYNC_ROOT,
+            syncUid: options.syncUid ?? DEFAULT_HERMES_AGENT_SYNC_UID,
+            syncGid: options.syncGid ?? DEFAULT_HERMES_AGENT_SYNC_GID,
+            routes: options.routes === undefined
+                ? buildHermesAgentRoutes(options.hermesRoute ?? {})
+                : options.routes,
+        };
+        const agent = await this.start(agentIdOrName, effectiveOptions);
+        if (!(agent instanceof HermesAgent)) {
+            throw new Error("Hermes deployment response did not identify runtime 'hermes-agent'");
         }
-        effectiveOptions.image = defaultOpenClawImage(options.image);
-        if (effectiveOptions.syncRoot === undefined)
-            effectiveOptions.syncRoot = DEFAULT_OPENCLAW_SYNC_ROOT;
-        if (effectiveOptions.syncEnabled === undefined)
-            effectiveOptions.syncEnabled = true;
-        return this.start(agentIdOrName, effectiveOptions);
+        agent.apiServerKey = apiServerKey;
+        return agent;
     }
     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 ?? {}) },
-        });
+        return this.startOpenClaw(agentIdOrName, options);
     }
     async update(agentIdOrName, options = {}) {
         const body = {};
@@ -2851,8 +3410,8 @@ export class Deployments {
             body.launch_config = options.launchConfig;
         if (options.refreshFromLagoon !== undefined)
             body.refresh_from_lagoon = options.refreshFromLagoon;
-        if (options.lastError !== undefined)
-            body.last_error = options.lastError;
+        if (options.error !== undefined)
+            body.error = options.error;
         const agentId = await this.resolveAgentId(agentIdOrName);
         const data = await this.agentHttp.patch(`${DEPLOYMENTS_API_PREFIX}/${agentId}`, body);
         return this.hydrateAgent(data);
@@ -2877,10 +3436,42 @@ export class Deployments {
      * deployment slot as released.
      */
     async stop(agentIdOrName) {
+        const agentId = await this.resolveAgentId(agentIdOrName, {}, true);
+        const data = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/stop`, undefined, { retries: 1 });
+        return this.hydrateAgent(data);
+    }
+    /** Restore durable storage. The accepted snapshot is `RESTORING`; completion is `STOPPED`. */
+    async restore(agentIdOrName) {
         const agentId = await this.resolveAgentId(agentIdOrName);
-        const data = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/stop`);
+        const data = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/restore`, undefined, { retries: 1 });
         return this.hydrateAgent(data);
     }
+    async getRoutes(agentIdOrName) {
+        const agentId = await this.resolveAgentId(agentIdOrName, {}, true);
+        const data = await this.agentHttp.get(`${DEPLOYMENTS_API_PREFIX}/${agentId}/routes`);
+        return agentRoutesStateFromData(data);
+    }
+    async setRoutes(agentIdOrName, routes) {
+        const agentId = await this.resolveAgentId(agentIdOrName, {}, true);
+        const body = { routes: structuredClone(routes) };
+        const data = await this.agentHttp.put(`${DEPLOYMENTS_API_PREFIX}/${agentId}/routes`, body);
+        return agentRoutesStateFromData(data);
+    }
+    async setRoute(agentIdOrName, name, route) {
+        const agentId = await this.resolveAgentId(agentIdOrName, {}, true);
+        const body = { port: route.port };
+        if (route.auth !== undefined)
+            body.auth = route.auth;
+        if (route.prefix !== undefined)
+            body.prefix = route.prefix;
+        const data = await this.agentHttp.put(`${DEPLOYMENTS_API_PREFIX}/${agentId}/routes/${encodeURIComponent(name)}`, body);
+        return agentRoutesStateFromData(data);
+    }
+    async removeRoute(agentIdOrName, name) {
+        const agentId = await this.resolveAgentId(agentIdOrName, {}, true);
+        const data = await this.agentHttp.delete(`${DEPLOYMENTS_API_PREFIX}/${agentId}/routes/${encodeURIComponent(name)}`);
+        return agentRoutesStateFromData(data);
+    }
     async delete(agentIdOrName) {
         const agentId = await this.resolveAgentId(agentIdOrName);
         return this.agentHttp.delete(`${DEPLOYMENTS_API_PREFIX}/${agentId}`);
@@ -2927,6 +3518,20 @@ export class Deployments {
             ? this.agentHttp.get(path)
             : this.agentHttp.get(path, undefined, requestOptions);
     }
+    async secretNames(agentIdOrName, requestOptions = {}) {
+        const agentId = await this.resolveAgentId(agentIdOrName, requestOptions);
+        const path = `${DEPLOYMENTS_API_PREFIX}/${agentId}/secrets`;
+        return Object.keys(requestOptions).length === 0
+            ? this.agentHttp.get(path)
+            : this.agentHttp.get(path, undefined, requestOptions);
+    }
+    async secret(agentIdOrName, key, requestOptions = {}) {
+        const agentId = await this.resolveAgentId(agentIdOrName, requestOptions);
+        const path = `${DEPLOYMENTS_API_PREFIX}/${agentId}/secrets/${encodeURIComponent(key)}`;
+        return Object.keys(requestOptions).length === 0
+            ? this.agentHttp.get(path)
+            : this.agentHttp.get(path, undefined, requestOptions);
+    }
     async exec(target, command, options = {}) {
         const agentId = await this.agentIdFor(target);
         const payload = {
@@ -2938,21 +3543,6 @@ export class Deployments {
         const data = await this.agentHttp.post(`${DEPLOYMENTS_API_PREFIX}/${agentId}/exec`, payload);
         return execResultFromDict(data);
     }
-    async health(target) {
-        if (!target.executorUrl) {
-            throw new Error('Agent has no executor URL');
-        }
-        const headers = {};
-        if (target.jwtToken) {
-            headers.Authorization = `Bearer ${target.jwtToken}`;
-            headers.Cookie = `${target.podName}-token=${target.jwtToken}`;
-        }
-        const response = await fetch(`${target.executorUrl}/health`, { headers });
-        if (!response.ok) {
-            throw new Error(`Agent health failed: ${response.status} ${response.statusText}`);
-        }
-        return (await response.json());
-    }
     async filesList(target, path = '', source = 'auto') {
         const { suffix, params } = deploymentFileReadRequest(path, source);
         const agentId = await this.agentIdFor(target);