@gajae-code/agent-core 0.15.5 → 0.16.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [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

package/dist/types/agent.d.ts

@@ -5,7 +5,7 @@ import { type AssistantMessage, type AssistantMessageEvent, type CursorExecHandl
 import type { AppendOnlyContextManager } from "./append-only-context";
 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";
+import type { AgentEvent, AgentLoopConfig, AgentMessage, AgentMetadataResolverContext, AgentState, AgentTool, AgentToolContext, ManagedLogicalRunId, RunCancellationDomainBridge, RunResourceLedger, RunTerminalRequest, StreamFn, ToolCallContext } from "./types";
 /**
  * Whether persisted history ends at a point where a new model turn can resume.
  * Assistant-ended histories require an in-memory queued message and are handled
@@ -271,7 +271,7 @@ export declare class Agent {
      * only included for `"anthropic"` requests). Falls back to the static
      * {@link metadata} value when no resolver is set.
      */
-    metadataForProvider(provider: string): Record<string, unknown> | undefined;
+    metadataForProvider(provider: string, model?: Model, transport?: AgentMetadataResolverContext["transport"]): Record<string, unknown> | undefined;
     /**
      * Install a function that resolves request metadata at call time. The
      * resolver receives the target provider string and can gate provider-specific
@@ -280,7 +280,7 @@ export declare class Agent {
      * credential. Pass `undefined` to clear and revert to the static
      * {@link metadata} value.
      */
-    setMetadataResolver(resolver: ((provider: string) => Record<string, unknown> | undefined) | undefined): void;
+    setMetadataResolver(resolver: ((context: AgentMetadataResolverContext) => Record<string, unknown> | undefined) | undefined): void;
     /**
      * Read the active OpenTelemetry configuration. Returns `undefined` when
      * instrumentation is disabled. Callers spawning child runs (e.g. subagent
@@ -358,6 +358,18 @@ export declare class Agent {
     setProvisionalAssistantMessageEventInterceptor(fn: ((message: AssistantMessage, event: AssistantMessageEvent) => void) | undefined): void;
     setOnBeforeYield(fn: (() => Promise<void> | void) | undefined): void;
     setShouldPause(fn: AgentLoopConfig["shouldPause"] | undefined): void;
+    /** The currently installed cooperative pause checkpoint, if any. */
+    get shouldPause(): AgentLoopConfig["shouldPause"] | undefined;
+    /**
+     * Fence old-turn steering admission.
+     *
+     * The loop polls steering UPSTREAM of its pause checkpoint (and again on the
+     * immediate-interrupt path), so a cooperative stop alone cannot prevent one
+     * more old-turn model call once a steering message has already been dequeued.
+     * While the fence returns true the poll yields no messages AND does not
+     * dequeue, so the queue survives intact for the next turn.
+     */
+    setSteeringAdmissionFence(fn: (() => boolean) | undefined): void;
     setMaintainContext(fn: AgentLoopConfig["maintainContext"] | undefined): void;
     /**
      * Publish an event produced OUTSIDE the agent loop (a provider that executed the tool

package/dist/types/types.d.ts

@@ -6,6 +6,20 @@ import type { AgentRunCoverage, AgentRunSummary } from "./run-collector";
 import type { AgentTelemetryConfig } from "./telemetry";
 /** Stream function - can return sync or Promise for async config lookup */
 export type StreamFn = (...args: Parameters<typeof streamSimple>) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>;
+/**
+ * Request context supplied to provider-aware metadata resolvers.
+ *
+ * The model is the exact model selected for the concrete request (including
+ * fallback and ephemeral requests), while `transport` distinguishes the
+ * built-in stream path from a caller-supplied stream function. Metadata that
+ * carries provider identity must use both values to fail closed when routing
+ * is not the canonical provider path.
+ */
+export interface AgentMetadataResolverContext {
+    provider: string;
+    model?: Model;
+    transport?: "default" | "custom";
+}
 /** Stable identifier for a managed logical run, shared by all of its retry attempts. */
 export type ManagedLogicalRunId = number;
 /** A resource owned by a prompt run until its promise settles. */
@@ -233,7 +247,7 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * current when `AgentLoopConfig` was first constructed). Overrides the static
      * `metadata` field when present.
      */
-    metadataResolver?: (provider: string) => Record<string, unknown> | undefined;
+    metadataResolver?: (context: AgentMetadataResolverContext) => Record<string, unknown> | undefined;
     /**
      * Converts AgentMessage[] to LLM-compatible Message[] before each LLM call.
      *

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/agent-core",
-	"version": "0.15.5",
+	"version": "0.16.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.15.5",
-		"@gajae-code/natives": "0.15.5",
-		"@gajae-code/utils": "0.15.5",
+		"@gajae-code/ai": "0.16.0",
+		"@gajae-code/natives": "0.16.0",
+		"@gajae-code/utils": "0.16.0",
 		"@opentelemetry/api": "^1.9.0"
 	},
 	"devDependencies": {

package/src/agent-loop.ts

@@ -4523,7 +4523,13 @@ async function streamAssistantResponse(
 	// reflects the credential actually used, not the snapshot from AgentLoopConfig construction.
 	const authCredentialType = config.getAuthCredentialType?.(config.model.provider);
 
-	const resolvedMetadata = config.metadataResolver ? config.metadataResolver(config.model.provider) : config.metadata;
+	const resolvedMetadata = config.metadataResolver
+		? config.metadataResolver({
+				provider: config.model.provider,
+				model: config.model,
+				transport: streamFunction === streamSimple ? "default" : "custom",
+			})
+		: config.metadata;
 
 	// Synthetic recovery requests choose their tool mode explicitly below and
 	// must never consume a queued dynamic choice intended for an ordinary turn.

package/src/agent.ts

@@ -38,6 +38,7 @@ import type {
 	AgentEvent,
 	AgentLoopConfig,
 	AgentMessage,
+	AgentMetadataResolverContext,
 	AgentState,
 	AgentTool,
 	AgentToolContext,
@@ -116,6 +117,27 @@ function sanitizeAgentFailure(error: unknown, runtimeClassifiedCode?: string): {
 	return { code, message: "Agent run failed." };
 }
 
+/** Only runtime-authenticated built-in constructors may contribute a name. */
+const TRUSTED_ERROR_CONSTRUCTORS = new Map<Function, string>([
+	[Error, "Error"],
+	[TypeError, "TypeError"],
+	[RangeError, "RangeError"],
+	[SyntaxError, "SyntaxError"],
+	[ReferenceError, "ReferenceError"],
+	[URIError, "URIError"],
+	[EvalError, "EvalError"],
+	[AggregateError, "AggregateError"],
+]);
+
+function safeErrorName(error: unknown): string | undefined {
+	try {
+		if (!(error instanceof Error)) return undefined;
+		return TRUSTED_ERROR_CONSTRUCTORS.get(error.constructor);
+	} catch {
+		return undefined;
+	}
+}
+
 /** Guarded HTTP-status extraction for untrusted provider errors: a throwing
  * getter must never escape the failure handler and suppress terminalization
  * (exact-head review P1). */
@@ -466,7 +488,7 @@ export class Agent {
 	#sessionId?: string;
 	#providerSessionId?: string;
 	#metadata?: Record<string, unknown>;
-	#metadataResolver?: (provider: string) => Record<string, unknown> | undefined;
+	#metadataResolver?: (context: AgentMetadataResolverContext) => Record<string, unknown> | undefined;
 	#providerSessionState?: Map<string, ProviderSessionState>;
 	#thinkingBudgets?: ThinkingBudgets;
 	#temperature?: number;
@@ -505,6 +527,8 @@ export class Agent {
 	#onHarmonyLeak?: (event: HarmonyAuditEvent) => void | Promise<void>;
 	#onBeforeYield?: () => Promise<void> | void;
 	#shouldPause?: AgentLoopConfig["shouldPause"];
+	/** While set and returning true, steering is neither admitted nor dequeued. */
+	#steeringAdmissionFence?: () => boolean;
 	#maintainContext?: AgentLoopConfig["maintainContext"];
 	#telemetry?: AgentLoopConfig["telemetry"];
 	#appendOnlyContext?: AppendOnlyContextManager;
@@ -669,8 +693,12 @@ export class Agent {
 	 * only included for `"anthropic"` requests). Falls back to the static
 	 * {@link metadata} value when no resolver is set.
 	 */
-	metadataForProvider(provider: string): Record<string, unknown> | undefined {
-		if (this.#metadataResolver) return this.#metadataResolver(provider);
+	metadataForProvider(
+		provider: string,
+		model?: Model,
+		transport?: AgentMetadataResolverContext["transport"],
+	): Record<string, unknown> | undefined {
+		if (this.#metadataResolver) return this.#metadataResolver({ provider, model, transport });
 		return this.#metadata;
 	}
 
@@ -682,7 +710,9 @@ export class Agent {
 	 * credential. Pass `undefined` to clear and revert to the static
 	 * {@link metadata} value.
 	 */
-	setMetadataResolver(resolver: ((provider: string) => Record<string, unknown> | undefined) | undefined): void {
+	setMetadataResolver(
+		resolver: ((context: AgentMetadataResolverContext) => Record<string, unknown> | undefined) | undefined,
+	): void {
 		this.#metadataResolver = resolver;
 	}
 
@@ -891,6 +921,24 @@ export class Agent {
 		this.#shouldPause = fn;
 	}
 
+	/** The currently installed cooperative pause checkpoint, if any. */
+	get shouldPause(): AgentLoopConfig["shouldPause"] | undefined {
+		return this.#shouldPause;
+	}
+
+	/**
+	 * Fence old-turn steering admission.
+	 *
+	 * The loop polls steering UPSTREAM of its pause checkpoint (and again on the
+	 * immediate-interrupt path), so a cooperative stop alone cannot prevent one
+	 * more old-turn model call once a steering message has already been dequeued.
+	 * While the fence returns true the poll yields no messages AND does not
+	 * dequeue, so the queue survives intact for the next turn.
+	 */
+	setSteeringAdmissionFence(fn: (() => boolean) | undefined): void {
+		this.#steeringAdmissionFence = fn;
+	}
+
 	setMaintainContext(fn: AgentLoopConfig["maintainContext"] | undefined): void {
 		this.#maintainContext = fn;
 	}
@@ -1911,6 +1959,12 @@ export class Agent {
 					skipInitialSteeringPoll = false;
 					return [];
 				}
+				// Fenced: yield nothing and dequeue nothing, so a steer submitted while a
+				// fold is being claimed is neither consumed by the run being wound down
+				// nor lost.
+				if (this.#steeringAdmissionFence?.() === true) {
+					return [];
+				}
 				const queued = this.#dequeueSteeringMessages();
 				if (this.#activeRunId !== runId) {
 					this.#steeringQueue = [...queued, ...this.#steeringQueue];
@@ -2095,6 +2149,8 @@ export class Agent {
 			const runtimeFailureCode = abortController.signal.aborted
 				? "aborted"
 				: (managedLocalErrorDiagnostic(err)?.errorKind ?? providerCode);
+			const sanitized = sanitizeAgentFailure(err, runtimeFailureCode);
+			const errorName = safeErrorName(err);
 
 			const errorMsg: AgentMessage = {
 				role: "assistant",
@@ -2111,7 +2167,9 @@ export class Agent {
 					cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
 				},
 				stopReason: abortController.signal.aborted ? "aborted" : "error",
-				errorMessage: sanitizeAgentFailure(err).message,
+				errorMessage: sanitized.message,
+				errorCode: sanitized.code,
+				...(errorName ? { errorName } : {}),
 				errorStatus: safeErrorStatus(err),
 				// Local-diagnostic authority (`errorKind` + structured
 				// `bufferOverflow`) comes from ONE identity check: a foreign error

package/src/types.ts

@@ -28,6 +28,21 @@ export type StreamFn = (
 	...args: Parameters<typeof streamSimple>
 ) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>;
 
+/**
+ * Request context supplied to provider-aware metadata resolvers.
+ *
+ * The model is the exact model selected for the concrete request (including
+ * fallback and ephemeral requests), while `transport` distinguishes the
+ * built-in stream path from a caller-supplied stream function. Metadata that
+ * carries provider identity must use both values to fail closed when routing
+ * is not the canonical provider path.
+ */
+export interface AgentMetadataResolverContext {
+	provider: string;
+	model?: Model;
+	transport?: "default" | "custom";
+}
+
 /** Stable identifier for a managed logical run, shared by all of its retry attempts. */
 export type ManagedLogicalRunId = number;
 /** A resource owned by a prompt run until its promise settles. */
@@ -257,7 +272,7 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 * current when `AgentLoopConfig` was first constructed). Overrides the static
 	 * `metadata` field when present.
 	 */
-	metadataResolver?: (provider: string) => Record<string, unknown> | undefined;
+	metadataResolver?: (context: AgentMetadataResolverContext) => Record<string, unknown> | undefined;
 
 	/**
 	 * Converts AgentMessage[] to LLM-compatible Message[] before each LLM call.