@rynx-ai/server 0.1.11-beta.3 → 0.1.11-beta.30

package/dist/machine-session-service.js

@@ -7,8 +7,10 @@
  * 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 { 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 +33,12 @@ export class MachineSessionServiceInputError extends Error {
 export class MachineSessionServiceFailure extends Error {
     code;
     detail;
-    constructor(code, message, detail) {
+    runtimeFailure;
+    constructor(code, message, detail, runtimeFailure) {
         super(message);
         this.code = code;
         this.detail = detail;
+        this.runtimeFailure = runtimeFailure;
         this.name = "MachineSessionServiceFailure";
     }
 }
@@ -52,6 +56,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");
@@ -159,11 +164,18 @@ export class MachineSessionService {
         const statusCache = new Map();
         const { agents } = await this.agentOptions();
         const [providers, launchAgents] = await Promise.all([
-            Promise.all(SESSION_PROVIDER_IDS.map(async (provider) => ({
-                id: provider,
-                name: getRuntimeProfile(provider).displayName,
-                ...await this.runtimeReadiness(provider, statusCache),
-            }))),
+            Promise.all(SESSION_PROVIDER_IDS.map(async (provider) => {
+                const execution = this.ports.execution;
+                const models = execution?.listModels
+                    ? await execution.listModels(provider).catch(() => [])
+                    : undefined;
+                return {
+                    id: provider,
+                    name: getRuntimeProfile(provider).displayName,
+                    ...await this.runtimeReadiness(provider, statusCache),
+                    ...(models === undefined ? {} : { models }),
+                };
+            })),
             Promise.all(agents.map(async (agent) => {
                 const execution = this.ports.execution;
                 if (!execution) {
@@ -192,6 +204,97 @@ export class MachineSessionService {
         ]);
         return { providers, agents: launchAgents };
     }
+    /** Read the effective model defaults used for the next turn. */
+    async executionSettings(sessionIdInput) {
+        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");
+        }
+        return executionSettingsResult(meta.execution);
+    }
+    /** 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 = input.model === null ? null : validRequiredText(input.model, "model");
+        const reasoningEffort = input.reasoningEffort === null
+            ? null
+            : validRequiredText(input.reasoningEffort, "reasoningEffort");
+        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: 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,
+                });
+            }
+            // Omnigent parity: 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);
+        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) {
         return this.withAdmission(() => this.createAdmitted(input));
@@ -223,6 +326,7 @@ export class MachineSessionService {
                 ...target,
                 ...(input.model === undefined ? {} : { model: input.model }),
                 ...(input.reasoningEffort === undefined ? {} : { reasoningEffort: input.reasoningEffort }),
+                ...(input.permissionPreset === undefined ? {} : { permissionPreset: input.permissionPreset }),
                 cwd: workspace.cwd,
             });
             const sessionId = newSessionId();
@@ -395,8 +499,122 @@ 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);
+                if (!result.responseId) {
+                    throw new MachineSessionServiceFailure("outcome_unknown", "run was already accepted but its response stream is unavailable");
+                }
+                const responseId = result.responseId;
+                const replayItems = result.replayed
+                    ? (await this.ports.log.snapshot(sessionId)).filter((item) => item.responseId === responseId)
+                    : [];
+                const replayedItemIds = new Set(replayItems.map((item) => item.id));
+                const replayWasActive = this.ports.runtimeState
+                    .snapshot(sessionId)
+                    .activeResponseIds.includes(responseId);
+                if (result.replayed && !replayWasActive) {
+                    throw new MachineSessionServiceFailure("outcome_unknown", "run was already accepted but its terminal event is no longer available");
+                }
+                if (result.replayed) {
+                    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;
+                const generator = (async function* () {
+                    try {
+                        if (result.replayed) {
+                            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 (sessionEventResponseId(event) !== responseId)
+                                continue;
+                            const itemId = sessionEventItemId(event);
+                            if (itemId && replayedItemIds.has(itemId))
+                                continue;
+                            yield event;
+                            if (event.type === "response.completed" || event.type === "response.failed")
+                                return;
+                        }
+                    }
+                    finally {
+                        options.signal?.removeEventListener("abort", interrupt);
+                        unsteer?.();
+                        await subscription.return?.();
+                    }
+                })();
+                const provider = meta.execution.provider;
+                return {
+                    responseId,
+                    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 }
@@ -412,7 +630,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;
@@ -428,14 +663,24 @@ 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 };
+                return {
+                    ok: true,
+                    injected: true,
+                    ...(includeResponseId && prepared.responseId
+                        ? { responseId: prepared.responseId }
+                        : {}),
+                    ...(prepared.operationExecution
+                        ? { operationExecution: prepared.operationExecution }
+                        : {}),
+                    replayed: true,
+                };
             }
         }
         else {
@@ -449,108 +694,123 @@ 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;
         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");
+            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");
+            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?.markMessageOutcomeUnknown(sessionId, request.clientMessageId, reason);
             }
-            throw new MachineSessionServiceFailure("outcome_unknown", `live injection ${outcome}`);
+            throw new MachineSessionServiceFailure("outcome_unknown", `live injection ${outcome}`, reason, failure);
         }
-        if (outcome !== "injected") {
-            abandonResponseHandoff?.();
-            await clearStartup("idle");
+        if (outcome !== "injected" && outcome !== "steered") {
+            const failure = execution.runner.lastLiveSessionFailure?.(sessionId);
+            const reason = failure?.message
+                ?? execution.runner.lastLiveSessionError?.(sessionId)
+                ?? `live injection ${outcome}`;
             if (request.clientMessageId) {
-                await resources?.markMessageFailedNotStarted(sessionId, request.clientMessageId, `live injection ${outcome}`);
+                await resources?.markMessageFailedNotStarted(sessionId, request.clientMessageId, reason);
             }
-            throw new MachineSessionServiceFailure("failed_precondition", `live injection ${outcome}`);
+            throw new MachineSessionServiceFailure("failed_precondition", `live injection ${outcome}`, reason, failure);
+        }
+        onTurnOwned?.();
+        if (signal?.aborted) {
+            await this.ports.interruption.interrupt(sessionId).catch(() => false);
+            if (request.clientMessageId) {
+                await Promise.resolve(resources?.markMessageInjected(sessionId, request.clientMessageId, result.responseId ? { responseId: result.responseId } : undefined)).catch(() => undefined);
+            }
+            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,
+            ...(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);
@@ -580,6 +840,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. */
@@ -627,7 +943,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 };
     }
@@ -635,7 +952,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;
     }
@@ -682,6 +1000,101 @@ 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);
+            const requestedPath = isAbsolute(input.path)
+                ? input.path
+                : resolve(workspaceRoot, input.path);
+            const canonicalPath = await realpath(requestedPath);
+            const workspaceRelative = relative(workspaceRoot, canonicalPath);
+            if (!workspaceRelative ||
+                workspaceRelative === ".." ||
+                workspaceRelative.startsWith(`..${sep}`) ||
+                isAbsolute(workspaceRelative)) {
+                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");
@@ -770,8 +1183,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);
                     });
@@ -997,6 +1410,14 @@ function sessionSummary(id, meta, log, runtimeState, pendingState) {
         updatedAt: validTimestamp(updatedAt, "updatedAt"),
     };
 }
+function executionSettingsResult(execution) {
+    return {
+        provider: execution.provider,
+        model: execution.model,
+        reasoningEffort: execution.reasoningEffort,
+        collaborationMode: execution.collaborationMode ?? null,
+    };
+}
 function compareMetaRecency(left, right) {
     const leftTime = validTimestamp(left.updatedAt ?? left.createdAt, "updatedAt");
     const rightTime = validTimestamp(right.updatedAt ?? right.createdAt, "updatedAt");
@@ -1066,6 +1487,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,
@@ -1073,6 +1497,115 @@ 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 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);
 }
@@ -1091,6 +1624,15 @@ function validOpaqueToken(value, field, maximum) {
     }
     return value;
 }
+function validRequiredText(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0 || value.length > 512) {
+        throw new MachineSessionServiceInputError(`${field} must be a non-empty string of at most 512 characters`);
+    }
+    if (/[\u0000-\u001f\u007f]/.test(value)) {
+        throw new MachineSessionServiceInputError(`${field} contains invalid control characters`);
+    }
+    return value.trim();
+}
 function validTimestamp(value, field) {
     if (typeof value !== "string" || !Number.isFinite(Date.parse(value))) {
         throw new MachineSessionServiceInputError(`${field} must be a valid timestamp`);
@@ -1103,6 +1645,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");
 }