@swarm-agent/sdk 0.1.49 → 0.1.51

package/dist/projects.js

@@ -1,4 +1,5 @@
-import { SwarmApiError, SwarmTimeoutError, } from './errors.js';
+import { SwarmApiError, SwarmTimeoutError, SwarmValidationError, } from './errors.js';
+import { SwarmSessionsNamespace } from './sessions.js';
 export class SwarmProjectsNamespace {
     transport;
     constructor(transport) {
@@ -115,9 +116,14 @@ export class SwarmProjectsNamespace {
             return session;
         });
     }
+    /** Rename a project conversation (a conversation ID is its session ID); see sessions.rename. */
+    async renameConversation(conversationId, title, options = {}) {
+        return new SwarmSessionsNamespace(this.transport).rename(conversationId, title, options);
+    }
     /** Create an independent project conversation without archiving existing conversations.
      * Models/context resolve on the daemon. Project conversations never bind a workspace.
-     * Reuse clientRequestId when retrying an uncertain creation result.
+     * Reuse clientRequestId when retrying an uncertain creation result. Without a title the
+     * conversation is named from its first message; rename it with renameConversation.
      */
     async createConversation(projectId, options = {}, reqOptions) {
         const id = projectId.trim();
@@ -132,7 +138,7 @@ export class SwarmProjectsNamespace {
             body: {
                 client_request_id: options.clientRequestId ?? `proj-orch-${globalThis.crypto.randomUUID()}`,
                 agent_name: options.agentName ?? 'system-orchestrator',
-                title: options.title ?? 'Orchestrator AI',
+                title: options.title,
                 mode: options.mode ?? 'auto',
             },
             ...reqOptions,
@@ -172,17 +178,6 @@ export class SwarmProjectsNamespace {
         const res = await this.transport.request(`/v3/projects/${id}`, { method: 'DELETE', ...options });
         return res.data ?? { status: 'deleted', id: projectId.trim() };
     }
-    /**
-     * Synthesizes Markdown project context from project name and linked workspaces.
-     */
-    async synthesizeContext(params, options) {
-        const res = await this.transport.request('/v3/projects/synthesize-context', {
-            method: 'POST',
-            body: params,
-            ...options,
-        });
-        return res.data?.project_context ?? '';
-    }
     /**
      * Clears orchestrator context for a project, archiving old session and provisioning replacement.
      */
@@ -485,11 +480,36 @@ export class SwarmProjectsNamespace {
     // ==========================================================================
     /**
      * Integrates task commits into the parent workspace repository.
-     */
-    async integrateTask(projectId, taskId, options) {
+     *
+     * The daemon only integrates an exact selection: the task's current session and its
+     * captured source/target branches. With no options the SDK fetches the task
+     * (`getTask`, which runs a fresh delivery assessment) and builds that selection from
+     * it; pass `options.selection` to override individual fields. A stale selection is
+     * refused by the daemon with a conflict error rather than integrating the wrong lane.
+     */
+    async integrateTask(projectId, taskId, options = {}) {
+        const { selection: overrides, body, ...requestOptions } = options;
         const pId = encodeURIComponent(projectId.trim());
         const tId = encodeURIComponent(taskId.trim());
-        const res = await this.transport.request(`/v3/projects/${pId}/tasks/${tId}/integrate`, { method: 'POST', ...options });
+        // A caller-supplied raw body is treated as overrides too (older workaround shape).
+        const given = {
+            ...(body && typeof body === 'object' ? body : {}),
+            ...(overrides ?? {}),
+        };
+        let selection = given;
+        if (!given.session_id || !given.source_branch || !given.target_branch) {
+            const { task } = await this.getTask(projectId, taskId, {
+                signal: requestOptions.signal,
+                timeoutMs: requestOptions.timeoutMs,
+                headers: requestOptions.headers,
+            });
+            selection = { ...integrationSelectionFromTask(task), ...stripUndefined(given) };
+        }
+        const missing = ['session_id', 'source_branch', 'target_branch'].filter((key) => typeof selection[key] !== 'string' || !selection[key].trim());
+        if (missing.length > 0) {
+            throw new SwarmValidationError(`Task ${taskId} cannot be integrated: no ${missing.join(', ')} on the task record (it has no captured worktree lane yet). Pass options.selection to supply them.`, { missing, selection });
+        }
+        const res = await this.transport.request(`/v3/projects/${pId}/tasks/${tId}/integrate`, { ...requestOptions, method: 'POST', body: stripUndefined(selection) });
         return res.data;
     }
     /**
@@ -606,3 +626,31 @@ export class SwarmProjectsNamespace {
         }
     }
 }
+function nonEmpty(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function stripUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
+}
+/**
+ * Builds the integrate selection the daemon checks from a fresh task record.
+ * Branch precedence: the detail GET's delivery assessment (the daemon's own view of
+ * the captured lane), then the task's recorded worktree/base branch, then the active
+ * attempt's. The daemon still verifies every field against the owned session.
+ */
+export function integrationSelectionFromTask(task) {
+    const assessment = task.delivery_assessment;
+    const attempts = Array.isArray(task.attempts) ? task.attempts : [];
+    const activeAttempt = attempts.find((a) => a && a.id && a.id === task.active_attempt_id) ??
+        attempts.find((a) => a && nonEmpty(a.session_id) && a.session_id === task.session_id);
+    const observed = assessment?.freshness === 'observed';
+    return stripUndefined({
+        session_id: nonEmpty(task.session_id) ?? nonEmpty(assessment?.session_id),
+        source_branch: nonEmpty(assessment?.source_branch) ?? nonEmpty(task.worktree_branch) ?? nonEmpty(activeAttempt?.worktree_branch),
+        target_branch: nonEmpty(assessment?.target_branch) ?? nonEmpty(task.base_branch) ?? nonEmpty(activeAttempt?.base_branch),
+        revision: typeof task.revision === 'number' ? task.revision : undefined,
+        attempt_id: nonEmpty(task.active_attempt_id) ?? nonEmpty(assessment?.attempt_id),
+        source_head: observed ? nonEmpty(assessment?.source_oid) : undefined,
+        target_head: observed ? nonEmpty(assessment?.target_oid) : undefined,
+    });
+}

package/dist/provider-auth.d.ts

@@ -185,9 +185,11 @@ export declare class SwarmOnboardingNamespace {
     get(): Promise<OnboardingStatus>;
     update(body: OnboardingUpdate): Promise<OnboardingStatus>;
     /**
-     * Ensures the headless daemon identity is bootstrapped.
-     * If the daemon requires onboarding, it automatically sets default identity parameters
-     * so provider authentication and sessions can immediately proceed without manual wizard steps.
+     * Ensures the daemon identity (owner name and Swarm name) is bootstrapped, so
+     * provider authentication and sessions can proceed. The owner name is kept as typed.
+     * This only creates identity: it does not mark onboarding finished, so
+     * `config.desktop_onboarding_complete` stays false until your app (or the desktop)
+     * finishes its own setup and calls `update({ desktop_onboarding_complete: true })`.
      */
     ensureBootstrapped(options?: {
         username?: string;

package/dist/provider-auth.js

@@ -116,22 +116,20 @@ export class SwarmOnboardingNamespace {
         return (await this.transport.request('/v1/onboarding', { method: 'POST', body })).data;
     }
     /**
-     * Ensures the headless daemon identity is bootstrapped.
-     * If the daemon requires onboarding, it automatically sets default identity parameters
-     * so provider authentication and sessions can immediately proceed without manual wizard steps.
+     * Ensures the daemon identity (owner name and Swarm name) is bootstrapped, so
+     * provider authentication and sessions can proceed. The owner name is kept as typed.
+     * This only creates identity: it does not mark onboarding finished, so
+     * `config.desktop_onboarding_complete` stays false until your app (or the desktop)
+     * finishes its own setup and calls `update({ desktop_onboarding_complete: true })`.
      */
     async ensureBootstrapped(options = {}) {
         const status = await this.get();
-        if (!status.needs_onboarding && status.identity?.bootstrapped) {
-            return status;
-        }
         if (status.identity?.bootstrapped) {
-            return this.update({ desktop_onboarding_complete: true });
+            return status;
         }
         return this.update({
             username: options.username ?? 'owner',
             swarm_name: options.swarm_name ?? 'Headless Swarm',
-            desktop_onboarding_complete: true,
         });
     }
     /** First credential only. Use auth.credentials.save for subsequent credentials. */

package/dist/realtime.d.ts

@@ -155,6 +155,19 @@ export interface V3SessionView {
     active_plan?: Record<string, unknown>;
     [key: string]: unknown;
 }
+/**
+ * A resource the daemon left out of (or truncated in) a sync snapshot. With
+ * `history.manifest_policy` 'manifest' or 'omit' the recent window is still returned and
+ * `next_cursor` points at the older history that was left out.
+ */
+export interface V3SyncOmission {
+    session_id?: string;
+    resource?: 'messages' | 'events' | string;
+    reason?: 'requires_manifest' | string;
+    next_cursor?: string;
+    manifest_ref?: string;
+    [key: string]: unknown;
+}
 export interface V3SyncSnapshot {
     ok: boolean;
     rev: number;
@@ -169,11 +182,7 @@ export interface V3SyncSnapshot {
         stream_path: string;
         resume: V3Resume;
     };
-    omissions: {
-        session_id?: string;
-        reason?: string;
-        [key: string]: unknown;
-    }[];
+    omissions: V3SyncOmission[];
     pagination: Record<string, unknown>;
     [key: string]: unknown;
 }
@@ -198,6 +207,13 @@ export interface SessionWatchState {
         text: string;
     }>;
     status: 'syncing' | 'live' | 'reconnecting';
+    /**
+     * True when older history did not fit the hydrate window (for example after a very large
+     * tool result) and was left out. `messages`/events still hold the most recent window; the
+     * conversation stays usable. `historyOmissions` names each resource and its `next_cursor`.
+     */
+    historyOmitted?: boolean;
+    historyOmissions?: V3SyncOmission[];
 }
 export interface SessionWatchOptions {
     signal?: AbortSignal;
@@ -212,21 +228,39 @@ export interface SessionWatch {
     done: Promise<void>;
     dispose(): void;
 }
-/** Offset authority is UTF-8 bytes (not JavaScript UTF-16 string length). */
+/**
+ * Transient assistant text assembled from live patches and durable delta checkpoints.
+ * UTF-8 byte offsets (not JavaScript string length) are the only placement authority:
+ * duplicate and overlapping ranges are trimmed, and a range beyond the contiguous prefix
+ * (joining or reconnecting mid-turn, while durable checkpoints lag live output) is held,
+ * bounded, until a durable checkpoint fills the gap. Text is never dropped, repeated or
+ * shown with a hole. A committed message retires its stream.
+ */
 export declare class V3LiveText {
     private streams;
     private committed;
     reset(): void;
     reconcile(messages: V3Message[]): void;
     durable(events: V3Event[]): void;
+    /** Returns false only for a malformed patch; gaps and duplicates are handled here. */
     accept(p: V3LivePatch): boolean;
     values(): SessionWatchState['live'];
+    private commit;
+    private append;
 }
 export declare class SwarmRealtimeNamespace {
     private readonly transport;
     constructor(transport: SwarmTransport);
     bootstrap(body: V3SyncRequest, signal?: AbortSignal): Promise<V3SyncSnapshot>;
     hydrate(body: V3SyncRequest, signal?: AbortSignal): Promise<V3SyncSnapshot>;
+    /**
+     * Hydrates a watch window. The daemon's default manifest policy ('error') refuses the whole
+     * snapshot when the recent window cannot hold all history (e.g. one ~280 KB tool result
+     * exhausts the 256 KB message budget). Both 'omit' and 'manifest' still return the same
+     * newest window plus an omission with `next_cursor`; 'manifest' also returns a descriptor
+     * of what was included, so it loses the least. The policy then sticks for this watch.
+     */
+    private hydrateWindow;
     /** Bounded durable replay. Keep the identical selector/resources/surface for every cursor. */
     replay(body: V3SyncRequest & {
         endpoint_cursor: string;

package/dist/realtime.js

@@ -1,4 +1,18 @@
-/** Offset authority is UTF-8 bytes (not JavaScript UTF-16 string length). */
+import { SwarmApiError } from './errors.js';
+const LIVE_MAX_STREAM_BYTES = 4 * 1024 * 1024;
+const LIVE_MAX_STREAMS = 64;
+const LIVE_MAX_COMMITTED = 4096;
+const utf8Encoder = new TextEncoder();
+const utf8Decoder = new TextDecoder('utf-8', { fatal: true });
+const DURABLE_TEXT_DELTA_EVENTS = new Set(['session.assistant.delta', 'session.message.delta']);
+/**
+ * Transient assistant text assembled from live patches and durable delta checkpoints.
+ * UTF-8 byte offsets (not JavaScript string length) are the only placement authority:
+ * duplicate and overlapping ranges are trimmed, and a range beyond the contiguous prefix
+ * (joining or reconnecting mid-turn, while durable checkpoints lag live output) is held,
+ * bounded, until a durable checkpoint fills the gap. Text is never dropped, repeated or
+ * shown with a hole. A committed message retires its stream.
+ */
 export class V3LiveText {
     streams = new Map();
     committed = new Set();
@@ -7,71 +21,104 @@ export class V3LiveText {
         for (const m of messages) {
             if (m.role !== 'assistant')
                 continue;
-            const run = m.metadata?.run_id ?? m.metadata?.runId;
-            const stream = m.metadata?.stream_id;
-            if (typeof run === 'string' && typeof stream === 'string') {
-                const key = JSON.stringify([run, stream]);
-                if (!this.committed.has(key) && this.committed.size >= 4096)
-                    throw new Error('Live stream history limit reached; reconnect required');
-                this.streams.delete(key);
-                this.committed.add(key);
-            }
+            this.commit(m.metadata?.run_id ?? m.metadata?.runId, m.metadata?.stream_id);
         }
     }
     durable(events) {
         for (const event of events) {
-            const p = event.payload;
+            const p = event.payload ?? {};
             if (event.event_type === 'session.assistant.completed') {
                 const message = p.message;
                 if (message?.role === 'assistant')
                     this.reconcile([message]);
-                const run = p.run_id ?? message?.metadata?.run_id;
-                const stream = p.stream_id ?? message?.metadata?.stream_id;
-                if (typeof run === 'string' && typeof stream === 'string') {
-                    const key = JSON.stringify([run, stream]);
-                    if (!this.committed.has(key) && this.committed.size >= 4096)
-                        throw new Error('Live history limit; reconnect required');
-                    this.streams.delete(key);
-                    this.committed.add(key);
-                }
+                this.commit(p.run_id ?? message?.metadata?.run_id, p.stream_id ?? message?.metadata?.stream_id);
                 continue;
             }
-            if (!['session.assistant.delta', 'session.message.delta'].includes(event.event_type))
+            if (!DURABLE_TEXT_DELTA_EVENTS.has(event.event_type))
                 continue;
-            const run = p.run_id, stream = p.stream_id, start = p.offset_start, end = p.offset_end;
             const text = p.delta ?? p.text_delta ?? p.content_delta;
-            if (typeof run !== 'string' || typeof stream !== 'string' || typeof start !== 'number' || typeof end !== 'number' || typeof text !== 'string')
-                continue;
-            const key = JSON.stringify([run, stream]);
-            const old = this.streams.get(key);
-            if (this.committed.has(key) || end <= (old?.offset ?? 0))
-                continue;
-            const offset = old?.offset ?? 0;
-            const bytes = new TextEncoder().encode(text);
-            if (start < 0 || start > offset || end !== start + bytes.length || end > 4 * 1024 * 1024 || (!old && this.streams.size >= 64))
+            if (typeof p.run_id !== 'string' || typeof p.stream_id !== 'string' || typeof p.offset_start !== 'number' ||
+                typeof p.offset_end !== 'number' || typeof text !== 'string')
                 continue;
-            const suffix = new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(offset - start));
-            this.streams.set(key, { runId: run, streamId: stream, text: (old?.text ?? '') + suffix, seq: 0, offset: end });
+            this.append(p.run_id, p.stream_id, p.offset_start, p.offset_end, text);
         }
     }
+    /** Returns false only for a malformed patch; gaps and duplicates are handled here. */
     accept(p) {
         if (p.stream_kind !== 'assistant_text')
             return true;
-        const key = JSON.stringify([p.run_id, p.stream_id]);
+        if (p.operation !== 'append' || typeof p.text !== 'string')
+            return false;
+        return this.append(p.run_id, p.stream_id, p.offset_start, p.offset_end, p.text);
+    }
+    values() {
+        return [...this.streams.values()].filter(s => s.text).map(({ runId, streamId, text }) => ({ runId, streamId, text }));
+    }
+    commit(run, stream) {
+        if (typeof run !== 'string' || typeof stream !== 'string')
+            return;
+        const key = JSON.stringify([run, stream]);
+        if (!this.committed.has(key) && this.committed.size >= LIVE_MAX_COMMITTED)
+            throw new Error('Live stream history limit reached; reconnect required');
+        this.streams.delete(key);
+        this.committed.add(key);
+    }
+    append(runId, streamId, start, end, text) {
+        const key = JSON.stringify([runId, streamId]);
         if (this.committed.has(key))
             return true;
-        const old = this.streams.get(key);
-        if (old && p.offset_end <= old.offset)
+        const bytes = utf8Encoder.encode(text);
+        if (!Number.isSafeInteger(start) || start < 0 || end !== start + bytes.length || end > LIVE_MAX_STREAM_BYTES)
+            return false;
+        let stream = this.streams.get(key);
+        if (!stream) {
+            if (this.streams.size >= LIVE_MAX_STREAMS)
+                return false;
+            stream = { runId, streamId, text: '', offset: 0 };
+            this.streams.set(key, stream);
+        }
+        if (end <= stream.offset)
+            return true;
+        if (start > stream.offset) {
+            holdLiveRange(stream, start, bytes);
             return true;
-        if (p.operation !== 'append' || (old?.seq !== 0 && p.live_seq_start !== (old?.seq ?? 0) + 1) ||
-            p.offset_start !== (old?.offset ?? 0) || p.live_seq_end < p.live_seq_start ||
-            p.offset_end !== p.offset_start + new TextEncoder().encode(p.text).length ||
-            p.offset_end > 4 * 1024 * 1024 || (!old && this.streams.size >= 64))
+        }
+        if (!extendLiveStream(stream, bytes.subarray(stream.offset - start)))
             return false;
-        this.streams.set(key, { runId: p.run_id, streamId: p.stream_id, text: (old?.text ?? '') + p.text, seq: p.live_seq_end, offset: p.offset_end });
+        const held = stream.held;
+        if (held && held.start <= stream.offset) {
+            stream.held = undefined;
+            if (held.start + held.bytes.length > stream.offset && !extendLiveStream(stream, held.bytes.subarray(stream.offset - held.start)))
+                return false;
+        }
         return true;
     }
-    values() { return [...this.streams.values()].map(({ runId, streamId, text }) => ({ runId, streamId, text })); }
+}
+function extendLiveStream(stream, suffix) {
+    try {
+        stream.text += utf8Decoder.decode(suffix);
+    }
+    catch {
+        return false;
+    }
+    stream.offset += suffix.length;
+    return true;
+}
+/** Keeps one contiguous range ahead of the prefix; adjoining ranges merge, a later disjoint one replaces it. */
+function holdLiveRange(stream, start, bytes) {
+    const held = stream.held;
+    const end = start + bytes.length;
+    if (held && start <= held.start + held.bytes.length && end >= held.start) {
+        const from = Math.min(start, held.start);
+        const to = Math.max(end, held.start + held.bytes.length);
+        const merged = new Uint8Array(to - from);
+        merged.set(held.bytes, held.start - from);
+        merged.set(bytes, start - from);
+        stream.held = { start: from, bytes: merged };
+        return;
+    }
+    if (!held || end > held.start + held.bytes.length)
+        stream.held = { start, bytes: bytes.slice() };
 }
 export class SwarmRealtimeNamespace {
     transport;
@@ -84,6 +131,24 @@ export class SwarmRealtimeNamespace {
     async hydrate(body, signal) {
         return (await this.transport.request('/v3/sync/hydrate', { method: 'POST', body, signal })).data;
     }
+    /**
+     * Hydrates a watch window. The daemon's default manifest policy ('error') refuses the whole
+     * snapshot when the recent window cannot hold all history (e.g. one ~280 KB tool result
+     * exhausts the 256 KB message budget). Both 'omit' and 'manifest' still return the same
+     * newest window plus an omission with `next_cursor`; 'manifest' also returns a descriptor
+     * of what was included, so it loses the least. The policy then sticks for this watch.
+     */
+    async hydrateWindow(body, signal) {
+        try {
+            return await this.hydrate(body, signal);
+        }
+        catch (error) {
+            if (body.history?.manifest_policy || !isRequiresManifestError(error))
+                throw error;
+            body.history = { ...body.history, manifest_policy: 'manifest' };
+            return this.hydrate(body, signal);
+        }
+    }
     /** Bounded durable replay. Keep the identical selector/resources/surface for every cursor. */
     async replay(body, signal) {
         return (await this.transport.request('/v3/sync/stream', { method: 'POST', body, signal })).data;
@@ -140,16 +205,19 @@ export class SwarmRealtimeNamespace {
         const body = { surface, session_ids: [id], selector: { kind: 'session_ids', session_ids: [id] },
             history: { mode: 'tail', max_messages_per_session: 200, max_events_per_session: 200, include_events: true },
             resources: { messages: true, events: true, current_run_state: true, session_view: true } };
+        // The budget bounds consecutive failures only; every replayed connection restores it.
         let attempts = 0;
+        let latest;
+        const onChange = (state) => { latest = state; options.onChange(state); };
         while (!signal.aborted) {
             // Every reconnect hydrates fresh durable authority before replay; no timer polling.
-            const snapshot = await this.hydrate(body, signal);
+            const snapshot = await this.hydrateWindow(body, signal);
             if (signal.aborted)
                 return;
             if (!snapshot.sessions_by_id[id] || !snapshot.realtime?.resume.endpoint_cursor)
                 throw new Error('Session omitted or realtime bootstrap unavailable');
             try {
-                await this.connection(id, body, snapshot, options, signal, ready);
+                await this.connection(id, body, snapshot, latest?.snapshot.events_by_session[id] ?? [], { ...options, onChange }, signal, ready, () => { attempts = 0; });
                 return;
             }
             catch (error) {
@@ -157,12 +225,13 @@ export class SwarmRealtimeNamespace {
                     return;
                 if (error instanceof FatalRealtimeError || attempts >= (options.maxReconnects ?? 6))
                     throw error;
-                options.onChange({ sessionId: id, snapshot, messages: snapshot.messages_by_session[id] ?? [], live: [], status: 'reconnecting' });
+                // Keep the last rendered conversation (including partial text) while reconnecting.
+                onChange({ ...(latest ?? { sessionId: id, snapshot, messages: snapshot.messages_by_session[id] ?? [], live: [], ...historyOmissionState(snapshot, id) }), status: 'reconnecting' });
                 await delay(Math.min(250 * 2 ** attempts++, 8000), signal);
             }
         }
     }
-    async connection(id, body, initial, options, signal, ready) {
+    async connection(id, body, initial, seenEvents, options, signal, ready, onReplayed) {
         const socket = await (options.socketFactory ?? ((path) => this.socket(path)))(`/v3/realtime/stream?${new URLSearchParams({ surface: body.surface })}`);
         if (signal.aborted) {
             socket.close();
@@ -179,13 +248,20 @@ export class SwarmRealtimeNamespace {
             let dirty = false;
             let readyPending = false;
             let lastSeq = snapshot.projections_by_session[id]?.last_event_seq ?? 0;
+            // Durable events delivered on the socket are merged into the hydrated tail, so a
+            // consumer sees every event once and immediately, even before the next hydration.
+            let events = mergeSessionEvents(seenEvents, snapshot.events_by_session[id] ?? []);
             const live = new V3LiveText();
             live.reconcile(snapshot.messages_by_session[id] ?? []);
-            live.durable(snapshot.events_by_session[id] ?? []);
+            live.durable(events);
             const subscription = `sdk:session:${id}`;
             const timer = setTimeout(() => finish(new Error('Realtime handshake timed out')), 30_000);
-            const emit = () => { if (!ended)
-                options.onChange({ sessionId: id, snapshot, messages: snapshot.messages_by_session[id] ?? [], live: live.values(), status: replayed ? 'live' : 'syncing' }); };
+            const emit = () => {
+                if (ended)
+                    return;
+                const view = { ...snapshot, events_by_session: { ...snapshot.events_by_session, [id]: events } };
+                options.onChange({ sessionId: id, snapshot: view, messages: snapshot.messages_by_session[id] ?? [], live: live.values(), status: replayed ? 'live' : 'syncing', ...historyOmissionState(snapshot, id) });
+            };
             const finish = (error) => {
                 if (ended)
                     return;
@@ -208,13 +284,14 @@ export class SwarmRealtimeNamespace {
                 try {
                     while (dirty && !ended) {
                         dirty = false;
-                        const next = await this.hydrate(body, requests.signal);
+                        const next = await this.hydrateWindow(body, requests.signal);
                         if (ended)
                             return;
                         if (!next.sessions_by_id[id])
                             throw new FatalRealtimeError('Session no longer available');
                         snapshot = next;
                         lastSeq = Math.max(lastSeq, next.projections_by_session[id]?.last_event_seq ?? 0);
+                        events = mergeSessionEvents(events, next.events_by_session[id] ?? []);
                         live.reconcile(next.messages_by_session[id] ?? []);
                         live.durable(next.events_by_session[id] ?? []);
                         emit();
@@ -267,6 +344,7 @@ export class SwarmRealtimeNamespace {
                         return;
                     if (frame.kind === 'replay.complete') {
                         replayed = true;
+                        onReplayed();
                         clearTimeout(timer);
                         readyPending = true;
                         void refresh();
@@ -275,7 +353,7 @@ export class SwarmRealtimeNamespace {
                         if (!liveNegotiated || !replayed)
                             return;
                         if (!live.accept(frame.live)) {
-                            finish(new Error('Live stream gap; durable rehydration required'));
+                            finish(new Error('Malformed live patch; durable rehydration required'));
                         }
                         else
                             emit();
@@ -284,9 +362,13 @@ export class SwarmRealtimeNamespace {
                         if (frame.event.seq <= lastSeq)
                             return;
                         lastSeq = frame.event.seq;
+                        events = mergeSessionEvents(events, [frame.event]);
                         live.durable([frame.event]);
                         emit();
-                        void refresh();
+                        // Streaming checkpoints change no hydrated authority (messages, run state,
+                        // permissions); re-hydrating on each one would only add load.
+                        if (!String(frame.event.event_type).endsWith('.delta'))
+                            void refresh();
                     }
                     else if (frame.kind === 'projection.high_watermark') {
                         void refresh();
@@ -299,6 +381,20 @@ export class SwarmRealtimeNamespace {
         });
     }
 }
+const MAX_WATCH_EVENTS = 1000;
+/** Union by durable sequence, ascending, bounded to the newest events. */
+function mergeSessionEvents(current, incoming) {
+    if (!incoming.length)
+        return current;
+    const bySeq = new Map();
+    for (const event of current)
+        bySeq.set(event.seq, event);
+    for (const event of incoming)
+        if (event && Number.isSafeInteger(event.seq) && !bySeq.has(event.seq))
+            bySeq.set(event.seq, event);
+    const merged = [...bySeq.values()].sort((a, b) => a.seq - b.seq);
+    return merged.length > MAX_WATCH_EVENTS ? merged.slice(merged.length - MAX_WATCH_EVENTS) : merged;
+}
 class FatalRealtimeError extends Error {
 }
 function delay(ms, signal) {
@@ -310,3 +406,11 @@ function delay(ms, signal) {
             finish();
     });
 }
+function isRequiresManifestError(error) {
+    return error instanceof SwarmApiError && error.status === 400 && /\brequires_manifest\b/.test(error.message);
+}
+function historyOmissionState(snapshot, id) {
+    const historyOmissions = (Array.isArray(snapshot.omissions) ? snapshot.omissions : [])
+        .filter((o) => o && o.session_id === id && (o.resource === 'messages' || o.resource === 'events'));
+    return { historyOmitted: historyOmissions.length > 0, historyOmissions };
+}

package/dist/remote.d.ts

@@ -0,0 +1,59 @@
+import type { SwarmTransport } from './transport.js';
+/** An AI client's authorization request waiting on this machine's owner. */
+export interface RemoteConsent {
+    code: string;
+    client_id: string;
+    client_name: string;
+    client_domain?: string;
+    redirect_host: string;
+    scopes: string[];
+    expires_at: number;
+}
+/** Relay connection state. Never contains the device key or token. */
+export interface RemoteStatus {
+    configured: boolean;
+    enabled: boolean;
+    connected: boolean;
+    relay_url?: string;
+    device_id?: string;
+    device_name?: string;
+    public_key?: string;
+    allow_write: boolean;
+    allow_approve: boolean;
+    allow_manage: boolean;
+    last_error?: string;
+    pending_consents: RemoteConsent[];
+    /** Set while the relay waits for an authorized client to pair this machine. */
+    pairing_code?: string;
+    pairing_expires_at?: number;
+}
+export interface RemoteInitInput {
+    relay_url: string;
+    device_name: string;
+    allow_write?: boolean;
+    allow_approve?: boolean;
+    allow_manage?: boolean;
+}
+/**
+ * Owner administration of the machine's relay connection (`/v1/remote*`).
+ * The daemon refuses scoped tokens here: call it only from a trusted backend
+ * on the private local transport, never from a browser.
+ */
+export declare class SwarmRemoteNamespace {
+    private readonly transport;
+    constructor(transport: SwarmTransport);
+    private call;
+    status(): Promise<RemoteStatus>;
+    /** Creates this machine's device key for one relay. Does not connect. */
+    init(input: RemoteInitInput): Promise<RemoteStatus>;
+    enable(): Promise<RemoteStatus>;
+    disable(): Promise<RemoteStatus>;
+    /**
+     * Approves or denies an AI client's authorization request shown on the
+     * relay's consent page. Approved scopes are clamped to the request and to
+     * this machine's ceiling by the daemon.
+     */
+    decideConsent(code: string, approve: boolean, scopes?: string[]): Promise<RemoteConsent>;
+    /** Disconnects, revokes the device token and deletes the device key. */
+    reset(): Promise<RemoteStatus>;
+}