@swarm-agent/sdk 0.1.50 → 0.1.52

package/README.md

@@ -21,8 +21,8 @@ Requires Node 22 or newer (ESM). The package is public on npm:
 npm install @swarm-agent/sdk
 </copy>
 
-You need a running Swarm on Linux x86_64. Install one with
-`curl -fsSL https://swarmagent.dev/install | sh -s -- --yes`.
+You need a running Swarm. Install the Swarm box (Ubuntu 24.04 x86_64) with
+`curl -fsSL https://swarmagent.dev/install | sudo bash`.
 
 ## Connect to your Swarm
 
@@ -58,10 +58,14 @@ example, not source tests or node_modules. `prepack` builds locally; there are n
 install/prepare hooks. TypeScript/tsx are build/test tools, not runtime dependencies.
 CommonJS `require` and non-Node runtimes are not validated by this packaging step.
 
-For the headless container, use the matching `@swarm-agent/cli` package and explicitly
-export a scoped token through `swarm-headless setup -- sdk-token`. Connect to
-`http://127.0.0.1:7783`; **do not** use Desktop bootstrap or a privileged socket.
-The headless listener allows session operations only, not the complete API below.
+On the Swarm box, `http://127.0.0.1:7783` is the scoped-token listener. The AI
+key the installer wrote to `~/.config/swarm/ai-key` (a new one:
+`sudo bash /var/lib/swarm-headless/src/containers/headless/app/install.sh connect-ai`)
+works only through its MCP, `http://127.0.0.1:7783/mcp`, with any MCP client;
+it reaches no SDK route. For the session routes there, use a client key (a full
+AI key's `swarm_create_client_key` mints one); **do not** use Desktop bootstrap
+or a privileged socket. A client key reaches session operations only, not the
+complete API below.
 The packaged `examples/headless-session.ts` imports `@swarm-agent/sdk` and can be copied
 into your consumer and run with an explicitly installed `tsx` runner. Protect its
 `SWARM_SDK_TOKEN_FILE` (0600); the example asks before each tool approval and uses
@@ -451,13 +455,28 @@ for (const ws of workspaces) {
 
 Manage multi-workspace projects, autonomous tasks, route previews, plan review lifecycles, and opaque event sync streams:
 
+A project groups registered workspaces: the existing folders or repositories the
+work lives in (`client.workspaces.add({ path, context_only: true,
+require_existing_content: true, make_current: false })`), not an empty
+repository created for it. Creating it makes Swarm write the project's
+`project.md` (the orchestrator's context) from the workspaces' AGENTS.md, README
+and file tree; `context_generation.status` moves from `pending`/`running` to
+`ready` or `failed` (`retryContext(id, attempt)`). Open orchestrator
+conversations once it is `ready`. Workspace and `project_context` edits through
+`update` are refused until then.
+
 ```typescript
-// Create a new project aggregating workspaces
-const project = await client.projects.create({
+// Create a new project aggregating the person's existing workspaces
+let project = await client.projects.create({
   name: 'Mobile Core Redesign',
   description: 'Refactor mobile navigation and auth screens',
   workspaces: [{ path: '/workspaces/mobile-app', role: 'primary_code' }],
 });
+// Re-read until project.md is generated (or follow realtime project updates)
+project = await client.projects.get(project.id);
+if (project.context_generation?.status === 'failed') {
+  project = await client.projects.retryContext(project.id, project.context_generation.attempt);
+}
 
 // Create an autonomous task with agent routing
 const { task, model_preview } = await client.projects.createTask(project.id, {

package/dist/auth.d.ts

@@ -25,10 +25,11 @@ export declare class SwarmAuthNamespace {
     /**
      * Creates an AI key for Swarm Control (`/mcp` on the scoped-token gateway).
      * `read` keys see and call only read tools; `write` keys may also start and
-     * steer sessions; neither may approve tool calls or manage anything. `full`
+     * steer sessions and start the person's ChatGPT sign-in (they finish it in
+     * their own browser); neither may approve tool calls or manage anything. `full`
      * keys are for an AI the owner trusts to run the box: they also approve
-     * tool calls and manage models, workers, limits, custom agents, client app
-     * keys and ChatGPT sign-in. Every level reaches only `/mcp`. Lifetime
+     * tool calls and manage models, workers, limits, custom agents and client app
+     * keys. Every level reaches only `/mcp`. Lifetime
      * defaults to 30 days (at most 365). Owner only.
      */
     createAIKey(params: {

package/dist/auth.js

@@ -57,10 +57,11 @@ export class SwarmAuthNamespace {
     /**
      * Creates an AI key for Swarm Control (`/mcp` on the scoped-token gateway).
      * `read` keys see and call only read tools; `write` keys may also start and
-     * steer sessions; neither may approve tool calls or manage anything. `full`
+     * steer sessions and start the person's ChatGPT sign-in (they finish it in
+     * their own browser); neither may approve tool calls or manage anything. `full`
      * keys are for an AI the owner trusts to run the box: they also approve
-     * tool calls and manage models, workers, limits, custom agents, client app
-     * keys and ChatGPT sign-in. Every level reaches only `/mcp`. Lifetime
+     * tool calls and manage models, workers, limits, custom agents and client app
+     * keys. Every level reaches only `/mcp`. Lifetime
      * defaults to 30 days (at most 365). Owner only.
      */
     async createAIKey(params) {

package/dist/box.d.ts

@@ -10,6 +10,26 @@ export interface BoxSummary {
     machine: {
         name?: string;
         uptime_ms: number;
+        version?: string;
+        commit?: string;
+        /** The installer's update state (install.sh update), when it has one. */
+        update?: {
+            auto?: 'on' | 'off';
+            channel?: string;
+            /** current, waiting, waiting_review, blocked, building, waiting_idle, installed, rolled_back or failed. */
+            state?: string;
+            reason?: string;
+            running?: string;
+            candidate?: string;
+            at?: number;
+        };
+    };
+    /** What a restart of Swarm would interrupt now, across the machine. */
+    busy: {
+        busy: boolean;
+        sessions: number;
+        worker_runs: number;
+        environment_builds: number;
     };
     sandbox: {
         mode: string;

package/dist/projects.d.ts

@@ -1,5 +1,5 @@
 import type { SwarmTransport } from './transport.js';
-import type { ApproveProjectTaskResult, ClearProjectContextResult, CompleteProjectTaskResult, CreateProjectParams, CreateProjectTaskParams, CreateProjectTaskResult, DeleteProjectMediaResult, DeleteProjectResult, DeleteProjectTaskResult, DeployProjectTaskProgramResult, GetProjectTaskProgramResult, GetProjectTaskResult, IntegrateProjectTaskOptions, IntegrateProjectTaskResult, IntegrateProjectTaskSelection, ListProjectsParams, PreviewProjectTaskParams, ProjectRecord, ProjectTaskApprovalGuards, ProjectTaskMediaRef, ProjectTaskModelPreviewResult, ProjectTaskPreviewResult, ProjectTaskRecord, RedeployProjectTaskJobResult, RefineProjectTaskParams, RefineProjectTaskResult, RejectProjectTaskResult, ReopenProjectTaskResult, RequestOptions, SessionRecord, SyncStreamParams, SyncStreamResult, SynthesizeProjectContextParams, UpdateProjectParams, UpdateProjectTaskParams } from './types.js';
+import type { ApproveProjectTaskResult, ClearProjectContextResult, CompleteProjectTaskResult, CreateProjectParams, CreateProjectTaskParams, CreateProjectTaskResult, DeleteProjectMediaResult, DeleteProjectResult, DeleteProjectTaskResult, DeployProjectTaskProgramResult, GetProjectTaskProgramResult, GetProjectTaskResult, IntegrateProjectTaskOptions, IntegrateProjectTaskResult, IntegrateProjectTaskSelection, ListProjectsParams, PreviewProjectTaskParams, ProjectRecord, ProjectTaskApprovalGuards, ProjectTaskMediaRef, ProjectTaskModelPreviewResult, ProjectTaskPreviewResult, ProjectTaskRecord, RedeployProjectTaskJobResult, RefineProjectTaskParams, RefineProjectTaskResult, RejectProjectTaskResult, ReopenProjectTaskResult, RequestOptions, SessionRecord, SyncStreamParams, SyncStreamResult, UpdateProjectParams, UpdateProjectTaskParams } from './types.js';
 export declare class SwarmProjectsNamespace {
     private readonly transport;
     constructor(transport: SwarmTransport);
@@ -65,10 +65,6 @@ export declare class SwarmProjectsNamespace {
      * Deletes a project by ID.
      */
     delete(projectId: string, options?: RequestOptions): Promise<DeleteProjectResult>;
-    /**
-     * Synthesizes Markdown project context from project name and linked workspaces.
-     */
-    synthesizeContext(params: SynthesizeProjectContextParams, options?: RequestOptions): Promise<string>;
     /**
      * Clears orchestrator context for a project, archiving old session and provisioning replacement.
      */

package/dist/projects.js

@@ -178,17 +178,6 @@ export class SwarmProjectsNamespace {
         const res = await this.transport.request(`/v3/projects/${id}`, { method: 'DELETE', ...options });
         return res.data ?? { status: 'deleted', id: projectId.trim() };
     }
-    /**
-     * Synthesizes Markdown project context from project name and linked workspaces.
-     */
-    async synthesizeContext(params, options) {
-        const res = await this.transport.request('/v3/projects/synthesize-context', {
-            method: 'POST',
-            body: params,
-            ...options,
-        });
-        return res.data?.project_context ?? '';
-    }
     /**
      * Clears orchestrator context for a project, archiving old session and provisioning replacement.
      */

package/dist/types.d.ts

@@ -500,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;
@@ -982,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;
@@ -1001,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;
@@ -1038,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>;
@@ -1081,6 +1094,7 @@ export interface PortableWorkerDefinition {
     provenance?: PortableWorkerProvenance | null;
 }
 export interface CreateWorkerParams {
+    role?: WorkerRole;
     name: string;
     description?: string;
     instructions?: string;
@@ -1091,6 +1105,7 @@ export interface CreateWorkerParams {
     idempotency_key: string;
 }
 export interface UpdateWorkerParams {
+    role?: WorkerRole;
     name?: string;
     description?: string;
     instructions?: string;
@@ -1174,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;
@@ -1181,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/workers.d.ts

@@ -25,6 +25,12 @@ export declare class SwarmWorkersNamespace {
      * Lists durable workers with pagination, lifecycle filters, and cursor support.
      */
     list(params?: ListWorkersParams): Promise<ListWorkersResult>;
+    /**
+     * Creates and activates the box's missing premade workers (Coder, Designer,
+     * Finder) and returns all three. Existing presets are returned unchanged.
+     * Presets are box-level: every job names its workspace.
+     */
+    ensurePresets(): Promise<WorkerRecord[]>;
     /**
      * Updates a worker's definition with an explicit expected revision for optimistic concurrency.
      * Body carries expected_revision only (no query params, no local_bindings).

package/dist/workers.js

@@ -39,6 +39,8 @@ export class SwarmWorkersNamespace {
             instructions: params.instructions,
             idempotency_key: params.idempotency_key.trim(),
         };
+        if (params.role !== undefined)
+            body.role = params.role;
         if (params.description !== undefined)
             body.description = params.description;
         if (params.requested_capabilities !== undefined)
@@ -132,6 +134,21 @@ export class SwarmWorkersNamespace {
             next_cursor: typeof res.data.next_cursor === 'string' && res.data.next_cursor.length > 0 ? res.data.next_cursor : undefined,
         };
     }
+    /**
+     * Creates and activates the box's missing premade workers (Coder, Designer,
+     * Finder) and returns all three. Existing presets are returned unchanged.
+     * Presets are box-level: every job names its workspace.
+     */
+    async ensurePresets() {
+        const res = await this.transport.request('/v3/workers:ensure-presets', {
+            method: 'POST',
+            body: {},
+        });
+        if (!res.data || typeof res.data !== 'object' || !Array.isArray(res.data.workers)) {
+            throw new SwarmValidationError('Malformed response envelope: expected workers array');
+        }
+        return res.data.workers;
+    }
     /**
      * Updates a worker's definition with an explicit expected revision for optimistic concurrency.
      * Body carries expected_revision only (no query params, no local_bindings).
@@ -151,6 +168,8 @@ export class SwarmWorkersNamespace {
         const body = {
             expected_revision: expectedRevision,
         };
+        if (params.role !== undefined)
+            body.role = params.role;
         if (params.name !== undefined)
             body.name = params.name;
         if (params.description !== undefined)
@@ -593,6 +612,10 @@ export class SwarmWorkersNamespace {
             body.input = params.input;
         if (params.idempotency_key)
             body.idempotency_key = params.idempotency_key.trim();
+        if (params.workspace_id && params.workspace_id.trim() !== '')
+            body.workspace_id = params.workspace_id.trim();
+        if (params.workspace_path && params.workspace_path.trim() !== '')
+            body.workspace_path = params.workspace_path.trim();
         const res = await this.transport.request(`/v3/workers/${encodeURIComponent(params.worker_id.trim())}/direct`, {
             method: 'POST',
             headers,
@@ -629,6 +652,10 @@ export class SwarmWorkersNamespace {
         }
         if (params.idempotency_key)
             body.idempotency_key = params.idempotency_key.trim();
+        if (params.workspace_id && params.workspace_id.trim() !== '')
+            body.workspace_id = params.workspace_id.trim();
+        if (params.workspace_path && params.workspace_path.trim() !== '')
+            body.workspace_path = params.workspace_path.trim();
         const res = await this.transport.request(`/v3/workers/${encodeURIComponent(params.worker_id.trim())}/test`, {
             method: 'POST',
             headers,

package/dist/workspaces.d.ts

@@ -15,12 +15,21 @@ export declare class SwarmWorkspacesNamespace {
         name: string;
         make_current?: boolean;
     }): Promise<WorkspaceResolution>;
+    /**
+     * Registers an existing folder. A Git repository by default; with
+     * `context_only` any readable folder (a project source, never selected as the
+     * coding workspace), and with `require_existing_content` as well the daemon
+     * refuses empty folders, system/Swarm storage directories and folders inside
+     * an already registered workspace (for folders the person named).
+     */
     add(body: {
         path: string;
         name?: string;
         theme_id?: string;
         make_current?: boolean;
         confirm_committed_only?: boolean;
+        context_only?: boolean;
+        require_existing_content?: boolean;
     }): Promise<WorkspaceResolution>;
     inspectRepository(path: string): Promise<WorkspaceRepository>;
     setupRepository(path: string, expected_resolved_path: string): Promise<WorkspaceRepository>;

package/dist/workspaces.js

@@ -23,6 +23,13 @@ export class SwarmWorkspacesNamespace {
         await this.setupRepository(path, path);
         return this.add({ path, name: body.name, make_current: body.make_current ?? false });
     }
+    /**
+     * Registers an existing folder. A Git repository by default; with
+     * `context_only` any readable folder (a project source, never selected as the
+     * coding workspace), and with `require_existing_content` as well the daemon
+     * refuses empty folders, system/Swarm storage directories and folders inside
+     * an already registered workspace (for folders the person named).
+     */
     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.50",
+  "version": "0.1.52",
   "description": "Official TypeScript SDK for Swarm local AI coding workspace",
   "type": "module",
   "main": "./dist/index.js",