@swarm-agent/sdk 0.1.47 → 0.1.48

package/HEADLESS_UI.md

@@ -1,5 +1,7 @@
 # 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.

package/README.md

@@ -49,19 +49,282 @@ explicit refresh, not timer polling. Live agent verification is a separate step.
 
 ## Quick Start
 
-### 1. Initialize Client
+### Chat Flow vs. Autonomous Orchestration Flow
+
+Swarm supports two distinct modes of execution depending on your application goals:
+
+1. **Interactive Chat Flow (`client.chat` / `client.sessions`)**:
+   - Best for conversational assistants, interactive Q&A, and direct tool calling.
+   - A standalone session has one primary workspace, can use additional authorized workspaces, and follows normal worktree/permission/plan rules. It does not carry a project's high-level Markdown context.
+   - Use `client.chat.createSession()`, `client.chat.run()`, and `client.chat.stream()`.
+
+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.
+   - **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.
+   - Naming a workspace session “Orchestrator” does not grant orchestration authority. Use the project conversation helper; do not supply a workspace path or spoof task metadata.
+   - Models and thinking resolve from daemon account settings. Conversation creation must not overwrite provider/model preferences.
+
+---
+
+### 1. Initialize Client & Auto-Configure Credentials
+
+The SDK can automatically discover credentials from your environment or Codex OAuth:
 
 ```typescript
-import { createSwarmClient } from '@swarm-agent/sdk';
+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
+});
+
+// 1. Ensure headless identity is bootstrapped
+await client.onboarding.ensureBootstrapped({ username: 'developer', swarm_name: 'My Swarm' });
+
+// 2. Auto-configure credentials from environment variables:
+// (checks OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY/GOOGLE_API_KEY, DEEPSEEK_API_KEY, etc.)
+// When found, automatically applies verified provider model recommendations to the fleet & router!
+const auth = await client.auth.autoConfigure();
+console.log(`Provider: ${auth.primaryProvider} (Fleet configured: ${auth.fleetApplied})`);
+
+// Or if using OpenAI Codex OAuth device flow:
+if (!auth.primaryProvider) {
+  await client.auth.codex.loginDevice({
+    onCode: (code) => console.log(`Open ${code.verification_url} and enter ${code.user_code}`),
+  });
+  await client.settings.applyProviderFleet('codex');
+}
+```
+
+---
+
+### 2. Fleet & Router Model Settings
+
+Swarm automatically optimizes models for each specific role in the agent fleet. You can customize them or apply verified recommendations in a single call:
+
+```typescript
+// Apply verified recommendations for a provider across the fleet:
+// Sets Swarm Action (auto), Swarm Plan (plan), Coder, Finder, Designer, Router, and Compact.
+await client.settings.applyProviderFleet('codex');
+
+// Inspect current fleet configuration
+const settings = await client.settings.agentModels();
+console.log('Action Model:', settings.agent_model_settings.swarm.action.model);
+console.log('Router Model:', settings.agent_model_settings.system_agents.router.model);
+console.log('Coder Model:', settings.agent_model_settings.system_agents.coder.model);
+
+// Customize individual slots:
+await client.settings.setSystemAgentModel('router', {
+  provider: 'codex',
+  model: 'gpt-6-luna',
+  thinking: 'low',
+});
+
+// Restore system defaults at any time:
+await client.settings.restoreDefaults();
+```
+
+---
+
+### 3. Explicit permission decisions
+
+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:
+the backend enforces policy, project scope and specialized plan/proposal acceptance.
+
+```typescript
+import { describePermission, answerPermission } from '@swarm-agent/sdk';
+
+const pending = await client.permissions.listSessionPending(sessionId);
+for (const permission of pending) {
+  renderPermission(describePermission(permission)); // Your UI; does not approve anything.
+}
+
+// Call from a user submit handler, with actual user-entered input:
+async function submitAnswer(permission, userInput) {
+  const options = answerPermission(permission, userInput);
+  return await client.permissions.resolve(sessionId, permission.id, 'allow_once', options);
+}
+// Single question: userInput is a string (choice value or custom text).
+// Structured questions: { questionId: 'actual answer', q_2: 'custom text' }.
+// answerPermission serializes the backend reason/answers-map contract, not approved_arguments.answer.
+// Ordinary tools: resolve(..., 'allow_once') or resolve(..., 'deny') only after a user click.
+```
+
+`resolve` returns the confirmed permission record. Transport failures and mismatched/stale
+results reject; `PermissionResolutionError.result` retains a conflicting authoritative record.
+A cancelled request or a prior different answer is not success. Backend sanitization can also
+change returned text; review the returned record instead of blindly resubmitting. Duplicate
+in-flight resolutions are rejected. `approvedArguments` supports an explicitly reviewed JSON
+object where the backend supports it; it is not a question-answer channel.
+
+Persistent actions and policy methods are advanced account-policy operations, not default UI
+buttons. Project conversations require individual one-time decisions. Avoid `resolveAll` for
+interactive forms: it can partially mutate on failure. Never enable bypass or change models
+as incidental chat setup. Explicit auto-approval options affect ordinary tools only; ask-user
+always requires actual user input.
+
+---
 
-// Connect to local Swarm daemon (defaults to http://127.0.0.1:18080 or SWARM_API_URL)
-const client = createSwarmClient({
-  baseUrl: process.env.SWARM_API_URL || 'http://127.0.0.1:18080',
-  token: process.env.SWARM_DEPLOY_TOKEN, // Optional: scoped deploy token
+### 4. Interactive Chat & Live Tool Stream
+
+Build responsive chat UIs that stream model text, reasoning, and live tool execution cards like Swarm Desktop:
+
+```typescript
+// 1. Create a chat session
+const session = await client.chat.createSession({
+  title: 'Repository Exploration',
+  workspace_path: '/path/to/project',
+});
+
+// 2. Stream live text, reasoning, and tool calls
+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); }
+    });
+  },
+  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,
+});
+console.log(response.reply);
+```
+
+---
+
+### 5. Native WebSocket Streaming Bridge & Browser Client
+
+Swarmagent communicates in real-time over bidirectional WebSockets (`/v3/realtime/stream`). The SDK provides an out-of-the-box WebSocket Bridge for Node.js backends and a universal browser client for web frontends (React, Vue, Svelte, or Vanilla JS):
+
+#### Backend (Node.js): Mount WebSocket Bridge
+```typescript
+import http from 'node:http';
+import { SwarmClient } from '@swarm-agent/sdk';
+
+const server = http.createServer((req, res) => { /* app routes */ });
+const client = new SwarmClient();
+
+// Mounts bidirectional WebSocket bridge on /ws:
+// Hooks directly into Swarm daemon's realtime WebSocket outbox, multiplexing tokens, reasoning, and tool calls.
+client.chat.attachWebSocket(server, {
+  path: '/ws',
+  autoApprovePermissions: false, // Explicit server policy; browser cannot enable it
+});
+
+server.listen(3456, '127.0.0.1');
+```
+
+#### Frontend (Browser): Real-Time WebSocket Hooking
+```typescript
+import { SwarmBrowserChat, describePermission, answerPermission } from '@swarm-agent/sdk/browser';
+
+const chat = new SwarmBrowserChat(); // same-origin ws/wss selected automatically
+chat.on('state', state => {
+  // Replace durable history and transient streams separately; never append fullText to history.
+  renderConversation(state.messages, state.live, state.snapshot);
+  // snapshot.current_run_state_by_session[state.sessionId] owns busy/waiting/failed status.
+});
+chat.on('error', showError);
+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));
+// 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)));
+chat.on('permission_error', (id, error) => showPermissionError(id, error));
+chat.on('permission_removed', id => removePermissionForm(id));
+
+// Wire to your form's explicit user-submit handler. Never remove a card on send alone.
+async function onPermissionSubmit(permission, action, userInput) {
+  try {
+    const result = await chat.resolvePermission(permission.id, action,
+      action === 'allow_once' && describePermission(permission).kind === 'ask-user'
+        ? answerPermission(permission, userInput) : {});
+    showConfirmedDecision(result.permission);
+  } catch (error) { showPermissionError(permission.id, error); }
+}
+
+// 2. Connect & subscribe to session
+await chat.connect();
+await chat.subscribe('session_123');
+
+// 3. Send messages directly over WebSocket
+const requestId = chat.sendMessage('Inspect the git repository and list modified files.');
+// `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.
+```
+
+Backend conversation routes should use the same project identity for listing and creation:
+```typescript
+const project = await client.projects.ensureProject('Social content');
+const conversations = await client.projects.listConversations(project.id, { limit: 100 });
+const created = await client.projects.createConversation(project.id, {
+  title: 'New campaign', clientRequestId: crypto.randomUUID(),
 });
+// Return created.id to the browser; await chat.subscribe(created.id) before sending.
 ```
 
-### 2. Local Desktop Bootstrap & Scoped Tokens
+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.
+The browser bridge requires an explicit selected session and never guesses a recent account
+session. Keep it on host loopback; network/multi-user apps must supply `authorize` and their
+own per-session authorization. Foreign browser origins are rejected. Auto approval never
+chooses an `ask-user` answer: render the question and send the operator's reply explicitly.
+
+`resolvePermission` now returns a promise: await it and handle rejection. Browser and bridge
+must be upgraded together; resolution frames require `requestId` and acknowledgements carry
+`result`. `permission_removed` means no longer pending, not approval. `permissions` is a
+rendering projection of the canonical session view, not a second durable authority. Timeout,
+disconnect, disposal or session switch rejects uncertain submissions; reconnect rehydrates
+without replaying decisions. To explicitly rehydrate after an acknowledgement timeout, retain
+`chat.sessionId`, call `chat.unsubscribe()`, then `await chat.subscribe(retainedId)`; never resend
+the decision automatically. Review refreshed state before manually retrying. No UI can infer
+exactly-once application from a lost acknowledgement. `onPermissionError` is recoverable and
+does not close the watch; `onError` reports stream failures. Existing string-reason resolver
+calls remain supported, while options objects carry structured replies and reviewed arguments.
+
+Runnable terminal examples: `examples/chat-quickstart.ts`, `examples/orchestrator-quickstart.ts`
+and their shared `examples/interactive-permissions.ts`. They require a preconfigured daemon,
+ask for actual terminal input, and never configure credentials, model fleets or bypass.
+
+---
+
+### 5. Local Desktop Bootstrap & Scoped Tokens
 
 ```typescript
 // Bootstrap local session credentials from Desktop

package/WORKER_CONTROL.md

@@ -0,0 +1,77 @@
+# Headless worker control (configuration preview)
+
+`client.workers.control` uses authenticated `/v3/workers/{worker_id}` APIs.
+It extends canonical worker identity, run receipts and V3 worker realtime
+invalidation. It is not a second executor or a direct SSH/cloud deployment helper.
+Use a trusted backend/private full API connection, not the restricted container
+session listener. Never give a browser the privileged daemon socket.
+
+## Supported operations
+
+| SDK operation | Route suffix | Effect |
+| --- | --- | --- |
+| `registerSSHTarget` | POST `ssh-targets` | Register an existing-host configuration in the canonical workspace/account connection catalog; idempotent, no network contact. |
+| `resolveTarget` | POST `target-reference` | Authorize an existing SSH connection or GCP topology reference and compute its configuration digest. |
+| `getContext`, `updateContext` | GET/PUT `context` | Read current/exact revision; publish explicit bounded knowledge with CAS and provenance. |
+| `proposeDeployment` | POST `deployments` | Persist pending intent pinned to worker/context/target and explicit lifecycle. |
+| `listDeployments`, `getDeployment` | GET `deployments[/{id}]` | Inspect persisted intent, not runtime health. |
+| `approveDeployment` | POST `deployments/{id}/approve` | Explicit user approves exact revision/digest; stale worker/context/target rejects. |
+| `queueJob` | POST `deployments/{id}/jobs` | Admit a canonical run with resolved account model, context, target, deployment and pending-attempt pins. Does not execute it. |
+| `command`, `commands` | POST/GET `deployments/{id}/commands` | Stop is durable pending intent; start returns 503 unavailable. |
+
+Use existing `workers.listRuns`, `getRun`, and `cancelRun` for job receipts.
+Cancellation of a still-unstarted remote intent releases reservations atomically
+and records `cancelled_before_dispatch`. It is not remote runtime cleanup.
+
+## Safety and semantics
+
+- SDK transport/user identity is authenticated; request JSON cannot supply an
+  account or agent role. Scopes remain `automations:read`/`automations:write`.
+  Trigger/worker-scoped credentials cannot use control-plane operations.
+- Ordinary chat/subagents cannot manage workers. Canonical Orchestrator agent
+  callers can propose intent through the shared service; approvals and explicit
+  context publication require a user. This preview adds no AI tool schema.
+- Existing workers keep IDs and local behavior. Queued remote intent reserves
+  one job per deployment and one context writer per worker. Local admission is
+  also blocked while a remote context writer owns the worker. The first target
+  capacity policy is shared across deployments; a later proposal cannot silently
+  enlarge it. Reservations survive restart.
+- `persistent` and `on_demand` are explicit for SSH and GCP. Approval sets desired
+  state `running`, while observed state remains `unavailable`. A saved intent is
+  never readiness. A stop command closes further admission, stays `pending`,
+  and does not fabricate acknowledgement. Cancel pending jobs separately.
+- Registered existing targets authorize only `owned_runtime` cleanup. No host
+  delete/shutdown capability exists. Future GCP provisioning must establish exact
+  owned resource identity before adding compute deletion.
+- Context is at most 64 KiB plus 32 bounded opaque artifact/checkpoint references;
+  references grant no access and must be reauthorized before use. Updates reject
+  while jobs own context. No automatic transcript ingestion or vector store.
+- Worker changes require new reviewed deployment intent. The preview requires a
+  currently approved active worker and its existing primary workspace binding to
+  admit a job; it does not invent a different worker approval engine.
+
+## Durability and replay
+
+Deployment, context, admission and command mutations use the canonical durable
+worker transaction/outbox. Subscribe to existing V3 `worker.updated` account
+invalidation and rehydrate these APIs; retain opaque scoped endpoint cursors.
+Do not parse cursor numbers or poll for fabricated runtime progress. Worker runs
+retain session identity, but a queued remote attempt has no materialized V3
+session until an adapter actually prepares execution. Do not call a session
+watcher on that reserved ID as if it were a live session.
+
+## Explicitly unavailable
+
+No SSH process launch, GCP provisioning, remote readiness/heartbeat, execution,
+remote acknowledgement, remote context publication, result manifest or cleanup
+is implemented by this preview. Legacy direct dispatch is not a remote fallback.
+Remote outcome writes through the local writer fail closed. Generation is pinned
+at one until a qualified adapter supports replacement/retry fencing. Schedule
+occurrence deduplication is retained at canonical storage; selecting remote
+placement in the live scheduler is deferred, not silently enabled by a proposal.
+GCP references must already exist in canonical account topology with transport
+`gcp`; this API does not enroll cloud credentials or create machines.
+
+`examples/headless-worker-control.ts` is an SDK-only configuration example. It
+registers up to ten explicit SSH configurations and proposes placement. Approval
+is a separate user decision; running the example is not live execution proof.

package/dist/auth.d.ts

@@ -42,4 +42,30 @@ export declare class SwarmAuthNamespace {
         ok: boolean;
         deleted: boolean;
     }>;
+    /**
+     * Automatically configures provider credentials and the AI fleet from environment variables or existing credentials.
+     * Checks for:
+     * - OPENAI_API_KEY -> provider 'openai'
+     * - ANTHROPIC_API_KEY -> provider 'anthropic'
+     * - GEMINI_API_KEY / GOOGLE_API_KEY -> provider 'google'
+     * - DEEPSEEK_API_KEY -> provider 'deepseek'
+     * - GROQ_API_KEY -> provider 'groq'
+     * - MISTRAL_API_KEY -> provider 'mistral'
+     * Also verifies if Codex is authenticated via OAuth.
+     * When credentials are found or active, automatically configures the whole fleet (Swarm Core & System Agents)
+     * with verified catalog recommendations.
+     */
+    autoConfigure(options?: AutoConfigureAuthOptions): Promise<AutoConfigureAuthResult>;
+}
+export interface AutoConfigureAuthOptions {
+    /** If true (default), automatically applies verified catalog recommendations to the fleet */
+    applyFleetRecommendations?: boolean;
+    /** Custom env map (defaults to process.env) */
+    env?: Record<string, string | undefined>;
+}
+export interface AutoConfigureAuthResult {
+    configuredProviders: string[];
+    primaryProvider?: string;
+    source: 'env' | 'existing_credential' | 'none';
+    fleetApplied: boolean;
 }

package/dist/auth.js

@@ -1,4 +1,5 @@
 import { SwarmCredentialsNamespace, SwarmCodexAuthNamespace } from './provider-auth.js';
+import { SwarmSettingsNamespace } from './settings.js';
 export class SwarmAuthNamespace {
     credentials;
     codex;
@@ -86,4 +87,84 @@ export class SwarmAuthNamespace {
         });
         return res.data;
     }
+    /**
+     * Automatically configures provider credentials and the AI fleet from environment variables or existing credentials.
+     * Checks for:
+     * - OPENAI_API_KEY -> provider 'openai'
+     * - ANTHROPIC_API_KEY -> provider 'anthropic'
+     * - GEMINI_API_KEY / GOOGLE_API_KEY -> provider 'google'
+     * - DEEPSEEK_API_KEY -> provider 'deepseek'
+     * - GROQ_API_KEY -> provider 'groq'
+     * - MISTRAL_API_KEY -> provider 'mistral'
+     * Also verifies if Codex is authenticated via OAuth.
+     * When credentials are found or active, automatically configures the whole fleet (Swarm Core & System Agents)
+     * with verified catalog recommendations.
+     */
+    async autoConfigure(options = {}) {
+        const env = options.env || (typeof process !== 'undefined' && process?.env ? process.env : {});
+        const configuredProviders = [];
+        const providerKeyMap = [
+            { provider: 'openai', envVar: 'OPENAI_API_KEY' },
+            { provider: 'anthropic', envVar: 'ANTHROPIC_API_KEY' },
+            { provider: 'google', envVar: 'GEMINI_API_KEY', fallbackEnv: 'GOOGLE_API_KEY' },
+            { provider: 'deepseek', envVar: 'DEEPSEEK_API_KEY' },
+            { provider: 'groq', envVar: 'GROQ_API_KEY' },
+            { provider: 'mistral', envVar: 'MISTRAL_API_KEY' },
+        ];
+        for (const mapping of providerKeyMap) {
+            const key = env[mapping.envVar] || (mapping.fallbackEnv ? env[mapping.fallbackEnv] : undefined);
+            if (key && key.trim()) {
+                try {
+                    await this.credentials.save({
+                        provider: mapping.provider,
+                        type: 'api',
+                        api_key: key.trim(),
+                        active: true,
+                    });
+                    configuredProviders.push(mapping.provider);
+                }
+                catch {
+                    // Continue if already registered or error
+                }
+            }
+        }
+        let source = configuredProviders.length > 0 ? 'env' : 'none';
+        let primaryProvider = configuredProviders[0];
+        // Check if Codex is authenticated via OAuth
+        const codexAuthed = await this.codex.isAuthenticated();
+        if (codexAuthed) {
+            primaryProvider = 'codex';
+            if (source === 'none')
+                source = 'existing_credential';
+        }
+        else if (!primaryProvider) {
+            // Check if existing credentials exist in daemon
+            try {
+                const creds = await this.credentials.list();
+                const activeCred = creds.records.find((r) => r.active);
+                if (activeCred) {
+                    primaryProvider = activeCred.provider;
+                    source = 'existing_credential';
+                }
+            }
+            catch { }
+        }
+        let fleetApplied = false;
+        if (primaryProvider && options.applyFleetRecommendations !== false) {
+            try {
+                const settings = new SwarmSettingsNamespace(this.transport);
+                await settings.applyProviderFleet(primaryProvider);
+                fleetApplied = true;
+            }
+            catch {
+                // Fallback or retry
+            }
+        }
+        return {
+            configuredProviders,
+            primaryProvider,
+            source,
+            fleetApplied,
+        };
+    }
 }

package/dist/browser.d.ts

@@ -0,0 +1,94 @@
+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 interface SwarmBrowserChatOptions {
+    /** WebSocket URL, e.g. ws://localhost:3456/ws. Defaults to ws(s)://${location.host}/ws */
+    url?: string;
+    /** Whether to automatically connect on construction (default: true) */
+    autoConnect?: boolean;
+    /** Whether to automatically reconnect on drop (default: true) */
+    autoReconnect?: boolean;
+    /** Max reconnection attempts before giving up (default: 10) */
+    maxReconnectAttempts?: number;
+    /** Bounds subscription acknowledgement waits (default 45 seconds). */
+    subscribeTimeoutMs?: number;
+    /** Lost acknowledgements reject with an uncertain outcome; decisions are never replayed. */
+    permissionTimeoutMs?: number;
+    /** Optional custom WebSocket constructor (useful in Node.js test environments) */
+    webSocketClass?: any;
+}
+type EventMap = {
+    state: (state: SessionWatchState) => void;
+    accepted: (requestId: string) => void;
+    connected: () => void;
+    disconnected: () => void;
+    subscribed: (sessionId: string) => void;
+    unsubscribed: () => void;
+    text: (delta: string, fullText: string) => void;
+    reasoning: (delta: string, fullText: string) => void;
+    tool_start: (tool: ToolStreamItem) => void;
+    tool_delta: (tool: ToolStreamItem, delta: string) => void;
+    tool_done: (tool: ToolStreamItem) => void;
+    tool_permission: (permission: PendingPermissionRecord) => void;
+    permission_resolved: (permissionId: string, result: ResolvePermissionResult) => void;
+    permission_removed: (permissionId: string) => void;
+    permission_error: (permissionId: string, error: Error) => void;
+    permissions: (pending: PendingPermissionRecord[]) => void;
+    done: (messages: V3Message[]) => void;
+    error: (error: string) => void;
+};
+/**
+ * Universal browser-side WebSocket client for Swarm.
+ * Hooks directly into the Swarm WebSocket Bridge with typed callbacks for live
+ * assistant tokens, model reasoning deltas, real-time tool events, and permission approvals.
+ */
+export declare class SwarmBrowserChat {
+    private readonly options;
+    private ws;
+    private currentSessionId;
+    private isDisposed;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private subscribedSessionId;
+    private permissionsLive;
+    private cancelSubscription?;
+    private connectPromise;
+    private readonly listeners;
+    private readonly pendingPermissions;
+    private readonly decisions;
+    get permissions(): PendingPermissionRecord[];
+    private rejectDecisions;
+    private removePermission;
+    constructor(options?: SwarmBrowserChatOptions);
+    get sessionId(): string | null;
+    get isSubscribed(): boolean;
+    get isConnected(): boolean;
+    private resolveUrl;
+    /**
+     * Connects to the Swarm WebSocket Bridge. Returns a Promise that resolves when connected.
+     */
+    connect(): Promise<void>;
+    private maybeReconnect;
+    private handleServerMessage;
+    private send;
+    /**
+     * Subscribes to real-time events for a specific session.
+     * Returns a promise that resolves once the session subscription is acknowledged.
+     */
+    subscribe(sessionId: string, autoApprovePermissions?: boolean): Promise<string>;
+    /** Unsubscribes from active session streaming */
+    unsubscribe(): void;
+    /** Sends a chat message over the WebSocket */
+    sendMessage(message: string, sessionId?: string, autoApprovePermissions?: boolean, requestId?: string): string;
+    /** Resolve only after a user gesture. Await confirmation; on failure keep the form recoverable. */
+    resolvePermission(permissionId: string, action: PermissionAction, options?: ResolvePermissionOptions & {
+        sessionId?: string;
+    }): Promise<ResolvePermissionResult>;
+    on<K extends keyof EventMap>(event: K, handler: EventMap[K]): () => void;
+    off<K extends keyof EventMap>(event: K, handler: EventMap[K]): void;
+    private emit;
+    /** Closes and disposes the WebSocket connection */
+    dispose(): void;
+}