@gajae-code/ai 0.12.5 → 0.12.7

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+## [0.12.7] - 2026-07-31
+
+## [0.12.6] - 2026-07-31
+
 ## [0.12.5] - 2026-07-30
 ### Fixed
 

package/dist/types/types.d.ts

@@ -224,19 +224,21 @@ export interface StreamOptions {
     /**
      * Optional callback for inspecting or replacing provider payloads before sending.
      * Return undefined to keep the payload unchanged.
+     * The `scope` parameter carries the per-attempt identity for execution attribution.
      */
-    onPayload?: (payload: unknown, model?: Model<Api>) => unknown | undefined | Promise<unknown | undefined>;
+    onPayload?: (payload: unknown, model?: Model<Api>, scope?: AttemptScopeRef) => unknown | undefined | Promise<unknown | undefined>;
     /**
      * Optional callback for provider response metadata after headers are received.
+     * The `scope` parameter carries the per-attempt identity for execution attribution.
      */
-    onResponse?: (response: ProviderResponseMetadata, model?: Model<Api>) => void | Promise<void>;
+    onResponse?: (response: ProviderResponseMetadata, model?: Model<Api>, scope?: AttemptScopeRef) => void | Promise<void>;
     /**
      * Optional callback for raw Server-Sent Events as they arrive from HTTP streaming providers.
      *
      * Diagnostic only: provider implementations must ignore callback failures and must not
      * let observers alter stream contents.
      */
-    onSseEvent?: (event: RawSseEvent, model?: Model<Api>) => void;
+    onSseEvent?: (event: RawSseEvent, model?: Model<Api>, scope?: AttemptScopeRef) => void;
     /**
      * Optional override for the first streamed event watchdog in milliseconds.
      * Set to 0 to disable the first-event watchdog for this request.
@@ -266,6 +268,22 @@ export interface StreamOptions {
     authCredentialType?: "api_key" | "oauth";
     /** Cursor exec/MCP tool handlers (cursor-agent only). */
     execHandlers?: CursorExecHandlers;
+    /** Per-attempt identity for execution attribution. Threaded into onPayload/onResponse calls. */
+    attemptScope?: AttemptScopeRef;
+}
+/**
+ * Low-level structural carrier for per-attempt identity attribution.
+ *
+ * Defined in `packages/ai` so that {@link SimpleStreamOptions} and provider
+ * hook signatures can carry an attempt identity without a reverse dependency
+ * on `packages/agent`. The concrete `AttemptScope` in `packages/agent` is
+ * structurally assignable to this interface (same `attemptId` + `generation`
+ * + `lineage` fields).
+ */
+export interface AttemptScopeRef {
+    readonly attemptId: string;
+    readonly generation: number;
+    readonly lineage: string;
 }
 export interface SimpleStreamOptions extends StreamOptions {
     reasoning?: Effort;

package/dist/types/utils/provider-response.d.ts

@@ -1,3 +1,6 @@
-import type { Api, Model, ProviderResponseMetadata, StreamOptions } from "../types";
+import type { Api, AttemptScopeRef, Model, ProviderResponseMetadata, StreamOptions } from "../types";
 export declare function normalizeProviderResponse(response: Response, requestId?: string | null, metadata?: Record<string, unknown>): ProviderResponseMetadata;
-export declare function notifyProviderResponse(options: Pick<StreamOptions, "onResponse"> | undefined, response: Response, model?: Model<Api>, requestId?: string | null, metadata?: Record<string, unknown>): Promise<void>;
+export declare function notifyProviderResponse(options: {
+    onResponse?: StreamOptions["onResponse"];
+    attemptScope?: AttemptScopeRef;
+} | undefined, response: Response, model?: Model<Api>, requestId?: string | null, metadata?: Record<string, unknown>): Promise<void>;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/ai",
-	"version": "0.12.5",
+	"version": "0.12.7",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -40,7 +40,7 @@
 	"dependencies": {
 		"@anthropic-ai/sdk": "^0.94.0",
 		"@bufbuild/protobuf": "^2.12.0",
-		"@gajae-code/utils": "0.12.5",
+		"@gajae-code/utils": "0.12.7",
 		"openai": "^6.36.0",
 		"partial-json": "^0.1.7",
 		"zod": "4.4.3"

package/src/providers/amazon-bedrock.ts

@@ -228,7 +228,7 @@ export const streamBedrock: StreamFunction<"bedrock-converse-stream"> = (
 				toolConfig,
 				additionalModelRequestFields,
 			};
-			options?.onPayload?.(commandInput);
+			options?.onPayload?.(commandInput, model, options?.attemptScope);
 
 			const host = `bedrock-runtime.${region}.amazonaws.com`;
 			const url = `https://${host}/model/${encodeURIComponent(model.id)}/converse-stream`;

package/src/providers/anthropic.ts

@@ -1348,7 +1348,9 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 					dynamicHeaders: copilotDynamicHeaders?.headers,
 					isOAuth: options?.isOAuth,
 					hasTools: !!context.tools?.length,
-					onSseEvent: options?.onSseEvent,
+					onSseEvent: options?.onSseEvent
+						? event => options.onSseEvent!(event, model, options?.attemptScope)
+						: undefined,
 					fetch: options?.fetch,
 					requestMaxRetries: options?.requestMaxRetries,
 					maxRetryDelayMs: options?.maxRetryDelayMs,
@@ -1386,7 +1388,7 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 				if (dropFastMode) {
 					dropAnthropicFastMode(nextParams);
 				}
-				const replacementPayload = await options?.onPayload?.(nextParams, model);
+				const replacementPayload = await options?.onPayload?.(nextParams, model, options?.attemptScope);
 				if (replacementPayload !== undefined) {
 					nextParams = replacementPayload as typeof nextParams;
 				}
@@ -1489,7 +1491,7 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 					} = await getAnthropicStreamResponse(
 						anthropicRequest,
 						requestSignal,
-						options?.client ? event => options?.onSseEvent?.(event, model) : undefined,
+						options?.client ? event => options?.onSseEvent?.(event, model, options?.attemptScope) : undefined,
 					);
 					await notifyProviderResponse(options, response, model, requestId);
 					let sawEvent = false;

package/src/providers/azure-openai-responses.ts

@@ -126,7 +126,7 @@ export const streamAzureOpenAIResponses: StreamFunction<"azure-openai-responses"
 			const { baseUrl } = resolveAzureConfig(model, options);
 			const params = buildParams(model, context, options, deploymentName, baseUrl);
 			const idleTimeoutMs = options?.streamIdleTimeoutMs ?? getOpenAIStreamIdleTimeoutMs();
-			options?.onPayload?.(params);
+			options?.onPayload?.(params, model, options?.attemptScope);
 			rawRequestDump = {
 				provider: model.provider,
 				api: output.api,
@@ -312,7 +312,9 @@ function createClient(model: Model<"azure-openai-responses">, apiKey: string, op
 		maxRetries: resolveRetryBudget(options?.requestMaxRetries, 5),
 		defaultHeaders: headers,
 		baseURL: baseUrl,
-		fetch: onSseEvent ? wrapFetchForSseDebug(baseFetch, event => onSseEvent(event, model)) : baseFetch,
+		fetch: onSseEvent
+			? wrapFetchForSseDebug(baseFetch, event => onSseEvent(event, model, options?.attemptScope))
+			: baseFetch,
 	});
 }
 

package/src/providers/cursor.ts

@@ -2632,7 +2632,7 @@ function buildGrpcRequest(
 		conversationId: state.conversationId,
 	});
 
-	options?.onPayload?.(runRequest);
+	options?.onPayload?.(runRequest, model, options?.attemptScope);
 
 	// Tools are sent later via requestContext (exec handshake)
 

package/src/providers/gitlab-duo.ts

@@ -279,6 +279,7 @@ export function streamGitLabDuo(
 								sessionId: options.sessionId,
 								providerSessionState: options.providerSessionState,
 								onPayload: options.onPayload,
+								attemptScope: options?.attemptScope,
 								onResponse: options.onResponse,
 								onSseEvent: options.onSseEvent,
 								fetch: options.fetch,
@@ -316,6 +317,7 @@ export function streamGitLabDuo(
 									sessionId: options.sessionId,
 									providerSessionState: options.providerSessionState,
 									onPayload: options.onPayload,
+									attemptScope: options?.attemptScope,
 									onResponse: options.onResponse,
 									onSseEvent: options.onSseEvent,
 									fetch: options.fetch,
@@ -348,6 +350,7 @@ export function streamGitLabDuo(
 									sessionId: options.sessionId,
 									providerSessionState: options.providerSessionState,
 									onPayload: options.onPayload,
+									attemptScope: options?.attemptScope,
 									onResponse: options.onResponse,
 									onSseEvent: options.onSseEvent,
 									fetch: options.fetch,

package/src/providers/google-gemini-cli.ts

@@ -350,7 +350,7 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 			const endpoints = baseUrl ? [baseUrl] : isAntigravity ? ANTIGRAVITY_ENDPOINT_FALLBACKS : [DEFAULT_ENDPOINT];
 
 			let requestBody = buildRequest(model, context, projectId, options, isAntigravity);
-			const replacementPayload = await options?.onPayload?.(requestBody, model);
+			const replacementPayload = await options?.onPayload?.(requestBody, model, options?.attemptScope);
 			if (replacementPayload !== undefined) {
 				requestBody = replacementPayload as typeof requestBody;
 			}
@@ -483,7 +483,12 @@ export const streamGoogleGeminiCli: StreamFunction<"google-gemini-cli"> = (
 				for await (const chunk of readSseJson<CloudCodeAssistResponseChunk>(
 					activeResponse.body!,
 					options?.signal,
-					event => options?.onSseEvent?.({ event: event.event, data: event.data, raw: [...event.raw] }, model),
+					event =>
+						options?.onSseEvent?.(
+							{ event: event.event, data: event.data, raw: [...event.raw] },
+							model,
+							options?.attemptScope,
+						),
 				)) {
 					const responseData = chunk.response;
 					if (!responseData) continue;

package/src/providers/google-shared.ts

@@ -835,7 +835,7 @@ export function streamGoogleGenAI<T extends "google-generative-ai" | "google-ver
 		try {
 			const plan = await prepare();
 			let params = plan.params;
-			const replacement = await options?.onPayload?.(params, model);
+			const replacement = await options?.onPayload?.(params, model, options?.attemptScope);
 			if (replacement !== undefined) {
 				params = replacement as GenerateContentParameters;
 			}
@@ -915,7 +915,11 @@ export function streamGoogleGenAI<T extends "google-generative-ai" | "google-ver
 			}
 
 			const googleStream = readSseJson<GenerateContentResponse>(response.body, options?.signal, event =>
-				options?.onSseEvent?.({ event: event.event, data: event.data, raw: [...event.raw] }, model),
+				options?.onSseEvent?.(
+					{ event: event.event, data: event.data, raw: [...event.raw] },
+					model,
+					options?.attemptScope,
+				),
 			);
 
 			stream.push({ type: "start", partial: output });

package/src/providers/mock.ts

@@ -327,6 +327,7 @@ async function runMock(
 					...(response.responseRequestId !== undefined ? { requestId: response.responseRequestId } : {}),
 				},
 				model,
+				options.attemptScope,
 			);
 		} catch (err) {
 			stream.fail(err);

package/src/providers/ollama.ts

@@ -406,7 +406,7 @@ export const streamOllama: StreamFunction<"ollama-chat"> = (
 			const baseUrl = normalizeBaseUrl(model.baseUrl);
 			let body = createChatBody(model, context, options);
 			const sentForcedToolChoice = body.tool_choice === "required";
-			const replacementPayload = await options.onPayload?.(body, model);
+			const replacementPayload = await options.onPayload?.(body, model, options?.attemptScope);
 			if (replacementPayload !== undefined) {
 				body = replacementPayload as typeof body;
 			}

package/src/providers/openai-anthropic-shim.ts

@@ -86,6 +86,7 @@ export function streamOpenAIAnthropicShim(
 					headers: mergedHeaders,
 					sessionId: options?.sessionId,
 					onPayload: options?.onPayload,
+					attemptScope: options?.attemptScope,
 					onResponse: options?.onResponse,
 					onSseEvent: options?.onSseEvent,
 					fetch: options?.fetch,
@@ -117,6 +118,7 @@ export function streamOpenAIAnthropicShim(
 					headers: mergedHeaders,
 					sessionId: options?.sessionId,
 					onPayload: options?.onPayload,
+					attemptScope: options?.attemptScope,
 					onResponse: options?.onResponse,
 					onSseEvent: options?.onSseEvent,
 					fetch: options?.fetch,

package/src/providers/openai-codex-responses.ts

@@ -647,7 +647,7 @@ async function buildCodexRequestContext(
 	const url = resolveCodexResponsesUrl(baseUrl);
 	const promptCacheKey = normalizeOpenAIResponsesPromptCacheKey(options?.sessionId);
 	const transformedBody = await buildTransformedCodexRequestBody(model, context, options);
-	options?.onPayload?.(transformedBody);
+	options?.onPayload?.(transformedBody, model, options?.attemptScope);
 
 	const requestHeaders = { ...(model.headers ?? {}), ...(options?.headers ?? {}) };
 	const rawRequestDump: RawHttpRequestDump = {
@@ -881,7 +881,7 @@ async function openCodexSseTransport(
 			body,
 			state,
 			requestSetup.requestSignal,
-			event => options?.onSseEvent?.(event, model),
+			event => options?.onSseEvent?.(event, model, options?.attemptScope),
 			options?.fetch,
 			options,
 		),

package/src/providers/openai-completions.ts

@@ -482,6 +482,7 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 				options?.requestMaxRetries,
 				options?.sessionId,
 				options?.maxRetryDelayMs,
+				options?.attemptScope,
 			);
 			const premiumRequestsTotal = copilotPremiumRequests;
 			getCapturedErrorResponse = captureErrorResponse;
@@ -504,7 +505,7 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 					effectiveToolStrictModeOverride,
 				);
 				appliedToolStrictMode = toolStrictMode;
-				options?.onPayload?.(params);
+				options?.onPayload?.(params, undefined, options?.attemptScope);
 				rawRequestDump = {
 					provider: model.provider,
 					api: output.api,
@@ -1023,6 +1024,7 @@ async function createClient(
 	requestMaxRetries?: number,
 	sessionId?: string,
 	maxRetryDelayMs?: number,
+	attemptScope?: import("../types.js").AttemptScopeRef,
 ): Promise<{
 	client: OpenAI;
 	copilotPremiumRequests: number | undefined;
@@ -1145,7 +1147,7 @@ async function createClient(
 		`Gajae-Code/${packageJson.version}`,
 	);
 	const debugFetch = onSseEvent
-		? wrapFetchForSseDebug(transformedFetch, event => onSseEvent(event, model))
+		? wrapFetchForSseDebug(transformedFetch, event => onSseEvent(event, model, attemptScope))
 		: transformedFetch;
 	// Bound HTTP request timeout to roughly the first-event watchdog window.
 	// The OpenAI SDK's default is 10 minutes per attempt × `maxRetries`, which

package/src/providers/openai-responses.ts

@@ -284,12 +284,13 @@ export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
 				options?.authCredentialType,
 				options?.requestMaxRetries,
 				options?.maxRetryDelayMs,
+				options?.attemptScope,
 			);
 			const premiumRequestsTotal = copilotPremiumRequests;
 			const providerSessionState = getOpenAIResponsesProviderSessionState(model, options?.providerSessionState);
 			const { params } = buildParams(model, context, options, providerSessionState, baseUrl);
 			const idleTimeoutMs = options?.streamIdleTimeoutMs ?? getOpenAIStreamIdleTimeoutMs();
-			options?.onPayload?.(params);
+			options?.onPayload?.(params, undefined, options?.attemptScope);
 			rawRequestDump = {
 				provider: model.provider,
 				api: output.api,
@@ -433,6 +434,7 @@ function createClient(
 	authCredentialType?: OpenAIResponsesOptions["authCredentialType"],
 	requestMaxRetries?: number,
 	maxRetryDelayMs?: number,
+	attemptScope?: import("../types.js").AttemptScopeRef,
 ): {
 	client: OpenAI;
 	copilotPremiumRequests: number | undefined;
@@ -502,7 +504,7 @@ function createClient(
 			maxRetries: resolveRetryBudget(requestMaxRetries, 5),
 			defaultHeaders: headers,
 			fetch: onSseEvent
-				? wrapFetchForSseDebug(transformedFetch, event => onSseEvent(event, model))
+				? wrapFetchForSseDebug(transformedFetch, event => onSseEvent(event, model, attemptScope))
 				: transformedFetch,
 		}),
 		copilotPremiumRequests,

package/src/stream.ts

@@ -705,6 +705,7 @@ function mapOptionsForApi<TApi extends Api>(
 		onPayload: options?.onPayload,
 		onResponse: options?.onResponse,
 		onSseEvent: options?.onSseEvent,
+		attemptScope: options?.attemptScope,
 		execHandlers: options?.execHandlers,
 		[managedAttemptValidated]: hasValidatedManagedAttempt(options),
 	};

package/src/types.ts

@@ -385,19 +385,29 @@ export interface StreamOptions {
 	/**
 	 * Optional callback for inspecting or replacing provider payloads before sending.
 	 * Return undefined to keep the payload unchanged.
+	 * The `scope` parameter carries the per-attempt identity for execution attribution.
 	 */
-	onPayload?: (payload: unknown, model?: Model<Api>) => unknown | undefined | Promise<unknown | undefined>;
+	onPayload?: (
+		payload: unknown,
+		model?: Model<Api>,
+		scope?: AttemptScopeRef,
+	) => unknown | undefined | Promise<unknown | undefined>;
 	/**
 	 * Optional callback for provider response metadata after headers are received.
+	 * The `scope` parameter carries the per-attempt identity for execution attribution.
 	 */
-	onResponse?: (response: ProviderResponseMetadata, model?: Model<Api>) => void | Promise<void>;
+	onResponse?: (
+		response: ProviderResponseMetadata,
+		model?: Model<Api>,
+		scope?: AttemptScopeRef,
+	) => void | Promise<void>;
 	/**
 	 * Optional callback for raw Server-Sent Events as they arrive from HTTP streaming providers.
 	 *
 	 * Diagnostic only: provider implementations must ignore callback failures and must not
 	 * let observers alter stream contents.
 	 */
-	onSseEvent?: (event: RawSseEvent, model?: Model<Api>) => void;
+	onSseEvent?: (event: RawSseEvent, model?: Model<Api>, scope?: AttemptScopeRef) => void;
 	/**
 	 * Optional override for the first streamed event watchdog in milliseconds.
 	 * Set to 0 to disable the first-event watchdog for this request.
@@ -427,6 +437,23 @@ export interface StreamOptions {
 	authCredentialType?: "api_key" | "oauth";
 	/** Cursor exec/MCP tool handlers (cursor-agent only). */
 	execHandlers?: CursorExecHandlers;
+	/** Per-attempt identity for execution attribution. Threaded into onPayload/onResponse calls. */
+	attemptScope?: AttemptScopeRef;
+}
+
+/**
+ * Low-level structural carrier for per-attempt identity attribution.
+ *
+ * Defined in `packages/ai` so that {@link SimpleStreamOptions} and provider
+ * hook signatures can carry an attempt identity without a reverse dependency
+ * on `packages/agent`. The concrete `AttemptScope` in `packages/agent` is
+ * structurally assignable to this interface (same `attemptId` + `generation`
+ * + `lineage` fields).
+ */
+export interface AttemptScopeRef {
+	readonly attemptId: string;
+	readonly generation: number;
+	readonly lineage: string;
 }
 
 // Unified options with reasoning passed to streamSimple() and completeSimple()

package/src/utils/provider-response.ts

@@ -1,4 +1,4 @@
-import type { Api, Model, ProviderResponseMetadata, StreamOptions } from "../types";
+import type { Api, AttemptScopeRef, Model, ProviderResponseMetadata, StreamOptions } from "../types";
 
 export function normalizeProviderResponse(
 	response: Response,
@@ -19,12 +19,12 @@ export function normalizeProviderResponse(
 }
 
 export async function notifyProviderResponse(
-	options: Pick<StreamOptions, "onResponse"> | undefined,
+	options: { onResponse?: StreamOptions["onResponse"]; attemptScope?: AttemptScopeRef } | undefined,
 	response: Response,
 	model?: Model<Api>,
 	requestId?: string | null,
 	metadata?: Record<string, unknown>,
 ): Promise<void> {
 	if (!options?.onResponse) return;
-	await options.onResponse(normalizeProviderResponse(response, requestId, metadata), model);
+	await options.onResponse(normalizeProviderResponse(response, requestId, metadata), model, options.attemptScope);
 }