@qilin-agent/llm 0.0.0-stage → 3.1.3

package/lib/types/types.d.ts

@@ -0,0 +1,532 @@
+/**
+ * Canonical provider-neutral message and streaming vocabulary for the loop,
+ * session log, and plugins. Adapters alone translate provider wire messages;
+ * mapped interfaces make the content, source, and finish unions extensible.
+ */
+import type { Branded } from '@qilin-agent/brand';
+import type { FileAttachmentRef, ImageAttachmentRef } from '@qilin-agent/attachment';
+import type { MessageId, ToolCallId, ProviderRequestId, ReasoningEffortId } from './brand.ts';
+import type { Message, UserMessage } from './message.ts';
+declare module '@qilin-agent/kylin' {
+    interface Events {
+        /**
+         * The provider topology changed: an adapter registered or unregistered
+         * routes, or the configurable-provider directory gained or lost entries.
+         * This payload-free registry notification fires at each commit point
+         * (including registration disposal); consumers re-read `listProviders()`,
+         * `listModels()`, or `listConfigurableProviders()` for the new state.
+         * Observer failures are contained and cannot veto the registry mutation.
+         * @mode emit
+         */
+        'llm/adapters-updated'(): void;
+    }
+}
+export type { AssistantMessage, DeveloperMessage, AssistantProviderMetadata, Message, MessageSource, MessageSourceMap, ModelMessageSource, ToolMessageSource, ToolResultMessage, UserMessage, } from './message.ts';
+/** Serializable provider or transport failure facts; policy decides whether they are retryable. */
+export interface LlmFailure {
+    /** Human-readable provider or transport failure. */
+    readonly message: string;
+    /** Stable provider-neutral machine-routing code. */
+    readonly code: string;
+    /** HTTP status returned by the provider, when available. */
+    readonly status?: number;
+    /** Provider-requested delay in milliseconds, when valid and available. */
+    readonly providerRetryAfterMs?: number;
+    /** Opaque provider-issued request identifier for diagnostics. */
+    readonly requestId?: ProviderRequestId;
+    /**
+     * With code `IMAGE_OFFLOAD_REQUIRED`: how many more of the oldest retained
+     * image occurrences the route needs offloaded before the same request fits
+     * its exact byte accounting. `qilin-compaction-image-offload` records the
+     * selected occurrences in an `image/offload` event and retries the step.
+     */
+    readonly offloadImages?: number;
+}
+/** Plain text visible to the end user. */
+export interface TextBlock {
+    type: 'text';
+    text: string;
+}
+/** Reasoning / thinking content, distinct from visible text. */
+export interface ReasoningBlock {
+    type: 'reasoning';
+    text: string;
+}
+/**
+ * A durable raster image reference, valid in user or assistant content. The
+ * block is deliberately role-neutral; assistant-side rendering is forward
+ * compatibility — the current production adapters declare text-only output,
+ * so only user messages may carry images.
+ */
+export interface ImageBlock {
+    type: 'image';
+    /** Immutable bytes and intrinsic display metadata owned by the attachment service. */
+    attachment: ImageAttachmentRef;
+    /**
+     * Derived from a durable image-offload decision or preserved by a message
+     * rewrite. Every route sends placeholder text naming the image and its
+     * available read-only path instead of image bytes.
+     */
+    offloaded?: true;
+}
+/**
+ * A durable verbatim file reference, valid in user content. Files never reach
+ * a provider natively: request assembly projects every occurrence to
+ * deterministic handle text (name, byte size, and the read-only saved path),
+ * so adapters and providers see text in its place while the durable log keeps
+ * the structured reference for presentation and authorization.
+ */
+export interface FileBlock {
+    type: 'file';
+    /** Immutable verbatim bytes and display metadata owned by the attachment service. */
+    attachment: FileAttachmentRef;
+}
+/** A tool invocation requested by the model. */
+export interface ToolCallBlock {
+    type: 'tool-call';
+    /** Provider-issued call id; correlates with the matching tool result. */
+    id: ToolCallId;
+    name: string;
+    /** Raw JSON string as produced by the model. */
+    arguments: string;
+}
+/** Activates a tool definition from the developer event's referenced request header. */
+export interface ToolAdditionBlock {
+    type: 'tool-addition';
+    /** Name of exactly one tool in the referenced historical header. */
+    toolName: string;
+    /**
+     * Reserved against inline definitions; the historical request header owns the schema.
+     * @persistenceReserved
+     */
+    tool?: never;
+}
+/** Records the dynamic removal of a tool identified by its session-local name. */
+export interface ToolRemovalBlock {
+    type: 'tool-removal';
+    toolName: string;
+}
+/**
+ * Merge-extensible content blocks keyed by `type`. New core blocks must land
+ * with adapter, UI, and compaction support. Tool-change blocks belong to
+ * developer messages; `projectToolUpdates` selects what each route receives.
+ */
+export interface ContentBlockMap {
+    'text': TextBlock;
+    'reasoning': ReasoningBlock;
+    'image': ImageBlock;
+    'file': FileBlock;
+    'tool-call': ToolCallBlock;
+    'tool-addition': ToolAdditionBlock;
+    'tool-removal': ToolRemovalBlock;
+}
+/** The block `type` tag vocabulary; widens as plugins add entries to {@link ContentBlockMap}. */
+export type ContentBlockType = keyof ContentBlockMap;
+/** Any known content block, derived from {@link ContentBlockMap}; switch on `type` and fall through unknowns (merge-extensible). */
+export type ContentBlock = ContentBlockMap[ContentBlockType];
+/**
+ * Why a model response stopped.
+ * Merge-extensible so adapters can surface provider-specific reasons.
+ */
+export interface FinishReasonMap {
+    'stop': {
+        kind: 'stop';
+    };
+    'tool-calls': {
+        kind: 'tool-calls';
+    };
+    'max-tokens': {
+        kind: 'max-tokens';
+    };
+    'aborted': {
+        kind: 'aborted';
+        failure: LlmFailure;
+    };
+    'error': {
+        kind: 'error';
+        failure: LlmFailure;
+    };
+}
+/** Any known finish reason, derived from {@link FinishReasonMap}; switch on `kind` and fall through unknowns (merge-extensible). */
+export type FinishReason = FinishReasonMap[keyof FinishReasonMap];
+/**
+ * Token accounting for one model call (cache fields are optional).
+ *
+ * Counts are DISJOINT: `inputTokens` is uncached input only; cached input is
+ * reported separately as `cacheReadTokens`/`cacheWriteTokens` (billed input =
+ * sum of the three). Adapters whose providers fold cache hits into a total
+ * prompt count (DeepSeek's `prompt_tokens`) subtract them out.
+ */
+export interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    /**
+     * Exact full-call total including aggregate prompt and output tokens.
+     *
+     * Adapters preserve a provider total or derive it from authoritative
+     * aggregate prompt/output counters; they omit it when unavailable or
+     * inconsistent.
+     */
+    totalTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    reasoningTokens?: number;
+}
+/**
+ * Request price of one ordered image occurrence under one exact model route's
+ * request projection. Every occurrence resolves to the pair the wire actually
+ * carries: provider visual tokens for a retained image, plus the model-visible
+ * text sent with or instead of it (request-preview handle, offload placeholder,
+ * or text-only substitution). The caller prices `text` with its own text
+ * estimator so provider pricing never fixes a text tokenization.
+ */
+export interface LlmImageRequestPrice {
+    /** Provider visual tokens for the retained request image; 0 when only text represents this occurrence. */
+    visualTokens: number;
+    /** Model-visible text sent for this occurrence, to be priced by the caller's text estimator. */
+    text: string;
+}
+/**
+ * Provider-side request-image pricing for one exact model route. Implemented
+ * by adapters whose provider charges visual tokens; consumers (the token
+ * meter) resolve it synchronously per measurement, so implementations must not
+ * perform I/O.
+ */
+export interface LlmImageRequestPricing {
+    /**
+     * Price every image occurrence of one request projection.
+     * @param images - surface image blocks in request order, one entry per occurrence; an `offloaded` block
+     *   is priced as its placeholder text.
+     * @returns one price per occurrence, aligned by index with `images`.
+     */
+    priceImages(images: readonly ImageBlock[]): readonly LlmImageRequestPrice[];
+}
+/** Display metadata for one registered provider route. */
+export interface LlmProviderInfo {
+    /** Provider route key used by {@link GenerateOptions.provider}. */
+    id: string;
+    /** Human-readable provider name for selectors and diagnostics. */
+    name: string;
+}
+/** Merge-extensible provider model modality vocabulary. */
+export interface ModelModalityMap {
+    text: 'text';
+    image: 'image';
+}
+/** Any declared provider model modality. */
+export type ModelModality = ModelModalityMap[keyof ModelModalityMap];
+/**
+ * One provider route an adapter plugin can activate through configuration,
+ * whether or not the route is currently registered. Configuration surfaces
+ * merge this directory with `listProviders()` to offer every configurable
+ * provider alongside its live/dormant state.
+ */
+export interface LlmConfigurableProvider {
+    /** Provider route key this entry activates when configured. */
+    provider: string;
+    /** Human-readable provider name for configuration surfaces. */
+    displayName: string;
+    /** User-settings namespace whose section configures this provider. */
+    settingsNs: string;
+    /**
+     * Path from that namespace's section root to this provider's profile
+     * object; empty when the whole section is the profile.
+     */
+    settingsPath: readonly string[];
+    /**
+     * Whether the owning adapter knows this route only because configuration
+     * declared it — a gateway or self-hosted server it ships nothing about.
+     * Absent means the adapter draws no such distinction; false means it does
+     * and this route is one of its own. Only the adapter can answer: a stored
+     * profile is how a user-added route AND a corrected shipped one both look
+     * from outside.
+     */
+    declared?: boolean;
+    /** Configuration diagnostic for repair; unaffected models may remain serviceable. */
+    error?: string;
+}
+/**
+ * One interrogation of a provider endpoint that configuration has not stored
+ * yet. Configuration surfaces send the draft a user is still editing, so the
+ * request carries the endpoint and credential directly instead of naming a
+ * route: a provider being added has no route to name.
+ */
+export interface LlmModelDiscoveryRequest {
+    /**
+     * Route the draft is editing, when it edits an existing one. A route whose
+     * adapter already knows its models answers from that knowledge instead of
+     * asking the endpoint — the adapter's own registry is the better answer, and
+     * it costs no network call.
+     */
+    provider?: string;
+    /**
+     * Endpoint to interrogate. Optional because a route the adapter already
+     * describes needs none; a route it does not must supply one.
+     */
+    baseURL?: string;
+    /** Wire protocol the endpoint speaks, when the draft names one. */
+    api?: string;
+    /** Credential for this interrogation alone; the harness never stores it. */
+    apiKey?: string;
+}
+/** Provider-side discovery request with operation-local cancellation attached. */
+export interface LlmModelDiscoveryOperation extends LlmModelDiscoveryRequest {
+    /** Caller cancellation; implementations must settle promptly after it aborts. */
+    signal?: AbortSignal;
+}
+declare module '@qilin-agent/typert-protocol' {
+    interface RemoteErrorDetailsMap {
+        /** A draft provider interrogation refused or failed. */
+        'llm/model-discovery-rejected': {
+            readonly settingsNs: string;
+            readonly baseURL?: string;
+        };
+    }
+}
+/**
+ * One model an endpoint reports about itself. Every field but the id is
+ * optional because most provider listings disclose an id and nothing else;
+ * a surface adopting one of these still owes the capacities its adapter needs.
+ */
+export interface LlmDiscoveredModel {
+    /** Model id the endpoint accepts. */
+    id: string;
+    /** Human-readable name when the endpoint supplies one. */
+    name?: string;
+    /** Maximum combined request and response context, when disclosed. */
+    contextWindow?: number;
+    /** Maximum output tokens, when disclosed. */
+    maxTokens?: number;
+    /** Accepted input types when disclosed by the catalog or endpoint; absent means unknown. */
+    inputModalities?: readonly ModelModality[];
+}
+/** One adapter-discovered model; catalog membership is advisory, not request validation. */
+export interface LlmModelInfo {
+    /** Provider route that owns this model entry. */
+    provider: string;
+    /** Model id passed to {@link GenerateOptions.model}. */
+    id: string;
+    /** Human-readable model name for selectors. */
+    name: string;
+    /** Optional user-facing distinction from otherwise similar models. */
+    description?: string;
+    /** Accepted request modalities; absent means unknown, while an explicit omission is negative capability. */
+    inputModalities?: readonly ModelModality[];
+}
+/** Provider-owned context capacity for one exact provider/model route. */
+export interface LlmModelContext {
+    /** Maximum combined request and response context in tokens. */
+    contextWindow: number;
+}
+/**
+ * Request-image budget one exact image-capable route enforces over the
+ * retained occurrences' exact request-version bytes; for the `base64`
+ * representation each byte count expands to its encoded length. A route whose
+ * retained occurrences exceed the budget fails the request with
+ * `IMAGE_OFFLOAD_REQUIRED` naming the additional occurrences to offload.
+ */
+export interface LlmImageRequestBudget {
+    /** Whether the route accounts raw file bytes or inline base64 length. */
+    representation: 'raw' | 'base64';
+    /** Accumulated represented image bytes the route accepts; absent leaves bytes unbounded. */
+    maxBytes?: number;
+    /** Image occurrences the route accepts; absent leaves the count unbounded. */
+    maxImages?: number;
+    /** Represented bytes removed as one deterministic advance step; absent removes the minimum. */
+    byteQuantum?: number;
+    /** Occurrences removed as one deterministic advance step; absent removes the minimum. */
+    countQuantum?: number;
+}
+/** Display metadata for one adapter-owned reasoning effort. */
+export interface LlmReasoningEffortInfo {
+    /** Opaque stable value accepted by {@link GenerateOptions.reasoningEffort}. */
+    id: ReasoningEffortId;
+    /** Human-readable effort name for selectors and diagnostics. */
+    name: string;
+    /** Optional user-facing distinction from otherwise similar efforts. */
+    description?: string;
+}
+/** Selectable reasoning efforts for one exact provider/model route. */
+export interface LlmModelReasoningInfo {
+    /** Supported efforts in adapter-preferred display order. */
+    efforts: readonly LlmReasoningEffortInfo[];
+    /**
+     * Adapter-configured default materialized into requests when callers omit
+     * an effort. Absence preserves the provider's own default.
+     */
+    defaultEffort?: ReasoningEffortId;
+}
+/**
+ * How a model applies a system prompt that changes mid-conversation.
+ * `'in-history'`: the model reads the latest `system` message at any position
+ * of `messages` as the complete effective system prompt, so a changed prompt
+ * can follow the cached history instead of rewriting message 0.
+ */
+export type SystemPromptUpdate = 'in-history';
+/**
+ * How a model accepts native tool declarations that change mid-conversation.
+ * `'addition-only'`: the model reads a `tool-addition` block in a later
+ * developer message as activating a tool declared with `deferLoading`, so an
+ * added tool follows the cached history instead of rewriting the declaration
+ * list. `'in-history'`: the model additionally reads `tool-removal` blocks,
+ * so a removed tool keeps its declaration and the removal follows the history.
+ * Absent means every request declares the complete current tool list.
+ */
+export type ToolUpdate = 'in-history' | 'addition-only';
+/** Exact-route model metadata resolved by its owning adapter. */
+export interface LlmResolvedModelInfo extends LlmModelInfo {
+    /** Provider-owned context capacity when known. */
+    context?: LlmModelContext;
+    /** Adapter-configured per-request output cap materialized when callers omit one. */
+    defaultMaxTokens?: number;
+    /** Adapter-owned selectable reasoning levels when exposed. */
+    reasoning?: LlmModelReasoningInfo;
+    /** Declared mid-conversation system prompt handling; absent means only a leading system message is read. */
+    systemPromptUpdate?: SystemPromptUpdate;
+    /** Declared mid-conversation tool declaration handling; absent means every request declares the complete tool list. */
+    toolUpdate?: ToolUpdate;
+}
+/**
+ * Adapter-private lossless-JSON state for replaying a successful response,
+ * carried by a terminal `finish` chunk and stored on the assembled assistant
+ * message's model source. Both halves stay opaque to the harness; only the
+ * split is shared vocabulary, so assembly can keep stored metadata aligned
+ * with stored content without reading either half.
+ */
+export interface ReplayEnvelope {
+    /** Response-level adapter-private metadata (ids, native stop reason). */
+    response: unknown;
+    /**
+     * Per-block adapter-private metadata, one entry per emitted block in
+     * first-seen stream order. When assembly drops a block it drops the entry at
+     * the same position; entries whose length does not match the emitted block
+     * count discard the whole envelope. An adapter whose metadata is independent
+     * of block structure omits this field and the envelope passes through
+     * assembly unchanged.
+     */
+    blocks?: readonly unknown[];
+}
+/**
+ * Raw streaming protocol emitted by adapters.
+ * Block indexes correlate interleaved deltas, and `block-end` carries the
+ * assembled block. Adapters emit usage before the terminal finish and nothing
+ * afterward; tool arguments remain raw JSON strings. An adapter implementation
+ * may throw, but `LlmRuntime.stream()` normalizes that failure to a terminal
+ * `error` or `aborted` finish before exposing it to consumers.
+ */
+export type StreamChunk = {
+    type: 'block-start';
+    index: number;
+    blockType: ContentBlockType;
+} | {
+    type: 'text-delta';
+    index: number;
+    text: string;
+} | {
+    type: 'reasoning-delta';
+    index: number;
+    text: string;
+} | {
+    type: 'tool-call-delta';
+    index: number;
+    id: ToolCallId;
+    name?: string;
+    argumentsDelta: string;
+} | {
+    type: 'block-end';
+    index: number;
+    block: ContentBlock;
+} | {
+    type: 'usage';
+    usage: TokenUsage;
+} | {
+    type: 'finish';
+    reason: FinishReason;
+    /** Replay metadata for a successful response; see {@link ReplayEnvelope}. */
+    replayState?: ReplayEnvelope;
+};
+/**
+ * JSON-schema description of a tool, as sent to the model.
+ *
+ * Declared here (not in qilin-tools) because it is part of {@link GenerateOptions};
+ * qilin-tools' ToolDefinition and qilin-system-prompt's PromptAssembly both import
+ * it from this package.
+ */
+export interface ToolSchema {
+    /**
+     * Requests deferred loading of the tool definition into model context,
+     * independently of whether a tool-addition block records the tool.
+     * Uses Anthropic's defer_loading terminology.
+     */
+    deferLoading?: true;
+    name: string;
+    description: string;
+    /** JSON Schema object for the arguments. */
+    parameters: Record<string, unknown>;
+}
+/** User input for one LLM request; it has no durable Session identity or source. */
+export interface RequestUserInput {
+    readonly role: 'user';
+    readonly content: UserMessage['content'];
+    readonly id?: never;
+    readonly source?: never;
+}
+/** A durable conversation message or a user input used only for one request. */
+export type RequestMessage = Message | RequestUserInput;
+/** Logged tool declarations and update identities since the last declaration reset. */
+export interface ToolHistory {
+    /** Complete active declarations at the start of this history. */
+    readonly tools: readonly ToolSchema[];
+    /** Ordered developer messages, with additions resolved from their historical headers. */
+    readonly updates: readonly {
+        /** Identity used to locate this update in the derived request history. */
+        readonly messageId: MessageId;
+        /** Added definitions resolved from the event's referenced request header. */
+        readonly additions: readonly ToolSchema[];
+    }[];
+}
+/** A single model request, fully assembled. */
+export interface GenerateOptions {
+    /** Registered provider route selecting the adapter instance. */
+    provider: string;
+    model: string;
+    /** Adapter-owned reasoning effort selected for this exact model. */
+    reasoningEffort?: ReasoningEffortId;
+    /**
+     * Ordered conversation messages, exactly as the provider sees them. A
+     * loop-built request passes the derived history (qilin-agent-loop), whose
+     * leading system-role message carries the system prompt; a hand-built
+     * one-shot may include identity-free user inputs.
+     */
+    messages: RequestMessage[];
+    /**
+     * System prompt text for one-shot callers; adapters map it to the provider's
+     * system slot ahead of `messages`. Loop-built requests leave it undefined.
+     */
+    system?: string;
+    /** Tool schemas (adapters map to the provider's `tools` field). */
+    tools?: ToolSchema[];
+    /** Session-folded tool history used for route projection; omission sends complete declarations without tool updates. */
+    toolHistory?: ToolHistory;
+    temperature?: number;
+    maxTokens?: number;
+    /**
+     * Stop sequences: generation halts as soon as the model produces any one of
+     * these strings (adapters map to the provider's stop field, e.g. OpenAI
+     * `stop`). The stop string itself is not included in the output.
+     */
+    stop?: string[];
+    signal?: AbortSignal;
+    /**
+     * Session identity stamped by the loop for request routing. Replay uses it
+     * to separate cursors; adapters may map it to model-hidden transport metadata.
+     */
+    sessionId?: Branded<'SessionId'>;
+    /**
+     * Provider-neutral classification for an auxiliary model call. Adapters may
+     * map the purpose to model-hidden transport metadata or purpose-specific
+     * generation policy. Ordinary conversation requests leave it unset.
+     */
+    purpose?: 'compaction' | 'session-title';
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,7 @@
+/**
+ * Canonical provider-neutral message and streaming vocabulary for the loop,
+ * session log, and plugins. Adapters alone translate provider wire messages;
+ * mapped interfaces make the content, source, and finish unions extensible.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,77 @@
 {
   "name": "@qilin-agent/llm",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Provider-neutral LLM service interface for the QiLin",
+  "version": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/llm/llm"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./brand": {
+      "types": "./lib/types/brand.d.ts",
+      "default": "./lib/types/brand.js"
+    },
+    "./message": {
+      "types": "./lib/types/message.d.ts",
+      "default": "./lib/types/message.js"
+    },
+    "./assistant-stream": {
+      "types": "./lib/types/assistant-stream.d.ts",
+      "default": "./lib/types/assistant-stream.js"
+    },
+    "./typert": {
+      "types": "./lib/typert.host.d.ts",
+      "default": "./lib/typert.host.js"
+    },
+    "./remote": {
+      "types": "./lib/typert.remote-client.d.ts",
+      "default": "./lib/typert.remote-client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts",
+    "lib/typert.host.js",
+    "lib/typert.host.d.ts",
+    "lib/typert.remote-client.js",
+    "lib/typert.remote-client.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@qilin-agent/schemastery": "~3.18.3",
+    "@qilin-agent/util-crypto": "3.1.3",
+    "@qilin-agent/timeout": "3.1.3",
+    "@qilin-agent/brand": "3.1.3",
+    "@qilin-agent/util-values": "3.1.3",
+    "@qilin-agent/typert-protocol": "3.1.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/attachment": "3.1.3",
+    "@qilin-agent/kylin": "~4.0.3"
+  }
 }