@poncho-ai/sdk 1.15.2 → 1.17.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/sdk@1.15.2 build /home/runner/work/poncho-ai/poncho-ai/packages/sdk
+> @poncho-ai/sdk@1.17.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 21ms
+ESM ⚡️ Build success in 22ms
 DTS Build start
-DTS ⚡️ Build success in 1365ms
-DTS dist/index.d.ts 32.36 KB
+DTS ⚡️ Build success in 1468ms
+DTS dist/index.d.ts 33.95 KB

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # @poncho-ai/sdk
 
+## 1.17.0
+
+### Minor Changes
+
+- [#192](https://github.com/cesr/poncho-ai/pull/192) [`bfd8012`](https://github.com/cesr/poncho-ai/commit/bfd80125ad71cd4401221c598faebf71afda2078) Thanks [@cesr](https://github.com/cesr)! - Fix context-compaction correctness so the agent stops losing context and
+  mislabeling failed work after a compaction:
+  - **Turn-based retention.** Compaction now preserves the last N whole _turns_
+    verbatim (new `compaction.keepRecentTurns`, default 4) instead of N messages,
+    which in tool-heavy turns collapsed to just the summary. The preserved side is
+    bounded by a token budget (≤ 50% of the context window) so keeping recent turns
+    can't leave the post-compaction context above the trigger (re-compaction
+    thrash / overflow). Adds exported `findSafeSplitPointByTurns`.
+  - **Faithful summaries.** The summarization output cap is raised 768 → 8192
+    tokens (768 physically truncated summaries mid-content); per-message truncation
+    1200 → 4000 chars, with a total summarizer-input budget that drops the oldest
+    non-error messages first. The prompt now requires a non-omittable "Unresolved
+    errors & failures" section, a "Pending promises" section, forbids claiming
+    unconfirmed completion, and preserves identifiers verbatim.
+  - **Structured subagent task outcome.** New `PendingSubagentResult.taskOutcome`
+    (`succeeded | failed | partial | unknown`) distinct from run status: a subagent
+    that ran but failed its task is no longer recorded as "completed". Subagents
+    self-report a machine-readable verdict; it is parsed deterministically
+    (defaulting to "unknown", never success) and rendered in the callback header
+    and compaction ledger. The subagent digest is enlarged (2000 chars, ungated on
+    status) so the failure reason survives compaction.
+  - **Per-run `maxSteps` override.** New `RunInput.maxSteps` lets a caller raise the
+    step ceiling for foreground turns without raising it for background/job turns
+    that share the same agent definition.
+
+## 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

package/dist/index.d.ts

@@ -765,12 +765,33 @@ 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.
+     * Per-run override for the step ceiling. Takes precedence over the agent
+     * definition's `limits.maxSteps` (default 20). Lets one harness instance run
+     * foreground turns with a higher ceiling than background/job turns without a
+     * frontmatter mutation that would affect concurrent runs.
+     */
+    maxSteps?: number;
+    /**
+     * 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
@@ -792,6 +813,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.2",
+  "version": "1.17.0",
   "description": "Core types and utilities for building Poncho skills",
   "repository": {
     "type": "git",

package/src/index.ts

@@ -146,12 +146,33 @@ 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.
+   * Per-run override for the step ceiling. Takes precedence over the agent
+   * definition's `limits.maxSteps` (default 20). Lets one harness instance run
+   * foreground turns with a higher ceiling than background/job turns without a
+   * frontmatter mutation that would affect concurrent runs.
+   */
+  maxSteps?: number;
+  /**
+   * 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
@@ -173,6 +194,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 {