@polpo-ai/tools 0.2.4

package/dist/memory-tools.js

@@ -0,0 +1,104 @@
+/**
+ * Memory tools for agents — scoped to a single agent's private memory.
+ *
+ * These tools let an agent read and write its own persistent memory
+ * during direct-chat sessions. The agent scope is baked in at creation
+ * time so the agent cannot access other agents' or shared memory.
+ */
+import { Type } from "@sinclair/typebox";
+import { agentMemoryScope } from "@polpo-ai/core";
+// ── Tool names ──
+export const ALL_MEMORY_TOOL_NAMES = [
+    "memory_get",
+    "memory_save",
+    "memory_append",
+    "memory_update",
+];
+// ── Schemas ──
+const MemoryGetSchema = Type.Object({});
+const MemorySaveSchema = Type.Object({
+    content: Type.String({ description: "The full memory content to save (overwrites existing)" }),
+});
+const MemoryAppendSchema = Type.Object({
+    text: Type.String({ description: "Text to append to your memory" }),
+});
+const MemoryUpdateSchema = Type.Object({
+    old_text: Type.String({ description: "Exact substring in your memory to find" }),
+    new_text: Type.String({ description: "Replacement text" }),
+});
+// ── Factory ──
+/**
+ * Create memory tools for an agent, scoped to that agent's private memory.
+ *
+ * @param store   The MemoryStore instance
+ * @param agent   The agent name — tools will only access `agent:<name>` scope
+ */
+export function createMemoryTools(store, agent) {
+    const scope = agentMemoryScope(agent);
+    const memoryGet = {
+        name: "memory_get",
+        label: "Read Memory",
+        description: "Read your persistent memory. This memory survives across sessions " +
+            "and contains your personal notes, learnings, and context. " +
+            "Returns empty string if you have no saved memory yet.",
+        parameters: MemoryGetSchema,
+        async execute() {
+            const content = await store.get(scope);
+            return {
+                content: [{ type: "text", text: content || "(no memory saved yet)" }],
+                details: { scope },
+            };
+        },
+    };
+    const memorySave = {
+        name: "memory_save",
+        label: "Save Memory",
+        description: "Overwrite your entire persistent memory with new content. " +
+            "Use this when you want to restructure or rewrite your memory completely. " +
+            "For adding a single note, prefer memory_append instead.",
+        parameters: MemorySaveSchema,
+        async execute(_toolCallId, params) {
+            await store.save(params.content, scope);
+            return {
+                content: [{ type: "text", text: `Memory saved (${params.content.length} chars).` }],
+                details: { scope, chars: params.content.length },
+            };
+        },
+    };
+    const memoryAppend = {
+        name: "memory_append",
+        label: "Append to Memory",
+        description: "Append a timestamped line to your persistent memory. " +
+            "Good for quick notes, learnings, or observations you want to remember.",
+        parameters: MemoryAppendSchema,
+        async execute(_toolCallId, params) {
+            await store.append(params.text, scope);
+            return {
+                content: [{ type: "text", text: `Appended to memory: "${params.text}"` }],
+                details: { scope },
+            };
+        },
+    };
+    const memoryUpdate = {
+        name: "memory_update",
+        label: "Update Memory",
+        description: "Find and replace a specific section in your memory. " +
+            "The old_text must be an exact unique substring of your current memory.",
+        parameters: MemoryUpdateSchema,
+        async execute(_toolCallId, params) {
+            const result = await store.update(params.old_text, params.new_text, scope);
+            if (result === true) {
+                return {
+                    content: [{ type: "text", text: "Memory updated successfully." }],
+                    details: { scope, success: true },
+                };
+            }
+            return {
+                content: [{ type: "text", text: `Failed to update memory: ${result}` }],
+                details: { scope, success: false },
+            };
+        },
+    };
+    return [memoryGet, memorySave, memoryAppend, memoryUpdate];
+}
+//# sourceMappingURL=memory-tools.js.map

package/dist/memory-tools.js.map

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

package/dist/outcome-tools.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Outcome registration tool.
+ *
+ * The ONLY mechanism for agents to declare task outcomes. Producing a file
+ * (via write, pdf_create, bash, etc.) does NOT auto-register it as an
+ * outcome — the agent must explicitly call register_outcome for every
+ * deliverable artifact.
+ *
+ * Supports files, media, text, URLs, and structured JSON data.
+ * The tool validates that file outcomes actually exist on disk before
+ * registering them.
+ */
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+export type OutcomeToolName = "register_outcome";
+export declare const ALL_OUTCOME_TOOL_NAMES: OutcomeToolName[];
+/**
+ * Create outcome registration tools.
+ *
+ * @param cwd - Working directory
+ * @param allowedPaths - Sandbox paths
+ * @param allowedTools - Optional filter
+ * @param outputDir - Per-task output directory for deliverables
+ */
+export declare function createOutcomeTools(cwd: string, allowedPaths?: string[], allowedTools?: string[], outputDir?: string): AgentTool<any>[];
+//# sourceMappingURL=outcome-tools.d.ts.map

package/dist/outcome-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outcome-tools.d.ts","sourceRoot":"","sources":["../src/outcome-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAiK7D,MAAM,MAAM,eAAe,GAAG,kBAAkB,CAAC;AAEjD,eAAO,MAAM,sBAAsB,EAAE,eAAe,EAAyB,CAAC;AAE9E;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,EAAE,CAYtI"}

package/dist/outcome-tools.js

@@ -0,0 +1,191 @@
+/**
+ * Outcome registration tool.
+ *
+ * The ONLY mechanism for agents to declare task outcomes. Producing a file
+ * (via write, pdf_create, bash, etc.) does NOT auto-register it as an
+ * outcome — the agent must explicitly call register_outcome for every
+ * deliverable artifact.
+ *
+ * Supports files, media, text, URLs, and structured JSON data.
+ * The tool validates that file outcomes actually exist on disk before
+ * registering them.
+ */
+import { existsSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { Type } from "@sinclair/typebox";
+import { resolveAllowedPaths, assertPathAllowed } from "./path-sandbox.js";
+// ─── Tool: register_outcome ───
+const RegisterOutcomeSchema = Type.Object({
+    type: Type.Union([
+        Type.Literal("file"),
+        Type.Literal("media"),
+        Type.Literal("text"),
+        Type.Literal("url"),
+        Type.Literal("json"),
+    ], { description: "Outcome type. 'file' for documents (PDF, Excel, DOCX, HTML, archives). 'media' for images/audio/video. 'text' for inline text content. 'url' for links. 'json' for structured data." }),
+    label: Type.String({ description: "Human-readable label for this outcome (e.g. 'Q4 Sales Report', 'Architecture Diagram', 'API Response')" }),
+    path: Type.Optional(Type.String({ description: "File path (required for type 'file' or 'media'). Relative paths resolved from cwd." })),
+    text: Type.Optional(Type.String({ description: "Text content (for type 'text'). The actual content to include in the outcome." })),
+    url: Type.Optional(Type.String({ description: "URL (for type 'url'). Link to external resource." })),
+    data: Type.Optional(Type.Unknown({ description: "Structured data (for type 'json'). Any JSON-serializable value." })),
+    tags: Type.Optional(Type.Array(Type.String(), { description: "Optional tags for categorization (e.g. ['report', 'quarterly'])" })),
+});
+/** MIME type inference from file extension. */
+const EXT_MIME = {
+    ".mp3": "audio/mpeg", ".wav": "audio/wav", ".ogg": "audio/ogg", ".flac": "audio/flac", ".m4a": "audio/mp4",
+    ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".gif": "image/gif", ".svg": "image/svg+xml",
+    ".mp4": "video/mp4", ".webm": "video/webm", ".mov": "video/quicktime",
+    ".pdf": "application/pdf",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".xls": "application/vnd.ms-excel",
+    ".csv": "text/csv",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".doc": "application/msword",
+    ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    ".json": "application/json",
+    ".txt": "text/plain",
+    ".html": "text/html", ".htm": "text/html",
+    ".zip": "application/zip",
+    ".tar": "application/x-tar",
+    ".gz": "application/gzip",
+};
+function guessMime(filePath) {
+    const dot = filePath.lastIndexOf(".");
+    if (dot === -1)
+        return undefined;
+    return EXT_MIME[filePath.slice(dot).toLowerCase()];
+}
+function createRegisterOutcomeTool(cwd, sandbox, outputDir) {
+    // Use outputDir in examples when available so the agent naturally writes there
+    const exampleDir = outputDir ? outputDir.replace(/\/$/, "") : "output";
+    return {
+        name: "register_outcome",
+        label: "Register Outcome",
+        description: "Register a file, text, URL, or data as a task outcome. This is the ONLY way to declare " +
+            "deliverables — producing files does NOT auto-register them. You MUST call this tool for " +
+            "every artifact that should appear in notifications and the task record.\n\n" +
+            (outputDir ? `Your task output directory is: ${outputDir}\nWrite deliverable files there before registering them.\n\n` : "") +
+            "Examples:\n" +
+            `- After creating a PDF: register_outcome({type: 'file', label: 'Sales Report', path: '${exampleDir}/report.pdf'})\n` +
+            `- After generating an image: register_outcome({type: 'media', label: 'Revenue Chart', path: '${exampleDir}/revenue.png'})\n` +
+            "- To share a deploy URL: register_outcome({type: 'url', label: 'Staging Deploy', url: 'https://staging.example.com'})\n" +
+            "- To include analysis results: register_outcome({type: 'text', label: 'Summary', text: 'Revenue increased 23%...'})\n" +
+            "- To return structured data: register_outcome({type: 'json', label: 'Metrics', data: {revenue: 1234}})",
+        parameters: RegisterOutcomeSchema,
+        async execute(_id, params) {
+            const { type, label } = params;
+            // Validate type-specific fields
+            if ((type === "file" || type === "media") && !params.path) {
+                return {
+                    content: [{ type: "text", text: `Error: 'path' is required for outcome type '${type}'` }],
+                    details: { error: "missing_path" },
+                };
+            }
+            if (type === "text" && !params.text) {
+                return {
+                    content: [{ type: "text", text: `Error: 'text' is required for outcome type 'text'` }],
+                    details: { error: "missing_text" },
+                };
+            }
+            if (type === "url" && !params.url) {
+                return {
+                    content: [{ type: "text", text: `Error: 'url' is required for outcome type 'url'` }],
+                    details: { error: "missing_url" },
+                };
+            }
+            if (type === "json" && params.data === undefined) {
+                return {
+                    content: [{ type: "text", text: `Error: 'data' is required for outcome type 'json'` }],
+                    details: { error: "missing_data" },
+                };
+            }
+            // For file/media outcomes, validate the file exists
+            let filePath;
+            let fileSize;
+            let mimeType;
+            if (params.path) {
+                filePath = resolve(cwd, params.path);
+                assertPathAllowed(filePath, sandbox, "register_outcome");
+                if (!existsSync(filePath)) {
+                    return {
+                        content: [{ type: "text", text: `Error: file not found: ${filePath}` }],
+                        details: { error: "file_not_found", path: filePath },
+                    };
+                }
+                try {
+                    const stats = statSync(filePath);
+                    fileSize = stats.size;
+                }
+                catch {
+                    // stat failed — file may have been deleted between exists check and stat
+                }
+                mimeType = guessMime(filePath);
+            }
+            // Build the details object that engine.ts collectOutcome() will consume.
+            // The key fields are: path, outcomeType, outcomeLabel, outcomeTags,
+            // outcomeMimeType, outcomeSize, outcomeText, outcomeUrl, outcomeData.
+            const details = {
+                path: filePath,
+                outcomeType: type,
+                outcomeLabel: label,
+            };
+            if (mimeType)
+                details.outcomeMimeType = mimeType;
+            if (fileSize !== undefined)
+                details.outcomeSize = fileSize;
+            if (params.text)
+                details.outcomeText = params.text;
+            if (params.url)
+                details.outcomeUrl = params.url;
+            if (params.data !== undefined)
+                details.outcomeData = params.data;
+            if (params.tags)
+                details.outcomeTags = params.tags;
+            // Build human-readable confirmation
+            const parts = [`Outcome registered: "${label}" (${type})`];
+            if (filePath)
+                parts.push(`  Path: ${filePath}`);
+            if (mimeType)
+                parts.push(`  MIME: ${mimeType}`);
+            if (fileSize !== undefined)
+                parts.push(`  Size: ${formatBytes(fileSize)}`);
+            if (params.url)
+                parts.push(`  URL: ${params.url}`);
+            if (params.text)
+                parts.push(`  Text: ${params.text.slice(0, 100)}${params.text.length > 100 ? "..." : ""}`);
+            if (params.tags?.length)
+                parts.push(`  Tags: ${params.tags.join(", ")}`);
+            return {
+                content: [{ type: "text", text: parts.join("\n") }],
+                details,
+            };
+        },
+    };
+}
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+export const ALL_OUTCOME_TOOL_NAMES = ["register_outcome"];
+/**
+ * Create outcome registration tools.
+ *
+ * @param cwd - Working directory
+ * @param allowedPaths - Sandbox paths
+ * @param allowedTools - Optional filter
+ * @param outputDir - Per-task output directory for deliverables
+ */
+export function createOutcomeTools(cwd, allowedPaths, allowedTools, outputDir) {
+    const sandbox = resolveAllowedPaths(cwd, allowedPaths);
+    const factories = {
+        register_outcome: () => createRegisterOutcomeTool(cwd, sandbox, outputDir),
+    };
+    const names = allowedTools
+        ? ALL_OUTCOME_TOOL_NAMES.filter(n => allowedTools.some(a => a.toLowerCase() === n))
+        : ALL_OUTCOME_TOOL_NAMES;
+    return names.map(n => factories[n]());
+}
+//# sourceMappingURL=outcome-tools.js.map

package/dist/outcome-tools.js.map

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

package/dist/path-sandbox.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Path sandboxing for agent filesystem access.
+ *
+ * When an agent has `allowedPaths` configured, all file tool operations
+ * (read/write/edit/glob/grep/ls) validate that resolved paths fall within
+ * the allowed directories. This prevents agents from escaping their workspace
+ * via absolute paths or `../` traversal.
+ *
+ * The bash tool cannot be fully sandboxed at this level (arbitrary shell commands),
+ * but its cwd is set to the agent's primary allowed path.
+ */
+/**
+ * Resolve allowedPaths to absolute paths, normalizing relative paths against cwd.
+ * If no allowedPaths are configured, defaults to [cwd] (the project workDir).
+ */
+export declare function resolveAllowedPaths(cwd: string, allowedPaths?: string[]): string[];
+/**
+ * Check whether a resolved absolute path falls within any of the allowed directories.
+ * Uses path prefix matching with separator awareness to prevent partial matches
+ * (e.g. `/home/user/project-evil` should NOT match `/home/user/project`).
+ */
+export declare function isPathAllowed(filePath: string, allowedPaths: string[]): boolean;
+/**
+ * Validate a path and throw a descriptive error if it's outside the sandbox.
+ * Call this in every file tool's execute() before performing the operation.
+ */
+export declare function assertPathAllowed(filePath: string, allowedPaths: string[], toolName: string): void;
+//# sourceMappingURL=path-sandbox.d.ts.map

package/dist/path-sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-sandbox.d.ts","sourceRoot":"","sources":["../src/path-sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAKlF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAa/E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAOlG"}

package/dist/path-sandbox.js

@@ -0,0 +1,58 @@
+/**
+ * Path sandboxing for agent filesystem access.
+ *
+ * When an agent has `allowedPaths` configured, all file tool operations
+ * (read/write/edit/glob/grep/ls) validate that resolved paths fall within
+ * the allowed directories. This prevents agents from escaping their workspace
+ * via absolute paths or `../` traversal.
+ *
+ * The bash tool cannot be fully sandboxed at this level (arbitrary shell commands),
+ * but its cwd is set to the agent's primary allowed path.
+ */
+import { resolve, sep } from "node:path";
+import { realpathSync } from "node:fs";
+/**
+ * Resolve allowedPaths to absolute paths, normalizing relative paths against cwd.
+ * If no allowedPaths are configured, defaults to [cwd] (the project workDir).
+ */
+export function resolveAllowedPaths(cwd, allowedPaths) {
+    if (!allowedPaths || allowedPaths.length === 0) {
+        return [resolve(cwd)];
+    }
+    return allowedPaths.map((p) => resolve(cwd, p));
+}
+/**
+ * Check whether a resolved absolute path falls within any of the allowed directories.
+ * Uses path prefix matching with separator awareness to prevent partial matches
+ * (e.g. `/home/user/project-evil` should NOT match `/home/user/project`).
+ */
+export function isPathAllowed(filePath, allowedPaths) {
+    let resolved = resolve(filePath);
+    // Resolve symlinks to prevent symlink-based sandbox escape
+    try {
+        resolved = realpathSync(resolved);
+    }
+    catch { /* file may not exist yet — use logical path */ }
+    for (const allowed of allowedPaths) {
+        const normalizedAllowed = resolve(allowed);
+        // Exact match
+        if (resolved === normalizedAllowed)
+            return true;
+        // Prefix match with separator (e.g. /foo/bar/ is prefix of /foo/bar/baz)
+        const prefix = normalizedAllowed.endsWith(sep) ? normalizedAllowed : normalizedAllowed + sep;
+        if (resolved.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
+/**
+ * Validate a path and throw a descriptive error if it's outside the sandbox.
+ * Call this in every file tool's execute() before performing the operation.
+ */
+export function assertPathAllowed(filePath, allowedPaths, toolName) {
+    if (!isPathAllowed(filePath, allowedPaths)) {
+        const dirs = allowedPaths.join(", ");
+        throw new Error(`[sandbox] ${toolName}: access denied — "${filePath}" is outside allowed directories [${dirs}]`);
+    }
+}
+//# sourceMappingURL=path-sandbox.js.map

package/dist/path-sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-sandbox.js","sourceRoot":"","sources":["../src/path-sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAW,EAAE,YAAuB;IACtE,IAAI,CAAC,YAAY,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/C,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;AAClD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,QAAgB,EAAE,YAAsB;IACpE,IAAI,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACjC,2DAA2D;IAC3D,IAAI,CAAC;QAAC,QAAQ,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC,CAAC,+CAA+C,CAAC,CAAC;IACpG,KAAK,MAAM,OAAO,IAAI,YAAY,EAAE,CAAC;QACnC,MAAM,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QAC3C,cAAc;QACd,IAAI,QAAQ,KAAK,iBAAiB;YAAE,OAAO,IAAI,CAAC;QAChD,yEAAyE;QACzE,MAAM,MAAM,GAAG,iBAAiB,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,iBAAiB,GAAG,GAAG,CAAC;QAC7F,IAAI,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,OAAO,IAAI,CAAC;IAC/C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,YAAsB,EAAE,QAAgB;IAC1F,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,YAAY,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrC,MAAM,IAAI,KAAK,CACb,aAAa,QAAQ,sBAAsB,QAAQ,qCAAqC,IAAI,GAAG,CAChG,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/pdf-tools.d.ts

@@ -0,0 +1,25 @@
+/**
+ * PDF tools for document operations.
+ *
+ * Provides tools for agents to:
+ * - Read text from PDF files
+ * - Create new PDF documents with text, images, and pages
+ * - Merge multiple PDFs into one
+ * - Extract pages from a PDF
+ * - Get PDF metadata (pages, title, author, etc.)
+ *
+ * Uses `pdf-lib` for creation/manipulation and a built-in text extractor.
+ * All file operations enforce path sandboxing.
+ */
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+export type PdfToolName = "pdf_read" | "pdf_create" | "pdf_merge" | "pdf_info";
+export declare const ALL_PDF_TOOL_NAMES: PdfToolName[];
+/**
+ * Create PDF tools.
+ *
+ * @param cwd - Working directory
+ * @param allowedPaths - Sandbox paths
+ * @param allowedTools - Optional filter
+ */
+export declare function createPdfTools(cwd: string, allowedPaths?: string[], allowedTools?: string[]): AgentTool<any>[];
+//# sourceMappingURL=pdf-tools.d.ts.map

package/dist/pdf-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pdf-tools.d.ts","sourceRoot":"","sources":["../src/pdf-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAmB,MAAM,6BAA6B,CAAC;AA4W9E,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,YAAY,GAAG,WAAW,GAAG,UAAU,CAAC;AAE/E,eAAO,MAAM,kBAAkB,EAAE,WAAW,EAAwD,CAAC;AAErG;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC,GAAG,CAAC,EAAE,CAe9G"}