@amanm/openpaw 0.1.0

package/agent/tools/file-editor.ts

@@ -0,0 +1,293 @@
+import { mkdir, readdir, readFile, stat, unlink, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { tool } from "ai";
+import { z } from "zod";
+import { popHistory, pushHistory } from "../file-editor-store";
+import { refreshSkillCatalog, type OpenPawSkillCatalog } from "../skill-catalog";
+import { resolveScopePath } from "../sandbox-paths";
+
+type ToolSuccess = { success: true; output: string };
+type ToolFailure = { success: false; error: string };
+
+/**
+ * Reads a file and returns numbered lines in Anthropic text-editor style: padded index, ` | `, content.
+ * Optional {@link viewRange} is `[start_line, end_line]` (1-based, inclusive); the slice uses the same
+ * rules as the classic str_replace editor (end is passed directly to {@link String#slice}’s end index).
+ */
+async function readFileWithLines(
+  absPath: string,
+  viewRange?: [number, number],
+): Promise<string> {
+  const raw = await readFile(absPath, "utf-8");
+  const lines = raw.split("\n");
+  const start = viewRange ? viewRange[0] - 1 : 0;
+  const end = viewRange ? viewRange[1] : lines.length;
+  const width = String(lines.length).length;
+  return lines
+    .slice(start, end)
+    .map((l, i) => `${String(start + i + 1).padStart(width)} | ${l}`)
+    .join("\n");
+}
+
+/**
+ * str_replace-style file editor (Anthropic `text_editor_20250728`-like), scoped by sandbox.
+ * Single flat input object so models can pass one JSON shape per call.
+ */
+const FileEditorInputSchema = z.object({
+  command: z
+    .enum([
+      "view",
+      "create",
+      "delete",
+      "str_replace",
+      "insert",
+      "delete_lines",
+      "undo_edit",
+    ])
+    .describe(
+      '"view" to read a file or list a directory, "create" to write a new file, ' +
+        '"delete" to remove a file, "str_replace" for an exact substring replace, ' +
+        '"insert" to add lines after a line number, "delete_lines" to remove a line range, ' +
+        '"undo_edit" to revert the last mutating change to that path.',
+    ),
+
+  path: z.string().describe("Relative or absolute path (sandbox still applies)."),
+
+  view_range: z
+    .array(z.number().int().positive())
+    .length(2)
+    .optional()
+    .describe("Optional [start_line, end_line] to view a slice (1-indexed, inclusive)."),
+
+  file_text: z.string().optional().describe('Full content for "create".'),
+
+  old_str: z
+    .string()
+    .optional()
+    .describe(
+      "Exact string to find for str_replace — must match whitespace/indentation; copy from view output.",
+    ),
+
+  new_str: z
+    .string()
+    .optional()
+    .describe("Replacement for str_replace; may be empty to delete old_str."),
+
+  insert_line: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe("Insert insert_text AFTER this line; 0 inserts at the top."),
+
+  insert_text: z.string().optional().describe("Text to insert (may be multiple lines)."),
+
+  start_line: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe("First line to delete (1-based, inclusive) for delete_lines."),
+
+  end_line: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe("Last line to delete (1-based, inclusive) for delete_lines."),
+});
+
+type FileEditorInput = z.infer<typeof FileEditorInputSchema>;
+
+/**
+ * Portable str_replace-style file editor: view, create, delete, str_replace, insert, delete_lines,
+ * undo_edit. When the sandbox is on, paths must stay under the workspace (or `FILE_EDITOR_ROOT`)
+ * or under one of the discovered skill directories. Rescans skill metadata at each invocation so
+ * installs in the same turn (e.g. after `bash`) are visible before the next gateway `prepareCall`.
+ */
+export function createFileEditorTool(workspaceRoot: string, skillCatalog: OpenPawSkillCatalog) {
+  return tool({
+    description: `
+A file editor for viewing and editing files.
+
+COMMANDS:
+- view         → Read a file with line numbers (pipe-separated). Always do this before editing.
+- create       → Create a new file with given content.
+- delete       → Delete a file.
+- str_replace  → Replace an exact string with new text. old_str must match exactly, including
+                 whitespace and indentation. Use "view" first to copy it precisely.
+- insert       → Insert new lines after a given line number (0 = top).
+- delete_lines → Delete a range of lines (1-based, inclusive).
+- undo_edit    → Revert the last mutating change to that file (OpenPaw extension).
+
+IMPORTANT: For str_replace, copy old_str character-for-character from the view output.
+Even a single space difference will cause the edit to fail.
+`.trim(),
+    inputSchema: FileEditorInputSchema,
+    execute: async (params: FileEditorInput): Promise<ToolSuccess | ToolFailure> => {
+      await refreshSkillCatalog(skillCatalog);
+      const skillRoots = skillCatalog.skills.map((s) => s.path);
+      const {
+        command,
+        path: filePath,
+        view_range,
+        file_text,
+        old_str,
+        new_str,
+        insert_line,
+        insert_text,
+        start_line,
+        end_line,
+      } = params;
+
+      try {
+        switch (command) {
+          case "view": {
+            const abs = resolveScopePath(workspaceRoot, skillRoots, filePath);
+            const st = await stat(abs);
+            if (st.isDirectory()) {
+              const names = await readdir(abs);
+              return {
+                success: true,
+                output: `Directory: ${filePath}\n${names.join("\n")}`,
+              };
+            }
+            const rangeTuple =
+              view_range !== undefined
+                ? ([view_range[0], view_range[1]] as [number, number])
+                : undefined;
+            const content = await readFileWithLines(abs, rangeTuple);
+            return { success: true, output: content };
+          }
+
+          case "create": {
+            if (file_text == null) {
+              return { success: false, error: "file_text is required for create." };
+            }
+            const abs = resolveScopePath(workspaceRoot, skillRoots, filePath);
+            await mkdir(dirname(abs), { recursive: true });
+            try {
+              const existing = await readFile(abs, "utf-8");
+              pushHistory(abs, existing);
+            } catch {
+              /* new file */
+            }
+            await writeFile(abs, file_text, "utf-8");
+            const lineCount = file_text.split("\n").length;
+            return {
+              success: true,
+              output: `Created ${filePath} (${lineCount} lines).`,
+            };
+          }
+
+          case "delete": {
+            const abs = resolveScopePath(workspaceRoot, skillRoots, filePath);
+            const previous = await readFile(abs, "utf-8");
+            pushHistory(abs, previous);
+            await unlink(abs);
+            return { success: true, output: `Deleted ${filePath}.` };
+          }
+
+          case "str_replace": {
+            if (old_str == null) {
+              return { success: false, error: "old_str is required for str_replace." };
+            }
+            const abs = resolveScopePath(workspaceRoot, skillRoots, filePath);
+            const content = await readFile(abs, "utf-8");
+            const occurrences = content.split(old_str).length - 1;
+            if (occurrences === 0) {
+              return {
+                success: false,
+                error:
+                  `old_str not found in ${filePath}. ` +
+                  `Tip: Use "view" to copy the exact string including whitespace/indentation.`,
+              };
+            }
+            if (occurrences > 1) {
+              return {
+                success: false,
+                error:
+                  `old_str matches ${occurrences} locations in ${filePath}. ` +
+                  `Add more surrounding context to old_str to make it unique.`,
+              };
+            }
+            pushHistory(abs, content);
+            await writeFile(abs, content.replace(old_str, new_str ?? ""), "utf-8");
+            return {
+              success: true,
+              output: `str_replace applied successfully in ${filePath}.`,
+            };
+          }
+
+          case "insert": {
+            if (insert_line == null) {
+              return { success: false, error: "insert_line is required for insert." };
+            }
+            if (insert_text == null || insert_text === "") {
+              return { success: false, error: "insert_text is required for insert." };
+            }
+            const abs = resolveScopePath(workspaceRoot, skillRoots, filePath);
+            const original = await readFile(abs, "utf-8");
+            const lines = original.split("\n");
+            pushHistory(abs, original);
+            lines.splice(insert_line, 0, ...insert_text.split("\n"));
+            await writeFile(abs, lines.join("\n"), "utf-8");
+            return {
+              success: true,
+              output: `Inserted ${insert_text.split("\n").length} line(s) after line ${insert_line} in ${filePath}.`,
+            };
+          }
+
+          case "delete_lines": {
+            if (start_line == null) {
+              return { success: false, error: "start_line is required for delete_lines." };
+            }
+            if (end_line == null) {
+              return { success: false, error: "end_line is required for delete_lines." };
+            }
+            const abs = resolveScopePath(workspaceRoot, skillRoots, filePath);
+            const original = await readFile(abs, "utf-8");
+            const lines = original.split("\n");
+            pushHistory(abs, original);
+            lines.splice(start_line - 1, end_line - start_line + 1);
+            await writeFile(abs, lines.join("\n"), "utf-8");
+            return {
+              success: true,
+              output: `Deleted lines ${start_line}–${end_line} from ${filePath}.`,
+            };
+          }
+
+          case "undo_edit": {
+            const abs = resolveScopePath(workspaceRoot, skillRoots, filePath);
+            const previous = popHistory(abs);
+            if (previous === null) {
+              return {
+                success: false,
+                error: `No edit history found for "${filePath}".`,
+              };
+            }
+            try {
+              await stat(abs);
+              await writeFile(abs, previous, "utf-8");
+            } catch {
+              await mkdir(dirname(abs), { recursive: true });
+              await writeFile(abs, previous, "utf-8");
+            }
+            return {
+              success: true,
+              output: `Reverted "${filePath}" to its previous state.`,
+            };
+          }
+
+          default: {
+            const _exhaustive: never = command;
+            return { success: false, error: `Unknown command: ${_exhaustive}` };
+          }
+        }
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { success: false, error: msg };
+      }
+    },
+  });
+}

package/agent/tools/list-dir.ts

@@ -0,0 +1,58 @@
+import { readdir } from "node:fs/promises";
+import { tool } from "ai";
+import { z } from "zod";
+import { refreshSkillCatalog, type OpenPawSkillCatalog } from "../skill-catalog";
+import { resolveScopePath, workspaceSandboxBase } from "../sandbox-paths";
+import { isSandboxRestricted } from "../turn-context";
+
+/**
+ * Resolves which directory to list: optional path, or workspace root (sandbox on) / cwd (sandbox off).
+ */
+function resolveListDirPath(
+  workspaceRoot: string,
+  skillRoots: readonly string[],
+  pathArg: string | undefined,
+): string {
+  if (pathArg === undefined || pathArg === "") {
+    if (isSandboxRestricted()) {
+      return workspaceSandboxBase(workspaceRoot);
+    }
+    return process.cwd();
+  }
+  return resolveScopePath(workspaceRoot, skillRoots, pathArg);
+}
+
+/**
+ * Lists directory entries as newline-separated names. Paths follow the same sandbox rules as
+ * `file_editor` and `bash`.
+ */
+export function createListDirTool(workspaceRoot: string, skillCatalog: OpenPawSkillCatalog) {
+  return tool({
+    description:
+      "List the contents of a directory at the given path. If no path is provided, lists the " +
+      "workspace root when the filesystem sandbox is on, or the current working directory when it is off.",
+    inputSchema: z.object({
+      path: z
+        .string()
+        .optional()
+        .describe(
+          "Directory path to list; relative to workspace when sandbox is on, or under a loaded skill directory.",
+        ),
+    }),
+    execute: async ({ path: pathArg }): Promise<{ contents: string }> => {
+      try {
+        await refreshSkillCatalog(skillCatalog);
+        const dirPath = resolveListDirPath(
+          workspaceRoot,
+          skillCatalog.skills.map((s) => s.path),
+          pathArg,
+        );
+        const names = await readdir(dirPath);
+        return { contents: names.join("\n") };
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return { contents: `Error: ${msg}` };
+      }
+    },
+  });
+}

package/agent/tools/load-skill.ts

@@ -0,0 +1,40 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tool } from "ai";
+import { z } from "zod";
+import type { OpenPawSkillCatalog } from "../skill-catalog";
+import { refreshSkillCatalog } from "../skill-catalog";
+import { stripSkillBody } from "../skills/discover";
+
+/**
+ * Tool that loads the markdown body of a discovered skill and returns its directory for bundled assets.
+ * Rescans the skill directories before each load so skills installed during the session are visible immediately.
+ */
+export function createLoadSkillTool(catalog: OpenPawSkillCatalog) {
+  return tool({
+    description:
+      "Load a skill by name to get specialized instructions (markdown, no frontmatter) and " +
+      "`skillDirectory` for paths to references, scripts, etc. Use when the user's task matches " +
+      "a skill listed in the system prompt.",
+    inputSchema: z.object({
+      name: z.string().describe("Skill name from the available skills list"),
+    }),
+    execute: async ({ name }) => {
+      await refreshSkillCatalog(catalog);
+      const key = name.trim().toLowerCase();
+      const skill = catalog.skills.find((s) => s.name.toLowerCase() === key);
+      if (!skill) {
+        return { error: `Skill "${name}" not found` };
+      }
+      try {
+        const raw = await readFile(join(skill.path, "SKILL.md"), "utf-8");
+        return {
+          skillDirectory: skill.path,
+          content: stripSkillBody(raw),
+        };
+      } catch (e) {
+        return { error: e instanceof Error ? e.message : String(e) };
+      }
+    },
+  });
+}

package/agent/tools/memory.ts

@@ -0,0 +1,84 @@
+/**
+ * Persistent curated memory tool — add / replace / remove entries in MEMORY.md or USER.md.
+ */
+
+import { tool } from "ai";
+import { z } from "zod";
+import type { MemoryStore } from "../memory-store";
+
+const DESCRIPTION =
+  "Save durable information to persistent memory (survives across sessions; compact entries).\n\n" +
+  "PARAMETERS BY ACTION (do not skip required fields):\n" +
+  "- action add: MUST set `content` (the new entry). Do NOT use replace for brand-new facts.\n" +
+  "- action replace: MUST set BOTH `old_text` AND `content`. `old_text` is a short unique substring that appears in exactly one existing entry (copy from the memory block in the prompt or from your last memory tool result). `content` is the full replacement text for that entry.\n" +
+  "- action remove: MUST set `old_text` (substring identifying the entry). `content` is ignored.\n\n" +
+  "Common mistake: using action replace with only `content` — that fails; use add for new entries, or include `old_text` when replacing.\n\n" +
+  "WHEN TO SAVE: corrections, preferences, timezone/location when relevant, stable environment facts. Not ephemeral logs.\n\n" +
+  "TARGETS: user = user profile facts; memory = your notes.\n\n" +
+  "When you tell the user you saved something, say it in ordinary words — do not name backing files or tools.";
+
+/**
+ * Registers the memory tool against a shared {@link MemoryStore} instance.
+ */
+export function createMemoryTool(store: MemoryStore) {
+  return tool({
+    description: DESCRIPTION,
+    inputSchema: z.object({
+      action: z
+        .enum(["add", "replace", "remove"])
+        .describe(
+          "add = append one entry (needs content only). replace = rewrite one entry (needs old_text + content). remove = delete one entry (needs old_text only).",
+        ),
+      target: z
+        .enum(["memory", "user"])
+        .describe("memory = agent notes; user = user profile."),
+      content: z
+        .string()
+        .optional()
+        .describe(
+          "For add: required full text of the new entry. For replace: required full text that will replace the matched entry. Omit for remove.",
+        ),
+      old_text: z
+        .string()
+        .optional()
+        .describe(
+          "For replace and remove: required. A substring unique to one existing entry (e.g. 'Birthday:' or an old date). Not needed for add.",
+        ),
+    }),
+    execute: async ({ action, target, content, old_text }) => {
+      if (action === "add") {
+        if (!content?.trim()) {
+          return JSON.stringify({ success: false, error: "content is required for add." });
+        }
+        const result = await store.add(target, content);
+        return JSON.stringify(result);
+      }
+      if (action === "replace") {
+        if (!old_text?.trim()) {
+          return JSON.stringify({
+            success: false,
+            error:
+              "replace requires `old_text` (substring of the entry to change) AND `content` (new full entry). For a new fact with no prior entry, use action `add` with only `content`.",
+          });
+        }
+        if (!content?.trim()) {
+          return JSON.stringify({
+            success: false,
+            error:
+              "replace requires `content` (the full replacement text for the entry matched by `old_text`).",
+          });
+        }
+        const result = await store.replace(target, old_text, content);
+        return JSON.stringify(result);
+      }
+      if (action === "remove") {
+        if (!old_text?.trim()) {
+          return JSON.stringify({ success: false, error: "old_text is required for remove." });
+        }
+        const result = await store.remove(target, old_text);
+        return JSON.stringify(result);
+      }
+      return JSON.stringify({ success: false, error: "Unknown action." });
+    },
+  });
+}

package/agent/turn-context.ts

@@ -0,0 +1,46 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { OpenPawSurface } from "./types";
+
+/**
+ * Per-turn flags for tool execution. Used with {@link runWithTurnContext} so concurrent
+ * gateway chats do not share mutable sandbox state on a single AgentRuntime.
+ */
+export type OpenPawTurnContext = {
+  /** When true (default), file_editor and bash are scoped to the workspace; when false, broader access. */
+  sandboxRestricted: boolean;
+  /** Chat surface for platform hints in the system prompt. */
+  surface: OpenPawSurface;
+};
+
+const turnStorage = new AsyncLocalStorage<OpenPawTurnContext>();
+
+/**
+ * Runs {@link fn} with turn context stored for the current async execution chain.
+ */
+export function runWithTurnContext<T>(
+  ctx: OpenPawTurnContext,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return turnStorage.run(ctx, fn);
+}
+
+/**
+ * Returns the current turn context, or undefined if not inside {@link runWithTurnContext}.
+ */
+export function getTurnContext(): OpenPawTurnContext | undefined {
+  return turnStorage.getStore();
+}
+
+/**
+ * Whether the filesystem/shell sandbox is restricted for this turn. Defaults to true when unset.
+ */
+export function isSandboxRestricted(): boolean {
+  return getTurnContext()?.sandboxRestricted ?? true;
+}
+
+/**
+ * Current chat surface for system prompt hints. Defaults to `cli` when not in a turn.
+ */
+export function getTurnSurface(): OpenPawSurface {
+  return getTurnContext()?.surface ?? "cli";
+}

package/agent/types.ts

@@ -0,0 +1,37 @@
+/**
+ * Opaque session identifier, e.g. `telegram:12345`, `tui:main`, or `cli:main`.
+ */
+export type SessionId = string;
+
+/** Chat surface — used for platform-specific system prompt hints. */
+export type OpenPawSurface = "cli" | "telegram";
+
+/**
+ * High-signal tool lifecycle events from the UI message stream (for channels like Telegram).
+ */
+export type ToolStreamEvent =
+  | { type: "tool_input"; toolCallId: string; toolName: string; input: unknown }
+  | { type: "tool_output"; toolCallId: string; toolName: string; output: unknown }
+  | { type: "tool_error"; toolCallId: string; toolName: string; errorText: string }
+  | { type: "tool_denied"; toolCallId: string; toolName: string };
+
+export type RunTurnParams = {
+  sessionId: SessionId;
+  userText: string;
+  /**
+   * Where the user is chatting from — affects formatting hints in the system prompt.
+   * Defaults to `telegram` when `sessionId` starts with `telegram:`, otherwise `cli`.
+   */
+  surface?: OpenPawSurface;
+  /**
+   * When true (default), file_editor paths and bash cwd are workspace-scoped.
+   * When false, file_editor may access the broader filesystem and bash uses $HOME as cwd.
+   */
+  sandboxRestricted?: boolean;
+  /** Called for streamed assistant text tokens (optional). */
+  onTextDelta?: (delta: string) => void;
+  /** Called for streamed model reasoning tokens when the provider exposes them (optional). */
+  onReasoningDelta?: (delta: string) => void;
+  /** Tool status for live UI (optional). */
+  onToolStatus?: (event: ToolStreamEvent) => void;
+};

package/agent/workspace-bootstrap.ts

@@ -0,0 +1,98 @@
+import { cpSync, existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  ensureWorkspaceDirectories,
+  getWorkspaceRoot,
+} from "../config/paths";
+
+export const DEFAULT_AGENTS_MD = `<!-- OpenPaw workspace instructions -->
+# Workspace
+
+You are operating in the user's OpenPaw workspace. Follow project conventions and prefer small, focused changes.
+
+## How you come across
+
+When you reply to the user, speak like a normal person who remembers — not like software citing files. Use "you mentioned", "you told me", "sounds like you're in…" and avoid lines like "your profile says" or naming markdown paths.
+
+## Persisting things (for you, not for the user to hear about)
+
+Use the \`memory\` tool for facts worth keeping: \`add\` with \`content\` for new items; \`replace\` needs both \`old_text\` and \`content\`. Use the file editor for longer persona or workspace wording when needed. Entries in memory are separated by §.
+`;
+
+export const DEFAULT_SOUL_MD = `<!-- Assistant persona — fill in with the user's help -->
+`;
+
+export const DEFAULT_USER_MD = `<!-- Legacy: prefer the memory tool (target user) for durable profile facts -->
+`;
+
+/** Only this skill is seeded by default; users add more via \`npx skills\` (see find-skills SKILL). */
+const BUNDLED_FIND_SKILLS_DIR = "find-skills";
+
+/**
+ * Shipped skill trees live under \`bundled-skills/\` at the package root (not under \`.agents/skills\` in the repo).
+ */
+const BUNDLED_SKILLS_ROOT = "bundled-skills";
+
+/**
+ * Path to the shipped \`find-skills\` folder (\`SKILL.md\` + any assets), from \`bundled-skills/find-skills\`.
+ */
+function bundledFindSkillsSourceDir(): string | null {
+  const moduleDir = dirname(fileURLToPath(import.meta.url));
+  const candidate = join(moduleDir, "..", BUNDLED_SKILLS_ROOT, BUNDLED_FIND_SKILLS_DIR);
+  return existsSync(candidate) ? candidate : null;
+}
+
+/**
+ * Seeds \`workspace/.agents/skills/find-skills\` when that folder is missing (onboard / reset).
+ * Other skills are installed later into the same \`skills\` directory by the user or agent.
+ */
+function seedBundledFindSkillsIfAbsent(workspaceRoot: string): void {
+  const src = bundledFindSkillsSourceDir();
+  if (!src) {
+    return;
+  }
+  const dest = join(workspaceRoot, ".agents", "skills", BUNDLED_FIND_SKILLS_DIR);
+  if (existsSync(dest)) {
+    return;
+  }
+  mkdirSync(join(workspaceRoot, ".agents", "skills"), { recursive: true });
+  cpSync(src, dest, { recursive: true });
+}
+
+/**
+ * Creates \`~/.openpaw/workspace\`, \`sessions/\`, \`memories/\`, default markdown files if absent,
+ * and seeds the default \`find-skills\` skill under \`.agents/skills/\` when absent.
+ */
+export function ensureWorkspaceLayout(): void {
+  ensureWorkspaceDirectories();
+  const root = getWorkspaceRoot();
+  const memoriesDir = join(root, "memories");
+  if (!existsSync(memoriesDir)) {
+    mkdirSync(memoriesDir, { recursive: true });
+  }
+  seedBundledFindSkillsIfAbsent(root);
+  const files: { name: string; content: string }[] = [
+    { name: "agents.md", content: DEFAULT_AGENTS_MD },
+    { name: "soul.md", content: DEFAULT_SOUL_MD },
+    { name: "user.md", content: DEFAULT_USER_MD },
+  ];
+  for (const { name, content } of files) {
+    const p = join(root, name);
+    if (!existsSync(p)) {
+      writeFileSync(p, content, "utf8");
+    }
+  }
+}
+
+/**
+ * Deletes the entire workspace directory (sessions, markdown, and any other files), then
+ * recreates it with the same defaults as a fresh onboarding run.
+ */
+export function resetWorkspaceToOnboardingDefaults(): void {
+  const root = getWorkspaceRoot();
+  if (existsSync(root)) {
+    rmSync(root, { recursive: true, force: true });
+  }
+  ensureWorkspaceLayout();
+}