@hypercli.com/sdk 2026.6.26 → 2026.8.11

package/dist/agents.d.ts

@@ -1,7 +1,32 @@
-import { HTTPClient } from './http.js';
-import { GatewayClient, type ChatAttachment, type ChatEvent, type GatewayIntegrationAuthStartParams, type GatewayIntegrationAuthStartResult, type GatewayIntegrationAuthStatusParams, type GatewayIntegrationAuthStatusResult, type GatewayIntegrationDisconnectParams, type GatewayIntegrationDisconnectResult, type GatewayIntegrationStatusParams, type GatewayIntegrationStatusResult, type GatewayOptions, type GatewayWaitReadyOptions, type OpenClawConfigSchemaResponse } from './openclaw/gateway.js';
-export declare const DEFAULT_OPENCLAW_IMAGE = "ghcr.io/hypercli/hypercli-openclaw:prod";
-export declare const DEFAULT_OPENCLAW_PRO_IMAGE = "ghcr.io/hypercli/hypercli-openclaw:pro-prod";
+import { type AgentSlot, type AgentSlotInventory } from './agent-slots.js';
+export { agentSlotFromDict, type AgentSlot, type AgentSlotInventory, type AgentSlotSize, } from './agent-slots.js';
+import { HTTPClient, type RequestOverrides } from './http.js';
+import { GatewayClient, type ChatAttachment, type ChatEvent, type GatewayIntegrationAuthStartParams, type GatewayIntegrationAuthStartResult, type GatewayIntegrationAuthStatusParams, type GatewayIntegrationAuthStatusResult, type GatewayIntegrationDisconnectParams, type GatewayIntegrationDisconnectResult, type GatewayIntegrationStatusParams, type GatewayIntegrationStatusResult, type GatewayOptions, type GatewaySessionsListResult, type GatewayWebLoginStartOptions, type GatewayWebLoginStartResult, type GatewayWebLoginWaitOptions, type GatewayWebLoginWaitResult, type GatewayWaitReadyOptions, type OpenClawConfigSchemaResponse, type OpenClawSlackRelayOptions } from './openclaw/gateway.js';
+import type { OpenClawTelegramConfigPatch, OpenClawWhatsAppConfigPatch } from './openclaw/channels.js';
+import type { OpenClawSlackHttpConfiguration, OpenClawSlackRelayConfiguration, OpenClawSlackSocketConfiguration } from './openclaw/slack.js';
+import { HermesApiClient } from './hermes/gateway.js';
+export declare const DEFAULT_OPENCLAW_IMAGE = "ghcr.io/hypercli/hypercli-openclaw:pro-latest";
+export declare const DEFAULT_OPENCLAW_PRO_IMAGE = "ghcr.io/hypercli/hypercli-openclaw:pro-latest";
+export declare const DEFAULT_HERMES_AGENT_IMAGE = "ghcr.io/hypercli/hypercli-hermes-agent:latest";
+export declare const DEFAULT_OPENCODE_IMAGE = "ghcr.io/hypercli/hypercli-opencode:latest";
+export declare const DEFAULT_CODEX_IMAGE = "ghcr.io/hypercli/hypercli-codex:latest";
+export declare const DEFAULT_CLAUDE_CODE_IMAGE = "ghcr.io/hypercli/hypercli-claude-code:latest";
+export declare const DEFAULT_GOOSE_IMAGE = "ghcr.io/hypercli/hypercli-goose:latest";
+export declare const DEFAULT_KIMI_CODE_IMAGE = "ghcr.io/hypercli/hypercli-kimi-code:latest";
+export declare const DEFAULT_BUZZ_AGENT_IMAGE = "ghcr.io/hypercli/hypercli-buzz-agent:latest";
+export declare const DEFAULT_BUZZ_OPENCODE_IMAGE = "ghcr.io/hypercli/hypercli-buzz-opencode:latest";
+export declare const DEFAULT_BUZZ_CODEX_IMAGE = "ghcr.io/hypercli/hypercli-buzz-codex:latest";
+export declare const DEFAULT_BUZZ_CLAUDE_CODE_IMAGE = "ghcr.io/hypercli/hypercli-buzz-claude:latest";
+export declare const DEFAULT_BUZZ_GOOSE_IMAGE = "ghcr.io/hypercli/hypercli-buzz-goose:latest";
+export declare const DEFAULT_BUZZ_KIMI_CODE_IMAGE = "ghcr.io/hypercli/hypercli-buzz-kimi-code:latest";
+export declare const DEFAULT_AGENT_RUNTIME_SCOPES: readonly string[];
+export declare const DEFAULT_CODING_AGENT_SYNC_ROOT = "/home/node";
+export type ManagedAgentRuntime = 'generic' | 'openclaw' | 'openclaw-pro' | 'hermes-agent' | 'buzz-agent' | 'opencode' | 'codex' | 'claude-code' | 'goose' | 'kimi-code';
+export type CodingAgentRuntime = Extract<ManagedAgentRuntime, 'buzz-agent' | 'opencode' | 'codex' | 'claude-code' | 'goose' | 'kimi-code'>;
+export declare const DEFAULT_CODING_AGENT_IMAGES: Readonly<Record<CodingAgentRuntime, string>>;
+export declare const DEFAULT_CODING_AGENT_SYNC_INCLUDES: Readonly<Record<CodingAgentRuntime, readonly string[]>>;
+export declare const DEFAULT_BUZZ_CODING_AGENT_IMAGES: Readonly<Record<CodingAgentRuntime, string>>;
+export declare const DEFAULT_BUZZ_RUST_LOG = "buzz_acp=info,pool::prompt=info,acp::stream=off";
 export declare const OPENCLAW_MEMORY_SEARCH_ENV_DEFAULTS: {
     readonly OPENCLAW_MEMORY_SEARCH_ENABLED: "1";
     readonly OPENCLAW_MEMORY_SEARCH_SYNC_ON_SESSION_START: "0";
@@ -10,6 +35,14 @@ export declare const OPENCLAW_MEMORY_SEARCH_ENV_DEFAULTS: {
     readonly OPENCLAW_MEMORY_SEARCH_SYNC_WATCH_DEBOUNCE_MS: "30000";
     readonly OPENCLAW_MEMORY_SEARCH_SYNC_INTERVAL_MINUTES: "0";
 };
+export declare const OPENCLAW_WORKSPACES_SYNC_ENV_DEFAULTS: {
+    readonly HYPER_WORKSPACES_BOOT_SYNC: "1";
+    readonly HYPER_WORKSPACES_DIR: "/home/node/shared";
+    readonly HYPER_WORKSPACES_SYNC_READY_ONLY: "1";
+};
+export declare const DEFAULT_HERMES_AGENT_SYNC_ROOT = "/opt/data";
+export declare const DEFAULT_HERMES_AGENT_SYNC_UID = 10000;
+export declare const DEFAULT_HERMES_AGENT_SYNC_GID = 10000;
 export declare const AGENT_FILE_MAX_BYTES: number;
 export declare const AGENT_FILE_TRANSFER_CHUNK_BYTES: number;
 export declare const AGENT_FILE_OPERATION_TIMEOUT_MS = 300000;
@@ -20,19 +53,46 @@ export interface AgentExecResult {
 }
 export interface AgentTokenResponse {
     agent_id?: string;
-    pod_id?: string;
     token?: string;
     jwt?: string;
     expires_at?: string | null;
 }
+export interface BrowserDesktopUrlOptions {
+    redirect?: string | null;
+    resize?: string | null;
+}
 export interface AgentGatewayContext {
-    agent_id?: string;
-    hostname?: string | null;
-    gateway_token?: string | null;
+    agent_id: string;
+    gateway_url: string;
+    gateway_token: string;
+    launch_epoch: number;
+}
+export interface AgentEnvResponse {
+    agent_id: string;
+    env: Record<string, string>;
+    launch_epoch: number;
+}
+export interface AgentSecretNamesResponse {
+    agent_id: string;
+    names: string[];
+    launch_epoch: number;
+}
+export interface AgentSecretResponse {
+    agent_id: string;
+    key: string;
+    value: string;
+    launch_epoch: number;
 }
 export interface GatewayContextWaitOptions {
     timeoutMs?: number;
     retryIntervalMs?: number;
+    signal?: AbortSignal;
+}
+export interface OpenClawOperationsSnapshot {
+    sessions: GatewaySessionsListResult | null;
+    cronJobs: any[] | null;
+    failures: Partial<Record<'sessions' | 'cron', string>>;
+    capturedAt: number;
 }
 export interface AgentShellTokenResponse {
     agent_id?: string;
@@ -42,12 +102,144 @@ export interface AgentShellTokenResponse {
     shell?: string | null;
     dry_run?: boolean;
 }
+export interface AgentShellConnectOptions {
+    signal?: AbortSignal;
+    tokenTimeoutMs?: number;
+    openTimeoutMs?: number;
+}
 export interface AgentLogsTokenResponse {
     agent_id?: string;
     jwt: string;
     expires_at?: string | null;
     ws_url?: string;
 }
+export interface AgentRelayKey {
+    key_id?: string | null;
+    key_name?: string | null;
+    tags?: string[];
+    api_key?: string | null;
+    api_key_preview?: string | null;
+    last4?: string | null;
+    [key: string]: any;
+}
+export interface AgentProfileImageUploadResult {
+    id: string;
+    avatar_url: string | null;
+    s3_key: string | null;
+}
+export interface BootstrapInferenceMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+export interface BootstrapInferenceResponseFormat {
+    type: 'text' | 'json_object' | 'json_schema';
+    json_schema?: {
+        name: string;
+        description?: string;
+        strict?: boolean;
+        schema: Record<string, unknown>;
+    };
+}
+export interface BootstrapInferenceResult {
+    model: string;
+    content: string;
+    finish_reason: string | null;
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+}
+export interface ListAgentsOptions extends RequestOverrides {
+    state?: string | null;
+    handle?: string | null;
+    name?: string | null;
+    query?: string | null;
+    includeDeleted?: boolean | null;
+}
+export interface AgentCapacity {
+    items: Agent[];
+    totalAgents: number;
+    maxAgentsPerAccount: number;
+    runningAgents: number;
+    slots: Record<string, AgentSlotInventory>;
+    agentSlots: AgentSlot[];
+    pooledTpd: number;
+}
+export interface SlackOAuthStartOptions {
+    relayBaseUrl: string;
+    token: string;
+}
+export interface SlackOAuthStartResult {
+    authorizeUrl: string;
+    expiresAt?: string | null;
+}
+export interface SlackInstallStatusOptions {
+    relayBaseUrl: string;
+    token: string;
+}
+export interface SlackInstallStatus {
+    connected: boolean;
+    teamId?: string | null;
+    teamName?: string | null;
+    botUserId?: string | null;
+    installerUserId?: string | null;
+    updatedAt?: string | null;
+}
+export interface SlackDirectoryOptions {
+    relayBaseUrl: string;
+    token: string;
+    cursor?: string | null;
+    limit?: number | null;
+}
+export interface SlackDirectoryConversationsOptions extends SlackDirectoryOptions {
+    types?: string | null;
+}
+export interface SlackDirectoryConversation {
+    id: string;
+    name?: string | null;
+    isChannel?: boolean | null;
+    isGroup?: boolean | null;
+    isIm?: boolean | null;
+    isMpim?: boolean | null;
+    isMember?: boolean | null;
+    isPrivate?: boolean | null;
+}
+export interface SlackDirectoryUser {
+    id: string;
+    name?: string | null;
+    realName?: string | null;
+    teamId?: string | null;
+    isBot?: boolean | null;
+    deleted?: boolean | null;
+}
+export interface SlackDirectoryConversationsResult {
+    conversations: SlackDirectoryConversation[];
+    nextCursor?: string | null;
+}
+export interface SlackDirectoryUsersResult {
+    users: SlackDirectoryUser[];
+    nextCursor?: string | null;
+}
+export interface AttachSlackRelayAgentOptions {
+    relayBaseUrl: string;
+    token: string;
+    agentId: string;
+}
+export interface AttachSlackRelayAgentResult {
+    connected: boolean;
+    agentId: string;
+    gatewayId: string;
+    config: Record<string, unknown>;
+    restartRequired: boolean;
+    teamId?: string | null;
+    teamName?: string | null;
+    botUserId?: string | null;
+}
+export interface AttachDeploymentSlackRelayAgentOptions {
+    relayBaseUrl: string;
+    token?: string;
+}
 export interface BraveWebSearchOptions {
     count?: number;
     country?: string;
@@ -67,8 +259,17 @@ export interface AgentRouteConfig {
     port: number;
     prefix?: string;
     auth?: boolean;
-    strip_prefix?: boolean;
-    [key: string]: any;
+}
+export interface AgentRoutesState {
+    agentId: string;
+    routes: Record<string, AgentRouteConfig>;
+    routeStatuses: Record<string, Record<string, unknown>>;
+}
+export type LaunchConfigFlatMap = Record<string, unknown>;
+export interface AgentDesktopConfigSource {
+    launchConfig?: unknown;
+    launch_config?: unknown;
+    routes?: unknown;
 }
 export interface RegistryAuth {
     username?: string;
@@ -78,21 +279,26 @@ export interface RegistryAuth {
 }
 export interface BuildAgentConfigOptions {
     env?: Record<string, string>;
-    ports?: Record<string, any>[] | null;
+    secrets?: Record<string, string>;
     routes?: Record<string, AgentRouteConfig> | null;
     command?: string[] | null;
     entrypoint?: string[] | null;
     image?: string | null;
     syncRoot?: string | null;
-    syncEnabled?: boolean | null;
+    syncInclude?: readonly string[] | null;
+    syncExclude?: readonly string[] | null;
     syncUid?: number | null;
     syncGid?: number | null;
     registryUrl?: string | null;
     registryAuth?: RegistryAuth | null;
+    restart?: boolean | null;
+    runtimeScopes?: readonly string[] | null;
     gatewayToken?: string | null;
     heartbeat?: OpenClawHeartbeatConfig | null;
     /** Disable to avoid automatically locking browser control UI access to globalThis.location.origin. */
     controlUiOriginLock?: boolean | null;
+    /** Internal launch behavior; coding runtimes do not use the OpenClaw gateway. */
+    injectGatewayToken?: boolean;
 }
 export interface OpenClawRouteOptions {
     includeGateway?: boolean;
@@ -104,6 +310,11 @@ export interface OpenClawRouteOptions {
     gatewayPrefix?: string;
     desktopPrefix?: string;
 }
+export interface HermesAgentRouteOptions {
+    port?: number;
+    auth?: boolean;
+    prefix?: string;
+}
 export interface OpenClawMemoryIndexOptions {
     enabled?: boolean | null;
     onSessionStart?: boolean | null;
@@ -112,6 +323,11 @@ export interface OpenClawMemoryIndexOptions {
     watchDebounceMs?: number | null;
     intervalMinutes?: number | null;
 }
+export interface OpenClawWorkspacesSyncOptions {
+    enabled?: boolean | null;
+    readyOnly?: boolean | null;
+    workspace?: string | null;
+}
 export interface OpenClawHeartbeatConfig {
     every?: string;
     model?: string;
@@ -137,7 +353,6 @@ export interface AgentUiAvatarMeta {
 }
 export interface AgentUiMeta {
     avatar?: AgentUiAvatarMeta | null;
-    [key: string]: any;
 }
 export interface AgentMeta {
     ui?: AgentUiMeta | null;
@@ -193,12 +408,30 @@ export interface OpenClawModelProviderConfig {
 export type OpenClawModelProviderPatch = Partial<Omit<OpenClawModelProviderConfig, 'baseUrl'>> & Pick<OpenClawModelProviderConfig, 'baseUrl'>;
 export interface CreateAgentOptions extends BuildAgentConfigOptions {
     name?: string;
+    handle?: string | null;
     size?: string;
     config?: Record<string, any>;
     meta?: AgentMeta | null;
     tags?: string[];
     dryRun?: boolean;
     start?: boolean;
+    runtime?: ManagedAgentRuntime;
+}
+export interface CreateExternalAgentOptions {
+    name: string;
+    displayName?: string | null;
+    handle?: string | null;
+    runtime?: string;
+    status?: string;
+    meta?: Record<string, any> | null;
+}
+export interface UpdateExternalAgentOptions {
+    name?: string | null;
+    displayName?: string | null;
+    handle?: string | null;
+    runtime?: 'openclaw' | null;
+    status?: 'active' | 'inactive' | 'error' | null;
+    meta?: Record<string, any> | null;
 }
 export interface StartAgentOptions extends BuildAgentConfigOptions {
     config?: Record<string, any>;
@@ -206,19 +439,79 @@ export interface StartAgentOptions extends BuildAgentConfigOptions {
 }
 export interface UpdateAgentOptions {
     name?: string;
+    handle?: string | null;
     size?: string;
+    launchConfig?: Record<string, any> | null;
     refreshFromLagoon?: boolean;
-    lastError?: string | null;
+    error?: string | null;
 }
 export interface OpenClawCreateAgentOptions extends CreateAgentOptions {
     openClawRoutes?: OpenClawRouteOptions | null;
     heartbeat?: OpenClawHeartbeatConfig | null;
     memoryIndex?: OpenClawMemoryIndexOptions | null;
+    workspacesSync?: OpenClawWorkspacesSyncOptions | boolean | null;
 }
 export interface OpenClawStartAgentOptions extends StartAgentOptions {
     openClawRoutes?: OpenClawRouteOptions | null;
     heartbeat?: OpenClawHeartbeatConfig | null;
     memoryIndex?: OpenClawMemoryIndexOptions | null;
+    workspacesSync?: OpenClawWorkspacesSyncOptions | boolean | null;
+}
+export interface HermesAgentCreateOptions extends CreateAgentOptions {
+    hermesRoute?: HermesAgentRouteOptions | null;
+    /** Explicit inbound Hermes API credential; a fresh 32-byte key is generated when omitted. */
+    apiServerKey?: string | null;
+}
+export interface HermesAgentStartOptions extends StartAgentOptions {
+    hermesRoute?: HermesAgentRouteOptions | null;
+    /** Explicit inbound Hermes API credential; a fresh 32-byte key is generated when omitted. */
+    apiServerKey?: string | null;
+}
+export interface CodingAgentCreateOptions extends Omit<CreateAgentOptions, 'runtime' | 'injectGatewayToken'> {
+    workspacesSync?: OpenClawWorkspacesSyncOptions | boolean | null;
+    /** @deprecated Use the typed `buzz` launch contract. */
+    buzzEnabled?: boolean;
+    /** Launch Buzz ACP with runtime-specific harness and MCP defaults. */
+    buzz?: BuzzLaunchConfig | null;
+}
+export interface BuzzLaunchConfig {
+    privateKeyNsec: string;
+    relayUrl: string;
+    authTag?: string | null;
+    systemPrompt?: string | null;
+    model?: string | null;
+    idleTimeoutSeconds?: number | null;
+    maxTurnDurationSeconds?: number | null;
+    parallelism?: number;
+    respondTo?: string | null;
+    respondToAllowlist?: string[];
+    displayName?: string | null;
+    textMentions?: boolean;
+    requireReply?: boolean;
+    sessionTitle?: string | null;
+    rustLog?: string;
+}
+export interface RuntimeAuthMethod {
+    id: string;
+    name: string;
+    description: string;
+    kind: string;
+    command: string[];
+    metadata: Record<string, unknown>;
+}
+export interface RuntimeAuthStatus {
+    authenticated: boolean;
+    provider?: string | null;
+    account?: string | null;
+    method?: string | null;
+    detail: Record<string, unknown>;
+}
+export interface RuntimeAuthLoginOptions {
+    method?: string;
+    provider?: string;
+    providerMethod?: string;
+    email?: string;
+    challengeTimeoutMs?: number;
 }
 export interface AgentExecOptions {
     timeout?: number;
@@ -230,9 +523,92 @@ export interface AgentFileEntry {
     type: 'file' | 'directory';
     size?: number;
     size_formatted?: string;
+    mime_type?: string;
+    mimeType?: string;
+    content_type?: string;
+    contentType?: string;
     last_modified?: string;
+    checksum?: string;
+    checksum_algorithm?: string;
+    checksumAlgorithm?: string;
+    hash?: string;
+    hash_algorithm?: string;
+    hashAlgorithm?: string;
+    sha256?: string;
+    sha_256?: string;
+    md5?: string;
+    etag?: string;
+    version_id?: string;
+    versionId?: string;
+    source?: AgentFileSource;
     [key: string]: any;
 }
+export interface AgentFileReadOptions {
+    maxBytes?: number;
+    signal?: AbortSignal;
+}
+export interface AgentFileReadBytesResult {
+    content: Uint8Array;
+    mimeType?: string;
+}
+/**
+ * The three file-access paths for an OpenClaw agent, each with its own root —
+ * the SDK owns the roots so a workspace-relative path (e.g. `"AGENTS.md"`) hits
+ * the same file on all three:
+ * - `agent`  — the files API on the agent's live pod filesystem. A
+ *              workspace-relative path resolves under the workspace, while an
+ *              absolute `/…` path can be listed/read anywhere on the pod.
+ *              Writes under the sync root are supported. (wire `source=pod`)
+ * - `backup` — the S3 backup of the sync root (`/home/node`); served when the
+ *              pod is stopped. Scoped to the sync root. (wire `source=s3`)
+ * - `gateway`— the operator-WebSocket `agents.files.*` RPC; scoped to the
+ *              `.openclaw/workspace` (name-addressed; no delete). Works on any
+ *              gateway, self-hosted included.
+ * - `auto`   — backend default: the agent while running, else the backup.
+ *
+ * `pod`/`s3` are accepted as deprecated aliases of `agent`/`backup`.
+ */
+export type AgentFileSource = 'auto' | 'agent' | 'backup' | 'gateway' | 'pod' | 's3';
+/** @deprecated Alias of {@link AgentFileSource}; gateway is a base capability now. */
+export type OpenClawFileSource = AgentFileSource;
+/** The backend (non-gateway) file sources — the deployment HTTP files store. */
+export type AgentFileBackendSource = Exclude<AgentFileSource, 'gateway'>;
+/** The value the deployment HTTP API accepts on the wire (`source`/`destination`). */
+export type AgentFileWireSource = 'auto' | 'pod' | 's3';
+/** The agent's sync root and workspace, owned by the SDK so paths are unambiguous. */
+export declare const OPENCLAW_SYNC_ROOT = "/home/node";
+export declare const OPENCLAW_WORKSPACE_PREFIX = ".openclaw/workspace";
+/** Map the friendly `agent`/`backup` names to their on-the-wire `pod`/`s3` values. */
+export declare function toWireFileSource(source: AgentFileBackendSource): AgentFileWireSource;
+/** Hooks an OpenClaw agent provides so AgentFiles can reach its gateway. */
+export interface AgentFilesGatewayHooks {
+    withGateway<T>(fn: (client: GatewayClient) => Promise<T>): Promise<T>;
+    resolveAgentId(client: GatewayClient): Promise<string>;
+}
+/**
+ * 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 declare class AgentFiles {
+    private readonly agent;
+    private readonly deployments;
+    private readonly gatewayHooks?;
+    constructor(agent: Agent, deployments: Deployments, gatewayHooks?: AgentFilesGatewayHooks | undefined);
+    private requireGateway;
+    list(path?: string, source?: OpenClawFileSource): Promise<AgentFileEntry[]>;
+    readBytes(path: string, source?: OpenClawFileSource, options?: AgentFileReadOptions): Promise<Uint8Array>;
+    readBytesWithMetadata(path: string, source?: OpenClawFileSource, options?: AgentFileReadOptions): Promise<AgentFileReadBytesResult>;
+    read(path: string, source?: OpenClawFileSource, options?: AgentFileReadOptions): Promise<string>;
+    writeBytes(path: string, content: Uint8Array | ArrayBuffer | string, source?: OpenClawFileSource): Promise<Record<string, any>>;
+    write(path: string, content: string, source?: OpenClawFileSource): Promise<Record<string, any>>;
+    delete(path: string, options?: {
+        recursive?: boolean;
+        source?: OpenClawFileSource;
+    }): Promise<Record<string, any>>;
+}
 export interface AgentDirectoryListing {
     type: 'directory';
     prefix: string;
@@ -241,13 +617,45 @@ export interface AgentDirectoryListing {
     truncated?: boolean;
     [key: string]: any;
 }
+export type AgentState = 'CREATING' | 'STARTING' | 'RESTORING' | 'RUNNING' | 'STOPPING' | 'STOPPED' | 'ARCHIVING' | 'ARCHIVED' | 'FAILED' | 'DELETED' | (string & {});
+/** Canonical states understood by this SDK. AgentState remains forward-open. */
+export declare const CANONICAL_AGENT_STATES: readonly ["CREATING", "STARTING", "RESTORING", "RUNNING", "STOPPING", "STOPPED", "ARCHIVING", "ARCHIVED", "FAILED", "DELETED"];
+export declare const AGENT_TRANSITIONAL_STATES: ReadonlySet<AgentState>;
+export declare const AGENT_RUNTIME_INACTIVE_STATES: ReadonlySet<AgentState>;
+export declare function isAgentTransitionalState(state: string): boolean;
+export declare function isAgentRuntimeInactiveState(state: string): boolean;
+export interface DeploymentTransitionEvent {
+    type: 'deployment.transition';
+    agent_id: string;
+    state?: AgentState;
+    reason?: string | null;
+    error?: string | null;
+    message?: string | null;
+    launch_epoch?: number;
+    resources_exist?: boolean;
+    namespace_exists?: boolean;
+}
+export type DeploymentEvent = DeploymentTransitionEvent;
+export interface DeploymentSubscribeOptions {
+    signal?: AbortSignal;
+    /** Runs after socket authentication and before transition frames are read. */
+    onReady?: () => void | Promise<void>;
+}
 export interface AgentStateFields {
     id: string;
     userId: string;
-    podId: string;
-    podName: string;
-    state: string;
+    state: AgentState;
     name?: string | null;
+    handle?: string | null;
+    displayName?: string | null;
+    avatarUrl?: string | null;
+    displayIdentity?: Record<string, any> | null;
+    runtime?: string | null;
+    managed?: boolean | null;
+    isLaunchable?: boolean;
+    gatewayId?: string | null;
+    runtimeKeyAlias?: string | null;
+    relayKey?: AgentRelayKey | null;
     cpu: number;
     memory: number;
     hostname?: string | null;
@@ -256,7 +664,9 @@ export interface AgentStateFields {
     jwtExpiresAt?: Date | null;
     startedAt?: Date | null;
     stoppedAt?: Date | null;
-    lastError?: string | null;
+    archivedAt?: Date | null;
+    clusterId?: string | null;
+    launchEpoch?: number;
     createdAt?: Date | null;
     updatedAt?: Date | null;
     launchConfig?: Record<string, any> | null;
@@ -264,16 +674,23 @@ export interface AgentStateFields {
     routes: Record<string, AgentRouteConfig>;
     command: string[];
     entrypoint: string[];
-    ports: Record<string, any>[];
     dryRun: boolean;
 }
 export interface AgentHydrationData {
     id?: string;
     user_id?: string;
-    pod_id?: string;
-    pod_name?: string;
-    state?: string;
+    state?: AgentState;
     name?: string | null;
+    handle?: string | null;
+    display_name?: string | null;
+    avatar_url?: string | null;
+    display_identity?: Record<string, any> | null;
+    runtime?: string | null;
+    managed?: boolean | null;
+    is_launchable?: boolean;
+    gateway_id?: string | null;
+    runtime_key_alias?: string | null;
+    relay_key?: AgentRelayKey | null;
     cpu?: number;
     memory?: number;
     hostname?: string | null;
@@ -282,7 +699,9 @@ export interface AgentHydrationData {
     jwt_expires_at?: string | null;
     started_at?: string | null;
     stopped_at?: string | null;
-    last_error?: string | null;
+    archived_at?: string | null;
+    cluster_id?: string | null;
+    launch_epoch?: number;
     created_at?: string | null;
     updated_at?: string | null;
     launch_config?: Record<string, any> | null;
@@ -292,27 +711,46 @@ export interface AgentHydrationData {
     routes?: Record<string, AgentRouteConfig> | null;
     command?: string[] | null;
     entrypoint?: string[] | null;
-    ports?: Record<string, any>[] | null;
     dry_run?: boolean;
     openclaw_url?: string | null;
     gateway_url?: string | null;
-    gateway_token?: string | null;
     [key: string]: any;
 }
+export declare function flattenLaunchConfig(launchConfig: unknown): LaunchConfigFlatMap;
+export declare function getLaunchConfigValue(launchConfig: unknown, path: string | Array<string | number>): unknown;
+export declare function routesHaveDesktop(routes: unknown): boolean;
+export declare function launchConfigHasDesktop(launchConfig: unknown): boolean;
+export declare function agentConfigHasDesktop(source: AgentDesktopConfigSource | null | undefined): boolean;
+export declare function buildBrowserDesktopUrl(desktopBaseUrl: string, token: string, options?: BrowserDesktopUrlOptions): string;
 export declare function resolveAgentsApiBase(apiBase: string): string;
 export declare function buildAgentConfig(config?: Record<string, any>, options?: BuildAgentConfigOptions): {
     config: Record<string, any>;
-    gatewayToken: string;
+    gatewayToken: string | null;
 };
+export declare function startSlackOAuth(options: SlackOAuthStartOptions): Promise<SlackOAuthStartResult>;
+export declare function getSlackInstallStatus(options: SlackInstallStatusOptions): Promise<SlackInstallStatus>;
+export declare function listSlackDirectoryConversations(options: SlackDirectoryConversationsOptions): Promise<SlackDirectoryConversationsResult>;
+export declare function listSlackDirectoryUsers(options: SlackDirectoryOptions): Promise<SlackDirectoryUsersResult>;
+export declare function attachSlackRelayAgent(options: AttachSlackRelayAgentOptions): Promise<AttachSlackRelayAgentResult>;
 export declare function buildOpenClawRoutes(options?: OpenClawRouteOptions): Record<string, AgentRouteConfig>;
+export declare function buildHermesAgentRoutes(options?: HermesAgentRouteOptions): Record<string, AgentRouteConfig>;
 export declare function buildOpenClawMemoryIndexEnv(memoryIndex?: OpenClawMemoryIndexOptions | null): Record<string, string>;
+export declare function buildOpenClawWorkspacesSyncEnv(workspacesSync?: OpenClawWorkspacesSyncOptions | boolean | null): Record<string, string>;
 export declare class Agent {
     readonly id: string;
     readonly userId: string;
-    readonly podId: string;
-    readonly podName: string;
     readonly state: string;
     readonly name: string | null;
+    readonly handle: string | null;
+    readonly displayName: string | null;
+    readonly avatarUrl: string | null;
+    readonly displayIdentity: Record<string, any> | null;
+    readonly runtime: string | null;
+    readonly managed: boolean | null;
+    readonly isLaunchable: boolean;
+    readonly gatewayId: string | null;
+    readonly runtimeKeyAlias: string | null;
+    readonly relayKey: AgentRelayKey | null;
     readonly cpu: number;
     readonly memory: number;
     readonly hostname: string | null;
@@ -321,7 +759,9 @@ export declare class Agent {
     jwtExpiresAt: Date | null;
     readonly startedAt: Date | null;
     readonly stoppedAt: Date | null;
-    readonly lastError: string | null;
+    readonly archivedAt: Date | null;
+    readonly clusterId: string | null;
+    readonly launchEpoch: number;
     readonly createdAt: Date | null;
     readonly updatedAt: Date | null;
     launchConfig: Record<string, any> | null;
@@ -329,7 +769,6 @@ export declare class Agent {
     routes: Record<string, AgentRouteConfig>;
     command: string[];
     entrypoint: string[];
-    ports: Record<string, any>[];
     readonly dryRun: boolean;
     _deployments: Deployments | null;
     constructor(fields: AgentStateFields);
@@ -339,9 +778,15 @@ export declare class Agent {
     routeUrl(routeName: string, defaultPrefix?: string | null): string | null;
     get desktopUrl(): string | null;
     get vncUrl(): string | null;
+    browserDesktopUrl(token: string, options?: BrowserDesktopUrlOptions): string | null;
     get shellUrl(): string | null;
-    get executorUrl(): string | null;
     get isRunning(): boolean;
+    get isTransitioning(): boolean;
+    /** True when the agent is cold-restorable from its verified archive. */
+    get isArchived(): boolean;
+    /** True only for an explicitly included deletion tombstone. */
+    get isDeleted(): boolean;
+    get hasDesktop(): boolean;
     protected requireDeployments(): Deployments;
     routeRequiresAuth(routeName: string, defaultValue?: boolean): boolean;
     refreshToken(): Promise<AgentTokenResponse>;
@@ -349,19 +794,120 @@ export declare class Agent {
     update(options: UpdateAgentOptions): Promise<Agent>;
     resize(options: Pick<UpdateAgentOptions, 'size'>): Promise<Agent>;
     env(): Promise<Record<string, string>>;
+    secretNames(): Promise<string[]>;
+    secret(key: string): Promise<string>;
     exec(command: string, options?: AgentExecOptions): Promise<AgentExecResult>;
-    health(): Promise<Record<string, any>>;
-    filesList(path?: string, source?: 'auto' | 'pod' | 's3'): Promise<AgentFileEntry[]>;
-    fileReadBytes(path: string, source?: 'auto' | 'pod' | 's3'): Promise<Uint8Array>;
-    fileRead(path: string, source?: 'auto' | 'pod' | 's3'): Promise<string>;
-    fileWriteBytes(path: string, content: Uint8Array | ArrayBuffer | string, destination?: 'auto' | 'pod' | 's3'): Promise<Record<string, any>>;
-    fileWrite(path: string, content: string, destination?: 'auto' | 'pod' | 's3'): Promise<Record<string, any>>;
+    /**
+     * 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.
+     */
+    protected gatewayFileHooks(): AgentFilesGatewayHooks | 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(): AgentFiles;
+    filesList(path?: string, source?: AgentFileSource): Promise<AgentFileEntry[]>;
+    fileReadBytes(path: string, source?: AgentFileSource, options?: AgentFileReadOptions): Promise<Uint8Array>;
+    fileReadBytesWithMetadata(path: string, source?: AgentFileSource, options?: AgentFileReadOptions): Promise<AgentFileReadBytesResult>;
+    fileRead(path: string, source?: AgentFileSource, options?: AgentFileReadOptions): Promise<string>;
+    fileWriteBytes(path: string, content: Uint8Array | ArrayBuffer | string, destination?: AgentFileSource): Promise<Record<string, any>>;
+    fileWrite(path: string, content: string, destination?: AgentFileSource): Promise<Record<string, any>>;
     fileDelete(path: string, options?: {
         recursive?: boolean;
+        source?: AgentFileSource;
     }): Promise<Record<string, any>>;
     cpTo(localPath: string, remotePath: string): Promise<Record<string, any>>;
     cpFrom(remotePath: string, localPath: string): Promise<string>;
-    shellConnect(shell?: string): Promise<WebSocket>;
+    shellConnect(shell?: string, options?: AgentShellConnectOptions): Promise<WebSocket>;
+}
+export declare class RuntimeLoginSession {
+    private readonly authClient;
+    readonly socket: WebSocket;
+    private readonly requiresDeviceChallenge;
+    output: string;
+    verificationUrl: string | null;
+    userCode: string | null;
+    interactiveRequired: boolean;
+    private rawOutput;
+    private exitCode;
+    private readonly marker;
+    private readonly completion;
+    private readonly ready;
+    private complete;
+    private markReady;
+    private constructor();
+    static start(authClient: RuntimeAuthClient, command: string[], challengeTimeoutMs?: number, requiresDeviceChallenge?: boolean): Promise<RuntimeLoginSession>;
+    private consume;
+    send(text: string): void;
+    wait(timeoutMs?: number): Promise<RuntimeAuthStatus>;
+    cancel(): void;
+}
+export declare class RuntimeAuthClient {
+    readonly agent: CodingAgent;
+    private readonly config;
+    constructor(agent: CodingAgent);
+    methods(): Promise<RuntimeAuthMethod[]>;
+    status(): Promise<RuntimeAuthStatus>;
+    login(options?: RuntimeAuthLoginOptions): Promise<RuntimeLoginSession>;
+    logout(provider?: string): Promise<RuntimeAuthStatus>;
+}
+export declare class CodingAgent extends Agent {
+    readonly runtime: CodingAgentRuntime;
+    static readonly defaultSyncInclude: readonly string[] | null;
+    get auth(): RuntimeAuthClient;
+}
+export declare class BuzzAgent extends CodingAgent {
+    readonly runtime: 'buzz-agent';
+    static readonly defaultSyncInclude: readonly string[];
+    static fromDict(data: AgentHydrationData): BuzzAgent;
+}
+export declare class OpenCodeAgent extends CodingAgent {
+    readonly runtime: 'opencode';
+    static readonly defaultSyncInclude: readonly string[];
+    static fromDict(data: AgentHydrationData): OpenCodeAgent;
+}
+export declare class CodexAgent extends CodingAgent {
+    readonly runtime: 'codex';
+    static readonly defaultSyncInclude: readonly string[];
+    static fromDict(data: AgentHydrationData): CodexAgent;
+}
+export declare class ClaudeCodeAgent extends CodingAgent {
+    readonly runtime: 'claude-code';
+    static readonly defaultSyncInclude: readonly string[];
+    static fromDict(data: AgentHydrationData): ClaudeCodeAgent;
+}
+export declare class GooseAgent extends CodingAgent {
+    readonly runtime: 'goose';
+    static readonly defaultSyncInclude: readonly string[];
+    static fromDict(data: AgentHydrationData): GooseAgent;
+}
+export declare class KimiCodeAgent extends CodingAgent {
+    readonly runtime: 'kimi-code';
+    static readonly defaultSyncInclude: readonly string[];
+    static fromDict(data: AgentHydrationData): KimiCodeAgent;
+}
+export declare class HermesAgent extends Agent {
+    readonly runtime: 'hermes-agent';
+    readonly apiUrl: string | null;
+    readonly openaiBaseUrl: string | null;
+    /** Available only on the instance returned by createHermesAgent/startHermesAgent. */
+    apiServerKey: string | null;
+    constructor(fields: AgentStateFields & {
+        apiUrl?: string | null;
+        apiServerKey?: string | null;
+    });
+    static fromDict(data: AgentHydrationData): HermesAgent;
+    /** Create a client for this agent's authenticated Hermes API. */
+    get api(): HermesApiClient | null;
+    /** Require a ready URL and the one-time SDK-retained API server key. */
+    apiClient(): HermesApiClient;
+    waitRunning(timeoutMs?: number, pollIntervalMs?: number): Promise<HermesAgent>;
 }
 export declare class OpenClawAgent extends Agent {
     gatewayUrl: string | null;
@@ -371,46 +917,67 @@ export declare class OpenClawAgent extends Agent {
         gatewayToken?: string | null;
     });
     static fromDict(data: AgentHydrationData): OpenClawAgent;
-    private static gatewayUrlFromHostname;
-    private currentGatewayHostname;
-    /**
-     * 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.
-     */
+    protected static gatewayUrlFromHostname(hostname: string | null | undefined): string | null;
+    /** Resolve OpenClaw connection context from the generic Agent and Secret APIs. */
     waitForGatewayContext(options?: GatewayContextWaitOptions): Promise<AgentGatewayContext>;
     resolveGatewayToken(): Promise<string | null>;
     gateway(options?: Omit<Partial<GatewayOptions>, 'url' | 'token'>): GatewayClient;
     connect(options?: Omit<Partial<GatewayOptions>, 'url' | 'token'>): Promise<GatewayClient>;
+    /** Run a fn against a connected gateway client, then close it. */
+    private withGateway;
+    private _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.
+     */
+    private resolveGatewayAgentId;
+    /**
+     * 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.
+     */
+    protected gatewayFileHooks(): AgentFilesGatewayHooks;
     gatewayStatus(options?: Omit<Partial<GatewayOptions>, 'url' | 'token'>): Promise<Record<string, any>>;
     waitReady(timeoutMs?: number, options?: Omit<Partial<GatewayOptions>, 'url' | 'token'> & GatewayWaitReadyOptions): Promise<Record<string, any>>;
     configGet(options?: Omit<Partial<GatewayOptions>, 'url' | 'token'>): Promise<Record<string, any>>;
     configSchema(options?: Omit<Partial<GatewayOptions>, 'url' | 'token'>): Promise<OpenClawConfigSchemaResponse>;
     configPatch(patch: Record<string, any>, options?: Omit<Partial<GatewayOptions>, 'url' | 'token'>): Promise<void>;
+    configureSlackRelay(options: (Omit<OpenClawSlackRelayOptions, 'gatewayId'> & {
+        gatewayId?: string;
+    }) | OpenClawSlackRelayConfiguration, gatewayOptions?: Omit<Partial<GatewayOptions>, 'url' | 'token'> & {
+        accountId?: string;
+    }): Promise<void>;
+    configureSlackSocket(config: OpenClawSlackSocketConfiguration, options?: Omit<Partial<GatewayOptions>, 'url' | 'token'> & {
+        accountId?: string;
+    }): Promise<void>;
+    configureSlackHttp(config: OpenClawSlackHttpConfiguration, options?: Omit<Partial<GatewayOptions>, 'url' | 'token'> & {
+        accountId?: string;
+    }): Promise<void>;
+    configureTelegram(config: OpenClawTelegramConfigPatch, options?: Omit<Partial<GatewayOptions>, 'url' | 'token'> & {
+        accountId?: string;
+    }): Promise<void>;
+    configureWhatsapp(config: OpenClawWhatsAppConfigPatch, options?: Omit<Partial<GatewayOptions>, 'url' | 'token'> & {
+        accountId?: string;
+    }): Promise<void>;
     configApply(config: Record<string, any>, options?: Omit<Partial<GatewayOptions>, 'url' | 'token'>): Promise<void>;
     modelsList(options?: Omit<Partial<GatewayOptions>, 'url' | 'token'>): Promise<any[]>;
     sessionsList(options?: Omit<Partial<GatewayOptions>, 'url' | 'token'>): Promise<any[]>;
+    sessionsListResult(options?: Omit<Partial<GatewayOptions>, 'url' | 'token'>): Promise<GatewaySessionsListResult>;
+    operationsSnapshot(options?: Omit<Partial<GatewayOptions>, 'url' | 'token'>): Promise<OpenClawOperationsSnapshot>;
     chatSend(message: string, sessionKey: string, options?: Omit<Partial<GatewayOptions>, 'url' | 'token'> & {
         attachments?: ChatAttachment[];
     }): AsyncGenerator<ChatEvent>;
     channelsStatus(options?: Omit<Partial<GatewayOptions>, 'url' | 'token'> & {
         probe?: boolean;
         timeoutMs?: number;
+        channel?: string;
     }): Promise<Record<string, any>>;
+    channelsStart(channel: string, accountId?: string, options?: Omit<Partial<GatewayOptions>, 'url' | 'token'>): Promise<Record<string, any>>;
+    channelsStop(channel: string, accountId?: string, options?: Omit<Partial<GatewayOptions>, 'url' | 'token'>): Promise<Record<string, any>>;
     channelsLogout(channel: string, accountId?: string, options?: Omit<Partial<GatewayOptions>, 'url' | 'token'>): Promise<Record<string, any>>;
-    webLoginStart(options?: Omit<Partial<GatewayOptions>, 'url' | 'token'> & {
-        force?: boolean;
-        timeoutMs?: number;
-        verbose?: boolean;
-        accountId?: string;
-    }): Promise<Record<string, any>>;
-    webLoginWait(options?: Omit<Partial<GatewayOptions>, 'url' | 'token'> & {
-        timeoutMs?: number;
-        accountId?: string;
-    }): Promise<Record<string, any>>;
+    webLoginStart(options?: Omit<Partial<GatewayOptions>, 'url' | 'token'> & GatewayWebLoginStartOptions): Promise<GatewayWebLoginStartResult>;
+    webLoginWait(options?: Omit<Partial<GatewayOptions>, 'url' | 'token'> & GatewayWebLoginWaitOptions): Promise<GatewayWebLoginWaitResult>;
     integrationsAuthStart(params: GatewayIntegrationAuthStartParams, options?: Omit<Partial<GatewayOptions>, 'url' | 'token'>): Promise<GatewayIntegrationAuthStartResult>;
     integrationsAuthStatus(params: GatewayIntegrationAuthStatusParams, options?: Omit<Partial<GatewayOptions>, 'url' | 'token'>): Promise<GatewayIntegrationAuthStatusResult>;
     integrationsStatus(params?: GatewayIntegrationStatusParams, options?: Omit<Partial<GatewayOptions>, 'url' | 'token'>): Promise<GatewayIntegrationStatusResult>;
@@ -456,6 +1023,9 @@ export declare class OpenClawAgent extends Agent {
         accountId?: string;
     }): Promise<Record<string, any>>;
     cronList(options?: Omit<Partial<GatewayOptions>, 'url' | 'token'>): Promise<any[]>;
+    cronAdd(job: Record<string, any>, options?: Omit<Partial<GatewayOptions>, 'url' | 'token'>): Promise<any>;
+    cronRemove(jobId: string, options?: Omit<Partial<GatewayOptions>, 'url' | 'token'>): Promise<void>;
+    cronRun(jobId: string, options?: Omit<Partial<GatewayOptions>, 'url' | 'token'>): Promise<any>;
 }
 export declare class OpenClawProAgent extends OpenClawAgent {
     static fromDict(data: AgentHydrationData): OpenClawProAgent;
@@ -466,52 +1036,90 @@ export declare class Deployments {
     private readonly apiBase;
     private readonly agentsWsUrl;
     private readonly agentHttp;
-    constructor(http: HTTPClient, agentApiKey?: string, agentApiBase?: string, agentsWsUrl?: string);
+    constructor(http: HTTPClient, agentApiKey?: string, agentApiBase?: string, agentsWsUrl?: string, requestTimeout?: number);
     get agentApiKey(): string;
     get agentApiBase(): string;
     private hydrateAgent;
+    private getById;
+    resolveAgent(agentIdOrName: string, requestOptions?: RequestOverrides): Promise<Agent>;
+    resolveAgentId(agentIdOrName: string, requestOptions?: RequestOverrides, allowSelf?: boolean): Promise<string>;
     private agentIdFor;
     private fetchRaw;
     create(options?: CreateAgentOptions): Promise<Agent>;
     createOpenClaw(options?: OpenClawCreateAgentOptions): Promise<Agent>;
+    createHermesAgent(options?: HermesAgentCreateOptions): Promise<HermesAgent>;
     createOpenClawPro(options?: OpenClawCreateAgentOptions): Promise<Agent>;
+    private createCodingAgent;
+    createOpenCode(options?: CodingAgentCreateOptions): Promise<OpenCodeAgent>;
+    createBuzzAgent(options?: CodingAgentCreateOptions): Promise<BuzzAgent>;
+    createCodex(options?: CodingAgentCreateOptions): Promise<CodexAgent>;
+    createClaudeCode(options?: CodingAgentCreateOptions): Promise<ClaudeCodeAgent>;
+    createGoose(options?: CodingAgentCreateOptions): Promise<GooseAgent>;
+    createKimiCode(options?: CodingAgentCreateOptions): Promise<KimiCodeAgent>;
     budget(): Promise<Record<string, any>>;
-    metrics(agentId: string): Promise<Record<string, any>>;
-    list(): Promise<Agent[]>;
-    get(agentId: string): Promise<Agent>;
-    waitRunning(agentId: string, timeoutMs?: number, pollIntervalMs?: number): Promise<Agent>;
-    start(agentId: string, options?: StartAgentOptions): Promise<Agent>;
-    startOpenClaw(agentId: string, options?: OpenClawStartAgentOptions): Promise<Agent>;
-    startOpenClawPro(agentId: string, options?: OpenClawStartAgentOptions): Promise<Agent>;
-    update(agentId: string, options?: UpdateAgentOptions): Promise<Agent>;
+    bootstrapInference(messages: BootstrapInferenceMessage[], responseFormat?: BootstrapInferenceResponseFormat, requestOptions?: RequestOverrides): Promise<BootstrapInferenceResult>;
+    metrics(agentIdOrName: string): Promise<Record<string, any>>;
+    list(options?: ListAgentsOptions): Promise<Agent[]>;
+    listWithCapacity(options?: ListAgentsOptions): Promise<AgentCapacity>;
+    get(agentIdOrName: string, requestOptions?: RequestOverrides): Promise<Agent>;
+    createExternalAgent(options: CreateExternalAgentOptions): Promise<Agent>;
+    updateExternalAgent(externalAgentId: string, options: UpdateExternalAgentOptions): Promise<Agent>;
+    getExternalAgent(externalAgentId: string): Promise<Agent>;
+    uploadExternalAgentProfileImage(externalAgentId: string, content: Blob | ArrayBuffer | ArrayBufferView, contentType?: string): Promise<AgentProfileImageUploadResult>;
+    deleteExternalAgentProfileImage(externalAgentId: string): Promise<AgentProfileImageUploadResult>;
+    rotateExternalAgentKey(agentIdOrName: string): Promise<Record<string, any>>;
+    attachSlackRelayAgent(agentIdOrName: string, options: AttachDeploymentSlackRelayAgentOptions): Promise<AttachSlackRelayAgentResult>;
+    subscribe(handler: (event: DeploymentEvent) => void | Promise<void>, options?: DeploymentSubscribeOptions): Promise<void>;
+    waitForState(agentIdOrName: string, states: readonly AgentState[], timeoutMs?: number, failureStates?: readonly AgentState[], minimumLaunchEpoch?: number, pollIntervalMs?: number): Promise<Agent>;
+    waitRunning(agentIdOrName: string, timeoutMs?: number, pollIntervalMs?: number, minimumLaunchEpoch?: number): Promise<Agent>;
+    start(agentIdOrName: string, options?: StartAgentOptions): Promise<Agent>;
+    startOpenClaw(agentIdOrName: string, options?: OpenClawStartAgentOptions): Promise<Agent>;
+    startHermesAgent(agentIdOrName: string, options?: HermesAgentStartOptions): Promise<HermesAgent>;
+    startOpenClawPro(agentIdOrName: string, options?: OpenClawStartAgentOptions): Promise<Agent>;
+    update(agentIdOrName: string, options?: UpdateAgentOptions): Promise<Agent>;
+    uploadProfileImage(agentId: string, content: Blob | ArrayBuffer | ArrayBufferView, contentType?: string): Promise<AgentProfileImageUploadResult>;
+    deleteProfileImage(agentId: string): Promise<AgentProfileImageUploadResult>;
     resize(agentId: string, options: Pick<UpdateAgentOptions, 'size'>): Promise<Agent>;
-    stop(agentId: string): Promise<Agent>;
-    delete(agentId: string): Promise<Record<string, any>>;
-    refreshToken(agentId: string): Promise<AgentTokenResponse>;
-    createScopedKey(agentId: string, name?: string): Promise<Record<string, any>>;
+    /**
+     * 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.
+     */
+    stop(agentIdOrName: string): Promise<Agent>;
+    /** Restore durable storage. The accepted snapshot is `RESTORING`; completion is `STOPPED`. */
+    restore(agentIdOrName: string): Promise<Agent>;
+    getRoutes(agentIdOrName: string): Promise<AgentRoutesState>;
+    setRoutes(agentIdOrName: string, routes: Record<string, AgentRouteConfig>): Promise<AgentRoutesState>;
+    setRoute(agentIdOrName: string, name: string, route: AgentRouteConfig): Promise<AgentRoutesState>;
+    removeRoute(agentIdOrName: string, name: string): Promise<AgentRoutesState>;
+    delete(agentIdOrName: string): Promise<Record<string, any>>;
+    refreshToken(agentIdOrName: string): Promise<AgentTokenResponse>;
+    createScopedKey(agentIdOrName: string, name?: string): Promise<Record<string, any>>;
     webSearch(query: string, options?: BraveWebSearchOptions): Promise<BraveWebSearchResponse>;
-    logsToken(agentId: string): Promise<AgentLogsTokenResponse>;
-    env(agentId: string): Promise<{
-        agent_id: string;
-        env: Record<string, string>;
-    }>;
+    logsToken(agentIdOrName: string): Promise<AgentLogsTokenResponse>;
+    env(agentIdOrName: string, requestOptions?: RequestOverrides): Promise<AgentEnvResponse>;
+    secretNames(agentIdOrName: string, requestOptions?: RequestOverrides): Promise<AgentSecretNamesResponse>;
+    secret(agentIdOrName: string, key: string, requestOptions?: RequestOverrides): Promise<AgentSecretResponse>;
     exec(target: Agent | string, command: string, options?: AgentExecOptions): Promise<AgentExecResult>;
-    health(target: Agent): Promise<Record<string, any>>;
     filesList(target: Agent | string, path?: string, source?: 'auto' | 'pod' | 's3'): Promise<AgentFileEntry[]>;
-    fileReadBytes(target: Agent | string, path: string, source?: 'auto' | 'pod' | 's3'): Promise<Uint8Array>;
-    fileRead(target: Agent | string, path: string, source?: 'auto' | 'pod' | 's3'): Promise<string>;
+    fileReadBytesWithMetadata(target: Agent | string, path: string, source?: 'auto' | 'pod' | 's3', options?: AgentFileReadOptions): Promise<AgentFileReadBytesResult>;
+    fileReadBytes(target: Agent | string, path: string, source?: 'auto' | 'pod' | 's3', options?: AgentFileReadOptions): Promise<Uint8Array>;
+    fileRead(target: Agent | string, path: string, source?: 'auto' | 'pod' | 's3', options?: AgentFileReadOptions): Promise<string>;
     fileWriteBytes(target: Agent | string, path: string, content: Uint8Array | ArrayBuffer | string, destination?: 'auto' | 'pod' | 's3'): Promise<Record<string, any>>;
     fileWrite(target: Agent | string, path: string, content: string, destination?: 'auto' | 'pod' | 's3'): Promise<Record<string, any>>;
     fileDelete(target: Agent | string, path: string, options?: {
         recursive?: boolean;
+        source?: 'auto' | 'pod' | 's3';
     }): Promise<Record<string, any>>;
     cpTo(target: Agent | string, localPath: string, remotePath: string): Promise<Record<string, any>>;
     cpFrom(target: Agent | string, remotePath: string, localPath: string): Promise<string>;
-    logsConnect(agentId: string, options?: {
+    logsConnect(agentIdOrName: string, options?: {
         tailLines?: number;
         container?: string;
     }): Promise<WebSocket>;
-    shellToken(agentId: string, shell?: string, dryRun?: boolean): Promise<AgentShellTokenResponse>;
-    shellConnect(agentId: string, shell?: string): Promise<WebSocket>;
+    shellToken(agentIdOrName: string, shell?: string, dryRun?: boolean, requestOptions?: RequestOverrides): Promise<AgentShellTokenResponse>;
+    shellConnect(agentIdOrName: string, shell?: string, options?: AgentShellConnectOptions): Promise<WebSocket>;
 }
 //# sourceMappingURL=agents.d.ts.map