catui-agent 1.0.0-beta.0

package/dist/core/lib/agent-core/src/types.d.ts

@@ -0,0 +1,417 @@
+/**
+ * [WHO]: AgentLoopFramework, AgentLoopTransition, AgentRunResult with transition history, AgentModelErrorRecoveryResult, AgentLoopConfig, CustomAgentMessages, AgentState, AgentToolResult, AgentTool, AgentToolConcurrencySafety, AgentToolInterruptBehavior
+ * [FROM]: No external dependencies
+ * [TO]: Consumed by core/lib/agent-core/src/index.ts
+ * [HERE]: core/lib/agent-core/src/types.ts -
+ */
+import type { AssistantMessageEvent, DocumentContent, ImageContent, Message, Model, SimpleStreamOptions, TextContent, Tool, ToolResultMessage, Usage } from "@catui/ai/types";
+import type { streamSimple } from "@catui/ai/stream";
+import type { Static, TSchema } from "@catui/ai/schema";
+/** Stream function - can return sync or Promise for async config lookup */
+export type StreamFn = (...args: Parameters<typeof streamSimple>) => ReturnType<typeof streamSimple> | Promise<ReturnType<typeof streamSimple>>;
+export type AgentLoopFramework = "standard" | "weak-model-compatible";
+export type AgentLoopFrameworkInput = AgentLoopFramework | "high-intelligence" | "low-intelligence" | "structured-adaptive";
+export type AgentLoopTransition = {
+    reason: "start";
+} | {
+    reason: "tool_result";
+    toolCallCount: number;
+} | {
+    reason: "follow_up";
+} | {
+    reason: "max_turns_reached";
+    maxTurns: number;
+    turnCount: number;
+} | {
+    reason: "tool_call_limit_reached";
+    maxToolCalls: number;
+    requestedToolCalls: number;
+    toolCallCount: number;
+} | {
+    reason: "stop_hook_limit_reached";
+    maxContinuations: number;
+    continuationCount: number;
+} | {
+    reason: "max_output_tokens_recovery";
+    attempt: number;
+} | {
+    reason: "stop_hook_blocking";
+    continuationCount: number;
+} | {
+    reason: "model_error_recovery";
+    subtype: string;
+    attempt: number;
+} | {
+    reason: "token_budget_continuation";
+    continuationCount: number;
+    outputTokens: number;
+    targetTokens: number;
+};
+export interface AgentRunResult {
+    stopReason: string;
+    loopFramework?: AgentLoopFramework;
+    loopPolicy?: AgentRunPolicy;
+    turnCount: number;
+    toolCallCount: number;
+    durationMs: number;
+    usage?: Usage;
+    permissionDenialCount?: number;
+    permissionDenials?: AgentToolPermissionDenial[];
+    transitions?: AgentLoopTransition[];
+    lastTransition?: AgentLoopTransition;
+    errorMessage?: string;
+    errorSubtype?: string;
+}
+export interface AgentRunPolicy {
+    maxModelErrorRecoveryAttempts?: number;
+    maxOutputTokenRecoveryAttempts?: number;
+    outputTokenBudget?: {
+        targetTokens: number;
+        thresholdPct?: number;
+        maxContinuations?: number;
+    };
+    maxStopHookContinuations?: number;
+    maxToolConcurrency?: number;
+    maxToolResultBatchSizeChars?: number;
+    maxTurnsPerPrompt?: number;
+    maxToolCallsPerPrompt?: number;
+}
+export declare function normalizeAgentLoopFramework(value: AgentLoopFrameworkInput | undefined): AgentLoopFramework | undefined;
+export type AgentToolPermissionDecision = {
+    decision: "allow";
+} | {
+    decision: "deny";
+    reason?: string;
+};
+export interface AgentToolPermissionDenial {
+    toolCallId: string;
+    toolName: string;
+    reason?: string;
+}
+export type AgentModelErrorRecoveryResult = {
+    action: "stop";
+} | {
+    action: "retry";
+    messages: AgentMessage[];
+    transition?: AgentLoopTransition;
+};
+/**
+ * Configuration for the agent loop.
+ */
+export interface AgentLoopConfig extends SimpleStreamOptions {
+    model: Model<any>;
+    loopFramework?: AgentLoopFrameworkInput;
+    /**
+     * Converts AgentMessage[] to LLM-compatible Message[] before each LLM call.
+     *
+     * Each AgentMessage must be converted to a UserMessage, AssistantMessage, or ToolResultMessage
+     * that the LLM can understand. AgentMessages that cannot be converted (e.g., UI-only notifications,
+     * status messages) should be filtered out.
+     *
+     * @example
+     * ```typescript
+     * convertToLlm: (messages) => messages.flatMap(m => {
+     *   if (m.role === "custom") {
+     *     // Convert custom message to user message
+     *     return [{ role: "user", content: m.content, timestamp: m.timestamp }];
+     *   }
+     *   if (m.role === "notification") {
+     *     // Filter out UI-only messages
+     *     return [];
+     *   }
+     *   // Pass through standard LLM messages
+     *   return [m];
+     * })
+     * ```
+     */
+    convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
+    /**
+     * Optional transform applied to the context before `convertToLlm`.
+     *
+     * Use this for operations that work at the AgentMessage level:
+     * - Context window management (pruning old messages)
+     * - Injecting context from external sources
+     *
+     * @example
+     * ```typescript
+     * transformContext: async (messages) => {
+     *   if (estimateTokens(messages) > MAX_TOKENS) {
+     *     return pruneOldMessages(messages);
+     *   }
+     *   return messages;
+     * }
+     * ```
+     */
+    transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
+    /**
+     * Resolves an API key dynamically for each LLM call.
+     *
+     * Useful for short-lived OAuth tokens (e.g., GitHub Copilot) that may expire
+     * during long-running tool execution phases.
+     */
+    getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+    /**
+     * Returns steering messages to inject into the conversation mid-run.
+     *
+     * Called after each tool execution to check for user interruptions.
+     * If messages are returned, remaining tool calls are skipped and
+     * these messages are added to the context before the next LLM call.
+     *
+     * Use this for "steering" the agent while it's working.
+     */
+    getSteeringMessages?: () => Promise<AgentMessage[]>;
+    /**
+     * Returns follow-up messages to process after the agent would otherwise stop.
+     *
+     * Called when the agent has no more tool calls and no steering messages.
+     * If messages are returned, they're added to the context and the agent
+     * continues with another turn.
+     *
+     * Use this for follow-up messages that should wait until the agent finishes.
+     */
+    getFollowUpMessages?: () => Promise<AgentMessage[]>;
+    /**
+     * Optional tool permission gate for agent loop tool execution.
+     *
+     * Called after schema/custom validation and before the tool executes.
+     * Return "deny" to feed a permission-denied tool_result back to the model
+     * without crashing the loop.
+     */
+    canUseTool?: (event: {
+        toolCallId: string;
+        toolName: string;
+        requestedToolName: string;
+        input: unknown;
+        rawInput: unknown;
+        tool: AgentTool<any>;
+    }) => Promise<AgentToolPermissionDecision> | AgentToolPermissionDecision;
+    /**
+     * Optional in-loop model error recovery hook.
+     *
+     * Hosts can use this to recover from context overflow or transient provider
+     * errors before the loop reaches agent_end. Return retry with a replacement
+     * AgentMessage context to make the next model call use recovered state.
+     */
+    recoverModelError?: (event: {
+        message: AgentMessage;
+        messages: AgentMessage[];
+        errorSubtype: string;
+        attempt: number;
+    }) => Promise<AgentModelErrorRecoveryResult> | AgentModelErrorRecoveryResult;
+    /**
+     * Optional non-blocking summary for completed tool batches.
+     *
+     * The loop starts this after a tool batch finishes. If the summary is
+     * already settled at the start of a later turn, it is emitted as a normal
+     * AgentMessage and included in that model request. If it is still pending,
+     * the model request proceeds without waiting.
+     */
+    createToolUseSummary?: (event: {
+        assistantMessage: AgentMessage;
+        toolResults: ToolResultMessage[];
+        contextMessages: AgentMessage[];
+        messages: AgentMessage[];
+    }) => AgentMessage | undefined | Promise<AgentMessage | undefined>;
+    /**
+     * Maximum model-error recovery retries for one prompt. Defaults to 1.
+     */
+    maxModelErrorRecoveryAttempts?: number;
+    /**
+     * Maximum assistant turns allowed for one prompt/continue loop.
+     *
+     * Prevents runaway model/tool/follow-up cycles from consuming unbounded
+     * tokens when the model keeps asking for tools or queued messages keep the
+     * loop alive.
+     */
+    maxTurnsPerPrompt?: number;
+    /**
+     * Maximum tool calls allowed for one prompt/continue loop.
+     *
+     * The loop stops before executing a batch that would exceed this limit and
+     * emits a controlled assistant error message.
+     */
+    maxToolCallsPerPrompt?: number;
+    /**
+     * Maximum concurrency for one batch of concurrency-safe tool calls in the
+     * weak-model-compatible loop. Defaults to 10.
+     */
+    maxToolConcurrency?: number;
+    /**
+     * Maximum combined text characters from one assistant tool-use batch that
+     * may be fed into the next model request.
+     *
+     * This aggregate guard complements per-tool maxResultSizeChars: it prevents
+     * several individually valid read/search results from flooding the next
+     * context turn. Loops preserve tool_result order and trim the largest
+     * successful results first.
+     */
+    maxToolResultBatchSizeChars?: number;
+    /**
+     * Maximum automatic continuations after a model stops because it hit its
+     * output-token limit. Defaults to 1.
+     */
+    maxOutputTokenRecoveryAttempts?: number;
+    /**
+     * Optional output-token budget target for long-form agent turns.
+     *
+     * If the assistant stops naturally before cumulative output reaches
+     * thresholdPct * targetTokens, the loop injects a meta continuation prompt.
+     * This is distinct from max-output-token recovery: it handles
+     * under-complete answers, not hard length stops.
+     */
+    outputTokenBudget?: {
+        targetTokens: number;
+        thresholdPct?: number;
+        maxContinuations?: number;
+    };
+    /**
+     * Optional stop hook. Called when the assistant would stop without tool
+     * calls. Return action "continue" with messages to force a
+     * correction/validation turn; return "stop" to allow completion.
+     */
+    runStopHooks?: (event: {
+        message: AgentMessage;
+        messages: AgentMessage[];
+    }) => Promise<StructuredAdaptiveStopHookResult> | StructuredAdaptiveStopHookResult;
+    /**
+     * Maximum stop-hook continuation turns for one prompt. Defaults to 3.
+     */
+    maxStopHookContinuations?: number;
+}
+export type StructuredAdaptiveStopHookResult = {
+    action: "stop";
+} | {
+    action: "continue";
+    messages: AgentMessage[];
+    reason?: string;
+};
+/**
+ * Thinking/reasoning level for models that support it.
+ * Note: "xhigh" is only supported by OpenAI gpt-5.1-codex-max, gpt-5.2, gpt-5.2-codex, gpt-5.3, and gpt-5.3-codex models.
+ */
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+/**
+ * Extensible interface for custom app messages.
+ * Apps can extend via declaration merging:
+ *
+ * @example
+ * ```typescript
+ * declare module "@catui/agent-core" {
+ *   interface CustomAgentMessages {
+ *     artifact: ArtifactMessage;
+ *     notification: NotificationMessage;
+ *   }
+ * }
+ * ```
+ */
+export interface CustomAgentMessages {
+}
+/**
+ * AgentMessage: Union of LLM messages + custom messages.
+ * This abstraction allows apps to add custom message types while maintaining
+ * type safety and compatibility with the base LLM messages.
+ */
+export type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessages];
+/**
+ * Agent state containing all configuration and conversation data.
+ */
+export interface AgentState {
+    systemPrompt: string;
+    model: Model<any>;
+    thinkingLevel: ThinkingLevel;
+    tools: AgentTool<any>[];
+    messages: AgentMessage[];
+    isStreaming: boolean;
+    streamMessage: AgentMessage | null;
+    pendingToolCalls: Set<string>;
+    lastResult?: AgentRunResult;
+    error?: string;
+}
+export interface AgentToolResult<T> {
+    content: (TextContent | ImageContent | DocumentContent)[];
+    details: T;
+    /**
+     * Optional messages appended after the corresponding tool_result messages.
+     * Use this for tool-generated attachments or context updates that should not
+     * interrupt assistant tool_use -> tool_result pairing.
+     */
+    contextMessages?: AgentMessage[];
+}
+export type AgentToolUpdateCallback<T = any> = (partialResult: AgentToolResult<T>) => void;
+export type AgentToolConcurrencySafety<TParameters extends TSchema = TSchema> = boolean | ((params: Static<TParameters>) => boolean);
+export type AgentToolInterruptBehavior<TParameters extends TSchema = TSchema> = "cancel" | "block" | ((params: Static<TParameters>) => "cancel" | "block");
+export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any> extends Tool<TParameters> {
+    label: string;
+    /** Alternative model-facing names accepted for transcript/tool compatibility. */
+    aliases?: string[];
+    /**
+     * Whether the tool can safely run alongside other concurrency-safe tools.
+     * The weak-model-compatible loop uses this to batch read-only work while keeping
+     * stateful tools such as edit/write/bash serialized.
+     */
+    isConcurrencySafe?: AgentToolConcurrencySafety<TParameters>;
+    interruptBehavior?: AgentToolInterruptBehavior<TParameters>;
+    /** Optional semantic validation after schema validation and before execute. */
+    validateInput?: (params: Static<TParameters>) => void | string | Promise<void | string>;
+    /** Optional maximum text result size enforced by agent loop tool orchestration. */
+    maxResultSizeChars?: number;
+    execute: (toolCallId: string, params: Static<TParameters>, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<TDetails>) => Promise<AgentToolResult<TDetails>>;
+}
+export interface AgentContext {
+    systemPrompt: string;
+    messages: AgentMessage[];
+    tools?: AgentTool<any>[];
+}
+/**
+ * Events emitted by the Agent for UI updates.
+ * These events provide fine-grained lifecycle information for messages, turns, and tool executions.
+ */
+export type AgentEvent = {
+    type: "agent_start";
+} | {
+    type: "agent_end";
+    messages: AgentMessage[];
+} | ({
+    type: "agent_result";
+} & AgentRunResult) | {
+    type: "stream_request_start";
+    model: string;
+    provider: string;
+    api: string;
+    messageCount: number;
+    maxTokens?: number;
+} | {
+    type: "turn_start";
+} | {
+    type: "turn_end";
+    message: AgentMessage;
+    toolResults: ToolResultMessage[];
+} | {
+    type: "message_start";
+    message: AgentMessage;
+} | {
+    type: "message_update";
+    message: AgentMessage;
+    assistantMessageEvent: AssistantMessageEvent;
+} | {
+    type: "message_end";
+    message: AgentMessage;
+} | {
+    type: "tool_execution_start";
+    toolCallId: string;
+    toolName: string;
+    args: any;
+} | {
+    type: "tool_execution_update";
+    toolCallId: string;
+    toolName: string;
+    args: any;
+    partialResult: any;
+} | {
+    type: "tool_execution_end";
+    toolCallId: string;
+    toolName: string;
+    result: any;
+    isError: boolean;
+    durationMs?: number;
+};

package/dist/core/lib/agent-core/src/types.js

@@ -0,0 +1 @@
+var n=Object.defineProperty;var r=(e,t)=>n(e,"name",{value:t,configurable:!0});function o(e){return e==="high-intelligence"?"standard":e==="low-intelligence"||e==="structured-adaptive"?"weak-model-compatible":e}r(o,"normalizeAgentLoopFramework");export{o as normalizeAgentLoopFramework};

package/dist/core/lib/ai/src/api-registry.d.ts

@@ -0,0 +1,27 @@
+/**
+ * [WHO]: ApiProvider, registerApiProvider, registerApiProviderLoader, getApiProvider, ensureApiProvider, reset helpers
+ * [FROM]: Depends on core AI stream/model types for provider contracts
+ * [TO]: Consumed by core/lib/ai/src/stream.ts and providers/register-builtins.ts for provider dispatch
+ * [HERE]: core/lib/ai/src/api-registry.ts - provider registry plus runtime lazy-loader registry
+ */
+import type { Api, AssistantMessageEventStreamContract, Context, Model, SimpleStreamOptions, StreamFunction, StreamOptions } from "./types.js";
+export type ApiStreamFunction = (model: Model<Api>, context: Context, options?: StreamOptions) => AssistantMessageEventStreamContract;
+export type ApiStreamSimpleFunction = (model: Model<Api>, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStreamContract;
+export interface ApiProvider<TApi extends Api = Api, TOptions extends StreamOptions = StreamOptions> {
+    api: TApi;
+    stream: StreamFunction<TApi, TOptions>;
+    streamSimple: StreamFunction<TApi, SimpleStreamOptions>;
+}
+export interface ApiProviderInternal {
+    api: Api;
+    stream: ApiStreamFunction;
+    streamSimple: ApiStreamSimpleFunction;
+}
+export type ApiProviderLoader<TApi extends Api = Api, TOptions extends StreamOptions = StreamOptions> = () => Promise<ApiProvider<TApi, TOptions>>;
+export declare function registerApiProvider<TApi extends Api, TOptions extends StreamOptions>(provider: ApiProvider<TApi, TOptions>, sourceId?: string): void;
+export declare function registerApiProviderLoader<TApi extends Api, TOptions extends StreamOptions>(api: TApi, loader: ApiProviderLoader<TApi, TOptions>, sourceId?: string): void;
+export declare function getApiProvider(api: Api): ApiProviderInternal | undefined;
+export declare function ensureApiProvider(api: Api): Promise<ApiProviderInternal | undefined>;
+export declare function getApiProviders(): ApiProviderInternal[];
+export declare function unregisterApiProviders(sourceId: string): void;
+export declare function clearApiProviders(): void;

package/dist/core/lib/ai/src/api-registry.js

@@ -0,0 +1 @@
+var w=Object.defineProperty;var n=(r,e)=>w(r,"name",{value:e,configurable:!0});import{AssistantMessageEventStream as u}from"./utils/event-stream.js";const a=new Map,p=new Map;function y(r,e){return(t,o,i)=>{if(t.api!==r)throw new Error(`Mismatched api: ${t.api} expected ${r}`);return e(t,o,i)}}n(y,"wrapStream");function l(r,e){return(t,o,i)=>{if(t.api!==r)throw new Error(`Mismatched api: ${t.api} expected ${r}`);return e(t,o,i)}}n(l,"wrapStreamSimple");function h(){return{input:0,output:0,cacheRead:0,cacheWrite:0,totalTokens:0,cost:{input:0,output:0,cacheRead:0,cacheWrite:0,total:0}}}n(h,"emptyUsage");function P(r){return r instanceof Error?r.message:typeof r=="string"?r:JSON.stringify(r)??String(r)}n(P,"getErrorMessage");function f(r,e){return{role:"assistant",content:[],api:r.api,provider:r.provider,model:r.id,stopReason:"error",errorMessage:P(e),usage:h(),timestamp:Date.now()}}n(f,"createProviderLoadErrorMessage");function S(r){return f(r,new Error("Provider stream ended without a final assistant message"))}n(S,"createMissingProviderResultMessage");function A(r){return{api:r,stream:n((e,t,o)=>{const i=new u;return d(r,e,t,o,i,"stream"),i},"stream"),streamSimple:n((e,t,o)=>{const i=new u;return d(r,e,t,o,i,"streamSimple"),i},"streamSimple")}}n(A,"createLazyProvider");async function d(r,e,t,o,i,m){try{const s=await x(r);if(!s)throw new Error(`No API provider registered for api: ${r}`);const c=m==="stream"?s.stream(e,t,o):s.streamSimple(e,t,o);for await(const v of c)i.push(v);c.resultIfResolved()||i.push({type:"error",reason:"error",error:S(e)})}catch(s){i.push({type:"error",reason:"error",error:f(e,s)})}}n(d,"pipeLazyProviderStream");function M(r,e){a.set(r.api,{provider:{api:r.api,stream:y(r.api,r.stream),streamSimple:l(r.api,r.streamSimple)},sourceId:e})}n(M,"registerApiProvider");function L(r,e,t){p.set(r,{loader:e,sourceId:t}),a.set(r,{provider:A(r),sourceId:t,lazy:!0})}n(L,"registerApiProviderLoader");function g(r){return a.get(r)?.provider}n(g,"getApiProvider");async function x(r){const e=a.get(r);if(e&&!e.lazy)return e.provider;const t=p.get(r);return t?(t.pending??=t.loader().then(o=>(M(o,t.sourceId),g(r))).finally(()=>{t.pending=void 0}),await t.pending,g(r)):e?.provider}n(x,"ensureApiProvider");function $(){return Array.from(a.values(),r=>r.provider)}n($,"getApiProviders");function z(r){for(const[e,t]of a.entries())t.sourceId===r&&a.delete(e);for(const[e,t]of p.entries())t.sourceId===r&&p.delete(e)}n(z,"unregisterApiProviders");function I(){a.clear(),p.clear()}n(I,"clearApiProviders");export{I as clearApiProviders,x as ensureApiProvider,g as getApiProvider,$ as getApiProviders,M as registerApiProvider,L as registerApiProviderLoader,z as unregisterApiProviders};

package/dist/core/lib/ai/src/config-path.d.ts

@@ -0,0 +1 @@
+export declare function getDebugLogPath(): string;

package/dist/core/lib/ai/src/config-path.js

@@ -0,0 +1 @@
+var n=Object.defineProperty;var e=(t,o)=>n(t,"name",{value:o,configurable:!0});import{homedir as r}from"os";import{join as i}from"path";function s(){const t=process.env.CATUI_CODING_AGENT_DIR;if(t){const o=t==="~"?r():t.startsWith("~/")?r()+t.slice(1):t;return i(o,"catui-debug.log")}return i(r(),".catui","agent","catui-debug.log")}e(s,"getDebugLogPath");export{s as getDebugLogPath};

package/dist/core/lib/ai/src/debug-logger.d.ts

@@ -0,0 +1,94 @@
+export type DebugLogLevel = "error" | "warn" | "info" | "debug" | "trace";
+interface DebugLoggerOptions {
+    enabled?: boolean;
+    level?: DebugLogLevel;
+    maxFileSize?: number;
+}
+declare class DebugLogger {
+    private enabled;
+    private level;
+    private maxFileSize;
+    private logPath;
+    constructor(options?: DebugLoggerOptions);
+    /**
+     * Detect if debug logging is enabled from environment
+     */
+    private detectEnabled;
+    /**
+     * Detect log level from environment
+     */
+    private detectLevel;
+    /**
+     * Enable or disable logging at runtime
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Set log level at runtime
+     */
+    setLevel(level: DebugLogLevel): void;
+    /**
+     * Re-check environment variables (for when they change after initialization)
+     */
+    refreshFromEnv(): void;
+    /**
+     * Check if a specific level is enabled
+     */
+    private isLevelEnabled;
+    /**
+     * Write a log entry to file
+     */
+    private writeLog;
+    /**
+     * Rotate log file if it exceeds max size
+     */
+    private rotateIfNeeded;
+    error(category: string, message: string, data?: unknown): void;
+    warn(category: string, message: string, data?: unknown): void;
+    info(category: string, message: string, data?: unknown): void;
+    debug(category: string, message: string, data?: unknown): void;
+    trace(category: string, message: string, data?: unknown): void;
+    /**
+     * Log AI provider request
+     */
+    logProviderRequest(provider: string, model: string, request: unknown): void;
+    /**
+     * Log AI provider response chunk (for streaming)
+     */
+    logProviderChunk(provider: string, model: string, chunk: unknown): void;
+    /**
+     * Log AI provider response (non-streaming)
+     */
+    logProviderResponse(provider: string, model: string, response: unknown): void;
+    /**
+     * Log content parsing events
+     */
+    logContentParse(operation: string, input: unknown, output?: unknown): void;
+    /**
+     * Log TUI rendering events
+     */
+    logTUI(operation: string, details?: unknown): void;
+    /**
+     * Get the log file path
+     */
+    getLogPath(): string;
+    /**
+     * Clear the log file
+     */
+    clear(): void;
+}
+export declare function getDebugLogger(): DebugLogger;
+export declare function createDebugLogger(options: DebugLoggerOptions): DebugLogger;
+export declare const debug: {
+    error: (category: string, message: string, data?: unknown) => void;
+    warn: (category: string, message: string, data?: unknown) => void;
+    info: (category: string, message: string, data?: unknown) => void;
+    debug: (category: string, message: string, data?: unknown) => void;
+    trace: (category: string, message: string, data?: unknown) => void;
+    logProviderRequest: (provider: string, model: string, request: unknown) => void;
+    logProviderChunk: (provider: string, model: string, chunk: unknown) => void;
+    logProviderResponse: (provider: string, model: string, response: unknown) => void;
+    logContentParse: (operation: string, input: unknown, output?: unknown) => void;
+    getLogPath: () => string;
+    clear: () => void;
+};
+export {};

package/dist/core/lib/ai/src/debug-logger.js

@@ -0,0 +1,4 @@
+var f=Object.defineProperty;var o=(r,e)=>f(r,"name",{value:e,configurable:!0});import{appendFileSync as v,existsSync as b,mkdirSync as P}from"fs";import{dirname as L}from"path";import{getDebugLogPath as p}from"./config-path.js";const a={error:0,warn:1,info:2,debug:3,trace:4};class d{static{o(this,"DebugLogger")}enabled;level;maxFileSize;logPath;constructor(e={}){this.enabled=e.enabled??this.detectEnabled(),this.level=a[e.level??this.detectLevel()],this.maxFileSize=e.maxFileSize??10*1024*1024,this.logPath=p()}detectEnabled(){return process.env.CATUI_DEBUG==="1"||process.env.DEBUG?.includes("catui")||!1}detectLevel(){const e=process.env.CATUI_DEBUG_LEVEL;return e&&e in a?e:"info"}setEnabled(e){this.enabled=e}setLevel(e){this.level=a[e]}refreshFromEnv(){this.enabled=this.detectEnabled(),this.level=a[this.detectLevel()]}isLevelEnabled(e){return!this.enabled&&process.env.CATUI_DEBUG==="1"&&this.refreshFromEnv(),this.enabled&&a[e]<=this.level}writeLog(e,t,i,s){if(!this.isLevelEnabled(e))return;const l=new Date().toISOString(),u=e.toUpperCase().padStart(5);let g=`[${l}] [${u}] [${t}] ${i}`;if(s!==void 0)try{const h=typeof s=="string"?s:JSON.stringify(s,null,2);g+=`
+${h}`}catch{g+=`
+[Unable to serialize data]`}g+=`
+`;try{const h=L(this.logPath);b(h)||P(h,{recursive:!0}),this.rotateIfNeeded(),v(this.logPath,g)}catch{}}rotateIfNeeded(){try{const{statSync:e,renameSync:t,existsSync:i}=require("fs");if(i(this.logPath)&&e(this.logPath).size>this.maxFileSize){const l=`${this.logPath}.old`;i(l)&&require("fs").unlinkSync(l),t(this.logPath,l)}}catch{}}error(e,t,i){this.writeLog("error",e,t,i)}warn(e,t,i){this.writeLog("warn",e,t,i)}info(e,t,i){this.writeLog("info",e,t,i)}debug(e,t,i){this.writeLog("debug",e,t,i)}trace(e,t,i){this.writeLog("trace",e,t,i)}logProviderRequest(e,t,i){this.debug("AI",`Request to ${e}/${t}`,i)}logProviderChunk(e,t,i){this.trace("AI",`Chunk from ${e}/${t}`,i)}logProviderResponse(e,t,i){this.debug("AI",`Response from ${e}/${t}`,i)}logContentParse(e,t,i){this.trace("PARSE",e,{input:t,output:i})}logTUI(e,t){this.trace("TUI",e,t)}getLogPath(){return this.logPath}clear(){try{const{writeFileSync:e}=require("fs");e(this.logPath,"")}catch{}}}let c=null;function n(){return c||(c=new d),c}o(n,"getDebugLogger");function y(r){return new d(r)}o(y,"createDebugLogger");const $={error:o((r,e,t)=>n().error(r,e,t),"error"),warn:o((r,e,t)=>n().warn(r,e,t),"warn"),info:o((r,e,t)=>n().info(r,e,t),"info"),debug:o((r,e,t)=>n().debug(r,e,t),"debug"),trace:o((r,e,t)=>n().trace(r,e,t),"trace"),logProviderRequest:o((r,e,t)=>n().logProviderRequest(r,e,t),"logProviderRequest"),logProviderChunk:o((r,e,t)=>n().logProviderChunk(r,e,t),"logProviderChunk"),logProviderResponse:o((r,e,t)=>n().logProviderResponse(r,e,t),"logProviderResponse"),logContentParse:o((r,e,t)=>n().logContentParse(r,e,t),"logContentParse"),getLogPath:o(()=>n().getLogPath(),"getLogPath"),clear:o(()=>n().clear(),"clear")};export{y as createDebugLogger,$ as debug,n as getDebugLogger};

package/dist/core/lib/ai/src/env-api-keys.d.ts

@@ -0,0 +1,8 @@
+import type { KnownProvider } from "./types.js";
+/**
+ * Get API key for provider from known environment variables, e.g. OPENAI_API_KEY.
+ *
+ * Will not return API keys for providers that require OAuth tokens.
+ */
+export declare function getEnvApiKey(provider: KnownProvider): string | undefined;
+export declare function getEnvApiKey(provider: string): string | undefined;

package/dist/core/lib/ai/src/env-api-keys.js

@@ -0,0 +1 @@
+var I=Object.defineProperty;var o=(e,_)=>I(e,"name",{value:_,configurable:!0});let s=null,E=null,i=null;typeof process<"u"&&(process.versions?.node||process.versions?.bun)&&(import("node:fs").then(e=>{s=e.existsSync}),import("node:os").then(e=>{E=e.homedir}),import("node:path").then(e=>{i=e.join}));let n=null;function a(){if(n===null){if(!s||!E||!i)return typeof process<"u"&&(process.versions?.node||process.versions?.bun)||(n=!1),!1;const e=process.env.GOOGLE_APPLICATION_CREDENTIALS;e?n=s(e):n=s(i(E(),".config","gcloud","application_default_credentials.json"))}return n}o(a,"hasVertexAdcCredentials");function O(e){if(e==="github-copilot")return process.env.COPILOT_GITHUB_TOKEN||process.env.GH_TOKEN||process.env.GITHUB_TOKEN;if(e==="anthropic")return process.env.ANTHROPIC_OAUTH_TOKEN||process.env.ANTHROPIC_API_KEY;if(e==="google-vertex"){const t=a(),A=!!(process.env.GOOGLE_CLOUD_PROJECT||process.env.GCLOUD_PROJECT),c=!!process.env.GOOGLE_CLOUD_LOCATION;if(t&&A&&c)return"<authenticated>"}if(e==="amazon-bedrock"&&(process.env.AWS_PROFILE||process.env.AWS_ACCESS_KEY_ID&&process.env.AWS_SECRET_ACCESS_KEY||process.env.AWS_BEARER_TOKEN_BEDROCK||process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI||process.env.AWS_CONTAINER_CREDENTIALS_FULL_URI||process.env.AWS_WEB_IDENTITY_TOKEN_FILE))return"<authenticated>";const r={openai:"OPENAI_API_KEY","azure-openai-responses":"AZURE_OPENAI_API_KEY",google:"GEMINI_API_KEY",groq:"GROQ_API_KEY",cerebras:"CEREBRAS_API_KEY",xai:"XAI_API_KEY",openrouter:"OPENROUTER_API_KEY","vercel-ai-gateway":"AI_GATEWAY_API_KEY",zai:"ZAI_API_KEY",mistral:"MISTRAL_API_KEY",minimax:"MINIMAX_API_KEY","minimax-cn":"MINIMAX_CN_API_KEY",huggingface:"HF_TOKEN",opencode:"OPENCODE_API_KEY","opencode-go":"OPENCODE_API_KEY","kimi-coding":"KIMI_API_KEY","ali-token-plan-openai":"ALI_TOKEN_PLAN_API_KEY","ali-token-plan-anthropic":"ALI_TOKEN_PLAN_API_KEY"}[e];return r?process.env[r]:void 0}o(O,"getEnvApiKey");export{O as getEnvApiKey};

package/dist/core/lib/ai/src/env.d.ts

@@ -0,0 +1,7 @@
+/**
+ * [WHO]: getEnvApiKey
+ * [FROM]: Depends on env-api-keys for environment/provider API key lookup
+ * [TO]: Consumed by @catui/ai/env subpath consumers
+ * [HERE]: core/lib/ai/src/env.ts - additive env helper subpath entry for AI package
+ */
+export { getEnvApiKey } from "./env-api-keys.js";

package/dist/core/lib/ai/src/env.js

@@ -0,0 +1 @@
+import{getEnvApiKey as p}from"./env-api-keys.js";export{p as getEnvApiKey};

package/dist/core/lib/ai/src/events.d.ts

@@ -0,0 +1,8 @@
+/**
+ * [WHO]: EventStream, AssistantMessageEventStream, createAssistantMessageEventStream, AsyncEventStream
+ * [FROM]: Depends on AI event stream implementation and structural event stream types
+ * [TO]: Consumed by @catui/ai/events subpath consumers
+ * [HERE]: core/lib/ai/src/events.ts - additive events subpath entry for AI package
+ */
+export * from "./utils/event-stream.js";
+export type * from "./utils/event-stream-types.js";

package/dist/core/lib/ai/src/events.js

@@ -0,0 +1 @@
+export*from"./utils/event-stream.js";

package/dist/core/lib/ai/src/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * [WHO]: AI package barrel exports
+ * [FROM]: Depends on typebox, all providers
+ * [TO]: Consumed by core/lib/ai/src/index.ts
+ * [HERE]: core/lib/ai/src/index.ts - AI package entry point
+ */
+export type { Static, TSchema } from "@sinclair/typebox";
+export { Type } from "@sinclair/typebox";
+export * from "./api-registry.js";
+export * from "./env-api-keys.js";
+export * from "./models.js";
+export * from "./providers/anthropic.js";
+export * from "./providers/azure-openai-responses.js";
+export * from "./providers/google.js";
+export * from "./providers/google-gemini-cli.js";
+export * from "./providers/google-vertex.js";
+export * from "./providers/openai-completions.js";
+export * from "./providers/openai-responses.js";
+export * from "./providers/register-builtins.js";
+export * from "./stream.js";
+export * from "./types.js";
+export * from "./utils/event-stream.js";
+export * from "./utils/json-parse.js";
+export * from "./utils/oauth/index.js";
+export * from "./utils/overflow.js";
+export * from "./utils/typebox-helpers.js";
+export * from "./utils/validation.js";

package/dist/core/lib/ai/src/index.js

@@ -0,0 +1 @@
+import{Type as e}from"@sinclair/typebox";export*from"./api-registry.js";export*from"./env-api-keys.js";export*from"./models.js";export*from"./providers/anthropic.js";export*from"./providers/azure-openai-responses.js";export*from"./providers/google.js";export*from"./providers/google-gemini-cli.js";export*from"./providers/google-vertex.js";export*from"./providers/openai-completions.js";export*from"./providers/openai-responses.js";export*from"./providers/register-builtins.js";export*from"./stream.js";export*from"./types.js";export*from"./utils/event-stream.js";export*from"./utils/json-parse.js";export*from"./utils/oauth/index.js";export*from"./utils/overflow.js";export*from"./utils/typebox-helpers.js";export*from"./utils/validation.js";export{e as Type};

package/dist/core/lib/ai/src/json.d.ts

@@ -0,0 +1,7 @@
+/**
+ * [WHO]: parseStreamingJson
+ * [FROM]: Depends on streaming JSON parser utility
+ * [TO]: Consumed by @catui/ai/json subpath consumers
+ * [HERE]: core/lib/ai/src/json.ts - additive JSON helper subpath entry for AI package
+ */
+export * from "./utils/json-parse.js";

package/dist/core/lib/ai/src/json.js

@@ -0,0 +1 @@
+export*from"./utils/json-parse.js";