@sema-agent/core 5.64.0 → 6.0.0

package/dist/core/runner/session-file-state-replay.d.ts

@@ -18,11 +18,17 @@
  *     a `git checkout`, a bash command — anything this transcript does not record) therefore fails
  *     the staleness comparison and the edit is refused, exactly as it is inside a single task. A
  *     reconstruction that re-read the file to build its hash would instead wave the dirty edit
- *     through; that is the one thing this module must never do.
- *  2. **Only WHOLE-file records qualify.** A partial read, a notebook projection or an `Edit` result
- *     does not carry the file's full post-condition text, so there is nothing to hash honestly.
- *     Those files are simply not reported: the gate then behaves exactly as it does today (the model
- *     re-reads), which is the pre-existing cost, not a new failure.
+ *     through; that is the one thing this module must never do. (#483 D1, ruled 2026-08-28: this is
+ *     deliberately STRICTER than CC's own rehydrate, whose Edit arm re-reads the disk and would
+ *     admit a between-turns external change — same gate satisfaction, no staleness give-up.)
+ *  2. **Only records whose full post-condition is PROVABLE qualify.** A whole-file `Read` and a
+ *     `Write` carry the text verbatim. An `Edit` card (#483 rung-2) carries a diff BASE — the
+ *     pre-edit whole text plus the resolved mutations — so its post-condition is RECOMPUTED through
+ *     the same single-source application step the tool itself used (`applyRecordedEdit`); a card
+ *     that cannot recompute (malformed, offloaded, or its oldString absent from its own base) falls
+ *     back to RETRACTING the file's record, never to a guess. A partial read or a notebook
+ *     projection proves nothing and is simply not reported: the gate then behaves exactly as before
+ *     (the model re-reads), which is the pre-existing cost, not a new failure.
  */
 import type { AgentMessage } from "../../internal/harness.js";
 /** The whole text of one file at the moment the transcript recorded it. */
@@ -39,11 +45,13 @@ export interface TranscriptFileRecord {
  *
  * Records are read only from SUCCESSFUL results (an `isError` result changed nothing and proves
  * nothing). A `Write` proves the post-condition it just persisted; a whole-file `Read` proves what it
- * just served. An `Edit` result proves that the file CHANGED without recording its new text, so it
- * retracts whatever an earlier record said — leaving a stale entry behind would blame the user for
- * the agent's own edit ("modified since read") the next turn. Anything else (partial reads, dedup
- * stubs, notebook projections, image/document reads, foreign tools) is inert: it neither proves nor
- * retracts, because reading a file does not change it.
+ * just served. An `Edit` card (#483 rung-2) proves the post-condition RECOMPUTED from its recorded
+ * diff base + mutations — or, when it cannot prove (malformed / offloaded / inconsistent), retracts
+ * whatever an earlier record said (leaving a stale entry behind would blame the user for the agent's
+ * own edit, "modified since read", the next turn). A `NotebookEdit` always retracts (deliberate
+ * residual — see {@link RETRACTING_RESULTS}). Anything else (partial reads, dedup stubs, notebook
+ * projections, image/document reads, foreign tools) is inert: it neither proves nor retracts,
+ * because reading a file does not change it.
  *
  * The parameter is the session's own message lane (`AgentMessage`, custom lanes included) rather than
  * the narrowed model-facing union: this reads the branch as the session stores it, and every lane that

package/dist/core/runner/session-file-state-replay.js

@@ -1,11 +1,49 @@
 import { isAbsolutePathForm } from "../../tools/fs/safety.js";
+import { applyRecordedEdit } from "../../tools/fs/fs-shared.js";
+import { normalizeFileText } from "../../tools/fs/encoding.js";
 import { isOffloadedDetailReplacement } from "../tool-result-store.js";
 const READ_TOOL = "Read";
 const WRITE_TOOL = "Write";
+const EDIT_TOOL = "Edit";
 const RETRACTING_RESULTS = [
-    { toolName: "Edit", type: "edit", pathField: "filePath" },
     { toolName: "NotebookEdit", type: "notebook-edit", pathField: "notebookPath" },
 ];
+function replayedEditContent(rest) {
+    const originalFile = rest.originalFile;
+    if (typeof originalFile !== "string" || isOffloadedDetailReplacement(originalFile))
+        return undefined;
+    const member = (v) => (typeof v === "string" && !isOffloadedDetailReplacement(v) ? v : undefined);
+    let edits;
+    const rawEdits = rest.edits;
+    if (Array.isArray(rawEdits) && rawEdits.length > 0) {
+        const out = [];
+        for (const e of rawEdits) {
+            const r = e;
+            const oldS = member(r?.oldString);
+            const newS = member(r?.newString);
+            if (oldS === undefined || newS === undefined)
+                return undefined;
+            out.push({ oldString: oldS, newString: newS, replaceAll: r.replaceAll === true });
+        }
+        edits = out;
+    }
+    else {
+        const oldS = member(rest.oldString);
+        const newS = member(rest.newString);
+        if (oldS === undefined || newS === undefined)
+            return undefined;
+        edits = [{ oldString: oldS, newString: newS, replaceAll: rest.replaceAll === true }];
+    }
+    let working = originalFile;
+    for (const e of edits) {
+        if (e.oldString !== "" && !working.includes(e.oldString))
+            return undefined;
+        working = applyRecordedEdit(working, e);
+    }
+    if (normalizeFileText(working) !== working)
+        return undefined;
+    return working;
+}
 function cardOf(details) {
     if (typeof details !== "object" || details === null)
         return undefined;
@@ -32,6 +70,19 @@ export function wholeFileRecordsFromTranscript(messages) {
         if (card === undefined)
             continue;
         const { type, rest } = card;
+        if (m.toolName === EDIT_TOOL && type === "edit") {
+            const changed = rest.filePath;
+            if (typeof changed !== "string")
+                continue;
+            const replayed = replayedEditContent(rest);
+            if (replayed !== undefined && isAbsolutePathForm(changed)) {
+                byPath.set(changed, { path: changed, content: replayed, at: m.timestamp });
+            }
+            else {
+                byPath.delete(changed);
+            }
+            continue;
+        }
         const retracts = RETRACTING_RESULTS.find((r) => r.toolName === m.toolName && r.type === type);
         if (retracts !== undefined) {
             const changed = rest[retracts.pathField];

package/dist/core/runner/tool-disclosure.js

@@ -2,9 +2,10 @@ import { Type } from "typebox";
 import { Value } from "typebox/value";
 import { defineTool, errorResult } from "../tools.js";
 import { formatZodValidationError, truncateError } from "../tool-errors.js";
+import { DEFAULT_CHARS_PER_TOKEN } from "../../internal/harness.js";
 export const TOOL_SEARCH_NAME = "ToolSearch";
 const DEFER_AUTO_FRACTION = 0.1;
-const CHARS_PER_TOKEN = 4;
+const CHARS_PER_TOKEN = DEFAULT_CHARS_PER_TOKEN;
 export const TOOL_SEARCH_DEFAULT_MAX_RESULTS = 5;
 const MAX_QUERY_RESULTS = 25;
 export const DEFERRED_NO_PROGRESS_LIMIT = 3;

package/dist/core/runner/turn-attachments.d.ts

@@ -437,9 +437,11 @@ export interface AttachmentInputs {
         /**
          * RB-318 (裁 B, 2026-08-26) — `total_tokens_reminder` (CC 2.1.245 producer `MPs`, renderer `Oje`,
          * registered in the SHARED producer group beside `budget_usd`, so a subagent carrying its own
-         * ceiling sees it too — the RB-311 attribution verbatim). Opt-in, default OFF like every other 133
-         * member: an un-opted deployment renders no reminder frame — the ATTACHMENT lane itself is
-         * byte-identical to the pre-lane engine. (Scoped deliberately to this lane: registering
+         * ceiling sees it too — the RB-311 attribution verbatim). DEFAULT ON since design/374 slice 4
+         * (ruled 2026-08-28, matching 2.1.245+'s own default); explicit `false` opts out. Before the
+         * flip an un-opted deployment rendered no reminder frame at all. The countdown arms still need a
+         * declared ceiling, so a task without one is silent either way. (Scoped deliberately to this lane:
+         * registering
          * `<total_tokens>` in ENGINE_ENVELOPES changed the SANITIZE/DISCLOSURE faces for every
          * deployment, opted or not — untrusted text carrying that spelling is now defused on the fenced
          * lanes and envelope-shaped external data trips the design/319 disclosure tail. That is the
@@ -454,6 +456,14 @@ export interface AttachmentInputs {
          * ({@link AttachmentInputs.totalTokens}), the ceiling is the deployment's own declared
          * `limits.maxTokens`, and with no ceiling declared the countdown arms simply never fire.
          *
+         * AND WHY IT IS NOW ON BY DEFAULT (design/374 slice 4, 2026-08-28): the same 245 fact that
+         * justified BUILDING it is a statement about its DEFAULT, so shipping it opt-in left the engine
+         * one ruling short of the anchor. Both halves of "is this safe on by default" hold here — the
+         * readout cannot be wrong (it reads the enforced coordinate, never an estimate), and it cannot
+         * appear where nobody asked for a ceiling (no ceiling ⇒ no numbers ⇒ silence). The `budget_usd`
+         * twin stays opt-in: CC has no default-on posture for it, and inventing one would be the
+         * unanchored move.
+         *
          * The arm is chosen by {@link totalTokensReminderMode} (default {@link
          * TOTAL_TOKENS_REMINDER_DEFAULT_MODE}); `off` there silences the lane without un-wiring it.
          */
@@ -482,7 +492,7 @@ export interface AttachmentInputs {
      *  activated), sorted, snapshotted by the run loop. CC 220's equivalent is
      *  `tools.filter(iY(u) && !discovered.has(u.name)).map(name).sort()` (@608934-608938). Only passed
      *  when `config.toolSearchReminder` is opted in AND the task actually has deferred tools — an empty
-     *  or absent list silences the lane permanently (CC `no_undiscovered_tools`, @608939). */
+     *  or absent list silences the lane permanently (CC `no_undiscovered_tools`, @608939 (cli250.js:44368)). */
     undiscoveredTools?: readonly string[];
     /** RB-403 — is the direct-call lane mounted on this run's placeholders (`Prepared.deferDirectCall`,
      *  i.e. `TaskSpec.deferSelfResolve` not disabled)? Selects which closing sentence the
@@ -673,7 +683,7 @@ export declare function renderOrphanedBackgroundTasks(tasks: ReadonlyArray<{
     description?: string;
 }>): string;
 /**
- * RB-309 — CC's per-frame list cap for the `deferred_tools_delta` arms (`lP`, pretty220.js:518269).
+ * RB-309 — CC's per-frame list cap for the `deferred_tools_delta` arms (`lP`, (pretty220.js:518269, historical; not relocated in 250 — see cc-250 anchors)).
  * Lists longer than this collapse to a grouped one-liner + "…and N more".
  */
 export declare const TOOLS_DELTA_LIST_MAX = 30;
@@ -682,13 +692,13 @@ export declare const TOOLS_DELTA_LIST_MAX = 30;
  *  are CALLER-drained on intact cap survival, exactly like {@link AttachmentInputs.newTools}. */
 export interface McpToolsDeltaFacts {
     /** Previously-announced deferred tools that LEFT the harness roster (their server withdrew them —
-     *  reached through RefreshMcpTools's prefix re-splice). CC `removedNames` @626530. */
+     *  reached through RefreshMcpTools's prefix re-splice). CC `removedNames` @626530 (cli250.js:45892). */
     removed?: readonly string[];
     /** Previously-announced-then-withdrawn deferred tools that came BACK. CC `readdedNames` @626525. */
     readded?: readonly string[];
     /** Declared MCP servers that failed to connect at materialize (`MaterializedMcp.statuses`, status
      *  `"failed"`). `error` is REMOTE/transport text — the producer neutralizes + bounds it at intake.
-     *  CC `failedMcpServers` @626561. */
+     *  CC `failedMcpServers` @626561 (cli250.js:45904). */
     failedServers?: ReadonlyArray<{
         name: string;
         error?: string;
@@ -704,15 +714,15 @@ export interface McpToolsDeltaFacts {
  * the middle clause is inverted to match sema's actual contract. Same CC shape: lead sentence +
  * name list.
  *
- * RB-309 — CC 2.1.220 (`deferred_tools_delta`, pretty220.js:626512-626600) carries SIX arms; sema
+ * RB-309 — CC 2.1.220 (`deferred_tools_delta`, cli250.js:45890-45918) carries SIX arms; sema
  * shipped only the `added` one. The arms below are the ones whose STATE IS REACHABLE in this engine
  * (data-side audit, RB-309):
- * - `readded` (@626525) / `removed` (@626530): reachable via RefreshMcpTools — the refresh splices a
+ * - `readded` (@626525) / `removed` (@626530 (cli250.js:45892)): reachable via RefreshMcpTools — the refresh splices a
  *   server's whole `mcp__<server>__` prefix domain out of the live tool array and pushes the fresh
  *   listing back, so a withdrawn tool genuinely leaves (and a re-advertised one genuinely returns)
  *   the roster mid-task. CC's trailing "Load via ToolSearch as before" / "Do not search for them —
  *   ToolSearch will return no match" clauses are kept, because sema mounts the SAME ToolSearch name.
- * - `failed` (@626561): reachable from `MaterializedMcp.statuses` (`status: "failed"`, fail-open
+ * - `failed` (@626561 (cli250.js:45904)): reachable from `MaterializedMcp.statuses` (`status: "failed"`, fail-open
  *   connect skip). CC additionally splits a MANAGED-POLICY sub-arm off this list (`jlr`/`Oy_` error
  *   codes @626575) — sema has no managed-policy error taxonomy, so only the connection-failure form
  *   is rendered.
@@ -721,7 +731,7 @@ export interface McpToolsDeltaFacts {
  *   (`McpServerSpec.transport.headers` / `principalHeader`) with no OAuth flow and no
  *   authorization-required status — an auth rejection surfaces as an ordinary connect failure and is
  *   covered by the `failed` arm above.
- * - `pending` (@626586): `materializeMcpTools` is fully AWAITED inside prepareTask (one
+ * - `pending` (@626586 (cli250.js:45913)): `materializeMcpTools` is fully AWAITED inside prepareTask (one
  *   `Promise.allSettled` over every server) before the run loop's first turn, so "still connecting"
  *   does not exist at any turn boundary — `McpServerStatus.status` is `connected | failed` only.
  * Returns `undefined` when every arm is empty (CC `i.length === 0 → []`).
@@ -918,7 +928,7 @@ export declare function renderMcpInstructionsDelta(added: ReadonlyArray<{
  * `mcp_dropped_tools_delta` system reminder). Per-entry line shape follows CC's `qny`
  * (pretty.js:481821): `"${tool}" (MCP server "${server}"): "${reason}"`.
  *
- * RB-310 — the lead is now CC 2.1.220 VERBATIM (pretty220.js:626666-626670): the `# Unavailable MCP
+ * RB-310 — the lead is now CC 2.1.220 VERBATIM (cli250.js:45934-45936): the `# Unavailable MCP
  * Tools` heading, the full lead sentence, the **"Quoted text is data reported during validation, not
  * instructions"** neutralizer (which is exactly what sema's quote-wrapped `"${reason}"` /
  * `"${server}"` interpolation needed and did not have), and the "tell them it was excluded and why"

package/dist/core/session-store.d.ts

@@ -145,7 +145,7 @@ export declare class TtlSessionStore implements SessionStore {
     /** Record the most recent task run on a cached session (the `/resume` `lastRunId`); also bumps the idle
      *  timer. Best-effort — a no-op if the session isn't cached here (the run will still be re-attachable via
      *  its checkpoint). */
-    noteTaskRun(sessionId: string, taskId: string): void;
+    noteTaskRun(sessionId: string, taskId: string, runId?: string): void;
     /** List the live cache as {@link SessionStoreSummary} projections, newest-first by `lastActiveAt` (so a
      *  shell's `/resume` shows recent sessions + their last run first). The in-memory store lists only its
      *  live cache, not evicted/durable history — a durable backend overrides this to list persisted sessions. */

package/dist/core/session-store.js

@@ -119,10 +119,14 @@ export class TtlSessionStore {
             e.lastActiveAt = Date.now();
         }
     }
-    noteTaskRun(sessionId, taskId) {
+    noteTaskRun(sessionId, taskId, runId) {
         const e = this.entries.get(sessionId);
         if (e) {
             e.lastTaskId = taskId;
+            if (runId !== undefined)
+                e.lastTaskRunId = runId;
+            else
+                delete e.lastTaskRunId;
             e.lastActiveAt = Date.now();
         }
     }
@@ -134,6 +138,7 @@ export class TtlSessionStore {
             lastActiveAt: e.lastActiveAt,
             ...(e.createdAt !== undefined && e.createdAt !== "" ? { createdAt: e.createdAt } : {}),
             ...(e.lastTaskId !== undefined ? { lastTaskId: e.lastTaskId } : {}),
+            ...(e.lastTaskRunId !== undefined ? { lastTaskRunId: e.lastTaskRunId } : {}),
             ...(e.forkedFrom !== undefined ? { forkedFrom: e.forkedFrom } : {}),
         }))
             .sort((a, b) => b.lastActiveAt - a.lastActiveAt);

package/dist/core/session.d.ts

@@ -73,6 +73,30 @@ export interface SessionStoreSummary {
     /** The most recent task run on this session (core's `taskId`; the service projects it as `lastRunId`).
      *  Absent until a task has run on the session (recorded via {@link SessionStore.noteTaskRun}). */
     lastTaskId?: string;
+    /**
+     * #499 — an ENGINE-minted run identity for this session ({@link import("./types.js").TaskResult.runId}),
+     * recorded by the most recent {@link SessionStore.noteTaskRun} write to LAND.
+     * {@link lastTaskId} above is `spec.taskId ?? sessionId`, so on the ordinary deployment that supplies no
+     * host task id it answers the SESSION's own id: a "last run" handle that names the session it hangs off
+     * cannot say WHICH run it means. This one names a specific run — read the ORDERING clause below for
+     * exactly how strong "most recent" is here, which is weaker than the sibling field's wording implies.
+     *
+     * Named `lastTaskRunId`, NOT `lastRunId`: the paragraph above this interface records that a service
+     * backend renames `lastTaskId` → the WIRE field `lastRunId`, so a store field spelled `lastRunId` would
+     * be the same name carrying a different identity one hop apart — a mixed-version mapper (or an object
+     * spread) could then publish either value under the one wire name with no type error. Same
+     * collision-avoidance as {@link import("../orchestration/workflow-types.js").WorkflowAgentRun.taskRunId}.
+     *
+     * ORDERING (honest limit): the Runner records this fire-and-forget, exactly as it always has for
+     * `lastTaskId`, so on a store whose write is asynchronous two runs of one session race and the loser's
+     * id can land last. That race was invisible while both runs wrote the same `lastTaskId`; it is
+     * observable here. Read this as "an id of a recent run", and take strict ordering from the runs'
+     * own results, not from this projection.
+     *
+     * Additive and optional: absent on a store that predates it, absent until a task has run, and absent
+     * whenever the recording caller had no run id (see {@link SessionStore.noteTaskRun}).
+     */
+    lastTaskRunId?: string;
     /** F7 fork-GC seam: the parent session this one was forked from ({@link SessionMetadata.forkedFrom}).
      *  Lets a consumer render/reap fork lineage; absent on non-forked sessions and on cache views that
      *  predate the fork. The durable source of truth is the repo's persisted metadata. */
@@ -175,8 +199,17 @@ export interface SessionStore {
      * re-attach to the most recent run, even one still in-flight or suspended. **Optional + best-effort**: a
      * store that surfaces no session list may ignore it; it MUST NOT throw. The engine's `taskId` is the
      * service's `lastRunId`.
+     *
+     * `runId` (#499, additive third parameter — an existing implementation keeps typechecking and keeps
+     * working): the engine's own identity for THIS run, for {@link SessionStoreSummary.lastTaskRunId}. It
+     * is supplied because `taskId` cannot answer "which run": with no host task id it IS the session id.
+     *
+     * The two seats describe ONE run and MUST move together: a call that omits `runId` records the new
+     * `lastTaskId` and CLEARS `lastTaskRunId`. Keeping the previous run's id beside a newer task id would
+     * assert that an id belonging to an older run identifies the latest one — absence is the honest answer
+     * to "which run was last" when the caller does not know.
      */
-    noteTaskRun?(sessionId: string, taskId: string): void | Promise<void>;
+    noteTaskRun?(sessionId: string, taskId: string, runId?: string): void | Promise<void>;
     /**
      * Enumerate known sessions as lightweight {@link SessionStoreSummary} projections (newest-first by
      * `lastActiveAt`) so a shell's `/resume` lists sessions + their last run in ONE call. **Optional**: the

package/dist/core/store-contracts/file-history-store-contract.d.ts

@@ -0,0 +1,3 @@
+import type { FileHistoryStore } from "../file-history-store.js";
+import { type ContractAssertionRunner } from "./contract-harness.js";
+export declare function fileHistoryStoreContract(make: () => FileHistoryStore, runAssertion?: ContractAssertionRunner): Promise<void>;