tarsk 0.3.43 → 0.4.4

package/dist/tools/agent-tool.js

@@ -0,0 +1,131 @@
+/**
+ * Agent Tool
+ *
+ * Allows the running agent to spawn focused subagents for isolated subtasks.
+ * Subagents have their own execution context and controlled tool access.
+ *
+ * Inspired by VS Code Copilot's subagent model:
+ * https://code.visualstudio.com/docs/copilot/agents/subagents
+ */
+import { Type } from "@sinclair/typebox";
+import { executeSubagent } from "../agent/agent.subagent-executor.js";
+/** Maximum subagent nesting depth (enforced by the caller via tool registration) */
+export const MAX_SUBAGENT_DEPTH = 2;
+const agentToolSchema = Type.Object({
+    prompt: Type.String({ description: "The task or question for the subagent to work on" }),
+    agentName: Type.Optional(Type.String({
+        description: "Name of a defined agent (from AGENT.md) to use. If omitted, a general-purpose subagent is created.",
+    })),
+    description: Type.Optional(Type.String({
+        description: "A short (3-5 word) label describing what the subagent will do",
+    })),
+});
+/**
+ * Filter a base tool set to only tools whose names appear in the whitelist.
+ * Returns all tools if allowedToolNames is undefined/empty.
+ */
+function filterTools(baseTools, allowedToolNames) {
+    if (!allowedToolNames || !allowedToolNames.trim())
+        return baseTools;
+    const allowed = new Set(allowedToolNames
+        .split(/\s+/)
+        .map((s) => s.trim())
+        .filter(Boolean));
+    return baseTools.filter((t) => allowed.has(t.name));
+}
+/**
+ * Create the `agent` tool that allows the running agent to spawn subagents.
+ *
+ * @param options - Configuration including agents list, tools, metadata manager, etc.
+ * @returns AgentTool for registration with the Pi agent
+ */
+export function createAgentTool(options) {
+    const { agents, baseTools, metadataManager, parentModel, parentProvider, defaultSystemPrompt, onEvent, signal, } = options;
+    return {
+        name: "agent",
+        label: "agent",
+        description: "Launch a specialized subagent to handle a focused subtask in an isolated context. " +
+            "The subagent runs autonomously and returns its result. " +
+            "Use this to delegate research, analysis, or parallel work without polluting the current context. " +
+            "If agentName is provided, that agent's system prompt and tool restrictions are applied.",
+        parameters: agentToolSchema,
+        execute: async (_toolCallId, { prompt, agentName, description }) => {
+            // Resolve agent definition if named
+            const agentDef = agentName
+                ? agents.find((a) => a.name === agentName && !a.disableModelInvocation)
+                : undefined;
+            if (agentName && !agentDef) {
+                const available = agents
+                    .filter((a) => !a.disableModelInvocation)
+                    .map((a) => a.name)
+                    .join(", ");
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Agent '${agentName}' not found or is not invocable. Available agents: ${available || "none"}`,
+                        },
+                    ],
+                    details: undefined,
+                };
+            }
+            const label = description ?? agentName ?? "subagent";
+            const systemPrompt = agentDef?.systemPrompt ?? defaultSystemPrompt;
+            const model = agentDef?.model ?? parentModel;
+            const provider = agentDef?.provider ?? parentProvider;
+            const subTools = filterTools(baseTools, agentDef?.tools);
+            console.log(`[agent-tool] Spawning subagent '${label}' with model=${model}, tools=${subTools.map((t) => t.name).join(",")}`);
+            // Emit subagent_start so the UI can render a collapsible block
+            onEvent({
+                type: "subagent_start",
+                subagentName: label,
+                subagentDescription: agentDef?.description,
+                subagentPrompt: prompt,
+            });
+            let result = "";
+            try {
+                result = await executeSubagent({
+                    prompt,
+                    systemPrompt,
+                    tools: subTools,
+                    model,
+                    provider,
+                    metadataManager,
+                    onEvent: (event) => {
+                        // Wrap nested events in subagent_event envelope
+                        onEvent({
+                            type: "subagent_event",
+                            subagentName: label,
+                            subagentEvent: event,
+                        });
+                    },
+                    signal,
+                });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                console.error(`[agent-tool] Subagent '${label}' failed:`, message);
+                onEvent({
+                    type: "subagent_complete",
+                    subagentName: label,
+                    subagentResult: `Error: ${message}`,
+                });
+                return {
+                    content: [{ type: "text", text: `Subagent failed: ${message}` }],
+                    details: undefined,
+                };
+            }
+            onEvent({
+                type: "subagent_complete",
+                subagentName: label,
+                subagentResult: result,
+            });
+            console.log(`[agent-tool] Subagent '${label}' completed, result length=${result.length}`);
+            return {
+                content: [{ type: "text", text: result || "(subagent produced no output)" }],
+                details: undefined,
+            };
+        },
+    };
+}
+//# sourceMappingURL=agent-tool.js.map

package/dist/tools/ask-user.d.ts

@@ -0,0 +1,25 @@
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import { type Static } from "@sinclair/typebox";
+declare const askUserSchema: import("@sinclair/typebox").TObject<{
+    question: import("@sinclair/typebox").TString;
+    options: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    context: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export type AskUserToolInput = Static<typeof askUserSchema>;
+/**
+ * Submit a user's answer for a pending question.
+ * Called by the API route when the frontend posts a response.
+ */
+export declare function submitAnswer(toolCallId: string, answer: string): boolean;
+/**
+ * Cancel a pending question (e.g. when the stream is aborted).
+ */
+export declare function cancelPendingQuestion(toolCallId: string): boolean;
+export declare function createAskUserTool(): AgentTool<typeof askUserSchema>;
+export declare const askUserTool: AgentTool<import("@sinclair/typebox").TObject<{
+    question: import("@sinclair/typebox").TString;
+    options: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    context: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>, any>;
+export {};
+//# sourceMappingURL=ask-user.d.ts.map

package/dist/tools/ask-user.js

@@ -0,0 +1,74 @@
+import { Type } from "@sinclair/typebox";
+const askUserSchema = Type.Object({
+    question: Type.String({
+        description: "A clear, specific question to ask the user. Frame it to help clarify ambiguous requirements, confirm decisions, or gather preferences needed to proceed.",
+    }),
+    options: Type.Optional(Type.Array(Type.String(), {
+        description: "Optional list of predefined answer choices. The user can pick one or type a custom response. Use when there are a small number of clear alternatives.",
+    })),
+    context: Type.Optional(Type.String({
+        description: "Optional brief context explaining why this question is being asked, so the user understands the impact of their answer.",
+    })),
+});
+/**
+ * Registry of pending questions awaiting user responses.
+ * Keyed by toolCallId so the HTTP endpoint can resolve the correct Promise.
+ */
+const pendingQuestions = new Map();
+/**
+ * Submit a user's answer for a pending question.
+ * Called by the API route when the frontend posts a response.
+ */
+export function submitAnswer(toolCallId, answer) {
+    const pending = pendingQuestions.get(toolCallId);
+    if (!pending)
+        return false;
+    pending.resolve(answer);
+    pendingQuestions.delete(toolCallId);
+    return true;
+}
+/**
+ * Cancel a pending question (e.g. when the stream is aborted).
+ */
+export function cancelPendingQuestion(toolCallId) {
+    const pending = pendingQuestions.get(toolCallId);
+    if (!pending)
+        return false;
+    pending.reject(new Error("Question cancelled"));
+    pendingQuestions.delete(toolCallId);
+    return true;
+}
+export function createAskUserTool() {
+    return {
+        name: "ask_user",
+        label: "ask_user",
+        description: "Ask the user a question when you need clarification, confirmation, or a decision when there is ambiguity or multiple choices.",
+        parameters: askUserSchema,
+        execute: async (toolCallId, { question, options, context }, signal) => {
+            console.log(`[ai] ask_user: "${question}" (options: ${options?.join(", ") ?? "free-text"})`);
+            if (signal?.aborted) {
+                throw new Error("Operation aborted");
+            }
+            const answer = await new Promise((resolve, reject) => {
+                pendingQuestions.set(toolCallId, {
+                    resolve,
+                    reject,
+                    question,
+                    options,
+                    context,
+                });
+                const onAbort = () => {
+                    cancelPendingQuestion(toolCallId);
+                };
+                signal?.addEventListener("abort", onAbort, { once: true });
+            });
+            console.log(`[ai] ask_user response: "${answer}"`);
+            return {
+                content: [{ type: "text", text: answer }],
+                details: undefined,
+            };
+        },
+    };
+}
+export const askUserTool = createAskUserTool();
+//# sourceMappingURL=ask-user.js.map

package/dist/tools/ast-grep.d.ts

@@ -0,0 +1,28 @@
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import { type Static } from "@sinclair/typebox";
+import { type TruncationResult } from "./truncate.js";
+declare const astGrepSchema: import("@sinclair/typebox").TObject<{
+    command: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"run">, import("@sinclair/typebox").TLiteral<"scan">]>;
+    pattern: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    lang: import("@sinclair/typebox").TString;
+    rule: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    path: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+export type AstGrepToolInput = Static<typeof astGrepSchema>;
+export interface AstGrepToolDetails {
+    truncation?: TruncationResult;
+    matchLimitReached?: number;
+    linesTruncated?: boolean;
+}
+export declare function createAstGrepTool(cwd: string): AgentTool<typeof astGrepSchema>;
+export declare const astGrepTool: AgentTool<import("@sinclair/typebox").TObject<{
+    command: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"run">, import("@sinclair/typebox").TLiteral<"scan">]>;
+    pattern: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    lang: import("@sinclair/typebox").TString;
+    rule: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    path: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>, any>;
+export {};
+//# sourceMappingURL=ast-grep.d.ts.map

package/dist/tools/ast-grep.js

@@ -0,0 +1,273 @@
+import { Type } from "@sinclair/typebox";
+import { spawnProcess } from "../core/utils.js";
+import path from "path";
+import { existsSync, readdirSync } from "fs";
+import { fileURLToPath } from "url";
+import { resolveToCwd, validatePathWithinCwd } from "./path-utils.js";
+import { DEFAULT_MAX_BYTES, formatSize, GREP_MAX_LINE_LENGTH, truncateHead, truncateLine, } from "./truncate.js";
+const astGrepSchema = Type.Object({
+    command: Type.Union([Type.Literal("run"), Type.Literal("scan")], {
+        description: "Mode: 'run' for simple pattern search, 'scan' for complex rule-based search",
+    }),
+    pattern: Type.Optional(Type.String({
+        description: "AST pattern for 'run' command. Use metavariables like $NAME, $$$ARGS. Example: 'console.log($ARG)'",
+    })),
+    lang: Type.String({
+        description: "Language to parse: javascript, typescript, python, rust, go, java, css, html, etc.",
+    }),
+    rule: Type.Optional(Type.String({
+        description: "YAML rule for 'scan' command. Supports kind, has, inside, all, any, not. Example: 'id: test\\nlanguage: javascript\\nrule:\\n  kind: function_declaration\\n  has:\\n    pattern: await $EXPR\\n    stopBy: end'",
+    })),
+    path: Type.Optional(Type.String({
+        description: "Directory or file to search (default: current directory)",
+    })),
+    limit: Type.Optional(Type.Number({
+        description: "Maximum number of matches to return (default: 50)",
+    })),
+});
+const DEFAULT_LIMIT = 50;
+const PLATFORM_PACKAGES = {
+    "darwin-arm64": "@ast-grep/cli-darwin-arm64",
+    "darwin-x64": "@ast-grep/cli-darwin-x64",
+    "linux-arm64": "@ast-grep/cli-linux-arm64-gnu",
+    "linux-x64": "@ast-grep/cli-linux-x64-gnu",
+    "win32-arm64": "@ast-grep/cli-win32-arm64-msvc",
+    "win32-ia32": "@ast-grep/cli-win32-ia32-msvc",
+    "win32-x64": "@ast-grep/cli-win32-x64-msvc",
+};
+function findBinInNodeModules(startDir, pkg, binName) {
+    const pkgPath = pkg.replace("/", path.sep);
+    let dir = startDir;
+    while (true) {
+        const nmDir = path.join(dir, "node_modules");
+        // Standard layout: node_modules/@ast-grep/cli-darwin-arm64/ast-grep
+        const standardPath = path.join(nmDir, pkgPath, binName);
+        if (existsSync(standardPath))
+            return standardPath;
+        // Bun cache layout: node_modules/.bun/@ast-grep+cli-darwin-arm64@*/node_modules/@ast-grep/cli-darwin-arm64/ast-grep
+        const bunDir = path.join(nmDir, ".bun");
+        if (existsSync(bunDir)) {
+            const bunPrefix = pkg.replace("/", "+");
+            try {
+                const entries = readdirSync(bunDir);
+                const match = entries.find((e) => e.startsWith(bunPrefix + "@"));
+                if (match) {
+                    const bunPath = path.join(bunDir, match, "node_modules", pkgPath, binName);
+                    if (existsSync(bunPath))
+                        return bunPath;
+                }
+            }
+            catch {
+                // ignore
+            }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+// Resolve from the tarsk app's own install directory (where @ast-grep/cli is a dependency)
+const APP_DIR = path.resolve(fileURLToPath(import.meta.url), "../../..");
+function resolveAstGrepBin(cwd) {
+    const key = `${process.platform}-${process.arch}`;
+    const pkg = PLATFORM_PACKAGES[key];
+    if (!pkg)
+        return null;
+    const binName = process.platform === "win32" ? "ast-grep.exe" : "ast-grep";
+    console.log(`[ast-grep] resolving binary: platform=${key}, pkg=${pkg}, APP_DIR=${APP_DIR}`);
+    // First: search from the tarsk app's own directory (where @ast-grep/cli is installed as a dependency)
+    const appResult = findBinInNodeModules(APP_DIR, pkg, binName);
+    if (appResult)
+        return appResult;
+    // Fallback: search from the user's working directory
+    return findBinInNodeModules(cwd, pkg, binName);
+}
+export function createAstGrepTool(cwd) {
+    return {
+        name: "ast_grep",
+        label: "Code Search",
+        description: `Structural code search using AST patterns. Matches code by structure, not text. Use 'run' for simple pattern matching (e.g. 'console.log($ARG)') or 'scan' for complex YAML rules with kind/has/inside/all/any/not. Output truncated to ${DEFAULT_LIMIT} matches or ${DEFAULT_MAX_BYTES / 1024}KB.`,
+        parameters: astGrepSchema,
+        execute: async (_toolCallId, { command, pattern, lang, rule, path: searchDir, limit }, signal) => {
+            return new Promise((resolve, reject) => {
+                if (signal?.aborted) {
+                    reject(new Error("Operation aborted"));
+                    return;
+                }
+                let settled = false;
+                const settle = (fn) => {
+                    if (!settled) {
+                        settled = true;
+                        fn();
+                    }
+                };
+                void (async () => {
+                    try {
+                        if (command === "run" && !pattern) {
+                            settle(() => reject(new Error("'pattern' is required when command is 'run'")));
+                            return;
+                        }
+                        if (command === "scan" && !rule) {
+                            settle(() => reject(new Error("'rule' is required when command is 'scan'")));
+                            return;
+                        }
+                        const searchPath = resolveToCwd(searchDir ?? ".", cwd);
+                        validatePathWithinCwd(searchPath, cwd);
+                        const effectiveLimit = Math.max(1, limit ?? DEFAULT_LIMIT);
+                        const args = [];
+                        if (command === "run") {
+                            args.push("run", "--pattern", pattern, "--lang", lang, "--json", searchPath);
+                        }
+                        else {
+                            args.push("scan", "--inline-rules", rule, "--json", searchPath);
+                        }
+                        const binPath = resolveAstGrepBin(cwd);
+                        if (!binPath) {
+                            settle(() => reject(new Error("ast-grep is not available. Install @ast-grep/cli or add it to PATH.")));
+                            return;
+                        }
+                        console.log(`[ast-grep] ${binPath} ${args.join(" ")}`);
+                        const child = spawnProcess(binPath, args, {
+                            stdio: ["ignore", "pipe", "pipe"],
+                        });
+                        const MAX_STDOUT_BYTES = 2 * 1024 * 1024; // 2MB cap on raw stdout
+                        let stdout = "";
+                        let stdoutBytes = 0;
+                        let stderr = "";
+                        let aborted = false;
+                        let killedDueToCap = false;
+                        const onAbort = () => {
+                            aborted = true;
+                            if (!child.killed)
+                                child.kill();
+                        };
+                        signal?.addEventListener("abort", onAbort, { once: true });
+                        child.stdout?.on("data", (chunk) => {
+                            if (killedDueToCap)
+                                return;
+                            stdoutBytes += chunk.length;
+                            if (stdoutBytes > MAX_STDOUT_BYTES) {
+                                killedDueToCap = true;
+                                if (!child.killed)
+                                    child.kill();
+                                return;
+                            }
+                            stdout += chunk.toString();
+                        });
+                        child.stderr?.on("data", (chunk) => {
+                            stderr += chunk.toString();
+                        });
+                        child.on("error", (error) => {
+                            signal?.removeEventListener("abort", onAbort);
+                            settle(() => reject(new Error(`Failed to run ast-grep: ${error.message}`)));
+                        });
+                        child.on("close", (code) => {
+                            signal?.removeEventListener("abort", onAbort);
+                            console.log(`[ast-grep] exit code: ${code}, stdout: ${stdout.length} bytes, stderr: ${stderr.length} bytes`);
+                            if (stderr.trim())
+                                console.log(`[ast-grep] stderr: ${stderr.trim()}`);
+                            if (aborted) {
+                                settle(() => reject(new Error("Operation aborted")));
+                                return;
+                            }
+                            if (!killedDueToCap && code !== 0 && code !== 1) {
+                                const errMsg = stderr.trim() || `ast-grep exited with code ${code}`;
+                                settle(() => reject(new Error(errMsg)));
+                                return;
+                            }
+                            let matches;
+                            try {
+                                matches = JSON.parse(stdout || "[]");
+                            }
+                            catch {
+                                // If killed due to cap, stdout is truncated JSON — try to recover
+                                if (killedDueToCap) {
+                                    const lastBrace = stdout.lastIndexOf("}");
+                                    if (lastBrace > 0) {
+                                        try {
+                                            matches = JSON.parse(stdout.slice(0, lastBrace + 1) + "]");
+                                        }
+                                        catch {
+                                            matches = [];
+                                        }
+                                    }
+                                    else {
+                                        matches = [];
+                                    }
+                                }
+                                else if (!stdout.trim()) {
+                                    settle(() => resolve({
+                                        content: [{ type: "text", text: "No matches found" }],
+                                        details: undefined,
+                                    }));
+                                    return;
+                                }
+                                else {
+                                    settle(() => reject(new Error(`Failed to parse ast-grep JSON output: ${stdout.slice(0, 200)}`)));
+                                    return;
+                                }
+                            }
+                            if (!Array.isArray(matches) || matches.length === 0) {
+                                settle(() => resolve({
+                                    content: [{ type: "text", text: "No matches found" }],
+                                    details: undefined,
+                                }));
+                                return;
+                            }
+                            const matchLimitReached = matches.length > effectiveLimit;
+                            if (matchLimitReached) {
+                                matches = matches.slice(0, effectiveLimit);
+                            }
+                            let linesTruncated = false;
+                            const outputLines = [];
+                            for (const match of matches) {
+                                const filePath = match.file ?? "unknown";
+                                const relativePath = path.relative(searchPath, filePath).replace(/\\/g, "/") || filePath;
+                                const lineNum = (match.range?.start?.line ?? 0) + 1;
+                                const matchText = (match.lines ?? match.text ?? "").trimEnd();
+                                const firstLine = matchText.split("\n")[0] ?? "";
+                                const { text: truncatedText, wasTruncated } = truncateLine(firstLine);
+                                if (wasTruncated)
+                                    linesTruncated = true;
+                                outputLines.push(`${relativePath}:${lineNum}: ${truncatedText}`);
+                            }
+                            const rawOutput = outputLines.join("\n");
+                            const truncation = truncateHead(rawOutput, { maxLines: Number.MAX_SAFE_INTEGER });
+                            let output = truncation.content;
+                            const details = {};
+                            const notices = [];
+                            if (killedDueToCap) {
+                                notices.push(`Output exceeded 2MB cap. Refine your pattern for more precise results`);
+                            }
+                            if (matchLimitReached) {
+                                notices.push(`${effectiveLimit} matches limit reached. Use limit=${effectiveLimit * 2} for more, or refine pattern`);
+                                details.matchLimitReached = effectiveLimit;
+                            }
+                            if (truncation.truncated) {
+                                notices.push(`${formatSize(DEFAULT_MAX_BYTES)} limit reached`);
+                                details.truncation = truncation;
+                            }
+                            if (linesTruncated) {
+                                notices.push(`Some lines truncated to ${GREP_MAX_LINE_LENGTH} chars. Use read tool to see full lines`);
+                                details.linesTruncated = true;
+                            }
+                            if (notices.length > 0)
+                                output += `\n\n[${notices.join(". ")}]`;
+                            settle(() => resolve({
+                                content: [{ type: "text", text: output }],
+                                details: Object.keys(details).length > 0 ? details : undefined,
+                            }));
+                        });
+                    }
+                    catch {
+                        settle(() => reject(new Error("Error processing ast-grep request")));
+                    }
+                })();
+            });
+        },
+    };
+}
+export const astGrepTool = createAstGrepTool(process.cwd());
+//# sourceMappingURL=ast-grep.js.map

package/dist/tools/bash.d.ts

@@ -0,0 +1,33 @@
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import { type Static } from "@sinclair/typebox";
+import { type TruncationResult } from "./truncate.js";
+declare const bashSchema: import("@sinclair/typebox").TObject<{
+    command: import("@sinclair/typebox").TString;
+    timeout: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+export type BashToolInput = Static<typeof bashSchema>;
+export interface BashToolDetails {
+    truncation?: TruncationResult;
+    fullOutputPath?: string;
+}
+export interface BashOperations {
+    exec: (command: string, cwd: string, options: {
+        onData: (data: Buffer) => void;
+        signal?: AbortSignal;
+        timeout?: number;
+        env?: NodeJS.ProcessEnv;
+    }) => Promise<{
+        exitCode: number | null;
+    }>;
+}
+export interface BashToolOptions {
+    operations?: BashOperations;
+    commandPrefix?: string;
+}
+export declare function createBashTool(cwd: string, options?: BashToolOptions): AgentTool<typeof bashSchema>;
+export declare const bashTool: AgentTool<import("@sinclair/typebox").TObject<{
+    command: import("@sinclair/typebox").TString;
+    timeout: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>, any>;
+export {};
+//# sourceMappingURL=bash.d.ts.map