@jskit-ai/assistant-core 0.1.240 → 0.1.242

package/src/server/conversation/codexTurnRecovery.js

@@ -124,15 +124,26 @@ export function createCodexTurnRecovery({
     const delayMs = failureDetail
       ? Math.max(0, failureDetail.expiresAt - Date.now())
       : codexAppServerFinalizingRemainingMs({ completedAt, state: "finalizing", updatedAt });
-    const timer = setTimeout(() => {
+    // One record per pending deadline: `recovery` is the in-flight expiry
+    // (retained-timer policy only), `expiresAt` the first deadline that a later
+    // failure-detail grace may not exceed, `failureDetail` a deferred provider
+    // failure, and `startedAt` the post-read clock that rereads must keep.
+    const entry = {
+      timer: null,
+      recovery: null,
+      expiresAt: failureDetailGraceMs > 0 ? Date.now() + delayMs : null,
+      failureDetail,
+      startedAt: !failureDetail && finalizingGraceAfterHistoryRead ? completedAt : ""
+    };
+    entry.timer = setTimeout(() => {
       if (failureDetail) {
         notificationQueue.run({ projectContext, provider: failureDetail.provider, sessionId: normalizedSessionId }, async () => {
-          if (codexAppServerFinalizingTimers.get(key) !== timer) return;
+          if (codexAppServerFinalizingTimers.get(key) !== entry) return;
           try {
             return await stopCodexAppServerTurnWithProviderFailure(normalizedSessionId, normalizedThreadId, normalizedTurnId,
               { ...failureDetail, failureDetailReady: true });
           } finally {
-            if (codexAppServerFinalizingTimers.get(key) === timer) {
+            if (codexAppServerFinalizingTimers.get(key) === entry) {
               clearCodexAppServerFinalizingTimer(normalizedSessionId, normalizedThreadId, normalizedTurnId);
             }
           }
@@ -151,11 +162,11 @@ export function createCodexTurnRecovery({
         )
       );
       if (retainFinalizingTimer) {
-        timer.finalizingRecovery = recovery;
+        entry.recovery = recovery;
         void recovery.then(
-          () => { if (timer.finalizingRecovery === recovery) delete timer.finalizingRecovery; },
+          () => { if (entry.recovery === recovery) entry.recovery = null; },
           error => {
-            if (timer.finalizingRecovery === recovery) delete timer.finalizingRecovery;
+            if (entry.recovery === recovery) entry.recovery = null;
             debugLog("appServerFinalizingRecovery.error", {
               error: debugError(error), sessionId: normalizedSessionId,
               threadId: normalizedThreadId, turnId: normalizedTurnId
@@ -166,11 +177,8 @@ export function createCodexTurnRecovery({
         void recovery;
       }
     }, delayMs);
-    if (failureDetailGraceMs > 0) timer.finalizingExpiresAt = Date.now() + delayMs;
-    if (failureDetail) timer.failureDetail = failureDetail;
-    else if (finalizingGraceAfterHistoryRead) timer.finalizingStartedAt = completedAt;
-    timer.unref?.();
-    codexAppServerFinalizingTimers.set(key, timer);
+    entry.timer.unref?.();
+    codexAppServerFinalizingTimers.set(key, entry);
   }
 
   async function reconcileCodexAppServerActiveTurn(session = {}, {
@@ -194,8 +202,8 @@ export function createCodexTurnRecovery({
             status: trackedTurn.status || "completed"
           }
         );
-        const runtime = await createRuntime();
-        return runtime.getSession(sessionId);
+        const activeRuntime = runtime || await createRuntime();
+        return activeRuntime.getSession(sessionId);
       }
       return session;
     }
@@ -313,12 +321,13 @@ export function createCodexTurnRecovery({
         scheduleCodexAppServerActiveRecovery(sessionId);
         return currentSession;
       }
-      if (!promptDeliveryIsLocal && (!providerTurnId || !codexAppServerTurnStatusIsComplete(status))) {
-        return failOrphanedCodexAppServerPromptDelivery(activeRuntime, currentSession, currentTurn);
-      }
+      // A local prompt delivery owns the outcome of its own starting turn.
       if (promptDeliveryIsLocal) {
         return currentSession;
       }
+      if (!providerTurnId || !codexAppServerTurnStatusIsComplete(status)) {
+        return failOrphanedCodexAppServerPromptDelivery(activeRuntime, currentSession, currentTurn);
+      }
       await markCodexAppServerProviderTurnActive(sessionId, {
         source: "active_reconciliation",
         status: "inProgress",
@@ -603,7 +612,7 @@ export function createCodexTurnRecovery({
     const normalizedTurnId = normalizeCodexRunText(turnId);
     const key = codexAppServerResultFinalizationKey(normalizedSessionId, normalizedThreadId, normalizedTurnId);
     const priorTimer = retainFinalizingTimer ? codexAppServerFinalizingTimers.get(key) : null;
-    if (!timerRecovery && priorTimer?.finalizingRecovery) return priorTimer.finalizingRecovery;
+    if (!timerRecovery && priorTimer?.recovery) return priorTimer.recovery;
     const runtime = await createRuntime();
     const session = await runtime.getSession(normalizedSessionId);
     const turn = turnState(session);
@@ -651,9 +660,9 @@ export function createCodexTurnRecovery({
         clearCodexAppServerFinalizingTimer(normalizedSessionId, normalizedThreadId, normalizedTurnId);
         return { ok: true, processed: false, reason: "goal_continuation_pending" };
       }
-      if (!timerRecovery && timer?.finalizingRecovery) return timer.finalizingRecovery;
+      if (!timerRecovery && timer?.recovery) return timer.recovery;
       // This local clock never changes the native completion timestamp.
-      graceTurn = { ...currentTurn, completedAt: timer?.finalizingStartedAt || readReturnedAt };
+      graceTurn = { ...currentTurn, completedAt: timer?.startedAt || readReturnedAt };
     }
     if (!codexAppServerFinalizingExpired(graceTurn)) {
       scheduleCodexAppServerFinalizingRecovery(normalizedSessionId, normalizedThreadId, normalizedTurnId, {
@@ -920,9 +929,11 @@ export function createCodexTurnRecovery({
       }
     }
     const runtime = await createRuntime();
-    const session = await runtime.getSession(normalizedSessionId);
-    const turn = turnState(session);
-    if (!codexAppServerTurnCanReceiveProviderCompletion(turn, normalizedThreadId, normalizedTurnId)) {
+    const staleFailure = async () => {
+      const turn = turnState(await runtime.getSession(normalizedSessionId));
+      if (codexAppServerTurnCanReceiveProviderCompletion(turn, normalizedThreadId, normalizedTurnId)) {
+        return null;
+      }
       debugLog("appServerTurn.failure.stale", {
         currentState: turn.state,
         currentStatus: turn.status,
@@ -938,6 +949,10 @@ export function createCodexTurnRecovery({
         processed: false,
         reason: "stale_turn_state"
       };
+    };
+    const staleBeforeRecovery = await staleFailure();
+    if (staleBeforeRecovery) {
+      return staleBeforeRecovery;
     }
     const key = codexAppServerResultFinalizationKey(normalizedSessionId, normalizedThreadId, normalizedTurnId);
     const pendingTimer = codexAppServerFinalizingTimers.get(key);
@@ -949,7 +964,7 @@ export function createCodexTurnRecovery({
           failureDetail: { error, ok, outcome: resolvedOutcome, provider, status: normalizedStatus,
             usageLimitExceeded, verifyInactive,
             expiresAt: Math.min(observedAt + failureDetailGraceMs,
-              pendingTimer?.finalizingExpiresAt ?? Infinity) }
+              pendingTimer?.expiresAt ?? Infinity) }
         });
       }
       return { ok: true, processed: false, reason: "failure_detail_pending", status: normalizedStatus };
@@ -972,8 +987,13 @@ export function createCodexTurnRecovery({
         return recovered;
       }
     }
-    // History recovery awaited the provider. Confirm activity again before
-    // publishing a failure, because the goal may have continued in that gap.
+    // History recovery awaited the provider. Confirm ownership and activity
+    // again before publishing a failure: a successor, Stop or goal
+    // continuation may own the run after that gap.
+    const staleAfterRecovery = await staleFailure();
+    if (staleAfterRecovery) {
+      return staleAfterRecovery;
+    }
     if (verifyInactive && await codexAppServerProviderBlocksTurnRelease(normalizedSessionId, provider, normalizedThreadId, normalizedTurnId, {
       source: "provider_failure"
     })) {
@@ -1018,9 +1038,6 @@ export function createCodexTurnRecovery({
     const normalizedThreadId = normalizeCodexRunText(threadId);
     const normalizedStatus = normalizeCodexRunText(status) || "completed";
     const normalizedTurnId = await resolveCodexAppServerTurnId(normalizedSessionId, normalizedThreadId, turnId);
-    const runtime = await createRuntime();
-    const currentSession = await runtime.getSession(normalizedSessionId);
-    const currentTurn = turnState(currentSession);
     const recovered = await recoverCodexAppServerFinalResponseBeforeOutcome(
       normalizedSessionId,
       normalizedThreadId,
@@ -1030,6 +1047,10 @@ export function createCodexTurnRecovery({
     if (recovered?.processed) {
       return recovered;
     }
+    // The history read can outlive this turn: a successor or Stop may own the
+    // run by now, so the outcome is decided against the run read after it.
+    const runtime = await createRuntime();
+    const currentTurn = turnState(await runtime.getSession(normalizedSessionId));
     if (!codexAppServerTurnCanReceiveProviderCompletion(currentTurn, normalizedThreadId, normalizedTurnId)) {
       codexAppServerFinalizedTurns.add(codexAppServerResultFinalizationKey(
         normalizedSessionId,

package/src/server/conversation/codexTurnState.js

@@ -1,20 +1,21 @@
-import { normalizeText, isPlainObject } from "./normalize.js";
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeNullableText } from "./normalize.js";
 import { codexAppServerStatusFromValue, codexAppServerThreadRawValue } from "./codexEvents.js";
 
 function codexAppServerTurnStatusIsActive(status = "") {
-  return normalizeText(status) === "inProgress";
+  return normalizeNullableText(status) === "inProgress";
 }
 
 function codexAppServerTurnStatusIsComplete(status = "") {
-  return ["completed", "interrupted", "failed"].includes(normalizeText(status));
+  return ["completed", "interrupted", "failed"].includes(normalizeNullableText(status));
 }
 
 function codexAppServerTurnStatusIsSuccessfulComplete(status = "") {
-  return normalizeText(status) === "completed";
+  return normalizeNullableText(status) === "completed";
 }
 
 function codexAppServerTurnStatusIsProviderFailure(status = "") {
-  return ["failed", "interrupted"].includes(normalizeText(status));
+  return ["failed", "interrupted"].includes(normalizeNullableText(status));
 }
 
 function codexAppServerThreadStatus(thread = {}) {
@@ -26,7 +27,7 @@ function codexAppServerThreadStatus(thread = {}) {
   if (codexAppServerTurnStatusIsActive(liveStatus)) {
     return liveStatus;
   }
-  if (isPlainObject(thread.observedTurn)) {
+  if (isRecord(thread.observedTurn)) {
     const observedStatus = codexAppServerStatusFromValue(thread.observedTurn.status);
     if (observedStatus) {
       return observedStatus;
@@ -38,7 +39,7 @@ function codexAppServerThreadStatus(thread = {}) {
 async function codexAppServerReadThreadStatus(provider = null, threadId = "", {
   observeLatestTurn = false
 } = {}) {
-  const normalizedThreadId = normalizeText(threadId || "");
+  const normalizedThreadId = normalizeNullableText(threadId || "");
   if (!normalizedThreadId) {
     return null;
   }
@@ -54,7 +55,7 @@ async function codexAppServerReadThreadStatus(provider = null, threadId = "", {
     });
     const observedTurn = Array.isArray(response?.data) ? response.data[0] : null;
     if (provider.isControlProbeTurn?.(normalizedThreadId, observedTurn?.id)) return thread;
-    return isPlainObject(observedTurn)
+    return isRecord(observedTurn)
       ? {
           ...thread,
           observedTurn
@@ -199,7 +200,9 @@ export function codexAppServerTurnState(session = {}, normalizeRunState = normal
     error: "",
     goalStatus: "",
     goalThreadId: "",
+    inputSource: "",
     outerTurnId: "",
+    phase: "",
     runId: "",
     runState: "",
     startedAt: "",
@@ -298,6 +301,12 @@ export function codexAppServerTurnKey(threadId = "", turnId = "") {
   return `${normalizeCodexRunText(threadId)}:${normalizeCodexRunText(turnId)}`;
 }
 
+// Identity of a native outer turn. Terminal turns and persistent-conversation
+// checkpoints must agree on it, so both build it here.
+export function codexAppServerNativeOuterTurnId(threadId = "", turnId = "") {
+  return `codex:${threadId}:${turnId}`;
+}
+
 export function codexAppServerAgentRunPatch({
   error = "",
   inputSource = "",
@@ -336,7 +345,7 @@ export function codexAppServerAgentRunPatch({
   // owner's id would checkpoint two different turns with one identity.
   const normalizedOuterTurnId = normalizeCodexRunText(outerTurnId) ||
     (normalizedInputSource === "terminal" && normalizedRunState === CODEX_APP_SERVER_RUN_STATE.ACTIVE && !sameActiveTurn
-      ? `codex:${normalizeCodexRunText(threadId)}:${normalizeCodexRunText(turnId)}`
+      ? codexAppServerNativeOuterTurnId(normalizeCodexRunText(threadId), normalizeCodexRunText(turnId))
       : normalizeCodexRunText(currentRun?.outerTurnId));
   if (normalizedOuterTurnId) {
     patch.outerTurnId = normalizedOuterTurnId;
@@ -387,6 +396,18 @@ export function codexAppServerRunIdentityForPatch(session = {}, {
   };
 }
 
+// A settling writer names the turn it settles. While another turn owns the
+// active run, that write belongs to a predecessor and must not end the run.
+export function codexAppServerRunPatchSettlesOtherActiveTurn(currentTurn = {}, patch = {}) {
+  const currentTurnId = normalizeCodexRunText(currentTurn.turnId);
+  const patchTurnId = normalizeCodexRunText(patch.providerTurnId);
+  return currentTurn.active === true &&
+    !codexAppServerRunStateIsActive(patch.state) &&
+    Boolean(currentTurnId) &&
+    Boolean(patchTurnId) &&
+    currentTurnId !== patchTurnId;
+}
+
 export function codexAppServerRunPatchIsStaleAfterTerminalState(currentTurn = {}, patch = {}, normalizeRunState = normalizeCodexAppServerRunState) {
   const currentRunState = normalizeRunState(currentTurn.runState);
   const patchRunState = normalizeRunState(patch.state);
@@ -413,7 +434,7 @@ function codexAppServerErrorMessage(value, fallback = "Codex could not be prepar
 }
 
 export function codexAppServerSteerFailure(result = {}, steerFailedCode = "codex_turn_steer_failed") {
-  if (!isPlainObject(result)) {
+  if (!isRecord(result)) {
     return null;
   }
   if (result.ok !== false) {
@@ -464,7 +485,7 @@ function codexAppServerMessageDeferred({
 }
 
 export function codexAppServerInterruptFailure(result = {}, interruptFailedCode = "codex_turn_interrupt_failed") {
-  if (!isPlainObject(result)) {
+  if (!isRecord(result)) {
     return null;
   }
   if (result.ok !== false && result.interrupted !== false) {
@@ -522,14 +543,14 @@ export function codexAppServerMessageText(input = {}) {
   if (typeof input === "string") {
     return normalizeCodexRunText(input);
   }
-  if (!isPlainObject(input)) {
+  if (!isRecord(input)) {
     return "";
   }
   return normalizeCodexRunText(input.message);
 }
 
 export function codexAppServerMessageDisplayText(input = {}, fallback = "") {
-  if (!isPlainObject(input)) {
+  if (!isRecord(input)) {
     return normalizeCodexRunText(fallback || input);
   }
   return normalizeCodexRunText(input.displayMessage || input.message || fallback);

package/src/server/conversation/commandWrapper.js

@@ -1,6 +1,9 @@
 import { isAbsolute } from "node:path";
 import { fileURLToPath } from "node:url";
 
+// Always single-quotes, unlike codexProvider's shellQuote, which leaves plain
+// tokens bare. Wrapped hook commands keep their exact quoted form, which
+// conversationCommandWrapper.test.js asserts, so the two are not merged.
 const shellQuote = value => `'${value.replaceAll("'", `'"'"'`)}'`;
 
 export function validateCommandWrapper(wrapper) {

package/src/server/conversation/deliveryTiming.js

@@ -1,21 +1,30 @@
-// Finer marks within each phase locate slow work. Hosts may mark git-actor
-// and genesis-rendered while preparing a native prompt.
+// Finer marks within each phase locate slow work. Hosts declare any marks of
+// their own preparation through hostStages.
 const stages = new Set([
   "received", "preparation-started", "authorized", "history-read", "state-read", "request-saved",
   "input-prepared", "provider-started", "duplicate-checked", "native-history-read", "process-ready",
-  "git-actor", "genesis-rendered", "prompt-rendered", "metadata-ready", "runtime-ready", "dispatch-started",
+  "prompt-rendered", "metadata-ready", "runtime-ready", "dispatch-started",
   "native-acknowledged", "receipt-written", "state-active", "receipt-persisted", "admission-authorized",
   "turn-located", "accepted", "first-response", "failed"
 ]);
+const hostStagePattern = /^[a-z][a-z-]{0,63}$/u;
+
+export function normalizeConversationDeliveryHostStages(hostStages = []) {
+  if (!Array.isArray(hostStages) || hostStages.some(stage => typeof stage !== "string" || !hostStagePattern.test(stage))) {
+    throw new TypeError("Host delivery stages must be lowercase hyphenated names.");
+  }
+  return Object.freeze([...new Set(hostStages)]);
+}
 
 // Observer results are never awaited and failures cannot change delivery.
-export function createConversationDeliveryTiming({ engine, conversationId, messageId, report, clock = () => performance.now() }) {
+export function createConversationDeliveryTiming({ engine, conversationId, messageId, report, hostStages = [],
+  clock = () => performance.now() }) {
   const startedAt = clock();
   let previousAt = startedAt;
   let previousStage = "";
   const timings = {};
   return stage => {
-    if (!report || !stages.has(stage) || Object.hasOwn(timings, stage)) return;
+    if (!report || !(stages.has(stage) || hostStages.includes(stage)) || Object.hasOwn(timings, stage)) return;
     const at = clock();
     timings[stage] = Math.max(0, at - startedAt);
     const event = { engine, conversationId, messageId, stage, previousStage,

package/src/server/conversation/index.js

@@ -14,3 +14,4 @@ export { createConversationHookBridge } from "./hookBridge.js";
 export { nativeConversationStoragePolicy } from "./nativeStorage.js";
 export { createConversationProcessIdentity } from "./localExecution.js";
 export { validateConversationOutputSchema } from "./structuredOutput.js";
+export { conversationAttachmentIds } from "./attachments.js";

package/src/server/conversation/localExecution.js

@@ -2,7 +2,8 @@ import { execFile, spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { closeSync, openSync } from "node:fs";
 import { mkdtemp, open, readFile, readdir, rm } from "node:fs/promises";
-import { isPlainObject, normalizeText } from "./normalize.js";
+import { isRecord, normalizePositiveInteger } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeNullableText } from "./normalize.js";
 import { isAbsolute, join } from "node:path";
 import { tmpdir } from "node:os";
 import { setTimeout as delay } from "node:timers/promises";
@@ -197,11 +198,6 @@ export function createConversationProcessIdentity({
     ABSENT: "absent", AMBIGUOUS: "ambiguous", EXACT: "exact", INVALID: "invalid", MISMATCH: "mismatch"
   });
 
-  function normalizePositiveInteger(value, fallback) {
-    const number = Number(value);
-    return Number.isSafeInteger(number) && number > 0 ? number : fallback;
-  }
-
   function processMetadataIsIdentifiable(metadata = {}) {
     return Boolean(
       Number.isSafeInteger(Number(metadata.pid)) && Number(metadata.pid) > 0 &&
@@ -283,12 +279,12 @@ export function createConversationProcessIdentity({
   }
 
   function normalizeProcessIdentity(value = {}) {
-    const normalized = isPlainObject(value) ? value : {};
+    const normalized = isRecord(value) ? value : {};
     return {
-      commandHash: normalizeText(normalized.commandHash),
-      platform: normalizeText(normalized.platform),
-      runtimeToken: normalizeText(normalized.runtimeToken),
-      startTimeTicks: normalizeText(normalized.startTimeTicks),
+      commandHash: normalizeNullableText(normalized.commandHash),
+      platform: normalizeNullableText(normalized.platform),
+      runtimeToken: normalizeNullableText(normalized.runtimeToken),
+      startTimeTicks: normalizeNullableText(normalized.startTimeTicks),
       version: Number(normalized.version || 0)
     };
   }
@@ -535,11 +531,11 @@ export function createConversationProcessIdentity({
   async function waitForProcessIdentityToSettle(metadata = {}, options = {}) {
     const timeoutMs = normalizePositiveInteger(
       options.processIdentitySettleTimeoutMs,
-      PROCESS_IDENTITY_SETTLE_TIMEOUT_MS
+      { fallback: PROCESS_IDENTITY_SETTLE_TIMEOUT_MS }
     );
     const pollMs = normalizePositiveInteger(
       options.processIdentitySettlePollMs,
-      PROCESS_IDENTITY_SETTLE_POLL_MS
+      { fallback: PROCESS_IDENTITY_SETTLE_POLL_MS }
     );
     const deadline = Date.now() + timeoutMs;
     let inspection = await inspectProcessIdentity(metadata, options);
@@ -648,7 +644,7 @@ export function createConversationProcessIdentity({
     let after = await waitForProcessIdentityExit(
       metadata,
       options,
-      normalizePositiveInteger(options.termTimeoutMs, 3000)
+      normalizePositiveInteger(options.termTimeoutMs, { fallback: 3000 })
     );
     let signaledProcessGroups = [...term.signaledProcessGroups];
     if (after.status === PROCESS_IDENTITY_STATUS.EXACT) {
@@ -668,7 +664,7 @@ export function createConversationProcessIdentity({
       after = await waitForProcessIdentityExit(
         metadata,
         options,
-        normalizePositiveInteger(options.killTimeoutMs, 1000)
+        normalizePositiveInteger(options.killTimeoutMs, { fallback: 1000 })
       );
     }
     const processExitVerified = [
@@ -702,8 +698,8 @@ export function createConversationProcessIdentity({
     reportedIdentity = null,
     runtimeToken = ""
   } = {}) {
-    const expectedCommandHash = normalizeText(commandHash);
-    const expectedRuntimeToken = normalizeText(runtimeToken);
+    const expectedCommandHash = normalizeNullableText(commandHash);
+    const expectedRuntimeToken = normalizeNullableText(runtimeToken);
     const reported = normalizeProcessIdentity(reportedIdentity);
     if (
       processIdentityIsWellFormed(reported) &&

package/src/server/conversation/normalize.js

@@ -1,7 +1,12 @@
-export function normalizeText(value) {
+import { createHash } from "node:crypto";
+
+// Unlike the kernel's normalizeText, only null and undefined become blank:
+// 0 and false keep their text, as native protocol fields require.
+export function normalizeNullableText(value) {
   return String(value ?? "").trim();
 }
 
-export function isPlainObject(value) {
-  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+/** SHA-256 of the value's JSON text, used for stable configuration identities. */
+export function jsonHash(value) {
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex");
 }

package/src/server/conversation/openCodeClient.js

@@ -1,19 +1,16 @@
 import { pathToFileURL } from "node:url";
 import { Buffer } from "node:buffer";
 import path from "node:path";
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeNullableText } from "./normalize.js";
 import { createNativeHistoryExport, readStoppedNativeDatabase, retireNativeConversation } from "./nativeHistoryExport.js";
 
 const OPENCODE_RESPONSE_LIMIT_BYTES = 2 * 1024 * 1024;
 const OPENCODE_CATALOG_LIMIT_BYTES = 32 * 1024 * 1024;
 const OPENCODE_EVENT_LIMIT_BYTES = 2 * 1024 * 1024;
 
-function text(value = "") {
-  return String(value ?? "").trim();
-}
-
-function record(value = null) {
-  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
-}
+const text = normalizeNullableText;
+const record = value => isRecord(value) ? value : {};
 
 function openCodeServerError(message, {
   body = null,
@@ -594,12 +591,14 @@ function createOpenCodeServerClient({
       return statuses?.[text(sessionId)] || { type: "idle" };
     },
     async messages(sessionId = "", input = {}, { signal } = {}) {
-      const result = await request(
+      // A limited read is the newest page; `before` continues with older rows.
+      const { source, headers } = await requestResponse(
         "GET",
-        `${stableSessionPath(sessionId, "/message")}${queryString({ limit: input.limit })}`,
+        `${stableSessionPath(sessionId, "/message")}${queryString({ limit: input.limit, before: input.before })}`,
         { signal }
       );
-      return { data: normalizedMessageRows(result) };
+      const nextCursor = headers.get("x-next-cursor");
+      return { data: normalizedMessageRows(parsedJson(source)), ...(nextCursor ? { nextCursor } : {}) };
     },
     async prompt(sessionId = "", input = {}, { signal } = {}) {
       const body = stablePromptBody(input);

package/src/server/conversation/openCodeProcess.js

@@ -5,6 +5,7 @@ import path from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { createOpenCodeServerClient, readBoundedResponse } from "./openCodeClient.js";
 import { createLocalConversationExecution } from "./localExecution.js";
+import { normalizeNullableText } from "./normalize.js";
 import { DISCOVERY_TOOL_DESCRIPTORS } from "../lib/serviceToolCatalog.js";
 export { createOpenCodeSharedRuntime, openCodeServerForDirectory, readOpenCodeEnvironments, openCodeEnvironmentForDirectory,
   openCodeEnvironmentForSession, assertOpenCodeModelProvider, limitOpenCodeModelOutput,
@@ -25,9 +26,7 @@ const OPENCODE_ZEN_MODELS_URL = "https://opencode.ai/zen/v1/models";
 const OPENCODE_ZEN_PROVIDER_ID = "opencode";
 const OPENCODE_ZEN_PUBLIC_API_KEY = "public";
 
-function text(value = "") {
-  return String(value ?? "").trim();
-}
+const text = normalizeNullableText;
 
 export function openCodeProcessEnvironment(baseEnv = {}, {
   cacheRoot = "", dbPath = "", inlineConfig = "", outputTokenMax = 0, password = ""
@@ -348,6 +347,11 @@ export async function readOpenCodeZenModelIds({
   }
 }
 
+/**
+ * Read OpenCode's provider and agent catalogue through a temporary server.
+ * `createServerProcess({ dbPath, privateRoot, providerConnections, workdir })`
+ * starts the host's server; it must resolve to `{ client, stop }`.
+ */
 export async function readOpenCodeCatalog({
   createServerProcess,
   privateRoot = "",
@@ -380,8 +384,8 @@ export async function readOpenCodeCatalog({
   let readError;
   try {
     const [providers, agents] = await Promise.all([
-      server.client.providers({ directory: server.workdir }),
-      server.client.agents({ directory: server.workdir })
+      server.client.providers({ directory: normalizedWorkdir }),
+      server.client.agents({ directory: normalizedWorkdir })
     ]);
     catalog = { agents, providers };
   } catch (error) {

package/src/server/conversation/openCodeRuntime.js

@@ -1,17 +1,19 @@
 import {
   OPENCODE_INTERRUPT_TIMEOUT_MS, waitForOpenCodeFinalResponse, openCodeLastAssistantResult, inspectOpenCodeMessageAdmission, observeOpenCodeEvents,
-  openCodeMessageRows, openCodeRowsForInput, openCodePersistentConversationMessages, openCodeStructuredOutput, projectOpenCodeConversationMessages, waitForOpenCodeMessages, steerOpenCodeTurn, dispatchOpenCodeTurn, observeOpenCodeTurnCompletion, runOpenCodeConversationTurn
+  openCodeMessageRows, openCodeRowsForInput, readOpenCodeMessagesUntil, openCodePersistentConversationMessages, openCodeStructuredOutput, projectOpenCodeConversationMessages, waitForOpenCodeMessages, steerOpenCodeTurn, dispatchOpenCodeTurn, observeOpenCodeTurnCompletion, runOpenCodeConversationTurn
 } from "./openCodeTurn.js";
 import { openCodeAssistantMessageText as assistantMessageText } from "./openCodeClient.js";
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeNullableText } from "./normalize.js";
 import { randomUUID } from "node:crypto";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import path from "node:path";
 
-const text = value => String(value ?? "").trim();
+const text = normalizeNullableText;
 const sharedRuntimes = new Map();
 
 function openCodeTurnSnapshot(turn = null, threadId = "") {
-  const source = turn && typeof turn === "object" && !Array.isArray(turn) ? turn : {};
+  const source = isRecord(turn) ? turn : {};
   const active = source.active === true;
   return active || text(source.id)
     ? {
@@ -466,7 +468,7 @@ export function createOpenCodeSharedRuntime({ onStop = () => {}, scope } = {}) {
         const targets = [...processes.values()];
         const providerId = text(input.modelProviderId);
         if (!providerId || targets.some(target => text(target.modelProviderId) !== providerId || !application.ownsTarget(target))) {
-          throw Object.assign(new Error("Close other OpenCode chats and Colleague conversations, then retry this connection change. The saved connection has not changed."), {
+          throw Object.assign(new Error("Close the other OpenCode conversations that use this connection, then retry this connection change. The saved connection has not changed."), {
             code: "assistant_opencode_connection_in_use", statusCode: 409
           });
         }
@@ -734,11 +736,8 @@ export function createOpenCodeSharedRuntime({ onStop = () => {}, scope } = {}) {
   }
 
   async function readConversation(target = {}, conversationId = "", tracked = null, options = {}, readError) {
-    const messages = await target.server.client.messages(conversationId, {
-      limit: 100,
-      order: "desc"
-    }, options);
-    options.signal?.throwIfAborted();
+    const messages = await readOpenCodeMessagesUntil(target.server.client, conversationId,
+      rows => rows.some(row => row?.type === "assistant"), options);
     const result = openCodeLastAssistantResult(messages, { readError });
     return {
       conversationId,
@@ -829,7 +828,7 @@ export function createOpenCodeSharedRuntime({ onStop = () => {}, scope } = {}) {
       : options.observe(observedTarget, turnAbort, signal);
     let admitted;
     try {
-      admitted = await dispatchOpenCodeTurn(null, null, tracked, {
+      admitted = await dispatchOpenCodeTurn(tracked, {
         get agent() { return input.agent; },
         id: inputMessageId,
         get model() { return input.model; },
@@ -1160,7 +1159,7 @@ export function createOpenCodeSharedRuntime({ onStop = () => {}, scope } = {}) {
         }, application.monitor);
         dispatchTurn = turns.get(key);
       }
-      admitted = await dispatchOpenCodeTurn(null, null, dispatchTurn, {
+      admitted = await dispatchOpenCodeTurn(dispatchTurn, {
         get agent() { return prompt.agent; },
         delivery: currentMonitor ? "steer" : "queue",
         id: providerMessageId,