@godscene/core 1.7.11

package/dist/types/ai-model/conversation-history.d.ts

@@ -0,0 +1,105 @@
+import type { SubGoal } from '../types';
+import type { ChatCompletionMessageParam } from 'openai/resources/index';
+export interface ConversationHistoryOptions {
+    initialMessages?: ChatCompletionMessageParam[];
+}
+export declare class ConversationHistory {
+    private readonly messages;
+    private subGoals;
+    private memories;
+    private historicalLogs;
+    pendingFeedbackMessage: string;
+    constructor(options?: ConversationHistoryOptions);
+    resetPendingFeedbackMessageIfExists(): void;
+    append(message: ChatCompletionMessageParam): void;
+    seed(messages: ChatCompletionMessageParam[]): void;
+    reset(): void;
+    /**
+     * Snapshot the conversation history, and replace the images with text if the number of images exceeds the limit.
+     * @param maxImages - The maximum number of images to include in the snapshot. Undefined means no limit.
+     * @returns The snapshot of the conversation history.
+     */
+    snapshot(maxImages?: number): ChatCompletionMessageParam[];
+    get length(): number;
+    [Symbol.iterator](): IterableIterator<ChatCompletionMessageParam>;
+    toJSON(): ChatCompletionMessageParam[];
+    /**
+     * Set all sub-goals, replacing any existing ones.
+     * Automatically marks the first pending goal as running.
+     */
+    setSubGoals(subGoals: SubGoal[]): void;
+    /**
+     * Merge sub-goals from update-plan-content.
+     * Preserves existing descriptions when incoming description is empty.
+     *
+     * This handles compact XML updates like:
+     * <sub-goal index="1" status="finished" />
+     */
+    mergeSubGoals(subGoals: SubGoal[]): void;
+    /**
+     * Update a single sub-goal by index.
+     * Clears logs if status or description actually changes.
+     * @returns true if the sub-goal was found and updated, false otherwise
+     */
+    updateSubGoal(index: number, updates: Partial<Omit<SubGoal, 'index'>>): boolean;
+    /**
+     * Mark the first pending sub-goal as running.
+     * Clears logs since status changes.
+     */
+    markFirstPendingAsRunning(): void;
+    /**
+     * Mark a sub-goal as finished.
+     * Automatically marks the next pending goal as running.
+     * @returns true if the sub-goal was found and updated, false otherwise
+     */
+    markSubGoalFinished(index: number): boolean;
+    /**
+     * Mark all sub-goals as finished.
+     * Clears logs for any goal whose status actually changes.
+     */
+    markAllSubGoalsFinished(): void;
+    /**
+     * Append a log entry to the currently running sub-goal.
+     * The log describes an action performed while working on the sub-goal.
+     */
+    appendSubGoalLog(log: string): void;
+    /**
+     * Convert sub-goals to text representation.
+     * Includes actions performed (logs) for the current sub-goal.
+     */
+    subGoalsToText(): string;
+    /**
+     * Append a log entry to the historical logs list.
+     * Used in non-deepThink mode to track executed steps across planning rounds.
+     */
+    appendHistoricalLog(log: string): void;
+    /**
+     * Convert historical logs to text representation.
+     * Provides context about previously executed steps to the model.
+     */
+    historicalLogsToText(): string;
+    /**
+     * Append a memory to the memories list
+     */
+    appendMemory(memory: string): void;
+    /**
+     * Get all memories
+     */
+    getMemories(): string[];
+    /**
+     * Convert memories to text representation
+     */
+    memoriesToText(): string;
+    /**
+     * Clear all memories
+     */
+    clearMemories(): void;
+    /**
+     * Compress the conversation history if it exceeds the threshold.
+     * Removes the oldest messages and replaces them with a single placeholder message.
+     * @param threshold - The number of messages that triggers compression.
+     * @param keepCount - The number of recent messages to keep after compression.
+     * @returns true if compression was performed, false otherwise.
+     */
+    compressHistory(threshold: number, keepCount: number): boolean;
+}

package/dist/types/ai-model/index.d.ts

@@ -0,0 +1,16 @@
+export { AIResponseParseError, callAIWithStringResponse, callAIWithObjectResponse, callAI, } from './service-caller/index';
+export { runConnectivityTest, type ConnectivityCheckResultItem, type ConnectivityTestConfig, type ConnectivityTestResult, } from './connectivity';
+export { systemPromptToLocateElement } from './prompt/llm-locator';
+export { generatePlaywrightTest, generatePlaywrightTestStream, } from './prompt/playwright-generator';
+export { generateYamlTest, generateYamlTestStream, } from './prompt/yaml-generator';
+export type { YamlGenerationOptions } from './prompt/yaml-generator';
+export type { ChatCompletionMessageParam } from 'openai/resources/index';
+export { AiLocateElement, AiExtractElementInfo, AiLocateSection, AiJudgeOrderSensitive, } from './inspect';
+export { plan } from './llm-planning';
+export { autoGLMPlanning } from './auto-glm/planning';
+export { adaptBboxToRect } from '../common';
+export { uiTarsPlanning } from './ui-tars-planning';
+export { ConversationHistory, type ConversationHistoryOptions, } from './conversation-history';
+export type { SubGoal, SubGoalStatus } from '../types';
+export type { AIArgs } from '../common';
+export { getMidsceneLocationSchema, PointSchema, SizeSchema, RectSchema, TMultimodalPromptSchema, TUserPromptSchema, type TMultimodalPrompt, type TUserPrompt, findAllMidsceneLocatorField, dumpActionParam, parseActionParam, } from '../common';

package/dist/types/ai-model/inspect.d.ts

@@ -0,0 +1,67 @@
+import type { AIDataExtractionResponse, AIUsageInfo, Rect, ServiceExtractOption, UIContext } from '../types';
+import type { IModelConfig } from '@godscene/shared/env';
+import type { LocateResultElement } from '@godscene/shared/types';
+import type { ChatCompletionSystemMessageParam, ChatCompletionUserMessageParam } from 'openai/resources/index';
+import type { TMultimodalPrompt, TUserPrompt } from '../common';
+import { callAIWithObjectResponse } from './service-caller/index';
+export type AIArgs = [
+    ChatCompletionSystemMessageParam,
+    ...ChatCompletionUserMessageParam[]
+];
+export declare function buildSearchAreaConfig(options: {
+    context: UIContext;
+    baseRect: Rect;
+    modelFamily: IModelConfig['modelFamily'];
+}): Promise<{
+    rect: Rect;
+    imageBase64: string;
+    scale: number;
+}>;
+export declare function AiLocateElement(options: {
+    context: UIContext;
+    targetElementDescription: TUserPrompt;
+    searchConfig?: Awaited<ReturnType<typeof AiLocateSection>>;
+    modelConfig: IModelConfig;
+    abortSignal?: AbortSignal;
+}): Promise<{
+    parseResult: {
+        elements: LocateResultElement[];
+        errors?: string[];
+    };
+    rect?: Rect;
+    rawResponse: string;
+    usage?: AIUsageInfo;
+    reasoning_content?: string;
+}>;
+export declare function AiLocateSection(options: {
+    context: UIContext;
+    sectionDescription: TUserPrompt;
+    modelConfig: IModelConfig;
+    abortSignal?: AbortSignal;
+}): Promise<{
+    rect?: Rect;
+    imageBase64?: string;
+    scale?: number;
+    error?: string;
+    rawResponse: string;
+    usage?: AIUsageInfo;
+}>;
+export declare function AiExtractElementInfo<T>(options: {
+    dataQuery: string | Record<string, string>;
+    multimodalPrompt?: TMultimodalPrompt;
+    context: UIContext;
+    pageDescription?: string;
+    extractOption?: ServiceExtractOption;
+    modelConfig: IModelConfig;
+}): Promise<{
+    parseResult: AIDataExtractionResponse<T>;
+    rawResponse: string;
+    usage: AIUsageInfo | undefined;
+    reasoning_content: string | undefined;
+}>;
+export declare function AiJudgeOrderSensitive(description: string, callAIFn: typeof callAIWithObjectResponse<{
+    isOrderSensitive: boolean;
+}>, modelConfig: IModelConfig): Promise<{
+    isOrderSensitive: boolean;
+    usage?: AIUsageInfo;
+}>;

package/dist/types/ai-model/llm-planning.d.ts

@@ -0,0 +1,19 @@
+import type { DeepThinkOption, DeviceAction, InterfaceType, PlanningAIResponse, RawResponsePlanningAIResponse, UIContext } from '../types';
+import type { IModelConfig, TModelFamily } from '@godscene/shared/env';
+import type { ConversationHistory } from './conversation-history';
+/**
+ * Parse XML response from LLM and convert to RawResponsePlanningAIResponse
+ */
+export declare function parseXMLPlanningResponse(xmlString: string, modelFamily: TModelFamily | undefined): RawResponsePlanningAIResponse;
+export declare function plan(userInstruction: string, opts: {
+    context: UIContext;
+    interfaceType: InterfaceType;
+    actionSpace: DeviceAction<any>[];
+    actionContext?: string;
+    modelConfig: IModelConfig;
+    conversationHistory: ConversationHistory;
+    includeBbox: boolean;
+    imagesIncludeCount?: number;
+    deepThink?: DeepThinkOption;
+    abortSignal?: AbortSignal;
+}): Promise<PlanningAIResponse>;

package/dist/types/ai-model/prompt/common.d.ts

@@ -0,0 +1,2 @@
+import type { TModelFamily } from '@godscene/shared/env';
+export declare function bboxDescription(modelFamily: TModelFamily | undefined): "box_2d bounding box for the target element, should be [ymin, xmin, ymax, xmax] normalized to 0-1000." | "2d bounding box as [xmin, ymin, xmax, ymax]";

package/dist/types/ai-model/prompt/describe.d.ts

@@ -0,0 +1 @@
+export declare const elementDescriberInstruction: () => string;

package/dist/types/ai-model/prompt/extraction.d.ts

@@ -0,0 +1,7 @@
+import type { AIDataExtractionResponse } from '../../types';
+/**
+ * Parse XML response from LLM and convert to AIDataExtractionResponse
+ */
+export declare function parseXMLExtractionResponse<T>(xmlString: string): AIDataExtractionResponse<T>;
+export declare function systemPromptToExtract(): string;
+export declare const extractDataQueryPrompt: (pageDescription: string, dataQuery: string | Record<string, string>) => string;

package/dist/types/ai-model/prompt/llm-locator.d.ts

@@ -0,0 +1,3 @@
+import type { TModelFamily } from '@godscene/shared/env';
+export declare function systemPromptToLocateElement(modelFamily: TModelFamily | undefined): string;
+export declare const findElementPrompt: (targetElementDescription: string) => string;

package/dist/types/ai-model/prompt/llm-planning.d.ts

@@ -0,0 +1,10 @@
+import type { DeviceAction } from '../../types';
+import type { TModelFamily } from '@godscene/shared/env';
+export declare const descriptionForAction: (action: DeviceAction<any>, locatorSchemaTypeDescription: string, includeBbox?: boolean) => string;
+export declare function systemPromptToTaskPlanning({ actionSpace, modelFamily, includeBbox, includeThought, includeSubGoals, }: {
+    actionSpace: DeviceAction<any>[];
+    modelFamily: TModelFamily | undefined;
+    includeBbox: boolean;
+    includeThought?: boolean;
+    includeSubGoals?: boolean;
+}): Promise<string>;

package/dist/types/ai-model/prompt/llm-section-locator.d.ts

@@ -0,0 +1,3 @@
+import type { TModelFamily } from '@godscene/shared/env';
+export declare function systemPromptToLocateSection(modelFamily: TModelFamily | undefined): string;
+export declare const sectionLocatorInstruction: (sectionDescription: string) => string;

package/dist/types/ai-model/prompt/order-sensitive-judge.d.ts

@@ -0,0 +1,2 @@
+export declare function systemPromptToJudgeOrderSensitive(): string;
+export declare const orderSensitiveJudgePrompt: (description: string) => string;

package/dist/types/ai-model/prompt/playwright-generator.d.ts

@@ -0,0 +1,26 @@
+import type { StreamingAIResponse, StreamingCodeGenerationOptions } from '../../types';
+import type { IModelConfig } from '@godscene/shared/env';
+import { type ChromeRecordedEvent, type EventCounts, type EventSummary, type InputDescription, type ProcessedEvent, createEventCounts, createMessageContent, extractInputDescriptions, filterEventsByType, getScreenshotsForLLM, prepareEventSummary, processEventsForLLM, validateEvents } from './yaml-generator';
+export interface PlaywrightGenerationOptions {
+    testName?: string;
+    includeScreenshots?: boolean;
+    includeTimestamps?: boolean;
+    maxScreenshots?: number;
+    description?: string;
+    viewportSize?: {
+        width: number;
+        height: number;
+    };
+    waitForNetworkIdle?: boolean;
+    waitForNetworkIdleTimeout?: number;
+}
+export type { ChromeRecordedEvent, EventCounts, InputDescription, ProcessedEvent, EventSummary, };
+export { getScreenshotsForLLM, filterEventsByType, createEventCounts, extractInputDescriptions, processEventsForLLM, prepareEventSummary, createMessageContent, validateEvents, };
+/**
+ * Generates Playwright test code from recorded events
+ */
+export declare const generatePlaywrightTest: (events: ChromeRecordedEvent[], options: PlaywrightGenerationOptions, modelConfig: IModelConfig) => Promise<string>;
+/**
+ * Generates Playwright test code from recorded events with streaming support
+ */
+export declare const generatePlaywrightTestStream: (events: ChromeRecordedEvent[], options: PlaywrightGenerationOptions & StreamingCodeGenerationOptions, modelConfig: IModelConfig) => Promise<StreamingAIResponse>;

package/dist/types/ai-model/prompt/ui-tars-planning.d.ts

@@ -0,0 +1,2 @@
+export declare function getUiTarsPlanningPrompt(): string;
+export declare const getSummary: (prediction: string) => string;

package/dist/types/ai-model/prompt/util.d.ts

@@ -0,0 +1,33 @@
+import type { SubGoal } from '../../types';
+/**
+ * Extract content from an XML tag in a string, searching from the end.
+ * This approach handles cases where models prepend thinking content (like <think>...</think>)
+ * before the actual response tags, or when there are incomplete/nested tags.
+ *
+ * Strategy: Find the LAST closing tag, then search backwards for the nearest opening tag.
+ * This ensures we get the last complete tag pair, even if there are incomplete tags before it.
+ *
+ * @param xmlString - The XML string to parse
+ * @param tagName - The name of the tag to extract (case-insensitive)
+ * @returns The trimmed content of the tag, or undefined if not found
+ */
+export declare function extractXMLTag(xmlString: string, tagName: string): string | undefined;
+/**
+ * Parse sub-goals from XML content
+ * Handles both formats:
+ * - <sub-goal index="1" status="pending">description</sub-goal>
+ * - <sub-goal index="1" status="finished" />
+ */
+export declare function parseSubGoalsFromXML(xmlContent: string): SubGoal[];
+/**
+ * Extract indexes of sub-goals marked as finished from <mark-sub-goal-done> content
+ */
+export declare function parseMarkFinishedIndexes(xmlContent: string): number[];
+export declare const distanceThreshold = 16;
+export declare function distance(point1: {
+    x: number;
+    y: number;
+}, point2: {
+    x: number;
+    y: number;
+}): number;

package/dist/types/ai-model/prompt/yaml-generator.d.ts

@@ -0,0 +1,102 @@
+import type { StreamingAIResponse, StreamingCodeGenerationOptions } from '../../types';
+import type { IModelConfig } from '@godscene/shared/env';
+export interface EventCounts {
+    navigation: number;
+    click: number;
+    input: number;
+    scroll: number;
+    total: number;
+}
+export interface InputDescription {
+    description: string;
+    value: string;
+}
+export interface ProcessedEvent {
+    type: string;
+    timestamp: number;
+    url?: string;
+    title?: string;
+    elementDescription?: string;
+    value?: string;
+    pageInfo?: any;
+    elementRect?: any;
+}
+export interface EventSummary {
+    testName: string;
+    startUrl: string;
+    eventCounts: EventCounts;
+    urls: string[];
+    clickDescriptions: string[];
+    inputDescriptions: InputDescription[];
+    events: ProcessedEvent[];
+}
+export interface ChromeRecordedEvent {
+    type: string;
+    timestamp: number;
+    url?: string;
+    title?: string;
+    elementDescription?: string;
+    value?: string;
+    pageInfo?: any;
+    elementRect?: any;
+    screenshotBefore?: string;
+    screenshotAfter?: string;
+    screenshotWithBox?: string;
+}
+export interface YamlGenerationOptions {
+    testName?: string;
+    includeTimestamps?: boolean;
+    maxScreenshots?: number;
+    description?: string;
+    /** Language for human-readable YAML content (e.g. 'English', 'Chinese'). Keys and API names are kept as-is. */
+    language?: string;
+}
+export interface FilteredEvents {
+    navigationEvents: ChromeRecordedEvent[];
+    clickEvents: ChromeRecordedEvent[];
+    inputEvents: ChromeRecordedEvent[];
+    scrollEvents: ChromeRecordedEvent[];
+}
+/**
+ * Get screenshots from events for LLM context
+ */
+export declare const getScreenshotsForLLM: (events: ChromeRecordedEvent[], maxScreenshots?: number) => string[];
+/**
+ * Filter events by type for easier processing
+ */
+export declare const filterEventsByType: (events: ChromeRecordedEvent[]) => FilteredEvents;
+/**
+ * Create event counts summary
+ */
+export declare const createEventCounts: (filteredEvents: FilteredEvents, totalEvents: number) => EventCounts;
+/**
+ * Extract input descriptions from input events
+ */
+export declare const extractInputDescriptions: (inputEvents: ChromeRecordedEvent[]) => InputDescription[];
+/**
+ * Process events for LLM consumption
+ */
+export declare const processEventsForLLM: (events: ChromeRecordedEvent[]) => ProcessedEvent[];
+/**
+ * Prepare comprehensive event summary for LLM
+ */
+export declare const prepareEventSummary: (events: ChromeRecordedEvent[], options?: {
+    testName?: string;
+    maxScreenshots?: number;
+}) => EventSummary;
+/**
+ * Create message content for LLM with optional screenshots
+ */
+export declare const createMessageContent: (promptText: string, screenshots?: string[], includeScreenshots?: boolean) => any[];
+/**
+ * Validate events before processing
+ */
+export declare const validateEvents: (events: ChromeRecordedEvent[]) => void;
+/**
+ * Generates YAML test configuration from recorded events using AI
+ */
+export declare const generateYamlTest: (events: ChromeRecordedEvent[], options: YamlGenerationOptions, modelConfig: IModelConfig) => Promise<string>;
+/**
+ * Generates YAML test configuration from recorded events using AI with streaming support
+ */
+export declare const generateYamlTestStream: (events: ChromeRecordedEvent[], options: YamlGenerationOptions & StreamingCodeGenerationOptions, modelConfig: IModelConfig) => Promise<StreamingAIResponse>;

package/dist/types/ai-model/service-caller/codex-app-server.d.ts

@@ -0,0 +1,42 @@
+import type { AIUsageInfo, DeepThinkOption, StreamingCallback } from '../../types';
+import type { IModelConfig } from '@godscene/shared/env';
+import type { ChatCompletionMessageParam } from 'openai/resources/index';
+type CodexReasoningEffort = 'low' | 'medium' | 'high' | 'xhigh';
+type CodexTextInput = {
+    type: 'text';
+    text: string;
+    text_elements: any[];
+};
+type CodexImageInput = {
+    type: 'image';
+    url: string;
+};
+type CodexLocalImageInput = {
+    type: 'localImage';
+    path: string;
+};
+type CodexTurnInput = CodexTextInput | CodexImageInput | CodexLocalImageInput;
+type CodexTurnResult = {
+    content: string;
+    reasoning_content?: string;
+    usage?: AIUsageInfo;
+    isStreamed: boolean;
+};
+export declare const isCodexAppServerProvider: (baseURL?: string) => boolean;
+export declare const normalizeCodexLocalImagePath: (imageUrl: string, platform?: NodeJS.Platform) => string;
+export declare const resolveCodexReasoningEffort: ({ deepThink, modelConfig, }: {
+    deepThink?: DeepThinkOption;
+    modelConfig: IModelConfig;
+}) => CodexReasoningEffort | undefined;
+export declare const buildCodexTurnPayloadFromMessages: (messages: ChatCompletionMessageParam[]) => {
+    developerInstructions?: string;
+    input: CodexTurnInput[];
+};
+export declare function callAIWithCodexAppServer(messages: ChatCompletionMessageParam[], modelConfig: IModelConfig, options?: {
+    stream?: boolean;
+    onChunk?: StreamingCallback;
+    deepThink?: DeepThinkOption;
+    abortSignal?: AbortSignal;
+}): Promise<CodexTurnResult>;
+export declare function __shutdownCodexAppServerForTests(): Promise<void>;
+export {};

package/dist/types/ai-model/service-caller/image-detail.d.ts

@@ -0,0 +1,2 @@
+import type { IModelConfig } from '@godscene/shared/env';
+export declare function shouldForceOriginalImageDetail(modelConfig: Pick<IModelConfig, 'intent' | 'modelFamily'>): boolean;

package/dist/types/ai-model/service-caller/index.d.ts

@@ -0,0 +1,60 @@
+import type { AIUsageInfo, DeepThinkOption } from '../../types';
+import type { StreamingCallback } from '../../types';
+export declare class AIResponseParseError extends Error {
+    usage?: AIUsageInfo;
+    rawResponse: string;
+    constructor(message: string, rawResponse: string, usage?: AIUsageInfo);
+}
+import { type IModelConfig, type TModelFamily } from '@godscene/shared/env';
+import type { ChatCompletionMessageParam } from 'openai/resources/index';
+import type { AIArgs } from '../../common';
+export declare function yhtCallAI(messages: ChatCompletionMessageParam[], modelConfig: IModelConfig, options?: {
+    stream?: boolean;
+    onChunk?: StreamingCallback;
+    deepThink?: DeepThinkOption;
+    abortSignal?: AbortSignal;
+}): Promise<{
+    content: string;
+    reasoning_content?: string;
+    usage?: AIUsageInfo;
+    isStreamed: boolean;
+}>;
+export declare function callAI(messages: ChatCompletionMessageParam[], modelConfig: IModelConfig, options?: {
+    stream?: boolean;
+    onChunk?: StreamingCallback;
+    deepThink?: DeepThinkOption;
+    abortSignal?: AbortSignal;
+}): Promise<{
+    content: string;
+    reasoning_content?: string;
+    usage?: AIUsageInfo;
+    isStreamed: boolean;
+}>;
+export declare function callAIWithObjectResponse<T>(messages: ChatCompletionMessageParam[], modelConfig: IModelConfig, options?: {
+    deepThink?: DeepThinkOption;
+    abortSignal?: AbortSignal;
+}): Promise<{
+    content: T;
+    contentString: string;
+    usage?: AIUsageInfo;
+    reasoning_content?: string;
+}>;
+export declare function callAIWithStringResponse(msgs: AIArgs, modelConfig: IModelConfig, options?: {
+    abortSignal?: AbortSignal;
+}): Promise<{
+    content: string;
+    usage?: AIUsageInfo;
+}>;
+export declare function extractJSONFromCodeBlock(response: string): string;
+export declare function preprocessDoubaoBboxJson(input: string): string;
+export declare function resolveReasoningConfig({ reasoningEnabled, reasoningEffort, reasoningBudget, modelFamily, }: {
+    reasoningEnabled?: boolean;
+    reasoningEffort?: string;
+    reasoningBudget?: number;
+    modelFamily?: TModelFamily;
+}): {
+    config: Record<string, unknown>;
+    debugMessage?: string;
+    warningMessage?: string;
+};
+export declare function safeParseJson(input: string, modelFamily: TModelFamily | undefined): any;

package/dist/types/ai-model/service-caller/request-timeout.d.ts

@@ -0,0 +1,32 @@
+import type { IModelConfig } from '@godscene/shared/env';
+/**
+ * Default hard timeout (ms) applied to every AI HTTP call.
+ *
+ * We need an end-to-end timeout for the whole request lifecycle, not just the
+ * time until response headers arrive. Some providers can return headers
+ * quickly and then stall while the body is still being read.
+ *
+ * Override per intent via `MIDSCENE_MODEL_TIMEOUT`,
+ * `MIDSCENE_INSIGHT_MODEL_TIMEOUT`, or `MIDSCENE_PLANNING_MODEL_TIMEOUT`.
+ * Set the env var (or `modelConfig.timeout`) to `0` to disable the hard
+ * timeout entirely; only a caller-provided `abortSignal` will cancel the
+ * request in that case.
+ */
+export declare const DEFAULT_AI_CALL_TIMEOUT_MS = 180000;
+/** Identifying code set on the AbortError raised by our hard timeout. */
+export declare const AI_CALL_HARD_TIMEOUT_CODE = "AI_CALL_HARD_TIMEOUT";
+/**
+ * Resolve the hard request timeout for an AI call.
+ * Returns `null` when the user explicitly opted out (`timeout === 0`).
+ */
+export declare function resolveEffectiveTimeoutMs(modelConfig: Pick<IModelConfig, 'timeout'>): number | null;
+/**
+ * True if the error was raised by our hard-timeout AbortSignal (vs any other
+ * abort/network/HTTP error). Used to drive observability without having to
+ * string-match the message.
+ */
+export declare function isHardTimeoutError(err: unknown): boolean;
+export declare function buildRequestAbortSignal(timeoutMs: number | null, userSignal?: AbortSignal): {
+    signal: AbortSignal;
+    cleanup: () => void;
+};

package/dist/types/ai-model/ui-tars-planning.d.ts

@@ -0,0 +1,72 @@
+import type { PlanningAIResponse, UIContext } from '../types';
+import { type IModelConfig } from '@godscene/shared/env';
+import type { ConversationHistory } from './conversation-history';
+type ActionType = 'click' | 'left_double' | 'right_single' | 'drag' | 'type' | 'hotkey' | 'finished' | 'scroll' | 'wait';
+export declare function uiTarsPlanning(userInstruction: string, options: {
+    conversationHistory: ConversationHistory;
+    context: UIContext;
+    modelConfig: IModelConfig;
+    actionContext?: string;
+    abortSignal?: AbortSignal;
+}): Promise<PlanningAIResponse>;
+interface BaseAction {
+    action_type: ActionType;
+    action_inputs: Record<string, any>;
+    reflection: string | null;
+    thought: string | null;
+}
+interface ClickAction extends BaseAction {
+    action_type: 'click';
+    action_inputs: {
+        start_box: string;
+    };
+}
+interface DragAction extends BaseAction {
+    action_type: 'drag';
+    action_inputs: {
+        start_box: string;
+        end_box: string;
+    };
+}
+interface WaitAction extends BaseAction {
+    action_type: 'wait';
+    action_inputs: {
+        time: string;
+    };
+}
+interface LeftDoubleAction extends BaseAction {
+    action_type: 'left_double';
+    action_inputs: {
+        start_box: string;
+    };
+}
+interface RightSingleAction extends BaseAction {
+    action_type: 'right_single';
+    action_inputs: {
+        start_box: string;
+    };
+}
+interface TypeAction extends BaseAction {
+    action_type: 'type';
+    action_inputs: {
+        content: string;
+    };
+}
+interface HotkeyAction extends BaseAction {
+    action_type: 'hotkey';
+    action_inputs: {
+        key: string;
+    };
+}
+interface ScrollAction extends BaseAction {
+    action_type: 'scroll';
+    action_inputs: {
+        direction: 'up' | 'down';
+    };
+}
+interface FinishedAction extends BaseAction {
+    action_type: 'finished';
+    action_inputs: Record<string, never>;
+}
+export type Action = ClickAction | LeftDoubleAction | RightSingleAction | DragAction | TypeAction | HotkeyAction | ScrollAction | FinishedAction | WaitAction;
+export {};