@rynx-ai/server 0.1.0 → 0.1.10-beta.2

package/dist/machine-session-service.js

@@ -0,0 +1,822 @@
+/**
+ * Daemon-owned application service for the first Remote Runtime Session slice.
+ *
+ * This service deliberately has no HTTP, Koa, WebSocket, or Direct-binding
+ * knowledge. Durable records, live state, events, and interruption remain owned
+ * by the daemon process and arrive through narrow injected ports. Local and
+ * Direct adapters can therefore expose the same behavior without copying state
+ * into a Control Plane database.
+ */
+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";
+import { ensureCodexResumeRollout, } from "@rynx-ai/runtime";
+const DEFAULT_LIST_LIMIT = REMOTE_RUNTIME_SESSION_DEFAULT_PAGE_SIZE;
+const MAX_LIST_LIMIT = REMOTE_RUNTIME_SESSION_MAX_PAGE_SIZE;
+const DEFAULT_SNAPSHOT_ITEM_LIMIT = REMOTE_RUNTIME_SESSION_DEFAULT_PAGE_SIZE;
+const MAX_SNAPSHOT_ITEM_LIMIT = REMOTE_RUNTIME_SESSION_MAX_PAGE_SIZE;
+const DEFAULT_LIST_PAGE_MAX_BYTES = 48 * 1024;
+const DEFAULT_SNAPSHOT_PAGE_MAX_BYTES = 48 * 1024;
+const MIN_PAGE_MAX_BYTES = 4 * 1024;
+const MAX_PAGE_MAX_BYTES = 56 * 1024;
+const DEFAULT_DIRECTORY_SCAN_LIMIT = 10_000;
+const MAX_DIRECTORY_SCAN_LIMIT = 100_000;
+const MAX_SESSION_ID_CHARS = REMOTE_RUNTIME_SESSION_MAX_ID_CHARS;
+export class MachineSessionServiceInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MachineSessionServiceInputError";
+    }
+}
+/** Expected application failure; adapters decide how to represent it on the wire. */
+export class MachineSessionServiceFailure extends Error {
+    code;
+    detail;
+    constructor(code, message, detail) {
+        super(message);
+        this.code = code;
+        this.detail = detail;
+        this.name = "MachineSessionServiceFailure";
+    }
+}
+/** Application boundary shared by an in-process Local adapter and Direct RPC. */
+export class MachineSessionService {
+    ports;
+    maxListLimit;
+    listPageMaxBytes;
+    maxSnapshotItemLimit;
+    snapshotPageMaxBytes;
+    directoryScanLimit;
+    pendingMessageRetryMs;
+    pendingDeliveries = new Map();
+    cancelledPendingDeliveries = new Set();
+    constructor(ports, options = {}) {
+        this.ports = ports;
+        this.maxListLimit = boundedInteger(options.maxListLimit ?? MAX_LIST_LIMIT, 1, MAX_LIST_LIMIT, "maxListLimit");
+        this.listPageMaxBytes = boundedInteger(options.listPageMaxBytes ?? DEFAULT_LIST_PAGE_MAX_BYTES, MIN_PAGE_MAX_BYTES, MAX_PAGE_MAX_BYTES, "listPageMaxBytes");
+        this.maxSnapshotItemLimit = boundedInteger(options.maxSnapshotItemLimit ?? MAX_SNAPSHOT_ITEM_LIMIT, 1, MAX_SNAPSHOT_ITEM_LIMIT, "maxSnapshotItemLimit");
+        this.snapshotPageMaxBytes = boundedInteger(options.snapshotPageMaxBytes ?? DEFAULT_SNAPSHOT_PAGE_MAX_BYTES, MIN_PAGE_MAX_BYTES, MAX_PAGE_MAX_BYTES, "snapshotPageMaxBytes");
+        this.directoryScanLimit = boundedInteger(options.directoryScanLimit ?? DEFAULT_DIRECTORY_SCAN_LIMIT, 1, MAX_DIRECTORY_SCAN_LIMIT, "directoryScanLimit");
+        this.pendingMessageRetryMs = boundedInteger(options.pendingMessageRetryMs ?? 1_000, 10, 60_000, "pendingMessageRetryMs");
+        void this.resumePendingDeliveries();
+    }
+    async list(input = {}) {
+        const limit = requestLimit(input.limit, DEFAULT_LIST_LIMIT, this.maxListLimit, "limit");
+        const cursor = input.cursor === undefined
+            ? undefined
+            : decodeListCursor(input.cursor);
+        const allMetas = this.ports.registry.list();
+        const metas = [...allMetas]
+            .sort(compareMetaRecency)
+            .slice(0, this.directoryScanLimit);
+        const [logged, pendingMessages] = await Promise.all([
+            this.ports.log.listSessions({ limit: this.directoryScanLimit + 1 }),
+            this.ports.pendingMessages?.list() ?? [],
+        ]);
+        const directoryTruncated = allMetas.length > this.directoryScanLimit || logged.length > this.directoryScanLimit;
+        const boundedLogs = logged.slice(0, this.directoryScanLimit);
+        const metaById = new Map(metas.map((meta) => [meta.id, meta]));
+        const logById = new Map(boundedLogs.map((entry) => [entry.sessionId, entry]));
+        const pendingById = new Map(pendingMessages.map((entry) => [entry.sessionId, entry.state]));
+        const ids = new Set([...metaById.keys(), ...logById.keys()]);
+        const summaries = [...ids]
+            .map((id) => sessionSummary(id, metaById.get(id), logById.get(id), this.ports.runtimeState, pendingById.get(id)))
+            .sort(compareSummaryRecency);
+        const afterCursor = cursor === undefined
+            ? summaries
+            : summaries.filter((summary) => isAfterListCursor(summary, cursor));
+        const page = afterCursor.slice(0, limit);
+        while (page.length > 0) {
+            const result = listPage(page, afterCursor.length > page.length, directoryTruncated);
+            if (page.length === 1 || jsonByteLength(result) <= this.listPageMaxBytes)
+                return result;
+            page.pop();
+        }
+        return listPage([], false, directoryTruncated);
+    }
+    async snapshot(input) {
+        const sessionId = validOpaqueToken(input.sessionId, "sessionId", MAX_SESSION_ID_CHARS);
+        const afterId = input.afterId === undefined
+            ? undefined
+            : validOpaqueToken(input.afterId, "afterId", MAX_SESSION_ID_CHARS);
+        const limit = requestLimit(input.limit, DEFAULT_SNAPSHOT_ITEM_LIMIT, this.maxSnapshotItemLimit, "limit");
+        const candidates = (await this.ports.log.list(sessionId, {
+            ...(afterId === undefined ? {} : { afterId }),
+            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 items = candidates.slice(0, limit);
+        while (items.length > 0) {
+            const result = snapshotPage(sessionId, items, runtime, candidates.length > items.length);
+            if (items.length === 1 || jsonByteLength(result) <= this.snapshotPageMaxBytes)
+                return result;
+            items.pop();
+        }
+        return empty;
+    }
+    /**
+     * Install a live subscriber synchronously, before returning control to an
+     * adapter. The adapter may now acknowledge readiness and request snapshot
+     * pages while buffering this tail, closing the subscribe/snapshot race.
+     */
+    watch(sessionIdInput, options = {}) {
+        const sessionId = validOpaqueToken(sessionIdInput, "sessionId", MAX_SESSION_ID_CHARS);
+        const iterator = this.ports.events.subscribe(sessionId)[Symbol.asyncIterator]();
+        return cancellableWatch(sessionId, iterator, options.signal);
+    }
+    async interrupt(sessionIdInput) {
+        const sessionId = validOpaqueToken(sessionIdInput, "sessionId", MAX_SESSION_ID_CHARS);
+        return { interrupted: await this.ports.interruption.interrupt(sessionId) };
+    }
+    /** Session-scoped projection of the target daemon's own Agent catalog. */
+    async agentOptions() {
+        const catalog = this.requireAgents();
+        const agents = (await catalog.list()).map((agent) => ({
+            id: agent.id,
+            ...(agent.name === undefined ? {} : { name: agent.name }),
+            ...(agent.runtime === undefined ? {} : { runtime: agent.runtime }),
+            ...(agent.model === undefined ? {} : { model: agent.model }),
+        }));
+        agents.sort((left, right) => (left.name ?? left.id).localeCompare(right.name ?? right.id) || left.id.localeCompare(right.id));
+        return { agents };
+    }
+    /** Target-owned Provider readiness plus the existing Agent preset catalog. */
+    async launchOptions() {
+        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(agents.map(async (agent) => {
+                const execution = this.ports.execution;
+                if (!execution) {
+                    return {
+                        ...agent,
+                        ready: false,
+                        reason: "Session execution is unavailable on this Runtime.",
+                    };
+                }
+                try {
+                    const runtime = await execution.runtime.resolveRuntime({ agentName: agent.id });
+                    return {
+                        ...agent,
+                        runtime,
+                        ...await this.runtimeReadiness(runtime, statusCache),
+                    };
+                }
+                catch {
+                    return {
+                        ...agent,
+                        ready: false,
+                        reason: "Agent execution settings could not be resolved.",
+                    };
+                }
+            })),
+        ]);
+        return { providers, agents: launchAgents };
+    }
+    /** Create target-owned Session identity from one Agent preset or direct Provider. */
+    async create(input) {
+        const hasAgent = input.agent !== undefined;
+        const hasProvider = input.provider !== undefined;
+        if (hasAgent === hasProvider) {
+            throw new MachineSessionServiceInputError("exactly one of agent or provider is required");
+        }
+        let target;
+        if (hasAgent) {
+            const agent = validOpaqueToken(input.agent, "agent", MAX_SESSION_ID_CHARS);
+            const known = (await this.requireAgents().list()).some((candidate) => candidate.id === agent);
+            if (!known)
+                throw new MachineSessionServiceFailure("not_found", "agent not found");
+            target = { agent };
+        }
+        else {
+            if (!isSessionProviderId(input.provider)) {
+                throw new MachineSessionServiceInputError("provider must be codex, traex, or claude");
+            }
+            target = { provider: input.provider };
+        }
+        const sessionId = newSessionId();
+        this.ports.registry.create({
+            id: sessionId,
+            source: "console",
+            ...target,
+            ...(input.model === undefined ? {} : { model: input.model }),
+            ...(input.reasoningEffort === undefined ? {} : { reasoningEffort: input.reasoningEffort }),
+            ...(input.title === undefined ? {} : { title: input.title }),
+            createdAt: new Date().toISOString(),
+        });
+        return { sessionId };
+    }
+    /** Inject one turn through the target daemon's native single-writer runner. */
+    async sendMessage(sessionIdInput, messageInput) {
+        const sessionId = validOpaqueToken(sessionIdInput, "sessionId", MAX_SESSION_ID_CHARS);
+        const request = typeof messageInput === "string"
+            ? { message: messageInput }
+            : messageInput;
+        const hasMessage = request.message !== undefined;
+        const hasContent = request.content !== undefined;
+        if (hasMessage === hasContent) {
+            throw new MachineSessionServiceInputError("provide exactly one of message or content");
+        }
+        if (hasMessage && (typeof request.message !== "string" || request.message.length === 0)) {
+            throw new MachineSessionServiceInputError("message must be a non-empty string");
+        }
+        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);
+        const consoleMeta = meta?.source === "console" ? meta : undefined;
+        let prepared;
+        const needsPreparedOperation = hasContent || request.clientMessageId !== undefined;
+        if (needsPreparedOperation) {
+            const resources = this.ports.resources;
+            if (!resources) {
+                throw new MachineSessionServiceFailure("failed_precondition", "Session resources are unavailable");
+            }
+            if (hasContent &&
+                request.content.some((part) => part.type === "input_image") &&
+                !request.clientMessageId) {
+                throw new MachineSessionServiceInputError("clientMessageId is required for image input");
+            }
+            prepared = await resources.prepareInput(sessionId, hasContent
+                ? request.content
+                : [{ type: "input_text", text: request.message }], request.clientMessageId);
+            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 };
+            }
+        }
+        else {
+            prepared = {
+                input: {
+                    content: [{ type: "text", text: request.message }],
+                    ...(request.clientMessageId
+                        ? { clientMessageId: request.clientMessageId }
+                        : {}),
+                },
+                title: request.message,
+            };
+        }
+        if (consoleMeta && !consoleMeta.title) {
+            this.ports.registry.setTitle(sessionId, synthesizeSessionTitle(prepared.title));
+        }
+        const resources = this.ports.resources;
+        if (request.clientMessageId) {
+            await resources?.markMessageInjecting(sessionId, request.clientMessageId);
+        }
+        let execution;
+        try {
+            execution = await this.ensureLiveSession(sessionId, meta);
+        }
+        catch (error) {
+            if (request.clientMessageId) {
+                await resources?.markMessageFailedNotStarted(sessionId, request.clientMessageId, error instanceof Error ? error.message : String(error));
+            }
+            throw error;
+        }
+        let outcome;
+        try {
+            outcome = await execution.runner.injectMessage(sessionId, hasMessage && !needsPreparedOperation ? request.message : prepared.input);
+        }
+        catch (error) {
+            if (request.clientMessageId) {
+                await Promise.resolve(resources?.markMessageOutcomeUnknown(sessionId, request.clientMessageId, error instanceof Error ? error.message : String(error))).catch(() => undefined);
+            }
+            throw new MachineSessionServiceFailure("outcome_unknown", "live injection outcome is unknown");
+        }
+        if (outcome === "failed") {
+            if (request.clientMessageId) {
+                await resources?.markMessageOutcomeUnknown(sessionId, request.clientMessageId, `live injection ${outcome}`);
+            }
+            throw new MachineSessionServiceFailure("outcome_unknown", `live injection ${outcome}`);
+        }
+        if (outcome !== "injected") {
+            if (request.clientMessageId) {
+                await resources?.markMessageFailedNotStarted(sessionId, request.clientMessageId, `live injection ${outcome}`);
+            }
+            throw new MachineSessionServiceFailure("failed_precondition", `live injection ${outcome}`);
+        }
+        if (request.clientMessageId) {
+            try {
+                await resources?.markMessageInjected(sessionId, request.clientMessageId);
+            }
+            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 };
+    }
+    resourcePolicy(sessionIdInput) {
+        const sessionId = this.requireResourceSession(sessionIdInput);
+        return this.requireResources().policy(sessionId);
+    }
+    async beginResourceUpload(input) {
+        const sessionId = this.requireResourceSession(input.sessionId);
+        return this.requireResources().beginUpload({ ...input, sessionId });
+    }
+    async writeResourceUploadChunk(input) {
+        const sessionId = this.requireResourceSession(input.sessionId);
+        return this.requireResources().writeUploadChunk({ ...input, sessionId });
+    }
+    async commitResourceUpload(input) {
+        const sessionId = this.requireResourceSession(input.sessionId);
+        return this.requireResources().commitUpload({ ...input, sessionId });
+    }
+    async getResource(input) {
+        const sessionId = this.requireResourceSession(input.sessionId);
+        return this.requireResources().getResource({ ...input, sessionId });
+    }
+    async readResource(input) {
+        const sessionId = this.requireResourceSession(input.sessionId);
+        return this.requireResources().readResource({ ...input, sessionId });
+    }
+    async deleteResource(input) {
+        const sessionId = this.requireResourceSession(input.sessionId);
+        return this.requireResources().deleteResource({ ...input, sessionId });
+    }
+    /** 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. */
+    async enqueueMessage(sessionIdInput, messageInput) {
+        const sessionId = validOpaqueToken(sessionIdInput, "sessionId", MAX_SESSION_ID_CHARS);
+        if (typeof messageInput !== "string" || messageInput.length === 0) {
+            throw new MachineSessionServiceInputError("message must be a non-empty string");
+        }
+        const meta = this.ports.registry.get(sessionId);
+        if (!meta)
+            throw new MachineSessionServiceFailure("not_found", "session not found");
+        const pending = this.ports.pendingMessages;
+        if (!pending) {
+            throw new MachineSessionServiceFailure("failed_precondition", "Provider setup task queue is unavailable");
+        }
+        const inserted = await pending.put({
+            sessionId,
+            message: messageInput,
+            createdAt: new Date().toISOString(),
+        });
+        if (!inserted) {
+            throw new MachineSessionServiceFailure("failed_precondition", "This Session already has a task waiting for Provider setup");
+        }
+        if (meta.source === "console" && !meta.title) {
+            this.ports.registry.setTitle(sessionId, synthesizeSessionTitle(messageInput));
+        }
+        this.schedulePendingDelivery(sessionId);
+        // Best effort: delivery also starts/retries the pane, but awaiting this path
+        // makes the setup Terminal attachable as soon as the enqueue RPC returns.
+        await this.startTerminal(sessionId).catch(() => undefined);
+        return { ok: true, queued: true };
+    }
+    /** Explicitly restore the target daemon's live runner without starting a turn. */
+    async startTerminal(sessionIdInput) {
+        const sessionId = validOpaqueToken(sessionIdInput, "sessionId", MAX_SESSION_ID_CHARS);
+        const request = await this.liveSessionRequest(sessionId);
+        const start = request.execution.runner.startLiveSession?.bind(request.execution.runner) ??
+            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));
+        }
+        return { ok: true };
+    }
+    async ensureLiveSession(sessionId, meta = this.ports.registry.get(sessionId)) {
+        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));
+        }
+        return request.execution;
+    }
+    async liveSessionRequest(sessionId, meta = this.ports.registry.get(sessionId)) {
+        const execution = this.requireExecution();
+        const consoleMeta = meta?.source === "console" ? meta : undefined;
+        const bound = consoleMeta ? null : ((await execution.sessionStore?.get(sessionId)) ?? null);
+        if (!meta && !bound) {
+            throw new MachineSessionServiceFailure("not_found", "session not found");
+        }
+        const liveRuntime = await execution.runtime.resolveRuntime({
+            agentName: consoleMeta?.agent,
+            agentSpec: consoleMeta?.config,
+            provider: meta?.provider ?? bound?.runtime,
+        });
+        if (liveRuntime === "codex" || liveRuntime === "traex") {
+            const codexRecord = await execution.sessionStore?.get(sessionId);
+            if (codexRecord?.codexSessionId) {
+                ensureCodexResumeRollout({
+                    sessionId,
+                    runtime: liveRuntime,
+                    threadId: codexRecord.codexSessionId,
+                    cwd: codexRecord.cwd ?? process.cwd(),
+                    items: await this.ports.log.snapshot(sessionId),
+                });
+            }
+        }
+        const options = {
+            ...(bound?.cwd
+                ? { cwd: bound.cwd }
+                : consoleMeta?.config?.osEnv?.cwd
+                    ? { cwd: consoleMeta.config.osEnv.cwd }
+                    : {}),
+            runtime: liveRuntime,
+            ...(consoleMeta?.reasoningEffort
+                ? { reasoningEffort: consoleMeta.reasoningEffort }
+                : {}),
+            ...(consoleMeta?.agent ? { agentName: consoleMeta.agent } : {}),
+            ...(consoleMeta?.config ? { agentSpec: consoleMeta.config } : {}),
+        };
+        return { execution, liveRuntime, options };
+    }
+    async resolveInteraction(sessionIdInput, interactionIdInput, resolution) {
+        const sessionId = validOpaqueToken(sessionIdInput, "sessionId", MAX_SESSION_ID_CHARS);
+        const interactionId = validOpaqueToken(interactionIdInput, "interactionId", MAX_SESSION_ID_CHARS);
+        return this.requireExecution().runner.resolveInteraction(sessionId, interactionId, structuredClone(resolution));
+    }
+    async delete(sessionIdInput) {
+        const sessionId = validOpaqueToken(sessionIdInput, "sessionId", MAX_SESSION_ID_CHARS);
+        try {
+            await this.ports.lifecycle?.beforeDelete?.(sessionId);
+        }
+        catch (error) {
+            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);
+        this.ports.events.close?.(sessionId);
+        await this.ports.pendingMessages?.delete(sessionId);
+        await this.ports.resources?.deleteSession(sessionId);
+        this.ports.registry.remove(sessionId);
+        await this.ports.log.deleteSession(sessionId);
+        this.ports.runtimeState.remove?.(sessionId);
+        try {
+            await this.ports.lifecycle?.afterDelete?.(sessionId);
+        }
+        catch (error) {
+            throw new MachineSessionServiceFailure("outcome_unknown", "Session was deleted but resource finalization did not complete", error instanceof Error ? error.message : String(error));
+        }
+        return { ok: true };
+    }
+    requireAgents() {
+        if (!this.ports.agents) {
+            throw new MachineSessionServiceFailure("failed_precondition", "session agent options are unavailable");
+        }
+        return this.ports.agents;
+    }
+    requireResources() {
+        if (!this.ports.resources) {
+            throw new MachineSessionServiceFailure("failed_precondition", "Session resources are unavailable");
+        }
+        return this.ports.resources;
+    }
+    requireResourceSession(sessionIdInput) {
+        const sessionId = validOpaqueToken(sessionIdInput, "sessionId", MAX_SESSION_ID_CHARS);
+        if (!this.ports.registry.get(sessionId)) {
+            throw new MachineSessionServiceFailure("not_found", "session not found");
+        }
+        return sessionId;
+    }
+    async resumePendingDeliveries() {
+        const pending = this.ports.pendingMessages;
+        if (!pending)
+            return;
+        try {
+            for (const message of await pending.list()) {
+                if (message.state === "queued")
+                    this.schedulePendingDelivery(message.sessionId);
+            }
+        }
+        catch {
+            // A later enqueue or daemon restart retries recovery; startup remains usable.
+        }
+    }
+    schedulePendingDelivery(sessionId) {
+        if (this.pendingDeliveries.has(sessionId))
+            return;
+        this.cancelledPendingDeliveries.delete(sessionId);
+        const delivery = this.deliverPendingMessage(sessionId)
+            .catch(() => undefined)
+            .finally(() => {
+            if (this.pendingDeliveries.get(sessionId) === delivery) {
+                this.pendingDeliveries.delete(sessionId);
+            }
+        });
+        this.pendingDeliveries.set(sessionId, delivery);
+    }
+    async deliverPendingMessage(sessionId) {
+        const pendingStore = this.ports.pendingMessages;
+        if (!pendingStore)
+            return;
+        for (;;) {
+            if (this.cancelledPendingDeliveries.has(sessionId))
+                return;
+            const pending = await pendingStore.get(sessionId);
+            if (!pending || pending.state !== "queued")
+                return;
+            let injectionAttempted = false;
+            try {
+                const execution = await this.ensureLiveSession(sessionId);
+                if (this.cancelledPendingDeliveries.has(sessionId))
+                    return;
+                const current = await pendingStore.get(sessionId);
+                if (!current ||
+                    current.state !== "queued" ||
+                    current.createdAt !== pending.createdAt ||
+                    current.message !== pending.message)
+                    return;
+                injectionAttempted = true;
+                const outcome = await execution.runner.injectMessage(sessionId, pending.message);
+                if (outcome === "injected") {
+                    await Promise.resolve(pendingStore.delete(sessionId)).catch(async () => {
+                        await Promise.resolve(pendingStore.markOutcomeUnknown(sessionId)).catch(() => undefined);
+                    });
+                    return;
+                }
+                if (outcome === "failed") {
+                    await pendingStore.markOutcomeUnknown(sessionId);
+                    return;
+                }
+            }
+            catch (error) {
+                if (injectionAttempted) {
+                    await Promise.resolve(pendingStore.markOutcomeUnknown(sessionId)).catch(() => undefined);
+                    return;
+                }
+                if (error instanceof MachineSessionServiceFailure && error.code === "not_found") {
+                    await pendingStore.delete(sessionId);
+                    return;
+                }
+            }
+            await retryDelay(this.pendingMessageRetryMs);
+        }
+    }
+    runtimeReadiness(runtime, cache) {
+        const cached = cache?.get(runtime);
+        if (cached)
+            return cached;
+        const pending = this.probeRuntimeReadiness(runtime);
+        cache?.set(runtime, pending);
+        return pending;
+    }
+    async probeRuntimeReadiness(runtime) {
+        const runner = this.ports.execution?.runner;
+        if (!runner?.getStatus) {
+            return { ready: false, reason: "Runtime readiness could not be checked." };
+        }
+        try {
+            const status = await runner.getStatus({ runtime });
+            const ready = status.codex_available &&
+                status.logged_in &&
+                status.session_store_writable &&
+                status.codex_sessions_accessible;
+            if (ready)
+                return { ready: true };
+            return {
+                ready: false,
+                reason: boundedLaunchReason(runtimeSetupReason(runtime, status)),
+            };
+        }
+        catch {
+            return { ready: false, reason: "Runtime readiness check failed." };
+        }
+    }
+    requireExecution() {
+        if (!this.ports.execution) {
+            throw new MachineSessionServiceFailure("failed_precondition", "session execution is unavailable");
+        }
+        return this.ports.execution;
+    }
+}
+/** One-line title derived from the first user message; no model call. */
+export function synthesizeSessionTitle(message, limit = 60) {
+    const collapsed = message.replace(/\s+/g, " ").trim();
+    if (collapsed.length <= limit)
+        return collapsed;
+    return `${collapsed.slice(0, limit - 1).trimEnd()}…`;
+}
+/** Keep target-owned setup diagnostics comfortably inside the wire DTO bound. */
+function boundedLaunchReason(reason) {
+    const normalized = reason.replace(/\s+/g, " ").trim();
+    return [...normalized].slice(0, 512).join("") || "Runtime needs setup.";
+}
+function runtimeSetupReason(runtime, status) {
+    const name = getRuntimeProfile(runtime).displayName;
+    if (!status.codex_available)
+        return `${name} CLI is unavailable.`;
+    if (!status.logged_in)
+        return `${name} is not authenticated.`;
+    if (!status.session_store_writable)
+        return "The Session store is not writable.";
+    if (!status.codex_sessions_accessible)
+        return `${name} Session storage is not accessible.`;
+    return status.issues.find((issue) => issue.trim().length > 0) ??
+        `${name} needs setup before it can start Sessions.`;
+}
+function retryDelay(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+    });
+}
+function listPage(sessions, hasMore, directoryTruncated) {
+    return {
+        sessions,
+        hasMore,
+        ...(hasMore && sessions.length > 0 ? { nextCursor: encodeListCursor(sessions.at(-1)) } : {}),
+        directoryTruncated,
+    };
+}
+function isAfterListCursor(summary, cursor) {
+    const updatedAt = summaryUpdatedAt(summary);
+    return updatedAt < cursor.updatedAt || (updatedAt === cursor.updatedAt && summary.id > cursor.id);
+}
+function encodeListCursor(summary) {
+    const cursor = {
+        v: 1,
+        updatedAt: summaryUpdatedAt(summary),
+        id: summary.id,
+    };
+    return Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+}
+function decodeListCursor(value) {
+    if (value.length === 0 ||
+        value.length > REMOTE_RUNTIME_SESSION_MAX_CURSOR_CHARS ||
+        !/^[A-Za-z0-9_-]+$/.test(value)) {
+        throw new MachineSessionServiceInputError("cursor is invalid");
+    }
+    try {
+        const bytes = Buffer.from(value, "base64url");
+        if (bytes.length === 0 || bytes.toString("base64url") !== value)
+            throw new Error();
+        const parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            throw new Error();
+        const record = parsed;
+        if (Object.keys(record).length !== 3 ||
+            !("v" in record) ||
+            !("updatedAt" in record) ||
+            !("id" in record)) {
+            throw new Error();
+        }
+        if (record.v !== 1) {
+            throw new MachineSessionServiceInputError("cursor version is not supported");
+        }
+        return {
+            v: 1,
+            updatedAt: validTimestamp(record.updatedAt, "cursor.updatedAt"),
+            id: validOpaqueToken(record.id, "cursor.id", MAX_SESSION_ID_CHARS),
+        };
+    }
+    catch (error) {
+        if (error instanceof MachineSessionServiceInputError)
+            throw error;
+        throw new MachineSessionServiceInputError("cursor is invalid");
+    }
+}
+function snapshotPage(sessionId, items, runtime, hasMore) {
+    return {
+        sessionId,
+        items,
+        runtime,
+        hasMore,
+        ...(hasMore && items.length > 0 ? { nextAfterId: items.at(-1).id } : {}),
+    };
+}
+function sessionSummary(id, meta, log, runtimeState, pendingState) {
+    const createdAt = meta?.createdAt ?? timestampFromEpoch(log?.createdAt, "createdAt");
+    const updatedAt = log
+        ? timestampFromEpoch(log.updatedAt, "updatedAt")
+        : (meta?.updatedAt ?? createdAt);
+    return {
+        id,
+        ...(meta?.provider === undefined ? {} : { provider: meta.provider }),
+        ...(meta?.agent === undefined ? {} : { agent: meta.agent }),
+        ...(meta?.title === undefined ? {} : { title: normalizeSessionTitle(meta.title) }),
+        status: runtimeState.snapshot(id).status,
+        ...(pendingState === undefined
+            ? {}
+            : {
+                setupStatus: pendingState === "queued"
+                    ? "waiting_for_provider"
+                    : "delivery_unknown",
+            }),
+        createdAt: validTimestamp(createdAt, "createdAt"),
+        source: meta?.source ?? "unknown",
+        updatedAt: validTimestamp(updatedAt, "updatedAt"),
+    };
+}
+function compareMetaRecency(left, right) {
+    const leftTime = validTimestamp(left.updatedAt ?? left.createdAt, "updatedAt");
+    const rightTime = validTimestamp(right.updatedAt ?? right.createdAt, "updatedAt");
+    return rightTime.localeCompare(leftTime) || left.id.localeCompare(right.id);
+}
+function compareSummaryRecency(left, right) {
+    return summaryUpdatedAt(right).localeCompare(summaryUpdatedAt(left)) || left.id.localeCompare(right.id);
+}
+function summaryUpdatedAt(summary) {
+    return summary.updatedAt ?? summary.createdAt;
+}
+function cancellableWatch(sessionId, iterator, signal) {
+    let cancelled = false;
+    let cancellationResolve;
+    const cancellation = new Promise((resolve) => {
+        cancellationResolve = resolve;
+    });
+    let cancelPromise;
+    const onAbort = () => {
+        void cancel().catch(() => undefined);
+    };
+    const cancel = () => {
+        if (cancelPromise)
+            return cancelPromise;
+        cancelled = true;
+        cancellationResolve();
+        signal?.removeEventListener("abort", onAbort);
+        cancelPromise = Promise.resolve(iterator.return?.()).then(() => undefined);
+        return cancelPromise;
+    };
+    if (signal?.aborted)
+        void cancel().catch(() => undefined);
+    else
+        signal?.addEventListener("abort", onAbort, { once: true });
+    const consumer = {
+        async next() {
+            if (cancelled)
+                return { value: undefined, done: true };
+            try {
+                const result = await Promise.race([
+                    iterator.next(),
+                    cancellation.then(() => ({ value: undefined, done: true })),
+                ]);
+                if (result.done)
+                    await cancel();
+                return result;
+            }
+            catch (error) {
+                await cancel().catch(() => undefined);
+                throw error;
+            }
+        },
+        async return() {
+            await cancel();
+            return { value: undefined, done: true };
+        },
+    };
+    const watch = {
+        sessionId,
+        cancel,
+        [Symbol.asyncIterator]() {
+            return consumer;
+        },
+    };
+    return watch;
+}
+function cloneRuntimeSnapshot(snapshot) {
+    return {
+        status: snapshot.status,
+        activeResponseIds: [...snapshot.activeResponseIds],
+        pendingInteractions: snapshot.pendingInteractions.map((pending) => ({
+            responseId: pending.responseId,
+            interaction: structuredClone(pending.interaction),
+        })),
+    };
+}
+function requestLimit(value, fallback, maximum, field) {
+    return value === undefined ? Math.min(fallback, maximum) : boundedInteger(value, 1, maximum, field);
+}
+function boundedInteger(value, minimum, maximum, field) {
+    if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+        throw new MachineSessionServiceInputError(`${field} must be an integer between ${minimum} and ${maximum}`);
+    }
+    return value;
+}
+function validOpaqueToken(value, field, maximum) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > maximum ||
+        /[\u0000-\u001f\u007f]/.test(value)) {
+        throw new MachineSessionServiceInputError(`${field} must be a non-empty opaque string of at most ${maximum} characters`);
+    }
+    return value;
+}
+function validTimestamp(value, field) {
+    if (typeof value !== "string" || !Number.isFinite(Date.parse(value))) {
+        throw new MachineSessionServiceInputError(`${field} must be a valid timestamp`);
+    }
+    return new Date(value).toISOString();
+}
+function timestampFromEpoch(value, field) {
+    if (value === undefined || !Number.isFinite(value)) {
+        throw new MachineSessionServiceInputError(`${field} is unavailable`);
+    }
+    return new Date(value).toISOString();
+}
+function jsonByteLength(value) {
+    return Buffer.byteLength(JSON.stringify(value), "utf8");
+}