@poncho-ai/harness 0.24.0 → 0.25.0

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,7 +15,7 @@ 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 { parseAgentFile, parseAgentMarkdown, renderAgentPrompt, type ParsedAgent, type AgentFrontmatter } from "./agent-parser.js";
 import { loadPonchoConfig, resolveMemoryConfig, type PonchoConfig, type ToolAccess, type BuiltInToolToggles } from "./config.js";
 import { createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createEditTool, createWriteTool, ponchoDocsTool } from "./default-tools.js";
 import {
@@ -563,6 +565,7 @@ export class AgentHarness {
   };
 
   private parsedAgent?: ParsedAgent;
+  private agentFileFingerprint = "";
   private mcpBridge?: LocalMcpBridge;
   private subagentManager?: SubagentManager;
 
@@ -696,20 +699,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 +727,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 +888,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 +950,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;
@@ -1286,10 +1346,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 +1360,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 +1376,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 +1408,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 +1420,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 +1434,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 +2328,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/memory.ts

@@ -27,7 +27,7 @@ export interface MemoryConfig {
 
 export interface MemoryStore {
   getMainMemory(): Promise<MainMemory>;
-  updateMainMemory(input: { content: string; mode?: "replace" | "append" }): Promise<MainMemory>;
+  updateMainMemory(input: { content: string }): Promise<MainMemory>;
 }
 
 type MainMemoryPayload = {
@@ -89,19 +89,10 @@ class InMemoryMemoryStore implements MemoryStore {
     return this.mainMemory;
   }
 
-  async updateMainMemory(input: {
-    content: string;
-    mode?: "replace" | "append";
-  }): Promise<MainMemory> {
-    const now = Date.now();
-    const existing = await this.getMainMemory();
-    const nextContent =
-      input.mode === "append" && existing.content
-        ? `${existing.content}\n\n${input.content}`.trim()
-        : input.content;
+  async updateMainMemory(input: { content: string }): Promise<MainMemory> {
     this.mainMemory = {
-      content: nextContent.trim(),
-      updatedAt: now,
+      content: input.content.trim(),
+      updatedAt: Date.now(),
     };
     return this.mainMemory;
   }
@@ -166,18 +157,10 @@ class FileMainMemoryStore implements MemoryStore {
     return this.mainMemory;
   }
 
-  async updateMainMemory(input: {
-    content: string;
-    mode?: "replace" | "append";
-  }): Promise<MainMemory> {
+  async updateMainMemory(input: { content: string }): Promise<MainMemory> {
     await this.ensureLoaded();
-    const existing = await this.getMainMemory();
-    const nextContent =
-      input.mode === "append" && existing.content
-        ? `${existing.content}\n\n${input.content}`.trim()
-        : input.content;
     this.mainMemory = {
-      content: nextContent.trim(),
+      content: input.content.trim(),
       updatedAt: Date.now(),
     };
     await this.persist();
@@ -225,7 +208,6 @@ abstract class KeyValueMainMemoryStoreBase implements MemoryStore {
     } catch {
       await this.memoryFallback.updateMainMemory({
         content: payload.main.content,
-        mode: "replace",
       });
     }
   }
@@ -235,18 +217,11 @@ abstract class KeyValueMainMemoryStoreBase implements MemoryStore {
     return payload.main;
   }
 
-  async updateMainMemory(input: {
-    content: string;
-    mode?: "replace" | "append";
-  }): Promise<MainMemory> {
+  async updateMainMemory(input: { content: string }): Promise<MainMemory> {
     const key = this.key();
     const payload = await this.readPayload(key);
-    const nextContent =
-      input.mode === "append" && payload.main.content
-        ? `${payload.main.content}\n\n${input.content}`.trim()
-        : input.content;
     payload.main = {
-      content: nextContent.trim(),
+      content: input.content.trim(),
       updatedAt: Date.now(),
     };
     await this.writePayload(key, payload);
@@ -590,20 +565,17 @@ export const createMemoryTools = (
       },
     }),
     defineTool({
-      name: "memory_main_update",
+      name: "memory_main_write",
       description:
-        "Update persistent main memory when new stable preferences, long-term goals, or durable facts appear. Proactively evaluate every turn whether memory should be updated, and avoid storing ephemeral details.",
+        "Overwrite the entire persistent main memory document. " +
+        "Use for initial writes or full rewrites. " +
+        "Prefer memory_main_edit for targeted changes to existing memory.",
       inputSchema: {
         type: "object",
         properties: {
-          mode: {
-            type: "string",
-            enum: ["replace", "append"],
-            description: "replace overwrites memory; append adds content to the end",
-          },
           content: {
             type: "string",
-            description: "The memory content to write",
+            description: "The full memory content to write",
           },
         },
         required: ["content"],
@@ -614,11 +586,56 @@ export const createMemoryTools = (
         if (!content) {
           throw new Error("content is required");
         }
-        const mode =
-          input.mode === "append" || input.mode === "replace"
-            ? input.mode
-            : "replace";
-        const memory = await store.updateMainMemory({ content, mode });
+        const memory = await store.updateMainMemory({ content });
+        return { ok: true, memory };
+      },
+    }),
+    defineTool({
+      name: "memory_main_edit",
+      description:
+        "Edit persistent main memory by replacing an exact string match with new content. " +
+        "The old_str must match exactly one location in memory. " +
+        "Use an empty new_str to delete matched content. " +
+        "Proactively evaluate every turn whether memory should be updated.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          old_str: {
+            type: "string",
+            description:
+              "The exact text to find and replace (must be unique in memory). " +
+              "Include surrounding context if needed to ensure uniqueness.",
+          },
+          new_str: {
+            type: "string",
+            description: "The replacement text (use empty string to delete the matched content)",
+          },
+        },
+        required: ["old_str", "new_str"],
+        additionalProperties: false,
+      },
+      handler: async (input) => {
+        const oldStr = typeof input.old_str === "string" ? input.old_str : "";
+        const newStr = typeof input.new_str === "string" ? input.new_str : "";
+        if (!oldStr) {
+          throw new Error("old_str must not be empty.");
+        }
+        const current = await store.getMainMemory();
+        const content = current.content;
+        const first = content.indexOf(oldStr);
+        if (first === -1) {
+          throw new Error(
+            "old_str not found in memory. Make sure it matches exactly, including whitespace and line breaks.",
+          );
+        }
+        const last = content.lastIndexOf(oldStr);
+        if (first !== last) {
+          throw new Error(
+            "old_str appears multiple times in memory. Please provide more context to ensure a unique match.",
+          );
+        }
+        const newContent = content.slice(0, first) + newStr + content.slice(first + oldStr.length);
+        const memory = await store.updateMainMemory({ content: newContent });
         return { ok: true, memory };
       },
     }),

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(