@amanm/openpaw 0.1.0

package/agent/sandbox-paths.ts

@@ -0,0 +1,52 @@
+import { parse, resolve, sep } from "node:path";
+import { isSandboxRestricted } from "./turn-context";
+
+/**
+ * Workspace root used for sandboxed file paths (`FILE_EDITOR_ROOT` overrides `workspaceRoot`).
+ */
+export function workspaceSandboxBase(workspaceRoot: string): string {
+  return resolve(process.env.FILE_EDITOR_ROOT ?? workspaceRoot);
+}
+
+/**
+ * When the sandbox is off, tools use the OS filesystem root (same as previous `allowedBaseFor` behavior).
+ */
+export function filesystemSandboxBase(): string {
+  return parse(process.cwd()).root;
+}
+
+/**
+ * Resolves `userPath` for file_editor and list_dir: when the sandbox is on, the result must lie
+ * under the workspace sandbox base or under one of the absolute `skillRoots`; when off, under
+ * the filesystem root only.
+ */
+export function resolveScopePath(
+  workspaceRoot: string,
+  skillRoots: readonly string[],
+  userPath: string,
+): string {
+  if (!isSandboxRestricted()) {
+    return resolveUnderRoot(filesystemSandboxBase(), userPath);
+  }
+
+  const ws = workspaceSandboxBase(workspaceRoot);
+  const roots = [ws, ...skillRoots.map((r) => resolve(r))];
+  for (const base of roots) {
+    const full = resolve(base, userPath);
+    const prefix = base.endsWith(sep) ? base : `${base}${sep}`;
+    if (full === base || full.startsWith(prefix)) {
+      return full;
+    }
+  }
+  throw new Error(`Path outside sandbox: "${userPath}"`);
+}
+
+function resolveUnderRoot(root: string, userPath: string): string {
+  const r = resolve(root);
+  const full = resolve(r, userPath);
+  const prefix = r.endsWith(sep) ? r : `${r}${sep}`;
+  if (full !== r && !full.startsWith(prefix)) {
+    throw new Error(`Path traversal blocked: "${userPath}"`);
+  }
+  return full;
+}

package/agent/session-store.ts

@@ -0,0 +1,80 @@
+import { existsSync } from "node:fs";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import type { ToolSet, UIMessage } from "ai";
+import { safeValidateUIMessages } from "ai";
+import { getSessionsDir } from "../config/paths";
+import type { SessionId } from "./types";
+
+const SESSION_FILE_VERSION = 1;
+
+export type SessionFileV1 = {
+  version: typeof SESSION_FILE_VERSION;
+  messages: UIMessage[];
+};
+
+/**
+ * Maps a session id to a single filesystem-safe filename (no path separators).
+ */
+export function sessionIdToFilename(sessionId: SessionId): string {
+  const safe = sessionId.replace(/[^a-zA-Z0-9._-]+/g, "_");
+  return `${safe}.json`;
+}
+
+export function getSessionFilePath(sessionId: SessionId): string {
+  return join(getSessionsDir(), sessionIdToFilename(sessionId));
+}
+
+/**
+ * Loads UI messages for a session; returns empty history if missing or invalid.
+ */
+export async function loadSessionMessages(
+  sessionId: SessionId,
+  tools: ToolSet,
+): Promise<UIMessage[]> {
+  const path = getSessionFilePath(sessionId);
+  if (!existsSync(path)) {
+    return [];
+  }
+  try {
+    const raw = await Bun.file(path).text();
+    const parsed = JSON.parse(raw) as SessionFileV1 | unknown;
+    if (
+      typeof parsed !== "object" ||
+      parsed === null ||
+      !("messages" in parsed) ||
+      !Array.isArray((parsed as SessionFileV1).messages)
+    ) {
+      return [];
+    }
+    const messages = (parsed as SessionFileV1).messages as UIMessage[];
+    const validated = await safeValidateUIMessages({
+      messages,
+      tools: tools as never,
+    });
+    if (!validated.success) {
+      return [];
+    }
+    return validated.data;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Persists the full UI message list for a session.
+ */
+export async function saveSessionMessages(
+  sessionId: SessionId,
+  messages: UIMessage[],
+): Promise<void> {
+  const dir = getSessionsDir();
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  const payload: SessionFileV1 = {
+    version: SESSION_FILE_VERSION,
+    messages,
+  };
+  await Bun.write(getSessionFilePath(sessionId), JSON.stringify(payload, null, 2));
+}

package/agent/skill-catalog.ts

@@ -0,0 +1,25 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { discoverSkillDirectories, type SkillMetadata } from "./skills/discover";
+
+/**
+ * Mutable list of discovered skills for the agent runtime; rescan the filesystem to pick up installs.
+ */
+export type OpenPawSkillCatalog = {
+  workspacePath: string;
+  skills: SkillMetadata[];
+};
+
+/**
+ * Directories scanned for `SKILL.md` under immediate subfolders (OpenPaw workspace + optional user dir).
+ */
+export function skillScanDirsForWorkspace(workspacePath: string): string[] {
+  return [join(workspacePath, ".agents/skills"), join(homedir(), ".config/agent/skills")];
+}
+
+/**
+ * Re-reads skill metadata from disk into {@link OpenPawSkillCatalog.skills}.
+ */
+export async function refreshSkillCatalog(catalog: OpenPawSkillCatalog): Promise<void> {
+  catalog.skills = await discoverSkillDirectories(skillScanDirsForWorkspace(catalog.workspacePath));
+}

package/agent/skills/discover.ts

@@ -0,0 +1,100 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
+
+/** Metadata for one discovered skill (Agent Skills-style); `path` is the absolute skill folder. */
+export type SkillMetadata = {
+  name: string;
+  description: string;
+  path: string;
+};
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
+
+/**
+ * Returns the raw YAML string inside the first frontmatter block, or null if none.
+ */
+export function extractFrontmatterYaml(content: string): string | null {
+  const m = content.match(FRONTMATTER_RE);
+  return m?.[1]?.trim() ? m[1] : null;
+}
+
+/**
+ * Strips the leading `---` / `---` frontmatter block from SKILL.md content for tool output.
+ */
+export function stripSkillBody(content: string): string {
+  const m = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
+  return (m ? content.slice(m[0].length) : content).trim();
+}
+
+/**
+ * Scans each base directory for immediate subfolders containing `SKILL.md`, parses YAML
+ * frontmatter for `name` and `description`, and returns skills in stable order.
+ * First occurrence of a given `name` wins; invalid or missing entries are skipped.
+ */
+export async function discoverSkillDirectories(dirs: string[]): Promise<SkillMetadata[]> {
+  const skills: SkillMetadata[] = [];
+  const seenNames = new Set<string>();
+
+  for (const dir of dirs) {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+
+      const skillDir = resolve(dir, entry.name);
+      const skillFile = join(skillDir, "SKILL.md");
+
+      let content: string;
+      try {
+        content = await readFile(skillFile, "utf-8");
+      } catch {
+        continue;
+      }
+
+      const fm = extractFrontmatterYaml(content);
+      if (fm == null) {
+        continue;
+      }
+
+      let meta: unknown;
+      try {
+        meta = parseYaml(fm);
+      } catch {
+        continue;
+      }
+
+      if (typeof meta !== "object" || meta === null) {
+        continue;
+      }
+
+      const rec = meta as { name?: unknown; description?: unknown };
+      if (typeof rec.name !== "string" || typeof rec.description !== "string") {
+        continue;
+      }
+
+      const name = rec.name.trim();
+      const description = rec.description.trim();
+      if (!name || !description) {
+        continue;
+      }
+
+      const dedupeKey = name.toLowerCase();
+      if (seenNames.has(dedupeKey)) {
+        continue;
+      }
+      seenNames.add(dedupeKey);
+
+      skills.push({ name, description, path: skillDir });
+    }
+  }
+
+  return skills;
+}

package/agent/tool-stream-format.ts

@@ -0,0 +1,126 @@
+/**
+ * Short one-line formatting for tool I/O in Telegram, TUI, and stream callbacks.
+ */
+
+import type { ToolStreamEvent } from "./types";
+import { toolInputToYamlLike, toolOutputToYamlLike } from "./tool-yaml-like";
+
+const DEFAULT_MAX_JSON_LEN = 200;
+
+/**
+ * Serializes a value for one-line display, capped in length.
+ */
+export function truncateJson(value: unknown, maxLen: number = DEFAULT_MAX_JSON_LEN): string {
+  try {
+    const s = typeof value === "string" ? value : JSON.stringify(value);
+    if (s.length <= maxLen) {
+      return s;
+    }
+    return `${s.slice(0, maxLen)}…`;
+  } catch {
+    return String(value);
+  }
+}
+
+/**
+ * One line for tool invocation (Telegram / TUI).
+ */
+export function formatToolInputLine(toolName: string, input: unknown): string {
+  return `${toolName}: ${truncateJson(input)}`;
+}
+
+/**
+ * One line for tool result (Telegram / TUI).
+ */
+export function formatToolOutputLine(output: unknown): string {
+  return `→ ${truncateJson(output)}`;
+}
+
+/**
+ * One line for tool failure.
+ */
+export function formatToolErrorLine(toolName: string, errorText: string): string {
+  return `⚠ ${toolName}: ${errorText}`;
+}
+
+/**
+ * One line when tool execution was denied.
+ */
+export function formatToolDeniedLine(toolName: string): string {
+  return `⛔ ${toolName} (denied)`;
+}
+
+/**
+ * Formats a streamed tool event for Telegram or TUI (one line).
+ */
+export function formatToolStreamEvent(ev: ToolStreamEvent): string {
+  switch (ev.type) {
+    case "tool_input":
+      return formatToolInputLine(ev.toolName, ev.input);
+    case "tool_output":
+      return formatToolOutputLine(ev.output);
+    case "tool_error":
+      return formatToolErrorLine(ev.toolName, ev.errorText);
+    case "tool_denied":
+      return formatToolDeniedLine(ev.toolName);
+    default:
+      return "";
+  }
+}
+
+const TUI_YAML_BLOCK_MAX = 3500;
+
+function truncateTuiYamlBlock(s: string, max: number): string {
+  if (s.length <= max) {
+    return s;
+  }
+  return `${s.slice(0, max - 1)}…`;
+}
+
+/**
+ * Markdown block for a tool invocation in the terminal chat (fenced YAML, same as live stream).
+ */
+export function formatTuiToolInputMarkdown(toolName: string, input: unknown): string {
+  const yaml = truncateTuiYamlBlock(toolInputToYamlLike(toolName, input), TUI_YAML_BLOCK_MAX);
+  return `**Tool · ${toolName}**\n\n\`\`\`yaml\n${yaml}\n\`\`\``;
+}
+
+/**
+ * Markdown block for a tool result in the terminal chat.
+ */
+export function formatTuiToolOutputMarkdown(output: unknown): string {
+  const yaml = truncateTuiYamlBlock(toolOutputToYamlLike(output), TUI_YAML_BLOCK_MAX);
+  return `→ **Result**\n\n\`\`\`yaml\n${yaml}\n\`\`\``;
+}
+
+/**
+ * Markdown block for a tool error in the terminal chat.
+ */
+export function formatTuiToolErrorMarkdown(toolName: string, errorText: string): string {
+  return `⚠ **${toolName}**\n\n${errorText}`;
+}
+
+/**
+ * Markdown line for a denied tool in the terminal chat.
+ */
+export function formatTuiToolDeniedMarkdown(toolName: string): string {
+  return `⛔ **${toolName}** (denied)`;
+}
+
+/**
+ * Markdown tool status for the terminal chat: headings plus fenced YAML (same shape as Telegram).
+ */
+export function formatToolStreamEventForTui(ev: ToolStreamEvent): string {
+  switch (ev.type) {
+    case "tool_input":
+      return formatTuiToolInputMarkdown(ev.toolName, ev.input);
+    case "tool_output":
+      return formatTuiToolOutputMarkdown(ev.output);
+    case "tool_error":
+      return formatTuiToolErrorMarkdown(ev.toolName, ev.errorText);
+    case "tool_denied":
+      return formatTuiToolDeniedMarkdown(ev.toolName);
+    default:
+      return "";
+  }
+}

package/agent/tool-yaml-like.ts

@@ -0,0 +1,96 @@
+/**
+ * YAML-like plain-text rendering for tool inputs and outputs.
+ * Shared by Telegram HTML and the terminal UI.
+ */
+
+const DEFAULT_MAX_JSON_LEN = 800;
+
+/**
+ * Serializes a value for one-line display, capped in length.
+ */
+function truncateJson(value: unknown, maxLen: number = DEFAULT_MAX_JSON_LEN): string {
+  try {
+    const s = typeof value === "string" ? value : JSON.stringify(value);
+    if (s.length <= maxLen) {
+      return s;
+    }
+    return `${s.slice(0, maxLen)}…`;
+  } catch {
+    return String(value);
+  }
+}
+
+/**
+ * Formats a scalar value for YAML-style lines (quote when ambiguous).
+ */
+function formatYamlScalar(v: unknown): string {
+  if (typeof v === "string") {
+    if (/[\n\r:#]/.test(v) || v.length > 160 || v.includes('"')) {
+      return JSON.stringify(v);
+    }
+    return v;
+  }
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return String(v);
+  }
+}
+
+/**
+ * Flattens a plain object into indented YAML-style key lines.
+ */
+function linesForObject(obj: Record<string, unknown>, indent: number): string[] {
+  const pad = "  ".repeat(indent);
+  const out: string[] = [];
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+      out.push(`${pad}${k}:`);
+      out.push(...linesForObject(v as Record<string, unknown>, indent + 1));
+    } else {
+      out.push(`${pad}${k}: ${formatYamlScalar(v)}`);
+    }
+  }
+  return out;
+}
+
+/**
+ * Renders tool input as a compact YAML-style string (tool name as top-level key).
+ */
+export function toolInputToYamlLike(toolName: string, input: unknown): string {
+  if (input !== null && typeof input === "object" && !Array.isArray(input)) {
+    const lines = [`${toolName}:`];
+    lines.push(...linesForObject(input as Record<string, unknown>, 1));
+    return lines.join("\n");
+  }
+  return `${toolName}: ${truncateJson(input)}`;
+}
+
+/**
+ * YAML-style rendering for tool results (e.g. bash exitCode/stdout/stderr or generic objects).
+ */
+export function toolOutputToYamlLike(output: unknown): string {
+  if (output !== null && typeof output === "object" && !Array.isArray(output)) {
+    const o = output as Record<string, unknown>;
+    if ("exitCode" in o && ("stdout" in o || "stderr" in o)) {
+      const lines: string[] = [`exitCode: ${formatYamlScalar(o.exitCode)}`];
+      const stdout = typeof o.stdout === "string" ? o.stdout : String(o.stdout ?? "");
+      const stderr = typeof o.stderr === "string" ? o.stderr : String(o.stderr ?? "");
+      if (stdout.includes("\n")) {
+        lines.push("stdout: |");
+        for (const line of stdout.split("\n")) {
+          lines.push(`  ${line}`);
+        }
+      } else {
+        lines.push(`stdout: ${formatYamlScalar(stdout)}`);
+      }
+      lines.push(`stderr: ${formatYamlScalar(stderr)}`);
+      return lines.join("\n");
+    }
+    return linesForObject(o, 0).join("\n");
+  }
+  if (typeof output === "string") {
+    return output;
+  }
+  return truncateJson(output, 2000);
+}

package/agent/tools/bash.ts

@@ -0,0 +1,100 @@
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { tool } from "ai";
+import { z } from "zod";
+import { isSandboxRestricted } from "../turn-context";
+
+const DEFAULT_TIMEOUT_MS = 60_000;
+const MAX_OUTPUT_BYTES = 256_000;
+
+function runBunSpawn(
+  command: string,
+  cwd: string,
+  timeoutMs: number,
+): Promise<{ stdout: string; stderr: string; exitCode: number | null }> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn("/bin/sh", ["-c", command], {
+      cwd,
+      env: { ...process.env, PATH: process.env.PATH },
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let killed = false;
+
+    const timer = setTimeout(() => {
+      killed = true;
+      proc.kill("SIGTERM");
+    }, timeoutMs);
+
+    const cap = (chunk: Buffer, acc: { s: string; n: number }) => {
+      const str = chunk.toString("utf8");
+      if (acc.n >= MAX_OUTPUT_BYTES) {
+        return;
+      }
+      const take = Math.min(str.length, MAX_OUTPUT_BYTES - acc.n);
+      acc.s += str.slice(0, take);
+      acc.n += take;
+    };
+
+    const outAcc = { s: "", n: 0 };
+    const errAcc = { s: "", n: 0 };
+
+    proc.stdout?.on("data", (d: Buffer) => cap(d, outAcc));
+    proc.stderr?.on("data", (d: Buffer) => cap(d, errAcc));
+
+    proc.on("error", (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+
+    proc.on("close", (code) => {
+      clearTimeout(timer);
+      if (killed) {
+        resolve({
+          stdout: outAcc.s,
+          stderr: errAcc.s + "\n[openpaw] Command timed out.",
+          exitCode: 124,
+        });
+        return;
+      }
+      resolve({ stdout: outAcc.s, stderr: errAcc.s, exitCode: code });
+    });
+  });
+}
+
+/**
+ * Runs a shell command; cwd is the workspace when sandbox is on, or the user home when off.
+ */
+export function createBashTool(workspaceRoot: string) {
+  return tool({
+    description:
+      "Run a shell command via sh -c. With sandbox on, cwd is the OpenPaw workspace root; with sandbox off, cwd is the user home directory. Avoid destructive commands unless the user asked.",
+    inputSchema: z.object({
+      command: z.string().describe("Shell command to run (sh -c)"),
+      timeoutMs: z
+        .number()
+        .optional()
+        .describe(`Optional timeout in ms (default ${DEFAULT_TIMEOUT_MS})`),
+    }),
+    execute: async ({ command, timeoutMs }) => {
+      const ms = timeoutMs ?? DEFAULT_TIMEOUT_MS;
+      const cwd = isSandboxRestricted() ? workspaceRoot : homedir();
+      try {
+        const { stdout, stderr, exitCode } = await runBunSpawn(command, cwd, ms);
+        return {
+          exitCode,
+          stdout,
+          stderr,
+        };
+      } catch (e) {
+        return {
+          exitCode: -1,
+          stdout: "",
+          stderr: e instanceof Error ? e.message : String(e),
+        };
+      }
+    },
+  });
+}