@codelia/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,638 @@
+import { JSONSchema7 } from 'json-schema';
+import { ZodSchema } from 'zod';
+import { Logger } from 'openai/client';
+import { AgentEvent, SessionStateSummary as SessionStateSummary$1 } from '@codelia/shared-types';
+export { AgentEvent, FinalResponseEvent, ReasoningEvent, StepCompleteEvent, StepStartEvent, TextEvent, ToolCallEvent, ToolResultEvent } from '@codelia/shared-types';
+import Anthropic from '@anthropic-ai/sdk';
+import { MessageCreateParamsNonStreaming } from '@anthropic-ai/sdk/resources/messages/messages';
+import OpenAI, { ClientOptions } from 'openai';
+import { ResponseCreateParamsBase, ResponseTextConfig } from 'openai/resources/responses/responses';
+import { ReasoningEffort } from 'openai/resources/shared';
+
+/**
+ * Message Content Parts
+ */
+type TextPart = {
+    type: "text";
+    text: string;
+};
+type ImagePart = {
+    type: "image_url";
+    image_url: {
+        url: string;
+        detail?: "auto" | "low" | "high";
+        media_type?: "image/png" | "image/jpeg" | "image/webp" | "image/gif";
+    };
+};
+type DocumentPart = {
+    type: "document";
+    source: {
+        data: string;
+        media_type: "application/pdf";
+    };
+};
+type OtherPart = {
+    type: "other";
+    provider: string;
+    kind: string;
+    payload: unknown;
+};
+type ContentPart = TextPart | ImagePart | DocumentPart | OtherPart;
+
+/**
+ * Tool Call
+ */
+type ToolCall = {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+    provider_meta?: unknown;
+};
+/**
+ * Tool Definition
+ */
+type ToolDefinition = {
+    name: string;
+    description: string;
+    parameters: JSONSchema7;
+    strict?: boolean;
+};
+type ToolChoice = "auto" | "required" | "none" | string;
+type JsonValue = string | number | boolean | null | {
+    [key: string]: JsonValue;
+} | JsonValue[];
+type ToolResult = {
+    type: "text";
+    text: string;
+} | {
+    type: "parts";
+    parts: ContentPart[];
+} | {
+    type: "json";
+    value: unknown;
+};
+type ToolReturn = ToolResult | string | ContentPart[] | JsonValue;
+
+/**
+ * Base Message
+ */
+type UserMessage = {
+    role: "user";
+    content: string | ContentPart[];
+    name?: string;
+};
+type SystemMessage = {
+    role: "system";
+    content: string | TextPart[];
+    name?: string;
+    cache?: boolean;
+};
+type AssistantMessage = {
+    role: "assistant";
+    content: string | ContentPart[] | null;
+    name?: string;
+    tool_calls?: ToolCall[];
+    refusal?: string | null;
+};
+type ToolOutputRef = {
+    id: string;
+    byte_size?: number;
+    line_count?: number;
+};
+type ReasoningMessage<T = unknown> = {
+    role: "reasoning";
+    content: string | null;
+    raw_item?: T | null;
+};
+type ToolMessage = {
+    role: "tool";
+    tool_call_id: string;
+    tool_name: string;
+    content: string | ContentPart[];
+    is_error?: boolean;
+    output_ref?: ToolOutputRef;
+    trimmed?: boolean;
+};
+type BaseMessage = UserMessage | SystemMessage | AssistantMessage | ToolMessage | ReasoningMessage;
+
+type ChatInvokeUsage = {
+    model: string;
+    input_tokens: number;
+    input_cached_tokens?: number | null;
+    input_cache_creation_tokens?: number | null;
+    input_image_tokens?: number | null;
+    output_tokens: number;
+    total_tokens: number;
+};
+type ChatInvokeCompletion = {
+    messages: BaseMessage[];
+    usage?: ChatInvokeUsage | null;
+    stop_reason?: string | null;
+    provider_meta?: unknown;
+};
+
+type ToolOutputCacheRecord = {
+    tool_call_id: string;
+    tool_name: string;
+    content: string;
+    is_error?: boolean;
+};
+type ToolOutputCacheReadOptions = {
+    offset?: number;
+    limit?: number;
+};
+type ToolOutputCacheSearchOptions = {
+    pattern: string;
+    regex?: boolean;
+    before?: number;
+    after?: number;
+    max_matches?: number;
+};
+type ToolOutputCacheStore = {
+    save: (record: ToolOutputCacheRecord) => Promise<ToolOutputRef> | ToolOutputRef;
+    read?: (refId: string, options?: ToolOutputCacheReadOptions) => Promise<string> | string;
+    grep?: (refId: string, options: ToolOutputCacheSearchOptions) => Promise<string> | string;
+};
+
+type ModelCost = {
+    input?: number;
+    output?: number;
+    reasoning?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    inputAudio?: number;
+    outputAudio?: number;
+};
+type ModelLimits = {
+    contextWindow?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+};
+type ModelEntry = {
+    provider: string;
+    modelId: string;
+    cost?: ModelCost;
+    limits?: ModelLimits;
+};
+type ModelMetadataIndex = {
+    models: Record<string, Record<string, ModelEntry>>;
+};
+interface ModelMetadataService {
+    getModelEntry(provider: string, modelId: string): Promise<ModelEntry | null>;
+    getModelEntries(provider: string): Promise<ModelEntry[] | null>;
+    getAllModelEntries(): Promise<Record<string, Record<string, ModelEntry>>>;
+}
+
+type AgentServices = {
+    modelMetadata?: ModelMetadataService;
+    toolOutputCacheStore?: ToolOutputCacheStore | null;
+};
+
+type ProviderName = "openai" | "anthropic" | "google";
+type ChatInvokeInput = {
+    messages: BaseMessage[];
+    model?: string;
+    tools?: ToolDefinition[] | null;
+    toolChoice?: ToolChoice | null;
+    signal?: AbortSignal;
+};
+interface BaseChatModel<P extends ProviderName = ProviderName, O = unknown> {
+    readonly provider: P;
+    readonly model: string;
+    ainvoke(input: ChatInvokeInput & {
+        options?: O;
+    }): Promise<ChatInvokeCompletion>;
+}
+
+type ModelSpec = {
+    id: string;
+    provider: ProviderName;
+    aliases?: string[];
+    contextWindow?: number;
+    maxInputTokens?: number;
+    maxOutputTokens?: number;
+    supportsTools?: boolean;
+    supportsVision?: boolean;
+    supportsReasoning?: boolean;
+    supportsJsonSchema?: boolean;
+};
+type ModelRegistry = {
+    modelsById: Record<string, ModelSpec>;
+    aliasesByProvider: Record<ProviderName, Record<string, string>>;
+};
+declare function createModelRegistry(specs: ModelSpec[]): ModelRegistry;
+declare function registerModels(registry: ModelRegistry, specs: ModelSpec[]): void;
+declare function resolveModel(registry: ModelRegistry, idOrAlias: string, provider?: ProviderName): ModelSpec | undefined;
+declare function listModels(registry: ModelRegistry, provider?: ProviderName): ModelSpec[];
+declare function applyModelMetadata(registry: ModelRegistry, index: ModelMetadataIndex): ModelRegistry;
+
+type CompactionConfig = {
+    enabled?: boolean;
+    auto?: boolean;
+    thresholdRatio?: number;
+    model?: string | null;
+    summaryPrompt?: string;
+    summaryDirectives?: string[];
+    retainPrompt?: string | null;
+    retainDirectives?: string[];
+    retainLastTurns?: number;
+};
+
+type ToolOutputCacheConfig = {
+    enabled?: boolean;
+    contextBudgetTokens?: number | null;
+    maxMessageBytes?: number;
+    maxLineLength?: number;
+};
+
+type ToolOutputCacheDependencies = {
+    modelRegistry: ModelRegistry;
+    store?: ToolOutputCacheStore | null;
+};
+type TrimResult = {
+    messages: BaseMessage[];
+    trimmed: boolean;
+};
+declare class ToolOutputCacheService {
+    private readonly config;
+    private readonly modelRegistry;
+    private readonly store?;
+    constructor(config: ToolOutputCacheConfig, deps: ToolOutputCacheDependencies);
+    processToolMessage(message: ToolMessage): Promise<ToolMessage>;
+    trimMessages(llm: BaseChatModel, messages: BaseMessage[]): Promise<TrimResult>;
+    private persistToolOutput;
+    private resolveContextBudgetTokens;
+}
+
+type UsageSummary = {
+    total_calls: number;
+    total_tokens: number;
+    total_input_tokens: number;
+    total_output_tokens: number;
+    total_cached_input_tokens: number;
+    total_cache_creation_tokens: number;
+    total_cost_usd?: number | null;
+    by_model: Record<string, {
+        calls: number;
+        input_tokens: number;
+        output_tokens: number;
+        cached_input_tokens: number;
+        cache_creation_tokens: number;
+        total_tokens: number;
+        cost_usd?: number | null;
+    }>;
+};
+
+type DependencyKey<T> = {
+    id: string;
+    create: () => T | Promise<T>;
+};
+type ToolContext = {
+    signal?: AbortSignal;
+    logger?: Logger;
+    now?: () => Date;
+    deps: Record<string, unknown>;
+    resolve: <T>(key: DependencyKey<T>) => Promise<T>;
+};
+
+type DefineToolOptions<TInput, TResult extends ToolReturn = ToolReturn> = {
+    name: string;
+    description: string;
+    input: ZodSchema<TInput>;
+    execute: (input: TInput, ctx: ToolContext) => Promise<TResult> | TResult;
+};
+type Tool = {
+    name: string;
+    description: string;
+    definition: ToolDefinition;
+    executeRaw: (rawArgsJson: string, ctx: ToolContext) => Promise<ToolResult>;
+};
+type ToolExecution = {
+    message: ToolMessage;
+    done?: boolean;
+    finalMessage?: string;
+};
+
+type ToolPermissionDecision = {
+    decision: "allow" | "deny";
+    reason?: string;
+    stop_turn?: boolean;
+};
+type ToolPermissionHook = (call: ToolCall, rawArgs: string, ctx: ToolContext) => Promise<ToolPermissionDecision> | ToolPermissionDecision;
+
+type SessionHeader = {
+    type: "header";
+    schema_version: 1;
+    run_id: string;
+    session_id?: string;
+    started_at: string;
+    client?: {
+        name: string;
+        version: string;
+    };
+    server?: {
+        name: string;
+        version: string;
+    };
+    model?: {
+        provider?: string;
+        name?: string;
+        reasoning?: string;
+    };
+    prompts?: {
+        system?: string;
+    };
+    tools?: {
+        definitions?: ToolDefinition[];
+        source?: string;
+    };
+    runtime?: {
+        cwd?: string;
+        os?: string;
+        arch?: string;
+        version?: string;
+    };
+    meta?: Record<string, unknown>;
+};
+type RunStartRecord = {
+    type: "run.start";
+    run_id: string;
+    session_id?: string;
+    ts: string;
+    input: {
+        type: "text";
+        text: string;
+    };
+    ui_context?: unknown;
+    meta?: Record<string, unknown>;
+};
+type RunContextRecord = {
+    type: "run.context";
+    run_id: string;
+    ts: string;
+    context_left_percent: number;
+    meta?: Record<string, unknown>;
+};
+type AgentEventRecord = {
+    type: "agent.event";
+    run_id: string;
+    ts: string;
+    seq: number;
+    event: AgentEvent;
+    meta?: Record<string, unknown>;
+};
+type ToolOutputRecord = {
+    type: "tool.output";
+    run_id: string;
+    ts: string;
+    tool: string;
+    tool_call_id: string;
+    result_raw: string;
+    is_error?: boolean;
+    output_ref?: ToolOutputRef;
+    meta?: Record<string, unknown>;
+};
+type LlmRequestRecord = {
+    type: "llm.request";
+    run_id: string;
+    ts: string;
+    seq: number;
+    model?: {
+        provider?: string;
+        name?: string;
+        reasoning?: string;
+    };
+    input: {
+        messages: BaseMessage[];
+        tools?: ToolDefinition[] | null;
+        tool_choice?: ToolChoice | null;
+        model?: string;
+    };
+    meta?: Record<string, unknown>;
+};
+type LlmResponseRecord = {
+    type: "llm.response";
+    run_id: string;
+    ts: string;
+    seq: number;
+    output: {
+        messages: BaseMessage[];
+        usage?: ChatInvokeUsage | null;
+        stop_reason?: string | null;
+        provider_meta?: unknown;
+    };
+    meta?: Record<string, unknown>;
+};
+type RunStatusRecord = {
+    type: "run.status";
+    run_id: string;
+    ts: string;
+    status: "running" | "awaiting_ui" | "completed" | "error" | "cancelled";
+    message?: string;
+    meta?: Record<string, unknown>;
+};
+type RunErrorRecord = {
+    type: "run.error";
+    run_id: string;
+    ts: string;
+    error: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    meta?: Record<string, unknown>;
+};
+type RunEndRecord = {
+    type: "run.end";
+    run_id: string;
+    ts: string;
+    outcome: "completed" | "cancelled" | "error";
+    final?: string;
+    meta?: Record<string, unknown>;
+};
+type SessionRecord = SessionHeader | RunStartRecord | RunContextRecord | AgentEventRecord | ToolOutputRecord | LlmRequestRecord | LlmResponseRecord | RunStatusRecord | RunErrorRecord | RunEndRecord;
+type SessionStore = {
+    append: (record: SessionRecord) => Promise<void> | void;
+};
+type RunEventStoreInit = {
+    runId: string;
+    startedAt: string;
+};
+type RunEventStoreFactory = {
+    create: (init: RunEventStoreInit) => SessionStore;
+};
+type SessionState = {
+    schema_version: 1;
+    session_id: string;
+    updated_at: string;
+    run_id?: string;
+    invoke_seq?: number;
+    messages: BaseMessage[];
+    meta?: Record<string, unknown>;
+};
+type SessionStateSummary = SessionStateSummary$1;
+type SessionStateStore = {
+    load: (sessionId: string) => Promise<SessionState | null>;
+    save: (state: SessionState) => Promise<void>;
+    list: () => Promise<SessionStateSummary[]>;
+};
+type AgentSession = {
+    run_id: string;
+    session_id?: string;
+    invoke_seq?: number;
+    on_error?: (error: unknown, record: SessionRecord) => void;
+    append: (record: SessionRecord) => void;
+};
+
+type AgentRunOptions = {
+    session?: AgentSession;
+    signal?: AbortSignal;
+    forceCompaction?: boolean;
+};
+type AgentOptions = {
+    llm: BaseChatModel;
+    tools: Tool[];
+    systemPrompt?: string;
+    maxIterations?: number;
+    toolChoice?: ToolChoice;
+    compaction?: CompactionConfig | null;
+    toolOutputCache?: ToolOutputCacheConfig | null;
+    services?: AgentServices;
+    modelRegistry?: ModelRegistry;
+    enableUsageTracking?: boolean;
+    requireDoneTool?: boolean;
+    llmMaxRetries?: number;
+    llmRetryBaseDelayMs?: number;
+    llmRetryMaxDelayMs?: number;
+    llmRetryableStatusCodes?: number[];
+    canExecuteTool?: ToolPermissionHook;
+};
+declare class Agent {
+    private readonly llm;
+    private readonly tools;
+    private readonly systemPrompt?;
+    private readonly maxIterations;
+    private readonly toolChoice?;
+    private readonly requireDoneTool;
+    private readonly compactionService?;
+    private readonly toolOutputCacheService?;
+    private readonly services;
+    private readonly modelRegistry;
+    private readonly canExecuteTool?;
+    private history;
+    private usageService;
+    constructor(options: AgentOptions);
+    getUsageSummary(): UsageSummary;
+    getContextLeftPercent(): number | null;
+    getHistoryMessages(): BaseMessage[];
+    replaceHistoryMessages(messages: BaseMessage[]): void;
+    private checkAndCompact;
+    private trimToolOutputs;
+    private processToolMessage;
+    private buildToolContext;
+    private recordLlmRequest;
+    private recordLlmResponse;
+    run(message: string, options?: AgentRunOptions): Promise<string>;
+    runStream(message: string, options?: AgentRunOptions): AsyncGenerator<AgentEvent>;
+    private generateFinalResponse;
+    private executeToolCall;
+}
+
+type StringifyContentMode = "display" | "log";
+type StringifyContentOptions = {
+    mode?: StringifyContentMode;
+    joiner?: string;
+    includeOtherPayload?: boolean;
+};
+declare const stringifyContentParts: (content: ContentPart[], options?: StringifyContentOptions) => string;
+declare const stringifyContent: (content: string | ContentPart[] | null | undefined, options?: StringifyContentOptions) => string;
+
+type StorageLayout = "home" | "xdg";
+type StoragePaths = {
+    root: string;
+    configDir: string;
+    configFile: string;
+    authFile: string;
+    mcpAuthFile: string;
+    cacheDir: string;
+    toolOutputCacheDir: string;
+    sessionsDir: string;
+    logsDir: string;
+};
+type ResolveStorageOptions = {
+    layout?: StorageLayout;
+    rootOverride?: string;
+};
+interface StoragePathService {
+    resolvePaths(options?: ResolveStorageOptions): StoragePaths;
+}
+
+declare const PROVIDER_NAME$1: "anthropic";
+type AnthropicMessageCreateParams = MessageCreateParamsNonStreaming;
+type AnthropicInvokeOptions = Omit<AnthropicMessageCreateParams, "model" | "messages" | "tools" | "tool_choice" | "system" | "stream">;
+type ChatAnthropicOptions = {
+    client?: Anthropic;
+    clientOptions?: ConstructorParameters<typeof Anthropic>[0];
+    model?: string;
+    maxTokens?: number;
+};
+declare class ChatAnthropic implements BaseChatModel<typeof PROVIDER_NAME$1, AnthropicInvokeOptions> {
+    readonly provider: typeof PROVIDER_NAME$1;
+    readonly model: string;
+    private readonly client;
+    private readonly defaultMaxTokens;
+    constructor(options?: ChatAnthropicOptions);
+    ainvoke(input: ChatInvokeInput & {
+        options?: AnthropicInvokeOptions;
+    }, verbose?: boolean): Promise<ChatInvokeCompletion>;
+}
+
+declare const PROVIDER_NAME: "openai";
+type OpenAITextVerbosity = Exclude<ResponseTextConfig["verbosity"], null>;
+type OpenAIInvokeOptions = Omit<ResponseCreateParamsBase, "model" | "input" | "tools" | "tool_choice" | "stream"> & {
+    reasoningEffort?: ReasoningEffort;
+    textVerbosity?: OpenAITextVerbosity;
+};
+type ChatOpenAIOptions = {
+    client?: OpenAI;
+    clientOptions?: ClientOptions;
+    model?: string;
+    reasoningEffort?: ReasoningEffort;
+    textVerbosity?: OpenAITextVerbosity;
+};
+declare class ChatOpenAI implements BaseChatModel<typeof PROVIDER_NAME, OpenAIInvokeOptions> {
+    readonly provider: typeof PROVIDER_NAME;
+    readonly model: string;
+    private readonly client;
+    private readonly defaultReasoningEffort?;
+    private readonly defaultTextVerbosity?;
+    constructor(options?: ChatOpenAIOptions);
+    ainvoke(input: ChatInvokeInput & {
+        options?: OpenAIInvokeOptions;
+    }, verbose?: boolean): Promise<ChatInvokeCompletion>;
+}
+
+declare const ANTHROPIC_DEFAULT_MODEL = "claude-sonnet-4-5";
+declare const ANTHROPIC_MODELS: ModelSpec[];
+
+declare const GOOGLE_MODELS: ModelSpec[];
+
+declare const OPENAI_DEFAULT_MODEL = "gpt-5.2-codex";
+declare const OPENAI_DEFAULT_REASONING_EFFORT = "medium";
+declare const OPENAI_MODELS: ModelSpec[];
+
+declare const DEFAULT_MODEL_REGISTRY: ModelRegistry;
+
+declare const getDefaultSystemPromptPath: () => string;
+
+declare function defineTool<TInput, TResult extends ToolReturn>(toolOptions: DefineToolOptions<TInput, TResult>): Tool;
+
+declare class TaskComplete extends Error {
+    readonly finalMessage?: string;
+    constructor(finalMessage?: string);
+}
+
+export { ANTHROPIC_DEFAULT_MODEL, ANTHROPIC_MODELS, Agent, type AgentEventRecord, type AgentOptions, type AgentRunOptions, type AgentServices, type AgentSession, type BaseChatModel, type BaseMessage, ChatAnthropic, type ChatInvokeInput, ChatOpenAI, type ContentPart, DEFAULT_MODEL_REGISTRY, type DependencyKey, GOOGLE_MODELS, type LlmRequestRecord, type LlmResponseRecord, type ModelCost, type ModelEntry, type ModelLimits, type ModelMetadataIndex, type ModelMetadataService, type ModelRegistry, type ModelSpec, OPENAI_DEFAULT_MODEL, OPENAI_DEFAULT_REASONING_EFFORT, OPENAI_MODELS, type ResolveStorageOptions, type RunContextRecord, type RunEndRecord, type RunErrorRecord, type RunEventStoreFactory, type RunEventStoreInit, type RunStartRecord, type RunStatusRecord, type SessionHeader, type SessionRecord, type SessionState, type SessionStateStore, type SessionStateSummary, type SessionStore, type StorageLayout, type StoragePathService, type StoragePaths, type StringifyContentMode, type StringifyContentOptions, TaskComplete, type Tool, type ToolContext, type ToolDefinition, type ToolExecution, type ToolOutputCacheConfig, type ToolOutputCacheReadOptions, type ToolOutputCacheRecord, type ToolOutputCacheSearchOptions, ToolOutputCacheService, type ToolOutputCacheStore, type ToolOutputRecord, type ToolOutputRef, type ToolPermissionDecision, type ToolPermissionHook, applyModelMetadata, createModelRegistry, defineTool, getDefaultSystemPromptPath, listModels, registerModels, resolveModel, stringifyContent, stringifyContentParts };