@poncho-ai/harness 0.22.1 → 0.24.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/harness@0.22.1 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
+> @poncho-ai/harness@0.24.0 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
 > node scripts/embed-docs.js && tsup src/index.ts --format esm --dts
 
 [embed-docs] Generated poncho-docs.ts with 4 topics
@@ -8,8 +8,8 @@
 CLI tsup v8.5.1
 CLI Target: es2022
 ESM Build start
-ESM dist/index.js 260.03 KB
-ESM ⚡️ Build success in 131ms
+ESM dist/index.js 263.89 KB
+ESM ⚡️ Build success in 136ms
 DTS Build start
-DTS ⚡️ Build success in 6723ms
-DTS dist/index.d.ts 27.15 KB
+DTS ⚡️ Build success in 6918ms
+DTS dist/index.d.ts 27.50 KB

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @poncho-ai/harness
 
+## 0.24.0
+
+### Minor Changes
+
+- [`aee4f17`](https://github.com/cesr/poncho-ai/commit/aee4f17237d33b2cc134ed9934b709d967ca3f10) Thanks [@cesr](https://github.com/cesr)! - Add `edit_file` built-in tool with str_replace semantics for targeted file edits. The tool takes `path`, `old_str`, and `new_str` parameters, enforces uniqueness of the match, and is write-gated like `write_file` (disabled in production by default). Also improves browser SSE frame streaming with backpressure handling and auto-stops screencast when all listeners disconnect.
+
+## 0.23.0
+
+### Minor Changes
+
+- [`d1e1bfb`](https://github.com/cesr/poncho-ai/commit/d1e1bfbf35b18788ab79231ca675774e949f5116) Thanks [@cesr](https://github.com/cesr)! - Add proactive scheduled messaging via channel-targeted cron jobs. Cron jobs with `channel: telegram` (or `slack`) now automatically discover known conversations and send the agent's response directly to each chat, continuing the existing conversation history.
+
 ## 0.22.1
 
 ### Patch Changes

package/dist/index.d.ts

@@ -19,6 +19,7 @@ interface CronJobConfig {
     schedule: string;
     task: string;
     timezone?: string;
+    channel?: string;
 }
 interface AgentFrontmatter {
     name: string;
@@ -155,6 +156,11 @@ interface Conversation {
         result?: _poncho_ai_sdk.RunResult;
         error?: _poncho_ai_sdk.AgentFailure;
     };
+    channelMeta?: {
+        platform: string;
+        channelId: string;
+        platformThreadId: string;
+    };
     createdAt: number;
     updatedAt: number;
 }
@@ -208,6 +214,11 @@ type ConversationSummary = {
     parentConversationId?: string;
     messageCount?: number;
     hasPendingApprovals?: boolean;
+    channelMeta?: {
+        platform: string;
+        channelId: string;
+        platformThreadId: string;
+    };
 };
 declare const createStateStore: (config?: StateConfig, options?: {
     workingDir?: string;
@@ -317,6 +328,7 @@ type BuiltInToolToggles = {
     list_directory?: boolean;
     read_file?: boolean;
     write_file?: boolean;
+    edit_file?: boolean;
     delete_file?: boolean;
     delete_directory?: boolean;
 };
@@ -423,6 +435,7 @@ declare const loadPonchoConfig: (workingDir: string) => Promise<PonchoConfig | u
 
 declare const createDefaultTools: (workingDir: string) => ToolDefinition[];
 declare const createWriteTool: (workingDir: string) => ToolDefinition;
+declare const createEditTool: (workingDir: string) => ToolDefinition;
 declare const createDeleteTool: (workingDir: string) => ToolDefinition;
 declare const createDeleteDirectoryTool: (workingDir: string) => ToolDefinition;
 declare const ponchoDocsTool: ToolDefinition;
@@ -751,4 +764,4 @@ declare class TelemetryEmitter {
 
 declare const createSubagentTools: (manager: SubagentManager, getConversationId: () => string | undefined, getOwnerId: () => string) => ToolDefinition[];
 
-export { type AgentFrontmatter, AgentHarness, type AgentIdentity, type AgentLimitsConfig, type AgentModelConfig, type BuiltInToolToggles, type CompactMessagesOptions, type CompactResult, type CompactionConfig, type Conversation, type ConversationState, type ConversationStore, type ConversationSummary, type CronJobConfig, type HarnessOptions, type HarnessRunOutput, InMemoryConversationStore, InMemoryStateStore, LatitudeCapture, type LatitudeCaptureConfig, LocalMcpBridge, LocalUploadStore, type MainMemory, type McpConfig, type MemoryConfig, type MemoryStore, type MessagingChannelConfig, type ModelProviderFactory, PONCHO_UPLOAD_SCHEME, type ParsedAgent, type PonchoConfig, type ProviderConfig, type RemoteMcpServerConfig, type RuntimeRenderContext, S3UploadStore, STORAGE_SCHEMA_VERSION, type SkillContextEntry, type SkillMetadata, type StateConfig, type StateProviderName, type StateStore, type StorageConfig, type SubagentManager, type SubagentResult, type SubagentSummary, type TelemetryConfig, TelemetryEmitter, type ToolAccess, type ToolCall, ToolDispatcher, type ToolExecutionResult, type UploadStore, type UploadsConfig, VercelBlobUploadStore, buildAgentDirectoryName, buildSkillContextWindow, compactMessages, createConversationStore, createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createMemoryStore, createMemoryTools, createModelProvider, createSkillTools, createStateStore, createSubagentTools, createUploadStore, createWriteTool, deriveUploadKey, ensureAgentIdentity, estimateTokens, estimateTotalTokens, findSafeSplitPoint, generateAgentId, getAgentStoreDirectory, getModelContextWindow, getPonchoStoreRoot, jsonSchemaToZod, loadPonchoConfig, loadSkillContext, loadSkillInstructions, loadSkillMetadata, normalizeScriptPolicyPath, parseAgentFile, parseAgentMarkdown, ponchoDocsTool, readSkillResource, renderAgentPrompt, resolveAgentIdentity, resolveCompactionConfig, resolveMemoryConfig, resolveSkillDirs, resolveStateConfig, slugifyStorageComponent };
+export { type AgentFrontmatter, AgentHarness, type AgentIdentity, type AgentLimitsConfig, type AgentModelConfig, type BuiltInToolToggles, type CompactMessagesOptions, type CompactResult, type CompactionConfig, type Conversation, type ConversationState, type ConversationStore, type ConversationSummary, type CronJobConfig, type HarnessOptions, type HarnessRunOutput, InMemoryConversationStore, InMemoryStateStore, LatitudeCapture, type LatitudeCaptureConfig, LocalMcpBridge, LocalUploadStore, type MainMemory, type McpConfig, type MemoryConfig, type MemoryStore, type MessagingChannelConfig, type ModelProviderFactory, PONCHO_UPLOAD_SCHEME, type ParsedAgent, type PonchoConfig, type ProviderConfig, type RemoteMcpServerConfig, type RuntimeRenderContext, S3UploadStore, STORAGE_SCHEMA_VERSION, type SkillContextEntry, type SkillMetadata, type StateConfig, type StateProviderName, type StateStore, type StorageConfig, type SubagentManager, type SubagentResult, type SubagentSummary, type TelemetryConfig, TelemetryEmitter, type ToolAccess, type ToolCall, ToolDispatcher, type ToolExecutionResult, type UploadStore, type UploadsConfig, VercelBlobUploadStore, buildAgentDirectoryName, buildSkillContextWindow, compactMessages, createConversationStore, createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createEditTool, createMemoryStore, createMemoryTools, createModelProvider, createSkillTools, createStateStore, createSubagentTools, createUploadStore, createWriteTool, deriveUploadKey, ensureAgentIdentity, estimateTokens, estimateTotalTokens, findSafeSplitPoint, generateAgentId, getAgentStoreDirectory, getModelContextWindow, getPonchoStoreRoot, jsonSchemaToZod, loadPonchoConfig, loadSkillContext, loadSkillInstructions, loadSkillMetadata, normalizeScriptPolicyPath, parseAgentFile, parseAgentMarkdown, ponchoDocsTool, readSkillResource, renderAgentPrompt, resolveAgentIdentity, resolveCompactionConfig, resolveMemoryConfig, resolveSkillDirs, resolveStateConfig, slugifyStorageComponent };

package/dist/index.js

@@ -112,10 +112,12 @@ var parseCronJobs = (value) => {
     if (timezone) {
       validateTimezone(timezone, path);
     }
+    const channel = typeof jobValue.channel === "string" && jobValue.channel.trim() ? jobValue.channel.trim() : void 0;
     jobs[jobName] = {
       schedule: jobValue.schedule.trim(),
       task: jobValue.task,
-      timezone
+      timezone,
+      channel
     };
   }
   return jobs;
@@ -1030,6 +1032,22 @@ messaging: [
 ]
 \`\`\`
 
+#### Proactive scheduled messages
+
+You can have the agent proactively message Telegram chats on a cron schedule. Add \`channel: telegram\` to any cron job in your \`AGENT.md\` frontmatter:
+
+\`\`\`yaml
+cron:
+  daily-checkin:
+    schedule: "0 9 * * *"
+    task: "Check in with the user about their plans for today"
+    channel: telegram
+\`\`\`
+
+The system auto-discovers all Telegram chats the bot has interacted with and sends the agent's response to each one. No chat IDs need to be configured -- filtering is handled by \`allowedUserIds\` if set. The agent runs with the full conversation history for each chat, so it has context from prior interactions.
+
+The bot must have received at least one message from a user before it can send proactive messages to that chat (Telegram API requirement).
+
 ### Email (Resend)
 
 #### 1. Set up Resend
@@ -1890,6 +1908,52 @@ var createWriteTool = (workingDir) => defineTool({
     return { path, written: true };
   }
 });
+var createEditTool = (workingDir) => 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 readFile3(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 writeFile2(resolved, newContent, "utf8");
+    return { path, edited: true };
+  }
+});
 var createDeleteTool = (workingDir) => defineTool({
   name: "delete_file",
   description: "Delete a file at a path inside the working directory",
@@ -4309,7 +4373,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
@@ -4365,6 +4429,10 @@ cron:
     schedule: "0 9 * * *"        # Standard 5-field cron expression
     timezone: "America/New_York" # Optional IANA timezone (default: UTC)
     task: "Generate the daily sales report"
+  telegram-checkin:
+    schedule: "0 18 * * 1-5"
+    channel: telegram              # Proactive message to all known Telegram chats
+    task: "Send an end-of-day summary to the user"
 \`\`\`
 
 - Each cron job triggers an autonomous agent run with the specified task, creating a fresh conversation.
@@ -4373,6 +4441,7 @@ cron:
 - Jobs can also be triggered manually: \`GET /api/cron/<jobName>\`.
 - To carry context across cron runs, enable memory.
 - **IMPORTANT**: When adding a new cron job, always PRESERVE all existing cron jobs. Never remove or overwrite existing jobs unless the user explicitly asks you to replace or delete them. Read the full current \`cron:\` block before editing, and append the new job alongside the existing ones.
+- **Proactive channel messaging**: Adding \`channel: telegram\` (or \`slack\`) makes the cron job send its response directly to all known conversations on that platform, instead of creating a standalone conversation. The agent continues the existing conversation history for context. A chat must have at least one prior user message for auto-discovery to find it.
 
 ## Messaging Integrations (Slack, Telegram, Email)
 
@@ -4565,6 +4634,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
@@ -4635,7 +4705,7 @@ var AgentHarness = class _AgentHarness {
   isToolEnabled(name) {
     const access3 = this.resolveToolAccess(name);
     if (access3 === 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;
@@ -4678,6 +4748,9 @@ var AgentHarness = 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));
     }
@@ -6350,7 +6423,8 @@ var InMemoryConversationStore = class {
       ownerId: c.ownerId,
       parentConversationId: c.parentConversationId,
       messageCount: c.messages.length,
-      hasPendingApprovals: Array.isArray(c.pendingApprovals) && c.pendingApprovals.length > 0
+      hasPendingApprovals: Array.isArray(c.pendingApprovals) && c.pendingApprovals.length > 0,
+      channelMeta: c.channelMeta
     }));
   }
   async get(conversationId) {
@@ -6512,7 +6586,8 @@ var FileConversationStore = class {
         fileName,
         parentConversationId: conversation.parentConversationId,
         messageCount: conversation.messages.length,
-        hasPendingApprovals: Array.isArray(conversation.pendingApprovals) && conversation.pendingApprovals.length > 0
+        hasPendingApprovals: Array.isArray(conversation.pendingApprovals) && conversation.pendingApprovals.length > 0,
+        channelMeta: conversation.channelMeta
       });
       await this.writeIndex();
     });
@@ -6540,7 +6615,8 @@ var FileConversationStore = class {
       ownerId: c.ownerId,
       parentConversationId: c.parentConversationId,
       messageCount: c.messageCount,
-      hasPendingApprovals: c.hasPendingApprovals
+      hasPendingApprovals: c.hasPendingApprovals,
+      channelMeta: c.channelMeta
     }));
   }
   async get(conversationId) {
@@ -6806,7 +6882,8 @@ var KeyValueConversationStoreBase = class {
             ownerId: meta.ownerId,
             parentConversationId: meta.parentConversationId,
             messageCount: meta.messageCount,
-            hasPendingApprovals: meta.hasPendingApprovals
+            hasPendingApprovals: meta.hasPendingApprovals,
+            channelMeta: meta.channelMeta
           });
         }
       } catch {
@@ -6867,7 +6944,8 @@ var KeyValueConversationStoreBase = class {
         ownerId: nextConversation.ownerId,
         parentConversationId: nextConversation.parentConversationId,
         messageCount: nextConversation.messages.length,
-        hasPendingApprovals: Array.isArray(nextConversation.pendingApprovals) && nextConversation.pendingApprovals.length > 0
+        hasPendingApprovals: Array.isArray(nextConversation.pendingApprovals) && nextConversation.pendingApprovals.length > 0,
+        channelMeta: nextConversation.channelMeta
       }),
       this.ttl
     );
@@ -7384,6 +7462,7 @@ export {
   createDefaultTools,
   createDeleteDirectoryTool,
   createDeleteTool,
+  createEditTool,
   createMemoryStore,
   createMemoryTools,
   createModelProvider,

package/package.json

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

package/src/agent-parser.ts

@@ -27,6 +27,7 @@ export interface CronJobConfig {
   schedule: string;
   task: string;
   timezone?: string;
+  channel?: string;
 }
 
 export interface AgentFrontmatter {
@@ -138,10 +139,16 @@ const parseCronJobs = (
       validateTimezone(timezone, path);
     }
 
+    const channel =
+      typeof jobValue.channel === "string" && jobValue.channel.trim()
+        ? jobValue.channel.trim()
+        : undefined;
+
     jobs[jobName] = {
       schedule: jobValue.schedule.trim(),
       task: jobValue.task,
       timezone,
+      channel,
     };
   }
   return jobs;

package/src/config.ts

@@ -39,6 +39,7 @@ export type BuiltInToolToggles = {
   list_directory?: boolean;
   read_file?: boolean;
   write_file?: boolean;
+  edit_file?: boolean;
   delete_file?: boolean;
   delete_directory?: boolean;
 };

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

@@ -15,7 +15,7 @@ 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 { 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 +224,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
@@ -280,6 +280,10 @@ cron:
     schedule: "0 9 * * *"        # Standard 5-field cron expression
     timezone: "America/New_York" # Optional IANA timezone (default: UTC)
     task: "Generate the daily sales report"
+  telegram-checkin:
+    schedule: "0 18 * * 1-5"
+    channel: telegram              # Proactive message to all known Telegram chats
+    task: "Send an end-of-day summary to the user"
 \`\`\`
 
 - Each cron job triggers an autonomous agent run with the specified task, creating a fresh conversation.
@@ -288,6 +292,7 @@ cron:
 - Jobs can also be triggered manually: \`GET /api/cron/<jobName>\`.
 - To carry context across cron runs, enable memory.
 - **IMPORTANT**: When adding a new cron job, always PRESERVE all existing cron jobs. Never remove or overwrite existing jobs unless the user explicitly asks you to replace or delete them. Read the full current \`cron:\` block before editing, and append the new job alongside the existing ones.
+- **Proactive channel messaging**: Adding \`channel: telegram\` (or \`slack\`) makes the cron job send its response directly to all known conversations on that platform, instead of creating a standalone conversation. The agent continues the existing conversation history for context. A chat must have at least one prior user message for auto-discovery to find it.
 
 ## Messaging Integrations (Slack, Telegram, Email)
 
@@ -480,6 +485,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
@@ -580,7 +586,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;
@@ -628,6 +634,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));
     }

package/src/state.ts

@@ -50,6 +50,11 @@ export interface Conversation {
     result?: import("@poncho-ai/sdk").RunResult;
     error?: import("@poncho-ai/sdk").AgentFailure;
   };
+  channelMeta?: {
+    platform: string;
+    channelId: string;
+    platformThreadId: string;
+  };
   createdAt: number;
   updatedAt: number;
 }
@@ -247,6 +252,7 @@ export class InMemoryConversationStore implements ConversationStore {
         parentConversationId: c.parentConversationId,
         messageCount: c.messages.length,
         hasPendingApprovals: Array.isArray(c.pendingApprovals) && c.pendingApprovals.length > 0,
+        channelMeta: c.channelMeta,
       }));
   }
 
@@ -305,6 +311,11 @@ export type ConversationSummary = {
   parentConversationId?: string;
   messageCount?: number;
   hasPendingApprovals?: boolean;
+  channelMeta?: {
+    platform: string;
+    channelId: string;
+    platformThreadId: string;
+  };
 };
 
 type ConversationStoreFile = {
@@ -319,6 +330,11 @@ type ConversationStoreFile = {
     parentConversationId?: string;
     messageCount?: number;
     hasPendingApprovals?: boolean;
+    channelMeta?: {
+      platform: string;
+      channelId: string;
+      platformThreadId: string;
+    };
   }>;
 };
 
@@ -451,6 +467,7 @@ class FileConversationStore implements ConversationStore {
         parentConversationId: conversation.parentConversationId,
         messageCount: conversation.messages.length,
         hasPendingApprovals: Array.isArray(conversation.pendingApprovals) && conversation.pendingApprovals.length > 0,
+        channelMeta: conversation.channelMeta,
       });
       await this.writeIndex();
     });
@@ -486,6 +503,7 @@ class FileConversationStore implements ConversationStore {
         parentConversationId: c.parentConversationId,
         messageCount: c.messageCount,
         hasPendingApprovals: c.hasPendingApprovals,
+        channelMeta: c.channelMeta,
       }));
   }
 
@@ -660,6 +678,11 @@ type ConversationMeta = {
   parentConversationId?: string;
   messageCount?: number;
   hasPendingApprovals?: boolean;
+  channelMeta?: {
+    platform: string;
+    channelId: string;
+    platformThreadId: string;
+  };
 };
 
 abstract class KeyValueConversationStoreBase implements ConversationStore {
@@ -804,6 +827,7 @@ abstract class KeyValueConversationStoreBase implements ConversationStore {
             parentConversationId: meta.parentConversationId,
             messageCount: meta.messageCount,
             hasPendingApprovals: meta.hasPendingApprovals,
+            channelMeta: meta.channelMeta,
           });
         }
       } catch { /* skip invalid records */ }
@@ -867,6 +891,7 @@ abstract class KeyValueConversationStoreBase implements ConversationStore {
         parentConversationId: nextConversation.parentConversationId,
         messageCount: nextConversation.messages.length,
         hasPendingApprovals: Array.isArray(nextConversation.pendingApprovals) && nextConversation.pendingApprovals.length > 0,
+        channelMeta: nextConversation.channelMeta,
       } satisfies ConversationMeta),
       this.ttl,
     );

package/test/harness.test.ts

@@ -1,10 +1,11 @@
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { createServer } from "node:http";
 import { tmpdir } from "node:os";
 import { join } from "path";
 import { describe, expect, it } from "vitest";
 import type { ToolContext } from "@poncho-ai/sdk";
 import { AgentHarness } from "../src/harness.js";
+import { createEditTool } from "../src/default-tools.js";
 import { loadSkillMetadata } from "../src/skill-context.js";
 
 const stubContext: ToolContext = {
@@ -39,6 +40,7 @@ model:
     expect(names).toContain("list_directory");
     expect(names).toContain("read_file");
     expect(names).toContain("write_file");
+    expect(names).toContain("edit_file");
   });
 
   it("disables write_file by default in production environment", async () => {
@@ -64,6 +66,7 @@ model:
     expect(names).toContain("list_directory");
     expect(names).toContain("read_file");
     expect(names).not.toContain("write_file");
+    expect(names).not.toContain("edit_file");
   });
 
   it("allows disabling built-in tools via poncho.config.js", async () => {
@@ -1230,3 +1233,63 @@ allowed-tools:
   });
 
 });
+
+describe("edit_file tool", () => {
+  it("replaces a unique string match in a file", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "poncho-edit-tool-"));
+    const filePath = join(dir, "test.txt");
+    await writeFile(filePath, "hello world\nfoo bar\nbaz qux\n", "utf8");
+
+    const tool = createEditTool(dir);
+    const result = await tool.handler(
+      { path: "test.txt", old_str: "foo bar", new_str: "replaced" },
+      stubContext,
+    );
+
+    expect(result).toEqual({ path: "test.txt", edited: true });
+    const content = await readFile(filePath, "utf8");
+    expect(content).toBe("hello world\nreplaced\nbaz qux\n");
+  });
+
+  it("errors when old_str is not found in the file", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "poncho-edit-tool-notfound-"));
+    await writeFile(join(dir, "test.txt"), "hello world\n", "utf8");
+
+    const tool = createEditTool(dir);
+    await expect(
+      tool.handler({ path: "test.txt", old_str: "nonexistent", new_str: "x" }, stubContext),
+    ).rejects.toThrow("old_str not found in file");
+  });
+
+  it("errors when old_str matches multiple locations", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "poncho-edit-tool-multi-"));
+    await writeFile(join(dir, "test.txt"), "aaa\nbbb\naaa\n", "utf8");
+
+    const tool = createEditTool(dir);
+    await expect(
+      tool.handler({ path: "test.txt", old_str: "aaa", new_str: "ccc" }, stubContext),
+    ).rejects.toThrow("old_str appears multiple times");
+  });
+
+  it("deletes matched content when new_str is empty", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "poncho-edit-tool-delete-"));
+    const filePath = join(dir, "test.txt");
+    await writeFile(filePath, "keep this\nremove this\nkeep this too\n", "utf8");
+
+    const tool = createEditTool(dir);
+    await tool.handler({ path: "test.txt", old_str: "remove this\n", new_str: "" }, stubContext);
+
+    const content = await readFile(filePath, "utf8");
+    expect(content).toBe("keep this\nkeep this too\n");
+  });
+
+  it("errors when old_str is empty", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "poncho-edit-tool-empty-"));
+    await writeFile(join(dir, "test.txt"), "content\n", "utf8");
+
+    const tool = createEditTool(dir);
+    await expect(
+      tool.handler({ path: "test.txt", old_str: "", new_str: "x" }, stubContext),
+    ).rejects.toThrow("old_str must not be empty");
+  });
+});