@swarm-agent/sdk 0.1.49 → 0.1.51

package/dist/remote.js

@@ -0,0 +1,46 @@
+/**
+ * Owner administration of the machine's relay connection (`/v1/remote*`).
+ * The daemon refuses scoped tokens here: call it only from a trusted backend
+ * on the private local transport, never from a browser.
+ */
+export class SwarmRemoteNamespace {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async call(path, method, body) {
+        const res = await this.transport.request(`/v1/remote${path}`, { method, ...(method === 'POST' ? { body: body ?? {} } : {}) });
+        return res.data.remote;
+    }
+    status() {
+        return this.call('', 'GET');
+    }
+    /** Creates this machine's device key for one relay. Does not connect. */
+    init(input) {
+        return this.call('/init', 'POST', {
+            relay_url: input.relay_url, device_name: input.device_name,
+            allow_write: input.allow_write === true, allow_approve: input.allow_approve === true, allow_manage: input.allow_manage === true,
+        });
+    }
+    enable() {
+        return this.call('/enable', 'POST');
+    }
+    disable() {
+        return this.call('/disable', 'POST');
+    }
+    /**
+     * Approves or denies an AI client's authorization request shown on the
+     * relay's consent page. Approved scopes are clamped to the request and to
+     * this machine's ceiling by the daemon.
+     */
+    async decideConsent(code, approve, scopes) {
+        const res = await this.transport.request(`/v1/remote/consents/${approve ? 'approve' : 'deny'}`, {
+            method: 'POST', body: approve && scopes ? { code, scopes } : { code },
+        });
+        return res.data.consent;
+    }
+    /** Disconnects, revokes the device token and deletes the device key. */
+    reset() {
+        return this.call('/reset', 'POST');
+    }
+}

package/dist/sessions.d.ts

@@ -35,14 +35,44 @@ export declare class SwarmSessionsNamespace {
      * Deletes a session and triggers cascading cancellation of associated runs and worktrees.
      */
     delete(sessionId: string): Promise<boolean>;
+    /**
+     * Renames a session or project conversation you own (`POST /v3/sessions/{id}/title`).
+     * The title is trimmed and must be 1–200 characters. A renamed conversation keeps its
+     * title: Swarm no longer titles it automatically. (Untitled conversations are named
+     * from their first message.) Retrying with the same `clientRequestId` is idempotent.
+     */
+    rename(sessionId: string, title: string, options?: {
+        clientRequestId?: string;
+    }): Promise<{
+        ok: boolean;
+        session_id: string;
+        title: string;
+    }>;
     /**
      * Appends a message to a session conversation.
      */
     sendMessage(sessionId: string, params: {
         content: string;
-        role?: 'user' | 'assistant' | 'system';
+        role?: 'user';
         client_request_id?: string;
     }): Promise<any>;
+    /**
+     * Starts a fresh model context in the same conversation (`POST /v3/sessions/{id}/context/clear`).
+     * History stays visible and the session ID is unchanged; the next turn starts without the
+     * earlier provider context. The daemon accepts this only for an idle project conversation
+     * without an unresolved plan, and only when `expectedLastEventSeq` equals the session's current
+     * durable sequence (`state.snapshot.projections_by_session[id].last_event_seq`); otherwise it
+     * rejects with `SwarmConflictError` and changes nothing. A standalone chat session cannot be
+     * cleared: create a new session instead. Retrying with the same `clientRequestId` is idempotent.
+     */
+    clearContext(sessionId: string, params: {
+        expectedLastEventSeq: number;
+        clientRequestId?: string;
+    }): Promise<{
+        ok: boolean;
+        session_id: string;
+        mutation: Record<string, unknown>;
+    }>;
     /**
      * Stops an active execution run for a session.
      */

package/dist/sessions.js

@@ -84,10 +84,14 @@ export class SwarmSessionsNamespace {
         const data = res.data;
         if (data && typeof data === 'object') {
             const sessionObj = data.session || data;
+            // V3 sessions carry their source workspace as the primary grant.
+            const primaryGrant = Array.isArray(sessionObj.workspace_grants)
+                ? sessionObj.workspace_grants.find((grant) => grant?.kind === 'primary')
+                : undefined;
             return {
                 id: sessionObj.id || sessionObj.session_id || sessionId,
                 title: sessionObj.title || '',
-                workspace_id: sessionObj.workspace_id,
+                workspace_id: sessionObj.workspace_id || primaryGrant?.workspace_id,
                 workspace_path: sessionObj.workspace_path,
                 state: sessionObj.state || data.projection?.state || 'idle',
                 mode: sessionObj.mode,
@@ -145,6 +149,27 @@ export class SwarmSessionsNamespace {
         });
         return res.data?.ok === true;
     }
+    /**
+     * Renames a session or project conversation you own (`POST /v3/sessions/{id}/title`).
+     * The title is trimmed and must be 1–200 characters. A renamed conversation keeps its
+     * title: Swarm no longer titles it automatically. (Untitled conversations are named
+     * from their first message.) Retrying with the same `clientRequestId` is idempotent.
+     */
+    async rename(sessionId, title, options = {}) {
+        const id = sessionId.trim();
+        if (!id)
+            throw new Error('sessionId is required');
+        const trimmed = typeof title === 'string' ? title.trim() : '';
+        if (!trimmed)
+            throw new Error('title is required');
+        if ([...trimmed].length > 200)
+            throw new Error('title must be 200 characters or fewer');
+        const res = await this.transport.request(`/v3/sessions/${encodeURIComponent(id)}/title`, {
+            method: 'POST',
+            body: { title: trimmed, client_request_id: options.clientRequestId || generateRequestId() },
+        });
+        return res.data;
+    }
     /**
      * Appends a message to a session conversation.
      */
@@ -161,6 +186,29 @@ export class SwarmSessionsNamespace {
         });
         return res.data;
     }
+    /**
+     * Starts a fresh model context in the same conversation (`POST /v3/sessions/{id}/context/clear`).
+     * History stays visible and the session ID is unchanged; the next turn starts without the
+     * earlier provider context. The daemon accepts this only for an idle project conversation
+     * without an unresolved plan, and only when `expectedLastEventSeq` equals the session's current
+     * durable sequence (`state.snapshot.projections_by_session[id].last_event_seq`); otherwise it
+     * rejects with `SwarmConflictError` and changes nothing. A standalone chat session cannot be
+     * cleared: create a new session instead. Retrying with the same `clientRequestId` is idempotent.
+     */
+    async clearContext(sessionId, params) {
+        if (!Number.isSafeInteger(params.expectedLastEventSeq) || params.expectedLastEventSeq < 0) {
+            throw new Error('expectedLastEventSeq must be the current non-negative session event sequence');
+        }
+        const id = encodeURIComponent(sessionId.trim());
+        const res = await this.transport.request(`/v3/sessions/${id}/context/clear`, {
+            method: 'POST',
+            body: {
+                client_request_id: params.clientRequestId || generateRequestId(),
+                expected_last_event_seq: params.expectedLastEventSeq,
+            },
+        });
+        return res.data;
+    }
     /**
      * Stops an active execution run for a session.
      */

package/dist/settings.d.ts

@@ -98,6 +98,9 @@ export declare class SwarmSettingsNamespace {
     /**
      * Restores verified recommended defaults across all system agent and swarm core roles.
      * If expectedUpdatedAt is omitted, automatically reads the current setting's revision first.
+     * An account with no model settings yet (a provider is connected but its
+     * models were never set up) restores from revision 0: the daemon then sets
+     * up the recommended models from a ready provider.
      */
     restoreDefaults(expectedUpdatedAt?: number): Promise<AgentModelSettingsResponse>;
     /**

package/dist/settings.js

@@ -1,3 +1,4 @@
+import { SwarmNotFoundError } from './errors.js';
 /** Account-scoped settings. Requires the local administrative connection, not a session token. */
 export class SwarmSettingsNamespace {
     transport;
@@ -23,12 +24,22 @@ export class SwarmSettingsNamespace {
     /**
      * Restores verified recommended defaults across all system agent and swarm core roles.
      * If expectedUpdatedAt is omitted, automatically reads the current setting's revision first.
+     * An account with no model settings yet (a provider is connected but its
+     * models were never set up) restores from revision 0: the daemon then sets
+     * up the recommended models from a ready provider.
      */
     async restoreDefaults(expectedUpdatedAt) {
         let updatedAt = expectedUpdatedAt;
         if (typeof updatedAt !== 'number') {
-            const current = await this.agentModels();
-            updatedAt = current.agent_model_settings.updated_at;
+            try {
+                const current = await this.agentModels();
+                updatedAt = current.agent_model_settings.updated_at;
+            }
+            catch (error) {
+                if (!(error instanceof SwarmNotFoundError))
+                    throw error;
+                updatedAt = 0;
+            }
         }
         return (await this.transport.request('/v1/agent-model-settings/restore-defaults', {
             method: 'POST',
@@ -87,7 +98,12 @@ export class SwarmSettingsNamespace {
      */
     async applyProviderFleet(provider) {
         const fleet = await this.getRecommendationsForProvider(provider);
-        return this.patch(fleet);
+        // The daemon takes one target per PATCH: the swarm pair, then each system agent.
+        let result = await this.patch({ swarm: fleet.swarm });
+        for (const [slot, assignment] of Object.entries(fleet.system_agents)) {
+            result = await this.patch({ system_agents: { [slot]: assignment } });
+        }
+        return result;
     }
     async patch(body) {
         return (await this.transport.request('/v1/agent-model-settings', { method: 'PATCH', body })).data;

package/dist/signals.d.ts

@@ -0,0 +1,148 @@
+import type { SwarmTransport } from './transport.js';
+export type SignalSeverity = 'info' | 'warning' | 'critical';
+/**
+ * One entry in a machine's signal feed: a high-level event such as an agent
+ * waiting on a person, a failed run, a refused key or an event an outside
+ * source reported. Signals carry ids and a one-line summary, never transcripts,
+ * command arguments or secret values.
+ */
+export interface Signal {
+    /** Position in this machine's feed; pass the last one back as `after`. */
+    seq: number;
+    /** Unique id, stable across forwarding (use it to drop duplicates). */
+    id: string;
+    /** Unix milliseconds. */
+    at: number;
+    /** Dotted kind, e.g. `agent.blocked`, `run.failed`, `external.falco`. */
+    kind: string;
+    severity: SignalSeverity;
+    /** `swarmd` for Swarm's own signals, `external:<name>` for reported ones. */
+    source: string;
+    /** Empty for machine-wide signals. */
+    account?: string;
+    summary: string;
+    /** Signals with the same key describe the same ongoing condition. */
+    dedup_key?: string;
+    refs?: Record<string, string>;
+    attrs?: Record<string, string>;
+}
+export interface SignalPage {
+    signals: Signal[];
+    /** The last position examined; pass it as `after` to continue. */
+    next_after: number;
+    oldest_seq: number;
+    latest_seq: number;
+    /**
+     * True when signals after your cursor were already dropped (the feed keeps
+     * the newest entries only) or your cursor is ahead of the feed. Resync
+     * from `next_after` and treat the missed range as unknown.
+     */
+    gap: boolean;
+}
+export interface ListSignalsParams {
+    /** Return signals numbered after this position (default 0: from the oldest kept). */
+    after?: number;
+    /** At most this many signals (default 100, maximum 500). */
+    limit?: number;
+    /** Kind prefixes, e.g. `['agent', 'run.failed']`. */
+    kinds?: string[];
+    /** Only signals at least this severe. */
+    minSeverity?: SignalSeverity;
+}
+export interface ReportSignalParams {
+    /** Must start with `external.`, e.g. `external.falco`. */
+    kind: string;
+    /** One line; longer text is cut to 300 characters. */
+    summary: string;
+    severity?: SignalSeverity;
+    /** Lowercase name of the reporting source, e.g. `falco`. */
+    source?: string;
+    dedup_key?: string;
+    refs?: Record<string, string>;
+    attrs?: Record<string, string>;
+}
+/**
+ * The machine signal feed. Reading needs a key with `signals:read`; reporting
+ * an outside event needs `signals:write`. Readers see their own account's
+ * signals and machine-wide ones.
+ */
+export declare class SwarmSignalsNamespace {
+    private readonly transport;
+    /** Where this machine forwards its feed (owner only). */
+    readonly sinks: SwarmSignalSinksNamespace;
+    constructor(transport: SwarmTransport);
+    /** Lists signals after a cursor, oldest first. */
+    list(params?: ListSignalsParams): Promise<SignalPage>;
+    /**
+     * Reports an outside event (a host security monitor, a backup script) into
+     * the feed. Swarm records the source as `external:<source>` and, for a
+     * scoped key, which key reported it.
+     */
+    report(params: ReportSignalParams): Promise<Signal>;
+}
+/** Where a machine forwards its signal feed (owner only). */
+export interface SignalSink {
+    id: string;
+    account: string;
+    name: string;
+    url: string;
+    kinds?: string[];
+    min_severity?: SignalSeverity;
+    heartbeat_seconds: number;
+    /** Last signal position the sink accepted. */
+    cursor: number;
+    created_at: number;
+    last_delivered_at?: number;
+    last_attempt_at?: number;
+    last_error?: string;
+    failures?: number;
+}
+export interface CreateSignalSinkParams {
+    name: string;
+    /** https URL (http only to this machine's loopback). */
+    url: string;
+    /** Kind prefixes to forward, e.g. `['agent', 'worker.run.failed']`; empty forwards all. */
+    kinds?: string[];
+    minSeverity?: SignalSeverity;
+    /** Idle heartbeat interval, 30 to 3600 seconds (default 60). */
+    heartbeatSeconds?: number;
+}
+/**
+ * Signal sinks: the machine POSTs batches of its feed to each sink, signed
+ * with the sink's secret (see `verifySignalDelivery`). Owner only: scoped
+ * keys, including admin keys, are refused.
+ */
+export declare class SwarmSignalSinksNamespace {
+    private readonly transport;
+    constructor(transport: SwarmTransport);
+    list(): Promise<SignalSink[]>;
+    /** Creates a sink. The signing secret is returned only here; store it in the receiver. */
+    create(params: CreateSignalSinkParams): Promise<{
+        sink: SignalSink;
+        secret: string;
+    }>;
+    delete(id: string): Promise<void>;
+}
+/** Body of one signal delivery (version 1). */
+export interface SignalDelivery {
+    version: 1;
+    sink_id: string;
+    machine?: string;
+    sent_at: number;
+    /** True for an idle heartbeat with no signals. */
+    heartbeat: boolean;
+    signals: Signal[];
+    next_after: number;
+    latest_seq: number;
+    gap: boolean;
+}
+/**
+ * Checks a delivery's `X-Swarm-Signature` for a receiver: HMAC-SHA256 of
+ * `${X-Swarm-Timestamp}.${rawBody}` with the sink secret, and a timestamp
+ * within `maxSkewMs` of now (rejects replays). Pass the raw request body,
+ * not re-serialized JSON. Works with WebCrypto (Node 18+, Workers, browsers).
+ */
+export declare function verifySignalDelivery(secret: string, timestamp: string | number, rawBody: string | Uint8Array, signature: string, { now, maxSkewMs }?: {
+    now?: number;
+    maxSkewMs?: number;
+}): Promise<boolean>;

package/dist/signals.js

@@ -0,0 +1,97 @@
+/**
+ * The machine signal feed. Reading needs a key with `signals:read`; reporting
+ * an outside event needs `signals:write`. Readers see their own account's
+ * signals and machine-wide ones.
+ */
+export class SwarmSignalsNamespace {
+    transport;
+    /** Where this machine forwards its feed (owner only). */
+    sinks;
+    constructor(transport) {
+        this.transport = transport;
+        this.sinks = new SwarmSignalSinksNamespace(transport);
+    }
+    /** Lists signals after a cursor, oldest first. */
+    async list(params = {}) {
+        const q = new URLSearchParams();
+        if (typeof params.after === 'number')
+            q.set('after', String(params.after));
+        if (typeof params.limit === 'number')
+            q.set('limit', String(params.limit));
+        if (params.kinds?.length)
+            q.set('kind', params.kinds.join(','));
+        if (params.minSeverity)
+            q.set('min_severity', params.minSeverity);
+        const path = q.toString() ? `/v3/signals?${q.toString()}` : '/v3/signals';
+        const res = await this.transport.request(path, { method: 'GET' });
+        const { signals, next_after, oldest_seq, latest_seq, gap } = res.data;
+        return { signals: signals ?? [], next_after, oldest_seq, latest_seq, gap };
+    }
+    /**
+     * Reports an outside event (a host security monitor, a backup script) into
+     * the feed. Swarm records the source as `external:<source>` and, for a
+     * scoped key, which key reported it.
+     */
+    async report(params) {
+        const res = await this.transport.request('/v3/signals', {
+            method: 'POST',
+            body: params,
+        });
+        return res.data.signal;
+    }
+}
+/**
+ * Signal sinks: the machine POSTs batches of its feed to each sink, signed
+ * with the sink's secret (see `verifySignalDelivery`). Owner only: scoped
+ * keys, including admin keys, are refused.
+ */
+export class SwarmSignalSinksNamespace {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async list() {
+        const res = await this.transport.request('/v3/signals/sinks', { method: 'GET' });
+        return res.data.sinks ?? [];
+    }
+    /** Creates a sink. The signing secret is returned only here; store it in the receiver. */
+    async create(params) {
+        const res = await this.transport.request('/v3/signals/sinks', {
+            method: 'POST',
+            body: {
+                name: params.name,
+                url: params.url,
+                kinds: params.kinds,
+                min_severity: params.minSeverity,
+                heartbeat_seconds: params.heartbeatSeconds,
+            },
+        });
+        return { sink: res.data.sink, secret: res.data.secret };
+    }
+    async delete(id) {
+        await this.transport.request(`/v3/signals/sinks/${encodeURIComponent(id)}`, { method: 'DELETE' });
+    }
+}
+/**
+ * Checks a delivery's `X-Swarm-Signature` for a receiver: HMAC-SHA256 of
+ * `${X-Swarm-Timestamp}.${rawBody}` with the sink secret, and a timestamp
+ * within `maxSkewMs` of now (rejects replays). Pass the raw request body,
+ * not re-serialized JSON. Works with WebCrypto (Node 18+, Workers, browsers).
+ */
+export async function verifySignalDelivery(secret, timestamp, rawBody, signature, { now = Date.now(), maxSkewMs = 5 * 60 * 1000 } = {}) {
+    const ts = Number(timestamp);
+    if (!Number.isFinite(ts) || Math.abs(now - ts) > maxSkewMs || !signature.startsWith('v1='))
+        return false;
+    const enc = new TextEncoder();
+    const body = typeof rawBody === 'string' ? enc.encode(rawBody) : rawBody;
+    const message = new Uint8Array([...enc.encode(`${ts}.`), ...body]);
+    const key = await crypto.subtle.importKey('raw', enc.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const mac = new Uint8Array(await crypto.subtle.sign('HMAC', key, message));
+    const expected = 'v1=' + Array.from(mac, (b) => b.toString(16).padStart(2, '0')).join('');
+    if (expected.length !== signature.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < expected.length; i++)
+        diff |= expected.charCodeAt(i) ^ signature.charCodeAt(i);
+    return diff === 0;
+}

package/dist/types.d.ts

@@ -1,10 +1,14 @@
 export type TokenScope = 'automations:trigger' | 'automations:read' | 'automations:write' | 'sessions:read' | 'sessions:write' | 'projects:read' | 'projects:write' | 'admin' | string;
 export interface SwarmClientConfig {
-    /** Base URL for the Swarm API/Desktop daemon (e.g. http://127.0.0.1:18080 or http://127.0.0.1:7781) */
+    /**
+     * Base URL of the Swarm daemon API (default http://127.0.0.1:7781). With no
+     * `baseUrl`, `socketPath` or environment override, Node clients use the
+     * owner socket of a system install when this process may connect to it.
+     */
     baseUrl?: string;
     /** Bearer authentication token (attach token or scoped token starting with 'swk_') */
     token?: string;
-    /** Unix domain socket path for zero-conf local IPC (e.g. /run/swarmd/swarmd.sock) */
+    /** Unix socket for local IPC (owner socket: /var/lib/swarmd/local-transport/api.sock) */
     socketPath?: string;
     /** Custom default HTTP headers */
     defaultHeaders?: Record<string, string>;
@@ -496,10 +500,6 @@ export interface UpdateProjectParams {
 export interface ListProjectsParams {
     limit?: number;
 }
-export interface SynthesizeProjectContextParams {
-    name: string;
-    workspaces: string[];
-}
 export interface DeleteProjectResult {
     status: string;
     id: string;
@@ -535,6 +535,43 @@ export interface ProjectTaskPlanBinding {
     session_id?: string;
     receipt?: string;
 }
+/**
+ * Backend-inspected delivery facts for a task's captured worktree lane. Only the
+ * task-detail GET (`getTask`) observes Git; collection rows carry `freshness: 'stale'`.
+ */
+export interface ProjectTaskDeliveryAssessment {
+    task_id?: string;
+    task_revision?: number;
+    attempt_id?: string;
+    session_id?: string;
+    base_oid?: string;
+    source_oid?: string;
+    target_oid?: string;
+    source_branch?: string;
+    target_branch?: string;
+    state?: 'candidate_work' | 'integrated' | 'unavailable' | string;
+    reason_code?: string;
+    reason?: string;
+    freshness?: 'observed' | 'stale' | 'unknown' | string;
+    source_dirty?: boolean;
+    target_dirty?: boolean;
+    candidate_commits?: number;
+    files?: string[];
+    allowed_actions?: string[];
+    [key: string]: unknown;
+}
+/** One coordinator attempt (session reservation) on a project task. */
+export interface ProjectTaskAttempt {
+    id: string;
+    session_id?: string;
+    status?: string;
+    role?: string;
+    workspace_path?: string;
+    worktree_branch?: string;
+    base_branch?: string;
+    base_commit?: string;
+    [key: string]: unknown;
+}
 export interface ProjectTaskRecord {
     id: string;
     project_id: string;
@@ -543,6 +580,9 @@ export interface ProjectTaskRecord {
     description?: string;
     status: 'queued' | 'in_progress' | 'needs_review' | 'completed' | 'failed' | 'pending_approval' | 'planning' | 'rejected' | string;
     session_id?: string;
+    active_attempt_id?: string;
+    attempts?: ProjectTaskAttempt[];
+    delivery_assessment?: ProjectTaskDeliveryAssessment;
     agent?: string;
     worker_name?: string;
     outcome_type?: string;
@@ -744,6 +784,30 @@ export interface RefineProjectTaskResult {
     status: 'refined' | string;
     task: ProjectTaskRecord;
 }
+/**
+ * Selection body for POST /v3/projects/{id}/tasks/{taskId}/integrate. The daemon
+ * requires `session_id` (must equal the task's current session) plus the captured
+ * `source_branch`/`target_branch` (must equal the session worktree branch and its
+ * base branch). The remaining fields are the stale-state guards the daemon's
+ * `recover-integrate` path checks; plain integrate accepts and ignores them.
+ */
+export interface IntegrateProjectTaskSelection {
+    session_id: string;
+    source_branch: string;
+    target_branch: string;
+    revision?: number;
+    attempt_id?: string;
+    source_head?: string;
+    target_head?: string;
+}
+export interface IntegrateProjectTaskOptions extends RequestOptions {
+    /**
+     * Overrides merged over the selection the SDK derives from a fresh `getTask`.
+     * When `session_id`, `source_branch` and `target_branch` are all supplied, the
+     * SDK skips the task fetch and sends them as given.
+     */
+    selection?: Partial<IntegrateProjectTaskSelection>;
+}
 export interface IntegrateProjectTaskResult {
     status: 'integrated' | 'already_integrated' | string;
     message?: string;
@@ -914,10 +978,18 @@ export interface WorkerAutomationDefinition {
     plan_document: SessionPlanDocument;
     input_requirements?: WorkerInputRequirement[] | null;
     deliverable_requirements?: WorkerDeliverableRequirement[] | null;
+    /** Registered workspace this automation's runs work in; absent means the worker's primary binding. */
+    workspace_id?: string | null;
     revision: number;
     created_at: number;
     updated_at: number;
 }
+/**
+ * Code-owned system agent that runs a worker's jobs. Absent means `swarm`.
+ * `swarm` executes jobs as accepted plans; `coder`, `designer` and `finder`
+ * run their compiled agent in an auto session.
+ */
+export type WorkerRole = 'swarm' | 'coder' | 'designer' | 'finder';
 export interface WorkerAutomationInput {
     name: string;
     description?: string;
@@ -933,10 +1005,13 @@ export interface WorkerAutomationInput {
     plan_document: SessionPlanDocument;
     input_requirements?: WorkerInputRequirement[];
     deliverable_requirements?: WorkerDeliverableRequirement[];
+    /** Registered workspace this automation's runs work in. Required for schedules of a worker with no primary binding. */
+    workspace_id?: string;
 }
 export interface WorkerRecord {
     id: string;
     account_scope_id: string;
+    role?: WorkerRole | null;
     name: string;
     description?: string | null;
     instructions: string;
@@ -970,6 +1045,12 @@ export interface WorkerRunRecord {
     automation_id?: string;
     automation_revision?: number;
     occurrence_id?: string;
+    /** Workspace pinned at admission. */
+    workspace_id?: string;
+    /** `worker_job` when the request or automation named the workspace, `worker_binding` when it came from the primary binding. */
+    workspace_source?: 'worker_job' | 'worker_binding' | string;
+    /** Worker role pinned at admission; absent means `swarm`. */
+    role?: WorkerRole | string;
     session_id?: string;
     request_source: 'direct' | 'schedule' | 'trigger' | 'test_run' | 'orchestrator' | string;
     input?: Record<string, unknown>;
@@ -1013,6 +1094,7 @@ export interface PortableWorkerDefinition {
     provenance?: PortableWorkerProvenance | null;
 }
 export interface CreateWorkerParams {
+    role?: WorkerRole;
     name: string;
     description?: string;
     instructions?: string;
@@ -1023,6 +1105,7 @@ export interface CreateWorkerParams {
     idempotency_key: string;
 }
 export interface UpdateWorkerParams {
+    role?: WorkerRole;
     name?: string;
     description?: string;
     instructions?: string;
@@ -1106,6 +1189,10 @@ export interface DirectWorkerRequestParams {
     prompt?: string;
     input?: Record<string, unknown>;
     idempotency_key?: string;
+    /** Workspace this job works in (registered workspace ID). Required when the worker has no primary binding. */
+    workspace_id?: string;
+    /** Alternative to workspace_id: the exact root path of a registered workspace. */
+    workspace_path?: string;
 }
 export interface TestWorkerRunParams {
     worker_id: string;
@@ -1113,6 +1200,10 @@ export interface TestWorkerRunParams {
     prompt?: string;
     input?: Record<string, unknown>;
     idempotency_key?: string;
+    /** Workspace this job works in (registered workspace ID). */
+    workspace_id?: string;
+    /** Alternative to workspace_id: the exact root path of a registered workspace. */
+    workspace_path?: string;
 }
 export interface TriggerWorkerParams {
     worker_id: string;

package/dist/websocket.d.ts

@@ -3,7 +3,7 @@ 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';
+import type { SessionWatchState, V3Message, V3RunState } from './realtime.js';
 export interface SwarmWebSocketBridgeOptions {
     path?: string;
     /** Server-owned policy. Browser frames cannot enable auto approval. Questions always require a reply. */
@@ -37,6 +37,8 @@ export interface SwarmWebSocketServerMessage {
     result?: ResolvePermissionResult;
     permissionId?: string;
     messages?: V3Message[];
+    /** Finished run on `done`: `status` is completed, failed, cancelled, ... */
+    run?: V3RunState;
     error?: string;
 }
 /** Application-owned bridge to canonical V3 realtime. A subscription survives every turn.