@poncho-ai/harness 0.59.19 → 0.60.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/harness@0.59.19 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
+> @poncho-ai/harness@0.60.0 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
 > node scripts/embed-docs.js && tsup src/index.ts --format esm --dts
 
 [embed-docs] Generated poncho-docs.ts with 4 topics
@@ -9,8 +9,8 @@
 CLI Target: es2022
 ESM Build start
 ESM dist/isolate-F2PPSUL6.js 53.82 KB
-ESM dist/index.js            572.59 KB
-ESM ⚡️ Build success in 249ms
+ESM dist/index.js            574.06 KB
+ESM ⚡️ Build success in 251ms
 DTS Build start
-DTS ⚡️ Build success in 7835ms
-DTS dist/index.d.ts 104.09 KB
+DTS ⚡️ Build success in 7890ms
+DTS dist/index.d.ts 105.18 KB

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @poncho-ai/harness
 
+## 0.60.0
+
+### Minor Changes
+
+- [`8a5a367`](https://github.com/cesr/poncho-ai/commit/8a5a367dd4b2ea477b3e0146a7253cedcdc34a1c) Thanks [@cesr](https://github.com/cesr)! - Prompt-cache efficiency: tail breakpoint pin + volatile context slot + span attribution.
+  - **Second message-history cache breakpoint.** When prior-run tool results
+    are still untruncated, the history breakpoint used to sit only at the
+    last _stable_ index (before those results) — so a tool-heavy turn
+    re-sent everything after it raw on every step. Now a second breakpoint
+    is pinned at the true tail, so the current run reads its own growing
+    history at 0.1× while the stable entry keeps serving across runs.
+    `addPromptCacheBreakpoints` accepts `number | number[]` (out-of-range
+    indices dropped, duplicates collapsed). The Anthropic breakpoint budget
+    of 4 is now fully spent: static (1h), memory (1h), stable-history, tail.
+  - **`RunInput.volatileContext`** — per-run context rendered into the
+    _uncached_ dynamic tail of the system prompt. Embedders that previously
+    appended volatile blocks (live VFS tree, connected integrations) to the
+    agent body — busting the 1h static cache block on every change — can
+    pass them here instead, keeping the static block byte-stable (and
+    shareable across users when the agent definition is identical). The
+    value is captured per conversation so orchestrator-initiated turns
+    (continuations, subagent-callback resumes) reuse it. Forwarded through
+    `runConversationTurn` opts.
+  - **`RunInput.telemetryAttributes`** — extra attributes stamped on the
+    `invoke_agent` root span (e.g. `{"poncho.run.kind": "job"}`), letting
+    observability backends segment traffic classes without timing
+    forensics. Forwarded through `runConversationTurn` opts.
+
+### Patch Changes
+
+- Updated dependencies [[`8a5a367`](https://github.com/cesr/poncho-ai/commit/8a5a367dd4b2ea477b3e0146a7253cedcdc34a1c)]:
+  - @poncho-ai/sdk@1.16.0
+
 ## 0.59.19
 
 ### Patch Changes

package/dist/index.d.ts

@@ -1482,6 +1482,12 @@ declare class AgentHarness {
     private mcpBridge?;
     private subagentManager?;
     private readonly archivedToolResultsByConversation;
+    /** Last explicit `RunInput.volatileContext` per conversation, reused by
+     *  orchestrator-initiated turns (continuations, subagent-callback
+     *  resumes) that build their own RunInput and can't know the embedder's
+     *  volatile blocks. Values are small (the field's contract) and entries
+     *  live for the harness instance's lifetime. */
+    private readonly volatileContextByConversation;
     /** Unified storage engine (replaces individual KV-backed stores). */
     storageEngine?: StorageEngine;
     /** Bash environment manager (creates per-tenant bash instances). */
@@ -2371,17 +2377,31 @@ interface RunConversationTurnOpts {
     abortSignal?: AbortSignal;
     tenantId?: string | null;
     /**
-     * Forwarded to `RunInput.disablePromptCache`. Set true for one-shot
-     * turns with no follow-up coming (cron-fired jobs, etc.) so the
-     * harness skips the Anthropic cache write.
+     * Forwarded to `RunInput.disablePromptCache`. Only worth it for runs
+     * that are both single-step and one-shot — see the RunInput doc; a
+     * multi-step run reads its own growing history through the tail
+     * breakpoint, so disabling it costs more than the write it saves.
      */
     disablePromptCache?: boolean;
+    /**
+     * Forwarded to `RunInput.volatileContext`: per-run context appended to
+     * the uncached dynamic tail of the system prompt. Keep it small — it is
+     * re-sent raw every step. Also captured per conversation so
+     * orchestrator-initiated turns (subagent-callback resumes) reuse the
+     * value from the turn that spawned the subagent.
+     */
+    volatileContext?: string;
     /**
      * Forwarded to `RunInput.suppressTelemetry`. Set true to emit no telemetry
      * for this run (e.g. an incognito / telemetry-off turn) even on a harness
      * built with an OTLP exporter attached.
      */
     suppressTelemetry?: boolean;
+    /**
+     * Forwarded to `RunInput.telemetryAttributes` — extra attributes for the
+     * `invoke_agent` root span (e.g. run kind / job name for segmentation).
+     */
+    telemetryAttributes?: Record<string, string>;
     /**
      * Forwarded to `RunInput.model`. Per-run model override, captured once at
      * run start — safe under concurrent runs on a shared harness, unlike

package/dist/index.js

@@ -7978,19 +7978,22 @@ function isAnthropicModel(model) {
   }
   return model.provider === "anthropic" || model.provider.includes("anthropic") || model.modelId.includes("anthropic") || model.modelId.includes("claude");
 }
-function addPromptCacheBreakpoints(messages, model, targetIndex) {
+function addPromptCacheBreakpoints(messages, model, target) {
   if (messages.length === 0 || !isAnthropicModel(model)) {
     return messages;
   }
-  const index = targetIndex ?? messages.length - 1;
-  if (index < 0 || index >= messages.length) {
+  const requested = target === void 0 ? [messages.length - 1] : Array.isArray(target) ? target : [target];
+  const indices = new Set(
+    requested.filter((i) => i >= 0 && i < messages.length)
+  );
+  if (indices.size === 0) {
     return messages;
   }
   const cacheDirective = {
     anthropic: { cacheControl: { type: "ephemeral" } }
   };
   return messages.map((message, i) => {
-    if (i === index) {
+    if (indices.has(i)) {
       return {
         ...message,
         providerOptions: {
@@ -9674,6 +9677,12 @@ var AgentHarness = class _AgentHarness {
   mcpBridge;
   subagentManager;
   archivedToolResultsByConversation = /* @__PURE__ */ new Map();
+  /** Last explicit `RunInput.volatileContext` per conversation, reused by
+   *  orchestrator-initiated turns (continuations, subagent-callback
+   *  resumes) that build their own RunInput and can't know the embedder's
+   *  volatile blocks. Values are small (the field's contract) and entries
+   *  live for the harness instance's lifetime. */
+  volatileContextByConversation = /* @__PURE__ */ new Map();
   /** Unified storage engine (replaces individual KV-backed stores). */
   storageEngine;
   /** Bash environment manager (creates per-tenant bash instances). */
@@ -10732,7 +10741,10 @@ var AgentHarness = class _AgentHarness {
             "session.id": input.conversationId
           } : {},
           ...this.telemetryUserId ? { "user.id": this.telemetryUserId } : {},
-          ...input.tenantId ? { "tenant.id": input.tenantId } : {}
+          ...input.tenantId ? { "tenant.id": input.tenantId } : {},
+          // Embedder-supplied attribution (e.g. run kind, job name) so
+          // observability backends can segment traffic classes directly.
+          ...input.telemetryAttributes ?? {}
         }
       });
       let spanContext = trace.setSpan(otelContext.active(), rootSpan);
@@ -10816,6 +10828,14 @@ var AgentHarness = class _AgentHarness {
     }
     const hasFullToolResults = hasUntruncatedToolResults(messages);
     const skipTailCache = input.disablePromptCache === true;
+    let volatileRunContext = input.volatileContext;
+    if (input.conversationId) {
+      if (volatileRunContext !== void 0) {
+        this.volatileContextByConversation.set(input.conversationId, volatileRunContext);
+      } else {
+        volatileRunContext = this.volatileContextByConversation.get(input.conversationId);
+      }
+    }
     if (skipTailCache) {
       costLog.debug(`tail cache breakpoint skipped \u2014 disablePromptCache (run=${runId.slice(0, 12)})`);
     } else if (hasFullToolResults) {
@@ -10929,7 +10949,10 @@ ${skillContextWindow}${browserContext}${fsContext}${isolateContext}` : `${agentP
       const timeContext = `
 
 Current UTC time (hour precision): ${hourlyTime}`;
-      const dynamicPart = `${todoContext}${timeContext}`;
+      const volatileContext = volatileRunContext ? `
+
+${volatileRunContext.trim()}` : "";
+      const dynamicPart = `${todoContext}${volatileContext}${timeContext}`;
       return { staticPart, memoryPart: memoryContext, dynamicPart };
     };
     let { staticPart: staticSystemPart, memoryPart: memorySystemPart, dynamicPart: dynamicSystemPart } = await buildSystemPromptParts();
@@ -11402,7 +11425,7 @@ ${textContent}` };
           const cachedMessages = skipTailCache ? coreMessages : addPromptCacheBreakpoints(
             coreMessages,
             modelInstance,
-            hasFullToolResults ? findLastStableCacheIndex(coreMessages) : coreMessages.length - 1
+            hasFullToolResults ? [findLastStableCacheIndex(coreMessages), coreMessages.length - 1] : coreMessages.length - 1
           );
           const useStaticCache = isAnthropicModel(modelInstance);
           const finalMessages = useStaticCache ? [
@@ -11417,7 +11440,10 @@ ${textContent}` };
             // an explicit memory write — its own 1h breakpoint means a
             // memory edit busts THIS block forward but a normal turn reads
             // it (plus everything before it) from cache. Breakpoint budget:
-            // Anthropic allows 4; this is #2 of 3 (static, memory, tail).
+            // Anthropic allows 4 and ALL FOUR ARE NOW SPENT (static,
+            // memory, stable-history, tail — the last two collapse to one
+            // when there are no untruncated prior tool results). Adding a
+            // fifth cache_control block anywhere is an API 400.
             ...memorySystemPart.length > 0 ? [{
               role: "system",
               content: memorySystemPart,
@@ -14608,7 +14634,9 @@ var runConversationTurn = async (opts) => {
         abortSignal: opts.abortSignal,
         disablePromptCache: opts.disablePromptCache,
         suppressTelemetry: opts.suppressTelemetry,
-        model: opts.model
+        model: opts.model,
+        volatileContext: opts.volatileContext,
+        telemetryAttributes: opts.telemetryAttributes
       },
       initialContextTokens: conversation.contextTokens ?? 0,
       initialContextWindow: conversation.contextWindow ?? 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/harness",
-  "version": "0.59.19",
+  "version": "0.60.0",
   "description": "Agent execution runtime - conversation loop, tool dispatch, streaming",
   "repository": {
     "type": "git",
@@ -34,7 +34,7 @@
     "mustache": "^4.2.0",
     "yaml": "^2.4.0",
     "zod": "^3.22.0",
-    "@poncho-ai/sdk": "1.15.2"
+    "@poncho-ai/sdk": "1.16.0"
   },
   "peerDependencies": {
     "esbuild": ">=0.17.0",

package/src/harness.ts

@@ -937,6 +937,12 @@ export class AgentHarness {
   private mcpBridge?: LocalMcpBridge;
   private subagentManager?: SubagentManager;
   private readonly archivedToolResultsByConversation = new Map<string, Record<string, ArchivedToolResult>>();
+  /** Last explicit `RunInput.volatileContext` per conversation, reused by
+   *  orchestrator-initiated turns (continuations, subagent-callback
+   *  resumes) that build their own RunInput and can't know the embedder's
+   *  volatile blocks. Values are small (the field's contract) and entries
+   *  live for the harness instance's lifetime. */
+  private readonly volatileContextByConversation = new Map<string, string>();
 
   /** Unified storage engine (replaces individual KV-backed stores). */
   storageEngine?: StorageEngine;
@@ -2224,6 +2230,9 @@ export class AgentHarness {
             : {}),
           ...(this.telemetryUserId ? { "user.id": this.telemetryUserId } : {}),
           ...(input.tenantId ? { "tenant.id": input.tenantId } : {}),
+          // Embedder-supplied attribution (e.g. run kind, job name) so
+          // observability backends can segment traffic classes directly.
+          ...(input.telemetryAttributes ?? {}),
         },
       });
 
@@ -2337,6 +2346,20 @@ export class AgentHarness {
     // 1-hour static breakpoint on the system prompt is always on — it
     // amortizes across every later turn or job within the hour.
     const skipTailCache = input.disablePromptCache === true;
+    // Effective volatile context for this run. An explicit value (even "")
+    // wins and is remembered per conversation so orchestrator-initiated
+    // turns on the same conversation — continuations, subagent-callback
+    // resumes — reuse the value from the turn that set it instead of
+    // silently dropping it (they build their own RunInput and can't know
+    // the embedder's blocks).
+    let volatileRunContext = input.volatileContext;
+    if (input.conversationId) {
+      if (volatileRunContext !== undefined) {
+        this.volatileContextByConversation.set(input.conversationId, volatileRunContext);
+      } else {
+        volatileRunContext = this.volatileContextByConversation.get(input.conversationId);
+      }
+    }
     if (skipTailCache) {
       costLog.debug(`tail cache breakpoint skipped — disablePromptCache (run=${runId.slice(0, 12)})`);
     } else if (hasFullToolResults) {
@@ -2485,7 +2508,11 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
         return `${weekday} ${d.toISOString().slice(0, 13)}Z`;
       })();
       const timeContext = `\n\nCurrent UTC time (hour precision): ${hourlyTime}`;
-      const dynamicPart = `${todoContext}${timeContext}`;
+      // Embedder-supplied volatile blocks (live VFS tree, connected
+      // integrations, …) land here — uncached by design, so their churn
+      // never busts the 1h static/memory cache entries above.
+      const volatileContext = volatileRunContext ? `\n\n${volatileRunContext.trim()}` : "";
+      const dynamicPart = `${todoContext}${volatileContext}${timeContext}`;
       return { staticPart, memoryPart: memoryContext, dynamicPart };
     };
     let { staticPart: staticSystemPart, memoryPart: memorySystemPart, dynamicPart: dynamicSystemPart } =
@@ -3107,19 +3134,24 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
         // below: omitted from the request when undefined.
         const temperature = agent.frontmatter.model?.temperature;
         const maxTokens = agent.frontmatter.model?.maxTokens;
-        // Place the tail breakpoint before any untruncated tool-result so
-        // we cache only the stable prefix when prior-run tool results are
-        // still full-fidelity. Otherwise cache at the history tail. When
-        // `skipTailCache` is set (per-run override), don't write the tail
-        // breakpoint at all. The 1-hour static-prefix breakpoint is added
-        // separately when assembling the final messages array.
+        // Two history breakpoints: one just before any untruncated
+        // prior-run tool-result (the stable prefix keeps its cross-run
+        // cache entry — truncateHistoricalToolResults rewrites everything
+        // after it next run) AND one pinned at the true tail so the
+        // current run's own steps read the growing history at 0.1x instead
+        // of re-paying it raw every step. Without the tail pin, a
+        // tool-heavy turn with full prior results re-sent everything past
+        // the stable index uncached on all of its (up to maxSteps) steps.
+        // When there are no untruncated results the two collapse to the
+        // tail (addPromptCacheBreakpoints dedupes). When `skipTailCache`
+        // is set (per-run override), write no history breakpoints at all.
         const cachedMessages = skipTailCache
           ? coreMessages
           : addPromptCacheBreakpoints(
               coreMessages,
               modelInstance,
               hasFullToolResults
-                ? findLastStableCacheIndex(coreMessages)
+                ? [findLastStableCacheIndex(coreMessages), coreMessages.length - 1]
                 : coreMessages.length - 1,
             );
 
@@ -3146,7 +3178,10 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
               // an explicit memory write — its own 1h breakpoint means a
               // memory edit busts THIS block forward but a normal turn reads
               // it (plus everything before it) from cache. Breakpoint budget:
-              // Anthropic allows 4; this is #2 of 3 (static, memory, tail).
+              // Anthropic allows 4 and ALL FOUR ARE NOW SPENT (static,
+              // memory, stable-history, tail — the last two collapse to one
+              // when there are no untruncated prior tool results). Adding a
+              // fifth cache_control block anywhere is an API 400.
               ...(memorySystemPart.length > 0
                 ? [{
                     role: "system" as const,

package/src/orchestrator/run-conversation-turn.ts

@@ -64,17 +64,31 @@ export interface RunConversationTurnOpts {
   abortSignal?: AbortSignal;
   tenantId?: string | null;
   /**
-   * Forwarded to `RunInput.disablePromptCache`. Set true for one-shot
-   * turns with no follow-up coming (cron-fired jobs, etc.) so the
-   * harness skips the Anthropic cache write.
+   * Forwarded to `RunInput.disablePromptCache`. Only worth it for runs
+   * that are both single-step and one-shot — see the RunInput doc; a
+   * multi-step run reads its own growing history through the tail
+   * breakpoint, so disabling it costs more than the write it saves.
    */
   disablePromptCache?: boolean;
+  /**
+   * Forwarded to `RunInput.volatileContext`: per-run context appended to
+   * the uncached dynamic tail of the system prompt. Keep it small — it is
+   * re-sent raw every step. Also captured per conversation so
+   * orchestrator-initiated turns (subagent-callback resumes) reuse the
+   * value from the turn that spawned the subagent.
+   */
+  volatileContext?: string;
   /**
    * Forwarded to `RunInput.suppressTelemetry`. Set true to emit no telemetry
    * for this run (e.g. an incognito / telemetry-off turn) even on a harness
    * built with an OTLP exporter attached.
    */
   suppressTelemetry?: boolean;
+  /**
+   * Forwarded to `RunInput.telemetryAttributes` — extra attributes for the
+   * `invoke_agent` root span (e.g. run kind / job name for segmentation).
+   */
+  telemetryAttributes?: Record<string, string>;
   /**
    * Forwarded to `RunInput.model`. Per-run model override, captured once at
    * run start — safe under concurrent runs on a shared harness, unlike
@@ -238,6 +252,8 @@ export const runConversationTurn = async (
         disablePromptCache: opts.disablePromptCache,
         suppressTelemetry: opts.suppressTelemetry,
         model: opts.model,
+        volatileContext: opts.volatileContext,
+        telemetryAttributes: opts.telemetryAttributes,
       },
       initialContextTokens: conversation.contextTokens ?? 0,
       initialContextWindow: conversation.contextWindow ?? 0,

package/src/prompt-cache.ts

@@ -17,23 +17,32 @@ export function isAnthropicModel(model: LanguageModel): boolean {
  * explicit opt-in (Anthropic). For providers with automatic caching
  * (OpenAI), messages are returned unchanged.
  *
- * For Anthropic, marks the target message with ephemeral cache control so
- * the conversation prefix is incrementally cached across steps. When
- * `targetIndex` is omitted, the last message is used (default behavior).
- * Callers that want to cache only a stable prefix (e.g. skipping tool
- * results that will be truncated next turn) can pass an earlier index.
+ * For Anthropic, marks the target message(s) with ephemeral cache control
+ * so the conversation prefix is incrementally cached across steps. When
+ * `target` is omitted, the last message is used (default behavior).
+ * Callers can pass an earlier index to cache only a stable prefix (e.g.
+ * skipping tool results that will be truncated next turn), or an array to
+ * mark several — typically `[stableIndex, tail]` so the stable prefix
+ * keeps its cross-run entry while the moving tail serves within-run reads.
+ * Out-of-range indices are dropped and duplicates collapse to one mark
+ * (a message must never carry two cache_control blocks).
  */
 export function addPromptCacheBreakpoints(
   messages: ModelMessage[],
   model: LanguageModel,
-  targetIndex?: number,
+  target?: number | number[],
 ): ModelMessage[] {
   if (messages.length === 0 || !isAnthropicModel(model)) {
     return messages;
   }
 
-  const index = targetIndex ?? messages.length - 1;
-  if (index < 0 || index >= messages.length) {
+  const requested = target === undefined
+    ? [messages.length - 1]
+    : Array.isArray(target) ? target : [target];
+  const indices = new Set(
+    requested.filter((i) => i >= 0 && i < messages.length),
+  );
+  if (indices.size === 0) {
     return messages;
   }
 
@@ -42,7 +51,7 @@ export function addPromptCacheBreakpoints(
   };
 
   return messages.map((message, i) => {
-    if (i === index) {
+    if (indices.has(i)) {
       return {
         ...message,
         providerOptions: {

package/test/prompt-cache.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+import type { ModelMessage } from "ai";
+import { addPromptCacheBreakpoints } from "../src/prompt-cache.js";
+
+const ANTHROPIC_MODEL = "anthropic/claude-opus-4-8";
+const OPENAI_MODEL = "openai/gpt-4o";
+
+function messages(n: number): ModelMessage[] {
+  return Array.from({ length: n }, (_, i) => ({
+    role: i % 2 === 0 ? ("user" as const) : ("assistant" as const),
+    content: `message ${i}`,
+  }));
+}
+
+function markedIndices(result: ModelMessage[]): number[] {
+  return result
+    .map((m, i) => ((m.providerOptions as Record<string, unknown> | undefined)?.anthropic ? i : -1))
+    .filter((i) => i >= 0);
+}
+
+describe("addPromptCacheBreakpoints", () => {
+  it("marks the last message by default", () => {
+    const result = addPromptCacheBreakpoints(messages(4), ANTHROPIC_MODEL);
+    expect(markedIndices(result)).toEqual([3]);
+  });
+
+  it("marks a single explicit index", () => {
+    const result = addPromptCacheBreakpoints(messages(4), ANTHROPIC_MODEL, 1);
+    expect(markedIndices(result)).toEqual([1]);
+  });
+
+  it("marks stable + tail when given an array", () => {
+    const result = addPromptCacheBreakpoints(messages(6), ANTHROPIC_MODEL, [2, 5]);
+    expect(markedIndices(result)).toEqual([2, 5]);
+  });
+
+  it("collapses duplicate indices to one mark (stable == tail)", () => {
+    const result = addPromptCacheBreakpoints(messages(4), ANTHROPIC_MODEL, [3, 3]);
+    expect(markedIndices(result)).toEqual([3]);
+    const marked = result[3].providerOptions as Record<string, unknown>;
+    // One cacheControl object, not a doubled/merged mess.
+    expect(marked.anthropic).toEqual({ cacheControl: { type: "ephemeral" } });
+  });
+
+  it("drops out-of-range indices (findLastStableCacheIndex can return -1)", () => {
+    const result = addPromptCacheBreakpoints(messages(4), ANTHROPIC_MODEL, [-1, 3]);
+    expect(markedIndices(result)).toEqual([3]);
+  });
+
+  it("returns messages unchanged when every index is out of range", () => {
+    const input = messages(2);
+    const result = addPromptCacheBreakpoints(input, ANTHROPIC_MODEL, [-1, 9]);
+    expect(result).toBe(input);
+  });
+
+  it("leaves non-Anthropic models untouched", () => {
+    const input = messages(3);
+    const result = addPromptCacheBreakpoints(input, OPENAI_MODEL, [0, 2]);
+    expect(result).toBe(input);
+  });
+
+  it("preserves existing providerOptions on the marked message", () => {
+    const input = messages(2);
+    input[1] = { ...input[1], providerOptions: { other: { keep: true } } as never };
+    const result = addPromptCacheBreakpoints(input, ANTHROPIC_MODEL, [1]);
+    const opts = result[1].providerOptions as Record<string, unknown>;
+    expect(opts.other).toEqual({ keep: true });
+    expect(opts.anthropic).toEqual({ cacheControl: { type: "ephemeral" } });
+  });
+});