@anthropic-field/core 0.1.0

package/dist/src/core/turn.js

@@ -0,0 +1,209 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { getResponseText } from '../utils/partUtils.js';
+import { reportError } from '../utils/errorReporting.js';
+import { getErrorMessage, UnauthorizedError, toFriendlyError, } from '../utils/errors.js';
+import { InvalidStreamError } from './geminiChat.js';
+import { parseThought } from '../utils/thoughtUtils.js';
+import { createUserContent } from '@google/genai';
+import { getCitations } from '../utils/generateContentResponseUtilities.js';
+import {} from '../scheduler/types.js';
+export var GeminiEventType;
+(function (GeminiEventType) {
+    GeminiEventType["Content"] = "content";
+    GeminiEventType["ToolCallRequest"] = "tool_call_request";
+    GeminiEventType["ToolCallResponse"] = "tool_call_response";
+    GeminiEventType["ToolCallConfirmation"] = "tool_call_confirmation";
+    GeminiEventType["UserCancelled"] = "user_cancelled";
+    GeminiEventType["Error"] = "error";
+    GeminiEventType["ChatCompressed"] = "chat_compressed";
+    GeminiEventType["Thought"] = "thought";
+    GeminiEventType["MaxSessionTurns"] = "max_session_turns";
+    GeminiEventType["Finished"] = "finished";
+    GeminiEventType["LoopDetected"] = "loop_detected";
+    GeminiEventType["Citation"] = "citation";
+    GeminiEventType["Retry"] = "retry";
+    GeminiEventType["ContextWindowWillOverflow"] = "context_window_will_overflow";
+    GeminiEventType["InvalidStream"] = "invalid_stream";
+    GeminiEventType["ModelInfo"] = "model_info";
+    GeminiEventType["AgentExecutionStopped"] = "agent_execution_stopped";
+    GeminiEventType["AgentExecutionBlocked"] = "agent_execution_blocked";
+})(GeminiEventType || (GeminiEventType = {}));
+export var CompressionStatus;
+(function (CompressionStatus) {
+    /** The compression was successful */
+    CompressionStatus[CompressionStatus["COMPRESSED"] = 1] = "COMPRESSED";
+    /** The compression failed due to the compression inflating the token count */
+    CompressionStatus[CompressionStatus["COMPRESSION_FAILED_INFLATED_TOKEN_COUNT"] = 2] = "COMPRESSION_FAILED_INFLATED_TOKEN_COUNT";
+    /** The compression failed due to an error counting tokens */
+    CompressionStatus[CompressionStatus["COMPRESSION_FAILED_TOKEN_COUNT_ERROR"] = 3] = "COMPRESSION_FAILED_TOKEN_COUNT_ERROR";
+    /** The compression failed because the summary was empty */
+    CompressionStatus[CompressionStatus["COMPRESSION_FAILED_EMPTY_SUMMARY"] = 4] = "COMPRESSION_FAILED_EMPTY_SUMMARY";
+    /** The compression was not necessary and no action was taken */
+    CompressionStatus[CompressionStatus["NOOP"] = 5] = "NOOP";
+})(CompressionStatus || (CompressionStatus = {}));
+// A turn manages the agentic loop turn within the server context.
+export class Turn {
+    chat;
+    prompt_id;
+    pendingToolCalls = [];
+    debugResponses = [];
+    pendingCitations = new Set();
+    finishReason = undefined;
+    constructor(chat, prompt_id) {
+        this.chat = chat;
+        this.prompt_id = prompt_id;
+    }
+    // The run method yields simpler events suitable for server logic
+    async *run(modelConfigKey, req, signal, displayContent) {
+        try {
+            // Note: This assumes `sendMessageStream` yields events like
+            // { type: StreamEventType.RETRY } or { type: StreamEventType.CHUNK, value: GenerateContentResponse }
+            const responseStream = await this.chat.sendMessageStream(modelConfigKey, req, this.prompt_id, signal, displayContent);
+            for await (const streamEvent of responseStream) {
+                if (signal?.aborted) {
+                    yield { type: GeminiEventType.UserCancelled };
+                    return;
+                }
+                // Handle the new RETRY event
+                if (streamEvent.type === 'retry') {
+                    yield { type: GeminiEventType.Retry };
+                    continue; // Skip to the next event in the stream
+                }
+                if (streamEvent.type === 'agent_execution_stopped') {
+                    yield {
+                        type: GeminiEventType.AgentExecutionStopped,
+                        value: { reason: streamEvent.reason },
+                    };
+                    return;
+                }
+                if (streamEvent.type === 'agent_execution_blocked') {
+                    yield {
+                        type: GeminiEventType.AgentExecutionBlocked,
+                        value: { reason: streamEvent.reason },
+                    };
+                    continue;
+                }
+                // Assuming other events are chunks with a `value` property
+                const resp = streamEvent.value;
+                if (!resp)
+                    continue; // Skip if there's no response body
+                this.debugResponses.push(resp);
+                const traceId = resp.responseId;
+                const parts = resp.candidates?.[0]?.content?.parts ?? [];
+                for (const part of parts) {
+                    if (part.thought) {
+                        const thought = parseThought(part.text ?? '');
+                        yield {
+                            type: GeminiEventType.Thought,
+                            value: thought,
+                            traceId,
+                        };
+                    }
+                }
+                const text = getResponseText(resp);
+                if (text) {
+                    yield { type: GeminiEventType.Content, value: text, traceId };
+                }
+                // Handle function calls (requesting tool execution)
+                const functionCalls = resp.functionCalls ?? [];
+                for (const fnCall of functionCalls) {
+                    const event = this.handlePendingFunctionCall(fnCall, traceId);
+                    if (event) {
+                        yield event;
+                    }
+                }
+                for (const citation of getCitations(resp)) {
+                    this.pendingCitations.add(citation);
+                }
+                // Check if response was truncated or stopped for various reasons
+                const finishReason = resp.candidates?.[0]?.finishReason;
+                // This is the key change: Only yield 'Finished' if there is a finishReason.
+                if (finishReason) {
+                    if (this.pendingCitations.size > 0) {
+                        yield {
+                            type: GeminiEventType.Citation,
+                            value: `Citations:\n${[...this.pendingCitations].sort().join('\n')}`,
+                        };
+                        this.pendingCitations.clear();
+                    }
+                    this.finishReason = finishReason;
+                    yield {
+                        type: GeminiEventType.Finished,
+                        value: {
+                            reason: finishReason,
+                            usageMetadata: resp.usageMetadata,
+                        },
+                    };
+                }
+            }
+        }
+        catch (e) {
+            if (signal.aborted) {
+                yield { type: GeminiEventType.UserCancelled };
+                // Regular cancellation error, fail gracefully.
+                return;
+            }
+            if (e instanceof InvalidStreamError) {
+                yield { type: GeminiEventType.InvalidStream };
+                return;
+            }
+            const error = toFriendlyError(e);
+            if (error instanceof UnauthorizedError) {
+                throw error;
+            }
+            const contextForReport = [
+                ...this.chat.getHistory(/*curated*/ true),
+                createUserContent(req),
+            ];
+            await reportError(error, 'Error when talking to Gemini API', contextForReport, 'Turn.run-sendMessageStream');
+            const status = typeof error === 'object' &&
+                error !== null &&
+                'status' in error &&
+                typeof error.status === 'number'
+                ? error.status
+                : undefined;
+            const structuredError = {
+                message: getErrorMessage(error),
+                status,
+            };
+            await this.chat.maybeIncludeSchemaDepthContext(structuredError);
+            yield { type: GeminiEventType.Error, value: { error: structuredError } };
+            return;
+        }
+    }
+    handlePendingFunctionCall(fnCall, traceId) {
+        const callId = fnCall.id ??
+            `${fnCall.name}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+        const name = fnCall.name || 'undefined_tool_name';
+        const args = fnCall.args || {};
+        const toolCallRequest = {
+            callId,
+            name,
+            args,
+            isClientInitiated: false,
+            prompt_id: this.prompt_id,
+            traceId,
+        };
+        this.pendingToolCalls.push(toolCallRequest);
+        // Yield a request for the tool call, not the pending/confirming status
+        return { type: GeminiEventType.ToolCallRequest, value: toolCallRequest };
+    }
+    getDebugResponses() {
+        return this.debugResponses;
+    }
+    /**
+     * Get the concatenated response text from all responses in this turn.
+     * This extracts and joins all text content from the model's responses.
+     */
+    getResponseText() {
+        return this.debugResponses
+            .map((response) => getResponseText(response))
+            .filter((text) => text !== null)
+            .join(' ');
+    }
+}
+//# sourceMappingURL=turn.js.map

package/dist/src/core/turn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn.js","sourceRoot":"","sources":["../../../src/core/turn.ts"],"names":[],"mappings":"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"}

package/dist/src/fallback/handler.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Config } from '../config/config.js';
+export declare function handleFallback(config: Config, failedModel: string, authType?: string, error?: unknown): Promise<string | boolean | null>;

package/dist/src/fallback/handler.js

@@ -0,0 +1,110 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AuthType } from '../core/contentGenerator.js';
+import { openBrowserSecurely } from '../utils/secure-browser-launcher.js';
+import { debugLogger } from '../utils/debugLogger.js';
+import { getErrorMessage } from '../utils/errors.js';
+import { classifyFailureKind } from '../availability/errorClassification.js';
+import { buildFallbackPolicyContext, resolvePolicyChain, resolvePolicyAction, applyAvailabilityTransition, } from '../availability/policyHelpers.js';
+const UPGRADE_URL_PAGE = 'https://goo.gle/set-up-gemini-code-assist';
+export async function handleFallback(config, failedModel, authType, error) {
+    if (authType !== AuthType.LOGIN_WITH_GOOGLE) {
+        return null;
+    }
+    const chain = resolvePolicyChain(config);
+    const { failedPolicy, candidates } = buildFallbackPolicyContext(chain, failedModel);
+    const failureKind = classifyFailureKind(error);
+    const availability = config.getModelAvailabilityService();
+    const getAvailabilityContext = () => {
+        if (!failedPolicy)
+            return undefined;
+        return { service: availability, policy: failedPolicy };
+    };
+    let fallbackModel;
+    if (!candidates.length) {
+        fallbackModel = failedModel;
+    }
+    else {
+        const selection = availability.selectFirstAvailable(candidates.map((policy) => policy.model));
+        const lastResortPolicy = candidates.find((policy) => policy.isLastResort);
+        const selectedFallbackModel = selection.selectedModel ?? lastResortPolicy?.model;
+        const selectedPolicy = candidates.find((policy) => policy.model === selectedFallbackModel);
+        if (!selectedFallbackModel ||
+            selectedFallbackModel === failedModel ||
+            !selectedPolicy) {
+            return null;
+        }
+        fallbackModel = selectedFallbackModel;
+        // failureKind is already declared and calculated above
+        const action = resolvePolicyAction(failureKind, selectedPolicy);
+        if (action === 'silent') {
+            applyAvailabilityTransition(getAvailabilityContext, failureKind);
+            return processIntent(config, 'retry_always', fallbackModel);
+        }
+        // This will be used in the future when FallbackRecommendation is passed through UI
+        const recommendation = {
+            ...selection,
+            selectedModel: fallbackModel,
+            action,
+            failureKind,
+            failedPolicy,
+            selectedPolicy,
+        };
+        void recommendation;
+    }
+    const handler = config.getFallbackModelHandler();
+    if (typeof handler !== 'function') {
+        return null;
+    }
+    try {
+        const intent = await handler(failedModel, fallbackModel, error);
+        // If the user chose to switch/retry, we apply the availability transition
+        // to the failed model (e.g. marking it terminal if it had a quota error).
+        // We DO NOT apply it if the user chose 'stop' or 'retry_later', allowing
+        // them to try again later with the same model state.
+        if (intent === 'retry_always' || intent === 'retry_once') {
+            applyAvailabilityTransition(getAvailabilityContext, failureKind);
+        }
+        return await processIntent(config, intent, fallbackModel);
+    }
+    catch (handlerError) {
+        debugLogger.error('Fallback handler failed:', handlerError);
+        return null;
+    }
+}
+async function handleUpgrade() {
+    try {
+        await openBrowserSecurely(UPGRADE_URL_PAGE);
+    }
+    catch (error) {
+        debugLogger.warn('Failed to open browser automatically:', getErrorMessage(error));
+    }
+}
+async function processIntent(config, intent, fallbackModel) {
+    switch (intent) {
+        case 'retry_always':
+            // TODO(telemetry): Implement generic fallback event logging. Existing
+            // logFlashFallback is specific to a single Model.
+            config.activateFallbackMode(fallbackModel);
+            return true;
+        case 'retry_once':
+            // For distinct retry (retry_once), we do NOT set the active model permanently.
+            // The FallbackStrategy will handle routing to the available model for this turn
+            // based on the availability service state (which is updated before this).
+            return true;
+        case 'stop':
+            // Do not switch model on stop. User wants to stay on current model (and stop).
+            return false;
+        case 'retry_later':
+            return false;
+        case 'upgrade':
+            await handleUpgrade();
+            return false;
+        default:
+            throw new Error(`Unexpected fallback intent received from fallbackModelHandler: "${intent}"`);
+    }
+}
+//# sourceMappingURL=handler.js.map

package/dist/src/fallback/handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.js","sourceRoot":"","sources":["../../../src/fallback/handler.ts"],"names":[],"mappings":"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"}

package/dist/src/fallback/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ModelSelectionResult } from '../availability/modelAvailabilityService.js';
+import type { FailureKind, FallbackAction, ModelPolicy } from '../availability/modelPolicy.js';
+/**
+ * Defines the intent returned by the UI layer during a fallback scenario.
+ */
+export type FallbackIntent = 'retry_always' | 'retry_once' | 'stop' | 'retry_later' | 'upgrade';
+export interface FallbackRecommendation extends ModelSelectionResult {
+    action: FallbackAction;
+    failureKind: FailureKind;
+    failedPolicy?: ModelPolicy;
+    selectedPolicy: ModelPolicy;
+}
+/**
+ * The interface for the handler provided by the UI layer (e.g., the CLI)
+ * to interact with the user during a fallback scenario.
+ */
+export type FallbackModelHandler = (failedModel: string, fallbackModel: string, error?: unknown) => Promise<FallbackIntent | null>;
+/**
+ * Defines the intent returned by the UI layer during a validation required scenario.
+ */
+export type ValidationIntent = 'verify' | 'change_auth' | 'cancel';
+/**
+ * The interface for the handler provided by the UI layer (e.g., the CLI)
+ * to interact with the user when validation is required.
+ */
+export type ValidationHandler = (validationLink?: string, validationDescription?: string, learnMoreUrl?: string) => Promise<ValidationIntent>;

package/dist/src/fallback/types.js

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/fallback/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/fallback/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/src/generated/git-commit.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export declare const GIT_COMMIT_INFO = "2a3f1f278";
+export declare const CLI_VERSION = "0.28.0-nightly.20260128.adc8e11bb";

package/dist/src/generated/git-commit.js

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// This file is auto-generated by the build script (scripts/generate-git-commit-info.js)
+// Do not edit this file manually.
+export const GIT_COMMIT_INFO = '2a3f1f278';
+export const CLI_VERSION = '0.28.0-nightly.20260128.adc8e11bb';
+//# sourceMappingURL=git-commit.js.map

package/dist/src/generated/git-commit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-commit.js","sourceRoot":"","sources":["../../../src/generated/git-commit.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,wFAAwF;AACxF,kCAAkC;AAClC,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAC;AAC3C,MAAM,CAAC,MAAM,WAAW,GAAG,mCAAmC,CAAC"}

package/dist/src/hooks/hookAggregator.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { HookOutput, HookExecutionResult } from './types.js';
+import { DefaultHookOutput } from './types.js';
+import { HookEventName } from './types.js';
+/**
+ * Aggregated hook result
+ */
+export interface AggregatedHookResult {
+    success: boolean;
+    finalOutput?: DefaultHookOutput;
+    allOutputs: HookOutput[];
+    errors: Error[];
+    totalDuration: number;
+}
+/**
+ * Hook aggregator that merges results from multiple hooks using event-specific strategies
+ */
+export declare class HookAggregator {
+    /**
+     * Aggregate results from multiple hook executions
+     */
+    aggregateResults(results: HookExecutionResult[], eventName: HookEventName): AggregatedHookResult;
+    /**
+     * Merge hook outputs using event-specific strategies
+     *
+     * Note: We always use the merge logic even for single hooks to ensure
+     * consistent default behaviors (e.g., default decision='allow' for OR logic)
+     */
+    private mergeOutputs;
+    /**
+     * Merge outputs with OR decision logic and message concatenation
+     */
+    private mergeWithOrDecision;
+    /**
+     * Merge outputs with later fields replacing earlier fields
+     */
+    private mergeWithFieldReplacement;
+    /**
+     * Merge tool selection outputs with specific logic for tool config
+     *
+     * Tool Selection Strategy:
+     * - The intent is to provide a UNION of tools from all hooks
+     * - If any hook specifies NONE mode, no tools are available (most restrictive wins)
+     * - If any hook specifies ANY mode (and no NONE), ANY mode is used
+     * - Otherwise AUTO mode is used
+     * - Function names are collected from all hooks and sorted for deterministic caching
+     *
+     * This means hooks can only add/enable tools, not filter them out individually.
+     * If one hook restricts and another re-enables, the union takes the re-enabled tool.
+     */
+    private mergeToolSelectionOutputs;
+    /**
+     * Simple merge for events without special logic
+     */
+    private mergeSimple;
+    /**
+     * Create the appropriate specific hook output class based on event type
+     */
+    private createSpecificHookOutput;
+    /**
+     * Extract additional context from hook-specific outputs
+     */
+    private extractAdditionalContext;
+}