pretticlaw 0.1.0

package/src/agent/memory.ts

@@ -0,0 +1,104 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { LLMProvider } from "../providers/base.js";
+import type { Session } from "../session/manager.js";
+
+const SAVE_MEMORY_TOOL = [{
+  type: "function",
+  function: {
+    name: "save_memory",
+    description: "Save the memory consolidation result to persistent storage.",
+    parameters: {
+      type: "object",
+      properties: {
+        history_entry: { type: "string" },
+        memory_update: { type: "string" },
+      },
+      required: ["history_entry", "memory_update"],
+    },
+  },
+}];
+
+export class MemoryStore {
+  readonly memoryDir: string;
+  readonly memoryFile: string;
+  readonly historyFile: string;
+
+  constructor(workspace: string) {
+    this.memoryDir = path.join(workspace, "memory");
+    fs.mkdirSync(this.memoryDir, { recursive: true });
+    this.memoryFile = path.join(this.memoryDir, "MEMORY.md");
+    this.historyFile = path.join(this.memoryDir, "HISTORY.md");
+  }
+
+  readLongTerm(): string {
+    return fs.existsSync(this.memoryFile) ? fs.readFileSync(this.memoryFile, "utf8") : "";
+  }
+
+  writeLongTerm(content: string): void {
+    fs.writeFileSync(this.memoryFile, content, "utf8");
+  }
+
+  appendHistory(entry: string): void {
+    fs.appendFileSync(this.historyFile, `${entry.trim()}\n\n`, "utf8");
+  }
+
+  getMemoryContext(): string {
+    const longTerm = this.readLongTerm();
+    return longTerm ? `## Long-term Memory\n${longTerm}` : "";
+  }
+
+  async consolidate(session: Session, provider: LLMProvider, model: string, opts?: { archiveAll?: boolean; memoryWindow?: number }): Promise<boolean> {
+    const archiveAll = opts?.archiveAll ?? false;
+    const memoryWindow = opts?.memoryWindow ?? 50;
+
+    let oldMessages = [] as any[];
+    let keepCount = 0;
+    if (archiveAll) {
+      oldMessages = session.messages;
+      keepCount = 0;
+    } else {
+      keepCount = Math.floor(memoryWindow / 2);
+      if (session.messages.length <= keepCount) return true;
+      if (session.messages.length - session.lastConsolidated <= 0) return true;
+      oldMessages = session.messages.slice(session.lastConsolidated, session.messages.length - keepCount);
+      if (!oldMessages.length) return true;
+    }
+
+    const lines: string[] = [];
+    for (const m of oldMessages) {
+      if (!m.content) continue;
+      const tools = Array.isArray(m.tools_used) && m.tools_used.length ? ` [tools: ${m.tools_used.join(", ")}]` : "";
+      lines.push(`[${String(m.timestamp ?? "?").slice(0, 16)}] ${String(m.role).toUpperCase()}${tools}: ${String(m.content)}`);
+    }
+
+    const currentMemory = this.readLongTerm();
+    const prompt = `Process this conversation and call the save_memory tool with your consolidation.\n\n## Current Long-term Memory\n${currentMemory || "(empty)"}\n\n## Conversation to Process\n${lines.join("\n")}`;
+
+    try {
+      const response = await provider.chat({
+        model,
+        messages: [
+          { role: "system", content: "You are a memory consolidation agent. Call the save_memory tool." },
+          { role: "user", content: prompt },
+        ],
+        tools: SAVE_MEMORY_TOOL,
+      });
+
+      if (!response.toolCalls.length) return false;
+      const call = response.toolCalls[0];
+      const args = call.arguments ?? {};
+      const entry = args.history_entry;
+      const update = args.memory_update;
+      if (entry != null) this.appendHistory(typeof entry === "string" ? entry : JSON.stringify(entry));
+      if (update != null) {
+        const text = typeof update === "string" ? update : JSON.stringify(update);
+        if (text !== currentMemory) this.writeLongTerm(text);
+      }
+      session.lastConsolidated = archiveAll ? 0 : session.messages.length - keepCount;
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/agent/skills.ts

@@ -0,0 +1,121 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const BUILTIN_SKILLS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../skills");
+
+export class SkillsLoader {
+  private readonly workspaceSkills: string;
+  private readonly builtinSkills: string;
+
+  constructor(workspace: string, builtinSkillsDir = BUILTIN_SKILLS_DIR) {
+    this.workspaceSkills = path.join(workspace, "skills");
+    this.builtinSkills = builtinSkillsDir;
+  }
+
+  listSkills(filterUnavailable = true): Array<{ name: string; path: string; source: string }> {
+    const skills: Array<{ name: string; path: string; source: string }> = [];
+    const load = (root: string, source: string) => {
+      if (!fs.existsSync(root)) return;
+      for (const name of fs.readdirSync(root)) {
+        const skillFile = path.join(root, name, "SKILL.md");
+        if (!fs.existsSync(skillFile)) continue;
+        if (skills.some((s) => s.name === name)) continue;
+        skills.push({ name, path: skillFile, source });
+      }
+    };
+    load(this.workspaceSkills, "workspace");
+    load(this.builtinSkills, "builtin");
+
+    if (!filterUnavailable) return skills;
+    return skills.filter((s) => this.checkRequirements(this.getSkillMeta(s.name)));
+  }
+
+  loadSkill(name: string): string | null {
+    const workspace = path.join(this.workspaceSkills, name, "SKILL.md");
+    if (fs.existsSync(workspace)) return fs.readFileSync(workspace, "utf8");
+    const builtin = path.join(this.builtinSkills, name, "SKILL.md");
+    if (fs.existsSync(builtin)) return fs.readFileSync(builtin, "utf8");
+    return null;
+  }
+
+  loadSkillsForContext(skillNames: string[]): string {
+    const parts: string[] = [];
+    for (const name of skillNames) {
+      const c = this.loadSkill(name);
+      if (c) parts.push(`### Skill: ${name}\n\n${this.stripFrontmatter(c)}`);
+    }
+    return parts.join("\n\n---\n\n");
+  }
+
+  buildSkillsSummary(): string {
+    const all = this.listSkills(false);
+    if (!all.length) return "";
+    const esc = (s: string) => s.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+    const lines = ["<skills>"];
+    for (const s of all) {
+      const meta = this.getSkillMetadata(s.name) ?? {};
+      const prettiMeta = this.getSkillMeta(s.name);
+      const available = this.checkRequirements(prettiMeta);
+      lines.push(`  <skill available="${available}">`);
+      lines.push(`    <name>${esc(s.name)}</name>`);
+      lines.push(`    <description>${esc((meta.description as string) || s.name)}</description>`);
+      lines.push(`    <location>${s.path}</location>`);
+      lines.push("  </skill>");
+    }
+    lines.push("</skills>");
+    return lines.join("\n");
+  }
+
+  getAlwaysSkills(): string[] {
+    const out: string[] = [];
+    for (const s of this.listSkills(true)) {
+      const meta = this.getSkillMetadata(s.name) ?? {};
+      const m = this.getSkillMeta(s.name);
+      if (m.always || meta.always) out.push(s.name);
+    }
+    return out;
+  }
+
+  getSkillMetadata(name: string): Record<string, unknown> | null {
+    const content = this.loadSkill(name);
+    if (!content?.startsWith("---")) return null;
+    const m = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!m) return null;
+    const out: Record<string, unknown> = {};
+    for (const line of m[1].split(/\r?\n/)) {
+      const idx = line.indexOf(":");
+      if (idx <= 0) continue;
+      out[line.slice(0, idx).trim()] = line.slice(idx + 1).trim().replace(/^['"]|['"]$/g, "");
+    }
+    return out;
+  }
+
+  private stripFrontmatter(content: string): string {
+    const m = content.match(/^---\n[\s\S]*?\n---\n?/);
+    return m ? content.slice(m[0].length).trim() : content;
+  }
+
+  private getSkillMeta(name: string): Record<string, any> {
+    const meta = this.getSkillMetadata(name) ?? {};
+    const raw = typeof meta.metadata === "string" ? meta.metadata : "{}";
+    try {
+      const data = JSON.parse(raw);
+      return data.pretticlaw || data.openclaw || {};
+    } catch {
+      return {};
+    }
+  }
+
+  private checkRequirements(skillMeta: Record<string, any>): boolean {
+    const req = skillMeta.requires ?? {};
+    const bins: string[] = req.bins ?? [];
+    const env: string[] = req.env ?? [];
+    const hasBin = (name: string) => {
+      const pathEntries = (process.env.PATH ?? "").split(path.delimiter);
+      const exts = process.platform === "win32" ? ["", ".exe", ".cmd", ".bat"] : [""];
+      return pathEntries.some((p) => exts.some((e) => fs.existsSync(path.join(p, `${name}${e}`))));
+    };
+    return bins.every(hasBin) && env.every((k) => !!process.env[k]);
+  }
+}

package/src/agent/subagent.ts

@@ -0,0 +1,96 @@
+import { randomUUID } from "node:crypto";
+import type { MessageBus } from "../bus/queue.js";
+import type { LLMProvider } from "../providers/base.js";
+import type { InboundMessage } from "../bus/events.js";
+import { ToolRegistry } from "./tools/registry.js";
+import { ReadFileTool, WriteFileTool, EditFileTool, ListDirTool } from "./tools/filesystem.js";
+import { ExecTool } from "./tools/shell.js";
+import { WebSearchTool, WebFetchTool } from "./tools/web.js";
+
+export class SubagentManager {
+  private running = new Map<string, Promise<void>>();
+  private sessionTasks = new Map<string, Set<string>>();
+
+  constructor(
+    private readonly provider: LLMProvider,
+    private readonly workspace: string,
+    private readonly bus: MessageBus,
+    private readonly model: string,
+    private readonly temperature: number,
+    private readonly maxTokens: number,
+    private readonly braveApiKey: string | null,
+    private readonly execConfig: { timeout: number; pathAppend: string },
+    private readonly restrictToWorkspace: boolean,
+  ) {}
+
+  async spawn(input: { task: string; label: string | null; originChannel: string; originChatId: string; sessionKey: string }): Promise<string> {
+    const taskId = randomUUID().slice(0, 8);
+    const label = input.label ?? (input.task.length > 30 ? `${input.task.slice(0, 30)}...` : input.task);
+
+    const p = this.runSubagent(taskId, input.task, label, { channel: input.originChannel, chatId: input.originChatId })
+      .finally(() => {
+        this.running.delete(taskId);
+        const ids = this.sessionTasks.get(input.sessionKey);
+        if (ids) {
+          ids.delete(taskId);
+          if (!ids.size) this.sessionTasks.delete(input.sessionKey);
+        }
+      });
+
+    this.running.set(taskId, p);
+    if (!this.sessionTasks.has(input.sessionKey)) this.sessionTasks.set(input.sessionKey, new Set());
+    this.sessionTasks.get(input.sessionKey)!.add(taskId);
+
+    return `Subagent [${label}] started (id: ${taskId}). I'll notify you when it completes.`;
+  }
+
+  private async runSubagent(taskId: string, task: string, label: string, origin: { channel: string; chatId: string }): Promise<void> {
+    const tools = new ToolRegistry();
+    const allowedDir = this.restrictToWorkspace ? this.workspace : undefined;
+    tools.register(new ReadFileTool(this.workspace, allowedDir));
+    tools.register(new WriteFileTool(this.workspace, allowedDir));
+    tools.register(new EditFileTool(this.workspace, allowedDir));
+    tools.register(new ListDirTool(this.workspace, allowedDir));
+    tools.register(new ExecTool(this.execConfig.timeout, this.workspace, this.restrictToWorkspace, this.execConfig.pathAppend));
+    tools.register(new WebSearchTool(this.braveApiKey));
+    tools.register(new WebFetchTool());
+
+    let messages: Array<Record<string, unknown>> = [
+      { role: "system", content: this.buildSubagentPrompt() },
+      { role: "user", content: task },
+    ];
+
+    let finalResult = "Task completed but no final response was generated.";
+    for (let i = 0; i < 15; i++) {
+      const response = await this.provider.chat({ messages, tools: tools.getDefinitions(), model: this.model, temperature: this.temperature, maxTokens: this.maxTokens });
+      if (response.toolCalls.length) {
+        messages.push({ role: "assistant", content: response.content ?? "", tool_calls: response.toolCalls.map((tc) => ({ id: tc.id, type: "function", function: { name: tc.name, arguments: JSON.stringify(tc.arguments) } })) });
+        for (const tc of response.toolCalls) {
+          const result = await tools.execute(tc.name, tc.arguments);
+          messages.push({ role: "tool", tool_call_id: tc.id, name: tc.name, content: result });
+        }
+      } else {
+        finalResult = response.content ?? finalResult;
+        break;
+      }
+    }
+
+    const announceContent = `[Subagent '${label}' completed successfully]\n\nTask: ${task}\n\nResult:\n${finalResult}\n\nSummarize this naturally for the user. Keep it brief (1-2 sentences).`;
+    const msg: InboundMessage = { channel: "system", senderId: "subagent", chatId: `${origin.channel}:${origin.chatId}`, content: announceContent };
+    await this.bus.publishInbound(msg);
+  }
+
+  private buildSubagentPrompt(): string {
+    const now = new Date().toLocaleString();
+    return `# Subagent\n\nCurrent Time: ${now}\n\nYou are a subagent spawned by the main agent to complete a specific task. Stay focused and concise.`;
+  }
+
+  async cancelBySession(sessionKey: string): Promise<number> {
+    const ids = [...(this.sessionTasks.get(sessionKey) ?? [])];
+    return ids.filter((id) => this.running.has(id)).length;
+  }
+
+  getRunningCount(): number {
+    return this.running.size;
+  }
+}

package/src/agent/tools/base.ts

@@ -0,0 +1,59 @@
+export abstract class Tool {
+  protected static typeMap: Record<string, (v: unknown) => boolean> = {
+    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),
+  };
+
+  abstract readonly name: string;
+  abstract readonly description: string;
+  abstract readonly parameters: Record<string, unknown>;
+  abstract execute(args: Record<string, unknown>): Promise<string>;
+
+  validateParams(params: Record<string, unknown>): string[] {
+    const schema = (this.parameters ?? {}) as Record<string, unknown>;
+    if ((schema.type as string | undefined) !== "object") {
+      throw new Error(`Schema must be object type, got ${String(schema.type)}`);
+    }
+    return this.validateValue(params, { ...schema, type: "object" }, "parameter");
+  }
+
+  private validateValue(value: unknown, schema: Record<string, unknown>, label: string): string[] {
+    const t = schema.type as string | undefined;
+    const errors: string[] = [];
+    if (t && Tool.typeMap[t] && !Tool.typeMap[t](value)) return [`${label} should be ${t}`];
+
+    if (schema.enum && !((schema.enum as unknown[]).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 as Record<string, unknown>;
+      const props = (schema.properties ?? {}) as Record<string, Record<string, unknown>>;
+      for (const req of (schema.required ?? []) as string[]) {
+        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 as Record<string, unknown>, `${label}[${i}]`)));
+    }
+    return errors;
+  }
+
+  toSchema(): Record<string, unknown> {
+    return { type: "function", function: { name: this.name, description: this.description, parameters: this.parameters } };
+  }
+}

package/src/agent/tools/cron.ts

@@ -0,0 +1,79 @@
+import { Tool } from "./base.js";
+import type { CronService } from "../../cron/service.js";
+import type { CronSchedule } from "../../cron/types.js";
+
+export class CronTool extends Tool {
+  readonly name = "cron";
+  readonly description = "Schedule reminders and recurring tasks. Actions: add, list, remove.";
+  readonly 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"],
+  };
+
+  private channel = "";
+  private chatId = "";
+
+  constructor(private readonly cron: CronService) { super(); }
+
+  setContext(channel: string, chatId: string): void {
+    this.channel = channel;
+    this.chatId = chatId;
+  }
+
+  async execute(args: Record<string, unknown>): Promise<string> {
+    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}`;
+  }
+
+  private addJob(args: Record<string, unknown>): string {
+    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: CronSchedule;
+    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*/, "")}`;
+    }
+  }
+
+  private listJobs(): string {
+    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")}`;
+  }
+
+  private removeJob(id: string): string {
+    if (!id) return "Error: job_id is required for remove";
+    return this.cron.removeJob(id) ? `Removed job ${id}` : `Job ${id} not found`;
+  }
+}

package/src/agent/tools/filesystem.ts

@@ -0,0 +1,93 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Tool } from "./base.js";
+
+function resolvePath(input: string, workspace?: string, allowedDir?: string): string {
+  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 {
+  readonly name = "read_file";
+  readonly description = "Read the contents of a file at the given path.";
+  readonly parameters = { type: "object", properties: { path: { type: "string", description: "The file path to read" } }, required: ["path"] };
+  constructor(private readonly workspace?: string, private readonly allowedDir?: string) { super(); }
+  async execute(args: Record<string, unknown>): Promise<string> {
+    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 {
+  readonly name = "write_file";
+  readonly description = "Write content to a file at the given path. Creates parent directories if needed.";
+  readonly parameters = { type: "object", properties: { path: { type: "string" }, content: { type: "string" } }, required: ["path", "content"] };
+  constructor(private readonly workspace?: string, private readonly allowedDir?: string) { super(); }
+  async execute(args: Record<string, unknown>): Promise<string> {
+    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 {
+  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: "object", properties: { path: { type: "string" }, old_text: { type: "string" }, new_text: { type: "string" } }, required: ["path", "old_text", "new_text"] };
+  constructor(private readonly workspace?: string, private readonly allowedDir?: string) { super(); }
+  async execute(args: Record<string, unknown>): Promise<string> {
+    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 {
+  readonly name = "list_dir";
+  readonly description = "List the contents of a directory.";
+  readonly parameters = { type: "object", properties: { path: { type: "string" } }, required: ["path"] };
+  constructor(private readonly workspace?: string, private readonly allowedDir?: string) { super(); }
+  async execute(args: Record<string, unknown>): Promise<string> {
+    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/src/agent/tools/message.ts

@@ -0,0 +1,57 @@
+import { Tool } from "./base.js";
+import type { OutboundMessage } from "../../bus/events.js";
+
+export class MessageTool extends Tool {
+  readonly name = "message";
+  readonly description = "Send a message to the user. Use this when you want to communicate something.";
+  readonly 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"],
+  };
+
+  private defaultChannel = "";
+  private defaultChatId = "";
+  private defaultMessageId: string | null = null;
+  sentInTurn = false;
+
+  constructor(private sendCallback?: (msg: OutboundMessage) => Promise<void>) { super(); }
+
+  setContext(channel: string, chatId: string, messageId?: string): void {
+    this.defaultChannel = channel;
+    this.defaultChatId = chatId;
+    this.defaultMessageId = messageId ?? null;
+  }
+
+  setSendCallback(cb: (msg: OutboundMessage) => Promise<void>): void {
+    this.sendCallback = cb;
+  }
+
+  startTurn(): void {
+    this.sentInTurn = false;
+  }
+
+  async execute(args: Record<string, unknown>): Promise<string> {
+    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 as string[]) : [];
+
+    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/src/agent/tools/registry.ts

@@ -0,0 +1,36 @@
+import { Tool } from "./base.js";
+
+export class ToolRegistry {
+  private tools = new Map<string, Tool>();
+
+  register(tool: Tool): void {
+    this.tools.set(tool.name, tool);
+  }
+
+  get(name: string): Tool | undefined {
+    return this.tools.get(name);
+  }
+
+  getDefinitions(): Array<Record<string, unknown>> {
+    return [...this.tools.values()].map((t) => t.toSchema());
+  }
+
+  get toolNames(): string[] {
+    return [...this.tools.keys()];
+  }
+
+  async execute(name: string, params: Record<string, unknown>): Promise<string> {
+    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}`;
+    }
+  }
+}