maestro-agent-sdk 0.1.0

package/dist/tools/builtin/todo_write.d.ts

@@ -0,0 +1,29 @@
+import type { TodoStore } from "../../state/todos.js";
+import type { ToolHandler } from "../../tools/registry.js";
+/**
+ * `todo_write` builtin — TodoWrite-style task tracking for maestro.
+ *
+ * One tool, snapshot-replace semantics: the model passes the COMPLETE list
+ * it wants in place, and the store reconciles (upsert by id, drop entries
+ * absent from the snapshot, auto-assign ids on new items).
+ *
+ * Claude Code parity:
+ *   - No separate `todo_list`. Read-side surfaces via the per-turn system
+ *     reminder, which renders the current list each turn — no extra
+ *     round-trip + no decision surface for "which tool do I call?".
+ *   - 1-in-progress invariant. The LAST `in_progress` in the incoming
+ *     snapshot wins; earlier in_progress entries are flipped to `pending`
+ *     and the demoted id is reported back so the model knows.
+ *
+ * Side-effecting: every call mutates the store + persists to disk.
+ * `parallelSafe: false` is the right default — running two `todo_write`
+ * calls in parallel would race the snapshot.
+ */
+export interface TodoWriteToolOptions {
+    /** Required. The per-session store. Built by maestroProvider via
+     *  `getTodoStore(sessionId)` so the same instance is shared across
+     *  every tool call in this turn. */
+    store: TodoStore;
+}
+export declare function createTodoWriteTool(opts: TodoWriteToolOptions): ToolHandler;
+//# sourceMappingURL=todo_write.d.ts.map

package/dist/tools/builtin/todo_write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"todo_write.d.ts","sourceRoot":"","sources":["../../../src/tools/builtin/todo_write.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,eAAe,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,oBAAoB;IACnC;;wCAEoC;IACpC,KAAK,EAAE,SAAS,CAAC;CAClB;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,oBAAoB,GAAG,WAAW,CA+E3E"}

package/dist/tools/builtin/todo_write.js

@@ -0,0 +1,96 @@
+export function createTodoWriteTool(opts) {
+    const { store } = opts;
+    return {
+        parallelSafe: false,
+        schema: {
+            name: "todo_write",
+            description: "Write the current task list. Pass the COMPLETE snapshot of what you want the list " +
+                "to look like — entries with an existing `id` are updated, new entries (id omitted) " +
+                "get an auto-assigned id (task-N), and entries absent from the snapshot are dropped. " +
+                "At most one entry may have status `in_progress`; if you mark more than one, the LAST " +
+                "in_progress wins and the others are flipped to `pending`. The current list is " +
+                "surfaced to you in the system reminder each turn — call this whenever a multi-step " +
+                "plan starts, mid-flight when a step finishes, or to add/drop items.",
+            input_schema: {
+                type: "object",
+                properties: {
+                    todos: {
+                        type: "array",
+                        description: "Complete snapshot of the task list. Each item: " +
+                            "{id?: string, content: string, status: 'pending'|'in_progress'|'completed', " +
+                            "activeForm?: string}. Include EVERY task you want to keep — omitting one drops it.",
+                    },
+                },
+                required: ["todos"],
+            },
+        },
+        async execute(input) {
+            const raw = input.todos;
+            if (!Array.isArray(raw)) {
+                return JSON.stringify({
+                    error: "todo_write: 'todos' must be an array",
+                });
+            }
+            const incoming = [];
+            for (let i = 0; i < raw.length; i++) {
+                const item = raw[i];
+                if (!item || typeof item !== "object") {
+                    return JSON.stringify({
+                        error: `todo_write: todos[${i}] must be an object`,
+                    });
+                }
+                const obj = item;
+                const content = obj.content;
+                const status = obj.status;
+                if (typeof content !== "string" || content.length === 0) {
+                    return JSON.stringify({
+                        error: `todo_write: todos[${i}].content must be a non-empty string`,
+                    });
+                }
+                if (status !== "pending" && status !== "in_progress" && status !== "completed") {
+                    return JSON.stringify({
+                        error: `todo_write: todos[${i}].status must be 'pending', 'in_progress', or 'completed'`,
+                    });
+                }
+                const upsert = { content, status };
+                if (typeof obj.id === "string" && obj.id.length > 0)
+                    upsert.id = obj.id;
+                if (typeof obj.activeForm === "string" && obj.activeForm.length > 0) {
+                    upsert.activeForm = obj.activeForm;
+                }
+                incoming.push(upsert);
+            }
+            const result = store.upsert(incoming);
+            const summary = summarize(result.todos);
+            const parts = [
+                `Task list updated (${result.todos.length} item${result.todos.length === 1 ? "" : "s"}).`,
+                summary,
+            ];
+            if (result.demotedId) {
+                parts.push(`Note: more than one item was marked in_progress; '${result.demotedId}' was flipped to pending so only the last in_progress entry stays active.`);
+            }
+            return parts.join("\n\n");
+        },
+    };
+}
+/**
+ * Render a compact ascii summary of the list. Used in the tool result so
+ * the model immediately sees what landed (mirrors how Edit returns a
+ * preview after a successful write).
+ *
+ * Format:
+ *   [✓] task-1  Done thing here
+ *   [→] task-2  In-flight thing
+ *   [ ] task-3  Pending thing
+ */
+function summarize(todos) {
+    if (todos.length === 0)
+        return "(list is empty)";
+    return todos
+        .map((t) => {
+        const mark = t.status === "completed" ? "✓" : t.status === "in_progress" ? "→" : " ";
+        return `[${mark}] ${t.id}  ${t.content}`;
+    })
+        .join("\n");
+}
+//# sourceMappingURL=todo_write.js.map

package/dist/tools/builtin/todo_write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"todo_write.js","sourceRoot":"","sources":["../../../src/tools/builtin/todo_write.ts"],"names":[],"mappings":"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"}

package/dist/tools/builtin/web_fetch.d.ts

@@ -0,0 +1,10 @@
+import type { ToolHandler } from "../../tools/registry.js";
+export declare const webFetchTool: ToolHandler;
+/** Strip HTML to plain text using cheerio. Removes <script>/<style>/<head>/
+ *  <noscript> blocks entirely; then extracts remaining text with full entity
+ *  decoding and comment removal built into cheerio's .text(). Collapses
+ *  whitespace and preserves paragraph breaks — clean prose, no markup noise. */
+export declare function htmlToText(html: string): string;
+export declare const __FETCH_TIMEOUT_MS = 30000;
+export declare const __MAX_RESPONSE_BYTES: number;
+//# sourceMappingURL=web_fetch.d.ts.map

package/dist/tools/builtin/web_fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web_fetch.d.ts","sourceRoot":"","sources":["../../../src/tools/builtin/web_fetch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AA6BpD,eAAO,MAAM,YAAY,EAAE,WAuG1B,CAAC;AAWF;;;gFAGgF;AAChF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAa/C;AAGD,eAAO,MAAM,kBAAkB,QAAmB,CAAC;AACnD,eAAO,MAAM,oBAAoB,QAAqB,CAAC"}

package/dist/tools/builtin/web_fetch.js

@@ -0,0 +1,150 @@
+import * as cheerio from "cheerio";
+/**
+ * WebFetch builtin — claude SDK `WebFetch` tool parity for maestro.
+ *
+ * Claude SDK's WebFetch fetches the URL, converts the body to markdown, then
+ * spins up a sub-model with the user's `prompt` to extract / summarize the
+ * result. We don't have a free sub-model channel here, so the maestro variant
+ * returns the raw text body (stripped of HTML tags) and ignores the prompt —
+ * the parent model can apply its own reasoning to the body, which is the
+ * same end state at one less hop.
+ *
+ * Bounds:
+ *  - URL must start with http:// or https://.
+ *  - 30s timeout via AbortController.
+ *  - 1MB response cap (`MAX_RESPONSE_BYTES`). Anything larger is truncated.
+ *  - Only `text/*` and `application/json` content-types are decoded; binary
+ *    types return a stub message.
+ *  - HTML is parsed with cheerio for robust text extraction (script/style/
+ *    head elements removed, entities decoded, comments ignored).
+ *
+ * Returns the formatted preamble + body on success, or `JSON.stringify({error})`
+ * on every failure mode.
+ */
+const FETCH_TIMEOUT_MS = 30_000;
+const MAX_RESPONSE_BYTES = 1 * 1024 * 1024; // 1MB
+export const webFetchTool = {
+    // HTTP GET against an external URL with no local side effects — multiple
+    // fetches in the same turn can run in parallel.
+    parallelSafe: true,
+    schema: {
+        name: "WebFetch",
+        description: "Fetch a URL and return its text content. Supports text/* and application/json " +
+            "content types only — binary responses (PDF, images) are not decoded. " +
+            "30s timeout, 1MB response cap. The optional 'prompt' field is accepted " +
+            "for claude SDK compatibility but ignored — return value is the raw body.",
+        input_schema: {
+            type: "object",
+            properties: {
+                url: {
+                    type: "string",
+                    description: "Absolute http(s) URL to fetch.",
+                },
+                prompt: {
+                    type: "string",
+                    description: "Ignored — accepted for claude SDK compatibility.",
+                },
+            },
+            required: ["url"],
+        },
+    },
+    async execute(input) {
+        const url = typeof input.url === "string" ? input.url.trim() : "";
+        if (!url) {
+            return JSON.stringify({ error: "WebFetch: missing 'url' argument" });
+        }
+        if (!/^https?:\/\//i.test(url)) {
+            return JSON.stringify({
+                error: `WebFetch: url must start with http:// or https://, got '${url}'`,
+            });
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+        let response;
+        try {
+            response = await fetch(url, { signal: controller.signal });
+        }
+        catch (e) {
+            clearTimeout(timer);
+            const err = e;
+            if (err.name === "AbortError") {
+                return JSON.stringify({
+                    error: `WebFetch: timeout after ${FETCH_TIMEOUT_MS}ms`,
+                    url,
+                });
+            }
+            return JSON.stringify({
+                error: `WebFetch: fetch failed: ${err.message ?? String(e)}`,
+                url,
+            });
+        }
+        clearTimeout(timer);
+        const contentType = (response.headers.get("content-type") ?? "").toLowerCase();
+        if (!response.ok) {
+            const text = await safeText(response);
+            return JSON.stringify({
+                error: `WebFetch: HTTP ${response.status} ${response.statusText}`,
+                url,
+                contentType,
+                body: text.slice(0, 500),
+            });
+        }
+        // Only decode text-ish responses. application/json is a text content type
+        // that browsers serve without `text/` prefix — special-case it.
+        const isTextLike = contentType.startsWith("text/") || contentType.includes("json");
+        if (!isTextLike) {
+            return JSON.stringify({
+                error: `WebFetch: non-text content-type '${contentType}'. Download with bash + Read.`,
+                url,
+                contentType,
+            });
+        }
+        let body = await safeText(response);
+        let truncated = false;
+        if (body.length > MAX_RESPONSE_BYTES) {
+            body = body.slice(0, MAX_RESPONSE_BYTES);
+            truncated = true;
+        }
+        // HTML → text via cheerio: parse the DOM, remove script/style/head/no-
+        // script, then extract text. cheerio handles entity decoding and ignores
+        // comments; the output is clean prose with paragraph breaks preserved.
+        if (contentType.includes("html")) {
+            body = htmlToText(body);
+        }
+        const parts = [];
+        parts.push(`URL: ${url}`);
+        parts.push(`Content-Type: ${contentType}`);
+        parts.push(`Length: ${body.length}${truncated ? " (truncated at 1MB)" : ""}`);
+        parts.push("");
+        parts.push(body);
+        return parts.join("\n");
+    },
+};
+/** Best-effort text decode — never throws. */
+async function safeText(response) {
+    try {
+        return await response.text();
+    }
+    catch {
+        return "";
+    }
+}
+/** Strip HTML to plain text using cheerio. Removes <script>/<style>/<head>/
+ *  <noscript> blocks entirely; then extracts remaining text with full entity
+ *  decoding and comment removal built into cheerio's .text(). Collapses
+ *  whitespace and preserves paragraph breaks — clean prose, no markup noise. */
+export function htmlToText(html) {
+    const $ = cheerio.load(html);
+    // Remove script/style/head/noscript blocks — pure noise for the model.
+    $("script, style, head, noscript").remove();
+    // cheerio's .text() decodes all HTML entities and ignores comments.
+    let out = $.text();
+    // Collapse runs of whitespace to a single space, keep paragraph breaks.
+    out = out.replace(/[ \t]+/g, " ");
+    out = out.replace(/\n\s*\n+/g, "\n\n");
+    return out.trim();
+}
+// Internal exports for tests.
+export const __FETCH_TIMEOUT_MS = FETCH_TIMEOUT_MS;
+export const __MAX_RESPONSE_BYTES = MAX_RESPONSE_BYTES;
+//# sourceMappingURL=web_fetch.js.map

package/dist/tools/builtin/web_fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web_fetch.js","sourceRoot":"","sources":["../../../src/tools/builtin/web_fetch.ts"],"names":[],"mappings":"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"}

package/dist/tools/builtin/write.d.ts

@@ -0,0 +1,35 @@
+import type { FileStateTracker } from "../../tools/file-state.js";
+import type { ToolHandler } from "../../tools/registry.js";
+/**
+ * NOTE: filesystem sandboxing now lives in the `sandbox-fs` PreToolUse hook.
+ * Standalone callers (tests, scripts) without the registry get NO sandbox.
+ */
+/**
+ * Write builtin — claude SDK `Write` tool parity for maestro.
+ *
+ * Mirrors the upstream `Write` tool's name + schema so the model's pretrained
+ * instinct calls our handler with the right shape. Overwrite-on-collision is
+ * the documented claude SDK behavior — no merge, no append. Callers that need
+ * additive writes should use the bash tool with `>>` for now (Phase 5 may add
+ * a separate `Edit` builtin that handles the read-modify-write cycle).
+ *
+ * Path safety: absolute path is enforced. We DO NOT sandbox the write under
+ * the user's workspace dir here — Clawgram's permission system + the agent
+ * loop's abort plumbing are the authoritative guardrails. A stricter check
+ * can land later without breaking the schema (the model only sees the public
+ * fields).
+ */
+export interface WriteToolOptions {
+    /**
+     * Per-session file-state tracker. When provided, Write enforces Read-
+     * before-Write on existing files (same invariant as Edit — the model must
+     * see line-numbered content before overwriting). Write-on-create is always
+     * allowed. After Write, the tracker forgets the recorded state so the next
+     * Edit on the path must Re-read.
+     */
+    tracker?: FileStateTracker;
+}
+export declare function createWriteTool(opts?: WriteToolOptions): ToolHandler;
+/** Backwards-compatible singleton (no tracker). */
+export declare const writeTool: ToolHandler;
+//# sourceMappingURL=write.d.ts.map

package/dist/tools/builtin/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../../src/tools/builtin/write.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;GAGG;AAEH;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B;AAED,wBAAgB,eAAe,CAAC,IAAI,GAAE,gBAAqB,GAAG,WAAW,CAkExE;AAED,mDAAmD;AACnD,eAAO,MAAM,SAAS,EAAE,WAA+B,CAAC"}

package/dist/tools/builtin/write.js

@@ -0,0 +1,70 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute } from "node:path";
+export function createWriteTool(opts = {}) {
+    const { tracker } = opts;
+    return {
+        schema: {
+            name: "Write",
+            description: "Write content to a file (overwrite). Parent directories are created " +
+                "automatically. file_path must be absolute. Use this for new files or " +
+                "complete rewrites; for additive output use the bash tool with `>>`.",
+            input_schema: {
+                type: "object",
+                properties: {
+                    file_path: {
+                        type: "string",
+                        description: "Absolute path to the file to write. Parent dirs auto-created.",
+                    },
+                    content: {
+                        type: "string",
+                        description: "Full file content. Overwrites any existing file.",
+                    },
+                },
+                required: ["file_path", "content"],
+            },
+        },
+        async execute(input) {
+            const filePath = typeof input.file_path === "string" ? input.file_path : "";
+            if (!filePath) {
+                return JSON.stringify({ error: "Write: missing 'file_path' argument" });
+            }
+            if (!isAbsolute(filePath)) {
+                return JSON.stringify({
+                    error: `Write: file_path must be absolute, got '${filePath}'`,
+                });
+            }
+            // gate: Read-before-Write — when the file already exists the model
+            // must have read it first (line-numbered view) to avoid blind overwrites.
+            if (tracker) {
+                const gateErr = tracker.checkBeforeMutate(filePath, "Write");
+                if (gateErr)
+                    return JSON.stringify({ error: gateErr });
+            }
+            // `content` is allowed to be the empty string (legit way to truncate a
+            // file), so we accept any string but reject non-strings outright.
+            if (typeof input.content !== "string") {
+                return JSON.stringify({
+                    error: `Write: 'content' must be a string, got ${typeof input.content}`,
+                });
+            }
+            const content = input.content;
+            try {
+                mkdirSync(dirname(filePath), { recursive: true });
+                writeFileSync(filePath, content, "utf-8");
+            }
+            catch (e) {
+                return JSON.stringify({
+                    error: `Write: failed: ${e instanceof Error ? e.message : String(e)}`,
+                });
+            }
+            // Forget any prior Read state — the file just changed under us. Next
+            // Edit must Re-read to refresh the line-numbered view.
+            tracker?.forget(filePath);
+            const bytes = Buffer.byteLength(content, "utf-8");
+            return `File written: ${filePath} (${bytes} bytes)`;
+        },
+    };
+}
+/** Backwards-compatible singleton (no tracker). */
+export const writeTool = createWriteTool();
+//# sourceMappingURL=write.js.map

package/dist/tools/builtin/write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../../../src/tools/builtin/write.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAoChD,MAAM,UAAU,eAAe,CAAC,OAAyB,EAAE;IACzD,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACzB,OAAO;QACL,MAAM,EAAE;YACN,IAAI,EAAE,OAAO;YACb,WAAW,EACT,sEAAsE;gBACtE,uEAAuE;gBACvE,qEAAqE;YACvE,YAAY,EAAE;gBACZ,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,SAAS,EAAE;wBACT,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,+DAA+D;qBAC7E;oBACD,OAAO,EAAE;wBACP,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,kDAAkD;qBAChE;iBACF;gBACD,QAAQ,EAAE,CAAC,WAAW,EAAE,SAAS,CAAC;aACnC;SACF;QACD,KAAK,CAAC,OAAO,CAAC,KAAK;YACjB,MAAM,QAAQ,GAAG,OAAO,KAAK,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5E,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,qCAAqC,EAAE,CAAC,CAAC;YAC1E,CAAC;YACD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC1B,OAAO,IAAI,CAAC,SAAS,CAAC;oBACpB,KAAK,EAAE,2CAA2C,QAAQ,GAAG;iBAC9D,CAAC,CAAC;YACL,CAAC;YACD,mEAAmE;YACnE,0EAA0E;YAC1E,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,OAAO,GAAG,OAAO,CAAC,iBAAiB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;gBAC7D,IAAI,OAAO;oBAAE,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;YACzD,CAAC;YACD,uEAAuE;YACvE,kEAAkE;YAClE,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;gBACtC,OAAO,IAAI,CAAC,SAAS,CAAC;oBACpB,KAAK,EAAE,0CAA0C,OAAO,KAAK,CAAC,OAAO,EAAE;iBACxE,CAAC,CAAC;YACL,CAAC;YACD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;YAE9B,IAAI,CAAC;gBACH,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;gBAClD,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;YAC5C,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,OAAO,IAAI,CAAC,SAAS,CAAC;oBACpB,KAAK,EAAE,kBAAkB,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE;iBACtE,CAAC,CAAC;YACL,CAAC;YAED,qEAAqE;YACrE,uDAAuD;YACvD,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;YAE1B,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAClD,OAAO,iBAAiB,QAAQ,KAAK,KAAK,SAAS,CAAC;QACtD,CAAC;KACF,CAAC;AACJ,CAAC;AAED,mDAAmD;AACnD,MAAM,CAAC,MAAM,SAAS,GAAgB,eAAe,EAAE,CAAC"}

package/dist/tools/file-state.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Per-session file-state tracker for Read-before-Edit enforcement.
+ *
+ * Claude Code's Edit refuses to touch a path that hasn't been Read in the
+ * same session. The invariant cuts two failure modes the model otherwise
+ * runs into:
+ *
+ *   1. Blind edits — the model guesses an `old_string` it never saw and
+ *      either fails the match or replaces the wrong region.
+ *   2. Race-on-edit — a path was Read N turns ago, an external process (or
+ *      another session) mutated it since, and the model's stale `old_string`
+ *      lands but corrupts the actual current contents.
+ *
+ * Maestro lacked this gate; this module is the smallest implementation that
+ * closes both. Each session gets its own tracker (keyed by maestro sessionId
+ * in `sessions` below) so two users / two topics don't share file state.
+ *
+ * Recorded fields per path:
+ *   - mtime  — mtimeMs at the time of Read. Drift detection compares this
+ *              against the live stat at Edit/Write time.
+ *   - size   — secondary drift signal. mtime can stay the same when content
+ *              is rewritten within the same millisecond (rare but real on
+ *              fast filesystems); size is a cheap belt-and-suspenders.
+ *   - readAt — wall clock of the Read. Diagnostic only — surfaced in the
+ *              "stale" error message so users see how old the Read was.
+ *
+ * Cleanup contract: `deleteSession(sessionId)` is called from
+ * `deleteMaestroSession` and (per-session) inside `cleanupStaleMaestroSessions`
+ * so the tracker map can't outlive its sessions. Without that hook, a long-
+ * running bot accumulates one map entry per forgotten session forever.
+ */
+export interface FileStateEntry {
+    /** mtimeMs at the time of Read. */
+    mtime: number;
+    /** size in bytes at the time of Read. */
+    size: number;
+    /** Date.now() when the Read happened. Diagnostic only. */
+    readAt: number;
+}
+/**
+ * One tracker per session — `Map<absPath, FileStateEntry>`.
+ *
+ * Wrapped (instead of a raw Map) so the public surface is explicit: callers
+ * only record and check, they don't iterate or mutate entries directly.
+ */
+export declare class FileStateTracker {
+    private readonly entries;
+    /**
+     * Record a successful Read of `absPath`. Called from Read's execute()
+     * after the file has been stat'd and the contents handed back to the
+     * model. A subsequent Read of the same path overwrites the entry — the
+     * latest Read is what Edit's drift check compares against.
+     */
+    recordRead(absPath: string, mtime: number, size: number): void;
+    /**
+     * Forget the recorded state for `absPath`. Called when Edit / Write
+     * mutates the file so the next Edit must Re-read first (its prior cached
+     * stat is now stale by definition). Also called when a Write creates a
+     * file — the next Edit on the same path must Read it back to confirm
+     * the model's mental model matches what landed on disk.
+     */
+    forget(absPath: string): void;
+    /**
+     * Check whether `absPath` may be Edit/Write'd. Returns null on allow,
+     * or a string error on deny — callers stringify into `{error}` so the
+     * model sees the same shape as sandbox / arg-validation rejections.
+     *
+     * Three reject paths:
+     *   - "no_read": never Read this session. Forces the model to Read first.
+     *   - "stale_mtime": mtime drifted vs recorded — file changed externally.
+     *   - "stale_size": same as above but size changed (covers same-ms writes).
+     *
+     * Allow path: live stat matches recorded mtime AND size.
+     *
+     * One subtlety: if the path doesn't exist, we return null (allow). Write
+     * legitimately creates files, and Edit's "must exist" check runs after
+     * this gate inside the tool — so a missing file in Edit will reject with
+     * "file does not exist, use Write to create". Read-before-Mutate is about
+     * content drift, not existence.
+     */
+    checkBeforeMutate(absPath: string, tool: "Edit" | "Write"): string | null;
+    /** Used by tests + diagnostics. Not part of the per-turn contract. */
+    has(absPath: string): boolean;
+    /** Total number of tracked paths. Diagnostic. */
+    size(): number;
+}
+/** Get or create the tracker for a session. */
+export declare function getFileStateTracker(sessionId: string): FileStateTracker;
+/**
+ * Drop a session's tracker. Called from `deleteMaestroSession` and from
+ * `cleanupStaleMaestroSessions` after the on-disk JSONL is unlinked.
+ * ENOENT-equivalent: deleting a session that was never tracked is a no-op.
+ */
+export declare function dropFileStateTracker(sessionId: string): void;
+/** Test-only. Drops every tracker. */
+export declare function __resetAllTrackers(): void;
+/** Test-only. Snapshot of how many sessions are currently tracked. */
+export declare function __trackerCount(): number;
+//# sourceMappingURL=file-state.d.ts.map

package/dist/tools/file-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-state.d.ts","sourceRoot":"","sources":["../../src/tools/file-state.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,MAAM,WAAW,cAAc;IAC7B,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAE7D;;;;;OAKG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAI9D;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI7B;;;;;;;;;;;;;;;;;OAiBG;IACH,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI;IAiDzE,sEAAsE;IACtE,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI7B,iDAAiD;IACjD,IAAI,IAAI,MAAM;CAGf;AAiBD,+CAA+C;AAC/C,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,CAOvE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAE5D;AAED,sCAAsC;AACtC,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED,sEAAsE;AACtE,wBAAgB,cAAc,IAAI,MAAM,CAEvC"}