@jskit-ai/assistant-core 0.1.239 → 0.1.241

package/src/server/conversation/codexConfiguration.js

@@ -3,7 +3,8 @@ import { execFile } from "node:child_process";
 import { open, readFile, rename, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
-import { isPlainObject as isRecord, normalizeText } from "./normalize.js";
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeNullableText } from "./normalize.js";
 
 const execute = promisify(execFile);
 const CODEX_THREAD_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
@@ -40,9 +41,9 @@ export function codexAppServerThreadSettings({
       ...(config && typeof config === "object" && !Array.isArray(config) ? config : {})
     },
     cwd,
-    ...(typeof systemPrompt === "string" && systemPrompt.trim() ? { systemPrompt: normalizeText(systemPrompt) } : {}),
+    ...(typeof systemPrompt === "string" && systemPrompt.trim() ? { systemPrompt: normalizeNullableText(systemPrompt) } : {}),
     ...(hostContext ? { hostContext } : {}),
-    model: normalizeText(model) || effectiveSettings.model,
+    model: normalizeNullableText(model) || effectiveSettings.model,
     ...(effectiveSettings.modelProviderId ? { modelProvider: effectiveSettings.modelProviderId } : {}),
     sandbox
   };
@@ -73,11 +74,11 @@ export function codexAppServerTurnSettings({
   const settings = {
     approvalPolicy,
     cwd,
-    model: normalizeText(model) || effectiveSettings.model,
+    model: normalizeNullableText(model) || effectiveSettings.model,
     sandboxPolicy: externalSandbox ? { networkAccess: "enabled", type: "externalSandbox" } : sandboxPolicy
   };
   if (effectiveSettings.request.reasoning !== false) {
-    settings.effort = normalizeText(effort) || effectiveSettings.thinking;
+    settings.effort = normalizeNullableText(effort) || effectiveSettings.thinking;
   }
   if (effectiveSettings.request.summary !== false) {
     settings.summary = reasoningSummary;
@@ -115,22 +116,22 @@ export function codexInteractiveArguments({
 export async function codexAppServerProjectHookTrustConfig(provider, cwd = "", {
   persist = false
 } = {}) {
-  const normalizedCwd = normalizeText(cwd);
+  const normalizedCwd = normalizeNullableText(cwd);
   if (!normalizedCwd || typeof provider?.listHooks !== "function") {
     return null;
   }
   await provider.trustProject(normalizedCwd);
   const result = await provider.listHooks([normalizedCwd]);
   const record = (Array.isArray(result?.data) ? result.data : [])
-    .find((item) => normalizeText(item?.cwd) === normalizedCwd);
+    .find((item) => normalizeNullableText(item?.cwd) === normalizedCwd);
   const trustedHooks = (Array.isArray(record?.hooks) ? record.hooks : [])
     // Session flags contain the host's command hook. Trust its exact hash
     // alongside project hooks; unrelated account and plugin hooks stay separate.
     .filter((hook) => hook?.enabled === true && ["project", "sessionFlags"].includes(hook?.source))
     .map((hook) => ({
-      currentHash: normalizeText(hook?.currentHash),
-      key: normalizeText(hook?.key),
-      trustStatus: normalizeText(hook?.trustStatus)
+      currentHash: normalizeNullableText(hook?.currentHash),
+      key: normalizeNullableText(hook?.key),
+      trustStatus: normalizeNullableText(hook?.trustStatus)
     }))
     .filter(({ currentHash, key }) => key && currentHash);
   if (trustedHooks.length === 0) {
@@ -277,7 +278,7 @@ function deepFreezeCodexAppServerHelperConfig(value) {
 }
 
 function codexAppServerIsolationPolicyError(message = "", details = {}) {
-  const error = new Error(normalizeText(message) || "Codex cannot prove the helper execution policy.");
+  const error = new Error(normalizeNullableText(message) || "Codex cannot prove the helper execution policy.");
   error.code = "codex_policy_unenforceable";
   error.details = Object.freeze({ ...details });
   for (const [name, value] of Object.entries(error.details)) {
@@ -288,7 +289,7 @@ function codexAppServerIsolationPolicyError(message = "", details = {}) {
   return error;
 }
 
-/** Original native helper policy verification; hosts supply their profile policy. */
+/** Native helper isolation verification; hosts supply their profile policy. */
 export function createCodexAppServerIsolation({
   clientName = "jskit",
   minimumVersion = "0.151.0",
@@ -346,8 +347,8 @@ export function createCodexAppServerIsolation({
       );
     }
     const context = await provider.currentHelperExecutionContext();
-    const cwd = normalizeText(context?.cwd);
-    const accountIdentitySignature = normalizeText(context?.accountIdentitySignature);
+    const cwd = normalizeNullableText(context?.cwd);
+    const accountIdentitySignature = normalizeNullableText(context?.accountIdentitySignature);
     if (
       context?.executionMode !== "helper" ||
       !cwd ||
@@ -366,7 +367,7 @@ export function createCodexAppServerIsolation({
   }
 
   function codexAppServerSemanticVersionParts(value = "") {
-    const match = normalizeText(value).match(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u);
+    const match = normalizeNullableText(value).match(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u);
     if (!match) {
       return null;
     }
@@ -375,7 +376,7 @@ export function createCodexAppServerIsolation({
   }
 
   function codexAppServerUserAgentVersionParts(value = "") {
-    const userAgent = normalizeText(value);
+    const userAgent = normalizeNullableText(value);
     if (
       !userAgent ||
       userAgent.length > userAgentMaxLength ||
@@ -398,7 +399,7 @@ export function createCodexAppServerIsolation({
         { minimumVersion }
       );
     }
-    const userAgent = normalizeText(provider.currentServerInfo()?.userAgent);
+    const userAgent = normalizeNullableText(provider.currentServerInfo()?.userAgent);
     const actualParts = codexAppServerUserAgentVersionParts(userAgent);
     if (!actualParts) {
       throw createError(
@@ -482,8 +483,8 @@ export function createCodexAppServerIsolation({
     }
     const record = result.data[0];
     if (
-      normalizeText(record?.cwd) !== cwd ||
-      normalizeText(record?.cwd).length > hookFieldMaxLength ||
+      normalizeNullableText(record?.cwd) !== cwd ||
+      normalizeNullableText(record?.cwd).length > hookFieldMaxLength ||
       !Array.isArray(record.hooks) ||
       !Array.isArray(record.errors) ||
       record.hooks.length > hookMaxCount ||
@@ -500,10 +501,10 @@ export function createCodexAppServerIsolation({
       );
     }
     const hooks = record.hooks.map((hook) => {
-      const key = normalizeText(hook?.key);
-      const currentHash = normalizeText(hook?.currentHash);
-      const handlerType = normalizeText(hook?.handlerType);
-      const sourcePath = normalizeText(hook?.sourcePath);
+      const key = normalizeNullableText(hook?.key);
+      const currentHash = normalizeNullableText(hook?.currentHash);
+      const handlerType = normalizeNullableText(hook?.handlerType);
+      const sourcePath = normalizeNullableText(hook?.sourcePath);
       if (
         !key ||
         [key, currentHash, handlerType, sourcePath].some((field) => (
@@ -600,6 +601,21 @@ export function createCodexAppServerIsolation({
     return frozenConfig;
   }
 
+  function isolationConfigFrom(configResult, hookResult, cwd, { effort = "", summary = "" } = {}) {
+    const mcpServerNames = codexAppServerHelperMcpServerNames(configResult);
+    const hookState = codexAppServerHelperHookState(hookResult, cwd);
+    return {
+      mcpServerNames,
+      hookState,
+      config: codexAppServerHelperIsolationConfig({
+        effort,
+        summary,
+        hookKeys: hookState.hookKeys,
+        mcpServerNames
+      })
+    };
+  }
+
   async function codexAppServerHelperIsolationState(provider, { effort = "", summary = "" } = {}) {
     assertCodexAppServerHelperCompatibility(provider);
     if (
@@ -627,16 +643,13 @@ export function createCodexAppServerIsolation({
         "Codex app-server reconnected during helper policy verification."
       );
     }
-    const mcpServerNames = codexAppServerHelperMcpServerNames(configResult);
-    const hookState = codexAppServerHelperHookState(hookResult, executionContext.cwd);
+    const { mcpServerNames, hookState, config } = isolationConfigFrom(configResult, hookResult, executionContext.cwd, {
+      effort,
+      summary
+    });
     return Object.freeze({
       accountIdentitySignature: executionContext.accountIdentitySignature,
-      config: codexAppServerHelperIsolationConfig({
-        effort,
-        summary,
-        hookKeys: hookState.hookKeys,
-        mcpServerNames
-      }),
+      config,
       connectionGeneration: generation,
       executionCwd: executionContext.cwd,
       hookFingerprint: hookState.fingerprint,
@@ -654,7 +667,7 @@ export function createCodexAppServerIsolation({
   }
 
   function codexAppServerHelperVerificationFailure(error, cleanupError, threadId = "") {
-    const normalizedThreadId = normalizeText(threadId);
+    const normalizedThreadId = normalizeNullableText(threadId);
     if (!cleanupError) {
       error.codexAppServerHelperThreadId = normalizedThreadId;
       error.codexAppServerHelperThreadRetired = true;
@@ -686,34 +699,19 @@ export function createCodexAppServerIsolation({
     throw codexAppServerHelperVerificationFailure(error, cleanupError, threadId);
   }
 
-  async function startCodexAppServerHelperThread(provider, prepare) {
-    if (
-      typeof provider?.startThread !== "function" ||
-      typeof provider?.deleteThread !== "function"
-    ) {
-      throw createError(
-        "Codex helper execution cannot own and clean up its app-server thread."
-      );
-    }
-    const prepared = await prepare();
-    const thread = await provider.startThread(prepared.settings);
-    const threadId = normalizeText(thread?.id);
-    if (!threadId) {
-      throw createError(
-        "Codex app-server did not return a helper thread id."
-      );
-    }
+  // Re-inspect after the native thread exists; a changed surface retires it.
+  async function verifyHelperThread(provider, enforcement, thread, threadId, phase) {
     try {
       const verified = await codexAppServerHelperIsolationState(
         provider,
         {
-          effort: prepared.enforcement.config.model_reasoning_effort,
-          summary: prepared.enforcement.config.model_reasoning_summary
+          effort: enforcement.config.model_reasoning_effort,
+          summary: enforcement.config.model_reasoning_summary
         }
       );
-      if (!codexAppServerHelperIsolationMatches(prepared.enforcement, verified)) {
+      if (!codexAppServerHelperIsolationMatches(enforcement, verified)) {
         throw createError(
-          "Codex execution surfaces changed while the helper thread was starting."
+          `Codex execution surfaces changed while the helper thread was ${phase}.`
         );
       }
       return Object.freeze({
@@ -730,6 +728,26 @@ export function createCodexAppServerIsolation({
     }
   }
 
+  async function startCodexAppServerHelperThread(provider, prepare) {
+    if (
+      typeof provider?.startThread !== "function" ||
+      typeof provider?.deleteThread !== "function"
+    ) {
+      throw createError(
+        "Codex helper execution cannot own and clean up its app-server thread."
+      );
+    }
+    const prepared = await prepare();
+    const thread = await provider.startThread(prepared.settings);
+    const threadId = normalizeNullableText(thread?.id);
+    if (!threadId) {
+      throw createError(
+        "Codex app-server did not return a helper thread id."
+      );
+    }
+    return verifyHelperThread(provider, prepared.enforcement, thread, threadId, "starting");
+  }
+
   async function resumeCodexAppServerHelperThread(provider, threadId, prepare) {
     if (
       typeof provider?.resumeThread !== "function" ||
@@ -739,7 +757,7 @@ export function createCodexAppServerIsolation({
         "Codex helper execution cannot safely resume and clean up its app-server thread."
       );
     }
-    const normalizedThreadId = normalizeText(threadId);
+    const normalizedThreadId = normalizeNullableText(threadId);
     if (!normalizedThreadId) {
       throw createError(
         "Codex helper resume requires a controller-owned thread id."
@@ -751,42 +769,11 @@ export function createCodexAppServerIsolation({
       normalizedThreadId,
       prepared.settings
     );
-    try {
-      const verified = await codexAppServerHelperIsolationState(
-        provider,
-        {
-          effort: enforcement.config.model_reasoning_effort,
-          summary: enforcement.config.model_reasoning_summary
-        }
-      );
-      if (!codexAppServerHelperIsolationMatches(enforcement, verified)) {
-        throw createError(
-          "Codex execution surfaces changed while the helper thread was resuming."
-        );
-      }
-      return Object.freeze({
-        enforcement: verified,
-        thread,
-        threadId: normalizedThreadId
-      });
-    } catch (error) {
-      await throwAfterCodexAppServerHelperVerificationFailure({
-        error,
-        provider,
-        threadId: normalizedThreadId
-      });
-    }
+    return verifyHelperThread(provider, enforcement, thread, normalizedThreadId, "resuming");
   }
 
   function configuration({ configResult, hookResult, workdir, effort = "", summary = "" }) {
-    const mcpServerNames = codexAppServerHelperMcpServerNames(configResult);
-    const hookState = codexAppServerHelperHookState(hookResult, workdir);
-    return codexAppServerHelperIsolationConfig({
-      effort,
-      summary,
-      hookKeys: hookState.hookKeys,
-      mcpServerNames
-    });
+    return isolationConfigFrom(configResult, hookResult, workdir, { effort, summary }).config;
   }
 
   // Native Helper requests retain their verified configuration object and the
@@ -924,19 +911,19 @@ export function codexCatalogReasoningEfforts(model = {}) {
   return new Set((Array.isArray(model?.supportedReasoningEfforts)
     ? model.supportedReasoningEfforts
     : [])
-    .map((option) => normalizeText(option?.reasoningEffort))
+    .map((option) => normalizeNullableText(option?.reasoningEffort))
     .filter(Boolean));
 }
 
 export function codexCatalogModels(rows) {
   return rows.map((model) => ({
-    id: normalizeText(model.model),
-    label: normalizeText(model.displayName) || normalizeText(model.model),
+    id: normalizeNullableText(model.model),
+    label: normalizeNullableText(model.displayName) || normalizeNullableText(model.model),
     status: "available",
     variants: [...codexCatalogReasoningEfforts(model)]
       .map((variantId) => ({
-        id: normalizeText(variantId),
-        label: normalizeText(variantId).replace(/^./u, (value) => value.toUpperCase())
+        id: normalizeNullableText(variantId),
+        label: normalizeNullableText(variantId).replace(/^./u, (value) => value.toUpperCase())
       }))
   }));
 }
@@ -991,12 +978,21 @@ export function codexProviderConfiguration(provider, apiKey) {
   };
 }
 
+/** Where a curated provider home keeps the model catalogue its config.toml names. */
+export function codexProviderCatalogPath(codexHome) {
+  return path.join(codexHome, "models.json");
+}
+
+function codexProviderCatalogSetting(codexHome) {
+  return `model_catalog_json = ${JSON.stringify(codexProviderCatalogPath(codexHome))}`;
+}
+
 /** Format a private native config file from an already-authorized provider and key. */
 export function codexProviderFileConfiguration(provider, key, codexHome) {
   return [
     `model = ${JSON.stringify(provider.models[0].id)}`,
     `model_provider = ${JSON.stringify(provider.id)}`,
-    `model_catalog_json = ${JSON.stringify(path.join(codexHome, "models.json"))}`,
+    codexProviderCatalogSetting(codexHome),
     `model_reasoning_effort = ${JSON.stringify(provider.models[0].defaultThinking)}`,
     'model_reasoning_summary = "none"',
     `web_search = "${provider.webSearch ? "live" : "disabled"}"`,
@@ -1010,6 +1006,24 @@ export function codexProviderFileConfiguration(provider, key, codexHome) {
   ].join("\n");
 }
 
+/**
+ * Copy a curated provider home's config and catalogue into another home, with
+ * the copied config naming the copied catalogue. A config that does not name
+ * its own home's catalogue exactly once is refused rather than left pointing
+ * at the source home.
+ */
+export async function copyCodexProviderHome(sourceHome, targetHome) {
+  const config = await readFile(path.join(sourceHome, "config.toml"), "utf8");
+  const sourceSetting = codexProviderCatalogSetting(sourceHome);
+  if (config.split(sourceSetting).length !== 2) {
+    throw new Error("Codex provider config does not name its own model catalogue.");
+  }
+  await writeFile(codexProviderCatalogPath(targetHome),
+    await readFile(codexProviderCatalogPath(sourceHome)), { mode: 0o600 });
+  await writeFile(path.join(targetHome, "config.toml"),
+    config.replace(sourceSetting, codexProviderCatalogSetting(targetHome)), { mode: 0o600 });
+}
+
 export async function verifyCodexProviderKey(provider, apiKey, fetchImpl = fetch) {
   let response;
   try {
@@ -1057,9 +1071,9 @@ export function createCodexAccountReader({
 } = {}) {
   function codexAppServerHelperAuthError(code = "", message = "") {
     const error = new Error(
-      normalizeText(message) || "Codex helper authentication is unavailable. Reconnect Codex and retry."
+      normalizeNullableText(message) || "Codex helper authentication is unavailable. Reconnect Codex and retry."
     );
-    error.code = normalizeText(code) || `${errorPrefix}codex_helper_auth_unavailable`;
+    error.code = normalizeNullableText(code) || `${errorPrefix}codex_helper_auth_unavailable`;
     return error;
   }
 
@@ -1079,7 +1093,7 @@ export function createCodexAccountReader({
   function codexAccountIdentitySignature(authMode = "", identity = "") {
     return `sha256:${createHash("sha256")
       .update(`${identityNamespace}\0`, "utf8")
-      .update(normalizeText(authMode), "utf8")
+      .update(normalizeNullableText(authMode), "utf8")
       .update("\0", "utf8")
       .update(String(identity || ""), "utf8")
       .digest("hex")}`;
@@ -1137,7 +1151,7 @@ export function createCodexAccountReader({
   }
 
   async function readCodexSelectedAccountAuth(options = {}) {
-    const toolHomeSource = normalizeText(options.toolHomeSource);
+    const toolHomeSource = normalizeNullableText(options.toolHomeSource);
     if (!toolHomeSource || !path.isAbsolute(toolHomeSource)) {
       throw codexAppServerHelperAuthError(
         `${errorPrefix}codex_helper_auth_unavailable`,
@@ -1145,7 +1159,7 @@ export function createCodexAccountReader({
       );
     }
     const auth = await readBoundedCodexAuthJson(path.join(toolHomeSource, ".codex", "auth.json"));
-    const storedMode = normalizeText(auth.auth_mode).toLowerCase();
+    const storedMode = normalizeNullableText(auth.auth_mode).toLowerCase();
     if (storedMode === "chatgpt") {
       const tokens = isRecord(auth.tokens) ? auth.tokens : {};
       const accountId = boundedCodexAuthText(tokens.account_id, {

package/src/server/conversation/codexConversationStore.js

@@ -0,0 +1,189 @@
+import { normalizeNullableText } from "./normalize.js";
+import { createReentrantConversationStorage } from "./storage.js";
+import { isCompletedEnvelopeTurn } from "./transcript.js";
+import { conversationAgentRunRecord, conversationAgentRunEvent } from "./agentRun.js";
+
+/** The original native run occupies its bound conversation segment. Reading a
+ * binding without a run never constructs historical ownership or writes state.
+ */
+export function createCodexConversationRunStore({ storage, scope, segmentId, isCurrent, clock = () => new Date() } = {}) {
+  if (typeof isCurrent !== "function") throw new TypeError("A native run store requires its provider ownership fence.");
+  storage = createReentrantConversationStorage(storage);
+  const runId = "codex_app_server";
+
+  function assertScope(sessionId, requestedRunId = runId) {
+    if (sessionId !== scope) throw new Error("The native run belongs to another conversation.");
+    if (normalizeNullableText(requestedRunId) !== runId) throw new TypeError("This binding stores only its Codex app-server run.");
+    if (!isCurrent()) throw new Error("A retired provider cannot change a native binding.");
+  }
+
+  async function currentMetadata(transaction) {
+    const metadata = await transaction.readMetadata();
+    if (!isCurrent() || metadata.runtime?.segmentId !== segmentId || metadata.runtime?.engine !== "codex") {
+      throw new Error("A retired native conversation cannot change the current binding.");
+    }
+    return metadata;
+  }
+
+  async function readAgentRun(sessionId, requestedRunId) {
+    assertScope(sessionId, requestedRunId);
+    return storage.read(scope, async transaction => {
+      const metadata = await currentMetadata(transaction);
+      return conversationAgentRunRecord(metadata.runtime.binding?.codexAppServerRun, runId);
+    });
+  }
+
+  function mutateSession(sessionId, operation) {
+    assertScope(sessionId);
+    return storage.write(scope, async transaction => {
+      await currentMetadata(transaction);
+      return operation(transaction);
+    });
+  }
+
+  return Object.freeze({
+    readAgentRun,
+    mutateSession,
+    async getSession(sessionId) {
+      const run = await readAgentRun(sessionId, runId);
+      return { sessionId, agentRuns: run ? [run] : [] };
+    },
+    async writeAgentRunEvent(sessionId, requestedRunId, input = {}) {
+      assertScope(sessionId, requestedRunId);
+      return mutateSession(sessionId, async transaction => {
+        const previous = await readAgentRun(sessionId, runId) || { events: [], id: runId };
+        const record = conversationAgentRunEvent(previous, runId, input, { now: clock });
+        const metadata = await currentMetadata(transaction);
+        metadata.runtime.binding.codexAppServerRun = record;
+        await transaction.writeMetadata(metadata);
+        return record;
+      });
+    }
+  });
+}
+
+/** The native owner uses the existing transcript and transient streams through
+ * the same fenced transaction as its original run. Its private delivery read is
+ * a projection of the one authored request, never another stored journal.
+ */
+export function createCodexConversationStore({ storage, scope, segmentId, isCurrent, transcript, streams } = {}) {
+  const runStore = createCodexConversationRunStore({ storage, scope, segmentId, isCurrent });
+  const assertCurrent = sessionId => {
+    if (sessionId !== scope || !isCurrent()) throw new Error("A retired provider cannot change this conversation.");
+  };
+  const reader = name => (sessionId, ...args) => {
+    assertCurrent(sessionId);
+    return transcript[name](sessionId, ...args);
+  };
+  async function nativeAuthorship(transaction, identity) {
+    if (!identity?.threadId || !identity.turnId) return undefined;
+    const { runtime } = await transaction.readMetadata();
+    const run = runtime.binding?.codexAppServerRun;
+    if (runtime.segmentId !== segmentId || runtime.binding.threadId !== identity.threadId ||
+        run?.providerThreadId !== identity.threadId || run.providerTurnId !== identity.turnId || !run.outerTurnId) return undefined;
+    for (const turnId of (await transaction.listTurnIds()).reverse()) {
+      const turn = await transaction.readTurn(turnId);
+      if (turn?.metadata?.runtime?.segmentId !== segmentId) continue;
+      if (turn.user?.messageId === run.outerTurnId) return { origin: "user", messageId: run.outerTurnId, turnId };
+      if (turn.system?.messageId === run.outerTurnId && turn.system.origin === "application") {
+        return { origin: "application", messageId: run.outerTurnId, turnId,
+          ...(isCompletedEnvelopeTurn(turn) ? { completedEnvelope: true } : {}) };
+      }
+    }
+    const request = runtime.request;
+    if (request?.messageId === run.outerTurnId && ["user", "application"].includes(request.origin)) {
+      return { origin: request.origin, messageId: request.messageId,
+        ...(request.origin === "application" && request.completedEnvelope === true ? { completedEnvelope: true } : {}) };
+    }
+    return undefined;
+  }
+  const writer = name => (sessionId, input = {}) => runStore.mutateSession(sessionId, async transaction => {
+    const authorship = await nativeAuthorship(transaction, input.nativeIdentity);
+    if (authorship?.completedEnvelope && !authorship.turnId) {
+      throw new Error("The native output's original turn no longer exists.");
+    }
+    // Queued human rows do not own an already admitted private native response.
+    // Corrections retain their original explicit target and message identity.
+    const written = await transcript[name](sessionId, {
+      ...input, ...(name !== "upsertConversationAssistantMessage" && authorship?.completedEnvelope && authorship.turnId
+        ? { turnId: authorship.turnId } : {})
+    });
+    if (!written || written.metadata?.runtime?.segmentId) return written;
+    const origin = authorship?.origin;
+    await transaction.updateTurnMetadata(written.turnId, { runtime: {
+      status: "complete", engine: "codex", segmentId, ...(origin ? { origin } : {}),
+      ...(input.nativeIdentity?.turnId ? { nativeTurnId: input.nativeIdentity.turnId } : {})
+    } });
+    return transaction.readTurn(written.turnId);
+  });
+  return Object.freeze({
+    ...runStore,
+    readConversationLog: reader("readConversationLog"),
+    conversationMessageIdExists: reader("conversationMessageIdExists"),
+    writeConversationAssistantMessage: writer("writeConversationAssistantMessage"),
+    writeConversationCommentaryMessage: writer("writeConversationCommentaryMessage"),
+    writeConversationThinkingMessage: writer("writeConversationThinkingMessage"),
+    upsertConversationAssistantMessage: writer("upsertConversationAssistantMessage"),
+    async writeConversationUserMessage(sessionId, input = {}) {
+      return runStore.mutateSession(sessionId, async transaction => {
+        if (input.messageId && await transaction.hasMessage(input.messageId)) return null;
+        const metadata = await transaction.readMetadata();
+        const request = input.authoredRequest?.messageId === input.messageId ? input.authoredRequest
+          : metadata.runtime.request?.messageId === input.messageId ? metadata.runtime.request : null;
+        if (!request) {
+          const written = await transcript.writeConversationUserMessage(sessionId, input);
+          if (!written) return null;
+          await transaction.updateTurnMetadata(written.turnId, { runtime: {
+            status: "running", engine: "codex", segmentId, origin: "user",
+            ...(input.nativeIdentity?.turnId ? { nativeTurnId: input.nativeIdentity.turnId } : {})
+          } });
+          return transaction.readTurn(written.turnId);
+        }
+        const turnId = await transaction.nextTurnId();
+        await transaction.appendMessage(turnId, {
+          role: request.origin === "application" ? "system" : "user",
+          messageId: request.messageId, text: request.text, origin: request.origin || "user",
+          attachments: request.attachments || input.attachments || [], at: request.at || new Date().toISOString(),
+          ...(request.data !== undefined ? { data: request.data } : {}), ...(request.goal ? { goal: request.goal } : {}),
+          turnMetadata: { ...input.turnMetadata, runtime: { ...input.turnMetadata?.runtime,
+            status: "running", engine: "codex", segmentId, origin: request.origin || "user",
+            ...(metadata.runtime.request?.messageId === input.messageId && metadata.runtime.request.completedEnvelope === true
+              ? { completedEnvelope: true } : {}),
+            ...(input.nativeIdentity?.turnId ? { nativeTurnId: input.nativeIdentity.turnId } : {}),
+            ...(request.goal ? { goalMessageId: request.messageId } : {}) } }
+        });
+        return transaction.readTurn(turnId);
+      });
+    },
+    readMetadataValue(sessionId, key) {
+      assertCurrent(sessionId);
+      if (key !== "assistant_delivery") throw new Error("The native conversation requested unknown delivery metadata.");
+      return storage.read(sessionId, async transaction => {
+        const { runtime } = await transaction.readMetadata();
+        if (!isCurrent() || runtime.segmentId !== segmentId || runtime.engine !== "codex") {
+          throw new Error("A retired native conversation cannot read current delivery metadata.");
+        }
+        const request = runtime.request;
+        return JSON.stringify({ engines: { codex: { pending: request && { ...request,
+          displayMessage: request.displayMessage ?? request.text,
+          displayAttachments: request.displayAttachments ?? request.attachments } } } });
+      });
+    },
+    updateConversationStream(sessionId, input) {
+      return runStore.mutateSession(sessionId, async transaction => {
+        const authorship = await nativeAuthorship(transaction, input.nativeIdentity);
+        return streams.update(sessionId, { ...input, origin: authorship?.origin, authorship });
+      });
+    },
+    completeConversationStreamMessage(sessionId, messageId, options) {
+      assertCurrent(sessionId);
+      if (options?.nativeIdentity) return runStore.mutateSession(sessionId, async transaction => {
+        const authorship = await nativeAuthorship(transaction, options.nativeIdentity);
+        return streams.complete(sessionId, messageId, { ...options, authorship,
+          ...(!authorship ? { text: undefined } : {}) });
+      });
+      return streams.complete(sessionId, messageId, options);
+    },
+    clearConversationStream(sessionId) { assertCurrent(sessionId); return streams.clear(sessionId); }
+  });
+}