catui-agent 1.0.0-beta.0

package/dist/core/lib/ai/src/providers/openai-responses-shared.d.ts

@@ -0,0 +1,22 @@
+/**
+ * [WHO]: OpenAIResponsesStreamOptions, ConvertResponsesMessagesOptions, ConvertResponsesToolsOptions, convertResponsesMessages, convertResponsesTools
+ * [FROM]: Depends on ../models.js, ../utils/json-parse.js, ../utils/sanitize-unicode.js, ./transform-messages.js
+ * [TO]: Consumed by core/lib/ai/src/index.ts
+ * [HERE]: core/lib/ai/src/providers/openai-responses-shared.ts -
+ */
+import type { Tool as OpenAITool, ResponseCreateParamsStreaming, ResponseInput, ResponseStreamEvent } from "openai/resources/responses/responses.js";
+import type { Api, AssistantMessage, Context, Model, Tool, Usage } from "../types.js";
+import type { AssistantMessageEventStream } from "../utils/event-stream.js";
+export interface OpenAIResponsesStreamOptions {
+    serviceTier?: ResponseCreateParamsStreaming["service_tier"];
+    applyServiceTierPricing?: (usage: Usage, serviceTier: ResponseCreateParamsStreaming["service_tier"] | undefined) => void;
+}
+export interface ConvertResponsesMessagesOptions {
+    includeSystemPrompt?: boolean;
+}
+export interface ConvertResponsesToolsOptions {
+    strict?: boolean | null;
+}
+export declare function convertResponsesMessages<TApi extends Api>(model: Model<TApi>, context: Context, allowedToolCallProviders: ReadonlySet<string>, options?: ConvertResponsesMessagesOptions): ResponseInput;
+export declare function convertResponsesTools(tools: Tool[], options?: ConvertResponsesToolsOptions): OpenAITool[];
+export declare function processResponsesStream<TApi extends Api>(openaiStream: AsyncIterable<ResponseStreamEvent>, output: AssistantMessage, stream: AssistantMessageEventStream, model: Model<TApi>, options?: OpenAIResponsesStreamOptions): Promise<void>;

package/dist/core/lib/ai/src/providers/openai-responses-shared.js

@@ -0,0 +1,10 @@
+var I=Object.defineProperty;var g=(r,n)=>I(r,"name",{value:n,configurable:!0});import{calculateCost as S}from"../models.js";import{parseStreamingJson as h}from"../utils/json-parse.js";import{sanitizeSurrogates as y}from"../utils/sanitize-unicode.js";import{transformMessages as $}from"./transform-messages.js";function C(r){let n=3735928559,o=1103547991;for(let f=0;f<r.length;f++){const d=r.charCodeAt(f);n=Math.imul(n^d,2654435761),o=Math.imul(o^d,1597334677)}return n=Math.imul(n^n>>>16,2246822507)^Math.imul(o^o>>>13,3266489909),o=Math.imul(o^o>>>16,2246822507)^Math.imul(n^n>>>13,3266489909),(o>>>0).toString(36)+(n>>>0).toString(36)}g(C,"shortHash");function T(r,n,o,f){const d=[],a=g(t=>{if(!o.has(r.provider)||!t.includes("|"))return t;const[e,i]=t.split("|"),p=e.replace(/[^a-zA-Z0-9_-]/g,"_");let c=i.replace(/[^a-zA-Z0-9_-]/g,"_");c.startsWith("fc")||(c=`fc_${c}`);let l=p.length>64?p.slice(0,64):p,u=c.length>64?c.slice(0,64):c;return l=l.replace(/_+$/,""),u=u.replace(/_+$/,""),`${l}|${u}`},"normalizeToolCallId"),s=$(n.messages,r,a);if((f?.includeSystemPrompt??!0)&&n.systemPrompt){const t=r.reasoning?"developer":"system";d.push({role:t,content:y(n.systemPrompt)})}let m=0;for(const t of s){if(t.role==="user")if(typeof t.content=="string")d.push({role:"user",content:[{type:"input_text",text:y(t.content)}]});else{const e=t.content.map(p=>p.type==="text"?{type:"input_text",text:y(p.text)}:p.type==="document"?{type:"input_text",text:"[PDF document - content not available in OpenAI format]"}:{type:"input_image",detail:"auto",image_url:`data:${p.mimeType};base64,${p.data}`}),i=r.input.includes("image")?e:e.filter(p=>p.type!=="input_image");if(i.length===0)continue;d.push({role:"user",content:i})}else if(t.role==="assistant"){const e=[],i=t,p=i.model!==r.id&&i.provider===r.provider&&i.api===r.api;for(const c of t.content)if(c.type==="thinking"){if(c.thinkingSignature){const l=JSON.parse(c.thinkingSignature);e.push(l)}}else if(c.type==="text"){const l=c;let u=l.textSignature;u?u.length>64&&(u=`msg_${C(u)}`):u=`msg_${m}`,e.push({type:"message",role:"assistant",content:[{type:"output_text",text:y(l.text),annotations:[]}],status:"completed",id:u})}else if(c.type==="toolCall"){const l=c,[u,k]=l.id.split("|");let _=k;p&&_?.startsWith("fc_")&&(_=void 0),e.push({type:"function_call",id:_,call_id:u,name:l.name,arguments:JSON.stringify(l.arguments)})}if(e.length===0)continue;d.push(...e)}else if(t.role==="toolResult"){const e=t.content.filter(l=>l.type==="text").map(l=>l.text).join(`
+`),i=t.content.some(l=>l.type==="image"),p=e.length>0,[c]=t.toolCallId.split("|");if(d.push({type:"function_call_output",call_id:c,output:y(p?e:"(see attached image)")}),i&&r.input.includes("image")){const l=[];l.push({type:"input_text",text:"Attached image(s) from tool result:"});for(const u of t.content)u.type==="image"&&l.push({type:"input_image",detail:"auto",image_url:`data:${u.mimeType};base64,${u.data}`});d.push({role:"user",content:l})}}m++}return d}g(T,"convertResponsesMessages");function b(r,n){const o=n?.strict===void 0?!1:n.strict;return r.map(f=>({type:"function",name:f.name,description:f.description,parameters:f.parameters,strict:o}))}g(b,"convertResponsesTools");async function z(r,n,o,f,d){let a=null,s=null;const x=n.content,m=g(()=>x.length-1,"blockIndex");for await(const t of r)if(t.type==="response.output_item.added"){const e=t.item;e.type==="reasoning"?(a=e,s={type:"thinking",thinking:""},n.content.push(s),o.push({type:"thinking_start",contentIndex:m(),partial:n})):e.type==="message"?(a=e,s={type:"text",text:""},n.content.push(s),o.push({type:"text_start",contentIndex:m(),partial:n})):e.type==="function_call"&&(a=e,s={type:"toolCall",id:`${e.call_id}|${e.id}`,name:e.name,arguments:{},partialJson:e.arguments||""},n.content.push(s),o.push({type:"toolcall_start",contentIndex:m(),partial:n}))}else if(t.type==="response.reasoning_summary_part.added")a&&a.type==="reasoning"&&(a.summary=a.summary||[],a.summary.push(t.part));else if(t.type==="response.reasoning_summary_text.delta"){if(a?.type==="reasoning"&&s?.type==="thinking"){a.summary=a.summary||[];const e=a.summary[a.summary.length-1];e&&(s.thinking+=t.delta,e.text+=t.delta,o.push({type:"thinking_delta",contentIndex:m(),delta:t.delta,partial:n}))}}else if(t.type==="response.reasoning_summary_part.done"){if(a?.type==="reasoning"&&s?.type==="thinking"){a.summary=a.summary||[];const e=a.summary[a.summary.length-1];e&&(s.thinking+=`
+
+`,e.text+=`
+
+`,o.push({type:"thinking_delta",contentIndex:m(),delta:`
+
+`,partial:n}))}}else if(t.type==="response.content_part.added")a?.type==="message"&&(a.content=a.content||[],(t.part.type==="output_text"||t.part.type==="refusal")&&a.content.push(t.part));else if(t.type==="response.output_text.delta"){if(a?.type==="message"&&s?.type==="text"){if(!a.content||a.content.length===0)continue;const e=a.content[a.content.length-1];e?.type==="output_text"&&(s.text+=t.delta,e.text+=t.delta,o.push({type:"text_delta",contentIndex:m(),delta:t.delta,partial:n}))}}else if(t.type==="response.refusal.delta"){if(a?.type==="message"&&s?.type==="text"){if(!a.content||a.content.length===0)continue;const e=a.content[a.content.length-1];e?.type==="refusal"&&(s.text+=t.delta,e.refusal+=t.delta,o.push({type:"text_delta",contentIndex:m(),delta:t.delta,partial:n}))}}else if(t.type==="response.function_call_arguments.delta")a?.type==="function_call"&&s?.type==="toolCall"&&(s.partialJson+=t.delta,s.arguments=h(s.partialJson),o.push({type:"toolcall_delta",contentIndex:m(),delta:t.delta,partial:n}));else if(t.type==="response.function_call_arguments.done")a?.type==="function_call"&&s?.type==="toolCall"&&(s.partialJson=t.arguments,s.arguments=h(s.partialJson));else if(t.type==="response.output_item.done"){const e=t.item;if(e.type==="reasoning"&&s?.type==="thinking")s.thinking=e.summary?.map(i=>i.text).join(`
+
+`)||"",s.thinkingSignature=JSON.stringify(e),o.push({type:"thinking_end",contentIndex:m(),content:s.thinking,partial:n}),s=null;else if(e.type==="message"&&s?.type==="text")s.text=e.content.map(i=>i.type==="output_text"?i.text:i.refusal).join(""),s.textSignature=e.id,o.push({type:"text_end",contentIndex:m(),content:s.text,partial:n}),s=null;else if(e.type==="function_call"){const i=s?.type==="toolCall"&&s.partialJson?h(s.partialJson):h(e.arguments||"{}"),p={type:"toolCall",id:`${e.call_id}|${e.id}`,name:e.name,arguments:i};s=null,o.push({type:"toolcall_end",contentIndex:m(),toolCall:p,partial:n})}}else if(t.type==="response.completed"){const e=t.response;if(e?.usage){const i=e.usage.input_tokens_details?.cached_tokens||0;n.usage={input:(e.usage.input_tokens||0)-i,output:e.usage.output_tokens||0,cacheRead:i,cacheWrite:0,totalTokens:e.usage.total_tokens||0,cost:{input:0,output:0,cacheRead:0,cacheWrite:0,total:0}}}if(S(f,n.usage),d?.applyServiceTierPricing){const i=e?.service_tier??d.serviceTier;d.applyServiceTierPricing(n.usage,i)}n.stopReason=v(e?.status),n.content.some(i=>i.type==="toolCall")&&n.stopReason==="stop"&&(n.stopReason="toolUse")}else{if(t.type==="error")throw new Error(`Error Code ${t.code}: ${t.message}`||"Unknown error");if(t.type==="response.failed")throw new Error("Unknown error")}}g(z,"processResponsesStream");function v(r){if(!r)return"stop";switch(r){case"completed":return"stop";case"incomplete":return"length";case"failed":case"cancelled":return"error";case"in_progress":case"queued":return"stop";default:{const n=r;throw new Error(`Unhandled stop reason: ${n}`)}}}g(v,"mapStopReason");export{T as convertResponsesMessages,b as convertResponsesTools,z as processResponsesStream};

package/dist/core/lib/ai/src/providers/openai-responses.d.ts

@@ -0,0 +1,19 @@
+/**
+ * [WHO]: OpenAIResponsesOptions, streamOpenAIResponses, streamSimpleOpenAIResponses
+ * [FROM]: Depends on openai, ../env-api-keys.js, ../models.js, ../utils/event-stream.js, ./github-copilot-headers.js
+ * [TO]: Consumed by core/lib/ai/src/index.ts
+ * [HERE]: core/lib/ai/src/providers/openai-responses.ts -
+ */
+import type { ResponseCreateParamsStreaming } from "openai/resources/responses/responses.js";
+import type { SimpleStreamOptions, StreamFunction, StreamOptions } from "../types.js";
+export interface OpenAIResponsesOptions extends StreamOptions {
+    reasoningEffort?: "minimal" | "low" | "medium" | "high" | "xhigh";
+    reasoningSummary?: "auto" | "detailed" | "concise" | null;
+    serviceTier?: ResponseCreateParamsStreaming["service_tier"];
+    toolChoice?: unknown;
+}
+/**
+ * Generate function for OpenAI Responses API
+ */
+export declare const streamOpenAIResponses: StreamFunction<"openai-responses", OpenAIResponsesOptions>;
+export declare const streamSimpleOpenAIResponses: StreamFunction<"openai-responses", SimpleStreamOptions>;

package/dist/core/lib/ai/src/providers/openai-responses.js

@@ -0,0 +1 @@
+var f=Object.defineProperty;var i=(e,s)=>f(e,"name",{value:s,configurable:!0});import d from"openai";import{getEnvApiKey as u}from"../env-api-keys.js";import{supportsXhigh as m}from"../models.js";import{AssistantMessageEventStream as l}from"../utils/event-stream.js";import{buildCopilotDynamicHeaders as h,hasCopilotVisionInput as g}from"./github-copilot-headers.js";import{convertResponsesMessages as v,convertResponsesTools as E,processResponsesStream as y}from"./openai-responses-shared.js";import{buildBaseOptions as R,clampReasoning as _}from"./simple-options.js";const A=new Set(["openai","openai-codex","opencode"]);function b(e){return e||(typeof process<"u"&&(process.env.CATUI_CACHE_RETENTION??process.env.NANOPENCIL_CACHE_RETENTION)==="long"?"long":"short")}i(b,"resolveCacheRetention");function I(e,s){if(s==="long"&&e.includes("api.openai.com"))return"24h"}i(I,"getPromptCacheRetention");const w=i((e,s,r)=>{const o=new l;return(async()=>{const n={role:"assistant",content:[],api:e.api,provider:e.provider,model:e.id,usage:{input:0,output:0,cacheRead:0,cacheWrite:0,totalTokens:0,cost:{input:0,output:0,cacheRead:0,cacheWrite:0,total:0}},stopReason:"stop",timestamp:Date.now()};try{const t=r?.apiKey||u(e.provider)||"",a=O(e,s,t,r?.headers),c=C(e,s,r);r?.onPayload?.(c);const p=await a.responses.create(c,r?.signal?{signal:r.signal}:void 0);if(o.push({type:"start",partial:n}),await y(p,n,o,e,{serviceTier:r?.serviceTier,applyServiceTierPricing:P}),r?.signal?.aborted)throw new Error("Request was aborted");if(n.stopReason==="aborted"||n.stopReason==="error")throw new Error("An unknown error occurred");o.push({type:"done",reason:n.stopReason,message:n}),o.end()}catch(t){for(const a of n.content)delete a.index;if(n.stopReason=r?.signal?.aborted?"aborted":"error",n.errorMessage=t instanceof Error?t.message:JSON.stringify(t),t&&typeof t=="object"&&"headers"in t){const a=t.headers;a&&typeof a=="object"&&(n.errorHeaders=Object.fromEntries(Object.entries(a).map(([c,p])=>[c.toLowerCase(),String(p)])))}o.push({type:"error",reason:n.stopReason,error:n}),o.end()}})(),o},"streamOpenAIResponses"),W=i((e,s,r)=>{const o=r?.apiKey||u(e.provider);if(!o)throw new Error(`No API key for provider: ${e.provider}`);const n=R(e,r,o),t=m(e)?r?.reasoning:_(r?.reasoning);return w(e,s,{...n,reasoningEffort:t,toolChoice:r?.toolChoice})},"streamSimpleOpenAIResponses");function O(e,s,r,o){if(!r){if(!process.env.OPENAI_API_KEY)throw new Error("OpenAI API key is required. Set OPENAI_API_KEY environment variable or pass it as an argument.");r=process.env.OPENAI_API_KEY}const n={...e.headers};if(e.provider==="github-copilot"){const t=g(s.messages),a=h({messages:s.messages,hasImages:t});Object.assign(n,a)}return o&&Object.assign(n,o),new d({apiKey:r,baseURL:e.baseUrl,dangerouslyAllowBrowser:!0,defaultHeaders:n})}i(O,"createClient");function C(e,s,r){const o=v(e,s,A),n=b(r?.cacheRetention),t={model:e.id,input:o,stream:!0,prompt_cache_key:n==="none"?void 0:r?.sessionId,prompt_cache_retention:I(e.baseUrl,n),store:!1};return r?.maxTokens&&(t.max_output_tokens=r?.maxTokens),r?.temperature!==void 0&&(t.temperature=r?.temperature),r?.serviceTier!==void 0&&(t.service_tier=r.serviceTier),s.tools&&(t.tools=E(s.tools)),r?.toolChoice!==void 0&&(t.tool_choice=r.toolChoice),e.reasoning&&(r?.reasoningEffort||r?.reasoningSummary?(t.reasoning={effort:r?.reasoningEffort||"medium",summary:r?.reasoningSummary||"auto"},t.include=["reasoning.encrypted_content"]):e.name.startsWith("gpt-5")&&o.push({role:"developer",content:[{type:"input_text",text:"# Juice: 0 !important"}]})),t}i(C,"buildParams");function T(e){switch(e){case"flex":return .5;case"priority":return 2;default:return 1}}i(T,"getServiceTierCostMultiplier");function P(e,s){const r=T(s);r!==1&&(e.cost.input*=r,e.cost.output*=r,e.cost.cacheRead*=r,e.cost.cacheWrite*=r,e.cost.total=e.cost.input+e.cost.output+e.cost.cacheRead+e.cost.cacheWrite)}i(P,"applyServiceTierPricing");export{w as streamOpenAIResponses,W as streamSimpleOpenAIResponses};

package/dist/core/lib/ai/src/providers/register-builtins.d.ts

@@ -0,0 +1,8 @@
+/**
+ * [WHO]: registerBuiltInApiProviders, resetApiProviders
+ * [FROM]: Depends on ../api-registry.js and dynamic imports for built-in provider runtime modules
+ * [TO]: Consumed by core/lib/ai/src/stream.ts and core/lib/ai/src/index.ts for built-in provider availability
+ * [HERE]: core/lib/ai/src/providers/register-builtins.ts - lazy registration boundary for built-in AI providers
+ */
+export declare function registerBuiltInApiProviders(): void;
+export declare function resetApiProviders(): void;

package/dist/core/lib/ai/src/providers/register-builtins.js

@@ -0,0 +1 @@
+var a=Object.defineProperty;var t=(e,r)=>a(e,"name",{value:r,configurable:!0});import{clearApiProviders as i,registerApiProviderLoader as s}from"../api-registry.js";function o(){s("anthropic-messages",async()=>{const{streamAnthropic:e,streamSimpleAnthropic:r}=await import("./anthropic.js");return{api:"anthropic-messages",stream:e,streamSimple:r}}),s("openai-completions",async()=>{const{streamOpenAICompletions:e,streamSimpleOpenAICompletions:r}=await import("./openai-completions.js");return{api:"openai-completions",stream:e,streamSimple:r}}),s("openai-responses",async()=>{const{streamOpenAIResponses:e,streamSimpleOpenAIResponses:r}=await import("./openai-responses.js");return{api:"openai-responses",stream:e,streamSimple:r}}),s("azure-openai-responses",async()=>{const{streamAzureOpenAIResponses:e,streamSimpleAzureOpenAIResponses:r}=await import("./azure-openai-responses.js");return{api:"azure-openai-responses",stream:e,streamSimple:r}}),s("openai-codex-responses",async()=>{const{streamOpenAICodexResponses:e,streamSimpleOpenAICodexResponses:r}=await import("./openai-codex-responses.js");return{api:"openai-codex-responses",stream:e,streamSimple:r}}),s("google-generative-ai",async()=>{const{streamGoogle:e,streamSimpleGoogle:r}=await import("./google.js");return{api:"google-generative-ai",stream:e,streamSimple:r}}),s("google-gemini-cli",async()=>{const{streamGoogleGeminiCli:e,streamSimpleGoogleGeminiCli:r}=await import("./google-gemini-cli.js");return{api:"google-gemini-cli",stream:e,streamSimple:r}}),s("google-vertex",async()=>{const{streamGoogleVertex:e,streamSimpleGoogleVertex:r}=await import("./google-vertex.js");return{api:"google-vertex",stream:e,streamSimple:r}}),s("bedrock-converse-stream",async()=>{const{streamBedrock:e,streamSimpleBedrock:r}=await import("./amazon-bedrock.js");return{api:"bedrock-converse-stream",stream:e,streamSimple:r}})}t(o,"registerBuiltInApiProviders");function n(){i(),o()}t(n,"resetApiProviders"),o();export{o as registerBuiltInApiProviders,n as resetApiProviders};

package/dist/core/lib/ai/src/providers/simple-options.d.ts

@@ -0,0 +1,13 @@
+/**
+ * [WHO]: buildBaseOptions, clampReasoning, adjustMaxTokensForThinking
+ * [FROM]: No external dependencies
+ * [TO]: Consumed by core/lib/ai/src/index.ts
+ * [HERE]: core/lib/ai/src/providers/simple-options.ts -
+ */
+import type { Api, Model, SimpleStreamOptions, StreamOptions, ThinkingBudgets, ThinkingLevel } from "../types.js";
+export declare function buildBaseOptions(model: Model<Api>, options?: SimpleStreamOptions, apiKey?: string): StreamOptions;
+export declare function clampReasoning(effort: ThinkingLevel | undefined): Exclude<ThinkingLevel, "xhigh"> | undefined;
+export declare function adjustMaxTokensForThinking(baseMaxTokens: number, modelMaxTokens: number, reasoningLevel: ThinkingLevel, customBudgets?: ThinkingBudgets): {
+    maxTokens: number;
+    thinkingBudget: number;
+};

package/dist/core/lib/ai/src/providers/simple-options.js

@@ -0,0 +1 @@
+var h=Object.defineProperty;var n=(a,e)=>h(a,"name",{value:e,configurable:!0});function x(a,e,s){return{temperature:e?.temperature,maxTokens:e?.maxTokens||Math.min(a.maxTokens,32e3),signal:e?.signal,apiKey:s||e?.apiKey,cacheRetention:e?.cacheRetention,sessionId:e?.sessionId,headers:e?.headers,onPayload:e?.onPayload,maxRetryDelayMs:e?.maxRetryDelayMs,metadata:e?.metadata}}n(x,"buildBaseOptions");function l(a){return a==="xhigh"?"high":a}n(l,"clampReasoning");function o(a,e,s,m){const u={...{minimal:1024,low:2048,medium:8192,high:16384},...m},d=1024,r=l(s);let t=u[r];const i=Math.min(a+t,e);return i<=t&&(t=Math.max(0,i-d)),{maxTokens:i,thinkingBudget:t}}n(o,"adjustMaxTokensForThinking");export{o as adjustMaxTokensForThinking,x as buildBaseOptions,l as clampReasoning};

package/dist/core/lib/ai/src/providers/transform-messages.d.ts

@@ -0,0 +1,13 @@
+/**
+ * [WHO]: Provides transformMessages
+ * [FROM]: No external dependencies
+ * [TO]: Consumed by provider stream implementations and core/lib/ai/src/index.ts
+ * [HERE]: core/lib/ai/src/providers/transform-messages.ts - cross-provider message replay normalization
+ */
+import type { Api, AssistantMessage, Message, Model } from "../types.js";
+/**
+ * Normalize tool call ID for cross-provider compatibility.
+ * OpenAI Responses API generates IDs that are 450+ chars with special characters like `|`.
+ * Anthropic APIs require IDs matching ^[a-zA-Z0-9_-]+$ (max 64 chars).
+ */
+export declare function transformMessages<TApi extends Api>(messages: Message[], model: Model<TApi>, normalizeToolCallId?: (id: string, model: Model<TApi>, source: AssistantMessage) => string): Message[];

package/dist/core/lib/ai/src/providers/transform-messages.js

@@ -0,0 +1 @@
+var S=Object.defineProperty;var h=(u,i)=>S(u,"name",{value:i,configurable:!0});function w(u,i,r){const I=new Map,x=u.map(n=>{if(n.role==="user")return n;if(n.role==="toolResult"){const t=I.get(n.toolCallId);return t&&t!==n.toolCallId?{...n,toolCallId:t}:n}if(n.role==="assistant"){const t=n,o=t.provider===i.provider&&t.api===i.api&&t.model===i.id,p=t.content.flatMap(e=>{if(e.type==="thinking")return e.redacted?o?e:[]:o&&e.thinkingSignature?e:!e.thinking||e.thinking.trim()===""?[]:o?e:{type:"text",text:e.thinking};if(e.type==="text")return o?e:{type:"text",text:e.text};if(e.type==="toolCall"){const d=e;let f=d;if(!o&&d.thoughtSignature&&(f={...d},delete f.thoughtSignature),!o&&r){const c=r(d.id,i,t);c!==d.id&&(I.set(d.id,c),f={...f,id:c})}return f}return e});return{...t,content:p}}return n}),s=[];let l=[],a=new Set;const C=new Set;for(let n=0;n<x.length;n++){const t=x[n];if(t.role==="assistant"){l.length>0&&(s.push(...g(l,a)),l=[],a=new Set);const o=t;if(o.stopReason==="error"||o.stopReason==="aborted"){for(const e of o.content)e.type==="toolCall"&&C.add(e.id);continue}if(o.content.length===0)continue;const p=o.content.filter(e=>e.type==="toolCall");p.length>0&&(l=p,a=new Set),s.push(t)}else if(t.role==="toolResult"){if(C.has(t.toolCallId)){C.delete(t.toolCallId);continue}if(!y(l,t.toolCallId)||a.has(t.toolCallId))continue;a.add(t.toolCallId),s.push(t)}else t.role==="user"&&l.length>0&&(s.push(...g(l,a)),l=[],a=new Set),s.push(t)}return l.length>0&&s.push(...g(l,a)),s}h(w,"transformMessages");function y(u,i){return u.some(r=>r.id===i)}h(y,"hasPendingToolCall");function g(u,i){return u.filter(r=>!i.has(r.id)).map(r=>({role:"toolResult",toolCallId:r.id,toolName:r.name,content:[{type:"text",text:"No result provided"}],isError:!0,timestamp:Date.now()}))}h(g,"createMissingToolResults");export{w as transformMessages};

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

@@ -0,0 +1,8 @@
+/**
+ * [WHO]: ApiProvider registry exports plus built-in provider loader reset helpers
+ * [FROM]: Depends on api-registry and providers/register-builtins for provider registration seams
+ * [TO]: Consumed by @catui/ai/registry subpath consumers
+ * [HERE]: core/lib/ai/src/registry.ts - additive provider registry subpath entry for AI package
+ */
+export * from "./api-registry.js";
+export * from "./providers/register-builtins.js";

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

@@ -0,0 +1 @@
+export*from"./api-registry.js";export*from"./providers/register-builtins.js";

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

@@ -0,0 +1,10 @@
+/**
+ * [WHO]: TypeBox schema re-exports, StringEnum, validateToolCall, validateToolArguments
+ * [FROM]: Depends on @sinclair/typebox and AI validation/typebox helper modules
+ * [TO]: Consumed by @catui/ai/schema subpath consumers
+ * [HERE]: core/lib/ai/src/schema.ts - additive schema subpath entry for AI package
+ */
+export type { Static, TSchema } from "@sinclair/typebox";
+export { Type } from "@sinclair/typebox";
+export * from "./utils/typebox-helpers.js";
+export * from "./utils/validation.js";

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

@@ -0,0 +1 @@
+import{Type as e}from"@sinclair/typebox";export*from"./utils/typebox-helpers.js";export*from"./utils/validation.js";export{e as Type};

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

@@ -0,0 +1,33 @@
+/**
+ * [WHO]: getEnvApiKey, stream, streamSimple, complete, completeSimple, RetryOptions
+ * [FROM]: Depends on ./api-registry.js, providers/register-builtins.js, and utils/http-proxy.js
+ * [TO]: Consumed by core/lib/ai/src/index.ts
+ * [HERE]: core/lib/ai/src/stream.ts - provider streaming entrypoint with lazy provider resolution, retry, abort, and factory-error event handling
+ */
+import "./providers/register-builtins.js";
+import "./utils/http-proxy.js";
+import type { Api, AssistantMessage, Context, Model, ProviderStreamOptions, SimpleStreamOptions } from "./types.js";
+import { AssistantMessageEventStream } from "./utils/event-stream.js";
+export { getEnvApiKey } from "./env-api-keys.js";
+export interface RetryOptions {
+    /** Maximum number of retry attempts (default: 3). Ignored when persistentRetry is true. */
+    maxRetries?: number;
+    /** Base delay in ms for exponential backoff (default: 1000) */
+    baseDelayMs?: number;
+    /** Maximum delay cap in ms (default: 30000, or 300000 for persistentRetry) */
+    maxDelayMs?: number;
+    /** Whether to add jitter to avoid thundering herd (default: true) */
+    jitter?: boolean;
+    /**
+     * Persistent/unattended retry mode for 429/529 overload errors.
+     * When true, retries indefinitely with capped backoff and periodic heartbeat yields.
+     * Only applies to overload errors (429, 529); other retriable errors still respect maxRetries.
+     */
+    persistentRetry?: boolean;
+    /** Heartbeat interval in ms during persistent retry to prevent idle timeouts (default: 30000) */
+    heartbeatMs?: number;
+}
+export declare function stream<TApi extends Api>(model: Model<TApi>, context: Context, options?: ProviderStreamOptions): AssistantMessageEventStream;
+export declare function complete<TApi extends Api>(model: Model<TApi>, context: Context, options?: ProviderStreamOptions): Promise<AssistantMessage>;
+export declare function streamSimple<TApi extends Api>(model: Model<TApi>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream;
+export declare function completeSimple<TApi extends Api>(model: Model<TApi>, context: Context, options?: SimpleStreamOptions): Promise<AssistantMessage>;

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

@@ -0,0 +1 @@
+var D=Object.defineProperty;var o=(e,t)=>D(e,"name",{value:t,configurable:!0});import"./providers/register-builtins.js";import"./utils/http-proxy.js";import{ensureApiProvider as g}from"./api-registry.js";import{AssistantMessageEventStream as A}from"./utils/event-stream.js";import{isContextOverflow as I}from"./utils/overflow.js";import{getEnvApiKey as H}from"./env-api-keys.js";const v={maxRetries:3,baseDelayMs:1e3,maxDelayMs:3e4,jitter:!0,persistentRetry:!1,heartbeatMs:3e4};function E(){return{input:0,output:0,cacheRead:0,cacheWrite:0,totalTokens:0,cost:{input:0,output:0,cacheRead:0,cacheWrite:0,total:0}}}o(E,"emptyUsage");const T=new Set([429,500,502,503,504,529]),N=[/ECONNRESET/i,/ETIMEDOUT/i,/ECONNREFUSED/i,/socket hang up/i,/fetch failed/i,/network/i,/aborted/i,/without a final assistant message/i];function P(e){if(e.stopReason!=="error"||!e.errorMessage||I(e))return!1;const t=e.errorMessage,r=t.match(/^([45]\d\d)\b/);if(r){const n=parseInt(r[1],10);return T.has(n)}return N.some(n=>n.test(t))}o(P,"isRetriableStreamError");function m(e,t){const r=t.baseDelayMs*Math.pow(2,e),n=Math.min(r,t.maxDelayMs);return t.jitter?Math.floor(Math.random()*n):n}o(m,"calculateDelay");function w(e,t){if(t){const n=t["retry-after"]??t["Retry-After"];if(n){const a=parseInt(n,10);if(!isNaN(a))return a*1e3}}const r=e.match(/retry[_-]after[:\s]+(\d+)/i);if(r)return parseInt(r[1],10)*1e3}o(w,"extractRetryAfterMs");function _(e){return/^[45]29\b/.test(e.errorMessage??"")}o(_,"isOverloadError");function h(e,t,r){if(!P(e))return;const n=_(e);if(n&&r.persistentRetry){const a={...r,maxDelayMs:Math.max(r.maxDelayMs,3e5)};return w(e.errorMessage??"",e.errorHeaders)??m(t,a)}if(!(t>=r.maxRetries))return n?w(e.errorMessage??"",e.errorHeaders)??m(t,r):m(t,r)}o(h,"getRetryDelayMs");function k(e){return e instanceof Error?e.message:typeof e=="string"?e:JSON.stringify(e)??String(e)}o(k,"getErrorMessage");function R(e,t,r){return{role:"assistant",content:[],api:e.api,provider:e.provider,model:e.id,stopReason:"error",errorMessage:k(t),errorHeaders:r,usage:E(),timestamp:Date.now()}}o(R,"createStreamErrorMessage");function L(e){return R(e,new Error("Provider stream ended without a final assistant message"))}o(L,"createMissingStreamResultMessage");function C(e){return R(e,new Error("Request was aborted"))}o(C,"createAbortMessage");function l(e,t){e.push({type:"error",reason:"error",error:C(t)})}o(l,"emitAbortError");function b(e,t,r,n){return t?.aborted?Promise.resolve("aborted"):new Promise(a=>{let i,u;const p=o(()=>{i!==void 0&&clearTimeout(i),u!==void 0&&clearInterval(u),t?.removeEventListener("abort",s)},"cleanup"),s=o(()=>{p(),a("aborted")},"onAbort");r&&r>0&&r<e&&n&&(u=setInterval(n,r)),i=setTimeout(()=>{p(),a("elapsed")},e),t?.addEventListener("abort",s,{once:!0})})}o(b,"waitForRetryDelay");function U(e,t){return t?.aborted?Promise.resolve("aborted"):new Promise((r,n)=>{const a=o(()=>{t?.removeEventListener("abort",i)},"cleanup"),i=o(()=>{a(),r("aborted")},"onAbort");t?.addEventListener("abort",i,{once:!0}),e.next().then(u=>{a(),r(u)},u=>{a(),n(u)})})}o(U,"waitForStreamEvent");async function S(e){const t=await g(e);if(!t)throw new Error(`No API provider registered for api: ${e}`);return t}o(S,"resolveApiProvider");function F(e,t,r){const n={...v,...r?.retry};return x(e,async()=>(await S(e.api)).stream(e,t,r),n,r?.signal)}o(F,"stream");async function Y(e,t,r){return F(e,t,r).result()}o(Y,"complete");function W(e,t,r){const n={...v,...r?.retry};return x(e,async()=>(await S(e.api)).streamSimple(e,t,r),n,r?.signal)}o(W,"streamSimple");async function $(e,t,r){return W(e,t,r).result()}o($,"completeSimple");function x(e,t,r,n){const a=new A;return(async()=>{let i=0;const u=r.persistentRetry?()=>{a.push({type:"text_delta",contentIndex:0,delta:"",partial:{role:"assistant",content:[],api:e.api,provider:e.provider,model:e.id,usage:E(),stopReason:"error",timestamp:Date.now()}})}:void 0;for(;i<=r.maxRetries||r.persistentRetry;){if(n?.aborted){l(a,e);return}let p;try{p=await t()}catch(f){const c=R(e,f),d=h(c,i,r);if(d!==void 0){if(i++,await b(d,n,r.heartbeatMs,u)==="aborted"){l(a,e);return}continue}a.push({type:"error",reason:"error",error:c});return}let s=null;const y=p[Symbol.asyncIterator]();for(;;){let f;try{f=await U(y,n)}catch(d){s=R(e,d);const M=h(s,i,r);if(M!==void 0){if(i++,await b(M,n,r.heartbeatMs,u)==="aborted"){l(a,e);return}break}a.push({type:"error",reason:"error",error:s});return}if(f==="aborted"){y.return?.(),l(a,e);return}if(f.done)break;const c=f.value;if(c.type==="done"){s=c.message,a.push(c);break}else if(c.type==="error"){s=c.error;const d=h(s,i,r);if(d!==void 0){if(i++,await b(d,n,r.heartbeatMs,u)==="aborted"){l(a,e);return}break}a.push(c);return}else i===0&&a.push(c)}if(!s){s=p.resultIfResolved()??L(e);const f=h(s,i,r);if(f!==void 0){if(i++,await b(f,n,r.heartbeatMs,u)==="aborted"){l(a,e);return}continue}if(s.stopReason==="error"||s.stopReason==="aborted"){a.push({type:"error",reason:s.stopReason,error:s});return}a.push({type:"done",reason:s.stopReason,message:s});return}if(s&&s.stopReason!=="error")return}})(),a}o(x,"wrapWithRetry");export{Y as complete,$ as completeSimple,H as getEnvApiKey,F as stream,W as streamSimple};

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

@@ -0,0 +1,331 @@
+/**
+ * [WHO]: ThinkingBudgets, StreamOptions, SimpleStreamOptions, TextContent, ThinkingContent, Model
+ * [FROM]: Depends on utils/event-stream-types for structural stream contracts
+ * [TO]: Consumed by core/lib/ai/src/index.ts
+ * [HERE]: core/lib/ai/src/types.ts -
+ */
+import type { AsyncEventStream } from "./utils/event-stream-types.js";
+export type KnownApi = "openai-completions" | "openai-responses" | "azure-openai-responses" | "openai-codex-responses" | "anthropic-messages" | "bedrock-converse-stream" | "google-generative-ai" | "google-gemini-cli" | "google-vertex";
+export type Api = KnownApi | (string & {});
+export type KnownProvider = "amazon-bedrock" | "anthropic" | "google" | "google-gemini-cli" | "google-antigravity" | "google-vertex" | "openai" | "azure-openai-responses" | "openai-codex" | "github-copilot" | "xai" | "groq" | "cerebras" | "openrouter" | "vercel-ai-gateway" | "zai" | "mistral" | "minimax" | "minimax-cn" | "huggingface" | "opencode" | "opencode-go" | "kimi-coding" | "ali-token-plan-openai" | "ali-token-plan-anthropic";
+export type Provider = KnownProvider | string;
+export type ThinkingLevel = "minimal" | "low" | "medium" | "high" | "xhigh";
+/** Token budgets for each thinking level (token-based providers only) */
+export interface ThinkingBudgets {
+    minimal?: number;
+    low?: number;
+    medium?: number;
+    high?: number;
+}
+export type CacheRetention = "none" | "short" | "long";
+export type Transport = "sse" | "websocket" | "auto";
+export interface StreamOptions {
+    temperature?: number;
+    maxTokens?: number;
+    signal?: AbortSignal;
+    /** Retry configuration for automatic retry on retriable errors */
+    retry?: {
+        /** Maximum number of retry attempts (default: 3). Ignored when persistentRetry is true. */
+        maxRetries?: number;
+        /** Base delay in ms for exponential backoff (default: 1000) */
+        baseDelayMs?: number;
+        /** Maximum delay cap in ms (default: 30000, or 300000 for persistentRetry) */
+        maxDelayMs?: number;
+        /** Whether to add jitter to avoid thundering herd (default: true) */
+        jitter?: boolean;
+        /**
+         * Persistent/unattended retry mode for 429/529 overload errors.
+         * When true, retries indefinitely with capped backoff and periodic heartbeat yields.
+         * Only applies to overload errors (429, 529); other retriable errors still respect maxRetries.
+         */
+        persistentRetry?: boolean;
+        /** Heartbeat interval in ms during persistent retry to prevent idle timeouts (default: 30000) */
+        heartbeatMs?: number;
+    };
+    apiKey?: string;
+    /**
+     * Preferred transport for providers that support multiple transports.
+     * Providers that do not support this option ignore it.
+     */
+    transport?: Transport;
+    /**
+     * Prompt cache retention preference. Providers map this to their supported values.
+     * Default: "short".
+     */
+    cacheRetention?: CacheRetention;
+    /**
+     * Optional session identifier for providers that support session-based caching.
+     * Providers can use this to enable prompt caching, request routing, or other
+     * session-aware features. Ignored by providers that don't support it.
+     */
+    sessionId?: string;
+    /**
+     * Optional callback for inspecting provider payloads before sending.
+     */
+    onPayload?: (payload: unknown) => void;
+    /**
+     * Optional custom HTTP headers to include in API requests.
+     * Merged with provider defaults; can override default headers.
+     * Not supported by all providers (e.g., AWS Bedrock uses SDK auth).
+     */
+    headers?: Record<string, string>;
+    /**
+     * Maximum delay in milliseconds to wait for a retry when the server requests a long wait.
+     * If the server's requested delay exceeds this value, the request fails immediately
+     * with an error containing the requested delay, allowing higher-level retry logic
+     * to handle it with user visibility.
+     * Default: 60000 (60 seconds). Set to 0 to disable the cap.
+     */
+    maxRetryDelayMs?: number;
+    /**
+     * Optional metadata to include in API requests.
+     * Providers extract the fields they understand and ignore the rest.
+     * For example, Anthropic uses `user_id` for abuse tracking and rate limiting.
+     */
+    metadata?: Record<string, unknown>;
+}
+export type ProviderStreamOptions = StreamOptions & Record<string, unknown>;
+export interface SimpleStreamOptions extends StreamOptions {
+    reasoning?: ThinkingLevel;
+    /** Custom token budgets for thinking levels (token-based providers only) */
+    thinkingBudgets?: ThinkingBudgets;
+    /** Provider-specific tool choice override for structured calls. */
+    toolChoice?: unknown;
+}
+export type StreamFunction<TApi extends Api = Api, TOptions extends StreamOptions = StreamOptions> = (model: Model<TApi>, context: Context, options?: TOptions) => AssistantMessageEventStreamContract;
+export interface TextContent {
+    type: "text";
+    text: string;
+    textSignature?: string;
+}
+export interface ThinkingContent {
+    type: "thinking";
+    thinking: string;
+    thinkingSignature?: string;
+    /** When true, the thinking content was redacted by safety filters. The opaque
+     *  encrypted payload is stored in `thinkingSignature` so it can be passed back
+     *  to the API for multi-turn continuity. */
+    redacted?: boolean;
+}
+export interface ImageContent {
+    type: "image";
+    data: string;
+    mimeType: string;
+}
+export interface DocumentContent {
+    type: "document";
+    source: {
+        type: "base64";
+        media_type: "application/pdf";
+        data: string;
+    };
+}
+export interface ToolCall {
+    type: "toolCall";
+    id: string;
+    name: string;
+    arguments: Record<string, any>;
+    thoughtSignature?: string;
+}
+export interface Usage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    totalTokens: number;
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        total: number;
+    };
+}
+export type StopReason = "stop" | "length" | "toolUse" | "error" | "aborted";
+export interface UserMessage {
+    role: "user";
+    content: string | (TextContent | ImageContent | DocumentContent)[];
+    timestamp: number;
+}
+export interface AssistantMessage {
+    role: "assistant";
+    content: (TextContent | ThinkingContent | ToolCall)[];
+    api: Api;
+    provider: Provider;
+    model: string;
+    usage: Usage;
+    stopReason: StopReason;
+    errorMessage?: string;
+    /** HTTP response headers from the error response, if available. Used for retry-after extraction. */
+    errorHeaders?: Record<string, string>;
+    timestamp: number;
+}
+export interface ToolResultMessage<TDetails = any> {
+    role: "toolResult";
+    toolCallId: string;
+    toolName: string;
+    content: (TextContent | ImageContent | DocumentContent)[];
+    details?: TDetails;
+    isError: boolean;
+    timestamp: number;
+}
+export type Message = UserMessage | AssistantMessage | ToolResultMessage;
+import type { TSchema } from "@sinclair/typebox";
+export interface Tool<TParameters extends TSchema = TSchema> {
+    name: string;
+    description: string;
+    parameters: TParameters;
+}
+export interface Context {
+    systemPrompt?: string;
+    messages: Message[];
+    tools?: Tool[];
+}
+export type AssistantMessageEvent = {
+    type: "start";
+    partial: AssistantMessage;
+} | {
+    type: "text_start";
+    contentIndex: number;
+    partial: AssistantMessage;
+} | {
+    type: "text_delta";
+    contentIndex: number;
+    delta: string;
+    partial: AssistantMessage;
+} | {
+    type: "text_end";
+    contentIndex: number;
+    content: string;
+    partial: AssistantMessage;
+} | {
+    type: "thinking_start";
+    contentIndex: number;
+    partial: AssistantMessage;
+} | {
+    type: "thinking_delta";
+    contentIndex: number;
+    delta: string;
+    partial: AssistantMessage;
+} | {
+    type: "thinking_end";
+    contentIndex: number;
+    content: string;
+    partial: AssistantMessage;
+} | {
+    type: "toolcall_start";
+    contentIndex: number;
+    partial: AssistantMessage;
+} | {
+    type: "toolcall_delta";
+    contentIndex: number;
+    delta: string;
+    partial: AssistantMessage;
+} | {
+    type: "toolcall_end";
+    contentIndex: number;
+    toolCall: ToolCall;
+    partial: AssistantMessage;
+} | {
+    type: "done";
+    reason: Extract<StopReason, "stop" | "length" | "toolUse">;
+    message: AssistantMessage;
+} | {
+    type: "error";
+    reason: Extract<StopReason, "aborted" | "error">;
+    error: AssistantMessage;
+};
+export type AssistantMessageEventStreamContract = AsyncEventStream<AssistantMessageEvent, AssistantMessage>;
+/**
+ * Compatibility settings for OpenAI-compatible completions APIs.
+ * Use this to override URL-based auto-detection for custom providers.
+ */
+export interface OpenAICompletionsCompat {
+    /** Whether the provider supports the `store` field. Default: auto-detected from URL. */
+    supportsStore?: boolean;
+    /** Whether the provider supports the `developer` role (vs `system`). Default: auto-detected from URL. */
+    supportsDeveloperRole?: boolean;
+    /** Whether the provider supports `reasoning_effort`. Default: auto-detected from URL. */
+    supportsReasoningEffort?: boolean;
+    /** Optional mapping from catui-ai reasoning levels to provider/model-specific `reasoning_effort` values. */
+    reasoningEffortMap?: Partial<Record<ThinkingLevel, string>>;
+    /** Whether the provider supports `stream_options: { include_usage: true }` for token usage in streaming responses. Default: true. */
+    supportsUsageInStreaming?: boolean;
+    /** Which field to use for max tokens. Default: auto-detected from URL. */
+    maxTokensField?: "max_completion_tokens" | "max_tokens";
+    /** Whether tool results require the `name` field. Default: auto-detected from URL. */
+    requiresToolResultName?: boolean;
+    /** Whether a user message after tool results requires an assistant message in between. Default: auto-detected from URL. */
+    requiresAssistantAfterToolResult?: boolean;
+    /** Whether thinking blocks must be converted to text blocks with <thinking> delimiters. Default: auto-detected from URL. */
+    requiresThinkingAsText?: boolean;
+    /** Whether tool call IDs must be normalized to Mistral format (exactly 9 alphanumeric chars). Default: auto-detected from URL. */
+    requiresMistralToolIds?: boolean;
+    /** Format for reasoning/thinking parameter. "openai" uses reasoning_effort, "zai" uses thinking: { type: "enabled" }, "qwen" uses enable_thinking: boolean. Default: "openai". */
+    thinkingFormat?: "openai" | "zai" | "qwen";
+    /** OpenRouter-specific routing preferences. Only used when baseUrl points to OpenRouter. */
+    openRouterRouting?: OpenRouterRouting;
+    /** Vercel AI Gateway routing preferences. Only used when baseUrl points to Vercel AI Gateway. */
+    vercelGatewayRouting?: VercelGatewayRouting;
+    /** Whether the provider supports the `strict` field in tool definitions. Default: true. */
+    supportsStrictMode?: boolean;
+}
+/** Compatibility settings for OpenAI Responses APIs. */
+export interface OpenAIResponsesCompat {
+}
+/**
+ * OpenRouter provider routing preferences.
+ * Controls which upstream providers OpenRouter routes requests to.
+ * @see https://openrouter.ai/docs/provider-routing
+ */
+export interface OpenRouterRouting {
+    /** List of provider slugs to exclusively use for this request (e.g., ["amazon-bedrock", "anthropic"]). */
+    only?: string[];
+    /** List of provider slugs to try in order (e.g., ["anthropic", "openai"]). */
+    order?: string[];
+}
+/**
+ * Vercel AI Gateway routing preferences.
+ * Controls which upstream providers the gateway routes requests to.
+ * @see https://vercel.com/docs/ai-gateway/models-and-providers/provider-options
+ */
+export interface VercelGatewayRouting {
+    /** List of provider slugs to exclusively use for this request (e.g., ["bedrock", "anthropic"]). */
+    only?: string[];
+    /** List of provider slugs to try in order (e.g., ["anthropic", "openai"]). */
+    order?: string[];
+}
+export interface Model<TApi extends Api> {
+    id: string;
+    name: string;
+    api: TApi;
+    provider: Provider;
+    baseUrl: string;
+    reasoning: boolean;
+    input: ("text" | "image")[];
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+    contextWindow: number;
+    maxTokens: number;
+    headers?: Record<string, string>;
+    /**
+     * Agent loop framework used by higher-level agent runtimes.
+     * "standard" keeps the existing high-autonomy loop; "weak-model-compatible"
+     * opts into stronger scaffolding for lower-intelligence adaptation or
+     * stronger-model runs that need tighter control.
+     */
+    agentLoopFramework?: "standard" | "weak-model-compatible";
+    /** Compatibility overrides for OpenAI-compatible APIs. If not set, auto-detected from baseUrl. */
+    compat?: TApi extends "openai-completions" ? OpenAICompletionsCompat : TApi extends "openai-responses" ? OpenAIResponsesCompat : never;
+    /**
+     * Origin of this model definition.
+     * - "builtin": shipped in models.generated.ts
+     * - "config": defined in user's models.json
+     * - "discovery": discovered from remote /models endpoint
+     */
+    source?: "builtin" | "config" | "discovery";
+}

package/dist/core/lib/ai/src/utils/event-stream-types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * [WHO]: Provides AsyncEventStream structural contract for provider stream types
+ * [FROM]: No runtime dependencies; pure stream type contract
+ * [TO]: Consumed by core/lib/ai/src/types.ts and utils/event-stream.ts
+ * [HERE]: core/lib/ai/src/utils/event-stream-types.ts - acyclic type seam between message types and stream implementation
+ */
+export interface AsyncEventStream<T, R = T> extends AsyncIterable<T> {
+    push(event: T): void;
+    end(result?: R): void;
+    result(): Promise<R>;
+    resultIfResolved(): R | undefined;
+}

package/dist/core/lib/ai/src/utils/event-stream.d.ts

@@ -0,0 +1,31 @@
+/**
+ * [WHO]: EventStream, AssistantMessageEventStream, createAssistantMessageEventStream
+ * [FROM]: Depends on ai message/event types and event-stream-types structural contract
+ * [TO]: Consumed by core/lib/ai/src/index.ts
+ * [HERE]: core/lib/ai/src/utils/event-stream.ts - async event queue with final-result tracking
+ */
+import type { AssistantMessage, AssistantMessageEvent } from "../types.js";
+import type { AsyncEventStream } from "./event-stream-types.js";
+export declare class EventStream<T, R = T> implements AsyncEventStream<T, R> {
+    private isComplete;
+    private extractResult;
+    private queue;
+    private waiting;
+    private done;
+    private finalResult?;
+    private hasFinalResult;
+    private finalResultPromise;
+    private resolveFinalResult;
+    constructor(isComplete: (event: T) => boolean, extractResult: (event: T) => R);
+    push(event: T): void;
+    end(result?: R): void;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    result(): Promise<R>;
+    resultIfResolved(): R | undefined;
+    private setFinalResult;
+}
+export declare class AssistantMessageEventStream extends EventStream<AssistantMessageEvent, AssistantMessage> {
+    constructor();
+}
+/** Factory function for AssistantMessageEventStream (for use in extensions) */
+export declare function createAssistantMessageEventStream(): AssistantMessageEventStream;

package/dist/core/lib/ai/src/utils/event-stream.js

@@ -0,0 +1 @@
+var l=Object.defineProperty;var s=(i,e)=>l(i,"name",{value:e,configurable:!0});class n{static{s(this,"EventStream")}isComplete;extractResult;queue=[];waiting=[];done=!1;finalResult;hasFinalResult=!1;finalResultPromise;resolveFinalResult;constructor(e,t){this.isComplete=e,this.extractResult=t,this.finalResultPromise=new Promise(r=>{this.resolveFinalResult=r})}push(e){if(this.done)return;this.isComplete(e)&&(this.done=!0,this.setFinalResult(this.extractResult(e)));const t=this.waiting.shift();t?t({value:e,done:!1}):this.queue.push(e)}end(e){for(this.done=!0,e!==void 0&&this.setFinalResult(e);this.waiting.length>0;)this.waiting.shift()({value:void 0,done:!0})}async*[Symbol.asyncIterator](){for(;;)if(this.queue.length>0)yield this.queue.shift();else{if(this.done)return;{const e=await new Promise(t=>this.waiting.push(t));if(e.done)return;yield e.value}}}result(){return this.finalResultPromise}resultIfResolved(){return this.hasFinalResult?this.finalResult:void 0}setFinalResult(e){this.hasFinalResult||(this.finalResult=e,this.hasFinalResult=!0,this.resolveFinalResult(e))}}class u extends n{static{s(this,"AssistantMessageEventStream")}constructor(){super(e=>e.type==="done"||e.type==="error",e=>{if(e.type==="done")return e.message;if(e.type==="error")return e.error;throw new Error("Unexpected event type for final result")})}}function h(){return new u}s(h,"createAssistantMessageEventStream");export{u as AssistantMessageEventStream,n as EventStream,h as createAssistantMessageEventStream};

package/dist/core/lib/ai/src/utils/http-proxy.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Set up HTTP proxy according to env variables for `fetch` based SDKs in Node.js.
+ * Bun has builtin support for this.
+ *
+ * This module should be imported early by any code that needs proxy support for fetch().
+ * ES modules are cached, so importing multiple times is safe - setup only runs once.
+ */
+/**
+ * [WHO]: Extension interface
+ * [FROM]: No external dependencies
+ * [TO]: Consumed by core/lib/ai/src/index.ts
+ * [HERE]: core/lib/ai/src/utils/http-proxy.ts -
+ */

package/dist/core/lib/ai/src/utils/http-proxy.js

@@ -0,0 +1 @@
+typeof process<"u"&&process.versions?.node&&import("undici").then(e=>{const{EnvHttpProxyAgent:s,setGlobalDispatcher:t}=e;t(new s)});