@jskit-ai/assistant-core 0.1.239 → 0.1.241

package/src/server/conversation/runtime.js

@@ -1,5 +1,5 @@
 import { createConversationProviderFactory } from "./provider.js";
-import { createConversationDeliveryTiming } from "./deliveryTiming.js";
+import { createConversationDeliveryTiming, normalizeConversationDeliveryHostStages } from "./deliveryTiming.js";
 import { normalizeConversationConfiguration } from "./configuration.js";
 import { runScopedConversationTurn, readPersistentConversation, projectStoredPersistentConversation, startPersistentConversationTurn,
   inspectPersistentConversationAdmission, preparePersistentConversationChangeover,
@@ -9,13 +9,14 @@ import { randomUUID } from "node:crypto";
 import { createConversationTranscript, isCompletedEnvelopeTurn } from "./transcript.js";
 import { createConversationStreams } from "./streams.js";
 import { createReentrantConversationStorage } from "./storage.js";
-import { createCodexConversationStore } from "./agentRun.js";
+import { createCodexConversationStore } from "./codexConversationStore.js";
 import { codexAppServerTurnStateFromAgentRun } from "./codexTurn.js";
 import { hasUnfinishedConversationRewind, createConversationRuntimeReplacement,
-  releaseConversationRuntimeBinding, finishConversationRuntimeReplacement } from "./runtimeStateUpgrade.js";
+  releaseConversationRuntimeBinding, finishConversationRuntimeReplacement,
+  conversationNativeIdentity, conversationNativeBinding } from "./runtimeStateUpgrade.js";
 import { createServiceToolCatalog } from "../lib/serviceToolCatalog.js";
 import { createConversationTools } from "./tools.js";
-import { readAssistantResponseEnvelope } from "../lib/assistantToolLoop.js";
+import { readAssistantResponseEnvelope } from "./boundedToolLoop.js";
 import { conversationAttachmentIds, createConversationAttachmentReader } from "./attachments.js";
 import { conversationAttachmentManifest } from "../../shared/conversation/attachments.js";
 import { createConversationChangeover, conversationContinuity, conversationHistoryVersions,
@@ -27,8 +28,6 @@ function failure(message, code, statusCode = 409) {
 
 const submittedMessage = turn => turn.user || turn.system;
 const retainedSegments = state => [...new Map([...state.predecessors, state].map(segment => [segment.segmentId, segment])).values()];
-const nativeIdentity = segment => segment.engine === "codex" ? segment.binding?.threadId
-  : segment.engine === "claude" ? segment.binding?.conversationId : segment.binding?.sessionId;
 const pendingSuccessor = state => state.engine !== "api" && state.predecessors.findLast(segment => segment.successorId === state.segmentId &&
   segment.segmentId !== state.segmentId && segment.replacement?.operation === "replace" && !segment.acceptedAt);
 const sameRequest = (left, right) => left.text === right.text && (left.origin || "user") === right.origin &&
@@ -37,9 +36,10 @@ const sameRequest = (left, right) => left.text === right.text && (left.origin ||
 
 /** One application conversation API. Storage and authorization remain host facilities. */
 export function createConversationRuntime({ engine: defaultEngine = "api", defaultIntegrationId, storage, authorize, connections, apiClientFactory, apiHistory,
-  actions, toolPolicy, toolCatalog, attachments, fetch, host: defaultHost, onDeliveryTiming, persistCommentary = true, completedEnvelope = false, limits = {} } = {}) {
+  actions, toolPolicy, toolCatalog, attachments, fetch, host: defaultHost, onDeliveryTiming, hostDeliveryStages, persistCommentary = true, completedEnvelope = false, limits = {} } = {}) {
   if (typeof authorize !== "function") throw new TypeError("Conversation access requires an authorize function.");
   if (onDeliveryTiming !== undefined && typeof onDeliveryTiming !== "function") throw new TypeError("Delivery timing requires a server-owned observer.");
+  const deliveryHostStages = normalizeConversationDeliveryHostStages(hostDeliveryStages);
   if (typeof completedEnvelope !== "boolean") throw new TypeError("Completed envelope policy requires a server-side boolean.");
   if (typeof persistCommentary !== "boolean") throw new TypeError("Conversation commentary persistence requires an explicit server-side boolean.");
   if (apiHistory !== undefined && typeof apiHistory !== "function") throw new TypeError("API request history requires a server-owned selector.");
@@ -188,10 +188,15 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
       ? await entry.driver.readState({ conversation: entry.conversation, context })
       : await entry.conversation.read(context);
     entry.segmentId = value.threadId ? `${entry.engine}:${value.threadId}` : null;
-    const pending = value.delivery?.engines[entry.engine]?.pending;
+    const saved = value.delivery?.engines[entry.engine]?.pending;
+    // The saved receipt is the delivery proof, as in changeover recovery. A
+    // restart after native admission leaves only a stale attempt marker, which
+    // must not leave the conversation unconfirmed until another message is sent.
+    const pending = (saved?.attempted && !saved.inspectionOnly &&
+      await entry.conversation.transcript.hasMessage(saved.messageId)) ? null : saved;
     return { engine: entry.engine, configuration: value.configuration, segmentId: entry.segmentId,
-      binding: entry.engine === "codex" ? { threadId: value.threadId, codexAppServerRun: value.run }
-        : entry.engine === "claude" ? { conversationId: value.threadId } : { sessionId: value.threadId },
+      binding: { ...conversationNativeBinding(entry.engine, value.threadId),
+        ...(entry.engine === "codex" ? { codexAppServerRun: value.run } : {}) },
       nativeTurn: value.turn, nativeResult: value.nativeResult,
       lastEngine: value.delivery?.lastEngine ?? entry.engine,
       replacement: ["preparing", "ready"].includes(value.delivery?.replacement?.status) ? value.delivery.replacement : null,
@@ -386,11 +391,11 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
         return { lastEngine: runtime.lastEngine, engines,
           ...(preparing ? { replacement: { engineId: preparing.engine, status: "preparing",
             operationId: preparing.request.operationId, handover: preparing.request.briefing || "",
-            bindingNames: ["binding"], previous: { engineId: runtime.engine, conversationId: nativeIdentity(runtime) },
+            bindingNames: ["binding"], previous: { engineId: runtime.engine, conversationId: conversationNativeIdentity(runtime) },
             ...(preparing.preparedAt ? { preparedAt: preparing.preparedAt } : {}) } }
             : predecessor ? { replacement: { engineId: runtime.engine, status: "ready",
             operationId: predecessor.replacement.operationId, handover: predecessor.replacement.briefing || "",
-            previous: { engineId: predecessor.engine, conversationId: nativeIdentity(predecessor) },
+            previous: { engineId: predecessor.engine, conversationId: conversationNativeIdentity(predecessor) },
             ...(predecessor.preparedAt ? { preparedAt: predecessor.preparedAt } : {}) } } : {}) };
       },
       write(value) {
@@ -473,7 +478,7 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
             return { admission: observation.accepted ? "accepted" : "unknown" };
           }
           const { runtime } = await storage.read(entry.id, transaction => transaction.readMetadata());
-          if (!threadId || threadId !== nativeIdentity(runtime) || runtime.request?.messageId !== messageId) return null;
+          if (!threadId || threadId !== conversationNativeIdentity(runtime) || runtime.request?.messageId !== messageId) return null;
           observation = await entry.provider.inspectAdmission({ ...runtime.request, context, configuration: runtime.configuration });
           await access(context, entry.id, request?.operation || "inspectDelivery", entry);
           return { admission: observation.accepted ? "accepted" : "unknown" };
@@ -604,7 +609,7 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
       const authored = submittedMessage(turn || {});
       const saved = turn?.metadata?.runtime;
       if (runtime?.version !== 3 || runtime.engine !== engine || runtime.segmentId !== segmentId ||
-          runtime.replacement || runtime.request || !nativeIdentity(runtime) || authored?.messageId !== messageId ||
+          runtime.replacement || runtime.request || !conversationNativeIdentity(runtime) || authored?.messageId !== messageId ||
           authored.origin !== "application" || saved?.completedEnvelope !== true || saved.engine !== engine ||
           saved.segmentId !== segmentId || saved.status !== "complete" || saved.supersededBy ||
           typeof turn.assistant?.text !== "string" || !turn.assistant.text || !turn.assistant.messageId) {
@@ -644,7 +649,7 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
       await access(context, entry.id, "tool", entry);
       const saved = await storage.read(entry.id, transaction => exact(transaction));
       const observation = await entry.provider.inspectAdmission({ messageId,
-        threadId: nativeIdentity(saved.runtime), nativeTurnId: saved.turn.metadata.runtime.nativeTurnId,
+        threadId: conversationNativeIdentity(saved.runtime), nativeTurnId: saved.turn.metadata.runtime.nativeTurnId,
         configuration: saved.runtime.configuration, receiptBinding: saved.runtime.binding, context, verifyAccount: true });
       signal.throwIfAborted();
       await access(context, entry.id, "tool", entry);
@@ -777,6 +782,13 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
     let toolFailure;
     const applicationTools = entry.applicationTools;
     const toolStorage = applicationTools?.storage || storage;
+    // Every saved turn and pending request records its attribution identically.
+    const turnAttribution = (request, extra = {}) => ({ engine, segmentId, origin: request.input.origin,
+      ...(request.completedEnvelope ? { completedEnvelope: true } : {}),
+      ...(typeof request.nativeToolAttempt === "boolean" ? { nativeToolAttempt: request.nativeToolAttempt } : {}), ...extra });
+    const authoredRequestRecord = request => ({ ...request.input, at: request.at,
+      ...(request.completedEnvelope ? { completedEnvelope: true, excludedMessageIds: request.excludedMessageIds } : {}),
+      ...(typeof request.nativeToolAttempt === "boolean" ? { nativeToolAttempt: request.nativeToolAttempt } : {}) });
 
     function prepareTools(request) {
       if (request.completedEnvelope || !catalog || entry.conversation && !applicationTools) return;
@@ -822,12 +834,10 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
         if (request.answer?.text.trim()) await transaction.replaceAssistant(request.turnId, request.answer);
       }
       const saved = driver.canonicalTranscript ? await transaction.readTurn(request.turnId) : null;
-      await transaction.updateTurnMetadata(request.turnId, { runtime: { ...saved?.metadata?.runtime, status, engine, segmentId, origin: request.input.origin,
-        ...(request.completedEnvelope ? { completedEnvelope: true } : {}),
-        ...(typeof request.nativeToolAttempt === "boolean" ? { nativeToolAttempt: request.nativeToolAttempt } : {}),
+      await transaction.updateTurnMetadata(request.turnId, { runtime: { ...saved?.metadata?.runtime, status, ...turnAttribution(request, {
         ...(request.nativeTurnId ? { nativeTurnId: request.nativeTurnId } : {}),
         ...(request.goalMessageId ? { goalMessageId: request.goalMessageId } : {}),
-        ...(request.continuedBy ? { continuedBy: request.continuedBy } : {}), ...extra, ...(error ? { error } : {}) } });
+        ...(request.continuedBy ? { continuedBy: request.continuedBy } : {}) }), ...extra, ...(error ? { error } : {}) } });
       return conversationHistoryVersions([{ turnId: request.turnId,
         messages: [...request.progress.values()].filter(message => !(message.turnId === request.turnId && message.status === "complete"))
           .concat(request.answer?.text.trim() ? [request.answer] : []) }]);
@@ -895,11 +905,9 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
         } else {
           id = await transaction.nextTurnId();
           await transaction.appendMessage(id, { role: request.input.origin === "application" ? "system" : "user", ...request.input, at: new Date().toISOString(),
-            turnMetadata: { runtime: { status: "running", engine, segmentId, origin: request.input.origin,
-              ...(request.completedEnvelope ? { completedEnvelope: true } : {}),
-              ...(typeof request.nativeToolAttempt === "boolean" ? { nativeToolAttempt: request.nativeToolAttempt } : {}),
+            turnMetadata: { runtime: { status: "running", ...turnAttribution(request, {
               ...(request.goalMessageId ? { goalMessageId: request.goalMessageId } : {}),
-              ...(nativeTurnId ? { nativeTurnId } : {}) } } });
+              ...(nativeTurnId ? { nativeTurnId } : {}) }) } } });
         }
         if (engine === "api") {
           metadata.runtime.seen = { ...(seen || metadata.runtime.seen), ...conversationHistoryVersions([await transaction.readTurn(id)]) };
@@ -1085,9 +1093,7 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
             throw failure("Authorized attachment paths changed after this instruction was prepared. Restore the original files or send a new message.", "conversation_attachment_manifest_changed");
           }
           metadata.runtime.request = { ...(pending?.messageId === request.input.messageId ? pending
-            : { ...request.input, at: request.at, attempted: false,
-              ...(request.completedEnvelope ? { completedEnvelope: true, excludedMessageIds: request.excludedMessageIds } : {}),
-              ...(typeof request.nativeToolAttempt === "boolean" ? { nativeToolAttempt: request.nativeToolAttempt } : {}) }), attachmentManifest };
+            : { ...authoredRequestRecord(request), attempted: false }), attachmentManifest };
           await transaction.writeMetadata(metadata);
         });
         const admitted = Promise.withResolvers();
@@ -1113,9 +1119,7 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
             threadId = native?.threadId;
             if (!threadId) throw new Error("Native admission requires the saved conversation identity.");
             await input.onPromptSending(entry.conversation ? native : { threadId, displayAttachments: files.attachments,
-              turnMetadata: { runtime: { engine, segmentId, origin: request.input.origin,
-                ...(request.completedEnvelope ? { completedEnvelope: true } : {}),
-                ...(typeof request.nativeToolAttempt === "boolean" ? { nativeToolAttempt: request.nativeToolAttempt } : {}) } } });
+              turnMetadata: { runtime: turnAttribution(request) } });
             if (request.input.goal && request.context?.signal?.aborted) {
               throw Object.assign(failure("The goal command was stopped before delivery.", "conversation_goal_stopped"), { delivery: "not-sent" });
             }
@@ -1167,9 +1171,7 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
               const metadata = await transaction.readMetadata();
               const pending = metadata.runtime.request;
               if (pending && pending.messageId !== request.input.messageId && (pending.attempted || pending.inspectionOnly)) throw new Error("The pending conversation instruction changed.");
-              metadata.runtime.request = { ...request.input, at: request.at,
-                ...(request.completedEnvelope ? { completedEnvelope: true, excludedMessageIds: request.excludedMessageIds } : {}),
-                ...(typeof request.nativeToolAttempt === "boolean" ? { nativeToolAttempt: request.nativeToolAttempt } : {}),
+              metadata.runtime.request = { ...authoredRequestRecord(request),
                 message: rendered.message, displayMessage: rendered.displayMessage,
                 displayAttachments, attachmentIds: rendered.attachmentIds,
                 attachmentManifest,
@@ -1181,7 +1183,7 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
           },
           async onPromptRejected() {
             if (entry.conversation) return request.originalInput?.onPromptRejected?.();
-            if (!entry.conversation) await storage.write(entry.id, async transaction => {
+            await storage.write(entry.id, async transaction => {
               const metadata = await transaction.readMetadata();
               if (metadata.runtime.request?.messageId === request.input.messageId) {
                 metadata.runtime.request.attempted = false;
@@ -1309,7 +1311,7 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
               const turn = await transaction.readTurn(initial.turnId);
               const saved = turn?.metadata?.runtime;
               if (metadata.runtime.engine !== engine || metadata.runtime.segmentId !== segmentId ||
-                  nativeIdentity(metadata.runtime) !== threadId || submittedMessage(turn || {})?.messageId !== messageId ||
+                  conversationNativeIdentity(metadata.runtime) !== threadId || submittedMessage(turn || {})?.messageId !== messageId ||
                   saved?.engine !== engine || saved.segmentId !== segmentId || saved.completedEnvelope !== true ||
                   typeof saved.nativeToolAttempt !== "boolean" || saved.status !== "running" || saved.supersededBy ||
                   entry.active !== active || current !== initial || initial.finished || initial.sealed || active.controller.signal.aborted) {
@@ -1475,7 +1477,7 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
 
   async function send(entry, context, input, origin = "user", goal, representation, wakeOptions) {
     const deliveryTiming = createConversationDeliveryTiming({ engine: entry.engine,
-      conversationId: entry.id, messageId: input?.messageId, report: onDeliveryTiming });
+      conversationId: entry.id, messageId: input?.messageId, report: onDeliveryTiming, hostStages: deliveryHostStages });
     deliveryTiming("received");
     const grant = new Set();
     try {
@@ -1701,9 +1703,6 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
     await access(context, entry.id, "goal", entry);
     context?.signal?.throwIfAborted();
     if (!capabilities(entry).goals) throw failure("This connection does not support native goals.", "conversation_unsupported", 400);
-    if (representation !== "native" && !capabilities(entry).goals) {
-      throw failure("This bound conversation does not yet map native goal messages to canonical receipts.", "conversation_unsupported", 400);
-    }
     if (representation === "native") {
       const { operation } = await serial(entry, async () => {
         await access(context, entry.id, "goal", entry);
@@ -1817,8 +1816,7 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
       // Release the queue once Send is reserved, just as an ordinary message
       // does. Stop remains available while native acknowledgement is pending.
       if (delivery) return delivery;
-      if (entry.conversation && updated.nativeResult.ok === false) throw Object.assign(new Error(updated.nativeResult.error), updated.nativeResult);
-      entry.goal = entry.conversation ? updated.goal : updated;
+      entry.goal = updated;
       await emit(entry, { type: "goal", goal: entry.goal });
       return { goal: structuredClone(entry.goal) };
     });
@@ -1851,13 +1849,16 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
     const history = await readTranscript(entry);
     const existing = history.find(turn => submittedMessage(turn)?.messageId === messageId);
     const receipt = existing && { status: "accepted", messageId, turnId: existing.turnId, duplicate: true };
-    const goalMessageId = existing?.metadata.runtime.goalMessageId;
+    // Turns written before the first runtime segment carry no runtime metadata.
+    const existingRuntime = existing?.metadata?.runtime;
+    const goalMessageId = existingRuntime?.goalMessageId;
     const goalRequest = Boolean(submittedMessage(existing || {})?.goal || goalMessageId === messageId);
-    if (existing && (existing.metadata?.runtime?.segmentId !== entry.segmentId || existing.metadata.runtime.supersededBy ||
-        existing.metadata.runtime.status === "complete" && !goalRequest)) return receipt;
+    if (existing && (existingRuntime?.segmentId !== entry.segmentId || existingRuntime.supersededBy ||
+        existingRuntime.status === "complete" && !goalRequest)) return receipt;
     if (goalMessageId && goalMessageId !== messageId) {
       const owner = history.find(turn => submittedMessage(turn)?.messageId === goalMessageId);
-      if (owner?.metadata.runtime.goalMessageId !== goalMessageId || owner.metadata.runtime.segmentId !== entry.segmentId) throw new Error("The goal command for this native continuation is missing.");
+      const ownerRuntime = owner?.metadata?.runtime;
+      if (ownerRuntime?.goalMessageId !== goalMessageId || ownerRuntime.segmentId !== entry.segmentId) throw new Error("The goal command for this native continuation is missing.");
       const result = await inspectDelivery(entry, context, goalMessageId);
       return { ...receipt, recovered: result.recovered === true };
     }
@@ -1873,7 +1874,7 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
     const request = existing ? submittedMessage(existing) : metadata.runtime.request;
     if (!request || request.messageId !== messageId || !entry.provider.inspectAdmission) return receipt || { status: "unknown", messageId };
     const pending = metadata.runtime.request?.messageId === messageId ? metadata.runtime.request : null;
-    if (pending?.threadId && pending.threadId !== nativeIdentity(metadata.runtime)) return receipt || { status: "unknown", messageId };
+    if (pending?.threadId && pending.threadId !== conversationNativeIdentity(metadata.runtime)) return receipt || { status: "unknown", messageId };
     const observation = suppliedObservation || await entry.provider.inspectAdmission({ ...request, nativeTurnId: existing?.metadata?.runtime?.nativeTurnId,
       context, configuration: metadata.runtime.configuration });
     await access(context, entry.id, "inspectDelivery", entry);
@@ -1998,7 +1999,7 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
       }
       const row = (await readTranscript(entry)).find(turn => submittedMessage(turn)?.messageId === messageId);
       if (row) return { status: "accepted", messageId, turnId: row.turnId, duplicate: true };
-      const threadId = state.request?.messageId === messageId ? state.request.threadId : nativeIdentity(state);
+      const threadId = state.request?.messageId === messageId ? state.request.threadId : conversationNativeIdentity(state);
       if (!threadId) return { status: "unknown", messageId };
       const observation = await entry.provider.inspectAdmission({ messageId, threadId, context });
       await access(context, entry.id, "inspectDelivery", entry);
@@ -2106,7 +2107,7 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
       ? normalizeConversationConfiguration(input.configuration, { engine, defaultIntegrationId }) : state.configuration);
     const driver = createDriver(engine, entry.host);
     driver.validateConfiguration(configuration);
-    const predecessorId = nativeIdentity(state);
+    const predecessorId = conversationNativeIdentity(state);
     const nativeReplacement = !selection && state.engine !== "api" && predecessorId &&
       (state.engine !== "claude" || state.binding.sent);
     const retainNativeBinding = input.retireNative !== true && engine === state.engine &&
@@ -2189,7 +2190,7 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
           }
           await callback({
             async releaseBinding(replacement) {
-              if (replacement && nativeIdentity(state) !== replacement.previous.conversationId) {
+              if (replacement && conversationNativeIdentity(state) !== replacement.previous.conversationId) {
                 throw failure("The native predecessor identity changed before its binding was released.", "conversation_replacement_conflict");
               }
               releaseConversationRuntimeBinding(state, pending, request, engine);
@@ -2216,7 +2217,7 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
         identity: {
           async inspect(expectedId) {
             const { runtime } = await storage.read(entry.id, transaction => transaction.readMetadata());
-            if (runtime.segmentId !== input.expectedSegmentId || nativeIdentity(runtime) !== expectedId) {
+            if (runtime.segmentId !== input.expectedSegmentId || conversationNativeIdentity(runtime) !== expectedId) {
               throw failure("The native predecessor identity changed or is incomplete.", "conversation_replacement_conflict");
             }
             return { bindingNames: ["binding"], previous: { engineId: runtime.engine, conversationId: expectedId } };

package/src/server/conversation/runtimeStateUpgrade.js

@@ -31,9 +31,15 @@ function validateSegment(segment) {
   }
 }
 
-function nativeIdentity(segment) {
-  return segment.engine === "codex" ? segment.binding.threadId
-    : segment.engine === "claude" ? segment.binding.conversationId : segment.binding.sessionId;
+const nativeIdentityField = engine => engine === "codex" ? "threadId" : engine === "claude" ? "conversationId" : "sessionId";
+
+/** The saved binding field that holds a native segment's conversation identity. */
+export function conversationNativeIdentity(segment) {
+  return segment.binding?.[nativeIdentityField(segment.engine)];
+}
+
+export function conversationNativeBinding(engine, id) {
+  return { [nativeIdentityField(engine)]: id };
 }
 
 function inspectRequest(request, segment, version, warnings) {
@@ -44,7 +50,7 @@ function inspectRequest(request, segment, version, warnings) {
     invalid("Conversation runtime has an unsupported pending request. Inspect it before upgrading.");
   }
   if (segment.engine === "api") return;
-  const threadId = nativeIdentity(segment);
+  const threadId = conversationNativeIdentity(segment);
   if (version === 3 && !Object.hasOwn(request, "inspectionOnly")) {
     if (typeof request.attempted !== "boolean" || request.attempted &&
         (typeof threadId !== "string" || !threadId || request.threadId !== threadId || typeof request.message !== "string") ||
@@ -143,30 +149,21 @@ function retireCodexBinding(runtime, retirement) {
   finishConversationRuntimeReplacement(runtime, { engine: "codex", selection: true, retireNative: true, pending });
 }
 
-/** Pure offline transform. The application owns enumeration, backups and publication. */
-export function upgradeConversationRuntimeState({ metadata, conversationLog, retirement }) {
-  if (!object(metadata) || !Array.isArray(conversationLog)) {
-    invalid("Conversation runtime upgrade requires metadata and the complete stored transcript.");
-  }
-  if (metadata.runtime === undefined) {
-    if (retirement !== undefined) invalid("Offline native retirement requires the exact saved runtime; it cannot create a historical binding.");
-    return { metadata, changed: false, warnings: [] };
-  }
-  const source = metadata.runtime;
-  if (!object(source) || ![2, 3].includes(source.version) || !Array.isArray(source.predecessors)) {
+/** Validates a saved runtime and its retained requests. A version 2 request is
+ * marked inspection-only in place, so the upgrade passes its own copy. */
+function validateConversationRuntimeState(runtime, warnings) {
+  if (!object(runtime) || ![2, 3].includes(runtime.version) || !Array.isArray(runtime.predecessors)) {
     invalid("This conversation has an unsupported runtime version. Inspect its original format and provide an offline conversion before opening it.");
   }
-  if (hasUnfinishedConversationRewind(source)) {
+  if (hasUnfinishedConversationRewind(runtime)) {
     invalid("This conversation has an unfinished Undo operation from an earlier runtime. Inspect its saved native and local history offline before upgrading; no history was changed.");
   }
-  if (source.version === 3 && (typeof source.lastEngine !== "string" || source.lastEngine && !engines.has(source.lastEngine))) {
+  if (runtime.version === 3 && (typeof runtime.lastEngine !== "string" || runtime.lastEngine && !engines.has(runtime.lastEngine))) {
     invalid("Conversation runtime has an invalid last-delivered engine. Inspect it before upgrading.");
   }
-  const runtime = structuredClone(source);
-  const warnings = [];
   for (const segment of [...runtime.predecessors, runtime]) {
     validateSegment(segment);
-    inspectRequest(segment.request, segment, source.version, warnings);
+    inspectRequest(segment.request, segment, runtime.version, warnings);
   }
   if (runtime.replacement !== undefined) {
     const pending = runtime.replacement;
@@ -177,11 +174,26 @@ export function upgradeConversationRuntimeState({ metadata, conversationLog, ret
     }
     if (pending.binding) {
       validateSegment(pending);
-      inspectRequest(pending.submission, pending, source.version, warnings);
+      inspectRequest(pending.submission, pending, runtime.version, warnings);
     } else if (pending.submission !== undefined) {
       invalid("An unfinished replacement has a request without its exact saved binding. Inspect it before upgrading.");
     }
   }
+}
+
+/** Pure offline transform. The application owns enumeration, backups and publication. */
+export function upgradeConversationRuntimeState({ metadata, conversationLog, retirement }) {
+  if (!object(metadata) || !Array.isArray(conversationLog)) {
+    invalid("Conversation runtime upgrade requires metadata and the complete stored transcript.");
+  }
+  if (metadata.runtime === undefined) {
+    if (retirement !== undefined) invalid("Offline native retirement requires the exact saved runtime; it cannot create a historical binding.");
+    return { metadata, changed: false, warnings: [] };
+  }
+  const source = metadata.runtime;
+  const runtime = structuredClone(source);
+  const warnings = [];
+  validateConversationRuntimeState(runtime, warnings);
   if (retirement !== undefined) {
     retireCodexBinding(runtime, retirement);
     return { metadata: { ...metadata, runtime }, changed: true, warnings };
@@ -211,7 +223,7 @@ export async function prepareConversationRuntimeCopy(transaction, { at }) {
   const runtime = metadata.runtime;
   if (runtime) {
     if (runtime.version !== 3) invalid("Upgrade the parent conversation before copying its runtime state.");
-    upgradeConversationRuntimeState({ metadata, conversationLog: turns });
+    validateConversationRuntimeState(runtime, []);
     if (runtime.replacement) invalid("Finish the parent conversation changeover before copying it.");
     for (const segment of [...runtime.predecessors, runtime]) {
       if (segment.binding) {

package/src/server/conversation/transcript.js

@@ -1,4 +1,4 @@
-import { normalizeText } from "./normalize.js";
+import { normalizeNullableText } from "./normalize.js";
 import { conversationLogPage } from "../../shared/conversation/pagination.js";
 
 /** Conversation policy, independent of database, filesystem, identity and HTTP. */
@@ -25,7 +25,7 @@ export function createConversationTranscript({ storage, clock = () => new Date()
         ? (await Promise.all(allIds.map(id => transaction.readTurn(id))))
           .filter(turn => hasMessages(turn) && (!presentation || !isCompletedEnvelopeTurn(turn))) : null;
       const ids = visible ? visible.map(turn => turn.turnId) : allIds;
-      const before = normalizeText(beforeTurnId);
+      const before = normalizeNullableText(beforeTurnId);
       const requestedLimit = Number.parseInt(String(limit || ""), 10);
       const pageLimit = Number.isFinite(requestedLimit) && requestedLimit > 0 ? Math.min(requestedLimit, 100) : 0;
       let page;
@@ -66,13 +66,13 @@ export function createConversationTranscript({ storage, clock = () => new Date()
   }
 
   async function append(scope, role, { text = "", messageId = "", at = "", attachments = [], data, turnMetadata = null, requireOpenTurn = false, outputId = "", turnId: requestedTurnId = "" } = {}) {
-    const messageText = normalizeText(text);
-    const id = normalizeText(messageId);
+    const messageText = normalizeNullableText(text);
+    const id = normalizeNullableText(messageId);
     if (!messageText && !(role === "user" && Array.isArray(attachments) && attachments.length)) return null;
     return storage.write(scope, async (transaction) => {
       if (id && await transaction.hasMessage(id)) return null;
       const createdAt = new Date(at || clock());
-      const targetId = ["assistant", "commentary", "thinking"].includes(role) ? normalizeText(requestedTurnId) : "";
+      const targetId = ["assistant", "commentary", "thinking"].includes(role) ? normalizeNullableText(requestedTurnId) : "";
       const target = targetId ? await transaction.readTurn(targetId) : null;
       if (targetId && !target) throw new Error("The native output's original turn no longer exists.");
       const tail = target || (["assistant", "commentary", "thinking"].includes(role) ? await tailTurn(transaction) : null);
@@ -84,7 +84,7 @@ export function createConversationTranscript({ storage, clock = () => new Date()
       const turnId = target?.turnId || open?.turnId || (thinkingOnly ? tail.turnId : await transaction.nextTurnId());
       await transaction.appendMessage(turnId, {
         role, text: messageText, messageId: id, at: createdAt.toISOString(),
-        ...(["assistant", "commentary", "thinking"].includes(role) && normalizeText(outputId) ? { outputId: normalizeText(outputId) } : {}),
+        ...(["assistant", "commentary", "thinking"].includes(role) && normalizeNullableText(outputId) ? { outputId: normalizeNullableText(outputId) } : {}),
         ...(role === "user" ? { attachments, turnMetadata } : {}),
         ...(data !== undefined ? { data: structuredClone(data) } : {})
       });
@@ -94,7 +94,7 @@ export function createConversationTranscript({ storage, clock = () => new Date()
 
   // The first turn whose submitted (user or application) message has this ID.
   async function findSubmittedTurn(scope, messageId) {
-    const id = normalizeText(messageId);
+    const id = normalizeNullableText(messageId);
     if (!id) return null;
     return storage.read(scope, async (transaction) => {
       const submitted = turn => hasMessages(turn) && (turn.user || turn.system)?.messageId === id ? turn : null;
@@ -116,17 +116,17 @@ export function createConversationTranscript({ storage, clock = () => new Date()
     readConversationLog,
     findSubmittedTurn,
     readConversationLogPage,
-    conversationMessageIdExists: (scope, messageId) => storage.read(scope, (transaction) => transaction.hasMessage(normalizeText(messageId))),
+    conversationMessageIdExists: (scope, messageId) => storage.read(scope, (transaction) => transaction.hasMessage(normalizeNullableText(messageId))),
     writeConversationUserMessage: (scope, input) => append(scope, "user", input),
     writeConversationAssistantMessage: (scope, input) => append(scope, "assistant", input),
     writeConversationCommentaryMessage: (scope, input) => append(scope, "commentary", input),
     writeConversationThinkingMessage: (scope, input) => append(scope, "thinking", input),
     writeConversationSystemMessage: (scope, input) => append(scope, "system", input),
     async upsertConversationAssistantMessage(scope, { turnId = "", text = "" } = {}) {
-      const messageText = normalizeText(text);
+      const messageText = normalizeNullableText(text);
       if (!messageText) return null;
       return storage.write(scope, async (transaction) => {
-        const id = normalizeText(turnId);
+        const id = normalizeNullableText(turnId);
         await transaction.replaceAssistant(id, { role: "assistant", text: messageText, at: new Date(clock()).toISOString() });
         return transaction.readTurn(id);
       });

package/src/server/hosts/codexConfiguration.js

@@ -8,6 +8,7 @@ export {
   codexAuthOutputRequiresReconnect,
   codexProviderConfiguration,
   codexProviderFileConfiguration,
+  codexProviderCatalogPath,
   verifyCodexProviderKey,
   codexProviderModelCatalog,
   codexCatalogRows,

package/src/server/hosts/codexProvider.js

@@ -1,26 +1,28 @@
 export {
   CODEX_APP_SERVER_INVALID_REQUEST_CODE,
   CodexAppServerAgentProvider,
-  assertCodexAuthPreflightReady,
   codexAppServerEndpointForTarget,
   codexAppServerRequestIsInvalid,
   codexAppServerRuntimeStopWasVerified,
   codexCliResumeCommand,
-  codexRenewalThreadError,
   codexTextInput,
   codexTurnInput,
   createCodexAppServerProviderOwner,
-  defineCodexRenewalThreadIds,
   deleteCodexAppServerHelperThread,
   deleteCodexAppServerThread,
   ensureCodexAppServerThread,
   inspectCodexAppServerMessageAdmission,
   retireCodexConversationHistory,
   readCodexNativeGoal,
-  resumeExactCodexAppServerThread,
   sendCodexAppServerPrompt,
-  shellQuote,
-  startFreshCodexAppServerThread
+  shellQuote
 } from "../conversation/codexProvider.js";
+export { assertCodexAuthPreflightReady } from "../conversation/codexAuthPreflight.js";
+export {
+  codexRenewalThreadError,
+  defineCodexRenewalThreadIds,
+  resumeExactCodexAppServerThread,
+  startFreshCodexAppServerThread
+} from "../conversation/codexRenewalThreads.js";
 
 export { readCodexHistoryRows } from "../conversation/codexHistoryAdapter.js";

package/src/server/index.js

@@ -15,4 +15,5 @@ export {
 export { resolveWorkspaceSlug } from "./lib/resolveWorkspaceSlug.js";
 export { createServiceToolCatalog } from "./lib/serviceToolCatalog.js";
 export { consumeCompletionStream, sanitizeAssistantMessageText } from "./lib/assistantCompletion.js";
-export { runAssistantToolLoop, runBoundedAssistantToolLoop, readAssistantResponseEnvelope, readPartialAssistantReply } from "./lib/assistantToolLoop.js";
+export { runAssistantToolLoop } from "./lib/assistantToolLoop.js";
+export { runBoundedAssistantToolLoop, readAssistantResponseEnvelope, readPartialAssistantReply } from "./conversation/boundedToolLoop.js";