@tyvm/knowhow 0.0.159 → 0.0.160

package/tests/patching/fixtures/transcript-mangles/agent-sync-fs-nested-catch.json

@@ -1,9 +0,0 @@
-{
-  "taskId": "1785613689-for-the-usage-tracking-write-the-full-agent-thread",
-  "sourceBefore": "/**\n * Agent Synchronization Service - Filesystem-based synchronization\n * Handles synchronization via filesystem files in .knowhow/processes/agents/taskId/\n */\nimport { BaseAgent } from \"../agents/base/base\";\nimport { promises as fs } from \"fs\";\nimport * as path from \"path\";\nimport { watch } from \"fs\";\n\nexport interface FsSyncOptions {\n  taskId: string;\n  prompt: string;\n  agentName?: string;\n  /** The taskId of the parent agent that spawned this task, if any. */\n  parentTaskId?: string;\n}\n\n/**\n * AgentSyncFs handles filesystem-based synchronization for agent tasks\n * Creates files in .knowhow/processes/agents/{taskId}/ for status and input\n */\nexport class AgentSyncFs {\n  /** Shared cleanup interval across all instances to avoid duplicate cleanup runs */\n  private static sharedCleanupInterval: NodeJS.Timeout | null = null;\n  private static sharedBasePath: string = \".knowhow/processes/agents\";\n  private static cleanupStarted: boolean = false;\n\n  private taskId: string | undefined;\n  private basePath: string = \".knowhow/processes/agents\";\n  private taskPath: string | undefined;\n  private eventHandlersSetup: boolean = false;\n  private watcher: ReturnType<typeof watch> | null = null;\n  private lastInputContent: string = \"\";\n  private finalizationPromise: Promise<void> | null = null;\n  private agent: BaseAgent | undefined;\n  private threadUpdateHandler: ((...args: any[]) => void) | undefined;\n  private doneHandler: ((...args: any[]) => void) | undefined;\n  private tokenUsageHandler: ((...args: any[]) => void) | undefined;\n  /**\n   * Tracks the most recent in-flight filesystem metadata update.\n   * The done handler awaits this before finalizing, preventing a race where\n   * the completion call writes before the last thread sync finishes.\n   */\n  private pendingThreadUpdatePromise: Promise<void> | null = null;\n\n  constructor() {\n    // Start cleanup process when created\n    AgentSyncFs.startSharedCleanupProcess();\n  }\n\n  /**\n   * Create filesystem sync for a task\n   */\n  async createTask(options: FsSyncOptions): Promise<string> {\n    this.taskId = options.taskId;\n    this.taskPath = path.join(this.basePath, this.taskId);\n\n    try {\n      // Create directory structure\n      await fs.mkdir(this.taskPath, { recursive: true });\n\n      // Create initial files\n      await this.writeStatus(\"running\");\n      await this.writeInput(\"\");\n      await this.writeMetadata({\n        taskId: this.taskId,\n        // Record the OS process id of this agent subprocess so orchestrating\n        // tools (e.g. waitForAgentCompleted) can detect a crashed-but-not-\n        // finalized task via process-liveness. This is the child's own pid,\n        // so it needs no coordination with the spawner and never touches\n        // execCommand's child processes.\n        pid: process.pid,\n        prompt: options.prompt,\n        agentName: options.agentName || \"unknown\",\n        ...(options.parentTaskId ? { parentTaskId: options.parentTaskId } : {}),\n        startTime: new Date().toISOString(),\n        status: \"running\",\n      });\n\n      console.log(`\u2705 Created filesystem sync at: ${this.taskPath}`);\n      return this.taskId;\n    } catch (error) {\n      console.error(`\u274c Failed to create filesystem sync:`, error);\n      throw error;\n    }\n  }\n\n  /**\n   * Update task status\n   */\n  private async writeStatus(status: string): Promise<void> {\n    if (!this.taskPath) return;\n\n    try {\n      const statusPath = path.join(this.taskPath, \"status.txt\");\n      await fs.writeFile(statusPath, status, \"utf8\");\n    } catch (error) {\n      console.error(`\u274c Failed to write status:`, error);\n    }\n  }\n\n  /**\n   * Write input file (used for initial state)\n   */\n  private async writeInput(content: string): Promise<void> {\n    if (!this.taskPath) return;\n\n    try {\n      const inputPath = path.join(this.taskPath, \"input.txt\");\n      await fs.writeFile(inputPath, content, \"utf8\");\n      this.lastInputContent = content;\n    } catch (error) {\n      console.error(`\u274c Failed to write input:`, error);\n    }\n  }\n\n  /**\n   * Write metadata file\n   */\n  private async writeMetadata(data: any): Promise<void> {\n    if (!this.taskPath) return;\n\n    try {\n      const metadataPath = path.join(this.taskPath, \"metadata.json\");\n      await fs.writeFile(metadataPath, JSON.stringify(data, null, 2), \"utf8\");\n    } catch (error) {\n      console.error(`\u274c Failed to write metadata:`, error);\n    }\n  }\n\n  /**\n   * Append a token usage entry (including the full message chain sent for\n   * that call) to usage.json. This is intended for debugging cache-hit\n   * issues, where comparing the message chains and usage values between\n   * consecutive calls can reveal when a cache prefix was invalidated.\n   */\n  private async appendUsageEntry(entry: any): Promise<void> {\n    if (!this.taskPath) return;\n\n    try {\n      const usagePath = path.join(this.taskPath, \"usage.json\");\n      let entries: any[] = [];\n\n      try {\n        const existingData = await fs.readFile(usagePath, \"utf8\");\n        entries = JSON.parse(existingData);\n      } catch {\n        // File doesn't exist or is invalid, start fresh\n      }\n\n      entries.push(entry);\n      await fs.writeFile(usagePath, JSON.stringify(entries, null, 2), \"utf8\");\n    } catch (error) {\n      console.error(`\u274c Failed to append usage entry:`, error);\n    }\n  }\n\n  /**\n   * Update metadata file with current agent state\n   */\n  private async updateMetadata(\n    agent: BaseAgent,\n    inProgress: boolean,\n    result?: string\n  ): Promise<void> {\n    if (!this.taskPath) return;\n\n    try {\n      const metadataPath = path.join(this.taskPath, \"metadata.json\");\n      let metadata: any = {};\n\n      try {\n        const existingData = await fs.readFile(metadataPath, \"utf8\");\n        metadata = JSON.parse(existingData);\n      } catch {\n        // File doesn't exist or is invalid, start fresh\n      }\n\n      metadata.threads = agent.getThreads();\n      metadata.totalCostUsd = agent.getTotalCostUsd();\n      metadata.tokenUsage = agent.getTokenUsage();\n      metadata.agentName = agent.name;\n      // Record the model/provider actually in use at this sync so task\n      // history reflects the real model (including mid-run fallbacks), not\n      // just the named agent.\n      metadata.model = agent.getModel();\n      metadata.provider = agent.getProvider();\n      // Persist reasoning settings so a resume can restore the exact\n      // reasoning effort / summarize behavior the run was using. (The\n      // encrypted reasoning items + summaries themselves ride along on the\n      // thread messages via `_reasoning_details` / `reasoning_summary`.)\n      metadata.reasoningEffort = agent.getReasoningEffort?.();\n      metadata.summarizeReasoning = agent.getSummarizeReasoning?.();\n      metadata.inProgress = inProgress;\n      metadata.lastUpdate = new Date().toISOString();\n\n      if (result !== undefined) {\n        metadata.result = result;\n        metadata.status = \"completed\";\n        await this.writeStatus(\"completed\");\n      }\n\n      await fs.writeFile(\n        metadataPath,\n        JSON.stringify(metadata, null, 2),\n        \"utf8\"\n      );\n    } catch (error) {\n      console.error(`\u274c Failed to update metadata:`, error);\n    }\n  }\n\n  /**\n   * Read and process status file changes\n   */\n  private async readStatus(): Promise<string | null> {\n    if (!this.taskPath) return null;\n\n    try {\n      const statusPath = path.join(this.taskPath, \"status.txt\");\n      const content = await fs.readFile(statusPath, \"utf8\");\n      return content.trim();\n    } catch (error) {\n      // File might not exist or be accessible\n      return null;\n    }\n  }\n\n  /**\n   * Read and process input file changes\n   */\n  private async readInput(): Promise<string | null> {\n    if (!this.taskPath) return null;\n\n    try {\n      const inputPath = path.join(this.taskPath, \"input.txt\");\n      const content = await fs.readFile(inputPath, \"utf8\");\n      return content;\n    } catch (error) {\n      // File might not exist or be accessible\n      return null;\n    }\n  }\n\n  /**\n   * Check for file changes and process them\n   */\n  private async checkForChanges(agent: BaseAgent): Promise<void> {\n    if (!this.taskPath) return;\n\n    try {\n      // Check status changes\n      const status = await this.readStatus();\n      if (status === \"paused\") {\n        console.log(`\u23f8\ufe0f Agent task ${this.taskId} paused via filesystem`);\n        await agent.pause();\n        await this.waitForResume(agent);\n      } else if (status === \"killed\") {\n        console.log(`\ud83d\uded1 Agent task ${this.taskId} killed via filesystem`);\n        await agent.kill();\n      }\n\n      // Check for new input/messages\n      const input = await this.readInput();\n      if (input && input !== this.lastInputContent && input.trim() !== \"\") {\n        console.log(\n          `\ud83d\udcec New message received via filesystem for task ${this.taskId}`\n        );\n        this.lastInputContent = input;\n\n        // Detect slash commands in the input\n        if (input.trim().startsWith(\"/\")) {\n          await this.handleInputCommand(agent, input.trim());\n        } else {\n          agent.addPendingUserMessage({\n            role: \"user\",\n            content: input,\n          });\n        }\n\n        // Clear the input file after processing\n        await this.writeInput(\"\");\n      }\n    } catch (error) {\n      console.error(`\u274c Error checking for changes:`, error);\n    }\n  }\n\n  /**\n   * Handle slash commands sent via input.txt\n   */\n  private async handleInputCommand(agent: BaseAgent, input: string): Promise<void> {\n    const [command, ...rest] = input.split(\" \");\n    const message = rest.join(\" \").trim() || undefined;\n\n    if (command === \"/poke\") {\n      console.log(`\ud83e\udef5 Received /poke command for task ${this.taskId}`);\n      agent.interrupt(message);\n    } else {\n      // Unknown command \u2014 treat as a regular message\n      console.warn(`\u26a0\ufe0f Unknown command \"${command}\", treating as message`);\n      agent.addPendingUserMessage({ role: \"user\", content: input });\n    }\n  }\n\n  /**\n   * Wait for resume by monitoring status file\n   */\n  private async waitForResume(agent: BaseAgent): Promise<void> {\n    const POLL_INTERVAL_MS = 2000;\n    const MAX_WAIT_MS = 60 * 60 * 1000; // 1 hour\n    const startTime = Date.now();\n\n    while (Date.now() - startTime < MAX_WAIT_MS) {\n      await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));\n\n      const status = await this.readStatus();\n\n      if (status === \"killed\") {\n        console.log(`\ud83d\uded1 Agent task ${this.taskId} killed while paused`);\n        await agent.kill();\n        return;\n      }\n\n      if (status === \"running\") {\n        console.log(`\u25b6\ufe0f Agent task ${this.taskId} resumed`);\n        await agent.unpause();\n        return;\n      }\n    }\n\n    console.warn(`\u26a0\ufe0f Timeout waiting for resume on task ${this.taskId}`);\n  }\n\n  /**\n   * Setup filesystem watching for the task\n   */\n  private setupFileWatcher(agent: BaseAgent): void {\n    if (!this.taskPath || this.watcher) return;\n\n    try {\n      this.watcher = watch(this.taskPath, async (eventType, filename) => {\n        if (filename === \"status.txt\" || filename === \"input.txt\") {\n          await this.checkForChanges(agent);\n        }\n      });\n\n      console.log(`\ud83d\udc41\ufe0f Watching filesystem at: ${this.taskPath}`);\n    } catch (error) {\n      console.error(`\u274c Failed to setup file watcher:`, error);\n    }\n  }\n\n  /**\n   * Set up event-based synchronization for an agent task\n   */\n  async setupAgentSync(agent: BaseAgent, taskId?: string): Promise<void> {\n    if (!taskId) return;\n\n    this.taskId = taskId;\n    this.taskPath = path.join(this.basePath, this.taskId);\n\n    // Ensure directory exists (might have been created by createTask)\n    try {\n      await fs.mkdir(this.taskPath, { recursive: true });\n    } catch (error) {\n      // Directory might already exist\n    }\n\n    if (!this.eventHandlersSetup) {\n      this.setupEventHandlers(agent);\n      this.setupFileWatcher(agent);\n      this.eventHandlersSetup = true;\n    }\n  }\n\n  /**\n   * Set up event handlers for automatic synchronization\n   */\n  private setupEventHandlers(agent: BaseAgent): void {\n    this.agent = agent;\n\n    // Listen to thread updates to sync state (store reference for cleanup)\n    this.threadUpdateHandler = async () => {\n      if (!this.taskId) return;\n\n      try {\n        // Track the pending update so the done handler can await it.\n        this.pendingThreadUpdatePromise = (async () => {\n          await this.updateMetadata(agent, true);\n          await this.checkForChanges(agent);\n        })();\n        await this.pendingThreadUpdatePromise;\n      } catch (error) {\n        console.error(`\u274c Error during threadUpdate sync:`, error);\n      }\n    };\n    agent.agentEvents.on(\n      agent.eventTypes.threadUpdate,\n      this.threadUpdateHandler\n    );\n\n    // Listen to token usage events to record per-call usage + message chain\n    // (store reference for cleanup). This is written to usage.json so that\n    // cache-hit/cache-miss issues can be debugged by comparing the message\n    // chain and usage values sent/received on consecutive AI calls.\n    this.tokenUsageHandler = (usage: any) => {\n      this.appendUsageEntry(usage).catch((error) => {\n        console.error(`\u274c Error recording token usage:`, error);\n      });\n    };\n    agent.agentEvents.on(\n      agent.eventTypes.tokenUsage,\n      this.tokenUsageHandler\n    );\n\n    // Listen to completion event to finalize task (store reference for cleanup)\n    this.doneHandler = (result: string) => {\n      if (!this.taskId) {\n        console.warn(`\u26a0\ufe0f [AgentSyncFs] Cannot finalize: taskId=${this.taskId}`);\n        return;\n      }\n\n      console.log(\n        `\ud83c\udfaf [AgentSyncFs] Done event received for task: ${this.taskId}`\n      );\n\n      // Store finalization promise so callers can await it (same pattern as AgentSyncKnowhowWeb)\n      this.finalizationPromise = (async () => {\n        try {\n          // Flush any in-flight thread update before finalizing.\n          // This prevents the race where a pending \"inProgress: true\" metadata write\n          // overwrites the finalization write.\n          if (this.pendingThreadUpdatePromise) {\n            console.log(\n              `\u23f3 [AgentSyncFs] Awaiting pending thread update before finalizing...`\n            );\n            await this.pendingThreadUpdatePromise.catch(() => {\n              // Ignore errors in pending update \u2014 we still want to finalize\n            });\n            this.pendingThreadUpdatePromise = null;\n          }\n\n          await this.updateMetadata(agent, false, result);\n          console.log(`\u2705 Completed filesystem sync for task: ${this.taskId}`);\n          await this.cleanup();\n        } catch (error) {\n          console.error(`\u274c Error finalizing task:`, error);\n          throw error;\n        }\n      })();\n    };\n    agent.agentEvents.on(agent.eventTypes.done, this.doneHandler);\n  }\n\n  /**\n   * Wait for finalization to complete (for CLI usage)\n   */\n  async waitForFinalization(): Promise<void> {\n    if (this.finalizationPromise) {\n      await this.finalizationPromise;\n    }\n  }\n\n  /**\n   * Cleanup task directory and watcher\n   */\n  async cleanup(): Promise<void> {\n    if (this.watcher) {\n      this.watcher.close();\n      this.watcher = null;\n    }\n\n    // Note: We don't delete the directory here to preserve task history\n    // The cleanup process will handle old directories\n  }\n\n  /**\n   * Clean up old task directories (older than 3 days)\n   */\n  private static async cleanupOldTasks(): Promise<void> {\n    try {\n      const agentsPath = AgentSyncFs.sharedBasePath;\n\n      // Check if directory exists\n      try {\n        await fs.access(agentsPath);\n      } catch {\n        // Directory doesn't exist, nothing to clean\n        return;\n      }\n\n      const entries = await fs.readdir(agentsPath, { withFileTypes: true });\n      const now = Date.now();\n      const threeDaysMs = 3 * 24 * 60 * 60 * 1000;\n\n      for (const entry of entries) {\n        if (!entry.isDirectory()) continue;\n\n        const taskPath = path.join(agentsPath, entry.name);\n\n        try {\n          const stats = await fs.stat(taskPath);\n          const age = now - stats.mtimeMs;\n\n          if (age > threeDaysMs) {\n            console.log(`\ud83e\uddf9 Cleaning up old task directory: ${entry.name}`);\n            await fs.rm(taskPath, { recursive: true, force: true });\n          }\n        } catch (error) {\n          // Skip if we can't stat or delete\n          console.error(`\u274c Error cleaning up ${entry.name}:`, error);\n        }\n      }\n\n      // Also clean up old execCommand background log files in .knowhow/processes/*.txt\n      await AgentSyncFs.cleanupOldProcessLogs(threeDaysMs);\n    } catch (error) {\n      console.error(`\u274c Error during cleanup:`, error);\n    }\n  }\n\n  /**\n   * Clean up old execCommand background log files (.knowhow/processes/*.txt).\n   * These are created by the execCommand tool when running background/long-lived\n   * commands, and are never cleaned up otherwise.\n   */\n  private static async cleanupOldProcessLogs(maxAgeMs: number): Promise<void> {\n    try {\n      // execCommand writes logs to the parent of the agents dir: .knowhow/processes\n      const processesPath = path.dirname(AgentSyncFs.sharedBasePath);\n\n      try {\n        await fs.access(processesPath);\n      } catch {\n        return;\n      }\n\n      const entries = await fs.readdir(processesPath, { withFileTypes: true });\n      const now = Date.now();\n\n      for (const entry of entries) {\n        // Only target the .txt log files that execCommand creates; leave the\n        // agents/ directory (and any other subdirectories) alone.\n        if (!entry.isFile() || !entry.name.endsWith(\".txt\")) continue;\n\n        const logPath = path.join(processesPath, entry.name);\n\n        try {\n          const stats = await fs.stat(logPath);\n          const age = now - stats.mtimeMs;\n\n          if (age > maxAgeMs) {\n            console.log(`\ud83e\uddf9 Cleaning up old process log file: ${entry.name}`);\n            await fs.rm(logPath, { force: true });\n          }\n        } catch (error) {\n          // Skip if we can't stat or delete\n          console.error(`\u274c Error cleaning up log ${entry.name}:`, error);\n        }\n      }\n    } catch (error) {\n      console.error(`\u274c Error during process log cleanup:`, error);\n    }\n  }\n\n  /**\n   * Start periodic cleanup process\n   */\n  private static startSharedCleanupProcess(): void {\n    if (AgentSyncFs.cleanupStarted) return;\n    AgentSyncFs.cleanupStarted = true;\n\n    // Run cleanup every hour (shared across all instances)\n    AgentSyncFs.sharedCleanupInterval = setInterval(() => {\n      AgentSyncFs.cleanupOldTasks();\n    }, 60 * 60 * 1000);\n\n    // Also run once on startup\n    AgentSyncFs.cleanupOldTasks();\n  }\n\n  /**\n   * Stop cleanup process\n   */\n  stopCleanup(): void {\n    if (AgentSyncFs.sharedCleanupInterval) {\n      clearInterval(AgentSyncFs.sharedCleanupInterval);\n      AgentSyncFs.sharedCleanupInterval = null;\n      AgentSyncFs.cleanupStarted = false;\n    }\n  }\n\n  /**\n   * Reset synchronization state\n   */\n  reset(): void {\n    // Remove old event listeners from the agent before resetting\n    if (this.agent) {\n      if (this.threadUpdateHandler) {\n        this.agent.agentEvents.removeListener(\n          this.agent.eventTypes.threadUpdate,\n          this.threadUpdateHandler\n        );\n        this.threadUpdateHandler = undefined;\n      }\n      if (this.tokenUsageHandler) {\n        this.agent.agentEvents.removeListener(\n          this.agent.eventTypes.tokenUsage,\n          this.tokenUsageHandler\n        );\n        this.tokenUsageHandler = undefined;\n      }\n      if (this.doneHandler) {\n        this.agent.agentEvents.removeListener(\n          this.agent.eventTypes.done,\n          this.doneHandler\n        );\n        this.doneHandler = undefined;\n      }\n      this.agent = undefined;\n    }\n    this.cleanup();\n    this.taskId = undefined;\n    this.taskPath = undefined;\n    this.eventHandlersSetup = false;\n    this.lastInputContent = \"\";\n    this.finalizationPromise = null;\n    this.pendingThreadUpdatePromise = null;\n  }\n}\n",
-  "patch": "@@ -131,7 +131,7 @@\n   /**\n    * Append a token usage entry (including the full message chain sent for\n    * that call) to usage.json. This is intended for debugging cache-hit\n-   * issues, where comparing the message chains and usage values between\n+   * issues, where comparing the message chains and usage values between\n    * consecutive calls can reveal when a cache prefix was invalidated.\n+   *\n+   * To prevent exponential file growth, if the new entry's message thread\n+   * fully contains the previous entry's thread as a prefix, the previous\n+   * thread is replaced with { PREV_CACHE_HIT: true } so only the new\n+   * messages (the delta) are stored alongside the new usage data.\n    */\n   private async appendUsageEntry(entry: any): Promise<void> {\n     if (!this.taskPath) return;\n@@ -143,7 +143,26 @@\n       try {\n         const existingData = await fs.readFile(usagePath, \"utf8\");\n         entries = JSON.parse(existingData);\n       } catch {\n         // File doesn't exist or is invalid, start fresh\n       }\n \n-      entries.push(entry);\n+      // If the new entry's messages are a superset of the last entry's\n+      // messages (i.e. the last thread is a prefix of the new thread),\n+      // collapse the last entry's messages to { PREV_CACHE_HIT: true }\n+      // and store only the new delta \u2014 preventing exponential growth.\n+      if (entries.length > 0) {\n+        const lastEntry = entries[entries.length - 1];\n+        const prevMessages: any[] = lastEntry?.messages;\n+        const newMessages: any[] = entry?.messages;\n+        if (\n+          Array.isArray(prevMessages) &&\n+          Array.isArray(newMessages) &&\n+          prevMessages.length > 0 &&\n+          newMessages.length >= prevMessages.length &&\n+          JSON.stringify(newMessages.slice(0, prevMessages.length)) ===\n+            JSON.stringify(prevMessages)\n+        ) {\n+          // Replace the previous full thread with a compact sentinel\n+          lastEntry.messages = [{ PREV_CACHE_HIT: true }];\n+        }\n+      }\n+\n+      entries.push(entry);\n       await fs.writeFile(usagePath, JSON.stringify(entries, null, 2), \"utf8\");\n     } catch (error) {\n       console.error(`\u274c Failed to append usage entry:`, error);\n",
-  "observedAfter": "131:   /**\n132:    * Append a token usage entry (including the full message chain sent for\n133:    * that call) to usage.json. This is intended for debugging cache-hit\n134:    * issues, where comparing the message chains and usage values between\n135:    * consecutive calls can reveal when a cache prefix was invalidated.\n136:    *\n137:    * To prevent exponential file growth, if the new entry's message thread\n138:    * fully contains the previous entry's thread as a prefix, the previous\n139:    * thread is replaced with { PREV_CACHE_HIT: true } so only the new\n140:    * messages (the delta) are stored alongside the new usage data.\n141:    */\n142:   private async appendUsageEntry(entry: any): Promise<void> {\n143:     if (!this.taskPath) return;\n144: \n145:     try {\n146:       const usagePath = path.join(this.taskPath, \"usage.json\");\n147:       let entries: any[] = [];\n148: \n149:       try {\n150:         const existingData = await fs.readFile(usagePath, \"utf8\");\n151:       // If the new entry's messages are a superset of the last entry's\n152:       // messages (i.e. the last thread is a prefix of the new thread),\n153:       // collapse the last entry's messages to { PREV_CACHE_HIT: true }\n154:       // and store only the new delta \u2014 preventing exponential growth.\n155:       if (entries.length > 0) {\n156:         const lastEntry = entries[entries.length - 1];\n157:         const prevMessages: any[] = lastEntry?.messages;\n158:         const newMessages: any[] = entry?.messages;\n159:         if (\n160:           Array.isArray(prevMessages) &&\n161:           Array.isArray(newMessages) &&\n162:           prevMessages.length > 0 &&\n163:           newMessages.length >= prevMessages.length &&\n164:           JSON.stringify(newMessages.slice(0, prevMessages.length)) ===\n165:             JSON.stringify(prevMessages)\n166:         ) {\n167:           // Replace the previous full thread with a compact sentinel\n168:           lastEntry.messages = [{ PREV_CACHE_HIT: true }];\n169:         }\n170:       }\n171: \n172:       entries.push(entry);\n173:       } catch {\n174:         // File doesn't exist or is invalid, start fresh\n175:       }\n176: \n177:       entries.push(entry);\n178:       await fs.writeFile(usagePath, JSON.stringify(entries, null, 2), \"utf8\");\n179:     } catch (error) {\n180:       console.error(`\u274c Failed to append usage entry:`, error);\n181:     }\n182:   }\n183: \n184:   /**\n185:    * Update metadata file with current agent state",
-  "agentStatement": "The patch got mangled \u2014 the code is nested incorrectly. Let me rewrite the method cleanly:",
-  "sourceRevision": "b0634f8^",
-  "sourcePath": "packages/knowhow/src/services/AgentSyncFs.ts"
-}

package/tests/patching/fixtures/transcript-mangles/automation-functions-crossed.json

@@ -1,9 +0,0 @@
-{
-  "taskId": "1785594693-okay-just-tried-the-computer-use-agent-play-game",
-  "sourceBefore": "import * as fs from \"fs\";\nimport * as path from \"path\";\nimport {\n  AccessibilityElement,\n  AccessibilityOptions,\n  Point,\n  Region,\n} from \"@tyvm/knowhow\";\nimport {\n  ComputerService,\n  ColorRegion,\n  DesktopBox,\n  DesktopShape,\n  OcrResult,\n  ReadTextOptions,\n} from \"./ComputerService\";\nimport { resolveRegionAsync } from \"./regions\";\n\n/**\n * Automations \u2014 a locally-run perception\u2192action loop that the LLM authors once\n * (after watching a game/UI) and then launches with a single tool call. The LLM\n * (the slow, smart \"coach\") stays OUT of the per-frame loop; the automation (the\n * fast, dumb \"actor\") runs entirely in-process at a tight interval with no model\n * round-trip per target, which is the only way to beat the ~1s human bar.\n *\n * Design (see .knowhow/tasks/computer-use-improvements/implementation-plan.md):\n *  - The automation is a .ts async function body with access to a small `sdk`.\n *  - It can call `await sdk.requiredWindow(...)`; if OS focus leaves that window\n *    the runner auto-pauses (action methods become no-ops), so a human\n *    interrupts any automation just by clicking away / Cmd-Tabbing out.\n *  - It supports `dryRun`, where action methods RECORD intent instead of moving\n *    the real mouse \u2014 this powers offline testAutomation against a recording.\n */\n\nconst STORE_DIR = path.join(\".knowhow\", \"automations\");\n\n/**\n * Hard ceiling on how long ANY automation may run before it is force-stopped.\n * Automations take over the real mouse/keyboard, so a human needs to be able to\n * reliably reclaim control quickly. We cap every run at 10s (regardless of what\n * the caller requests) so a runaway automation can never hold the mouse hostage\n * for longer than that. Re-launch the automation if you legitimately need more time.\n */\nexport const MAX_AUTOMATION_DURATION_MS = 30000;\n\n/** Default run duration when the caller doesn't specify one. */\nexport const DEFAULT_AUTOMATION_DURATION_MS = 30000;\n\nexport interface WindowMatch {\n  /** Substring (case-insensitive) that must appear in the active window title. */\n  titleIncludes?: string;\n  /** Substring (case-insensitive) that must appear in the active window app. */\n  app?: string;\n}\n\nexport interface AutomationSpec {\n  name: string;\n  /** Async function body. Receives (sdk). May `await` sdk.* calls. */\n  script: string;\n  /** Parsed structured header (see parseAutomationDoc) describing when to use it. */\n  doc?: AutomationDoc;\n  /** Absolute path to the saved .ts file (populated by loaders). */\n  filePath?: string;\n}\n\n/**\n * Structured \"skill card\" for an automation, parsed from a JSDoc-style header\n * comment at the very top of the script. This is what makes an automation\n * DISCOVERABLE: it tells a future agent what the automation does, WHEN to reach\n * for it, what the screen must look like before it runs, and what it leaves\n * behind afterward \u2014 so the agent can pick the right automation without reading\n * (or guessing at) the whole implementation.\n */\nexport interface AutomationDoc {\n  description?: string;\n  useWhen?: string;\n  startState?: string;\n  endState?: string;\n  window?: string;\n  notes?: string;\n}\n\nexport interface AutomationAction {\n  t: number;\n  kind:\n    | \"clickAt\"\n    | \"moveMouse\"\n    | \"type\"\n    | \"key\"\n    | \"hotkey\"\n    | \"focus\"\n    | \"selectAccessibilityOption\"\n    | \"setAccessibilityValue\"\n    | \"performAccessibilityAction\";\n  x?: number;\n  y?: number;\n  button?: string;\n  text?: string;\n  /** True when the runner suppressed this action (paused / dry-run). */\n  suppressed?: boolean;\n}\n\nexport interface AutomationLogEntry {\n  t: number;\n  data: any;\n}\n\nexport interface AutomationRunResult {\n  name: string;\n  elapsedMs: number;\n  stopped: \"duration\" | \"manual\" | \"completed\" | \"error\";\n  error?: string;\n  actions: AutomationAction[];\n  actionCount: number;\n  logs: AutomationLogEntry[];\n  pausedMs: number;\n  dryRun: boolean;\n  /** The window gate that was in effect (if any) \u2014 the focus-loss auto-pause. */\n  requiredWindow?: WindowMatch;\n  /**\n   * True when a LIVE run performed real actions without ever configuring a\n   * required-window gate. Such a run can't be reclaimed by clicking away, so\n   * callers should treat this as a warning.\n   */\n  ranWithoutWindowGate?: boolean;\n}\n\nexport interface AutomationControl {\n  paused: boolean;\n  stopped: boolean;\n  requiredWindow?: WindowMatch;\n  stop(): void;\n}\n\n/**\n * The surface handed to an authored automation script. Perception methods read\n * real rendered pixels; action methods drive the real mouse/keyboard (unless\n * paused or in dry-run). Everything is in ABSOLUTE DESKTOP coordinates.\n */\nexport interface AutomationSDK {\n  // \u2500\u2500 perception (real pixels) \u2500\u2500\n  screenSize(): Promise<{ width: number; height: number }>;\n  /** Return the currently focused window, if one can be identified. */\n  activeWindow(): Promise<{ title: string; app?: string; bounds?: Region } | null>;\n  /**\n   * Inspect the focused window's native accessibility tree. Element IDs are\n   * short-lived: discover and use an element before requesting another tree.\n   */\n  accessibilityTrusted(): Promise<boolean>;\n  accessibilityElements(opts?: AccessibilityOptions): Promise<AccessibilityElement[]>;\n  findColor(\n    colors: string | string[],\n    opts?: {\n      region?: Region | string;\n      tolerance?: number;\n      minPixels?: number;\n      minSize?: number;\n      maxSize?: number;\n    }\n  ): Promise<ColorRegion[]>;\n  findShape(opts: {\n    kind: \"line-h\" | \"line-v\" | \"rect\" | \"square\" | \"circle\" | \"blob\";\n    color?: string;\n    region?: Region | string;\n    tolerance?: number;\n    minSize?: number;\n    maxSize?: number;\n    length?: number;\n    thickness?: number;\n  }): Promise<DesktopShape[]>;\n  findBoxes(opts?: {\n    region?: Region | string;\n    minSize?: number;\n    maxSize?: number;\n    minEdgeScore?: number;\n    maxBoxes?: number;\n  }): Promise<DesktopBox[]>;\n  /**\n   * Detect UI element regions by color segmentation, returned as a nested\n   * containment hierarchy in ABSOLUTE DESKTOP coords (each box: bounds, center,\n   * area, depth, children). Useful for \"find the clickable things in the play\n   * area\" without knowing their exact color:\n   *  - mode \"panels\" (default here): find large flat BACKGROUND surfaces and\n   *    group the FOREGROUND content on each into element boxes (score readouts,\n   *    button rows) \u2014 i.e. things that AREN'T the background color.\n   *  - mode \"colors\": one box per contiguous same-color area, nested.\n   *  - mode \"foreground\": everything differing from the dominant background.\n   * Pass a region to constrain the search (e.g. the playfield) so you only get\n   * targets inside the game area.\n   */\n  findRegions(opts?: {\n    region?: Region | string;\n    mode?: \"foreground\" | \"colors\" | \"panels\";\n    minSize?: number;\n    colorBits?: number;\n    clusterGap?: number;\n    minPixels?: number;\n    maxBoxes?: number;\n  }): Promise<DesktopBox[]>;\n  pixelColor(x: number, y: number): Promise<string>;\n\n  // \u2500\u2500 action (no-op while paused; recorded in dry-run) \u2500\u2500\n  clickAt(x: number, y: number, button?: \"left\" | \"right\" | \"middle\"): Promise<void>;\n  moveMouse(x: number, y: number): Promise<void>;\n  type(text: string): Promise<void>;\n  key(name: string): Promise<void>;\n  /** Press a key chord, e.g. `[\"command\", \"a\"]`. */\n  hotkey(keys: string[]): Promise<void>;\n  /** Focus an app/window. Call before installing requiredWindow. */\n  focus(match: string): Promise<boolean>;\n  /** Select a pop-up/combo-box option without keyboard type-ahead. */\n  selectAccessibilityOption(id: string, option: string): Promise<void>;\n  /** Set a settable accessibility element value using a fresh discovered ID. */\n  setAccessibilityValue(id: string, value: string): Promise<void>;\n  /** Perform an allowlisted AX action (for example AXPress or AXShowMenu). */\n  performAccessibilityAction(id: string, action: string): Promise<void>;\n\n  // \u2500\u2500 control / telemetry \u2500\u2500\n  sleep(ms: number): Promise<void>;\n  now(): number;\n  elapsed(): number;\n  log(data: any): void;\n  /**\n   * Run this callback repeatedly on a fixed interval (in MILLISECONDS, like\n   * setInterval) until the run is stopped (or the max duration cap is\n   * reached). The interval is measured between iteration starts; if a callback\n   * overruns its interval it simply runs again immediately (after a yield).\n   * Pass `intervalMs` of 0 to run as fast as possible. Optionally pass\n   * `{ requiredWindow }` to gate the loop on a focused window in one call \u2014\n   * equivalent to awaiting sdk.requiredWindow(match) first, so actions auto-\n   * pause the moment focus leaves that window (the primary way a human reclaims\n   * the mouse mid-run).\n   */\n  runEvery(\n    callback: () => void | Promise<void>,\n    intervalMs: number,\n    opts?: { requiredWindow?: WindowMatch }\n  ): Promise<void>;\n  /** Set/clear the focus gate. Await before performing actions. */\n  requiredWindow(match?: WindowMatch): Promise<void>;\n  /**\n   * Read text from the screen (or a named/explicit region) using macOS Vision\n   * OCR. Returns recognized text regions in ABSOLUTE DESKTOP coordinates,\n   * sorted top-to-bottom then left-to-right.\n   * Each result: { text, confidence, bounds, center }\n   * bounds/center are desktop coords ready for clickAt().\n   * Pass a region to restrict OCR to part of the screen \u2014 faster, less noise.\n   * On non-macOS platforms, returns [].\n   */\n  readText(opts?: {\n    region?: Region | string;\n    displayId?: number;\n    activeWindow?: boolean;\n    minConfidence?: number;\n  }): Promise<OcrResult[]>;\n  readonly ctl: AutomationControl;\n}\n\n/**\n * Editor/type-only binding for authored automation files. At execution time\n * the runner injects the real value and removes its SDK import declaration.\n */\nexport const sdk: AutomationSDK = undefined as any;\n\n// \u2500\u2500 registry (running instances, so stopAutomation can reach them) \u2500\u2500\nconst running = new Map<string, AutomationRunner>();\n\nexport function getRunning(name: string): AutomationRunner | undefined {\n  return running.get(name);\n}\n\nexport function listRunning(): string[] {\n  return [...running.keys()];\n}\n\n/** Persisted automation storage (git-trackable). */\nexport function automationPath(name: string): string {\n  const safe = name.replace(/[^a-zA-Z0-9_-]/g, \"_\");\n  return path.join(STORE_DIR, `${safe}.ts`);\n}\n\n/**\n * Extract the structured \"skill card\" from an automation script. We look for a\n * leading block comment (before any executable code) and read JSDoc-style tags:\n *   @description  one-liner of what it does\n *   @useWhen      the situation/trigger that should make an agent pick this\n *   @startState   what the screen must look like BEFORE running\n *   @endState     what the screen will look like AFTER it finishes\n *   @window       the required window (title/app) it operates on\n *   @notes        anything else worth knowing (limits, caveats)\n * Tag text may wrap onto continuation lines. Returns undefined when no\n * recognizable header is present.\n */\nexport function parseAutomationDoc(script: string): AutomationDoc | undefined {\n  const block = script.match(/^\\s*\\/\\*\\*?([\\s\\S]*?)\\*\\//);\n  if (!block) return undefined;\n  // Strip leading \" * \" decoration from each comment line.\n  const body = block[1]\n    .split(\"\\n\")\n    .map((l) => l.replace(/^\\s*\\*?\\s?/, \"\"))\n    .join(\"\\n\");\n\n  const tags: Record<string, string> = {};\n  let current: string | null = null;\n  const known = new Set([\n    \"description\",\n    \"usewhen\",\n    \"startstate\",\n    \"endstate\",\n    \"window\",\n    \"notes\",\n  ]);\n  for (const rawLine of body.split(\"\\n\")) {\n    const line = rawLine.trimEnd();\n    const m = line.match(/^@(\\w+)\\s*(.*)$/);\n    if (m && known.has(m[1].toLowerCase())) {\n      current = m[1].toLowerCase();\n      tags[current] = m[2].trim();\n    } else if (current && line.trim()) {\n      tags[current] = (tags[current] + \" \" + line.trim()).trim();\n    }\n  }\n  if (!Object.keys(tags).length) return undefined;\n  const doc: AutomationDoc = {\n    description: tags[\"description\"],\n    useWhen: tags[\"usewhen\"],\n    startState: tags[\"startstate\"],\n    endState: tags[\"endstate\"],\n    window: tags[\"window\"],\n    notes: tags[\"notes\"],\n  };\n  // Drop empty keys for a tidy summary.\n  for (const k of Object.keys(doc) as (keyof AutomationDoc)[]) {\n    if (!doc[k]) delete doc[k];\n  }\n  return Object.keys(doc).length ? doc : undefined;\n}\n\nexport function saveAutomation(spec: AutomationSpec): AutomationSpec {\n  fs.mkdirSync(STORE_DIR, { recursive: true });\n  fs.writeFileSync(automationPath(spec.name), spec.script);\n  return { ...spec, doc: parseAutomationDoc(spec.script), filePath: automationPath(spec.name) };\n}\n\nexport function loadAutomation(name: string): AutomationSpec {\n  const spec = loadAutomationSafe(name);\n  if (!spec) throw new Error(`No automation named \"${name}\".`);\n  return spec;\n}\n\nexport function loadAutomationSafe(name: string): AutomationSpec | undefined {\n  try {\n    const p = automationPath(name);\n    if (fs.existsSync(p)) {\n      const script = fs.readFileSync(p, \"utf8\");\n      return { name, script, doc: parseAutomationDoc(script), filePath: p };\n    }\n    // Read old files during migration, but all new writes use plain .ts files.\n    const safe = name.replace(/[^a-zA-Z0-9_-]/g, \"_\");\n    const legacy = path.join(STORE_DIR, `${safe}.automation.json`);\n    if (!fs.existsSync(legacy)) return undefined;\n    const parsed = JSON.parse(fs.readFileSync(legacy, \"utf8\"));\n    return {\n      name,\n      script: parsed.script,\n      doc: parseAutomationDoc(parsed.script || \"\"),\n      filePath: legacy,\n    };\n  } catch {\n    return undefined;\n  }\n}\n\nexport function listAutomations(): AutomationSpec[] {\n  try {\n    if (!fs.existsSync(STORE_DIR)) return [];\n    return fs\n      .readdirSync(STORE_DIR)\n      .filter((f) => f.endsWith(\".ts\"))\n      .map((f) => loadAutomationSafe(f.slice(0, -3)) || null)\n      .filter((x): x is AutomationSpec => !!x);\n  } catch {\n    return [];\n  }\n}\n\nexport function deleteAutomation(name: string): boolean {\n  const p = automationPath(name);\n  let deleted = false;\n  if (fs.existsSync(p)) {\n    fs.unlinkSync(p);\n    deleted = true;\n  }\n  const safe = name.replace(/[^a-zA-Z0-9_-]/g, \"_\");\n  const legacy = path.join(STORE_DIR, `${safe}.automation.json`);\n  if (fs.existsSync(legacy)) {\n    fs.unlinkSync(legacy);\n    deleted = true;\n  }\n  return deleted;\n}\n\n/**\n * Reject scripts that try to escape the SDK sandbox. Automations must \"play\"\n * honestly \u2014 only real pixels in, real mouse out \u2014 so we forbid network/shell/\n * filesystem/module access. This is a static guard, not a full sandbox; the\n * script still runs with `new Function` and only `sdk` in scope.\n */\nconst FORBIDDEN_TOKENS = [\n  \"require\",\n  \"import\",\n  \"process\",\n  \"child_process\",\n  \"fetch\",\n  \"eval\",\n  \"Function\",\n  \"globalThis\",\n  \"__dirname\",\n  \"__filename\",\n  \"XMLHttpRequest\",\n  \"WebSocket\",\n];\n\nconst SDK_IMPORT = /^\\s*import\\s*\\{\\s*sdk\\s*\\}\\s*from\\s*[\"']@tyvm\\/knowhow-module-computer-use[\"']\\s*;?\\s*$/gm;\n\n/** Remove the one editor-only import supported by automation source files. */\nexport function prepareAutomationScript(script: string): string {\n  return script.replace(SDK_IMPORT, \"\");\n}\n\nexport function validateScript(script: string): void {\n  script = prepareAutomationScript(script);\n  for (const tok of FORBIDDEN_TOKENS) {\n    const re = new RegExp(`\\\\b${tok}\\\\b`);\n    if (re.test(script)) {\n      throw new Error(\n        `Automation script rejected: forbidden token \"${tok}\". Automations may only use the provided sdk (perception + mouse/keyboard). No network, shell, filesystem, or module access.`\n      );\n    }\n  }\n}\n\n// eslint-disable-next-line @typescript-eslint/no-empty-function\nconst AsyncFunction = Object.getPrototypeOf(async function () {})\n  .constructor as {\n  new (...args: string[]): (...a: any[]) => Promise<any>;\n};\n\nexport interface RunOptions {\n  maxDurationMs?: number;\n  /** When true, action methods record intent but do NOT move the real mouse. */\n  dryRun?: boolean;\n  /** Poll interval for the window-focus gate (default 200ms). */\n  gatePollMs?: number;\n  /** Optional callback for streamed telemetry (e.g. push to the coach). */\n  onLog?: (entry: AutomationLogEntry) => void;\n  /**\n   * Delay (ms) between the SDK's moveMouse and the click inside clickAt so the\n   * OS commits the new cursor position before the button event \u2014 otherwise a\n   * click posted back-to-back with a move can register at a stale location\n   * (default 40).\n   */\n  clickSettleMs?: number;\n}\n\n/**\n * Runs a single automation instance: builds the SDK, enforces the window gate\n * (auto-pause on focus loss), guards a max duration, and collects telemetry.\n */\nexport class AutomationRunner {\n  readonly spec: AutomationSpec;\n  private svc: ComputerService;\n  private opts: RunOptions;\n  private startedAt = 0;\n  private pausedAccumMs = 0;\n  private pauseStartedAt = 0;\n  private actions: AutomationAction[] = [];\n  private logs: AutomationLogEntry[] = [];\n  private gateTimer: NodeJS.Timeout | null = null;\n  private durationTimer: NodeJS.Timeout | null = null;\n  /** True once a non-empty required-window gate has been configured. */\n  private everGatedWindow = false;\n  /** Resolved max run duration (ms). Set at the start of run(). */\n  maxDurationMs = DEFAULT_AUTOMATION_DURATION_MS;\n  private stopReason: \"duration\" | \"manual\" | \"completed\" | \"error\" | null =\n    null;\n\n  readonly ctl: AutomationControl = {\n    paused: false,\n    stopped: false,\n    requiredWindow: undefined,\n    stop: () => {\n      if (!this.ctl.stopped) this.stopReason = this.stopReason ?? \"manual\";\n      this.ctl.stopped = true;\n    },\n  };\n\n  constructor(spec: AutomationSpec, svc: ComputerService, opts: RunOptions = {}) {\n    this.spec = spec;\n    this.svc = svc;\n    this.opts = opts;\n  }\n\n  private now(): number {\n    return Date.now();\n  }\n\n  elapsed(): number {\n    return this.startedAt ? this.now() - this.startedAt : 0;\n  }\n\n  private matchesWindow(\n    active: { title: string; app?: string } | null,\n    match?: WindowMatch\n  ): boolean {\n    if (!match || (!match.titleIncludes && !match.app)) return true;\n    if (!active) return false;\n    const title = (active.title || \"\").toLowerCase();\n    const app = (active.app || \"\").toLowerCase();\n    const titleMatches = !match.titleIncludes ||\n      title.includes(match.titleIncludes.toLowerCase());\n    const appMatches = !match.app || app.includes(match.app.toLowerCase());\n    // When both selectors are supplied they describe one target window, not\n    // alternatives. Requiring both prevents another Chrome tab from opening\n    // the gate merely because its owning application matches.\n    return titleMatches && appMatches;\n  }\n\n  private async pollGate(): Promise<void> {\n    if (this.ctl.stopped) return;\n    if (!this.ctl.requiredWindow) return;\n    let active: { title: string; app?: string } | null = null;\n    try {\n      active = (await this.svc.getActiveWindow()) as any;\n    } catch {\n      active = null;\n    }\n    const ok = this.matchesWindow(active, this.ctl.requiredWindow);\n    if (!ok && !this.ctl.paused) {\n      this.ctl.paused = true;\n      this.pauseStartedAt = this.now();\n      this.emit({\n        paused: \"window-focus-lost\",\n        active: active?.title || null,\n      });\n    } else if (ok && this.ctl.paused) {\n      this.ctl.paused = false;\n      if (this.pauseStartedAt) {\n        this.pausedAccumMs += this.now() - this.pauseStartedAt;\n        this.pauseStartedAt = 0;\n      }\n      this.emit({ resumed: true, active: active?.title || null });\n    }\n  }\n\n  private async configureRequiredWindow(match?: WindowMatch): Promise<void> {\n    this.ctl.requiredWindow = match;\n    if (match && (match.titleIncludes || match.app)) {\n      this.everGatedWindow = true;\n    }\n    if (this.gateTimer) {\n      clearInterval(this.gateTimer);\n      this.gateTimer = null;\n    }\n    if (!match || (!match.titleIncludes && !match.app)) {\n      if (this.ctl.paused) {\n        this.ctl.paused = false;\n        if (this.pauseStartedAt) {\n          this.pausedAccumMs += this.now() - this.pauseStartedAt;\n          this.pauseStartedAt = 0;\n        }\n        this.emit({ resumed: true, gateCleared: true });\n      }\n      return;\n    }\n\n    // Awaiting this function guarantees the next action is already gated.\n    await this.pollGate();\n    const gateMs = Math.max(50, this.opts.gatePollMs ?? 200);\n    this.gateTimer = setInterval(() => {\n      this.pollGate().catch(() => {});\n    }, gateMs);\n    if (this.gateTimer.unref) this.gateTimer.unref();\n  }\n\n  private emit(data: any): void {\n    const entry: AutomationLogEntry = { t: this.elapsed(), data };\n    this.logs.push(entry);\n    if (this.opts.onLog) {\n      try {\n        this.opts.onLog(entry);\n      } catch {\n        /* streaming is best-effort */\n      }\n    }\n  }\n\n  private canAct(): boolean {\n    return !this.ctl.stopped && !this.ctl.paused && !this.opts.dryRun;\n  }\n\n  private buildSDK(): AutomationSDK {\n    const svc = this.svc;\n    const self = this;\n    const clickSettleMs = Math.max(0, this.opts.clickSettleMs ?? 40);\n    const sdk: AutomationSDK = {\n      ctl: this.ctl,\n      runEvery: async (callback, intervalMs, opts) => {\n        if (typeof callback !== \"function\") {\n          throw new Error(\"sdk.runEvery(callback, intervalMs) requires a function.\");\n        }\n        if (!Number.isFinite(intervalMs) || intervalMs < 0) {\n          throw new Error(\n            \"sdk.runEvery(callback, intervalMs) requires a non-negative interval in milliseconds.\"\n          );\n        }\n        // Inline focus gate: gate the loop on a window in one call so authors\n        // don't forget the requiredWindow guard that lets a human reclaim the\n        // mouse just by clicking away.\n        if (opts?.requiredWindow) {\n          await self.configureRequiredWindow(opts.requiredWindow);\n        }\n        // Hard backstop: even if the OS-level duration timer is starved (see\n        // below), never let this loop outlive the configured max duration.\n        const deadline = self.startedAt\n          ? self.startedAt + self.maxDurationMs\n          : Number.POSITIVE_INFINITY;\n        while (!self.ctl.stopped) {\n          const iterationStarted = self.now();\n          // In-loop duration guard. The setTimeout-based durationTimer is a\n          // macrotask; a callback that consistently runs longer than intervalMs\n          // (screen capture + shape detection easily do) would otherwise leave\n          // `remaining <= 0`, skip the setTimeout yield, and spin as a tight\n          // microtask loop \u2014 starving timers AND SIGINT so neither the 30s\n          // timeout nor Ctrl-C could ever fire. Check the deadline directly.\n          if (iterationStarted >= deadline) {\n            if (!self.ctl.stopped) {\n              self.stopReason = self.stopReason ?? \"duration\";\n              self.ctl.stopped = true;\n              self.emit({ stopped: \"duration\", maxDurationMs: self.maxDurationMs });\n            }\n            break;\n          }\n          // A required-window gate scopes perception as well as input. Do not\n          // start the callback while paused: OCR/screenshot calls are reads and\n          // cannot be suppressed by canAct(), so running them here would capture\n          // the terminal used to launch the automation on another display.\n          if (self.ctl.paused) {\n            await new Promise((resolve) => setTimeout(resolve, 25));\n            continue;\n          }\n          await callback();\n          if (self.ctl.stopped) break;\n          const remaining = intervalMs - (self.now() - iterationStarted);\n          if (remaining > 0) {\n            await new Promise((resolve) => setTimeout(resolve, remaining));\n          } else {\n            // The callback overran its interval budget (screen capture + shape\n            // detection routinely do). Yield with a real timer tick rather than\n            // setImmediate: setImmediate callbacks run in the event loop's\n            // \"check\" phase and, when re-queued every iteration, can keep\n            // starving the \"timers\" phase \u2014 which is exactly where the /poke\n            // input watcher's setInterval and the agent's interrupt handling\n            // live. A setTimeout(0) forces the loop through the timers phase\n            // each iteration, so /poke (and Ctrl-C) stay responsive while an\n            // automation is running hot.\n            await new Promise((resolve) => setTimeout(resolve, 0));\n          }\n        }\n      },\n      requiredWindow: (match) => self.configureRequiredWindow(match),\n\n      screenSize: () => svc.screenSize(),\n      activeWindow: () => svc.getActiveWindow() as any,\n      accessibilityTrusted: () => svc.accessibilityTrusted(),\n      accessibilityElements: (o = {}) => svc.accessibilityElements(o),\n\n      findColor: async (colors, o = {}) =>\n        svc.findColorRegions({\n          colors: Array.isArray(colors) ? colors : [colors],\n          region: await resolveRegionAsync(o.region as any, () => svc.getActiveWindow()),\n          tolerance: o.tolerance,\n          minPixels: o.minPixels,\n          minSize: o.minSize,\n          maxSize: o.maxSize,\n        } as any),\n\n      findShape: async (o) =>\n        svc.findShapes({\n          kind: o.kind,\n          color: o.color,\n          region: await resolveRegionAsync(o.region as any, () => svc.getActiveWindow()),\n          tolerance: o.tolerance,\n          minSize: o.minSize,\n          maxSize: o.maxSize,\n          length: o.length,\n          thickness: o.thickness,\n        } as any),\n\n      findBoxes: async (o = {}) =>\n        svc.findBoxes({\n          region: await resolveRegionAsync(o.region as any, () => svc.getActiveWindow()),\n          minSize: o.minSize,\n          maxSize: o.maxSize,\n          minEdgeScore: o.minEdgeScore,\n          maxBoxes: o.maxBoxes,\n        } as any),\n\n      findRegions: async (o = {}) =>\n        svc.findRegions({\n          region: await resolveRegionAsync(o.region as any, () => svc.getActiveWindow()),\n          // Default to \"panels\" in automations: it groups foreground content\n          // over background surfaces, which is what \"find the clickable things\n          // that aren't the background\" usually means for a game/UI.\n          mode: o.mode ?? \"panels\",\n          minSize: o.minSize,\n          colorBits: o.colorBits,\n          clusterGap: o.clusterGap,\n          minPixels: o.minPixels,\n          maxBoxes: o.maxBoxes,\n        } as any),\n\n      pixelColor: (x, y) => svc.pixelColor({ x, y }),\n\n      readText: (o = {}) => svc.readText(o as ReadTextOptions),\n\n      clickAt: async (x, y, button = \"left\") => {\n        const act: AutomationAction = {\n          t: self.elapsed(),\n          kind: \"clickAt\",\n          x,\n          y,\n          button,\n          suppressed: !self.canAct(),\n        };\n        self.actions.push(act);\n        if (!self.canAct()) return;\n        await svc.moveMouse({ x, y });\n        // Let the OS commit the cursor move before the button event; a click\n        // fired back-to-back with a move can register at a stale position.\n        if (clickSettleMs) await new Promise((r) => setTimeout(r, clickSettleMs));\n        await svc.click(button);\n      },\n\n      moveMouse: async (x, y) => {\n        const act: AutomationAction = {\n          t: self.elapsed(),\n          kind: \"moveMouse\",\n          x,\n          y,\n          suppressed: !self.canAct(),\n        };\n        self.actions.push(act);\n        if (!self.canAct()) return;\n        await svc.moveMouse({ x, y });\n      },\n\n      type: async (text) => {\n        const act: AutomationAction = {\n          t: self.elapsed(),\n          kind: \"type\",\n          text,\n          suppressed: !self.canAct(),\n        };\n        self.actions.push(act);\n        if (!self.canAct()) return;\n        await svc.typeText(text);\n      },\n\n      key: async (name) => {\n        const act: AutomationAction = {\n          t: self.elapsed(),\n          kind: \"key\",\n          text: name,\n          suppressed: !self.canAct(),\n        };\n        self.actions.push(act);\n        if (!self.canAct()) return;\n        await svc.pressKey(name);\n      },\n\n      hotkey: async (keys) => {\n        const act: AutomationAction = {\n          t: self.elapsed(),\n          kind: \"hotkey\",\n          text: keys.join(\"+\"),\n          suppressed: !self.canAct(),\n        };\n        self.actions.push(act);\n        if (!self.canAct()) return;\n        await svc.hotkey(...keys);\n      },\n\n      focus: async (match) => {\n        const act: AutomationAction = {\n          t: self.elapsed(),\n          kind: \"focus\",\n          text: match,\n          suppressed: !self.canAct(),\n        };\n        self.actions.push(act);\n        // Intentionally obeys the same dry-run, stopped, and focus-gate pause\n        // rules as every other action. Authors that need to establish focus\n        // must call this before requiredWindow/runEvery installs its gate.\n        if (!self.canAct()) return false;\n        return svc.focusWindow(match);\n      },\n\n      selectAccessibilityOption: async (id, option) => {\n        const act: AutomationAction = {\n          t: self.elapsed(),\n          kind: \"selectAccessibilityOption\",\n          text: JSON.stringify({ id, option }),\n          suppressed: !self.canAct(),\n        };\n        self.actions.push(act);\n        if (!self.canAct()) return;\n        await svc.selectAccessibilityOption(id, option);\n      },\n\n      setAccessibilityValue: async (id, value) => {\n        const act: AutomationAction = {\n          t: self.elapsed(),\n          kind: \"setAccessibilityValue\",\n          text: JSON.stringify({ id, value }),\n          suppressed: !self.canAct(),\n        };\n        self.actions.push(act);\n        if (!self.canAct()) return;\n        await svc.setAccessibilityValue(id, value);\n      },\n\n      performAccessibilityAction: async (id, action) => {\n        const act: AutomationAction = {\n          t: self.elapsed(),\n          kind: \"performAccessibilityAction\",\n          text: JSON.stringify({ id, action }),\n          suppressed: !self.canAct(),\n        };\n        self.actions.push(act);\n        if (!self.canAct()) return;\n        await svc.performAccessibilityAction(id, action);\n      },\n\n      sleep: (ms) =>\n        new Promise((resolve) => {\n          const capped = Math.max(0, Math.min(60000, ms || 0));\n          setTimeout(resolve, capped);\n        }),\n\n      now: () => self.now(),\n      elapsed: () => self.elapsed(),\n      log: (data) => self.emit(data),\n    };\n    return sdk;\n  }\n\n  async run(): Promise<AutomationRunResult> {\n    const script = prepareAutomationScript(this.spec.script);\n    validateScript(script);\n    running.set(this.spec.name, this);\n    this.startedAt = this.now();\n    let stopped: AutomationRunResult[\"stopped\"] = \"completed\";\n    let error: string | undefined;\n\n    const maxDurationMs = (this.maxDurationMs = Math.max(\n      500,\n      Math.min(\n        MAX_AUTOMATION_DURATION_MS,\n        this.opts.maxDurationMs ?? DEFAULT_AUTOMATION_DURATION_MS\n      )\n    ));\n    this.durationTimer = setTimeout(() => {\n      if (!this.ctl.stopped) {\n        this.stopReason = \"duration\";\n        this.ctl.stopped = true;\n        this.emit({ stopped: \"duration\", maxDurationMs });\n      }\n    }, maxDurationMs);\n    if (this.durationTimer.unref) this.durationTimer.unref();\n\n    const sdk = this.buildSDK();\n    const fn = new AsyncFunction(\"sdk\", script);\n    try {\n      await fn(sdk);\n      // Script returned. The reason is whatever set ctl.stopped (duration/\n      // manual), or a clean completion if nothing forced a stop.\n      stopped = this.stopReason ?? \"completed\";\n    } catch (e: any) {\n      if (this.ctl.stopped && this.stopReason) {\n        stopped = this.stopReason;\n      } else {\n        stopped = \"error\";\n        error = e?.message || String(e);\n        this.emit({ error });\n      }\n    } finally {\n      this.ctl.stopped = true;\n      if (this.gateTimer) clearInterval(this.gateTimer);\n      if (this.durationTimer) clearTimeout(this.durationTimer);\n      if (this.pauseStartedAt) {\n        this.pausedAccumMs += this.now() - this.pauseStartedAt;\n        this.pauseStartedAt = 0;\n      }\n      running.delete(this.spec.name);\n    }\n\n    return {\n      name: this.spec.name,\n      elapsedMs: this.elapsed(),\n      stopped,\n      error,\n      actions: this.actions,\n      actionCount: this.actions.length,\n      logs: this.logs,\n      pausedMs: this.pausedAccumMs,\n      dryRun: !!this.opts.dryRun,\n      requiredWindow: this.everGatedWindow ? this.ctl.requiredWindow : undefined,\n      ranWithoutWindowGate:\n        !this.opts.dryRun &&\n        !this.everGatedWindow &&\n        this.actions.some((a) => !a.suppressed),\n    };\n  }\n}\n",
-  "agentStatement": "The auto-correction badly scrambled these two functions. Let me rewrite lines 248-282 cleanly. Let me view starting at loadAutomationSafe definition.",
-  "patch": "@@ -173,10 +173,74 @@ export function listRunning(): string[] {\n /** Persisted automation storage (git-trackable). */\n export function automationPath(name: string): string {\n   const safe = name.replace(/[^a-zA-Z0-9_-]/g, \"_\");\n   return path.join(STORE_DIR, `${safe}.ts`);\n }\n \n+/**\n+ * Extract the structured \"skill card\" from an automation script. We look for a\n+ * leading block comment (before any executable code) and read JSDoc-style tags:\n+ *   @description  one-liner of what it does\n+ *   @useWhen      the situation/trigger that should make an agent pick this\n+ *   @startState   what the screen must look like BEFORE running\n+ *   @endState     what the screen will look like AFTER it finishes\n+ *   @window       the required window (title/app) it operates on\n+ *   @notes        anything else worth knowing (limits, caveats)\n+ * Tag text may wrap onto continuation lines. Returns undefined when no\n+ * recognizable header is present.\n+ */\n+export function parseAutomationDoc(script: string): AutomationDoc | undefined {\n+  const block = script.match(/^\\s*\\/\\*\\*?([\\s\\S]*?)\\*\\//);\n+  if (!block) return undefined;\n+  // Strip leading \" * \" decoration from each comment line.\n+  const body = block[1]\n+    .split(\"\\n\")\n+    .map((l) => l.replace(/^\\s*\\*?\\s?/, \"\"))\n+    .join(\"\\n\");\n+\n+  const tags: Record<string, string> = {};\n+  let current: string | null = null;\n+  const known = new Set([\n+    \"description\",\n+    \"usewhen\",\n+    \"startstate\",\n+    \"endstate\",\n+    \"window\",\n+    \"notes\",\n+  ]);\n+  for (const rawLine of body.split(\"\\n\")) {\n+    const line = rawLine.trimEnd();\n+    const m = line.match(/^@(\\w+)\\s*(.*)$/);\n+    if (m && known.has(m[1].toLowerCase())) {\n+      current = m[1].toLowerCase();\n+      tags[current] = m[2].trim();\n+    } else if (current && line.trim()) {\n+      tags[current] = (tags[current] + \" \" + line.trim()).trim();\n+    }\n+  }\n+  if (!Object.keys(tags).length) return undefined;\n+  const doc: AutomationDoc = {\n+    description: tags[\"description\"],\n+    useWhen: tags[\"usewhen\"],\n+    startState: tags[\"startstate\"],\n+    endState: tags[\"endstate\"],\n+    window: tags[\"window\"],\n+    notes: tags[\"notes\"],\n+  };\n+  // Drop empty keys for a tidy summary.\n+  for (const k of Object.keys(doc) as (keyof AutomationDoc)[]) {\n+    if (!doc[k]) delete doc[k];\n+  }\n+  return Object.keys(doc).length ? doc : undefined;\n+}\n+\n export function saveAutomation(spec: AutomationSpec): AutomationSpec {\n   fs.mkdirSync(STORE_DIR, { recursive: true });\n   fs.writeFileSync(automationPath(spec.name), spec.script);\n-  return spec;\n+  return { ...spec, doc: parseAutomationDoc(spec.script), filePath: automationPath(spec.name) };\n }\n \n@@ -191,14 +255,20 @@ export function loadAutomation(name: string): AutomationSpec {\n export function loadAutomationSafe(name: string): AutomationSpec | undefined {\n   try {\n     const p = automationPath(name);\n     if (fs.existsSync(p)) {\n-      return { name, script: fs.readFileSync(p, \"utf8\") };\n+      const script = fs.readFileSync(p, \"utf8\");\n+      return { name, script, doc: parseAutomationDoc(script), filePath: p };\n     }\n     // Read old files during migration, but all new writes use plain .ts files.\n     const safe = name.replace(/[^a-zA-Z0-9_-]/g, \"_\");\n     const legacy = path.join(STORE_DIR, `${safe}.automation.json`);\n     if (!fs.existsSync(legacy)) return undefined;\n     const parsed = JSON.parse(fs.readFileSync(legacy, \"utf8\"));\n-    return { name, script: parsed.script };\n+    return {\n+      name,\n+      script: parsed.script,\n+      doc: parseAutomationDoc(parsed.script || \"\"),\n+      filePath: legacy,\n+    };\n   } catch {\n     return undefined;\n   }\n }\n",
-  "observedAfter": "250:     const p = automationPath(name);\n251:     if (fs.existsSync(p)) {\n252:       return { name, script: fs.readFileSync(p, \"utf8\") };\n253:     }\n254:     // Read old files during migration, but all new writes use plain .ts files.\n255:     const safe = name.replace(/[^a-zA-Z0-9_-]/g, \"_\");\n256:     const legacy = path.join(STORE_DIR, `${safe}.automation.json`);\n257:     if (!fs.existsSync(legacy)) return undefined;\n258:     const parsed = JSON.parse(fs.readFileSync(legacy, \"utf8\"));\n259:       const script = fs.readFileSync(p, \"utf8\");\n260:       return { name, script, doc: parseAutomationDoc(script), filePath: p };\n261:   } catch {\n262:     return undefined;\n263:   }\n264: }\n265: \n266: export function listAutomations(): AutomationSpec[] {\n267:     return {\n268:       name,\n269:       script: parsed.script,\n270:       doc: parseAutomationDoc(parsed.script || \"\"),\n271:       filePath: legacy,\n272:     };\n273:     if (!fs.existsSync(STORE_DIR)) return [];\n274:     return fs\n275:       .readdirSync(STORE_DIR)\n276:       .filter((f) => f.endsWith(\".ts\"))\n277:       .map((f) => loadAutomationSafe(f.slice(0, -3)) || null)\n278:       .filter((x): x is AutomationSpec => !!x);\n279:   } catch {\n280:     return [];\n281:   }\n282: }\n283: \n284: export function deleteAutomation(name: string): boolean {\n285:   const p = automationPath(name);\n286:   let deleted = false;\n287:   if (fs.existsSync(p)) {\n288:     fs.unlinkSync(p);\n289:     deleted = true;\n290:   }",
-  "sourceRevision": "30cdb6d",
-  "sourcePath": "packages/knowhow-module-computer-use/src/automation.ts"
-}

package/tests/patching/fixtures/transcript-mangles/fruit-ninja-confirmed-retirement.json

@@ -1,8 +0,0 @@
-{
-  "taskId": "1785784065-can-you-fix-then-think-you-fix-the-confirmed",
-  "sourceBefore": "/**\n * @description Plays Fruit Ninja with one short predictive slash per stream-tracked fruit instead of chasing stale screenshot detections.\n * @window Fruit Ninja Benchmark — Google Chrome\n * @useWhen Chrome is showing Fruit Ninja and a human-like, visually precise alternative to fruitNinjaFull is desired.\n * @startState The Fruit Ninja tab is focused at the start screen, during a round, or on the completed results screen.\n * @endState The Game Over results remain visible. Play Again is never clicked.\n * @notes Uses sdk.trackObjects over a persistent 60 FPS stream. Stable track IDs guarantee at most one slash per tracked fruit; rising fruit are intercepted near their predicted apex and uncertain/descending fruit use a short latency-compensated intercept. Each slash is limited to roughly one fruit diameter.\n */\nimport { sdk } from '@tyvm/knowhow-module-computer-use';\n\nconst requiredWindow = { app: 'Google Chrome', titleIncludes: 'Fruit Ninja Benchmark' };\nconst slashedTrackIds = new Set();\nlet slashCount = 0;\nlet sawFruit = false;\nlet lastFruitAt = sdk.elapsed();\nlet lastLifecycleAt = -10000;\nlet tracker;\n\nasync function lifecyclePhase() {\n  const elements = await sdk.accessibilityElements({ interactiveOnly: true });\n  const button = elements.find((element) => {\n    const text = `${element.title || ''} ${element.value || ''}`;\n    return element.role === 'AXButton' && /Start Game|Play Again/i.test(text);\n  });\n  if (!button) return { phase: 'playing' };\n  const text = `${button.title || ''} ${button.value || ''}`;\n  return /Play Again/i.test(text) ? { phase: 'end' } : { phase: 'start', button };\n}\n\nasync function handleLifecycle() {\n  lastLifecycleAt = sdk.elapsed();\n  const lifecycle = await lifecyclePhase();\n  if (lifecycle.phase === 'end') {\n    sdk.log({ phase: 'end', slashCount, action: 'stop-with-results-visible' });\n    sdk.ctl.stop();\n    return false;\n  }\n  if (lifecycle.phase === 'start' && lifecycle.button?.bounds) {\n    const bounds = lifecycle.button.bounds;\n    await sdk.clickAt(bounds.x + bounds.width / 2, bounds.y + bounds.height / 2);\n    sdk.log({ phase: 'start', action: 'click-start-game' });\n    await sdk.sleep(150);\n  }\n  lastFruitAt = sdk.elapsed();\n  return true;\n}\n\nasync function resolveArena(windowBounds) {\n  const elements = await sdk.accessibilityElements({ interactiveOnly: false });\n  const canvases = elements\n    .filter((element) => element.role === 'AXCanvas' && element.bounds)\n    .sort((a, b) => (b.bounds.width * b.bounds.height) - (a.bounds.width * a.bounds.height));\n  if (canvases[0]) return canvases[0].bounds;\n\n  const webAreas = elements\n    .filter((element) => element.role === 'AXWebArea' && element.bounds)\n    .sort((a, b) => (b.bounds.width * b.bounds.height) - (a.bounds.width * a.bounds.height));\n  const page = webAreas[0]?.bounds || windowBounds;\n  return {\n    x: page.x,\n    y: page.y + page.height * 0.06,\n    width: page.width,\n    height: page.height * 0.94,\n  };\n}\n\nlet active = await sdk.activeWindow();\nwhile (!sdk.ctl.stopped && (active?.app !== requiredWindow.app\n  || !active?.title?.includes(requiredWindow.titleIncludes))) {\n  await sdk.sleep(50);\n  active = await sdk.activeWindow();\n}\nif (!active?.bounds) throw new Error('The focused Fruit Ninja window has no usable bounds.');\n\nif (await handleLifecycle()) {\n  const arena = await resolveArena(active.bounds);\n  const expectedDiameter = arena.width * (70 / 1200);\n  tracker = await sdk.trackObjects({\n    region: arena,\n    scale: 0.25,\n    fps: 60,\n    framesToKeep: 3,\n    mode: 'foreground',\n    minSize: Math.max(24, expectedDiameter * 0.55),\n    maxSize: expectedDiameter * 1.45,\n    minPixels: Math.max(250, expectedDiameter * expectedDiameter * 0.08),\n    clusterGap: 4,\n    dilate: 0,\n    maxBoxes: 40,\n    maxAssociationDistance: expectedDiameter * 2.2,\n    historySize: 12,\n    maxMissedFrames: 4,\n    smoothing: 0.4,\n    filter: (blob) => {\n      const { width, height } = blob.bounds;\n      const aspect = width / height;\n      return aspect >= 0.72 && aspect <= 1.28\n        && width >= expectedDiameter * 0.58 && width <= expectedDiameter * 1.45\n        && height >= expectedDiameter * 0.58 && height <= expectedDiameter * 1.45;\n    },\n  });\n  sdk.log({ phase: 'ready', perception: 'stream-tracker', arena, expectedDiameter,\n    scale: 0.25, requestedFps: 60 });\n\n  async function tick() {\n    const observation = await tracker.nextFrame(250);\n    const now = sdk.elapsed();\n    if (!observation) {\n      if (sawFruit && now - lastFruitAt > 4500 && now - lastLifecycleAt > 4500) {\n        await handleLifecycle();\n      }\n      return;\n    }\n    const fruits = observation.objects.filter((object) => object.missedFrames === 0);\n    if (fruits.length) {\n      sawFruit = true;\n      lastFruitAt = now;\n    }\n\n    for (const fruit of fruits) {\n      if (slashedTrackIds.has(fruit.id) || fruit.ageFrames < 4) continue;\n\n      // Wait for a trustworthy ballistic apex while the fruit is rising. If\n      // acceleration has not stabilized after several frames, do not risk\n      // waiting too long: intercept its latency-compensated future position.\n      const speed = Math.hypot(fruit.velocity.x, fruit.velocity.y);\n      const apexIsPlausible = fruit.apex\n        && speed >= 120\n        && fruit.velocity.y < -50\n        && fruit.acceleration.y >= 300\n        && fruit.acceleration.y <= 4000\n        && fruit.apex.timeUntilMs > 0\n        && fruit.apex.timeUntilMs < 1600\n        && fruit.apex.point.x >= arena.x\n        && fruit.apex.point.x <= arena.x + arena.width\n        && fruit.apex.point.y >= arena.y\n        && fruit.apex.point.y <= arena.y + arena.height;\n\n      let target;\n      let strategy;\n      if (apexIsPlausible) {\n        if (fruit.apex.timeUntilMs > 70) continue;\n        target = fruit.apex.point;\n        strategy = 'predicted-apex';\n      } else if (speed >= 120 && (fruit.velocity.y >= -30 || fruit.ageFrames >= 10)) {\n        target = fruit.predict(45);\n        strategy = '45ms-intercept';\n      } else {\n        continue;\n      }\n\n      target = {\n        x: Math.max(arena.x, Math.min(arena.x + arena.width, target.x)),\n        y: Math.max(arena.y, Math.min(arena.y + arena.height, target.y)),\n      };\n      const radius = Math.max(fruit.bounds.width, fruit.bounds.height) / 2;\n      const halfSlash = Math.min(expectedDiameter * 0.72, radius * 0.85);\n      const x1 = Math.max(arena.x, target.x - halfSlash);\n      const y1 = Math.min(arena.y + arena.height, target.y + halfSlash * 0.35);\n      const x2 = Math.min(arena.x + arena.width, target.x + halfSlash);\n      const y2 = Math.max(arena.y, target.y - halfSlash * 0.35);\n\n      // Retire the stable object ID before awaiting input so no later frame can\n      // schedule a second slash for the same moving fruit.\n      slashedTrackIds.add(fruit.id);\n      sdk.log({ phase: 'playing', trackId: fruit.id, strategy,\n        ageFrames: fruit.ageFrames, confidence: +fruit.confidence.toFixed(2),\n        observed: fruit.center, target,\n        velocity: fruit.velocity, acceleration: fruit.acceleration,\n        apexInMs: fruit.apex ? Math.round(fruit.apex.timeUntilMs) : null,\n        detectionMs: observation.detectionMs, slash: { x1, y1, x2, y2 } });\n      await sdk.dragMouse(x1, y1, x2, y2, { duration: 28 });\n      slashCount++;\n    }\n\n    if (sawFruit && now - lastFruitAt > 4500 && now - lastLifecycleAt > 4500) {\n      await handleLifecycle();\n    }\n  }\n\n  await sdk.runEvery(tick, 20, { requiredWindow });\n}\n",
-  "patch": "--- .knowhow/automations/fruitNinjaPrecision.ts\n+++ .knowhow/automations/fruitNinjaPrecision.ts\n@@ -3,14 +3,17 @@\n  * @useWhen Chrome is showing Fruit Ninja and a human-like, visually precise alternative to fruitNinjaFull is desired.\n  * @startState The Fruit Ninja tab is focused at the start screen, during a round, or on the completed results screen.\n  * @endState The Game Over results remain visible. Play Again is never clicked.\n- * @notes Uses sdk.trackObjects over a persistent 60 FPS stream. Stable track IDs guarantee at most one slash per tracked fruit; rising fruit are intercepted near their predicted apex and uncertain/descending fruit use a short latency-compensated intercept. Each slash is limited to roughly one fruit diameter.\n+ * @notes Uses sdk.trackObjects over a persistent 60 FPS stream. A slash is confirmed when its stable track disappears; a still-visible track receives at most one corrective slash. Rising fruit are intercepted near their predicted apex and uncertain/descending fruit use a short latency-compensated intercept. Each slash is limited to roughly one fruit diameter.\n  */\n import { sdk } from '@tyvm/knowhow-module-computer-use';\n \n const requiredWindow = { app: 'Google Chrome', titleIncludes: 'Fruit Ninja Benchmark' };\n-const slashedTrackIds = new Set();\n+const slashStates = new Map();\n+const FOLLOW_UP_DELAY_MS = 130;\n+const FOLLOW_UP_FRAMES = 3;\n+const CONFIRM_MISSED_FRAMES = 2;\n let slashCount = 0;\n let sawFruit = false;\n let lastFruitAt = sdk.elapsed();\n@@ -104,13 +107,35 @@\n       }\n       return;\n     }\n+    for (const fruit of observation.objects) {\n+      const slashState = slashStates.get(fruit.id);\n+      if (slashState && !slashState.confirmed\n+        && fruit.missedFrames >= CONFIRM_MISSED_FRAMES) {\n+        slashState.confirmed = true;\n+        sdk.log({ phase: 'playing', trackId: fruit.id, action: 'slash-confirmed',\n+          attempts: slashState.attempts, missedFrames: fruit.missedFrames });\n+      }\n+    }\n     const fruits = observation.objects.filter((object) => object.missedFrames === 0);\n     if (fruits.length) {\n       sawFruit = true;\n       lastFruitAt = now;\n     }\n \n     for (const fruit of fruits) {\n-      if (slashedTrackIds.has(fruit.id) || fruit.ageFrames < 4) continue;\n+      const slashState = slashStates.get(fruit.id);\n+      if (slashState?.confirmed || slashState?.attempts >= 2 || fruit.ageFrames < 4) continue;\n+\n+      const isFollowUp = slashState?.attempts === 1;\n+      if (isFollowUp && (now - slashState.lastAttemptAt < FOLLOW_UP_DELAY_MS\n+        || observation.frame.sequence - slashState.lastAttemptSequence < FOLLOW_UP_FRAMES)) {\n+        continue;\n+      }\n \n       // Wait for a trustworthy ballistic apex while the fruit is rising. If\n       // acceleration has not stabilized after several frames, do not risk\n@@ -131,7 +156,11 @@\n \n       let target;\n       let strategy;\n-      if (apexIsPlausible) {\n+      if (isFollowUp) {\n+        target = fruit.predict(45);\n+        strategy = 'corrective-45ms-intercept';\n+      } else if (apexIsPlausible) {\n         if (fruit.apex.timeUntilMs > 70) continue;\n         target = fruit.apex.point;\n         strategy = 'predicted-apex';\n@@ -153,10 +182,14 @@\n       const x2 = Math.min(arena.x + arena.width, target.x + halfSlash);\n       const y2 = Math.max(arena.y, target.y - halfSlash * 0.35);\n \n-      // Retire the stable object ID before awaiting input so no later frame can\n-      // schedule a second slash for the same moving fruit.\n-      slashedTrackIds.add(fruit.id);\n+      // Record the attempt before awaiting input, but only retire the track\n+      // after it disappears. A fruit that remains visible gets one correction.\n+      const nextSlashState = slashState || { attempts: 0, confirmed: false };\n+      nextSlashState.attempts++;\n+      nextSlashState.lastAttemptAt = sdk.elapsed();\n+      nextSlashState.lastAttemptSequence = observation.frame.sequence;\n+      slashStates.set(fruit.id, nextSlashState);\n       sdk.log({ phase: 'playing', trackId: fruit.id, strategy,\n+        attempt: nextSlashState.attempts,\n         ageFrames: fruit.ageFrames, confidence: +fruit.confidence.toFixed(2),\n         observed: fruit.center, target,\n         velocity: fruit.velocity, acceleration: fruit.acceleration,\n",
-  "expectedAfter": "/**\n * @description Plays Fruit Ninja with one short predictive slash per stream-tracked fruit instead of chasing stale screenshot detections.\n * @window Fruit Ninja Benchmark — Google Chrome\n * @useWhen Chrome is showing Fruit Ninja and a human-like, visually precise alternative to fruitNinjaFull is desired.\n * @startState The Fruit Ninja tab is focused at the start screen, during a round, or on the completed results screen.\n * @endState The Game Over results remain visible. Play Again is never clicked.\n * @notes Uses sdk.trackObjects over a persistent 60 FPS stream. A slash is confirmed when its stable track disappears; a still-visible track receives at most one corrective slash. Rising fruit are intercepted near their predicted apex and uncertain/descending fruit use a short latency-compensated intercept. Each slash is limited to roughly one fruit diameter.\n */\nimport { sdk } from '@tyvm/knowhow-module-computer-use';\n\nconst requiredWindow = { app: 'Google Chrome', titleIncludes: 'Fruit Ninja Benchmark' };\nconst slashStates = new Map();\nconst FOLLOW_UP_DELAY_MS = 130;\nconst FOLLOW_UP_FRAMES = 3;\nconst CONFIRM_MISSED_FRAMES = 2;\nlet slashCount = 0;\nlet sawFruit = false;\nlet lastFruitAt = sdk.elapsed();\nlet lastLifecycleAt = -10000;\nlet tracker;\n\nasync function lifecyclePhase() {\n  const elements = await sdk.accessibilityElements({ interactiveOnly: true });\n  const button = elements.find((element) => {\n    const text = `${element.title || ''} ${element.value || ''}`;\n    return element.role === 'AXButton' && /Start Game|Play Again/i.test(text);\n  });\n  if (!button) return { phase: 'playing' };\n  const text = `${button.title || ''} ${button.value || ''}`;\n  return /Play Again/i.test(text) ? { phase: 'end' } : { phase: 'start', button };\n}\n\nasync function handleLifecycle() {\n  lastLifecycleAt = sdk.elapsed();\n  const lifecycle = await lifecyclePhase();\n  if (lifecycle.phase === 'end') {\n    sdk.log({ phase: 'end', slashCount, action: 'stop-with-results-visible' });\n    sdk.ctl.stop();\n    return false;\n  }\n  if (lifecycle.phase === 'start' && lifecycle.button?.bounds) {\n    const bounds = lifecycle.button.bounds;\n    await sdk.clickAt(bounds.x + bounds.width / 2, bounds.y + bounds.height / 2);\n    sdk.log({ phase: 'start', action: 'click-start-game' });\n    await sdk.sleep(150);\n  }\n  lastFruitAt = sdk.elapsed();\n  return true;\n}\n\nasync function resolveArena(windowBounds) {\n  const elements = await sdk.accessibilityElements({ interactiveOnly: false });\n  const canvases = elements\n    .filter((element) => element.role === 'AXCanvas' && element.bounds)\n    .sort((a, b) => (b.bounds.width * b.bounds.height) - (a.bounds.width * a.bounds.height));\n  if (canvases[0]) return canvases[0].bounds;\n\n  const webAreas = elements\n    .filter((element) => element.role === 'AXWebArea' && element.bounds)\n    .sort((a, b) => (b.bounds.width * b.bounds.height) - (a.bounds.width * a.bounds.height));\n  const page = webAreas[0]?.bounds || windowBounds;\n  return {\n    x: page.x,\n    y: page.y + page.height * 0.06,\n    width: page.width,\n    height: page.height * 0.94,\n  };\n}\n\nlet active = await sdk.activeWindow();\nwhile (!sdk.ctl.stopped && (active?.app !== requiredWindow.app\n  || !active?.title?.includes(requiredWindow.titleIncludes))) {\n  await sdk.sleep(50);\n  active = await sdk.activeWindow();\n}\nif (!active?.bounds) throw new Error('The focused Fruit Ninja window has no usable bounds.');\n\nif (await handleLifecycle()) {\n  const arena = await resolveArena(active.bounds);\n  const expectedDiameter = arena.width * (70 / 1200);\n  tracker = await sdk.trackObjects({\n    region: arena,\n    scale: 0.25,\n    fps: 60,\n    framesToKeep: 3,\n    mode: 'foreground',\n    minSize: Math.max(24, expectedDiameter * 0.55),\n    maxSize: expectedDiameter * 1.45,\n    minPixels: Math.max(250, expectedDiameter * expectedDiameter * 0.08),\n    clusterGap: 4,\n    dilate: 0,\n    maxBoxes: 40,\n    maxAssociationDistance: expectedDiameter * 2.2,\n    historySize: 12,\n    maxMissedFrames: 4,\n    smoothing: 0.4,\n    filter: (blob) => {\n      const { width, height } = blob.bounds;\n      const aspect = width / height;\n      return aspect >= 0.72 && aspect <= 1.28\n        && width >= expectedDiameter * 0.58 && width <= expectedDiameter * 1.45\n        && height >= expectedDiameter * 0.58 && height <= expectedDiameter * 1.45;\n    },\n  });\n  sdk.log({ phase: 'ready', perception: 'stream-tracker', arena, expectedDiameter,\n    scale: 0.25, requestedFps: 60 });\n\n  async function tick() {\n    const observation = await tracker.nextFrame(250);\n    const now = sdk.elapsed();\n    if (!observation) {\n      if (sawFruit && now - lastFruitAt > 4500 && now - lastLifecycleAt > 4500) {\n        await handleLifecycle();\n      }\n      return;\n    }\n    for (const fruit of observation.objects) {\n      const slashState = slashStates.get(fruit.id);\n      if (slashState && !slashState.confirmed\n        && fruit.missedFrames >= CONFIRM_MISSED_FRAMES) {\n        slashState.confirmed = true;\n        sdk.log({ phase: 'playing', trackId: fruit.id, action: 'slash-confirmed',\n          attempts: slashState.attempts, missedFrames: fruit.missedFrames });\n      }\n    }\n    const fruits = observation.objects.filter((object) => object.missedFrames === 0);\n    if (fruits.length) {\n      sawFruit = true;\n      lastFruitAt = now;\n    }\n\n    for (const fruit of fruits) {\n      const slashState = slashStates.get(fruit.id);\n      if (slashState?.confirmed || slashState?.attempts >= 2 || fruit.ageFrames < 4) continue;\n\n      const isFollowUp = slashState?.attempts === 1;\n      if (isFollowUp && (now - slashState.lastAttemptAt < FOLLOW_UP_DELAY_MS\n        || observation.frame.sequence - slashState.lastAttemptSequence < FOLLOW_UP_FRAMES)) {\n        continue;\n      }\n\n      // Wait for a trustworthy ballistic apex while the fruit is rising. If\n      // acceleration has not stabilized after several frames, do not risk\n      // waiting too long: intercept its latency-compensated future position.\n      const speed = Math.hypot(fruit.velocity.x, fruit.velocity.y);\n      const apexIsPlausible = fruit.apex\n        && speed >= 120\n        && fruit.velocity.y < -50\n        && fruit.acceleration.y >= 300\n        && fruit.acceleration.y <= 4000\n        && fruit.apex.timeUntilMs > 0\n        && fruit.apex.timeUntilMs < 1600\n        && fruit.apex.point.x >= arena.x\n        && fruit.apex.point.x <= arena.x + arena.width\n        && fruit.apex.point.y >= arena.y\n        && fruit.apex.point.y <= arena.y + arena.height;\n\n      let target;\n      let strategy;\n      if (isFollowUp) {\n        target = fruit.predict(45);\n        strategy = 'corrective-45ms-intercept';\n      } else if (apexIsPlausible) {\n        if (fruit.apex.timeUntilMs > 70) continue;\n        target = fruit.apex.point;\n        strategy = 'predicted-apex';\n      } else if (speed >= 120 && (fruit.velocity.y >= -30 || fruit.ageFrames >= 10)) {\n        target = fruit.predict(45);\n        strategy = '45ms-intercept';\n      } else {\n        continue;\n      }\n\n      target = {\n        x: Math.max(arena.x, Math.min(arena.x + arena.width, target.x)),\n        y: Math.max(arena.y, Math.min(arena.y + arena.height, target.y)),\n      };\n      const radius = Math.max(fruit.bounds.width, fruit.bounds.height) / 2;\n      const halfSlash = Math.min(expectedDiameter * 0.72, radius * 0.85);\n      const x1 = Math.max(arena.x, target.x - halfSlash);\n      const y1 = Math.min(arena.y + arena.height, target.y + halfSlash * 0.35);\n      const x2 = Math.min(arena.x + arena.width, target.x + halfSlash);\n      const y2 = Math.max(arena.y, target.y - halfSlash * 0.35);\n\n      // Record the attempt before awaiting input, but only retire the track\n      // after it disappears. A fruit that remains visible gets one correction.\n      const nextSlashState = slashState || { attempts: 0, confirmed: false };\n      nextSlashState.attempts++;\n      nextSlashState.lastAttemptAt = sdk.elapsed();\n      nextSlashState.lastAttemptSequence = observation.frame.sequence;\n      slashStates.set(fruit.id, nextSlashState);\n      sdk.log({ phase: 'playing', trackId: fruit.id, strategy,\n        attempt: nextSlashState.attempts,\n        ageFrames: fruit.ageFrames, confidence: +fruit.confidence.toFixed(2),\n        observed: fruit.center, target,\n        velocity: fruit.velocity, acceleration: fruit.acceleration,\n        apexInMs: fruit.apex ? Math.round(fruit.apex.timeUntilMs) : null,\n        detectionMs: observation.detectionMs, slash: { x1, y1, x2, y2 } });\n      await sdk.dragMouse(x1, y1, x2, y2, { duration: 28 });\n      slashCount++;\n    }\n\n    if (sawFruit && now - lastFruitAt > 4500 && now - lastLifecycleAt > 4500) {\n      await handleLifecycle();\n    }\n  }\n\n  await sdk.runEvery(tick, 20, { requiredWindow });\n}\n",
-  "observedAfter": "",
-  "agentStatement": "The patch tool reported a clean application, but crossed the targeting and slash-state blocks and produced invalid TypeScript."
-}

package/tests/patching/imports.patch.txt

@@ -1,11 +0,0 @@
-@@ -5,7 +6,7 @@
- import React from 'react';
- import { Col, Row } from 'react-bootstrap';
-
--import { NameValueRow, NameValueRowWithBottomBorder } from '~/components/NameValueRow';
-+import { NameValueRow } from '~/components/NameValueRow';
- import { BOTTOM_BORDER_CONTAINER_STYLE } from '~/components/NameValueRow/NameValueRowWithBottomBorder';
- import { NotesPopoverWrapper } from '~/components/Notes';
- import { TokenAgreementRowAssetUnion, UpdateTokenAgreement, UpdateTokenAgreementVariables } from '~/generated/schema';
-
-

package/tests/patching/imports.test.ts

@@ -1,43 +0,0 @@
-import * as fs from "fs";
-import { parseHunks, fixPatch } from "../../src/agents/tools/patch";
-import { applyPatch } from "diff";
-
-describe("fixPatch", () => {
-  it("should fix patch", async () => {
-    const patch = fs.readFileSync(__dirname + "/imports.patch.txt").toString();
-    const originalContent = fs
-      .readFileSync(__dirname + "/imports.txt")
-      .toString();
-    const hunks = parseHunks(patch);
-
-    console.log(hunks);
-    expect(hunks.length).toBe(1);
-
-    expect(hunks[0].newStartLine).toBe(6);
-    expect(hunks[0].originalStartLine).toBe(5);
-
-    const fixedPatch = await fixPatch(originalContent, patch);
-    console.log(fixedPatch);
-
-    const patched = applyPatch(originalContent, fixedPatch);
-    console.log("PATCH OUTPUT");
-    console.log(patched);
-  });
-
-  it("should patch interface.text", async () => {
-    const patch = fs
-      .readFileSync(__dirname + "/interface.patch.txt")
-      .toString();
-    const originalContent = fs
-      .readFileSync(__dirname + "/interface.txt")
-      .toString();
-
-    const hunks = parseHunks(patch);
-    const fixedPatch = await fixPatch(originalContent, patch);
-    console.log(fixedPatch);
-
-    const patched = applyPatch(originalContent, fixedPatch);
-    console.log("PATCH OUTPUT");
-    console.log(patched);
-  });
-});

package/tests/patching/imports.txt

@@ -1,11 +0,0 @@
-import { gql, useMutation } from '@apollo/client';
-import React from 'react';
-import { Col, Row } from 'react-bootstrap';
-
-import InformationTooltip from '~/components/InformationTooltip';
-import Link from '~/components/Link';
-import { NameValueRow, NameValueRowWithBottomBorder } from '~/components/NameValueRow';
-import { BOTTOM_BORDER_CONTAINER_STYLE } from '~/components/NameValueRow/NameValueRowWithBottomBorder';
-import { NotesPopoverWrapper } from '~/components/Notes';
-import { TokenAgreementRowAssetUnion, UpdateTokenAgreement, UpdateTokenAgreementVariables } from '~/generated/schema';
-

package/tests/patching/interface.patch.txt

@@ -1,15 +0,0 @@
---- ./tests/patching/interface.txt
-+++ ./tests/patching/interface.txt
-@@ -3,8 +3,14 @@
- import { Message } from "../clients/types";
-
- export interface IAgent {
-+  getModel(): string;
-+  setModel(value: string): void;
-+  getProvider(): string;
-+  setProvider(value: string): void;
-   name: string;
-   description: string;
--  call: (userInput: string, messages?: Message[]) => Promise<string>;
-+  call: (userInput: string, messages?: Message[]) => Promise<string>;
- }

package/tests/patching/interface.txt

@@ -1,7 +0,0 @@
-import { Message } from "../clients/types";
-
-export interface IAgent {
-  name: string;
-  description: string;
-  call: (userInput: string, messages?: Message[]) => Promise<string>;
-}