@tea-agent/loop-agent 0.39.0-beta.0 → 0.39.0-beta.10

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

@@ -0,0 +1,239 @@
+import { access, open, readFile, stat, } from "node:fs/promises";
+import path from "node:path";
+class PiReadBudgetSoftLimitError extends Error {
+}
+class PiReadAccessDeniedError extends Error {
+}
+class PiReadBudgetGuard {
+    budget;
+    files = new Set();
+    violations = [];
+    bytes = 0;
+    operations = 0;
+    startedAt = Date.now();
+    allowedReadPaths;
+    allowedReadRoots;
+    constructor(budget, readAccess) {
+        this.budget = budget;
+        this.allowedReadPaths = readAccess?.allowedReadPaths
+            ? new Set(readAccess.allowedReadPaths.map((candidate) => path.resolve(candidate)))
+            : undefined;
+        this.allowedReadRoots = (readAccess?.allowedReadRoots ?? []).map((candidate) => path.resolve(candidate));
+    }
+    issues() {
+        return [...this.violations];
+    }
+    report(message) {
+        if (!this.violations.includes(message))
+            this.violations.push(message);
+    }
+    exhaust(message) {
+        if (this.budget.onExhaustion === "return-guidance") {
+            throw new PiReadBudgetSoftLimitError(message);
+        }
+        this.report(message);
+        throw new Error(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.exhaust(message);
+        }
+    }
+    beforeToolOperation() {
+        this.assertElapsed();
+        if (this.budget.maxOperations === undefined)
+            return true;
+        if (this.operations >= this.budget.maxOperations) {
+            const message = `read budget exhausted: operation ${this.operations + 1} would exceed ${this.budget.maxOperations} read-only tool calls`;
+            if (this.budget.onExhaustion === "return-guidance")
+                return false;
+            this.exhaust(message);
+        }
+        this.operations += 1;
+        return true;
+    }
+    operationLimitGuidance() {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "[read limit reached: no repository data was read. Do not call discovery tools again; use injected facts, commit remaining record_* facts, then call finalize_plan exactly once.]",
+                },
+            ],
+        };
+    }
+    readAccessGuidance() {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "[read denied: this node may read only named upstream artifacts or Scout-confirmed paths. Do not explore a new repository path; use committed facts or record an evidence gap, then finish the required terminal protocol.]",
+                },
+            ],
+        };
+    }
+    assertReadablePath(absolutePath) {
+        if (!this.allowedReadPaths)
+            return;
+        const resolved = path.resolve(absolutePath);
+        if (this.allowedReadPaths.has(resolved))
+            return;
+        if (this.allowedReadRoots.some((root) => resolved === root || resolved.startsWith(`${root}${path.sep}`)))
+            return;
+        throw new PiReadAccessDeniedError(`read access denied: ${resolved}`);
+    }
+    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.exhaust(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.exhaust(message);
+        }
+        const granted = Math.min(bytes, remaining);
+        if (granted < bytes && this.budget.onExhaustion === "return-guidance") {
+            this.exhaust(`read budget exhausted: ${bytes} requested bytes would exceed ${this.budget.maxBytes} bytes`);
+        }
+        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.assertReadablePath(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.assertReadablePath(absolutePath);
+        this.reserveFile(absolutePath);
+        await access(absolutePath);
+    }
+    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) {
+            try {
+                if (!guard.beforeToolOperation())
+                    return guard.operationLimitGuidance();
+                const result = await definition.execute(...args);
+                return consumeResult ? guard.limitToolResult(result) : result;
+            }
+            catch (error) {
+                if (error instanceof PiReadBudgetSoftLimitError) {
+                    return guard.operationLimitGuidance();
+                }
+                if (error instanceof PiReadAccessDeniedError) {
+                    return guard.readAccessGuidance();
+                }
+                throw error;
+            }
+        },
+    };
+}
+/**
+ * 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, input.readAccess);
+    const read = wrapTool(createReadToolDefinition(input.repoRoot, {
+        operations: {
+            readFile: (absolutePath) => guard.readFile(absolutePath),
+            access: (absolutePath) => guard.access(absolutePath),
+        },
+    }), guard, false);
+    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() };
+}

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

@@ -1,8 +1,16 @@
 import { appendFile, mkdir } from "node:fs/promises";
 import path from "node:path";
+import { computeExtensionToolAllowlistExtras } from "./pi-extension-resolver.js";
 import { BoundedTextPreview, classifyPiFailure, createPiJsonlStreamCollector, DEFAULT_ABORT_GRACE_MS, DEFAULT_STALL_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, extractPiEventStopReason, extractAssistantTextFromPiJson, } from "./pi-executor.js";
 import { serializeSessionEvent } from "./pi-event-serializer.js";
 import { PI_RECOMMENDED_COMPACTION, PI_RECOMMENDED_RETRY, } from "../shared/pi-retry-settings.js";
+/** Same-session recovery after a transport stall. Exactly one continue per SDK attempt. */
+export const PI_SDK_STALL_CONTINUE_MAX = 1;
+/**
+ * Fixed follow-up sent after aborting a stalled prompt.
+ * Kept short so the model can resume without repeating the original task payload.
+ */
+export const PI_SDK_STALL_CONTINUE_PROMPT = "继续。上一轮因长时间无 provider 活动已被中止；请从中断处接着完成，不要重复已完成的步骤。若此前没有有效输出，请重新执行原任务。";
 let sdkSessionFactoryOverride;
 let sdkImportOverrideForTests;
 let sdkModuleOverrideForTests;
@@ -222,6 +230,9 @@ async function createSdkSession(sdk, input, shared) {
         noContextFiles: true,
         noSkills: true,
         noExtensions: true,
+        ...(input.additionalExtensionPaths && input.additionalExtensionPaths.length > 0
+            ? { additionalExtensionPaths: input.additionalExtensionPaths }
+            : {}),
         ...(settingsManager ? { settingsManager } : {}),
         appendSystemPromptOverride: (base) => [
             ...base,
@@ -229,6 +240,19 @@ async function createSdkSession(sdk, input, shared) {
         ],
     });
     await loader.reload();
+    // Discover extension-registered tool names BEFORE session creation (plan
+    // 2026-08-21 D5): verified against the real SDK — passing extension tool
+    // names in createAgentSession `tools` activates them, while a post-create
+    // setActiveToolsByName pin leaves the active set unchanged. Merge filtered
+    // extras into the create-time allowlist; protected builtins, the deny
+    // surface, and write-capable extension tools never join.
+    const extensionToolExtras = [];
+    if (input.additionalExtensionPaths &&
+        input.additionalExtensionPaths.length > 0) {
+        const registered = collectLoaderExtensionToolNames(loader);
+        extensionToolExtras.push(...computeExtensionToolAllowlistExtras(registered.map((name) => ({ name })), input.toolNames));
+    }
+    const sessionToolNames = [...input.toolNames, ...extensionToolExtras];
     if (input.requireWriterCustomTools) {
         if (!Array.isArray(input.customTools) || input.customTools.length === 0) {
             throw new Error("pi writer tool policy missing customTools; refusing to create uncontrolled writer session");
@@ -238,7 +262,7 @@ async function createSdkSession(sdk, input, shared) {
         cwd: input.cwd,
         sessionManager: SessionManager.inMemory(input.cwd),
         resourceLoader: loader,
-        tools: input.toolNames,
+        tools: sessionToolNames,
         modelRuntime,
         ...(settingsManager ? { settingsManager } : {}),
         ...(model ? { model } : {}),
@@ -247,6 +271,22 @@ async function createSdkSession(sdk, input, shared) {
             ? { customTools: input.customTools }
             : {}),
     });
+    if (extensionToolExtras.length > 0) {
+        // Fail closed when merged extension tools did not activate: a silent
+        // pin failure must never let the node run without its declared tools.
+        const activeTools = created.session.agent?.state?.tools;
+        if (!Array.isArray(activeTools)) {
+            throw new Error("pi SDK session does not expose agent.state.tools; refusing unverifiable extension-tool activation");
+        }
+        const activeNames = new Set(activeTools
+            .map((tool) => typeof tool?.name === "string" ? tool.name : undefined)
+            .filter((name) => Boolean(name)));
+        for (const extensionToolName of extensionToolExtras) {
+            if (!activeNames.has(extensionToolName)) {
+                throw new Error(`pi SDK extension-tool activation mismatch for ${extensionToolName}: tool did not activate at session creation`);
+            }
+        }
+    }
     const customToolNames = (input.customTools ?? [])
         .map((tool) => isRecord(tool) && typeof tool.name === "string" ? tool.name : undefined)
         .filter((name) => Boolean(name));
@@ -259,7 +299,7 @@ async function createSdkSession(sdk, input, shared) {
             .map((tool) => typeof tool?.name === "string" ? tool.name : undefined)
             .filter((name) => Boolean(name)));
         for (const customToolName of customToolNames) {
-            const expectedActive = input.toolNames.includes(customToolName);
+            const expectedActive = sessionToolNames.includes(customToolName);
             if (activeNames.has(customToolName) !== expectedActive) {
                 throw new Error(`pi SDK custom-tool activation mismatch for ${customToolName}: expectedActive=${expectedActive}`);
             }
@@ -267,6 +307,47 @@ async function createSdkSession(sdk, input, shared) {
     }
     return created.session;
 }
+/**
+ * Collect tool names registered by loader-resolved extensions. The SDK exposes
+ * each extension's `tools` as a Record (name → definition) or Map; both shapes
+ * are handled. Missing getExtensions (older SDK) yields no extras — the node
+ * then runs with the baseline allowlist only.
+ */
+function collectLoaderExtensionToolNames(loader) {
+    const getExtensions = loader?.getExtensions;
+    if (typeof getExtensions !== "function")
+        return [];
+    let parsed;
+    try {
+        parsed = getExtensions.call(loader);
+    }
+    catch {
+        return [];
+    }
+    if (!parsed || typeof parsed !== "object")
+        return [];
+    const extensions = parsed.extensions;
+    if (!Array.isArray(extensions))
+        return [];
+    const names = [];
+    for (const extension of extensions) {
+        if (!extension || typeof extension !== "object")
+            continue;
+        const tools = extension.tools;
+        if (tools instanceof Map) {
+            for (const key of tools.keys()) {
+                if (typeof key === "string")
+                    names.push(key);
+            }
+        }
+        else if (tools && typeof tools === "object") {
+            for (const key of Object.keys(tools)) {
+                names.push(key);
+            }
+        }
+    }
+    return names;
+}
 /**
  * Throttle high-noise Pi SDK events from session-events.jsonl.
  * Always keeps tool lifecycle, turn/agent end, assistant messages, and errors.
@@ -425,6 +506,8 @@ function aggregateSdkTokenUsage(samples) {
  * When reuseScope is active, only shared auth/model resources are reused; each attempt still
  * creates and disposes its own session and resource loader. Session reuse across steps is
  * deferred until a proven reset/isolation strategy exists.
+ * A transport stall may abort the current prompt and send one continue on the
+ * same session; that is in-attempt recovery, not cross-step session reuse.
  */
 export async function executeSingleSdkAttempt(options) {
     const modelConfig = options.modelConfig;
@@ -536,20 +619,37 @@ export async function executeSingleSdkAttempt(options) {
                 ? { customTools: writerCustomTools }
                 : {}),
             ...(requireWriterCustomTools ? { requireWriterCustomTools: true } : {}),
+            ...(options.piExtensionPaths && options.piExtensionPaths.length > 0
+                ? { additionalExtensionPaths: options.piExtensionPaths }
+                : {}),
         });
         let resolveStall;
         let resolveSettlement;
         let settled = false;
-        const settlementPromise = new Promise((resolve) => {
-            resolveSettlement = resolve;
-        });
-        const stallPromise = stallTimeoutMs > 0
-            ? new Promise((resolve) => {
+        let abortConfirmed = true;
+        const persistRuntimeNote = (event) => {
+            const line = serializeSessionEvent(event);
+            stdoutPreview.append(`${line}\n`);
+            stdoutCollector.append(`${line}\n`);
+            sessionEventAppender?.append(line, event);
+        };
+        const resetSettlement = () => {
+            settled = false;
+            return new Promise((resolve) => {
+                resolveSettlement = resolve;
+            });
+        };
+        const resetStallPromise = () => {
+            if (stallTimeoutMs <= 0) {
+                resolveStall = undefined;
+                return null;
+            }
+            return new Promise((resolve) => {
                 resolveStall = resolve;
-            })
-            : null;
+            });
+        };
         const armStallWatchdog = () => {
-            if (!stallPromise || !resolveStall)
+            if (stallTimeoutMs <= 0 || !resolveStall)
                 return;
             if (stallHandle)
                 clearTimeout(stallHandle);
@@ -590,17 +690,6 @@ export async function executeSingleSdkAttempt(options) {
             stdoutCollector.append(`${line}\n`);
             sessionEventAppender?.append(line, event);
         });
-        const filePrefix = options.attachedFiles
-            .map((file) => `@${file}`)
-            .join(" ");
-        const promptMessage = filePrefix
-            ? `${filePrefix}\n${options.userMessage}`
-            : options.userMessage;
-        const promptPromise = session.prompt(promptMessage);
-        // A settlement event is permitted to win the race while prompt() remains
-        // pending. Observe a later rejection so it never becomes unhandled.
-        void promptPromise.catch(() => { });
-        armStallWatchdog();
         const timeoutPromise = timeoutMs > 0
             ? new Promise((resolve) => {
                 timeoutHandle = setTimeout(() => {
@@ -608,21 +697,79 @@ export async function executeSingleSdkAttempt(options) {
                 }, timeoutMs);
             })
             : null;
-        const raced = await Promise.race([
-            promptPromise.then(() => "done"),
-            settlementPromise,
-            ...(timeoutPromise ? [timeoutPromise] : []),
-            ...(stallPromise ? [stallPromise] : []),
-        ]);
-        if (raced !== "done" && raced !== "settled") {
-            timedOut = true;
-            appendStderr(raced === "stall"
-                ? `pi SDK step stalled after ${stallTimeoutMs}ms with no provider activity`
-                : `pi SDK step timed out after ${timeoutMs}ms`);
-            const abortConfirmed = await runSessionActionWithGrace("abort", () => session.abort());
+        const runTurn = async (userMessage) => {
+            const settlementPromise = resetSettlement();
+            const stallPromise = resetStallPromise();
+            const promptPromise = session.prompt(userMessage);
+            // A settlement event is permitted to win the race while prompt() remains
+            // pending. Observe a later rejection so it never becomes unhandled.
+            void promptPromise.catch(() => { });
+            armStallWatchdog();
+            return Promise.race([
+                promptPromise.then(() => "done"),
+                settlementPromise,
+                ...(timeoutPromise ? [timeoutPromise] : []),
+                ...(stallPromise ? [stallPromise] : []),
+            ]);
+        };
+        const disposeSession = async () => {
             disposeAttempted = true;
             const disposeConfirmed = await runSessionActionWithGrace("dispose", () => session.dispose());
             terminationConfirmed = abortConfirmed && disposeConfirmed;
+        };
+        const failClosedAfterWait = async (reason, extraStderr, abortFirst = true) => {
+            timedOut = true;
+            appendStderr(reason === "stall"
+                ? `pi SDK step stalled after ${stallTimeoutMs}ms with no provider activity`
+                : `pi SDK step timed out after ${timeoutMs}ms`);
+            if (extraStderr)
+                appendStderr(extraStderr);
+            if (abortFirst) {
+                abortConfirmed = await runSessionActionWithGrace("abort", () => session.abort());
+            }
+            await disposeSession();
+        };
+        const filePrefix = options.attachedFiles
+            .map((file) => `@${file}`)
+            .join(" ");
+        const promptMessage = filePrefix
+            ? `${filePrefix}\n${options.userMessage}`
+            : options.userMessage;
+        let continuesSent = 0;
+        let raced = await runTurn(promptMessage);
+        if (raced === "stall") {
+            abortConfirmed = await runSessionActionWithGrace("abort", () => session.abort());
+            const withinAbsoluteTimeout = timeoutMs <= 0 || Date.now() - startedAt < timeoutMs;
+            const canContinue = abortConfirmed &&
+                writeToolCallCount === 0 &&
+                withinAbsoluteTimeout &&
+                continuesSent < PI_SDK_STALL_CONTINUE_MAX;
+            if (canContinue) {
+                // The aborted turn's stopReason must not leak onto a recovered continue.
+                stopReason = undefined;
+                continuesSent += 1;
+                persistRuntimeNote({
+                    type: "loop-agent-stall-continue",
+                    prompt: PI_SDK_STALL_CONTINUE_PROMPT,
+                    maxContinues: PI_SDK_STALL_CONTINUE_MAX,
+                });
+                raced = await runTurn(PI_SDK_STALL_CONTINUE_PROMPT);
+                if (raced !== "done" && raced !== "settled") {
+                    await failClosedAfterWait(raced === "stall" ? "stall" : "absolute-timeout", raced === "stall"
+                        ? "pi SDK stall continue did not recover; treating as timeout"
+                        : "pi SDK stall continue hit the absolute timeout", true);
+                }
+            }
+            else {
+                await failClosedAfterWait("stall", !abortConfirmed
+                    ? undefined
+                    : writeToolCallCount > 0
+                        ? "pi SDK stall continue skipped because write tools already ran"
+                        : "pi SDK stall continue skipped because absolute timeout elapsed", false);
+            }
+        }
+        else if (raced === "absolute-timeout") {
+            await failClosedAfterWait("absolute-timeout");
         }
     }
     catch (error) {