@poncho-ai/harness 0.23.0 → 0.25.0

package/src/default-tools.ts

@@ -89,6 +89,59 @@ export const createWriteTool = (workingDir: string): ToolDefinition =>
     },
   });
 
+export const createEditTool = (workingDir: string): ToolDefinition =>
+  defineTool({
+    name: "edit_file",
+    description:
+      "Edit a file by replacing an exact string match with new content. " +
+      "The old_str must match exactly one location in the file (including whitespace and indentation). " +
+      "Use an empty new_str to delete matched content.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: {
+          type: "string",
+          description: "File path relative to working directory",
+        },
+        old_str: {
+          type: "string",
+          description:
+            "The exact text to find and replace (must be unique in the file). " +
+            "Include surrounding context lines if needed to ensure uniqueness.",
+        },
+        new_str: {
+          type: "string",
+          description: "The replacement text (use empty string to delete the matched content)",
+        },
+      },
+      required: ["path", "old_str", "new_str"],
+      additionalProperties: false,
+    },
+    handler: async (input) => {
+      const path = typeof input.path === "string" ? input.path : "";
+      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 resolved = resolveSafePath(workingDir, path);
+      const content = await readFile(resolved, "utf8");
+      const first = content.indexOf(oldStr);
+      if (first === -1) {
+        throw new Error(
+          "old_str not found in file. 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 the file. Please provide more context to ensure a unique match.",
+        );
+      }
+      const newContent = content.slice(0, first) + newStr + content.slice(first + oldStr.length);
+      await writeFile(resolved, newContent, "utf8");
+      return { path, edited: true };
+    },
+  });
+
 export const createDeleteTool = (workingDir: string): ToolDefinition =>
   defineTool({
     name: "delete_file",

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,9 +15,9 @@ 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, createWriteTool, ponchoDocsTool } from "./default-tools.js";
+import { createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createEditTool, createWriteTool, ponchoDocsTool } from "./default-tools.js";
 import {
   createMemoryStore,
   createMemoryTools,
@@ -224,7 +226,7 @@ You are running locally in development mode. Treat this as an editable agent wor
 ## Understanding Your Environment
 
 - Built-in tools: \`list_directory\` and \`read_file\`
-- \`write_file\` is available in development (disabled by default in production)
+- \`write_file\` and \`edit_file\` are available in development (disabled by default in production)
 - A starter local skill is included (\`starter-echo\`)
 - Bash/shell commands are **not** available unless you install and enable a shell tool/skill
 - Git operations are only available if a git-capable tool/skill is configured
@@ -485,6 +487,7 @@ Since all fields have defaults, you only need to specify \`*Env\` when your env
 - If shell/CLI access is unavailable, ask the user to run needed commands and provide exact copy-paste commands.
 - For setup, skills, MCP, auth, storage, telemetry, or "how do I..." questions, proactively read \`README.md\` with \`read_file\` before answering.
 - Prefer quoting concrete commands and examples from \`README.md\` over guessing.
+- Prefer \`edit_file\` for targeted changes to existing files (uses exact string matching); use \`write_file\` only for creating new files or full rewrites.
 - Keep edits minimal, preserve unrelated settings/code, and summarize what changed.
 
 ## Detailed Documentation
@@ -562,6 +565,7 @@ export class AgentHarness {
   };
 
   private parsedAgent?: ParsedAgent;
+  private agentFileFingerprint = "";
   private mcpBridge?: LocalMcpBridge;
   private subagentManager?: SubagentManager;
 
@@ -585,7 +589,7 @@ export class AgentHarness {
   private isToolEnabled(name: string): boolean {
     const access = this.resolveToolAccess(name);
     if (access === false) return false;
-    if (name === "write_file" || name === "delete_file" || name === "delete_directory") {
+    if (name === "write_file" || name === "edit_file" || name === "delete_file" || name === "delete_directory") {
       return this.shouldEnableWriteTool();
     }
     return true;
@@ -633,6 +637,9 @@ export class AgentHarness {
     if (this.isToolEnabled("write_file")) {
       this.registerIfMissing(createWriteTool(this.workingDir));
     }
+    if (this.isToolEnabled("edit_file")) {
+      this.registerIfMissing(createEditTool(this.workingDir));
+    }
     if (this.isToolEnabled("delete_file")) {
       this.registerIfMissing(createDeleteTool(this.workingDir));
     }
@@ -692,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[] {
@@ -723,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[] {
@@ -887,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 {
@@ -903,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;
@@ -1282,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
@@ -1295,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;
@@ -1311,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
@@ -1342,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
@@ -1357,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
 
@@ -1365,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);
@@ -2256,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 };
       },
     }),