@hypercli.com/sdk 2026.6.26 → 2026.7.31

package/dist/agents.d.ts

@@ -1,7 +1,25 @@
-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 { 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';
+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_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_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_CODING_AGENT_SYNC_ROOT = "/home/node";
+export type ManagedAgentRuntime = 'generic' | 'openclaw' | 'openclaw-pro' | 'opencode' | 'codex' | 'claude-code' | 'goose' | 'kimi-code';
+export type CodingAgentRuntime = Extract<ManagedAgentRuntime, 'opencode' | 'codex' | 'claude-code' | 'goose' | 'kimi-code'>;
+export declare const DEFAULT_CODING_AGENT_IMAGES: Readonly<Record<CodingAgentRuntime, 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 +28,11 @@ 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/workspaces";
+    readonly HYPER_WORKSPACES_SYNC_READY_ONLY: "1";
+};
 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;
@@ -25,6 +48,10 @@ export interface AgentTokenResponse {
     jwt?: string;
     expires_at?: string | null;
 }
+export interface BrowserDesktopUrlOptions {
+    redirect?: string | null;
+    resize?: string | null;
+}
 export interface AgentGatewayContext {
     agent_id?: string;
     hostname?: string | null;
@@ -33,6 +60,7 @@ export interface AgentGatewayContext {
 export interface GatewayContextWaitOptions {
     timeoutMs?: number;
     retryIntervalMs?: number;
+    signal?: AbortSignal;
 }
 export interface AgentShellTokenResponse {
     agent_id?: string;
@@ -42,12 +70,135 @@ 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 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;
@@ -70,6 +221,13 @@ export interface AgentRouteConfig {
     strip_prefix?: boolean;
     [key: string]: any;
 }
+export type LaunchConfigFlatMap = Record<string, unknown>;
+export interface AgentDesktopConfigSource {
+    launchConfig?: unknown;
+    launch_config?: unknown;
+    routes?: unknown;
+    ports?: unknown;
+}
 export interface RegistryAuth {
     username?: string;
     password?: string;
@@ -89,10 +247,13 @@ export interface BuildAgentConfigOptions {
     syncGid?: number | null;
     registryUrl?: string | null;
     registryAuth?: RegistryAuth | null;
+    restart?: boolean | 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;
@@ -112,6 +273,12 @@ export interface OpenClawMemoryIndexOptions {
     watchDebounceMs?: number | null;
     intervalMinutes?: number | null;
 }
+export interface OpenClawWorkspacesSyncOptions {
+    enabled?: boolean | null;
+    outputDir?: string | null;
+    readyOnly?: boolean | null;
+    workspace?: string | null;
+}
 export interface OpenClawHeartbeatConfig {
     every?: string;
     model?: string;
@@ -193,12 +360,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,7 +391,9 @@ 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;
 }
@@ -214,11 +401,57 @@ 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 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[];
+    sessionTitle?: string | null;
+    rustLog?: string;
+    restart?: boolean;
+}
+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 +463,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 +557,24 @@ export interface AgentDirectoryListing {
     truncated?: boolean;
     [key: string]: any;
 }
+export type AgentState = 'PENDING' | 'RESTORING' | 'RESTORE_FAILED' | 'SYNCING' | 'SYNC_FAILED' | 'STARTING' | 'RUNNING' | 'STOPPING' | 'STOPPED' | 'FAILED' | (string & {});
 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;
@@ -272,8 +599,18 @@ export interface AgentHydrationData {
     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;
@@ -299,13 +636,26 @@ export interface AgentHydrationData {
     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 portsHaveDesktop(ports: 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;
 };
+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 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;
@@ -313,6 +663,16 @@ export declare class Agent {
     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;
@@ -339,9 +699,11 @@ 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 hasDesktop(): boolean;
     protected requireDeployments(): Deployments;
     routeRequiresAuth(routeName: string, defaultValue?: boolean): boolean;
     refreshToken(): Promise<AgentTokenResponse>;
@@ -351,17 +713,87 @@ export declare class Agent {
     env(): Promise<Record<string, 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;
+    output: string;
+    verificationUrl: string | null;
+    userCode: string | null;
+    interactiveRequired: boolean;
+    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): 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;
+    get auth(): RuntimeAuthClient;
+}
+export declare class OpenCodeAgent extends CodingAgent {
+    readonly runtime: 'opencode';
+    static fromDict(data: AgentHydrationData): OpenCodeAgent;
+}
+export declare class CodexAgent extends CodingAgent {
+    readonly runtime: 'codex';
+    static fromDict(data: AgentHydrationData): CodexAgent;
+}
+export declare class ClaudeCodeAgent extends CodingAgent {
+    readonly runtime: 'claude-code';
+    static fromDict(data: AgentHydrationData): ClaudeCodeAgent;
+}
+export declare class GooseAgent extends CodingAgent {
+    readonly runtime: 'goose';
+    static fromDict(data: AgentHydrationData): GooseAgent;
+}
+export declare class KimiCodeAgent extends CodingAgent {
+    readonly runtime: 'kimi-code';
+    static fromDict(data: AgentHydrationData): KimiCodeAgent;
 }
 export declare class OpenClawAgent extends Agent {
     gatewayUrl: string | null;
@@ -371,7 +803,7 @@ export declare class OpenClawAgent extends Agent {
         gatewayToken?: string | null;
     });
     static fromDict(data: AgentHydrationData): OpenClawAgent;
-    private static gatewayUrlFromHostname;
+    protected static gatewayUrlFromHostname(hostname: string | null | undefined): string | null;
     private currentGatewayHostname;
     /**
      * Resolve gateway context through the deployment record plus `/env`.
@@ -385,32 +817,60 @@ export declare class OpenClawAgent extends Agent {
     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>;
     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 +916,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 +929,80 @@ 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): Promise<string>;
     private agentIdFor;
     private fetchRaw;
     create(options?: CreateAgentOptions): Promise<Agent>;
     createOpenClaw(options?: OpenClawCreateAgentOptions): Promise<Agent>;
     createOpenClawPro(options?: OpenClawCreateAgentOptions): Promise<Agent>;
+    private createCodingAgent;
+    createOpenCode(options?: CodingAgentCreateOptions): Promise<OpenCodeAgent>;
+    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[]>;
+    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>;
+    waitRunning(agentIdOrName: string, timeoutMs?: number, pollIntervalMs?: number): Promise<Agent>;
+    start(agentIdOrName: string, options?: StartAgentOptions): Promise<Agent>;
+    startOpenClaw(agentIdOrName: string, options?: OpenClawStartAgentOptions): Promise<Agent>;
+    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>;
+    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<{
+    logsToken(agentIdOrName: string): Promise<AgentLogsTokenResponse>;
+    env(agentIdOrName: string, requestOptions?: RequestOverrides): Promise<{
         agent_id: string;
         env: Record<string, string>;
     }>;
     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