@tachu/extensions 1.0.0-alpha.1

package/dist/backends/file.d.ts

@@ -0,0 +1,18 @@
+import type { BackendInput, BackendOutput, ExecutionBackend, ExecutionContext, ExecutionTraits } from "@tachu/core";
+/**
+ * 文件系统执行后端。
+ */
+export declare class FileBackend implements ExecutionBackend {
+    readonly name = "file";
+    readonly kind: "file";
+    readonly traits: ExecutionTraits;
+    /**
+     * 执行文件操作。
+     *
+     * @param input 后端输入
+     * @param context 执行上下文
+     * @returns 后端输出
+     */
+    execute(input: BackendInput, context: ExecutionContext): Promise<BackendOutput>;
+}
+//# sourceMappingURL=file.d.ts.map

package/dist/backends/file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../../src/backends/file.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EAChB,MAAM,aAAa,CAAC;AAerB;;GAEG;AACH,qBAAa,WAAY,YAAW,gBAAgB;IAClD,QAAQ,CAAC,IAAI,UAAU;IACvB,QAAQ,CAAC,IAAI,EAAG,MAAM,CAAU;IAChC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAK9B;IAEF;;;;;;OAMG;IACG,OAAO,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,aAAa,CAAC;CA0DtF"}

package/dist/backends/file.js

@@ -0,0 +1,85 @@
+import { copyFile, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { ValidationError } from "@tachu/core";
+/**
+ * 如果 `context.abortSignal` 已触发，就立即抛出；否则 no-op。
+ *
+ * D1-LOW-11：Node fs 的 Promises API 并非每个方法都支持 `signal`，改用显式检查
+ * 在 backend 入口以及每个分支前完成"响应外部取消"的语义。
+ */
+const assertNotAborted = (context) => {
+    if (context.abortSignal?.aborted) {
+        throw context.abortSignal.reason ?? new Error("file backend aborted");
+    }
+};
+/**
+ * 文件系统执行后端。
+ */
+export class FileBackend {
+    name = "file";
+    kind = "file";
+    traits = {
+        sideEffect: "write",
+        idempotent: false,
+        requiresApproval: true,
+        timeout: 30_000,
+    };
+    /**
+     * 执行文件操作。
+     *
+     * @param input 后端输入
+     * @param context 执行上下文
+     * @returns 后端输出
+     */
+    async execute(input, context) {
+        const payload = input.payload;
+        if (!payload.operation || !payload.path) {
+            throw new ValidationError("VALIDATION_FILE_OPERATION", "file backend 缺少 operation/path");
+        }
+        assertNotAborted(context);
+        switch (payload.operation) {
+            case "read": {
+                const data = await readFile(payload.path, payload.encoding ?? "utf8");
+                assertNotAborted(context);
+                return { success: true, result: { content: data, traceId: context.traceId } };
+            }
+            case "write": {
+                if (typeof payload.content !== "string") {
+                    throw new ValidationError("VALIDATION_FILE_OPERATION", "write 操作缺少 content");
+                }
+                if (payload.createDirs) {
+                    await mkdir(dirname(payload.path), { recursive: true });
+                }
+                assertNotAborted(context);
+                await writeFile(payload.path, payload.content, payload.encoding ?? "utf8");
+                const fileStat = await stat(payload.path);
+                return { success: true, result: { bytesWritten: fileStat.size, traceId: context.traceId } };
+            }
+            case "delete": {
+                await rm(payload.path, { force: true, recursive: true });
+                return { success: true, result: { deleted: true, traceId: context.traceId } };
+            }
+            case "move": {
+                if (!payload.to) {
+                    throw new ValidationError("VALIDATION_FILE_OPERATION", "move 操作缺少 to");
+                }
+                await mkdir(dirname(payload.to), { recursive: true });
+                assertNotAborted(context);
+                await rename(payload.path, payload.to);
+                return { success: true, result: { moved: true, traceId: context.traceId } };
+            }
+            case "copy": {
+                if (!payload.to) {
+                    throw new ValidationError("VALIDATION_FILE_OPERATION", "copy 操作缺少 to");
+                }
+                await mkdir(dirname(payload.to), { recursive: true });
+                assertNotAborted(context);
+                await copyFile(payload.path, payload.to);
+                return { success: true, result: { copied: true, traceId: context.traceId } };
+            }
+            default:
+                throw new ValidationError("VALIDATION_FILE_OPERATION", `未知文件操作: ${payload.operation}`);
+        }
+    }
+}
+//# sourceMappingURL=file.js.map

package/dist/backends/file.js.map

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

package/dist/backends/index.d.ts

@@ -0,0 +1,4 @@
+export { TerminalBackend } from "./terminal";
+export { FileBackend } from "./file";
+export { WebBackend } from "./web";
+//# sourceMappingURL=index.d.ts.map

package/dist/backends/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/backends/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC"}

package/dist/backends/index.js

@@ -0,0 +1,4 @@
+export { TerminalBackend } from "./terminal";
+export { FileBackend } from "./file";
+export { WebBackend } from "./web";
+//# sourceMappingURL=index.js.map

package/dist/backends/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/backends/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC"}

package/dist/backends/terminal.d.ts

@@ -0,0 +1,18 @@
+import type { BackendInput, BackendOutput, ExecutionBackend, ExecutionTraits, ExecutionContext } from "@tachu/core";
+/**
+ * 终端执行后端。
+ */
+export declare class TerminalBackend implements ExecutionBackend {
+    readonly name = "terminal";
+    readonly kind: "terminal";
+    readonly traits: ExecutionTraits;
+    /**
+     * 执行终端命令。
+     *
+     * @param input 后端输入
+     * @param context 执行上下文
+     * @returns 后端输出
+     */
+    execute(input: BackendInput, context: ExecutionContext): Promise<BackendOutput>;
+}
+//# sourceMappingURL=terminal.d.ts.map

package/dist/backends/terminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../../src/backends/terminal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAMrB;;GAEG;AACH,qBAAa,eAAgB,YAAW,gBAAgB;IACtD,QAAQ,CAAC,IAAI,cAAc;IAC3B,QAAQ,CAAC,IAAI,EAAG,UAAU,CAAU;IACpC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAK9B;IAEF;;;;;;OAMG;IACG,OAAO,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,aAAa,CAAC;CAqEtF"}

package/dist/backends/terminal.js

@@ -0,0 +1,81 @@
+import { ValidationError } from "@tachu/core";
+import { readStreamWithLimit, terminateProcess } from "../common/process";
+const OUTPUT_LIMIT_BYTES = 1024 * 1024;
+/**
+ * 终端执行后端。
+ */
+export class TerminalBackend {
+    name = "terminal";
+    kind = "terminal";
+    traits = {
+        sideEffect: "irreversible",
+        idempotent: false,
+        requiresApproval: true,
+        timeout: 60_000,
+    };
+    /**
+     * 执行终端命令。
+     *
+     * @param input 后端输入
+     * @param context 执行上下文
+     * @returns 后端输出
+     */
+    async execute(input, context) {
+        const payload = input.payload;
+        if (!payload.command) {
+            throw new ValidationError("VALIDATION_EMPTY_COMMAND", "terminal backend command 不能为空");
+        }
+        // D1-LOW-11：尊重宿主注入的 `context.abortSignal`。即便主干传入一个已取消的
+        // 信号，也直接返回失败，不再产生真实子进程，避免 "先 spawn 再 kill" 的开销。
+        if (context.abortSignal?.aborted) {
+            const reason = context.abortSignal.reason instanceof Error
+                ? context.abortSignal.reason.message
+                : String(context.abortSignal.reason ?? "aborted");
+            return {
+                success: false,
+                result: {
+                    stdout: "",
+                    stderr: `terminal backend aborted before spawn: ${reason}`,
+                    exitCode: -1,
+                    traceId: context.traceId,
+                    aborted: true,
+                },
+            };
+        }
+        const processRef = Bun.spawn({
+            cmd: [payload.command, ...(payload.args ?? [])],
+            ...(payload.cwd ? { cwd: payload.cwd } : {}),
+            stdout: "pipe",
+            stderr: "pipe",
+            env: process.env,
+        });
+        const onExternalAbort = () => {
+            if (processRef.pid) {
+                void terminateProcess(processRef.pid);
+            }
+        };
+        context.abortSignal?.addEventListener("abort", onExternalAbort, { once: true });
+        const timeoutId = setTimeout(() => {
+            if (processRef.pid) {
+                void terminateProcess(processRef.pid);
+            }
+        }, payload.timeoutMs ?? this.traits.timeout);
+        const [stdout, stderr, exitCode] = await Promise.all([
+            readStreamWithLimit(processRef.stdout, OUTPUT_LIMIT_BYTES),
+            readStreamWithLimit(processRef.stderr, OUTPUT_LIMIT_BYTES),
+            processRef.exited,
+        ]);
+        clearTimeout(timeoutId);
+        context.abortSignal?.removeEventListener("abort", onExternalAbort);
+        return {
+            success: exitCode === 0,
+            result: {
+                stdout: stdout.text,
+                stderr: stderr.text,
+                exitCode,
+                traceId: context.traceId,
+            },
+        };
+    }
+}
+//# sourceMappingURL=terminal.js.map

package/dist/backends/terminal.js.map

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

package/dist/backends/web.d.ts

@@ -0,0 +1,18 @@
+import type { BackendInput, BackendOutput, ExecutionBackend, ExecutionContext, ExecutionTraits } from "@tachu/core";
+/**
+ * Web 请求执行后端。
+ */
+export declare class WebBackend implements ExecutionBackend {
+    readonly name = "web";
+    readonly kind: "web";
+    readonly traits: ExecutionTraits;
+    /**
+     * 执行 HTTP 请求。
+     *
+     * @param input 后端输入
+     * @param context 执行上下文
+     * @returns 后端输出
+     */
+    execute(input: BackendInput, context: ExecutionContext): Promise<BackendOutput>;
+}
+//# sourceMappingURL=web.d.ts.map

package/dist/backends/web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../../src/backends/web.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EAChB,MAAM,aAAa,CAAC;AAMrB;;GAEG;AACH,qBAAa,UAAW,YAAW,gBAAgB;IACjD,QAAQ,CAAC,IAAI,SAAS;IACtB,QAAQ,CAAC,IAAI,EAAG,KAAK,CAAU;IAC/B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAK9B;IAEF;;;;;;OAMG;IACG,OAAO,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,aAAa,CAAC;CAyCtF"}

package/dist/backends/web.js

@@ -0,0 +1,55 @@
+import { ValidationError } from "@tachu/core";
+import { assertPublicUrl, readResponseBodyWithLimit, withAbortTimeout } from "../common/net";
+const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
+/**
+ * Web 请求执行后端。
+ */
+export class WebBackend {
+    name = "web";
+    kind = "web";
+    traits = {
+        sideEffect: "readonly",
+        idempotent: false,
+        requiresApproval: false,
+        timeout: 30_000,
+    };
+    /**
+     * 执行 HTTP 请求。
+     *
+     * @param input 后端输入
+     * @param context 执行上下文
+     * @returns 后端输出
+     */
+    async execute(input, context) {
+        const payload = input.payload;
+        if (!payload.url) {
+            throw new ValidationError("VALIDATION_INVALID_URL", "web backend 缺少 url");
+        }
+        const target = await assertPublicUrl(payload.url);
+        // D1-LOW-11：把宿主注入的 `context.abortSignal` 与本地超时信号合并，外部取消
+        // 能立即中断下游 fetch 请求，不必等到本 backend 的内建超时到期。
+        const timeout = withAbortTimeout(context.abortSignal, payload.timeoutMs ?? this.traits.timeout, "TIMEOUT_WEB_BACKEND");
+        try {
+            const response = await fetch(target, {
+                method: payload.method ?? "GET",
+                headers: payload.headers,
+                body: payload.body,
+                signal: timeout.signal,
+            });
+            const body = await readResponseBodyWithLimit(response, MAX_RESPONSE_BYTES);
+            return {
+                success: response.ok,
+                result: {
+                    status: response.status,
+                    body: body.body,
+                    truncated: body.truncated,
+                    traceId: context.traceId,
+                },
+            };
+        }
+        finally {
+            timeout.cleanup();
+        }
+    }
+}
+//# sourceMappingURL=web.js.map

package/dist/backends/web.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.js","sourceRoot":"","sources":["../../src/backends/web.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAE7F,MAAM,kBAAkB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAE3C;;GAEG;AACH,MAAM,OAAO,UAAU;IACZ,IAAI,GAAG,KAAK,CAAC;IACb,IAAI,GAAG,KAAc,CAAC;IACtB,MAAM,GAAoB;QACjC,UAAU,EAAE,UAAU;QACtB,UAAU,EAAE,KAAK;QACjB,gBAAgB,EAAE,KAAK;QACvB,OAAO,EAAE,MAAM;KAChB,CAAC;IAEF;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CAAC,KAAmB,EAAE,OAAyB;QAC1D,MAAM,OAAO,GAAG,KAAK,CAAC,OAMrB,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;YACjB,MAAM,IAAI,eAAe,CAAC,wBAAwB,EAAE,oBAAoB,CAAC,CAAC;QAC5E,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAClD,wDAAwD;QACxD,0CAA0C;QAC1C,MAAM,OAAO,GAAG,gBAAgB,CAC9B,OAAO,CAAC,WAAW,EACnB,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,EACxC,qBAAqB,CACtB,CAAC;QACF,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,MAAM,EAAE;gBACnC,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,KAAK;gBAC/B,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,MAAM,EAAE,OAAO,CAAC,MAAM;aACvB,CAAC,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,yBAAyB,CAAC,QAAQ,EAAE,kBAAkB,CAAC,CAAC;YAC3E,OAAO;gBACL,OAAO,EAAE,QAAQ,CAAC,EAAE;gBACpB,MAAM,EAAE;oBACN,MAAM,EAAE,QAAQ,CAAC,MAAM;oBACvB,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,SAAS,EAAE,IAAI,CAAC,SAAS;oBACzB,OAAO,EAAE,OAAO,CAAC,OAAO;iBACzB;aACF,CAAC;QACJ,CAAC;gBAAS,CAAC;YACT,OAAO,CAAC,OAAO,EAAE,CAAC;QACpB,CAAC;IACH,CAAC;CACF"}

package/dist/common/net.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 配置网络安全开关。仅供集成测试在启动本地 HTTP 服务时临时放行 127.0.0.1 / localhost。
+ *
+ * 生产代码不应调用本函数。调用后请在用例结束时显式还原为 `false`，避免污染其它测试。
+ */
+export declare const configureNetSafety: (opts: {
+    allowLoopbackForTests?: boolean;
+}) => void;
+/**
+ * 检查 URL 是否指向私网地址。
+ *
+ * @param input 待检查 URL
+ * @throws SafetyError 当 URL 指向私网/本机地址时抛出
+ */
+export declare const assertPublicUrl: (input: string) => Promise<URL>;
+/**
+ * 组合外部取消信号与超时控制。
+ *
+ * @param signal 外部取消信号
+ * @param timeoutMs 超时时间（毫秒）
+ * @param timeoutCode 超时错误码
+ * @returns 合并信号与清理函数
+ */
+export declare const withAbortTimeout: (signal: AbortSignal | undefined, timeoutMs: number, timeoutCode?: string) => {
+    signal: AbortSignal;
+    cleanup: () => void;
+};
+/**
+ * 读取响应体并按最大字节数截断。
+ *
+ * @param response Fetch 响应
+ * @param maxBytes 最大字节数
+ * @returns 文本内容和截断标识
+ */
+export declare const readResponseBodyWithLimit: (response: Response, maxBytes: number) => Promise<{
+    body: string;
+    truncated: boolean;
+}>;
+//# sourceMappingURL=net.d.ts.map

package/dist/common/net.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"net.d.ts","sourceRoot":"","sources":["../../src/common/net.ts"],"names":[],"mappings":"AAiBA;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM;IACvC,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,KAAG,IAIH,CAAC;AAyCF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAU,OAAO,MAAM,KAAG,OAAO,CAAC,GAAG,CAgDhE,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,WAAW,GAAG,SAAS,EAC/B,WAAW,MAAM,EACjB,oBAAwC,KACvC;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAsB5C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GACpC,UAAU,QAAQ,EAClB,UAAU,MAAM,KACf,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAwC9C,CAAC"}

package/dist/common/net.js

@@ -0,0 +1,177 @@
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+import { SafetyError, TimeoutError } from "@tachu/core";
+const LOCAL_HOSTNAMES = new Set(["localhost", "localhost.localdomain"]);
+const netSafety = {
+    allowLoopbackForTests: false,
+};
+/**
+ * 配置网络安全开关。仅供集成测试在启动本地 HTTP 服务时临时放行 127.0.0.1 / localhost。
+ *
+ * 生产代码不应调用本函数。调用后请在用例结束时显式还原为 `false`，避免污染其它测试。
+ */
+export const configureNetSafety = (opts) => {
+    if (typeof opts.allowLoopbackForTests === "boolean") {
+        netSafety.allowLoopbackForTests = opts.allowLoopbackForTests;
+    }
+};
+const isPrivateIpv4 = (ip) => {
+    const [aRaw, bRaw] = ip.split(".");
+    const a = Number(aRaw);
+    const b = Number(bRaw);
+    if (Number.isNaN(a) || Number.isNaN(b)) {
+        return false;
+    }
+    if (a === 10 || a === 127) {
+        return true;
+    }
+    if (a === 192 && b === 168) {
+        return true;
+    }
+    if (a === 172 && b >= 16 && b <= 31) {
+        return true;
+    }
+    if (a === 169 && b === 254) {
+        return true;
+    }
+    if (a === 0) {
+        return true;
+    }
+    return false;
+};
+const isPrivateIpv6 = (ip) => {
+    const lower = ip.toLowerCase();
+    if (lower === "::1") {
+        return true;
+    }
+    if (lower.startsWith("fc") || lower.startsWith("fd")) {
+        return true;
+    }
+    if (lower.startsWith("fe80")) {
+        return true;
+    }
+    return false;
+};
+/**
+ * 检查 URL 是否指向私网地址。
+ *
+ * @param input 待检查 URL
+ * @throws SafetyError 当 URL 指向私网/本机地址时抛出
+ */
+export const assertPublicUrl = async (input) => {
+    let parsed;
+    try {
+        parsed = new URL(input);
+    }
+    catch (error) {
+        throw new SafetyError("SAFETY_INVALID_URL", `URL 无效: ${input}`, { cause: error });
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new SafetyError("SAFETY_PROTOCOL_NOT_ALLOWED", `协议不允许: ${parsed.protocol}`);
+    }
+    const hostname = parsed.hostname.toLowerCase();
+    if (!netSafety.allowLoopbackForTests) {
+        if (LOCAL_HOSTNAMES.has(hostname) || hostname.endsWith(".local")) {
+            throw new SafetyError("SAFETY_PRIVATE_NETWORK_BLOCKED", `已阻止私网地址: ${hostname}`, {
+                context: { hostname },
+            });
+        }
+        const literalIpFamily = isIP(hostname);
+        if (literalIpFamily === 4 && isPrivateIpv4(hostname)) {
+            throw new SafetyError("SAFETY_PRIVATE_NETWORK_BLOCKED", `已阻止私网地址: ${hostname}`, {
+                context: { hostname },
+            });
+        }
+        if (literalIpFamily === 6 && isPrivateIpv6(hostname)) {
+            throw new SafetyError("SAFETY_PRIVATE_NETWORK_BLOCKED", `已阻止私网地址: ${hostname}`, {
+                context: { hostname },
+            });
+        }
+        if (literalIpFamily === 0) {
+            const records = await lookup(hostname, { all: true });
+            for (const record of records) {
+                if ((record.family === 4 && isPrivateIpv4(record.address)) ||
+                    (record.family === 6 && isPrivateIpv6(record.address))) {
+                    throw new SafetyError("SAFETY_PRIVATE_NETWORK_BLOCKED", `已阻止私网地址: ${hostname}`, {
+                        context: { hostname, resolved: records.map((item) => item.address) },
+                    });
+                }
+            }
+        }
+    }
+    return parsed;
+};
+/**
+ * 组合外部取消信号与超时控制。
+ *
+ * @param signal 外部取消信号
+ * @param timeoutMs 超时时间（毫秒）
+ * @param timeoutCode 超时错误码
+ * @returns 合并信号与清理函数
+ */
+export const withAbortTimeout = (signal, timeoutMs, timeoutCode = "TIMEOUT_PROVIDER_REQUEST") => {
+    const controller = new AbortController();
+    let timeoutId;
+    const onAbort = () => {
+        controller.abort(signal?.reason ?? new Error("aborted"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    timeoutId = setTimeout(() => {
+        controller.abort(new TimeoutError(timeoutCode, `请求超时: ${timeoutMs}ms`, { retryable: true }));
+    }, timeoutMs);
+    return {
+        signal: controller.signal,
+        cleanup: () => {
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+            signal?.removeEventListener("abort", onAbort);
+        },
+    };
+};
+/**
+ * 读取响应体并按最大字节数截断。
+ *
+ * @param response Fetch 响应
+ * @param maxBytes 最大字节数
+ * @returns 文本内容和截断标识
+ */
+export const readResponseBodyWithLimit = async (response, maxBytes) => {
+    const reader = response.body?.getReader();
+    if (!reader) {
+        return { body: "", truncated: false };
+    }
+    const chunks = [];
+    let total = 0;
+    let truncated = false;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+            break;
+        }
+        if (!value) {
+            continue;
+        }
+        const room = maxBytes - total;
+        if (room <= 0) {
+            truncated = true;
+            break;
+        }
+        if (value.byteLength > room) {
+            chunks.push(value.subarray(0, room));
+            total += room;
+            truncated = true;
+            break;
+        }
+        chunks.push(value);
+        total += value.byteLength;
+    }
+    const merged = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        merged.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return { body: new TextDecoder().decode(merged), truncated };
+};
+//# sourceMappingURL=net.js.map

package/dist/common/net.js.map

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

package/dist/common/path.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 解析一条工具输入路径的可选上下文。
+ */
+export interface ResolveAllowedPathOptions {
+    /**
+     * 允许访问的根目录列表（绝对路径）。相对路径会以第一个根为基准展开。
+     * 至少包含一个；通常是 `[workspaceRoot, ...extraRoots]`。
+     */
+    allowedRoots: readonly string[];
+    /**
+     * 本次调用是否已经通过用户审批（见 `@tachu/core` 的 `onBeforeToolCall`）。
+     *
+     * 一旦为 `true`，路径校验会直接放行：语义上用户已经在审批提示里看过
+     * `argumentsPreview`（包括任何路径字段）并显式同意。这条通道只用于"本次
+     * 工具调用"，不会污染后续调用的沙箱策略。
+     *
+     * 审批未触发或被拒绝时必须保持 `false`。
+     */
+    sandboxWaived?: boolean;
+}
+/**
+ * 把用户输入路径规范化到允许的根目录集合之一。
+ *
+ * 沙箱层级自上而下：
+ *   1. `sandboxWaived === true` → 本次调用豁免，直接返回 `resolve(...)` 后的绝对路径；
+ *   2. 否则检查候选路径是否落在任意 `allowedRoots` 之下；全部不满足时抛出
+ *      `ValidationError(VALIDATION_PATH_ESCAPE)`。
+ *
+ * 该函数对"同时传入了相对路径与绝对路径"的语义：相对路径基于
+ * `allowedRoots[0]` 展开（通常就是 workspaceRoot），因为模型给出相对路径时
+ * 默认意图"相对工作区"；绝对路径则直接 resolve 后再做白名单判定。
+ *
+ * @throws ValidationError 当沙箱未豁免且候选路径不在任何允许的根下
+ */
+export declare const resolveAllowedPath: (targetPath: string, options: ResolveAllowedPathOptions) => string;
+/**
+ * 旧签名兼容层：仅允许 `workspaceRoot` 一个根，不走审批豁免。
+ *
+ * @deprecated 新代码请改用 {@link resolveAllowedPath}，通过 `ToolExecutionContext.allowedRoots`
+ * 和 `ToolExecutionContext.sandboxWaived` 传递完整的白名单/审批状态。
+ */
+export declare const resolveWorkspacePath: (workspaceRoot: string, targetPath: string) => string;
+/**
+ * 将绝对路径转换为相对工作区路径。
+ *
+ * @param workspaceRoot 工作区根目录
+ * @param absPath 绝对路径
+ * @returns 相对路径（POSIX 风格）
+ */
+export declare const toWorkspaceRelativePath: (workspaceRoot: string, absPath: string) => string;
+//# sourceMappingURL=path.d.ts.map

package/dist/common/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../src/common/path.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAID;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,kBAAkB,GAC7B,YAAY,MAAM,EAClB,SAAS,yBAAyB,KACjC,MAsCF,CAAC;AAUF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAAI,eAAe,MAAM,EAAE,YAAY,MAAM,KAAG,MAEhF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,GAAI,eAAe,MAAM,EAAE,SAAS,MAAM,KAAG,MAGhF,CAAC"}