tarsk 0.3.43 → 0.4.4

package/dist/tools/path-utils.d.ts

@@ -0,0 +1,14 @@
+export declare function expandPath(filePath: string): string;
+/**
+ * Resolve a path relative to the given cwd.
+ * Handles ~ expansion and absolute paths.
+ */
+export declare function resolveToCwd(filePath: string, cwd: string): string;
+/**
+ * Validates that a resolved path is within the allowed cwd directory.
+ * Prevents directory traversal attacks and access to files outside the project.
+ * @throws Error if the path is outside the cwd
+ */
+export declare function validatePathWithinCwd(resolvedPath: string, cwd: string): void;
+export declare function resolveReadPath(filePath: string, cwd: string): string;
+//# sourceMappingURL=path-utils.d.ts.map

package/dist/tools/path-utils.js

@@ -0,0 +1,87 @@
+import { accessSync, constants } from "node:fs";
+import * as os from "node:os";
+import { isAbsolute, resolve as resolvePath, relative } from "node:path";
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+const NARROW_NO_BREAK_SPACE = "\u202F";
+function normalizeUnicodeSpaces(str) {
+    return str.replace(UNICODE_SPACES, " ");
+}
+function tryMacOSScreenshotPath(filePath) {
+    return filePath.replace(/ (AM|PM)\./g, `${NARROW_NO_BREAK_SPACE}$1.`);
+}
+function tryNFDVariant(filePath) {
+    return filePath.normalize("NFD");
+}
+function tryCurlyQuoteVariant(filePath) {
+    return filePath.replace(/'/g, "\u2019");
+}
+function fileExists(filePath) {
+    try {
+        accessSync(filePath, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function normalizeAtPrefix(filePath) {
+    return filePath.startsWith("@") ? filePath.slice(1) : filePath;
+}
+export function expandPath(filePath) {
+    const normalized = normalizeUnicodeSpaces(normalizeAtPrefix(filePath));
+    if (normalized === "~") {
+        return os.homedir();
+    }
+    if (normalized.startsWith("~/")) {
+        return os.homedir() + normalized.slice(1);
+    }
+    return normalized;
+}
+/**
+ * Resolve a path relative to the given cwd.
+ * Handles ~ expansion and absolute paths.
+ */
+export function resolveToCwd(filePath, cwd) {
+    const expanded = expandPath(filePath);
+    if (isAbsolute(expanded)) {
+        return expanded;
+    }
+    return resolvePath(cwd, expanded);
+}
+/**
+ * Validates that a resolved path is within the allowed cwd directory.
+ * Prevents directory traversal attacks and access to files outside the project.
+ * @throws Error if the path is outside the cwd
+ */
+export function validatePathWithinCwd(resolvedPath, cwd) {
+    const relativePath = relative(cwd, resolvedPath);
+    // If relative path starts with "..", it's outside the cwd
+    if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
+        throw new Error(`Access denied: Path is outside the allowed directory. ` +
+            `Requested: ${resolvedPath}, Allowed root: ${cwd}`);
+    }
+}
+export function resolveReadPath(filePath, cwd) {
+    const resolved = resolveToCwd(filePath, cwd);
+    if (fileExists(resolved)) {
+        return resolved;
+    }
+    const amPmVariant = tryMacOSScreenshotPath(resolved);
+    if (amPmVariant !== resolved && fileExists(amPmVariant)) {
+        return amPmVariant;
+    }
+    const nfdVariant = tryNFDVariant(resolved);
+    if (nfdVariant !== resolved && fileExists(nfdVariant)) {
+        return nfdVariant;
+    }
+    const curlyVariant = tryCurlyQuoteVariant(resolved);
+    if (curlyVariant !== resolved && fileExists(curlyVariant)) {
+        return curlyVariant;
+    }
+    const nfdCurlyVariant = tryCurlyQuoteVariant(nfdVariant);
+    if (nfdCurlyVariant !== resolved && fileExists(nfdCurlyVariant)) {
+        return nfdCurlyVariant;
+    }
+    return resolved;
+}
+//# sourceMappingURL=path-utils.js.map

package/dist/tools/read.d.ts

@@ -0,0 +1,27 @@
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import { type Static } from "@sinclair/typebox";
+import { type TruncationResult } from "./truncate.js";
+declare const readSchema: import("@sinclair/typebox").TObject<{
+    path: import("@sinclair/typebox").TString;
+    offset: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+export type ReadToolInput = Static<typeof readSchema>;
+export interface ReadToolDetails {
+    truncation?: TruncationResult;
+}
+export interface ReadOperations {
+    readFile: (absolutePath: string) => Promise<Buffer>;
+    access: (absolutePath: string) => Promise<void>;
+}
+export interface ReadToolOptions {
+    operations?: ReadOperations;
+}
+export declare function createReadTool(cwd: string, options?: ReadToolOptions): AgentTool<typeof readSchema>;
+export declare const readTool: AgentTool<import("@sinclair/typebox").TObject<{
+    path: import("@sinclair/typebox").TString;
+    offset: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>, any>;
+export {};
+//# sourceMappingURL=read.d.ts.map

package/dist/tools/read.js

@@ -0,0 +1,86 @@
+import { Type } from "@sinclair/typebox";
+import { constants } from "fs";
+import { access as fsAccess, readFile as fsReadFile } from "fs/promises";
+import { resolveReadPath, validatePathWithinCwd } from "./path-utils.js";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, truncateHead, } from "./truncate.js";
+import { withAbortSignal } from "./tool-helpers.js";
+const readSchema = Type.Object({
+    path: Type.String({ description: "Path to the file to read (relative or absolute)" }),
+    offset: Type.Optional(Type.Number({ description: "Line number to start reading from (1-indexed)" })),
+    limit: Type.Optional(Type.Number({ description: "Maximum number of lines to read" })),
+});
+const defaultReadOperations = {
+    readFile: (path) => fsReadFile(path),
+    access: (path) => fsAccess(path, constants.R_OK),
+};
+export function createReadTool(cwd, options) {
+    const ops = options?.operations ?? defaultReadOperations;
+    return {
+        name: "read",
+        label: "read",
+        description: `Read the contents of a text file. Output is truncated to ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). Use offset/limit for large files.`,
+        parameters: readSchema,
+        execute: async (_toolCallId, { path, offset, limit }, signal) => {
+            const absolutePath = resolveReadPath(path, cwd);
+            validatePathWithinCwd(absolutePath, cwd);
+            return withAbortSignal(signal, async (isAborted) => {
+                await ops.access(absolutePath);
+                if (isAborted())
+                    return { content: [], details: undefined };
+                const buffer = await ops.readFile(absolutePath);
+                const textContent = buffer.toString("utf-8");
+                const allLines = textContent.split("\n");
+                const totalFileLines = allLines.length;
+                const startLine = offset ? Math.max(0, offset - 1) : 0;
+                const startLineDisplay = startLine + 1;
+                if (startLine >= allLines.length) {
+                    throw new Error(`Offset ${offset} is beyond end of file (${allLines.length} lines total)`);
+                }
+                let selectedContent;
+                let userLimitedLines;
+                if (limit !== undefined) {
+                    const endLine = Math.min(startLine + limit, allLines.length);
+                    selectedContent = allLines.slice(startLine, endLine).join("\n");
+                    userLimitedLines = endLine - startLine;
+                }
+                else {
+                    selectedContent = allLines.slice(startLine).join("\n");
+                }
+                const truncation = truncateHead(selectedContent);
+                let outputText;
+                let details;
+                if (truncation.firstLineExceedsLimit) {
+                    outputText = `[Line ${startLineDisplay} is ${formatSize(Buffer.byteLength(allLines[startLine], "utf-8"))}, exceeds ${formatSize(DEFAULT_MAX_BYTES)} limit. Use bash: sed -n '${startLineDisplay}p' ${path} | head -c ${DEFAULT_MAX_BYTES}]`;
+                    details = { truncation };
+                }
+                else if (truncation.truncated) {
+                    const endLineDisplay = startLineDisplay + truncation.outputLines - 1;
+                    const nextOffset = endLineDisplay + 1;
+                    outputText = truncation.content;
+                    if (truncation.truncatedBy === "lines") {
+                        outputText += `\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines}. Use offset=${nextOffset} to continue.]`;
+                    }
+                    else {
+                        outputText += `\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines} (${formatSize(DEFAULT_MAX_BYTES)} limit). Use offset=${nextOffset} to continue.]`;
+                    }
+                    details = { truncation };
+                }
+                else if (userLimitedLines !== undefined &&
+                    startLine + userLimitedLines < allLines.length) {
+                    const remaining = allLines.length - (startLine + userLimitedLines);
+                    const nextOffset = startLine + userLimitedLines + 1;
+                    outputText = truncation.content;
+                    outputText += `\n\n[${remaining} more lines in file. Use offset=${nextOffset} to continue.]`;
+                }
+                else {
+                    outputText = truncation.content;
+                }
+                if (isAborted())
+                    return { content: [], details: undefined };
+                return { content: [{ type: "text", text: outputText }], details };
+            });
+        },
+    };
+}
+export const readTool = createReadTool(process.cwd());
+//# sourceMappingURL=read.js.map

package/dist/tools/resolve-bin.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Resolve path to an executable on PATH. Returns the command name if found, null otherwise.
+ */
+export declare function resolveBin(name: string): Promise<string | null>;
+//# sourceMappingURL=resolve-bin.d.ts.map

package/dist/tools/resolve-bin.js

@@ -0,0 +1,28 @@
+import { spawnSyncProcess } from "../core/utils.js";
+/**
+ * Resolve path to an executable on PATH. Returns the command name if found, null otherwise.
+ */
+export function resolveBin(name) {
+    return new Promise((resolve) => {
+        const cmd = process.platform === "win32" ? "where" : "which";
+        const args = process.platform === "win32" ? [name + ".exe", name] : [name];
+        try {
+            const result = spawnSyncProcess(cmd, args, { encoding: "utf-8", timeout: 5000 });
+            if (result.status === 0 && result.stdout) {
+                const first = (typeof result.stdout === "string" ? result.stdout : result.stdout?.toString() || "")
+                    .trim()
+                    .split(/\r?\n/)[0]
+                    ?.trim();
+                if (first) {
+                    resolve(first);
+                    return;
+                }
+            }
+        }
+        catch {
+            // ignore
+        }
+        resolve(null);
+    });
+}
+//# sourceMappingURL=resolve-bin.js.map

package/dist/tools/shell.d.ts

@@ -0,0 +1,7 @@
+export declare function getShellConfig(): {
+    shell: string;
+    args: string[];
+};
+export declare function getShellEnv(): NodeJS.ProcessEnv;
+export declare function killProcessTree(pid: number): void;
+//# sourceMappingURL=shell.d.ts.map

package/dist/tools/shell.js

@@ -0,0 +1,143 @@
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { spawnProcess } from "../core/utils.js";
+import { spawnSyncProcess } from "../core/utils.js";
+let cachedShellConfig = null;
+let cachedLoginShellEnv = null;
+function findBashOnPath() {
+    if (process.platform === "win32") {
+        try {
+            const syncResult = spawnSyncProcess("where", ["bash.exe"], {
+                encoding: "utf-8",
+                timeout: 5000,
+            });
+            if (syncResult.status === 0 && typeof syncResult.stdout === "string") {
+                const firstMatch = syncResult.stdout.trim().split(/\r?\n/)[0];
+                if (firstMatch && existsSync(firstMatch)) {
+                    return firstMatch;
+                }
+            }
+        }
+        catch {
+            // ignore
+        }
+        return null;
+    }
+    try {
+        const syncResult = spawnSyncProcess("which", ["bash"], {
+            encoding: "utf-8",
+            timeout: 5000,
+        });
+        if (syncResult.status === 0 && typeof syncResult.stdout === "string") {
+            const firstMatch = syncResult.stdout.trim().split(/\r?\n/)[0];
+            if (firstMatch)
+                return firstMatch;
+        }
+    }
+    catch {
+        // ignore
+    }
+    return null;
+}
+export function getShellConfig() {
+    if (cachedShellConfig) {
+        return cachedShellConfig;
+    }
+    if (process.platform === "win32") {
+        const paths = [];
+        if (process.env.ProgramFiles) {
+            paths.push(`${process.env.ProgramFiles}\\Git\\bin\\bash.exe`);
+        }
+        if (process.env["ProgramFiles(x86)"]) {
+            paths.push(`${process.env["ProgramFiles(x86)"]}\\Git\\bin\\bash.exe`);
+        }
+        for (const p of paths) {
+            if (existsSync(p)) {
+                cachedShellConfig = { shell: p, args: ["-c"] };
+                return cachedShellConfig;
+            }
+        }
+        const bashOnPath = findBashOnPath();
+        if (bashOnPath) {
+            cachedShellConfig = { shell: bashOnPath, args: ["-c"] };
+            return cachedShellConfig;
+        }
+        throw new Error("No bash shell found. Install Git for Windows or add bash to PATH.");
+    }
+    if (existsSync("/bin/bash")) {
+        cachedShellConfig = { shell: "/bin/bash", args: ["-c"] };
+        return cachedShellConfig;
+    }
+    const bashOnPath = findBashOnPath();
+    if (bashOnPath) {
+        cachedShellConfig = { shell: bashOnPath, args: ["-c"] };
+        return cachedShellConfig;
+    }
+    cachedShellConfig = { shell: "sh", args: ["-c"] };
+    return cachedShellConfig;
+}
+function getLoginShellEnv() {
+    if (cachedLoginShellEnv) {
+        return cachedLoginShellEnv;
+    }
+    const shell = process.env.SHELL ?? (process.platform === "win32" ? undefined : "/bin/zsh");
+    if (!shell) {
+        cachedLoginShellEnv = { ...process.env };
+        return cachedLoginShellEnv;
+    }
+    try {
+        const quotedShell = shell.replace(/'/g, "'\\''");
+        const output = execSync(`'${quotedShell}' -ilc 'env'`, {
+            encoding: "utf-8",
+            timeout: 5000,
+            stdio: ["ignore", "pipe", "ignore"],
+            env: { ...process.env },
+        });
+        const loginEnv = { ...process.env };
+        for (const line of output.split(/\r?\n/)) {
+            const separatorIndex = line.indexOf("=");
+            if (separatorIndex <= 0) {
+                continue;
+            }
+            const key = line.slice(0, separatorIndex);
+            const value = line.slice(separatorIndex + 1);
+            loginEnv[key] = value;
+        }
+        cachedLoginShellEnv = loginEnv;
+        return cachedLoginShellEnv;
+    }
+    catch {
+        cachedLoginShellEnv = { ...process.env };
+        return cachedLoginShellEnv;
+    }
+}
+export function getShellEnv() {
+    return { ...getLoginShellEnv() };
+}
+export function killProcessTree(pid) {
+    if (process.platform === "win32") {
+        try {
+            spawnProcess("taskkill", ["/F", "/T", "/PID", String(pid)], {
+                stdio: "ignore",
+                detached: true,
+            });
+        }
+        catch {
+            // ignore
+        }
+    }
+    else {
+        try {
+            process.kill(-pid, "SIGKILL");
+        }
+        catch {
+            try {
+                process.kill(pid, "SIGKILL");
+            }
+            catch {
+                // already dead
+            }
+        }
+    }
+}
+//# sourceMappingURL=shell.js.map

package/dist/tools/skill-reference-tool.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Skill Reference Tool
+ *
+ * Loads reference files from activated skills' references/ directories on-demand.
+ * This implements progressive disclosure - reference files are only loaded when needed.
+ */
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import { type Static } from "@sinclair/typebox";
+import type { Skill } from "@tarsk/shared";
+/**
+ * Schema for skill reference tool input
+ */
+declare const skillReferenceSchema: import("@sinclair/typebox").TObject<{
+    skillName: import("@sinclair/typebox").TString;
+    referencePath: import("@sinclair/typebox").TString;
+}>;
+export type SkillReferenceToolInput = Static<typeof skillReferenceSchema>;
+/**
+ * Create a skill reference reader tool
+ */
+export declare function createSkillReferenceTool(skills: Skill[]): AgentTool<typeof skillReferenceSchema>;
+/**
+ * List all available skill references (utility function)
+ */
+export declare function listSkillReferences(skills: Skill[]): Promise<Array<{
+    skillName: string;
+    referencePath: string;
+}>>;
+export {};
+//# sourceMappingURL=skill-reference-tool.d.ts.map

package/dist/tools/skill-reference-tool.js

@@ -0,0 +1,171 @@
+/**
+ * Skill Reference Tool
+ *
+ * Loads reference files from activated skills' references/ directories on-demand.
+ * This implements progressive disclosure - reference files are only loaded when needed.
+ */
+import { readFile, readdir } from "fs/promises";
+import { join, normalize, relative } from "path";
+import { existsSync } from "fs";
+import { Type } from "@sinclair/typebox";
+/**
+ * Validate that a reference path is safe (no path traversal attacks)
+ */
+function isPathSafe(basePath, requestedPath) {
+    const normalized = normalize(requestedPath);
+    const fullPath = join(basePath, normalized);
+    const relativePath = relative(basePath, fullPath);
+    // Check if the relative path tries to escape the base directory
+    return !relativePath.startsWith("..") && !relativePath.startsWith("/");
+}
+/**
+ * Schema for skill reference tool input
+ */
+const skillReferenceSchema = Type.Object({
+    skillName: Type.String({ description: "Name of the skill" }),
+    referencePath: Type.String({
+        description: 'Path to the reference file relative to the skill\'s references/ directory (e.g., "api-reference.md" or "guides/setup.md")',
+    }),
+});
+/**
+ * Create a skill reference reader tool
+ */
+export function createSkillReferenceTool(skills) {
+    return {
+        name: "read_skill_reference",
+        label: "read_skill_reference",
+        description: "Read a reference file from an activated skill. Skills provide additional documentation in their references/ directory.",
+        parameters: skillReferenceSchema,
+        execute: async (_toolCallId, { skillName, referencePath }) => {
+            // 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 references directory exists
+            const referencesDir = join(skill.skillPath, "references");
+            if (!existsSync(referencesDir)) {
+                return {
+                    content: [
+                        { type: "text", text: `Skill '${skillName}' has no references directory` },
+                    ],
+                    details: undefined,
+                };
+            }
+            // Validate path safety (prevent path traversal)
+            if (!isPathSafe(referencesDir, referencePath)) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Invalid reference path: ${referencePath}. Path must be within the skill's references directory.`,
+                        },
+                    ],
+                    details: undefined,
+                };
+            }
+            // Read the reference file
+            const fullPath = join(referencesDir, referencePath);
+            if (!existsSync(fullPath)) {
+                // List available references for better error message
+                try {
+                    const availableRefs = await listReferencesRecursive(referencesDir);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Reference file '${referencePath}' not found in skill '${skillName}'. Available references:\n${availableRefs.join("\n")}`,
+                            },
+                        ],
+                        details: undefined,
+                    };
+                }
+                catch {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Reference file '${referencePath}' not found in skill '${skillName}'`,
+                            },
+                        ],
+                        details: undefined,
+                    };
+                }
+            }
+            try {
+                const content = await readFile(fullPath, "utf-8");
+                return {
+                    content: [{ type: "text", text: content }],
+                    details: undefined,
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Failed to read reference file: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                    details: undefined,
+                };
+            }
+        },
+    };
+}
+/**
+ * Recursively list all reference files in a directory
+ */
+async function listReferencesRecursive(dir, prefix = "") {
+    const files = [];
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const relativePath = prefix ? join(prefix, entry.name) : entry.name;
+            if (entry.isDirectory()) {
+                const subFiles = await listReferencesRecursive(join(dir, entry.name), relativePath);
+                files.push(...subFiles);
+            }
+            else {
+                files.push(relativePath);
+            }
+        }
+    }
+    catch (error) {
+        console.error(`Failed to list references in ${dir}:`, error);
+    }
+    return files;
+}
+/**
+ * List all available skill references (utility function)
+ */
+export async function listSkillReferences(skills) {
+    const references = [];
+    for (const skill of skills) {
+        const referencesDir = join(skill.skillPath, "references");
+        if (!existsSync(referencesDir))
+            continue;
+        try {
+            const files = await listReferencesRecursive(referencesDir);
+            for (const file of files) {
+                references.push({
+                    skillName: skill.name,
+                    referencePath: file,
+                });
+            }
+        }
+        catch (error) {
+            console.error(`Failed to list references for skill ${skill.name}:`, error);
+        }
+    }
+    return references;
+}
+//# sourceMappingURL=skill-reference-tool.js.map

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

@@ -0,0 +1,33 @@
+/**
+ * Skill Script Tool
+ *
+ * Executes scripts from activated skills' scripts/ directories.
+ * Scripts can be written in any supported language (.sh, .py, .js, etc.)
+ */
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import { type Static } from "@sinclair/typebox";
+import type { Skill } from "@tarsk/shared";
+/**
+ * Schema for skill script tool input
+ */
+declare const skillScriptSchema: import("@sinclair/typebox").TObject<{
+    skillName: import("@sinclair/typebox").TString;
+    scriptName: import("@sinclair/typebox").TString;
+    args: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    timeout: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+export type SkillScriptToolInput = Static<typeof skillScriptSchema>;
+/**
+ * Create a skill script executor tool
+ */
+export declare function createSkillScriptTool(skills: Skill[], cwd: string): AgentTool<typeof skillScriptSchema>;
+/**
+ * List all available skill scripts
+ */
+export declare function listSkillScripts(skills: Skill[]): Promise<Array<{
+    skillName: string;
+    scriptName: string;
+    path: string;
+}>>;
+export {};
+//# sourceMappingURL=skill-tool.d.ts.map