@swarm-agent/sdk 0.1.49 → 0.1.50

package/HEADLESS_UI.md

@@ -1,7 +1,5 @@
 # Build a real headless UI with the SDK
 
-For planned SDK completeness, safe tool control and non-production qualification, see the [five-step headless application plan](HEADLESS_PLAN.md). That roadmap is not a claim of implemented capabilities.
-
 ## Trust boundary
 
 Run the administrative Node SDK in your backend-for-frontend **inside the same container as swarmd**, using its configured private Unix socket. Do not mount/export that socket, put daemon credentials in browser code, or forward arbitrary browser-selected daemon paths. Authenticate your app's users, check Origin/CSRF, and allowlist app operations. Never log credential request bodies. The separate `--container-sdk-port` listener remains session-only: it cannot onboard providers, change settings, or create workspaces.
@@ -18,7 +16,7 @@ const providers = await swarm.settings.providers(); // readiness and supported a
 const credentials = await swarm.auth.credentials.list(); // redacted status only
 </copy>
 
-Your app must supply its configured socket path and authenticated local identity. This is not a recipe to import host credentials. Complete the daemon's identity/onboarding requirements using `onboarding.update({ username, swarm_name })` when needed.
+Your app must supply its configured socket path and authenticated local identity. This is not a recipe to import host credentials. Create the daemon identity with `onboarding.ensureBootstrapped({ username, swarm_name })` when needed (the name is kept as typed; repeating it is a no-op). It does not mark onboarding finished: once your setup (provider key, models, workspace) is done, call `onboarding.update({ desktop_onboarding_complete: true })`.
 
 For an API key collected through your app UI, pass the user-selected provider and its advertised credential type. The first-provider endpoint requires zero existing credentials/agents; use the ordinary save endpoint afterward. Errors are not silently retried on a different route.
 
@@ -86,13 +84,13 @@ await watch.done; // rejects on terminal transport/protocol/auth errors
 // On app disconnect: watch.dispose() or abort.abort().
 </copy>
 
-The watcher hydrates one session (including its session view), waits for `hello` (`v3.realtime`, version 1), and resumes from the **snapshot handoff cursor**, not the newer hello head. The server replays to the subscription before delivering live updates. It advertises `live_patch_v1` only when the server offers it. UTF-8 byte offsets and sequence ranges deduplicate live text; durable checkpoints and committed messages remain authoritative. Foreign-session frames never update the view.
+The watcher hydrates one session (including its session view), waits for `hello` (`v3.realtime`, version 1), and resumes from the **snapshot handoff cursor**, not the newer hello head. The server replays to the subscription before delivering live updates. It advertises `live_patch_v1` only when the server offers it. UTF-8 byte offsets place live text: duplicates and overlaps are trimmed, and output that starts beyond the durable prefix (normal when joining or reconnecting mid-turn, since durable checkpoints trail live text by up to 250ms) is held until a durable checkpoint fills the gap, never shown with a hole. Committed messages remain authoritative. Foreign-session frames never update the view.
 
-Durable events trigger coalesced `/v3/sync/hydrate` reads, not interval polling. Disconnects, cursor errors and slow consumers start fresh scoped hydration/replay with bounded exponential backoff (six retries, 250ms to 8s). Authentication/protocol errors terminate. No cursor is parsed, numerically compared, or persisted across watches/principals. `dispose` cancels HTTP, closes WebSocket, and ends `done`; a disposed-before-ready watcher rejects `ready`.
+Durable events delivered on the socket are merged into `state.snapshot.events_by_session` immediately (deduplicated by sequence, newest 1000 kept); other than streaming `*.delta` checkpoints they also trigger coalesced `/v3/sync/hydrate` reads, not interval polling. Disconnects, cursor errors and slow consumers start fresh scoped hydration/replay with bounded exponential backoff (six consecutive retries per outage, 250ms to 8s; a replayed connection restores the budget). While reconnecting, `state` keeps the last rendered conversation with `status: 'reconnecting'`. Authentication/protocol errors terminate. No cursor is parsed, numerically compared, or persisted across watches/principals. `dispose` cancels HTTP, closes WebSocket, and ends `done`; a disposed-before-ready watcher rejects `ready`.
 
 ### Bounded view and raw access
 
-The high-level view is a **200-message / 200-event tail**, not the complete transcript. Inspect `snapshot.pagination`, `omissions`, history manifests and session views before claiming complete history. A mid-stream reconnect whose retained event tail lacks the stream prefix may show no partial draft until a durable complete message arrives; it never guesses missing text. A live offset gap pauses that stream's speculative patches and relies on durable repair. Live overlays are bounded to 64 streams / 4 MiB per stream. Tool, plan, permission and other resources stay in the canonical raw snapshot; the SDK does not invent a second plan authority.
+The high-level view is a **200-message / 200-event tail**, not the complete transcript. Inspect `snapshot.pagination`, `omissions`, history manifests and session views before claiming complete history. A mid-stream reconnect whose retained event tail lacks the stream prefix may show no partial draft until a durable complete message arrives; it never guesses missing text. Live overlays are bounded to 64 streams / 4 MiB per stream. Tool, plan, permission and other resources stay in the canonical raw snapshot; the SDK does not invent a second plan authority.
 
 `realtime.bootstrap(request)`, `hydrate(request)` and `replay({...request, endpoint_cursor, limit})` expose typed canonical V3 envelopes for advanced consumers. Keep surface, selector and resources identical when using `/v3/sync/stream` cursors. `realtime.socket(path)` exposes transport only; raw consumers own reducer/replay correctness. The convenience watcher uses fresh durable repair on reconnect rather than retaining a possibly stale speculative cache.
 

package/README.md

@@ -2,26 +2,46 @@
 
 Official TypeScript SDK for [Swarm](https://github.com/swarm-agent/swarm), the local-first AI coding workspace.
 
-`@swarm-agent/sdk` provides a typed, zero-dependency client to interact programmatically with the Swarm daemon (`swarmd`) over HTTP and local Unix domain sockets.
+`@swarm-agent/sdk` provides a typed client to interact programmatically with the Swarm daemon (`swarmd`) over HTTP and its local owner socket.
 
 ## Features
 
-- **Zero Runtime Dependencies**: Works out-of-the-box in Node.js, Bun, Deno, and modern browser/edge environments.
-- **Zero-Conf Unix Sockets**: Native support for daemon Unix domain sockets (`/run/swarmd/swarmd.sock`) for automatic peer identity.
+- **Finds your local Swarm**: In Node, `new SwarmClient()` connects to the owner socket of a system install (`/var/lib/swarmd/local-transport/api.sock`) when the process may use it, otherwise to `http://127.0.0.1:7781`.
+- **Owner Socket**: The owner socket is trusted daemon-owner IPC: run as the user that runs Swarm and no token is needed.
 - **Granular Scoped Tokens**: Create, list, revoke, and purge scoped deploy tokens (`swk_...`) with fine-grained permissions (`automations:trigger`, `sessions:read`, `sessions:write`, `admin`).
 - **Worker / Automation V2 Triggers**: Trigger workers on-demand with dynamic caller context (e.g. GitHub Webhooks, CI/CD events, alert payloads).
 - **Session & Workspace Lifecycle**: Create durable V3 sessions, manage runs, send messages, poll for completion, and inspect workspaces.
 - **Typed Error Hierarchy**: `SwarmAuthError` (401), `SwarmForbiddenError` (403), `SwarmNotFoundError` (404), `SwarmConflictError` (409), `SwarmTimeoutError`.
 
-## Unpublished npm candidate
+## Install
 
-Node 22+ and ESM imports are the validated packaging target. The prerelease name
-is not a claim of registry ownership or publication. Install the local candidate
-from a clean consumer directory (no Swarm checkout or Desktop required):
+Requires Node 22 or newer (ESM). The package is public on npm:
 
 <copy>
-npm install "$SDK_TARBALL"
-node --input-type=module -e "import { SwarmClient } from '@swarm-agent/sdk'; console.log(typeof SwarmClient)"
+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`.
+
+## Connect to your Swarm
+
+`new SwarmClient()` with no options picks the first of:
+
+1. `socketPath` or `baseUrl` passed to the constructor;
+2. `SWARM_SOCKET_PATH` (a Unix socket);
+3. `SWARM_API_URL` (or `SWARM_DESKTOP_URL`);
+4. Node only: the owner socket `/var/lib/swarmd/local-transport/api.sock`, if it
+   exists, is a socket and this process can read and write it;
+5. `http://127.0.0.1:7781`, the daemon's default API address.
+
+The owner socket's directory is private to the user that runs Swarm, so other
+users fall through to HTTP, which needs a token (`token` or `SWARM_AUTH_TOKEN`).
+Browser code never touches the filesystem; use `@swarm-agent/sdk/browser` there.
+`resolveSwarmConnection()` returns the choice without connecting.
+
+<copy>
+node --input-type=module -e "import { SwarmClient } from '@swarm-agent/sdk'; const c = new SwarmClient(); console.log(c.config.socketPath ?? c.config.baseUrl)"
 </copy>
 
 For maintainers, the SDK builds independently with its own locked dev dependencies:
@@ -38,7 +58,7 @@ 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` candidate and explicitly
+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.
@@ -76,10 +96,9 @@ The SDK can automatically discover credentials from your environment or Codex OA
 ```typescript
 import { SwarmClient } from '@swarm-agent/sdk';
 
-const client = new SwarmClient({
-  baseUrl: process.env.SWARM_API_URL || 'http://127.0.0.1:5555',
-  socketPath: process.env.SWARM_SOCKET_PATH, // e.g. /var/lib/swarmd/local-transport/api.sock
-});
+// Owner socket when this process may use it, else http://127.0.0.1:7781
+// (see "Connect to your Swarm"; pass socketPath/baseUrl/token to choose).
+const client = new SwarmClient();
 
 // 1. Ensure headless identity is bootstrapped
 await client.onboarding.ensureBootstrapped({ username: 'developer', swarm_name: 'My Swarm' });
@@ -133,7 +152,9 @@ await client.settings.restoreDefaults();
 
 Use `describePermission(record)` to render tool details, conservative per-request `actions`,
 question IDs, options and custom-response fields. Treat all text/arguments as untrusted text,
-not HTML. `parseError` leaves malformed questions deny-only. These helpers do not grant authority:
+not HTML. `title` is always a plain-text heading: the request's own title, else the bash
+command, the first ask-user question, or the humanized tool name and action (for example
+`Manage projects: propose task (Add login)`). `parseError` leaves malformed questions deny-only. These helpers do not grant authority:
 the backend enforces policy, project scope and specialized plan/proposal acceptance.
 
 ```typescript
@@ -172,51 +193,68 @@ always requires actual user input.
 
 ### 4. Interactive Chat & Live Tool Stream
 
-Build responsive chat UIs that stream model text, reasoning, and live tool execution cards like Swarm Desktop:
+One `chat.stream()` watch per selected conversation serves every turn. It hydrates the
+session, resumes `/v3/realtime/stream` from the snapshot cursor, and reconnects on its own.
 
 ```typescript
-// 1. Create a chat session
-const session = await client.chat.createSession({
-  title: 'Repository Exploration',
-  workspace_path: '/path/to/project',
-});
+const session = await client.chat.createSession({ title: 'Repo tour', workspace_path: '/path/to/repo' });
 
-// 2. Stream live text, reasoning, and tool calls
+let answer = '';
 const stream = await client.chat.stream(session.id, {
-  onText: (delta, fullText) => process.stdout.write(delta),
-  onReasoning: (delta) => console.log('[Thinking]', delta),
-  onToolStarted: (tool) => console.log(`[Tool Started] ${tool.name}`),
-  onToolDelta: (tool, delta) => console.log(`[Tool Output] ${delta}`),
-  onToolCompleted: (tool) => console.log(`[Tool Done] ${tool.name} in ${tool.durationMs}ms`),
-  onPermissionRequested: async (perm, resolve) => {
-    // Your UI must wait for a real user gesture. Keep errors visible and retain the form.
-    renderPermissionForm(describePermission(perm), async (action, userInput) => {
-      try {
-        const result = await resolve(action, action === 'allow_once' && describePermission(perm).kind === 'ask-user'
-          ? answerPermission(perm, userInput) : {});
-        showConfirmedDecision(result.permission);
-      } catch (error) { showPermissionError(perm.id, error); }
-    });
+  onText: (delta) => { answer += delta; render(answer); },  // deltas join to exactly the reply
+  onReasoning: (_delta, full) => renderThinking(full),
+  onToolStarted: (tool) => showTool(tool.callId, tool.name, tool.arguments),
+  onToolDelta: (tool, chunk) => appendToolOutput(tool.callId, chunk),
+  onToolCompleted: (tool) => finishTool(tool.callId, tool.status), // completed | failed | cancelled
+  onPermissionRequested: (perm, resolve) => askUser(perm, resolve), // see section 3; never auto-answer
+  onState: (state) => setStatus(state.status),               // syncing | live | reconnecting
+  onComplete: (messages, run) => {                            // once per run, success or not
+    if (run.status !== 'completed') showFailure(run.status, run.blocked_reason, messages);
+    answer = '';
   },
-  onPermissionRemoved: id => removePermissionForm(id), // No longer pending; not necessarily approved.
-  onPermissionError: (error, perm) => showPermissionError(perm.id, error),
-  onState: (state) => renderConversation(state.messages, state.live, state.snapshot),
-  onComplete: () => console.log('Turn finished; stream remains open'),
-});
-
-await stream.ready; // Hydration and replay MUST finish before dispatch.
-await client.chat.sendMessage(session.id, 'Find all configuration files and summarize them.');
-// Keep this watch for subsequent messages. Dispose only on switch/unmount/shutdown.
-// stream.done means the watch ended, not that a single assistant turn finished.
-
-// 3. Or use chat.run while the watch above serves the explicit permission UI
-const response = await client.chat.run(session.id, {
-  message: 'What is the git status of this repository?',
-  timeoutMs: 120_000,
+  onError: (error) => showDisconnected(error),               // terminal: auth/protocol/retries exhausted
 });
-console.log(response.reply);
+await stream.ready;                                           // hydrated and replayed: safe to send
+await client.chat.sendMessage(session.id, 'Summarize the build setup.');
+// Send further turns on the same watch. Switching conversations: stream.dispose(), then
+// chat.stream(otherId). client.sessions.list() lists conversations.
 ```
 
+Guarantees, verified end to end against the API server (see "Streaming verification" below):
+
+- `onText` deltas concatenate to exactly the assistant text, including when the socket drops
+  mid-turn: nothing is repeated and nothing is skipped; the last call carries any committed
+  text beyond what streamed. Use `fullText` (2nd argument) to replace instead of append.
+- A dropped socket reconnects (exponential backoff, 6 consecutive attempts per outage) and
+  resumes from durable state; `state.status` is `reconnecting` meanwhile and keeps the last view.
+- `onComplete(messages, run)` fires once per finished run, whatever its outcome.
+  A failed provider turn has `run.status === 'failed'` and a system message in `messages`.
+- Durable events (newest 1000) are in `state.snapshot.events_by_session[id]` once, in sequence order.
+- Live tool objects carry `callId`, equal to `payload.call_id` on the durable `session.tool.*`
+  events. When you merge history cards with live cards, match on `callId`: `tool.id` is kept
+  for compatibility and can be the step-scoped instance id (`step-2:call_…`).
+- A conversation whose history no longer fits the hydrate window (for example after a very
+  large tool result) still opens: the watch retries with `history.manifest_policy: 'manifest'`,
+  keeps the newest window, and sets `state.historyOmitted = true` with
+  `state.historyOmissions` (resource and `next_cursor`) so you can show "older history not
+  loaded" instead of presenting the window as complete.
+
+`state.messages` (a 200-message tail) and `state.live` are the rendering authority;
+callbacks are conveniences. Clearing context: `client.sessions.clearContext(id, { expectedLastEventSeq })`
+starts a fresh model context in the same conversation, but the daemon allows it only for an
+idle project conversation (`SwarmConflictError` otherwise, nothing changes); for a standalone
+chat, create a new session.
+
+**Streaming verification.** `swarmd/internal/api` `TestSDKChatStreamE2E` (opt-in:
+`npm run build`, then `SWARM_SDK_E2E=1 go test ./internal/api -run TestSDKChatStreamE2E`)
+drives the built package (`e2e/chat-stream.e2e.mjs`) against the real API server, store,
+executor and realtime socket with a scripted provider: incremental text, a socket drop mid-turn
+while durable checkpoints lag, completion, failure, session switching and context clear. It does
+not exercise a real model, tool calls or permission prompts, or token authentication.
+
+`chat.run()` (polling, returns the final reply) remains available for scripts; keep a
+`chat.stream()` watch open when tool permissions need an explicit answer.
+
 ---
 
 ### 5. Native WebSocket Streaming Bridge & Browser Client
@@ -257,9 +295,9 @@ chat.on('disconnected', disableComposer);
 // 1. Hook into live tool execution and token streams
 chat.on('text', (delta, fullText) => renderLiveMarkdown(fullText));
 chat.on('reasoning', (delta, fullText) => renderModelThinking(fullText));
-chat.on('tool_start', (tool) => renderToolStartedCard(tool.id, tool.name, tool.arguments));
-chat.on('tool_delta', (tool, delta) => appendToolOutput(tool.id, delta));
-chat.on('tool_done', (tool) => markToolCompleted(tool.id, tool.durationMs));
+chat.on('tool_start', (tool) => renderToolStartedCard(tool.callId, tool.name, tool.arguments));
+chat.on('tool_delta', (tool, delta) => appendToolOutput(tool.callId, delta));
+chat.on('tool_done', (tool) => markToolCompleted(tool.callId, tool.durationMs));
 // Replace pending cards on hydration/live updates/reconnect, keyed by permission.id.
 // Preserve unsent input for unchanged requests; do not submit during render.
 chat.on('permissions', pending => renderPendingForms(pending.map(describePermission)));
@@ -285,7 +323,9 @@ const requestId = chat.sendMessage('Inspect the git repository and list modified
 // `accepted` acknowledges durable dispatch. Never blindly resend an uncertain message.
 // Retain requestId if your UI offers an explicit retry, and pass it as argument 4.
 // Switching: await chat.subscribe(otherSession.id). Reconnect rehydrates selected history.
-// Unmount: chat.dispose(). Disconnected sends throw instead of silently disappearing.
+// Unmount: chat.dispose(). Sends that cannot go out throw SwarmChatNotReadyError (nothing was
+// sent): its message is fit to show people, and `code` is chat_reconnecting (retry shortly),
+// chat_disconnected (call connect()) or chat_not_subscribed (subscribe first).
 ```
 
 Backend conversation routes should use the same project identity for listing and creation:
@@ -298,6 +338,17 @@ const created = await client.projects.createConversation(project.id, {
 // Return created.id to the browser; await chat.subscribe(created.id) before sending.
 ```
 
+Conversation titles come from Swarm: a conversation created without a `title` is named from
+its first message (refined later when a title model is available), and `listConversations`
+returns it. Rename with `client.sessions.rename(id, title)` (or
+`client.projects.renameConversation(id, title)`); a renamed title is kept.
+
+Assistant text can contain `<copy label="…">…</copy>` snippet tags, which Swarm's own apps
+render as copy buttons. `chat.run`, `chat.listMessages` and `chat.stream` (and the browser
+bridge built on it) turn them into Markdown code blocks by default; pass `rawCopyTags: true`
+to keep them. For text read elsewhere (`sessions.get`, `realtime.watchSession`), use the
+exported `copyTagsToMarkdown(text)`.
+
 Use `state` as the conversation rendering authority, including initial history, failed/empty
 turns and durable reconnect recovery. `text`/tool callbacks are convenience notifications.
 History is a bounded 200-message tail; use canonical sync hydration for additional history.
@@ -442,8 +493,22 @@ await client.projects.refineTask(project.id, task.id, {
 
 // Stream or replay outbox events starting after an opaque cursor
 const streamResult = await client.projects.replayEvents('opaque_cursor_token');
+
+// Integrate a finished task's commits into its captured target branch
+const integration = await client.projects.integrateTask(project.id, task.id);
 ```
 
+`integrateTask` reads the task first (`getTask`, which observes Git) and sends the exact
+selection the daemon checks: `session_id` (the task's current session) and the captured
+`source_branch`/`target_branch` (from `task.delivery_assessment`, else the task's
+`worktree_branch`/`base_branch`, else its active attempt), plus `revision`, `attempt_id` and the
+observed `source_head`/`target_head`. Override any field with
+`integrateTask(projectId, taskId, { selection: { target_branch: 'main' } })`; supplying
+`session_id`, `source_branch` and `target_branch` skips the read. A task with no captured
+worktree lane throws `SwarmValidationError` without calling the daemon; a stale selection, dirty
+checkout or non-actionable delivery state comes back as `SwarmConflictError` and nothing is
+integrated.
+
 ### 7. Programmable Push Alert Webhooks
 
 Register push alert webhook destinations to receive HMAC-signed real-time notifications on worker lifecycle events (`started`, `succeeded`, `failed`, `retry_exhausted`):

package/dist/agents.d.ts

@@ -0,0 +1,114 @@
+import type { SwarmTransport } from './transport.js';
+/** A typed tool the application answers. Swarm validates and waits; it never executes it. */
+export interface ClientToolDefinition {
+    name: string;
+    description: string;
+    /** JSON Schema for the arguments; must be `type: "object"` with only local `$ref`s. */
+    input_schema: Record<string, unknown>;
+    /** `write` marks a tool with external effects (confirm with a person before running it). */
+    effect?: 'read' | 'write';
+    /** How long a call waits for an answer before the model gets "client tool timed out" (max 300000). */
+    timeout_ms?: number;
+}
+/**
+ * An agent whose only capabilities are the client tools listed. It has no
+ * built-in tools: no shell, files, web or delegation. Swarm enforces this
+ * when each call executes, not only in what the model is shown.
+ */
+export interface SealedAgentDefinition {
+    name: string;
+    prompt: string;
+    description?: string;
+    tools: string[];
+    provider?: string;
+    model?: string;
+    thinking?: string;
+    /** Bounds one message's cost. Unset fields use the sealed defaults (4 model calls, 1024 output tokens, last 40 messages, 60 s). */
+    limits?: {
+        max_steps?: number;
+        max_output_tokens?: number;
+        max_history_messages?: number;
+        run_timeout_ms?: number;
+    };
+}
+/** The account's spend today and its daily cap, as the daemon enforces it. */
+export interface SpendToday {
+    today_cost_usd: number;
+    daily_cost_limit_usd: number;
+    enabled: boolean;
+    limit_exceeded: boolean;
+}
+/** A pending client tool call your application must answer. */
+export interface ClientToolCall {
+    /** Pass to `answer`/`fail`. */
+    id: string;
+    sessionId: string;
+    runId: string;
+    tool: string;
+    /** Already validated by Swarm against the tool's input_schema. */
+    arguments: Record<string, unknown>;
+    createdAt: number;
+}
+/** Throw from a handler to send this message to the model; other errors send "tool failed". */
+export declare class ClientToolError extends Error {
+    constructor(message: string);
+}
+export type ClientToolHandler = (args: Record<string, unknown>, call: ClientToolCall) => Promise<unknown> | unknown;
+/** One visitor turn: the agent's reply and every message the turn added (including tool results). */
+export interface ConverseResult {
+    reply: string;
+    messages: Array<Record<string, any>>;
+}
+/**
+ * Sealed agents and client tools (`/v2/agents`, `/v2/custom-tools`). Defining
+ * them needs the owner or an `admin` token: keep this in a trusted backend.
+ */
+export declare class SwarmAgentsNamespace {
+    private readonly transport;
+    constructor(transport: SwarmTransport);
+    defineClientTool(definition: ClientToolDefinition): Promise<Record<string, unknown>>;
+    defineSealedAgent(definition: SealedAgentDefinition): Promise<Record<string, unknown>>;
+    /**
+     * Mints the token a gateway holds to serve one sealed agent. It can only
+     * create and use that agent's sessions and answer its client tool calls;
+     * it stops working if the agent is given any built-in tool. Owner only.
+     */
+    createGatewayToken(agentName: string, options?: {
+        name?: string;
+        expiresInSeconds?: number;
+        messagesPerMinute?: number;
+        sessionsPerHour?: number;
+    }): Promise<{
+        token: string;
+        record: Record<string, unknown>;
+    }>;
+    /** Today's spend against the daily cap. A gateway token may read it. */
+    spendToday(): Promise<SpendToday>;
+    removeAgent(name: string): Promise<void>;
+    removeClientTool(name: string): Promise<void>;
+    /** Client tool calls waiting in a session, limited to the tool names you answer. */
+    pendingCalls(sessionId: string, tools: Iterable<string>): Promise<ClientToolCall[]>;
+    /** Returns `result` (any JSON value) to the model as the tool's output. */
+    answer(sessionId: string, callId: string, result: unknown): Promise<void>;
+    /** Returns `reason` to the model as the tool's error. */
+    fail(sessionId: string, callId: string, reason: string): Promise<void>;
+    /**
+     * Answers one session's client tool calls with `handlers` until `signal`
+     * aborts. Each call is answered at most once; a handler error fails the
+     * call with "tool failed" unless it is a ClientToolError.
+     */
+    serve(sessionId: string, handlers: Record<string, ClientToolHandler>, options?: {
+        signal?: AbortSignal;
+        intervalMs?: number;
+    }): Promise<void>;
+    /**
+     * Sends one user message to a sealed agent's session, answers its client
+     * tool calls with `handlers` while it runs, and returns once the run has
+     * finished. This is the whole loop a gateway needs per visitor message.
+     */
+    converse(sessionId: string, message: string, handlers: Record<string, ClientToolHandler>, options?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<ConverseResult>;
+    private resolve;
+}

package/dist/agents.js

@@ -0,0 +1,183 @@
+import { SwarmSessionsNamespace } from './sessions.js';
+/** Throw from a handler to send this message to the model; other errors send "tool failed". */
+export class ClientToolError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ClientToolError';
+    }
+}
+const NAME = /^[a-z][a-z0-9_]{0,63}$/;
+function toolName(name) {
+    if (typeof name !== 'string' || !NAME.test(name))
+        throw new Error('tool and agent names are lowercase letters, digits and underscores');
+    return name;
+}
+/**
+ * Sealed agents and client tools (`/v2/agents`, `/v2/custom-tools`). Defining
+ * them needs the owner or an `admin` token: keep this in a trusted backend.
+ */
+export class SwarmAgentsNamespace {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async defineClientTool(definition) {
+        const name = toolName(definition.name);
+        const res = await this.transport.request(`/v2/custom-tools/${name}`, {
+            method: 'PUT',
+            body: {
+                kind: 'client',
+                description: definition.description,
+                input_schema: definition.input_schema,
+                effect: definition.effect ?? 'read',
+                ...(definition.timeout_ms !== undefined ? { timeout_ms: definition.timeout_ms } : {}),
+            },
+        });
+        return res.data.custom_tool;
+    }
+    async defineSealedAgent(definition) {
+        const name = toolName(definition.name);
+        if (!Array.isArray(definition.tools))
+            throw new Error('tools must be an array of client tool names');
+        const tools = {};
+        for (const tool of definition.tools)
+            tools[toolName(tool)] = { enabled: true };
+        const res = await this.transport.request(`/v2/agents/${name}`, {
+            method: 'PUT',
+            body: {
+                mode: 'subagent',
+                description: definition.description ?? '',
+                prompt: definition.prompt,
+                ...(definition.provider ? { provider: definition.provider } : {}),
+                ...(definition.model ? { model: definition.model } : {}),
+                ...(definition.thinking ? { thinking: definition.thinking } : {}),
+                ...(definition.limits ? { limits: definition.limits } : {}),
+                tool_contract: { preset: 'custom', tools },
+            },
+        });
+        return res.data.profile;
+    }
+    /**
+     * Mints the token a gateway holds to serve one sealed agent. It can only
+     * create and use that agent's sessions and answer its client tool calls;
+     * it stops working if the agent is given any built-in tool. Owner only.
+     */
+    async createGatewayToken(agentName, options = {}) {
+        const agent = toolName(agentName);
+        const res = await this.transport.request('/v3/auth/tokens', {
+            method: 'POST',
+            body: {
+                name: options.name ?? `${agent} gateway`, agent_name: agent,
+                ...(options.expiresInSeconds ? { expires_in_seconds: options.expiresInSeconds } : {}),
+                ...(options.messagesPerMinute ? { messages_per_minute: options.messagesPerMinute } : {}),
+                ...(options.sessionsPerHour ? { sessions_per_hour: options.sessionsPerHour } : {}),
+            },
+        });
+        return { token: res.data.token, record: res.data.record };
+    }
+    /** Today's spend against the daily cap. A gateway token may read it. */
+    async spendToday() {
+        const res = await this.transport.request('/v3/sessions:usage-limits');
+        return res.data.limits;
+    }
+    async removeAgent(name) {
+        await this.transport.request(`/v2/agents/${toolName(name)}`, { method: 'DELETE' });
+    }
+    async removeClientTool(name) {
+        await this.transport.request(`/v2/custom-tools/${toolName(name)}`, { method: 'DELETE' });
+    }
+    /** Client tool calls waiting in a session, limited to the tool names you answer. */
+    async pendingCalls(sessionId, tools) {
+        const names = new Set(tools);
+        const res = await this.transport.request(`/v3/sessions/${encodeURIComponent(sessionId)}/permissions?status=pending&limit=100`);
+        const calls = [];
+        for (const record of res.data.permissions ?? []) {
+            if (!names.has(record.tool_name) || record.session_id !== sessionId)
+                continue;
+            let args;
+            try {
+                args = JSON.parse(record.tool_call_arguments || record.tool_arguments || '{}');
+            }
+            catch {
+                args = null;
+            }
+            if (!args || typeof args !== 'object' || Array.isArray(args))
+                continue;
+            calls.push({ id: record.id, sessionId, runId: record.run_id, tool: record.tool_name, arguments: args, createdAt: record.created_at });
+        }
+        return calls;
+    }
+    /** Returns `result` (any JSON value) to the model as the tool's output. */
+    async answer(sessionId, callId, result) {
+        await this.resolve(sessionId, callId, { action: 'allow_once', reason: '', approved_arguments: { result: JSON.parse(JSON.stringify(result ?? null)) } });
+    }
+    /** Returns `reason` to the model as the tool's error. */
+    async fail(sessionId, callId, reason) {
+        await this.resolve(sessionId, callId, { action: 'deny', reason: String(reason || 'tool failed') });
+    }
+    /**
+     * Answers one session's client tool calls with `handlers` until `signal`
+     * aborts. Each call is answered at most once; a handler error fails the
+     * call with "tool failed" unless it is a ClientToolError.
+     */
+    async serve(sessionId, handlers, options = {}) {
+        const handled = new Set();
+        const interval = Math.max(50, options.intervalMs ?? 250);
+        while (!options.signal?.aborted) {
+            for (const call of await this.pendingCalls(sessionId, Object.keys(handlers))) {
+                if (handled.has(call.id))
+                    continue;
+                handled.add(call.id);
+                try {
+                    await this.answer(sessionId, call.id, await handlers[call.tool](call.arguments, call));
+                }
+                catch (error) {
+                    await this.fail(sessionId, call.id, error instanceof ClientToolError ? error.message : 'tool failed').catch(() => undefined);
+                }
+            }
+            await new Promise((resolve) => {
+                const timer = setTimeout(resolve, interval);
+                options.signal?.addEventListener('abort', () => { clearTimeout(timer); resolve(); }, { once: true });
+            });
+        }
+    }
+    /**
+     * Sends one user message to a sealed agent's session, answers its client
+     * tool calls with `handlers` while it runs, and returns once the run has
+     * finished. This is the whole loop a gateway needs per visitor message.
+     */
+    async converse(sessionId, message, handlers, options = {}) {
+        const sessions = new SwarmSessionsNamespace(this.transport);
+        const before = new Set(((await sessions.get(sessionId)).messages ?? []).map((m) => m.id));
+        const controller = new AbortController();
+        const serving = this.serve(sessionId, handlers, { signal: controller.signal, intervalMs: options.pollIntervalMs ?? 200 });
+        const deadline = Date.now() + (options.timeoutMs ?? 120_000);
+        try {
+            await sessions.sendMessage(sessionId, { content: message });
+            for (;;) {
+                const detail = await sessions.get(sessionId);
+                const raw = (detail.raw ?? {});
+                const added = (detail.messages ?? []).filter((m) => !before.has(m.id));
+                const pending = Array.isArray(raw.pending_permissions) ? raw.pending_permissions.length : 0;
+                const failure = added.find((m) => m.role === 'system' && m.metadata?.message_kind === 'run_failure');
+                if (!raw.active_run_intent && failure)
+                    throw new Error(`The agent's run failed: ${String(failure.content ?? '').slice(0, 300)}`);
+                if (!raw.active_run_intent && pending === 0 && added.some((m) => m.role === 'assistant')) {
+                    return { reply: added.filter((m) => m.role === 'assistant').map((m) => String(m.content ?? '')).join('\n\n'), messages: added };
+                }
+                if (Date.now() > deadline)
+                    throw new Error('The agent did not finish in time; the run may still complete');
+                await new Promise((resolve) => setTimeout(resolve, options.pollIntervalMs ?? 400));
+            }
+        }
+        finally {
+            controller.abort();
+            await serving.catch(() => undefined);
+        }
+    }
+    async resolve(sessionId, callId, body) {
+        if (typeof callId !== 'string' || !callId)
+            throw new Error('callId is required');
+        await this.transport.request(`/v3/sessions/${encodeURIComponent(sessionId)}/permissions/${encodeURIComponent(callId)}/resolve`, { method: 'POST', body });
+    }
+}

package/dist/auth.d.ts

@@ -22,6 +22,20 @@ export declare class SwarmAuthNamespace {
      * Store the token securely—it cannot be retrieved again in plaintext!
      */
     createScopedToken(params: CreateScopedTokenParams): Promise<CreateScopedTokenResult>;
+    /**
+     * 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`
+     * 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
+     * defaults to 30 days (at most 365). Owner only.
+     */
+    createAIKey(params: {
+        name: string;
+        access: 'read' | 'write' | 'full';
+        expires_in_seconds?: number;
+    }): Promise<CreateScopedTokenResult>;
     /**
      * Lists all scoped deploy tokens for the active account.
      * Secret hashes are masked; hints (e.g. 'swk_...abcd') are displayed.

package/dist/auth.js

@@ -54,6 +54,22 @@ export class SwarmAuthNamespace {
         });
         return res.data;
     }
+    /**
+     * 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`
+     * 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
+     * defaults to 30 days (at most 365). Owner only.
+     */
+    async createAIKey(params) {
+        const res = await this.transport.request('/v3/auth/tokens', {
+            method: 'POST',
+            body: { name: params.name, ai_access: params.access, expires_in_seconds: params.expires_in_seconds },
+        });
+        return res.data;
+    }
     /**
      * Lists all scoped deploy tokens for the active account.
      * Secret hashes are masked; hints (e.g. 'swk_...abcd') are displayed.