@tea-agent/loop-agent 0.39.0-beta.7 → 0.39.0-beta.9

package/dist/executors/dag-pi-executor.js

@@ -8,6 +8,7 @@ import { routeFrontendProviderCapability } from "../workflows/dag/frontend-provi
 import { executePiStep, resolvePiBackend, } from "./pi-executor.js";
 import { resolveDagPiExtensions, } from "./pi-extension-resolver.js";
 import { buildPiWriterToolPolicyContext, createPiWriterCustomTools, } from "./pi-writer-tool-policy.js";
+import { createPiReadBudgetCustomTools, } from "./pi-read-budget-policy.js";
 import { cleanupPlaywrightCliDefaultSession, createPlaywrightCliTool, PI_COMMAND_CAPABILITY_REGISTRY, resolveCaseIdFromWriteSet, resolveEvidenceDirFromWriteSet, } from "./pi-playwright-cli-tool.js";
 import { dagCommandPolicyAllows, resolveDagCommandPolicy, } from "../workflows/dag/types.js";
 import { redactPromptForLog, truncateOutput, } from "../shared/output-truncation.js";
@@ -338,6 +339,90 @@ export function scanReviewTerminalKindsFromSessionEvents(content) {
  * the plan re-read upstream outputs/sources instead of trusting typed facts,
  * which blows up the context window (400 request-too-large). */
 const PLAN_READ_TOOL_BUDGET = 40;
+const READ_ONLY_TOOL_NAMES = new Set(["read", "grep", "ls", "find"]);
+function readEventPath(event) {
+    const candidates = [event.path, event.readPath, event.input];
+    for (const value of candidates) {
+        if (typeof value === "string")
+            return value;
+        if (value && typeof value === "object") {
+            const nested = value;
+            for (const key of ["path", "readPath", "file"]) {
+                if (typeof nested[key] === "string")
+                    return nested[key];
+            }
+        }
+    }
+    return undefined;
+}
+function eventTimestamp(event) {
+    for (const key of ["timestamp", "timestampMs", "ts", "createdAt"]) {
+        const value = event[key];
+        if (typeof value === "number" && Number.isFinite(value))
+            return value < 10_000_000_000 ? value * 1000 : value;
+        if (typeof value === "string") {
+            const parsed = Date.parse(value);
+            if (Number.isFinite(parsed))
+                return parsed;
+        }
+    }
+    return undefined;
+}
+function eventBytes(event, line) {
+    const result = event.result ?? event.toolResult ?? event.output;
+    if (typeof result === "string")
+        return Buffer.byteLength(result);
+    if (result !== undefined)
+        return Buffer.byteLength(JSON.stringify(result));
+    return Buffer.byteLength(line);
+}
+export async function detectNodeReadBudget(input) {
+    if (!input.budget)
+        return [];
+    const sessionEventsPath = path.join(input.runDir, input.nodeId, "session-events.jsonl");
+    let content;
+    try {
+        content = await readFile(sessionEventsPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const stats = { files: new Set(), bytes: 0, tools: 0 };
+    let firstTs;
+    let lastTs;
+    for (const line of content.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const event = JSON.parse(line);
+            if (event.type !== "tool_execution_start" || typeof event.toolName !== "string" || !READ_ONLY_TOOL_NAMES.has(event.toolName))
+                continue;
+            stats.tools++;
+            const readPath = readEventPath(event);
+            if (readPath)
+                stats.files.add(readPath);
+            stats.bytes += eventBytes(event, line);
+            const ts = eventTimestamp(event);
+            if (ts !== undefined) {
+                firstTs ??= ts;
+                lastTs = ts;
+            }
+        }
+        catch { /* ignore malformed telemetry */ }
+    }
+    if (firstTs !== undefined && lastTs !== undefined)
+        stats.elapsedMs = Math.max(0, lastTs - firstTs);
+    const issues = [];
+    if (stats.files.size > input.budget.maxFiles)
+        issues.push(`frontend ${input.nodeId} read budget exceeded: ${stats.files.size} files (budget ${input.budget.maxFiles})`);
+    if (stats.bytes > input.budget.maxBytes)
+        issues.push(`frontend ${input.nodeId} read budget exceeded: ${stats.bytes} bytes (budget ${input.budget.maxBytes})`);
+    if (input.budget.maxMs !== undefined &&
+        stats.elapsedMs !== undefined &&
+        stats.elapsedMs > input.budget.maxMs)
+        issues.push(`frontend ${input.nodeId} read budget exceeded: ${stats.elapsedMs}ms (budget ${input.budget.maxMs}ms)`);
+    return issues;
+}
 /** Deterministic read-burst guard for frontend-plan-pi: count read-only
  * discovery tool calls (read/grep/ls/find) from the session log. Over budget →
  * read-burst, retried with a reduced-reading instruction. Pure scan; a
@@ -685,6 +770,56 @@ export async function createFrontendDesignTerminalTools(input) {
         },
     };
 }
+/**
+ * Source fidelity ledger (AC-005/AC-006): load the contract node's committed
+ * requirement facts and build a requirement-id → provenance map. The contract
+ * node declared sourceFragmentIds/sourceRefs from the ledger's
+ * requirement→fragment mapping; the plan inherits them by id so the compiled
+ * canonical contract carries authoritative provenance without the plan
+ * re-deriving (or fabricating) it. Best-effort: missing/unreadable contract
+ * ledger yields an empty map and the plan compiles as before (the design
+ * policy shell will then fail closed on missing provenance).
+ */
+async function loadContractRequirementInheritance(runDir) {
+    const { readTypedEventStoreFromJsonl } = await import("../workflows/dag/frontend-typed-event-store.js");
+    let records;
+    try {
+        records = await readTypedEventStoreFromJsonl(path.join(runDir, "frontend-contract-pi", "contract-typed-facts.jsonl"));
+    }
+    catch {
+        return new Map();
+    }
+    const byId = new Map();
+    for (const record of records) {
+        const fact = record.fact;
+        if (!fact || typeof fact !== "object")
+            continue;
+        const recordFact = fact;
+        if (recordFact.origin !== "contract" ||
+            recordFact.kind !== "requirement") {
+            continue;
+        }
+        // Contract requirement facts carry id/sourceFragmentIds/sourceRefs on
+        // the fact itself (origin=contract, kind=requirement, id, text, ...),
+        // not inside an `entry` wrapper.
+        const id = typeof recordFact.id === "string" ? recordFact.id : "";
+        if (!id)
+            continue;
+        const sourceFragmentIds = Array.isArray(recordFact.sourceFragmentIds)
+            ? recordFact.sourceFragmentIds.filter((value) => typeof value === "string")
+            : undefined;
+        const sourceRefs = Array.isArray(recordFact.sourceRefs)
+            ? recordFact.sourceRefs.filter((value) => typeof value === "string")
+            : undefined;
+        if (sourceFragmentIds || sourceRefs) {
+            byId.set(id, {
+                ...(sourceFragmentIds ? { sourceFragmentIds } : {}),
+                ...(sourceRefs ? { sourceRefs } : {}),
+            });
+        }
+    }
+    return byId;
+}
 /**
  * A+B: `frontend-plan-pi` now records its decision ledger through seven
  * incremental `record_*` tools (origin=plan) and closes with exactly one
@@ -725,9 +860,19 @@ export async function createFrontendPlanLedgerTools(input) {
         implementationTargets: optionalStringArray,
         verificationTargetIds: optionalStringArray,
         notApplicableReason: optionalString,
+        // Compatibility is intentionally limited to this model-facing tool
+        // boundary. Canonical contract facts always use notApplicableReason.
+        reason: Type.Optional(Type.String({
+            description: "Legacy/model alias for notApplicableReason. Use notApplicableReason in new calls.",
+        })),
     }, { additionalProperties: false });
     const interactionSchema = Type.Object({
-        name: Type.String({}),
+        name: optionalString,
+        // Compatibility is intentionally limited to this model-facing tool
+        // boundary. Canonical contract facts always use name.
+        id: Type.Optional(Type.String({
+            description: "Legacy/model alias for name. Use name in new calls.",
+        })),
         trigger: Type.String({}),
         expectedBehavior: Type.String({}),
         implementationTargets: stringArray,
@@ -764,7 +909,9 @@ export async function createFrontendPlanLedgerTools(input) {
             description: "Optional. Real exported identifier or describe/it title in the target file. Omit it to keep the call small — the trace gate then only verifies the file exists and the command ran. Forbidden for type=static (runtime strips it).",
         })),
         requirementIds: stringArray,
-        uiStates: stringArray,
+        uiStates: Type.Optional(Type.Array(Type.String({}), {
+            description: "Optional only at this tool boundary. An omitted value is deterministically recorded as []. Pass an explicit array for new calls.",
+        })),
     }, { additionalProperties: false });
     const evidenceGapSchema = Type.Object({
         requirementId: optionalString,
@@ -791,6 +938,9 @@ export async function createFrontendPlanLedgerTools(input) {
     const stringList = (value) => Array.isArray(value)
         ? value.filter((item) => typeof item === "string")
         : [];
+    const nonEmptyString = (value) => typeof value === "string" && value.trim().length > 0
+        ? value.trim()
+        : undefined;
     const planToolReceipt = (details) => ({
         content: [
             {
@@ -863,7 +1013,7 @@ export async function createFrontendPlanLedgerTools(input) {
     const recordComponentChoiceTool = defineTool({
         name: "record_component_choice",
         label: "record_component_choice",
-        description: "Record ONE component choice (origin=plan component-choice fact). Only declare components you add or replace; reuse of existing components needs no entry. Omit rationale for reuse-existing; it is optional. Call once per component — one tool call per message. Optionally include stylingStrategy (set it once, on the first call).",
+        description: "Record ONE component choice (origin=plan component-choice fact). Declare every UI purpose's component selection. A component the task source/PRD mandates adding (not present in the repo) MUST be decision=new with a specReference pointing at the PRD section that defines it; decision=reuse-existing is only for components that already exist in the repo (e.g. reusing ActiveRunBadge's styling convention). Omit rationale for reuse-existing; it is optional. Call once per component — one tool call per message. Optionally include stylingStrategy (set it once, on the first call).",
         promptSnippet: "Record one component choice (one tool call per message).",
         parameters: Type.Object({
             choice: uiComponentChoiceSchema,
@@ -902,10 +1052,79 @@ export async function createFrontendPlanLedgerTools(input) {
             interactions: Type.Array(interactionSchema),
         }, { additionalProperties: false }),
         async execute(_toolCallId, params) {
-            const uiStates = Array.isArray(params?.uiStates) ? params.uiStates : [];
-            const interactions = Array.isArray(params?.interactions)
+            const rawUiStates = Array.isArray(params?.uiStates)
+                ? params.uiStates
+                : [];
+            const rawInteractions = Array.isArray(params?.interactions)
                 ? params.interactions
                 : [];
+            const uiStates = [];
+            for (const rawState of rawUiStates) {
+                if (!isRecordObject(rawState)) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "state-flow",
+                        error: "record_state_flow uiStates entries must be objects",
+                    });
+                }
+                const { reason, notApplicableReason, ...state } = rawState;
+                const canonicalReason = nonEmptyString(notApplicableReason);
+                const aliasReason = nonEmptyString(reason);
+                if (canonicalReason !== undefined &&
+                    aliasReason !== undefined &&
+                    canonicalReason !== aliasReason) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "state-flow",
+                        error: "record_state_flow uiState has conflicting reason and notApplicableReason values",
+                    });
+                }
+                const resolvedReason = canonicalReason ?? aliasReason;
+                if (state.applicable === false && !resolvedReason) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "state-flow",
+                        error: "record_state_flow requires non-empty notApplicableReason when uiState.applicable is false",
+                    });
+                }
+                uiStates.push({
+                    ...state,
+                    ...(resolvedReason
+                        ? { notApplicableReason: resolvedReason }
+                        : {}),
+                });
+            }
+            const interactions = [];
+            for (const rawInteraction of rawInteractions) {
+                if (!isRecordObject(rawInteraction)) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "state-flow",
+                        error: "record_state_flow interactions entries must be objects",
+                    });
+                }
+                const { id, name, ...interaction } = rawInteraction;
+                const canonicalName = nonEmptyString(name);
+                const aliasName = nonEmptyString(id);
+                if (canonicalName !== undefined &&
+                    aliasName !== undefined &&
+                    canonicalName !== aliasName) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "state-flow",
+                        error: "record_state_flow interaction has conflicting id and name values",
+                    });
+                }
+                const resolvedName = canonicalName ?? aliasName;
+                if (!resolvedName) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "state-flow",
+                        error: "record_state_flow requires non-empty interaction.name (id is accepted only as a legacy alias)",
+                    });
+                }
+                interactions.push({ ...interaction, name: resolvedName });
+            }
             const states = uiStates
                 .map((state) => (typeof state?.name === "string" ? state.name : ""))
                 .filter(Boolean);
@@ -993,7 +1212,7 @@ export async function createFrontendPlanLedgerTools(input) {
     const recordPlanRequirementTool = defineTool({
         name: "record_plan_requirement",
         label: "record_plan_requirement",
-        description: "Commit one plan requirement entry (origin=plan plan-requirement fact). Call once per requirement; entry carries id, implementationTargets, verificationTargetIds, and optional expectedOutcome (omit it — the runtime derives the outcome text from the contract requirement). IMPORTANT: call this tool exactly ONE time per assistant message — never batch multiple record_* calls together in one message; emit one call, wait for its result, then call the next.",
+        description: "Commit one plan requirement entry (origin=plan plan-requirement fact). Call once per requirement; entry carries id, implementationTargets, verificationTargetIds, and optional expectedOutcome (omit it — the runtime derives the outcome text from the contract requirement). Each requirement id must be recorded EXACTLY once — re-recording the same id is rejected as a duplicate and would compile a duplicated requirements[] entry. IMPORTANT: call this tool exactly ONE time per assistant message — never batch multiple record_* calls together in one message; emit one call, wait for its result, then call the next.",
         promptSnippet: "Commit one plan requirement entry (one tool call per message).",
         parameters: Type.Object({
             entry: requirementSchema,
@@ -1008,6 +1227,28 @@ export async function createFrontendPlanLedgerTools(input) {
                 });
             }
             const entry = rawEntry;
+            // A requirement id is a canonical identity: recording it twice would
+            // compile a duplicate requirements[] entry and fail design review.
+            // Reject duplicates at the tool boundary so the model can fix them
+            // in-node instead of burning the attempt on a later validation error.
+            const id = typeof entry.id === "string" ? entry.id : "";
+            if (id) {
+                const existing = readCommittedEvents(store, attemptId).find((event) => {
+                    const fact = event.fact;
+                    if (!fact || fact.kind !== "plan-requirement")
+                        return false;
+                    const entryFact = fact.entry;
+                    return (typeof entryFact?.id === "string" &&
+                        entryFact.id === id);
+                });
+                if (existing) {
+                    return planToolReceipt({
+                        ok: false,
+                        kind: "plan-requirement",
+                        error: `record_plan_requirement duplicate: requirement ${id} is already recorded; do not record the same requirement id twice`,
+                    });
+                }
+            }
             const result = await adoptPlanFact("plan-requirement", `${attemptId}:record_plan_requirement:${randomUUID()}`, { kind: "plan-requirement", origin: "plan", entry });
             return planToolReceipt(result);
         },
@@ -1029,7 +1270,13 @@ export async function createFrontendPlanLedgerTools(input) {
                     error: "record_plan_verification_target requires a non-empty entry object",
                 });
             }
-            const entry = rawEntry;
+            // uiStates: [] means this verification target is intentionally not
+            // bound to a named UI state. Keep that canonical representation even
+            // when a model omits the optional tool-boundary field.
+            const entry = {
+                ...rawEntry,
+                uiStates: stringList(rawEntry.uiStates),
+            };
             const result = await adoptPlanFact("plan-verification-target", `${attemptId}:record_plan_verification_target:${randomUUID()}`, { kind: "plan-verification-target", origin: "plan", entry });
             return planToolReceipt(result);
         },
@@ -1068,7 +1315,13 @@ export async function createFrontendPlanLedgerTools(input) {
         async execute(_toolCallId, params) {
             try {
                 const committed = readCommittedEvents(store, attemptId);
-                const fragment = assemblePlanPatchFromCommittedFacts(committed) ?? {};
+                // Source fidelity ledger (AC-005/AC-006): inherit the contract
+                // node's declared requirement→fragment provenance so the compiled
+                // canonical contract carries sourceFragmentIds/sourceRefs even
+                // when the plan did not re-declare them. The contract node is the
+                // sole synthesis point; the plan inherits by requirement id.
+                const contractInheritance = await loadContractRequirementInheritance(input.runDir);
+                const fragment = assemblePlanPatchFromCommittedFacts(committed, contractInheritance) ?? {};
                 const patch = {
                     ...fragment,
                     ...(params?.residualRisks
@@ -1783,6 +2036,11 @@ const DEFAULT_DAG_PI_WRITE_GUARD_DEPENDENCIES = {
  * blocks the node.
  */
 async function runFrontendReviewTerminalShadow(input) {
+    // A provider/executor failure (in particular context-overflow) is already
+    // authoritative. Do not rewrite it to review-terminal-missing merely
+    // because no terminal tool could be submitted after the failed call.
+    if (!input.mapped.ok)
+        return input.mapped;
     const { compareTypedReviewToLegacyJsonVerdict } = await import("../workflows/dag/frontend-review-context.js");
     const { parseJsonReviewVerdict } = await import("../workflows/dag/output-protocol.js");
     const sessionEventsPath = path.join(input.meta.runDir, input.task.id, "session-events.jsonl");
@@ -1863,6 +2121,10 @@ async function runFrontendReviewTerminalShadow(input) {
  * `design-typed-facts.jsonl` as the only authoritative verdict.
  */
 async function runFrontendDesignTerminalShadow(input) {
+    // See the review counterpart above: a failed provider call cannot be
+    // diagnosed as an omitted terminal tool call.
+    if (!input.mapped.ok)
+        return input.mapped;
     const sessionEventsPath = path.join(input.meta.runDir, input.task.id, "session-events.jsonl");
     let typedKinds = [];
     try {
@@ -1980,6 +2242,7 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
     let planLedgerTools;
     let contractTools;
     let scoutEvidenceTools;
+    let readBudgetTools;
     const commandPolicy = resolveDagCommandPolicy(input.task.commandPolicy);
     const allowsPlaywrightCli = dagCommandPolicyAllows(input.task.commandPolicy, "playwright-cli");
     let playwrightToolContext;
@@ -2177,6 +2440,30 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
             };
         }
     }
+    if (input.task.readBudget) {
+        try {
+            readBudgetTools = await createPiReadBudgetCustomTools({
+                repoRoot: input.cwd,
+                budget: input.task.readBudget,
+            });
+            writerToolPolicy = {
+                requireSdk: true,
+                customTools: [
+                    ...(writerToolPolicy?.customTools ?? []),
+                    ...readBudgetTools.customTools,
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                stdout: "",
+                stderr: `pi read budget policy unavailable before Pi execution: ${error instanceof Error ? error.message : String(error)}`,
+                failureCategory: "tool-policy",
+                durationMs: Date.now() - started,
+            };
+        }
+    }
     let result;
     try {
         // Phase 5 (P1-9): capture the writeSet baseline BEFORE the writer provider
@@ -2294,6 +2581,37 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep, wr
         : input.task.writerOutcomePolicy
             ? WRITER_OUTCOME_PROTOCOL_LINE
             : input.task.firstProtocolLine);
+    // A node-specific budget is enforced for every frontend reader that opts in,
+    // including design/final review. Earlier code only checked contract, scout,
+    // and plan nodes, leaving the two largest review sessions unbounded.
+    const readBudgetIssues = [
+        ...(readBudgetTools?.issues() ?? []),
+        ...(await detectNodeReadBudget({
+            runDir: meta.runDir,
+            nodeId: input.task.id,
+            budget: input.task.readBudget,
+        })),
+    ];
+    if (readBudgetIssues.length > 0) {
+        // Read-budget telemetry is diagnostic only when the provider/executor has
+        // already failed. In particular, keep context-overflow so node-execution
+        // selects its compact retry envelope instead of treating the attempt as a
+        // generic read-burst retry.
+        if (!mapped.ok) {
+            return {
+                ...mapped,
+                stderr: [mapped.stderr, ...readBudgetIssues]
+                    .filter(Boolean)
+                    .join("\n\n"),
+            };
+        }
+        return {
+            ...mapped,
+            ok: false,
+            failureCategory: "read-burst",
+            stderr: [mapped.stderr, ...readBudgetIssues].filter(Boolean).join("\n\n"),
+        };
+    }
     if (isFrontendReviewTypedTerminalNode(input.task)) {
         return await runFrontendReviewTerminalShadow({
             task: input.task,

package/dist/executors/pi-read-budget-policy.js

@@ -0,0 +1,166 @@
+import { access, open, readFile, stat, } from "node:fs/promises";
+class PiReadBudgetGuard {
+    budget;
+    files = new Set();
+    violations = [];
+    bytes = 0;
+    startedAt = Date.now();
+    constructor(budget) {
+        this.budget = budget;
+    }
+    issues() {
+        return [...this.violations];
+    }
+    report(message) {
+        if (!this.violations.includes(message))
+            this.violations.push(message);
+    }
+    assertElapsed() {
+        if (this.budget.maxMs === undefined)
+            return;
+        const elapsedMs = Date.now() - this.startedAt;
+        if (elapsedMs > this.budget.maxMs) {
+            const message = `read budget exhausted: ${elapsedMs}ms (budget ${this.budget.maxMs}ms)`;
+            this.report(message);
+            throw new Error(message);
+        }
+    }
+    reserveFile(absolutePath) {
+        this.assertElapsed();
+        if (this.files.has(absolutePath))
+            return;
+        if (this.files.size >= this.budget.maxFiles) {
+            const message = `read budget exhausted: file ${absolutePath} would exceed ${this.budget.maxFiles} files`;
+            this.report(message);
+            throw new Error(message);
+        }
+        this.files.add(absolutePath);
+    }
+    reserveBytes(bytes) {
+        this.assertElapsed();
+        const remaining = Math.max(0, this.budget.maxBytes - this.bytes);
+        if (remaining === 0) {
+            const message = `read budget exhausted: ${this.bytes} bytes (budget ${this.budget.maxBytes})`;
+            this.report(message);
+            throw new Error(message);
+        }
+        const granted = Math.min(bytes, remaining);
+        this.bytes += granted;
+        if (granted < bytes) {
+            this.report(`read budget truncated: ${bytes} requested bytes at ${this.bytes}/${this.budget.maxBytes} bytes`);
+        }
+        return granted;
+    }
+    async readFile(absolutePath) {
+        this.reserveFile(absolutePath);
+        const metadata = await stat(absolutePath);
+        const granted = this.reserveBytes(metadata.size);
+        if (granted === metadata.size)
+            return await readFile(absolutePath);
+        const handle = await open(absolutePath, "r");
+        try {
+            const buffer = Buffer.allocUnsafe(granted);
+            const { bytesRead } = await handle.read(buffer, 0, granted, 0);
+            return buffer.subarray(0, bytesRead);
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async access(absolutePath) {
+        this.reserveFile(absolutePath);
+        await access(absolutePath);
+    }
+    beforeNonFileRead() {
+        this.assertElapsed();
+    }
+    limitToolResult(result) {
+        if (!result || typeof result !== "object" || !Array.isArray(result.content)) {
+            return result;
+        }
+        const content = result.content.map((item) => {
+            if (!item || item.type !== "text" || typeof item.text !== "string") {
+                this.report("read budget truncated: non-text tool result omitted");
+                return {
+                    type: "text",
+                    text: "[read budget reached: non-text result omitted]",
+                };
+            }
+            const granted = this.reserveBytes(Buffer.byteLength(item.text));
+            return {
+                ...item,
+                text: truncateUtf8(item.text, granted),
+            };
+        });
+        return { ...result, content };
+    }
+}
+function truncateUtf8(text, maxBytes) {
+    if (Buffer.byteLength(text) <= maxBytes)
+        return text;
+    const marker = "\n[read result truncated by node budget]";
+    const markerBytes = Buffer.byteLength(marker);
+    if (maxBytes <= markerBytes)
+        return truncateUtf8Prefix(marker, maxBytes);
+    const contentBudget = maxBytes - markerBytes;
+    return `${truncateUtf8Prefix(text, contentBudget)}${marker}`;
+}
+function truncateUtf8Prefix(text, maxBytes) {
+    let result = "";
+    let bytes = 0;
+    for (const codePoint of text) {
+        const size = Buffer.byteLength(codePoint);
+        if (bytes + size > maxBytes)
+            break;
+        result += codePoint;
+        bytes += size;
+    }
+    return result;
+}
+function wrapTool(definition, guard, consumeResult) {
+    return {
+        ...definition,
+        async execute(...args) {
+            guard.beforeNonFileRead();
+            const result = await definition.execute(...args);
+            return consumeResult ? guard.limitToolResult(result) : result;
+        },
+    };
+}
+/**
+ * Override Pi's built-in read-only tools with SDK definitions that meter the
+ * content before it reaches the model. The read tool caps filesystem bytes at
+ * the operation boundary; grep/find/ls have their returned payload clipped
+ * before the agent receives it. This is SDK-only by design: the CLI backend
+ * cannot inject same-name built-in overrides safely.
+ */
+export async function createPiReadBudgetCustomTools(input) {
+    const sdk = (await import("@earendil-works/pi-coding-agent"));
+    const createReadToolDefinition = sdk.createReadToolDefinition;
+    const createGrepToolDefinition = sdk.createGrepToolDefinition;
+    const createFindToolDefinition = sdk.createFindToolDefinition;
+    const createLsToolDefinition = sdk.createLsToolDefinition;
+    if (typeof createReadToolDefinition !== "function" ||
+        typeof createGrepToolDefinition !== "function" ||
+        typeof createFindToolDefinition !== "function" ||
+        typeof createLsToolDefinition !== "function") {
+        throw new Error("pi read budget policy unavailable: SDK read/grep/find/ls tool factories missing");
+    }
+    const guard = new PiReadBudgetGuard(input.budget);
+    const read = createReadToolDefinition(input.repoRoot, {
+        operations: {
+            readFile: (absolutePath) => guard.readFile(absolutePath),
+            access: (absolutePath) => guard.access(absolutePath),
+        },
+    });
+    const grep = wrapTool(createGrepToolDefinition(input.repoRoot), guard, true);
+    const find = wrapTool(createFindToolDefinition(input.repoRoot), guard, true);
+    const ls = wrapTool(createLsToolDefinition(input.repoRoot), guard, true);
+    if (read.name !== "read" ||
+        grep.name !== "grep" ||
+        find.name !== "find" ||
+        ls.name !== "ls") {
+        throw new Error("pi read budget policy unavailable: SDK tool name mismatch");
+    }
+    return { customTools: [read, grep, find, ls], issues: () => guard.issues() };
+}