@byfriends/kosong 0.1.0 → 0.2.1

package/dist/{anthropic-Dm_GqFgS.d.mts → anthropic-0CVG5rBE.d.mts}

@@ -1,5 +1,4 @@
-import { a as StreamedMessage, b as Message, i as ProviderRequestAuth, m as ModelCapability, o as ThinkingEffort, p as Tool, r as GenerateOptions, t as ChatProvider } from "./provider-DiJKWMsQ.mjs";
-import { o as ChatProviderError } from "./errors-DweKbIOf.mjs";
+import { P as Message, S as ModelCapability, d as StreamedMessage, f as ThinkingEffort, l as GenerateOptions, o as ChatProviderError, s as ChatProvider, u as ProviderRequestAuth, x as Tool } from "./errors-wlT14tC4.mjs";
 import Anthropic from "@anthropic-ai/sdk";
 import { MessageCreateParams } from "@anthropic-ai/sdk/resources/messages/messages.js";
 

package/dist/{provider-DiJKWMsQ.d.mts → errors-wlT14tC4.d.mts}

@@ -38,6 +38,18 @@ interface VideoURLPart {
  * {@link ChatProvider.generate}.
  */
 type ContentPart = TextPart | ThinkPart | ImageURLPart | AudioURLPart | VideoURLPart;
+/**
+ * Cache hint metadata attached to a {@link Message}.
+ *
+ * Used by the cache staking layer to signal which messages are good
+ * cache breakpoint candidates (e.g. the last message of a previous turn).
+ * The Anthropic adapter reads these hints to inject `cache_control` on
+ * the appropriate content blocks.
+ */
+interface CacheHint {
+  readonly isLastTurnEnd?: boolean;
+  readonly isSuddenLargeContext?: boolean;
+}
 interface ToolCall {
   type: 'function';
   id: string;
@@ -100,6 +112,8 @@ interface Message {
   toolCallId?: string;
   /** When `true`, indicates the message was not fully received (e.g. stream interrupted). */
   partial?: boolean;
+  /** Cache hint metadata for prompt caching strategies. */
+  cacheHint?: CacheHint;
 }
 /** Check if a streamed part is a ContentPart (text, think, image_url, audio_url, video_url). */
 declare function isContentPart(part: StreamedMessagePart): part is ContentPart;
@@ -140,7 +154,146 @@ declare function createAssistantMessage(content: ContentPart[], toolCalls?: Tool
 /** Create a tool result message. */
 declare function createToolMessage(toolCallId: string, output: string | ContentPart[]): Message;
 //#endregion
+//#region src/prompt-plan.d.ts
+/**
+ * Cache scope for a {@link PromptBlock} in a {@link PromptPlan}.
+ *
+ * Scopes determine the lifetime and sharing boundaries of cached prompt
+ * content, allowing providers to apply cache-breaking policies appropriately.
+ *
+ * - `'global'`: Content is cacheable across all projects/sessions. Useful for
+ *   stable system prompts that rarely change.
+ * - `'project'`: Content is cacheable within a single project. Typical for
+ *   project-specific instructions, domain knowledge, or coding standards.
+ * - `'session'`: Content is cacheable only within the current session.
+ *   Appropriate for conversation context that persists across turns but not
+ *   across sessions.
+ * - `'none'`: Content is not cacheable. Use for ephemeral or highly dynamic
+ *   content (user input, temporary context, rapidly changing data).
+ */
+type CacheScope = 'global' | 'project' | 'session' | 'none';
+/**
+ * Cache strategy supported by a provider.
+ *
+ * Each provider advertises which caching mechanism it implements via
+ * {@link ProviderCacheCapability.strategy}. Consumers must respect this
+ * when constructing {@link PromptPlan}s to avoid sending unsupported
+ * cache directives.
+ *
+ * - `'explicit-block'`: Provider supports explicit cache control at the
+ *   block level (e.g., Anthropic's `cache_control` headers). Each
+ *   {@link PromptBlock} can be independently marked as cacheable.
+ * - `'prompt-cache-key'`: Provider supports a cache key that spans the
+ *   entire prompt (OpenAI's `prompt_cache_key` approach).
+ * - `'prefix-match'`: Provider caches by matching prompt prefixes
+ *   (OpenAI's automatic prefix caching for repeated prefixes).
+ *   Reserved for future use — no provider currently declares this strategy.
+ * - `'none'`: Provider does not support prompt caching.
+ */
+type CacheStrategy = 'explicit-block' | 'prompt-cache-key' | 'prefix-match' | 'none';
+/**
+ * A single named block of text with an associated cache scope.
+ *
+ * {@link PromptPlan}s are composed of multiple blocks, each with its own
+ * caching semantics. This structure allows providers to apply different
+ * cache policies to different parts of the system prompt (e.g., global
+ * instructions vs. session-specific context).
+ *
+ * @readonly
+ */
+interface PromptBlock {
+  /**
+   * Identifier for this block.
+   *
+   * Used for debugging, logging, and potentially for cache key generation.
+   * Should be stable and descriptive (e.g., `'system-instructions'`,
+   * `'project-context'`).
+   */
+  readonly name: string;
+  /**
+   * Text content of this block.
+   *
+   * The actual prompt text that will be sent to the LLM. Blocks are
+   * typically concatenated in order when constructing the full system
+   * prompt.
+   */
+  readonly text: string;
+  /**
+   * Cache scope for this block.
+   *
+   * Determines how providers may cache this content. See {@link CacheScope}
+   * for details on each scope's semantics.
+   */
+  readonly cacheScope: CacheScope;
+}
+/**
+ * A structured prompt plan that defines cacheable blocks.
+ *
+ * PromptPlans allow consumers to provide explicit caching hints alongside
+ * their prompt content. When passed via {@link GenerateOptions.promptPlan},
+ * providers that support caching can translate the plan into their native
+ * cache control format.
+ *
+ * Example usage:
+ * ```ts
+ * const plan: PromptPlan = {
+ *   blocks: [
+ *     { name: 'system', text: 'You are a helpful assistant.', cacheScope: 'global' },
+ *     { name: 'project', text: 'Project-specific rules...', cacheScope: 'project' },
+ *     { name: 'context', text: 'Current session context...', cacheScope: 'session' },
+ *     { name: 'user-query', text: 'Answer this question...', cacheScope: 'none' },
+ *   ],
+ * };
+ * ```
+ *
+ * @readonly
+ */
+interface PromptPlan {
+  /**
+   * Ordered list of blocks that compose this prompt plan.
+   *
+   * Blocks are typically concatenated in order when constructing the full
+   * system prompt. Each block's `cacheScope` determines its caching
+   * semantics.
+   */
+  readonly blocks: readonly PromptBlock[];
+}
+//#endregion
 //#region src/capability.d.ts
+/**
+ * Cache capability advertised by a provider.
+ *
+ * Providers that support prompt caching expose this via
+ * {@link ModelCapability.cache} to describe which caching mechanisms they
+ * implement and any constraints consumers must respect.
+ *
+ * @readonly
+ */
+interface ProviderCacheCapability {
+  /**
+   * The caching strategy supported by this provider.
+   *
+   * See {@link CacheStrategy} for strategy descriptions and semantics.
+   */
+  readonly strategy: CacheStrategy;
+  /**
+   * Maximum number of cacheable blocks supported.
+   *
+   * Only applicable for `'explicit-block'` strategy. Providers may limit
+   * the number of distinct cache points they support (e.g., Anthropic
+   * supports up to 4 cache breakpoints). Omitted means "unknown" or "no
+   * practical limit."
+   */
+  readonly maxCacheableBlocks?: number;
+  /**
+   * Cache scopes supported by this provider.
+   *
+   * Providers may not support all scopes (e.g., some may not support
+   * `'global'` scoping). When omitted, consumers should assume all scopes
+   * are supported.
+   */
+  readonly supportedScopes?: readonly CacheScope[];
+}
 /**
  * Declared capabilities for a specific model exposed by a {@link ChatProvider}.
  *
@@ -157,7 +310,18 @@ interface ModelCapability {
   readonly audio_in: boolean;
   readonly thinking: boolean;
   readonly tool_use: boolean;
+  readonly thinking_effort: boolean;
+  readonly thinking_xhigh: boolean;
+  readonly thinking_max: boolean;
   readonly max_context_tokens: number;
+  /**
+   * Cache capability for this model.
+   *
+   * Present when the provider supports prompt caching. Consumers can inspect
+   * this field to determine which caching strategies and scopes are
+   * available, then construct appropriate {@link PromptPlan}s.
+   */
+  readonly cache?: ProviderCacheCapability;
 }
 /**
  * Shared read-only default returned when a provider has not catalogued a
@@ -217,6 +381,19 @@ declare function emptyUsage(): TokenUsage;
  * Sum two TokenUsage values.
  */
 declare function addUsage(a: TokenUsage, b: TokenUsage): TokenUsage;
+/**
+ * Branded type for cache hit rate to avoid accidental misuse as a raw number.
+ */
+type CacheHitRate = number & {
+  readonly __brand: unique symbol;
+};
+/**
+ * Compute the cache hit rate as a branded number between 0 and 1.
+ *
+ * Returns `undefined` when no input tokens were processed (inputTotal === 0),
+ * so callers can distinguish "no data" from "zero hits".
+ */
+declare function cacheHitRate(usage: TokenUsage): CacheHitRate | undefined;
 //#endregion
 //#region src/provider.d.ts
 /**
@@ -304,6 +481,13 @@ interface GenerateOptions {
    * each request/retry so providers never retain mutable credential state.
    */
   auth?: ProviderRequestAuth;
+  /**
+   * Structured prompt plan with explicit cache scoping.
+   *
+   * When provided, providers that support caching may translate this into
+   * their native cache control format.
+   */
+  promptPlan?: PromptPlan;
 }
 /**
  * In-memory video bytes for providers that require an uploaded file
@@ -347,7 +531,7 @@ interface ChatProvider {
    *
    * Implementations MUST NOT mutate or replace internal HTTP clients on the
    * returned clone — the clone is expected to share transport state with the
-   * original. See `OpenAICompatChatProvider._clone()` for the rationale.
+   * original. See `OpenAICompletionsChatProvider._clone()` for the rationale.
    */
   withMaxCompletionTokens?(maxCompletionTokens: number): ChatProvider;
   /** Upload a video and return a content part that can be sent to this provider. */
@@ -368,4 +552,45 @@ interface ChatProvider {
   getContextSizeLimit?(): number | undefined;
 }
 //#endregion
-export { createUserMessage as A, TextPart as C, VideoURLPart as D, ToolCallPart as E, mergeInPlace as F, isContentPart as M, isToolCall as N, createAssistantMessage as O, isToolCallPart as P, StreamedMessagePart as S, ToolCall as T, AudioURLPart as _, StreamedMessage as a, Message as b, TokenUsage as c, grandTotal as d, inputTotal as f, isUnknownCapability as g, UNKNOWN_CAPABILITY as h, ProviderRequestAuth as i, extractText as j, createToolMessage as k, addUsage as l, ModelCapability as m, FinishReason as n, ThinkingEffort as o, Tool as p, GenerateOptions as r, VideoUploadInput as s, ChatProvider as t, emptyUsage as u, ContentPart as v, ThinkPart as w, Role as x, ImageURLPart as y };
+//#region src/errors.d.ts
+/**
+ * Base error for all chat provider errors.
+ */
+declare class ChatProviderError extends Error {
+  constructor(message: string);
+}
+/**
+ * Network-level connection failure.
+ */
+declare class APIConnectionError extends ChatProviderError {
+  constructor(message: string);
+}
+/**
+ * Request timed out.
+ */
+declare class APITimeoutError extends ChatProviderError {
+  constructor(message: string);
+}
+/**
+ * HTTP status error from the API.
+ */
+declare class APIStatusError extends ChatProviderError {
+  readonly statusCode: number;
+  readonly requestId: string | null;
+  constructor(statusCode: number, message: string, requestId?: string | null);
+}
+/**
+ * HTTP status error that specifically means the request exceeded the model
+ * context window.
+ */
+declare class APIContextOverflowError extends APIStatusError {
+  constructor(statusCode: number, message: string, requestId?: string | null);
+}
+/**
+ * The API returned an empty response (no content, no tool calls).
+ */
+declare class APIEmptyResponseError extends ChatProviderError {
+  constructor(message: string);
+}
+//#endregion
+export { AudioURLPart as A, ToolCallPart as B, ProviderCacheCapability as C, CacheStrategy as D, CacheScope as E, Role as F, extractText as G, createAssistantMessage as H, StreamedMessagePart as I, isToolCallPart as J, isContentPart as K, TextPart as L, ContentPart as M, ImageURLPart as N, PromptBlock as O, Message as P, ThinkPart as R, ModelCapability as S, isUnknownCapability as T, createToolMessage as U, VideoURLPart as V, createUserMessage as W, mergeInPlace as Y, cacheHitRate as _, APITimeoutError as a, inputTotal as b, FinishReason as c, StreamedMessage as d, ThinkingEffort as f, addUsage as g, TokenUsage as h, APIStatusError as i, CacheHint as j, PromptPlan as k, GenerateOptions as l, CacheHitRate as m, APIContextOverflowError as n, ChatProviderError as o, VideoUploadInput as p, isToolCall as q, APIEmptyResponseError as r, ChatProvider as s, APIConnectionError as t, ProviderRequestAuth as u, emptyUsage as v, UNKNOWN_CAPABILITY as w, Tool as x, grandTotal as y, ToolCall as z };

package/dist/{google-genai-hX0X6CF3.d.mts → google-genai-xKK8lI_R.d.mts}

@@ -1,5 +1,4 @@
-import { S as StreamedMessagePart, a as StreamedMessage, b as Message, c as TokenUsage, i as ProviderRequestAuth, m as ModelCapability, n as FinishReason, o as ThinkingEffort, p as Tool, r as GenerateOptions, t as ChatProvider } from "./provider-DiJKWMsQ.mjs";
-import { o as ChatProviderError } from "./errors-DweKbIOf.mjs";
+import { I as StreamedMessagePart, P as Message, S as ModelCapability, c as FinishReason, d as StreamedMessage, f as ThinkingEffort, h as TokenUsage, l as GenerateOptions, o as ChatProviderError, s as ChatProvider, u as ProviderRequestAuth, x as Tool } from "./errors-wlT14tC4.mjs";
 import { GoogleGenAI } from "@google/genai";
 
 //#region src/providers/google-genai.d.ts

package/dist/index.d.mts

@@ -1,19 +1,53 @@
-import { A as createUserMessage, C as TextPart, D as VideoURLPart, E as ToolCallPart, F as mergeInPlace, M as isContentPart, N as isToolCall, O as createAssistantMessage, P as isToolCallPart, S as StreamedMessagePart, T as ToolCall, _ as AudioURLPart, a as StreamedMessage, b as Message, c as TokenUsage, d as grandTotal, f as inputTotal, g as isUnknownCapability, h as UNKNOWN_CAPABILITY, i as ProviderRequestAuth, j as extractText, k as createToolMessage, l as addUsage, m as ModelCapability, n as FinishReason, o as ThinkingEffort, p as Tool, r as GenerateOptions, s as VideoUploadInput, t as ChatProvider, u as emptyUsage, v as ContentPart, w as ThinkPart, x as Role, y as ImageURLPart } from "./provider-DiJKWMsQ.mjs";
-import { a as APITimeoutError, i as APIStatusError, n as APIContextOverflowError, o as ChatProviderError, r as APIEmptyResponseError, t as APIConnectionError } from "./errors-DweKbIOf.mjs";
-import { n as AnthropicOptions } from "./anthropic-Dm_GqFgS.mjs";
-import { r as GoogleGenAIOptions } from "./google-genai-hX0X6CF3.mjs";
-import { i as OpenAICompatOptions } from "./openai-compat-CMrIk-ib.mjs";
-import { r as OpenAILegacyOptions } from "./openai-legacy-B6CVfLlr.mjs";
-import { r as OpenAIResponsesOptions } from "./openai-responses-BxOwxtd3.mjs";
+import { A as AudioURLPart, B as ToolCallPart, C as ProviderCacheCapability, D as CacheStrategy, E as CacheScope, F as Role, G as extractText, H as createAssistantMessage, I as StreamedMessagePart, J as isToolCallPart, K as isContentPart, L as TextPart, M as ContentPart, N as ImageURLPart, O as PromptBlock, P as Message, R as ThinkPart, S as ModelCapability, T as isUnknownCapability, U as createToolMessage, V as VideoURLPart, W as createUserMessage, Y as mergeInPlace, _ as cacheHitRate, a as APITimeoutError, b as inputTotal, c as FinishReason, d as StreamedMessage, f as ThinkingEffort, g as addUsage, h as TokenUsage, i as APIStatusError, j as CacheHint, k as PromptPlan, l as GenerateOptions, m as CacheHitRate, n as APIContextOverflowError, o as ChatProviderError, p as VideoUploadInput, q as isToolCall, r as APIEmptyResponseError, s as ChatProvider, t as APIConnectionError, u as ProviderRequestAuth, v as emptyUsage, w as UNKNOWN_CAPABILITY, x as Tool, y as grandTotal, z as ToolCall } from "./errors-wlT14tC4.mjs";
+import { n as AnthropicOptions } from "./anthropic-0CVG5rBE.mjs";
+import { r as GoogleGenAIOptions } from "./google-genai-xKK8lI_R.mjs";
+import { i as ToolMessageConversion } from "./openai-common-DwkxUSyI.mjs";
+import { r as OpenAIResponsesOptions } from "./openai-responses-DZ9mQ5RA.mjs";
+import OpenAI from "openai";
 
+//#region src/providers/openai-completions.d.ts
+interface OpenAICompletionsOptions {
+  apiKey?: string;
+  baseUrl?: string;
+  model: string;
+  stream?: boolean;
+  defaultHeaders?: Record<string, string>;
+  thinkingEffortKey?: string;
+  reasoningKey?: string;
+  toolMessageConversion?: ToolMessageConversion;
+  generationKwargs?: GenerationKwargs;
+  clientFactory?: (auth: ProviderRequestAuth) => OpenAI;
+}
+interface GenerationKwargs {
+  max_tokens?: number | undefined;
+  max_completion_tokens?: number | undefined;
+  temperature?: number | undefined;
+  top_p?: number | undefined;
+  n?: number | undefined;
+  presence_penalty?: number | undefined;
+  frequency_penalty?: number | undefined;
+  stop?: string | string[] | undefined;
+  reasoning_effort?: string | undefined;
+  prompt_cache_key?: string | undefined;
+  extra_body?: ExtraBody;
+  [key: string]: unknown;
+}
+interface ThinkingConfig {
+  type?: 'enabled' | 'disabled';
+  keep?: unknown;
+  [key: string]: unknown;
+}
+interface ExtraBody {
+  thinking?: ThinkingConfig;
+  [key: string]: unknown;
+}
+//#endregion
 //#region src/providers/index.d.ts
 type ProviderConfig = ({
   type: 'anthropic';
 } & AnthropicOptions) | ({
-  type: 'openai';
-} & OpenAILegacyOptions) | ({
-  type: 'openai-compat';
-} & OpenAICompatOptions) | ({
+  type: 'openai-completions';
+} & OpenAICompletionsOptions) | ({
   type: 'google-genai';
 } & GoogleGenAIOptions) | ({
   type: 'openai_responses';
@@ -23,6 +57,14 @@ type ProviderConfig = ({
 type ProviderType = ProviderConfig['type'];
 declare function createProvider(config: ProviderConfig): ChatProvider;
 //#endregion
+//#region src/providers/capability-registry.d.ts
+/**
+ * Tries all provider-specific capability registries and returns the first
+ * non-UNKNOWN match. Used when the provider context is unknown (e.g., catalog
+ * enrichment) to fill in accurate thinking capability flags.
+ */
+declare function resolveCapabilityFromRegistry(modelName: string): ModelCapability | undefined;
+//#endregion
 //#region src/catalog.d.ts
 /**
  * models.dev-style catalog: a public map of provider/model metadata. Callers
@@ -118,6 +160,18 @@ interface GenerateResult {
    * `null` if the provider did not emit one.
    */
   readonly rawFinishReason: string | null;
+  /**
+   * Milliseconds between the `provider.generate()` call and the first
+   * streamed chunk. `undefined` when the stream produced no chunks
+   * (empty response, early abort, or error).
+   */
+  readonly llmFirstTokenLatencyMs?: number | undefined;
+  /**
+   * Milliseconds between the `provider.generate()` call and stream
+   * exhaustion (last chunk consumed). `undefined` when the stream
+   * produced no chunks (empty response, early abort, or error).
+   */
+  readonly llmStreamDurationMs?: number | undefined;
 }
 interface GenerateCallbacks {
   onMessagePart?: (part: StreamedMessagePart) => void | Promise<void>;
@@ -158,4 +212,4 @@ interface GenerateCallbacks {
  */
 declare function generate(provider: ChatProvider, systemPrompt: string, tools: Tool[], history: Message[], callbacks?: GenerateCallbacks, options?: GenerateOptions): Promise<GenerateResult>;
 //#endregion
-export { APIConnectionError, APIContextOverflowError, APIEmptyResponseError, APIStatusError, APITimeoutError, type AudioURLPart, type Catalog, type CatalogModel, type CatalogModelEntry, type CatalogProviderEntry, ChatProvider, ChatProviderError, type ContentPart, FinishReason, type GenerateCallbacks, GenerateOptions, type GenerateResult, type ImageURLPart, type Message, type ModelCapability, type ProviderConfig, ProviderRequestAuth, type ProviderType, type Role, StreamedMessage, type StreamedMessagePart, type TextPart, type ThinkPart, ThinkingEffort, type TokenUsage, type Tool, type ToolCall, type ToolCallPart, UNKNOWN_CAPABILITY, type VideoURLPart, VideoUploadInput, addUsage, catalogBaseUrl, catalogModelToCapability, catalogProviderModels, createAssistantMessage, createProvider, createToolMessage, createUserMessage, emptyUsage, extractText, generate, grandTotal, inferWireType, inputTotal, isContentPart, isToolCall, isToolCallPart, isUnknownCapability, mergeInPlace };
+export { APIConnectionError, APIContextOverflowError, APIEmptyResponseError, APIStatusError, APITimeoutError, type AudioURLPart, type CacheHint, type CacheHitRate, type CacheScope, type CacheStrategy, type Catalog, type CatalogModel, type CatalogModelEntry, type CatalogProviderEntry, ChatProvider, ChatProviderError, type ContentPart, FinishReason, type GenerateCallbacks, GenerateOptions, type GenerateResult, type ImageURLPart, type Message, type ModelCapability, type PromptBlock, type PromptPlan, type ProviderCacheCapability, type ProviderConfig, ProviderRequestAuth, type ProviderType, type Role, StreamedMessage, type StreamedMessagePart, type TextPart, type ThinkPart, ThinkingEffort, type TokenUsage, type Tool, type ToolCall, type ToolCallPart, UNKNOWN_CAPABILITY, type VideoURLPart, VideoUploadInput, addUsage, cacheHitRate, catalogBaseUrl, catalogModelToCapability, catalogProviderModels, createAssistantMessage, createProvider, createToolMessage, createUserMessage, emptyUsage, extractText, generate, grandTotal, inferWireType, inputTotal, isContentPart, isToolCall, isToolCallPart, isUnknownCapability, mergeInPlace, resolveCapabilityFromRegistry };