@rynx-ai/server 0.1.11-beta.24 → 0.1.11-beta.26

package/dist/machine-session-service.js

@@ -8,6 +8,8 @@
  * into a Control Plane database.
  */
 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;
@@ -54,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");
@@ -218,11 +221,20 @@ export class MachineSessionService {
     async updateExecutionSettings(input) {
         const sessionId = validOpaqueToken(input.sessionId, "sessionId", MAX_SESSION_ID_CHARS);
         const modelId = input.model === null ? null : 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 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);
@@ -234,19 +246,54 @@ export class MachineSessionService {
             }
         }
         const executionPort = this.requireExecution();
-        const reasoningEffort = input.reasoningEffort === null
-            ? null
-            : validRequiredText(input.reasoningEffort, "reasoningEffort");
         const nextExecution = {
             ...structuredClone(meta.execution),
-            model: modelId,
-            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,
+                });
+            }
+            // 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 executionSettingsResult(nextExecution);
+        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) {
@@ -452,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 }
@@ -469,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;
@@ -485,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 {
@@ -506,10 +694,24 @@ 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);
         }
@@ -523,9 +725,18 @@ export class MachineSessionService {
             }
             throw error;
         }
+        if (signal?.aborted) {
+            if (request.clientMessageId) {
+                await resources?.markMessageFailedNotStarted(sessionId, request.clientMessageId, "run was cancelled before injection");
+            }
+            throw abortReason(signal);
+        }
         let result;
         try {
-            result = await execution.runner.injectMessage(sessionId, needsPreparedOperation ? prepared.input : 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) {
             const failure = execution.runner.lastLiveSessionFailure?.(sessionId)
@@ -558,16 +769,48 @@ export class MachineSessionService {
             }
             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);
+        }
         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);
@@ -597,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. */
@@ -701,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");
@@ -1021,6 +1415,7 @@ function executionSettingsResult(execution) {
         provider: execution.provider,
         model: execution.model,
         reasoningEffort: execution.reasoningEffort,
+        collaborationMode: execution.collaborationMode ?? null,
     };
 }
 function compareMetaRecency(left, right) {
@@ -1092,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,
@@ -1099,6 +1497,87 @@ 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;
@@ -1113,6 +1592,20 @@ function liveSessionFailureFrom(error) {
         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);
 }
@@ -1152,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");
 }