tarsk 0.3.43 → 0.4.4

package/dist/tools/skill-tool.js

@@ -0,0 +1,213 @@
+/**
+ * Skill Script Tool
+ *
+ * Executes scripts from activated skills' scripts/ directories.
+ * Scripts can be written in any supported language (.sh, .py, .js, etc.)
+ */
+import { readdir } from "fs/promises";
+import { join, extname } from "path";
+import { existsSync, statSync } from "fs";
+import { Type } from "@sinclair/typebox";
+import { spawnProcess } from "../core/utils.js";
+/**
+ * Get the interpreter for a script based on its extension
+ */
+function getInterpreter(scriptPath) {
+    const ext = extname(scriptPath);
+    switch (ext) {
+        case ".sh":
+        case ".bash":
+            return { command: "bash", args: [scriptPath] };
+        case ".py":
+            return { command: "python3", args: [scriptPath] };
+        case ".js":
+            return { command: "node", args: [scriptPath] };
+        case ".ts":
+            // Use bun to run TypeScript directly
+            return { command: "bun", args: ["run", scriptPath] };
+        default:
+            // Try to execute directly if it's executable
+            try {
+                const stats = statSync(scriptPath);
+                if (stats.mode & 0o111) {
+                    // File is executable
+                    return { command: scriptPath, args: [] };
+                }
+            }
+            catch {
+                // Ignore stat errors
+            }
+            return null;
+    }
+}
+/**
+ * Execute a skill script
+ */
+async function executeScript(scriptPath, args, cwd, timeout = 30) {
+    const interpreter = getInterpreter(scriptPath);
+    if (!interpreter) {
+        throw new Error(`Unsupported script type: ${scriptPath}`);
+    }
+    return new Promise((resolve, reject) => {
+        const child = spawnProcess(interpreter.command, [...interpreter.args, ...args], {
+            cwd,
+            timeout: timeout * 1000,
+        });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        if (child.stdout) {
+            child.stdout.on("data", (data) => {
+                stdout += data.toString();
+            });
+        }
+        if (child.stderr) {
+            child.stderr.on("data", (data) => {
+                stderr += data.toString();
+            });
+        }
+        const timeoutHandle = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGTERM");
+        }, timeout * 1000);
+        child.on("error", (err) => {
+            clearTimeout(timeoutHandle);
+            reject(err);
+        });
+        child.on("close", (code) => {
+            clearTimeout(timeoutHandle);
+            if (timedOut) {
+                reject(new Error(`Script execution timed out after ${timeout}s`));
+                return;
+            }
+            resolve({ stdout, stderr, exitCode: code });
+        });
+    });
+}
+/**
+ * Schema for skill script tool input
+ */
+const skillScriptSchema = Type.Object({
+    skillName: Type.String({ description: "Name of the skill" }),
+    scriptName: Type.String({ description: "Name of the script to execute (without path)" }),
+    args: Type.Optional(Type.Array(Type.String(), { description: "Arguments to pass to the script" })),
+    timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (default: 30)" })),
+});
+/**
+ * Create a skill script executor tool
+ */
+export function createSkillScriptTool(skills, cwd) {
+    return {
+        name: "execute_skill_script",
+        label: "execute_skill_script",
+        description: "Execute a script from an activated skill. Skills provide executable scripts in their scripts/ directory.",
+        parameters: skillScriptSchema,
+        execute: async (_toolCallId, { skillName, scriptName, args = [], timeout = 30 }) => {
+            // Find the skill
+            const skill = skills.find((s) => s.name === skillName);
+            if (!skill) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Skill not found: ${skillName}. Available skills: ${skills.map((s) => s.name).join(", ")}`,
+                        },
+                    ],
+                    details: undefined,
+                };
+            }
+            // Check if scripts directory exists
+            const scriptsDir = join(skill.skillPath, "scripts");
+            if (!existsSync(scriptsDir)) {
+                return {
+                    content: [
+                        { type: "text", text: `Skill '${skillName}' has no scripts directory` },
+                    ],
+                    details: undefined,
+                };
+            }
+            // Find the script
+            const scriptPath = join(scriptsDir, scriptName);
+            if (!existsSync(scriptPath)) {
+                // List available scripts for better error message
+                try {
+                    const availableScripts = await readdir(scriptsDir);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Script '${scriptName}' not found in skill '${skillName}'. Available scripts: ${availableScripts.join(", ")}`,
+                            },
+                        ],
+                        details: undefined,
+                    };
+                }
+                catch {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Script '${scriptName}' not found in skill '${skillName}'`,
+                            },
+                        ],
+                        details: undefined,
+                    };
+                }
+            }
+            try {
+                const result = await executeScript(scriptPath, args, cwd, timeout);
+                // Format output
+                let output = "";
+                if (result.stdout) {
+                    output += `STDOUT:\n${result.stdout}\n`;
+                }
+                if (result.stderr) {
+                    output += `STDERR:\n${result.stderr}\n`;
+                }
+                output += `Exit code: ${result.exitCode}\n`;
+                return {
+                    content: [{ type: "text", text: output }],
+                    details: undefined,
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Failed to execute script: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                    details: undefined,
+                };
+            }
+        },
+    };
+}
+/**
+ * List all available skill scripts
+ */
+export async function listSkillScripts(skills) {
+    const scripts = [];
+    for (const skill of skills) {
+        const scriptsDir = join(skill.skillPath, "scripts");
+        if (!existsSync(scriptsDir))
+            continue;
+        try {
+            const files = await readdir(scriptsDir);
+            for (const file of files) {
+                const fullPath = join(scriptsDir, file);
+                scripts.push({
+                    skillName: skill.name,
+                    scriptName: file,
+                    path: fullPath,
+                });
+            }
+        }
+        catch (error) {
+            console.error(`Failed to list scripts for skill ${skill.name}:`, error);
+        }
+    }
+    return scripts;
+}
+//# sourceMappingURL=skill-tool.js.map

package/dist/tools/todo.d.ts

@@ -0,0 +1,20 @@
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import { type Static } from "@sinclair/typebox";
+declare const todoSchema: import("@sinclair/typebox").TObject<{
+    action: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"add">, import("@sinclair/typebox").TLiteral<"update">, import("@sinclair/typebox").TLiteral<"list">, import("@sinclair/typebox").TLiteral<"delete">]>;
+    descriptions: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    ids: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    status: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"pending">, import("@sinclair/typebox").TLiteral<"working">, import("@sinclair/typebox").TLiteral<"done">]>>;
+    assignedTo: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export type TodoToolInput = Static<typeof todoSchema>;
+export declare function createTodoTool(threadId: string): AgentTool<typeof todoSchema>;
+export declare const todoTool: AgentTool<import("@sinclair/typebox").TObject<{
+    action: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"add">, import("@sinclair/typebox").TLiteral<"update">, import("@sinclair/typebox").TLiteral<"list">, import("@sinclair/typebox").TLiteral<"delete">]>;
+    descriptions: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    ids: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    status: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"pending">, import("@sinclair/typebox").TLiteral<"working">, import("@sinclair/typebox").TLiteral<"done">]>>;
+    assignedTo: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>, any>;
+export {};
+//# sourceMappingURL=todo.d.ts.map

package/dist/tools/todo.js

@@ -0,0 +1,168 @@
+import { Type } from "@sinclair/typebox";
+import { getDatabase } from "../database/database.js";
+import { fetchAllTodos, addTodos } from "../features/todos/todos.database.js";
+const todoSchema = Type.Object({
+    action: Type.Union([Type.Literal("add"), Type.Literal("update"), Type.Literal("list"), Type.Literal("delete")], {
+        description: "Operation to perform: 'add' creates new items, 'update' changes status, 'list' returns all items, 'delete' removes items.",
+    }),
+    descriptions: Type.Optional(Type.Array(Type.String(), {
+        description: "Todo item descriptions. Required for 'add'. Provide one or more descriptions to create multiple items at once.",
+    })),
+    ids: Type.Optional(Type.Array(Type.String(), {
+        description: "Todo item IDs. Required for 'update' and 'delete'. Provide one or more IDs to update or delete multiple items at once.",
+    })),
+    status: Type.Optional(Type.Union([Type.Literal("pending"), Type.Literal("working"), Type.Literal("done")], {
+        description: "New status for 'update'. Applied to all specified IDs. 'pending' = not started, 'working' = in progress, 'done' = complete.",
+    })),
+    assignedTo: Type.Optional(Type.String({
+        description: "Who items are assigned to. Defaults to 'agent'. Applied to all specified items.",
+    })),
+});
+export function createTodoTool(threadId) {
+    return {
+        name: "todo",
+        label: "todo",
+        description: "Manage todo items to break down the current task into 2 more items. Use 'add' to create items when planning work, 'update' to change an item's status as you progress (pending → working → done), 'list' to see all current items, and 'delete' to remove one. Marking an item done does not end the conversation — continue working on remaining items. Call 'list' at the end so the user sees a completion checklist.",
+        parameters: todoSchema,
+        execute: async (_toolCallId, { action, descriptions, ids, status, assignedTo }) => {
+            const db = await getDatabase();
+            const now = new Date().toISOString();
+            switch (action) {
+                case "add": {
+                    const validDescriptions = descriptions?.filter((d) => d.trim());
+                    if (!validDescriptions?.length) {
+                        return {
+                            content: [
+                                { type: "text", text: "Error: descriptions is required for 'add'" },
+                            ],
+                            details: undefined,
+                        };
+                    }
+                    const todosAfterAdd = await addTodos(threadId, validDescriptions, assignedTo ?? "agent");
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({ todos: todosAfterAdd }),
+                            },
+                        ],
+                        details: undefined,
+                    };
+                }
+                case "update": {
+                    if (!ids?.length) {
+                        return {
+                            content: [{ type: "text", text: "Error: ids is required for 'update'" }],
+                            details: undefined,
+                        };
+                    }
+                    const notFound = [];
+                    for (const id of ids) {
+                        const existing = await db.execute({
+                            sql: `SELECT id FROM todos WHERE id = ? AND threadId = ?`,
+                            args: [id, threadId],
+                        });
+                        if (existing.rows.length === 0) {
+                            notFound.push(id);
+                            continue;
+                        }
+                        const updates = [];
+                        const args = [];
+                        if (status) {
+                            updates.push("status = ?");
+                            args.push(status);
+                        }
+                        if (assignedTo !== undefined) {
+                            updates.push("assignedTo = ?");
+                            args.push(assignedTo);
+                        }
+                        updates.push("updatedAt = ?");
+                        args.push(now);
+                        args.push(id, threadId);
+                        await db.execute({
+                            sql: `UPDATE todos SET ${updates.join(", ")} WHERE id = ? AND threadId = ?`,
+                            args,
+                        });
+                    }
+                    if (notFound.length > 0) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `Error: todos not found: ${notFound.join(", ")}`,
+                                },
+                            ],
+                            details: undefined,
+                        };
+                    }
+                    const todosAfterUpdate = await fetchAllTodos(db, threadId);
+                    // If all items are now done, delete them all
+                    const allDone = todosAfterUpdate.length > 0 && todosAfterUpdate.every((t) => t.status === "done");
+                    if (allDone) {
+                        await db.execute({
+                            sql: `DELETE FROM todos WHERE threadId = ?`,
+                            args: [threadId],
+                        });
+                    }
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({ todos: allDone ? [] : todosAfterUpdate }),
+                            },
+                        ],
+                        details: undefined,
+                    };
+                }
+                case "list": {
+                    const todos = await fetchAllTodos(db, threadId);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({ todos }),
+                            },
+                        ],
+                        details: undefined,
+                    };
+                }
+                case "delete": {
+                    if (!ids?.length) {
+                        return {
+                            content: [{ type: "text", text: "Error: ids is required for 'delete'" }],
+                            details: undefined,
+                        };
+                    }
+                    for (const id of ids) {
+                        await db.execute({
+                            sql: `DELETE FROM todos WHERE id = ? AND threadId = ?`,
+                            args: [id, threadId],
+                        });
+                    }
+                    const todosAfterDelete = await fetchAllTodos(db, threadId);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({ todos: todosAfterDelete }),
+                            },
+                        ],
+                        details: undefined,
+                    };
+                }
+                default:
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Unknown action: ${String(action)}`,
+                            },
+                        ],
+                        details: undefined,
+                    };
+            }
+        },
+    };
+}
+export const todoTool = createTodoTool("");
+//# sourceMappingURL=todo.js.map

package/dist/tools/tool-helpers.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Tool helper utilities for reducing duplication in tool implementations
+ *
+ * Provides:
+ * - Abort signal handling wrapper to eliminate boilerplate in tool execute functions
+ * - Tool result formatting utilities for consistent output across tools
+ */
+/**
+ * Wraps an async operation with abort signal handling
+ *
+ * Eliminates the need for each tool to implement the same abort signal
+ * setup, cleanup, and error handling logic.
+ *
+ * @param signal - Optional abort signal from the tool execution
+ * @param operation - The async operation to perform, receives an abort check function
+ * @returns Promise that resolves with the operation result or rejects if aborted
+ *
+ * @example
+ * ```typescript
+ * execute: async (_toolCallId, { path, content }, signal) => {
+ *   return withAbortSignal(signal, async (isAborted) => {
+ *     await ops.mkdir(dir);
+ *     if (isAborted()) return { content: [], details: undefined };
+ *     await ops.writeFile(absolutePath, content);
+ *     return {
+ *       content: [{ type: "text", text: `Successfully wrote ${content.length} bytes to ${path}` }],
+ *       details: undefined,
+ *     };
+ *   });
+ * }
+ * ```
+ */
+export declare function withAbortSignal<T>(signal: AbortSignal | undefined, operation: (abortCheck: () => boolean) => Promise<T>): Promise<T>;
+/**
+ * Represents a notice message to be appended to tool output
+ */
+export interface ToolNotice {
+    /** Human-readable notice message */
+    message: string;
+    /** Key for the details object */
+    detailKey: string;
+    /** Value to include in details */
+    detailValue: unknown;
+}
+/**
+ * Formats tool output with optional notices appended
+ *
+ * Creates a consistent format for tool results that include notices
+ * (e.g., truncation warnings, result limits reached) and details metadata.
+ *
+ * @param baseOutput - The primary tool output text
+ * @param notices - Array of notices to append to the output
+ * @returns Object containing formatted output and optional details
+ *
+ * @example
+ * ```typescript
+ * const notices: ToolNotice[] = [];
+ *
+ * if (resultLimitReached) {
+ *   notices.push({
+ *     message: `${effectiveLimit} results limit reached. Use limit=${effectiveLimit * 2} for more`,
+ *     detailKey: 'resultLimitReached',
+ *     detailValue: effectiveLimit,
+ *   });
+ * }
+ *
+ * const { output, details } = formatToolOutput(truncation.content, notices);
+ * return {
+ *   content: [{ type: "text", text: output }],
+ *   details,
+ * };
+ * ```
+ */
+export declare function formatToolOutput(baseOutput: string, notices: ToolNotice[]): {
+    output: string;
+    details: Record<string, unknown> | undefined;
+};
+//# sourceMappingURL=tool-helpers.d.ts.map

package/dist/tools/tool-helpers.js

@@ -0,0 +1,109 @@
+/**
+ * Tool helper utilities for reducing duplication in tool implementations
+ *
+ * Provides:
+ * - Abort signal handling wrapper to eliminate boilerplate in tool execute functions
+ * - Tool result formatting utilities for consistent output across tools
+ */
+/**
+ * Wraps an async operation with abort signal handling
+ *
+ * Eliminates the need for each tool to implement the same abort signal
+ * setup, cleanup, and error handling logic.
+ *
+ * @param signal - Optional abort signal from the tool execution
+ * @param operation - The async operation to perform, receives an abort check function
+ * @returns Promise that resolves with the operation result or rejects if aborted
+ *
+ * @example
+ * ```typescript
+ * execute: async (_toolCallId, { path, content }, signal) => {
+ *   return withAbortSignal(signal, async (isAborted) => {
+ *     await ops.mkdir(dir);
+ *     if (isAborted()) return { content: [], details: undefined };
+ *     await ops.writeFile(absolutePath, content);
+ *     return {
+ *       content: [{ type: "text", text: `Successfully wrote ${content.length} bytes to ${path}` }],
+ *       details: undefined,
+ *     };
+ *   });
+ * }
+ * ```
+ */
+export async function withAbortSignal(signal, operation) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new Error("Operation aborted"));
+            return;
+        }
+        let aborted = false;
+        const onAbort = () => {
+            aborted = true;
+            reject(new Error("Operation aborted"));
+        };
+        if (signal) {
+            signal.addEventListener("abort", onAbort, { once: true });
+        }
+        const cleanup = () => {
+            if (signal)
+                signal.removeEventListener("abort", onAbort);
+        };
+        const abortCheck = () => aborted;
+        operation(abortCheck)
+            .then((result) => {
+            cleanup();
+            if (!aborted)
+                resolve(result);
+        })
+            .catch((error) => {
+            cleanup();
+            if (!aborted)
+                reject(error);
+        });
+    });
+}
+/**
+ * Formats tool output with optional notices appended
+ *
+ * Creates a consistent format for tool results that include notices
+ * (e.g., truncation warnings, result limits reached) and details metadata.
+ *
+ * @param baseOutput - The primary tool output text
+ * @param notices - Array of notices to append to the output
+ * @returns Object containing formatted output and optional details
+ *
+ * @example
+ * ```typescript
+ * const notices: ToolNotice[] = [];
+ *
+ * if (resultLimitReached) {
+ *   notices.push({
+ *     message: `${effectiveLimit} results limit reached. Use limit=${effectiveLimit * 2} for more`,
+ *     detailKey: 'resultLimitReached',
+ *     detailValue: effectiveLimit,
+ *   });
+ * }
+ *
+ * const { output, details } = formatToolOutput(truncation.content, notices);
+ * return {
+ *   content: [{ type: "text", text: output }],
+ *   details,
+ * };
+ * ```
+ */
+export function formatToolOutput(baseOutput, notices) {
+    let output = baseOutput;
+    const details = {};
+    if (notices.length > 0) {
+        const messages = notices.map((n) => n.message);
+        output += `\n\n[${messages.join(". ")}]`;
+        for (const notice of notices) {
+            details[notice.detailKey] = notice.detailValue;
+        }
+    }
+    return {
+        output,
+        details: Object.keys(details).length > 0 ? details : undefined,
+    };
+}
+//# sourceMappingURL=tool-helpers.js.map

package/dist/tools/truncate.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared truncation utilities for tool outputs.
+ */
+export declare const DEFAULT_MAX_LINES = 2000;
+export declare const DEFAULT_MAX_BYTES: number;
+export declare const GREP_MAX_LINE_LENGTH = 500;
+export interface TruncationResult {
+    content: string;
+    truncated: boolean;
+    truncatedBy: "lines" | "bytes" | null;
+    totalLines: number;
+    totalBytes: number;
+    outputLines: number;
+    outputBytes: number;
+    lastLinePartial: boolean;
+    firstLineExceedsLimit: boolean;
+    maxLines: number;
+    maxBytes: number;
+}
+export interface TruncationOptions {
+    maxLines?: number;
+    maxBytes?: number;
+}
+export declare function formatSize(bytes: number): string;
+export declare function truncateHead(content: string, options?: TruncationOptions): TruncationResult;
+export declare function truncateTail(content: string, options?: TruncationOptions): TruncationResult;
+export declare function truncateLine(line: string, maxChars?: number): {
+    text: string;
+    wasTruncated: boolean;
+};
+//# sourceMappingURL=truncate.d.ts.map