@deepseek-ai/dsh-api-session-controller 0.1.2-rc.1 → 0.1.5-alpha.1

package/lib/types/index.d.ts

@@ -19,8 +19,6 @@ declare module '@deepseek-ai/cordis' {
 }
 /** Session Controller deployment policy. */
 export interface Config {
-    /** Maximum cold Session artifact size eligible for one full projection observation. */
-    readonly coldBlankProbeMaxBytes?: number;
     /** Override platform desktop-opener detection. */
     readonly nativeOpen?: boolean;
 }
@@ -45,7 +43,8 @@ export declare class SessionController extends TypertRemoteService {
     private readonly promotions;
     /**
      * @param ctx - Host context containing the Session capability assembly.
-     * @param config - cold-list observation policy.
+     * @param config - native-opener deployment policy.
+     * @param internals - host integrations replaceable by direct unit tests.
      */
     constructor(ctx: Context, config: Config, internals?: SessionControllerInternals);
     private promote;
@@ -154,7 +153,8 @@ export declare class SessionController extends TypertRemoteService {
      * Follow one Session log from its opening or resume cursor.
      * @param request - durable address and last committed sequence already held by the caller.
      * @param signal - cancellation owned by the Remote stream carrier.
-     * @returns a complete opening snapshot followed by gap-free event frames.
+     * @returns a complete opening snapshot followed by gap-free durable event
+     *   frames and optional cursorless assistant-stream frames.
      */
     follow(request: SessionFollowRequest, signal: AbortSignal): AsyncIterable<SessionFollowFrame>;
     /**

package/lib/types/index.js

@@ -94,10 +94,11 @@ import { SessionCommandController } from "./commands.js";
 import { SessionControlController } from "./control.js";
 import { SessionHistoryController } from "./history.js";
 import { SessionFileReferences } from "./file-references.js";
-import { ApiSessionList, DEFAULT_COLD_BLANK_PROBE_MAX_BYTES } from "./list.js";
+import { ApiSessionList } from "./list.js";
 import { buildModelCatalog } from "./catalog.js";
 import { installModelSelectionProjection } from "./model-selection-projection.js";
 import { SessionSkillCatalog } from "./skill-catalog.js";
+import { SessionMediaReferences } from "./media-references.js";
 export { ApiSessionNotFound } from "./agent.js";
 export { SessionFileReferences } from "./file-references.js";
 export { SessionSkillCatalog } from "./skill-catalog.js";
@@ -162,6 +163,7 @@ let SessionController = (() => {
             'agentDefaultModel',
             'agents',
             'attachments',
+            'fileUploads',
             'llm',
             'sessions',
             'sessionProjections',
@@ -170,7 +172,6 @@ let SessionController = (() => {
             'workspaceRegistry',
         ];
         static Config = z.object({
-            coldBlankProbeMaxBytes: z.natural().default(DEFAULT_COLD_BLANK_PROBE_MAX_BYTES),
             nativeOpen: z.boolean(),
         });
         agents = __runInitializers(this, _instanceExtraInitializers);
@@ -183,13 +184,20 @@ let SessionController = (() => {
         promotions = new Set();
         /**
          * @param ctx - Host context containing the Session capability assembly.
-         * @param config - cold-list observation policy.
+         * @param config - native-opener deployment policy.
+         * @param internals - host integrations replaceable by direct unit tests.
          */
         constructor(ctx, config, internals = {}) {
             super(ctx, 'sessionController', { namespace: 'session' });
             installModelSelectionProjection(ctx);
             this.agents = new ApiSessionAgentController(ctx);
             this.commands = new SessionCommandController(ctx, this.agents, process.cwd());
+            ctx.effect(() => ctx.fileUploads.registerAgentResolver(async (sessionId) => {
+                const result = await this.agents.resolveAgent(sessionId);
+                if ('error' in result)
+                    throw result.error;
+                return result.agent;
+            }), 'session-controller: file-upload Agent resolver');
             this.controlState = new SessionControlController(ctx);
             // Registered before history so reverse-order teardown closes every
             // follower before waiting for already-admitted promotions.
@@ -197,11 +205,12 @@ let SessionController = (() => {
                 await Promise.allSettled([...this.promotions]);
             }, 'session-controller.promotions');
             this.history = new SessionHistoryController(ctx, (observation) => { this.promote(observation); });
-            this.listState = new ApiSessionList(ctx, config.coldBlankProbeMaxBytes ?? DEFAULT_COLD_BLANK_PROBE_MAX_BYTES);
+            this.listState = new ApiSessionList(ctx);
             this.openPath = internals.openPath ?? openNativePath;
             this.canOpenPath = internals.canOpenPath
                 ?? (() => config.nativeOpen ?? (internals.openPath !== undefined || canOpenNativePath()));
             ctx.plugin(SessionFileReferences);
+            ctx.plugin(SessionMediaReferences);
             ctx.plugin(SessionSkillCatalog);
             ctx.on('session/created', (session) => {
                 ctx.emit('api-session/added', this.listState.summaryFor(session));
@@ -407,7 +416,8 @@ let SessionController = (() => {
          * Follow one Session log from its opening or resume cursor.
          * @param request - durable address and last committed sequence already held by the caller.
          * @param signal - cancellation owned by the Remote stream carrier.
-         * @returns a complete opening snapshot followed by gap-free event frames.
+         * @returns a complete opening snapshot followed by gap-free durable event
+         *   frames and optional cursorless assistant-stream frames.
          */
         follow(request, signal) {
             return this.history.follow(request, signal);

package/lib/types/list.d.ts

@@ -2,8 +2,6 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { Session, SessionEvent } from '@deepseek-ai/dsh-session';
 import type { SessionListMetadata, SessionSearchValue, SessionSummary } from './types.ts';
-/** Default maximum artifact size eligible for one cold projection observation. */
-export declare const DEFAULT_COLD_BLANK_PROBE_MAX_BYTES = 1024;
 /**
  * Advance the Session-list metadata projection by one committed event.
  * @param state - metadata before the event.
@@ -21,12 +19,8 @@ export declare function truncateUnicodeCodePoints(value: string, maximum: number
 /** Owns list projection registration, bounded cold summaries, and authorized search. */
 export declare class ApiSessionList {
     private readonly ctx;
-    private readonly coldBlankProbeMaxBytes;
-    /**
-     * @param ctx - Host context carrying Session, query, persistence, and projection services.
-     * @param coldBlankProbeMaxBytes - maximum physical artifact size eligible for a full observation.
-     */
-    constructor(ctx: Context, coldBlankProbeMaxBytes: number);
+    /** @param ctx - Host context carrying Session, query, persistence, and projection services. */
+    constructor(ctx: Context);
     /**
      * Build one current attached-Session summary.
      * @param session - attached Session to summarize.
@@ -40,7 +34,6 @@ export declare class ApiSessionList {
      */
     list(signal?: AbortSignal): Promise<SessionSummary[]>;
     private summarizeCold;
-    private probeSmallCold;
     /**
      * Search current visible message content without activating any matching Session.
      * @param query - literal message-content query.

package/lib/types/list.js

@@ -1,65 +1,9 @@
 /** Cold-safe Session list and search projection. */
-var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
-    if (value !== null && value !== void 0) {
-        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
-        var dispose, inner;
-        if (async) {
-            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
-            dispose = value[Symbol.asyncDispose];
-        }
-        if (dispose === void 0) {
-            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
-            dispose = value[Symbol.dispose];
-            if (async) inner = dispose;
-        }
-        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
-        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
-        env.stack.push({ value: value, dispose: dispose, async: async });
-    }
-    else if (async) {
-        env.stack.push({ async: true });
-    }
-    return value;
-};
-var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
-    return function (env) {
-        function fail(e) {
-            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
-            env.hasError = true;
-        }
-        var r, s = 0;
-        function next() {
-            while (r = env.stack.pop()) {
-                try {
-                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
-                    if (r.dispose) {
-                        var result = r.dispose.call(r.value);
-                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
-                    }
-                    else s |= 1;
-                }
-                catch (e) {
-                    fail(e);
-                }
-            }
-            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
-            if (env.hasError) throw env.error;
-        }
-        return next();
-    };
-})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
-    var e = new Error(message);
-    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
-});
-import { stat } from 'node:fs/promises';
 import { SessionLogOffset } from '@deepseek-ai/dsh-session';
 import { SessionQueryError } from '@deepseek-ai/dsh-session-query';
 import { RemoteError } from '@deepseek-ai/dsh-typert-protocol';
 import { z } from 'zod';
 import { SESSION_SEARCH_RESULT_LIMIT, SESSION_SEARCH_SNIPPET_MAX_CODE_POINTS, } from "./types.js";
-/** Default maximum artifact size eligible for one cold projection observation. */
-export const DEFAULT_COLD_BLANK_PROBE_MAX_BYTES = 1024;
-const COLD_SUMMARY_BATCH_SIZE = 16;
 const SEARCH_PROVIDER_CALL_LIMIT = 100;
 const SESSION_SEARCH_QUERY_MAX_CHARS = 500;
 const MESSAGE_TYPES = new Set(['user/message', 'assistant/message']);
@@ -110,14 +54,9 @@ export function truncateUnicodeCodePoints(value, maximum) {
 /** Owns list projection registration, bounded cold summaries, and authorized search. */
 export class ApiSessionList {
     ctx;
-    coldBlankProbeMaxBytes;
-    /**
-     * @param ctx - Host context carrying Session, query, persistence, and projection services.
-     * @param coldBlankProbeMaxBytes - maximum physical artifact size eligible for a full observation.
-     */
-    constructor(ctx, coldBlankProbeMaxBytes) {
+    /** @param ctx - Host context carrying Session, query, persistence, and projection services. */
+    constructor(ctx) {
         this.ctx = ctx;
-        this.coldBlankProbeMaxBytes = coldBlankProbeMaxBytes;
         ctx.sessionProjections.register({
             key: 'sessionListMetadata',
             stateSchema: sessionListMetadataSchema,
@@ -178,79 +117,24 @@ export class ApiSessionList {
                 continue;
             cold.push(record.header);
         }
-        for (let offset = 0; offset < cold.length; offset += COLD_SUMMARY_BATCH_SIZE) {
-            const settled = await Promise.allSettled(cold.slice(offset, offset + COLD_SUMMARY_BATCH_SIZE)
-                .map(header => this.summarizeCold(header, signal)));
-            for (const result of settled) {
-                if (result.status === 'rejected')
-                    throw result.reason;
-                items.push(result.value);
-            }
-        }
+        for (const header of cold)
+            items.push(this.summarizeCold(header));
         items.sort((left, right) => right.updatedAt - left.updatedAt);
         return items;
     }
-    async summarizeCold(header, signal) {
-        const cached = this.projectionsFor(header, undefined);
-        const projections = cached?.values.sessionListMetadata?.blank === false
-            ? cached
-            : await this.probeSmallCold(header, signal) ?? cached;
-        const raced = this.ctx.sessions.get(header.id);
-        if (raced !== undefined)
-            return this.summaryFor(raced);
+    summarizeCold(header) {
+        const projections = this.projectionsFor(header, undefined);
         const metadata = projections?.values.sessionListMetadata;
         return {
             sessionId: header.id,
             updatedAt: updatedAt(header, metadata),
             running: false,
-            // A large or inaccessible cache miss remains unknown and visible.
+            // A large, metadata-less, or inaccessible cache miss remains unknown and visible.
             blank: metadata?.blank ?? false,
             ...listFields(header),
             ...(projections === undefined ? {} : { projections }),
         };
     }
-    async probeSmallCold(header, signal) {
-        if (this.coldBlankProbeMaxBytes === 0)
-            return undefined;
-        const persistence = this.ctx.get('sessionPersistence');
-        const location = persistence?.locate(header);
-        if (location === undefined)
-            return undefined;
-        signal?.throwIfAborted();
-        try {
-            if ((await stat(location.path)).size > this.coldBlankProbeMaxBytes)
-                return undefined;
-        }
-        catch {
-            signal?.throwIfAborted();
-            return undefined;
-        }
-        try {
-            const env_1 = { stack: [], error: void 0, hasError: false };
-            try {
-                const observation = __addDisposableResource(env_1, await this.ctx.sessionQuery.observeSession(header.id, {
-                    ...(signal === undefined ? {} : { signal }),
-                    projectionMode: 'all',
-                }), false);
-                const block = observation.projections;
-                return block === undefined
-                    ? undefined
-                    : { asOfSeq: block.asOfSeq, values: block.values };
-            }
-            catch (e_1) {
-                env_1.error = e_1;
-                env_1.hasError = true;
-            }
-            finally {
-                __disposeResources(env_1);
-            }
-        }
-        catch (error) {
-            signal?.throwIfAborted();
-            this.ctx.logger.warn(`api-session.list: small cold observation for "${header.id}" failed; serving it as visible: ${String(error)}`);
-            return undefined;
-        }
-    }
     /**
      * Search current visible message content without activating any matching Session.
      * @param query - literal message-content query.
@@ -362,10 +246,12 @@ export class ApiSessionList {
     }
     projectionsFor(header, session) {
         try {
+            const cache = this.ctx.get('sessionProjectionCache');
             const block = session === undefined
                 ? header.isSeeded
                     ? undefined
-                    : this.ctx.get('sessionProjectionCache')?.cachedSnapshot(header, SessionLogOffset(0))
+                    : cache?.cachedSnapshot(header, SessionLogOffset(0))
+                        ?? cache?.cachedPredecessorTitle(header, SessionLogOffset(0))
                 : this.ctx.sessionProjections.cachedSnapshot(session);
             return block !== undefined && Object.keys(block.values).length > 0
                 ? {

package/lib/types/media-references.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Authenticated GET/HEAD /api/file reads bounded file responses through
+ * the composed filesystem provider. Paths and MIME types do not restrict access;
+ * the connection service authenticates requests before this handler.
+ * @module @deepseek-ai/dsh-api-session-controller/media-references
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/**
+ * File-display contribution. The connection service supplies authentication;
+ * `ctx.fs` supplies the execution world's paths, reads, and access policy.
+ */
+export declare const SessionMediaReferences: {
+    inject: string[];
+    apply(ctx: Context): void;
+};
+//# sourceMappingURL=media-references.d.ts.map

package/lib/types/media-references.js

@@ -0,0 +1,77 @@
+/**
+ * Authenticated GET/HEAD /api/file reads bounded file responses through
+ * the composed filesystem provider. Paths and MIME types do not restrict access;
+ * the connection service authenticates requests before this handler.
+ * @module @deepseek-ai/dsh-api-session-controller/media-references
+ */
+import { isAbsolute } from 'node:path';
+import { FsError } from '@deepseek-ai/dsh-fs';
+import mime from 'mime-types';
+const BASE_HEADERS = {
+    'Cache-Control': 'private, no-store',
+    'X-Content-Type-Options': 'nosniff',
+    // HTML and SVG files may be opened directly on the authenticated API origin.
+    'Content-Security-Policy': "sandbox; default-src 'none'",
+};
+async function serveFile(request, fs, maxBytes) {
+    const fail = (status, text) => new Response(request.method === 'HEAD' ? null : text, { status, headers: BASE_HEADERS });
+    const path = new URL(request.url).searchParams.get('path');
+    if (path === null || path.length === 0)
+        return fail(400, 'missing path');
+    if (path.includes('\0') || !isAbsolute(path))
+        return fail(400, 'absolute path required');
+    try {
+        const target = await fs.resolve(path, { signal: request.signal });
+        const mediaType = mime.lookup(target.displayPath) || 'application/octet-stream';
+        const headers = {
+            ...BASE_HEADERS,
+            'Content-Type': mediaType,
+        };
+        if (request.method === 'HEAD') {
+            const info = await fs.stat(target, request.signal);
+            if (info === undefined)
+                return fail(404, 'not found');
+            if (info.type !== 'file')
+                return fail(403, 'not a regular file');
+            if (info.size !== undefined) {
+                if (info.size > maxBytes)
+                    return fail(413, 'file exceeds byte limit');
+                headers['Content-Length'] = String(info.size);
+            }
+            return new Response(null, { headers });
+        }
+        const bytes = await fs.readBytes(target, request.signal, maxBytes);
+        headers['Content-Length'] = String(bytes.byteLength);
+        return new Response(bytes.slice(), { headers });
+    }
+    catch (error) {
+        if (!(error instanceof FsError))
+            throw error;
+        const statuses = {
+            FS_NOT_FOUND: 404,
+            FS_NOT_REGULAR_FILE: 403,
+            FS_PERMISSION_DENIED: 403,
+            FS_SANDBOX_DENIED: 403,
+            FS_TOO_LARGE: 413,
+            FS_ABORTED: 499,
+        };
+        return fail(statuses[error.code] ?? 500, error.code);
+    }
+}
+/**
+ * File-display contribution. The connection service supplies authentication;
+ * `ctx.fs` supplies the execution world's paths, reads, and access policy.
+ */
+export const SessionMediaReferences = {
+    inject: ['connection', 'fs', 'attachments'],
+    apply(ctx) {
+        const maxBytes = ctx.attachments.imageLimits.maxImageBytes;
+        ctx.effect(() => ctx.connection.fetch.register({
+            path: '/api/file',
+            methods: ['GET', 'HEAD'],
+            requestBody: 'buffered',
+            fetch: request => serveFile(request, ctx.fs, maxBytes),
+        }), 'session-controller: /api/file');
+    },
+};
+//# sourceMappingURL=media-references.js.map

package/lib/types/types.d.ts

@@ -1,10 +1,9 @@
 /** Browser-safe request, result, and lifecycle vocabulary for the Session Remote service. */
 import type { AttachmentIdType, ImageAttachmentLimits, ImageAttachmentRef, ImageMediaType } from '@deepseek-ai/dsh-attachment';
 import type { Branded } from '@deepseek-ai/dsh-brand';
-import type { MessageId } from '@deepseek-ai/dsh-llm/brand';
-import type { ContentBlock } from '@deepseek-ai/dsh-llm/types';
-import type { ChunkRow } from '@deepseek-ai/dsh-session/chunk-rows';
-import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { LlmAttemptId, MessageId } from '@deepseek-ai/dsh-llm/brand';
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { SessionId, SessionSeqCursor } from '@deepseek-ai/dsh-session/types';
 import type { SessionProjectionMap } from '@deepseek-ai/dsh-session-projection/types';
 import type { JobId } from '@deepseek-ai/dsh-jobs/brand';
 import type { JsonValue } from '@deepseek-ai/dsh-util-values';
@@ -57,7 +56,11 @@ export interface SessionProjectionBaseline {
 }
 /** Typed known projections plus JSON-safe values contributed outside this compilation face. */
 export type SessionProjectionValues = Partial<SessionProjectionMap> & Readonly<Record<string, SessionProjectionValue>>;
-/** Browser-submitted prompt content; the Host promotes image bytes to durable references. */
+/**
+ * Browser-submitted prompt content; the Host promotes image bytes to durable
+ * references. File parts carry the opaque receipt returned by a preceding
+ * `uploadFile` call on the same Session.
+ */
 export type PromptContentPart = {
     readonly type: 'text';
     readonly text: string;
@@ -66,6 +69,9 @@ export type PromptContentPart = {
     readonly mediaType: ImageMediaType;
     readonly data: string;
     readonly name?: string;
+} | {
+    readonly type: 'file';
+    readonly receiptId: Branded<'file-upload-receipt-id'>;
 };
 /** Complete model selection for one Session. */
 export interface ModelSelection {
@@ -128,6 +134,7 @@ export interface ModelCatalog {
 /** One client-requested mutation of a still-pending queue item. */
 export type QueueAction = {
     readonly kind: 'edit';
+    /** Non-empty text-only replacement content. */
     readonly content: readonly ContentBlock[];
 } | {
     readonly kind: 'remove';
@@ -287,6 +294,7 @@ export interface SessionPromptRequest {
     readonly requestId: SessionRequestId;
     readonly sessionId: SessionId;
     readonly mode: 'queue' | 'steer';
+    /** At least one non-whitespace text part or attachment. */
     readonly content: readonly PromptContentPart[];
     readonly clientTimeZone?: string;
 }
@@ -358,52 +366,42 @@ export interface SessionEventEntry {
     readonly type: 'event';
     readonly event: SessionWireEvent;
 }
-/** v0-compatible Session metadata carried on the browser wire. */
+/** Current logical Session metadata carried on the browser wire. */
 export interface SessionWireHeader {
     readonly version: number;
     readonly id: SessionId;
     readonly createdAt: number;
     readonly cwd?: string;
     readonly parentSession?: SessionId;
-    /** Exact inherited prefix length; absent for an unseeded Session. */
-    readonly seedLength?: number;
+    /** Whether the Session contains a fork-inherited prefix. */
+    readonly isSeeded: boolean;
     readonly origin?: 'subagent';
     readonly delegationDepth?: number;
     readonly agentPreset?: string;
 }
-/** Browser wire form of one Session surface operation. */
+/** Browser wire surface operation; replacement endpoints are earlier event seqs in surface order. */
 export type SessionWireSurfaceOp = 'append' | {
     readonly op: 'replace';
-    readonly start: number;
-    readonly end: number;
+    readonly startSeq: number;
+    readonly endSeq: number;
 };
-/** Event-shaped wire representation of one packed chunk row. */
-export type ChunkRowEvent = {
-    [Kind in ChunkRow['type']]: {
-        readonly type: `chunkrow/${Kind}`;
-        readonly seq: number;
-        readonly time: number;
-        readonly data: Extract<ChunkRow, {
-            readonly type: Kind;
-        }>['data'];
-    };
-}[ChunkRow['type']];
-/** One lossless run of consecutive Assistant delta events in a history page. */
-export interface SessionChunkRun {
-    readonly type: 'chunks';
-    readonly event: ChunkRowEvent;
-}
-/** One history-page record: a raw event or a packed Assistant delta run. */
-export type SessionHistoryRecord = SessionEventEntry | SessionChunkRun;
-/** Session event wire form; durable readers own recognition of merge-extensible event names. */
+/** One history-page record with compact Assistant streams embedded inside events. */
+export type SessionHistoryRecord = SessionEventEntry;
+/**
+ * Exact Session event envelope accepted by the Client journal adapter.
+ * Surface events require surfaceOp; only non-Assistant surface events may cite earlier sources.
+ * Durable readers own recognition of merge-extensible event names.
+ */
 export interface SessionWireEvent {
     readonly type: string;
     readonly seq: number;
     readonly time: number;
     readonly data: JsonValue;
     readonly ignorable?: true;
-    readonly sourceEventSeqs?: number[];
-    readonly surfaceOp?: SessionWireSurfaceOp;
+    /** Earlier sources on current surface events; opaque JSON on unknown ignorable events. */
+    readonly sourceEventSeqs?: JsonValue;
+    /** Canonical placement on current surface events; opaque JSON on unknown ignorable events. */
+    readonly surfaceOp?: JsonValue;
 }
 /** One message-aligned backwards-history request. */
 export interface SessionPageRequest {
@@ -417,13 +415,61 @@ export interface SessionPageRequest {
 export interface SessionFollowRequest {
     readonly address: SessionAddress;
     readonly maxMessages?: number;
-}
+    /** Include process-local assistant presentation frames for the Web client. */
+    readonly assistantStream?: true;
+}
+/** One active assistant attempt in a reconnect opening snapshot. */
+export interface SessionAssistantStreamAttempt {
+    readonly attemptId: LlmAttemptId;
+    /** Last durable Session seq observed when this attempt started. */
+    readonly startedAfterSeq: SessionSeqCursor;
+    readonly turn: number;
+    readonly step: number;
+    /** Dense position expected for the next live chunk frame. */
+    readonly nextIndex: number;
+    /** Compact detached stream accumulated at this opening revision. */
+    readonly stream: readonly JsonValue[];
+}
+/** Complete process-local assistant state at one follow opening. */
+export interface SessionAssistantStreamBaseline {
+    readonly revision: number;
+    readonly activeAttempt?: SessionAssistantStreamAttempt;
+}
+/** Browser wire form of one process-local assistant frame. */
+export type SessionAssistantStreamFrame = {
+    readonly type: 'start';
+    readonly attemptId: LlmAttemptId;
+    readonly revision: number;
+    readonly startedAfterSeq: SessionSeqCursor;
+    readonly turn: number;
+    readonly step: number;
+} | {
+    readonly type: 'chunk';
+    readonly attemptId: LlmAttemptId;
+    readonly revision: number;
+    readonly index: number;
+    readonly time: number;
+    readonly chunk: JsonValue;
+} | {
+    readonly type: 'end';
+    readonly attemptId: LlmAttemptId;
+    readonly revision: number;
+    /** Number of chunk frames represented by this terminal marker. */
+    readonly index: number;
+    readonly outcome: {
+        readonly kind: 'committed';
+        readonly eventType: 'assistant/message' | 'assistant/attempt';
+        readonly seq: number;
+    } | {
+        readonly kind: 'abandoned';
+    };
+};
 /** One contiguous backwards page of a Session log. */
 export interface SessionPage {
     readonly records: readonly SessionHistoryRecord[];
     readonly hasMore: boolean;
 }
-/** Complete opening window followed by ordered events appended after its cursor. */
+/** Complete opening window followed by ordered durable events and opted-in assistant frames. */
 export type SessionFollowFrame = {
     readonly type: 'snapshot';
     readonly header: SessionWireHeader;
@@ -431,7 +477,11 @@ export type SessionFollowFrame = {
     readonly records: readonly SessionHistoryRecord[];
     readonly hasMore: boolean;
     readonly projections: SessionProjectionBaseline;
-} | SessionEventEntry;
+    readonly assistantStream?: SessionAssistantStreamBaseline;
+} | SessionEventEntry | {
+    readonly type: 'assistant-stream';
+    readonly frame: SessionAssistantStreamFrame;
+};
 /** One pending inbox occurrence in the authoritative queue snapshot. */
 export interface SessionQueuedItem {
     readonly id: MessageId;