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

package/lib/client.js

@@ -47,7 +47,7 @@ window.__ModuleLoader__.load({
 		}
 		/**
 		* Read the first logical sequence represented by one wire record.
-		* @param record - validated scalar event or packed Assistant delta run.
+		* @param record - validated Session event.
 		* @returns inclusive first Session sequence.
 		*/
 		function historyRecordFirstSeq(record) {
@@ -55,13 +55,254 @@ window.__ModuleLoader__.load({
 		}
 		/**
 		* Read the final logical sequence represented by one wire record.
-		* @param record - validated scalar event or packed Assistant delta run.
+		* @param record - validated Session event.
 		* @returns inclusive final Session sequence.
 		*/
 		function historyRecordLastSeq(record) {
-			if (record.type === "event") return record.event.seq;
-			const length = record.event.type === "chunkrow/tool-call-chunks" ? record.event.data.args.length : record.event.data.texts.length;
-			return record.event.seq + length - 1;
+			return record.event.seq;
+		}
+		//#endregion
+		//#region ../../util/brand/lib/index.js
+		/**
+		* Apply a compile-time number brand without changing the value.
+		* @param value - number admitted by the domain that owns the target brand.
+		* @returns the same number with the requested compile-time brand.
+		*/
+		function brandNumber(value) {
+			return value;
+		}
+		//#endregion
+		//#region ../../core/session/lib/types/types.js
+		/**
+		* Admit a numeric value as an existing Session event position.
+		* @param value - non-negative safe integer admitted by the owning log operation.
+		* @returns the same number with the Session-sequence brand.
+		*/
+		function SessionSeq(value) {
+			if (!Number.isSafeInteger(value) || value < 0 || Object.is(value, -0)) throw new TypeError(`SessionSeq must be a non-negative safe integer, got ${String(value)}`);
+			return brandNumber(value);
+		}
+		/**
+		* Admit a numeric value as a Session log offset.
+		* @param value - non-negative safe integer used as a gap or prefix length.
+		* @returns the same number with the Session-log-offset brand.
+		*/
+		function SessionLogOffset(value) {
+			if (!Number.isSafeInteger(value) || value < 0 || Object.is(value, -0)) throw new TypeError(`SessionLogOffset must be a non-negative safe integer, got ${String(value)}`);
+			return brandNumber(value);
+		}
+		//#endregion
+		//#region ../../core/session/lib/types/known-event-types.js
+		/**
+		* GENERATED by `scripts/gen-persistence-catalog.ts` — do not edit by hand; run
+		* `pnpm run gen-persistence-catalog` to regenerate (verified fresh by
+		* `pnpm run verify-persistence-catalog`, part of `doc-sync`).
+		* @module @deepseek-ai/dsh-session/known-event-types
+		*/
+		/**
+		* Every `SessionEventMap` member declared in this repository — the event
+		* vocabulary this build understands. The persistence read path refuses to
+		* interpret a log containing a type outside this set unless the event
+		* carries the envelope's `ignorable` marker (see `SessionEvent.ignorable`
+		* in `./types.ts`): such a log was likely written by a newer harness, and
+		* silently skipping a required event would reconstruct a wrong session.
+		* Downstream (out-of-repo) plugin events are outside this list by
+		* construction. The persisted `SessionEvent.ignorable` marker is the
+		* compatibility mechanism; event-name registration was rejected because
+		* it does not classify omission safety and would make reads
+		* composition-dependent. The rationale is in
+		* `.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.md`.
+		*/
+		const KNOWN_SESSION_EVENT_TYPES = new Set([
+			"agent-preset/selected",
+			"agent/inbox/spliced",
+			"approval/asked",
+			"approval/decided",
+			"approval/policy",
+			"assistant/attempt",
+			"assistant/message",
+			"command/done",
+			"command/run",
+			"compaction/end",
+			"compaction/prune",
+			"compaction/start",
+			"compaction/summary",
+			"feedback/message-delete",
+			"feedback/message-put",
+			"feedback/record",
+			"goal/change",
+			"hook/invoked",
+			"hook/result",
+			"llm/retry",
+			"llm/retry-started",
+			"model/selection",
+			"permission/preset",
+			"plan/mode",
+			"request/context",
+			"request/header",
+			"sandbox/mode",
+			"schedule/change",
+			"session-log-deepseek/delivery-accepted",
+			"session/end-seed",
+			"session/title",
+			"session/title-llm-request",
+			"step/end",
+			"step/start",
+			"subagent/descriptor",
+			"subagent/model-selection-policy",
+			"system/message",
+			"team/member",
+			"team/message/delivered",
+			"team/message/queued",
+			"team/task",
+			"todo/write",
+			"tool-workflow/agent-end",
+			"tool-workflow/agent-start",
+			"tool-workflow/run-end",
+			"tool-workflow/run-start",
+			"tool/call",
+			"tool/ptc-dispatch",
+			"tool/ptc-dispatch-start",
+			"tool/result",
+			"turn/end",
+			"turn/start",
+			"user/message",
+			"web/deepseek-search-llm-request"
+		]);
+		//#endregion
+		//#region ../../core/session/lib/types/surface.js
+		/** Runtime counterpart of the message-producing event union. */
+		const SURFACE_EVENT_TYPES = new Set([
+			"system/message",
+			"user/message",
+			"assistant/message",
+			"tool/result"
+		]);
+		/**
+		* Whether an event type can join the model-visible surface.
+		* @param type - event type to test.
+		* @returns true for one of the four message-producing event types.
+		*/
+		function isSurfaceEligibleType(type) {
+			return SURFACE_EVENT_TYPES.has(type);
+		}
+		/** Whether a payload field is a JSON object rather than an array or scalar. */
+		function isRecord(value) {
+			return typeof value === "object" && value !== null && !Array.isArray(value);
+		}
+		/**
+		* Reject noncanonical request-header fields and contradictory tool failure metadata.
+		* This does not validate complete event payloads or embedded provider streams.
+		* @param event - event whose locally related payload fields are inspected.
+		* @param subject - event location to include in validation errors.
+		* @throws when request data/header is not an object, optional header fields are empty, or tool failure metadata contradicts its message.
+		*/
+		function validateSessionEventData(event, subject) {
+			const data = event.data;
+			if (event.type === "request/header") {
+				if (!isRecord(data)) throw new Error(`${subject} data must be an object`);
+				const header = data["header"];
+				if (!isRecord(header)) throw new Error(`${subject} header must be an object`);
+				if (Object.hasOwn(header, "system")) throw new Error(`${subject} must omit header.system; use system/message`);
+				if (Array.isArray(header["tools"]) && header["tools"].length === 0) throw new Error(`${subject} must omit empty tools`);
+				const defaults = header["adapterDefaults"];
+				if (isRecord(defaults) && Object.keys(defaults).length === 0) throw new Error(`${subject} must omit empty adapterDefaults`);
+			} else if (event.type === "tool/result") {
+				if (!isRecord(data)) throw new Error(`${subject} data must be an object`);
+				if (data["error"] === void 0) return;
+				const message = data["message"];
+				const content = isRecord(message) ? message["content"] : void 0;
+				const block = Array.isArray(content) ? content[0] : void 0;
+				if (!isRecord(block) || block["isError"] !== true) throw new Error(`${subject} error requires message content[0].isError === true`);
+			}
+		}
+		/** Whether a runtime value is a non-negative safe event sequence. */
+		function isEventSeq(value) {
+			return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && !Object.is(value, -0);
+		}
+		/** Whether a runtime value is the exact positional-replacement shape. */
+		function isReplaceOp(value) {
+			const op = value;
+			return Object.keys(op).length === 3 && Object.hasOwn(op, "op") && Object.hasOwn(op, "startSeq") && Object.hasOwn(op, "endSeq") && op["op"] === "replace" && isEventSeq(op["startSeq"]) && isEventSeq(op["endSeq"]);
+		}
+		/** Validate event-local surface eligibility and return its operation. */
+		function surfaceOpOf(event) {
+			const raw = event;
+			if (!isSurfaceEligibleType(event.type)) {
+				if (!KNOWN_SESSION_EVENT_TYPES.has(event.type) && event.ignorable === true) return;
+				if (raw.surfaceOp !== void 0) throw new Error(`session event "${event.type}" is not surface-eligible and cannot carry surfaceOp`);
+				if (raw.sourceEventSeqs !== void 0) throw new Error(`session event "${event.type}" is not surface-eligible and cannot carry sourceEventSeqs`);
+				return;
+			}
+			const op = raw.surfaceOp;
+			if (op === void 0) throw new Error(`session event "${event.type}" is surface-eligible and requires a surfaceOp marker`);
+			if (op === "append") return op;
+			if (op === null || typeof op !== "object" || Array.isArray(op)) throw new Error(`session event "${event.type}" carries an invalid surfaceOp`);
+			if (!isReplaceOp(op)) throw new Error(`session event "${event.type}" carries an invalid replace surfaceOp`);
+			return op;
+		}
+		/** Validate cited source-event seqs against prior log entries and the replacement range. */
+		function assertProvenance(event, shadowedSeqs) {
+			const raw = event.sourceEventSeqs;
+			if (event.type === "assistant/message" && raw !== void 0) throw new Error("assistant/message embeds its source stream and cannot carry sourceEventSeqs");
+			const sources = /* @__PURE__ */ new Set();
+			if (raw !== void 0) {
+				if (!Array.isArray(raw)) throw new Error(`sourceEventSeqs on event at seq ${event.seq} must be an array when present`);
+				if (raw.length === 0) throw new Error("sourceEventSeqs must not be empty");
+				let nonEarlierSource;
+				for (const source of raw) {
+					if (!isEventSeq(source)) throw new Error(`session event "${event.type}" sourceEventSeqs must densely contain non-negative safe integers`);
+					sources.add(source);
+					if (nonEarlierSource === void 0 && source >= event.seq) nonEarlierSource = source;
+				}
+				if (sources.size !== raw.length) throw new Error("sourceEventSeqs must not contain duplicates");
+				if (nonEarlierSource !== void 0) throw new Error(`sourceEventSeqs must reference earlier events: ${nonEarlierSource} >= current seq ${event.seq}`);
+			}
+			const missing = shadowedSeqs.filter((seq) => !sources.has(seq));
+			if (missing.length > 0) throw new Error(`surface replace: sourceEventSeqs must include every shadowed surface node; missing ${missing.join(", ")}`);
+		}
+		/**
+		* Validate one event's surface metadata without checking membership in a log or surface.
+		* @param event - event whose marker and source sequence values are inspected.
+		* Unknown ignorable records retain opaque metadata and never change the surface.
+		* @returns the validated operation, or undefined for a log-only or unknown ignorable event.
+		* @throws when metadata violates event-local eligibility, marker, or source-sequence rules.
+		*/
+		function validateSurfaceMetadata(event) {
+			const op = surfaceOpOf(event);
+			if (op !== void 0 && op !== "append" && (op.startSeq >= event.seq || op.endSeq >= event.seq)) throw new Error(`surface replace at seq ${event.seq}: startSeq and endSeq must reference earlier events`);
+			if (op !== void 0) assertProvenance(event, []);
+			return op;
+		}
+		//#endregion
+		//#region lib/types/client/session-wire-event.js
+		/** Event-local acceptance for raw Session journal responses; payloads remain owner-defined JSON. */
+		/**
+		* Reject non-current event envelopes without stripping or normalizing wire fields.
+		* Range membership and source existence require the durable log and remain Host-owned.
+		* @param value - one event received in a follow frame or history page.
+		* @returns nothing after narrowing the accepted event envelope.
+		* @throws when the envelope or current event-local metadata is invalid.
+		*/
+		function assertSessionWireEvent(value) {
+			const subject = "session wire event";
+			if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error(`${subject} must be an object`);
+			const event = value;
+			for (const key of Object.keys(event)) switch (key) {
+				case "type":
+				case "seq":
+				case "time":
+				case "data":
+				case "ignorable":
+				case "surfaceOp":
+				case "sourceEventSeqs": break;
+				default: throw new Error(`${subject} has unexpected field ${key}`);
+			}
+			const seq = event["seq"];
+			if (typeof event["type"] !== "string" || typeof seq !== "number" || !Number.isSafeInteger(seq) || seq < 0 || Object.is(seq, -0) || typeof event["time"] !== "number" || !Number.isSafeInteger(event["time"]) || !Object.hasOwn(event, "data") || event["data"] === void 0 || Object.hasOwn(event, "ignorable") && event["ignorable"] !== true) throw new Error(`${subject} has an invalid envelope`);
+			const current = event;
+			validateSurfaceMetadata(current);
+			validateSessionEventData(current, subject);
 		}
 		//#endregion
 		//#region lib/types/types.js
@@ -80,12 +321,14 @@ window.__ModuleLoader__.load({
 					...change,
 					entries: historyEntries(change.entries)
 				};
-				case "append":
-					if (change.entry.type !== "event") throw new RemoteError("gateway/internal", "session live stream emitted a packed history record", {});
-					return {
-						type: "append",
-						entry: change.entry
-					};
+				case "append": return {
+					type: "append",
+					entry: change.entry
+				};
+				case "notification": return {
+					type: "assistant-stream",
+					frame: change.notification
+				};
 			}
 		}
 		/**
@@ -138,22 +381,39 @@ window.__ModuleLoader__.load({
 			}
 			/** @inheritdoc */
 			async *follow(request, signal) {
+				let assistantRevision;
 				for await (const frame of this.remote.session.follow({
 					address: this.address,
+					assistantStream: true,
 					...request.maxMessages === void 0 ? {} : { maxMessages: request.maxMessages }
 				}, signal)) {
 					if (frame.type === "snapshot") {
+						for (const record of frame.records) assertSessionWireEvent(record.event);
+						if (frame.assistantStream === void 0) throw new RemoteError("gateway/internal", "session assistant stream omitted its opted-in opening baseline", {});
+						assistantRevision = frame.assistantStream.revision;
 						yield {
 							type: "opened",
 							cursor: frame.cursor,
 							page: {
 								records: frame.records,
 								hasMore: frame.hasMore,
-								projections: frame.projections
+								projections: frame.projections,
+								assistantStream: frame.assistantStream
 							}
 						};
 						continue;
 					}
+					if (frame.type === "assistant-stream") {
+						const expected = (assistantRevision ?? 0) + 1;
+						if (frame.frame.revision !== expected) throw new _deepseek_ai_dsh_api_gateway_client.RemoteStreamCarrierError(`session assistant stream skipped revision ${String(expected)}`);
+						assistantRevision = frame.frame.revision;
+						yield {
+							type: "notification",
+							notification: frame.frame
+						};
+						continue;
+					}
+					assertSessionWireEvent(frame.event);
 					yield {
 						type: "entry",
 						entry: frame
@@ -168,6 +428,7 @@ window.__ModuleLoader__.load({
 					...request
 				}, signal);
 				if (!result.ok) throw result.error;
+				for (const record of result.value.records) assertSessionWireEvent(record.event);
 				return result.value;
 			}
 			/** @inheritdoc */
@@ -176,36 +437,6 @@ window.__ModuleLoader__.load({
 			}
 		};
 		//#endregion
-		//#region ../../util/brand/lib/index.js
-		/**
-		* Apply a compile-time number brand without changing the value.
-		* @param value - number admitted by the domain that owns the target brand.
-		* @returns the same number with the requested compile-time brand.
-		*/
-		function brandNumber(value) {
-			return value;
-		}
-		//#endregion
-		//#region ../../core/session/lib/types/types.js
-		/**
-		* Admit a numeric value as an existing Session event position.
-		* @param value - non-negative safe integer admitted by the owning log operation.
-		* @returns the same number with the Session-sequence brand.
-		*/
-		function SessionSeq(value) {
-			if (!Number.isSafeInteger(value) || value < 0 || Object.is(value, -0)) throw new TypeError(`SessionSeq must be a non-negative safe integer, got ${String(value)}`);
-			return brandNumber(value);
-		}
-		/**
-		* Admit a numeric value as a Session log offset.
-		* @param value - non-negative safe integer used as a gap or prefix length.
-		* @returns the same number with the Session-log-offset brand.
-		*/
-		function SessionLogOffset(value) {
-			if (!Number.isSafeInteger(value) || value < 0 || Object.is(value, -0)) throw new TypeError(`SessionLogOffset must be a non-negative safe integer, got ${String(value)}`);
-			return brandNumber(value);
-		}
-		//#endregion
 		//#region ../../util/workspace-path/lib/index.js
 		/**
 		* Read the final non-empty segment of a Workspace path for display.
@@ -679,6 +910,25 @@ window.__ModuleLoader__.load({
 					entries
 				});
 			}
+			/**
+			* Replace one attempt's transient rows with its committed durable settlement.
+			* @param attemptId - process-local attempt whose live rows are now redundant.
+			* @param entry - durable settlement committed for that attempt.
+			*/
+			settleAssistant(attemptId, entry) {
+				const entries = materialize(this.window).filter((candidate) => candidate.type !== "transient" || candidate.event.data.attemptId !== attemptId);
+				if (entry !== void 0) {
+					const index = entries.findIndex((candidate) => candidate.event.seq > entry.event.seq);
+					if (index < 0) entries.push(entry);
+					else entries.splice(index, 0, entry);
+				}
+				this.window = leaf(entries);
+				this.publish(this.snapshot.hasMore, {
+					kind: "settle-assistant",
+					attemptId,
+					...entry === void 0 ? {} : { entry }
+				});
+			}
 			publish(hasMore, change) {
 				this.snapshot = windowSnapshot(this.window, hasMore, this.snapshot.revision + 1, change);
 				(0, _deepseek_ai_dsh_client_store.notifySubscribers)(this.listeners, "[session-controller] event feed");
@@ -701,7 +951,7 @@ window.__ModuleLoader__.load({
 		//#region lib/types/client/sessions/queue-mirror.js
 		const QUEUE_PREVIEW_CHARS = 200;
 		function previewOf(content) {
-			const flat = content.filter((block) => block.type !== "image").map((block) => block.type === "text" ? block.text : `[${block.type}]`).join(" ").replace(/\s+/g, " ").trim();
+			const flat = content.filter((block) => block.type !== "image" && block.type !== "file").map((block) => block.type === "text" ? block.text : `[${block.type}]`).join(" ").replace(/\s+/g, " ").trim();
 			const chars = Array.from(flat);
 			return chars.length > QUEUE_PREVIEW_CHARS ? `${chars.slice(0, QUEUE_PREVIEW_CHARS).join("")}…` : flat;
 		}
@@ -752,6 +1002,498 @@ window.__ModuleLoader__.load({
 			}
 		};
 		//#endregion
+		//#region ../../util/values/lib/index.js
+		/** Whether a realm-owned intrinsic prototype is backed by its native constructor. */
+		function hasIntrinsicConstructor(prototype, name) {
+			const constructor = Object.getOwnPropertyDescriptor(prototype, "constructor")?.value;
+			if (typeof constructor !== "function") return false;
+			try {
+				return constructor.name === name && constructor.prototype === prototype && Function.prototype.toString.call(constructor) === `function ${name}() { [native code] }`;
+			} catch {
+				return false;
+			}
+		}
+		/** Whether a candidate is one realm's intrinsic `Object.prototype`. */
+		function isIntrinsicObjectPrototype(value) {
+			return Object.getPrototypeOf(value) === null && hasIntrinsicConstructor(value, "Object");
+		}
+		/** Whether an array uses one realm's intrinsic `Array.prototype`, not a subclass or forged prototype. */
+		function hasPlainArrayPrototype(value) {
+			const prototype = Object.getPrototypeOf(value);
+			if (!Array.isArray(prototype) || !hasIntrinsicConstructor(prototype, "Array")) return false;
+			const objectPrototype = Object.getPrototypeOf(prototype);
+			return typeof objectPrototype === "object" && objectPrototype !== null && isIntrinsicObjectPrototype(objectPrototype);
+		}
+		/** Whether an object is a plain or null-prototype record from any JavaScript realm. */
+		function hasPlainObjectPrototype(value) {
+			const prototype = Object.getPrototypeOf(value);
+			return prototype === null || typeof prototype === "object" && isIntrinsicObjectPrototype(prototype);
+		}
+		/** Return every JSON-visible object key, or reject own data JSON would discard. */
+		function enumerableStringKeys(value) {
+			const keys = Reflect.ownKeys(value);
+			if (keys.some((key) => typeof key !== "string" || !Object.prototype.propertyIsEnumerable.call(value, key))) return void 0;
+			return keys;
+		}
+		/** Validate lossless JSON iteratively, optionally materializing a detached snapshot. */
+		function walkJsonValue(value, detach) {
+			const ancestors = /* @__PURE__ */ new Set();
+			let root;
+			const assign = (destination, item) => {
+				if (destination === void 0) return;
+				if (destination.kind === "root") root = item;
+				else if (destination.kind === "array") destination.target[destination.index] = item;
+				else Object.defineProperty(destination.target, destination.key, {
+					value: item,
+					enumerable: true,
+					configurable: true,
+					writable: true
+				});
+			};
+			const tasks = [{
+				kind: "visit",
+				value,
+				...detach ? { destination: { kind: "root" } } : {}
+			}];
+			for (let task = tasks.pop(); task !== void 0; task = tasks.pop()) {
+				if (task.kind === "leave") {
+					ancestors.delete(task.source);
+					continue;
+				}
+				if (task.kind === "array-item") {
+					if (!Object.prototype.hasOwnProperty.call(task.source, task.index)) return void 0;
+					tasks.push({
+						kind: "visit",
+						value: task.source[task.index],
+						...task.target === void 0 ? {} : { destination: {
+							kind: "array",
+							target: task.target,
+							index: task.index
+						} }
+					});
+					continue;
+				}
+				if (task.kind === "object-property") {
+					tasks.push({
+						kind: "visit",
+						value: task.source[task.key],
+						...task.target === void 0 ? {} : { destination: {
+							kind: "object",
+							target: task.target,
+							key: task.key
+						} }
+					});
+					continue;
+				}
+				const current = task.value;
+				if (current === null) {
+					assign(task.destination, null);
+					continue;
+				}
+				if (typeof current === "boolean" || typeof current === "string") {
+					assign(task.destination, current);
+					continue;
+				}
+				if (typeof current === "number") {
+					if (!Number.isFinite(current) || Object.is(current, -0)) return void 0;
+					assign(task.destination, current);
+					continue;
+				}
+				if (typeof current !== "object") return void 0;
+				if (ancestors.has(current)) return void 0;
+				if (Array.isArray(current)) {
+					if (!hasPlainArrayPrototype(current)) return void 0;
+					const length = current.length;
+					if (Reflect.ownKeys(current).length !== length + 1) return void 0;
+					const target = detach ? [] : void 0;
+					if (target !== void 0) assign(task.destination, target);
+					ancestors.add(current);
+					tasks.push({
+						kind: "leave",
+						source: current
+					});
+					for (let index = length - 1; index >= 0; index--) tasks.push({
+						kind: "array-item",
+						source: current,
+						index,
+						...target === void 0 ? {} : { target }
+					});
+					continue;
+				}
+				if (!hasPlainObjectPrototype(current)) return void 0;
+				const keys = enumerableStringKeys(current);
+				if (keys === void 0) return void 0;
+				const target = detach ? {} : void 0;
+				if (target !== void 0) assign(task.destination, target);
+				ancestors.add(current);
+				tasks.push({
+					kind: "leave",
+					source: current
+				});
+				for (let index = keys.length - 1; index >= 0; index--) {
+					const key = keys[index];
+					/* v8 ignore next -- the loop is bounded by the captured key count. */
+					if (key === void 0) return void 0;
+					tasks.push({
+						kind: "object-property",
+						source: current,
+						key,
+						...target === void 0 ? {} : { target }
+					});
+				}
+			}
+			return detach ? root : true;
+		}
+		/**
+		* Validate and detach lossless JSON in one read per property.
+		* @param value - candidate value to validate and detach.
+		* @returns the detached snapshot, or `undefined` when the value is not losslessly JSON-serializable.
+		*/
+		function snapshotJsonValue(value) {
+			return walkJsonValue(value, true);
+		}
+		/**
+		* Deep-freeze an object graph in place while leaving live AbortSignal objects mutable.
+		* @param value - value to freeze.
+		* @returns the same value after every reachable enumerable child is frozen.
+		*/
+		function deepFreeze(value) {
+			const seen = /* @__PURE__ */ new WeakSet();
+			const pending = [{
+				kind: "visit",
+				node: value
+			}];
+			while (pending.length > 0) {
+				const task = pending.pop();
+				/* v8 ignore next -- the loop condition guarantees one pending task. */
+				if (task === void 0) continue;
+				if (task.kind === "property") {
+					pending.push({
+						kind: "visit",
+						node: task.source[task.key]
+					});
+					continue;
+				}
+				const node = task.node;
+				if (node === null || typeof node !== "object") continue;
+				if (node instanceof AbortSignal) continue;
+				if (seen.has(node)) continue;
+				seen.add(node);
+				Object.freeze(node);
+				const keys = Object.keys(node);
+				for (let index = keys.length - 1; index >= 0; index--) {
+					const key = keys[index];
+					/* v8 ignore next -- the loop is bounded by the captured key count. */
+					if (key === void 0) continue;
+					pending.push({
+						kind: "property",
+						source: node,
+						key
+					});
+				}
+			}
+			return value;
+		}
+		//#endregion
+		//#region ../../llm/llm/lib/types/assistant-stream.js
+		/**
+		* Lossless compact representation of one model-stream attempt, plus record-level
+		* readers that answer common consumer questions without materializing members.
+		* Readers trust the static record type; expandAssistantStream is the validating
+		* path for records read at a durable boundary.
+		*/
+		function safeTime(value) {
+			if (!Number.isSafeInteger(value)) throw new TypeError(`Assistant stream time must be a safe integer, got ${String(value)}`);
+			return value;
+		}
+		function safeIndex(value, label) {
+			if (!Number.isSafeInteger(value) || value < 0 || Object.is(value, -0)) throw new TypeError(`${label} index must be a non-negative safe integer`);
+			return value;
+		}
+		function snapshotChunk(chunk) {
+			const snapshot = snapshotJsonValue(chunk);
+			if (snapshot === void 0) throw new TypeError("Assistant stream chunk must be losslessly JSON-serializable");
+			return snapshot;
+		}
+		/**
+		* Expand compact records into the exact timed chunk sequence.
+		* @param stream - compact records from one durable Assistant settlement.
+		* @returns detached timed chunks with every original delta boundary preserved.
+		* @throws {TypeError} when a record or reconstructed timestamp is invalid.
+		*/
+		function expandAssistantStream(stream) {
+			const chunks = [];
+			for (const candidate of stream) {
+				const record = validateRecord(candidate);
+				if (record.type === "chunk") {
+					chunks.push({
+						time: record.time,
+						chunk: record.chunk
+					});
+					continue;
+				}
+				const members = record.type === "tool-call-chunks" ? record.args : record.texts;
+				let time = record.time0;
+				for (let index = 0; index < members.length; index += 1) {
+					if (index > 0) time += record.dt[index - 1];
+					let chunk;
+					if (record.type === "text-chunks") chunk = {
+						type: "text-delta",
+						index: record.index,
+						text: members[index]
+					};
+					else if (record.type === "reasoning-chunks") chunk = {
+						type: "reasoning-delta",
+						index: record.index,
+						text: members[index]
+					};
+					else chunk = {
+						type: "tool-call-delta",
+						index: record.index,
+						id: record.id,
+						...Object.hasOwn(record, "name") ? { name: record.name } : {},
+						argumentsDelta: members[index]
+					};
+					chunks.push({
+						time,
+						chunk
+					});
+				}
+			}
+			return chunks;
+		}
+		function validateRecord(value) {
+			if (typeof value !== "object" || value === null || Array.isArray(value)) throw new TypeError("Assistant stream record must be an object");
+			const record = value;
+			switch (record.type) {
+				case "text-chunks":
+				case "reasoning-chunks": {
+					exactKeys(record, [
+						"type",
+						"time0",
+						"index",
+						"dt",
+						"texts"
+					], record.type);
+					const texts = stringArray(record.texts, `${record.type} texts`);
+					if (texts.length === 0) throw new TypeError(`${record.type} texts must be non-empty`);
+					validateRun(record, texts.length, record.type);
+					return record;
+				}
+				case "tool-call-chunks": {
+					exactKeys(record, Object.hasOwn(record, "name") ? [
+						"type",
+						"time0",
+						"index",
+						"dt",
+						"id",
+						"name",
+						"args"
+					] : [
+						"type",
+						"time0",
+						"index",
+						"dt",
+						"id",
+						"args"
+					], record.type);
+					const args = stringArray(record.args, "tool-call-chunks args");
+					if (args.length === 0) throw new TypeError("tool-call-chunks args must be non-empty");
+					if (typeof record.id !== "string" || record.id.length === 0) throw new TypeError("tool-call-chunks id must be a non-empty string");
+					if (record.name !== void 0 && (typeof record.name !== "string" || record.name.length === 0)) throw new TypeError("tool-call-chunks name must be a non-empty string");
+					validateRun(record, args.length, record.type);
+					return record;
+				}
+				case "chunk": {
+					exactKeys(record, [
+						"type",
+						"time",
+						"chunk"
+					], "chunk");
+					const time = safeTime(record.time);
+					if (typeof record.chunk !== "object" || record.chunk === null || Array.isArray(record.chunk)) throw new TypeError("Assistant stream raw chunk must be a lossless JSON object");
+					let chunk;
+					try {
+						chunk = snapshotChunk(record.chunk);
+					} catch (error) {
+						throw new TypeError("Assistant stream raw chunk must be a lossless JSON object", { cause: error });
+					}
+					return deepFreeze({
+						type: "chunk",
+						time,
+						chunk
+					});
+				}
+				default: throw new TypeError(`Unsupported Assistant stream record ${JSON.stringify(record.type)}`);
+			}
+		}
+		function validateRun(record, members, label) {
+			safeTime(record.time0);
+			safeIndex(record.index, label);
+			if (!Array.isArray(record.dt) || record.dt.some((value) => !Number.isSafeInteger(value))) throw new TypeError(`${label} dt must contain safe integers`);
+			if (record.dt.length !== members - 1) throw new TypeError(`${label} dt length must be one less than its members`);
+			let time = record.time0;
+			for (const gap of record.dt) {
+				time += gap;
+				if (!Number.isSafeInteger(time)) throw new TypeError(`${label} member times must stay safe integers`);
+			}
+		}
+		function stringArray(value, label) {
+			if (!Array.isArray(value) || value.some((member) => typeof member !== "string")) throw new TypeError(`${label} must be a string array`);
+			return value;
+		}
+		function exactKeys(record, keys, label) {
+			if (Object.keys(record).length !== keys.length || !keys.every((key) => Object.hasOwn(record, key))) throw new TypeError(`${label} Assistant stream record must contain exactly ${keys.join(", ")}`);
+		}
+		//#endregion
+		//#region lib/types/client/sessions/assistant-stream.js
+		/** Web presentation fold joining transient Assistant frames to one durable v2 settlement. */
+		/** Keeps transient Assistant presentation behind one settlement-aware interface. */
+		var ClientAssistantStream = class {
+			activeAttempt;
+			pending = /* @__PURE__ */ new Map();
+			publishedSeqs = /* @__PURE__ */ new Set();
+			durableCursor = -1;
+			transientInGap = 0;
+			/**
+			* Replace the durable Web window and adopt an optional reconnect baseline.
+			* @param entries - durable entries in the replacement window.
+			* @param baseline - compact prefix for an Assistant attempt that is still live.
+			* @returns immediately visible durable entries plus reconstructed transient chunks.
+			*/
+			replace(entries, baseline) {
+				this.pending.clear();
+				this.transientInGap = 0;
+				this.activeAttempt = void 0;
+				const opening = baseline?.activeAttempt;
+				if (opening !== void 0) this.activeAttempt = {
+					attemptId: opening.attemptId,
+					startedAfterSeq: opening.startedAfterSeq,
+					turn: opening.turn,
+					step: opening.step,
+					nextIndex: opening.nextIndex
+				};
+				const visible = [...entries];
+				this.publishedSeqs = new Set(visible.map((entry) => entry.event.seq));
+				this.durableCursor = visible.reduce((cursor, entry) => Math.max(cursor, entry.event.seq), -1);
+				if (opening !== void 0) for (const [index, member] of expandAssistantStream(opening.stream).entries()) {
+					this.transientInGap += 1;
+					visible.push({
+						type: "transient",
+						event: {
+							type: "assistant/live-chunk",
+							seq: this.durableCursor + 1 - 1 / (this.transientInGap + 1),
+							time: member.time,
+							data: {
+								attemptId: opening.attemptId,
+								turn: opening.turn,
+								step: opening.step,
+								chunk: member.chunk
+							}
+						}
+					});
+					if (index + 1 >= opening.nextIndex) break;
+				}
+				return visible;
+			}
+			/**
+			* Stage one durable v2 settlement while its matching live attempt is open.
+			* @param entry - newly followed durable entry.
+			* @returns a publication decision, or `undefined` when no entry becomes visible.
+			*/
+			acceptDurable(entry) {
+				const event = entry.event;
+				this.durableCursor = Math.max(this.durableCursor, event.seq);
+				this.transientInGap = 0;
+				const settlement = assistantSettlementEntry(entry);
+				if (settlement !== void 0 && this.attemptForSettlement(settlement.event) !== void 0) {
+					if (this.pending.has(event.seq)) return { type: "rebaseline" };
+					this.pending.set(event.seq, settlement);
+					return;
+				}
+				return this.publish(entry);
+			}
+			/**
+			* Fold one dense transient frame and release its named durable settlement.
+			* @param frame - next Assistant stream frame received by the follow connection.
+			* @returns a transient, publication, or rebaseline decision, or `undefined` when no entry becomes visible.
+			*/
+			acceptFrame(frame) {
+				switch (frame.type) {
+					case "start":
+						if (this.activeAttempt !== void 0 || this.pending.size > 0) return { type: "rebaseline" };
+						this.pending.clear();
+						this.activeAttempt = {
+							attemptId: frame.attemptId,
+							startedAfterSeq: frame.startedAfterSeq,
+							turn: frame.turn,
+							step: frame.step,
+							nextIndex: 0
+						};
+						return;
+					case "chunk": {
+						const attempt = this.activeAttempt;
+						if (attempt === void 0 || attempt.attemptId !== frame.attemptId) return void 0;
+						if (frame.index !== attempt.nextIndex) return { type: "rebaseline" };
+						attempt.nextIndex += 1;
+						this.transientInGap += 1;
+						return {
+							type: "transient",
+							entry: {
+								type: "transient",
+								event: {
+									type: "assistant/live-chunk",
+									seq: this.durableCursor + 1 - 1 / (this.transientInGap + 1),
+									time: frame.time,
+									data: {
+										attemptId: frame.attemptId,
+										turn: attempt.turn,
+										step: attempt.step,
+										chunk: frame.chunk
+									}
+								}
+							}
+						};
+					}
+					case "end": {
+						const attempt = this.activeAttempt;
+						if (attempt === void 0 || attempt.attemptId !== frame.attemptId) return;
+						this.activeAttempt = void 0;
+						if (frame.index !== attempt.nextIndex) return { type: "rebaseline" };
+						if (frame.outcome.kind === "abandoned") return this.pending.size === 0 ? {
+							type: "abandonment",
+							attemptId: attempt.attemptId
+						} : { type: "rebaseline" };
+						if (this.publishedSeqs.has(frame.outcome.seq)) return void 0;
+						const entry = this.pending.get(frame.outcome.seq);
+						if (entry === void 0 || entry.event.type !== frame.outcome.eventType) return { type: "rebaseline" };
+						this.pending.delete(frame.outcome.seq);
+						this.publishedSeqs.add(entry.event.seq);
+						return {
+							type: "settlement",
+							attemptId: attempt.attemptId,
+							entry
+						};
+					}
+				}
+			}
+			attemptForSettlement(event) {
+				const attempt = this.activeAttempt;
+				if (attempt === void 0 || event.type === "assistant/message" && event.surfaceOp !== "append" || event.seq <= attempt.startedAfterSeq || attempt.turn !== event.data.turn || attempt.step !== event.data.step) return void 0;
+				return attempt;
+			}
+			publish(entry) {
+				this.publishedSeqs.add(entry.event.seq);
+				return {
+					type: "publish",
+					entry
+				};
+			}
+		};
+		function assistantSettlementEntry(entry) {
+			return entry.event.type === "assistant/message" || entry.event.type === "assistant/attempt" ? entry : void 0;
+		}
+		//#endregion
 		//#region lib/types/client/sessions/session.js
 		function projectionsBaseline(value) {
 			return {
@@ -784,6 +1526,7 @@ window.__ModuleLoader__.load({
 			jumpPromise = null;
 			/** Authoritative stream-only inbox snapshot; pending work never hits history. */
 			queueMirror = new SessionQueueMirror();
+			assistantStream = new ClientAssistantStream();
 			running = false;
 			address;
 			parentAvailable;
@@ -879,7 +1622,7 @@ window.__ModuleLoader__.load({
 					placement: this.running ? input.mode === "steer" ? "steering" : "queued" : "transcript",
 					time: Date.now(),
 					text: input.text,
-					images: input.images
+					attachments: input.attachments
 				}];
 				this.submissionSettlements.set(requestId, {
 					onRetire: input.onRetire,
@@ -896,7 +1639,7 @@ window.__ModuleLoader__.load({
 			}
 			/**
 			* Send (queue/steer passed through 1:1); failures land in the snapshot's promptError.
-			* @param content - text plus browser-owned temporary image uploads.
+			* @param content - text, browser-owned temporary image uploads, and staged-file receipts.
 			* @param mode - queue appends after the current turn; steer interrupts it.
 			* @param signal - optional caller cancellation for the complete admission round-trip.
 			* @param requestId - identity from {@link beginSubmission}; a failed identified prompt retires its echo.
@@ -918,13 +1661,19 @@ window.__ModuleLoader__.load({
 						content,
 						clientTimeZone
 					}, signal);
-				} else {
+				} else if (content.some((part) => part.type === "file")) result = {
+					ok: false,
+					error: new RemoteError("subagent/attachment-invalid", "subagent continuation does not accept files", { reason: "SUBAGENT_FILE_UNSUPPORTED" })
+				};
+				else {
+					const routedContent = content;
 					const routed = await this.remote.subagents.prompt({
 						requestId: randomUUID(),
 						parentSessionId: this.address.parentSessionId,
 						childSessionId: this.address.childSessionId,
 						mode: "continuable",
-						content,
+						delivery: mode,
+						content: routedContent,
 						clientTimeZone: resolvedClientTimeZone()
 					}, signal);
 					result = routed.ok ? {
@@ -1257,24 +2006,53 @@ window.__ModuleLoader__.load({
 			acceptEventChange(change) {
 				switch (change.type) {
 					case "replace":
-						this.installWindow(change.entries, change.hasMore, change.page.projections === void 0 ? void 0 : projectionsBaseline(change.page.projections));
+						this.installWindow(change.entries, change.hasMore, change.page.projections === void 0 ? void 0 : projectionsBaseline(change.page.projections), change.page.assistantStream);
 						return;
 					case "prepend":
 						this.prependWindow(change.entries, change.hasMore);
 						return;
-					case "append": if (this.appendLive(change.entry)) this.notifier.markDirty();
+					case "append":
+						this.publishAssistantEntry(this.assistantStream.acceptDurable(change.entry));
+						return;
+					case "assistant-stream": this.publishAssistantEntry(this.assistantStream.acceptFrame(change.frame));
 				}
 			}
 			/** Replace the complete contiguous window and apply page-owned projection metadata. */
-			installWindow(entries, hasMore, projections) {
+			installWindow(entries, hasMore, projections, assistantStream) {
+				const visible = this.assistantStream.replace(entries, assistantStream);
 				this.baseSeq = SessionLogOffset(entries[0]?.event.seq ?? 0);
 				this.hasMore = hasMore;
-				if (entries.some((entry) => entry.event.type === "turn/start")) this.firstPromptPendingTurn = false;
+				if (visible.some((entry) => entry.event.type === "turn/start")) this.firstPromptPendingTurn = false;
 				if (projections !== void 0) this.projections.seed(projections);
-				this.eventSource.replace(entries, hasMore);
-				for (const entry of entries) this.observeSubmissionEvent(entry.event);
+				this.eventSource.replace(visible, hasMore);
+				for (const entry of visible) this.observeSubmissionEvent(entry.event);
 				this.notifier.markDirty();
 			}
+			publishAssistantEntry(result) {
+				if (result?.type === "rebaseline") {
+					const events = this.events;
+					queueMicrotask(() => {
+						if (events !== void 0 && this.events === events) events.restart();
+					});
+					return;
+				}
+				if (result?.type === "settlement") {
+					this.eventSource.settleAssistant(result.attemptId, result.entry);
+					this.observeSubmissionEvent(result.entry.event);
+					this.notifier.markDirty();
+					return;
+				}
+				if (result?.type === "abandonment") {
+					this.eventSource.settleAssistant(result.attemptId);
+					this.notifier.markDirty();
+					return;
+				}
+				if (result?.type === "publish" && this.appendLive(result.entry)) this.notifier.markDirty();
+				else if (result?.type === "transient") {
+					this.eventSource.append(result.entry);
+					this.notifier.markDirty();
+				}
+			}
 			/** Prepend one stream-validated history page. */
 			prependWindow(entries, hasMore) {
 				this.baseSeq = entries[0] === void 0 ? this.baseSeq : SessionLogOffset(entries[0].event.seq);
@@ -1297,12 +2075,12 @@ window.__ModuleLoader__.load({
 				const data = event.data;
 				const source = data?.source;
 				if (source?.kind !== "user" || typeof source.rpcId !== "string") return;
-				this.scheduleObservedRetirement(source.rpcId, imageRefsIn(data?.content));
+				this.scheduleObservedRetirement(source.rpcId, attachmentRefsIn(data?.content));
 			}
 			/** Retire echoes whose prompts landed in the host inbox instead of the log (running-turn submissions). */
 			observeSubmissionQueue(items) {
 				if (this.submissionSettlements.size === 0) return;
-				for (const item of items) if (item.rpcId !== void 0) this.scheduleObservedRetirement(item.rpcId, imageRefsIn(item.message.content));
+				for (const item of items) if (item.rpcId !== void 0) this.scheduleObservedRetirement(item.rpcId, attachmentRefsIn(item.message.content));
 			}
 			/**
 			* Latch one observed settlement and remove the echo an animation frame
@@ -1389,14 +2167,14 @@ window.__ModuleLoader__.load({
 			});
 			else setTimeout(fn, 0);
 		}
-		/** Image attachment references in one structurally-read content block list, in block order. */
-		function imageRefsIn(content) {
+		/** Attachment references in one structurally-read content block list, in block order. */
+		function attachmentRefsIn(content) {
 			if (!Array.isArray(content)) return [];
 			const refs = [];
 			for (const block of content) {
 				if (typeof block !== "object" || block === null) continue;
 				const candidate = block;
-				if (candidate.type === "image" && typeof candidate.attachment === "object" && candidate.attachment !== null) refs.push(candidate.attachment);
+				if ((candidate.type === "image" || candidate.type === "file") && typeof candidate.attachment === "object" && candidate.attachment !== null) refs.push(candidate.attachment);
 			}
 			return refs;
 		}
@@ -2709,6 +3487,8 @@ window.__ModuleLoader__.load({
 		/** Client Session object layer, Agent scopes, and Remote lifecycle wiring. */
 		/** Required Remote and Context projection services. */
 		const inject = [
+			"connection",
+			"fileUpload",
 			"typert",
 			"remote",
 			"remote.commands",