@sema-agent/core 5.64.0 → 6.0.0

package/dist/tools/fs/fs-write.js

@@ -3,8 +3,22 @@ import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
 import { sha256, resolveKey, violationText, violationDetails, requireRead, checkStale, checkEditMatch, checkNoChange, fileArgPath, resolveQuoteMatch, adaptNewStringQuotes, resolveEscapeMatch, adaptNewStringEscapes, escapeMatchWasAttempted, ESCAPE_MATCH_MISS_NOTE, deletionOldString, countOccurrences, READ_REFUSED_ESCAPE_HINT, } from "./safety.js";
 import { decodeTextBytes, encodeTextForFile, normalizeEditText, normalizeFileText } from "./encoding.js";
-import { MAX_EDIT_BYTES, decodeEditBytes, tooLargeToEditMessage, truncatedUtf16BodyMessage, persistedTextOf, notReadRefusalText, enoentMessage, FILE_STATE_TRAILER, FILE_PATH_PARAMS, ipynbRedirect, countLines, } from "./fs-shared.js";
+import { MAX_EDIT_BYTES, decodeEditBytes, tooLargeToEditMessage, truncatedUtf16BodyMessage, persistedTextOf, notReadRefusalText, enoentMessage, FILE_STATE_TRAILER, FILE_PATH_PARAMS, ipynbRedirect, countLines, applyRecordedEdit, } from "./fs-shared.js";
 async function envFinalWrite(env, key, content, signal, opts) {
+    let r;
+    try {
+        r = await writeThroughEnv(env, key, content, signal, opts);
+    }
+    catch (err) {
+        await discardTrackedEdit(opts?.track, "verify");
+        throw err;
+    }
+    if (!r.ok)
+        await discardTrackedEdit(opts?.track, NOTHING_WAS_WRITTEN.has(r.error.code) ? "proven" : "verify");
+    return r;
+}
+const NOTHING_WAS_WRITTEN = new Set(["already_exists", "precondition_failed"]);
+async function writeThroughEnv(env, key, content, signal, opts) {
     if (env.writeFileGuarded !== undefined) {
         const r = await env.writeFileGuarded(key, content, { canonicalPath: key, ...(opts?.exclusive === true ? { exclusive: true } : {}) }, signal);
         return r.ok ? { ok: true } : r;
@@ -14,6 +28,30 @@ async function envFinalWrite(env, key, content, signal, opts) {
     }
     return env.writeFile(key, content, signal);
 }
+async function discardTrackedEdit(lease, proof) {
+    if (lease?.annul === undefined)
+        return;
+    try {
+        await lease.annul(proof);
+    }
+    catch {
+    }
+}
+const clipHookText = (s) => (s.length > 300 ? `${s.slice(0, 300)}…` : s);
+async function trackToolEdit(hook, tool, path, key, signal) {
+    if (hook === undefined)
+        return {};
+    let res;
+    try {
+        res = await hook({ tool, path, key, ...(signal !== undefined ? { signal } : {}) });
+    }
+    catch (err) {
+        return { refusal: `Error (${tool}): the file-history first-touch backup failed (${clipHookText(err instanceof Error ? err.message : String(err))}) — nothing was written.` };
+    }
+    if (res.ok === false)
+        return { refusal: clipHookText(res.refusal) };
+    return res.annul !== undefined ? { annul: res.annul } : {};
+}
 async function gateToolWrite(hook, tool, path, key, content) {
     if (hook === undefined)
         return undefined;
@@ -22,13 +60,13 @@ async function gateToolWrite(hook, tool, path, key, content) {
         res = await hook({ tool, path, key, content });
     }
     catch (err) {
-        return `Error (${tool}): the write gate failed (${err instanceof Error ? err.message : String(err)}) — nothing was written.`;
+        return `Error (${tool}): the write gate failed (${clipHookText(err instanceof Error ? err.message : String(err))}) — nothing was written.`;
     }
     if (res !== undefined && res.ok === false)
-        return `Error (${tool}): write rejected by the write gate (${res.code}): ${res.reason}`;
+        return `Error (${tool}): write rejected by the write gate (${res.code}): ${clipHookText(res.reason)}`;
     return undefined;
 }
-export function createEditFileTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite) {
+export function createEditFileTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit) {
     return defineTool({
         name: "Edit",
         contract: { contractId: "core.edit@1", implementationRevision: "1" },
@@ -81,7 +119,10 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
                     const gated = await gateToolWrite(beforeWrite, "Edit", path, r.key, created);
                     if (gated !== undefined)
                         return errorResult(gated);
-                    const write = await envFinalWrite(env, r.key, created, ctx.signal, { exclusive: true });
+                    const tracked = await trackToolEdit(trackEdit, "Edit", path, r.key, ctx.signal);
+                    if (tracked.refusal !== undefined)
+                        return errorResult(tracked.refusal);
+                    const write = await envFinalWrite(env, r.key, created, ctx.signal, { exclusive: true, track: tracked });
                     if (!write.ok) {
                         if (write.error.code === "already_exists") {
                             return errorResult(`Error (Edit): cannot create "${path}": file already exists (created concurrently since the existence check). Read the file first, then edit it normally (or Write after the Read to overwrite it).`);
@@ -131,8 +172,11 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
                 const gated = await gateToolWrite(beforeWrite, "Edit", path, r.key, newContent);
                 if (gated !== undefined)
                     return errorResult(gated);
+                const trackedOverwrite = await trackToolEdit(trackEdit, "Edit", path, r.key, ctx.signal);
+                if (trackedOverwrite.refusal !== undefined)
+                    return errorResult(trackedOverwrite.refusal);
                 const encodedOverwrite = encodeTextForFile(newContent, preDec.encoding, preDec.endings);
-                const write = await envFinalWrite(env, r.key, encodedOverwrite, ctx.signal);
+                const write = await envFinalWrite(env, r.key, encodedOverwrite, ctx.signal, { track: trackedOverwrite });
                 if (!write.ok)
                     return errorResult(`Error (Edit): cannot write "${path}": ${write.error.message}`);
                 const persistedOverwrite = persistedTextOf(encodedOverwrite);
@@ -198,14 +242,18 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
                 }
                 replacements += e.replace_all === true ? countOccurrences(working, oldS) : 1;
                 const effOld = e.replace_all === true ? oldS : deletionOldString(working, oldS, newS);
-                working = e.replace_all === true ? working.split(effOld).join(newS) : working.replace(effOld, () => newS);
-                appliedEdits.push({ oldString: effOld, newString: newS, replaceAll: e.replace_all === true });
+                const applied = { oldString: effOld, newString: newS, replaceAll: e.replace_all === true };
+                working = applyRecordedEdit(working, applied);
+                appliedEdits.push(applied);
             }
             const gated = await gateToolWrite(beforeWrite, "Edit", path, r.key, working);
             if (gated !== undefined)
                 return errorResult(gated);
+            const trackedEdit = await trackToolEdit(trackEdit, "Edit", path, r.key, ctx.signal);
+            if (trackedEdit.refusal !== undefined)
+                return errorResult(trackedEdit.refusal);
             const encodedEdit = encodeTextForFile(working, decoded.encoding, decoded.endings);
-            const write = await envFinalWrite(env, r.key, encodedEdit, ctx.signal);
+            const write = await envFinalWrite(env, r.key, encodedEdit, ctx.signal, { track: trackedEdit });
             if (!write.ok)
                 return errorResult(`Error (Edit): cannot write "${path}": ${write.error.message}`);
             const persistedEdit = persistedTextOf(encodedEdit);
@@ -228,7 +276,7 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
         },
     });
 }
-export function createWriteFileTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite) {
+export function createWriteFileTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit) {
     return defineTool({
         name: "Write",
         contract: { contractId: "core.write@1", implementationRevision: "1" },
@@ -275,8 +323,11 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
                 const gated = await gateToolWrite(beforeWrite, "Write", path, r.key, content);
                 if (gated !== undefined)
                     return errorResult(gated);
+                const trackedWrite = await trackToolEdit(trackEdit, "Write", path, r.key, ctx.signal);
+                if (trackedWrite.refusal !== undefined)
+                    return errorResult(trackedWrite.refusal);
                 const encodedWrite = encodeTextForFile(content, decodedPrev.encoding, "preserve");
-                const write = await envFinalWrite(env, r.key, encodedWrite, ctx.signal);
+                const write = await envFinalWrite(env, r.key, encodedWrite, ctx.signal, { track: trackedWrite });
                 if (!write.ok)
                     return errorResult(`Error (Write): cannot write "${path}": ${write.error.message}`);
                 const persistedWrite = persistedTextOf(encodedWrite);
@@ -289,7 +340,10 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
             const gatedCreate = await gateToolWrite(beforeWrite, "Write", path, r.key, content);
             if (gatedCreate !== undefined)
                 return errorResult(gatedCreate);
-            const write = await envFinalWrite(env, r.key, content, ctx.signal);
+            const trackedCreate = await trackToolEdit(trackEdit, "Write", path, r.key, ctx.signal);
+            if (trackedCreate.refusal !== undefined)
+                return errorResult(trackedCreate.refusal);
+            const write = await envFinalWrite(env, r.key, content, ctx.signal, { track: trackedCreate });
             if (!write.ok)
                 return errorResult(`Error (Write): cannot write "${path}": ${write.error.message}`);
             const totalLines = countLines(content);
@@ -302,7 +356,7 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
         },
     });
 }
-export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite) {
+export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additionalRoots, beforeWrite, trackEdit) {
     return defineTool({
         name: "NotebookEdit",
         contract: { contractId: "core.notebook_edit@1", implementationRevision: "1" },
@@ -420,7 +474,10 @@ export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additi
             const gated = await gateToolWrite(beforeWrite, "NotebookEdit", notebook_path, r.key, updated);
             if (gated !== undefined)
                 return errorResult(gated);
-            const w = await envFinalWrite(env, r.key, encodeTextForFile(updated, decodedNb.encoding, decodedNb.endings), ctx.signal);
+            const trackedNb = await trackToolEdit(trackEdit, "NotebookEdit", notebook_path, r.key, ctx.signal);
+            if (trackedNb.refusal !== undefined)
+                return errorResult(trackedNb.refusal);
+            const w = await envFinalWrite(env, r.key, encodeTextForFile(updated, decodedNb.encoding, decodedNb.endings), ctx.signal, { track: trackedNb });
             if (!w.ok)
                 return errorResult(`Error (NotebookEdit): cannot write "${notebook_path}": ${w.error.message}`);
             state.set(r.key, { hash: sha256(updated), totalLines: countLines(updated), truncated: false, lastReadAt: Date.now() });

package/dist/tools/fs/index.d.ts

@@ -1,5 +1,5 @@
 import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
-import { type BeforeWriteHook } from "../../core/types.js";
+import { type BeforeWriteHook, type TrackFileEditHook } from "../../core/types.js";
 import { type TaskRegistry } from "../../core/task-registry.js";
 import { type ReadFileState } from "./safety.js";
 import type { PdfModelCapabilities } from "./pdf.js";
@@ -115,6 +115,11 @@ export interface HandsToolkitOptions {
     /** design/138 S2-C — write-time content gate for Write/Edit/NotebookEdit (see {@link BeforeWriteHook}).
      *  The Runner wires the MemoryEngine's memory-domain scan here; absent ⇒ byte-identical behavior. */
     beforeWrite?: BeforeWriteHook;
+    /** design/381 — first-touch file-history hook for Write/Edit/NotebookEdit (see
+     *  {@link TrackFileEditHook}): called after the content gates pass, immediately before the final
+     *  env write, so the file's pre-edit state is durably recorded before it changes. The Runner
+     *  wires it to `FileHistoryStore.trackEdit`; absent ⇒ byte-identical behavior (no history). */
+    trackFileEdit?: TrackFileEditHook;
     /** #181-F6 — see createBashTool's taskOpts field of the same name: whether the Monitor tool is on
      *  this run's roster (the Runner mounts Monitor, this band never does). `false` drops the gh
      *  rate-limit hint's Monitor clause; absent ⇒ historic full wording (byte-compat). */

package/dist/tools/fs/index.js

@@ -50,7 +50,7 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
         createReadFileTool(env, readFileState, rootCanonical, readOnly ? undefined : cwdRef, readFaceRoots, opts.readImageDownsampler, opts.pdfModelCapabilities, bgOutputReadExemption, opts.readCyberReminder, readDeny, readFace, opts.reminderMark, opts.reminderDisclosureCounts),
     ];
     if (!readOnly) {
-        tools.push(createEditFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite), createWriteFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite), createNotebookEditTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite));
+        tools.push(createEditFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit), createWriteFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit), createNotebookEditTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit));
     }
     tools.push(createGrepTool(env, rootCanonical, readFaceRoots, readDeny, readFace), createGlobTool(env, rootCanonical, readFaceRoots, readDeny, readFace), createRepoMapTool(env, rootCanonical, readFaceRoots, readDeny, readFace));
     if (includeShell) {

package/dist/tools/web.js

@@ -4,6 +4,7 @@ import { delimitUntrusted, inlineUntrusted } from "../core/untrusted-text.js";
 import { discloseReminderShaped, observeReminderMarkEcho } from "../core/reminder-disclosure.js";
 import { redactSecrets } from "../core/untrusted-egress.js";
 import { isPrivateHost } from "../core/runner/image.js";
+import { DEFAULT_CHARS_PER_TOKEN } from "../internal/harness.js";
 import { binaryMagicFormat } from "./fs/safety.js";
 import { pdfMagicMatches } from "./fs/pdf.js";
 const MAX_REDIRECTS = 10;
@@ -701,7 +702,7 @@ export function resolveSummaryInputChars(model, override) {
         return Math.floor(override);
     }
     const window = model.contextTokens ?? model.contextWindow;
-    const charsPerToken = model.charsPerToken ?? 4;
+    const charsPerToken = model.charsPerToken ?? DEFAULT_CHARS_PER_TOKEN;
     for (const [name, value] of [
         ["contextTokens/contextWindow", window],
         ["maxTokens", model.maxTokens],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "5.64.0",
+  "version": "6.0.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",
@@ -48,6 +48,7 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json && tsc -p tsconfig.build.json --emitDeclarationOnly --removeComments false",
     "typecheck": "tsc --noEmit",
+    "pretest": "npm run gate:debts",
     "test": "vitest run --exclude \"**/*.local.test.ts\"",
     "test:watch": "vitest",
     "gate:skips": "vitest run --exclude \"**/node_modules/**\" --exclude \"**/*.local.test.ts\" --reporter=default --reporter=json --outputFile.json=.skip-report.json && node scripts/verify-skip-baseline.mjs --report .skip-report.json",
@@ -65,6 +66,9 @@
     "gate:single-mint": "node scripts/verify-single-mint.mjs",
     "gate:nuia": "node scripts/verify-nuia-baseline.mjs",
     "gate:field-liveness": "node scripts/verify-field-liveness.mjs",
+    "gate:debts": "node scripts/verify-debts.mjs",
+    "handoff:diff": "node scripts/dist-handoff-diff.mjs",
+    "gate:debts:rc": "node scripts/verify-debts.mjs --rc-gate",
     "gate:error-surface": "node scripts/verify-error-surface.mjs",
     "gate:criteria": "node scripts/criteria-lint.mjs",
     "gate:reminder-literal": "node scripts/verify-reminder-literal.mjs"