@swarm-agent/sdk 0.1.49 → 0.1.50

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>;
+}

package/dist/remote.js

@@ -0,0 +1,46 @@
+/**
+ * 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 class SwarmRemoteNamespace {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async call(path, method, body) {
+        const res = await this.transport.request(`/v1/remote${path}`, { method, ...(method === 'POST' ? { body: body ?? {} } : {}) });
+        return res.data.remote;
+    }
+    status() {
+        return this.call('', 'GET');
+    }
+    /** Creates this machine's device key for one relay. Does not connect. */
+    init(input) {
+        return this.call('/init', 'POST', {
+            relay_url: input.relay_url, device_name: input.device_name,
+            allow_write: input.allow_write === true, allow_approve: input.allow_approve === true, allow_manage: input.allow_manage === true,
+        });
+    }
+    enable() {
+        return this.call('/enable', 'POST');
+    }
+    disable() {
+        return this.call('/disable', 'POST');
+    }
+    /**
+     * 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.
+     */
+    async decideConsent(code, approve, scopes) {
+        const res = await this.transport.request(`/v1/remote/consents/${approve ? 'approve' : 'deny'}`, {
+            method: 'POST', body: approve && scopes ? { code, scopes } : { code },
+        });
+        return res.data.consent;
+    }
+    /** Disconnects, revokes the device token and deletes the device key. */
+    reset() {
+        return this.call('/reset', 'POST');
+    }
+}

package/dist/sessions.d.ts

@@ -35,14 +35,44 @@ export declare class SwarmSessionsNamespace {
      * Deletes a session and triggers cascading cancellation of associated runs and worktrees.
      */
     delete(sessionId: string): Promise<boolean>;
+    /**
+     * Renames a session or project conversation you own (`POST /v3/sessions/{id}/title`).
+     * The title is trimmed and must be 1–200 characters. A renamed conversation keeps its
+     * title: Swarm no longer titles it automatically. (Untitled conversations are named
+     * from their first message.) Retrying with the same `clientRequestId` is idempotent.
+     */
+    rename(sessionId: string, title: string, options?: {
+        clientRequestId?: string;
+    }): Promise<{
+        ok: boolean;
+        session_id: string;
+        title: string;
+    }>;
     /**
      * Appends a message to a session conversation.
      */
     sendMessage(sessionId: string, params: {
         content: string;
-        role?: 'user' | 'assistant' | 'system';
+        role?: 'user';
         client_request_id?: string;
     }): Promise<any>;
+    /**
+     * Starts a fresh model context in the same conversation (`POST /v3/sessions/{id}/context/clear`).
+     * History stays visible and the session ID is unchanged; the next turn starts without the
+     * earlier provider context. The daemon accepts this only for an idle project conversation
+     * without an unresolved plan, and only when `expectedLastEventSeq` equals the session's current
+     * durable sequence (`state.snapshot.projections_by_session[id].last_event_seq`); otherwise it
+     * rejects with `SwarmConflictError` and changes nothing. A standalone chat session cannot be
+     * cleared: create a new session instead. Retrying with the same `clientRequestId` is idempotent.
+     */
+    clearContext(sessionId: string, params: {
+        expectedLastEventSeq: number;
+        clientRequestId?: string;
+    }): Promise<{
+        ok: boolean;
+        session_id: string;
+        mutation: Record<string, unknown>;
+    }>;
     /**
      * Stops an active execution run for a session.
      */

package/dist/sessions.js

@@ -84,10 +84,14 @@ export class SwarmSessionsNamespace {
         const data = res.data;
         if (data && typeof data === 'object') {
             const sessionObj = data.session || data;
+            // V3 sessions carry their source workspace as the primary grant.
+            const primaryGrant = Array.isArray(sessionObj.workspace_grants)
+                ? sessionObj.workspace_grants.find((grant) => grant?.kind === 'primary')
+                : undefined;
             return {
                 id: sessionObj.id || sessionObj.session_id || sessionId,
                 title: sessionObj.title || '',
-                workspace_id: sessionObj.workspace_id,
+                workspace_id: sessionObj.workspace_id || primaryGrant?.workspace_id,
                 workspace_path: sessionObj.workspace_path,
                 state: sessionObj.state || data.projection?.state || 'idle',
                 mode: sessionObj.mode,
@@ -145,6 +149,27 @@ export class SwarmSessionsNamespace {
         });
         return res.data?.ok === true;
     }
+    /**
+     * Renames a session or project conversation you own (`POST /v3/sessions/{id}/title`).
+     * The title is trimmed and must be 1–200 characters. A renamed conversation keeps its
+     * title: Swarm no longer titles it automatically. (Untitled conversations are named
+     * from their first message.) Retrying with the same `clientRequestId` is idempotent.
+     */
+    async rename(sessionId, title, options = {}) {
+        const id = sessionId.trim();
+        if (!id)
+            throw new Error('sessionId is required');
+        const trimmed = typeof title === 'string' ? title.trim() : '';
+        if (!trimmed)
+            throw new Error('title is required');
+        if ([...trimmed].length > 200)
+            throw new Error('title must be 200 characters or fewer');
+        const res = await this.transport.request(`/v3/sessions/${encodeURIComponent(id)}/title`, {
+            method: 'POST',
+            body: { title: trimmed, client_request_id: options.clientRequestId || generateRequestId() },
+        });
+        return res.data;
+    }
     /**
      * Appends a message to a session conversation.
      */
@@ -161,6 +186,29 @@ export class SwarmSessionsNamespace {
         });
         return res.data;
     }
+    /**
+     * Starts a fresh model context in the same conversation (`POST /v3/sessions/{id}/context/clear`).
+     * History stays visible and the session ID is unchanged; the next turn starts without the
+     * earlier provider context. The daemon accepts this only for an idle project conversation
+     * without an unresolved plan, and only when `expectedLastEventSeq` equals the session's current
+     * durable sequence (`state.snapshot.projections_by_session[id].last_event_seq`); otherwise it
+     * rejects with `SwarmConflictError` and changes nothing. A standalone chat session cannot be
+     * cleared: create a new session instead. Retrying with the same `clientRequestId` is idempotent.
+     */
+    async clearContext(sessionId, params) {
+        if (!Number.isSafeInteger(params.expectedLastEventSeq) || params.expectedLastEventSeq < 0) {
+            throw new Error('expectedLastEventSeq must be the current non-negative session event sequence');
+        }
+        const id = encodeURIComponent(sessionId.trim());
+        const res = await this.transport.request(`/v3/sessions/${id}/context/clear`, {
+            method: 'POST',
+            body: {
+                client_request_id: params.clientRequestId || generateRequestId(),
+                expected_last_event_seq: params.expectedLastEventSeq,
+            },
+        });
+        return res.data;
+    }
     /**
      * Stops an active execution run for a session.
      */

package/dist/settings.d.ts

@@ -98,6 +98,9 @@ export declare class SwarmSettingsNamespace {
     /**
      * Restores verified recommended defaults across all system agent and swarm core roles.
      * If expectedUpdatedAt is omitted, automatically reads the current setting's revision first.
+     * An account with no model settings yet (a provider is connected but its
+     * models were never set up) restores from revision 0: the daemon then sets
+     * up the recommended models from a ready provider.
      */
     restoreDefaults(expectedUpdatedAt?: number): Promise<AgentModelSettingsResponse>;
     /**