@poncho-ai/harness 0.24.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/harness",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Agent execution runtime - conversation loop, tool dispatch, streaming",
   "repository": {
     "type": "git",

package/src/config.ts

@@ -42,6 +42,10 @@ export type BuiltInToolToggles = {
   edit_file?: boolean;
   delete_file?: boolean;
   delete_directory?: boolean;
+  todo_list?: boolean;
+  todo_add?: boolean;
+  todo_update?: boolean;
+  todo_remove?: boolean;
 };
 
 export interface MessagingChannelConfig {

package/src/harness.ts

@@ -1,4 +1,6 @@
 import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
 import type {
   AgentEvent,
   ContentPart,
@@ -13,14 +15,15 @@ import type {
 import { getTextContent } from "@poncho-ai/sdk";
 import type { UploadStore } from "./upload-store.js";
 import { PONCHO_UPLOAD_SCHEME, deriveUploadKey } from "./upload-store.js";
-import { parseAgentFile, renderAgentPrompt, type ParsedAgent, type AgentFrontmatter } from "./agent-parser.js";
-import { loadPonchoConfig, resolveMemoryConfig, type PonchoConfig, type ToolAccess, type BuiltInToolToggles } from "./config.js";
+import { parseAgentFile, parseAgentMarkdown, renderAgentPrompt, type ParsedAgent, type AgentFrontmatter } from "./agent-parser.js";
+import { loadPonchoConfig, resolveMemoryConfig, resolveStateConfig, type PonchoConfig, type ToolAccess, type BuiltInToolToggles } from "./config.js";
 import { createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createEditTool, createWriteTool, ponchoDocsTool } from "./default-tools.js";
 import {
   createMemoryStore,
   createMemoryTools,
   type MemoryStore,
 } from "./memory.js";
+import { createTodoStore, createTodoTools, type TodoItem, type TodoStore } from "./todo-tools.js";
 import { LocalMcpBridge } from "./mcp.js";
 import { createModelProvider, getModelContextWindow, type ModelProviderFactory, type ProviderConfig } from "./model-factory.js";
 import { buildSkillContextWindow, loadSkillMetadata } from "./skill-context.js";
@@ -548,6 +551,7 @@ export class AgentHarness {
   readonly uploadStore?: UploadStore;
   private skillContextWindow = "";
   private memoryStore?: MemoryStore;
+  private todoStore?: TodoStore;
   private loadedConfig?: PonchoConfig;
   private loadedSkills: SkillMetadata[] = [];
   private skillFingerprint = "";
@@ -563,6 +567,7 @@ export class AgentHarness {
   };
 
   private parsedAgent?: ParsedAgent;
+  private agentFileFingerprint = "";
   private mcpBridge?: LocalMcpBridge;
   private subagentManager?: SubagentManager;
 
@@ -675,6 +680,11 @@ export class AgentHarness {
     return this.parsedAgent?.frontmatter;
   }
 
+  async getTodos(conversationId: string): Promise<TodoItem[]> {
+    if (!this.todoStore) return [];
+    return this.todoStore.get(conversationId);
+  }
+
   private listActiveSkills(): string[] {
     return [...this.activeSkillNames].sort();
   }
@@ -696,20 +706,17 @@ export class AgentHarness {
   }
 
   private getRequestedMcpPatterns(): string[] {
-    const skillPatterns = new Set<string>();
+    const patterns = new Set<string>(this.getAgentMcpIntent());
     for (const skillName of this.activeSkillNames) {
       const skill = this.loadedSkills.find((entry) => entry.name === skillName);
       if (!skill) {
         continue;
       }
       for (const pattern of skill.allowedTools.mcp) {
-        skillPatterns.add(pattern);
+        patterns.add(pattern);
       }
     }
-    if (skillPatterns.size > 0) {
-      return [...skillPatterns];
-    }
-    return this.getAgentMcpIntent();
+    return [...patterns];
   }
 
   private getRequestedScriptPatterns(): string[] {
@@ -727,20 +734,17 @@ export class AgentHarness {
   }
 
   private getRequestedMcpApprovalPatterns(): string[] {
-    const skillPatterns = new Set<string>();
+    const patterns = new Set<string>(this.getAgentMcpApprovalPatterns());
     for (const skillName of this.activeSkillNames) {
       const skill = this.loadedSkills.find((entry) => entry.name === skillName);
       if (!skill) {
         continue;
       }
       for (const pattern of skill.approvalRequired.mcp) {
-        skillPatterns.add(pattern);
+        patterns.add(pattern);
       }
     }
-    if (skillPatterns.size > 0) {
-      return [...skillPatterns];
-    }
-    return this.getAgentMcpApprovalPatterns();
+    return [...patterns];
   }
 
   private getRequestedScriptApprovalPatterns(): string[] {
@@ -891,13 +895,59 @@ export class AgentHarness {
 
   private static readonly SKILL_REFRESH_DEBOUNCE_MS = 3000;
 
-  private async refreshSkillsIfChanged(): Promise<void> {
+  /**
+   * Re-read AGENT.md and update the parsed agent when the file has changed
+   * on disk.  Returns `true` when the agent was actually re-parsed.
+   *
+   * Preserves the agent identity (id) across reloads so conversation
+   * continuity isn't broken.
+   */
+  private async refreshAgentIfChanged(): Promise<boolean> {
     if (this.environment !== "development") {
-      return;
+      return false;
     }
-    const elapsed = Date.now() - this.lastSkillRefreshAt;
-    if (this.lastSkillRefreshAt > 0 && elapsed < AgentHarness.SKILL_REFRESH_DEBOUNCE_MS) {
-      return;
+    try {
+      const agentFilePath = resolve(this.workingDir, "AGENT.md");
+      const rawContent = await readFile(agentFilePath, "utf8");
+      if (rawContent === this.agentFileFingerprint) {
+        return false;
+      }
+      const parsed = parseAgentMarkdown(rawContent);
+      // Preserve the resolved agent identity so existing conversations
+      // keep working after an AGENT.md edit.
+      if (!parsed.frontmatter.id && this.parsedAgent?.frontmatter.id) {
+        parsed.frontmatter.id = this.parsedAgent.frontmatter.id;
+      }
+      this.parsedAgent = parsed;
+      this.agentFileFingerprint = rawContent;
+      return true;
+    } catch (error) {
+      console.warn(
+        `[poncho][agent] Failed to refresh AGENT.md in development mode: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+      return false;
+    }
+  }
+
+  /**
+   * Re-scan skill directories and update metadata, tools, and context window
+   * when skills have changed on disk. Returns `true` when the skill set was
+   * actually updated.
+   *
+   * @param force - bypass the time-based debounce (used for mid-run refreshes
+   *   after the agent may have written new skill files).
+   */
+  private async refreshSkillsIfChanged(force = false): Promise<boolean> {
+    if (this.environment !== "development") {
+      return false;
+    }
+    if (!force) {
+      const elapsed = Date.now() - this.lastSkillRefreshAt;
+      if (this.lastSkillRefreshAt > 0 && elapsed < AgentHarness.SKILL_REFRESH_DEBOUNCE_MS) {
+        return false;
+      }
     }
     this.lastSkillRefreshAt = Date.now();
     try {
@@ -907,27 +957,44 @@ export class AgentHarness {
       );
       const nextFingerprint = this.buildSkillFingerprint(latestSkills);
       if (nextFingerprint === this.skillFingerprint) {
-        return;
+        return false;
       }
       this.loadedSkills = latestSkills;
       this.skillContextWindow = buildSkillContextWindow(latestSkills);
       this.skillFingerprint = nextFingerprint;
       this.registerSkillTools(latestSkills);
-      // Skill metadata or layout changed; force re-activation to avoid stale
-      // instructions/tooling when files are renamed or moved during development.
-      this.activeSkillNames.clear();
+      // Prune active skills that no longer exist in the updated metadata,
+      // but preserve ones that were merely updated (same name).  This keeps
+      // MCP tools from active skills registered when their allowed-tools
+      // list changes, instead of forcing the agent to re-activate.
+      const latestSkillNames = new Set(latestSkills.map(s => s.name));
+      for (const name of this.activeSkillNames) {
+        if (!latestSkillNames.has(name)) {
+          this.activeSkillNames.delete(name);
+        }
+      }
+      // Re-discover MCP server catalogs so newly advertised tools are visible,
+      // then refresh the registered tool set with updated skill patterns.
+      if (this.mcpBridge) {
+        await this.mcpBridge.discoverTools();
+      }
       await this.refreshMcpTools("skills:changed");
+      return true;
     } catch (error) {
       console.warn(
         `[poncho][skills] Failed to refresh skills in development mode: ${
           error instanceof Error ? error.message : String(error)
         }`,
       );
+      return false;
     }
   }
 
   async initialize(): Promise<void> {
-    this.parsedAgent = await parseAgentFile(this.workingDir);
+    const agentFilePath = resolve(this.workingDir, "AGENT.md");
+    const agentRawContent = await readFile(agentFilePath, "utf8");
+    this.parsedAgent = parseAgentMarkdown(agentRawContent);
+    this.agentFileFingerprint = agentRawContent;
     const identity = await ensureAgentIdentity(this.workingDir);
     if (!this.parsedAgent.frontmatter.id) {
       this.parsedAgent.frontmatter.id = identity.id;
@@ -948,8 +1015,9 @@ export class AgentHarness {
     this.skillContextWindow = buildSkillContextWindow(skillMetadata);
     this.skillFingerprint = this.buildSkillFingerprint(skillMetadata);
     this.registerSkillTools(skillMetadata);
+    const agentId = this.parsedAgent.frontmatter.id ?? this.parsedAgent.frontmatter.name;
+
     if (memoryConfig?.enabled) {
-      const agentId = this.parsedAgent.frontmatter.id ?? this.parsedAgent.frontmatter.name;
       this.memoryStore = createMemoryStore(
         agentId,
         memoryConfig,
@@ -962,6 +1030,14 @@ export class AgentHarness {
       );
     }
 
+    const stateConfig = resolveStateConfig(config);
+    this.todoStore = createTodoStore(agentId, stateConfig, { workingDir: this.workingDir });
+    for (const tool of createTodoTools(this.todoStore)) {
+      if (this.isToolEnabled(tool.name)) {
+        this.registerIfMissing(tool);
+      }
+    }
+
     if (config?.browser) {
       await this.initBrowserTools(config)
         .catch((e) => {
@@ -1286,10 +1362,11 @@ export class AgentHarness {
     if (!this.parsedAgent) {
       await this.initialize();
     }
-    // Start memory fetch early so it overlaps with skill refresh I/O
+    // Start memory fetch early so it overlaps with refresh I/O
     const memoryPromise = this.memoryStore
       ? this.memoryStore.getMainMemory()
       : undefined;
+    await this.refreshAgentIfChanged();
     await this.refreshSkillsIfChanged();
 
     // Track which conversation/owner this run belongs to so browser & subagent tools resolve correctly
@@ -1299,7 +1376,7 @@ export class AgentHarness {
       this._currentRunOwnerId = ownerParam;
     }
 
-    const agent = this.parsedAgent as ParsedAgent;
+    let agent = this.parsedAgent as ParsedAgent;
     const runId = `run_${randomUUID()}`;
     const start = now();
     const maxSteps = agent.frontmatter.limits?.maxSteps ?? 50;
@@ -1315,15 +1392,16 @@ export class AgentHarness {
     const inputMessageCount = messages.length;
     const events: AgentEvent[] = [];
 
-    const systemPrompt = renderAgentPrompt(agent, {
-      parameters: input.parameters,
-      runtime: {
-        runId,
-        agentId: agent.frontmatter.id ?? agent.frontmatter.name,
-        environment: this.environment,
-        workingDir: this.workingDir,
-      },
-    });
+    const renderCurrentAgentPrompt = (): string =>
+      renderAgentPrompt(this.parsedAgent!, {
+        parameters: input.parameters,
+        runtime: {
+          runId,
+          agentId: this.parsedAgent!.frontmatter.id ?? this.parsedAgent!.frontmatter.name,
+          environment: this.environment,
+          workingDir: this.workingDir,
+        },
+      });
     const developmentContext =
       this.environment === "development" ? `\n\n${DEVELOPMENT_MODE_CONTEXT}` : "";
     const browserContext = this._browserSession
@@ -1346,9 +1424,6 @@ Browser sessions (cookies, localStorage, login state) are automatically saved an
 ### Tabs and resources
 Each conversation gets its own browser tab sharing a single browser instance. Call \`browser_close\` when done to free the tab. If you don't close it, the tab stays open and the user can continue interacting with it.`
       : "";
-    const promptWithSkills = this.skillContextWindow
-      ? `${systemPrompt}${developmentContext}\n\n${this.skillContextWindow}${browserContext}`
-      : `${systemPrompt}${developmentContext}${browserContext}`;
     const mainMemory = await memoryPromise;
     const boundedMainMemory =
       mainMemory && mainMemory.content.length > 4000
@@ -1361,7 +1436,13 @@ Each conversation gets its own browser tab sharing a single browser instance. Ca
 
 ${boundedMainMemory.trim()}`
         : "";
-    const integrityPrompt = `${promptWithSkills}${memoryContext}
+
+    const buildSystemPrompt = (): string => {
+      const agentPrompt = renderCurrentAgentPrompt();
+      const promptWithSkills = this.skillContextWindow
+        ? `${agentPrompt}${developmentContext}\n\n${this.skillContextWindow}${browserContext}`
+        : `${agentPrompt}${developmentContext}${browserContext}`;
+      return `${promptWithSkills}${memoryContext}
 
 ## Execution Integrity
 
@@ -1369,6 +1450,9 @@ ${boundedMainMemory.trim()}`
 - Do not fabricate "Tool Used" or "Tool Result" logs as plain text.
 - Never output faux execution transcripts, markdown tool logs, or "Tool Used/Result" sections.
 - If no suitable tool is available, explicitly say that and ask for guidance.`;
+    };
+    let integrityPrompt = buildSystemPrompt();
+    let lastPromptFingerprint = `${this.agentFileFingerprint}\n${this.skillFingerprint}`;
 
     const pushEvent = (event: AgentEvent): AgentEvent => {
       events.push(event);
@@ -2260,6 +2344,22 @@ ${boundedMainMemory.trim()}`
         metadata: toolMsgMeta as Message["metadata"],
       });
 
+        // In development, re-read AGENT.md and re-scan skills after tool
+        // execution so changes are available on the next step without
+        // requiring a server restart.
+        if (this.environment === "development") {
+          const agentChanged = await this.refreshAgentIfChanged();
+          const skillsChanged = await this.refreshSkillsIfChanged(true);
+          if (agentChanged || skillsChanged) {
+            agent = this.parsedAgent as ParsedAgent;
+            const currentFingerprint = `${this.agentFileFingerprint}\n${this.skillFingerprint}`;
+            if (currentFingerprint !== lastPromptFingerprint) {
+              integrityPrompt = buildSystemPrompt();
+              lastPromptFingerprint = currentFingerprint;
+            }
+          }
+        }
+
         yield pushEvent({
           type: "step:completed",
           step,

package/src/kv-store.ts

@@ -0,0 +1,206 @@
+import type { StateConfig } from "./state.js";
+
+/**
+ * Minimal raw key-value interface shared by MemoryStore, TodoStore, and any
+ * future stores that sit on top of the same user-configured backend.
+ */
+export interface RawKVStore {
+  get(key: string): Promise<string | undefined>;
+  set(key: string, value: string): Promise<void>;
+  setWithTtl(key: string, value: string, ttlSeconds: number): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Upstash
+// ---------------------------------------------------------------------------
+
+class UpstashKVStore implements RawKVStore {
+  private readonly baseUrl: string;
+  private readonly token: string;
+
+  constructor(baseUrl: string, token: string) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.token = token;
+  }
+
+  private headers(): HeadersInit {
+    return { Authorization: `Bearer ${this.token}`, "Content-Type": "application/json" };
+  }
+
+  async get(key: string): Promise<string | undefined> {
+    const response = await fetch(`${this.baseUrl}/get/${encodeURIComponent(key)}`, {
+      method: "POST",
+      headers: this.headers(),
+    });
+    if (!response.ok) return undefined;
+    const payload = (await response.json()) as { result?: string | null };
+    return payload.result ?? undefined;
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    await fetch(
+      `${this.baseUrl}/set/${encodeURIComponent(key)}/${encodeURIComponent(value)}`,
+      { method: "POST", headers: this.headers() },
+    );
+  }
+
+  async setWithTtl(key: string, value: string, ttl: number): Promise<void> {
+    await fetch(
+      `${this.baseUrl}/setex/${encodeURIComponent(key)}/${Math.max(1, ttl)}/${encodeURIComponent(value)}`,
+      { method: "POST", headers: this.headers() },
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Redis
+// ---------------------------------------------------------------------------
+
+class RedisKVStore implements RawKVStore {
+  private readonly clientPromise: Promise<
+    | {
+        get: (key: string) => Promise<string | null>;
+        set: (key: string, value: string, options?: { EX?: number }) => Promise<unknown>;
+      }
+    | undefined
+  >;
+
+  constructor(url: string) {
+    this.clientPromise = (async () => {
+      try {
+        const redisModule = (await import("redis")) as unknown as {
+          createClient: (args: { url: string }) => {
+            connect: () => Promise<unknown>;
+            get: (key: string) => Promise<string | null>;
+            set: (key: string, value: string, options?: { EX?: number }) => Promise<unknown>;
+          };
+        };
+        const client = redisModule.createClient({ url });
+        await client.connect();
+        return client;
+      } catch {
+        return undefined;
+      }
+    })();
+  }
+
+  async get(key: string): Promise<string | undefined> {
+    const client = await this.clientPromise;
+    if (!client) throw new Error("Redis unavailable");
+    const value = await client.get(key);
+    return value ?? undefined;
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    const client = await this.clientPromise;
+    if (!client) throw new Error("Redis unavailable");
+    await client.set(key, value);
+  }
+
+  async setWithTtl(key: string, value: string, ttl: number): Promise<void> {
+    const client = await this.clientPromise;
+    if (!client) throw new Error("Redis unavailable");
+    await client.set(key, value, { EX: Math.max(1, ttl) });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// DynamoDB
+// ---------------------------------------------------------------------------
+
+class DynamoDbKVStore implements RawKVStore {
+  private readonly table: string;
+  private readonly clientPromise: Promise<
+    | {
+        send: (command: unknown) => Promise<unknown>;
+        GetItemCommand: new (input: unknown) => unknown;
+        PutItemCommand: new (input: unknown) => unknown;
+      }
+    | undefined
+  >;
+
+  constructor(table: string, region?: string) {
+    this.table = table;
+    this.clientPromise = (async () => {
+      try {
+        const module = (await import("@aws-sdk/client-dynamodb")) as {
+          DynamoDBClient: new (input: { region?: string }) => {
+            send: (command: unknown) => Promise<unknown>;
+          };
+          GetItemCommand: new (input: unknown) => unknown;
+          PutItemCommand: new (input: unknown) => unknown;
+        };
+        const client = new module.DynamoDBClient({ region });
+        return {
+          send: client.send.bind(client),
+          GetItemCommand: module.GetItemCommand,
+          PutItemCommand: module.PutItemCommand,
+        };
+      } catch {
+        return undefined;
+      }
+    })();
+  }
+
+  async get(key: string): Promise<string | undefined> {
+    const client = await this.clientPromise;
+    if (!client) throw new Error("DynamoDB unavailable");
+    const result = (await client.send(
+      new client.GetItemCommand({ TableName: this.table, Key: { runId: { S: key } } }),
+    )) as { Item?: { value?: { S?: string } } };
+    return result.Item?.value?.S;
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    const client = await this.clientPromise;
+    if (!client) throw new Error("DynamoDB unavailable");
+    await client.send(
+      new client.PutItemCommand({
+        TableName: this.table,
+        Item: { runId: { S: key }, value: { S: value } },
+      }),
+    );
+  }
+
+  async setWithTtl(key: string, value: string, ttl: number): Promise<void> {
+    const client = await this.clientPromise;
+    if (!client) throw new Error("DynamoDB unavailable");
+    const ttlEpoch = Math.floor(Date.now() / 1000) + Math.max(1, ttl);
+    await client.send(
+      new client.PutItemCommand({
+        TableName: this.table,
+        Item: { runId: { S: key }, value: { S: value }, ttl: { N: String(ttlEpoch) } },
+      }),
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory — resolves the user's storage config into a RawKVStore, or
+// undefined when the provider is "local" or "memory" (handled by callers).
+// ---------------------------------------------------------------------------
+
+export const createRawKVStore = (config?: StateConfig): RawKVStore | undefined => {
+  const provider = config?.provider ?? "local";
+
+  if (provider === "upstash") {
+    const urlEnv = config?.urlEnv ?? (process.env.UPSTASH_REDIS_REST_URL ? "UPSTASH_REDIS_REST_URL" : "KV_REST_API_URL");
+    const tokenEnv = config?.tokenEnv ?? (process.env.UPSTASH_REDIS_REST_TOKEN ? "UPSTASH_REDIS_REST_TOKEN" : "KV_REST_API_TOKEN");
+    const url = process.env[urlEnv] ?? "";
+    const token = process.env[tokenEnv] ?? "";
+    if (url && token) return new UpstashKVStore(url, token);
+  }
+
+  if (provider === "redis") {
+    const urlEnv = config?.urlEnv ?? "REDIS_URL";
+    const url = process.env[urlEnv] ?? "";
+    if (url) return new RedisKVStore(url);
+  }
+
+  if (provider === "dynamodb") {
+    const table = config?.table ?? process.env.PONCHO_DYNAMODB_TABLE ?? "";
+    if (table) return new DynamoDbKVStore(table, config?.region);
+  }
+
+  return undefined;
+};