@gajae-code/agent-core 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [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

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

@@ -51,5 +51,6 @@ export declare function agentLoopContinueDetailed(context: AgentContext, config:
     readonly stream: EventStream<AgentEvent, AgentMessage[]>;
     readonly detailed: () => Promise<AgentLoopDetailedResult>;
 };
+export declare function normalizeMessagesForProvider(messages: Context["messages"], model: AgentLoopConfig["model"]): Context["messages"];
 export declare const INTENT_FIELD = "_i";
 export declare function normalizeTools(tools: AgentContext["tools"], injectIntent: boolean): Context["tools"];

package/dist/types/agent.d.ts

@@ -49,6 +49,8 @@ export interface AgentOptions {
      * Used by providers that support session-based caching (e.g., OpenAI code provider).
      */
     sessionId?: string;
+    /** Provider-facing cache/session affinity identifier. */
+    providerSessionId?: string;
     /**
      * Shared provider state map for session-scoped transport/session caches.
      */
@@ -157,6 +159,7 @@ export interface AgentPromptOptions {
 }
 export declare class Agent {
     #private;
+    get intentTracing(): boolean;
     streamFn: StreamFn;
     getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
     getAuthCredentialType?: (provider: string) => "api_key" | "oauth" | undefined;
@@ -180,6 +183,8 @@ export declare class Agent {
      * Call this when switching sessions (new session, branch, resume).
      */
     set sessionId(value: string | undefined);
+    get providerSessionId(): string | undefined;
+    set providerSessionId(value: string | undefined);
     /**
      * Static metadata forwarded to every API request when no resolver is installed
      * (e.g. `metadata.user_id` for Anthropic session attribution). Setting this

package/dist/types/append-only-context.d.ts

@@ -39,6 +39,8 @@ export declare class StablePrefix {
     get fingerprint(): string;
     get version(): number;
     get built(): boolean;
+    exportSnapshot(): StablePrefixSnapshot | null;
+    importSnapshot(snapshot: StablePrefixSnapshot, options: BuildOptions): void;
     /**
      * Build or rebuild from live context.
      * Returns `true` if the prefix actually changed (cache miss imminent).
@@ -94,6 +96,11 @@ export declare class AppendOnlyContextManager {
     #private;
     readonly prefix: StablePrefix;
     readonly log: AppendOnlyLog;
+    static forkFromSeed(args: {
+        prefixSnapshot?: StablePrefixSnapshot;
+        messages?: readonly Message[];
+        options: BuildOptions;
+    }): AppendOnlyContextManager;
     build(context: AgentContext, options: BuildOptions): Context;
     /**
      * Sync normalized (provider-level) messages into the append-only log.
@@ -102,6 +109,9 @@ export declare class AppendOnlyContextManager {
      * (same length, changed content via a rolling digest).
      */
     syncMessages(normalizedMessages: any[]): void;
+    seedNormalizedMessages(messages: readonly Message[], options?: {
+        reset?: boolean;
+    }): void;
     /** Reset prefix + log for a model/provider switch while mode stays active. */
     invalidateForModelChange(): void;
     /** Reset the sync cursor AND clear the log. */

package/dist/types/types.d.ts

@@ -21,6 +21,12 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * Used by providers that support session-based caching (e.g., OpenAI code provider).
      */
     sessionId?: string;
+    /**
+     * Optional provider-facing cache/session affinity identifier. When set, this
+     * is forwarded to providers as StreamOptions.sessionId while `sessionId`
+     * remains the logical agent conversation id for telemetry/metadata.
+     */
+    providerSessionId?: string;
     /**
      * Optional resolver called per LLM request to produce request metadata.
      * When set, the agent loop evaluates it **after** `getApiKey` resolves the

package/package.json

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

package/src/agent-loop.ts

@@ -300,7 +300,7 @@ function createDetailedCapture(config: AgentLoopConfig): {
 	};
 }
 
-function normalizeMessagesForProvider(
+export function normalizeMessagesForProvider(
 	messages: Context["messages"],
 	model: AgentLoopConfig["model"],
 ): Context["messages"] {
@@ -735,6 +735,7 @@ async function streamAssistantResponse(
 				apiKey: resolvedApiKey,
 				authCredentialType,
 				metadata: resolvedMetadata,
+				sessionId: config.providerSessionId ?? config.sessionId,
 				toolChoice: effectiveToolChoice,
 				reasoning: effectiveReasoning,
 				temperature: effectiveTemperature,
@@ -864,30 +865,28 @@ function emitAbortedAssistantMessage(
 	stream: EventStream<AgentEvent, AgentMessage[]>,
 ): AssistantMessage {
 	const errorMessage = "Request was aborted";
-	const abortedMessage: AssistantMessage = partialMessage
-		? { ...partialMessage, stopReason: "aborted", errorMessage }
-		: {
-				role: "assistant",
-				content: [],
-				api: config.model.api,
-				provider: config.model.provider,
-				model: config.model.id,
-				usage: {
-					input: 0,
-					output: 0,
-					cacheRead: 0,
-					cacheWrite: 0,
-					totalTokens: 0,
-					cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-				},
-				stopReason: "aborted",
-				errorMessage,
-				timestamp: Date.now(),
-			};
+	const now = Date.now();
+	const abortedMessage: AssistantMessage = {
+		role: "assistant",
+		content: partialMessage ? structuredClone(partialMessage.content) : [],
+		api: config.model.api,
+		provider: config.model.provider,
+		model: config.model.id,
+		usage: {
+			input: 0,
+			output: 0,
+			cacheRead: 0,
+			cacheWrite: 0,
+			totalTokens: 0,
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+		},
+		stopReason: "aborted",
+		errorMessage,
+		timestamp: now,
+	};
 	if (addedPartial) {
-		context.messages[context.messages.length - 1] = abortedMessage;
+		context.messages.pop();
 	} else {
-		context.messages.push(abortedMessage);
 		stream.push({ type: "message_start", message: { ...abortedMessage } });
 	}
 	stream.push({ type: "message_end", message: abortedMessage });

package/src/agent.ts

@@ -118,6 +118,8 @@ export interface AgentOptions {
 	 * Used by providers that support session-based caching (e.g., OpenAI code provider).
 	 */
 	sessionId?: string;
+	/** Provider-facing cache/session affinity identifier. */
+	providerSessionId?: string;
 	/**
 	 * Shared provider state map for session-scoped transport/session caches.
 	 */
@@ -269,6 +271,7 @@ export class Agent {
 	#followUpMode: "all" | "one-at-a-time";
 	#interruptMode: "immediate" | "wait";
 	#sessionId?: string;
+	#providerSessionId?: string;
 	#metadata?: Record<string, unknown>;
 	#metadataResolver?: (provider: string) => Record<string, unknown> | undefined;
 	#providerSessionState?: Map<string, ProviderSessionState>;
@@ -303,6 +306,10 @@ export class Agent {
 	#telemetry?: AgentLoopConfig["telemetry"];
 	#appendOnlyContext?: AppendOnlyContextManager;
 
+	get intentTracing(): boolean {
+		return this.#intentTracing;
+	}
+
 	/** Buffered Cursor tool results with text length at time of call (for correct ordering) */
 	#cursorToolResultBuffer: CursorToolResultEntry[] = [];
 
@@ -329,6 +336,7 @@ export class Agent {
 		this.#interruptMode = opts.interruptMode || "immediate";
 		this.streamFn = opts.streamFn || streamSimple;
 		this.#sessionId = opts.sessionId;
+		this.#providerSessionId = opts.providerSessionId;
 		this.#providerSessionState = opts.providerSessionState;
 		this.#thinkingBudgets = opts.thinkingBudgets;
 		this.#temperature = opts.temperature;
@@ -376,6 +384,14 @@ export class Agent {
 		this.#sessionId = value;
 	}
 
+	get providerSessionId(): string | undefined {
+		return this.#providerSessionId;
+	}
+
+	set providerSessionId(value: string | undefined) {
+		this.#providerSessionId = value;
+	}
+
 	/**
 	 * Static metadata forwarded to every API request when no resolver is installed
 	 * (e.g. `metadata.user_id` for Anthropic session attribution). Setting this
@@ -1070,6 +1086,7 @@ export class Agent {
 			hideThinkingSummary: this.#hideThinkingSummary,
 			interruptMode: this.#interruptMode,
 			sessionId: this.#sessionId,
+			providerSessionId: this.#providerSessionId,
 			metadata: this.#metadataResolver ? undefined : this.#metadata,
 			metadataResolver: this.#metadataResolver,
 			providerSessionState: this.#providerSessionState,

package/src/append-only-context.ts

@@ -57,6 +57,23 @@ export class StablePrefix {
 		return this.#snapshot !== null;
 	}
 
+	exportSnapshot(): StablePrefixSnapshot | null {
+		return this.#snapshot ? cloneJson(this.#snapshot) : null;
+	}
+
+	importSnapshot(snapshot: StablePrefixSnapshot, options: BuildOptions): void {
+		const systemPrompt = cloneJson(snapshot.systemPrompt);
+		const tools = normalizeImportedTools(snapshot.tools, options);
+		const fingerprint = computeFingerprint(systemPrompt, tools, options);
+		if (fingerprint !== snapshot.fingerprint) {
+			throw new Error(
+				`StablePrefix.importSnapshot() fingerprint mismatch: expected ${fingerprint}, received ${snapshot.fingerprint}`,
+			);
+		}
+		this.#snapshot = { systemPrompt, tools, fingerprint };
+		this.#version++;
+	}
+
 	/**
 	 * Build or rebuild from live context.
 	 * Returns `true` if the prefix actually changed (cache miss imminent).
@@ -83,7 +100,7 @@ export class StablePrefix {
 	toContext(): { systemPrompt: string[]; tools: Tool[] } {
 		const s = this.#snapshot;
 		if (!s) throw new Error("StablePrefix.toContext() called before build()");
-		return { systemPrompt: s.systemPrompt, tools: s.tools };
+		return { systemPrompt: cloneJson(s.systemPrompt), tools: cloneJson(s.tools) };
 	}
 }
 
@@ -160,6 +177,23 @@ export class AppendOnlyContextManager {
 	#lastSyncCount = 0;
 	/** Rolling digest of synced message content — detects in-place rewrites. */
 	#syncedDigest = 0;
+	/** Number of provider-normalized messages that were seeded before child-local messages. */
+	#seededPrefixCount = 0;
+
+	static forkFromSeed(args: {
+		prefixSnapshot?: StablePrefixSnapshot;
+		messages?: readonly Message[];
+		options: BuildOptions;
+	}): AppendOnlyContextManager {
+		const manager = new AppendOnlyContextManager();
+		if (args.prefixSnapshot) {
+			manager.prefix.importSnapshot(args.prefixSnapshot, args.options);
+		}
+		if (args.messages) {
+			manager.seedNormalizedMessages(args.messages);
+		}
+		return manager;
+	}
 
 	build(context: AgentContext, options: BuildOptions): Context {
 		this.prefix.build(context, options);
@@ -174,29 +208,57 @@ export class AppendOnlyContextManager {
 	 * (same length, changed content via a rolling digest).
 	 */
 	syncMessages(normalizedMessages: any[]): void {
+		const seededPrefix = this.#seededPrefixCount > 0 ? this.log.toMessages().slice(0, this.#seededPrefixCount) : [];
+		const includesSeedPrefix =
+			seededPrefix.length > 0 &&
+			normalizedMessages.length >= seededPrefix.length &&
+			this.#computeDigest(normalizedMessages.slice(0, seededPrefix.length)) === this.#computeDigest(seededPrefix);
+		const messagesToSync =
+			seededPrefix.length > 0 && !includesSeedPrefix ? [...seededPrefix, ...normalizedMessages] : normalizedMessages;
+
 		// Detect in-place rewrites of already-synced messages.
 		if (
 			this.#lastSyncCount > 0 &&
-			this.#lastSyncCount <= normalizedMessages.length &&
-			this.#computeDigest(normalizedMessages.slice(0, this.#lastSyncCount)) !== this.#syncedDigest
+			this.#lastSyncCount <= messagesToSync.length &&
+			this.#computeDigest(messagesToSync.slice(0, this.#lastSyncCount)) !== this.#syncedDigest
 		) {
+			if (this.#seededPrefixCount > 0) {
+				throw new Error("AppendOnlyContextManager.syncMessages() seed prefix changed");
+			}
 			this.log.clear();
 			this.#lastSyncCount = 0;
 		}
 
-		// Compaction — array shrunk.
-		if (normalizedMessages.length < this.#lastSyncCount) {
+		// Compaction — array shrunk. Seeded forks preserve the inherited prefix
+		// and append child-local deltas, so a shorter child message array is not a
+		// compaction signal while a seed prefix is active.
+		if (messagesToSync.length < this.#lastSyncCount) {
+			if (this.#seededPrefixCount > 0) {
+				throw new Error("AppendOnlyContextManager.syncMessages() cannot compact a seeded fork without reset");
+			}
 			this.log.clear();
 			this.#lastSyncCount = 0;
 		}
 
-		const newMsgs = normalizedMessages.slice(this.#lastSyncCount);
+		const newMsgs = messagesToSync.slice(this.#lastSyncCount);
 		for (const msg of newMsgs) {
 			this.log.append(msg);
 		}
 
-		this.#lastSyncCount = normalizedMessages.length;
-		this.#syncedDigest = this.#computeDigest(normalizedMessages);
+		this.#lastSyncCount = messagesToSync.length;
+		this.#syncedDigest = this.#computeDigest(messagesToSync);
+	}
+
+	seedNormalizedMessages(messages: readonly Message[], options?: { reset?: boolean }): void {
+		if (this.log.length > 0 && options?.reset !== true) {
+			throw new Error("AppendOnlyContextManager.seedNormalizedMessages() cannot seed a non-empty log without reset");
+		}
+		const clonedMessages = cloneJson([...messages]);
+		this.log.clear();
+		this.log.extend(clonedMessages);
+		this.#lastSyncCount = clonedMessages.length;
+		this.#syncedDigest = this.#computeDigest(clonedMessages);
+		this.#seededPrefixCount = clonedMessages.length;
 	}
 
 	/** Reset prefix + log for a model/provider switch while mode stays active. */
@@ -205,6 +267,7 @@ export class AppendOnlyContextManager {
 		this.log.clear();
 		this.#lastSyncCount = 0;
 		this.#syncedDigest = 0;
+		this.#seededPrefixCount = 0;
 	}
 
 	/** Reset the sync cursor AND clear the log. */
@@ -212,6 +275,7 @@ export class AppendOnlyContextManager {
 		this.log.clear();
 		this.#lastSyncCount = 0;
 		this.#syncedDigest = 0;
+		this.#seededPrefixCount = 0;
 	}
 
 	appendMessage(message: any): void {
@@ -231,6 +295,7 @@ export class AppendOnlyContextManager {
 		this.log.clear();
 		this.#lastSyncCount = 0;
 		this.#syncedDigest = 0;
+		this.#seededPrefixCount = 0;
 		this.prefix.build(context, options);
 	}
 
@@ -276,6 +341,16 @@ function takeSnapshot(context: AgentContext, options: BuildOptions): StablePrefi
 	};
 }
 
+function normalizeImportedTools(tools: readonly Tool[], options: BuildOptions): Tool[] {
+	const clonedTools = cloneJson(tools);
+	const normalizedTools = normalizeTools(clonedTools as AgentContext["tools"], options.intentTracing) ?? [];
+	return cloneJson(normalizedTools);
+}
+
+function cloneJson<T>(value: T): T {
+	return JSON.parse(JSON.stringify(value)) as T;
+}
+
 function computeFingerprint(systemPrompt: string[], tools: Tool[], options: BuildOptions): string {
 	const payload = JSON.stringify({
 		s: systemPrompt,

package/src/types.ts

@@ -43,6 +43,12 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 * Used by providers that support session-based caching (e.g., OpenAI code provider).
 	 */
 	sessionId?: string;
+	/**
+	 * Optional provider-facing cache/session affinity identifier. When set, this
+	 * is forwarded to providers as StreamOptions.sessionId while `sessionId`
+	 * remains the logical agent conversation id for telemetry/metadata.
+	 */
+	providerSessionId?: string;
 
 	/**
 	 * Optional resolver called per LLM request to produce request metadata.