@swarm-agent/sdk 0.1.47 → 0.1.48

package/dist/sessions.js

@@ -1,4 +1,5 @@
 import { SwarmTimeoutError } from './errors.js';
+import { SwarmPermissionsNamespace, isAskUserPermission } from './permissions.js';
 function generateRequestId() {
     if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
         return `sdk-session-${crypto.randomUUID()}`;
@@ -22,6 +23,7 @@ export class SwarmSessionsNamespace {
                 client_request_id: clientRequestId,
                 agent_name: agentName,
                 title: params.title,
+                project_id: params.project_id,
                 workspace_id: params.workspace_id,
                 workspace_path: params.workspace_path,
                 mode: params.mode ?? 'auto',
@@ -43,6 +45,8 @@ export class SwarmSessionsNamespace {
             q.set('limit', params.limit.toString());
         if (params.state)
             q.set('state', params.state);
+        if (params.project_id)
+            q.set('project_id', params.project_id);
         if (params.workspace_id)
             q.set('workspace_id', params.workspace_id);
         if (params.category)
@@ -52,13 +56,22 @@ export class SwarmSessionsNamespace {
         const queryStr = q.toString() ? `?${q.toString()}` : '';
         const res = await this.transport.request(`/v3/sessions${queryStr}`, { method: 'GET' });
         const data = res.data;
+        let list = [];
         if (Array.isArray(data)) {
-            return data;
+            list = data;
         }
-        if (data && typeof data === 'object' && 'sessions' in data && Array.isArray(data.sessions)) {
-            return data.sessions;
+        else if (data && typeof data === 'object' && 'sessions' in data && Array.isArray(data.sessions)) {
+            list = data.sessions;
         }
-        return [];
+        return list.map((item) => {
+            if (item && item.session && typeof item.session === 'object') {
+                return {
+                    ...item.session,
+                    projection: item.projection,
+                };
+            }
+            return item;
+        });
     }
     /**
      * Retrieves full details, history, and state for a single session.
@@ -173,22 +186,36 @@ export class SwarmSessionsNamespace {
     }
     /**
      * Helper that polls a session until its active run completes, or times out.
+     * Explicit autoApprovePermissions applies only to ordinary tools; questions still require user input.
      */
     async waitForRun(sessionId, options = {}) {
-        const timeoutMs = options.timeoutMs ?? 60_000;
+        const timeoutMs = options.timeoutMs ?? 180_000;
         const pollIntervalMs = options.pollIntervalMs ?? 1_000;
         const deadline = Date.now() + timeoutMs;
+        const permissions = new SwarmPermissionsNamespace(this.transport);
+        let lastPendingPerms = [];
         while (Date.now() < deadline) {
+            lastPendingPerms = await permissions.listSessionPending(sessionId, 20);
+            if (options.autoApprovePermissions) {
+                for (const p of lastPendingPerms) {
+                    if (!isAskUserPermission(p))
+                        await permissions.resolve(sessionId, p.id, 'allow_once', { reason: 'Approved by explicit application policy' });
+                }
+            }
             const detail = await this.get(sessionId);
             const raw = (detail.raw || {});
             const activeRun = raw.active_run_intent;
             const state = (detail.state || '').toLowerCase();
             const isRunning = state.includes('running') || state.includes('in_progress') || !!activeRun;
-            if (!isRunning) {
+            if (!isRunning && lastPendingPerms.length === 0) {
                 return detail;
             }
             await new Promise((r) => setTimeout(r, pollIntervalMs));
         }
-        throw new SwarmTimeoutError(`Session run did not complete within ${timeoutMs}ms`, timeoutMs);
+        let msg = `Session run did not complete within ${timeoutMs}ms`;
+        if (lastPendingPerms.length > 0) {
+            msg += `. Session has ${lastPendingPerms.length} pending tool permission(s) requiring approval: ${lastPendingPerms.map((p) => p.tool_name).join(', ')}. Render the requests and explicitly answer or deny via client.permissions.resolve().`;
+        }
+        throw new SwarmTimeoutError(msg, timeoutMs);
     }
 }

package/dist/settings.d.ts

@@ -36,6 +36,12 @@ export interface AgentModelSettingsResponse {
     agent_model_settings: AgentModelSettings;
     roles: Record<string, string>[];
 }
+export interface ModelRecommendation {
+    role: string;
+    thinking?: string;
+    serving?: string;
+    [key: string]: unknown;
+}
 /** Catalog extensions are preserved as unknown, never interpreted as runtime capability grants. */
 export interface ModelCatalogEntry {
     provider: string;
@@ -50,6 +56,7 @@ export interface ModelCatalogEntry {
     default_thinking?: string;
     service_tiers?: string[];
     default_service_tier?: string;
+    recommendations?: ModelRecommendation[];
     context_modes?: {
         mode: string;
         label?: string;
@@ -72,6 +79,13 @@ export interface ModelCatalogResponse {
         [key: string]: unknown;
     };
 }
+export interface FleetModelAssignments {
+    swarm: {
+        action: ModelAssignment;
+        plan: ModelAssignment;
+    };
+    system_agents: Record<SystemAgentSlot, ModelAssignment>;
+}
 /** Account-scoped settings. Requires the local administrative connection, not a session token. */
 export declare class SwarmSettingsNamespace {
     private readonly transport;
@@ -81,5 +95,19 @@ export declare class SwarmSettingsNamespace {
     agentModels(): Promise<AgentModelSettingsResponse>;
     setSwarmModel(slot: 'action' | 'plan', assignment: ModelAssignment): Promise<AgentModelSettingsResponse>;
     setSystemAgentModel(slot: SystemAgentSlot, assignment: ModelAssignment): Promise<AgentModelSettingsResponse>;
-    private patch;
+    /**
+     * Restores verified recommended defaults across all system agent and swarm core roles.
+     * If expectedUpdatedAt is omitted, automatically reads the current setting's revision first.
+     */
+    restoreDefaults(expectedUpdatedAt?: number): Promise<AgentModelSettingsResponse>;
+    /**
+     * Resolves the recommended model and thinking level for each role from a provider's catalog.
+     */
+    getRecommendationsForProvider(provider: string): Promise<FleetModelAssignments>;
+    /**
+     * Applies verified onboarding model recommendations for a specific provider across the entire fleet:
+     * Swarm Action, Swarm Plan, and System Agents (Coder, Finder, Designer, Router, Compact).
+     */
+    applyProviderFleet(provider: string): Promise<AgentModelSettingsResponse>;
+    patch(body: object): Promise<AgentModelSettingsResponse>;
 }

package/dist/settings.js

@@ -20,6 +20,75 @@ export class SwarmSettingsNamespace {
     async setSystemAgentModel(slot, assignment) {
         return this.patch({ system_agents: { [slot]: assignment } });
     }
+    /**
+     * Restores verified recommended defaults across all system agent and swarm core roles.
+     * If expectedUpdatedAt is omitted, automatically reads the current setting's revision first.
+     */
+    async restoreDefaults(expectedUpdatedAt) {
+        let updatedAt = expectedUpdatedAt;
+        if (typeof updatedAt !== 'number') {
+            const current = await this.agentModels();
+            updatedAt = current.agent_model_settings.updated_at;
+        }
+        return (await this.transport.request('/v1/agent-model-settings/restore-defaults', {
+            method: 'POST',
+            body: { expected_updated_at: updatedAt },
+        })).data;
+    }
+    /**
+     * Resolves the recommended model and thinking level for each role from a provider's catalog.
+     */
+    async getRecommendationsForProvider(provider) {
+        const normalizedProvider = provider.toLowerCase().trim();
+        const catalog = await this.models(normalizedProvider);
+        const records = catalog.records || [];
+        const findForRole = (role) => {
+            for (const entry of records) {
+                if (!entry.recommendations)
+                    continue;
+                const rec = entry.recommendations.find((r) => r.role?.toLowerCase().trim() === role.toLowerCase().trim());
+                if (rec) {
+                    return {
+                        model: entry.model,
+                        thinking: rec.thinking || entry.default_thinking || 'medium',
+                    };
+                }
+            }
+            return null;
+        };
+        const autoMatch = findForRole('auto') || {
+            model: records[0]?.model || 'default',
+            thinking: records[0]?.default_thinking || 'high',
+        };
+        const planMatch = findForRole('plan') || autoMatch;
+        const coderMatch = findForRole('coder') || autoMatch;
+        const utilityMatch = findForRole('utility');
+        const routerMatch = findForRole('router') || utilityMatch || autoMatch;
+        const compactMatch = findForRole('compact') || utilityMatch || autoMatch;
+        const finderMatch = findForRole('finder') || utilityMatch || autoMatch;
+        const designerMatch = findForRole('designer') || planMatch || autoMatch;
+        return {
+            swarm: {
+                action: { provider: normalizedProvider, model: autoMatch.model, thinking: autoMatch.thinking },
+                plan: { provider: normalizedProvider, model: planMatch.model, thinking: planMatch.thinking },
+            },
+            system_agents: {
+                coder: { provider: normalizedProvider, model: coderMatch.model, thinking: coderMatch.thinking },
+                finder: { provider: normalizedProvider, model: finderMatch.model, thinking: finderMatch.thinking },
+                designer: { provider: normalizedProvider, model: designerMatch.model, thinking: designerMatch.thinking },
+                router: { provider: normalizedProvider, model: routerMatch.model, thinking: routerMatch.thinking },
+                compact: { provider: normalizedProvider, model: compactMatch.model, thinking: compactMatch.thinking },
+            },
+        };
+    }
+    /**
+     * Applies verified onboarding model recommendations for a specific provider across the entire fleet:
+     * Swarm Action, Swarm Plan, and System Agents (Coder, Finder, Designer, Router, Compact).
+     */
+    async applyProviderFleet(provider) {
+        const fleet = await this.getRecommendationsForProvider(provider);
+        return this.patch(fleet);
+    }
     async patch(body) {
         return (await this.transport.request('/v1/agent-model-settings', { method: 'PATCH', body })).data;
     }

package/dist/types.d.ts

@@ -290,6 +290,7 @@ export interface SessionRecord {
 }
 export interface CreateSessionParams {
     title?: string;
+    project_id?: string;
     workspace_id?: string;
     workspace_path?: string;
     agent_name?: string;
@@ -301,6 +302,7 @@ export interface CreateSessionParams {
 export interface ListSessionsParams {
     limit?: number;
     state?: string;
+    project_id?: string;
     workspace_id?: string;
     category?: 'video' | 'needs_review' | 'blocked' | 'in_progress' | 'active_chats' | 'archived';
     cursor?: string;
@@ -447,7 +449,15 @@ export interface ProjectTaskMediaRef {
     size_bytes?: number;
     created_at?: number;
 }
+export interface ProjectContextGeneration {
+    status: 'pending' | 'running' | 'ready' | 'failed';
+    attempt: number;
+    lease_until?: number;
+    error?: string;
+    router_alert?: string;
+}
 export interface ProjectRecord {
+    context_generation?: ProjectContextGeneration;
     id: string;
     account_id?: string;
     name: string;
@@ -462,6 +472,8 @@ export interface ProjectRecord {
     updated_at: number;
 }
 export interface CreateProjectParams {
+    /** Reuse this key with the same input after a lost creation response. */
+    client_request_id?: string;
     id?: string;
     name: string;
     description?: string;
@@ -949,6 +961,7 @@ export interface WorkerRevisionRecord {
     change_summary?: string;
 }
 export interface WorkerRunRecord {
+    placement?: import('./worker-control.js').WorkerRunPlacement;
     cancel_requested?: boolean;
     id: string;
     account_scope_id: string;

package/dist/websocket.d.ts

@@ -0,0 +1,60 @@
+import type { IncomingMessage, Server as HttpServer } from 'node:http';
+import type { Server as HttpsServer } from 'node:https';
+import { WebSocket } from 'ws';
+import type { SwarmChatNamespace, ToolStreamItem } from './chat.js';
+import type { PendingPermissionRecord, SwarmPermissionsNamespace, PermissionResolver, ResolvePermissionOptions, ResolvePermissionResult } from './permissions.js';
+import type { SessionWatchState, V3Message } from './realtime.js';
+export interface SwarmWebSocketBridgeOptions {
+    path?: string;
+    /** Server-owned policy. Browser frames cannot enable auto approval. Questions always require a reply. */
+    autoApprovePermissions?: boolean;
+    socketFactory?: import('./realtime.js').RealtimeSocketFactory;
+    /** Authenticate/authorize upgrades for non-loopback or multi-user applications. */
+    authorize?: (request: IncomingMessage) => boolean | Promise<boolean>;
+    onPermissionRequested?: (permission: PendingPermissionRecord, clientSocket: WebSocket, resolve: PermissionResolver) => void | Promise<void>;
+}
+export interface SwarmWebSocketClientMessage {
+    type: 'subscribe' | 'chat_message' | 'resolve_permission' | 'ping' | 'unsubscribe';
+    sessionId?: string;
+    message?: string;
+    requestId?: string;
+    permissionId?: string;
+    action?: 'allow_once' | 'deny' | 'deny_once' | 'allow_always' | 'deny_always';
+    reason?: string;
+    approvedArguments?: ResolvePermissionOptions['approvedArguments'];
+    /** @deprecated Configure permission policy on the server instead. */
+    autoApprovePermissions?: boolean;
+}
+export interface SwarmWebSocketServerMessage {
+    type: 'connected' | 'subscribed' | 'unsubscribed' | 'state' | 'accepted' | 'text' | 'reasoning' | 'tool_start' | 'tool_delta' | 'tool_done' | 'tool_permission' | 'permission_resolved' | 'permission_removed' | 'permission_error' | 'done' | 'error' | 'pong';
+    sessionId?: string;
+    requestId?: string;
+    state?: SessionWatchState;
+    delta?: string;
+    fullText?: string;
+    tool?: ToolStreamItem;
+    permission?: PendingPermissionRecord;
+    result?: ResolvePermissionResult;
+    permissionId?: string;
+    messages?: V3Message[];
+    error?: string;
+}
+/** Application-owned bridge to canonical V3 realtime. A subscription survives every turn.
+ * One socket selects one conversation; reconnect rehydrates that exact conversation.
+ * Never expose this privileged bridge publicly without application authentication.
+ */
+export declare class SwarmWebSocketBridge {
+    private readonly chat;
+    private readonly permissions;
+    private readonly options;
+    private readonly wss;
+    private readonly activeWatches;
+    constructor(server: HttpServer | HttpsServer, chat: SwarmChatNamespace, permissions: SwarmPermissionsNamespace, options?: SwarmWebSocketBridgeOptions);
+    private send;
+    private handleConnection;
+    private handleMessage;
+    private cleanupSocket;
+    private subscribeSocket;
+    close(): Promise<void>;
+}
+export declare function createSwarmWebSocketBridge(server: HttpServer | HttpsServer, chat: SwarmChatNamespace, permissions: SwarmPermissionsNamespace, options?: SwarmWebSocketBridgeOptions): SwarmWebSocketBridge;

package/dist/websocket.js

@@ -0,0 +1,207 @@
+import { WebSocketServer, WebSocket } from 'ws';
+import { isAskUserPermission, permissionId, permissionResolutionBody, PermissionResolutionError } from './permission-ui.js';
+/** Application-owned bridge to canonical V3 realtime. A subscription survives every turn.
+ * One socket selects one conversation; reconnect rehydrates that exact conversation.
+ * Never expose this privileged bridge publicly without application authentication.
+ */
+export class SwarmWebSocketBridge {
+    chat;
+    permissions;
+    options;
+    wss;
+    activeWatches = new Map();
+    constructor(server, chat, permissions, options = {}) {
+        this.chat = chat;
+        this.permissions = permissions;
+        this.options = options;
+        this.wss = new WebSocketServer({
+            server, path: options.path ?? '/ws', maxPayload: 1024 * 1024,
+            verifyClient: (info, done) => {
+                // Prevent a foreign website from driving a localhost privileged bridge.
+                let sameOrigin = true;
+                try {
+                    if (info.origin)
+                        sameOrigin = new URL(info.origin).host === info.req.headers.host;
+                }
+                catch {
+                    sameOrigin = false;
+                }
+                if (!sameOrigin) {
+                    done(false, 403);
+                    return;
+                }
+                Promise.resolve().then(() => options.authorize?.(info.req) ?? true)
+                    .then(allowed => done(allowed, allowed ? undefined : 403), () => done(false, 403));
+            },
+        });
+        this.wss.on('connection', ws => this.handleConnection(ws));
+    }
+    send(ws, message) {
+        if (ws.readyState !== WebSocket.OPEN)
+            return;
+        if (ws.bufferedAmount > 8 * 1024 * 1024) {
+            ws.close(1013, 'Slow consumer; reconnect to rehydrate');
+            return;
+        }
+        ws.send(JSON.stringify(message));
+    }
+    handleConnection(ws) {
+        this.send(ws, { type: 'connected' });
+        // Ordered handling prevents subscribe/send/switch races. Bound queued work.
+        let queue = Promise.resolve();
+        let queued = 0;
+        const permissionRequests = new Set();
+        ws.on('message', raw => {
+            if (++queued > 64) {
+                ws.close(1008, 'Too many pending requests');
+                return;
+            }
+            queue = queue.then(async () => {
+                if (ws.readyState !== WebSocket.OPEN)
+                    return;
+                let data;
+                try {
+                    data = JSON.parse(raw.toString());
+                    if (!data || typeof data !== 'object')
+                        throw new Error('Expected a message object');
+                    if (data.type === 'resolve_permission') {
+                        const requestId = permissionId(data.requestId, 'requestId');
+                        if (permissionRequests.has(requestId))
+                            throw new Error('Duplicate permission requestId; refresh before retrying');
+                        // Bound replay memory; close rather than evict and accidentally replay an old decision.
+                        if (permissionRequests.size >= 4096) {
+                            ws.close(1008, 'Reconnect to refresh permission state');
+                            return;
+                        }
+                        permissionRequests.add(requestId);
+                    }
+                    await this.handleMessage(ws, data);
+                }
+                catch (error) {
+                    this.send(ws, { type: data?.type === 'resolve_permission' ? 'permission_error' : 'error', permissionId: data?.permissionId, sessionId: data?.sessionId, requestId: data?.requestId,
+                        result: error instanceof PermissionResolutionError ? error.result : undefined,
+                        error: error instanceof Error ? error.message : String(error) });
+                }
+            }).finally(() => { queued--; });
+        });
+        ws.on('close', () => this.cleanupSocket(ws));
+        ws.on('error', () => this.cleanupSocket(ws));
+    }
+    async handleMessage(ws, data) {
+        switch (data.type) {
+            case 'ping':
+                this.send(ws, { type: 'pong' });
+                return;
+            case 'unsubscribe':
+                this.cleanupSocket(ws);
+                this.send(ws, { type: 'unsubscribed' });
+                return;
+            case 'subscribe':
+                await this.subscribeSocket(ws, permissionId(data.sessionId, 'sessionId'));
+                return;
+            case 'chat_message': {
+                const sessionId = data.sessionId || this.activeWatches.get(ws)?.sessionId;
+                // Never guess the newest account session or silently create one.
+                if (!sessionId)
+                    throw new Error('Select or create a conversation before sending a message');
+                if (typeof data.message !== 'string' || !data.message.trim())
+                    throw new Error('message is required');
+                await this.subscribeSocket(ws, sessionId);
+                if (ws.readyState !== WebSocket.OPEN)
+                    return;
+                await this.chat.sendMessage(sessionId, data.message, 'user', data.requestId);
+                this.send(ws, { type: 'accepted', sessionId, requestId: data.requestId });
+                return;
+            }
+            case 'resolve_permission': {
+                if (!data.sessionId || data.sessionId !== this.activeWatches.get(ws)?.sessionId)
+                    throw new Error('Permission reply must target the selected conversation');
+                if (!data.permissionId || !['allow_once', 'deny', 'deny_once', 'allow_always', 'deny_always'].includes(data.action ?? ''))
+                    throw new Error('Valid permissionId and action are required');
+                permissionResolutionBody(data.action, { reason: data.reason, approvedArguments: data.approvedArguments });
+                const result = await this.permissions.resolve(data.sessionId, data.permissionId, data.action, { reason: data.reason, approvedArguments: data.approvedArguments });
+                this.send(ws, { type: 'permission_resolved', sessionId: data.sessionId, permissionId: data.permissionId, requestId: data.requestId, result });
+                return;
+            }
+            default: throw new Error(`Unknown message type: ${data.type}`);
+        }
+    }
+    cleanupSocket(ws) {
+        this.activeWatches.get(ws)?.watch.dispose();
+        this.activeWatches.delete(ws);
+    }
+    async subscribeSocket(ws, sessionId) {
+        const existing = this.activeWatches.get(ws);
+        if (existing?.sessionId === sessionId) {
+            await existing.watch.ready;
+            this.send(ws, { type: 'subscribed', sessionId });
+            return;
+        }
+        this.cleanupSocket(ws);
+        let watch;
+        const send = (message) => {
+            if (this.activeWatches.get(ws)?.watch === watch)
+                this.send(ws, { ...message, sessionId });
+        };
+        watch = await this.chat.stream(sessionId, {
+            socketFactory: this.options.socketFactory,
+            onState: state => send({ type: 'state', state }),
+            onText: (delta, fullText) => send({ type: 'text', delta, fullText }),
+            onReasoning: (delta, fullText) => send({ type: 'reasoning', delta, fullText }),
+            onToolStarted: tool => send({ type: 'tool_start', tool }),
+            onToolDelta: (tool, delta) => send({ type: 'tool_delta', tool, delta }),
+            onToolCompleted: tool => send({ type: 'tool_done', tool }),
+            onPermissionRequested: async (permission, resolve) => {
+                if (this.activeWatches.get(ws)?.watch !== watch)
+                    return;
+                if (this.options.autoApprovePermissions && !isAskUserPermission(permission)) {
+                    await resolve('allow_once', 'Approved by application server policy');
+                }
+                else if (this.options.onPermissionRequested) {
+                    await this.options.onPermissionRequested(permission, ws, resolve);
+                }
+                else
+                    send({ type: 'tool_permission', permission });
+            },
+            onPermissionRemoved: permissionId => send({ type: 'permission_removed', permissionId }),
+            onPermissionError: (error, permission) => send({ type: 'permission_error', permissionId: permission.id, error: error.message }),
+            onComplete: messages => send({ type: 'done', messages }),
+            onError: error => {
+                send({ type: 'error', error: error.message });
+                if (this.activeWatches.get(ws)?.watch === watch) {
+                    this.cleanupSocket(ws);
+                    ws.close(1011, 'Conversation stream unavailable; reconnect');
+                }
+            },
+        });
+        this.activeWatches.set(ws, { sessionId, watch });
+        // A failed watch must not leave an apparently subscribed but dead socket.
+        void watch.done.catch(() => { }).finally(() => {
+            if (this.activeWatches.get(ws)?.watch === watch)
+                this.activeWatches.delete(ws);
+        });
+        try {
+            await watch.ready;
+            if (ws.readyState !== WebSocket.OPEN) {
+                this.cleanupSocket(ws);
+                return;
+            }
+            send({ type: 'subscribed' });
+        }
+        catch (error) {
+            if (this.activeWatches.get(ws)?.watch === watch)
+                this.cleanupSocket(ws);
+            throw error;
+        }
+    }
+    async close() {
+        for (const ws of this.wss.clients) {
+            this.cleanupSocket(ws);
+            ws.terminate();
+        }
+        await new Promise(resolve => this.wss.close(() => resolve()));
+    }
+}
+export function createSwarmWebSocketBridge(server, chat, permissions, options = {}) {
+    return new SwarmWebSocketBridge(server, chat, permissions, options);
+}

package/dist/worker-control.d.ts

@@ -0,0 +1,133 @@
+import type { SwarmTransport } from './transport.js';
+import type { WorkerRunRecord } from './types.js';
+export interface WorkerSSHRegistration {
+    workspace_id: string;
+    name: string;
+    host: string;
+    user: string;
+    port: number;
+    idempotency_key: string;
+    /** Absolute hub-side trust-store reference; never key contents or automatic trust enrollment. */
+    known_hosts_file?: string;
+}
+export interface WorkerGCPRegistration {
+    name: string;
+    runtime_id: string;
+    desktop_url?: string;
+    idempotency_key: string;
+}
+export interface WorkerTargetReference {
+    kind: 'ssh' | 'gcp';
+    workspace_id?: string;
+    reference_id: string;
+    reference_digest?: string;
+    capacity: number;
+}
+export interface WorkerContextUpdate {
+    expected_revision: number;
+    text: string;
+    provenance: string;
+    references?: {
+        kind: 'artifact' | 'checkpoint';
+        reference: string;
+    }[];
+}
+export interface WorkerContextRecord {
+    worker_id: string;
+    revision: number;
+    text: string;
+    provenance: string;
+    references?: WorkerContextUpdate['references'];
+    published_by: string;
+    published_at: number;
+}
+export interface WorkerDeploymentRequest {
+    worker_revision: number;
+    context_revision: number;
+    target: WorkerTargetReference;
+    lifecycle: 'persistent' | 'on_demand';
+    idempotency_key: string;
+}
+export interface WorkerDeploymentRecord {
+    id: string;
+    account_scope_id: string;
+    worker_id: string;
+    worker_revision: number;
+    context_revision: number;
+    target: WorkerTargetReference;
+    lifecycle: 'persistent' | 'on_demand';
+    revision: number;
+    generation: number;
+    desired_state: 'stopped' | 'running';
+    observed_state: 'unavailable';
+    approval_state: 'pending' | 'approved';
+    approval_digest: string;
+    approved_by?: string;
+    cleanup_scope: 'owned_runtime';
+    cleanup_state: 'not_allocated';
+    active_job_id?: string;
+    created_at: number;
+    updated_at: number;
+}
+export interface WorkerRunPlacement {
+    deployment_id: string;
+    deployment_revision: number;
+    target: WorkerTargetReference;
+    context_revision: number;
+    generation: number;
+    attempt_id: string;
+    attempt_number: number;
+    state: 'pending_adapter' | 'cancelled_before_dispatch';
+}
+export interface WorkerCommandRequest {
+    expected_revision: number;
+    generation: number;
+    kind: 'stop' | 'start';
+    idempotency_key: string;
+}
+export interface WorkerCommandRecord {
+    id: string;
+    deployment_id: string;
+    generation: number;
+    kind: 'stop';
+    status: 'pending' | 'acknowledged' | 'rejected';
+    requested_by: string;
+    created_at: number;
+}
+export interface WorkerCommandAcknowledgement {
+    generation: number;
+    status: 'acknowledged' | 'rejected';
+    evidence_digest: string;
+}
+export interface QueueWorkerDeploymentJob {
+    worker_revision: number;
+    deployment_revision: number;
+    context_revision: number;
+    idempotency_key: string;
+    input: {
+        prompt: string;
+        [key: string]: unknown;
+    };
+}
+/** Durable configuration/queued intent only. No SSH, cloud credentials or remote executor. */
+export declare class SwarmWorkerControlNamespace {
+    private transport;
+    constructor(transport: SwarmTransport);
+    private path;
+    private call;
+    registerSSHTarget(worker: string, request: WorkerSSHRegistration): Promise<WorkerTargetReference>;
+    registerGCPTarget(worker: string, request: WorkerGCPRegistration): Promise<WorkerTargetReference>;
+    resolveTarget(worker: string, target: WorkerTargetReference): Promise<WorkerTargetReference>;
+    getContext(worker: string, atRevision?: number): Promise<WorkerContextRecord>;
+    updateContext(worker: string, request: WorkerContextUpdate): Promise<WorkerContextRecord>;
+    proposeDeployment(worker: string, request: WorkerDeploymentRequest): Promise<WorkerDeploymentRecord>;
+    listDeployments(worker: string): Promise<WorkerDeploymentRecord[]>;
+    getDeployment(worker: string, deployment: string): Promise<WorkerDeploymentRecord>;
+    /** Explicit user approval of the exact digest; does not start a runtime. */
+    approveDeployment(worker: string, deployment: string, expectedRevision: number, approvalDigest: string): Promise<WorkerDeploymentRecord>;
+    queueJob(worker: string, deployment: string, request: QueueWorkerDeploymentJob): Promise<WorkerRunRecord>;
+    /** Start rejects with service unavailable. Stop is durable pending intent, not acknowledgement. */
+    command(worker: string, deployment: string, request: WorkerCommandRequest): Promise<WorkerCommandRecord>;
+    commands(worker: string, deployment: string): Promise<WorkerCommandRecord[]>;
+    acknowledgeCommand(worker: string, deployment: string, commandId: string, ack: WorkerCommandAcknowledgement): Promise<WorkerCommandRecord>;
+}