@swarm-agent/sdk 0.1.51 → 0.1.53

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-launcher | 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/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
@@ -69,9 +73,18 @@ explicit refresh, not timer polling. Live agent verification is a separate step.
 
 ## Quick Start
 
-### Chat Flow vs. Autonomous Orchestration Flow
+### Workers and jobs
 
-Swarm supports two distinct modes of execution depending on your application goals:
+Start with a project and its authorized folders, then give jobs to workers:
+coder for code changes, designer for UI/design, finder for research, or reviewer
+for independent read-only review of another job. Reviewers require `review_job`,
+use detached disposable checkouts, and report without delivering. Worker models
+follow account role settings unless pinned. Read each job's result before
+delivery (local merge, configured pull request, or queued landing).
+
+### Advanced: sessions, plans and orchestration
+
+For conversational interfaces or structured multi-stage work:
 
 1. **Interactive Chat Flow (`client.chat` / `client.sessions`)**:
    - Best for conversational assistants, interactive Q&A, and direct tool calling.
@@ -80,7 +93,7 @@ Swarm supports two distinct modes of execution depending on your application goa
 
 2. **Autonomous Orchestration Flow (`client.projects` / `client.workers` / `client.deploy`)**:
    - Best for multi-agent background tasks, codebase modifications, and durable pipelines.
-   - Deploys specialized subagent fleets (Coder, Finder, Designer, Router, Compact) across bounded repository worktrees with structured checkpoint contracts.
+   - Organizes worker jobs across authorized folders with structured plans and checkpoint contracts.
    - **Project → orchestrator conversations → delegated tasks → task sessions.** Project Markdown and linked workspaces provide high-level context; each deployed task resolves its own authorized execution workspace.
    - Use `client.projects.listConversations(projectId)` and `createConversation(projectId)` for the session picker and New Conversation button. These call canonical `/v3/projects/{id}/sessions`, not generic workspace session creation. `getOrchestratorSession` reuses an existing conversation or creates one; it does not mean there can only be one.
    - Use `client.projects.createTask()` / `listTasks()` for custom task organization. Task-linked sessions must be continued through `reopenTask` with exact revision guards, not ordinary chat messages.
@@ -386,8 +399,11 @@ console.log(`Authenticated as user ${session.user_id}`);
 const { token, record } = await client.auth.createScopedToken({
   name: 'GitHub Actions Trigger',
   scopes: ['automations:trigger'],
-  expires_in_seconds: 86400, // 24 hours
 });
+// Every key works while it is used and stops after 90 days unused; nothing to
+// renew. Pass expires_in_seconds only for a fixed end date (at most 365 days).
+// client.auth.createKey({ kind: 'app' | 'bot' | 'ai', ... }), listKeys() and
+// revokeKey(id) cover all three kinds.
 console.log(`Created deploy token: ${token} (hint: ${record.token_hint})`);
 
 // List active tokens

package/dist/activity.d.ts

@@ -0,0 +1,33 @@
+import type { SwarmTransport } from './transport.js';
+export interface ActivityEvent {
+    seq: number;
+    at: number;
+    kind: string;
+    session_id: string;
+    job_id: string;
+    worker_id: string;
+    worker_name: string;
+    project_id: string;
+    state: string;
+    summary: string;
+    tool_name?: string;
+    file_path?: string;
+}
+export interface ActivityGap {
+    kind: 'gap';
+    from: number;
+    to: number;
+    cursor: string;
+}
+export interface ActivityStreamOptions {
+    cursor?: string;
+    project?: string;
+    worker?: string;
+    signal?: AbortSignal;
+}
+export declare class SwarmActivityNamespace {
+    private readonly transport;
+    constructor(transport: SwarmTransport);
+    /** Metadata only. Gap records must be surfaced to users; they are not activity events. */
+    stream(options?: ActivityStreamOptions): AsyncGenerator<ActivityEvent | ActivityGap>;
+}

package/dist/activity.js

@@ -0,0 +1,83 @@
+export class SwarmActivityNamespace {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /** Metadata only. Gap records must be surfaced to users; they are not activity events. */
+    async *stream(options = {}) {
+        let cursor = options.cursor ?? '0';
+        while (!options.signal?.aborted) {
+            const config = this.transport.getConfig();
+            if (config.socketPath)
+                throw new Error('Activity SSE requires an HTTP connection');
+            const query = new URLSearchParams({ cursor });
+            if (options.project)
+                query.set('project', options.project);
+            if (options.worker)
+                query.set('worker', options.worker);
+            const headers = { ...config.defaultHeaders, Accept: 'text/event-stream' };
+            if (config.token && !headers.Authorization && !headers.authorization)
+                headers.Authorization = `Bearer ${config.token}`;
+            try {
+                const response = await fetch(`${config.baseUrl.replace(/\/+$/, '')}/v3/activity/stream?${query}`, { headers, signal: options.signal, redirect: 'error' });
+                if (!response.ok || !response.body)
+                    throw new Error(`Activity stream failed: ${response.status}`);
+                const reader = response.body.getReader();
+                const decoder = new TextDecoder();
+                let pending = '';
+                try {
+                    for (;;) {
+                        const chunk = await reader.read();
+                        if (chunk.done)
+                            break;
+                        pending += decoder.decode(chunk.value, { stream: true }).replace(/\r\n/g, '\n');
+                        if (pending.length > 1024 * 1024)
+                            throw new Error('Activity frame too large');
+                        let end;
+                        while ((end = pending.indexOf('\n\n')) >= 0) {
+                            const frame = pending.slice(0, end);
+                            pending = pending.slice(end + 2);
+                            const kind = frame.split('\n').find(line => line.startsWith('event:'))?.slice(6).trim();
+                            const data = frame.split('\n').filter(line => line.startsWith('data:')).map(line => line.slice(5).trimStart()).join('\n');
+                            if (!data)
+                                continue;
+                            const value = JSON.parse(data);
+                            if (kind === 'cursor')
+                                cursor = value.cursor;
+                            else if (kind === 'gap') {
+                                cursor = value.cursor;
+                                yield { ...value, kind: 'gap' };
+                            }
+                            else if (kind === 'activity') {
+                                cursor = String(value.seq);
+                                yield value;
+                            }
+                        }
+                    }
+                }
+                finally {
+                    try {
+                        await reader.cancel();
+                    }
+                    catch { /* The disconnected transport is already closed. */ }
+                    reader.releaseLock();
+                }
+            }
+            catch (error) {
+                if (options.signal?.aborted)
+                    return;
+                // fetch and stream transport failures are TypeErrors; malformed frames
+                // and HTTP authorization failures are not retried.
+                if (!(error instanceof TypeError))
+                    throw error;
+            }
+            // Bound reconnect frequency; this is reconnection, not polling for activity.
+            if (!options.signal?.aborted)
+                await new Promise(resolve => {
+                    const finish = () => { clearTimeout(timer); options.signal?.removeEventListener('abort', finish); resolve(); };
+                    const timer = setTimeout(finish, 1000);
+                    options.signal?.addEventListener('abort', finish, { once: true });
+                });
+        }
+    }
+}