@jskit-ai/assistant-core 0.1.232 → 0.1.234

package/examples/conversation/package.json

@@ -8,7 +8,7 @@
     "build": "vite build"
   },
   "dependencies": {
-    "@jskit-ai/assistant-core": "0.1.232",
+    "@jskit-ai/assistant-core": "0.1.234",
     "@jskit-ai/http-runtime": "0.1.242",
     "@jskit-ai/kernel": "0.1.244",
     "@mdi/js": "^7.4.47",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/assistant-core",
-  "version": "0.1.232",
+  "version": "0.1.234",
   "type": "module",
   "scripts": {
     "test": "node --test --test-concurrency=1"

package/src/server/conversation/claudeHistory.js

@@ -1,5 +1,5 @@
 import { createReadStream } from "node:fs";
-import { lstat, readdir, realpath, rm, stat } from "node:fs/promises";
+import { lstat, open, readdir, realpath, rm, stat } from "node:fs/promises";
 import path from "node:path";
 import { readClaudeJsonFrames } from "./claudeClient.js";
 import { createNativeHistoryExport, retireNativeConversation } from "./nativeHistoryExport.js";
@@ -63,7 +63,7 @@ async function claudeHistoryPath({ configRoot, workdir, conversationId }) {
       if (error.code === "ENOENT") return null;
       throw error;
     });
-    if (info?.isFile()) return { path: candidate, size: info.size };
+    if (info?.isFile()) return { path: candidate, size: info.size, dev: info.dev, ino: info.ino };
   }
   return null;
 }
@@ -95,6 +95,82 @@ function claudeMessageBlocks(frame, { includeNested = false, commentary = false
   });
 }
 
+// Claude appends to its native history. Live reads keep the parsed complete
+// frames per file and parse only bytes appended since the previous read. A
+// replaced, truncated or rewritten file is parsed again from the start.
+const HISTORY_CACHE_LIMIT = 8;
+const HISTORY_CHECK_BYTES = 256;
+const historyCache = new Map();
+
+// Retain only the fields the history projection reads. Tool results and tool
+// inputs can be large and are never part of the projection.
+function retainedClaudeFrame(frame) {
+  if (!["user", "assistant", "system", "attachment", "result", "last-prompt"].includes(frame.type)) {
+    return { type: frame.type, uuid: frame.uuid, parentUuid: frame.parentUuid };
+  }
+  const content = frame.message?.content;
+  if (!Array.isArray(content) || !["user", "assistant"].includes(frame.type)) {
+    if (frame.type !== "user" || frame.toolUseResult === undefined) return frame;
+    const { toolUseResult: _result, ...retained } = frame;
+    return retained;
+  }
+  const blocks = frame.type === "user"
+    ? content.filter(block => block?.type === "text")
+    : content.map(block => block?.type === "tool_use" && block.name !== "StructuredOutput"
+      ? { type: "tool_use", id: block.id, name: block.name } : block);
+  const { toolUseResult: _result, ...retained } = frame;
+  return { ...retained, message: { ...frame.message, content: blocks } };
+}
+
+function claudeHistoryFrames(file) {
+  // Reads of one file are serialized so each extends the same parsed prefix.
+  const previous = historyCache.get(file.path);
+  const reading = Promise.resolve(previous?.reading).catch(() => {}).then(() => readClaudeHistoryFrames(file));
+  historyCache.delete(file.path);
+  historyCache.set(file.path, { ...previous?.value && { value: previous.value }, reading });
+  while (historyCache.size > HISTORY_CACHE_LIMIT) historyCache.delete(historyCache.keys().next().value);
+  return reading;
+}
+
+async function readClaudeHistoryFrames(file) {
+  const cached = historyCache.get(file.path)?.value;
+  const handle = await open(file.path, "r");
+  try {
+    let reusable = cached && cached.dev === file.dev && cached.ino === file.ino && cached.offset <= file.size;
+    if (reusable) {
+      const check = Buffer.alloc(cached.check.length);
+      await handle.read(check, 0, check.length, cached.offset - check.length);
+      reusable = check.equals(cached.check);
+    }
+    const start = reusable ? cached.offset : 0;
+    const appended = Buffer.alloc(file.size - start);
+    if (appended.length) await handle.read(appended, 0, appended.length, start);
+    // Only newline-terminated frames are complete; a writer may still be
+    // writing the unfinished tail, which the next read parses.
+    const complete = appended.lastIndexOf(10) + 1;
+    const added = [];
+    if (complete) {
+      for await (const frame of readClaudeJsonFrames([appended.subarray(0, complete)])) {
+        if (!frame.isSidechain) added.push(retainedClaudeFrame(frame));
+      }
+    }
+    const offset = start + complete;
+    const check = Buffer.alloc(Math.min(HISTORY_CHECK_BYTES, offset));
+    await handle.read(check, 0, check.length, offset - check.length);
+    const value = { dev: file.dev, ino: file.ino, offset, check,
+      frames: reusable ? cached.frames.concat(added) : added };
+    const current = historyCache.get(file.path);
+    if (current) current.value = value;
+    return value.frames;
+  } catch (error) {
+    const current = historyCache.get(file.path);
+    if (current) delete current.value;
+    throw error;
+  } finally {
+    await handle.close();
+  }
+}
+
 async function readClaudeHistory(options) {
   const file = await claudeHistoryPath(options);
   const inspected = {
@@ -110,18 +186,20 @@ async function readClaudeHistory(options) {
   let goal = null;
   let goalStartId = "";
   let goalCommandId = "";
-  const frames = [];
+  let frames = [];
   const byId = new Map();
   let leafUuid = "";
   let rewound = false;
   // Snapshot the file length. A writer can be in the middle of its last frame;
   // Live history reads allow that unfinished tail. Stopped maintenance can
   // require the existing strict parser without changing live observation.
-  for await (const frame of readClaudeJsonFrames(createReadStream(file.path, { end: file.size - 1 }), {
-    allowIncompleteTail: options.allowIncompleteTail ?? true
-  })) {
-    if (frame.isSidechain) continue;
-    frames.push(frame);
+  if (options.allowIncompleteTail ?? true) frames = await claudeHistoryFrames(file);
+  else {
+    for await (const frame of readClaudeJsonFrames(createReadStream(file.path, { end: file.size - 1 }))) {
+      if (!frame.isSidechain) frames.push(frame);
+    }
+  }
+  for (const frame of frames) {
     if (frame.uuid) byId.set(frame.uuid, frame);
     if (["user", "assistant"].includes(frame.type) && frame.uuid) leafUuid = frame.uuid;
     if (frame.type === "last-prompt" && frame.leafUuid) {

package/src/server/conversation/claudeTurn.js

@@ -561,12 +561,15 @@ export function createClaudeConversationOwner({
     const context = entry.context;
     const messageId = command ? input.messageId : text(input.messageId) || randomUUID();
     const uuid = claudeNativeMessageId(messageId);
+    const deliveryTiming = (command || input).deliveryTiming;
     if (!command) {
       if (entry.main && await store.hasMessage(context, messageId)) {
         return { ok: true, delivered: true, duplicate: true, thread: { id: entry.id }, turn: snapshot(entry) };
       }
+      deliveryTiming?.("duplicate-checked");
       preparation.check(entry, context);
       const history = await readHistory(entry);
+      deliveryTiming?.("native-history-read");
       if (history.userIds.includes(uuid)) {
         return { ok: true, delivered: true, duplicate: true, thread: { id: entry.id }, turn: snapshot(entry) };
       }
@@ -587,6 +590,7 @@ export function createClaudeConversationOwner({
       // authored input. Keep its failure distinct from a lost native receipt.
       throw Object.assign(error, { delivery: "not-sent" });
     }
+    deliveryTiming?.("process-ready");
     if (command && !command.steering) command.signal.throwIfAborted();
     const steering = command ? command.steering === true : Boolean(entry.turn?.active);
     const sendNow = steering && native.client.supportsSendNow?.() === true;
@@ -607,7 +611,8 @@ export function createClaudeConversationOwner({
         throw Object.assign(error, { delivery: "not-sent" });
       }
     }
-    const prompt = command ? undefined : await preparation.message(entry, input, { context, message, steering, renewal });
+    const prompt = command ? undefined : await preparation.message(entry, input, { context, message, steering, renewal, deliveryTiming });
+    if (!command) deliveryTiming?.("prompt-rendered");
     if (command) {
       await command.beforeDispatch({ threadId: entry.id });
       command.signal.throwIfAborted();
@@ -623,6 +628,7 @@ export function createClaudeConversationOwner({
     entry.onEvent = context.onEvent;
     entry.lastMessageId = uuid;
     const actorMetadata = command ? undefined : await onEvent(entry, { type: "message-metadata", input, context });
+    if (!command) deliveryTiming?.("metadata-ready");
     const nativeOwner = applicationCommand ? { process: native, executionId: entry.executionId,
       accountIdentity: entry.accountIdentity, threadId: entry.id, turnId: entry.turn.id } : null;
     let conversationTurn;
@@ -646,8 +652,12 @@ export function createClaudeConversationOwner({
       } else {
         const admission = onEvent(entry, { type: "admit-message", input, context, renewal, message, messageId, uuid, actorMetadata });
         if (admission) conversationTurn = await admission;
+        deliveryTiming?.("receipt-written");
+      }
+      if (!command) {
+        await entry.nativeTurn.updateState("active");
+        deliveryTiming?.("state-active");
       }
-      if (!command) await entry.nativeTurn.updateState("active");
       (command || input).onReceiptPersisted?.();
       if (applicationCommand && conversationTurn) {
         const value = deliveryResult();
@@ -982,7 +992,8 @@ export function createClaudeConversationOwner({
       entry.toolSchemas = active.tools?.schemas || [];
     }
     const value = await send(entry, { ...command.input.nativeMessage, signal: command.input.signal, onPromptSending: command.beforeDispatch,
-      onNativeReceipt: command.onNativeReceipt, onReceiptPersisted: command.onReceiptPersisted }, { applicationCommand });
+      onNativeReceipt: command.onNativeReceipt, onReceiptPersisted: command.onReceiptPersisted, deliveryTiming: command.deliveryTiming },
+    { applicationCommand });
     const completion = value.conversationTurn ? entry.completion?.promise : null;
     const delivered = { value, completion };
     if (!applicationCommand && value.delivered === true && value.conversationTurn) {
@@ -1012,9 +1023,9 @@ export function createClaudeConversationOwner({
     control.current = active;
     const ready = Promise.withResolvers();
     ready.promise.catch(() => {});
-    active.steer = async ({ input, beforeDispatch, accept, onNativeReceipt, onReceiptPersisted }) => {
+    active.steer = async ({ input, beforeDispatch, accept, onNativeReceipt, onReceiptPersisted, deliveryTiming }) => {
       await ready.promise;
-      const nativeDispatch = { active, signal, beforeDispatch, accept, onNativeReceipt, onReceiptPersisted,
+      const nativeDispatch = { active, signal, beforeDispatch, accept, onNativeReceipt, onReceiptPersisted, deliveryTiming,
         timeoutMs, steering: true, interrupted: false, attempted: false, admitted: false };
       try { await dispatch(control, { input, context, signal }, { acquire, entry, dispatch: nativeDispatch }); }
       catch (error) {
@@ -1024,7 +1035,7 @@ export function createClaudeConversationOwner({
       }
     };
     const nativeDispatch = { active, signal, beforeDispatch, accept, onNativeReceipt: command.onNativeReceipt,
-      onReceiptPersisted: command.onReceiptPersisted, timeoutMs, maximumOutput, attempted: false, admitted: false };
+      onReceiptPersisted: command.onReceiptPersisted, deliveryTiming: command.deliveryTiming, timeoutMs, maximumOutput, attempted: false, admitted: false };
     let entry;
     let cancellation;
     let problem;

package/src/server/conversation/deliveryTiming.js

@@ -1,6 +1,11 @@
+// Finer marks within each phase locate slow work. Hosts may mark git-actor
+// and genesis-rendered while preparing a native prompt.
 const stages = new Set([
-  "received", "preparation-started", "provider-started", "runtime-ready", "dispatch-started",
-  "native-acknowledged", "receipt-persisted", "accepted", "first-response", "failed"
+  "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",
+  "native-acknowledged", "receipt-written", "state-active", "receipt-persisted", "admission-authorized",
+  "turn-located", "accepted", "first-response", "failed"
 ]);
 
 // Observer results are never awaited and failures cannot change delivery.

package/src/server/conversation/fileStorage.js

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { createConversationStorage } from "./storage.js";
 
@@ -34,6 +34,17 @@ export function createFileConversationStorage({ directory } = {}) {
 
   return createConversationStorage({
     readRecord,
+    // Atomic replacement gives every save a new inode; size and modification
+    // time also change for an in-place external edit.
+    async recordVersion(id) {
+      try {
+        const info = await stat(filename(id), { bigint: true });
+        return `${info.dev}:${info.ino}:${info.size}:${info.mtimeNs}`;
+      } catch (error) {
+        if (error.code === "ENOENT") return "absent";
+        throw error;
+      }
+    },
     async writeRecord(id, { turns, metadata }) {
       // Serialize before touching the filesystem: failed transactions cannot
       // replace the last saved conversation or leave a partial document.

package/src/server/conversation/runtime.js

@@ -83,10 +83,15 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
     throw new TypeError("Invalid conversation request time limit.");
   }
 
-  async function access(context, id, operation, entry) {
+  // Send and its immediate admission share one authorization. Dispatch,
+  // receipt admission and every other operation authorize again.
+  async function access(context, id, operation, entry, grant) {
     if (closed || entry?.disposed) throw failure("This conversation handle is closed.", "conversation_closed");
-    if (!await authorize({ context, conversationId: id, operation })) {
-      throw failure("This conversation is not available to this identity.", "conversation_forbidden", 403);
+    if (!grant?.has(operation)) {
+      if (!await authorize({ context, conversationId: id, operation })) {
+        throw failure("This conversation is not available to this identity.", "conversation_forbidden", 403);
+      }
+      grant?.add(operation);
     }
     if (closed || entry?.disposed) throw failure("This conversation handle is closed.", "conversation_closed");
   }
@@ -146,6 +151,27 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
   const readTranscript = entry => entry.conversation
     ? entry.conversation.transcript.readConversationLog() : transcript.readConversationLog(entry.id);
 
+  // Identity lookups avoid reading the whole log when the transcript supports
+  // them. A bound host may supply findSubmittedTurn(messageId) and readTurn(turnId).
+  async function findSubmittedTurn(entry, messageId) {
+    const find = entry.conversation ? entry.conversation.transcript.findSubmittedTurn : transcript.findSubmittedTurn &&
+      (id => transcript.findSubmittedTurn(entry.id, id));
+    if (typeof find === "function") return (await find(messageId)) || null;
+    return (await readTranscript(entry)).find(turn => submittedMessage(turn)?.messageId === messageId) || null;
+  }
+
+  async function readBoundTurn(entry, turnId) {
+    if (typeof entry.conversation.transcript.readTurn === "function") return (await entry.conversation.transcript.readTurn(turnId)) || null;
+    return (await readTranscript(entry)).find(turn => turn.turnId === turnId) || null;
+  }
+
+  async function lastTranscriptTurn(entry) {
+    const page = entry.conversation && typeof entry.conversation.transcript.readConversationLogPage !== "function" ? null
+      : entry.conversation ? await entry.conversation.transcript.readConversationLogPage({ limit: 1 })
+        : await transcript.readConversationLogPage(entry.id, { limit: 1 });
+    return page?.conversationLog.at(-1) || (await readTranscript(entry)).at(-1);
+  }
+
   function readTranscriptPage(entry, query) {
     if (!entry.conversation) return transcript.readConversationLogPage(entry.id, { ...query, presentation: completedEnvelope });
     if (typeof entry.conversation.transcript.readConversationLogPage !== "function") {
@@ -827,13 +853,15 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
 
     async function admit(request, seen, { nativeDelivery = false, conversationTurn } = {}) {
       await access(request.context, entry.id, request.operation, entry);
+      request.deliveryTiming?.("admission-authorized");
       if (!conversationTurn) active.controller.signal.throwIfAborted();
       if (request.input.goal) request.goalMessageId = request.input.messageId;
       else if (goalOwner) request.goalMessageId = goalOwner.input.messageId;
       const nativeTurnId = active.nativeTurnId;
       const previous = current;
       if (entry.conversation) {
-        const saved = (await readTranscript(entry)).find(turn => turn.turnId === conversationTurn?.turnId);
+        const saved = conversationTurn?.turnId ? await readBoundTurn(entry, conversationTurn.turnId) : null;
+        request.deliveryTiming?.("turn-located");
         if (submittedMessage(saved || {})?.messageId !== request.input.messageId) {
           throw new Error("The native receipt does not belong to this authored request.");
         }
@@ -1011,7 +1039,8 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
     }
 
     async function deliverNative(request, dispatch) {
-      const history = (await readTranscript(entry)).filter(turn => !turn.metadata?.runtime?.supersededBy);
+      // A bound conversation supplies its own native history below.
+      const history = entry.conversation ? [] : (await readTranscript(entry)).filter(turn => !turn.metadata?.runtime?.supersededBy);
       let completion;
       let committed;
       let rendered;
@@ -1029,10 +1058,12 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
         const readAttachments = attachmentReader(request);
         // The bound host has already resolved its original attachment records;
         // the production preparation owner keeps their manifest/native mapping.
-        const boundInput = entry.conversation ? await entry.conversation.prepareInput(input, request.context) : null;
+        const boundInput = entry.conversation
+          ? await entry.conversation.prepareInput(input, request.context, { deliveryTiming: request.deliveryTiming }) : null;
         const files = boundInput ? { attachments: boundInput.displayAttachments || [], localFiles: [], content: [] }
           : await readAttachments((input.attachmentIds || []).map(attachmentId => ({ attachmentId })));
         const contextFiles = boundInput ? { localFiles: [], content: [] } : await readAttachments(input.contextAttachments || []);
+        request.deliveryTiming?.("input-prepared");
         const localFiles = [...contextFiles.localFiles, ...files.localFiles];
         if (request.input.goal && localFiles.length) {
           throw failure("Native goals require extracted text or supported image bytes for attachments.", "conversation_unsupported", 400);
@@ -1066,6 +1097,7 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
             text: input.message, contextText: input.contextText || "",
             content: [...contextFiles.content, ...files.content], localFiles, attachmentManifest },
           signal: active.controller.signal,
+          deliveryTiming: request.deliveryTiming,
           onNativeReceipt: () => request.deliveryTiming?.("native-acknowledged"),
           onReceiptPersisted: () => request.deliveryTiming?.("receipt-persisted"),
           ...(engine === "opencode" ? { deliveryCommitted: committed.promise } : {}),
@@ -1170,7 +1202,7 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
         }
         if (request.accepted) await publishAdmission(request, nativeResult);
         else {
-          const saved = (await readTranscript(entry)).find(turn => submittedMessage(turn)?.messageId === request.input.messageId);
+          const saved = await findSubmittedTurn(entry, request.input.messageId);
           if (!saved && entry.conversation) {
             // An original native-history duplicate need not have an authored
             // application row. Preserve its exact result without inventing a
@@ -1226,7 +1258,8 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
 
     try {
       await setPhase(entry, "preparing");
-      const recordedHistory = await readTranscript(entry);
+      // Only the API engine sends the application transcript as history.
+      const recordedHistory = engine === "api" ? await readTranscript(entry) : [];
       const activeHistory = recordedHistory.filter(turn => !turn.metadata?.runtime?.supersededBy);
       const metadata = { runtime: await readState(entry) };
       const continuity = metadata.runtime.continuity;
@@ -1438,8 +1471,9 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
     const deliveryTiming = createConversationDeliveryTiming({ engine: entry.engine,
       conversationId: entry.id, messageId: input?.messageId, report: onDeliveryTiming });
     deliveryTiming("received");
+    const grant = new Set();
     try {
-      await access(context, entry.id, goal ? "goal" : input?.steer === true ? "steer" : origin === "application" ? "wake" : "send", entry);
+      await access(context, entry.id, goal ? "goal" : input?.steer === true ? "steer" : origin === "application" ? "wake" : "send", entry, grant);
       if (entry.conversation?.commands) {
         if (origin !== "user" || goal) throw failure("This conversation supports its original application Send operation.", "conversation_unsupported", 400);
         return entry.conversation.commands.send(input, context);
@@ -1447,7 +1481,7 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
       if (entry.conversation?.native?.scoped) return entry.provider.sendNative({ input, context });
       const originalInput = representation === "native" ? input : undefined;
       const message = originalInput ? { ...input, text: input.displayMessage ?? input.message ?? input.text ?? "" } : input;
-      const admission = await serial(entry, () => admitSend(entry, context, message, origin, goal, originalInput, wakeOptions, deliveryTiming));
+      const admission = await serial(entry, () => admitSend(entry, context, message, origin, goal, originalInput, wakeOptions, deliveryTiming, grant));
       const result = await (admission.receipt || admission.promise);
       if (!entry.conversation) return result;
       if (representation === "native") return result.nativeResult;
@@ -1461,11 +1495,12 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
 
   // Called while holding the conversation queue, including Claude's existing
   // stop-then-Send goal commands. All commands retain the ordinary receipt path.
-  async function admitSend(entry, context, input, origin = "user", goal, originalInput, wakeOptions, deliveryTiming) {
+  async function admitSend(entry, context, input, origin = "user", goal, originalInput, wakeOptions, deliveryTiming, grant) {
     deliveryTiming?.("preparation-started");
     const operation = goal ? "goal" : input?.steer === true ? "steer" : origin === "application" ? "wake" : "send";
-    await access(context, entry.id, operation, entry);
+    await access(context, entry.id, operation, entry, grant);
     await entry.conversation?.admission(context, operation);
+    deliveryTiming?.("authorized");
     if (goal) context?.signal?.throwIfAborted();
     let suppliedExclusions;
     if (wakeOptions !== undefined) {
@@ -1512,9 +1547,10 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
       if (!entry.conversation && !sameRequest(pending.input, message)) throw failure("This messageId already belongs to different content.", "conversation_message_conflict");
       return { promise: pending.admission.promise };
     }
-    const history = await readTranscript(entry);
-    const existing = history.find(turn => submittedMessage(turn)?.messageId === message.messageId);
+    const existing = await findSubmittedTurn(entry, message.messageId);
+    deliveryTiming?.("history-read");
     const nativeState = entry.engine !== "api" && (await readState(entry));
+    deliveryTiming?.("state-read");
     const nativePending = nativeState?.request;
     if (existing) {
       const previous = submittedMessage(existing);
@@ -1533,7 +1569,7 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
       // No native dispatch has occurred for this request. Finish the previous
       // waiter before reserving the same authored message or goal request.
       await working.done;
-      return admitSend(entry, context, input, origin, goal, originalInput, wakeOptions, deliveryTiming);
+      return admitSend(entry, context, input, origin, goal, originalInput, wakeOptions, deliveryTiming, grant);
     }
     const nativeSteering = !working && (nativeState.nativeTurn?.active || entry.driver.canonicalTranscript && nativeState.binding?.codexAppServerRun &&
       codexAppServerTurnStateFromAgentRun(nativeState.binding.codexAppServerRun).active);
@@ -1544,7 +1580,8 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
     }
     if (working && !input.steer && !goal && !entry.conversation) throw failure("Wait for this answer or use steer to send another instruction.", "conversation_busy");
     if (input.steer && (!working && !nativeSteering || working?.finishing) && !(nativePending?.attempted || nativePending?.inspectionOnly)) {
-      const previousState = nativeState?.nativeTurn?.runState || nativeState?.nativeTurn?.state || history.at(-1)?.metadata?.runtime?.status;
+      const previousState = nativeState?.nativeTurn?.runState || nativeState?.nativeTurn?.state ||
+        (await lastTranscriptTurn(entry))?.metadata?.runtime?.status;
       const completed = working ? !working.controller.signal.aborted && !working.timedOut : ["complete", "completed"].includes(previousState);
       throw Object.assign(failure("There is no active native turn to steer. Send a new message.",
         completed ? "conversation_steer_turn_finished" : "conversation_not_steerable"), { delivery: "not-sent" });
@@ -1562,7 +1599,8 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
     let nativeToolAttempt;
     let excludedMessageIds;
     let requestAt = new Date().toISOString();
-    try { configuration = entry.conversation ? (await readState(entry)).configuration : await storage.write(entry.id, async transaction => {
+    // The bound state was read above unless this is an API conversation.
+    try { configuration = entry.conversation ? (nativeState || await readState(entry)).configuration : await storage.write(entry.id, async transaction => {
       const metadata = await transaction.readMetadata();
       if (metadata.runtime.replacement) throw failure("Finish the pending native replacement before sending another message.", "conversation_replacement_pending");
       if (retainedSegments(metadata.runtime).some(segment => segment.segmentId !== entry.segmentId && segment.request?.messageId === message.messageId)) {
@@ -1591,6 +1629,7 @@ export function createConversationRuntime({ engine: defaultEngine = "api", defau
       await transaction.writeMetadata(metadata);
       return metadata.runtime.configuration;
     }); } catch (error) { release(); throw error; }
+    deliveryTiming?.("request-saved");
     const request = { input: message, originalInput, operation, context, at: requestAt, deliveryTiming,
       ...(markedResponse ? { completedEnvelope: true, excludedMessageIds } : {}),
       ...(typeof nativeToolAttempt === "boolean" ? { nativeToolAttempt } : {}), steering: Boolean(working || input.steer && nativeSteering),

package/src/server/conversation/storage.js

@@ -90,64 +90,129 @@ function conversationMessageStorageKey({ role, at, messageId } = {}) {
   return `${normalizedRole}.${timestamp}${idSuffix}.md`;
 }
 
+function conversationMessageIndex(record) {
+  if (!record.index) {
+    record.index = new Map();
+    for (const [turnId, turn] of record.turns) {
+      for (const message of turn.messages) {
+        if (message.messageId && !record.index.has(message.messageId)) record.index.set(message.messageId, turnId);
+      }
+    }
+  }
+  return record.index;
+}
+
 /** Transaction implementation for single-writer record adapters. This serializes
  * one instance's writes; a database with multiple writers must also hold its own
  * transaction/lock across readRecord and writeRecord, or implement read/write directly.
+ * An adapter may supply recordVersion(id), a cheap token that changes whenever
+ * the saved record changes; the parsed record is then reused until it changes.
  */
-export function createConversationStorage({ readRecord, writeRecord, deleteRecord }) {
+export function createConversationStorage({ readRecord, writeRecord, deleteRecord, recordVersion }) {
   const pending = new Map();
+  const cache = new Map();
 
   function key(scope) {
     if (typeof scope !== "string" || !scope.trim()) throw new TypeError("Conversation scope must be a nonempty string.");
     return scope;
   }
 
-  function transaction(record) {
-    const turns = record.turns;
+  async function readSaved(id) {
+    if (typeof recordVersion !== "function") return readRecord(id);
+    const version = await recordVersion(id);
+    const cached = cache.get(id);
+    if (version != null && cached?.version === version) return cached.record;
+    const record = await readRecord(id);
+    if (version == null) cache.delete(id);
+    else cache.set(id, { version, record });
+    return record;
+  }
+
+  // Saved records are shared and never changed in place. A transaction copies
+  // the turn map and each turn it changes, then commits that new record.
+  // Adapter fields the transaction does not manage are carried unchanged.
+  function transaction(saved) {
+    const { index: _index, ...draft } = saved;
+    const added = new Map();
+    let ownTurns = false;
+    const owned = new Set();
+    function ownTurn(id) {
+      if (!ownTurns) {
+        draft.turns = new Map(draft.turns);
+        ownTurns = true;
+      }
+      const existing = draft.turns.get(id);
+      if (existing && owned.has(id)) return existing;
+      const turn = existing ? { ...existing, messages: [...existing.messages] } : { messages: [] };
+      draft.turns.set(id, turn);
+      owned.add(id);
+      return turn;
+    }
+    function record() {
+      // Index entries are verified against the turn on lookup, so removed
+      // messages can remain listed; only additions need new entries.
+      if (!added.size) return saved.index ? { ...draft, index: saved.index } : draft;
+      const index = new Map(conversationMessageIndex(saved));
+      for (const [messageId, turnId] of added) index.set(messageId, turnId);
+      return { ...draft, index };
+    }
+    const turns = () => draft.turns;
+    function messageTurnId(id) {
+      if (!id) return "";
+      const turnId = added.get(id) ?? conversationMessageIndex(saved).get(id);
+      if (turnId === undefined) return "";
+      const contains = (turn) => turn.messages.some((message) => message.messageId === id);
+      if (turns().get(turnId) && contains(turns().get(turnId))) return turnId;
+      return [...turns()].find(([, turn]) => contains(turn))?.[0] || "";
+    }
     return {
-      async readMetadata() { return structuredClone(record.metadata); },
-      async writeMetadata(value) { record.metadata = structuredClone(value); },
-      async updateTurnMetadata(id, patch) {
-        const turn = turns.get(id);
-        if (!turn) throw new Error("The conversation turn does not exist.");
-        turn.metadata = { ...turn.metadata, ...structuredClone(patch) };
-      },
-      async listTurnIds() { return [...turns.keys()]; },
-      async nextTurnId() { return String(Math.max(0, ...[...turns.keys()].map(Number).filter(Number.isSafeInteger)) + 1).padStart(6, "0"); },
-      async hasMessage(id) {
-        return Boolean(id) && [...turns.values()].some((turn) => turn.messages.some((message) => message.messageId === id));
-      },
-      async readTurn(id) {
-        const turn = turns.get(id);
-        if (!turn) return null;
-        const find = (role) => turn.messages.find((message) => message.role === role) || null;
-        const thinking = turn.messages.filter((message) => message.role === "thinking");
-        const commentary = turn.messages.filter((message) => message.role === "commentary");
-        const activity = [...thinking, ...commentary].sort((a, b) => a.at.localeCompare(b.at));
-        const system = find("system"), user = find("user"), assistant = find("assistant");
-        return structuredClone({
-          turnId: id, user, assistant, thinking, commentary,
-          ...(system ? { system } : {}), ...(turn.metadata ? { metadata: turn.metadata } : {}),
-          messages: [system, user, ...activity, assistant].filter(Boolean)
-        });
-      },
-      async appendMessage(id, { turnMetadata, ...message }) {
-        const turn = turns.get(id) || { messages: [] };
-        if (turnMetadata) turn.metadata = structuredClone(turnMetadata);
-        const identity = conversationMessageStorageKey(message);
-        const existing = identity === null ? -1 : turn.messages.findIndex((previous) =>
-          conversationMessageStorageKey(previous) === identity);
-        if (existing < 0) turn.messages.push(structuredClone(message));
-        else turn.messages[existing] = structuredClone(message);
-        turns.set(id, turn);
-      },
-      async replaceAssistant(id, message) {
-        if (!id) throw new TypeError("Assistant replacement requires a turn id.");
-        const turn = turns.get(id) || { messages: [] };
-        const previous = turn.messages.find((entry) => entry.role === "assistant");
-        turn.messages = turn.messages.filter((entry) => entry.role !== "assistant");
-        turn.messages.push({ ...previous, ...structuredClone(message), at: previous?.at || message.at });
-        turns.set(id, turn);
+      record,
+      view: {
+        async readMetadata() { return structuredClone(draft.metadata); },
+        async writeMetadata(value) { draft.metadata = structuredClone(value); },
+        async updateTurnMetadata(id, patch) {
+          if (!turns().get(id)) throw new Error("The conversation turn does not exist.");
+          const turn = ownTurn(id);
+          turn.metadata = { ...turn.metadata, ...structuredClone(patch) };
+        },
+        async listTurnIds() { return [...turns().keys()]; },
+        async nextTurnId() { return String(Math.max(0, ...[...turns().keys()].map(Number).filter(Number.isSafeInteger)) + 1).padStart(6, "0"); },
+        async hasMessage(id) { return Boolean(messageTurnId(id)); },
+        // Optional transaction extension: the turn holding this message ID.
+        async findMessageTurnId(id) { return messageTurnId(id); },
+        async readTurn(id) {
+          const turn = turns().get(id);
+          if (!turn) return null;
+          const find = (role) => turn.messages.find((message) => message.role === role) || null;
+          const thinking = turn.messages.filter((message) => message.role === "thinking");
+          const commentary = turn.messages.filter((message) => message.role === "commentary");
+          const activity = [...thinking, ...commentary].sort((a, b) => a.at.localeCompare(b.at));
+          const system = find("system"), user = find("user"), assistant = find("assistant");
+          return structuredClone({
+            turnId: id, user, assistant, thinking, commentary,
+            ...(system ? { system } : {}), ...(turn.metadata ? { metadata: turn.metadata } : {}),
+            messages: [system, user, ...activity, assistant].filter(Boolean)
+          });
+        },
+        async appendMessage(id, { turnMetadata, ...message }) {
+          const turn = ownTurn(id);
+          if (turnMetadata) turn.metadata = structuredClone(turnMetadata);
+          const identity = conversationMessageStorageKey(message);
+          const existing = identity === null ? -1 : turn.messages.findIndex((previous) =>
+            conversationMessageStorageKey(previous) === identity);
+          if (existing < 0) turn.messages.push(structuredClone(message));
+          else turn.messages[existing] = structuredClone(message);
+          if (message.messageId) added.set(message.messageId, id);
+        },
+        async replaceAssistant(id, message) {
+          if (!id) throw new TypeError("Assistant replacement requires a turn id.");
+          const turn = ownTurn(id);
+          const previous = turn.messages.find((entry) => entry.role === "assistant");
+          turn.messages = turn.messages.filter((entry) => entry.role !== "assistant");
+          const replacement = { ...previous, ...structuredClone(message), at: previous?.at || message.at };
+          turn.messages.push(replacement);
+          if (replacement.messageId) added.set(replacement.messageId, id);
+        }
       }
     };
   }
@@ -157,11 +222,17 @@ export function createConversationStorage({ readRecord, writeRecord, deleteRecor
     const id = key(scope);
     const previous = pending.get(id) || Promise.resolve();
     const operation = previous.then(async () => {
-      const draft = structuredClone(await readRecord(id));
-      const view = transaction(draft);
-      const result = await callback(view);
+      const draft = transaction(await readSaved(id));
+      const result = await callback(draft.view);
+      // A failed or partial save leaves the cached record unknown.
+      cache.delete(id);
       if (remove) await deleteRecord(id);
-      else await writeRecord(id, draft, view);
+      else {
+        const record = draft.record();
+        await writeRecord(id, record, draft.view);
+        const version = typeof recordVersion === "function" ? await recordVersion(id) : null;
+        if (version != null) cache.set(id, { version, record });
+      }
       return result;
     });
     const settled = operation.then(() => undefined, () => undefined);
@@ -175,7 +246,7 @@ export function createConversationStorage({ readRecord, writeRecord, deleteRecor
     async read(scope, callback) {
       const id = key(scope);
       await pending.get(id);
-      return callback(transaction(structuredClone(await readRecord(id))));
+      return callback(transaction(await readSaved(id)).view);
     },
     async deleteConversation(scope) {
       await write(scope, async () => {}, true);

package/src/server/conversation/transcript.js

@@ -92,8 +92,29 @@ 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);
+    if (!id) return null;
+    return storage.read(scope, async (transaction) => {
+      const submitted = turn => hasMessages(turn) && (turn.user || turn.system)?.messageId === id ? turn : null;
+      if (typeof transaction.findMessageTurnId === "function") {
+        const turnId = await transaction.findMessageTurnId(id);
+        if (!turnId) return null;
+        const turn = submitted(await transaction.readTurn(turnId));
+        if (turn) return turn;
+      }
+      for (const turnId of await transaction.listTurnIds()) {
+        const turn = submitted(await transaction.readTurn(turnId));
+        if (turn) return turn;
+      }
+      return null;
+    });
+  }
+
   return Object.freeze({
     readConversationLog,
+    findSubmittedTurn,
     readConversationLogPage,
     conversationMessageIdExists: (scope, messageId) => storage.read(scope, (transaction) => transaction.hasMessage(normalizeText(messageId))),
     writeConversationUserMessage: (scope, input) => append(scope, "user", input),

package/test/claudeConversationSession.test.js

@@ -41,6 +41,29 @@ test("Claude account checks use the supplied finite capture policy without start
   assert.ok(checks.length > 0);
 });
 
+test("a warm Claude send neither rescans the whole transcript nor authorizes its admission twice", async t => {
+  let scans = 0;
+  const authorizations = [];
+  const f = await fixture(t, {
+    authorize: ({ operation }) => { authorizations.push(operation); return true; },
+    wrapStorage: storage => ({ ...storage, read: (scope, callback) => storage.read(scope, transaction => callback(new Proxy(transaction, {
+      get(target, property) {
+        if (property === "listTurnIds") scans += 1;
+        return target[property];
+      }
+    }))) })
+  });
+  assert.equal((await f.conversation.send(input)).status, "accepted");
+  await f.conversation.wait();
+  scans = 0;
+  authorizations.length = 0;
+  assert.equal((await f.conversation.send({ messageId: "second", text: "Hello again" })).status, "accepted");
+  await f.conversation.wait();
+  assert.equal(scans, 2, "Only native catch-up history and the final snapshot read the whole log; admission uses message identity.");
+  assert.equal(authorizations.filter(operation => operation === "send").length, 3,
+    "Send shares one grant with its admission; dispatch and receipt admission authorize again.");
+});
+
 test("Claude exposes the durable native identity before dispatch and respects a rejected gate", async t => {
   const f = await fixture(t);
   await f.first.close();

package/test/claudeTurn.test.js

@@ -1449,11 +1449,14 @@ test("Claude delivery timing separates native acknowledgement from the held cano
   const sending = f.conversation.send({ messageId: "timed-request", text: "Private message" });
   await writing.promise;
   assert.deepEqual(timings.map(event => event.stage), [
-    "received", "preparation-started", "provider-started", "runtime-ready", "dispatch-started", "native-acknowledged"
+    "received", "preparation-started", "authorized", "history-read", "state-read", "request-saved", "input-prepared",
+    "provider-started", "duplicate-checked", "native-history-read", "process-ready", "prompt-rendered", "metadata-ready",
+    "runtime-ready", "dispatch-started", "native-acknowledged"
   ]);
   release.resolve();
   assert.equal((await sending).status, "accepted");
-  assert.deepEqual(timings.slice(-2).map(event => event.stage), ["receipt-persisted", "accepted"]);
+  const admitted = timings.map(event => event.stage).slice(16);
+  assert.deepEqual(admitted, ["receipt-written", "state-active", "receipt-persisted", "admission-authorized", "turn-located", "accepted"]);
   await f.frame({ type: "result", subtype: "success", result: "Public answer" });
   await f.conversation.wait();
   assert.equal(JSON.stringify(timings).includes("Private message"), false);
@@ -2593,3 +2596,45 @@ test("Claude explicitly pauses a blocked goal without resuming native work", asy
   assert.equal(f.entry.pausedGoal.status, "paused");
   assert.equal(f.processes.length, 0);
 });
+
+test("live Claude history parses only frames appended since the previous read", async t => {
+  const { appendFile, mkdir: makeDirectory, mkdtemp: makeTemporary, rename: move, rm: remove, writeFile: write } = await import("node:fs/promises");
+  const root = await makeTemporary(path.join(os.tmpdir(), "claude-incremental-"));
+  t.after(() => remove(root, { recursive: true, force: true }));
+  const directory = path.join(root, "projects", root.replace(/[^a-zA-Z0-9]/gu, "-"));
+  await makeDirectory(directory, { recursive: true });
+  const conversationId = "7b1f9a52-1c1e-4d0b-9a55-3c8e2f4d6a10";
+  const file = path.join(directory, `${conversationId}.jsonl`);
+  const options = { configRoot: root, workdir: root, conversationId };
+  const user = id => JSON.stringify({ type: "user", uuid: id, message: { content: `Request ${id}` } });
+  const answer = (id, parent) => JSON.stringify({ type: "assistant", uuid: id, parentUuid: parent,
+    message: { id: `api-${id}`, content: [{ type: "text", text: `Answer ${id}` }] } });
+  await write(file, [user("u1"), answer("a1", "u1")].join("\n") + "\n");
+  const parse = JSON.parse;
+  let parsed = 0;
+  JSON.parse = (...args) => { parsed += 1; return parse(...args); };
+  try {
+    assert.deepEqual((await readClaudeHistory(options)).userIds, ["u1"]);
+    assert.equal(parsed, 2);
+    parsed = 0;
+    // A complete appended frame is parsed once; the writer's unfinished tail is not.
+    await appendFile(file, user("u2") + "\n" + user("u3").slice(0, 10));
+    assert.deepEqual((await readClaudeHistory(options)).userIds, ["u1", "u2"]);
+    assert.equal(parsed, 1);
+    parsed = 0;
+    await appendFile(file, user("u3").slice(10) + "\n");
+    const history = await readClaudeHistory(options);
+    assert.deepEqual(history.userIds, ["u1", "u2", "u3"]);
+    assert.deepEqual(history.messages.map(message => message.text), ["Answer a1"]);
+    assert.equal(parsed, 1);
+    parsed = 0;
+    assert.deepEqual((await readClaudeHistory(options)).userIds, ["u1", "u2", "u3"]);
+    assert.equal(parsed, 0);
+    // Replacement and truncation discard the parsed prefix.
+    await write(`${file}.next`, [user("r1"), answer("ra", "r1")].join("\n") + "\n");
+    await move(`${file}.next`, file);
+    assert.deepEqual((await readClaudeHistory(options)).userIds, ["r1"]);
+    await write(file, user("t1") + "\n");
+    assert.deepEqual((await readClaudeHistory(options)).userIds, ["t1"]);
+  } finally { JSON.parse = parse; }
+});

package/test/codexConversationSession.test.js

@@ -1265,8 +1265,10 @@ test("Codex delivery timing uses the common native receipt and first-response st
   assert.equal((await f.conversation.send({ messageId: "timed-request", text: "Private message" })).status, "accepted");
   await f.conversation.wait();
   const stages = timings.map(event => event.stage);
-  assert.deepEqual(stages.slice(0, 8), ["received", "preparation-started", "provider-started", "runtime-ready",
-    "dispatch-started", "native-acknowledged", "receipt-persisted", "accepted"]);
+  const common = ["received", "preparation-started", "provider-started", "runtime-ready", "dispatch-started",
+    "native-acknowledged", "receipt-persisted", "accepted"];
+  assert.deepEqual(stages.filter(stage => common.includes(stage)).slice(0, 8), common);
+  assert.deepEqual(stages.slice(2, 7), ["authorized", "history-read", "state-read", "request-saved", "input-prepared"]);
   assert.equal(stages.filter(stage => stage === "first-response").length, 1);
   assert.equal(JSON.stringify(timings).includes("Private message"), false);
 });

package/test/conversation.test.js

@@ -81,6 +81,15 @@ test("message adaptation retains progress, attachments, system actions and SQL m
   assert.equal(turns[2].assistant.sql, "select 1");
 });
 
+test("record storage carries adapter fields it does not manage through writes", async () => {
+  let record = { turns: new Map(), metadata: {}, rewound: [{ turnId: "000001" }] };
+  const storage = createConversationStorage({ readRecord: () => record, writeRecord: (_scope, next) => { record = next; } });
+  await storage.write("conversation", transaction => transaction.appendMessage("000002",
+    { role: "user", at: "2026-10-01T01:00:00.000Z", text: "Hello", messageId: "m1" }));
+  assert.deepEqual(record.rewound, [{ turnId: "000001" }]);
+  assert.equal(record.turns.get("000002").messages[0].text, "Hello");
+});
+
 test("record storage preserves original role, timestamp and message-id overwrite identity", async () => {
   let record = { turns: new Map(), metadata: {} };
   const storage = createConversationStorage({ readRecord: () => record, writeRecord: (_scope, next) => { record = next; } });

package/test/fileConversationStorage.test.js

@@ -71,3 +71,34 @@ test("application scopes cannot traverse paths and deletion remains isolated", a
   assert.deepEqual(await f.transcript.readConversationLog("../../other"), []);
   assert.equal((await f.transcript.readConversationLog("other"))[0].user.text, "Two");
 });
+
+test("saved conversations are parsed once until they change and look messages up by identity", async (t) => {
+  const f = await fixture(t);
+  await f.transcript.writeConversationUserMessage("cached", { text: "First", messageId: "first", at: "2026-01-01T00:00:00Z" });
+  await f.transcript.writeConversationUserMessage("cached", { text: "Second", messageId: "second", at: "2026-01-01T00:00:01Z" });
+  const [file] = (await readdir(f.directory)).filter(name => name.endsWith(".json"));
+  const parse = JSON.parse;
+  let parsed = 0;
+  JSON.parse = (...args) => { parsed += 1; return parse(...args); };
+  try {
+    assert.equal((await f.transcript.findSubmittedTurn("cached", "second")).user.text, "Second");
+    assert.equal(await f.transcript.conversationMessageIdExists("cached", "first"), true);
+    assert.equal(await f.transcript.conversationMessageIdExists("cached", "missing"), false);
+    assert.equal(await f.transcript.findSubmittedTurn("cached", "missing"), null);
+    assert.equal((await f.transcript.readConversationLog("cached")).length, 2);
+    assert.equal(parsed, 0, "The record written by this process is reused.");
+    // An external writer changes the saved file; the next read parses it.
+    const saved = parse(await readFile(join(f.directory, file), "utf8"));
+    saved.turns[1][1].messages[0].text = "Edited elsewhere";
+    await writeFile(join(f.directory, file), JSON.stringify(saved));
+    assert.equal((await f.transcript.findSubmittedTurn("cached", "second")).user.text, "Edited elsewhere");
+    assert.equal(parsed, 1);
+  } finally { JSON.parse = parse; }
+  // Changes made inside a failed write or a read never reach the saved record.
+  await assert.rejects(f.storage.write("cached", async transaction => {
+    await transaction.appendMessage("000001", { role: "assistant", text: "Discarded", at: "2026-01-01T00:00:02Z" });
+    throw new Error("rolled back");
+  }), /rolled back/);
+  await f.storage.read("cached", transaction => transaction.appendMessage("000001", { role: "assistant", text: "Read only", at: "2026-01-01T00:00:03Z" }));
+  assert.equal((await f.transcript.readConversationLog("cached"))[0].assistant, null);
+});

package/test/opencodeConversationSession.test.js

@@ -257,8 +257,10 @@ test("OpenCode delivery timing uses the common receipt stages without recording
   assert.equal(receipt.status, "accepted");
   await f.conversation.wait();
   const stages = timings.map(event => event.stage);
-  assert.deepEqual(stages.slice(0, 8), ["received", "preparation-started", "provider-started", "runtime-ready", "dispatch-started",
-    "native-acknowledged", "receipt-persisted", "accepted"]);
+  const common = ["received", "preparation-started", "provider-started", "runtime-ready", "dispatch-started",
+    "native-acknowledged", "receipt-persisted", "accepted"];
+  assert.deepEqual(stages.filter(stage => common.includes(stage)).slice(0, 8), common);
+  assert.deepEqual(stages.slice(2, 7), ["authorized", "history-read", "state-read", "request-saved", "input-prepared"]);
   assert.equal(stages.filter(stage => stage === "first-response").length, 1);
   assert.equal(JSON.stringify(timings).includes("Private message"), false);
 });