@amanm/openpaw 0.1.0

package/AGENTS.md

@@ -0,0 +1 @@
+Try to keep one file limited to one core feature, and include docstrings in all files and functions to explain what they do.

package/README.md

@@ -0,0 +1,144 @@
+# OpenPaw
+
+OpenPaw is a Bun + TypeScript local agent runtime with:
+
+- a terminal chat UI (`openpaw tui`) built with OpenTUI
+- a gateway process (`openpaw gateway dev` in foreground, `openpaw gateway start` in background) for messaging channels (Telegram today)
+- persisted sessions and workspace instructions under `~/.openpaw`
+
+## Prerequisites
+
+- Node.js `>=18.18` (for npm-installed launcher)
+- Bun `>=1.3` runtime (tested with `1.3.11`)
+- A model provider compatible with OpenAI-style chat APIs
+- Optional: Telegram bot token if you want Telegram channel support
+
+## Install
+
+Global install (recommended for end users):
+
+```bash
+npm i -g openpaw
+```
+
+The first `openpaw` run checks for Bun. If Bun is missing on macOS/Linux, OpenPaw prompts to install it automatically.
+
+Windows note: Bun auto-install is not performed yet. Install Bun manually from `https://bun.sh/docs/installation`.
+
+From-source install (development):
+
+```bash
+bun install
+```
+
+## CLI Usage
+
+```bash
+openpaw --help
+```
+
+Main commands:
+
+- `openpaw onboard`  
+  Interactive onboarding (provider URL, API key, model, optional Telegram token, personality)
+- `openpaw tui`  
+  Start local terminal chat UI
+- `openpaw gateway dev`  
+  Start configured messaging adapters in foreground mode (blocking)
+- `openpaw gateway start`  
+  Start gateway daemon in background mode
+- `openpaw gateway status`  
+  Show background gateway status and log paths
+- `openpaw gateway stop`  
+  Stop background gateway daemon
+- `openpaw gateway logs [-n 80] [--stderr]`  
+  Show recent daemon logs
+
+## First-Time Setup
+
+Run onboarding once:
+
+```bash
+openpaw onboard
+```
+
+This creates:
+
+- config file: `~/.openpaw/config.yaml`
+- workspace: `~/.openpaw/workspace`
+- defaults:
+  - `~/.openpaw/workspace/agents.md`
+  - `~/.openpaw/workspace/soul.md`
+  - `~/.openpaw/workspace/user.md` (legacy; prefer the `memory` tool for profile facts)
+  - `~/.openpaw/workspace/memories/` (curated `MEMORY.md` / `USER.md` via the `memory` tool)
+  - `~/.openpaw/workspace/sessions/*`
+
+## Configuration
+
+`~/.openpaw/config.yaml` contains:
+
+- `provider.baseUrl`
+- `provider.apiKey`
+- `provider.model`
+- optional `channels.telegram.botToken`
+- `personality` (`Assistant`, `Meowl`, `Coder`)
+
+Example:
+
+```yaml
+provider:
+  baseUrl: "https://api.openai.com/v1"
+  apiKey: "sk-..."
+  model: "gpt-4o"
+channels:
+  telegram:
+    botToken: "123456789:ABC..."
+personality: "Assistant"
+```
+
+## Sessions and Commands
+
+Sessions are persisted as JSON files under:
+
+- `~/.openpaw/workspace/sessions`
+
+TUI slash commands:
+
+- `/new` start a new thread
+- `/sessions` list saved sessions
+- `/resume N` resume by number
+
+Telegram bot commands:
+
+- `/new`
+- `/sessions`
+- `/resume N`
+
+## Architecture
+
+Top-level modules:
+
+- `agent/`  
+  Agent runtime, model wiring (`@ai-sdk/openai-compatible`), structured prompt building (identity, channel hints, optional project context from cwd), tools (`bash`, `file_editor`, `list_dir`, `memory`), session persistence
+- `gateway/`  
+  Shared runtime bootstrap + channel adapters (Telegram + channel orchestration)
+- `cli/`  
+  Commander CLI entrypoint and OpenTUI screens
+- `config/`  
+  Config schema, paths, and disk storage
+
+Execution flow:
+
+1. CLI command starts (`cli/openpaw.tsx`)
+2. Gateway context loads config and ensures workspace layout
+3. Agent runtime is created with tools scoped to workspace root
+4. Channel (TUI or Telegram) forwards user text to `runtime.runTurn(...)`
+5. Assistant output streams back and session history is saved
+
+## Notes
+
+- Background gateway state files:
+  - PID: `~/.openpaw/gateway/gateway.pid`
+  - stdout log: `~/.openpaw/gateway/gateway.log`
+  - stderr log: `~/.openpaw/gateway/gateway.err.log`
+- For development from source, you can still run: `bun run openpaw ...`

package/agent/agent.ts

@@ -0,0 +1,217 @@
+import {
+  createAgentUIStream,
+  generateId,
+  ToolLoopAgent,
+  validateUIMessages,
+} from "ai";
+import type { OpenPawConfig } from "../config/types";
+import { buildSystemPrompt } from "./prompt-builder";
+import { MemoryStore } from "./memory-store";
+import { createLanguageModel } from "./model";
+import {
+  refreshSkillCatalog,
+  type OpenPawSkillCatalog,
+} from "./skill-catalog";
+import { loadSessionMessages, saveSessionMessages } from "./session-store";
+import { createBashTool } from "./tools/bash";
+import { createFileEditorTool } from "./tools/file-editor";
+import { createListDirTool } from "./tools/list-dir";
+import { createLoadSkillTool } from "./tools/load-skill";
+import { createMemoryTool } from "./tools/memory";
+import type { OpenPawSurface, RunTurnParams } from "./types";
+import { getTurnSurface, isSandboxRestricted, runWithTurnContext } from "./turn-context";
+
+const STATIC_AGENT_INSTRUCTIONS = [
+  "You are OpenPaw, a capable local assistant.",
+  "Follow the system prompt: identity, voice with the user, workspace content, tools, and channel hints.",
+  "Use tools faithfully: file_editor (view before str_replace; exact single match for old_str), bash, list_dir, load_skill, memory.",
+  "Memory tool: add uses content only; replace needs old_text + content; remove needs old_text only.",
+  "load_skill: use when a listed skill fits the task; follow loaded instructions and use skillDirectory for bundled file paths.",
+  "To the user: sound human; recall context naturally. Do not mention workspace filenames, profile files, or tool names unless they are developers debugging.",
+].join(" ");
+
+/** Instantiates all tools, including `load_skill` and filesystem tools that rescan {@link OpenPawSkillCatalog}. */
+function createTools(workspacePath: string, memoryStore: MemoryStore, skillCatalog: OpenPawSkillCatalog) {
+  return {
+    bash: createBashTool(workspacePath),
+    file_editor: createFileEditorTool(workspacePath, skillCatalog),
+    list_dir: createListDirTool(workspacePath, skillCatalog),
+    load_skill: createLoadSkillTool(skillCatalog),
+    memory: createMemoryTool(memoryStore),
+  };
+}
+
+export type OpenPawTools = ReturnType<typeof createTools>;
+
+/**
+ * Derives chat surface from session id when callers do not pass `surface` explicitly.
+ */
+export function surfaceFromSessionId(sessionId: string): OpenPawSurface {
+  return sessionId.startsWith("telegram:") ? "telegram" : "cli";
+}
+
+/**
+ * Creates a {@link ToolLoopAgent} with workspace-scoped tools, curated memory, and a dynamic system prompt.
+ *
+ * @param skillCatalog Mutable skill list for this process; rescanned from disk before each model call and in `load_skill`.
+ */
+export function createOpenPawAgent(
+  config: OpenPawConfig,
+  workspacePath: string,
+  memoryStore: MemoryStore,
+  skillCatalog: OpenPawSkillCatalog,
+) {
+  const tools = createTools(workspacePath, memoryStore, skillCatalog);
+  return new ToolLoopAgent({
+    model: createLanguageModel(config),
+    instructions: STATIC_AGENT_INSTRUCTIONS,
+    tools,
+    prepareCall: async (options) => {
+      await refreshSkillCatalog(skillCatalog);
+      let instructions = await buildSystemPrompt({
+        workspacePath,
+        personality: config.personality,
+        surface: getTurnSurface(),
+        memoryUserBlock: memoryStore.formatForSystemPrompt("user"),
+        memoryAgentBlock: memoryStore.formatForSystemPrompt("memory"),
+        skills: skillCatalog.skills,
+      });
+      if (!isSandboxRestricted()) {
+        instructions +=
+          "\n\n## Sandbox (this turn)\nFilesystem sandbox is OFF: file_editor and list_dir may use absolute paths or paths anywhere under the filesystem root; bash runs with cwd set to the user home directory, not the workspace root.";
+      }
+      return { ...options, instructions };
+    },
+  });
+}
+
+export type OpenPawAgent = ReturnType<typeof createOpenPawAgent>;
+
+export type AgentRuntime = {
+  config: OpenPawConfig;
+  workspacePath: string;
+  /** Curated memory store (frozen snapshot + tool mutations). */
+  memoryStore: MemoryStore;
+  agent: OpenPawAgent;
+  runTurn: (params: RunTurnParams) => Promise<{ text: string }>;
+};
+
+/**
+ * Loads memory, discovers skills under the workspace and user config dirs, and builds the shared runtime.
+ */
+export async function createAgentRuntime(
+  config: OpenPawConfig,
+  workspacePath: string,
+): Promise<AgentRuntime> {
+  const memoryStore = new MemoryStore(workspacePath);
+  memoryStore.loadFromDisk();
+  const skillCatalog: OpenPawSkillCatalog = { workspacePath, skills: [] };
+  await refreshSkillCatalog(skillCatalog);
+  const agent = createOpenPawAgent(config, workspacePath, memoryStore, skillCatalog);
+
+  return {
+    config,
+    workspacePath,
+    memoryStore,
+    agent,
+    runTurn: async (params) => runTurnWithAgent(agent, params),
+  };
+}
+
+async function runTurnWithAgent(
+  agent: OpenPawAgent,
+  params: RunTurnParams,
+): Promise<{ text: string }> {
+  const {
+    sessionId,
+    userText,
+    sandboxRestricted = true,
+    surface = surfaceFromSessionId(sessionId),
+    onTextDelta,
+    onReasoningDelta,
+    onToolStatus,
+  } = params;
+
+  return runWithTurnContext({ sandboxRestricted, surface }, async () => {
+    const prior = await loadSessionMessages(sessionId, agent.tools);
+    const userMessage = {
+      id: generateId(),
+      role: "user" as const,
+      parts: [{ type: "text" as const, text: userText }],
+    };
+    const draft = [...prior, userMessage];
+
+    const uiMessages = await validateUIMessages({
+      messages: draft,
+      tools: agent.tools as never,
+    });
+
+    let accumulated = "";
+    const toolNameByCallId = new Map<string, string>();
+
+    const stream = await createAgentUIStream({
+      agent,
+      uiMessages,
+      onFinish: async ({ messages }) => {
+        await saveSessionMessages(sessionId, messages);
+      },
+    });
+
+    for await (const chunk of stream) {
+      if (chunk.type === "text-delta" && "delta" in chunk) {
+        const d = chunk.delta;
+        accumulated += d;
+        onTextDelta?.(d);
+      } else if (chunk.type === "error") {
+        const errLine = `Error: ${chunk.errorText}`;
+        accumulated += errLine;
+        onTextDelta?.(errLine);
+      } else if (chunk.type === "reasoning-delta" && "delta" in chunk) {
+        onReasoningDelta?.(chunk.delta);
+      } else if (chunk.type === "tool-input-start") {
+        toolNameByCallId.set(chunk.toolCallId, chunk.toolName);
+      } else if (chunk.type === "tool-input-available") {
+        toolNameByCallId.set(chunk.toolCallId, chunk.toolName);
+        onToolStatus?.({
+          type: "tool_input",
+          toolCallId: chunk.toolCallId,
+          toolName: chunk.toolName,
+          input: chunk.input,
+        });
+      } else if (chunk.type === "tool-input-error") {
+        toolNameByCallId.set(chunk.toolCallId, chunk.toolName);
+        onToolStatus?.({
+          type: "tool_error",
+          toolCallId: chunk.toolCallId,
+          toolName: chunk.toolName,
+          errorText: chunk.errorText,
+        });
+      } else if (chunk.type === "tool-output-available") {
+        const toolName = toolNameByCallId.get(chunk.toolCallId) ?? "tool";
+        onToolStatus?.({
+          type: "tool_output",
+          toolCallId: chunk.toolCallId,
+          toolName,
+          output: chunk.output,
+        });
+      } else if (chunk.type === "tool-output-error") {
+        const toolName = toolNameByCallId.get(chunk.toolCallId) ?? "tool";
+        onToolStatus?.({
+          type: "tool_error",
+          toolCallId: chunk.toolCallId,
+          toolName,
+          errorText: chunk.errorText,
+        });
+      } else if (chunk.type === "tool-output-denied") {
+        const toolName = toolNameByCallId.get(chunk.toolCallId) ?? "tool";
+        onToolStatus?.({
+          type: "tool_denied",
+          toolCallId: chunk.toolCallId,
+          toolName,
+        });
+      }
+    }
+
+    return { text: accumulated };
+  });
+}

package/agent/context-scan.ts

@@ -0,0 +1,81 @@
+/**
+ * Lightweight scanning and truncation for text injected into the system prompt (Hermes-style).
+ */
+
+/** Regex patterns with stable ids for logging / blocked messages. */
+const CONTEXT_THREAT_PATTERNS: [RegExp, string][] = [
+  [/ignore\s+(previous|all|above|prior)\s+instructions/i, "prompt_injection"],
+  [/do\s+not\s+tell\s+the\s+user/i, "deception_hide"],
+  [/system\s+prompt\s+override/i, "sys_prompt_override"],
+  [/disregard\s+(your|all|any)\s+(instructions|rules|guidelines)/i, "disregard_rules"],
+  [
+    /act\s+as\s+(if|though)\s+you\s+(have\s+no|don't\s+have)\s+(restrictions|limits|rules)/i,
+    "bypass_restrictions",
+  ],
+  [/<!--[^>]*(?:ignore|override|system|secret|hidden)[^>]*-->/i, "html_comment_injection"],
+  [/<\s*div\s+style\s*=\s*["'].*display\s*:\s*none/i, "hidden_div"],
+  [/translate\s+.*\s+into\s+.*\s+and\s+(execute|run|eval)/i, "translate_execute"],
+  [/curl\s+[^\n]*\$\{?\w*(KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|API)/i, "exfil_curl"],
+  [/cat\s+[^\n]*(\.env|credentials|\.netrc|\.pgpass)/i, "read_secrets"],
+];
+
+const CONTEXT_INVISIBLE_CHARS = new Set([
+  "\u200b",
+  "\u200c",
+  "\u200d",
+  "\u2060",
+  "\ufeff",
+  "\u202a",
+  "\u202b",
+  "\u202c",
+  "\u202d",
+  "\u202e",
+]);
+
+export const CONTEXT_FILE_MAX_CHARS = 20_000;
+const CONTEXT_TRUNCATE_HEAD_RATIO = 0.7;
+const CONTEXT_TRUNCATE_TAIL_RATIO = 0.2;
+
+/**
+ * Scans context file content for suspicious patterns. Returns sanitized replacement if blocked.
+ */
+export function scanContextContent(content: string, filename: string): string {
+  const findings: string[] = [];
+
+  for (const char of CONTEXT_INVISIBLE_CHARS) {
+    if (content.includes(char)) {
+      findings.push(`invisible unicode U+${char.charCodeAt(0).toString(16).toUpperCase().padStart(4, "0")}`);
+    }
+  }
+
+  for (const [re, pid] of CONTEXT_THREAT_PATTERNS) {
+    if (re.test(content)) {
+      findings.push(pid);
+    }
+  }
+
+  if (findings.length > 0) {
+    return `[BLOCKED: ${filename} contained potential prompt injection (${findings.join(", ")}). Content not loaded.]`;
+  }
+
+  return content;
+}
+
+/**
+ * Head/tail truncation with a middle marker when content exceeds maxChars.
+ */
+export function truncateContextContent(
+  content: string,
+  filename: string,
+  maxChars: number = CONTEXT_FILE_MAX_CHARS,
+): string {
+  if (content.length <= maxChars) {
+    return content;
+  }
+  const headChars = Math.floor(maxChars * CONTEXT_TRUNCATE_HEAD_RATIO);
+  const tailChars = Math.floor(maxChars * CONTEXT_TRUNCATE_TAIL_RATIO);
+  const head = content.slice(0, headChars);
+  const tail = content.slice(-tailChars);
+  const marker = `\n\n[...truncated ${filename}: kept ${headChars}+${tailChars} of ${content.length} chars. Use file tools to read the full file.]\n\n`;
+  return head + marker + tail;
+}

package/agent/file-editor-store.ts

@@ -0,0 +1,27 @@
+/**
+ * In-memory undo stacks for the file editor tool: each absolute file path maps to
+ * a stack of prior UTF-8 contents, pushed before mutating operations.
+ */
+
+const editHistory = new Map<string, string[]>();
+
+/**
+ * Records the previous file contents so the next {@link popHistory} can restore it.
+ */
+export function pushHistory(filePath: string, previousContent: string): void {
+  if (!editHistory.has(filePath)) {
+    editHistory.set(filePath, []);
+  }
+  editHistory.get(filePath)!.push(previousContent);
+}
+
+/**
+ * Removes and returns the most recent snapshot for {@link filePath}, or null if none.
+ */
+export function popHistory(filePath: string): string | null {
+  const stack = editHistory.get(filePath);
+  if (!stack || stack.length === 0) {
+    return null;
+  }
+  return stack.pop()!;
+}

package/agent/index.ts

@@ -0,0 +1,31 @@
+export type { SessionId, RunTurnParams, OpenPawSurface } from "./types";
+export type { BuildSystemPromptOptions } from "./prompt-builder";
+export { MemoryStore } from "./memory-store";
+export { buildSystemPrompt } from "./prompt-builder";
+export { createLanguageModel } from "./model";
+export {
+  loadSessionMessages,
+  saveSessionMessages,
+  getSessionFilePath,
+  sessionIdToFilename,
+} from "./session-store";
+export type { SessionFileV1 } from "./session-store";
+export {
+  createOpenPawAgent,
+  createAgentRuntime,
+  surfaceFromSessionId,
+  type OpenPawAgent,
+  type AgentRuntime,
+  type OpenPawTools,
+} from "./agent";
+export type { OpenPawSkillCatalog } from "./skill-catalog";
+export { refreshSkillCatalog, skillScanDirsForWorkspace } from "./skill-catalog";
+export {
+  ensureWorkspaceLayout,
+  resetWorkspaceToOnboardingDefaults,
+} from "./workspace-bootstrap";
+export {
+  DEFAULT_AGENTS_MD,
+  DEFAULT_SOUL_MD,
+  DEFAULT_USER_MD,
+} from "./workspace-bootstrap";