@swarm-agent/sdk 0.1.47

package/README.md

@@ -0,0 +1,473 @@
+# @swarm-agent/sdk
+
+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.
+
+## 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.
+- **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
+
+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):
+
+<copy>
+npm install "$SDK_TARBALL"
+node --input-type=module -e "import { SwarmClient } from '@swarm-agent/sdk'; console.log(typeof SwarmClient)"
+</copy>
+
+For maintainers, the SDK builds independently with its own locked dev dependencies:
+
+<copy>
+cd packages/sdk
+npm ci --ignore-scripts
+npm run build
+npm pack --pack-destination "$PACKAGE_OUTPUT_DIR"
+</copy>
+
+The pack contains compiled ESM, declarations, license, README and the headless
+example, not source tests or node_modules. `prepack` builds locally; there are no
+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
+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.
+The packaged `examples/headless-session.ts` imports `@swarm-agent/sdk` and can be copied
+into your consumer and run with an explicitly installed `tsx` runner. Protect its
+`SWARM_SDK_TOKEN_FILE` (0600); the example asks before each tool approval and uses
+explicit refresh, not timer polling. Live agent verification is a separate step.
+
+## Quick Start
+
+### 1. Initialize Client
+
+```typescript
+import { createSwarmClient } from '@swarm-agent/sdk';
+
+// 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
+});
+```
+
+### 2. Local Desktop Bootstrap & Scoped Tokens
+
+```typescript
+// Bootstrap local session credentials from Desktop
+const session = await client.auth.bootstrapDesktopSession();
+console.log(`Authenticated as user ${session.user_id}`);
+
+// Create a scoped deploy token for CI/CD or webhooks
+const { token, record } = await client.auth.createScopedToken({
+  name: 'GitHub Actions Trigger',
+  scopes: ['automations:trigger'],
+  expires_in_seconds: 86400, // 24 hours
+});
+console.log(`Created deploy token: ${token} (hint: ${record.token_hint})`);
+
+// List active tokens
+const tokens = await client.auth.listScopedTokens();
+```
+
+### 3. Trigger Workers On-Demand with Runtime Context
+
+```typescript
+// Trigger an automation with webhook/CI context
+const result = await client.automations.trigger({
+  worker_id: 'ci_test_analyzer',
+  context: {
+    event: 'push',
+    commit_sha: '44a93badc',
+    branch: 'dev',
+    failed_tests: ['TestWorkerRetry'],
+  },
+});
+
+console.log(`Trigger admitted! Occurrence ID: ${result.occurrence.id}`);
+console.log(`Worker execution session: ${result.occurrence.session_id}`);
+```
+
+### 4. Create and Manage Sessions
+
+```typescript
+// Create a new autonomous coding session
+const newSession = await client.sessions.create({
+  title: 'Investigate Test Flakes',
+  workspace_path: '/path/to/project',
+  agent: 'coder',
+});
+
+// Send a message
+await client.sessions.sendMessage(newSession.id, {
+  content: 'Please analyze why TestWorkerRetry is timing out.',
+});
+
+// Poll until the agent run finishes
+const finishedSession = await client.sessions.waitForRun(newSession.id, {
+  timeoutMs: 120_000,
+});
+```
+
+### 5. Workspaces and Health
+
+```typescript
+// Check daemon health
+const health = await client.system.health();
+console.log('Daemon healthy:', health.ok);
+
+// List registered workspaces
+const workspaces = await client.workspaces.list();
+for (const ws of workspaces) {
+  console.log(`- ${ws.name} (${ws.path})`);
+}
+```
+
+### 6. Projects, Autonomous Tasks, and Orchestrate Primitives
+
+Manage multi-workspace projects, autonomous tasks, route previews, plan review lifecycles, and opaque event sync streams:
+
+```typescript
+// Create a new project aggregating workspaces
+const project = await client.projects.create({
+  name: 'Mobile Core Redesign',
+  description: 'Refactor mobile navigation and auth screens',
+  workspaces: [{ path: '/workspaces/mobile-app', role: 'primary_code' }],
+});
+
+// Create an autonomous task with agent routing
+const { task, model_preview } = await client.projects.createTask(project.id, {
+  title: 'Implement OAuth refresh token rotation',
+  agent: 'coder',
+  feature_size: 'small',
+  prompt: 'Add proactive token refresh before expiration with retry backoff',
+});
+
+// Preview how Orchestrate routes and models a proposed task before creation
+const preview = await client.projects.previewTask(project.id, {
+  title: 'Audit API authorization checks',
+  agent: 'finder',
+});
+
+// Guarded plan acceptance: enforce exact session, plan, and definition revision
+const approved = await client.projects.approveTask(project.id, task.id, {
+  session_id: task.session_id,
+  plan_id: task.plan_binding?.plan_id,
+  definition_revision: task.plan_binding?.definition_revision,
+});
+
+// Reopen a task with focused human feedback directives
+await client.projects.reopenTask(project.id, task.id, {
+  feedback: 'Unit test flake on Node 20; please address.',
+});
+
+// Refine a plan based on feedback or error recovery
+await client.projects.refineTask(project.id, task.id, {
+  feedback: 'Split implementation into schema migration then service logic',
+  agent: 'coder',
+});
+
+// Stream or replay outbox events starting after an opaque cursor
+const streamResult = await client.projects.replayEvents('opaque_cursor_token');
+```
+
+### 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`):
+
+```typescript
+// Register a signed webhook destination
+const webhook = await client.automations.createWebhook({
+  url: 'https://api.mycompany.com/webhooks/swarm',
+  secret: 'whk_hmac_secret_key',
+  format: 'generic', // 'generic' | 'slack' | 'discord' | 'telegram'
+  events: ['failed', 'retry_exhausted'], // or ['*'] for all events
+});
+
+// Test the webhook with an immediate ping
+const testResult = await client.automations.testWebhook({
+  id: webhook.id,
+  worker_title: 'Database Backup',
+});
+console.log(`Ping delivered: HTTP ${testResult.result?.status_code} in ${testResult.result?.duration_ms}ms`);
+
+// List configured webhooks
+const webhooks = await client.automations.listWebhooks();
+
+// Delete a webhook
+await client.automations.deleteWebhook(webhook.id);
+```
+
+### 8. Deliverables Hub & Agent Mailbox
+
+Submit completed work (social media drafts, reports, test alerts) from background workers to the local Swarm Agent Mailbox for human review, editing, and one-click publication actions:
+
+```typescript
+// Submit finished worker output to the Mailbox
+const deliverable = await client.deliverables.submit({
+  title: 'Weekly Community Launch Thread',
+  kind: 'social_post',
+  worker_id: 'social_media_bot',
+  payload: {
+    posts: [
+      { text: '1/3 Announcing our new distributed agent architecture...' },
+      { text: '2/3 Run workers in the cloud, review in your local mailbox.' },
+      { text: '3/3 Try it today with @swarm-agent/sdk.' }
+    ]
+  },
+  action_contract: {
+    action: 'publish_x_post',
+    target_secret_ref: 'gcp:x-api-key'
+  }
+});
+
+// List unreviewed deliverables in the inbox
+const pending = await client.deliverables.list({ status: 'pending_review' });
+console.log(`Pending inbox items: ${pending.length}`);
+
+// Approve deliverable and trigger publication action
+const result = await client.deliverables.approve(deliverable.id);
+console.log('Published:', result.action_result);
+```
+
+### 9. Withdrawn cloud recipes — migration required
+
+**The historical recipes below are unsupported and all built-in generation/execution calls now reject them.** They are retained here only as migration context, not runnable instructions or verified measurements. The old latency, capacity, cost and image-size claims were not qualified for the canonical daemon and must not be relied upon.
+
+Use `generateOptimizedDockerfile({ runtimeImage })` with the exact
+`ghcr.io/swarm-agent/swarm-headless@sha256:<digest>` from the qualified release manifest.
+No digest is invented or selected automatically. See
+[the supported application recipe](../../containers/headless/app/README.md).
+Cloud Run, Cloud Run worker actors, and the old Compute Engine source installer
+are withdrawn: they do not preserve canonical runtime, private listener, and
+single-writer durable state contracts. Legacy manifest parsing remains available
+for migration, not as a supported deployment preset.
+
+<details>
+<summary>Historical unsupported API examples (do not execute)</summary>
+
+Deploy Swarm as a self-contained, serverless or dedicated cloud service on Google Cloud Platform with sub-1.5s cold starts and true scale-to-zero ($0 idle cost).
+
+The deployment module supports both programmatic definitions and file-driven workflows (`swarm.deploy.json`), producing optimized multi-stage distroless containers and execution pipelines directly from the canonical repository ([https://github.com/swarm-agent/swarm](https://github.com/swarm-agent/swarm)).
+
+#### The Easy 1-2-3 Deployment Flow for AI Agents & Developers
+
+##### Step 1: Create or Load a Deployment Manifest
+
+Use pre-tuned presets (`latency-optimized`, `zero-idle-cost`, `free-tier-vm`, `always-on`) or define a custom `swarm.deploy.json`:
+
+```typescript
+import { createSwarmClient } from '@swarm-agent/sdk';
+
+const client = createSwarmClient();
+
+// Programmatic creation with latency-optimized preset
+const manifest = client.deploy.createManifest({
+  preset: 'latency-optimized',
+  name: 'swarm-cloud-agent',
+  gcpCloudRun: {
+    serviceName: 'swarm-agent-service',
+    region: 'us-central1',
+    memory: '512Mi',
+    cpu: '1',
+    minInstances: 0, // True scale-to-zero ($0 idle spend)
+    cpuBoost: true,  // Startup CPU Boost for <1.5s cold boot
+  },
+  env: {
+    SWARM_ENV: 'production',
+  },
+});
+```
+
+Or load from a `swarm.deploy.json` file in your workspace:
+
+```json
+{
+  "version": "1.0",
+  "name": "swarm-gcp-service",
+  "target": "gcp-cloud-run",
+  "source": {
+    "type": "github",
+    "repository": "https://github.com/swarm-agent/swarm",
+    "branch": "main",
+    "buildStrategy": "distroless"
+  },
+  "gcpCloudRun": {
+    "serviceName": "swarmd",
+    "region": "us-central1",
+    "cpu": "1",
+    "memory": "512Mi",
+    "minInstances": 0,
+    "maxInstances": 10,
+    "concurrency": 80,
+    "port": 18080,
+    "cpuBoost": true,
+    "executionEnvironment": "gen2"
+  }
+}
+```
+
+##### Step 2: Generate Deployment Plan & Artifacts
+
+Generate the complete deployment plan, including standalone multi-stage Dockerfiles, Cloud Build configurations, and deployment scripts:
+
+```typescript
+// Generate the full structured deployment plan
+const plan = client.deploy.plan(manifest);
+console.log('Target Architecture:', plan.target);
+console.log('Cost Summary:', plan.summary);
+console.log('Recommendations:', plan.recommendations);
+
+// Or generate files ready to be written to disk
+const files = client.deploy.generateArtifacts(manifest);
+// files['Dockerfile']       -> Stripped multi-stage distroless container (<35MB)
+// files['.dockerignore']    -> Excludes git, node_modules, logs, and secrets
+// files['cloudbuild.yaml']  -> Google Cloud Build pipeline
+// files['deploy.sh']        -> Executable bash deployment script
+```
+
+##### Step 3: Execute Deployment (Programmatic or Command-Driven)
+
+You can either execute the deployment pipeline programmatically in a single SDK call, write artifacts to disk, or inspect the shell commands:
+
+```typescript
+// Option A: Programmatic Execution (0-1 in 1 line of code)
+const result = await client.deploy.execute(manifest, {
+  // dryRun: true, // Optional: simulate pipeline without mutating cloud resources
+  onLog: (line, phase) => console.log(`[${phase}] ${line}`),
+});
+
+console.log('Deploy Status:', result.success ? 'SUCCESS' : 'FAILED');
+console.log('Elapsed Time:', `${result.durationMs}ms`);
+console.log('Service URL:', result.serviceUrl || result.externalIp);
+
+// Option B: Write artifacts to directory
+await client.deploy.writeArtifacts('./deploy-output', manifest);
+
+// Option C: Inspect sequential shell commands
+const commands = client.deploy.generateCommands(manifest);
+for (const step of commands) {
+  console.log(`[${step.phase.toUpperCase()}] ${step.title}`);
+  console.log(`Command: ${step.command}`);
+  console.log(`Why:     ${step.explanation}\n`);
+}
+```
+
+The generated deployment commands execute:
+1. **Cloud Build**: Compiles a static Go binary with stripped symbol tables (`-ldflags="-s -w"`) inside a distroless runtime (`gcr.io/distroless/static-debian12:nonroot`).
+2. **Cloud Run Deploy**: Deploys the service with `--cpu-boost` (Startup CPU Boost) and `--execution-environment gen2`.
+3. **Health Verification**: Queries the service URL and verifies `/v1/system/health`.
+
+The former benchmark table has been withdrawn: there is no revision-bound live
+qualification evidence for those image-size, latency, capacity or cost claims.
+
+#### Free Tier Compute Engine (GCE) & Dynamic Context Management
+
+For persistent background daemons on Google Cloud's Free Tier ($0/month) with dynamic context management:
+
+```typescript
+const gceManifest = client.deploy.createManifest({
+  preset: 'free-tier-vm',
+  name: 'swarm-free-tier',
+  context: {
+    instructions: 'You are an autonomous background support agent.',
+    prompt: 'Monitor incoming notifications and update status.',
+    model: 'gemini-3.8-flash',
+    thinking: 'low',
+    workspaceUrl: 'https://github.com/my-org/my-project.git',
+  },
+  env: {
+    APP_ENV: 'production',
+  },
+  gcpCompute: {
+    instanceName: 'swarm-free-vm',
+    machineType: 'e2-micro', // 2 vCPU, 1GB RAM (Free Tier eligible)
+    diskSizeGb: 30,          // 30GB Standard persistent disk (Free Tier eligible)
+  },
+});
+
+const gcePlan = client.deploy.plan(gceManifest);
+// Generates:
+// 1. startup-script.sh with automated swapfile creation, systemd unit, and /usr/local/bin/swarm-sync-context.
+// 2. deploy-vm.sh provisioning the GCE VM unattended.
+// 3. AGENTS.md & PROMPT.txt context files.
+
+// Execute headless deployment
+const gceResult = await client.deploy.execute(gcePlan);
+```
+
+##### Managing Context Dynamically via Instance Metadata (No Rebuilds)
+Once the VM is running, users and orchestrators can dynamically update the agent's instructions, prompts, and environment without recreating the VM:
+```bash
+# Update instructions or prompt on a live VM
+gcloud compute instances add-metadata swarm-free-vm \
+  --metadata swarm-prompt="Audit and fix outstanding PR comments" \
+  --zone us-central1-a
+
+# The VM's /usr/local/bin/swarm-sync-context automatically applies the new context and reloads swarmd!
+```
+
+#### Multi-Cloud Extensibility
+
+The `@swarm-agent/sdk` deployment architecture is designed for multi-cloud extensibility. Custom providers (for AWS ECS, Azure Container Apps, Fly.io, or Kubernetes) can be registered at runtime:
+
+```typescript
+import type { CloudDeployProvider } from '@swarm-agent/sdk';
+
+class CustomCloudProvider implements CloudDeployProvider {
+  readonly target = 'my-cloud';
+  validate(manifest) { return { valid: true, errors: [], warnings: [] }; }
+  plan(manifest) { /* ... */ }
+  generateArtifacts(manifest) { return { 'deploy.yaml': '...' }; }
+  generateCommands(manifest) { return [/* ... */]; }
+}
+
+client.deploy.registerProvider(new CustomCloudProvider());
+```
+
+</details>
+
+## Error Handling
+
+All failed API responses throw typed `SwarmApiError` instances:
+
+```typescript
+import { SwarmForbiddenError, SwarmNotFoundError, SwarmTimeoutError } from '@swarm-agent/sdk';
+
+try {
+  await client.sessions.get('non_existent_session');
+} catch (err) {
+  if (err instanceof SwarmNotFoundError) {
+    console.error('Session not found (404)');
+  } else if (err instanceof SwarmForbiddenError) {
+    console.error('Missing required scope (403):', err.message);
+  } else if (err instanceof SwarmTimeoutError) {
+    console.error('Request timed out after', err.timeoutMs, 'ms');
+  }
+}
+```
+
+## License
+
+Apache-2.0
+
+### Application-owned agents and conversations
+
+`client.apps` provides durable named instructions/context, revision-pinned V3 conversations,
+owned reopen/result reads and idempotent event messages. See [Application agents](APPLICATIONS.md)
+for examples, revision semantics and the private local-API transport requirement. Existing
+`projects` and `workers` remain the task and background-execution authorities.
+
+## Custom headless UI
+
+See [HEADLESS_UI.md](./HEADLESS_UI.md) for private in-container administrative setup, typed provider/settings discovery, API keys and Codex device/manual/browser sign-in, workspace creation, and `client.realtime.watchSession()` with canonical V3 replay and cancellation. The container's session-only listener does not expose administrative APIs.

package/dist/app-results.d.ts

@@ -0,0 +1,24 @@
+import type { SwarmTransport } from './transport.js';
+import type { RealtimeSocketFactory, SessionWatch } from './realtime.js';
+import type { SwarmAppsNamespace, ApplicationAgent } from './apps.js';
+import type { ProjectTaskRecord, WorkerRecord, WorkerRunRecord } from './types.js';
+export interface ApplicationResults {
+    agent: ApplicationAgent;
+    tasks: ProjectTaskRecord[];
+    workers: Array<{
+        worker: WorkerRecord;
+        runs: WorkerRunRecord[];
+    }>;
+}
+export interface ApplicationResultsOptions {
+    signal?: AbortSignal;
+    socketFactory?: RealtimeSocketFactory;
+    onChange(results: ApplicationResults): void;
+    onError?(error: Error): void;
+    maxReconnects?: number;
+}
+/** Resource notifications invalidate authorized snapshots, never supply app data.
+ * Each connection starts with a durable bootstrap cursor BEFORE reading resources.
+ * Reconnect rehydrates everything; cursors are never parsed or shared across scopes.
+ */
+export declare function watchApplicationResults(apps: SwarmAppsNamespace, transport: SwarmTransport, id: string, options: ApplicationResultsOptions): SessionWatch;

package/dist/app-results.js

@@ -0,0 +1,167 @@
+import { SwarmRealtimeNamespace } from './realtime.js';
+/** Resource notifications invalidate authorized snapshots, never supply app data.
+ * Each connection starts with a durable bootstrap cursor BEFORE reading resources.
+ * Reconnect rehydrates everything; cursors are never parsed or shared across scopes.
+ */
+export function watchApplicationResults(apps, transport, id, options) {
+    const controller = new AbortController(), signal = controller.signal;
+    const abort = () => controller.abort();
+    options.signal?.addEventListener('abort', abort, { once: true });
+    if (options.signal?.aborted)
+        abort();
+    let resolveReady, rejectReady;
+    const ready = new Promise((resolve, reject) => { resolveReady = resolve; rejectReady = reject; });
+    void ready.catch(() => { });
+    const realtime = new SwarmRealtimeNamespace(transport);
+    const snapshot = async (readSignal = signal) => {
+        const agent = await apps.get(id, readSignal);
+        const tasks = agent.project_id ? (await apps.tasks(id, readSignal)).tasks : [];
+        const workers = [];
+        // Sequential resource reads bound concurrency even with 100 linked workers.
+        for (const workerId of agent.worker_ids ?? []) {
+            if (signal.aborted)
+                throw new Error('Watch disposed');
+            const { worker } = await apps.worker(id, workerId, readSignal);
+            const { runs } = await apps.runs(id, workerId, readSignal);
+            workers.push({ worker, runs });
+        }
+        return { agent, tasks, workers };
+    };
+    const connect = async () => {
+        await apps.get(id, signal); // Reject foreign app ownership before opening any event scope.
+        // Principal-scoped global workset is the existing resource event contract.
+        // A bounded recent membership is requested; unrelated session payloads are ignored.
+        const initial = (await transport.request('/v3/sync/bootstrap', {
+            method: 'POST', signal, body: { surface: 'desktop', selector: { kind: 'global', global: true, recent: { limit: 1 } }, history: { mode: 'none' } },
+        })).data;
+        if (signal.aborted)
+            return;
+        if (!initial.realtime?.resume.endpoint_cursor)
+            throw new Error('Resource realtime unavailable');
+        let state = await snapshot();
+        if (signal.aborted)
+            return;
+        const socket = await (options.socketFactory ?? (path => realtime.socket(path)))('/v3/realtime/stream?surface=desktop');
+        if (signal.aborted) {
+            socket.close();
+            return;
+        }
+        await new Promise((resolve, reject) => {
+            const requests = new AbortController();
+            let ended = false, hello = false, confirmed = false, refreshing = false, dirty = false;
+            const finish = (error) => {
+                if (ended)
+                    return;
+                ended = true;
+                requests.abort();
+                clearTimeout(timer);
+                signal.removeEventListener('abort', cancel);
+                socket.close();
+                error ? reject(error) : resolve();
+            };
+            const cancel = () => finish();
+            const timer = setTimeout(() => finish(new Error('Resource handshake timed out')), 30_000);
+            const refresh = async () => {
+                dirty = true;
+                if (refreshing)
+                    return;
+                refreshing = true;
+                try {
+                    while (dirty && !ended) {
+                        dirty = false;
+                        const next = await snapshot(requests.signal);
+                        if (ended)
+                            return;
+                        state = next;
+                        if (confirmed) {
+                            options.onChange(state);
+                            resolveReady();
+                        }
+                    }
+                }
+                catch (error) {
+                    finish(error instanceof Error ? error : new Error('Resource refresh failed'));
+                }
+                finally {
+                    refreshing = false;
+                }
+            };
+            signal.addEventListener('abort', cancel, { once: true });
+            socket.addEventListener('close', () => finish(new Error('Resource stream disconnected')));
+            socket.addEventListener('error', () => finish(new Error('Resource stream failed')));
+            socket.addEventListener('message', ({ data }) => {
+                if (ended)
+                    return;
+                try {
+                    const text = String(data);
+                    if (text.length > 8 * 1024 * 1024)
+                        throw new Error('Resource frame too large');
+                    const frame = JSON.parse(text);
+                    if (frame.protocol !== 'v3.realtime' || frame.protocol_version !== 1)
+                        throw new Error('Unsupported resource protocol');
+                    if (frame.kind === 'auth.denied')
+                        throw Object.assign(new Error('Resource authorization denied'), { status: 403 });
+                    if (['cursor.error', 'slow_consumer.reconnect_required'].includes(frame.kind))
+                        throw new Error('Resource stream requires reauthorization');
+                    if (frame.kind === 'hello') {
+                        if (hello)
+                            throw new Error('Duplicate hello');
+                        hello = true;
+                        socket.send(JSON.stringify({ ...initial.realtime.resume, subscriptions: [] }));
+                        return;
+                    }
+                    if (!hello)
+                        throw new Error('Resource frame before hello');
+                    // Resource-only resumes have no replay.done acknowledgment. The first
+                    // resource/watermark/keepalive is a liveness fence, not an atomic snapshot.
+                    // Re-read after it while coalescing replay invalidations; hello alone is
+                    // not readiness and an immediate resume denial must never emit data.
+                    if (!confirmed && ['keepalive', 'endpoint.watermark', 'project.updated', 'worker.updated', 'automation.updated'].includes(frame.kind)) {
+                        confirmed = true;
+                        clearTimeout(timer);
+                        void refresh();
+                        return;
+                    }
+                    if ((frame.kind === 'project.updated' && frame.project_id === state.agent.project_id) ||
+                        (['worker.updated', 'automation.updated'].includes(frame.kind) && state.workers.length > 0))
+                        void refresh();
+                }
+                catch (error) {
+                    finish(error instanceof Error ? error : new Error('Invalid resource frame'));
+                }
+            });
+        });
+    };
+    const done = (async () => {
+        for (let attempt = 0; !signal.aborted; attempt++) {
+            try {
+                await connect();
+                return;
+            }
+            catch (error) {
+                if (signal.aborted)
+                    return;
+                // Authorization errors are terminal, never retried against a different route.
+                const status = error.status;
+                if ([401, 403, 404].includes(status ?? 0) || attempt >= (options.maxReconnects ?? 3))
+                    throw error;
+                await new Promise(resolve => {
+                    const finish = () => { clearTimeout(timer); signal.removeEventListener('abort', finish); resolve(); };
+                    const timer = setTimeout(finish, Math.min(250 * 2 ** attempt, 4000));
+                    signal.addEventListener('abort', finish, { once: true });
+                    if (signal.aborted)
+                        finish();
+                });
+            }
+        }
+    })().catch((error) => {
+        const err = error instanceof Error ? error : new Error('Result watch failed');
+        rejectReady(err);
+        if (!signal.aborted) {
+            options.onError?.(err);
+            throw err;
+        }
+    }).finally(() => { rejectReady(new Error('Watch disposed')); options.signal?.removeEventListener('abort', abort); });
+    void done.catch(() => { });
+    return { ready, done, dispose: abort };
+}