@poncho-ai/harness 0.27.0 → 0.28.1

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/harness@0.27.0 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
+> @poncho-ai/harness@0.28.1 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 278.61 KB
-ESM ⚡️ Build success in 148ms
+ESM dist/index.js 288.74 KB
+ESM ⚡️ Build success in 135ms
 DTS Build start
-DTS ⚡️ Build success in 7054ms
-DTS dist/index.d.ts 29.13 KB
+DTS ⚡️ Build success in 6964ms
+DTS dist/index.d.ts 29.62 KB

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @poncho-ai/harness
 
+## 0.28.1
+
+### Patch Changes
+
+- [`4d50ad9`](https://github.com/cesr/poncho-ai/commit/4d50ad970886c9d3635ec36a407514c91ce6a71a) Thanks [@cesr](https://github.com/cesr)! - Improve callback-run reliability and streaming across subagent workflows, including safer concurrent approval handling and parent callback retriggers.
+
+  Add context window/token reporting through run completion events, improve cron/web UI rendering and approval streaming behavior, and harden built-in web search retry/throttle behavior.
+
+- Updated dependencies [[`4d50ad9`](https://github.com/cesr/poncho-ai/commit/4d50ad970886c9d3635ec36a407514c91ce6a71a)]:
+  - @poncho-ai/sdk@1.6.1
+
+## 0.28.0
+
+### Minor Changes
+
+- [`c0ca56b`](https://github.com/cesr/poncho-ai/commit/c0ca56b54bb877d96ba8088537d6f1c7461d2a55) Thanks [@cesr](https://github.com/cesr)! - Add built-in `web_search` and `web_fetch` tools so agents can search the web and fetch page content without a browser or API keys. Remove the scaffolded `fetch-page` skill (superseded by `web_fetch`). Fix `browser_open` crash when agent projects have an older `@poncho-ai/browser` installed.
+
 ## 0.27.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -188,6 +188,12 @@ interface ConversationStore {
     rename(conversationId: string, title: string): Promise<Conversation | undefined>;
     delete(conversationId: string): Promise<boolean>;
     appendSubagentResult(conversationId: string, result: PendingSubagentResult): Promise<void>;
+    /**
+     * Atomically clear `runningCallbackSince` without clobbering other fields.
+     * Returns the conversation as it exists after the clear (with current
+     * `pendingSubagentResults`).
+     */
+    clearCallbackLock(conversationId: string): Promise<Conversation | undefined>;
 }
 type StateProviderName = "local" | "memory" | "redis" | "upstash" | "dynamodb";
 interface StateConfig {
@@ -221,6 +227,7 @@ declare class InMemoryConversationStore implements ConversationStore {
     rename(conversationId: string, title: string): Promise<Conversation | undefined>;
     delete(conversationId: string): Promise<boolean>;
     appendSubagentResult(conversationId: string, result: PendingSubagentResult): Promise<void>;
+    clearCallbackLock(conversationId: string): Promise<Conversation | undefined>;
 }
 type ConversationSummary = {
     conversationId: string;
@@ -351,6 +358,8 @@ type BuiltInToolToggles = {
     todo_add?: boolean;
     todo_update?: boolean;
     todo_remove?: boolean;
+    web_search?: boolean;
+    web_fetch?: boolean;
 };
 interface MessagingChannelConfig {
     platform: "slack" | "resend" | "telegram";
@@ -738,6 +747,8 @@ declare class LatitudeCapture {
  */
 declare function jsonSchemaToZod(schema: JsonSchema): z.ZodType;
 
+declare const createSearchTools: () => ToolDefinition[];
+
 /**
  * Resolve the full list of skill directories to scan.
  * Merges the defaults with any extra paths provided via config.
@@ -813,4 +824,4 @@ declare class TelemetryEmitter {
 
 declare const createSubagentTools: (manager: SubagentManager) => 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 PendingSubagentResult, 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 SubagentSpawnResult, 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 };
+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 PendingSubagentResult, 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 SubagentSpawnResult, 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, createSearchTools, 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

@@ -4211,15 +4211,16 @@ var loadRunnableScriptFunction = async (scriptPath) => {
 };
 var loadScriptModule = async (scriptPath) => {
   const extension = extname(scriptPath).toLowerCase();
+  const cacheBust = `?t=${Date.now()}`;
   if (extension === ".ts" || extension === ".mts" || extension === ".cts") {
-    const jiti = createJiti2(import.meta.url, { interopDefault: true });
-    return await jiti.import(scriptPath);
+    const jiti = createJiti2(import.meta.url, { interopDefault: true, moduleCache: false });
+    return await jiti.import(scriptPath + cacheBust);
   }
   try {
-    return await import(pathToFileURL(scriptPath).href);
+    return await import(pathToFileURL(scriptPath).href + cacheBust);
   } catch {
-    const jiti = createJiti2(import.meta.url, { interopDefault: true });
-    return await jiti.import(scriptPath);
+    const jiti = createJiti2(import.meta.url, { interopDefault: true, moduleCache: false });
+    return await jiti.import(scriptPath + cacheBust);
   }
 };
 var extractRunnableFunction = (value) => {
@@ -4258,10 +4259,218 @@ var extractRunnableFunction = (value) => {
   return void 0;
 };
 
-// src/subagent-tools.ts
+// src/search-tools.ts
+import { load as cheerioLoad } from "cheerio";
 import { defineTool as defineTool5 } from "@poncho-ai/sdk";
-var createSubagentTools = (manager) => [
+var SEARCH_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36";
+var FETCH_TIMEOUT_MS = 15e3;
+var SEARCH_MAX_RETRIES = 4;
+var SEARCH_INITIAL_DELAY_MS = 2e3;
+var SEARCH_MIN_INTERVAL_MS = 4e3;
+var SEARCH_FALLBACK_COOLDOWN_MS = 12e3;
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var searchQueue = Promise.resolve();
+var nextSearchAllowedAt = 0;
+function parseRetryAfterMs(retryAfterHeader) {
+  if (!retryAfterHeader) return SEARCH_FALLBACK_COOLDOWN_MS;
+  const asSeconds = Number(retryAfterHeader);
+  if (Number.isFinite(asSeconds) && asSeconds >= 0) {
+    return Math.max(Math.floor(asSeconds * 1e3), SEARCH_MIN_INTERVAL_MS);
+  }
+  const asDate = new Date(retryAfterHeader).getTime();
+  if (Number.isFinite(asDate)) {
+    return Math.max(asDate - Date.now(), SEARCH_MIN_INTERVAL_MS);
+  }
+  return SEARCH_FALLBACK_COOLDOWN_MS;
+}
+function applyRateLimitCooldown(retryAfterHeader) {
+  const cooldownMs = parseRetryAfterMs(retryAfterHeader);
+  nextSearchAllowedAt = Math.max(nextSearchAllowedAt, Date.now() + cooldownMs);
+}
+async function runWithSearchThrottle(fn) {
+  const previous = searchQueue;
+  let release;
+  searchQueue = new Promise((resolve12) => {
+    release = resolve12;
+  });
+  await previous.catch(() => {
+  });
+  try {
+    const waitMs = nextSearchAllowedAt - Date.now();
+    if (waitMs > 0) {
+      await sleep(waitMs);
+    }
+    const result = await fn();
+    nextSearchAllowedAt = Math.max(nextSearchAllowedAt, Date.now() + SEARCH_MIN_INTERVAL_MS);
+    return result;
+  } finally {
+    release?.();
+  }
+}
+function isRetryableStatus(status) {
+  return status === 429 || status === 503 || status >= 500;
+}
+async function braveSearch(query, maxResults) {
+  const url = `https://search.brave.com/search?q=${encodeURIComponent(query)}`;
+  let lastError;
+  for (let attempt = 0; attempt < SEARCH_MAX_RETRIES; attempt++) {
+    if (attempt > 0) {
+      const delay = SEARCH_INITIAL_DELAY_MS * 2 ** (attempt - 1) + Math.floor(Math.random() * 500);
+      await sleep(delay);
+    }
+    try {
+      const html = await runWithSearchThrottle(async () => {
+        const res = await fetch(url, {
+          headers: {
+            "User-Agent": SEARCH_UA,
+            Accept: "text/html,application/xhtml+xml",
+            "Accept-Language": "en-US,en;q=0.9"
+          },
+          signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+        });
+        if (!res.ok) {
+          if (res.status === 429) {
+            applyRateLimitCooldown(res.headers.get("retry-after"));
+          }
+          const error = new Error(`Search request failed (${res.status} ${res.statusText})`);
+          if (isRetryableStatus(res.status)) {
+            throw error;
+          }
+          error.retryable = false;
+          throw error;
+        }
+        return await res.text();
+      });
+      return parseBraveResults(html, maxResults);
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+      if (lastError.retryable === false) {
+        throw lastError;
+      }
+      if (attempt < SEARCH_MAX_RETRIES - 1) continue;
+    }
+  }
+  throw lastError ?? new Error("Search failed after retries");
+}
+function parseBraveResults(html, max) {
+  const $ = cheerioLoad(html);
+  const results = [];
+  $('div.snippet[data-type="web"]').each((_i, el) => {
+    if (results.length >= max) return false;
+    const $el = $(el);
+    const anchor = $el.find(".result-content a").first();
+    const href = anchor.attr("href") ?? "";
+    if (!href.startsWith("http")) return;
+    const title = $el.find(".title").first().text().trim();
+    const snippet = $el.find(".generic-snippet .content").first().text().trim();
+    if (title) {
+      results.push({ title, url: href, snippet });
+    }
+  });
+  return results;
+}
+var DEFAULT_MAX_LENGTH = 16e3;
+function extractReadableText($, maxLength) {
+  const title = $("title").first().text().trim();
+  $("script, style, noscript, nav, footer, header, aside, [role='navigation'], [role='banner'], [role='contentinfo']").remove();
+  $("svg, iframe, form, button, input, select, textarea").remove();
+  let root = $("article").first();
+  if (!root.length) root = $("main").first();
+  if (!root.length) root = $("[role='main']").first();
+  if (!root.length) root = $("body").first();
+  const text = root.text().replace(/[ \t]+/g, " ").replace(/\n{3,}/g, "\n\n").trim();
+  const content = text.length > maxLength ? text.slice(0, maxLength) + "\n\u2026(truncated)" : text;
+  return { title, content };
+}
+var createSearchTools = () => [
+  defineTool5({
+    name: "web_search",
+    description: "Search the web and return a list of results (title, URL, snippet). Use this instead of opening a browser when you need to find information online.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "The search query"
+        },
+        max_results: {
+          type: "number",
+          description: "Maximum number of results to return (1-10, default 5)"
+        }
+      },
+      required: ["query"],
+      additionalProperties: false
+    },
+    handler: async (input) => {
+      const query = typeof input.query === "string" ? input.query.trim() : "";
+      if (!query) {
+        return { error: "A non-empty query string is required." };
+      }
+      const max = Math.min(Math.max(Number(input.max_results) || 5, 1), 10);
+      try {
+        const results = await braveSearch(query, max);
+        if (results.length === 0) {
+          return { query, results: [], note: "No results found. Try rephrasing your query." };
+        }
+        return { query, results };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+          error: `Search failed: ${msg}`,
+          hint: "The search provider may be rate-limiting requests. Try again shortly, or use browser tools as a fallback."
+        };
+      }
+    }
+  }),
   defineTool5({
+    name: "web_fetch",
+    description: "Fetch a web page and return its text content (HTML tags stripped). Useful for reading articles, documentation, or any web page without opening a browser.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        url: {
+          type: "string",
+          description: "The URL to fetch"
+        },
+        max_length: {
+          type: "number",
+          description: `Maximum character length of returned content (default ${DEFAULT_MAX_LENGTH})`
+        }
+      },
+      required: ["url"],
+      additionalProperties: false
+    },
+    handler: async (input) => {
+      const url = typeof input.url === "string" ? input.url.trim() : "";
+      if (!url) {
+        return { error: 'A "url" string is required.' };
+      }
+      const maxLength = Math.max(Number(input.max_length) || DEFAULT_MAX_LENGTH, 1e3);
+      try {
+        const res = await fetch(url, {
+          headers: { "User-Agent": SEARCH_UA, Accept: "text/html,application/xhtml+xml" },
+          redirect: "follow",
+          signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+        });
+        if (!res.ok) {
+          return { url, status: res.status, error: res.statusText };
+        }
+        const html = await res.text();
+        const $ = cheerioLoad(html);
+        const { title, content } = extractReadableText($, maxLength);
+        return { url, status: res.status, title, content };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { url, error: `Fetch failed: ${msg}` };
+      }
+    }
+  })
+];
+
+// src/subagent-tools.ts
+import { defineTool as defineTool6 } from "@poncho-ai/sdk";
+var createSubagentTools = (manager) => [
+  defineTool6({
     name: "spawn_subagent",
     description: "Spawn a subagent to work on a task in the background. Returns immediately with a subagent ID. The subagent runs independently and its result will be delivered to you as a message in the conversation when it completes.\n\nGuidelines:\n- Spawn all needed subagents in a SINGLE response (they run concurrently), then end your turn with a brief message to the user.\n- Do NOT spawn more subagents in follow-up steps. Wait for results to be delivered before deciding if more work is needed.\n- Prefer doing work yourself for simple or quick tasks. Spawn subagents for substantial, self-contained work.\n- The subagent has no memory of your conversation -- write thorough, self-contained instructions in the task.",
     inputSchema: {
@@ -4293,7 +4502,7 @@ var createSubagentTools = (manager) => [
       return { subagentId, status: "running" };
     }
   }),
-  defineTool5({
+  defineTool6({
     name: "message_subagent",
     description: "Send a follow-up message to a completed or stopped subagent. The subagent restarts in the background and its result will be delivered to you as a message when it completes. Only works when the subagent is not currently running.",
     inputSchema: {
@@ -4321,7 +4530,7 @@ var createSubagentTools = (manager) => [
       return { subagentId: id, status: "running" };
     }
   }),
-  defineTool5({
+  defineTool6({
     name: "stop_subagent",
     description: "Stop a running subagent. The subagent's conversation is preserved but it will stop processing. Use this to cancel work that is no longer needed.",
     inputSchema: {
@@ -4344,7 +4553,7 @@ var createSubagentTools = (manager) => [
       return { message: `Subagent "${subagentId}" has been stopped.` };
     }
   }),
-  defineTool5({
+  defineTool6({
     name: "list_subagents",
     description: "List all subagents that have been spawned in this conversation. Returns each subagent's ID, original task, current status, and message count. Use this to look up subagent IDs before calling message_subagent or stop_subagent.",
     inputSchema: {
@@ -4970,6 +5179,11 @@ var AgentHarness = class _AgentHarness {
     if (this.isToolEnabled("delete_directory")) {
       this.registerIfMissing(createDeleteDirectoryTool(this.workingDir));
     }
+    for (const tool of createSearchTools()) {
+      if (this.isToolEnabled(tool.name)) {
+        this.registerIfMissing(tool);
+      }
+    }
     if (this.environment === "development" && this.isToolEnabled("poncho_docs")) {
       this.registerIfMissing(ponchoDocsTool);
     }
@@ -5455,7 +5669,11 @@ var AgentHarness = class _AgentHarness {
     const session = new browserMod.BrowserSession(sessionId, browserCfg);
     this._browserSession = session;
     const tools = browserMod.createBrowserTools(
-      () => session
+      () => session,
+      // Backward compat: older @poncho-ai/browser versions expect a second
+      // getConversationId callback.  Current versions read from ToolContext
+      // and ignore extra args.
+      () => "__default__"
     );
     for (const tool of tools) {
       if (this.isToolEnabled(tool.name)) {
@@ -5733,6 +5951,8 @@ ${this.skillFingerprint}`;
     let totalOutputTokens = 0;
     let totalCachedTokens = 0;
     let transientStepRetryCount = 0;
+    let latestContextTokens = 0;
+    let toolOutputEstimateSinceModel = 0;
     let cachedCoreMessages = [];
     let convertedUpTo = 0;
     for (let step = 1; step <= maxSteps; step += 1) {
@@ -5762,7 +5982,9 @@ ${this.skillFingerprint}`;
             duration: now() - start,
             continuation: true,
             continuationMessages: [...messages],
-            maxSteps
+            maxSteps,
+            contextTokens: latestContextTokens + toolOutputEstimateSinceModel,
+            contextWindow
           };
           yield pushEvent({ type: "run:completed", runId, result: result2 });
           return;
@@ -6002,10 +6224,13 @@ ${textContent}` };
               if (emittedMessages.length > 0 && emittedMessages[emittedMessages.length - 1].role === "user") {
                 emittedMessages.pop();
               }
+              const tokensAfterCompaction = estimateTotalTokens(integrityPrompt, messages, toolDefsJson);
+              latestContextTokens = tokensAfterCompaction;
+              toolOutputEstimateSinceModel = 0;
               yield pushEvent({
                 type: "compaction:completed",
                 tokensBefore: effectiveTokens,
-                tokensAfter: estimateTotalTokens(integrityPrompt, messages, toolDefsJson),
+                tokensAfter: tokensAfterCompaction,
                 messagesBefore: compactResult.messagesBefore,
                 compactedMessages: emittedMessages,
                 messagesAfter: compactResult.messagesAfter
@@ -6152,13 +6377,16 @@ ${textContent}` };
         const usage = await result.usage;
         const toolCallsResult = await result.toolCalls;
         const stepCachedTokens = usage.inputTokenDetails?.cacheReadTokens ?? 0;
-        totalInputTokens += usage.inputTokens ?? 0;
+        const stepInputTokens = usage.inputTokens ?? 0;
+        totalInputTokens += stepInputTokens;
         totalOutputTokens += usage.outputTokens ?? 0;
         totalCachedTokens += stepCachedTokens;
+        latestContextTokens = stepInputTokens;
+        toolOutputEstimateSinceModel = 0;
         yield pushEvent({
           type: "model:response",
           usage: {
-            input: usage.inputTokens ?? 0,
+            input: stepInputTokens,
             output: usage.outputTokens ?? 0,
             cached: stepCachedTokens
           }
@@ -6204,7 +6432,9 @@ ${textContent}` };
               output: totalOutputTokens,
               cached: totalCachedTokens
             },
-            duration: now() - start
+            duration: now() - start,
+            contextTokens: latestContextTokens + toolOutputEstimateSinceModel,
+            contextWindow
           };
           yield pushEvent({ type: "run:completed", runId, result: result2 });
           return;
@@ -6332,6 +6562,7 @@ ${textContent}` };
             span?.end({ result: { value: result2.output ?? null, isError: false } });
             const serialized = JSON.stringify(result2.output ?? null);
             const outputTokenEstimate = Math.ceil(serialized.length / 4);
+            toolOutputEstimateSinceModel += outputTokenEstimate;
             yield pushEvent({
               type: "tool:completed",
               tool: result2.tool,
@@ -6442,7 +6673,9 @@ ${this.skillFingerprint}`;
         duration: now() - start,
         continuation: true,
         continuationMessages: [...messages],
-        maxSteps
+        maxSteps,
+        contextTokens: latestContextTokens + toolOutputEstimateSinceModel,
+        contextWindow
       };
       yield pushEvent({ type: "run:completed", runId, result });
     } else {
@@ -6770,6 +7003,13 @@ var InMemoryConversationStore = class {
     conversation.pendingSubagentResults.push(result);
     conversation.updatedAt = Date.now();
   }
+  async clearCallbackLock(conversationId) {
+    const conversation = this.conversations.get(conversationId);
+    if (!conversation) return void 0;
+    conversation.runningCallbackSince = void 0;
+    conversation.updatedAt = Date.now();
+    return conversation;
+  }
 };
 var FileConversationStore = class {
   workingDir;
@@ -6992,6 +7232,28 @@ var FileConversationStore = class {
     conversation.updatedAt = Date.now();
     await this.update(conversation);
   }
+  async clearCallbackLock(conversationId) {
+    await this.ensureLoaded();
+    const summary = this.conversations.get(conversationId);
+    if (!summary) return void 0;
+    const { conversationsDir } = await this.resolvePaths();
+    const filePath = resolve11(conversationsDir, summary.fileName);
+    let result;
+    this.writing = this.writing.then(async () => {
+      const conv = await this.readConversationFile(summary.fileName);
+      if (!conv) return;
+      conv.runningCallbackSince = void 0;
+      conv.updatedAt = Date.now();
+      await writeJsonAtomic3(filePath, conv);
+      this.conversations.set(conversationId, {
+        ...summary,
+        updatedAt: conv.updatedAt
+      });
+      result = conv;
+    });
+    await this.writing;
+    return result;
+  }
 };
 var FileStateStore = class {
   workingDir;
@@ -7332,6 +7594,18 @@ var KeyValueConversationStoreBase = class {
       await this.update(conversation);
     });
   }
+  async clearCallbackLock(conversationId) {
+    let result;
+    await this.withAppendLock(conversationId, async () => {
+      const conversation = await this.get(conversationId);
+      if (!conversation) return;
+      conversation.runningCallbackSince = void 0;
+      conversation.updatedAt = Date.now();
+      await this.update(conversation);
+      result = conversation;
+    });
+    return result;
+  }
 };
 var UpstashConversationStore = class extends KeyValueConversationStoreBase {
   baseUrl;
@@ -7782,7 +8056,7 @@ var TelemetryEmitter = class {
 };
 
 // src/index.ts
-import { defineTool as defineTool6 } from "@poncho-ai/sdk";
+import { defineTool as defineTool7 } from "@poncho-ai/sdk";
 export {
   AgentHarness,
   InMemoryConversationStore,
@@ -7807,12 +8081,13 @@ export {
   createMemoryStore,
   createMemoryTools,
   createModelProvider,
+  createSearchTools,
   createSkillTools,
   createStateStore,
   createSubagentTools,
   createUploadStore,
   createWriteTool,
-  defineTool6 as defineTool,
+  defineTool7 as defineTool,
   deriveUploadKey,
   ensureAgentIdentity,
   estimateTokens,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/harness",
-  "version": "0.27.0",
+  "version": "0.28.1",
   "description": "Agent execution runtime - conversation loop, tool dispatch, streaming",
   "repository": {
     "type": "git",
@@ -26,12 +26,13 @@
     "@latitude-data/telemetry": "^2.0.4",
     "@opentelemetry/api": "1.9.0",
     "ai": "^6.0.86",
+    "cheerio": "^1.2.0",
     "jiti": "^2.6.1",
     "mustache": "^4.2.0",
     "redis": "^5.10.0",
     "yaml": "^2.4.0",
     "zod": "^3.22.0",
-    "@poncho-ai/sdk": "1.6.0"
+    "@poncho-ai/sdk": "1.6.1"
   },
   "devDependencies": {
     "@types/mustache": "^4.2.6",

package/src/config.ts

@@ -46,6 +46,8 @@ export type BuiltInToolToggles = {
   todo_add?: boolean;
   todo_update?: boolean;
   todo_remove?: boolean;
+  web_search?: boolean;
+  web_fetch?: boolean;
 };
 
 export interface MessagingChannelConfig {

package/src/harness.ts

@@ -32,6 +32,7 @@ import { addPromptCacheBreakpoints } from "./prompt-cache.js";
 import { jsonSchemaToZod } from "./schema-converter.js";
 import type { SkillMetadata } from "./skill-context.js";
 import { createSkillTools, normalizeScriptPolicyPath } from "./skill-tools.js";
+import { createSearchTools } from "./search-tools.js";
 import { createSubagentTools } from "./subagent-tools.js";
 import type { SubagentManager } from "./subagent-manager.js";
 import { LatitudeTelemetry } from "@latitude-data/telemetry";
@@ -562,7 +563,7 @@ export class AgentHarness {
   private insideTelemetryCapture = false;
   private _browserSession?: unknown;
   private _browserMod?: {
-    createBrowserTools: (getSession: () => unknown) => ToolDefinition[];
+    createBrowserTools: (getSession: () => unknown, getConversationId?: () => string) => ToolDefinition[];
     BrowserSession: new (sessionId: string, config: Record<string, unknown>) => unknown;
   };
 
@@ -644,6 +645,11 @@ export class AgentHarness {
     if (this.isToolEnabled("delete_directory")) {
       this.registerIfMissing(createDeleteDirectoryTool(this.workingDir));
     }
+    for (const tool of createSearchTools()) {
+      if (this.isToolEnabled(tool.name)) {
+        this.registerIfMissing(tool);
+      }
+    }
     if (this.environment === "development" && this.isToolEnabled("poncho_docs")) {
       this.registerIfMissing(ponchoDocsTool);
     }
@@ -1161,7 +1167,7 @@ export class AgentHarness {
   private async initBrowserTools(config: PonchoConfig): Promise<void> {
     const spec = ["@poncho-ai", "browser"].join("/");
     let browserMod: {
-      createBrowserTools: (getSession: () => unknown) => ToolDefinition[];
+      createBrowserTools: (getSession: () => unknown, getConversationId?: () => string) => ToolDefinition[];
       BrowserSession: new (sessionId: string, cfg?: Record<string, unknown>) => unknown;
     };
     try {
@@ -1205,6 +1211,10 @@ export class AgentHarness {
 
     const tools = browserMod.createBrowserTools(
       () => session,
+      // Backward compat: older @poncho-ai/browser versions expect a second
+      // getConversationId callback.  Current versions read from ToolContext
+      // and ignore extra args.
+      () => "__default__",
     );
     for (const tool of tools) {
       if (this.isToolEnabled(tool.name)) {
@@ -1544,6 +1554,8 @@ ${boundedMainMemory.trim()}`
     let totalOutputTokens = 0;
     let totalCachedTokens = 0;
     let transientStepRetryCount = 0;
+    let latestContextTokens = 0;
+    let toolOutputEstimateSinceModel = 0;
     let cachedCoreMessages: ModelMessage[] = [];
     let convertedUpTo = 0;
 
@@ -1575,6 +1587,8 @@ ${boundedMainMemory.trim()}`
             continuation: true,
             continuationMessages: [...messages],
             maxSteps,
+            contextTokens: latestContextTokens + toolOutputEstimateSinceModel,
+            contextWindow,
           };
           yield pushEvent({ type: "run:completed", runId, result });
           return;
@@ -1875,10 +1889,13 @@ ${boundedMainMemory.trim()}`
               if (emittedMessages.length > 0 && emittedMessages[emittedMessages.length - 1].role === "user") {
                 emittedMessages.pop();
               }
+              const tokensAfterCompaction = estimateTotalTokens(integrityPrompt, messages, toolDefsJson);
+              latestContextTokens = tokensAfterCompaction;
+              toolOutputEstimateSinceModel = 0;
               yield pushEvent({
                 type: "compaction:completed",
                 tokensBefore: effectiveTokens,
-                tokensAfter: estimateTotalTokens(integrityPrompt, messages, toolDefsJson),
+                tokensAfter: tokensAfterCompaction,
                 messagesBefore: compactResult.messagesBefore!,
                 compactedMessages: emittedMessages,
                 messagesAfter: compactResult.messagesAfter!,
@@ -2050,14 +2067,17 @@ ${boundedMainMemory.trim()}`
 
       // Update token usage
       const stepCachedTokens = usage.inputTokenDetails?.cacheReadTokens ?? 0;
-      totalInputTokens += usage.inputTokens ?? 0;
+      const stepInputTokens = usage.inputTokens ?? 0;
+      totalInputTokens += stepInputTokens;
       totalOutputTokens += usage.outputTokens ?? 0;
       totalCachedTokens += stepCachedTokens;
+      latestContextTokens = stepInputTokens;
+      toolOutputEstimateSinceModel = 0;
 
       yield pushEvent({
         type: "model:response",
         usage: {
-          input: usage.inputTokens ?? 0,
+          input: stepInputTokens,
           output: usage.outputTokens ?? 0,
           cached: stepCachedTokens,
         },
@@ -2110,6 +2130,8 @@ ${boundedMainMemory.trim()}`
             cached: totalCachedTokens,
           },
           duration: now() - start,
+          contextTokens: latestContextTokens + toolOutputEstimateSinceModel,
+          contextWindow,
         };
         yield pushEvent({ type: "run:completed", runId, result });
         return;
@@ -2280,6 +2302,7 @@ ${boundedMainMemory.trim()}`
           span?.end({ result: { value: result.output ?? null, isError: false } });
           const serialized = JSON.stringify(result.output ?? null);
           const outputTokenEstimate = Math.ceil(serialized.length / 4);
+          toolOutputEstimateSinceModel += outputTokenEstimate;
           yield pushEvent({
             type: "tool:completed",
             tool: result.tool,
@@ -2405,6 +2428,8 @@ ${boundedMainMemory.trim()}`
         continuation: true,
         continuationMessages: [...messages],
         maxSteps,
+        contextTokens: latestContextTokens + toolOutputEstimateSinceModel,
+        contextWindow,
       };
       yield pushEvent({ type: "run:completed", runId, result });
     } else {

package/src/index.ts

@@ -9,6 +9,7 @@ export * from "./memory.js";
 export * from "./mcp.js";
 export * from "./model-factory.js";
 export * from "./schema-converter.js";
+export * from "./search-tools.js";
 export * from "./skill-context.js";
 export * from "./skill-tools.js";
 export * from "./state.js";

package/src/search-tools.ts

@@ -0,0 +1,267 @@
+import { load as cheerioLoad, type CheerioAPI } from "cheerio";
+import { defineTool, type ToolDefinition } from "@poncho-ai/sdk";
+
+const SEARCH_UA =
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36";
+
+const FETCH_TIMEOUT_MS = 15_000;
+
+const SEARCH_MAX_RETRIES = 4;
+const SEARCH_INITIAL_DELAY_MS = 2_000;
+const SEARCH_MIN_INTERVAL_MS = 4_000;
+const SEARCH_FALLBACK_COOLDOWN_MS = 12_000;
+
+const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+// ---------------------------------------------------------------------------
+// web_search — Brave Search HTML scraping (no API key)
+// ---------------------------------------------------------------------------
+
+interface SearchResult {
+  title: string;
+  url: string;
+  snippet: string;
+}
+
+let searchQueue: Promise<void> = Promise.resolve();
+let nextSearchAllowedAt = 0;
+
+function parseRetryAfterMs(retryAfterHeader: string | null): number {
+  if (!retryAfterHeader) return SEARCH_FALLBACK_COOLDOWN_MS;
+  const asSeconds = Number(retryAfterHeader);
+  if (Number.isFinite(asSeconds) && asSeconds >= 0) {
+    return Math.max(Math.floor(asSeconds * 1000), SEARCH_MIN_INTERVAL_MS);
+  }
+  const asDate = new Date(retryAfterHeader).getTime();
+  if (Number.isFinite(asDate)) {
+    return Math.max(asDate - Date.now(), SEARCH_MIN_INTERVAL_MS);
+  }
+  return SEARCH_FALLBACK_COOLDOWN_MS;
+}
+
+function applyRateLimitCooldown(retryAfterHeader: string | null): void {
+  const cooldownMs = parseRetryAfterMs(retryAfterHeader);
+  nextSearchAllowedAt = Math.max(nextSearchAllowedAt, Date.now() + cooldownMs);
+}
+
+async function runWithSearchThrottle<T>(fn: () => Promise<T>): Promise<T> {
+  const previous = searchQueue;
+  let release: (() => void) | undefined;
+  searchQueue = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+
+  await previous.catch(() => {});
+  try {
+    const waitMs = nextSearchAllowedAt - Date.now();
+    if (waitMs > 0) {
+      await sleep(waitMs);
+    }
+    const result = await fn();
+    nextSearchAllowedAt = Math.max(nextSearchAllowedAt, Date.now() + SEARCH_MIN_INTERVAL_MS);
+    return result;
+  } finally {
+    release?.();
+  }
+}
+
+function isRetryableStatus(status: number): boolean {
+  return status === 429 || status === 503 || status >= 500;
+}
+
+async function braveSearch(query: string, maxResults: number): Promise<SearchResult[]> {
+  const url = `https://search.brave.com/search?q=${encodeURIComponent(query)}`;
+
+  let lastError: Error | undefined;
+  for (let attempt = 0; attempt < SEARCH_MAX_RETRIES; attempt++) {
+    if (attempt > 0) {
+      const delay = SEARCH_INITIAL_DELAY_MS * 2 ** (attempt - 1) + Math.floor(Math.random() * 500);
+      await sleep(delay);
+    }
+
+    try {
+      const html = await runWithSearchThrottle(async () => {
+        const res = await fetch(url, {
+          headers: {
+            "User-Agent": SEARCH_UA,
+            Accept: "text/html,application/xhtml+xml",
+            "Accept-Language": "en-US,en;q=0.9",
+          },
+          signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+
+        if (!res.ok) {
+          if (res.status === 429) {
+            applyRateLimitCooldown(res.headers.get("retry-after"));
+          }
+          const error = new Error(`Search request failed (${res.status} ${res.statusText})`);
+          if (isRetryableStatus(res.status)) {
+            throw error;
+          }
+          // Non-retryable status: surface immediately.
+          (error as Error & { retryable?: boolean }).retryable = false;
+          throw error;
+        }
+
+        return await res.text();
+      });
+
+      return parseBraveResults(html, maxResults);
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+      if ((lastError as Error & { retryable?: boolean }).retryable === false) {
+        throw lastError;
+      }
+      if (attempt < SEARCH_MAX_RETRIES - 1) continue;
+    }
+  }
+
+  throw lastError ?? new Error("Search failed after retries");
+}
+
+function parseBraveResults(html: string, max: number): SearchResult[] {
+  const $ = cheerioLoad(html);
+  const results: SearchResult[] = [];
+
+  $('div.snippet[data-type="web"]').each((_i, el) => {
+    if (results.length >= max) return false;
+
+    const $el = $(el);
+    const anchor = $el.find(".result-content a").first();
+    const href = anchor.attr("href") ?? "";
+    if (!href.startsWith("http")) return;
+
+    const title = $el.find(".title").first().text().trim();
+    const snippet = $el.find(".generic-snippet .content").first().text().trim();
+
+    if (title) {
+      results.push({ title, url: href, snippet });
+    }
+  });
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// web_fetch — fetch a URL and extract readable text via cheerio
+// ---------------------------------------------------------------------------
+
+const DEFAULT_MAX_LENGTH = 16_000;
+
+function extractReadableText($: CheerioAPI, maxLength: number): { title: string; content: string } {
+  const title = $("title").first().text().trim();
+
+  $("script, style, noscript, nav, footer, header, aside, [role='navigation'], [role='banner'], [role='contentinfo']").remove();
+  $("svg, iframe, form, button, input, select, textarea").remove();
+
+  let root = $("article").first();
+  if (!root.length) root = $("main").first();
+  if (!root.length) root = $("[role='main']").first();
+  if (!root.length) root = $("body").first();
+
+  const text = root
+    .text()
+    .replace(/[ \t]+/g, " ")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+
+  const content =
+    text.length > maxLength ? text.slice(0, maxLength) + "\n…(truncated)" : text;
+
+  return { title, content };
+}
+
+// ---------------------------------------------------------------------------
+// Tool definitions
+// ---------------------------------------------------------------------------
+
+export const createSearchTools = (): ToolDefinition[] => [
+  defineTool({
+    name: "web_search",
+    description:
+      "Search the web and return a list of results (title, URL, snippet). " +
+      "Use this instead of opening a browser when you need to find information online.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "The search query",
+        },
+        max_results: {
+          type: "number",
+          description: "Maximum number of results to return (1-10, default 5)",
+        },
+      },
+      required: ["query"],
+      additionalProperties: false,
+    },
+    handler: async (input) => {
+      const query = typeof input.query === "string" ? input.query.trim() : "";
+      if (!query) {
+        return { error: "A non-empty query string is required." };
+      }
+      const max = Math.min(Math.max(Number(input.max_results) || 5, 1), 10);
+      try {
+        const results = await braveSearch(query, max);
+        if (results.length === 0) {
+          return { query, results: [], note: "No results found. Try rephrasing your query." };
+        }
+        return { query, results };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+          error: `Search failed: ${msg}`,
+          hint: "The search provider may be rate-limiting requests. Try again shortly, or use browser tools as a fallback.",
+        };
+      }
+    },
+  }),
+
+  defineTool({
+    name: "web_fetch",
+    description:
+      "Fetch a web page and return its text content (HTML tags stripped). " +
+      "Useful for reading articles, documentation, or any web page without opening a browser.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        url: {
+          type: "string",
+          description: "The URL to fetch",
+        },
+        max_length: {
+          type: "number",
+          description: `Maximum character length of returned content (default ${DEFAULT_MAX_LENGTH})`,
+        },
+      },
+      required: ["url"],
+      additionalProperties: false,
+    },
+    handler: async (input) => {
+      const url = typeof input.url === "string" ? input.url.trim() : "";
+      if (!url) {
+        return { error: 'A "url" string is required.' };
+      }
+      const maxLength = Math.max(Number(input.max_length) || DEFAULT_MAX_LENGTH, 1_000);
+
+      try {
+        const res = await fetch(url, {
+          headers: { "User-Agent": SEARCH_UA, Accept: "text/html,application/xhtml+xml" },
+          redirect: "follow",
+          signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+        if (!res.ok) {
+          return { url, status: res.status, error: res.statusText };
+        }
+        const html = await res.text();
+        const $ = cheerioLoad(html);
+        const { title, content } = extractReadableText($, maxLength);
+        return { url, status: res.status, title, content };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { url, error: `Fetch failed: ${msg}` };
+      }
+    },
+  }),
+];

package/src/skill-tools.ts

@@ -412,17 +412,19 @@ const loadRunnableScriptFunction = async (
 
 const loadScriptModule = async (scriptPath: string): Promise<unknown> => {
   const extension = extname(scriptPath).toLowerCase();
-  // Node emits noisy warnings when attempting native ESM import on TypeScript
-  // files in serverless environments. Use jiti first for TS entrypoints.
+  // Both Node's native import() and jiti cache modules by URL/path.
+  // Append a cache-busting query string so edits made by the agent are
+  // picked up on the next run_skill_script call.
+  const cacheBust = `?t=${Date.now()}`;
   if (extension === ".ts" || extension === ".mts" || extension === ".cts") {
-    const jiti = createJiti(import.meta.url, { interopDefault: true });
-    return await jiti.import(scriptPath);
+    const jiti = createJiti(import.meta.url, { interopDefault: true, moduleCache: false });
+    return await jiti.import(scriptPath + cacheBust);
   }
   try {
-    return await import(pathToFileURL(scriptPath).href);
+    return await import(pathToFileURL(scriptPath).href + cacheBust);
   } catch {
-    const jiti = createJiti(import.meta.url, { interopDefault: true });
-    return await jiti.import(scriptPath);
+    const jiti = createJiti(import.meta.url, { interopDefault: true, moduleCache: false });
+    return await jiti.import(scriptPath + cacheBust);
   }
 };
 

package/src/state.ts

@@ -84,6 +84,12 @@ export interface ConversationStore {
   rename(conversationId: string, title: string): Promise<Conversation | undefined>;
   delete(conversationId: string): Promise<boolean>;
   appendSubagentResult(conversationId: string, result: PendingSubagentResult): Promise<void>;
+  /**
+   * Atomically clear `runningCallbackSince` without clobbering other fields.
+   * Returns the conversation as it exists after the clear (with current
+   * `pendingSubagentResults`).
+   */
+  clearCallbackLock(conversationId: string): Promise<Conversation | undefined>;
 }
 
 export type StateProviderName =
@@ -325,6 +331,14 @@ export class InMemoryConversationStore implements ConversationStore {
     conversation.pendingSubagentResults.push(result);
     conversation.updatedAt = Date.now();
   }
+
+  async clearCallbackLock(conversationId: string): Promise<Conversation | undefined> {
+    const conversation = this.conversations.get(conversationId);
+    if (!conversation) return undefined;
+    conversation.runningCallbackSince = undefined;
+    conversation.updatedAt = Date.now();
+    return conversation;
+  }
 }
 
 export type ConversationSummary = {
@@ -607,6 +621,31 @@ class FileConversationStore implements ConversationStore {
     conversation.updatedAt = Date.now();
     await this.update(conversation);
   }
+
+  async clearCallbackLock(conversationId: string): Promise<Conversation | undefined> {
+    await this.ensureLoaded();
+    const summary = this.conversations.get(conversationId);
+    if (!summary) return undefined;
+    const { conversationsDir } = await this.resolvePaths();
+    const filePath = resolve(conversationsDir, summary.fileName);
+    let result: Conversation | undefined;
+    // Read inside the writing chain so we see the latest state after any
+    // pending appendSubagentResult writes have flushed.
+    this.writing = this.writing.then(async () => {
+      const conv = await this.readConversationFile(summary.fileName);
+      if (!conv) return;
+      conv.runningCallbackSince = undefined;
+      conv.updatedAt = Date.now();
+      await writeJsonAtomic(filePath, conv);
+      this.conversations.set(conversationId, {
+        ...summary,
+        updatedAt: conv.updatedAt,
+      });
+      result = conv;
+    });
+    await this.writing;
+    return result;
+  }
 }
 
 type LocalStateFile = {
@@ -1005,6 +1044,19 @@ abstract class KeyValueConversationStoreBase implements ConversationStore {
       await this.update(conversation);
     });
   }
+
+  async clearCallbackLock(conversationId: string): Promise<Conversation | undefined> {
+    let result: Conversation | undefined;
+    await this.withAppendLock(conversationId, async () => {
+      const conversation = await this.get(conversationId);
+      if (!conversation) return;
+      conversation.runningCallbackSince = undefined;
+      conversation.updatedAt = Date.now();
+      await this.update(conversation);
+      result = conversation;
+    });
+    return result;
+  }
 }
 
 class UpstashConversationStore extends KeyValueConversationStoreBase {