@rynx-ai/server 0.1.11-beta.5 → 0.1.11-beta.51

package/dist/machine-session-service.js

@@ -7,8 +7,11 @@
  * Direct adapters can therefore expose the same behavior without copying state
  * into a Control Plane database.
  */
-import { createHash, randomUUID } from "node:crypto";
-import { SESSION_PROVIDER_IDS, getRuntimeProfile, isSessionProviderId, newSessionItemId, newSessionId, normalizeSessionTitle, } from "@rynx-ai/core";
+import { createHash } from "node:crypto";
+import { open, realpath, stat } from "node:fs/promises";
+import { basename, extname, isAbsolute, relative, resolve, sep } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { SESSION_PROVIDER_IDS, getRuntimeProfile, isSessionProviderId, newSessionId, normalizeSessionTitle, } from "@rynx-ai/core";
 import { REMOTE_RUNTIME_SESSION_DEFAULT_PAGE_SIZE, REMOTE_RUNTIME_SESSION_MAX_CURSOR_CHARS, REMOTE_RUNTIME_SESSION_MAX_ID_CHARS, REMOTE_RUNTIME_SESSION_MAX_PAGE_SIZE, } from "@rynx-ai/protocol/remote-runtime-rpc";
 const DEFAULT_LIST_LIMIT = REMOTE_RUNTIME_SESSION_DEFAULT_PAGE_SIZE;
 const MAX_LIST_LIMIT = REMOTE_RUNTIME_SESSION_MAX_PAGE_SIZE;
@@ -31,10 +34,17 @@ export class MachineSessionServiceInputError extends Error {
 export class MachineSessionServiceFailure extends Error {
     code;
     detail;
-    constructor(code, message, detail) {
+    runtimeFailure;
+    retryable;
+    constructor(code, message, detail, runtimeFailure, 
+    /** True only when retrying the same operation can succeed without changing
+     * its payload. Used by durable mirror delivery to preserve transient data. */
+    retryable = false) {
         super(message);
         this.code = code;
         this.detail = detail;
+        this.runtimeFailure = runtimeFailure;
+        this.retryable = retryable;
         this.name = "MachineSessionServiceFailure";
     }
 }
@@ -52,6 +62,7 @@ export class MachineSessionService {
     pendingDeliveries = new Map();
     cancelledPendingDeliveries = new Set();
     forkTasks = new Map();
+    sessionMutationTails = new Map();
     constructor(ports, options = {}) {
         this.ports = ports;
         this.maxListLimit = boundedInteger(options.maxListLimit ?? MAX_LIST_LIMIT, 1, MAX_LIST_LIMIT, "maxListLimit");
@@ -110,7 +121,8 @@ export class MachineSessionService {
             limit: limit + 1,
         })).slice(0, limit + 1).map((item) => structuredClone(item));
         const runtime = cloneRuntimeSnapshot(this.ports.runtimeState.snapshot(sessionId));
-        const empty = snapshotPage(sessionId, [], runtime, false);
+        const pendingInputs = this.ports.pendingInputs?.snapshotFor(sessionId) ?? [];
+        const empty = snapshotPage(sessionId, [], pendingInputs, runtime, false);
         const items = [];
         let itemsJsonBytes = 0;
         for (const item of candidates.slice(0, limit)) {
@@ -118,14 +130,14 @@ export class MachineSessionService {
             const nextCount = items.length + 1;
             const hasMore = candidates.length > nextCount;
             if (items.length > 0 &&
-                snapshotPageJsonByteLength(sessionId, nextItemsJsonBytes, item.id, runtime, hasMore) > this.snapshotPageMaxBytes) {
+                snapshotPageJsonByteLength(sessionId, nextItemsJsonBytes, item.id, pendingInputs, runtime, hasMore) > this.snapshotPageMaxBytes) {
                 break;
             }
             items.push(item);
             itemsJsonBytes = nextItemsJsonBytes;
         }
         return items.length > 0
-            ? snapshotPage(sessionId, items, runtime, candidates.length > items.length)
+            ? snapshotPage(sessionId, items, pendingInputs, runtime, candidates.length > items.length)
             : empty;
     }
     /**
@@ -208,49 +220,87 @@ export class MachineSessionService {
         }
         return executionSettingsResult(meta.execution);
     }
-    /** Replace only the model defaults of an idle Session. The runner is closed
-     * so every Provider resumes its native context with the new settings on the
-     * next turn. */
+    /** Replace the defaults for the next new Turn. Codex-lineage Providers keep
+     * their live runner: the host applies changed native thread settings under
+     * its injection lock immediately before the next `turn/start`. Claude still
+     * needs an idle cold resume because its live CLI has no confirmed settings
+     * update boundary. Provider CLIs own model availability validation. */
     async updateExecutionSettings(input) {
         const sessionId = validOpaqueToken(input.sessionId, "sessionId", MAX_SESSION_ID_CHARS);
-        const modelId = validRequiredText(input.model, "model");
-        const meta = this.ports.registry.get(sessionId);
-        if (!meta) {
-            throw new MachineSessionServiceFailure("not_found", "session not found");
-        }
-        await this.assertNotForkReserved(sessionId);
-        const runtime = this.ports.runtimeState.snapshot(sessionId);
-        const pendingMessage = await this.ports.pendingMessages?.get(sessionId);
-        if (runtime.status !== "idle" ||
-            runtime.activeResponseIds.length > 0 ||
-            runtime.pendingInteractions.length > 0 ||
-            pendingMessage) {
-            throw new MachineSessionServiceFailure("failed_precondition", "Session must be idle before changing model settings");
-        }
-        const executionPort = this.requireExecution();
-        if (!executionPort.listModels) {
-            throw new MachineSessionServiceFailure("failed_precondition", "Runtime model catalog is unavailable");
-        }
-        const models = await executionPort.listModels(meta.execution.provider);
-        const model = models.find((candidate) => candidate.id === modelId);
-        if (!model) {
-            throw new MachineSessionServiceInputError(`model is not available for ${meta.execution.provider}`);
-        }
+        const modelId = input.model === null ? null : validRequiredText(input.model, "model");
         const reasoningEffort = input.reasoningEffort === null
             ? null
             : validRequiredText(input.reasoningEffort, "reasoningEffort");
-        if (reasoningEffort !== null &&
-            !model.reasoningOptions.some((option) => option.value === reasoningEffort)) {
-            throw new MachineSessionServiceInputError(`reasoningEffort is not available for model ${model.id}`);
+        return this.withSessionMutation(sessionId, async () => {
+            const meta = this.ports.registry.get(sessionId);
+            if (!meta) {
+                throw new MachineSessionServiceFailure("not_found", "session not found");
+            }
+            await this.assertNotForkReserved(sessionId);
+            const nextExecution = await this.replaceExecutionSettings(sessionId, meta, { model: modelId, reasoningEffort }, input.collaborationMode);
+            return executionSettingsResult(nextExecution);
+        });
+    }
+    async replaceExecutionSettings(sessionId, meta, selection, collaborationMode) {
+        if (meta.execution.provider === "claude") {
+            const runtime = this.ports.runtimeState.snapshot(sessionId);
+            const pendingMessage = await this.ports.pendingMessages?.get(sessionId);
+            if (runtime.status !== "idle" ||
+                runtime.activeResponseIds.length > 0 ||
+                runtime.pendingInteractions.length > 0 ||
+                pendingMessage) {
+                throw new MachineSessionServiceFailure("failed_precondition", "Claude Session must be idle before changing model settings");
+            }
         }
+        const executionPort = this.requireExecution();
         const nextExecution = {
             ...structuredClone(meta.execution),
-            model: model.id,
-            reasoningEffort,
+            model: selection.model,
+            reasoningEffort: selection.reasoningEffort,
+            ...(meta.execution.provider !== "claude" && collaborationMode !== undefined
+                ? { collaborationMode }
+                : {}),
         };
+        if (meta.execution.provider !== "claude" && collaborationMode !== undefined) {
+            const updateMode = executionPort.runner.updateCollaborationMode;
+            if (!updateMode) {
+                const message = "This Runtime does not support live collaboration-mode updates";
+                throw new MachineSessionServiceFailure("failed_precondition", message, message, {
+                    message,
+                    code: "collaboration_mode_unavailable",
+                    statusCode: 409,
+                });
+            }
+            // Native state is authoritative. Do not make a failed
+            // toggle survive reload when the loaded thread rejected it.
+            try {
+                await updateMode.call(executionPort.runner, sessionId, collaborationMode);
+            }
+            catch (error) {
+                const failure = liveSessionFailureFrom(error);
+                const message = collaborationModeFailureMessage(meta.execution.provider, failure, error instanceof Error ? error.message : "Native collaboration mode update failed");
+                throw new MachineSessionServiceFailure("failed_precondition", message, message, failure ? { ...failure, message } : undefined);
+            }
+        }
         this.ports.registry.setExecution(sessionId, nextExecution);
-        executionPort.runner.stopRunner(sessionId);
-        return executionSettingsResult(nextExecution);
+        if (nextExecution.provider === "claude") {
+            executionPort.runner.stopRunner(sessionId);
+        }
+        return nextExecution;
+    }
+    /** Persist a mode changed from the native TUI before its reflected event is
+     * fanned out to Web clients. Unknown/deleted and Claude Sessions are ignored. */
+    recordNativeCollaborationMode(sessionIdInput, mode) {
+        const sessionId = validOpaqueToken(sessionIdInput, "sessionId", MAX_SESSION_ID_CHARS);
+        const meta = this.ports.registry.get(sessionId);
+        if (!meta || meta.execution.provider === "claude")
+            return;
+        if (meta.execution.collaborationMode === mode)
+            return;
+        this.ports.registry.setExecution(sessionId, {
+            ...structuredClone(meta.execution),
+            collaborationMode: mode,
+        });
     }
     /** Create target-owned Session identity from one Agent preset or direct Provider. */
     async create(input) {
@@ -363,6 +413,11 @@ export class MachineSessionService {
             if (input.kind === "fork" &&
                 existing.forkedFromSessionId === sourceSessionId)
                 return;
+            if (input.kind === "clear" &&
+                existing.source === "clear" &&
+                isDeepStrictEqual(existing.workspace, source.workspace) &&
+                isDeepStrictEqual(existing.execution, source.execution))
+                return;
             throw new MachineSessionServiceFailure("conflict", "target Session already exists");
         }
         const workspace = structuredClone(source.workspace);
@@ -456,8 +511,169 @@ export class MachineSessionService {
     async sendMessage(sessionIdInput, messageInput) {
         return this.withAdmission(() => this.sendMessageAdmitted(sessionIdInput, messageInput));
     }
-    async sendMessageAdmitted(sessionIdInput, messageInput) {
+    /** Start a turn and return only that response's canonical event stream. */
+    async startRun(sessionIdInput, messageInput, options = {}) {
+        return this.withAdmission(async () => {
+            const sessionId = validOpaqueToken(sessionIdInput, "sessionId", MAX_SESSION_ID_CHARS);
+            const meta = this.ports.registry.get(sessionId);
+            if (!meta)
+                throw new MachineSessionServiceFailure("not_found", "Session not found");
+            const subscription = this.ports.events.subscribe(sessionId)[Symbol.asyncIterator]();
+            let unsteer;
+            let ownsTurn = false;
+            const activateTurn = () => {
+                if (ownsTurn)
+                    return;
+                ownsTurn = true;
+                if (!options.signal?.aborted) {
+                    unsteer = options.steer?.subscribe((text) => {
+                        void this.requireExecution().runner.injectMessage(sessionId, text);
+                    });
+                }
+            };
+            const interrupt = () => {
+                if (ownsTurn)
+                    void this.ports.interruption.interrupt(sessionId);
+            };
+            try {
+                options.signal?.addEventListener("abort", interrupt, { once: true });
+                const result = await this.sendMessageAdmitted(sessionId, messageInput, options.signal, activateTurn, true, options.collaborationMode
+                    ? { collaborationMode: options.collaborationMode }
+                    : undefined);
+                const initialResponseId = result.responseId;
+                const pendingId = result.pendingId;
+                const replayItems = result.replayed && initialResponseId
+                    ? (await this.ports.log.snapshot(sessionId)).filter((item) => item.responseId === initialResponseId)
+                    : [];
+                const replayedItemIds = new Set(replayItems.map((item) => item.id));
+                const replayWasActive = initialResponseId
+                    ? this.ports.runtimeState.snapshot(sessionId).activeResponseIds.includes(initialResponseId)
+                    : false;
+                if (result.replayed && initialResponseId && !replayWasActive) {
+                    throw new MachineSessionServiceFailure("outcome_unknown", "run was already accepted but its terminal event is no longer available");
+                }
+                if (result.replayed && (initialResponseId || pendingId)) {
+                    activateTurn();
+                    if (options.signal?.aborted) {
+                        await this.ports.interruption.interrupt(sessionId).catch(() => false);
+                        throw abortReason(options.signal);
+                    }
+                }
+                const runExecution = result.operationExecution ?? {
+                    model: meta.execution.model,
+                    reasoningEffort: meta.execution.reasoningEffort,
+                };
+                const model = runExecution.model;
+                // After a daemon restart an already-injected transcript-backed
+                // operation has neither a process-live pending id nor a replayable
+                // response id. Its delivery is still successful and must never be
+                // repeated. End this caller's projection without claiming a different
+                // future Turn; the transcript remains independently visible on the
+                // Session stream.
+                if (result.replayed && !initialResponseId && !pendingId) {
+                    options.signal?.removeEventListener("abort", interrupt);
+                    await subscription.return?.();
+                    const provider = meta.execution.provider;
+                    return {
+                        provider,
+                        model: runExecution.model,
+                        authSource: provider === "traex"
+                            ? "traex_cli"
+                            : provider === "claude"
+                                ? "claude_cli"
+                                : "codex_cli",
+                        generator: (async function* () { })(),
+                    };
+                }
+                const generator = (async function* () {
+                    let responseId = initialResponseId;
+                    const beforeIdentity = new Map();
+                    try {
+                        if (result.replayed && responseId) {
+                            yield {
+                                type: "response.created",
+                                sessionId,
+                                responseId,
+                                model: model ?? "unknown",
+                            };
+                            for (const item of replayItems)
+                                yield replaySessionItem(item);
+                        }
+                        while (true) {
+                            const next = await subscription.next();
+                            if (next.done)
+                                return;
+                            const event = next.value;
+                            if (!responseId) {
+                                const eventResponseId = sessionEventResponseId(event);
+                                if (eventResponseId) {
+                                    const buffered = beforeIdentity.get(eventResponseId) ?? [];
+                                    buffered.push(event);
+                                    beforeIdentity.set(eventResponseId, buffered);
+                                }
+                                const lateResponseId = pendingId
+                                    ? responseIdForClearedPending(event, pendingId)
+                                    : event.type === "response.created"
+                                        ? event.responseId
+                                        : undefined;
+                                if (!lateResponseId)
+                                    continue;
+                                responseId = lateResponseId;
+                                for (const buffered of beforeIdentity.get(responseId) ?? []) {
+                                    const itemId = sessionEventItemId(buffered);
+                                    if (itemId && replayedItemIds.has(itemId))
+                                        continue;
+                                    yield buffered;
+                                    if (isTerminalResponseEvent(buffered))
+                                        return;
+                                }
+                                beforeIdentity.clear();
+                                continue;
+                            }
+                            if (sessionEventResponseId(event) !== responseId)
+                                continue;
+                            const itemId = sessionEventItemId(event);
+                            if (itemId && replayedItemIds.has(itemId))
+                                continue;
+                            yield event;
+                            if (isTerminalResponseEvent(event))
+                                return;
+                        }
+                    }
+                    finally {
+                        options.signal?.removeEventListener("abort", interrupt);
+                        unsteer?.();
+                        await subscription.return?.();
+                    }
+                })();
+                const provider = meta.execution.provider;
+                return {
+                    ...(initialResponseId ? { responseId: initialResponseId } : {}),
+                    provider,
+                    model: runExecution.model,
+                    authSource: provider === "traex"
+                        ? "traex_cli"
+                        : provider === "claude"
+                            ? "claude_cli"
+                            : "codex_cli",
+                    generator,
+                };
+            }
+            catch (error) {
+                options.signal?.removeEventListener("abort", interrupt);
+                unsteer?.();
+                await subscription.return?.();
+                throw error;
+            }
+        });
+    }
+    async sendMessageAdmitted(sessionIdInput, messageInput, signal, onTurnOwned, includeResponseId = false, turnOptions) {
         const sessionId = validOpaqueToken(sessionIdInput, "sessionId", MAX_SESSION_ID_CHARS);
+        return this.withSessionMutation(sessionId, () => this.sendMessageAdmittedSerial(sessionId, messageInput, signal, onTurnOwned, includeResponseId, turnOptions));
+    }
+    async sendMessageAdmittedSerial(sessionId, messageInput, signal, onTurnOwned, includeResponseId = false, turnOptions) {
+        if (signal?.aborted)
+            throw abortReason(signal);
         await this.assertNotForkReserved(sessionId);
         const request = typeof messageInput === "string"
             ? { message: messageInput }
@@ -473,7 +689,24 @@ export class MachineSessionService {
         if (hasContent && (!Array.isArray(request.content) || request.content.length === 0)) {
             throw new MachineSessionServiceInputError("content must be a non-empty array");
         }
-        const meta = this.ports.registry.get(sessionId);
+        let meta = this.ports.registry.get(sessionId);
+        const executionSelection = normalizeRunExecutionSelection(request.execution);
+        if (executionSelection && !meta) {
+            throw new MachineSessionServiceFailure("not_found", "session not found");
+        }
+        const requestedOperationExecution = executionSelection && meta
+            ? {
+                selection: executionSelection,
+                snapshot: {
+                    model: executionSelection.model !== undefined
+                        ? executionSelection.model
+                        : meta.execution.model,
+                    reasoningEffort: executionSelection.reasoningEffort !== undefined
+                        ? executionSelection.reasoningEffort
+                        : meta.execution.reasoningEffort,
+                },
+            }
+            : undefined;
         const consoleMeta = meta?.source === "console" ? meta : undefined;
         let prepared;
         const needsPreparedOperation = hasContent || request.clientMessageId !== undefined;
@@ -489,14 +722,29 @@ export class MachineSessionService {
             }
             prepared = await resources.prepareInput(sessionId, hasContent
                 ? request.content
-                : [{ type: "input_text", text: request.message }], request.clientMessageId);
+                : [{ type: "input_text", text: request.message }], request.clientMessageId, ...(requestedOperationExecution ? [requestedOperationExecution] : []));
             if (prepared.operationState === "injecting" ||
                 prepared.operationState === "outcome_unknown") {
                 throw new MachineSessionServiceFailure("outcome_unknown", "message delivery outcome is unknown");
             }
             if (prepared.operationState === "injected" ||
                 prepared.operationState === "mirrored") {
-                return { ok: true, injected: true };
+                const replayPendingId = prepared.operationState === "injected" && request.clientMessageId
+                    ? this.ports.pendingInputs
+                        ?.findByClientMessageId(sessionId, request.clientMessageId)?.pendingId
+                    : undefined;
+                return {
+                    ok: true,
+                    injected: true,
+                    ...(replayPendingId ? { pendingId: replayPendingId } : {}),
+                    ...(includeResponseId && prepared.responseId
+                        ? { responseId: prepared.responseId }
+                        : {}),
+                    ...(prepared.operationExecution
+                        ? { operationExecution: prepared.operationExecution }
+                        : {}),
+                    replayed: true,
+                };
             }
         }
         else {
@@ -510,108 +758,139 @@ export class MachineSessionService {
                 title: request.message,
             };
         }
+        const operationExecution = prepared.operationExecution ?? requestedOperationExecution?.snapshot;
+        if (operationExecution &&
+            meta &&
+            (operationExecution.model !== meta.execution.model ||
+                operationExecution.reasoningEffort !== meta.execution.reasoningEffort)) {
+            const nextExecution = await this.replaceExecutionSettings(sessionId, meta, operationExecution);
+            meta = { ...meta, execution: nextExecution };
+        }
         if (consoleMeta && !consoleMeta.title) {
             this.ports.registry.setTitle(sessionId, synthesizeSessionTitle(prepared.title));
         }
         const resources = this.ports.resources;
+        if (signal?.aborted) {
+            if (request.clientMessageId) {
+                await resources?.markMessageFailedNotStarted(sessionId, request.clientMessageId, "run was cancelled before injection");
+            }
+            throw abortReason(signal);
+        }
         if (request.clientMessageId) {
             await resources?.markMessageInjecting(sessionId, request.clientMessageId);
         }
-        const responseId = this.ports.publishEvent ? `resp_${randomUUID()}` : undefined;
-        if (responseId) {
-            await this.ports.publishEvent(sessionId, {
-                type: "session.input.consumed",
-                item: {
-                    id: newSessionItemId("message"),
-                    sessionId,
-                    position: 0,
-                    responseId,
-                    status: "completed",
-                    createdAt: Date.now(),
-                    type: "message",
-                    data: {
-                        role: "user",
-                        content: prepared.input.content.map((part) => part.type === "text"
-                            ? { type: "input_text", text: part.text }
-                            : { ...part.resource }),
-                    },
-                },
-            });
-            await this.ports.publishEvent(sessionId, {
-                type: "session.status",
-                sessionId,
-                responseId,
-                status: "running",
-                statusKind: "startup",
-            });
-        }
-        const abandonResponseHandoff = responseId
-            ? this.ports.runtimeState.beginResponseHandoff?.(sessionId, responseId)
-            : undefined;
-        const clearStartup = async (status) => {
-            if (!responseId)
-                return;
-            await this.ports.publishEvent(sessionId, {
-                type: "session.status",
-                sessionId,
-                responseId,
-                status,
-            });
-        };
         let execution;
         try {
             execution = await this.ensureLiveSession(sessionId, meta);
         }
         catch (error) {
-            abandonResponseHandoff?.();
-            await clearStartup("idle");
             if (request.clientMessageId) {
                 await resources?.markMessageFailedNotStarted(sessionId, request.clientMessageId, error instanceof Error ? error.message : String(error));
             }
             throw error;
         }
-        let outcome;
+        if (signal?.aborted) {
+            if (request.clientMessageId) {
+                await resources?.markMessageFailedNotStarted(sessionId, request.clientMessageId, "run was cancelled before injection");
+            }
+            throw abortReason(signal);
+        }
+        let result;
+        const pendingId = this.ports.pendingInputs && request.clientMessageId
+            ? this.ports.pendingInputs.record(sessionId, {
+                clientMessageId: request.clientMessageId,
+                content: (hasContent
+                    ? request.content
+                    : [{ type: "input_text", text: request.message }]).map((part) => ({ ...part })),
+            })
+            : undefined;
+        const rollbackPendingInput = () => {
+            if (pendingId)
+                this.ports.pendingInputs?.resolve(sessionId, pendingId);
+        };
         try {
-            const runtimeInput = responseId
-                ? { ...prepared.input, responseId }
-                : prepared.input;
-            outcome = await execution.runner.injectMessage(sessionId, responseId || needsPreparedOperation ? runtimeInput : request.message);
+            const injectionInput = needsPreparedOperation ? prepared.input : request.message;
+            result = turnOptions
+                ? await execution.runner.injectMessage(sessionId, injectionInput, turnOptions)
+                : await execution.runner.injectMessage(sessionId, injectionInput);
         }
         catch (error) {
-            abandonResponseHandoff?.();
-            await clearStartup("idle");
+            rollbackPendingInput();
+            const failure = execution.runner.lastLiveSessionFailure?.(sessionId)
+                ?? liveSessionFailureFrom(error);
+            const reason = failure?.message
+                ?? (error instanceof Error ? error.message : String(error));
             if (request.clientMessageId) {
-                await Promise.resolve(resources?.markMessageOutcomeUnknown(sessionId, request.clientMessageId, error instanceof Error ? error.message : String(error))).catch(() => undefined);
+                await Promise.resolve(resources?.markMessageOutcomeUnknown(sessionId, request.clientMessageId, reason)).catch(() => undefined);
             }
-            throw new MachineSessionServiceFailure("outcome_unknown", "live injection outcome is unknown");
+            throw new MachineSessionServiceFailure("outcome_unknown", "live injection outcome is unknown", reason, failure);
         }
+        const outcome = result.outcome;
         if (outcome === "failed") {
-            abandonResponseHandoff?.();
-            await clearStartup("idle");
+            rollbackPendingInput();
+            const failure = execution.runner.lastLiveSessionFailure?.(sessionId);
+            const reason = failure?.message
+                ?? execution.runner.lastLiveSessionError?.(sessionId)
+                ?? `live injection ${outcome}`;
+            if (request.clientMessageId) {
+                await resources?.markMessageOutcomeUnknown(sessionId, request.clientMessageId, reason);
+            }
+            throw new MachineSessionServiceFailure("outcome_unknown", `live injection ${outcome}`, reason, failure);
+        }
+        if (outcome !== "injected" && outcome !== "steered") {
+            rollbackPendingInput();
+            const failure = execution.runner.lastLiveSessionFailure?.(sessionId);
+            const reason = failure?.message
+                ?? execution.runner.lastLiveSessionError?.(sessionId)
+                ?? `live injection ${outcome}`;
             if (request.clientMessageId) {
-                await resources?.markMessageOutcomeUnknown(sessionId, request.clientMessageId, `live injection ${outcome}`);
+                await resources?.markMessageFailedNotStarted(sessionId, request.clientMessageId, reason);
             }
-            throw new MachineSessionServiceFailure("outcome_unknown", `live injection ${outcome}`);
+            throw new MachineSessionServiceFailure("failed_precondition", `live injection ${outcome}`, reason, failure);
         }
-        if (outcome !== "injected") {
-            abandonResponseHandoff?.();
-            await clearStartup("idle");
+        onTurnOwned?.();
+        if (signal?.aborted) {
+            await this.ports.interruption.interrupt(sessionId).catch(() => false);
             if (request.clientMessageId) {
-                await resources?.markMessageFailedNotStarted(sessionId, request.clientMessageId, `live injection ${outcome}`);
+                await Promise.resolve(resources?.markMessageInjected(sessionId, request.clientMessageId, result.responseId ? { responseId: result.responseId } : undefined)).catch(() => undefined);
             }
-            throw new MachineSessionServiceFailure("failed_precondition", `live injection ${outcome}`);
+            throw abortReason(signal);
         }
-        await clearStartup("running");
         if (request.clientMessageId) {
             try {
-                await resources?.markMessageInjected(sessionId, request.clientMessageId);
+                await resources?.markMessageInjected(sessionId, request.clientMessageId, result.responseId ? { responseId: result.responseId } : undefined);
             }
             catch {
                 await Promise.resolve(resources?.markMessageOutcomeUnknown(sessionId, request.clientMessageId, "message state could not be persisted after injection")).catch(() => undefined);
                 throw new MachineSessionServiceFailure("outcome_unknown", "message was injected but its delivery state could not be persisted");
             }
         }
-        return { ok: true, injected: true };
+        return {
+            ok: true,
+            injected: true,
+            ...(pendingId ? { pendingId } : {}),
+            ...(includeResponseId && result.responseId ? { responseId: result.responseId } : {}),
+            ...(operationExecution ? { operationExecution } : {}),
+        };
+    }
+    async withSessionMutation(sessionId, action) {
+        const previous = this.sessionMutationTails.get(sessionId);
+        let release;
+        const tail = new Promise((resolve) => {
+            release = resolve;
+        });
+        this.sessionMutationTails.set(sessionId, tail);
+        if (previous)
+            await previous;
+        try {
+            return await action();
+        }
+        finally {
+            release();
+            if (this.sessionMutationTails.get(sessionId) === tail) {
+                this.sessionMutationTails.delete(sessionId);
+            }
+        }
     }
     resourcePolicy(sessionIdInput) {
         const sessionId = this.requireResourceSession(sessionIdInput);
@@ -641,6 +920,62 @@ export class MachineSessionService {
         const sessionId = this.requireResourceSession(input.sessionId);
         return this.requireResources().deleteResource({ ...input, sessionId });
     }
+    async resolveResourcePath(sessionIdInput, resourceId) {
+        const sessionId = this.requireResourceSession(sessionIdInput);
+        const resolve = this.requireResources().resolveCommittedLocalPath;
+        if (!resolve) {
+            throw new MachineSessionServiceFailure("failed_precondition", "Session resource paths are unavailable");
+        }
+        return resolve.call(this.requireResources(), sessionId, resourceId);
+    }
+    async getFile(input) {
+        const resolved = await this.resolveSessionItemFile(input);
+        return { file: resolved.metadata };
+    }
+    async readFile(input) {
+        const resolved = await this.resolveSessionItemFile(input);
+        return this.readResolvedFile(resolved, input);
+    }
+    async getWorkspaceFile(input) {
+        const resolved = await this.resolveSessionWorkspaceFile(input);
+        return { file: resolved.metadata };
+    }
+    async readWorkspaceFile(input) {
+        const resolved = await this.resolveSessionWorkspaceFile(input);
+        return this.readResolvedFile(resolved, input);
+    }
+    async readResolvedFile(resolved, input) {
+        if (resolved.metadata.version !== input.version) {
+            throw new MachineSessionServiceFailure("conflict", "Session file changed while it was being read");
+        }
+        if (input.offset >= resolved.metadata.byteLength) {
+            return { data: "", offset: input.offset, eof: true };
+        }
+        const length = Math.min(input.length, resolved.metadata.byteLength - input.offset);
+        const file = await open(resolved.path, "r");
+        try {
+            const openedStat = await file.stat();
+            if (!openedStat.isFile() ||
+                sessionFileVersion(resolved.path, openedStat) !== resolved.metadata.version) {
+                throw new MachineSessionServiceFailure("conflict", "Session file changed while it was being read");
+            }
+            const buffer = Buffer.allocUnsafe(length);
+            const { bytesRead } = await file.read(buffer, 0, length, input.offset);
+            const completedStat = await file.stat();
+            if (sessionFileVersion(resolved.path, completedStat) !== resolved.metadata.version) {
+                throw new MachineSessionServiceFailure("conflict", "Session file changed while it was being read");
+            }
+            const nextOffset = input.offset + bytesRead;
+            return {
+                data: buffer.subarray(0, bytesRead).toString("base64"),
+                offset: nextOffset,
+                eof: nextOffset >= resolved.metadata.byteLength,
+            };
+        }
+        finally {
+            await file.close();
+        }
+    }
     /** Persist the first task while login/onboarding owns the Provider TUI. The
      * delivery worker starts the pane now, waits for a real native thread, then
      * injects exactly once. `failed` is fenced as outcome_unknown and never retried. */
@@ -688,7 +1023,8 @@ export class MachineSessionService {
             request.execution.runner.ensureLiveSession.bind(request.execution.runner);
         const started = await start(sessionId, request.options);
         if (!started) {
-            throw new MachineSessionServiceFailure("failed_precondition", `Provider terminal unavailable (${request.liveRuntime})`, request.execution.runner.lastLiveSessionError?.(sessionId));
+            const failure = request.execution.runner.lastLiveSessionFailure?.(sessionId);
+            throw new MachineSessionServiceFailure("failed_precondition", `Provider terminal unavailable (${request.liveRuntime})`, failure?.message ?? request.execution.runner.lastLiveSessionError?.(sessionId), failure);
         }
         return { ok: true };
     }
@@ -696,7 +1032,8 @@ export class MachineSessionService {
         const request = await this.liveSessionRequest(sessionId, meta);
         const live = await request.execution.runner.ensureLiveSession(sessionId, request.options);
         if (!live) {
-            throw new MachineSessionServiceFailure("failed_precondition", `live session unavailable (${request.liveRuntime})`, request.execution.runner.lastLiveSessionError?.(sessionId));
+            const failure = request.execution.runner.lastLiveSessionFailure?.(sessionId);
+            throw new MachineSessionServiceFailure("failed_precondition", `live session unavailable (${request.liveRuntime})`, failure?.message ?? request.execution.runner.lastLiveSessionError?.(sessionId), failure);
         }
         return request.execution;
     }
@@ -727,9 +1064,22 @@ export class MachineSessionService {
             throw new MachineSessionServiceFailure("failed_precondition", "Session-owned resources could not be fenced before deletion", error instanceof Error ? error.message : String(error));
         }
         this.cancelledPendingDeliveries.add(sessionId);
-        this.ports.execution?.runner.stopRunner(sessionId);
+        const runner = this.ports.execution?.runner;
+        if (runner?.terminateLiveSession) {
+            try {
+                await runner.terminateLiveSession(sessionId);
+            }
+            catch (error) {
+                console.warn(`[machine-session] session=${sessionId} live teardown failed during deletion; continuing best-effort: ${error instanceof Error ? error.message : String(error)}`);
+                runner.stopRunner(sessionId);
+            }
+        }
+        else {
+            runner?.stopRunner(sessionId);
+        }
         this.ports.events.close?.(sessionId);
         await this.ports.pendingMessages?.delete(sessionId);
+        this.ports.pendingInputs?.deleteSession(sessionId);
         await this.ports.resources?.deleteSession(sessionId);
         this.ports.registry.remove(sessionId);
         await this.ports.log.deleteSession(sessionId);
@@ -743,6 +1093,114 @@ export class MachineSessionService {
         }
         return { ok: true };
     }
+    async resolveSessionItemFile(input) {
+        const sessionId = this.requireResourceSession(input.sessionId);
+        const item = await this.ports.log.get(sessionId, input.itemId);
+        if (!item) {
+            throw new MachineSessionServiceFailure("not_found", "Session item was not found");
+        }
+        let reference;
+        let type;
+        if (item.type === "message" && item.data.role === "user") {
+            const part = item.data.content[input.partIndex];
+            if (!part || (part.type !== "input_image" && part.type !== "input_file")) {
+                throw new MachineSessionServiceFailure("not_found", "Session item file was not found");
+            }
+            reference = part;
+            type = part.type;
+        }
+        else if (item.type === "function_call_output" && input.partIndex === 0) {
+            if (!item.data.generatedImage) {
+                throw new MachineSessionServiceFailure("not_found", "Session item file was not found");
+            }
+            reference = item.data.generatedImage;
+            type = "generated_image";
+        }
+        else {
+            throw new MachineSessionServiceFailure("not_found", "Session item file was not found");
+        }
+        if (!("path" in reference) || !reference.path || !isAbsolute(reference.path)) {
+            throw new MachineSessionServiceFailure("not_found", "Session item is not path-backed");
+        }
+        try {
+            const canonicalPath = await realpath(reference.path);
+            const fileStat = await stat(canonicalPath);
+            if (!fileStat.isFile() || fileStat.size < 1) {
+                throw new MachineSessionServiceFailure("not_found", "Session item path is not a file");
+            }
+            const modifiedAt = Math.max(0, Math.trunc(fileStat.mtimeMs));
+            const version = sessionFileVersion(canonicalPath, fileStat);
+            return {
+                path: canonicalPath,
+                metadata: {
+                    itemId: item.id,
+                    partIndex: input.partIndex,
+                    type,
+                    filename: reference.filename || basename(canonicalPath),
+                    mediaType: reference.mediaType,
+                    byteLength: fileStat.size,
+                    modifiedAt,
+                    version,
+                },
+            };
+        }
+        catch (error) {
+            if (error instanceof MachineSessionServiceFailure)
+                throw error;
+            throw new MachineSessionServiceFailure("not_found", "Session item file is unavailable", error instanceof Error ? error.message : String(error));
+        }
+    }
+    async resolveSessionWorkspaceFile(input) {
+        const sessionId = this.requireResourceSession(input.sessionId);
+        const session = this.ports.registry.get(sessionId);
+        try {
+            const workspaceRoot = await realpath(session.workspace.cwd).catch(() => undefined);
+            const requestedPath = isAbsolute(input.path)
+                ? input.path
+                : resolve(workspaceRoot ?? session.workspace.cwd, input.path);
+            const canonicalPath = await realpath(requestedPath);
+            let allowed = false;
+            for (const directory of new Set([session.workspace.cwd, ...session.workspace.allowedDirs])) {
+                // An unavailable root, including cwd, must not hide files in other roots.
+                const root = directory === session.workspace.cwd
+                    ? workspaceRoot
+                    : await realpath(directory).catch(() => undefined);
+                if (!root)
+                    continue;
+                const workspaceRelative = relative(root, canonicalPath);
+                if (workspaceRelative &&
+                    workspaceRelative !== ".." &&
+                    !workspaceRelative.startsWith(`..${sep}`) &&
+                    !isAbsolute(workspaceRelative)) {
+                    allowed = true;
+                    break;
+                }
+            }
+            if (!allowed) {
+                throw new MachineSessionServiceFailure("not_found", "Session workspace file was not found");
+            }
+            const fileStat = await stat(canonicalPath);
+            if (!fileStat.isFile()) {
+                throw new MachineSessionServiceFailure("not_found", "Session workspace path is not a file");
+            }
+            return {
+                path: canonicalPath,
+                metadata: {
+                    path: input.path,
+                    filename: basename(canonicalPath),
+                    mediaType: workspaceFileMediaType(canonicalPath),
+                    byteLength: fileStat.size,
+                    modifiedAt: Math.max(0, Math.trunc(fileStat.mtimeMs)),
+                    version: sessionFileVersion(canonicalPath, fileStat),
+                },
+            };
+        }
+        catch (error) {
+            if (error instanceof MachineSessionServiceFailure)
+                throw error;
+            throw new MachineSessionServiceFailure("not_found", "Session workspace file is unavailable", error instanceof Error ? error.message : String(error));
+        }
+    }
     requireAgents() {
         if (!this.ports.agents) {
             throw new MachineSessionServiceFailure("failed_precondition", "session agent options are unavailable");
@@ -831,8 +1289,8 @@ export class MachineSessionService {
                     current.message !== pending.message)
                     return;
                 injectionAttempted = true;
-                const outcome = await execution.runner.injectMessage(sessionId, pending.message);
-                if (outcome === "injected") {
+                const { outcome } = await execution.runner.injectMessage(sessionId, pending.message);
+                if (outcome === "injected" || outcome === "steered") {
                     await Promise.resolve(pendingStore.delete(sessionId)).catch(async () => {
                         await Promise.resolve(pendingStore.markOutcomeUnknown(sessionId)).catch(() => undefined);
                     });
@@ -1020,10 +1478,11 @@ function decodeListCursor(value) {
         throw new MachineSessionServiceInputError("cursor is invalid");
     }
 }
-function snapshotPage(sessionId, items, runtime, hasMore) {
+function snapshotPage(sessionId, items, pendingInputs, runtime, hasMore) {
     return {
         sessionId,
         items,
+        pendingInputs,
         runtime,
         hasMore,
         ...(hasMore && items.length > 0 ? { nextAfterId: items.at(-1).id } : {}),
@@ -1031,10 +1490,10 @@ function snapshotPage(sessionId, items, runtime, hasMore) {
 }
 /** Exact UTF-8 size of {@link snapshotPage} without repeatedly serializing the
  * complete item array while searching for a page boundary. */
-function snapshotPageJsonByteLength(sessionId, itemsJsonBytes, finalItemId, runtime, hasMore) {
+function snapshotPageJsonByteLength(sessionId, itemsJsonBytes, finalItemId, pendingInputs, runtime, hasMore) {
     return Buffer.byteLength(`{"sessionId":${JSON.stringify(sessionId)},"items":[`, "utf8")
         + itemsJsonBytes
-        + Buffer.byteLength(`],"runtime":${JSON.stringify(runtime)},"hasMore":${hasMore}${hasMore ? `,"nextAfterId":${JSON.stringify(finalItemId)}` : ""}}`, "utf8");
+        + Buffer.byteLength(`],"pendingInputs":${JSON.stringify(pendingInputs)},"runtime":${JSON.stringify(runtime)},"hasMore":${hasMore}${hasMore ? `,"nextAfterId":${JSON.stringify(finalItemId)}` : ""}}`, "utf8");
 }
 function sessionSummary(id, meta, log, runtimeState, pendingState) {
     const createdAt = meta?.createdAt ?? timestampFromEpoch(log?.createdAt, "createdAt");
@@ -1063,6 +1522,7 @@ function executionSettingsResult(execution) {
         provider: execution.provider,
         model: execution.model,
         reasoningEffort: execution.reasoningEffort,
+        collaborationMode: execution.collaborationMode ?? null,
     };
 }
 function compareMetaRecency(left, right) {
@@ -1134,6 +1594,9 @@ function cancellableWatch(sessionId, iterator, signal) {
 function cloneRuntimeSnapshot(snapshot) {
     return {
         status: snapshot.status,
+        ...(snapshot.backgroundTaskCount === undefined
+            ? {}
+            : { backgroundTaskCount: snapshot.backgroundTaskCount }),
         activeResponseIds: [...snapshot.activeResponseIds],
         pendingInteractions: snapshot.pendingInteractions.map((pending) => ({
             responseId: pending.responseId,
@@ -1141,6 +1604,125 @@ function cloneRuntimeSnapshot(snapshot) {
         })),
     };
 }
+function sessionEventResponseId(event) {
+    if ("responseId" in event && typeof event.responseId === "string")
+        return event.responseId;
+    if ("item" in event && event.item && typeof event.item.responseId === "string") {
+        return event.item.responseId;
+    }
+    return undefined;
+}
+function sessionEventItemId(event) {
+    return "item" in event && event.item && typeof event.item.id === "string"
+        ? event.item.id
+        : undefined;
+}
+function responseIdForClearedPending(event, pendingId) {
+    return event.type === "session.input.consumed" && event.clearedPendingId === pendingId
+        ? event.item.responseId
+        : undefined;
+}
+function isTerminalResponseEvent(event) {
+    return event.type === "response.completed" ||
+        event.type === "response.failed" ||
+        event.type === "session.interrupted";
+}
+function replaySessionItem(item) {
+    if (item.type === "message" && item.data.role === "user") {
+        return { type: "session.input.consumed", item };
+    }
+    if (item.type === "interaction_request") {
+        return {
+            type: "session.interaction.requested",
+            sessionId: item.sessionId,
+            responseId: item.responseId,
+            interaction: item.data.interaction,
+            item,
+        };
+    }
+    if (item.type === "interaction_resolution" &&
+        item.data.status === "resolved" &&
+        item.data.resolution) {
+        return {
+            type: "session.interaction.resolved",
+            sessionId: item.sessionId,
+            responseId: item.responseId,
+            interactionId: item.data.interactionId,
+            resolution: item.data.resolution,
+            item,
+        };
+    }
+    if (item.type === "interaction_resolution" &&
+        (item.data.status === "cancelled" || item.data.status === "expired")) {
+        const reason = item.data.reason ?? (item.data.status === "expired" ? "expired" : undefined);
+        return {
+            type: "session.interaction.cancelled",
+            sessionId: item.sessionId,
+            responseId: item.responseId,
+            interactionId: item.data.interactionId,
+            ...(reason ? { reason } : {}),
+            item,
+        };
+    }
+    return { type: "response.output_item.done", responseId: item.responseId, item };
+}
+function normalizeRunExecutionSelection(value) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new MachineSessionServiceInputError("execution must be an object");
+    }
+    if (Object.keys(value).some((key) => key !== "model" && key !== "reasoningEffort")) {
+        throw new MachineSessionServiceInputError("execution has unknown fields");
+    }
+    const selection = {};
+    if (Object.prototype.hasOwnProperty.call(value, "model")) {
+        selection.model = value.model === null
+            ? null
+            : validRequiredText(value.model, "execution.model");
+    }
+    if (Object.prototype.hasOwnProperty.call(value, "reasoningEffort")) {
+        selection.reasoningEffort = value.reasoningEffort === null
+            ? null
+            : validRequiredText(value.reasoningEffort, "execution.reasoningEffort");
+    }
+    return selection;
+}
+function abortReason(signal) {
+    if (signal.reason instanceof Error)
+        return signal.reason;
+    const error = new Error("run was cancelled");
+    error.name = "AbortError";
+    return error;
+}
+function liveSessionFailureFrom(error) {
+    if (!error || typeof error !== "object")
+        return undefined;
+    const candidate = error;
+    if (typeof candidate.message !== "string" ||
+        typeof candidate.code !== "string" ||
+        typeof candidate.statusCode !== "number")
+        return undefined;
+    return {
+        message: candidate.message,
+        code: candidate.code,
+        statusCode: candidate.statusCode,
+    };
+}
+/** Turn structured native mode failures into actionable, Provider-specific
+ * messages before the Direct Runtime adapter crosses the process boundary.
+ * Unstructured failures keep their original text and remain subject to the
+ * adapter's normal redaction policy. */
+function collaborationModeFailureMessage(provider, failure, fallback) {
+    const providerLabel = provider === "traex" ? "TraeX" : "Codex";
+    if (failure?.code === "native_session_not_live") {
+        return `No live ${providerLabel} runner is available. Reconnect this Session and try again.`;
+    }
+    if (failure?.code === "native_thread_not_ready") {
+        return `${providerLabel} is still loading its native thread. Reconnect this Session and try again.`;
+    }
+    return failure?.message ?? fallback;
+}
 function requestLimit(value, fallback, maximum, field) {
     return value === undefined ? Math.min(fallback, maximum) : boundedInteger(value, 1, maximum, field);
 }
@@ -1180,6 +1762,54 @@ function timestampFromEpoch(value, field) {
     }
     return new Date(value).toISOString();
 }
+function sessionFileVersion(path, fileStat) {
+    return createHash("sha256")
+        .update(`${path}\0${fileStat.dev}\0${fileStat.ino}\0${fileStat.size}\0${fileStat.mtimeMs}\0${fileStat.ctimeMs}`)
+        .digest("hex");
+}
+function workspaceFileMediaType(path) {
+    switch (extname(path).toLowerCase()) {
+        case ".png": return "image/png";
+        case ".jpg":
+        case ".jpeg": return "image/jpeg";
+        case ".webp": return "image/webp";
+        case ".gif": return "image/gif";
+        case ".svg": return "image/svg+xml";
+        case ".pdf": return "application/pdf";
+        case ".json": return "application/json";
+        case ".html":
+        case ".htm": return "text/html";
+        case ".css": return "text/css";
+        case ".js":
+        case ".mjs":
+        case ".cjs": return "text/javascript";
+        case ".md":
+        case ".mdx": return "text/markdown";
+        case ".csv": return "text/csv";
+        case ".tsv": return "text/tab-separated-values";
+        case ".txt":
+        case ".log":
+        case ".ts":
+        case ".tsx":
+        case ".jsx":
+        case ".py":
+        case ".go":
+        case ".rs":
+        case ".java":
+        case ".c":
+        case ".cc":
+        case ".cpp":
+        case ".h":
+        case ".hpp":
+        case ".sh":
+        case ".zsh":
+        case ".bash":
+        case ".yaml":
+        case ".yml":
+        case ".toml": return "text/plain";
+        default: return "application/octet-stream";
+    }
+}
 function jsonByteLength(value) {
     return Buffer.byteLength(JSON.stringify(value), "utf8");
 }