@qilin-agent/llm 0.0.0-stage → 3.1.3

package/lib/types/attribution.js

@@ -0,0 +1,46 @@
+/**
+ * Centralize the non-secret product identity every provider request sends as `User-Agent`, keeping
+ * adapters from drifting. See
+ * `.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md`.
+ *
+ * App-attribution vocabulary for provider requests.
+ * @module @qilin-agent/llm/attribution
+ */
+import { createRequire } from 'node:module';
+// The package's own manifest is the single source of the version so the
+// User-Agent cannot drift from what is published (`./package.json` is an
+// export of this package; the relative path resolves from both `src/` and
+// the bundled `lib/`).
+const { version } = createRequire(import.meta.url)('../package.json');
+/**
+ * The harness's own identity: the default every adapter sends. Deployments
+ * that need a white-label identity pass their own {@link AppIdentity} to
+ * {@link attributionHeaders} — omission falls back to this default; nothing
+ * can suppress attribution entirely.
+ */
+export const APP_IDENTITY = {
+    product: 'qilin',
+    version,
+    url: 'https://github.com/kkutysllb/QiLin',
+};
+/**
+ * The standard `User-Agent` value: `product/version (+url)`. The
+ * parenthesized `+url` comment is the conventional self-identification form
+ * (RFC 9110 §10.1.5 product + comment syntax).
+ * @param identity - the identity to render; defaults to {@link APP_IDENTITY}.
+ * @returns the ready-to-send header value.
+ */
+export function userAgent(identity = APP_IDENTITY) {
+    return `${identity.product}/${identity.version} (+${identity.url})`;
+}
+/**
+ * Build the attribution headers an adapter must send on every provider
+ * request. Header names are lowercase (HTTP field names are case-insensitive
+ * on the wire).
+ * @param identity - the identity to send; defaults to {@link APP_IDENTITY} — omission cannot suppress attribution.
+ * @returns headers to merge into the provider request (currently just `user-agent`).
+ */
+export function attributionHeaders(identity = APP_IDENTITY) {
+    return { 'user-agent': userAgent(identity) };
+}
+//# sourceMappingURL=attribution.js.map

package/lib/types/brand.d.ts

@@ -0,0 +1,56 @@
+/**
+ * qilin-llm's owned branded ids: tool-call correlation and provider request
+ * diagnostics.
+ *
+ * The `Branded<B>` primitive and stateless constructor live in
+ * `@qilin-agent/brand` so every owner of a cross-boundary id can brand it
+ * without depending on qilin-llm; see that package's README for the
+ * nominal-typing policy.
+ *
+ * @module @qilin-agent/llm/brand
+ */
+import { type Branded } from '@qilin-agent/brand';
+/** Stable identity carried by one message across inbox, log, and model-request boundaries. */
+export type MessageId = Branded<'MessageId'>;
+/**
+ * Brand a message identifier.
+ * @param id - the opaque message identifier.
+ * @returns the same string with the message-id brand.
+ */
+export declare function MessageId(id: string): MessageId;
+/**
+ * Correlates a model-issued tool call with its result. Provider-issued for
+ * real adapters; synthesized by mocks/assembler fallbacks.
+ */
+export type ToolCallId = Branded<'ToolCallId'>;
+/**
+ * Brand a string as a {@link ToolCallId}.
+ * @param id - the provider-issued or synthesized call id.
+ * @returns the same string with the tool-call-id brand.
+ */
+export declare function ToolCallId(id: string): ToolCallId;
+/** Provider-issued request identifier retained for diagnostics across package boundaries. */
+export type ProviderRequestId = Branded<'ProviderRequestId'>;
+/**
+ * Brand a provider-issued request identifier.
+ * @param id - the opaque provider-issued string.
+ * @returns the same string, branded; no validation is performed.
+ */
+export declare function ProviderRequestId(id: string): ProviderRequestId;
+/** Identity of one model streaming attempt, unique within one Agent lifecycle. */
+export type LlmAttemptId = Branded<'LlmAttemptId'>;
+/**
+ * Brand one loop-owned streaming attempt identifier.
+ * @param id - the opaque Agent-lifecycle-local identifier.
+ * @returns the same string with the attempt-id brand.
+ */
+export declare function LlmAttemptId(id: string): LlmAttemptId;
+/** Adapter-owned identifier for one model's selectable reasoning effort. */
+export type ReasoningEffortId = Branded<'ReasoningEffortId'>;
+/**
+ * Brand an adapter-owned reasoning-effort identifier.
+ * @param id - the opaque identifier exposed by one model capability.
+ * @returns the same string, branded; no validation is performed.
+ */
+export declare function ReasoningEffortId(id: string): ReasoningEffortId;
+//# sourceMappingURL=brand.d.ts.map

package/lib/types/brand.js

@@ -0,0 +1,53 @@
+/**
+ * qilin-llm's owned branded ids: tool-call correlation and provider request
+ * diagnostics.
+ *
+ * The `Branded<B>` primitive and stateless constructor live in
+ * `@qilin-agent/brand` so every owner of a cross-boundary id can brand it
+ * without depending on qilin-llm; see that package's README for the
+ * nominal-typing policy.
+ *
+ * @module @qilin-agent/llm/brand
+ */
+import { brandString } from '@qilin-agent/brand';
+/**
+ * Brand a message identifier.
+ * @param id - the opaque message identifier.
+ * @returns the same string with the message-id brand.
+ */
+export function MessageId(id) {
+    return brandString(id);
+}
+/**
+ * Brand a string as a {@link ToolCallId}.
+ * @param id - the provider-issued or synthesized call id.
+ * @returns the same string with the tool-call-id brand.
+ */
+export function ToolCallId(id) {
+    return brandString(id);
+}
+/**
+ * Brand a provider-issued request identifier.
+ * @param id - the opaque provider-issued string.
+ * @returns the same string, branded; no validation is performed.
+ */
+export function ProviderRequestId(id) {
+    return brandString(id);
+}
+/**
+ * Brand one loop-owned streaming attempt identifier.
+ * @param id - the opaque Agent-lifecycle-local identifier.
+ * @returns the same string with the attempt-id brand.
+ */
+export function LlmAttemptId(id) {
+    return brandString(id);
+}
+/**
+ * Brand an adapter-owned reasoning-effort identifier.
+ * @param id - the opaque identifier exposed by one model capability.
+ * @returns the same string, branded; no validation is performed.
+ */
+export function ReasoningEffortId(id) {
+    return brandString(id);
+}
+//# sourceMappingURL=brand.js.map

package/lib/types/call-config.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Conversation call configuration and freeze utilities. Provider routing,
+ * model, reasoning effort, and sampling values are request-header state that
+ * can affect cache reuse; request waterfalls replace them and the loop logs
+ * changed snapshots instead of allowing silent per-call drift.
+ * @module qilin-llm/call-config
+ */
+import type { GenerateOptions } from './types.ts';
+import type { ReasoningEffortId } from './brand.ts';
+/**
+ * Provider, model, reasoning effort, and sampling scalars of one conversation's
+ * requests. Every field maps 1:1 onto the same-named `GenerateOptions` field;
+ * the loop builds requests from the logged header rather than accepting these
+ * per call.
+ */
+export interface LlmCallConfig {
+    provider: string;
+    model: string;
+    reasoningEffort?: ReasoningEffortId;
+    temperature?: number;
+    maxTokens?: number;
+    stop?: string[];
+}
+/**
+ * Effective config fields supplied by exact-model adapter resolution rather
+ * than by the caller's request proposal.
+ */
+export interface LlmCallConfigAdapterDefaults {
+    reasoningEffort?: true;
+    maxTokens?: true;
+}
+/**
+ * Field-wise equality over {@link LlmCallConfig} — the comparison a caller
+ * runs to decide whether a proposed configuration is a real change (worth a
+ * logged header snapshot) or the held one restated.
+ * @param a - one configuration.
+ * @param b - the other.
+ * @returns whether every field (including the `stop` list, element-wise) matches.
+ */
+export declare function callConfigEquals(a: LlmCallConfig, b: LlmCallConfig): boolean;
+/**
+ * Mark one exact request object as assembled by qilin-agent-loop.
+ * @param request - loop-owned request envelope before LLM dispatch.
+ * @returns the same request object marked as created by the process-local agent loop.
+ */
+export declare function markAgentLoopRequest<T extends GenerateOptions>(request: T): T;
+/**
+ * Test whether the exact request object was assembled by qilin-agent-loop.
+ * @param request - request envelope observed at the LLM waterfall.
+ * @returns whether {@link markAgentLoopRequest} recorded this object.
+ */
+export declare function isAgentLoopRequest(request: GenerateOptions): boolean;
+//# sourceMappingURL=call-config.d.ts.map

package/lib/types/call-config.js

@@ -0,0 +1,46 @@
+/**
+ * Conversation call configuration and freeze utilities. Provider routing,
+ * model, reasoning effort, and sampling values are request-header state that
+ * can affect cache reuse; request waterfalls replace them and the loop logs
+ * changed snapshots instead of allowing silent per-call drift.
+ * @module qilin-llm/call-config
+ */
+/** Process-local identities of request objects assembled by qilin-agent-loop. */
+const AGENT_LOOP_REQUESTS = new WeakSet();
+/**
+ * Field-wise equality over {@link LlmCallConfig} — the comparison a caller
+ * runs to decide whether a proposed configuration is a real change (worth a
+ * logged header snapshot) or the held one restated.
+ * @param a - one configuration.
+ * @param b - the other.
+ * @returns whether every field (including the `stop` list, element-wise) matches.
+ */
+export function callConfigEquals(a, b) {
+    if (a.provider !== b.provider
+        || a.model !== b.model
+        || a.reasoningEffort !== b.reasoningEffort
+        || a.temperature !== b.temperature
+        || a.maxTokens !== b.maxTokens)
+        return false;
+    if (a.stop === undefined || b.stop === undefined)
+        return a.stop === b.stop;
+    return a.stop.length === b.stop.length && a.stop.every((s, i) => s === b.stop?.[i]);
+}
+/**
+ * Mark one exact request object as assembled by qilin-agent-loop.
+ * @param request - loop-owned request envelope before LLM dispatch.
+ * @returns the same request object marked as created by the process-local agent loop.
+ */
+export function markAgentLoopRequest(request) {
+    AGENT_LOOP_REQUESTS.add(request);
+    return request;
+}
+/**
+ * Test whether the exact request object was assembled by qilin-agent-loop.
+ * @param request - request envelope observed at the LLM waterfall.
+ * @returns whether {@link markAgentLoopRequest} recorded this object.
+ */
+export function isAgentLoopRequest(request) {
+    return AGENT_LOOP_REQUESTS.has(request);
+}
+//# sourceMappingURL=call-config.js.map

package/lib/types/content.d.ts

@@ -0,0 +1,149 @@
+/** Content-block structure helpers. @module @qilin-agent/llm/content */
+import type { ContentBlock, ImageBlock, LlmImageRequestBudget, ToolSchema, ToolUpdate, ToolHistory } from './types.ts';
+import type { RequestMessage } from './types.ts';
+import type { Message } from './message.ts';
+import type { AttachmentStore, FileAttachmentRef, ImageAttachmentRef, RequestImageAttachment } from '@qilin-agent/attachment';
+/** Execution-world path that model tools can use to read one normalized attachment. */
+export interface ImageAttachmentAccess {
+    /** Absolute path to immutable normalized bytes; callers must treat it as read-only. */
+    readonlyPath: string;
+}
+/**
+ * Resolve current execution-world access for one durable image reference.
+ * @param ref - durable normalized attachment reference.
+ * @returns a read-only execution-world path, or undefined when unavailable.
+ */
+export type ImageAttachmentAccessResolver = (ref: ImageAttachmentRef) => ImageAttachmentAccess | undefined;
+/**
+ * Bridge one attachment provider's host object location into the mounted
+ * tool execution world. The consumer supplies the current filesystem
+ * provider's mapping without making attachment or LLM definitions depend on it.
+ * @param attachments - provider that owns the normalized attachment object.
+ * @param mapHostPath - map one absolute host path into the current tool execution world.
+ * @param ref - durable normalized attachment reference.
+ * @returns a read-only execution-world path, or undefined when either provider exposes no mapping.
+ * @throws an attachment error when the durable reference is invalid.
+ */
+export declare function resolveImageAttachmentAccess(attachments: AttachmentStore, mapHostPath: (hostPath: string) => string | undefined, ref: ImageAttachmentRef): ImageAttachmentAccess | undefined;
+/**
+ * Stable text shown to a model that cannot accept one durable image reference.
+ * @param ref - durable normalized attachment omitted from the request.
+ * @returns deterministic text-only placeholder.
+ */
+export declare function textOnlyImageText(ref: ImageAttachmentRef): string;
+/**
+ * Stable model-facing handle for one exact request image. Identity comes from
+ * the occurrence's own durable reference: request versions are prepared per
+ * attachment id, so one shared version may serve occurrences whose display
+ * names differ.
+ * @param ref - the occurrence's durable normalized attachment.
+ * @param version - exact request-image dimensions shown beside the text.
+ * @param access - optional path resolved for the current tool execution world.
+ * @returns attachment handle and request-image dimensions.
+ */
+export declare function requestImageHandleText(ref: ImageAttachmentRef, version: Pick<RequestImageAttachment, 'width' | 'height'>, access?: ImageAttachmentAccess): string;
+/**
+ * Stable per-image placeholder for a request-limit omission.
+ * @param ref - durable normalized attachment omitted from this request.
+ * @param access - optional provider-resolved path for model tools.
+ * @returns identity, normalized metadata, and the available recovery path.
+ */
+export declare function offloadedImageText(ref: ImageAttachmentRef, access?: ImageAttachmentAccess): string;
+/**
+ * True when typed model content contains an image block. This is the one image
+ * walk shared by every image policy (capability gating, text-only
+ * serialization, compaction survey), so a consumer cannot silently diverge.
+ * @param content - typed model content blocks.
+ * @returns whether any block is an image.
+ */
+export declare function contentHasImage(content: readonly ContentBlock[]): boolean;
+/**
+ * True when typed model content contains a file block.
+ * Reads current content on every call without retaining scan results.
+ * @param content - typed model content blocks.
+ * @returns whether any block is a file.
+ */
+export declare function contentHasFile(content: readonly ContentBlock[]): boolean;
+/**
+ * Stable model-facing handle for one durable file reference: the address of
+ * the verbatim stored copy and the instruction to read it on demand. This is
+ * the only representation a provider ever receives for a file.
+ * @param ref - durable verbatim file reference.
+ * @param readonlyPath - execution-world path of the stored copy, when resolvable.
+ * @returns deterministic handle text naming the file, its size, and its address.
+ */
+export declare function fileHandleText(ref: FileAttachmentRef, readonlyPath: string | undefined): string;
+/**
+ * Project request file content into deterministic handle text for every model
+ * route. Unlike images, no provider receives file blocks natively, so this
+ * projection is unconditional in request assembly.
+ * @param messages - complete request history.
+ * @param resolvePath - resolve one reference's current execution-world read path.
+ * @returns the original list without files, otherwise shallow message copies with handle text.
+ */
+export declare function projectFilesToText(messages: readonly Message[], resolvePath: (ref: FileAttachmentRef) => string | undefined): readonly Message[];
+/**
+ * Project file content in mixed durable and request-only inputs.
+ * @param messages - complete request inputs.
+ * @param resolvePath - resolve a reference's execution-world read path.
+ * @returns original inputs without files, otherwise copies with handle text.
+ */
+export declare function projectFilesToText(messages: readonly RequestMessage[], resolvePath: (ref: FileAttachmentRef) => string | undefined): readonly RequestMessage[];
+/**
+ * Project the surface's offloaded occurrences into deterministic text for one
+ * request. The offloaded set is a durable surface fact, so every route sends
+ * the same set; only the placeholder text is route-owned.
+ * @param messages - derived request history.
+ * @param placeholder - build the model-visible replacement for one offloaded attachment.
+ * @returns the original list when nothing is offloaded, otherwise shallow message copies with placeholders.
+ */
+export declare function projectOffloadedImages(messages: readonly Message[], placeholder: (ref: ImageAttachmentRef) => string): readonly Message[];
+/**
+ * Project offloaded images in mixed durable and request-only inputs.
+ * @param messages - complete request inputs.
+ * @param placeholder - replacement text for an offloaded attachment.
+ * @returns original messages or shallow copies with placeholders.
+ */
+export declare function projectOffloadedImages(messages: readonly RequestMessage[], placeholder: (ref: ImageAttachmentRef) => string): readonly RequestMessage[];
+/**
+ * Number of oldest retained occurrences a route must still offload before a
+ * derived request fits its budget at the exact byte length the route sends;
+ * zero when the request fits. A route fails with `IMAGE_OFFLOAD_REQUIRED`
+ * carrying this count instead of offloading on its own.
+ * @param messages - derived request history carrying the surface's `offloaded` marks.
+ * @param budget - route representation, budgets, and removal quanta.
+ * @param versionBytes - exact request-version byte length of one retained occurrence.
+ * @returns how many more leading retained occurrences to offload.
+ */
+export declare function requiredImageOffload(messages: readonly RequestMessage[], budget: Pick<LlmImageRequestBudget, 'representation' | 'maxBytes' | 'maxImages' | 'byteQuantum' | 'countQuantum'>, versionBytes: (block: ImageBlock) => number): number;
+/**
+ * Project request image content into deterministic text for an exact text-only model.
+ * @param messages - complete request history.
+ * @returns the original list without images, otherwise shallow message copies with stable placeholders.
+ */
+export declare function projectImagesForTextModel(messages: readonly Message[]): readonly Message[];
+/**
+ * Project image content in mixed durable and request-only inputs for a text-only model.
+ * @param messages - complete request inputs.
+ * @returns original inputs without images, otherwise copies with stable placeholders.
+ */
+export declare function projectImagesForTextModel(messages: readonly RequestMessage[]): readonly RequestMessage[];
+/** Request messages and tools after one route's tool update projection. */
+export interface ProjectedToolUpdates {
+    /** History with only the developer updates supported by this route and declaration series. */
+    readonly messages: readonly RequestMessage[];
+    /** Provider declarations, including deferred and retained definitions when supported. */
+    readonly tools: readonly ToolSchema[] | undefined;
+}
+/**
+ * Construct provider declarations from session-folded history without changing logged active tools.
+ * Unsupported routes and incomplete history use current declarations without developer updates.
+ * Explicitly deferred baseline tools become available only after their first retained addition.
+ * @param messages - complete request inputs, or the prefix selected for an auxiliary call.
+ * @param tools - currently active tool schemas.
+ * @param toolUpdate - the resolved route's update mode.
+ * @param history - immutable state folded from committed headers and developer messages.
+ * @returns provider declarations and the corresponding filtered history.
+ */
+export declare function projectToolUpdates(messages: readonly RequestMessage[], tools: readonly ToolSchema[] | undefined, toolUpdate: ToolUpdate | undefined, history?: ToolHistory): ProjectedToolUpdates;
+//# sourceMappingURL=content.d.ts.map