@qilin-agent/llm 0.0.0-stage → 3.1.4

package/lib/types/message.d.ts

@@ -0,0 +1,246 @@
+/** Message value types, identity, and immutable construction helpers. */
+import type { MessageId, ToolCallId } from './brand.ts';
+import type { ContentBlock } from './types.ts';
+/** Provider/model identity and adapter-private replay data for an assistant message. */
+export interface AssistantProviderMetadata {
+    /** Provider route that produced the message. */
+    provider: string;
+    /** Provider model id that produced the message. */
+    model: string;
+    /**
+     * Lossless-JSON adapter state needed to replay the provider response.
+     * `LlmRuntime` exposes it to a target adapter only when that adapter instance
+     * currently owns both this historical provider and the target provider.
+     */
+    replayState?: unknown;
+}
+/** Required source of an assistant message produced by a routed model. */
+export interface ModelMessageSource extends AssistantProviderMetadata {
+    kind: 'model';
+}
+/** Required source of a tool-role message carrying one tool result. */
+export interface ToolMessageSource {
+    kind: 'tool';
+    callId: ToolCallId;
+}
+/** Required source of a system-role message produced by the system-prompt plugin. */
+export interface SystemPromptMessageSource {
+    kind: 'system-prompt';
+}
+/**
+ * The kind of information in producer-supplied context, declared by the
+ * producer in the same `MessageSource`.
+ *
+ * `MessageSource.kind` answers *who produced this*; `form` answers *what kind
+ * of thing it is*, and the two axes are deliberately independent — several
+ * producers share one form, and one producer may emit more than one form over
+ * a session.
+ *
+ * The vocabulary is SEMANTIC, never visual: a value states that the content is
+ * a file's instructions or a catalog of available items, and a consumer decides
+ * what that looks like. Colors, icons, ordering, and collapse defaults are the
+ * consumer's business and must not enter this union. It grows one value at a
+ * time as producers gain the structured fields their form needs; an absent or
+ * unknown value is the documented default, presented as opaque content.
+ */
+export type ContextForm = 
+/** Instructions read out of workspace files the model is expected to follow. */
+'instructions'
+/** A catalog of items available in this session, republished as it changes. */
+ | 'catalog'
+/** Current state, where a later snapshot from the same producer supersedes an earlier one. */
+ | 'snapshot'
+/** A one-off account of something that just happened; it supersedes nothing. */
+ | 'notice'
+/** A message another agent addressed to this one. */
+ | 'relay'
+/** Material lifted out of another session's log, possibly reduced on the way in. */
+ | 'recall';
+/** One named contribution to a `snapshot`-form context, in assembly order. */
+export interface ContextSnapshotSection {
+    /** The contributing subsystem's name. */
+    readonly name: string;
+    /** That contribution's model-facing text, exactly as assembled. */
+    readonly text: string;
+}
+/**
+ * Producer-declared {@link ContextForm} and the fields that form requires,
+ * mixed into the source types that carry one.
+ *
+ * Discriminated by `form` so a producer cannot select a form without the
+ * fields needed to present it: a `notice` must record its one-line
+ * account, a `snapshot` its sections. Omitting `form` stays valid — an
+ * undeclared context is the documented default.
+ */
+export type ContextFormed = {
+    readonly form?: never;
+} | {
+    readonly form: 'instructions';
+} | {
+    readonly form: 'catalog';
+} | {
+    readonly form: 'snapshot';
+    /** The named contributions this snapshot assembled, in order. */
+    readonly sections: readonly ContextSnapshotSection[];
+} | {
+    readonly form: 'notice';
+    /** One-line account of what happened, shown without expanding the row. */
+    readonly summary: string;
+} | {
+    readonly form: 'relay';
+} | {
+    readonly form: 'recall';
+};
+/**
+ * Where a message (or injected content) came from, in the harness's own
+ * vocabulary. Merge-extensible sum type — each producer declares its own
+ * `kind` in its own module; there is no shared catch-all `plugin` kind.
+ * Model and tool sources answer their role messages; user messages carry any
+ * producer's kind, and consumers fall through unknown kinds.
+ */
+export interface MessageSourceMap {
+    user: {
+        kind: 'user';
+    };
+    model: ModelMessageSource;
+    tool: ToolMessageSource;
+    'system-prompt': SystemPromptMessageSource;
+}
+/**
+ * Bound for a `notice` summary. Producers commit the one-line account to the
+ * durable log; its inputs — task labels, goal objectives, tool arguments —
+ * are caller text with no length of their own.
+ */
+export declare const CONTEXT_SUMMARY_MAX_CHARS = 120;
+/**
+ * Bound one `notice` summary to {@link CONTEXT_SUMMARY_MAX_CHARS}.
+ * @param summary - the producer's one-line account, of any length.
+ * @returns the account, ellipsized when it exceeds the bound.
+ */
+export declare function boundContextSummary(summary: string): string;
+/** Any known message source, derived from {@link MessageSourceMap}; switch on `kind` and fall through unknowns (merge-extensible). */
+export type MessageSource = MessageSourceMap[keyof MessageSourceMap];
+/** Shared immutable fields of every conversation message. */
+interface MessageBase {
+    /** Stable identity preserved across every representation boundary. */
+    readonly id: MessageId;
+    /** Exact model-facing blocks. */
+    readonly content: readonly ContentBlock[];
+    /** Required source fields supplied by the producer.
+     * @persistenceSource user developer
+     */
+    readonly source: MessageSource;
+}
+/** A rendered system prompt attributed to the system-prompt producer; empty content sends no prompt. */
+export interface SystemMessage extends MessageBase {
+    readonly role: 'system';
+    readonly source: MessageSourceMap['system-prompt'];
+}
+/** Incremental agent session changes in conversation order, currently tool additions and removals. */
+export interface DeveloperMessage extends MessageBase {
+    readonly role: 'developer';
+}
+/** A user-role specialization of the shared message representation. */
+export interface UserMessage extends MessageBase {
+    readonly role: 'user';
+}
+/** A model-produced assistant specialization of the shared message representation. */
+export interface AssistantMessage extends MessageBase {
+    readonly role: 'assistant';
+    readonly source: ModelMessageSource;
+}
+/** A first-class tool-role message carrying the result of one tool invocation. */
+export interface ToolResultMessage extends MessageBase {
+    readonly role: 'tool';
+    readonly source: ToolMessageSource;
+    /** Provider-issued id of the tool call this message answers. */
+    readonly toolCallId: ToolCallId;
+    /** Whether the tool invocation failed. */
+    readonly isError?: boolean;
+}
+/**
+ * The conversation messages persisted by Session, keyed by role. This map is
+ * closed because every model-visible role must have a durable Session event
+ * and an adapter projection.
+ */
+export interface MessageRoleMap {
+    system: SystemMessage;
+    developer: DeveloperMessage;
+    user: UserMessage;
+    assistant: AssistantMessage;
+    tool: ToolResultMessage;
+}
+/** Any persisted conversation message, discriminated by its `role`. */
+export type Message = MessageRoleMap[keyof MessageRoleMap];
+type NewMessage = {
+    [Role in keyof MessageRoleMap]: Omit<MessageRoleMap[Role], 'id'>;
+}[keyof MessageRoleMap];
+type NewDeveloperMessage = Omit<DeveloperMessage, 'id' | 'role'>;
+type NewUserMessage = Omit<UserMessage, 'id' | 'role'>;
+type NewAssistantMessage = Omit<AssistantMessage, 'id' | 'role' | 'source'> & {
+    readonly source: Omit<ModelMessageSource, 'kind'> & {
+        readonly kind?: never;
+    };
+};
+/**
+ * Detach and deep-freeze a message whose identity already exists.
+ * @param message - complete message, including its stable identity.
+ * @returns an immutable snapshot that preserves the identity.
+ */
+export declare function freezeMessage<T extends Message>(message: T): T;
+/**
+ * Create one identified message and freeze it before publication.
+ * @param input - complete role, content, and source for a new message.
+ * @returns an immutable message with a fresh stable identity.
+ */
+export declare function createMessage<T extends NewMessage>(input: T & {
+    readonly id?: never;
+}): T & Pick<Message, 'id'>;
+/**
+ * Create an identified, immutable developer message.
+ * @param input - content and producer source for the new message.
+ * @returns a detached developer message with a fresh identity.
+ */
+export declare function createDeveloperMessage<T extends NewDeveloperMessage>(input: T & {
+    readonly id?: never;
+    readonly role?: never;
+}): T & Pick<DeveloperMessage, 'id' | 'role'>;
+/**
+ * Create one identified user-role message and freeze it before publication.
+ * @param input - complete content and source for a new user message.
+ * @returns an immutable user message with a fresh stable identity.
+ */
+export declare function createUserMessage<T extends NewUserMessage>(input: T & {
+    readonly id?: never;
+    readonly role?: never;
+}): T & Pick<UserMessage, 'id' | 'role'>;
+/**
+ * Create one identified model-produced assistant message and freeze it before publication.
+ * @param input - complete content plus the provider, model, and optional replay state for a new assistant message.
+ * @returns an immutable assistant message with fixed role/source tags and a fresh stable identity.
+ */
+export declare function createAssistantMessage(input: NewAssistantMessage & {
+    readonly id?: never;
+    readonly role?: never;
+}): AssistantMessage;
+/**
+ * Create and freeze one identified system-role message holding a rendered
+ * system prompt.
+ * @param text - the complete rendered prompt; `''` records "no system prompt".
+ * @returns an immutable system message with a fresh stable identity.
+ */
+export declare function createSystemMessage(text: string): SystemMessage;
+/** Input whose acceptance creates one tool-result message. */
+export interface ToolResultMessageInput {
+    readonly callId: ToolCallId;
+    readonly content: readonly ContentBlock[];
+    readonly isError: boolean;
+}
+/**
+ * Create and freeze one identified tool-result message.
+ * @param input - call identity, raw result blocks, and outcome.
+ * @returns an immutable tool-role message that answers the tool call.
+ */
+export declare function createToolResultMessage(input: ToolResultMessageInput): ToolResultMessage;
+export {};
+//# sourceMappingURL=message.d.ts.map

package/lib/types/message.js

@@ -0,0 +1,101 @@
+/** Message value types, identity, and immutable construction helpers. */
+import { randomUUID } from '@qilin-agent/util-crypto';
+import { brandString } from '@qilin-agent/brand';
+import { deepFreeze } from '@qilin-agent/util-values';
+/**
+ * Bound for a `notice` summary. Producers commit the one-line account to the
+ * durable log; its inputs — task labels, goal objectives, tool arguments —
+ * are caller text with no length of their own.
+ */
+export const CONTEXT_SUMMARY_MAX_CHARS = 120;
+/**
+ * Bound one `notice` summary to {@link CONTEXT_SUMMARY_MAX_CHARS}.
+ * @param summary - the producer's one-line account, of any length.
+ * @returns the account, ellipsized when it exceeds the bound.
+ */
+export function boundContextSummary(summary) {
+    return summary.length <= CONTEXT_SUMMARY_MAX_CHARS
+        ? summary
+        : `${summary.slice(0, CONTEXT_SUMMARY_MAX_CHARS - 1)}…`;
+}
+/**
+ * Detach and deep-freeze a message whose identity already exists.
+ * @param message - complete message, including its stable identity.
+ * @returns an immutable snapshot that preserves the identity.
+ */
+export function freezeMessage(message) {
+    return deepFreeze(structuredClone(message));
+}
+/**
+ * Create one identified message and freeze it before publication.
+ * @param input - complete role, content, and source for a new message.
+ * @returns an immutable message with a fresh stable identity.
+ */
+export function createMessage(input) {
+    return deepFreeze(structuredClone({
+        ...input,
+        id: brandString(randomUUID()),
+    }));
+}
+/**
+ * Create an identified, immutable developer message.
+ * @param input - content and producer source for the new message.
+ * @returns a detached developer message with a fresh identity.
+ */
+export function createDeveloperMessage(input) {
+    return createMessage({ ...input, role: 'developer' });
+}
+/**
+ * Create one identified user-role message and freeze it before publication.
+ * @param input - complete content and source for a new user message.
+ * @returns an immutable user message with a fresh stable identity.
+ */
+export function createUserMessage(input) {
+    return createMessage({
+        ...input,
+        role: 'user',
+    });
+}
+/**
+ * Create one identified model-produced assistant message and freeze it before publication.
+ * @param input - complete content plus the provider, model, and optional replay state for a new assistant message.
+ * @returns an immutable assistant message with fixed role/source tags and a fresh stable identity.
+ */
+export function createAssistantMessage(input) {
+    return createMessage({
+        role: 'assistant',
+        content: input.content,
+        source: {
+            kind: 'model',
+            ...input.source,
+        },
+    });
+}
+/**
+ * Create and freeze one identified system-role message holding a rendered
+ * system prompt.
+ * @param text - the complete rendered prompt; `''` records "no system prompt".
+ * @returns an immutable system message with a fresh stable identity.
+ */
+export function createSystemMessage(text) {
+    return createMessage({
+        role: 'system',
+        content: text.length === 0 ? [] : [{ type: 'text', text }],
+        source: { kind: 'system-prompt' },
+    });
+}
+/**
+ * Create and freeze one identified tool-result message.
+ * @param input - call identity, raw result blocks, and outcome.
+ * @returns an immutable tool-role message that answers the tool call.
+ */
+export function createToolResultMessage(input) {
+    return createMessage({
+        role: 'tool',
+        source: { kind: 'tool', callId: input.callId },
+        toolCallId: input.callId,
+        content: input.content,
+        isError: input.isError,
+    });
+}
+//# sourceMappingURL=message.js.map

package/lib/types/retry-policy.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Provider-owned request-retry policy configuration and resolution.
+ *
+ * Adapters expose one resolved policy per registered provider route; the
+ * optional qilin-llm-retry plugin executes it on the agent's failed-step extension point.
+ *
+ * @module @qilin-agent/llm/retry-policy
+ */
+import z from '@qilin-agent/schemastery';
+/** Bounded exponential backoff with symmetric jitter around each local delay. */
+export interface BackoffConfig {
+    /** Initial local exponential-backoff delay in milliseconds (default 500). */
+    initialDelayMs?: number;
+    /** Maximum locally scheduled or accepted provider delay in milliseconds (default 10000). */
+    maxDelayMs?: number;
+    /** Symmetric random multiplier range around one (default 0.1). */
+    jitterRatio?: number;
+}
+/** Current bounded transient retry behavior for one provider route. */
+export interface NormalRetryPolicyConfig {
+    /** Retry only configured transient failure codes. */
+    mode: 'normal';
+    /** Maximum eligible retries after the first request (default 5). */
+    maxRetries?: number;
+    /** Stable failure codes eligible for this policy. */
+    retryableCodes?: string[];
+    /** Local exponential-backoff and jitter configuration. */
+    backoff?: BackoffConfig;
+}
+/** Unbounded retry behavior for every model-request failure on one provider route. */
+export interface AlwaysRetryPolicyConfig {
+    /** Retry every model-request failure until success, cancellation, or disposal. */
+    mode: 'always';
+    /** Local exponential-backoff and jitter configuration. */
+    backoff?: BackoffConfig;
+}
+/** Provider-owned model-request retry policy configuration. */
+export type RetryPolicyConfig = NormalRetryPolicyConfig | AlwaysRetryPolicyConfig;
+/** Fully resolved backoff shared by both retry modes. */
+export interface ResolvedRetryBackoff {
+    readonly initialDelayMs: number;
+    readonly maxDelayMs: number;
+    readonly jitterRatio: number;
+}
+/** Fully resolved bounded transient retry policy. */
+export interface ResolvedNormalRetryPolicy extends ResolvedRetryBackoff {
+    readonly mode: 'normal';
+    readonly maxRetries: number;
+    readonly retryableCodes: readonly string[];
+}
+/** Fully resolved unbounded retry policy. */
+export interface ResolvedAlwaysRetryPolicy extends ResolvedRetryBackoff {
+    readonly mode: 'always';
+}
+/** Immutable provider policy captured when its adapter route is registered. */
+export type ResolvedRetryPolicy = ResolvedNormalRetryPolicy | ResolvedAlwaysRetryPolicy;
+/** Cordis schema embedded by each concrete provider configuration. */
+export declare const RetryPolicySchema: z<RetryPolicyConfig>;
+/**
+ * Validate, default, and detach one provider-owned retry policy.
+ * @param config - optional provider configuration; omission selects normal defaults.
+ * @param path - diagnostic path naming the provider config that owns the value.
+ * @returns an immutable policy safe to capture in provider registration state.
+ */
+export declare function resolveRetryPolicy(config: RetryPolicyConfig | undefined, path: string): ResolvedRetryPolicy;
+//# sourceMappingURL=retry-policy.d.ts.map

package/lib/types/retry-policy.js

@@ -0,0 +1,127 @@
+/**
+ * Provider-owned request-retry policy configuration and resolution.
+ *
+ * Adapters expose one resolved policy per registered provider route; the
+ * optional qilin-llm-retry plugin executes it on the agent's failed-step extension point.
+ *
+ * @module @qilin-agent/llm/retry-policy
+ */
+import z from '@qilin-agent/schemastery';
+import { MAX_TIMER_DELAY_MS } from '@qilin-agent/timeout';
+import { EMPTY_RESPONSE_CODE } from "./error.js";
+const DEFAULT_MAX_RETRIES = 5;
+const DEFAULT_INITIAL_DELAY_MS = 500;
+const DEFAULT_MAX_DELAY_MS = 10_000;
+const DEFAULT_JITTER_RATIO = 0.1;
+const DEFAULT_RETRYABLE_CODES = Object.freeze([
+    EMPTY_RESPONSE_CODE,
+    'RATE_LIMIT',
+    'SERVER',
+    'TIMEOUT',
+    'TRANSPORT',
+]);
+const backoffSchema = z.object({
+    initialDelayMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_INITIAL_DELAY_MS),
+    maxDelayMs: z.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_MAX_DELAY_MS),
+    jitterRatio: z.number().min(0).max(1).default(DEFAULT_JITTER_RATIO),
+});
+const normalPolicySchema = z.object({
+    mode: z.const('normal').required(),
+    maxRetries: z.number().step(1).min(0).max(Number.MAX_SAFE_INTEGER).default(DEFAULT_MAX_RETRIES),
+    retryableCodes: z.array(z.string()).default([...DEFAULT_RETRYABLE_CODES]),
+    backoff: backoffSchema,
+});
+const alwaysPolicySchema = z.object({
+    mode: z.const('always').required(),
+    backoff: backoffSchema,
+});
+/** Cordis schema embedded by each concrete provider configuration. */
+export const RetryPolicySchema = z.union([
+    normalPolicySchema,
+    alwaysPolicySchema,
+]);
+const NORMAL_POLICY_KEYS = new Set([
+    'mode', 'maxRetries', 'retryableCodes', 'backoff',
+]);
+// Layered configuration can retain normal-only fields after switching modes;
+// always mode ignores those inactive values while still rejecting unknown keys.
+const ALWAYS_POLICY_KEYS = new Set([
+    'mode', 'maxRetries', 'retryableCodes', 'backoff',
+]);
+const BACKOFF_KEYS = new Set(['initialDelayMs', 'maxDelayMs', 'jitterRatio']);
+function validateKeys(value, allowed, path) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key))
+            throw new Error(`${path}: unknown key "${key}"`);
+    }
+}
+function resolveBackoff(config, path) {
+    if (config !== undefined)
+        validateKeys(config, BACKOFF_KEYS, path);
+    const initialDelayMs = config?.initialDelayMs ?? DEFAULT_INITIAL_DELAY_MS;
+    const maxDelayMs = config?.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+    const jitterRatio = config?.jitterRatio ?? DEFAULT_JITTER_RATIO;
+    if (!Number.isFinite(initialDelayMs) || initialDelayMs <= 0 || initialDelayMs > MAX_TIMER_DELAY_MS) {
+        throw new Error(`${path}.initialDelayMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`);
+    }
+    if (!Number.isFinite(maxDelayMs) || maxDelayMs <= 0 || maxDelayMs > MAX_TIMER_DELAY_MS) {
+        throw new Error(`${path}.maxDelayMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`);
+    }
+    if (initialDelayMs > maxDelayMs) {
+        throw new Error(`${path}.initialDelayMs must be less than or equal to maxDelayMs`);
+    }
+    if (!Number.isFinite(jitterRatio) || jitterRatio < 0 || jitterRatio > 1) {
+        throw new Error(`${path}.jitterRatio must be between 0 and 1`);
+    }
+    return Object.freeze({ initialDelayMs, maxDelayMs, jitterRatio });
+}
+/**
+ * Validate, default, and detach one provider-owned retry policy.
+ * @param config - optional provider configuration; omission selects normal defaults.
+ * @param path - diagnostic path naming the provider config that owns the value.
+ * @returns an immutable policy safe to capture in provider registration state.
+ */
+export function resolveRetryPolicy(config, path) {
+    if (config === undefined) {
+        return Object.freeze({
+            mode: 'normal',
+            maxRetries: DEFAULT_MAX_RETRIES,
+            retryableCodes: DEFAULT_RETRYABLE_CODES,
+            ...resolveBackoff(undefined, `${path}.backoff`),
+        });
+    }
+    switch (config.mode) {
+        case 'normal': {
+            validateKeys(config, NORMAL_POLICY_KEYS, path);
+            const maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+            const retryableCodes = config.retryableCodes ?? [...DEFAULT_RETRYABLE_CODES];
+            if (!Number.isSafeInteger(maxRetries) || maxRetries < 0) {
+                throw new Error(`${path}.maxRetries must be a non-negative safe integer`);
+            }
+            if (retryableCodes.length === 0) {
+                throw new Error(`${path}.retryableCodes must not be empty`);
+            }
+            if (retryableCodes.some(code => typeof code !== 'string' || code.length === 0)) {
+                throw new Error(`${path}.retryableCodes must contain only non-empty strings`);
+            }
+            if (new Set(retryableCodes).size !== retryableCodes.length) {
+                throw new Error(`${path}.retryableCodes must not contain duplicates`);
+            }
+            return Object.freeze({
+                mode: 'normal',
+                maxRetries,
+                retryableCodes: Object.freeze([...retryableCodes]),
+                ...resolveBackoff(config.backoff, `${path}.backoff`),
+            });
+        }
+        case 'always':
+            validateKeys(config, ALWAYS_POLICY_KEYS, path);
+            return Object.freeze({
+                mode: 'always',
+                ...resolveBackoff(config.backoff, `${path}.backoff`),
+            });
+        default:
+            throw new Error(`${path}.mode must be "normal" or "always"`);
+    }
+}
+//# sourceMappingURL=retry-policy.js.map