@swarm-agent/sdk 0.1.49 → 0.1.50

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>;
@@ -535,6 +539,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 +584,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 +788,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;

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.

package/dist/websocket.js

@@ -165,7 +165,7 @@ export class SwarmWebSocketBridge {
             },
             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 }),
+            onComplete: (messages, run) => send({ type: 'done', messages, run }),
             onError: error => {
                 send({ type: 'error', error: error.message });
                 if (this.activeWatches.get(ws)?.watch === watch) {

package/dist/workspaces.d.ts

@@ -4,6 +4,17 @@ export declare class SwarmWorkspacesNamespace {
     private transport;
     constructor(transport: SwarmTransport);
     createFolder(parent_path: string, name: string): Promise<WorkspaceFolder>;
+    /**
+     * Creates `parent_path/name` as a new, empty Git repository with one initial
+     * commit and registers it as a workspace, in one call. The daemon refuses a
+     * folder that already holds other content. Calling it again for a folder
+     * that is already registered returns that workspace.
+     */
+    create(body: {
+        parent_path: string;
+        name: string;
+        make_current?: boolean;
+    }): Promise<WorkspaceResolution>;
     add(body: {
         path: string;
         name?: string;

package/dist/workspaces.js

@@ -6,6 +6,23 @@ export class SwarmWorkspacesNamespace {
     async createFolder(parent_path, name) {
         return (await this.transport.request('/v1/workspace/folders/create', { method: 'POST', body: { parent_path, name } })).data.folder;
     }
+    /**
+     * Creates `parent_path/name` as a new, empty Git repository with one initial
+     * commit and registers it as a workspace, in one call. The daemon refuses a
+     * folder that already holds other content. Calling it again for a folder
+     * that is already registered returns that workspace.
+     */
+    async create(body) {
+        if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$/.test(body.name)) {
+            throw new Error('Workspace name must be letters, digits, dashes and underscores (at most 63).');
+        }
+        const parent = body.parent_path.replace(/\/+$/, '');
+        if (!parent.startsWith('/'))
+            throw new Error('parent_path must be absolute.');
+        const path = `${parent}/${body.name}`;
+        await this.setupRepository(path, path);
+        return this.add({ path, name: body.name, make_current: body.make_current ?? false });
+    }
     async add(body) {
         return (await this.transport.request('/v1/workspace/add', { method: 'POST', body })).data.workspace;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarm-agent/sdk",
-  "version": "0.1.49",
+  "version": "0.1.50",
   "description": "Official TypeScript SDK for Swarm local AI coding workspace",
   "type": "module",
   "main": "./dist/index.js",