@vib-rato/agent-core 0.16.0

package/CHANGELOG.md

@@ -0,0 +1,852 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.16.0] - 2026-09-02
+
+## [0.15.6] - 2026-08-30
+
+## [0.15.5] - 2026-08-29
+
+## [0.15.4] - 2026-08-29
+
+### Added
+
+- Added opt-in adaptive compaction thresholding based on context fullness and recent call rate. The default remains disabled, fixed token thresholds keep precedence, and the bounded tracker resets after successful compaction to avoid repeated immediate compactions.
+
+## [0.15.3] - 2026-08-27
+
+### Changed
+
+- Current provider adapters no longer mark syntactically valid `\uXXXX` arguments as guarded: JSON parsing has already produced the canonical string, so valid escaped Hangul, emoji, ASCII, and other scalars execute like literal UTF-8 in every tool. The existing `displaySafeEscapedArgFields` path remains only for compatibility with legacy producers that still attach non-malformed positional evidence. Malformed evidence, unauthenticated managed evidence, incomplete/conflicting arguments, and unpaired surrogates remain fail-closed.
+### Fixed
+
+- Managed fallback snapshots now convert unauthenticated Unicode evidence into `incompleteArgumentsReason: "malformed"` instead of preserving a boolean-only guard that could lose the evidence needed by terminal validation.
+- Compaction no longer crashes on a persisted tool call whose `arguments` payload is null. `serializeConversation` passed that value straight into `Object.entries`, which threw `TypeError: Object.entries requires that input parameter not be null or undefined`. Because this runs inside compaction — itself the recovery path for context overflow — the failure surfaced as `Context overflow recovery failed: Object.entries requires ...`, and the next request went out uncompacted until the provider rejected it with `prompt is too long`. Malformed argument payloads now serialize as an empty argument list instead of aborting the summary.
+
+## [0.15.2] - 2026-08-25
+
+### Changed
+
+- Version 0.15.1 was tagged but never published: release automation failed while deriving release notes, before any package reached npm. Everything listed under `## [0.15.1]` below ships in this release.
+
+## [0.15.1] - 2026-08-25
+- Display-safe escaped tool calls now require bounded raw escape-position/scalar evidence before the post-resample U+2014 exemption can execute. Printable ASCII escapes are retained too, so one-nibble mutations such as `\u00b7` → `\u0077` and `\u2026` → `\u0026` fail closed instead of disappearing after JSON decoding. Evidence carries only raw/decoded offsets, ordinals, location kinds, process-keyed scalar/path tags, a bounded total, and a process-local integrity tag; it is stripped before discarded, rejected, or executed calls can become durable. Exact decoded U+2014 positions/counts must correspond to the complete envelope. Overflow, malformed or duplicate-key JSON, missing/altered evidence, escaped keys, dotted-key ambiguity, excessive nesting, and every other scalar reject terminally. Existing resample/terminal debug records remain shape-only and never include argument payloads.
+- Escaped-non-ASCII turn discards and terminal per-call rejections are now logged at debug severity with bounded shape-only fields. Diagnostics distinguish managed policy handoff from in-loop resampling, type in-loop attempt/budget values as numbers, cap tool-call counts, and report only fixed booleans for registration/display-field contracts; tool names, call ids, arguments, steering text, and payload content never enter the log. The discarded turn never reaches durable history, so the defect previously left no trace anywhere except the surfaced tool error, and its fire rate could only be recovered by scraping session transcripts.
+- `normalizeTools` now converts every Zod-authored tool schema to the wire JSON schema even when intent tracing is off. Previously the conversion ran only inside the `_i` intent-injection branch, so canonical sub-sessions (role agents spawned via `task`, where `resolveIntentTracingEnabled` forces `_i` off) sent a live `ZodObject` across the provider boundary. On append-only context providers (`anthropic`, `deepseek`; auto-enabled) the stable-prefix clone JSON-round-trips tools, and a `ZodObject` without `toJSON` reduces to a bare `{def, type}` object with no `properties`/`required` — the model is then advertised a tool with no parameters and omits required arguments. This is the root cause of issue #4837: every subagent `bash` call failing with `command: Invalid input: expected string, received undefined` while the parent session's identical call worked. Tool argument validation itself is unchanged: executors still validate against the original Zod schema.
+- Managed fallback now transfers safety-stop authority only to the adjudicated final assistant shell; intermediate partial snapshots and hostile accessor-backed final messages cannot retain or bypass the provenance boundary (#4777 review).
+
+- Managed assistant reconstruction now copies provider metadata through guarded property reads instead of an unguarded spread, so accessor-trapped metadata degrades without aborting the attempt or creating managed retry authority (#4777 review).
+- Hostile Proxy-wrapped final messages no longer reintroduce a forged `provider_safety_stop` label through the sanitizer fallback shell; discarded failure outcomes are now label-free before session policy can suppress provider fallback (#4777 review).
+
+
+## [0.15.0] - 2026-08-22
+
+### Fixed
+- Staged-payload sizing no longer materializes what it is bounding (#4602 fix-forward of the exact-head 078e22c0 review). All staging measurements now walk the JSON surface directly: exact byte counts come from a code-point walk (quotes, escapes, separators, delimiters, nulls, array holes, and keys all charged) instead of building the full `JSON.stringify` string plus its UTF-8 encoding, and lone surrogates are charged as the six-byte `\udXXX` escape JSON emits rather than their three-byte UTF-8 form, closing a ~2x undercount on surrogate-heavy strings. `structuredClone` is additionally preflighted by a clone-surface walk that never dispatches `toJSON`, accessors, or proxy traps: a live payload class whose compact `toJSON` hides an oversized own payload is rejected as the typed `local_buffer_overflow` at `overflow.preMeasure` — before the duplicate is allocated — instead of being cloned first and rejected at `overflow.staged`. Accessors are no longer invoked at all while sizing (a staged witness getter is read zero times), `undefined`-valued record properties are skipped exactly as `JSON.stringify` omits them, an unmeasurable assistant pair now fails closed like its `#stage` twin instead of being retained with a zero-byte charge, the `overflow.preMeasure` diagnostic reports the incoming event's real bounded size instead of a constant fabricated after `discard()`, and above-ceiling clamp warnings are logged once per distinct knob value with a bounded digest. |
+- Queue-removal paths (`queue.message.remove`, positional editing, `clearQueue`, the terminal-abort purge) now fire the stored promotion hook with a removal disposition so an accepted SDK submission terminalizes boundedly instead of staying accepted forever (#4668).
+- Provider safety-stop messages now retain their explicitly allowlisted `errorKind: "provider_safety_stop"` through managed assistant snapshots and remain terminal even when transport facts are present on a multi-model fallback chain, while provider payloads still cannot forge the runtime-owned local diagnostic kinds (#4777).
+- Terminal safety-stop authority is now provenance-bound instead of data-bound: a provider or custom stream payload that self-labels `errorKind: "provider_safety_stop"` without the adapter-minted mark is stripped at the stream exit before any retry/discard gate or the managed snapshot shell reads it, so a compromised provider can no longer force refusal by naming the field (#4777 review). Authenticated first-party envelopes (structured refusal signals parsed by the anthropic, openai-completions, and google adapters) keep terminal treatment, and only the agent loop's module-private rebuild set carries that authority onto its own destination — clones, JSON/persistence round-trips, and re-emitted payloads are all unauthenticated.
+- Safety-stop minting is now limited to the package-private adapter capability, and public AI consumers cannot transfer authority from a genuine marked source to an arbitrary destination. The trailing stream-completion path also sanitizes provenance before rebuilding managed assistant messages, covering streams that end without a `done` or `error` event and keeping forged labels fallback-eligible (#4777 review).
+- Safety-stop authority now expires at every stream dispatch entry: committed assistant messages (including a previously adjudicated stop) are handed to the next — possibly custom — stream through `convertToLlm`, and the dispatch-entry expiry guarantees no live authority mark is ever exposed to a stream, so re-use of a committed stop object cannot forge a terminal failure (#4777 review). The provenance strip is also stopReason-independent and rebuilds frozen or Proxy-trapped final messages as plain mutable copies, so a forged label on a nominally successful response cannot survive into the committed message (where it could skip session compaction checks) and cannot abort the run through a rejection trap.
+- A foreign error that self-declares a local failure kind no longer gets one either (#4618). `errorKind` and the structured `bufferOverflow` shape now come from a single identity-checked extractor (`managedLocalErrorDiagnostic`) used by both terminal-message producers — `managedFailureMessage` and the `Agent` run catch. Previously the shape was identity-gated but the label was not, so a provider or custom-stream failure carrying `errorKind: "local_buffer_overflow"` reached the parent receipt preview as `Local staging-buffer overflow; structured diagnostic unavailable.` and pointed whoever read it at the wrong subsystem.
+- Local diagnostic authority fields are no longer foreign-settable through the managed snapshot shell (#4618). `managedAssistantShell` spreads the provider/stream message snapshot into the rebuilt assistant message; a payload that smuggled a local `errorKind` or `bufferOverflow` through that spread could masquerade as the runtime's own identity-checked diagnostic at the parent boundary. Local kinds and `bufferOverflow` remain stripped from the snapshot spread, while the provider-owned safety-stop kind is copied only through its explicit closed-literal guard.
+
+- Documented the accepted-prompt lifecycle hooks: `onFollowUpConsumed` and `onSteeringConsumed` now report `startsOwnRun` so integrations can distinguish new-run ownership from in-run or maintenance consumption. The agent also emits the typed `agent_failed` lifecycle event before an error terminal, allowing SDK hosts to reconcile failure causes and teardown ownership deterministically.
+- `Agent.waitForSteeringArrival(signal)` resolves when steering is queued without consuming it, so wait-style tools can end their observation early.
+- Managed fallback provisional-buffer caps are now operator-configurable: `GJC_FALLBACK_MAX_STAGED_EVENTS` (default 10000, hard ceiling 2000000) and `GJC_FALLBACK_MAX_STAGED_BYTES` (default 16 MiB, hard ceiling 1 GiB) bound the events/bytes staged by the provisional staging transaction in both managed fallback and ordinary (non-managed lossless) sessions; in non-managed sessions the cap only decides how much reasoning buffers before the batch flushes and streams through. Values are read once per attempt; the trusted environment resolver ignores surrounding whitespace, while invalid or non-positive values fall back to the defaults, and values above the ceiling clamp to it with a warning so the staging guard stays bounded instead of trading a typed `local_buffer_overflow` for a process OOM. Every retained batch item — including the assistant message/event pair staged for streaming callbacks — is measured and charged against the caps BEFORE it is retained, so actual retention can never exceed the counted bounds, and the ceilings are set from total retained memory (2,000,000 events / 1 GiB) at values an ordinary host survives. The knobs resolve from trusted environment sources only (`$credentialEnv`, which excludes the repository `cwd/.env` overlay), so a project cannot weaken or weaponize the staging guard. Raise both to survive reasoning-heavy streaming in long-running sessions and `gjc team` workers (#4602, #4618).
+
+### Fixed
+- The escaped-non-ASCII argument guard keeps its fail-closed terminal rejection and its unconditional two-resample budget for every tool and every field. After the budget is spent, one narrowly scoped exemption applies: a tool that enumerated its user-facing display fields (`displaySafeEscapedArgFields`; `ask` exempts only `questions.question` and `questions.options.label`) executes when every non-ASCII character lives inside those fields and is benign typographic punctuation (curated set: U+2014 em-dash). Escaped non-ASCII anywhere else — ids, deep-interview metadata, persisted records, non-ASCII object keys — and every other tool stays rejected terminally (#4627, reduced per both maintainer reviews: guard retained, exemption post-budget and field-scoped).
+
+- Escaped-non-ASCII turn resamples are now steered instead of blind: each unmanaged resample carries a transient synthetic instruction naming the `\uXXXX` defect and demanding literal UTF-8, so a model that escapes deterministically (observed with Hangul-heavy `ask` payloads exhausting the whole resample budget every turn) has a reason to change its spelling on the retry. The instruction never lands in durable history, tools stay enabled, and the captured logical-turn tool choice is still replayed across the steered attempts; a pending one-shot malformed-tool-call recovery is never displaced by the steering. Managed fallback retries receive the same steering: the typed `escaped_arguments_discarded` outcome now reports whether the discarded attempt still lacked an instruction, and the session's retry continuation attaches the same transient message through the new `transientRecoveryMessage` prompt option, so coding-agent sessions (which run managed) also get exactly one steered re-request before the budget ends.
+
+## [0.14.1] - 2026-08-18
+- Compaction pruning no longer kills the turn when a persisted `toolCall.arguments` is `null`. Sessions written by an earlier cold-spill eviction path store `null` where the spill sentinel belongs, and the staleness index dereferenced that payload unguarded, so reloading such a session threw `null is not an object (evaluating 'args.path')` as a turn-fatal error instead of skipping the one unusable call. `ToolCall.arguments` is typed non-nullable, so no type check flagged the gap. Every read of a persisted argument bag — path extraction, `apply_patch` header parsing, idempotent-bash keys, and search target keys — now treats a non-object payload as absent. The original arguments are not lost: the eviction marker still names the blob and rehydration restores them.
+- Managed fallback attempt snapshots no longer fail the whole run on benign provider shape variations: an assistant message whose `content` is a bare string, is missing, or is a primitive scalar (null/number/boolean) now degrades to an empty content array; staged `*_delta`/`*_end` events whose `delta`/`content` is missing or a primitive scalar degrade to an empty string; and staged assistant events with out-of-vocabulary `done`/`error` reasons or an unknown string `type` degrade to schema-valid values instead of throwing a non-retryable `ManagedAttemptSnapshotError`. Object-shaped or other plain-object `content`/`delta` stays fail-closed under the named `shell.content`/`event.delta`/`event.content` diagnostic, as does sanitizer-sentinel string content (`[unserializable]`/`[accessor]`/`[truncated]`/`[Circular]`, which marks a non-cloneable original rather than provider string variance — degrading those would silently drop real tool-call or streamed content behind a successful empty turn), and hostile inputs keep failing fast with no retry authority: a live proxy root, a throwing `get`/`getOwnPropertyDescriptor` trap, and a non-string event `type` all remain local snapshot failures.
+
+### Added
+
+- `toolFailureEnvelope` / `isToolFailureEnvelope` / `ToolFailureEnvelope` name the result details the loop attaches when a tool call fails without the tool returning details of its own. The guard matches only that envelope, so a consumer can tell it apart from a tool that reports a `failureKind` alongside its own details before dereferencing a tool-owned detail shape.
+- `ManagedAttemptBufferOverflowError` (`local_buffer_overflow`) now reports its full shape everywhere it can reach: the rejecting `stage`, which cap tripped (`exceeded: events|bytes|both`), the retained post-compaction staged event/byte counts, the rejected event's own serialized size, and both caps. The typed error carries this as a structured object, the terminal `AssistantMessage` carries an identity-checked `bufferOverflow` copy (only the module-private error class can attach it, so a foreign self-labeled error cannot), and the surfaced message keeps its stable prefix and appends the same shape-only values stating this is a local staging-buffer limit that reproduces on re-issue, not a provider or context-window failure. Previously every overflow surfaced as one static sentence with no way to tell an event-cap from a byte-cap trip or to distinguish it from a model-context problem (#4618).
+
+## [0.14.0] - 2026-08-17
+
+### Fixed
+
+- Managed fallback no longer kills a long turn with `Managed fallback attempt exceeded the provisional event buffer limit`. Every staged streaming frame carries the whole accumulated partial (once as `message`, once as `assistantMessageEvent.partial`), so staged bytes grew quadratically with the response length and a reasoning-heavy turn of a few thousand tokens crossed the 16 MiB cap even though no single event came close to it. Reaching the cap now first reclaims the staged `*_delta` increments, whose complete value is re-published by the retained `*_end` and terminal `message_end`/`done` frames, and only a batch that still cannot fit fails. Attempt atomicity is unchanged: nothing is published early, so a discarded attempt stays unobservable, and a single oversized event keeps its pre-clone rejection with no provider-fallback authority.
+- Non-managed lossless response staging now commits its buffered lifecycle and switches to ordinary pass-through publication when the provisional event cap is reached, instead of turning a large reasoning-only response into a fatal `local_snapshot_failure`. Managed fallback attempts keep the strict bounded-buffer rejection required for atomic retry and provider-fallback isolation.
+- Managed snapshot machinery no longer fails runs on benign payload-class or readable-proxy roots: an assistant message or stream event whose fields live on prototype getters (which `structuredClone` drops — it copies only own enumerable properties) or behind a proxy whose gets are readable is repaired through the existing guarded-read path instead of throwing a deterministic `shell.role`/`event.unknownType`/`event.snapshot` local snapshot failure. The run-loop message_update replay also builds its event through the managed event snapshot instead of a naive `{ ...event }` spread, which silently dropped prototype-carried fields before the snapshot boundary could see them. Hostile shapes (throwing get traps, sentinel-marked degraded content, malformed non-string event types) keep their named fail-fast diagnostics with no retry authority.
+
+- Managed fallback now validates and byte-measures the detached event snapshot rather than trusting the live payload's JSON result. Custom payload classes whose prototype `toJSON()` hides bigint state are sanitized after `structuredClone` removes that serializer, so every accepted snapshot stays detached, JSON-serializable, and bounded; residual typed `local_snapshot_failure` diagnostics remain outside provider fallback authority and surface without deterministic retry amplification.
+- Managed fallback buffer overflows now retain a typed `local_buffer_overflow` error kind on the terminal assistant message, so session retry policy surfaces them immediately without provider-fallback attribution instead of admitting them to the bounded `unknown` retry class.
+- Managed local-failure diagnostics: `ManagedAttemptSnapshotError` and `ManagedAttemptBufferOverflowError` now carry a stable `stage` discriminator naming the exact rejecting site (`shell.role`, `shell.content`, `event.snapshot`, `event.contentIndex`, `event.delta`, `event.content`, `event.toolcall`, `event.done.reason`, `event.error.reason`, `event.unknownType`, `staging.losslessSnapshot`, `staging.measure`, `staging.sanitize`, `staging.overflow`, `overflow.preMeasure`, `overflow.staged`), and the run-loop failure boundary emits ONE bounded shape-only `logger.warn` per stream invocation (stage, error kind, model, provider, snapshot mode, staged event count/bytes, and content block count for the content stage). The diagnostic is gated on the module-private local error identities and its stage is whitelisted against the closed vocabulary, so neither a foreign error that self-labels a local failure kind nor an in-module regression can route arbitrary text into the log; it never records raw text, thinking, tool arguments, or any provider payload, and the user-facing message string is unchanged so session-side classification keeps matching. Previously all 14 rejecting sites shared one static message, leaving no way to identify which provider shape a normalizer must be taught to accept.
+- A turn whose tool arguments arrive flagged `escapedNonAsciiArguments` is now resampled instead of being reported as a tool failure: the defective assistant turn is dropped from history and the request is re-issued, up to twice per turn, before the terminal per-call rejection takes over. Hand-spelled `\uXXXX` arguments decode into valid-looking but silently wrong text (observed as garbled Hangul in `ask` prompts) and no post-parse repair can recover them, but the defect is a wire-format accident that resampling clears - surfacing it as a tool error instead burned the whole turn and fed the literal escape syntax back into the context the model samples from next. Scoped to the non-managed session path, matching the existing `invalid_prompt` and reasoning-content repairs; managed fallback keeps owning its own retry policy.
+- Visible-text Harmony leak retries now close the already-published assistant lifecycle with an empty aborted terminal stripped of raw provider payload before contaminated history is removed and a replacement request begins, preventing both orphaned streaming updates and leaked control text in durable history or replay.
+- Unmanaged escaped-non-ASCII resampling now stages a detached, provider-metadata-preserving assistant lifecycle until validation, publishes live safety updates before dispatch, and defers terminal `message_end` publication until subscriber-triggered cancellation is resolved so persisted assistant state and aborted tool-result pairing cannot disagree.
+- The agent loop still rejects a tool call flagged `escapedNonAsciiArguments` before execution once the resample budget is spent, with a retryable error telling the model to re-issue the call writing non-ASCII characters literally.
+- Managed fallback attempt snapshots no longer fail the whole run on benign provider shape variations: an assistant message whose `content` is a bare string or is missing now degrades to an empty content array, and staged assistant events with out-of-vocabulary `done`/`error` reasons or an unknown string `type` degrade to schema-valid values instead of throwing a non-retryable `ManagedAttemptSnapshotError`. This matches the closed `StopReason` vocabulary already normalized elsewhere in the shell. Object-shaped and other exotic non-array `content` stays fail-closed under the named `shell.content` diagnostic, as does sanitizer-sentinel string content (`[unserializable]`/`[accessor]`/`[truncated]`/`[Circular]`, which mark a non-cloneable original value such as a proxy-wrapped content array rather than provider string variance — degrading those would silently drop real content behind a successful empty turn), and hostile inputs keep failing fast with no retry authority: a live proxy root, a throwing `get`/`getOwnPropertyDescriptor` trap, and a non-string event `type` all remain local snapshot failures.
+
+### Added
+
+- Reassignable `onFollowUpConsumed` hook on `Agent`: invoked with the follow-up messages the loop dequeues for the next turn, so consumers can attach per-turn state (e.g. a fresh owned-completion lineage) at actual resume admission.
+- `AgentPromptOptions.onRunAccepted` now receives a typed acceptance payload containing `consumedQueuedMessages`, allowing consumers to bind ownership and other per-message state only to the queued messages actually claimed by the accepted run.
+## [0.13.3] - 2026-08-15
+
+### Fixed
+- Emergency compaction now considers managed transcript file size so sessions compact before the managed per-file limit (#4411).
+- Managed runs discard assistant turns whose tool calls carried `\uXXXX`-escaped arguments and report them through the typed `escaped_arguments_discarded` outcome instead of executing unverifiable text; unmanaged runs reject such calls per-call with an actionable error (#4515).
+
+## [0.13.2] - 2026-08-13
+
+## [0.13.1] - 2026-08-11
+
+## [0.12.21] - 2026-08-09
+
+## [0.12.20] - 2026-08-09
+
+## [0.12.19] - 2026-08-08
+
+## [0.12.18] - 2026-08-08
+
+## [0.12.17] - 2026-08-08
+
+## [0.12.16] - 2026-08-08
+
+### Fixed
+
+- Forked-session restore no longer crashes when the seeded append-only prefix includes a tool whose `intent` policy is a deferred function (e.g. `eval`, `bisect`, `checkpoint`, `rewind`). `StablePrefix.importSnapshot` re-normalized the cloned tool JSON, which loses function-valued `intent` fields, so those tools flipped from `omit` to `optional` intent injection and the recomputed fingerprint diverged from the stored one (`StablePrefix.importSnapshot() fingerprint mismatch`). Import now verifies against the stored, already-normalized tools instead of re-normalizing.
+
+## [0.12.15] - 2026-08-06
+
+## [0.12.14] - 2026-08-06
+
+## [0.12.13] - 2026-08-06
+
+### Fixed
+
+- An aborted run whose tool ignores its `AbortSignal` now terminates on its own (#3894). `Promise.allSettled` waited on the unresolved call forever, so the turn only ended when the session's force-abort budget expired; the loop now emits a synthetic aborted result for the outstanding calls and `waitForIdle` settles immediately. Session dispose consequently reaches idle through the cooperative path instead of force-invalidating the run.
+
+### Changed
+
+- Telemetry configured with `spans: false` now skips span and attribute construction while preserving usage and cost hooks.
+
+## [0.12.12] - 2026-08-05
+
+### Fixed
+
+- DeepSeek-family reasoning-content replay 400s are now retryable via a bounded, strip-only circuit breaker. When a proxy strips the encrypted reasoning blob to an empty `encrypted_content`, DeepSeek rejects every follow-up turn with "The `reasoning_content` in the thinking mode must be passed back to the API." Resending the identical history re-triggers this deterministic 400, so the agent loop now strips the unusable `reasoning` items from the Responses history payload in place and resends exactly once (mirroring the `invalid_prompt` poisoned-history breaker). Non-reasoning items are preserved; fail-fast when nothing can be stripped. Budget = one repaired resend.
+
+## [0.12.11] - 2026-08-03
+
+## [0.12.10] - 2026-08-03
+
+### Fixed
+
+- Composer repository-file shell policy rejections now receive one bounded, tool-enabled recovery turn without persisting the synthetic instruction. Generic loops retain their repository tools with `toolChoice: auto`; Cursor remote turns continue only when native tools did not already recover, queued user follow-ups take priority, and a second policy block terminates instead of looping. Existing malformed-tool recovery remains tool-free and does not consume dynamic tool-choice state.
+
+## [0.12.8] - 2026-08-02
+
+## [0.12.7] - 2026-07-31
+
+## [0.12.6] - 2026-07-31
+
+## [0.12.5] - 2026-07-30
+### Fixed
+
+- Proxy streams now fail closed when a `toolcall_end` event references missing or non-tool-call content instead of silently dropping the protocol violation and accepting a later terminal event.
+
+## [0.12.4] - 2026-07-30
+
+## [0.12.3] - 2026-07-30
+
+## [0.12.2] - 2026-07-30
+
+## [0.12.1] - 2026-07-29
+- Agent session configuration can carry an explicit first-event stream timeout while preserving provider defaults when the setting is absent.
+
+### Fixed
+
+- The `invalid_prompt` circuit breaker no longer replays the rejected turn on its repaired resend. The streaming path commits the failed assistant message to the context before the breaker runs, so the one repaired resend re-sent that errored turn as if the model had spoken it — re-triggering `Request blocked (code=invalid_prompt)` and leaving a second assistant tail that no continuation can resume from. The breaker now repairs and resends only the history that preceded the rejection.
+- Compaction pruning now protects the newest two user/`bashExecution` turns, uses conservative read supersession, preserves bounded error-first diagnostics, and exposes reversible artifact-backed originals with exact savings accounting.
+- Cancelling a prompt no longer fails its terminal closed. `agent_end` is published before the run resource ledger is sealed, so the event's own handlers register post-prompt work against an already-sealed run; that late registration was treated as an escaped resource and quarantined the run, making `waitForSettlement` report `unfenced` forever. Cancel therefore never obtained settlement proof and the SDK refused to publish a terminal, surfacing over ACP as `-32603 "Prompt resources did not settle before the terminalization grace expired."` Sealing now only freezes admission of genuinely new work; post-seal registration joins ordinary settlement accounting so the run stays unsettled until it actually completes.
+
+## [0.11.11] - 2026-07-26
+
+### Fixed
+
+- Managed runs now release their logical-run ownership before terminal observers are notified, so terminal overflow recovery cannot leave a stale owner behind.
+- The OpenAI remote-compaction endpoint is now resolved from trusted environment sources only. `OPENAI_BASE_URL` was read through the merged view that includes the caller's `cwd/.env`, so a repository could redirect compaction requests that carry the OpenAI credential; it now uses the non-project resolver, leaving shell and user-level configuration unchanged.
+- Repeated malformed tool calls now get one tool-free recovery response, preventing argument-validation loops from ending without an answer while leaving ordinary execution-error retries unchanged. The recovery turn commits its assistant to the durable context, forces `toolChoice: "none"` alongside an empty tool list without consuming a queued tool choice, and never executes a tool call it did not advertise. Its recovery prompt is request-only, so append-only tool prefixes stay stable and the durable message log is unchanged.
+- Argument-validation loops now reach a deterministic terminal state. If a model keeps emitting only malformed tool calls after the one-shot recovery turn, the run stops with an explanatory error instead of calling the provider indefinitely. The bound counts consecutive all-malformed turns rather than repeated argument signatures, so a model rotating invalid argument shapes is bounded too; any healthy tool turn resets it.
+
+## [0.11.8] - 2026-07-23
+
+### Fixed
+
+- Managed model fallback now accepts `reasoning_summary_start`, `reasoning_summary_delta`, and `reasoning_summary_end` assistant events instead of failing them as local snapshot errors.
+## [0.11.3] - 2026-07-19
+
+### Fixed
+- Pre-compaction pruning now preserves bounded, actionable error evidence instead of discarding it, while enforcing exact positive-savings admission and accounting so a prune is only applied when it demonstrably reduces context cost (#2635).
+
+## [0.11.1] - 2026-07-16
+
+### Fixed
+
+- Hardened the managed fallback attempt snapshot: staged agent events and assistant partials were cloned with a bare `structuredClone`, so a single non-cloneable value in a staged payload (e.g. a live `Headers` inside `transportFailure`) threw `DataCloneError` ("The object can not be cloned."), masked the real provider outcome, and deterministically failed every attempt until the fallback chain exhausted. The snapshot now degrades to a cycle-aware sanitizing deep clone that always returns a detached, JSON-serializable value (unsupported leaves become placeholders), so event-time replay semantics are preserved and no local snapshot failure can masquerade as a provider attempt failure. Byte accounting in the provisional buffer measures the raw event before the snapshot duplicates it (over-limit payloads are rejected pre-clone), re-measures degraded snapshots so the retained sanitized form is what gets accounted, and uses the sanitized detached form as the cycle-safe estimator for cyclic payloads.
+- Enforced the managed fallback authority boundary for local staging failures: `ManagedAttemptBufferOverflowError` no longer carries a synthetic provider-like `503` status, so exceeding the provisional event buffer limit (like any other local snapshot failure) is non-retryable, never converts into `transportFailure { kind: "transport", status: 503 }` evidence, and never rotates or consumes the model fallback chain — it surfaces as an explicit local error instead. Only original typed provider transport facts may authorize provider fallback.
+- Added a bounded, neutralize-only `invalid_prompt` circuit breaker to the agent loop (#2282). A poisoned-history rejection (`Request blocked (code=invalid_prompt)`) is a deterministic content fault: re-sending the same history re-triggers it, so uncontrolled session auto-retry would burn its budget re-poisoning the model. On the first `invalid_prompt` of a run, leaked reserved control tokens are neutralized in place across history (no item is ever dropped). If that changes the outgoing bytes, the turn is resent exactly once with the repaired history; if neutralization cannot change anything, the run fails fast immediately with no resend. The repaired history is persisted for a clean resume, the breaker fires at most once per run (budget = one repaired resend), and it is scoped to the non-managed session path since managed fallback owns its own retry policy.
+
+## [0.10.2] - 2026-07-14
+
+### Fixed
+
+- Extended the gpt-5.6 `Request blocked (code=invalid_prompt)` fix to the compaction paths that bypass the streaming transport. Remote OpenAI compaction (`/responses/compact`, `compaction.remoteEnabled` default on — the "remote compact task" in openai/codex#32028) built its native `input` from reasoning signatures, verbatim history items, and message/tool text without neutralizing leaked Harmony control-token markers (e.g. `<|channel|>analysis`), so gpt-5.6 rejected the compaction request and, on retry, could escalate to account-level blocking. `requestOpenAiRemoteCompaction` now neutralizes reserved control tokens across the whole outgoing `input`, and the generic `requestRemoteCompaction` prompt/systemPrompt are neutralized too. Local summarization was already covered by the streaming-transport request-boundary fix.
+
+### Changed
+
+- `AgentLoopConfig.maintainContext` now receives a required cancellation-aware lifecycle (`signal`, `awaitEventDrain(invocationSignal)`). Agent loops compose the run and maintenance-invocation signals and pass that single signal to EventStream's FIFO consumer-drain barrier, so cancellation removes the pending drain at its owner instead of racing an orphaned wait.
+
+## [0.10.0] - 2026-07-12
+
+### Fixed
+
+- The native-free token heuristic is now script-aware: common-BMP CJK characters (Hangul, unified/compat Han, Kana, CJK punctuation, full-width forms) are charged at 1 token each (measured o200k_base upper bound 0.96 tokens/char) and supplementary code points (surrogate pairs: rare Han extensions, emoji) at 1 token per code point, instead of chars/4 for everything. The old estimate undercounted Korean/CJK-heavy unsent context by 2–4x and could delay threshold compaction past the provider window; ASCII estimates are unchanged. `boundConversationTextForSummary` now derives its truncation cut from the text's own estimated token density, validates the complete assembled excerpt (elision marker included) against the estimator, and fails closed — bare marker only when the marker itself fits the budget, otherwise an empty excerpt, including when the computed input budget is non-positive — instead of assuming 4 chars/token and returning over-budget or unbounded text.
+
+- A tool call for a name absent from the active tool set now appends a recovery hint pointing at `search_tool_bm25` (gated on a callable `search_tool_bm25`, matched by internal name or `customWireName`), so a model no longer abandons a discoverable tool such as `task` after a bare "Tool <name> not found"; the base error wording stays byte-for-byte stable when discovery is unavailable (#2042).
+
+## [0.9.2] - 2026-07-09
+
+### Fixed
+
+- Follow-up queues can now mark individual messages as one-at-a-time, so interactive composer queues can remain sequential without disabling the existing batch mode for other callers.
+
+## [0.8.2] - 2026-07-06
+### Added
+
+- Agent queues now expose ordered move helpers for steering and follow-up messages so callers can reorder pending work without removing and re-adding messages.
+
+### Fixed
+
+- Preserved inherited fork-context seed messages when a compacted child rebase receives only child-local normalized messages, avoiding seed loss after task-child compaction (#1567).
+
+## [0.7.7] - 2026-06-28
+
+### Fixed
+
+- Mitigate leaked Anthropic-style `<invoke name="…">` tool-call envelopes across providers, not only `openai-codex`, while keeping Codex `to=functions.*` harmony-header mitigation provider-scoped.
+
+## [0.7.4] - 2026-06-27
+
+### Added
+
+- Added `pruneAssistantToolArguments`: an isolated pre-compaction pruning pass that redacts stale `edit`/`write`/`apply_patch`/`ast_edit` tool-call argument payloads only when every touched path group has a later successful mutation, preserving tool-call identity (id/name/customWireName/signatures/intent/path hints), protecting latest/failed/ambiguous calls, and reporting separate stats from tool-result pruning. Reduces pre-compaction context pressure and the resident footprint of superseded large edit arguments.
+
+## [0.7.3] - 2026-06-25
+### Added
+
+- Added Composer evidence publication gates in the agent loop, so Composer-harness turns emit structured evidence under defined publication conditions (#1106).
+
+### Fixed
+
+- Wired the previously-dead GPT-5 harmony-leak detector into the streamed assistant-message path for openai-codex turns: recoverable tool-argument leaks are now recovered and everything else is routed through the existing abort-retry/audit loop, and the contaminated streamed message is removed (abort-retry) or replaced (truncate-resume) from working context so the model does not replay its own leak as history. Added detection of the leaked Anthropic-style `<invoke name="…">` envelope dialect that gpt-5.5 intermittently emits as visible assistant text instead of a native function call (#1069).
+- Detect proxy-level context overflow from empty responses: some proxies (notably LiteLLM) return an empty `content: []` with `stopReason: "stop"` and fabricated near-zero usage when the upstream context window is exceeded; the agent loop now recognizes this pattern and promotes it to an error so the existing overflow/compaction recovery path fires instead of freezing the session as a clean completion (#1102).
+- Hardened the Composer trace mutation classifier and its recovery-target guard (#1105).
+
+## [0.7.2] - 2026-06-24
+
+### Fixed
+
+- Reserved headroom when trimming OpenAI remote compaction input so `/responses/compact` requests stay below the model context window instead of filling the entire window.
+
+## [0.6.2] - 2026-06-19
+
+### Changed
+
+- Token accounting no longer depends on a native embedded tokenizer. Token usage now anchors on provider-reported usage (`calculatePromptTokens`) and estimates only the unsent delta with a cheap heuristic (~chars/4 × 1.2); emergency compaction floors are unchanged. Compaction, branch summarization, and fork-seed paths were repointed off the removed native token-estimate alias. Part of dropping the bundled tiktoken/o200k tokenizer (#879).
+
+## [0.5.4] - 2026-06-17
+
+### Fixed
+
+- Maintenance one-shot LLM calls now preserve active provider session state and the configured WebSocket transport preference. `SummaryOptions`, `HandoffOptions`, and `GenerateBranchSummaryOptions` accept `sessionId`, `providerSessionState`, and `preferWebsockets`, and `generateSummary`, `generateShortSummary`, `generateTurnPrefixSummary`, `generateHandoff`, `generateBranchSummary`, and `compact()` forward them through to `completeSimple` — previously these fields were dropped, so Codex/OpenAI-compatible compaction summaries, handoff generation, and branch summaries fell back to HTTP/SSE and lost `session_id` affinity even with `providers.openaiWebsockets: "on"`. Split-turn compaction now runs its history and turn-prefix summaries sequentially when they share a single provider WebSocket session, avoiding `websocket request already in progress`; non-WebSocket sessions still run them in parallel. `Agent` exposes a `preferWebsockets` getter so callers can forward the live transport preference (#736).
+
+## [0.5.3] - 2026-06-16
+
+### Fixed
+
+- Bounded agent context growth, compaction, and token accounting for long-running sessions: `appendMessage` pushes in place instead of rebuilding the array; the append-only context keeps rolling per-message hashes instead of rescanning the full digest; an emergency-compaction floor that cannot be disabled now surfaces its reason; `getSessionStats` is single-pass; and `nativeCountTokens` skips the synchronous ~39 MB BPE tokenizer above a 2 MiB input cap, falling back to the cheap heuristic (#717).
+
+## [0.5.2] - 2026-06-15
+
+### Fixed
+
+- Fixed compaction token estimation in Bun standalone binaries by loading the native tokenizer through the sibling native entrypoint instead of package-name dynamic resolution.
+
+## [0.5.1] - 2026-06-14
+
+- Version aligned with the 0.5.1 monorepo release; no functional changes in this package.
+
+## [0.5.0] - 2026-06-13
+
+### Fixed
+
+- Fixed compaction cut-point selection when the newest retained context ends in an uncuttable tool result, so automatic compaction can keep the latest assistant/tool-result pair instead of falling back to a no-op cut.
+
+### Changed
+
+- Optimization Suite v3 Lane 2 (context cost): compaction token estimates now use a shared per-entry cache (`estimateEntryTokens`) keyed by a boundary-lossless fingerprint of the exact estimator fragments, covering `estimateEntriesTokens`, the `findCutPoint` reverse walk, and pruning candidate scoring — repeated full-session estimate p95 −97%, token totals exactly equal to fresh estimates and never stale after prune mutation. Pruned bash/search/grep tool results now carry a one-line digest notice (exit code, match/file count, first error line; capped at 1.25× the generic notice cost) instead of a bare truncation notice, with savings computed from the exact notice string; reads and other tools keep the generic notice. `trimOpenAiCompactInput` is O(n) via per-item serialized lengths and a running character sum (5k-item trim −99.9%) and is now exported.
+- Optimization Suite v3 Lane 3 (serialization): `cloneJson` in the append-only context now uses a typed JSON-semantic recursive clone instead of a `JSON.parse(JSON.stringify())` round-trip (−36% median on clone-heavy paths), with exact JSON.stringify byte parity including the toJSON holder-key protocol (single get, no re-dispatch on replacement values), function/symbol dropping, sparse arrays, Dates, and prototype-bearing objects; the helper is now exported.
+
+## [0.4.5] - 2026-06-12
+
+### Changed
+
+- Made tool-output pruning staleness-aware: results superseded by a later same-target result (re-read file, re-run search) or invalidated by a later successful edit/write are pruned before merely-old ones, including inside the recency protect window. New optional `PruneConfig.staleOverridableTools` (default `["read"]`) waives protected-tool immunity for superseded results while the most recent result per target stays protected. Target identity uses collision-proof canonical JSON tuple keys.
+- `PruneResult` now returns `prunedEntries` so callers whose entry source materializes copies (e.g. blob-externalized session entries) can write mutations back into their canonical store.
+
+### Fixed
+
+- Preserved Cursor-native tool call rendering and execution through the agent tool-call path, including runtime tool details.
+
+## [0.4.4] - 2026-06-10
+
+- Version aligned with the 0.4.4 monorepo release; no functional changes in this package.
+
+## [0.4.3] - 2026-06-10
+
+### Fixed
+
+- Separated a model's total context window from its safe input/prompt-packing budget in the compaction threshold. `effectiveReserveTokens`, `resolveThresholdTokens`, and `shouldCompact` now accept an optional `maxOutputTokens` and reserve at least that completion budget, so a large-output model (e.g. 400K context / 128K max output) caps input near 272K instead of 340K and cannot overflow the total window with reserved output ([#442](https://github.com/Yeachan-Heo/gajae-code/issues/442)).
+
+## [0.4.0] - 2026-06-06
+
+### Changed
+
+- Refreshed agent-core package metadata for the GJC 0.4.0 release.
+
+## [0.3.1] - 2026-06-05
+
+### Fixed
+
+- Moved the env-driven full message content capture warning into agent-core telemetry resolution so direct `@gajae-code/agent-core` consumers receive `full_content_capture_env_active` when `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=full` is used without an explicit `captureMessageContent` override.
+
+### Changed
+
+- Clarified that telemetry `summary` content capture emits bounded real-content snippets in `pi.gen_ai.*` attributes and is not redacted or PII-free.
+
+## [0.2.4] - 2026-06-02
+
+### Added
+
+- Added agent options for provider request and stream retry budgets and thread them through streaming calls.
+
+## [0.2.2] - 2026-05-31
+
+### Changed
+
+- Refreshed agent-core package metadata for the GJC 0.2.2 release.
+
+## [0.2.1] - 2026-05-30
+
+### Changed
+
+- Refreshed agent-core package metadata for the GJC 0.2.1 release.
+
+## [0.2.0] - 2026-05-28
+
+### Changed
+
+- Refreshed agent-core package metadata for the GJC 0.2.0 release.
+
+## [0.1.3] - 2026-05-28
+
+### Changed
+
+- Released the current dev branch fixes with refreshed 0.1.3 package metadata.
+
+## [0.1.2] - 2026-05-28
+
+### Changed
+
+- Updated package metadata for the Gajae Code npm publication.
+
+## [0.1.1] - 2026-05-28
+
+### Added
+
+- Added `Agent.forceAbort()` so hosts can recover from provider/tool aborts that ignore cooperative cancellation without clearing conversation history.
+
+## [15.3.0] - 2026-05-25
+### Fixed
+
+- Fixed `transformContext` receiving the loop config object as the `signal` argument instead of the actual `AbortSignal`, so hooks that check `signal.aborted` or call `signal.addEventListener` now work correctly under abort/timeout conditions
+- Fixed `appendOnlyContext` not being re-evaluated after `setModel()` — the mode was decided once at session construction based on the initial model's provider, so switching from/to DeepSeek (or changing `provider.appendOnlyContext`) mid-session produced incorrect mode behavior
+
+## [15.2.3] - 2026-05-22
+### Added
+
+- Added `onBeforeYield` hook support so user code can run right before the agent loop checks for follow-up messages
+
+## [15.1.3] - 2026-05-17
+### Added
+
+- Added optional `telemetry` support to `generateSummary`, `generateHandoff`, `generateBranchSummary`, and `compact` options so compaction, handoff, and branch summary one-shot LLM calls can emit OpenTelemetry chat telemetry when enabled
+- Added shared oneshot telemetry instrumentation for compaction, handoff, and branch summary calls, tagging spans with `pi.gen_ai.oneshot.kind` values such as `compaction_summary`, `compaction_short_summary`, `compaction_turn_prefix`, `handoff`, and `branch_summary`
+
+## [15.1.2] - 2026-05-15
+### Added
+
+- Added `responseHeaders` to `ChatUsageEvent` and `ManualChatTelemetryOptions` so telemetry hooks receive captured lowercase upstream response headers for each chat span
+- Added automatic gateway/proxy detection from response headers (`litellm`, `helicone`, `portkey`, `openrouter`) and stamped `pi.gen_ai.gateway.*` span attributes for detected routing metadata
+- Added exported `detectGatewayFromHeaders` API for header-based gateway detection
+
+## [15.1.0] - 2026-05-15
+### Breaking Changes
+
+- Removed the `@gajae-code/agent-core/compaction/handoff` exports from the package surface, including `extractHandoffDocument`, `createHandoffContext`, and `createHandoffFileName`
+- Removed legacy telemetry constants from the public enum surface (including `AGGREGATE_ATTR`, `GenAIAttr.System`, and old `gen_ai.*` extension keys such as `gen_ai.request.service_tier`/cost/tool status/handoff fields) and replaced them with `OpenAIAttr`, `PiGenAIAttr`, and `PiGenAIAggregateAttr`
+
+### Added
+
+- Added `generateHandoff(messages, model, apiKey, options)` to `@gajae-code/agent-core/compaction` to generate a handoff document by calling the model directly, using live system/tool context and optional metadata
+- Added generation filtering so the returned handoff document now includes only text content blocks from the model output
+- Added support for defining `AgentTool` schemas with Zod, with legacy TypeBox schemas still supported when generating tool schemas for model calls
+- Added `OpenAIAttr`, `PiGenAIAttr`, and `PiGenAIAggregateAttr` exports so consumers can reference the new `openai.*` and `pi.gen_ai.*` telemetry attribute keys directly
+- Added `onChatUsage` to `AgentTelemetryConfig`, an always-fired hook receiving a `ChatUsageEvent` for every chat step that produced usage. The event carries the chat `span`, `agent`, `conversationId`, `stepNumber`, `model`, `provider`, `serviceTier`, `usage`, optional `cost`, and resolved dynamic `attributes` — independent of whether a `costEstimator` is configured.
+- Added `agentLoopDetailed(...)` and `agentLoopContinueDetailed(...)` helpers that return the same event stream plus a `detailed()` result with run `telemetry` and `coverage`
+- Added `onRunEnd` to `AgentTelemetryConfig` to receive `AgentRunSummary` and `AgentRunCoverage` at the end of each invocation
+- Added run-level telemetry and coverage types/helpers (for example `AgentRunSummary`, `AgentRunCoverage`, `aggregateAgentRunSummaries`, and `aggregateAgentRunCoverage`) to package exports
+- Added generic telemetry extension hooks for dynamic span attributes, provider/agent-name normalization, per-step cost deltas, warning callbacks, bounded summary content capture, and manual chat telemetry for non-loop model calls.
+- Added opt-in OpenTelemetry instrumentation on the agent loop. Pass `telemetry: {}` (or a richer `AgentTelemetryConfig`) on `AgentLoopConfig` / `AgentOptions` / `createAgentSession({ telemetry })` to emit GenAI-semantic-convention spans plus `pi.gen_ai.*` extension attributes:
+- `invoke_agent {agent.name}` wraps each `agentLoop` invocation with `gen_ai.operation.name=invoke_agent`, agent identity, conversation id, and `pi.gen_ai.agent.step.count`.
+- `chat {model}` per provider call, parented under `invoke_agent`, with OTEL request/response/usage attributes (`gen_ai.request.{model,stream,temperature,top_p,top_k,max_tokens,presence_penalty,stop_sequences}`, `gen_ai.response.{model,id,finish_reasons,time_to_first_chunk}`, `gen_ai.usage.{input_tokens,output_tokens,cache_read.input_tokens,cache_creation.input_tokens,reasoning.output_tokens}`) and project extensions for reasoning effort, tool choice, available tools, usage totals, and cost.
+- `execute_tool {tool.name}` per tool call, parented under `invoke_agent`, with `gen_ai.tool.{name,call.id,description,type}` plus the active context so user/MCP/provider spans created inside `tool.execute()` attach as children.
+- One-shot `handoff` span available via the public `recordHandoff(...)` helper for agent-to-agent transitions.
+- Added `AgentTelemetryConfig` hooks (`onSpanStart`, `onSpanEnd`, `costEstimator`), `agent` identity, `attributes` envelope merged onto every span, `captureMessageContent` toggle (defaults to the `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` env var) emitting OTEL-shaped `gen_ai.input.messages` / `gen_ai.output.messages` / `gen_ai.system_instructions` / `gen_ai.tool.call.arguments` / `gen_ai.tool.call.result`, and tracer/tracerName override surfaces.
+- Added `Agent#setTelemetry(config)` so consumers can swap or disable instrumentation between invocations.
+- Added `@opentelemetry/api` as a runtime dependency; SDK setup (exporters, samplers, processors) remains the host's responsibility per standard OTEL conventions. When no SDK is registered, helpers fall through to no-op spans with zero overhead.
+- Added compaction APIs under `@gajae-code/agent-core/compaction`, including context compaction, branch summarization, handoff prompt/context helpers, pruning, token budgeting, prompt templates, and OpenAI `/responses/compact` helpers.
+
+### Changed
+
+- Changed handoff document generation to force `toolChoice: "none"` when calling the model so tool invocation is disabled during generation
+- Changed `chat` spans to emit normalized provider identifiers in `gen_ai.provider.name` via OTEL-style values (for example `google` to `gcp.gemini`) instead of the legacy `gen_ai.system` label
+- Changed service-tier telemetry to emit `openai.request.service_tier`/`openai.response.service_tier` only when supported by provider via `shouldSendServiceTier`, rather than always using `gen_ai.request.service_tier`
+- Changed captured message payloads so full capture now records OTEL-structured message parts with `pi.gen_ai.request.messages`, `pi.gen_ai.system_instructions`, and `gen_ai.output.messages` including assistant `finish_reason`
+- Changed the `agent_end` event payload to include optional `telemetry` and `coverage` fields when telemetry is enabled, while keeping the legacy payload shape when disabled
+- Changed `invoke_agent` spans to include aggregate `pi.gen_ai.agent.*` attributes for chat/tool counts, latency, usage, cost, errors, and tool coverage
+
+### Fixed
+
+- Fixed intent-field injection for tool schemas defined with Zod by converting them to wire schema before mutation
+- Fixed token accounting in `ChatUsageEvent` and usage summaries so `inputTokens` and `totalTokens` now include cached read/write input tokens
+- Fixed `execute_tool` span attributes so `pi.gen_ai.tool.status` and `error.type` now reflect run-level tool outcomes (`ok`, `error`, `skipped`, `blocked`, `timeout`, `aborted`) instead of mapping all non-ok cases the same way
+- Fixed `onRunEnd` callbacks to be safe and idempotent by invoking them once per run and swallowing thrown callback errors so they cannot fail or duplicate successful runs
+- Fixed run telemetry to count interrupted, blocked, or otherwise skipped tool calls so run coverage and tool counters now include those paths
+- Fixed chat failure handling so failed chat steps are still represented in run summaries when provider streaming throws before yielding an assistant message
+- Fixed double-counting of interrupted tool calls in run summaries: the `runTool` early-return on a queued steering interrupt now defers to the post-batch tail sweep so each call is recorded exactly once
+- Fixed `coverage.toolsInvoked` and run-summary tool counters under-reporting tool calls embedded in an aborted/errored assistant message — those calls now record a collector orphan with status `aborted` or `error`
+- Fixed `AgentRunSummary.usage.inputTokens` so it now includes `cache_read` and `cache_write` input tokens, matching `ChatUsageEvent.inputTokens`
+- Fixed span lifecycle hooks (`onSpanStart`, `onSpanEnd`) so a thrown user callback is caught and surfaced via `onTelemetryWarning` (`on_span_start_failed` / `on_span_end_failed`) instead of leaking and aborting the surrounding span
+- Fixed unbounded recursion in summary content capture when a captured value contains a cyclic or deeply nested array — array recursion now respects the same depth cap as plain-object recursion and replaces back-references with `"[Circular]"`
+
+## [15.0.1] - 2026-05-14
+### Breaking Changes
+
+- Raised the minimum required Bun version from >=1.3.7 to >=1.3.14
+
+## [14.9.5] - 2026-05-12
+
+### Added
+
+- Added an `isError?: boolean` field on `AgentToolResult` so tools can flag a non-throwing failure (e.g. an aggregator that catches per-entry errors). `coerceToolResult` preserves the flag and the agent loop surfaces it as a tool error on the wire.
+
+## [14.9.3] - 2026-05-10
+### Added
+
+- Added `onHarmonyLeak` option on `Agent`/loop config to receive GPT-5 Harmony leak audit callbacks
+- Added harmony-leak detection and audit exports to the package index for programmatic leak detection and recovery hooks
+
+### Changed
+
+- Changed OpenAI code provider model runs to detect GPT-5 Harmony protocol leakage during streaming and automatically retry or recover tool calls instead of sending contaminated arguments downstream
+
+### Security
+
+- Hardened tool-call handling against leaked `to=functions.*` protocol tails by truncating or retrying before execution
+- Hardened failure handling so repeated GPT-5 Harmony leak mitigation is retried only up to two times before escalating to an explicit error
+
+## [14.9.0] - 2026-05-10
+### Added
+
+- Added `Agent#metadata` field forwarded to every API request; callers can set arbitrary provider metadata (e.g. `metadata.user_id`) once and have it applied to all subsequent stream calls without modifying per-call options
+- Added `Agent#setMetadataResolver(fn)` for installing a function that resolves request metadata at call time. The `metadata` getter dispatches through the resolver on every read (including the snapshot taken per `prompt()`), so callers reflect mutable external state (e.g. live OAuth account UUID after a token refresh) without manual re-syncs. Plain `agent.metadata = …` continues to set a static value and clears any installed resolver.
+
+### Added
+
+- Added an `onSseEvent` agent option and loop config forwarding path for raw provider SSE diagnostics.
+
+## [14.7.6] - 2026-05-07
+
+### Added
+
+- Added `hideThinkingSummary` option/getter/setter on `Agent` and `AgentLoopConfig`. Forwarded to the underlying stream call so providers can omit reasoning/thinking summaries on demand.
+## [14.7.2] - 2026-05-06
+### Added
+
+- Added `loadMode` option to `AgentTool` to mark built-in tools as `essential` for initial loading or `discoverable` for search activation
+- Added optional `summary` field to `AgentTool` definitions for one-line text used in tool discovery indexes
+
+## [14.7.0] - 2026-05-04
+### Breaking Changes
+
+- Changed `Agent` API types so `systemPrompt` is now a list of prompt strings, requiring callers to pass and update system prompts via string arrays
+
+### Changed
+
+- Removed automatic project-context injection into each model call from loop logic
+
+### Removed
+
+- Removed the `projectPrompt` field from agent state/context and the `setProjectPrompt` mutator
+
+## [14.6.2] - 2026-05-03
+
+### Fixed
+
+- Fixed unhandled promise rejection when `getApiKey` or any other async error occurs during `streamAssistantResponse`: agent loop IIFEs now catch and route errors through `EventStream.fail()`, which terminates the `for await` loop and lets `Agent#runLoop`'s catch block create a proper error assistant message instead of crashing
+
+## [14.6.0] - 2026-05-02
+### Fixed
+
+- Fixed request cancellation before provider events by emitting an aborted assistant message and ending the stream with `stopReason: "aborted"`
+
+## [14.5.10] - 2026-04-30
+
+### Added
+
+- Added an `onResponse` stream option for observing provider response metadata after response headers arrive.
+
+## [14.2.0] - 2026-04-23
+
+### Changed
+
+- Changed tool dispatch to match model-returned tool calls by either internal tool name or custom wire name, enabling custom OpenAI tool names such as `apply_patch`.
+
+## [14.0.1] - 2026-04-08
+### Added
+
+- Added `onAssistantMessageEvent` callback option to inspect assistant streaming events before they are emitted, enabling abort decisions before buffered events continue flowing
+- Added `setAssistantMessageEventInterceptor()` method to dynamically set or update the assistant message event interceptor
+
+## [13.13.0] - 2026-03-18
+
+### Added
+
+- Added `startup.checkUpdate` setting, set to `true` by default, can be disabled to skip the update check on agent initialization
+
+## [13.12.7] - 2026-03-16
+
+### Added
+
+- Added overload for `prompt()` method accepting a string input with optional options parameter
+
+### Fixed
+
+- Fixed stale forced toolChoice being passed to provider after tools are refreshed mid-turn
+
+## [13.9.16] - 2026-03-10
+### Added
+
+- Added `onPayload` option to `AgentOptions` to inspect or replace provider payloads before they are sent
+
+## [13.9.3] - 2026-03-07
+
+### Added
+
+- Exported `ThinkingLevel` selector constants and types for configuring agent reasoning behavior
+- Added `inherit` thinking level option to defer reasoning configuration to higher-level selectors
+- Added `serviceTier` option to configure service tier for agent requests
+
+### Changed
+
+- Changed `thinkingLevel` from required string to optional `Effort` type, allowing undefined state
+- Updated `setThinkingLevel()` method to accept `Effort | undefined` instead of `ThinkingLevel` string
+
+## [13.4.0] - 2026-03-01
+### Added
+
+- Added `getToolChoice` option to dynamically override tool choice per LLM call
+
+## [13.3.8] - 2026-02-28
+### Changed
+
+- Changed intent field name from `agent__intent` to `_i` in tool schemas
+
+### Fixed
+
+- Fixed synthetic tool result text formatting so aborted/error tool results no longer emit `Tool execution was aborted.: Request was aborted` style punctuation.
+## [13.3.7] - 2026-02-27
+### Added
+
+- Added `lenientArgValidation` option to tools to allow graceful handling of argument validation errors by passing raw arguments to execute() instead of returning an error to the LLM
+
+## [13.3.1] - 2026-02-26
+### Added
+
+- Added `topP`, `topK`, `minP`, `presencePenalty`, and `repetitionPenalty` options to `AgentOptions` for fine-grained sampling control
+- Added getter and setter properties for sampling parameters on the `Agent` class to allow runtime configuration
+
+## [13.1.0] - 2026-02-23
+
+### Changed
+
+- Removed per-tool `agent__intent` field description from injected schema to reduce token usage; intent format is now documented once in the system prompt instead of repeated in every tool definition
+## [12.19.0] - 2026-02-22
+### Changed
+
+- Updated tool result messages to include error details when tool execution fails
+
+## [12.14.0] - 2026-02-19
+
+### Added
+
+- Added `intentTracing` option to enable intent goal extraction from tool calls, allowing models to specify high-level goals via a required `_intent` field that is automatically injected into tool schemas and stripped from arguments before execution
+
+## [12.11.0] - 2026-02-19
+
+### Added
+
+- Exported `AgentBusyError` exception class for handling concurrent agent operations
+
+### Changed
+
+- Agent now throws `AgentBusyError` instead of generic `Error` when attempting concurrent operations
+
+## [12.8.0] - 2026-02-16
+
+### Added
+
+- Added `transformToolCallArguments` option to `AgentOptions` and `AgentLoopConfig` for transforming tool call arguments before execution (e.g. secret deobfuscation)
+
+## [12.2.0] - 2026-02-13
+
+### Added
+
+- Added `providerSessionState` option to share provider state map for session-scoped transport and session caches
+- Added `preferWebsockets` option to hint that websocket transport should be preferred when supported by the provider implementation
+
+## [11.10.0] - 2026-02-10
+
+### Added
+
+- Added `temperature` option to `AgentOptions` to control LLM sampling temperature
+- Added `temperature` getter and setter to `Agent` class for runtime configuration
+
+## [11.6.0] - 2026-02-07
+
+### Added
+
+- Added `hasQueuedMessages()` method to check for pending steering/follow-up messages
+- Resume queued steering and follow-up messages from `continue()` after auto-compaction
+
+### Changed
+
+- Extracted `dequeueSteeringMessages()` and `dequeueFollowUpMessages()` from inline config callbacks
+- Added `skipInitialSteeringPoll` option to `_runLoop()` for correct queue resume ordering
+
+## [11.3.0] - 2026-02-06
+
+### Added
+
+- Added `maxRetryDelayMs` option to AgentOptions to cap server-requested retry delays, allowing higher-level retry logic to handle long waits with user visibility
+
+### Changed
+
+- Updated ThinkingLevel documentation to include support for gpt-5.3 and gpt-5.3-openai-code models with 'xhigh' thinking level
+
+## [11.2.0] - 2026-02-05
+
+### Fixed
+
+- Fixed handling of aborted requests to properly throw abort errors when stream terminates without a terminal event
+
+## [10.5.0] - 2026-02-04
+
+### Added
+
+- Added `concurrency` option to `AgentTool` to control tool scheduling: "shared" (default, runs in parallel) or "exclusive" (runs alone)
+- Implemented parallel execution of shared tools within a single agent turn for improved performance
+
+### Changed
+
+- Refactored tool execution to support concurrent scheduling with proper interrupt handling and steering message checks
+
+## [9.2.2] - 2026-01-31
+
+### Added
+
+- Added toolChoice option to AgentPromptOptions for controlling tool selection
+
+## [8.2.0] - 2026-01-24
+
+### Changed
+
+- Updated TypeScript configuration for better publish-time configuration handling with tsconfig.publish.json
+
+## [8.0.0] - 2026-01-23
+
+### Added
+
+- Added `nonAbortable` option to tools to ignore abort signals during execution
+
+## [6.8.0] - 2026-01-20
+
+### Changed
+
+- Updated proxy stream processing to use utility function for reading lines
+
+## [6.2.0] - 2026-01-19
+
+### Added
+
+- Enhanced getToolContext to receive tool call batch information including batchId, index, total count, and tool call details
+
+## [5.6.7] - 2026-01-18
+
+### Fixed
+
+- Added proper tool result messages for tool calls that are aborted or error out
+- Ensured tool_use/tool_result pairing is maintained when tool execution fails
+
+## [4.6.0] - 2026-01-12
+
+### Changed
+
+- Modified assistant message handling to split messages around tool results for improved readability when using Cursor tools
+
+### Fixed
+
+- Fixed tool result ordering in Cursor mode by buffering results and emitting them at the correct position within assistant messages
+
+## [4.3.0] - 2026-01-11
+
+### Added
+
+- Added `cursorExecHandlers` and `cursorOnToolResult` options for local tool execution with cursor-based streaming
+- Added `emitExternalEvent` method to allow external event injection into the agent state
+
+## [4.0.0] - 2026-01-10
+
+### Added
+
+- Added `popLastSteer()` and `popLastFollowUp()` methods to remove and return the last queued message (LIFO) for dequeue operations
+- `thinkingBudgets` option on `Agent` and `AgentOptions` to customize token budgets per thinking level
+- `sessionId` option on `Agent` to forward session identifiers to LLM providers for session-based caching
+
+### Fixed
+
+- `minimal` thinking level now maps to `minimal` reasoning effort instead of being treated as `low`
+
+## [3.33.0] - 2026-01-08
+
+### Fixed
+
+- Ensured aborted assistant responses always include an error message for callers.
+- Filtered thinking blocks from Cerebras request context to keep multi-turn prompts compatible.
+
+## [3.21.0] - 2026-01-06
+
+### Changed
+
+- Switched from local `@gajae-code/ai` to upstream `@gajae-code/ai` package
+
+### Added
+
+- Added `sessionId` option for provider caching (e.g., OpenAI code provider session-based prompt caching)
+- Added `sessionId` getter/setter on Agent class for runtime session switching
+
+## [3.20.0] - 2026-01-06
+
+### Breaking Changes
+
+- Replaced `queueMessage`/`queueMode` with steering + follow-up queues: use `steer`, `setSteeringMode`, and `getSteeringMode` for mid-run interruptions, and `followUp`, `setFollowUpMode`, and `getFollowUpMode` for post-turn messages
+- Agent loop callbacks now use `getSteeringMessages` and `getFollowUpMessages` instead of `getQueuedMessages`
+
+### Added
+
+- Added follow-up message queue support so new user messages can continue a run after the agent would otherwise stop
+- Added `RenderResultOptions.spinnerFrame` for animated tool-result rendering
+
+### Changed
+
+- `prompt()` and `continue()` now throw when the agent is already streaming; use steering or follow-up queues instead
+
+## [3.4.1337] - 2026-01-03
+
+### Added
+
+- Added `popMessage()` method to Agent class for removing and retrieving the last message
+- Added abort signal checks during response streaming for faster interruption handling
+
+### Fixed
+
+- Fixed abort handling to properly return aborted message state when stream is interrupted mid-response
+
+## [1.341.0] - 2026-01-03
+
+### Added
+
+- Added `interruptMode` option to control when queued messages interrupt tool execution.
+- Implemented "immediate" mode (default) to check queue after each tool and interrupt remaining tools.
+- Implemented "wait" mode to defer queue processing until the entire turn completes.
+- Added getter and setter methods for `interruptMode` on Agent class.
+
+## [1.337.1] - 2026-01-02
+
+### Changed
+
+- Forked to @gajae-code scope with unified versioning across all packages
+
+## [1.337.0] - 2026-01-02
+
+Initial release under @gajae-code scope. See previous releases at [badlogic/pi-mono](https://github.com/badlogic/pi-mono).
+
+## [0.31.0] - 2026-01-02
+
+### Breaking Changes
+
+- **Transport abstraction removed**: `ProviderTransport`, `AppTransport`, and `AgentTransport` interface have been removed. Use the `streamFn` option directly for custom streaming implementations.
+
+- **Agent options renamed**:
+  - `transport` → removed (use `streamFn` instead)
+  - `messageTransformer` → `convertToLlm`
+  - `preprocessor` → `transformContext`
+
+- **`AppMessage` renamed to `AgentMessage`**: All references to `AppMessage` have been renamed to `AgentMessage` for consistency.
+
+- **`CustomMessages` renamed to `CustomAgentMessages`**: The declaration merging interface has been renamed.
+
+- **`UserMessageWithAttachments` and `Attachment` types removed**: Attachment handling is now the responsibility of the `convertToLlm` function.
+
+- **Agent loop moved from `@gajae-code/ai`**: The `agentLoop`, `agentLoopContinue`, and related types have moved to this package. Import from `@gajae-code/pi-agent` instead.
+
+### Added
+
+- `streamFn` option on `Agent` for custom stream implementations. Default uses `streamSimple` from pi-ai.
+
+- `streamProxy()` utility function for browser apps that need to proxy LLM calls through a backend server. Replaces the removed `AppTransport`.
+
+- `getApiKey` option for dynamic API key resolution (useful for expiring OAuth tokens like GitHub Copilot).
+
+- `agentLoop()` and `agentLoopContinue()` low-level functions for running the agent loop without the `Agent` class wrapper.
+
+- New exported types: `AgentLoopConfig`, `AgentContext`, `AgentTool`, `AgentToolResult`, `AgentToolUpdateCallback`, `StreamFn`.
+
+### Changed
+
+- `Agent` constructor now has all options optional (empty options use defaults).
+
+- `queueMessage()` is now synchronous (no longer returns a Promise).