@poncho-ai/harness 0.59.18 → 0.60.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/harness@0.59.18 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
@@ -8,9 +8,9 @@
 CLI tsup v8.5.1
 CLI Target: es2022
 ESM Build start
-ESM dist/index.js            572.34 KB
 ESM dist/isolate-F2PPSUL6.js 53.82 KB
-ESM ⚡️ Build success in 214ms
+ESM dist/index.js            574.06 KB
+ESM ⚡️ Build success in 251ms
 DTS Build start
-DTS ⚡️ Build success in 7534ms
-DTS dist/index.d.ts 104.01 KB
+DTS ⚡️ Build success in 7890ms
+DTS dist/index.d.ts 105.18 KB

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @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
+
+- [#186](https://github.com/cesr/poncho-ai/pull/186) [`b12ccbf`](https://github.com/cesr/poncho-ai/commit/b12ccbf1de63a5ef996b0896898c2afe7238a271) Thanks [@cesr](https://github.com/cesr)! - Stamp the tool-call id onto completed-tool activity lines (`{tcid:<id>}`
+  appended after any human detail). Display clients can now join a tool pill to
+  its full input/output by id instead of by tool-name + position. The old
+  positional/name match misaligns whenever parallel tool calls in a turn
+  complete out of declaration order, and can never reach a subagent's
+  inner-tool results; id-joining fixes both. The token sits after the first
+  `(...)` detail group, so existing clients that only parse inside it are
+  unaffected, and it is stripped from model-visible interruption text via the
+  new `stripPillMetaTokens` export.
+
 ## 0.59.18
 
 ### 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). */
@@ -2135,6 +2141,7 @@ declare const flushTurnDraft: (draft: TurnDraftState) => void;
 declare const buildToolCompletedText: (event: AgentEvent & {
     type: "tool:completed";
 }) => string;
+declare const stripPillMetaTokens: (line: string) => string;
 declare const recordStandardTurnEvent: (draft: TurnDraftState, event: AgentEvent) => void;
 declare const buildAssistantMetadata: (draft: TurnDraftState, sectionsOverride?: TurnSection[], opts?: {
     id?: string;
@@ -2370,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
@@ -2418,4 +2439,4 @@ type NewEntryNoId = NewConversationEntry extends infer T ? T extends NewConversa
  */
 declare const appendEntriesSafe: (store: ConversationStore, conversation: Pick<Conversation, "conversationId" | "ownerId" | "tenantId">, entries: NewEntryNoId[], log: Logger) => Promise<ConversationEntry[]>;
 
-export { type ActiveConversationRun, type ActiveSubagentRun, type AgentFrontmatter, AgentHarness, type AgentIdentity, type AgentLimitsConfig, type AgentModelConfig, AgentOrchestrator, type ApprovalEventItem, type ArchivedToolResult$1 as ArchivedToolResult, type BashConfig, BashEnvironmentManager, type BashExecutionLimits, type BuiltInToolToggles, CALLBACK_LOCK_STALE_MS, type CallbackStartedEntry, type CompactMessagesOptions, type CompactResult, type CompactionConfig, type ContinuationHooks, type Conversation, type ConversationCreateInit, type ConversationEntry, type ConversationState, type ConversationStatusSnapshot, type ConversationStore, type ConversationSummary, type CreateSkillToolsOptions, type CronJobConfig, DEFAULT_AGENT_DESCRIPTION, DEFAULT_AGENT_NAME, DEFAULT_MAX_STEPS, DEFAULT_MODEL_NAME, DEFAULT_MODEL_PROVIDER, DEFAULT_TAGLINE, DEFAULT_TEMPERATURE, DEFAULT_TIMEOUT, type DefaultAgentDefinitionOptions, type EventSink, type ExecuteTurnResult, type HarnessOptions, type HarnessRunOutput, type HistorySource, InMemoryConversationStore, InMemoryEngine, InMemoryStateStore, type IsolateBinding, type IsolateConfig, LocalMcpBridge, LocalUploadStore, MAX_CONCURRENT_SUBAGENTS, MAX_CONTINUATION_COUNT, MAX_SUBAGENT_CALLBACK_COUNT, MAX_SUBAGENT_NESTING, type MainMemory, type McpConfig, type MemoryConfig, type MemoryStore, type MessagingChannelConfig, type ModelProviderFactory, type MountProvider, type NetworkConfig, type NewConversationEntry, OPENAI_CODEX_CLIENT_ID, type OpenAICodexAuthConfig, type OpenAICodexDeviceAuthRequest, type OpenAICodexSession, type OrchestratorHooks, type OrchestratorOptions, type OtlpConfig, type OtlpOption, PONCHO_UPLOAD_SCHEME, type ParsedAgent, type PendingSubagentApproval, type PendingSubagentResult, type PendingToolCall, type PonchoConfig, PonchoFsAdapter, PostgresEngine, type ProviderConfig, type Recurrence, type RecurrenceType, type Reminder, type ReminderCreateInput, type ReminderStatus, type ReminderStore, type RemoteMcpServerConfig, type RunConversationTurnOpts, type RunConversationTurnResult, type RunOutcome, type RunRequest, type RuntimeRenderContext, S3UploadStore, STALE_SUBAGENT_THRESHOLD_MS, STORAGE_SCHEMA_VERSION, type SecretsStore, type SkillContextEntry, type SkillMetadata, type SkillSource, SqliteEngine, type StateConfig, type StateProviderName, type StateStore, type StorageConfig, type StorageEngine, type StorageFactoryOptions, type StorageProvider, type StoredApproval, type SubagentManager, type SubagentResult, type SubagentResultEntry, type SubagentSpawnResult, type SubagentSummary, type SubagentTranscript, type SubagentTranscriptMode, TOOL_RESULT_ARCHIVE_PARAM, type TelemetryConfig, TelemetryEmitter, type TenantTokenPayload, type ToolAccess, type ToolCall, ToolDispatcher, type ToolExecutionResult, type TurnDraftState, type TurnResultMetadata, type TurnSection, type UploadStore, type UploadsConfig, VFS_SCHEME, VercelBlobUploadStore, type VfsDirEntry, type VfsStat, type VirtualMount, abnormalEndResponse, appendEntriesSafe, applyTurnMetadata, buildAgentDirectoryName, buildApprovalCheckpoints, buildAssistantMetadata, buildSkillContextWindow, buildToolCompletedText, cloneSections, compactMessages, completeOpenAICodexDeviceAuth, computeNextOccurrence, createBashTool, createConversationStore, createConversationStoreFromEngine, createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createEditTool, createMemoryStore, createMemoryStoreFromEngine, createMemoryTools, createModelProvider, createReminderStore, createReminderStoreFromEngine, createReminderTools, createSearchTools, createSecretsStore, createSkillTools, createStateStore, createStorageEngine, createSubagentTools, createTodoStoreFromEngine, createTurnDraftState, createUploadStore, createWriteTool, decodeFileInputData, defaultAgentDefinition, deleteOpenAICodexSession, deriveUploadKey, ensureAgentIdentity, estimateTokens, estimateTotalTokens, executeConversationTurn, findSafeSplitPoint, flushTurnDraft, generateAgentId, getAgentStoreDirectory, getModelContextWindow, getOpenAICodexAccessToken, getOpenAICodexAuthFilePath, getOpenAICodexRequiredScopes, getPendingSubagentResults, getPonchoStoreRoot, isMessageArray, jsonSchemaToZod, lastAssistantText, loadCanonicalHistory, loadPonchoConfig, loadRunHistory, loadSkillContext, loadSkillInstructions, loadSkillMetadata, loadSkillMetadataFromDirs, loadVfsSkillMetadata, mergeSkills, normalizeApprovalCheckpoint, normalizeOtlp, normalizeScriptPolicyPath, normalizeToolAccess, parseAgentFile, parseAgentMarkdown, parseSkillFrontmatter, ponchoDocsTool, readOpenAICodexSession, readSkillResource, realResponseText, recordStandardTurnEvent, renderAgentPrompt, resolveAgentIdentity, resolveCompactionConfig, resolveEnv, resolveMemoryConfig, resolveRunRequest, resolveSkillDirs, resolveStateConfig, runConversationTurn, slugifyStorageComponent, startOpenAICodexDeviceAuth, verifyTenantToken, withToolResultArchiveParam, writeOpenAICodexSession };
+export { type ActiveConversationRun, type ActiveSubagentRun, type AgentFrontmatter, AgentHarness, type AgentIdentity, type AgentLimitsConfig, type AgentModelConfig, AgentOrchestrator, type ApprovalEventItem, type ArchivedToolResult$1 as ArchivedToolResult, type BashConfig, BashEnvironmentManager, type BashExecutionLimits, type BuiltInToolToggles, CALLBACK_LOCK_STALE_MS, type CallbackStartedEntry, type CompactMessagesOptions, type CompactResult, type CompactionConfig, type ContinuationHooks, type Conversation, type ConversationCreateInit, type ConversationEntry, type ConversationState, type ConversationStatusSnapshot, type ConversationStore, type ConversationSummary, type CreateSkillToolsOptions, type CronJobConfig, DEFAULT_AGENT_DESCRIPTION, DEFAULT_AGENT_NAME, DEFAULT_MAX_STEPS, DEFAULT_MODEL_NAME, DEFAULT_MODEL_PROVIDER, DEFAULT_TAGLINE, DEFAULT_TEMPERATURE, DEFAULT_TIMEOUT, type DefaultAgentDefinitionOptions, type EventSink, type ExecuteTurnResult, type HarnessOptions, type HarnessRunOutput, type HistorySource, InMemoryConversationStore, InMemoryEngine, InMemoryStateStore, type IsolateBinding, type IsolateConfig, LocalMcpBridge, LocalUploadStore, MAX_CONCURRENT_SUBAGENTS, MAX_CONTINUATION_COUNT, MAX_SUBAGENT_CALLBACK_COUNT, MAX_SUBAGENT_NESTING, type MainMemory, type McpConfig, type MemoryConfig, type MemoryStore, type MessagingChannelConfig, type ModelProviderFactory, type MountProvider, type NetworkConfig, type NewConversationEntry, OPENAI_CODEX_CLIENT_ID, type OpenAICodexAuthConfig, type OpenAICodexDeviceAuthRequest, type OpenAICodexSession, type OrchestratorHooks, type OrchestratorOptions, type OtlpConfig, type OtlpOption, PONCHO_UPLOAD_SCHEME, type ParsedAgent, type PendingSubagentApproval, type PendingSubagentResult, type PendingToolCall, type PonchoConfig, PonchoFsAdapter, PostgresEngine, type ProviderConfig, type Recurrence, type RecurrenceType, type Reminder, type ReminderCreateInput, type ReminderStatus, type ReminderStore, type RemoteMcpServerConfig, type RunConversationTurnOpts, type RunConversationTurnResult, type RunOutcome, type RunRequest, type RuntimeRenderContext, S3UploadStore, STALE_SUBAGENT_THRESHOLD_MS, STORAGE_SCHEMA_VERSION, type SecretsStore, type SkillContextEntry, type SkillMetadata, type SkillSource, SqliteEngine, type StateConfig, type StateProviderName, type StateStore, type StorageConfig, type StorageEngine, type StorageFactoryOptions, type StorageProvider, type StoredApproval, type SubagentManager, type SubagentResult, type SubagentResultEntry, type SubagentSpawnResult, type SubagentSummary, type SubagentTranscript, type SubagentTranscriptMode, TOOL_RESULT_ARCHIVE_PARAM, type TelemetryConfig, TelemetryEmitter, type TenantTokenPayload, type ToolAccess, type ToolCall, ToolDispatcher, type ToolExecutionResult, type TurnDraftState, type TurnResultMetadata, type TurnSection, type UploadStore, type UploadsConfig, VFS_SCHEME, VercelBlobUploadStore, type VfsDirEntry, type VfsStat, type VirtualMount, abnormalEndResponse, appendEntriesSafe, applyTurnMetadata, buildAgentDirectoryName, buildApprovalCheckpoints, buildAssistantMetadata, buildSkillContextWindow, buildToolCompletedText, cloneSections, compactMessages, completeOpenAICodexDeviceAuth, computeNextOccurrence, createBashTool, createConversationStore, createConversationStoreFromEngine, createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createEditTool, createMemoryStore, createMemoryStoreFromEngine, createMemoryTools, createModelProvider, createReminderStore, createReminderStoreFromEngine, createReminderTools, createSearchTools, createSecretsStore, createSkillTools, createStateStore, createStorageEngine, createSubagentTools, createTodoStoreFromEngine, createTurnDraftState, createUploadStore, createWriteTool, decodeFileInputData, defaultAgentDefinition, deleteOpenAICodexSession, deriveUploadKey, ensureAgentIdentity, estimateTokens, estimateTotalTokens, executeConversationTurn, findSafeSplitPoint, flushTurnDraft, generateAgentId, getAgentStoreDirectory, getModelContextWindow, getOpenAICodexAccessToken, getOpenAICodexAuthFilePath, getOpenAICodexRequiredScopes, getPendingSubagentResults, getPonchoStoreRoot, isMessageArray, jsonSchemaToZod, lastAssistantText, loadCanonicalHistory, loadPonchoConfig, loadRunHistory, loadSkillContext, loadSkillInstructions, loadSkillMetadata, loadSkillMetadataFromDirs, loadVfsSkillMetadata, mergeSkills, normalizeApprovalCheckpoint, normalizeOtlp, normalizeScriptPolicyPath, normalizeToolAccess, parseAgentFile, parseAgentMarkdown, parseSkillFrontmatter, ponchoDocsTool, readOpenAICodexSession, readSkillResource, realResponseText, recordStandardTurnEvent, renderAgentPrompt, resolveAgentIdentity, resolveCompactionConfig, resolveEnv, resolveMemoryConfig, resolveRunRequest, resolveSkillDirs, resolveStateConfig, runConversationTurn, slugifyStorageComponent, startOpenAICodexDeviceAuth, stripPillMetaTokens, verifyTenantToken, withToolResultArchiveParam, writeOpenAICodexSession };

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,
@@ -12739,8 +12765,10 @@ var buildToolCompletedText = (event) => {
   if (event.tool === "web_search" && Array.isArray(output?.results)) {
     text += ` \u2014 ${output.results.length} result${output.results.length !== 1 ? "s" : ""}`;
   }
+  if (event.toolCallId) text += ` {tcid:${event.toolCallId}}`;
   return text;
 };
+var stripPillMetaTokens = (line) => line.replace(/\s*\{tcid:[^}]+\}/g, "");
 var recordStandardTurnEvent = (draft, event) => {
   if (event.type === "model:chunk") {
     if (draft.currentTools.length > 0) {
@@ -13622,7 +13650,7 @@ var AgentOrchestrator = class {
             for (const a of decidedApprovals) {
               if (a.decision === "approved" && a.toolCallId) {
                 callsToExecute.push({ id: a.toolCallId, name: a.tool, input: a.input });
-                const toolText = `- done \`${a.tool}\``;
+                const toolText = `- done \`${a.tool}\`` + (a.toolCallId ? ` {tcid:${a.toolCallId}}` : "");
                 draft.toolTimeline.push(toolText);
                 draft.currentTools.push(toolText);
               } else if (a.toolCallId) {
@@ -14606,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,
@@ -14783,8 +14813,10 @@ var runConversationTurn = async (opts) => {
       const parts = [];
       if (draft.assistantResponse.length > 0) parts.push(draft.assistantResponse);
       if (draft.toolTimeline.length > 0) {
-        parts.push(`Tool activity before interruption:
-${draft.toolTimeline.join("\n")}`);
+        parts.push(
+          `Tool activity before interruption:
+${draft.toolTimeline.map(stripPillMetaTokens).join("\n")}`
+        );
       }
       parts.push(`[This turn was interrupted: ${reason}. The work above may be incomplete.]`);
       return [
@@ -14991,6 +15023,7 @@ export {
   runConversationTurn,
   slugifyStorageComponent,
   startOpenAICodexDeviceAuth,
+  stripPillMetaTokens,
   verifyTenantToken,
   withToolResultArchiveParam,
   writeOpenAICodexSession

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/harness",
-  "version": "0.59.18",
+  "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/index.ts

@@ -13,6 +13,7 @@ export {
   cloneSections,
   flushTurnDraft,
   buildToolCompletedText,
+  stripPillMetaTokens,
   recordStandardTurnEvent,
   buildAssistantMetadata,
   executeConversationTurn,

package/src/orchestrator/orchestrator.ts

@@ -904,7 +904,8 @@ export class AgentOrchestrator {
             for (const a of decidedApprovals) {
               if (a.decision === "approved" && a.toolCallId) {
                 callsToExecute.push({ id: a.toolCallId, name: a.tool, input: a.input });
-                const toolText = `- done \`${a.tool}\``;
+                const toolText =
+                  `- done \`${a.tool}\`` + (a.toolCallId ? ` {tcid:${a.toolCallId}}` : "");
                 draft.toolTimeline.push(toolText);
                 draft.currentTools.push(toolText);
               } else if (a.toolCallId) {

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

@@ -35,6 +35,7 @@ import {
   createTurnDraftState,
   executeConversationTurn,
   flushTurnDraft,
+  stripPillMetaTokens,
 } from "./turn.js";
 
 const log = createLogger("orchestrator");
@@ -63,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
@@ -237,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,
@@ -435,7 +452,11 @@ export const runConversationTurn = async (
       const parts: string[] = [];
       if (draft.assistantResponse.length > 0) parts.push(draft.assistantResponse);
       if (draft.toolTimeline.length > 0) {
-        parts.push(`Tool activity before interruption:\n${draft.toolTimeline.join("\n")}`);
+        parts.push(
+          `Tool activity before interruption:\n${draft.toolTimeline
+            .map(stripPillMetaTokens)
+            .join("\n")}`,
+        );
       }
       parts.push(`[This turn was interrupted: ${reason}. The work above may be incomplete.]`);
       return [

package/src/orchestrator/turn.ts

@@ -120,9 +120,25 @@ export const buildToolCompletedText = (event: AgentEvent & { type: "tool:complet
     text += ` \u2014 ${(output.results as unknown[]).length} result${(output.results as unknown[]).length !== 1 ? "s" : ""}`;
   }
 
+  // Trailing machine token: the tool-call id this pill corresponds to. Lets a
+  // display client join the pill to its full input/output by id rather than
+  // by tool-name+position (which misaligns whenever parallel tool calls in a
+  // turn complete out of declaration order, and can't reach a subagent's
+  // inner-tool results at all). Appended AFTER any human detail/parens so
+  // older clients \u2014 which only read inside the first `(...)` \u2014 ignore it.
+  // Stripped from model-visible interruption text via stripPillMetaTokens.
+  if (event.toolCallId) text += ` {tcid:${event.toolCallId}}`;
+
   return text;
 };
 
+// Remove machine tokens (e.g. `{tcid:\u2026}`) that buildToolCompletedText appends
+// to activity lines for the display client. Use anywhere a tool-timeline line
+// is folded into MODEL-visible text (e.g. interruption reconstruction) so the
+// internal id never leaks into the prompt.
+export const stripPillMetaTokens = (line: string): string =>
+  line.replace(/\s*\{tcid:[^}]+\}/g, "");
+
 export const recordStandardTurnEvent = (draft: TurnDraftState, event: AgentEvent): void => {
   if (event.type === "model:chunk") {
     if (draft.currentTools.length > 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/pill-tool-call-id.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import type { AgentEvent } from "@poncho-ai/sdk";
+import { buildToolCompletedText, stripPillMetaTokens } from "../src/orchestrator/turn.js";
+
+const completed = (over: Partial<AgentEvent & { type: "tool:completed" }>) =>
+  buildToolCompletedText({
+    type: "tool:completed",
+    tool: "bash",
+    toolCallId: "toolu_abc123",
+    input: { command: "ls -la" },
+    output: {},
+    duration: 45,
+    outputTokenEstimate: 0,
+    ...over,
+  } as AgentEvent & { type: "tool:completed" });
+
+describe("buildToolCompletedText tcid token", () => {
+  it("appends the tool-call id after the human detail", () => {
+    const line = completed({});
+    expect(line).toContain("- done `bash`");
+    expect(line).toContain("(45ms, ls -la)");
+    expect(line.endsWith("{tcid:toolu_abc123}")).toBe(true);
+    // Token sits AFTER the first (...) detail group so old clients ignore it.
+    expect(line.indexOf("{tcid:")).toBeGreaterThan(line.indexOf(")"));
+  });
+
+  it("omits the token when there is no tool-call id", () => {
+    const line = completed({ toolCallId: undefined as unknown as string });
+    expect(line).not.toContain("{tcid:");
+  });
+
+  it("keeps the id intact alongside the subagent token", () => {
+    const line = completed({
+      tool: "spawn_subagent",
+      toolCallId: "toolu_xyz",
+      input: { task: "research" },
+      output: { subagentId: "conv_child" },
+    });
+    expect(line).toContain("[subagent:conv_child]");
+    expect(line).toContain("{tcid:toolu_xyz}");
+  });
+});
+
+describe("stripPillMetaTokens", () => {
+  it("removes the tcid token (and its leading space) for model-visible text", () => {
+    expect(stripPillMetaTokens("- done `bash` (45ms, ls) {tcid:toolu_abc}")).toBe(
+      "- done `bash` (45ms, ls)",
+    );
+  });
+
+  it("is a no-op for lines without a token", () => {
+    expect(stripPillMetaTokens("- start `web_search` (\"q\")")).toBe(
+      "- start `web_search` (\"q\")",
+    );
+  });
+});

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" } });
+  });
+});