@gajae-code/agent-core 0.13.3 → 0.14.0

package/src/agent.ts

@@ -301,6 +301,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
@@ -322,8 +324,7 @@ 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. */
@@ -410,6 +411,7 @@ export class Agent {
 	#onResponse?: SimpleStreamOptions["onResponse"];
 	#onSseEvent?: SimpleStreamOptions["onSseEvent"];
 	#onAssistantMessageEvent?: (message: AssistantMessage, event: AssistantMessageEvent) => void;
+	#onProvisionalAssistantMessageEvent?: (message: AssistantMessage, event: AssistantMessageEvent) => void;
 	#onToolChoiceIncapability?: AgentLoopConfig["onToolChoiceIncapability"];
 	#onHarmonyLeak?: (event: HarmonyAuditEvent) => void | Promise<void>;
 	#onBeforeYield?: () => Promise<void> | void;
@@ -467,6 +469,8 @@ export 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 = {}) {
 		this.#state = { ...this.#state, ...opts.initialState };
@@ -510,6 +514,7 @@ export class Agent {
 		this.#onHarmonyLeak = opts.onHarmonyLeak;
 		this.#shouldPause = opts.shouldPause;
 		this.beforeToolCall = opts.beforeToolCall;
+		this.onFollowUpConsumed = opts.onFollowUpConsumed;
 		this.afterToolCall = opts.afterToolCall;
 		this.#telemetry = opts.telemetry;
 		this.#appendOnlyContext = opts.appendOnlyContext;
@@ -780,6 +785,12 @@ export class Agent {
 		this.#onAssistantMessageEvent = fn;
 	}
 
+	setProvisionalAssistantMessageEventInterceptor(
+		fn: ((message: AssistantMessage, event: AssistantMessageEvent) => void) | undefined,
+	): void {
+		this.#onProvisionalAssistantMessageEvent = fn;
+	}
+
 	setOnBeforeYield(fn: (() => Promise<void> | void) | undefined): void {
 		this.#onBeforeYield = fn;
 	}
@@ -792,6 +803,18 @@ export class Agent {
 		this.#maintainContext = fn;
 	}
 
+	/**
+	 * 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) {
 		switch (event.type) {
 			case "message_start":
@@ -1191,16 +1214,39 @@ export class Agent {
 		return true;
 	}
 
-	/** 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 {
+		this.#steeringQueue = [];
+	}
+
+	/**
+	 * 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" = "both",
+	): {
 		steering: number;
 		followUp: number;
 		total: number;
 	} {
 		const beforeSteering = this.#steeringQueue.length;
 		const beforeFollowUp = this.#followUpQueue.length;
-		this.#steeringQueue = this.#steeringQueue.filter(m => !predicate(m));
-		this.#followUpQueue = this.#followUpQueue.filter(m => !predicate(m));
+		if (scope !== "followUp") {
+			this.#steeringQueue = this.#steeringQueue.filter(m => !predicate(m));
+		}
+		if (scope !== "steering") {
+			this.#followUpQueue = this.#followUpQueue.filter(m => !predicate(m));
+		}
 		const steering = beforeSteering - this.#steeringQueue.length;
 		const followUp = beforeFollowUp - this.#followUpQueue.length;
 		return { steering, followUp, total: steering + followUp };
@@ -1409,13 +1455,28 @@ export class Agent {
 		if (messages[messages.length - 1].role === "assistant") {
 			const queuedSteering = this.#dequeueSteeringMessages();
 			if (queuedSteering.length > 0) {
-				await this.#runLoop(queuedSteering, { ...options, skipInitialSteeringPoll: true });
+				await this.#runLoop(queuedSteering, {
+					...options,
+					skipInitialSteeringPoll: true,
+					consumedQueuedMessages: queuedSteering,
+				});
 				return;
 			}
 
 			const queuedFollowUp = this.#dequeueFollowUpMessages();
 			if (queuedFollowUp.length > 0) {
-				await this.#runLoop(queuedFollowUp, options);
+				// Route the DIRECT-dequeue batch through the same consumption hook
+				// the in-loop getFollowUpMessages path uses: denied owned-completion
+				// envelopes are filtered before they reach the loop, and delivered
+				// envelopes settle their registrations — the direct path otherwise
+				// bypasses onFollowUpConsumed entirely (review threads P1/P2).
+				await this.onFollowUpConsumed?.(queuedFollowUp);
+				// The hook can filter the WHOLE batch (every entry denied by a
+				// scope:"owned" abort): starting an empty provider run would
+				// violate the zero-final-call guarantee, so return without
+				// running the loop (review thread P1).
+				if (queuedFollowUp.length === 0) return;
+				await this.#runLoop(queuedFollowUp, { ...options, consumedQueuedMessages: queuedFollowUp });
 				return;
 			}
 
@@ -1438,12 +1499,31 @@ export class Agent {
 		}
 		const queuedSteering = this.#dequeueSteeringMessages();
 		if (queuedSteering.length > 0) {
-			await this.#runLoop(queuedSteering, { ...options, skipInitialSteeringPoll: true });
+			await this.#runLoop(queuedSteering, {
+				...options,
+				skipInitialSteeringPoll: true,
+				consumedQueuedMessages: queuedSteering,
+			});
 			return;
 		}
 		const queuedFollowUp = this.#dequeueFollowUpMessages();
 		if (queuedFollowUp.length > 0) {
-			await this.#runLoop(queuedFollowUp, options);
+			// Route the queued-tail batch through the same consumption hook as the
+			// in-loop getFollowUpMessages path and the assistant-tail continue()
+			// path: denied owned-completion envelopes are filtered before they
+			// reach the loop, and delivered envelopes settle their registrations.
+			// A terminal abort that leaves a tool/result tail and rearms an
+			// authorized owned-completion follow-up reaches this branch, so
+			// bypassing the hook would leak every such job's ownership tuple and
+			// eventually exhaust the bounded ownership registries (review thread
+			// P2).
+			await this.onFollowUpConsumed?.(queuedFollowUp);
+			// The hook can filter the WHOLE batch (every entry denied by a
+			// scope:"owned" abort): starting an empty provider run would violate
+			// the zero-final-call guarantee, so return without running the loop
+			// (review thread P2).
+			if (queuedFollowUp.length === 0) return;
+			await this.#runLoop(queuedFollowUp, { ...options, consumedQueuedMessages: queuedFollowUp });
 			return;
 		}
 		throw new Error("No queued messages to continue");
@@ -1454,7 +1534,13 @@ export class Agent {
 	 * If messages are provided, starts a new conversation turn with those messages.
 	 * Otherwise, continues from existing context.
 	 */
-	async #runLoop(messages?: AgentMessage[], options?: AgentPromptOptions & { skipInitialSteeringPoll?: boolean }) {
+	async #runLoop(
+		messages?: AgentMessage[],
+		options?: AgentPromptOptions & {
+			skipInitialSteeringPoll?: boolean;
+			consumedQueuedMessages?: readonly AgentMessage[];
+		},
+	) {
 		const model = this.#state.model;
 		if (!model) throw new Error("No model configured");
 
@@ -1503,7 +1589,9 @@ export class Agent {
 		this.#observeMainAttemptScope(scope);
 		const handle: AttemptRunHandle = { logicalRunId, scope };
 		this.#runHandles.set(logicalRunId, handle);
-		options?.onRunAccepted?.(handle);
+		options?.onRunAccepted?.(handle, {
+			consumedQueuedMessages: options.consumedQueuedMessages ?? [],
+		});
 		if (startsManagedLogicalRun) {
 			this.#managedLogicalRunOwner = logicalRunId;
 			this.#emit({ type: "agent_start", scope });
@@ -1671,12 +1759,16 @@ export class Agent {
 						return result;
 					}
 				: undefined,
-			onAssistantMessageEvent: this.#onAssistantMessageEvent
-				? (message, event) => {
-						if (this.#activeRunId !== runId) return;
-						this.#onAssistantMessageEvent?.(message, event);
-					}
-				: undefined,
+			onAssistantMessageEvent: (message, event) => {
+				if (this.#activeRunId !== runId) return;
+				this.#onAssistantMessageEvent?.(message, event);
+			},
+			onProvisionalAssistantMessageEvent: (message, event) => {
+				if (this.#activeRunId !== runId) return;
+				this.#state.streamMessage = message;
+				this.#onProvisionalAssistantMessageEvent?.(message, event);
+			},
+			hasProvisionalAssistantMessageEventConsumer: this.#onProvisionalAssistantMessageEvent !== undefined,
 			onToolChoiceIncapability: this.#onToolChoiceIncapability
 				? event => {
 						if (this.#activeRunId !== runId) return;
@@ -1710,6 +1802,9 @@ export class Agent {
 					this.#followUpQueue = [...queued, ...this.#followUpQueue];
 					return [];
 				}
+				if (queued.length > 0) {
+					await this.onFollowUpConsumed?.(queued);
+				}
 				return queued;
 			},
 			getSyntheticRecoveryMessage: async () => {
@@ -1881,6 +1976,9 @@ export class Agent {
 				stopReason: abortController.signal.aborted ? "aborted" : "error",
 				errorMessage: err?.message || String(err),
 				errorStatus: extractHttpStatusFromError({ status: err?.errorStatus }) ?? extractHttpStatusFromError(err),
+				...(err?.errorKind === "local_snapshot_failure" || err?.errorKind === "local_buffer_overflow"
+					? { errorKind: err.errorKind as "local_snapshot_failure" | "local_buffer_overflow" }
+					: {}),
 				timestamp: Date.now(),
 			} as AgentMessage;
 

package/src/index.ts

@@ -17,5 +17,7 @@ export * from "./run-resource-ledger";
 export * from "./telemetry";
 // Thinking selectors
 export * from "./thinking";
+// Dispatch-bound tool identity (non-serializable side channel keyed by event object)
+export * from "./tool-dispatch-identity";
 // Types
 export * from "./types";

package/src/proxy.ts

@@ -13,7 +13,7 @@ import {
 	type ToolCall,
 } from "@gajae-code/ai";
 import { calculateCost } from "@gajae-code/ai/models";
-import { parseStreamingJson } from "@gajae-code/ai/utils/json-parse";
+import { findUnnecessaryUnicodeEscape, parseStreamingJson } from "@gajae-code/ai/utils/json-parse";
 import { readSseJson } from "@gajae-code/utils";
 
 // Create stream class matching ProxyMessageEventStream
@@ -379,6 +379,8 @@ function processProxyEvent(
 		case "toolcall_end": {
 			const content = partial.content[proxyEvent.contentIndex];
 			if (content?.type === "toolCall") {
+				const raw = (content as { partialJson?: string }).partialJson;
+				if (raw && findUnnecessaryUnicodeEscape(raw)) content.escapedNonAsciiArguments = true;
 				delete (content as any).partialJson;
 				return {
 					type: "toolcall_end",

package/src/tool-dispatch-identity.ts

@@ -0,0 +1,87 @@
+/**
+ * Identity of the tool object a `tool_execution_start` event was produced for.
+ *
+ * The producer already knows exactly which tool object it dispatched to: the agent loop
+ * resolves it once, from the run's immutable tool snapshot, before it emits anything. Any
+ * consumer that instead re-resolves `event.toolName` later reads a MUTABLE registry — a
+ * mid-run `setTools`, MCP reload, or tool refresh can hand the same wire name to a
+ * completely different object — and would then attribute the call to a tool that never
+ * ran.
+ *
+ * The binding is deliberately a side channel rather than an event field:
+ *
+ *  - a tool object exposes `execute`, closures over session state, and its own
+ *    description/parameters; putting it on `AgentEvent` would make it enumerable, walkable,
+ *    and reachable by every serializer, wire envelope, and log sink that copies events, and
+ *    `JSON.stringify(event)` would start emitting tool metadata;
+ *  - the map is weak on the event object, so the association disappears with the event it
+ *    describes and pins nothing alive;
+ *  - it carries no arguments, no results, no call ids, and no timing — only object identity,
+ *    which is exactly what provenance checks (`WeakSet.has`) need and nothing more.
+ */
+const dispatchedToolByEvent = new WeakMap<object, object>();
+
+/**
+ * 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 function bindDispatchedToolIdentity(event: object, tool: object | undefined): void {
+	if (!tool) return;
+	dispatchedToolByEvent.set(event, tool);
+}
+
+/** The tool object this event was actually dispatched to, if its producer bound one. */
+export function dispatchedToolIdentity(event: object): object | undefined {
+	return dispatchedToolByEvent.get(event);
+}
+
+/**
+ * Tool events emitted only to keep the stream's start/end PAIRING intact, for calls that
+ * were never dispatched.
+ *
+ * A skipped or aborted call still has to produce a result, and every consumer downstream
+ * is built around results arriving in pairs, so the loop synthesizes the missing start.
+ * That is a stream-shape obligation and nothing more: no `execute` ran, no work began, and
+ * no time was spent in a tool.
+ *
+ * Consumers that merely relay or record events are unaffected and must stay unaffected.
+ * Consumers that publish a claim about what is RUNNING are not: between the synthetic
+ * start and its end, such a consumer would report a tool as active that was never entered.
+ *
+ * A side channel rather than an `AgentEvent` field, for the same reasons the dispatched
+ * identity is one — no wire/schema surface to serialize, copy, or persist — and a `WeakSet`
+ * because the mark is meaningful only for the exact event object it was applied to.
+ */
+const nonDispatchedToolEvents = new WeakSet<object>();
+
+/** Mark an event as pairing-only: emitted for a call the loop never dispatched. */
+export function markNonDispatchedToolEvent(event: object): void {
+	nonDispatchedToolEvents.add(event);
+}
+
+/** Whether this exact event was synthesized for a call that never ran. */
+export function isNonDispatchedToolEvent(event: object): boolean {
+	return nonDispatchedToolEvents.has(event);
+}
+
+/**
+ * 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 function activeToolForCallName<T extends { name: string; customWireName?: string }>(
+	tools: ReadonlyArray<T> | undefined,
+	callName: string,
+): T | undefined {
+	return (
+		tools?.find(tool => tool.name === callName) ??
+		tools?.find(tool => tool.customWireName !== undefined && tool.customWireName === callName)
+	);
+}

package/src/types.ts

@@ -331,6 +331,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
@@ -423,6 +430,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" }>) => void;