indusagi 0.12.34 → 0.13.0

package/dist/react-ink.js

@@ -2061,6 +2061,9 @@ function statusMarker(status) {
       return ">";
   }
 }
+function statusColorKey(status) {
+  return status === "error" ? "error" : "text";
+}
 function plainToolText(text) {
   return stripAnsi5(text);
 }
@@ -2102,7 +2105,7 @@ function ToolEventBlock({
   showTitle = true,
   status,
   summary,
-  theme: _theme,
+  theme,
   title
 }) {
   const normalizedSummary = summary?.trim();
@@ -2118,19 +2121,19 @@ function ToolEventBlock({
   const { visibleLines, hiddenLineCount } = clampContentLines(combinedLines, maxContentLines);
   return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", marginBottom, marginLeft: indent, children: [
     showTitle ? /* @__PURE__ */ jsxs(Box, { children: [
-      /* @__PURE__ */ jsx(Text, { color: "white", children: plainToolText(`${statusMarker(status)} `) }),
-      /* @__PURE__ */ jsx(Text, { color: "white", children: plainToolText(title) }),
-      showSummaryInline && normalizedSummary ? /* @__PURE__ */ jsx(Text, { color: "white", children: plainToolText(` (${normalizedSummary})`) }) : null
+      /* @__PURE__ */ jsx(Text, { children: theme.color(statusColorKey(status), plainToolText(`${statusMarker(status)} `)) }),
+      /* @__PURE__ */ jsx(Text, { children: theme.color(statusColorKey(status), plainToolText(title)) }),
+      showSummaryInline && normalizedSummary ? /* @__PURE__ */ jsx(Text, { children: theme.muted(plainToolText(` (${normalizedSummary})`)) }) : null
     ] }) : null,
     visibleLines.map((line, index) => /* @__PURE__ */ jsx(
       Box,
       {
         marginLeft: line.kind === "response" ? showTitle ? 2 : 0 : showTitle ? 4 : 2,
-        children: preformatted ? /* @__PURE__ */ jsx(Text, { children: line.text }) : /* @__PURE__ */ jsx(Text, { color: "white", children: plainToolText(line.text) })
+        children: preformatted ? /* @__PURE__ */ jsx(Text, { children: line.text }) : /* @__PURE__ */ jsx(Text, { children: theme.color("text", plainToolText(line.text)) })
       },
       `${line.kind}:${index}:${stripAnsi5(line.text)}`
     )),
-    hiddenLineCount > 0 ? /* @__PURE__ */ jsx(Box, { marginLeft: showTitle ? 4 : 2, children: /* @__PURE__ */ jsx(Text, { color: "white", children: plainToolText(`... ${hiddenLineCount} more line(s)`) }) }) : null
+    hiddenLineCount > 0 ? /* @__PURE__ */ jsx(Box, { marginLeft: showTitle ? 4 : 2, children: /* @__PURE__ */ jsx(Text, { children: theme.muted(plainToolText(`... ${hiddenLineCount} more line(s)`)) }) }) : null
   ] });
 }
 
@@ -2473,20 +2476,20 @@ function MessageList({
 }
 
 // src/react-ink/components/StatusLine.tsx
-function StatusLine({ snapshot, status, theme }) {
+function StatusLine({ snapshot, status, theme, showBusyText = true }) {
   let text = status?.text;
   let tone = status?.kind ?? "info";
   if (!text) {
-    if (snapshot.isCompacting) {
+    if (showBusyText && snapshot.isCompacting) {
       text = "Compacting conversation context...";
       tone = "busy";
-    } else if (snapshot.isBashRunning) {
+    } else if (showBusyText && snapshot.isBashRunning) {
       text = "Running bash command...";
       tone = "busy";
-    } else if (snapshot.pendingToolCallCount > 0 || snapshot.pendingMessageCount > 0) {
+    } else if (showBusyText && (snapshot.pendingToolCallCount > 0 || snapshot.pendingMessageCount > 0)) {
       text = "Agent working...";
       tone = "busy";
-    } else if (snapshot.isStreaming) {
+    } else if (showBusyText && snapshot.isStreaming) {
       text = "Agent working...";
       tone = "busy";
     } else if (snapshot.error) {
@@ -3815,6 +3818,7 @@ export {
   previewText,
   safeStringify,
   splitAssistantMessage,
+  statusColorKey,
   stringWidth,
   wordDiffLine,
   wrapSelectionIndex

package/dist/shell-app.js

@@ -4635,6 +4635,7 @@ function runErrorThrowable(kind, message) {
 }
 
 // src/capabilities/kernel/spec.ts
+var READ_STATE_HANDLE_KEY = "readState";
 function coerceInput(raw) {
   if (typeof raw === "string") {
     const trimmed = raw.trim();
@@ -5088,7 +5089,7 @@ var standardBudget = {
 [${omitted} bytes elided to stay within the output ceiling]
 `
 };
-function makeNodeContext(cwd, signal, budget) {
+function makeNodeContext(cwd, signal, budget, framework) {
   if (typeof cwd !== "string" || cwd.length === 0) {
     throw new Error("makeNodeContext requires a non-empty working directory.");
   }
@@ -5097,10 +5098,60 @@ function makeNodeContext(cwd, signal, budget) {
     fs: nodeFs,
     shell: nodeShell,
     signal: signal ?? neverAborts(),
-    budget: budget ?? standardBudget
+    budget: budget ?? standardBudget,
+    ...framework ? { framework } : {}
   };
 }
 
+// src/capabilities/files/read-state-gate.ts
+var READ_BEFORE_EDIT_MESSAGE = "File has not been read yet. Read it first before writing to it.";
+var MODIFIED_SINCE_READ_MESSAGE = "File has been modified since read, either by the user or by a linter. Read it again before attempting to write it.";
+function getReadStateHandle(ctx) {
+  const bag = ctx.framework;
+  if (!bag || typeof bag !== "object") return void 0;
+  const candidate = bag[READ_STATE_HANDLE_KEY];
+  if (!candidate || typeof candidate !== "object") return void 0;
+  const handle = candidate;
+  if (typeof handle.get !== "function" || typeof handle.set !== "function" || typeof handle.has !== "function") {
+    return void 0;
+  }
+  return handle;
+}
+async function recordReadState(ctx, absPath, handle) {
+  if (!handle) return;
+  try {
+    const info = await ctx.fs.stat(absPath);
+    const record = {
+      mtimeMs: Math.floor(info.modifiedMs),
+      size: info.size,
+      readAt: Date.now()
+    };
+    handle.set(absPath, record);
+  } catch {
+  }
+}
+async function enforceReadGate(ctx, absPath, handle) {
+  if (!handle) return { ok: true };
+  if (!handle.has(absPath)) {
+    return { ok: false, message: READ_BEFORE_EDIT_MESSAGE };
+  }
+  const recorded = handle.get(absPath);
+  if (!recorded) {
+    return { ok: false, message: READ_BEFORE_EDIT_MESSAGE };
+  }
+  let info;
+  try {
+    info = await ctx.fs.stat(absPath);
+  } catch {
+    return { ok: true };
+  }
+  const currentMtime = Math.floor(info.modifiedMs);
+  if (currentMtime > recorded.mtimeMs || info.size !== recorded.size) {
+    return { ok: false, message: MODIFIED_SINCE_READ_MESSAGE };
+  }
+  return { ok: true };
+}
+
 // src/capabilities/files/read.ts
 var GUTTER_WIDTH = 6;
 var DESCRIPTION = [
@@ -5203,6 +5254,7 @@ var readTool = defineTool({
       const detail = err instanceof Error ? err.message : String(err);
       return failure(`Could not read ${path2}: ${detail}`);
     }
+    await recordReadState(ctx, path2, getReadStateHandle(ctx));
     const allLines = toLines(text);
     const totalLines = allLines.length;
     if (totalLines === 0) {
@@ -5310,11 +5362,19 @@ var writeTool = defineTool({
   async run(input, ctx) {
     const path2 = readPath(input?.path);
     const content = readContent(input?.content);
+    const handle = getReadStateHandle(ctx);
+    if (handle && await ctx.fs.exists(path2)) {
+      const gate = await enforceReadGate(ctx, path2, handle);
+      if (!gate.ok) {
+        return asText(gate.message, true);
+      }
+    }
     const folder = parentDir(path2);
     if (folder.length > 0) {
       await ctx.fs.mkdir(folder, { recursive: true });
     }
     await ctx.fs.writeFile(path2, content, "utf8");
+    await recordReadState(ctx, path2, handle);
     const bytes = Buffer.byteLength(content, "utf8");
     const unit = bytes === 1 ? "byte" : "bytes";
     return asText(`Saved ${bytes} ${unit} to ${path2}.`);
@@ -5604,6 +5664,11 @@ async function runEdit(input, ctx) {
   if (!info.isFile) {
     return failure2(`${path2} is not a regular file, so it cannot be edited.`);
   }
+  const handle = getReadStateHandle(ctx);
+  const gate = await enforceReadGate(ctx, path2, handle);
+  if (!gate.ok) {
+    return failure2(gate.message);
+  }
   const before = await ctx.fs.readFile(path2, "utf8");
   const literalHits = countLiteral(before, oldText);
   if (literalHits > 0) {
@@ -5617,6 +5682,7 @@ async function runEdit(input, ctx) {
       return failure2(`The replacement left ${path2} unchanged.`);
     }
     await ctx.fs.writeFile(path2, after2, "utf8");
+    await recordReadState(ctx, path2, handle);
     return success(path2, before, after2, replaceAll ? literalHits : 1);
   }
   const spans = findFuzzySpans(before, oldText);
@@ -5640,6 +5706,7 @@ async function runEdit(input, ctx) {
     return failure2(`The fuzzy replacement left ${path2} unchanged.`);
   }
   await ctx.fs.writeFile(path2, after, "utf8");
+  await recordReadState(ctx, path2, handle);
   return success(path2, before, after, targets.length);
 }
 var editTool = defineTool({
@@ -10381,6 +10448,9 @@ function statusMarker(status) {
       return ">";
   }
 }
+function statusColorKey(status) {
+  return status === "error" ? "error" : "text";
+}
 function plainToolText(text) {
   return stripAnsi5(text);
 }
@@ -10422,7 +10492,7 @@ function ToolEventBlock({
   showTitle = true,
   status,
   summary,
-  theme: _theme,
+  theme,
   title
 }) {
   const normalizedSummary = summary?.trim();
@@ -10438,19 +10508,19 @@ function ToolEventBlock({
   const { visibleLines, hiddenLineCount } = clampContentLines(combinedLines, maxContentLines);
   return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", marginBottom, marginLeft: indent, children: [
     showTitle ? /* @__PURE__ */ jsxs(Box, { children: [
-      /* @__PURE__ */ jsx(Text, { color: "white", children: plainToolText(`${statusMarker(status)} `) }),
-      /* @__PURE__ */ jsx(Text, { color: "white", children: plainToolText(title) }),
-      showSummaryInline && normalizedSummary ? /* @__PURE__ */ jsx(Text, { color: "white", children: plainToolText(` (${normalizedSummary})`) }) : null
+      /* @__PURE__ */ jsx(Text, { children: theme.color(statusColorKey(status), plainToolText(`${statusMarker(status)} `)) }),
+      /* @__PURE__ */ jsx(Text, { children: theme.color(statusColorKey(status), plainToolText(title)) }),
+      showSummaryInline && normalizedSummary ? /* @__PURE__ */ jsx(Text, { children: theme.muted(plainToolText(` (${normalizedSummary})`)) }) : null
     ] }) : null,
     visibleLines.map((line, index) => /* @__PURE__ */ jsx(
       Box,
       {
         marginLeft: line.kind === "response" ? showTitle ? 2 : 0 : showTitle ? 4 : 2,
-        children: preformatted ? /* @__PURE__ */ jsx(Text, { children: line.text }) : /* @__PURE__ */ jsx(Text, { color: "white", children: plainToolText(line.text) })
+        children: preformatted ? /* @__PURE__ */ jsx(Text, { children: line.text }) : /* @__PURE__ */ jsx(Text, { children: theme.color("text", plainToolText(line.text)) })
       },
       `${line.kind}:${index}:${stripAnsi5(line.text)}`
     )),
-    hiddenLineCount > 0 ? /* @__PURE__ */ jsx(Box, { marginLeft: showTitle ? 4 : 2, children: /* @__PURE__ */ jsx(Text, { color: "white", children: plainToolText(`... ${hiddenLineCount} more line(s)`) }) }) : null
+    hiddenLineCount > 0 ? /* @__PURE__ */ jsx(Box, { marginLeft: showTitle ? 4 : 2, children: /* @__PURE__ */ jsx(Text, { children: theme.muted(plainToolText(`... ${hiddenLineCount} more line(s)`)) }) }) : null
   ] });
 }
 
@@ -10793,20 +10863,20 @@ function MessageList({
 }
 
 // src/react-ink/components/StatusLine.tsx
-function StatusLine({ snapshot, status, theme }) {
+function StatusLine({ snapshot, status, theme, showBusyText = true }) {
   let text = status?.text;
   let tone = status?.kind ?? "info";
   if (!text) {
-    if (snapshot.isCompacting) {
+    if (showBusyText && snapshot.isCompacting) {
       text = "Compacting conversation context...";
       tone = "busy";
-    } else if (snapshot.isBashRunning) {
+    } else if (showBusyText && snapshot.isBashRunning) {
       text = "Running bash command...";
       tone = "busy";
-    } else if (snapshot.pendingToolCallCount > 0 || snapshot.pendingMessageCount > 0) {
+    } else if (showBusyText && (snapshot.pendingToolCallCount > 0 || snapshot.pendingMessageCount > 0)) {
       text = "Agent working...";
       tone = "busy";
-    } else if (snapshot.isStreaming) {
+    } else if (showBusyText && snapshot.isStreaming) {
       text = "Agent working...";
       tone = "busy";
     } else if (snapshot.error) {

package/dist/smithy.js

@@ -276,6 +276,7 @@ function getProfile(name) {
 }
 
 // src/capabilities/kernel/spec.ts
+var READ_STATE_HANDLE_KEY = "readState";
 function coerceInput(raw) {
   if (typeof raw === "string") {
     const trimmed = raw.trim();
@@ -729,7 +730,7 @@ var standardBudget = {
 [${omitted} bytes elided to stay within the output ceiling]
 `
 };
-function makeNodeContext(cwd, signal, budget) {
+function makeNodeContext(cwd, signal, budget, framework) {
   if (typeof cwd !== "string" || cwd.length === 0) {
     throw new Error("makeNodeContext requires a non-empty working directory.");
   }
@@ -738,10 +739,60 @@ function makeNodeContext(cwd, signal, budget) {
     fs: nodeFs,
     shell: nodeShell,
     signal: signal ?? neverAborts(),
-    budget: budget ?? standardBudget
+    budget: budget ?? standardBudget,
+    ...framework ? { framework } : {}
   };
 }
 
+// src/capabilities/files/read-state-gate.ts
+var READ_BEFORE_EDIT_MESSAGE = "File has not been read yet. Read it first before writing to it.";
+var MODIFIED_SINCE_READ_MESSAGE = "File has been modified since read, either by the user or by a linter. Read it again before attempting to write it.";
+function getReadStateHandle(ctx) {
+  const bag = ctx.framework;
+  if (!bag || typeof bag !== "object") return void 0;
+  const candidate = bag[READ_STATE_HANDLE_KEY];
+  if (!candidate || typeof candidate !== "object") return void 0;
+  const handle = candidate;
+  if (typeof handle.get !== "function" || typeof handle.set !== "function" || typeof handle.has !== "function") {
+    return void 0;
+  }
+  return handle;
+}
+async function recordReadState(ctx, absPath, handle) {
+  if (!handle) return;
+  try {
+    const info = await ctx.fs.stat(absPath);
+    const record = {
+      mtimeMs: Math.floor(info.modifiedMs),
+      size: info.size,
+      readAt: Date.now()
+    };
+    handle.set(absPath, record);
+  } catch {
+  }
+}
+async function enforceReadGate(ctx, absPath, handle) {
+  if (!handle) return { ok: true };
+  if (!handle.has(absPath)) {
+    return { ok: false, message: READ_BEFORE_EDIT_MESSAGE };
+  }
+  const recorded = handle.get(absPath);
+  if (!recorded) {
+    return { ok: false, message: READ_BEFORE_EDIT_MESSAGE };
+  }
+  let info;
+  try {
+    info = await ctx.fs.stat(absPath);
+  } catch {
+    return { ok: true };
+  }
+  const currentMtime = Math.floor(info.modifiedMs);
+  if (currentMtime > recorded.mtimeMs || info.size !== recorded.size) {
+    return { ok: false, message: MODIFIED_SINCE_READ_MESSAGE };
+  }
+  return { ok: true };
+}
+
 // src/capabilities/files/read.ts
 var GUTTER_WIDTH = 6;
 var DESCRIPTION = [
@@ -844,6 +895,7 @@ var readTool = defineTool({
       const detail = err instanceof Error ? err.message : String(err);
       return failure(`Could not read ${path}: ${detail}`);
     }
+    await recordReadState(ctx, path, getReadStateHandle(ctx));
     const allLines = toLines(text);
     const totalLines = allLines.length;
     if (totalLines === 0) {
@@ -951,11 +1003,19 @@ var writeTool = defineTool({
   async run(input, ctx) {
     const path = readPath(input?.path);
     const content = readContent(input?.content);
+    const handle = getReadStateHandle(ctx);
+    if (handle && await ctx.fs.exists(path)) {
+      const gate = await enforceReadGate(ctx, path, handle);
+      if (!gate.ok) {
+        return asText(gate.message, true);
+      }
+    }
     const folder = parentDir(path);
     if (folder.length > 0) {
       await ctx.fs.mkdir(folder, { recursive: true });
     }
     await ctx.fs.writeFile(path, content, "utf8");
+    await recordReadState(ctx, path, handle);
     const bytes = Buffer.byteLength(content, "utf8");
     const unit = bytes === 1 ? "byte" : "bytes";
     return asText(`Saved ${bytes} ${unit} to ${path}.`);
@@ -1245,6 +1305,11 @@ async function runEdit(input, ctx) {
   if (!info.isFile) {
     return failure2(`${path} is not a regular file, so it cannot be edited.`);
   }
+  const handle = getReadStateHandle(ctx);
+  const gate = await enforceReadGate(ctx, path, handle);
+  if (!gate.ok) {
+    return failure2(gate.message);
+  }
   const before = await ctx.fs.readFile(path, "utf8");
   const literalHits = countLiteral(before, oldText);
   if (literalHits > 0) {
@@ -1258,6 +1323,7 @@ async function runEdit(input, ctx) {
       return failure2(`The replacement left ${path} unchanged.`);
     }
     await ctx.fs.writeFile(path, after2, "utf8");
+    await recordReadState(ctx, path, handle);
     return success(path, before, after2, replaceAll ? literalHits : 1);
   }
   const spans = findFuzzySpans(before, oldText);
@@ -1281,6 +1347,7 @@ async function runEdit(input, ctx) {
     return failure2(`The fuzzy replacement left ${path} unchanged.`);
   }
   await ctx.fs.writeFile(path, after, "utf8");
+  await recordReadState(ctx, path, handle);
   return success(path, before, after, targets.length);
 }
 var editTool = defineTool({

package/dist/swarm.js

@@ -4383,6 +4383,7 @@ function runErrorThrowable(kind, message) {
 }
 
 // src/capabilities/kernel/spec.ts
+var READ_STATE_HANDLE_KEY = "readState";
 function coerceInput(raw) {
   if (typeof raw === "string") {
     const trimmed = raw.trim();
@@ -4836,7 +4837,7 @@ var standardBudget = {
 [${omitted} bytes elided to stay within the output ceiling]
 `
 };
-function makeNodeContext(cwd, signal, budget) {
+function makeNodeContext(cwd, signal, budget, framework) {
   if (typeof cwd !== "string" || cwd.length === 0) {
     throw new Error("makeNodeContext requires a non-empty working directory.");
   }
@@ -4845,10 +4846,60 @@ function makeNodeContext(cwd, signal, budget) {
     fs: nodeFs,
     shell: nodeShell,
     signal: signal ?? neverAborts(),
-    budget: budget ?? standardBudget
+    budget: budget ?? standardBudget,
+    ...framework ? { framework } : {}
   };
 }
 
+// src/capabilities/files/read-state-gate.ts
+var READ_BEFORE_EDIT_MESSAGE = "File has not been read yet. Read it first before writing to it.";
+var MODIFIED_SINCE_READ_MESSAGE = "File has been modified since read, either by the user or by a linter. Read it again before attempting to write it.";
+function getReadStateHandle(ctx) {
+  const bag = ctx.framework;
+  if (!bag || typeof bag !== "object") return void 0;
+  const candidate = bag[READ_STATE_HANDLE_KEY];
+  if (!candidate || typeof candidate !== "object") return void 0;
+  const handle = candidate;
+  if (typeof handle.get !== "function" || typeof handle.set !== "function" || typeof handle.has !== "function") {
+    return void 0;
+  }
+  return handle;
+}
+async function recordReadState(ctx, absPath, handle) {
+  if (!handle) return;
+  try {
+    const info = await ctx.fs.stat(absPath);
+    const record = {
+      mtimeMs: Math.floor(info.modifiedMs),
+      size: info.size,
+      readAt: Date.now()
+    };
+    handle.set(absPath, record);
+  } catch {
+  }
+}
+async function enforceReadGate(ctx, absPath, handle) {
+  if (!handle) return { ok: true };
+  if (!handle.has(absPath)) {
+    return { ok: false, message: READ_BEFORE_EDIT_MESSAGE };
+  }
+  const recorded = handle.get(absPath);
+  if (!recorded) {
+    return { ok: false, message: READ_BEFORE_EDIT_MESSAGE };
+  }
+  let info;
+  try {
+    info = await ctx.fs.stat(absPath);
+  } catch {
+    return { ok: true };
+  }
+  const currentMtime = Math.floor(info.modifiedMs);
+  if (currentMtime > recorded.mtimeMs || info.size !== recorded.size) {
+    return { ok: false, message: MODIFIED_SINCE_READ_MESSAGE };
+  }
+  return { ok: true };
+}
+
 // src/capabilities/files/read.ts
 var GUTTER_WIDTH = 6;
 var DESCRIPTION = [
@@ -4951,6 +5002,7 @@ var readTool = defineTool({
       const detail = err instanceof Error ? err.message : String(err);
       return failure(`Could not read ${path}: ${detail}`);
     }
+    await recordReadState(ctx, path, getReadStateHandle(ctx));
     const allLines = toLines(text);
     const totalLines = allLines.length;
     if (totalLines === 0) {
@@ -5058,11 +5110,19 @@ var writeTool = defineTool({
   async run(input, ctx) {
     const path = readPath(input?.path);
     const content = readContent(input?.content);
+    const handle = getReadStateHandle(ctx);
+    if (handle && await ctx.fs.exists(path)) {
+      const gate = await enforceReadGate(ctx, path, handle);
+      if (!gate.ok) {
+        return asText(gate.message, true);
+      }
+    }
     const folder = parentDir(path);
     if (folder.length > 0) {
       await ctx.fs.mkdir(folder, { recursive: true });
     }
     await ctx.fs.writeFile(path, content, "utf8");
+    await recordReadState(ctx, path, handle);
     const bytes = Buffer.byteLength(content, "utf8");
     const unit = bytes === 1 ? "byte" : "bytes";
     return asText(`Saved ${bytes} ${unit} to ${path}.`);
@@ -5352,6 +5412,11 @@ async function runEdit(input, ctx) {
   if (!info.isFile) {
     return failure2(`${path} is not a regular file, so it cannot be edited.`);
   }
+  const handle = getReadStateHandle(ctx);
+  const gate = await enforceReadGate(ctx, path, handle);
+  if (!gate.ok) {
+    return failure2(gate.message);
+  }
   const before = await ctx.fs.readFile(path, "utf8");
   const literalHits = countLiteral(before, oldText);
   if (literalHits > 0) {
@@ -5365,6 +5430,7 @@ async function runEdit(input, ctx) {
       return failure2(`The replacement left ${path} unchanged.`);
     }
     await ctx.fs.writeFile(path, after2, "utf8");
+    await recordReadState(ctx, path, handle);
     return success(path, before, after2, replaceAll ? literalHits : 1);
   }
   const spans = findFuzzySpans(before, oldText);
@@ -5388,6 +5454,7 @@ async function runEdit(input, ctx) {
     return failure2(`The fuzzy replacement left ${path} unchanged.`);
   }
   await ctx.fs.writeFile(path, after, "utf8");
+  await recordReadState(ctx, path, handle);
   return success(path, before, after, targets.length);
 }
 var editTool = defineTool({

package/dist/types/capabilities/backends/node-backends.d.ts

@@ -25,4 +25,6 @@ export declare const nodeShell: Shell;
  * required, while the cancellation `signal` and output `budget` fall back to a
  * never-aborting signal and the kernel's standard window when omitted.
  */
-export declare function makeNodeContext(cwd: string, signal?: AbortSignal, budget?: OutputBudget): ToolContext;
+export declare function makeNodeContext(cwd: string, signal?: AbortSignal, budget?: OutputBudget, framework?: {
+    readonly [key: string]: unknown;
+}): ToolContext;

package/dist/types/capabilities/files/read-state-gate.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The read-before-edit gate (shared by `read`, `edit`, and `write`).
+ *
+ * This is the framework half of the read-edit-gate feature. When — and ONLY
+ * when — a host has stashed a {@link ReadStateHandle} on
+ * `ctx.framework[READ_STATE_HANDLE_KEY]`, the file tools enforce a small
+ * discipline borrowed from interactive coding agents:
+ *
+ *   1. A file may not be edited or overwritten until it has been *read* in this
+ *      session (so the model is never blindly clobbering content it has not
+ *      seen).
+ *   2. A file may not be mutated if it has drifted on disk since that read — its
+ *      modification time or byte size advanced past what was recorded — because
+ *      that usually means a human or a linter changed it underneath us.
+ *
+ * After every successful read (and every successful mutation) the recorded state
+ * is refreshed from the fresh on-disk stat, so the next gate check compares
+ * against the latest known-good snapshot.
+ *
+ * The whole mechanism is *additive*: with no handle present, every helper here
+ * is a no-op and the tools behave exactly as they did before. Nothing imports
+ * from the product — the handle is duck-typed and the key is a shared string
+ * literal, so the framework consumer and the product injector agree on shape
+ * without a cross-package type import.
+ */
+import type { ReadStateHandle, ToolContext } from "../kernel";
+/** The two byte-stable refusal messages the gate emits. */
+export declare const READ_BEFORE_EDIT_MESSAGE = "File has not been read yet. Read it first before writing to it.";
+export declare const MODIFIED_SINCE_READ_MESSAGE = "File has been modified since read, either by the user or by a linter. Read it again before attempting to write it.";
+/**
+ * Pull the read-state handle off the context, if one was injected.
+ *
+ * Returns `undefined` whenever the framework bag, the key, or a well-formed
+ * handle is absent — the gate then degrades to a no-op. The handle is validated
+ * structurally (it must expose `get` / `set` / `has`) so a malformed injection
+ * can never throw mid-mutation; it simply disables the gate.
+ */
+export declare function getReadStateHandle(ctx: ToolContext): ReadStateHandle | undefined;
+/**
+ * Record (or refresh) the read state for `absPath` from a fresh stat.
+ *
+ * No-op when no handle is present. Stats are taken through the kernel `fs` seam
+ * — its `modifiedMs` field is floored to a whole millisecond so a sub-ms clock
+ * skew between read and a later compare can never spuriously trip the staleness
+ * check. A failed stat is swallowed: state-keeping is best-effort and must never
+ * mask the real operation's outcome.
+ */
+export declare function recordReadState(ctx: ToolContext, absPath: string, handle: ReadStateHandle | undefined): Promise<void>;
+/** Outcome of a gate check: either cleared, or refused with a message. */
+export type GateOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Enforce the read-before-edit + staleness gate ahead of a mutation.
+ *
+ * With no handle present this always clears (the gate is opt-in). With a handle:
+ *   - refuse when `absPath` has no recorded read this session;
+ *   - refuse when the on-disk modification time or byte size has advanced past
+ *     the recorded read.
+ *
+ * The on-disk stat is read through the kernel `fs` seam and floored the same way
+ * the recorded mtime is, so the comparison is apples-to-apples. A stat failure
+ * (e.g. the file vanished) clears the gate so the underlying tool can surface
+ * its own, more specific error.
+ */
+export declare function enforceReadGate(ctx: ToolContext, absPath: string, handle: ReadStateHandle | undefined): Promise<GateOutcome>;

package/dist/types/capabilities/files/read-state-gate.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Tests for the read-before-edit gate (framework half of read-edit-gate).
+ *
+ * The gate is opt-in: it activates only when a host injects a {@link ReadStateHandle}
+ * on `ctx.framework[READ_STATE_HANDLE_KEY]`. These cases exercise both worlds —
+ * the gate ACTIVE (handle present) and the gate ABSENT (no handle, today's
+ * behavior) — across the three file tools (`read`, `edit`, `write`).
+ *
+ * Everything runs against a real on-disk sandbox via the genuine
+ * {@link makeNodeContext}, so the tools take their real filesystem path. The
+ * injected store is a tiny in-memory Map, mirroring what the product host will
+ * supply through the shared string-literal handle key.
+ */
+export {};

package/dist/types/capabilities/kernel/context.d.ts

@@ -28,6 +28,10 @@ export interface ContextOverrides {
     readonly shell?: Shell;
     readonly signal?: AbortSignal;
     readonly budget?: OutputBudget;
+    /** Optional open bag of host-injected framework handles (e.g. the read-state store). */
+    readonly framework?: {
+        readonly [key: string]: unknown;
+    };
 }
 /**
  * Build a {@link ToolContext}, defaulting every field the caller omits.

package/dist/types/capabilities/kernel/index.d.ts

@@ -13,8 +13,8 @@
  * re-exported here; consumers import those straight from "../../runtime/contract"
  * and "../../llmgateway/contract" so there is a single source of truth.
  */
-export { defineTool } from "./spec";
-export type { ToolSpec, ToolResult, ToolContentBlock, TextContentBlock, JsonContentBlock, ToolContext, DefinedTool, } from "./spec";
+export { defineTool, READ_STATE_HANDLE_KEY } from "./spec";
+export type { ToolSpec, ToolResult, ToolContentBlock, TextContentBlock, JsonContentBlock, ToolContext, DefinedTool, ReadStateHandle, ReadStateRecord, } from "./spec";
 export type { Fs, FsEntryInfo, DirChild, RemoveOptions, Shell, ShellLaunchOptions, ShellExecOptions, ShellExecResult, ShellHandle, } from "./backends";
 export { clamp } from "./output";
 export type { OutputBudget, ClipEnd } from "./output";