@poncho-ai/harness 0.25.0 → 0.26.0

package/src/todo-tools.ts

@@ -0,0 +1,363 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { defineTool, type ToolDefinition } from "@poncho-ai/sdk";
+import type { StateConfig } from "./state.js";
+import {
+  ensureAgentIdentity,
+  getAgentStoreDirectory,
+  slugifyStorageComponent,
+  STORAGE_SCHEMA_VERSION,
+} from "./agent-identity.js";
+import { createRawKVStore, type RawKVStore } from "./kv-store.js";
+
+// ---------------------------------------------------------------------------
+// Data model
+// ---------------------------------------------------------------------------
+
+export type TodoStatus = "pending" | "in_progress" | "completed";
+export type TodoPriority = "high" | "medium" | "low";
+
+export interface TodoItem {
+  id: string;
+  content: string;
+  status: TodoStatus;
+  priority: TodoPriority;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface TodoStore {
+  get(conversationId: string): Promise<TodoItem[]>;
+  set(conversationId: string, todos: TodoItem[]): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const VALID_STATUSES: TodoStatus[] = ["pending", "in_progress", "completed"];
+const VALID_PRIORITIES: TodoPriority[] = ["high", "medium", "low"];
+const TODOS_DIRECTORY = "todos";
+
+const writeJsonAtomic = async (filePath: string, payload: unknown): Promise<void> => {
+  await mkdir(dirname(filePath), { recursive: true });
+  const tmpPath = `${filePath}.tmp`;
+  await writeFile(tmpPath, JSON.stringify(payload, null, 2), "utf8");
+  await rename(tmpPath, filePath);
+};
+
+const parseTodoList = (raw: unknown): TodoItem[] => {
+  if (!Array.isArray(raw)) return [];
+  return raw.filter(
+    (item): item is TodoItem =>
+      typeof item === "object" &&
+      item !== null &&
+      typeof (item as Record<string, unknown>).id === "string" &&
+      typeof (item as Record<string, unknown>).content === "string",
+  );
+};
+
+const generateId = (): string =>
+  (globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random()}`).slice(0, 8);
+
+// ---------------------------------------------------------------------------
+// InMemoryTodoStore
+// ---------------------------------------------------------------------------
+
+class InMemoryTodoStore implements TodoStore {
+  private readonly store = new Map<string, TodoItem[]>();
+
+  async get(conversationId: string): Promise<TodoItem[]> {
+    return this.store.get(conversationId) ?? [];
+  }
+
+  async set(conversationId: string, todos: TodoItem[]): Promise<void> {
+    this.store.set(conversationId, todos);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// FileTodoStore — one JSON file per conversation
+// ---------------------------------------------------------------------------
+
+class FileTodoStore implements TodoStore {
+  private readonly workingDir: string;
+  private todosDir = "";
+
+  constructor(workingDir: string) {
+    this.workingDir = workingDir;
+  }
+
+  private async ensureTodosDir(): Promise<string> {
+    if (this.todosDir) return this.todosDir;
+    const identity = await ensureAgentIdentity(this.workingDir);
+    this.todosDir = resolve(getAgentStoreDirectory(identity), TODOS_DIRECTORY);
+    await mkdir(this.todosDir, { recursive: true });
+    return this.todosDir;
+  }
+
+  private async filePath(conversationId: string): Promise<string> {
+    const dir = await this.ensureTodosDir();
+    return resolve(dir, `${slugifyStorageComponent(conversationId)}.json`);
+  }
+
+  async get(conversationId: string): Promise<TodoItem[]> {
+    try {
+      const fp = await this.filePath(conversationId);
+      const raw = await readFile(fp, "utf8");
+      return parseTodoList(JSON.parse(raw));
+    } catch {
+      return [];
+    }
+  }
+
+  async set(conversationId: string, todos: TodoItem[]): Promise<void> {
+    const fp = await this.filePath(conversationId);
+    await writeJsonAtomic(fp, todos);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// KVBackedTodoStore — wraps any RawKVStore (Upstash, Redis, DynamoDB)
+// ---------------------------------------------------------------------------
+
+class KVBackedTodoStore implements TodoStore {
+  private readonly kv: RawKVStore;
+  private readonly baseKey: string;
+  private readonly ttl?: number;
+  private readonly memoryFallback = new InMemoryTodoStore();
+
+  constructor(kv: RawKVStore, baseKey: string, ttl?: number) {
+    this.kv = kv;
+    this.baseKey = baseKey;
+    this.ttl = ttl;
+  }
+
+  private keyFor(conversationId: string): string {
+    return `${this.baseKey}:${slugifyStorageComponent(conversationId)}`;
+  }
+
+  async get(conversationId: string): Promise<TodoItem[]> {
+    try {
+      const raw = await this.kv.get(this.keyFor(conversationId));
+      if (!raw) return [];
+      return parseTodoList(JSON.parse(raw));
+    } catch {
+      return this.memoryFallback.get(conversationId);
+    }
+  }
+
+  async set(conversationId: string, todos: TodoItem[]): Promise<void> {
+    try {
+      const serialized = JSON.stringify(todos);
+      const key = this.keyFor(conversationId);
+      if (typeof this.ttl === "number") {
+        await this.kv.setWithTtl(key, serialized, Math.max(1, this.ttl));
+      } else {
+        await this.kv.set(key, serialized);
+      }
+    } catch {
+      await this.memoryFallback.set(conversationId, todos);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export const createTodoStore = (
+  agentId: string,
+  config?: StateConfig,
+  options?: { workingDir?: string },
+): TodoStore => {
+  const provider = config?.provider ?? "local";
+  const ttl = config?.ttl;
+  const workingDir = options?.workingDir ?? process.cwd();
+
+  if (provider === "local") {
+    return new FileTodoStore(workingDir);
+  }
+  if (provider === "memory") {
+    return new InMemoryTodoStore();
+  }
+
+  const kv = createRawKVStore(config);
+  if (kv) {
+    const baseKey = `poncho:${STORAGE_SCHEMA_VERSION}:${slugifyStorageComponent(agentId)}:todos`;
+    return new KVBackedTodoStore(kv, baseKey, ttl);
+  }
+  return new InMemoryTodoStore();
+};
+
+// ---------------------------------------------------------------------------
+// Tool definitions
+// ---------------------------------------------------------------------------
+
+export const createTodoTools = (store: TodoStore): ToolDefinition[] => {
+  const resolveKey = (context: { conversationId?: string; runId: string }): string =>
+    context.conversationId || context.runId;
+
+  return [
+    defineTool({
+      name: "todo_list",
+      description:
+        "List all todo items for the current conversation. " +
+        "Use this to check progress and plan next steps.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          status: {
+            type: "string",
+            enum: VALID_STATUSES,
+            description: "Filter by status (omit to list all)",
+          },
+        },
+        additionalProperties: false,
+      },
+      handler: async (input, context) => {
+        const key = resolveKey(context);
+        let todos = await store.get(key);
+        const status = typeof input.status === "string" ? input.status : undefined;
+        if (status && VALID_STATUSES.includes(status as TodoStatus)) {
+          todos = todos.filter((t) => t.status === status);
+        }
+        return { todos, count: todos.length };
+      },
+    }),
+
+    defineTool({
+      name: "todo_add",
+      description:
+        "Add a new todo item for the current conversation. " +
+        "Use proactively for complex multi-step tasks (3+ steps).",
+      inputSchema: {
+        type: "object",
+        properties: {
+          content: {
+            type: "string",
+            description: "Description of the task",
+          },
+          status: {
+            type: "string",
+            enum: VALID_STATUSES,
+            description: "Initial status (default: pending)",
+          },
+          priority: {
+            type: "string",
+            enum: VALID_PRIORITIES,
+            description: "Priority level (default: medium)",
+          },
+        },
+        required: ["content"],
+        additionalProperties: false,
+      },
+      handler: async (input, context) => {
+        const content = typeof input.content === "string" ? input.content.trim() : "";
+        if (!content) throw new Error("content is required");
+        const status: TodoStatus =
+          typeof input.status === "string" && VALID_STATUSES.includes(input.status as TodoStatus)
+            ? (input.status as TodoStatus)
+            : "pending";
+        const priority: TodoPriority =
+          typeof input.priority === "string" && VALID_PRIORITIES.includes(input.priority as TodoPriority)
+            ? (input.priority as TodoPriority)
+            : "medium";
+        const now = Date.now();
+        const todo: TodoItem = {
+          id: generateId(),
+          content,
+          status,
+          priority,
+          createdAt: now,
+          updatedAt: now,
+        };
+        const key = resolveKey(context);
+        const todos = await store.get(key);
+        todos.push(todo);
+        await store.set(key, todos);
+        return { todo, todos };
+      },
+    }),
+
+    defineTool({
+      name: "todo_update",
+      description:
+        "Update an existing todo item's status, content, or priority. " +
+        "Mark tasks in_progress when starting and completed when done.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: {
+            type: "string",
+            description: "ID of the todo to update",
+          },
+          status: {
+            type: "string",
+            enum: VALID_STATUSES,
+            description: "New status",
+          },
+          content: {
+            type: "string",
+            description: "New content/description",
+          },
+          priority: {
+            type: "string",
+            enum: VALID_PRIORITIES,
+            description: "New priority level",
+          },
+        },
+        required: ["id"],
+        additionalProperties: false,
+      },
+      handler: async (input, context) => {
+        const id = typeof input.id === "string" ? input.id : "";
+        if (!id) throw new Error("id is required");
+        const key = resolveKey(context);
+        const todos = await store.get(key);
+        const todo = todos.find((t) => t.id === id);
+        if (!todo) throw new Error(`Todo with id "${id}" not found`);
+
+        if (typeof input.status === "string" && VALID_STATUSES.includes(input.status as TodoStatus)) {
+          todo.status = input.status as TodoStatus;
+        }
+        if (typeof input.content === "string" && input.content.trim()) {
+          todo.content = input.content.trim();
+        }
+        if (typeof input.priority === "string" && VALID_PRIORITIES.includes(input.priority as TodoPriority)) {
+          todo.priority = input.priority as TodoPriority;
+        }
+        todo.updatedAt = Date.now();
+        await store.set(key, todos);
+        return { todo, todos };
+      },
+    }),
+
+    defineTool({
+      name: "todo_remove",
+      description: "Remove a todo item by ID.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: {
+            type: "string",
+            description: "ID of the todo to remove",
+          },
+        },
+        required: ["id"],
+        additionalProperties: false,
+      },
+      handler: async (input, context) => {
+        const id = typeof input.id === "string" ? input.id : "";
+        if (!id) throw new Error("id is required");
+        const key = resolveKey(context);
+        const todos = await store.get(key);
+        const index = todos.findIndex((t) => t.id === id);
+        if (index === -1) throw new Error(`Todo with id "${id}" not found`);
+        const [removed] = todos.splice(index, 1);
+        await store.set(key, todos);
+        return { removed, todos };
+      },
+    }),
+  ];
+};

package/.turbo/turbo-lint.log

@@ -1,6 +0,0 @@
-
-> @poncho-ai/harness@0.11.2 lint /Users/cesar/Dev/latitude/poncho-ai/packages/harness
-> eslint src/
-
-sh: eslint: command not found
- ELIFECYCLE  Command failed.

package/.turbo/turbo-test.log

@@ -1,135 +0,0 @@
-
-> @poncho-ai/harness@0.16.1 test /Users/cesar/Dev/latitude/poncho-ai/packages/harness
-> vitest
-
-
- RUN  v1.6.1 /Users/cesar/Dev/latitude/poncho-ai/packages/harness
-
- ✓ test/telemetry.test.ts  (3 tests) 2ms
-[event] step:completed {"type":"step:completed","step":1,"duration":1}
-[event] step:started {"type":"step:started","step":2}
- ✓ test/schema-converter.test.ts  (27 tests) 19ms
-stdout | test/mcp.test.ts > mcp bridge protocol transports > discovers and calls tools over streamable HTTP
-[poncho][mcp] {"event":"catalog.loaded","server":"remote","discoveredCount":1}
-[poncho][mcp] {"event":"tools.selected","requestedPatternCount":1,"registeredCount":1,"filteredByPolicyCount":0,"filteredByIntentCount":0}
-
-stdout | test/mcp.test.ts > mcp bridge protocol transports > selects discovered tools by requested patterns
-[poncho][mcp] {"event":"catalog.loaded","server":"remote","discoveredCount":2}
-[poncho][mcp] {"event":"tools.selected","requestedPatternCount":1,"registeredCount":1,"filteredByPolicyCount":0,"filteredByIntentCount":1}
-[poncho][mcp] {"event":"tools.selected","requestedPatternCount":1,"registeredCount":2,"filteredByPolicyCount":0,"filteredByIntentCount":0}
-
- ✓ test/agent-parser.test.ts  (10 tests) 24ms
-stdout | test/mcp.test.ts > mcp bridge protocol transports > skips discovery when bearer token env value is missing
-[poncho][mcp] {"event":"tools.selected","requestedPatternCount":1,"registeredCount":0,"filteredByPolicyCount":0,"filteredByIntentCount":0}
-
-stderr | test/mcp.test.ts > mcp bridge protocol transports > skips discovery when bearer token env value is missing
-[poncho][mcp] {"event":"auth.token_missing","server":"remote","tokenEnv":"MISSING_TOKEN_ENV"}
-
-stdout | test/mcp.test.ts > mcp bridge protocol transports > returns actionable errors for 403 permission failures
-[poncho][mcp] {"event":"catalog.loaded","server":"remote","discoveredCount":1}
-[poncho][mcp] {"event":"tools.selected","requestedPatternCount":1,"registeredCount":1,"filteredByPolicyCount":0,"filteredByIntentCount":0}
-
- ✓ test/mcp.test.ts  (6 tests) 81ms
- ✓ test/memory.test.ts  (4 tests) 56ms
- ✓ test/state.test.ts  (5 tests) 237ms
- ✓ test/model-factory.test.ts  (4 tests) 2ms
- ✓ test/agent-identity.test.ts  (2 tests) 43ms
-stdout | test/harness.test.ts > agent harness > registers default filesystem tools
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > disables write_file by default in production environment
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > allows disabling built-in tools via poncho.config.js
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > supports per-environment tool overrides
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > supports per-environment tool overrides
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > does not auto-register exported tool objects from skill scripts
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > refreshes skill metadata and tools in development mode
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > refreshes skill metadata and tools in development mode
-[poncho][mcp] {"event":"tools.cleared","reason":"skills:changed","requestedPatterns":[]}
-[poncho][mcp] {"event":"tools.cleared","reason":"activate:beta","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > prunes removed active skills after refresh in development mode
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-[poncho][mcp] {"event":"tools.cleared","reason":"activate:obsolete","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > prunes removed active skills after refresh in development mode
-[poncho][mcp] {"event":"tools.cleared","reason":"skills:changed","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > does not refresh skills outside development mode
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > clears active skills when skill metadata changes in development mode
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-[poncho][mcp] {"event":"tools.cleared","reason":"activate:alpha","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > clears active skills when skill metadata changes in development mode
-[poncho][mcp] {"event":"tools.cleared","reason":"skills:changed","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > lists skill scripts through list_skill_scripts
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > runs JavaScript/TypeScript skill scripts through run_skill_script
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > runs AGENT-scope scripts from root scripts directory
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > blocks path traversal in run_skill_script
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > requires allowed-tools entries for non-standard script directories
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > registers MCP tools dynamically for stacked active skills and supports deactivation
-[poncho][mcp] {"event":"catalog.loaded","server":"remote","discoveredCount":2}
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-[poncho][mcp] {"event":"tools.selected","requestedPatternCount":1,"registeredCount":1,"filteredByPolicyCount":0,"filteredByIntentCount":1}
-[poncho][mcp] {"event":"tools.refreshed","reason":"activate:skill-a","requestedPatterns":["remote/a"],"registeredCount":1,"activeSkills":["skill-a"]}
-[poncho][mcp] {"event":"tools.selected","requestedPatternCount":2,"registeredCount":2,"filteredByPolicyCount":0,"filteredByIntentCount":0}
-[poncho][mcp] {"event":"tools.refreshed","reason":"activate:skill-b","requestedPatterns":["remote/a","remote/b"],"registeredCount":2,"activeSkills":["skill-a","skill-b"]}
-[poncho][mcp] {"event":"tools.selected","requestedPatternCount":1,"registeredCount":1,"filteredByPolicyCount":0,"filteredByIntentCount":1}
-[poncho][mcp] {"event":"tools.refreshed","reason":"deactivate:skill-a","requestedPatterns":["remote/b"],"registeredCount":1,"activeSkills":["skill-b"]}
-
-stdout | test/harness.test.ts > agent harness > supports flat tool access config format
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > flat tool access takes priority over legacy defaults
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > byEnvironment overrides flat tool access
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > registerTools skips tools disabled via config
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > approval access level registers the tool but marks it for approval
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > tools without approval config do not require approval
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-
-stdout | test/harness.test.ts > agent harness > allows in-flight MCP calls to finish after skill deactivation
-[poncho][mcp] {"event":"catalog.loaded","server":"remote","discoveredCount":1}
-[poncho][mcp] {"event":"tools.cleared","reason":"initialize","requestedPatterns":[]}
-[poncho][mcp] {"event":"tools.selected","requestedPatternCount":1,"registeredCount":1,"filteredByPolicyCount":0,"filteredByIntentCount":0}
-[poncho][mcp] {"event":"tools.refreshed","reason":"activate:skill-slow","requestedPatterns":["remote/slow"],"registeredCount":1,"activeSkills":["skill-slow"]}
-[poncho][mcp] {"event":"tools.cleared","reason":"deactivate:skill-slow","requestedPatterns":[]}
-
- ✓ test/harness.test.ts  (25 tests) 291ms
-
- Test Files  9 passed (9)
-      Tests  86 passed (86)
-   Start at  17:47:43
-   Duration  1.88s (transform 684ms, setup 1ms, collect 2.34s, tests 755ms, environment 2ms, prepare 1.27s)
-