pretticlaw 0.1.0

package/dist/agent/tools/base.js

@@ -0,0 +1,58 @@
+export class Tool {
+    static typeMap = {
+        string: (v) => typeof v === "string",
+        integer: (v) => Number.isInteger(v),
+        number: (v) => typeof v === "number" && Number.isFinite(v),
+        boolean: (v) => typeof v === "boolean",
+        array: (v) => Array.isArray(v),
+        object: (v) => !!v && typeof v === "object" && !Array.isArray(v),
+    };
+    validateParams(params) {
+        const schema = (this.parameters ?? {});
+        if (schema.type !== "object") {
+            throw new Error(`Schema must be object type, got ${String(schema.type)}`);
+        }
+        return this.validateValue(params, { ...schema, type: "object" }, "parameter");
+    }
+    validateValue(value, schema, label) {
+        const t = schema.type;
+        const errors = [];
+        if (t && Tool.typeMap[t] && !Tool.typeMap[t](value))
+            return [`${label} should be ${t}`];
+        if (schema.enum && !(schema.enum.includes(value)))
+            errors.push(`${label} must be one of ${JSON.stringify(schema.enum)}`);
+        if (t === "integer" || t === "number") {
+            if (typeof value === "number") {
+                if (typeof schema.minimum === "number" && value < schema.minimum)
+                    errors.push(`${label} must be >= ${schema.minimum}`);
+                if (typeof schema.maximum === "number" && value > schema.maximum)
+                    errors.push(`${label} must be <= ${schema.maximum}`);
+            }
+        }
+        if (t === "string" && typeof value === "string") {
+            if (typeof schema.minLength === "number" && value.length < schema.minLength)
+                errors.push(`${label} must be at least ${schema.minLength} chars`);
+            if (typeof schema.maxLength === "number" && value.length > schema.maxLength)
+                errors.push(`${label} must be at most ${schema.maxLength} chars`);
+        }
+        if (t === "object" && value && typeof value === "object" && !Array.isArray(value)) {
+            const v = value;
+            const props = (schema.properties ?? {});
+            for (const req of (schema.required ?? [])) {
+                if (!(req in v))
+                    errors.push(`missing required ${label === "parameter" ? req : `${label}.${req}`}`);
+            }
+            for (const [k, child] of Object.entries(v)) {
+                if (props[k])
+                    errors.push(...this.validateValue(child, props[k], label === "parameter" ? k : `${label}.${k}`));
+            }
+        }
+        if (t === "array" && Array.isArray(value) && schema.items && typeof schema.items === "object") {
+            value.forEach((item, i) => errors.push(...this.validateValue(item, schema.items, `${label}[${i}]`)));
+        }
+        return errors;
+    }
+    toSchema() {
+        return { type: "function", function: { name: this.name, description: this.description, parameters: this.parameters } };
+    }
+}

package/dist/agent/tools/cron.d.ts

@@ -0,0 +1,43 @@
+import { Tool } from "./base.js";
+import type { CronService } from "../../cron/service.js";
+export declare class CronTool extends Tool {
+    private readonly cron;
+    readonly name = "cron";
+    readonly description = "Schedule reminders and recurring tasks. Actions: add, list, remove.";
+    readonly parameters: {
+        type: string;
+        properties: {
+            action: {
+                type: string;
+                enum: string[];
+            };
+            message: {
+                type: string;
+            };
+            every_seconds: {
+                type: string;
+            };
+            cron_expr: {
+                type: string;
+            };
+            tz: {
+                type: string;
+            };
+            at: {
+                type: string;
+            };
+            job_id: {
+                type: string;
+            };
+        };
+        required: string[];
+    };
+    private channel;
+    private chatId;
+    constructor(cron: CronService);
+    setContext(channel: string, chatId: string): void;
+    execute(args: Record<string, unknown>): Promise<string>;
+    private addJob;
+    private listJobs;
+    private removeJob;
+}

package/dist/agent/tools/cron.js

@@ -0,0 +1,83 @@
+import { Tool } from "./base.js";
+export class CronTool extends Tool {
+    cron;
+    name = "cron";
+    description = "Schedule reminders and recurring tasks. Actions: add, list, remove.";
+    parameters = {
+        type: "object",
+        properties: {
+            action: { type: "string", enum: ["add", "list", "remove"] },
+            message: { type: "string" },
+            every_seconds: { type: "integer" },
+            cron_expr: { type: "string" },
+            tz: { type: "string" },
+            at: { type: "string" },
+            job_id: { type: "string" },
+        },
+        required: ["action"],
+    };
+    channel = "";
+    chatId = "";
+    constructor(cron) {
+        super();
+        this.cron = cron;
+    }
+    setContext(channel, chatId) {
+        this.channel = channel;
+        this.chatId = chatId;
+    }
+    async execute(args) {
+        const action = String(args.action ?? "");
+        if (action === "add")
+            return this.addJob(args);
+        if (action === "list")
+            return this.listJobs();
+        if (action === "remove")
+            return this.removeJob(String(args.job_id ?? ""));
+        return `Unknown action: ${action}`;
+    }
+    addJob(args) {
+        const message = String(args.message ?? "");
+        if (!message)
+            return "Error: message is required for add";
+        if (!this.channel || !this.chatId)
+            return "Error: no session context (channel/chat_id)";
+        const every = args.every_seconds != null ? Number(args.every_seconds) : null;
+        const cronExpr = args.cron_expr != null ? String(args.cron_expr) : null;
+        const tz = args.tz != null ? String(args.tz) : null;
+        const at = args.at != null ? String(args.at) : null;
+        let schedule;
+        let deleteAfterRun = false;
+        if (every)
+            schedule = { kind: "every", everyMs: every * 1000 };
+        else if (cronExpr)
+            schedule = { kind: "cron", expr: cronExpr, tz: tz ?? undefined };
+        else if (at) {
+            const dt = new Date(at);
+            if (Number.isNaN(dt.getTime()))
+                return "Error: invalid ISO datetime in at";
+            schedule = { kind: "at", atMs: dt.getTime() };
+            deleteAfterRun = true;
+        }
+        else
+            return "Error: either every_seconds, cron_expr, or at is required";
+        try {
+            const job = this.cron.addJob({ name: message.slice(0, 30), schedule, message, deliver: true, channel: this.channel, to: this.chatId, deleteAfterRun });
+            return `Created job '${job.name}' (id: ${job.id})`;
+        }
+        catch (err) {
+            return `Error: ${String(err).replace(/^Error:\s*/, "")}`;
+        }
+    }
+    listJobs() {
+        const jobs = this.cron.listJobs();
+        if (!jobs.length)
+            return "No scheduled jobs.";
+        return `Scheduled jobs:\n${jobs.map((j) => `- ${j.name} (id: ${j.id}, ${j.schedule.kind})`).join("\n")}`;
+    }
+    removeJob(id) {
+        if (!id)
+            return "Error: job_id is required for remove";
+        return this.cron.removeJob(id) ? `Removed job ${id}` : `Job ${id} not found`;
+    }
+}

package/dist/agent/tools/filesystem.d.ts

@@ -0,0 +1,79 @@
+import { Tool } from "./base.js";
+export declare class ReadFileTool extends Tool {
+    private readonly workspace?;
+    private readonly allowedDir?;
+    readonly name = "read_file";
+    readonly description = "Read the contents of a file at the given path.";
+    readonly parameters: {
+        type: string;
+        properties: {
+            path: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    constructor(workspace?: string | undefined, allowedDir?: string | undefined);
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+export declare class WriteFileTool extends Tool {
+    private readonly workspace?;
+    private readonly allowedDir?;
+    readonly name = "write_file";
+    readonly description = "Write content to a file at the given path. Creates parent directories if needed.";
+    readonly parameters: {
+        type: string;
+        properties: {
+            path: {
+                type: string;
+            };
+            content: {
+                type: string;
+            };
+        };
+        required: string[];
+    };
+    constructor(workspace?: string | undefined, allowedDir?: string | undefined);
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+export declare class EditFileTool extends Tool {
+    private readonly workspace?;
+    private readonly allowedDir?;
+    readonly name = "edit_file";
+    readonly description = "Edit a file by replacing old_text with new_text. The old_text must exist exactly in the file.";
+    readonly parameters: {
+        type: string;
+        properties: {
+            path: {
+                type: string;
+            };
+            old_text: {
+                type: string;
+            };
+            new_text: {
+                type: string;
+            };
+        };
+        required: string[];
+    };
+    constructor(workspace?: string | undefined, allowedDir?: string | undefined);
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+export declare class ListDirTool extends Tool {
+    private readonly workspace?;
+    private readonly allowedDir?;
+    readonly name = "list_dir";
+    readonly description = "List the contents of a directory.";
+    readonly parameters: {
+        type: string;
+        properties: {
+            path: {
+                type: string;
+            };
+        };
+        required: string[];
+    };
+    constructor(workspace?: string | undefined, allowedDir?: string | undefined);
+    execute(args: Record<string, unknown>): Promise<string>;
+}

package/dist/agent/tools/filesystem.js

@@ -0,0 +1,125 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Tool } from "./base.js";
+function resolvePath(input, workspace, allowedDir) {
+    const expanded = input.startsWith("~") ? path.join(process.env.USERPROFILE || process.env.HOME || "", input.slice(1)) : input;
+    const base = path.isAbsolute(expanded) ? expanded : workspace ? path.join(workspace, expanded) : expanded;
+    const resolved = path.resolve(base);
+    if (allowedDir) {
+        const allow = path.resolve(allowedDir);
+        if (!resolved.startsWith(allow))
+            throw new Error(`Path ${input} is outside allowed directory ${allowedDir}`);
+    }
+    return resolved;
+}
+export class ReadFileTool extends Tool {
+    workspace;
+    allowedDir;
+    name = "read_file";
+    description = "Read the contents of a file at the given path.";
+    parameters = { type: "object", properties: { path: { type: "string", description: "The file path to read" } }, required: ["path"] };
+    constructor(workspace, allowedDir) {
+        super();
+        this.workspace = workspace;
+        this.allowedDir = allowedDir;
+    }
+    async execute(args) {
+        try {
+            const p = resolvePath(String(args.path), this.workspace, this.allowedDir);
+            if (!fs.existsSync(p))
+                return `Error: File not found: ${String(args.path)}`;
+            if (!fs.statSync(p).isFile())
+                return `Error: Not a file: ${String(args.path)}`;
+            return fs.readFileSync(p, "utf8");
+        }
+        catch (err) {
+            return `Error reading file: ${String(err)}`;
+        }
+    }
+}
+export class WriteFileTool extends Tool {
+    workspace;
+    allowedDir;
+    name = "write_file";
+    description = "Write content to a file at the given path. Creates parent directories if needed.";
+    parameters = { type: "object", properties: { path: { type: "string" }, content: { type: "string" } }, required: ["path", "content"] };
+    constructor(workspace, allowedDir) {
+        super();
+        this.workspace = workspace;
+        this.allowedDir = allowedDir;
+    }
+    async execute(args) {
+        try {
+            const p = resolvePath(String(args.path), this.workspace, this.allowedDir);
+            fs.mkdirSync(path.dirname(p), { recursive: true });
+            const content = String(args.content ?? "");
+            fs.writeFileSync(p, content, "utf8");
+            return `Successfully wrote ${content.length} bytes to ${p}`;
+        }
+        catch (err) {
+            return `Error writing file: ${String(err)}`;
+        }
+    }
+}
+export class EditFileTool extends Tool {
+    workspace;
+    allowedDir;
+    name = "edit_file";
+    description = "Edit a file by replacing old_text with new_text. The old_text must exist exactly in the file.";
+    parameters = { type: "object", properties: { path: { type: "string" }, old_text: { type: "string" }, new_text: { type: "string" } }, required: ["path", "old_text", "new_text"] };
+    constructor(workspace, allowedDir) {
+        super();
+        this.workspace = workspace;
+        this.allowedDir = allowedDir;
+    }
+    async execute(args) {
+        try {
+            const p = resolvePath(String(args.path), this.workspace, this.allowedDir);
+            if (!fs.existsSync(p))
+                return `Error: File not found: ${String(args.path)}`;
+            const content = fs.readFileSync(p, "utf8");
+            const oldText = String(args.old_text ?? "");
+            const newText = String(args.new_text ?? "");
+            if (!content.includes(oldText))
+                return `Error: old_text not found in ${String(args.path)}. Verify the file content.`;
+            if (content.split(oldText).length - 1 > 1)
+                return `Warning: old_text appears ${content.split(oldText).length - 1} times. Please provide more context to make it unique.`;
+            fs.writeFileSync(p, content.replace(oldText, newText), "utf8");
+            return `Successfully edited ${p}`;
+        }
+        catch (err) {
+            return `Error editing file: ${String(err)}`;
+        }
+    }
+}
+export class ListDirTool extends Tool {
+    workspace;
+    allowedDir;
+    name = "list_dir";
+    description = "List the contents of a directory.";
+    parameters = { type: "object", properties: { path: { type: "string" } }, required: ["path"] };
+    constructor(workspace, allowedDir) {
+        super();
+        this.workspace = workspace;
+        this.allowedDir = allowedDir;
+    }
+    async execute(args) {
+        try {
+            const p = resolvePath(String(args.path), this.workspace, this.allowedDir);
+            if (!fs.existsSync(p))
+                return `Error: Directory not found: ${String(args.path)}`;
+            if (!fs.statSync(p).isDirectory())
+                return `Error: Not a directory: ${String(args.path)}`;
+            const items = fs.readdirSync(p).sort().map((n) => {
+                const full = path.join(p, n);
+                return `${fs.statSync(full).isDirectory() ? "[DIR]" : "[FILE]"} ${n}`;
+            });
+            if (!items.length)
+                return `Directory ${String(args.path)} is empty`;
+            return items.join("\n");
+        }
+        catch (err) {
+            return `Error listing directory: ${String(err)}`;
+        }
+    }
+}

package/dist/agent/tools/message.d.ts

@@ -0,0 +1,41 @@
+import { Tool } from "./base.js";
+import type { OutboundMessage } from "../../bus/events.js";
+export declare class MessageTool extends Tool {
+    private sendCallback?;
+    readonly name = "message";
+    readonly description = "Send a message to the user. Use this when you want to communicate something.";
+    readonly parameters: {
+        type: string;
+        properties: {
+            content: {
+                type: string;
+                description: string;
+            };
+            channel: {
+                type: string;
+                description: string;
+            };
+            chat_id: {
+                type: string;
+                description: string;
+            };
+            media: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    private defaultChannel;
+    private defaultChatId;
+    private defaultMessageId;
+    sentInTurn: boolean;
+    constructor(sendCallback?: ((msg: OutboundMessage) => Promise<void>) | undefined);
+    setContext(channel: string, chatId: string, messageId?: string): void;
+    setSendCallback(cb: (msg: OutboundMessage) => Promise<void>): void;
+    startTurn(): void;
+    execute(args: Record<string, unknown>): Promise<string>;
+}

package/dist/agent/tools/message.js

@@ -0,0 +1,55 @@
+import { Tool } from "./base.js";
+export class MessageTool extends Tool {
+    sendCallback;
+    name = "message";
+    description = "Send a message to the user. Use this when you want to communicate something.";
+    parameters = {
+        type: "object",
+        properties: {
+            content: { type: "string", description: "The message content to send" },
+            channel: { type: "string", description: "Optional target channel" },
+            chat_id: { type: "string", description: "Optional target chat/user ID" },
+            media: { type: "array", items: { type: "string" }, description: "Optional file attachments" },
+        },
+        required: ["content"],
+    };
+    defaultChannel = "";
+    defaultChatId = "";
+    defaultMessageId = null;
+    sentInTurn = false;
+    constructor(sendCallback) {
+        super();
+        this.sendCallback = sendCallback;
+    }
+    setContext(channel, chatId, messageId) {
+        this.defaultChannel = channel;
+        this.defaultChatId = chatId;
+        this.defaultMessageId = messageId ?? null;
+    }
+    setSendCallback(cb) {
+        this.sendCallback = cb;
+    }
+    startTurn() {
+        this.sentInTurn = false;
+    }
+    async execute(args) {
+        const content = String(args.content ?? "");
+        const channel = String(args.channel ?? this.defaultChannel);
+        const chatId = String(args.chat_id ?? this.defaultChatId);
+        const messageId = String(args.message_id ?? this.defaultMessageId ?? "");
+        const media = Array.isArray(args.media) ? args.media : [];
+        if (!channel || !chatId)
+            return "Error: No target channel/chat specified";
+        if (!this.sendCallback)
+            return "Error: Message sending not configured";
+        try {
+            await this.sendCallback({ channel, chatId, content, media, metadata: { message_id: messageId } });
+            if (channel === this.defaultChannel && chatId === this.defaultChatId)
+                this.sentInTurn = true;
+            return `Message sent to ${channel}:${chatId}${media.length ? ` with ${media.length} attachments` : ""}`;
+        }
+        catch (err) {
+            return `Error sending message: ${String(err)}`;
+        }
+    }
+}

package/dist/agent/tools/registry.d.ts

@@ -0,0 +1,9 @@
+import { Tool } from "./base.js";
+export declare class ToolRegistry {
+    private tools;
+    register(tool: Tool): void;
+    get(name: string): Tool | undefined;
+    getDefinitions(): Array<Record<string, unknown>>;
+    get toolNames(): string[];
+    execute(name: string, params: Record<string, unknown>): Promise<string>;
+}

package/dist/agent/tools/registry.js

@@ -0,0 +1,33 @@
+export class ToolRegistry {
+    tools = new Map();
+    register(tool) {
+        this.tools.set(tool.name, tool);
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+    getDefinitions() {
+        return [...this.tools.values()].map((t) => t.toSchema());
+    }
+    get toolNames() {
+        return [...this.tools.keys()];
+    }
+    async execute(name, params) {
+        const hint = "\n\n[Analyze the error above and try a different approach.]";
+        const tool = this.tools.get(name);
+        if (!tool)
+            return `Error: Tool '${name}' not found. Available: ${this.toolNames.join(", ")}`;
+        try {
+            const errors = tool.validateParams(params);
+            if (errors.length)
+                return `Error: Invalid parameters for tool '${name}': ${errors.join("; ")}${hint}`;
+            const result = await tool.execute(params);
+            if (result.startsWith("Error"))
+                return result + hint;
+            return result;
+        }
+        catch (err) {
+            return `Error executing ${name}: ${String(err)}${hint}`;
+        }
+    }
+}

package/dist/agent/tools/shell.d.ts

@@ -0,0 +1,26 @@
+import { Tool } from "./base.js";
+export declare class ExecTool extends Tool {
+    private readonly timeout;
+    private readonly workingDir?;
+    private readonly restrictToWorkspace;
+    private readonly pathAppend;
+    readonly name = "exec";
+    readonly description = "Execute a shell command and return its output. Use with caution.";
+    readonly parameters: {
+        type: string;
+        properties: {
+            command: {
+                type: string;
+                description: string;
+            };
+            working_dir: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    constructor(timeout?: number, workingDir?: string | undefined, restrictToWorkspace?: boolean, pathAppend?: string);
+    private guard;
+    execute(args: Record<string, unknown>): Promise<string>;
+}

package/dist/agent/tools/shell.js

@@ -0,0 +1,78 @@
+import { exec } from "node:child_process";
+import path from "node:path";
+import { promisify } from "node:util";
+import { Tool } from "./base.js";
+const execAsync = promisify(exec);
+export class ExecTool extends Tool {
+    timeout;
+    workingDir;
+    restrictToWorkspace;
+    pathAppend;
+    name = "exec";
+    description = "Execute a shell command and return its output. Use with caution.";
+    parameters = {
+        type: "object",
+        properties: {
+            command: { type: "string", description: "The shell command to execute" },
+            working_dir: { type: "string", description: "Optional working directory for the command" },
+        },
+        required: ["command"],
+    };
+    constructor(timeout = 60, workingDir, restrictToWorkspace = false, pathAppend = "") {
+        super();
+        this.timeout = timeout;
+        this.workingDir = workingDir;
+        this.restrictToWorkspace = restrictToWorkspace;
+        this.pathAppend = pathAppend;
+    }
+    guard(command, cwd) {
+        const lower = command.toLowerCase();
+        const deny = [/\brm\s+-[rf]{1,2}\b/, /\bdel\s+\/[fq]\b/, /\brmdir\s+\/s\b/, /(?:^|[;&|]\s*)format\b/, /\b(mkfs|diskpart)\b/, /\bdd\s+if=/, />\s*\/dev\/sd/, /\b(shutdown|reboot|poweroff)\b/, /:\(\)\s*\{.*\};\s*:/];
+        if (deny.some((r) => r.test(lower)))
+            return "Error: Command blocked by safety guard (dangerous pattern detected)";
+        if (this.restrictToWorkspace) {
+            if (command.includes("../") || command.includes("..\\"))
+                return "Error: Command blocked by safety guard (path traversal detected)";
+            const abs = command.match(/[A-Za-z]:\\[^\s"']+/g) ?? [];
+            for (const raw of abs) {
+                const p = path.resolve(raw);
+                const c = path.resolve(cwd);
+                if (!p.startsWith(c))
+                    return "Error: Command blocked by safety guard (path outside working dir)";
+            }
+        }
+        return null;
+    }
+    async execute(args) {
+        const command = String(args.command ?? "");
+        const cwd = String(args.working_dir ?? this.workingDir ?? process.cwd());
+        const blocked = this.guard(command, cwd);
+        if (blocked)
+            return blocked;
+        const env = { ...process.env };
+        if (this.pathAppend)
+            env.PATH = `${env.PATH ?? ""}${path.delimiter}${this.pathAppend}`;
+        try {
+            const { stdout, stderr } = await execAsync(command, { cwd, env, timeout: this.timeout * 1000, maxBuffer: 1024 * 1024 });
+            let out = "";
+            if (stdout)
+                out += stdout;
+            if (stderr?.trim())
+                out += `${out ? "\n" : ""}STDERR:\n${stderr}`;
+            if (!out)
+                out = "(no output)";
+            if (out.length > 10000)
+                out = `${out.slice(0, 10000)}\n... (truncated, ${out.length - 10000} more chars)`;
+            return out;
+        }
+        catch (err) {
+            if (typeof err?.killed === "boolean" && err.killed)
+                return `Error: Command timed out after ${this.timeout} seconds`;
+            const stdout = err?.stdout ? `${err.stdout}\n` : "";
+            const stderr = err?.stderr ? `STDERR:\n${err.stderr}\n` : "";
+            const code = typeof err?.code === "number" ? `\nExit code: ${err.code}` : "";
+            const text = `${stdout}${stderr}${code}`.trim();
+            return text || `Error executing command: ${String(err)}`;
+        }
+    }
+}

package/dist/agent/tools/spawn.d.ts

@@ -0,0 +1,27 @@
+import { Tool } from "./base.js";
+import type { SubagentManager } from "../subagent.js";
+export declare class SpawnTool extends Tool {
+    private readonly manager;
+    readonly name = "spawn";
+    readonly description = "Spawn a subagent to handle a task in the background.";
+    readonly parameters: {
+        type: string;
+        properties: {
+            task: {
+                type: string;
+                description: string;
+            };
+            label: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    private originChannel;
+    private originChatId;
+    private sessionKey;
+    constructor(manager: SubagentManager);
+    setContext(channel: string, chatId: string): void;
+    execute(args: Record<string, unknown>): Promise<string>;
+}