@swarm-agent/sdk 0.1.49 → 0.1.50

package/dist/box.d.ts

@@ -0,0 +1,68 @@
+import type { SwarmTransport } from './transport.js';
+/** `ok`, `attention` (something waits on a person or failed today) or `degraded` (agents unconfined, or spending over the limit). */
+export type BoxStatus = 'ok' | 'attention' | 'degraded';
+/** One machine's state for a monitor: ids, names and counts only. */
+export interface BoxSummary {
+    generated_at: number;
+    status: BoxStatus;
+    /** Why the status is not `ok`. */
+    reasons: string[];
+    machine: {
+        name?: string;
+        uptime_ms: number;
+    };
+    sandbox: {
+        mode: string;
+        active: boolean;
+        runtime?: string;
+        reason?: string;
+    };
+    secrets_gateway: boolean;
+    permissions: {
+        bypass: boolean;
+        bypass_blocked_reason?: string;
+    };
+    attention: {
+        blocked_sessions: number;
+        oldest_pending_at?: number;
+        sessions: {
+            session_id: string;
+            pending: number;
+            oldest_pending_at: number;
+        }[];
+    };
+    workers: {
+        total: number;
+        truncated?: boolean;
+        active_runs: number;
+        today_runs: number;
+        today_failed: number;
+        /** UTC day the counts cover, YYYY-MM-DD. */
+        day?: string;
+        failing: {
+            worker_id: string;
+            name: string;
+            today_runs: number;
+            today_failed: number;
+            active_runs: number;
+        }[];
+    };
+    usage: {
+        today_cost_usd?: number;
+        today_tokens?: number;
+        daily_cost_limit_usd?: number;
+        limit_enabled?: boolean;
+        limit_exceeded?: boolean;
+    };
+    signals: {
+        latest_seq?: number;
+        oldest_seq?: number;
+    };
+}
+/** Machine-level state. Needs a key with `signals:read`. */
+export declare class SwarmBoxNamespace {
+    private readonly transport;
+    constructor(transport: SwarmTransport);
+    /** Is this machine all right, and does anything need a person? One cheap call. */
+    summary(): Promise<BoxSummary>;
+}

package/dist/box.js

@@ -0,0 +1,13 @@
+/** Machine-level state. Needs a key with `signals:read`. */
+export class SwarmBoxNamespace {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /** Is this machine all right, and does anything need a person? One cheap call. */
+    async summary() {
+        const res = await this.transport.request('/v3/box/summary', { method: 'GET' });
+        const { ok: _ok, ...summary } = res.data;
+        return summary;
+    }
+}

package/dist/browser.d.ts

@@ -2,7 +2,10 @@ import type { ToolStreamItem } from './chat.js';
 import type { PendingPermissionRecord, ResolvePermissionResult } from './permissions.js';
 import type { PermissionAction, ResolvePermissionOptions } from './permission-ui.js';
 export * from './permission-ui.js';
-import type { SessionWatchState, V3Message } from './realtime.js';
+export { copyTagsToMarkdown, hasCopyTags } from './copy-tags.js';
+export { SwarmChatNotReadyError } from './errors.js';
+export type { SwarmChatNotReadyCode } from './errors.js';
+import type { SessionWatchState, V3Message, V3RunState } from './realtime.js';
 export interface SwarmBrowserChatOptions {
     /** WebSocket URL, e.g. ws://localhost:3456/ws. Defaults to ws(s)://${location.host}/ws */
     url?: string;
@@ -36,7 +39,8 @@ type EventMap = {
     permission_removed: (permissionId: string) => void;
     permission_error: (permissionId: string, error: Error) => void;
     permissions: (pending: PendingPermissionRecord[]) => void;
-    done: (messages: V3Message[]) => void;
+    /** Once per finished run; `run.status` distinguishes completed from failed or cancelled. */
+    done: (messages: V3Message[], run?: V3RunState) => void;
     error: (error: string) => void;
 };
 /**

package/dist/browser.js

@@ -1,5 +1,8 @@
 import { confirmPermissionResolution, permissionId as validatePermissionId, permissionResolutionBody, PermissionResolutionError } from './permission-ui.js';
 export * from './permission-ui.js';
+export { copyTagsToMarkdown, hasCopyTags } from './copy-tags.js';
+import { SwarmChatNotReadyError } from './errors.js';
+export { SwarmChatNotReadyError } from './errors.js';
 /**
  * Universal browser-side WebSocket client for Swarm.
  * Hooks directly into the Swarm WebSocket Bridge with typed callbacks for live
@@ -241,7 +244,7 @@ export class SwarmBrowserChat {
                 break;
             }
             case 'done':
-                this.emit('done', msg.messages || []);
+                this.emit('done', msg.messages || [], msg.run);
                 break;
             case 'error':
                 this.emit('error', msg.error || 'Unknown error');
@@ -312,8 +315,13 @@ export class SwarmBrowserChat {
         if (!targetSession) {
             throw new Error('No active session. Call subscribe(sessionId) or provide sessionId');
         }
-        if (!this.isSubscribed || targetSession !== this.currentSessionId)
-            throw new Error('Await subscribe(sessionId) before sending');
+        if (targetSession !== this.currentSessionId)
+            throw new SwarmChatNotReadyError('chat_not_subscribed');
+        if (!this.isSubscribed) {
+            // Connected or about to reconnect: the subscription is restored automatically.
+            const recovering = this.isConnected || !!this.connectPromise || !!this.reconnectTimer;
+            throw new SwarmChatNotReadyError(recovering && !this.isDisposed ? 'chat_reconnecting' : 'chat_disconnected');
+        }
         const id = requestId ?? globalThis.crypto.randomUUID();
         this.send({
             type: 'chat_message',

package/dist/chat.d.ts

@@ -1,6 +1,6 @@
 import type { PendingPermissionRecord } from './permissions.js';
 import type { PermissionResolver } from './permissions.js';
-import type { SessionWatch, SessionWatchState, V3Message } from './realtime.js';
+import type { SessionWatch, SessionWatchState, V3Message, V3RunState } from './realtime.js';
 import type { SwarmTransport } from './transport.js';
 import type { SessionDetail, SessionRecord } from './types.js';
 import { SwarmWebSocketBridge, type SwarmWebSocketBridgeOptions } from './websocket.js';
@@ -23,7 +23,13 @@ export interface CreateChatSessionOptions {
     mode?: 'auto' | 'plan';
 }
 export interface ToolStreamItem {
+    /** Live stream id (kept for compatibility; may be the `step-<n>:<call_id>` instance id). */
     id: string;
+    /**
+     * Durable tool-call id: equals `payload.call_id` on the session's `session.tool.*` history
+     * events. Match live tool cards to history cards on this field, not on `id`.
+     */
+    callId: string;
     name: string;
     identity?: string;
     display?: string;
@@ -49,6 +55,11 @@ export interface ChatRunOptions {
     onToolEvent?: (event: ToolStreamItem) => void;
     /** Optional AbortSignal to cancel waiting */
     signal?: AbortSignal;
+    /**
+     * Keep Swarm's `<copy label="…">…</copy>` snippet tags in `reply` and assistant
+     * `messages`. By default they become Markdown code blocks (see copyTagsToMarkdown).
+     */
+    rawCopyTags?: boolean;
 }
 export interface ChatRunResult {
     /** The final text response from the assistant */
@@ -70,9 +81,21 @@ export interface ChatStreamOptions {
     socketFactory?: import('./realtime.js').RealtimeSocketFactory;
     /** Authoritative conversation snapshot on hydrate, live change and reconnect. */
     onState?: (state: SessionWatchState) => void;
-    /** Invoked with incremental and cumulative assistant response text */
+    /**
+     * Incremental and cumulative assistant text per run/stream. Concatenating `delta` values
+     * yields exactly `fullText`, including across reconnects (never repeated, never skipped);
+     * a turn's final call carries any committed text beyond what streamed.
+     */
     onText?: (delta: string, fullText: string) => void;
-    /** Invoked with incremental and cumulative reasoning/thinking text */
+    /**
+     * Keep Swarm's `<copy label="…">…</copy>` snippet tags in `onText` and `onComplete`.
+     * By default they become Markdown code blocks while streaming (a half-written tag is
+     * held back until it is complete). Only if a snippet's own payload contains a run of
+     * four or more backticks is it re-fenced; that call's `delta` is then empty and
+     * `fullText` stays exact.
+     */
+    rawCopyTags?: boolean;
+    /** Incremental and cumulative reasoning text from durable reasoning checkpoints. */
     onReasoning?: (delta: string, fullText: string) => void;
     /** Invoked when a tool call starts running */
     onToolStarted?: (tool: ToolStreamItem) => void;
@@ -86,8 +109,12 @@ export interface ChatStreamOptions {
     onPermissionRemoved?: (permissionId: string) => void;
     /** Recoverable UI/resolution failure; the watch stays open. Resolver also rejects. */
     onPermissionError?: (error: Error, permission: PendingPermissionRecord) => void;
-    /** Invoked when the agent turn completes */
-    onComplete?: (messages: V3Message[]) => void;
+    /**
+     * Once per finished run, including failed, cancelled and empty turns. `run.status`
+     * says which (`completed`, `failed`, ...); a failure's reason is in `run.blocked_reason`
+     * and its system message in `messages`. The watch stays open for the next turn.
+     */
+    onComplete?: (messages: V3Message[], run: V3RunState) => void;
     /** Invoked if an unrecoverable streaming error occurs */
     onError?: (err: Error) => void;
 }
@@ -116,11 +143,13 @@ export declare class SwarmChatNamespace {
     /**
      * Appends a message to a chat conversation.
      */
-    sendMessage(sessionId: string, content: string, role?: 'user' | 'assistant' | 'system', clientRequestId?: string): Promise<any>;
+    sendMessage(sessionId: string, content: string, role?: 'user', clientRequestId?: string): Promise<any>;
     /**
      * Lists messages from a session conversation.
      */
-    listMessages(sessionId: string): Promise<V3Message[]>;
+    listMessages(sessionId: string, options?: {
+        rawCopyTags?: boolean;
+    }): Promise<V3Message[]>;
     /**
      * High-level chat execution: sends a message, monitors execution, handles or surfaces
      * pending permissions, and returns the final assistant reply.
@@ -132,3 +161,8 @@ export declare class SwarmChatNamespace {
      */
     stream(sessionId: string, options?: ChatStreamOptions): Promise<SessionWatch>;
 }
+/**
+ * The durable tool-call id (`payload.call_id` on `session.tool.*` events). When an event
+ * carries only `tool_instance_id` (`step-<n>:<call_id>`), the step prefix is removed.
+ */
+export declare function toolCallIdFromPayload(payload: Record<string, unknown> | undefined): string;

package/dist/chat.js

@@ -2,6 +2,7 @@ import { SwarmPermissionsNamespace, isAskUserPermission, permissionId } from './
 import { SwarmRealtimeNamespace } from './realtime.js';
 import { SwarmSessionsNamespace } from './sessions.js';
 import { SwarmTimeoutError } from './errors.js';
+import { copyTagsToMarkdown } from './copy-tags.js';
 import { SwarmWebSocketBridge } from './websocket.js';
 /**
  * Dedicated high-level Chat namespace.
@@ -35,7 +36,7 @@ export class SwarmChatNamespace {
         if (options.project_id)
             throw new Error('Use projects.createConversation(projectId) for project orchestrator conversations');
         return this.sessions.create({
-            title: options.title ?? 'Chat Session',
+            title: options.title,
             agent_name: options.agent_name ?? 'swarm',
             workspace_path: options.workspace_path,
             workspace_id: options.workspace_id,
@@ -52,9 +53,10 @@ export class SwarmChatNamespace {
     /**
      * Lists messages from a session conversation.
      */
-    async listMessages(sessionId) {
+    async listMessages(sessionId, options = {}) {
         const detail = await this.sessions.get(sessionId);
-        return detail.messages || [];
+        const messages = detail.messages || [];
+        return options.rawCopyTags ? messages : messages.map(cleanAssistantMessage);
     }
     /**
      * High-level chat execution: sends a message, monitors execution, handles or surfaces
@@ -99,10 +101,10 @@ export class SwarmChatNamespace {
                     reply = sysMsg ? sysMsg.content : 'No response generated from model.';
                 }
                 return {
-                    reply,
+                    reply: options.rawCopyTags ? reply : copyTagsToMarkdown(reply),
                     sessionId: id,
                     runId: activeRun?.run_id || detail.last_run_id,
-                    messages: msgs,
+                    messages: options.rawCopyTags ? msgs : msgs.map(cleanAssistantMessage),
                     pendingPermissions: pending,
                     session: detail,
                 };
@@ -123,7 +125,10 @@ export class SwarmChatNamespace {
         const id = permissionId(sessionId, 'sessionId');
         const activeTools = new Map();
         const seenEventIds = new Set();
-        const previousStreams = new Map();
+        // Text already reported through onText per run/stream: a high-water mark, never shrunk
+        // by a reconnect, so deltas are neither repeated nor lost across reconnects.
+        const reportedText = new Map();
+        const reasoning = new Map();
         const completedRuns = new Set();
         const pendingSeen = new Map();
         const resolving = new Set();
@@ -131,6 +136,97 @@ export class SwarmChatNamespace {
         let permissionsLive = false;
         let initialized = false;
         let observedRun;
+        // Only extensions are reported: a shorter text (reconnect before durable catch-up) or a
+        // committed message that differs from the streamed prefix is never re-sent as a delta.
+        // Copy tags are converted on the cumulative text (in streaming mode, which only ever
+        // appends), and the delta is taken from the converted text.
+        const shownText = new Map();
+        const reportText = (key, runId, streamId, text) => {
+            const previous = reportedText.get(key)?.text ?? '';
+            if (text.length <= previous.length || !text.startsWith(previous))
+                return;
+            reportedText.set(key, { runId, streamId, text });
+            observedRun = runId;
+            if (!options.onText)
+                return;
+            if (options.rawCopyTags) {
+                options.onText(text.slice(previous.length), text);
+                return;
+            }
+            const shown = copyTagsToMarkdown(text, { streaming: true });
+            const before = shownText.get(key) ?? '';
+            if (shown === before)
+                return;
+            shownText.set(key, shown);
+            options.onText(shown.startsWith(before) ? shown.slice(before.length) : '', shown);
+        };
+        const forgetText = (key) => {
+            reportedText.delete(key);
+            shownText.delete(key);
+        };
+        // Applies one durable event. Hydrated history is applied silently: it is neither a new
+        // turn nor a new tool call, but running tools and partial reasoning must still be known.
+        const applyEvent = (evt, notify) => {
+            const payload = evt.payload || {};
+            const eventType = evt.event_type;
+            const toolId = String(payload.call_id || payload.tool_instance_id || '');
+            // Durable history keys tool calls by payload.call_id; tool_instance_id is `step-N:<call_id>`.
+            const callId = toolCallIdFromPayload(payload);
+            const toolKey = callId || toolId;
+            if (eventType === 'session.tool.started') {
+                const toolItem = {
+                    id: toolId || evt.id,
+                    callId: callId || toolId || evt.id,
+                    name: String(payload.tool_name || 'tool'),
+                    identity: payload.tool_identity ? String(payload.tool_identity) : undefined,
+                    display: payload.tool_display ? String(payload.tool_display) : undefined,
+                    arguments: payload.arguments ? String(payload.arguments) : undefined,
+                    status: 'running',
+                };
+                activeTools.set(toolKey || toolItem.id, toolItem);
+                if (notify)
+                    options.onToolStarted?.(toolItem);
+            }
+            else if (eventType === 'session.tool.delta') {
+                const toolItem = activeTools.get(toolKey);
+                const delta = String(payload.output || '');
+                if (toolItem && delta) {
+                    toolItem.output = (toolItem.output || '') + delta;
+                    if (notify)
+                        options.onToolDelta?.(toolItem, delta);
+                }
+            }
+            else if (TERMINAL_TOOL_STATUS[eventType]) {
+                let toolItem = activeTools.get(toolKey);
+                if (!toolItem) {
+                    toolItem = { id: toolId, callId: callId || toolId, name: String(payload.tool_name || 'tool'), status: TERMINAL_TOOL_STATUS[eventType] };
+                }
+                activeTools.delete(toolKey);
+                toolItem.status = TERMINAL_TOOL_STATUS[eventType];
+                if (payload.output)
+                    toolItem.output = String(payload.output);
+                if (toolItem.status === 'failed')
+                    toolItem.error = String(payload.error || 'Tool execution failed');
+                else if (payload.error)
+                    toolItem.error = String(payload.error);
+                if (payload.duration_ms)
+                    toolItem.durationMs = Number(payload.duration_ms);
+                if (notify)
+                    options.onToolCompleted?.(toolItem);
+            }
+            else if (eventType === 'session.reasoning.delta' && typeof payload.delta === 'string') {
+                const key = JSON.stringify([payload.run_id, payload.reasoning_id ?? payload.reasoning_key]);
+                const previous = reasoning.get(key) ?? '';
+                const full = payload.delta_mode === 'replace' ? payload.delta : previous + payload.delta;
+                if (full === previous)
+                    return;
+                reasoning.set(key, full);
+                if (reasoning.size > 64)
+                    reasoning.delete(reasoning.keys().next().value);
+                if (notify)
+                    options.onReasoning?.(full.startsWith(previous) ? full.slice(previous.length) : full, full);
+            }
+        };
         return this.realtime.watchSession(id, {
             signal: options.signal,
             surface: options.surface ?? 'chat',
@@ -143,96 +239,41 @@ export class SwarmChatNamespace {
                 const sessionEvents = state.snapshot.events_by_session?.[id] || [];
                 if (!initialized) {
                     initialized = true;
-                    // Hydrated history is not a new turn or a new permission request.
-                    for (const evt of sessionEvents)
+                    for (const evt of sessionEvents) {
                         seenEventIds.add(evt.id);
+                        applyEvent(evt, false);
+                    }
                     if (run?.run_id && !run.active)
                         completedRuns.add(run.run_id);
                 }
                 if (run?.active)
                     observedRun = run.run_id;
+                // 1. Assistant text: live text per run/stream, then the committed message's tail.
+                const liveKeys = new Set();
                 for (const item of state.live || []) {
                     const key = JSON.stringify([item.runId, item.streamId]);
-                    const previous = previousStreams.get(key) ?? '';
-                    if (item.text === previous)
+                    liveKeys.add(key);
+                    reportText(key, item.runId, item.streamId, item.text);
+                }
+                for (const [key, entry] of reportedText) {
+                    if (liveKeys.has(key))
                         continue;
-                    previousStreams.set(key, item.text);
-                    observedRun = item.runId;
-                    const delta = item.text.startsWith(previous) ? item.text.slice(previous.length) : item.text;
-                    if (item.streamId.includes('reasoning'))
-                        options.onReasoning?.(delta, item.text);
-                    else
-                        options.onText?.(delta, item.text);
+                    const committed = state.messages.find(m => m.role === 'assistant'
+                        && m.metadata?.run_id === entry.runId && m.metadata?.stream_id === entry.streamId);
+                    if (committed && typeof committed.content === 'string') {
+                        reportText(key, entry.runId, entry.streamId, committed.content);
+                        forgetText(key);
+                    }
+                    else if (state.status === 'live' && !(run?.active && run.run_id === entry.runId)) {
+                        forgetText(key);
+                    }
                 }
-                // Bound transient state to streams still in the current snapshot.
-                const liveKeys = new Set(state.live.map(item => JSON.stringify([item.runId, item.streamId])));
-                for (const key of previousStreams.keys())
-                    if (!liveKeys.has(key))
-                        previousStreams.delete(key);
-                // 2. Process Realtime Events (Tool streams & Permissions)
+                // 2. Durable events (tools, reasoning), each exactly once and in sequence order.
                 for (const evt of sessionEvents) {
                     if (seenEventIds.has(evt.id))
                         continue;
                     seenEventIds.add(evt.id);
-                    const payload = evt.payload || {};
-                    const eventType = evt.event_type;
-                    if (eventType === 'session.tool.started') {
-                        const toolId = String(payload.call_id || payload.tool_instance_id || evt.id);
-                        const toolItem = {
-                            id: toolId,
-                            name: String(payload.tool_name || 'tool'),
-                            identity: payload.tool_identity ? String(payload.tool_identity) : undefined,
-                            display: payload.tool_display ? String(payload.tool_display) : undefined,
-                            arguments: payload.arguments ? String(payload.arguments) : undefined,
-                            status: 'running',
-                        };
-                        activeTools.set(toolId, toolItem);
-                        options.onToolStarted?.(toolItem);
-                    }
-                    else if (eventType === 'session.tool.delta') {
-                        const toolId = String(payload.call_id || payload.tool_instance_id || '');
-                        const toolItem = activeTools.get(toolId);
-                        const delta = String(payload.output || '');
-                        if (toolItem && delta) {
-                            toolItem.output = (toolItem.output || '') + delta;
-                            options.onToolDelta?.(toolItem, delta);
-                        }
-                    }
-                    else if (eventType === 'session.tool.completed') {
-                        const toolId = String(payload.call_id || payload.tool_instance_id || '');
-                        let toolItem = activeTools.get(toolId);
-                        if (!toolItem) {
-                            toolItem = {
-                                id: toolId,
-                                name: String(payload.tool_name || 'tool'),
-                                status: 'completed',
-                            };
-                            activeTools.set(toolId, toolItem);
-                        }
-                        toolItem.status = 'completed';
-                        if (payload.output)
-                            toolItem.output = String(payload.output);
-                        if (payload.duration_ms)
-                            toolItem.durationMs = Number(payload.duration_ms);
-                        options.onToolCompleted?.(toolItem);
-                    }
-                    else if (eventType === 'session.tool.failed') {
-                        const toolId = String(payload.call_id || payload.tool_instance_id || '');
-                        let toolItem = activeTools.get(toolId);
-                        if (!toolItem) {
-                            toolItem = {
-                                id: toolId,
-                                name: String(payload.tool_name || 'tool'),
-                                status: 'failed',
-                            };
-                            activeTools.set(toolId, toolItem);
-                        }
-                        toolItem.status = 'failed';
-                        toolItem.error = String(payload.error || 'Tool execution failed');
-                        if (payload.duration_ms)
-                            toolItem.durationMs = Number(payload.duration_ms);
-                        options.onToolCompleted?.(toolItem);
-                    }
+                    applyEvent(evt, true);
                     if (seenEventIds.size > 4096)
                         seenEventIds.delete(seenEventIds.values().next().value);
                 }
@@ -296,7 +337,7 @@ export class SwarmChatNamespace {
                     if (completedRuns.size > 4096)
                         completedRuns.delete(completedRuns.values().next().value);
                     if (observedRun === run.run_id || run.completed_at)
-                        options.onComplete?.(state.messages);
+                        options.onComplete?.(options.rawCopyTags ? state.messages : state.messages.map(cleanAssistantMessage), run);
                 }
             },
             onError: (err) => {
@@ -305,3 +346,27 @@ export class SwarmChatNamespace {
         });
     }
 }
+const TERMINAL_TOOL_STATUS = {
+    'session.tool.completed': 'completed',
+    'session.tool.failed': 'failed',
+    'session.tool.cancelled': 'cancelled',
+    'session.tool.canceled': 'cancelled',
+};
+/**
+ * The durable tool-call id (`payload.call_id` on `session.tool.*` events). When an event
+ * carries only `tool_instance_id` (`step-<n>:<call_id>`), the step prefix is removed.
+ */
+export function toolCallIdFromPayload(payload) {
+    const callId = typeof payload?.call_id === 'string' ? payload.call_id.trim() : '';
+    if (callId)
+        return callId;
+    const instance = typeof payload?.tool_instance_id === 'string' ? payload.tool_instance_id.trim() : '';
+    return instance.replace(/^step-\d+:/, '');
+}
+/** Assistant message with Swarm copy tags turned into Markdown code blocks. */
+function cleanAssistantMessage(message) {
+    if (message?.role !== 'assistant' || typeof message.content !== 'string')
+        return message;
+    const content = copyTagsToMarkdown(message.content);
+    return content === message.content ? message : { ...message, content };
+}

package/dist/client.d.ts

@@ -1,3 +1,4 @@
+import { SwarmAgentsNamespace } from './agents.js';
 import { SwarmAppsNamespace } from './apps.js';
 import { SwarmChatNamespace } from './chat.js';
 import { SwarmPermissionsNamespace } from './permissions.js';
@@ -11,7 +12,10 @@ import { SwarmWorkersNamespace } from './workers.js';
 import { SwarmDeliverablesNamespace } from './deliverables.js';
 import { SwarmDeployNamespace } from './deploy/index.js';
 import { SwarmNotificationsNamespace } from './notifications.js';
+import { SwarmSignalsNamespace } from './signals.js';
+import { SwarmBoxNamespace } from './box.js';
 import { SwarmProjectsNamespace } from './projects.js';
+import { SwarmRemoteNamespace } from './remote.js';
 import { SwarmSessionsNamespace } from './sessions.js';
 import { SwarmSystemNamespace } from './system.js';
 import { SwarmStorageNamespace } from './storage/index.js';
@@ -52,7 +56,15 @@ export declare class SwarmClient {
     readonly notifications: SwarmNotificationsNamespace;
     /** Convenient alias for notifications namespace: inbox */
     readonly inbox: SwarmNotificationsNamespace;
+    /** Machine signal feed: blocked agents, failures, refused keys, reported events. */
+    readonly signals: SwarmSignalsNamespace;
+    /** Machine state for monitors: sandbox, blocked sessions, failing workers, usage. */
+    readonly box: SwarmBoxNamespace;
     readonly storage: SwarmStorageNamespace;
+    /** Owner administration of the relay connection (private transport only) */
+    readonly remote: SwarmRemoteNamespace;
+    /** Sealed agents and the client tools your application answers */
+    readonly agents: SwarmAgentsNamespace;
     /** Convenient alias for cloud storage connections: cloud */
     readonly cloud: SwarmStorageNamespace;
     constructor(config?: SwarmClientConfig);

package/dist/client.js

@@ -1,3 +1,4 @@
+import { SwarmAgentsNamespace } from './agents.js';
 import { SwarmAppsNamespace } from './apps.js';
 import { SwarmChatNamespace } from './chat.js';
 import { SwarmPermissionsNamespace } from './permissions.js';
@@ -11,10 +12,14 @@ import { SwarmWorkersNamespace } from './workers.js';
 import { SwarmDeliverablesNamespace } from './deliverables.js';
 import { SwarmDeployNamespace } from './deploy/index.js';
 import { SwarmNotificationsNamespace } from './notifications.js';
+import { SwarmSignalsNamespace } from './signals.js';
+import { SwarmBoxNamespace } from './box.js';
 import { SwarmProjectsNamespace } from './projects.js';
+import { SwarmRemoteNamespace } from './remote.js';
 import { SwarmSessionsNamespace } from './sessions.js';
 import { SwarmSystemNamespace } from './system.js';
 import { SwarmStorageNamespace } from './storage/index.js';
+import { resolveSwarmConnection } from './local-connection.js';
 import { SwarmTransport } from './transport.js';
 import { SwarmWorkspacesNamespace } from './workspaces.js';
 export class SwarmClient {
@@ -51,19 +56,23 @@ export class SwarmClient {
     notifications;
     /** Convenient alias for notifications namespace: inbox */
     inbox;
+    /** Machine signal feed: blocked agents, failures, refused keys, reported events. */
+    signals;
+    /** Machine state for monitors: sandbox, blocked sessions, failing workers, usage. */
+    box;
     storage;
+    /** Owner administration of the relay connection (private transport only) */
+    remote;
+    /** Sealed agents and the client tools your application answers */
+    agents;
     /** Convenient alias for cloud storage connections: cloud */
     cloud;
     constructor(config = {}) {
         const env = typeof process !== 'undefined' && process?.env ? process.env : {};
-        const baseUrl = config.baseUrl ||
-            env.SWARM_API_URL ||
-            env.SWARM_DESKTOP_URL ||
-            'http://127.0.0.1:18080';
-        const socketPath = config.socketPath || env.SWARM_SOCKET_PATH;
+        const { baseUrl, socketPath } = resolveSwarmConnection(config, { env });
         const token = config.token || env.SWARM_AUTH_TOKEN || env.SWARM_DEPLOY_TOKEN;
         const resolved = {
-            baseUrl: baseUrl.replace(/\/+$/, ''),
+            baseUrl,
             token,
             socketPath,
             defaultHeaders: config.defaultHeaders ?? {},
@@ -92,8 +101,12 @@ export class SwarmClient {
         this.deploy = new SwarmDeployNamespace(this.transport);
         this.notifications = new SwarmNotificationsNamespace(this.transport);
         this.inbox = this.notifications;
+        this.signals = new SwarmSignalsNamespace(this.transport);
+        this.box = new SwarmBoxNamespace(this.transport);
+        this.agents = new SwarmAgentsNamespace(this.transport);
         this.storage = new SwarmStorageNamespace(this.transport);
         this.cloud = this.storage;
+        this.remote = new SwarmRemoteNamespace(this.transport);
     }
     /**
      * Updates the bearer authentication token for all subsequent client requests.

package/dist/copy-tags.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Swarm agents wrap copyable snippets (commands, config, file payloads) in
+ * `<copy label="...">…</copy>` tags. Swarm's own desktop and terminal UIs render
+ * them as copy buttons; everywhere else they are noise. `copyTagsToMarkdown`
+ * turns each tag into a plain Markdown code block (with its label, if any, as a
+ * bold line above it), so any Markdown renderer shows it correctly.
+ *
+ * Rules (same parsing as Swarm's own renderers):
+ * - Tags inside fenced code blocks (``` or ~~~) are left untouched.
+ * - The label comes from `label`, `title` or `name`.
+ * - A tag that is never closed becomes a code block running to the end.
+ * - Text without copy tags is returned unchanged.
+ *
+ * Pass `{ streaming: true }` for text that is still arriving: a half-written tag
+ * at the very end is hidden, so converting the growing text only ever appends.
+ *
+ * The SDK applies it by default to assistant text from `chat.run`,
+ * `chat.listMessages` and `chat.stream` (`onText`, `onComplete`); pass
+ * `rawCopyTags: true` there to get the original text. Lower-level reads
+ * (`sessions.get`, `realtime.watchSession`) return the stored text unchanged.
+ */
+export declare function copyTagsToMarkdown(text: string, options?: {
+    streaming?: boolean;
+}): string;
+/** True when `text` contains at least one `<copy>` tag outside fenced code. */
+export declare function hasCopyTags(text: string): boolean;