@vinhnt-sdk/tools 1.0.0

package/dist/question-tool.d.ts

@@ -0,0 +1,15 @@
+export interface QuestionInput {
+    header: string;
+    question: string;
+    options?: {
+        label: string;
+        description?: string;
+    }[] | undefined;
+    multiple?: boolean;
+}
+export type QuestionHandler = (question: QuestionInput) => Promise<string>;
+export declare function createQuestionTool(handler?: QuestionHandler): import("./definitions.js").ToolDefinition<QuestionInput, {
+    answer: string;
+    error?: string;
+}>;
+//# sourceMappingURL=question-tool.d.ts.map

package/dist/question-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-tool.d.ts","sourceRoot":"","sources":["../src/question-tool.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,SAAS,CAAC;IAChE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,QAAQ,EAAE,aAAa,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAY3E,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,eAAe;YACf,MAAM;YAAU,MAAM;GAqClE"}

package/dist/question-tool.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { defineTool } from "./define-tool.js";
+const QuestionSchema = z.object({
+    header: z.string().min(1).max(30),
+    question: z.string().min(1),
+    options: z.array(z.object({
+        label: z.string().min(1),
+        description: z.string().optional(),
+    })).min(1).max(6).optional(),
+    multiple: z.boolean().optional(),
+});
+export function createQuestionTool(handler) {
+    return defineTool({
+        name: "question",
+        description: "Ask the user a question and get their response. Use this when you need clarification, preferences, or decisions from the user. Provide clear options when possible.",
+        risk: "external",
+        input: QuestionSchema,
+        jsonSchema: {
+            type: "object",
+            properties: {
+                header: { type: "string", description: "Short header or title for the question (max 100 chars)" },
+                question: { type: "string", description: "The question to ask the user" },
+                options: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            label: { type: "string", description: "Option label shown to user" },
+                            description: { type: "string", description: "Optional description" },
+                        },
+                        required: ["label"],
+                    },
+                    description: "Predefined answer options the user can pick from",
+                },
+                multiple: {
+                    type: "boolean",
+                    description: "Allow selecting multiple options (default: false)",
+                },
+            },
+            required: ["header", "question"],
+        },
+        async execute(v) {
+            if (!handler) {
+                return { answer: "", error: "No question handler configured" };
+            }
+            const answer = await handler(v);
+            return { answer };
+        },
+    }).toDefinition();
+}
+//# sourceMappingURL=question-tool.js.map

package/dist/question-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-tool.js","sourceRoot":"","sources":["../src/question-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAW9C,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;IACjC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;QACxB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACxB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KACnC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC5B,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC,CAAC;AAEH,MAAM,UAAU,kBAAkB,CAAC,OAAyB;IAC1D,OAAO,UAAU,CAAoD;QACnE,IAAI,EAAE,UAAU;QAChB,WAAW,EAAE,qKAAqK;QAClL,IAAI,EAAE,UAAU;QAChB,KAAK,EAAE,cAAc;QACrB,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,wDAAwD,EAAE;gBACjG,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,8BAA8B,EAAE;gBACzE,OAAO,EAAE;oBACP,IAAI,EAAE,OAAO;oBACb,KAAK,EAAE;wBACL,IAAI,EAAE,QAAQ;wBACd,UAAU,EAAE;4BACV,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,4BAA4B,EAAE;4BACpE,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sBAAsB,EAAE;yBACrE;wBACD,QAAQ,EAAE,CAAC,OAAO,CAAC;qBACpB;oBACD,WAAW,EAAE,kDAAkD;iBAChE;gBACD,QAAQ,EAAE;oBACR,IAAI,EAAE,SAAS;oBACf,WAAW,EAAE,mDAAmD;iBACjE;aACF;YACD,QAAQ,EAAE,CAAC,QAAQ,EAAE,UAAU,CAAC;SACjC;QACD,KAAK,CAAC,OAAO,CAAC,CAAC;YACb,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,gCAAgC,EAAE,CAAC;YACjE,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;YAChC,OAAO,EAAE,MAAM,EAAE,CAAC;QACpB,CAAC;KACF,CAAC,CAAC,YAAY,EAAE,CAAC;AACpB,CAAC"}

package/dist/read-tracker.d.ts

@@ -0,0 +1,8 @@
+export declare class FileReadTracker {
+    private records;
+    trackRead(filePath: string, mtimeMs: number): void;
+    assertWasRead(filePath: string): Promise<void>;
+    clear(filePath: string): void;
+    reset(): void;
+}
+//# sourceMappingURL=read-tracker.d.ts.map

package/dist/read-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-tracker.d.ts","sourceRoot":"","sources":["../src/read-tracker.ts"],"names":[],"mappings":"AAQA,qBAAa,eAAe;IAC1B,OAAO,CAAC,OAAO,CAAiC;IAEhD,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAI5C,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBpD,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAI7B,KAAK,IAAI,IAAI;CAGd"}

package/dist/read-tracker.js

@@ -0,0 +1,33 @@
+import { stat } from "node:fs/promises";
+import { ToolPermissionDenied } from "@vinhnt-sdk/schema";
+export class FileReadTracker {
+    records = new Map();
+    trackRead(filePath, mtimeMs) {
+        this.records.set(filePath, { readAt: Date.now(), mtimeMs });
+    }
+    async assertWasRead(filePath) {
+        const record = this.records.get(filePath);
+        if (!record) {
+            throw new ToolPermissionDenied("write_file", `File "${filePath}" has not been read before writing. Use read_file first.`);
+        }
+        try {
+            const st = await stat(filePath);
+            if (st.mtimeMs !== record.mtimeMs) {
+                this.records.delete(filePath);
+                throw new ToolPermissionDenied("write_file", `File "${filePath}" has been modified externally since it was last read. Read it again before writing.`);
+            }
+        }
+        catch (err) {
+            if (err instanceof ToolPermissionDenied)
+                throw err;
+            this.records.delete(filePath);
+        }
+    }
+    clear(filePath) {
+        this.records.delete(filePath);
+    }
+    reset() {
+        this.records.clear();
+    }
+}
+//# sourceMappingURL=read-tracker.js.map

package/dist/read-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-tracker.js","sourceRoot":"","sources":["../src/read-tracker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAO1D,MAAM,OAAO,eAAe;IAClB,OAAO,GAAG,IAAI,GAAG,EAAsB,CAAC;IAEhD,SAAS,CAAC,QAAgB,EAAE,OAAe;QACzC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,QAAgB;QAClC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC1C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,oBAAoB,CAC5B,YAAY,EACZ,SAAS,QAAQ,0DAA0D,CAC5E,CAAC;QACJ,CAAC;QACD,IAAI,CAAC;YACH,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC;YAChC,IAAI,EAAE,CAAC,OAAO,KAAK,MAAM,CAAC,OAAO,EAAE,CAAC;gBAClC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;gBAC9B,MAAM,IAAI,oBAAoB,CAC5B,YAAY,EACZ,SAAS,QAAQ,sFAAsF,CACxG,CAAC;YACJ,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,oBAAoB;gBAAE,MAAM,GAAG,CAAC;YACnD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IAED,KAAK,CAAC,QAAgB;QACpB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;CACF"}

package/dist/registry.d.ts

@@ -0,0 +1,58 @@
+import type { ToolDefinition, ToolContext, ToolRisk } from "./definitions.js";
+import type { DomainManifest, DomainSummary } from "./domain.js";
+export type ToolFilter = {
+    risk?: ToolRisk;
+    ids?: string[];
+    pattern?: string;
+};
+/** Minimal permission rule relevant for tool filtering at the tool boundary. */
+export interface ToolPermissionRule {
+    /** Tool id or wildcard pattern (e.g. "coding.*", "*"). */
+    action: string;
+    effect: "allow" | "deny" | "ask";
+}
+export interface ToolMaterialization {
+    /** Provider-facing definitions the model is ALLOWED to see/invoke. */
+    definitions: readonly ToolDefinition[];
+    /** Tool definitions that were denied by permission rules. */
+    denied: readonly ToolDefinition[];
+    /** Resolve one tool call: validate args and execute. */
+    settle(input: {
+        name: string;
+        args: unknown;
+        ctx?: ToolContext;
+    }): Promise<unknown>;
+    /** Lookup a tool definition by ID from the allowed set. */
+    getTool(id: string): ToolDefinition | undefined;
+}
+export declare class ToolRegistry {
+    protected readonly tools: Map<string, ToolDefinition<unknown, unknown>>;
+    protected readonly domains: Map<string, DomainManifest>;
+    register(tool: ToolDefinition): void;
+    /** Register a named domain and its tool membership (metadata only — does not register the tools). */
+    registerDomain(manifest: DomainManifest): void;
+    getDomains(): readonly DomainManifest[];
+    /** Resolve the domain id a tool belongs to, or undefined if it is a core tool. */
+    domainFor(id: string): string | undefined;
+    /** Get all registered domain manifests. */
+    listDomains(): readonly DomainManifest[];
+    /** Get domain summaries for UI/API consumption. */
+    domainSummaries(): DomainSummary[];
+    /** Get tools belonging to a specific domain. */
+    toolsForDomain(domainId: string): readonly ToolDefinition[];
+    unregister(id: string): boolean;
+    get(id: string): ToolDefinition | undefined;
+    list(filter?: ToolFilter): readonly ToolDefinition[];
+    count(): number;
+    /** Get a tool by ID, throwing a typed error if not found */
+    getOrThrow(id: string): ToolDefinition;
+    /**
+     * Materialize the tool set for a given permission ruleset: drop tools the
+     * model must not see (wholly-denied), and return a `settle` that validates
+     * and executes a single tool call. Defaults to exposing every registered tool.
+     */
+    materialize(permissions?: readonly ToolPermissionRule[]): ToolMaterialization;
+    /** Remove tools whose rule is wholly denied (deny "*" / deny this tool). */
+    private filterByRules;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAG9E,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjE,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,gFAAgF;AAChF,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;CAClC;AAED,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,WAAW,EAAE,SAAS,cAAc,EAAE,CAAC;IACvC,6DAA6D;IAC7D,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC;IAClC,wDAAwD;IACxD,MAAM,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,GAAG,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpF,2DAA2D;IAC3D,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAC;CACjD;AAED,qBAAa,YAAY;IACvB,SAAS,CAAC,QAAQ,CAAC,KAAK,gDAAqC;IAC7D,SAAS,CAAC,QAAQ,CAAC,OAAO,8BAAqC;IAE/D,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI;IAIpC,qGAAqG;IACrG,cAAc,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IAI9C,UAAU,IAAI,SAAS,cAAc,EAAE;IAIvC,kFAAkF;IAClF,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAOzC,2CAA2C;IAC3C,WAAW,IAAI,SAAS,cAAc,EAAE;IAIxC,mDAAmD;IACnD,eAAe,IAAI,aAAa,EAAE;IAIlC,gDAAgD;IAChD,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,cAAc,EAAE;IAK3D,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAI/B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAI3C,IAAI,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,SAAS,cAAc,EAAE;IAWpD,KAAK,IAAI,MAAM;IAIf,4DAA4D;IAC5D,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc;IAMtC;;;;OAIG;IACH,WAAW,CAAC,WAAW,CAAC,EAAE,SAAS,kBAAkB,EAAE,GAAG,mBAAmB;IAmC7E,4EAA4E;IAC5E,OAAO,CAAC,aAAa;CAWtB"}

package/dist/registry.js

@@ -0,0 +1,128 @@
+import { wildcardMatch } from "@vinhnt-sdk/schema";
+import { ToolNotFoundError } from "@vinhnt-sdk/schema";
+import { summarizeDomains } from "./domain.js";
+import { validateInput } from "./validate.js";
+export class ToolRegistry {
+    tools = new Map();
+    domains = new Map();
+    register(tool) {
+        this.tools.set(tool.id, tool);
+    }
+    /** Register a named domain and its tool membership (metadata only — does not register the tools). */
+    registerDomain(manifest) {
+        this.domains.set(manifest.id, manifest);
+    }
+    getDomains() {
+        return [...this.domains.values()];
+    }
+    /** Resolve the domain id a tool belongs to, or undefined if it is a core tool. */
+    domainFor(id) {
+        for (const [domainId, manifest] of this.domains) {
+            if (manifest.tools.some((t) => t.id === id))
+                return domainId;
+        }
+        return undefined;
+    }
+    /** Get all registered domain manifests. */
+    listDomains() {
+        return [...this.domains.values()];
+    }
+    /** Get domain summaries for UI/API consumption. */
+    domainSummaries() {
+        return summarizeDomains([...this.domains.values()]);
+    }
+    /** Get tools belonging to a specific domain. */
+    toolsForDomain(domainId) {
+        const manifest = this.domains.get(domainId);
+        return manifest?.tools ?? [];
+    }
+    unregister(id) {
+        return this.tools.delete(id);
+    }
+    get(id) {
+        return this.tools.get(id);
+    }
+    list(filter) {
+        const all = [...this.tools.values()];
+        if (!filter)
+            return all;
+        return all.filter((t) => {
+            if (filter.risk && t.risk !== filter.risk)
+                return false;
+            if (filter.ids && !filter.ids.includes(t.id))
+                return false;
+            if (filter.pattern && !wildcardMatch(filter.pattern, t.id))
+                return false;
+            return true;
+        });
+    }
+    count() {
+        return this.tools.size;
+    }
+    /** Get a tool by ID, throwing a typed error if not found */
+    getOrThrow(id) {
+        const tool = this.tools.get(id);
+        if (!tool)
+            throw new ToolNotFoundError(id);
+        return tool;
+    }
+    /**
+     * Materialize the tool set for a given permission ruleset: drop tools the
+     * model must not see (wholly-denied), and return a `settle` that validates
+     * and executes a single tool call. Defaults to exposing every registered tool.
+     */
+    materialize(permissions) {
+        const allTools = [...this.tools.values()];
+        const allowed = this.filterByRules(allTools, permissions);
+        const allowedIds = new Set(allowed.map((t) => t.id));
+        const denied = allTools.filter((t) => !allowedIds.has(t.id));
+        const allowedMap = new Map(allowed.map((t) => [t.id, t]));
+        return {
+            definitions: allowed,
+            denied,
+            getTool: (id) => allowedMap.get(id),
+            settle: async ({ name, args, ctx }) => {
+                const tool = this.tools.get(name);
+                if (!tool)
+                    throw new ToolNotFoundError(name);
+                // Validate input via Zod schema if available (non-breaking: falls through to raw execute if no schema)
+                let validatedInput = args;
+                if (tool.inputZodSchema) {
+                    validatedInput = validateInput(name, tool.inputZodSchema, args);
+                }
+                const defaultCtx = {
+                    sessionId: "",
+                    runId: "",
+                    agentId: "",
+                    agentName: "",
+                    signal: new AbortController().signal,
+                    env: {},
+                    ask: async () => "once",
+                    metadata: () => { },
+                    setCompensation: () => { },
+                };
+                return tool.execute(validatedInput, ctx ?? defaultCtx);
+            },
+        };
+    }
+    /** Remove tools whose rule is wholly denied (deny "*" / deny this tool). */
+    filterByRules(tools, permissions) {
+        if (!permissions || permissions.length === 0)
+            return tools;
+        const deniedActions = new Set();
+        for (const rule of permissions) {
+            if (rule.effect === "deny")
+                deniedActions.add(rule.action);
+        }
+        return tools.filter((t) => isDenied(t.id, deniedActions) === false);
+    }
+}
+/** A tool is denied if it matches a deny rule (exact or wildcard). */
+function isDenied(id, deniedActions) {
+    for (const pattern of deniedActions) {
+        if (wildcardMatch(pattern, id))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AA0B9C,MAAM,OAAO,YAAY;IACJ,KAAK,GAAG,IAAI,GAAG,EAA0B,CAAC;IAC1C,OAAO,GAAG,IAAI,GAAG,EAA0B,CAAC;IAE/D,QAAQ,CAAC,IAAoB;QAC3B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,qGAAqG;IACrG,cAAc,CAAC,QAAwB;QACrC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;IAC1C,CAAC;IAED,UAAU;QACR,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACpC,CAAC;IAED,kFAAkF;IAClF,SAAS,CAAC,EAAU;QAClB,KAAK,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAChD,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;gBAAE,OAAO,QAAQ,CAAC;QAC/D,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,2CAA2C;IAC3C,WAAW;QACT,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACpC,CAAC;IAED,mDAAmD;IACnD,eAAe;QACb,OAAO,gBAAgB,CAAC,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACtD,CAAC;IAED,gDAAgD;IAChD,cAAc,CAAC,QAAgB;QAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC5C,OAAO,QAAQ,EAAE,KAAK,IAAI,EAAE,CAAC;IAC/B,CAAC;IAED,UAAU,CAAC,EAAU;QACnB,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC5B,CAAC;IAED,IAAI,CAAC,MAAmB;QACtB,MAAM,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QACrC,IAAI,CAAC,MAAM;YAAE,OAAO,GAAG,CAAC;QACxB,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;YACtB,IAAI,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI;gBAAE,OAAO,KAAK,CAAC;YACxD,IAAI,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;gBAAE,OAAO,KAAK,CAAC;YAC3D,IAAI,MAAM,CAAC,OAAO,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC;gBAAE,OAAO,KAAK,CAAC;YACzE,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED,4DAA4D;IAC5D,UAAU,CAAC,EAAU;QACnB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,iBAAiB,CAAC,EAAE,CAAC,CAAC;QAC3C,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACH,WAAW,CAAC,WAA2C;QACrD,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QAC1C,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;QAC1D,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACrD,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC7D,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAE1D,OAAO;YACL,WAAW,EAAE,OAAO;YACpB,MAAM;YACN,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACnC,MAAM,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE;gBACpC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBAClC,IAAI,CAAC,IAAI;oBAAE,MAAM,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAC;gBAC7C,uGAAuG;gBACvG,IAAI,cAAc,GAAG,IAAI,CAAC;gBAC1B,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;oBACxB,cAAc,GAAG,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;gBAClE,CAAC;gBACD,MAAM,UAAU,GAAgB;oBAC9B,SAAS,EAAE,EAAE;oBACb,KAAK,EAAE,EAAE;oBACT,OAAO,EAAE,EAAE;oBACX,SAAS,EAAE,EAAE;oBACb,MAAM,EAAE,IAAI,eAAe,EAAE,CAAC,MAAM;oBACpC,GAAG,EAAE,EAAE;oBACP,GAAG,EAAE,KAAK,IAAI,EAAE,CAAC,MAAM;oBACvB,QAAQ,EAAE,GAAG,EAAE,GAAE,CAAC;oBAClB,eAAe,EAAE,GAAG,EAAE,GAAE,CAAC;iBAC1B,CAAC;gBACF,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,GAAG,IAAI,UAAU,CAAC,CAAC;YACzD,CAAC;SACF,CAAC;IACJ,CAAC;IAED,4EAA4E;IACpE,aAAa,CACnB,KAAgC,EAChC,WAA2C;QAE3C,IAAI,CAAC,WAAW,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QAC3D,MAAM,aAAa,GAAG,IAAI,GAAG,EAAU,CAAC;QACxC,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;YAC/B,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM;gBAAE,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC7D,CAAC;QACD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,aAAa,CAAC,KAAK,KAAK,CAAC,CAAC;IACtE,CAAC;CACF;AAED,sEAAsE;AACtE,SAAS,QAAQ,CAAC,EAAU,EAAE,aAA0B;IACtD,KAAK,MAAM,OAAO,IAAI,aAAa,EAAE,CAAC;QACpC,IAAI,aAAa,CAAC,OAAO,EAAE,EAAE,CAAC;YAAE,OAAO,IAAI,CAAC;IAC9C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/sandbox.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Tool sandboxing for isolated execution.
+ *
+ * @module tool/sandbox
+ * @packageDocumentation
+ */
+import type { ToolDefinition, ToolContext } from "./definitions.js";
+/** Sandbox execution scope — string type, NOT closed union */
+export type SandboxScope = string;
+/**
+ * Default sandbox scopes — exported for convenience.
+ * User có thể register custom scope qua ProcessSandbox adapter.
+ */
+export declare const KNOWN_SANDBOX_SCOPES: readonly ["host", "process", "container"];
+/** Sandbox configuration */
+export interface SandboxConfig {
+    defaultTimeoutMs: number;
+    /** Execution scope (default: "host" — no isolation) */
+    scope?: SandboxScope;
+    /** Allowed filesystem paths (for "process" scope) */
+    allowedPaths?: string[];
+    /** Blocked filesystem paths */
+    blockedPaths?: string[];
+    /** Allow network access (default: true) */
+    allowNetwork?: boolean;
+    /** Allowed environment variables */
+    allowedEnvVars?: string[];
+    /** Allowed commands (for "process" scope) */
+    allowedCommands?: Set<string>;
+    /** Enable Node.js Permission Model (Node 22+) */
+    enablePermissionModel?: boolean;
+}
+/** Result of a sandboxed execution */
+export interface SandboxResult<T = unknown> {
+    result: T;
+    exitCode: number;
+    durationMs: number;
+    timedOut: boolean;
+    /** Resources consumed during execution */
+    resources?: {
+        cpuTimeMs?: number;
+        memoryBytes?: number;
+    };
+}
+/**
+ * Interface for sandbox execution adapters.
+ *
+ * Implementations can provide different levels of isolation:
+ * - `host`: No isolation (current behavior)
+ * - `process`: Node.js Permission Model + empty env + command allowlist
+ * - `container`: Docker/Firecracker microVM
+ */
+export interface ProcessSandbox {
+    /** The scope this sandbox provides */
+    readonly scope: SandboxScope;
+    /** Execute a command in the sandbox */
+    execute(options: {
+        command: string;
+        cwd: string;
+        timeoutMs: number;
+        env?: Record<string, string>;
+        signal?: AbortSignal;
+    }): Promise<SandboxResult<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>>;
+    /** Clean up resources */
+    destroy(): Promise<void>;
+}
+/**
+ * Create a process sandbox based on the configured scope.
+ *
+ * @param config - Sandbox configuration
+ * @returns ProcessSandbox instance
+ */
+export declare function createSandbox(config: SandboxConfig): ProcessSandbox;
+/** Create a minimal ToolContext from an AbortSignal (for backward compat) */
+export declare function signalToToolContext(signal?: AbortSignal): ToolContext;
+export declare class ToolSandbox {
+    private readonly config;
+    constructor(config?: SandboxConfig);
+    execute(tool: ToolDefinition, input: unknown, ctx: ToolContext): Promise<unknown>;
+}
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AA6HpE,8DAA8D;AAC9D,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAElC;;;GAGG;AACH,eAAO,MAAM,oBAAoB,2CAA4C,CAAC;AAE9E,4BAA4B;AAC5B,MAAM,WAAW,aAAa;IAC5B,gBAAgB,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,+BAA+B;IAC/B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,2CAA2C;IAC3C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,oCAAoC;IACpC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,6CAA6C;IAC7C,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,iDAAiD;IACjD,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,sCAAsC;AACtC,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACxC,MAAM,EAAE,CAAC,CAAC;IACV,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,0CAA0C;IAC1C,SAAS,CAAC,EAAE;QACV,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAE7B,uCAAuC;IACvC,OAAO,CAAC,OAAO,EAAE;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,GAAG,EAAE,MAAM,CAAC;QACZ,SAAS,EAAE,MAAM,CAAC;QAClB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7B,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GAAG,OAAO,CAAC,aAAa,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IAEjF,yBAAyB;IACzB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AA0PD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,cAAc,CAUnE;AAMD,6EAA6E;AAC7E,wBAAgB,mBAAmB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,WAAW,CAgBrE;AAED,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,GAAE,aAA4C;IAE3E,OAAO,CACX,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,OAAO,CAAC;CAcpB"}