@gajae-code/agent-core 0.13.3 → 0.14.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-08-17
+
+### Fixed
+
+- 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
@@ -37,6 +57,7 @@
 ### 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.

package/dist/types/agent-loop.d.ts

@@ -2,7 +2,7 @@
  * Agent loop that works with AgentMessage throughout.
  * Transforms to Message[] only at the LLM call boundary.
  */
-import { type Context, EventStream } from "@gajae-code/ai";
+import { type AssistantMessage, type AssistantMessageEvent, type Context, EventStream } from "@gajae-code/ai";
 import type { AttemptScope } from "./attempt-scope";
 import { type AgentRunCoverage, type AgentRunSummary } from "./run-collector";
 import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn } from "./types";
@@ -72,6 +72,7 @@ export declare const MANAGED_SNAPSHOT_MAX_NODES = 100000;
  * callers use the default budget via {@link managedAttemptSnapshot}.
  */
 export declare function sanitizedDetachedClone<T>(value: T, maxNodes?: number): T;
+export declare function managedAssistantEventSnapshot(event: AssistantMessageEvent, message: AssistantMessage): AssistantMessageEvent;
 /**
  * Detailed-result handle returned by {@link agentLoopDetailed}. Adds the
  * run-level telemetry/coverage rollup to the existing `AgentMessage[]`

package/dist/types/agent.d.ts

@@ -3,7 +3,7 @@
  */
 import { type AssistantMessage, type AssistantMessageEvent, type CursorExecHandlers, type CursorToolResultHandler, type Effort, type ImageContent, type Message, type Model, type ProviderSessionState, type ServiceTier, type SimpleStreamOptions, type ThinkingBudgets, type ToolChoice } from "@gajae-code/ai";
 import type { AppendOnlyContextManager } from "./append-only-context";
-import type { AttemptScope } from "./attempt-scope";
+import type { AttemptRunHandle, AttemptScope } from "./attempt-scope";
 import type { HarmonyAuditEvent } from "./harmony-leak";
 import type { AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, AgentToolContext, ManagedLogicalRunId, RunCancellationDomainBridge, RunResourceLedger, RunTerminalRequest, StreamFn, ToolCallContext } from "./types";
 /**
@@ -162,6 +162,8 @@ export interface AgentOptions {
      * message are emitted. See {@link AgentLoopConfig.afterToolCall} for full semantics.
      */
     afterToolCall?: AgentLoopConfig["afterToolCall"];
+    /** Invoked with the follow-up messages dequeued for the next turn (reassignable). */
+    onFollowUpConsumed?: AgentLoopConfig["onFollowUpConsumed"];
     /**
      * Opt-in OpenTelemetry instrumentation. Passing `{}` enables the loop's
      * GenAI-semantic-convention spans using the global tracer provider. See
@@ -181,8 +183,9 @@ export interface AgentPromptOptions {
     /** Continue a cooperative maintenance checkpoint under its existing logical run and cancellation domain. */
     maintenanceContinuation?: boolean;
     /** Called synchronously after this invocation claims the agent run, before asynchronous provider work. */
-    /** Receives the immutable run handle as the first callback argument. */
-    onRunAccepted?: (...args: any[]) => void;
+    onRunAccepted?: (handle: AttemptRunHandle, acceptance: {
+        consumedQueuedMessages: readonly AgentMessage[];
+    }) => void;
     /** Called once immediately before every managed upstream request. */
     nextFallbackAttempt?: AgentLoopConfig["nextFallbackAttempt"];
     /** Called after a managed upstream request is accepted and committed. */
@@ -224,6 +227,8 @@ export declare class Agent {
      * message emission. Reassign at any time to swap the implementation.
      */
     afterToolCall?: AgentLoopConfig["afterToolCall"];
+    /** Invoked with the follow-up messages dequeued for the next turn. Reassign at any time. */
+    onFollowUpConsumed?: AgentLoopConfig["onFollowUpConsumed"];
     constructor(opts?: AgentOptions);
     /**
      * Get the current session ID used for provider caching.
@@ -344,9 +349,22 @@ export declare class Agent {
     setProviderResponseInterceptor(fn: SimpleStreamOptions["onResponse"] | undefined): void;
     setRawSseEventInterceptor(fn: SimpleStreamOptions["onSseEvent"] | undefined): void;
     setAssistantMessageEventInterceptor(fn: ((message: AssistantMessage, event: AssistantMessageEvent) => void) | undefined): void;
+    setProvisionalAssistantMessageEventInterceptor(fn: ((message: AssistantMessage, event: AssistantMessageEvent) => void) | undefined): void;
     setOnBeforeYield(fn: (() => Promise<void> | void) | undefined): void;
     setShouldPause(fn: AgentLoopConfig["shouldPause"] | undefined): void;
     setMaintainContext(fn: AgentLoopConfig["maintainContext"] | undefined): void;
+    /**
+     * Publish an event produced OUTSIDE the agent loop (a provider that executed the tool
+     * itself, a host bridge, a replay).
+     *
+     * Identity is the PRODUCER's to prove: whoever dispatched the call binds the tool object
+     * it actually ran (see `bindDispatchedToolIdentity`) before handing the event here, and
+     * that binding is never touched from this side. Re-resolving `event.toolName` against the
+     * mutable current tool list would let a mid-run `setTools`, MCP reload, or plain name
+     * collision overwrite a proven object with one that never ran — and would invent an
+     * identity for replays and host bridges that never executed an AgentTool at all. An
+     * unbound external event stays unbound; unproven provenance is `custom`.
+     */
     emitExternalEvent(event: AgentEvent): void;
     createExternalEventEmitterForCurrentRun(): ((event: AgentEvent) => void) | undefined;
     setSystemPrompt(v: string[]): void;
@@ -425,8 +443,21 @@ export declare class Agent {
     popLastFollowUp(): AgentMessage | undefined;
     removeFollowUpAt(index: number): AgentMessage | undefined;
     moveFollowUp(fromIndex: number, toIndex: number): boolean;
-    /** Remove queued steering+follow-up messages matching `predicate`, preserving order of the rest. */
-    removeQueuedMessages(predicate: (message: AgentMessage) => boolean): {
+    /**
+     * Remove ALL queued STEERING messages without touching the follow-up queue.
+     * Used by the terminal-abort path to purge steering queued for the aborted
+     * turn (the loop may exit on the abort signal without polling it); the
+     * follow-up queue is preserved because it may carry owned-completion
+     * resumes that must still deliver.
+     */
+    clearSteeringMessages(): void;
+    /**
+     * Remove queued steering/follow-up messages matching `predicate`, preserving
+     * order of the rest. `scope` restricts the removal to one queue — the
+     * terminal-abort steering purge must not wipe the follow-up queue, which
+     * the owned-completion resume policy preserves.
+     */
+    removeQueuedMessages(predicate: (message: AgentMessage) => boolean, scope?: "both" | "steering" | "followUp"): {
         steering: number;
         followUp: number;
         total: number;

package/dist/types/index.d.ts

@@ -9,4 +9,5 @@ export * from "./run-collector";
 export * from "./run-resource-ledger";
 export * from "./telemetry";
 export * from "./thinking";
+export * from "./tool-dispatch-identity";
 export * from "./types";

package/dist/types/tool-dispatch-identity.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Record, at the producer boundary, the tool object this event was emitted for.
+ *
+ * A call with no resolved tool (an unknown name the loop is about to reject, or a call
+ * aborted before dispatch) binds nothing: there is no object, so there is nothing to prove.
+ */
+export declare function bindDispatchedToolIdentity(event: object, tool: object | undefined): void;
+/** The tool object this event was actually dispatched to, if its producer bound one. */
+export declare function dispatchedToolIdentity(event: object): object | undefined;
+/** Mark an event as pairing-only: emitted for a call the loop never dispatched. */
+export declare function markNonDispatchedToolEvent(event: object): void;
+/** Whether this exact event was synthesized for a call that never ran. */
+export declare function isNonDispatchedToolEvent(event: object): boolean;
+/**
+ * Active tool a call name dispatches to. Tools emitted via OpenAI's custom-tool path
+ * (e.g. `apply_patch` on GPT-5) come back under their wire-level name, which may differ
+ * from the harness-internal `name`. Match on either, preferring `name` for determinism if
+ * both somehow collide.
+ *
+ * This is the single dispatch-matching rule: execution, external-event identity binding,
+ * and every "is this tool callable" check must agree, or a label can describe a tool the
+ * call would never have reached.
+ */
+export declare function activeToolForCallName<T extends {
+    name: string;
+    customWireName?: string;
+}>(tools: ReadonlyArray<T> | undefined, callName: string): T | undefined;

package/dist/types/types.d.ts

@@ -301,6 +301,13 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * continues with another turn.
      */
     getFollowUpMessages?: () => Promise<AgentMessage[]>;
+    /**
+     * Invoked with the follow-up messages the loop dequeues for the next turn
+     * (right after {@link getFollowUpMessages}). The consumer may use this to
+     * attach per-turn state (e.g. a fresh owned-completion lineage) at actual
+     * resume admission rather than when the message was merely queued.
+     */
+    onFollowUpConsumed?: (messages: AgentMessage[]) => void;
     /**
      * Supplies one bounded synthetic recovery instruction before the loop would
      * otherwise yield. Unlike a follow-up, it is sent only to the provider and
@@ -381,6 +388,10 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * Callers may abort synchronously to stop consuming buffered provider events.
      */
     onAssistantMessageEvent?: (message: AssistantMessage, event: AssistantMessageEvent) => void;
+    /** Observe unmanaged provisional assistant deltas before public publication. */
+    onProvisionalAssistantMessageEvent?: (message: AssistantMessage, event: AssistantMessageEvent) => void;
+    /** True when the host consumes provisional assistant events for live safety checks. */
+    hasProvisionalAssistantMessageEventConsumer?: boolean;
     /** Called for non-content tool-choice incapability stream events. */
     onToolChoiceIncapability?: (event: Extract<AssistantMessageEvent, {
         type: "toolChoiceIncapability";

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/agent-core",
-	"version": "0.13.3",
+	"version": "0.14.0",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -32,9 +32,9 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/ai": "0.13.3",
-		"@gajae-code/natives": "0.13.3",
-		"@gajae-code/utils": "0.13.3",
+		"@gajae-code/ai": "0.14.0",
+		"@gajae-code/natives": "0.14.0",
+		"@gajae-code/utils": "0.14.0",
 		"@opentelemetry/api": "^1.9.0"
 	},
 	"devDependencies": {