@poncho-ai/sdk 1.15.1 → 1.16.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/sdk@1.15.1 build /home/runner/work/poncho-ai/poncho-ai/packages/sdk
+> @poncho-ai/sdk@1.16.0 build /home/runner/work/poncho-ai/poncho-ai/packages/sdk
 > tsup src/index.ts --format esm --dts
 
 CLI Building entry: src/index.ts
@@ -8,7 +8,7 @@
 CLI Target: es2022
 ESM Build start
 ESM dist/index.js 17.24 KB
-ESM ⚡️ Build success in 18ms
+ESM ⚡️ Build success in 24ms
 DTS Build start
-DTS ⚡️ Build success in 1324ms
-DTS dist/index.d.ts 31.79 KB
+DTS ⚡️ Build success in 1382ms
+DTS dist/index.d.ts 33.61 KB

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @poncho-ai/sdk
 
+## 1.16.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.
+
+## 1.15.2
+
+### Patch Changes
+
+- [`3a25676`](https://github.com/cesr/poncho-ai/commit/3a2567666e1bc8d6650818db76d07765c0250264) Thanks [@cesr](https://github.com/cesr)! - Add a per-run `model` override to `RunInput` (and forward it from `runConversationTurn`'s opts). The override is captured once at run start and wins over the agent definition's `model.name` for every step of the run.
+
+  Previously the only way to vary the model per run kind on a shared harness was mutating `parsedAgent.frontmatter.model.name` before each run — but the harness re-reads that field at the start of every step, so a concurrent run's mutation flipped an in-flight run's model mid-turn. Besides being the wrong model, the switch invalidated the run's entire Anthropic prompt cache (caches are per-model), observed in production as the same ~104k-token prefix being cache-written twice back-to-back, once per model. Callers should pass `model` in the run input instead of mutating frontmatter.
+
 ## 1.15.1
 
 ### Patch Changes

package/dist/index.d.ts

@@ -765,12 +765,37 @@ interface RunInput {
     /** When true, ignores PONCHO_MAX_DURATION soft deadline (used for background subagent runs). */
     disableSoftDeadline?: boolean;
     /**
-     * When true, skip the Anthropic prompt-cache breakpoint for this run.
-     * Use for one-shot runs with no follow-up turn coming (e.g. cron-fired
-     * jobs) — the 1.25× write surcharge is pure waste when no later read
-     * will hit the cache before the 5-min TTL expires.
+     * When true, skip the Anthropic message-history prompt-cache breakpoints
+     * for this run (the 1h static/memory system breakpoints stay on).
+     * Only worth it for runs that are BOTH single-step AND one-shot: the
+     * breakpoint is recomputed every step, so any multi-step run reads its
+     * own growing history through it at 0.1× — disabling that costs far
+     * more than the one wasted 1.25× tail write it saves. (Cron-fired jobs
+     * used to set this; they stopped once job runs grew to dozens of steps.)
      */
     disablePromptCache?: boolean;
+    /**
+     * Volatile per-run context appended to the UNCACHED dynamic tail of the
+     * system prompt (after the agent body / skills / memory blocks, which
+     * carry 1h cache breakpoints). Put content here that changes often and
+     * would otherwise bust the big static cache block if embedded in the
+     * agent definition — e.g. a live file-tree listing or connected-
+     * integrations summary. Re-sent raw on every step, so keep it small.
+     * Orchestrator-initiated turns on the same conversation (subagent
+     * callback resumes) reuse the value captured at parent-turn start.
+     */
+    volatileContext?: string;
+    /**
+     * Model name override for this run, captured once at run start. Takes
+     * precedence over the agent definition's `model.name` for every step of
+     * the run. Use this instead of mutating the parsed agent's frontmatter
+     * when one harness instance serves runs that need different models
+     * (e.g. user turns vs cron jobs) — a frontmatter mutation made while
+     * another run is in flight changes that run's model mid-turn, and the
+     * model switch invalidates its entire Anthropic prompt cache (caches
+     * are per-model).
+     */
+    model?: string;
     /** Scope this run to a specific tenant. */
     tenantId?: string;
     /**
@@ -781,6 +806,14 @@ interface RunInput {
      * exporter-less harness instance per mode.
      */
     suppressTelemetry?: boolean;
+    /**
+     * Extra attributes stamped on the `invoke_agent` root telemetry span,
+     * e.g. `{ "poncho.run.kind": "job", "poncho.job.name": "heartbeat" }`.
+     * Lets observability backends segment traffic classes (jobs vs chat)
+     * without timing forensics. String values only; ignored when telemetry
+     * is off or suppressed.
+     */
+    telemetryAttributes?: Record<string, string>;
 }
 interface TokenUsage {
     input: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/sdk",
-  "version": "1.15.1",
+  "version": "1.16.0",
   "description": "Core types and utilities for building Poncho skills",
   "repository": {
     "type": "git",

package/src/index.ts

@@ -146,12 +146,37 @@ export interface RunInput {
   /** When true, ignores PONCHO_MAX_DURATION soft deadline (used for background subagent runs). */
   disableSoftDeadline?: boolean;
   /**
-   * When true, skip the Anthropic prompt-cache breakpoint for this run.
-   * Use for one-shot runs with no follow-up turn coming (e.g. cron-fired
-   * jobs) — the 1.25× write surcharge is pure waste when no later read
-   * will hit the cache before the 5-min TTL expires.
+   * When true, skip the Anthropic message-history prompt-cache breakpoints
+   * for this run (the 1h static/memory system breakpoints stay on).
+   * Only worth it for runs that are BOTH single-step AND one-shot: the
+   * breakpoint is recomputed every step, so any multi-step run reads its
+   * own growing history through it at 0.1× — disabling that costs far
+   * more than the one wasted 1.25× tail write it saves. (Cron-fired jobs
+   * used to set this; they stopped once job runs grew to dozens of steps.)
    */
   disablePromptCache?: boolean;
+  /**
+   * Volatile per-run context appended to the UNCACHED dynamic tail of the
+   * system prompt (after the agent body / skills / memory blocks, which
+   * carry 1h cache breakpoints). Put content here that changes often and
+   * would otherwise bust the big static cache block if embedded in the
+   * agent definition — e.g. a live file-tree listing or connected-
+   * integrations summary. Re-sent raw on every step, so keep it small.
+   * Orchestrator-initiated turns on the same conversation (subagent
+   * callback resumes) reuse the value captured at parent-turn start.
+   */
+  volatileContext?: string;
+  /**
+   * Model name override for this run, captured once at run start. Takes
+   * precedence over the agent definition's `model.name` for every step of
+   * the run. Use this instead of mutating the parsed agent's frontmatter
+   * when one harness instance serves runs that need different models
+   * (e.g. user turns vs cron jobs) — a frontmatter mutation made while
+   * another run is in flight changes that run's model mid-turn, and the
+   * model switch invalidates its entire Anthropic prompt cache (caches
+   * are per-model).
+   */
+  model?: string;
   /** Scope this run to a specific tenant. */
   tenantId?: string;
   /**
@@ -162,6 +187,14 @@ export interface RunInput {
    * exporter-less harness instance per mode.
    */
   suppressTelemetry?: boolean;
+  /**
+   * Extra attributes stamped on the `invoke_agent` root telemetry span,
+   * e.g. `{ "poncho.run.kind": "job", "poncho.job.name": "heartbeat" }`.
+   * Lets observability backends segment traffic classes (jobs vs chat)
+   * without timing forensics. String values only; ignored when telemetry
+   * is off or suppressed.
+   */
+  telemetryAttributes?: Record<string, string>;
 }
 
 export interface TokenUsage {