@poncho-ai/harness 0.24.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/test/harness.test.ts

@@ -367,7 +367,7 @@ description: Beta skill
     });
   });
 
-  it("clears active skills when skill metadata changes in development mode", async () => {
+  it("preserves active skills when skill metadata changes in development mode", async () => {
     const dir = await mkdtemp(join(tmpdir(), "poncho-harness-skill-refresh-clear-active-"));
     await writeFile(
       join(dir, "AGENT.md"),
@@ -405,6 +405,7 @@ description: Alpha skill
     await activate!.handler({ name: "alpha" }, {} as any);
     expect(await listActive!.handler({}, {} as any)).toEqual({ activeSkills: ["alpha"] });
 
+    // Update the skill metadata — the skill keeps the same name so it stays active
     await writeFile(
       join(dir, "skills", "alpha", "SKILL.md"),
       `---
@@ -417,7 +418,7 @@ description: Alpha skill updated
       "utf8",
     );
     await (harness as any).refreshSkillsIfChanged();
-    expect(await listActive!.handler({}, {} as any)).toEqual({ activeSkills: [] });
+    expect(await listActive!.handler({}, {} as any)).toEqual({ activeSkills: ["alpha"] });
   });
 
   it("lists skill scripts through list_skill_scripts", async () => {
@@ -910,6 +911,132 @@ allowed-tools:
     await new Promise<void>((resolveClose) => mcpServer.close(() => resolveClose()));
   });
 
+  it("agent-level MCP tools persist when a skill is activated (additive)", async () => {
+    process.env.LINEAR_TOKEN = "token-123";
+    const mcpServer = createServer(async (req, res) => {
+      if (req.method === "DELETE") {
+        res.statusCode = 200;
+        res.end();
+        return;
+      }
+      const chunks: Buffer[] = [];
+      for await (const chunk of req) chunks.push(Buffer.from(chunk));
+      const body = Buffer.concat(chunks).toString("utf8");
+      const payload = body.trim().length > 0 ? (JSON.parse(body) as any) : {};
+      if (payload.method === "initialize") {
+        res.setHeader("Content-Type", "application/json");
+        res.setHeader("Mcp-Session-Id", "sess");
+        res.end(
+          JSON.stringify({
+            jsonrpc: "2.0",
+            id: payload.id,
+            result: {
+              protocolVersion: "2025-03-26",
+              capabilities: { tools: { listChanged: true } },
+              serverInfo: { name: "remote", version: "1.0.0" },
+            },
+          }),
+        );
+        return;
+      }
+      if (payload.method === "notifications/initialized") {
+        res.statusCode = 202;
+        res.end();
+        return;
+      }
+      if (payload.method === "tools/list") {
+        res.setHeader("Content-Type", "application/json");
+        res.end(
+          JSON.stringify({
+            jsonrpc: "2.0",
+            id: payload.id,
+            result: {
+              tools: [
+                { name: "a", inputSchema: { type: "object", properties: {} } },
+                { name: "b", inputSchema: { type: "object", properties: {} } },
+              ],
+            },
+          }),
+        );
+        return;
+      }
+      if (payload.method === "tools/call") {
+        res.setHeader("Content-Type", "application/json");
+        res.end(
+          JSON.stringify({
+            jsonrpc: "2.0",
+            id: payload.id,
+            result: { result: { ok: true } },
+          }),
+        );
+        return;
+      }
+      res.statusCode = 404;
+      res.end();
+    });
+    await new Promise<void>((resolveOpen) => mcpServer.listen(0, () => resolveOpen()));
+    const address = mcpServer.address();
+    if (!address || typeof address === "string") throw new Error("Unexpected address");
+    const dir = await mkdtemp(join(tmpdir(), "poncho-harness-additive-mcp-"));
+    await writeFile(
+      join(dir, "AGENT.md"),
+      `---
+name: additive-agent
+model:
+  provider: anthropic
+  name: claude-opus-4-5
+allowed-tools:
+  - mcp:remote/a
+---
+
+# Additive Agent
+`,
+      "utf8",
+    );
+    await writeFile(
+      join(dir, "poncho.config.js"),
+      `export default {
+  mcp: [
+    {
+      name: "remote",
+      url: "http://127.0.0.1:${address.port}/mcp",
+      auth: { type: "bearer", tokenEnv: "LINEAR_TOKEN" }
+    }
+  ]
+};
+`,
+      "utf8",
+    );
+    await mkdir(join(dir, "skills", "skill-b"), { recursive: true });
+    await writeFile(
+      join(dir, "skills", "skill-b", "SKILL.md"),
+      `---
+name: skill-b
+description: B
+allowed-tools:
+  - mcp:remote/b
+---
+# B
+`,
+      "utf8",
+    );
+    const harness = new AgentHarness({ workingDir: dir });
+    await harness.initialize();
+    const toolNames = () => harness.listTools().map((t) => t.name);
+    expect(toolNames()).toContain("remote/a");
+    expect(toolNames()).not.toContain("remote/b");
+    const activate = harness.listTools().find((t) => t.name === "activate_skill")!;
+    const deactivate = harness.listTools().find((t) => t.name === "deactivate_skill")!;
+    await activate.handler({ name: "skill-b" }, {} as any);
+    expect(toolNames()).toContain("remote/a");
+    expect(toolNames()).toContain("remote/b");
+    await deactivate.handler({ name: "skill-b" }, {} as any);
+    expect(toolNames()).toContain("remote/a");
+    expect(toolNames()).not.toContain("remote/b");
+    await harness.shutdown();
+    await new Promise<void>((resolveClose) => mcpServer.close(() => resolveClose()));
+  });
+
   it("supports flat tool access config format", async () => {
     const dir = await mkdtemp(join(tmpdir(), "poncho-harness-flat-tool-access-"));
     await writeFile(

package/test/memory.test.ts

@@ -5,7 +5,6 @@ describe("memory store factory", () => {
   it("uses memory provider by default", async () => {
     const store = createMemoryStore("agent-test");
     const updated = await store.updateMainMemory({
-      mode: "replace",
       content: "Cesar prefers short bullet points.",
     });
     expect(updated.content).toContain("short bullet points");
@@ -13,24 +12,17 @@ describe("memory store factory", () => {
     expect(fetched.content).toContain("short bullet points");
   });
 
-  it("supports append updates", async () => {
-    const store = createMemoryStore("agent-append");
-    await store.updateMainMemory({
-      mode: "replace",
-      content: "Initial memory.",
-    });
-    const result = await store.updateMainMemory({
-      mode: "append",
-      content: "Appended line.",
-    });
-    expect(result.content).toContain("Initial memory.");
-    expect(result.content).toContain("Appended line.");
+  it("overwrites previous content on update", async () => {
+    const store = createMemoryStore("agent-overwrite");
+    await store.updateMainMemory({ content: "First version." });
+    const result = await store.updateMainMemory({ content: "Second version." });
+    expect(result.content).toBe("Second version.");
+    expect(result.content).not.toContain("First version.");
   });
 
   it("falls back gracefully when upstash is not configured", async () => {
     const store = createMemoryStore("agent-fallback", { provider: "upstash" });
     const updated = await store.updateMainMemory({
-      mode: "replace",
       content: "Fallback path still stores memory",
     });
     expect(updated.content).toContain("Fallback path");
@@ -43,8 +35,101 @@ describe("memory tools", () => {
     const tools = createMemoryTools(store);
     expect(tools.map((tool) => tool.name)).toEqual([
       "memory_main_get",
-      "memory_main_update",
+      "memory_main_write",
+      "memory_main_edit",
       "conversation_recall",
     ]);
   });
+
+  describe("memory_main_write", () => {
+    it("writes content to memory", async () => {
+      const store = createMemoryStore("agent-write");
+      const tools = createMemoryTools(store);
+      const writeTool = tools.find((t) => t.name === "memory_main_write")!;
+      const result = await writeTool.handler(
+        { content: "User prefers dark mode." },
+        { runId: "r1", agentId: "a1", step: 0, workingDir: ".", parameters: {} },
+      );
+      expect(result).toEqual({
+        ok: true,
+        memory: expect.objectContaining({ content: "User prefers dark mode." }),
+      });
+    });
+
+    it("errors when content is empty", async () => {
+      const store = createMemoryStore("agent-write-empty");
+      const tools = createMemoryTools(store);
+      const writeTool = tools.find((t) => t.name === "memory_main_write")!;
+      await expect(
+        writeTool.handler(
+          { content: "  " },
+          { runId: "r1", agentId: "a1", step: 0, workingDir: ".", parameters: {} },
+        ),
+      ).rejects.toThrow("content is required");
+    });
+  });
+
+  describe("memory_main_edit", () => {
+    const setupMemory = async () => {
+      const store = createMemoryStore("agent-edit-" + Math.random());
+      await store.updateMainMemory({
+        content: "- prefers dark mode\n- likes TypeScript\n- uses vim",
+      });
+      const tools = createMemoryTools(store);
+      const editTool = tools.find((t) => t.name === "memory_main_edit")!;
+      const ctx = { runId: "r1", agentId: "a1", step: 0, workingDir: ".", parameters: {} };
+      return { store, editTool, ctx };
+    };
+
+    it("replaces a unique string match in memory", async () => {
+      const { store, editTool, ctx } = await setupMemory();
+      const result = await editTool.handler(
+        { old_str: "likes TypeScript", new_str: "loves TypeScript" },
+        ctx,
+      );
+      expect(result).toEqual({
+        ok: true,
+        memory: expect.objectContaining({
+          content: "- prefers dark mode\n- loves TypeScript\n- uses vim",
+        }),
+      });
+      const fetched = await store.getMainMemory();
+      expect(fetched.content).toContain("loves TypeScript");
+    });
+
+    it("deletes matched content when new_str is empty", async () => {
+      const { store, editTool, ctx } = await setupMemory();
+      await editTool.handler(
+        { old_str: "\n- likes TypeScript", new_str: "" },
+        ctx,
+      );
+      const fetched = await store.getMainMemory();
+      expect(fetched.content).toBe("- prefers dark mode\n- uses vim");
+    });
+
+    it("errors when old_str is empty", async () => {
+      const { editTool, ctx } = await setupMemory();
+      await expect(
+        editTool.handler({ old_str: "", new_str: "anything" }, ctx),
+      ).rejects.toThrow("old_str must not be empty");
+    });
+
+    it("errors when old_str is not found in memory", async () => {
+      const { editTool, ctx } = await setupMemory();
+      await expect(
+        editTool.handler({ old_str: "nonexistent text", new_str: "x" }, ctx),
+      ).rejects.toThrow("old_str not found in memory");
+    });
+
+    it("errors when old_str matches multiple locations", async () => {
+      const store = createMemoryStore("agent-edit-dup");
+      await store.updateMainMemory({ content: "foo bar foo" });
+      const tools = createMemoryTools(store);
+      const editTool = tools.find((t) => t.name === "memory_main_edit")!;
+      const ctx = { runId: "r1", agentId: "a1", step: 0, workingDir: ".", parameters: {} };
+      await expect(
+        editTool.handler({ old_str: "foo", new_str: "baz" }, ctx),
+      ).rejects.toThrow("old_str appears multiple times");
+    });
+  });
 });