@leuduan/lagent 0.0.0-stage → 0.1.2

package/dist/kit/tool.d.ts

@@ -0,0 +1,72 @@
+import { type Context } from '@leuduan/cordis';
+import { z } from 'zod';
+import type { ParsedToolCall, ToolCall } from '../llm/index.js';
+import type { InvocationContext, Tool, ToolExecutionMode, WaitRequest } from '../loop/index.js';
+import type { InterruptionPolicy, ToolResult, ToolResultPayloadInput } from '../models/index.js';
+import type { JsonValue } from '../util/json.js';
+import type { AgentSelector } from './scope.js';
+/**
+ * Parameters described elsewhere, as JSON schema: advertised as given and handed to `execute`
+ * unvalidated, for a tool whose real validator is someone else's, such as an MCP server.
+ */
+export type JsonSchemaParameters = {
+    readonly jsonSchema: Record<string, JsonValue>;
+};
+type ParametersOf<P> = P extends z.ZodType ? z.output<P> : Record<string, unknown>;
+/** What `execute` returns: a result with `is_error`, `notes` and `metadata` optional, or a wait (`waitFor`). */
+export type ToolReply = ToolResultPayloadInput | WaitRequest;
+/** One tool, as {@link defineTool} takes it. */
+export type ToolDefinition<P extends z.ZodType | JsonSchemaParameters> = {
+    /** The name it is registered under, and advertised to the model by. */
+    readonly name: string;
+    /** One paragraph advertised to the model. */
+    readonly description: string;
+    /** A zod schema the arguments are validated against and advertised from, or JSON schema. */
+    readonly parameters: P;
+    /**
+     * What a re-dispatch may do with a call that may have begun when its turn was interrupted; see
+     * `Tool.onInterrupted`. Every tool says which; there is no default.
+     */
+    readonly onInterrupted: InterruptionPolicy;
+    /** Whether a call may overlap its batch's others; see `Tool.executionMode`. No default either. */
+    readonly executionMode: ToolExecutionMode;
+    /** Runs one call. A throw becomes an `is_error` result: a tool never fails a turn. */
+    execute(parameters: ParametersOf<P>, context: InvocationContext, call: ParsedToolCall): Promise<ToolReply>;
+};
+/**
+ * Defines a tool: the one way to write one. Arguments are validated against `parameters` when it is
+ * a zod schema, and a validation failure or a throw from `execute` becomes an `is_error` result, so
+ * a tool can never crash a turn; the result is timed. A tool that needs configuration closes over it.
+ *
+ * ```ts
+ * const echo = defineTool({
+ *   name: 'echo',
+ *   description: 'Repeat the text.',
+ *   parameters: z.strictObject({ text: z.string() }),
+ *   onInterrupted: 'rerun',
+ *   executionMode: 'parallel',
+ *   execute: async ({ text }) => ({ output: text }),
+ * })
+ * ```
+ */
+export declare function defineTool<P extends z.ZodType | JsonSchemaParameters>(definition: ToolDefinition<P>): Tool;
+/**
+ * Offers `tool` in the calling plugin's scope for the life of its fiber, and grants it to the agents
+ * `agents` selects when given; without them it is registered for a grant elsewhere, a preset's say.
+ * Returns the disposer.
+ */
+export declare function provideTool(ctx: Context, tool: Tool, options?: {
+    readonly agents?: AgentSelector;
+}): () => void | Promise<void>;
+/**
+ * {@link provideTool} for each of `tools`, then a prompt instruction under `tag` for every agent that
+ * is granted one of them: the `guidance` of each granted tool, in tool order, and nothing when none
+ * is granted or none has any.
+ */
+export declare function provideTools(ctx: Context, tools: readonly Tool[], options: {
+    readonly tag: string;
+    readonly guidance: ReadonlyMap<string, string>;
+}): void;
+/** A tool's result for `call`, its defaults applied and its duration recorded. */
+export declare function toToolResult(call: ToolCall, reply: ToolResultPayloadInput, startedAt: number): ToolResult;
+export { errorResult } from '../loop/index.js';

package/dist/llm/client.d.ts

@@ -0,0 +1,135 @@
+import type { ConversationMessage, JsonObject, LLMStreamChunk, ModelResponse, ThinkingEffort } from './primitives.js';
+import type { ModelRequest } from './request.js';
+/** A model a provider offers to route selection, in the order the provider prefers them. */
+export interface ModelOption {
+    readonly id: string;
+    /** When to pick it, written for a model choosing a route: cost, speed, strengths. */
+    readonly description?: string;
+    /** The efforts it accepts, when declared. Absent means unspecified, not unrestricted. */
+    readonly thinkingEfforts?: readonly ThinkingEffort[];
+}
+/**
+ * What a provider can carry for one model, as `LLMProvider.capacity` declares it and `ctx.llm`
+ * answers it for a route. A declaration, like the told model list, never discovered from the
+ * provider at run time.
+ */
+export interface ModelCapacity {
+    /**
+     * The usable context window in tokens, or `null` when the provider declares none for the model.
+     * Shipped figures are the conservative ones a provider documents, so a consumer that trusts them
+     * errs early, never late.
+     */
+    readonly contextWindow: number | null;
+    /** Whether a request may carry provider-executed tools (`ModelRequest.providerTools`). */
+    readonly providerTools: boolean;
+    /**
+     * Whether a tool result may carry an image part: the adapter sends one and the provider accepts
+     * it. A tool that can answer with an image or in words, as `read_file` can, asks this of the route
+     * its result goes to; a thread that later moves to a route without it still sends the image it
+     * already has, and that request fails.
+     */
+    readonly toolResultImages: boolean;
+}
+/**
+ * A streamed model response: iterate for deltas, then `completed()` for what came back. A response
+ * is read once, by these rules, which an implementation enforces and a consumer may rely on.
+ * - It is iterated at most once. The read is claimed when the iterator is acquired, not at its first
+ *   `next()`, and a second `[Symbol.asyncIterator]()` throws.
+ * - `completed()` on a response nobody has read drains it, publishing nothing, and settles.
+ * - Once the read has ended, whether it ran through, its reader stopped it early (`return`) or it
+ *   failed, `completed()` returns or throws that read's outcome: a reader that left gets what
+ *   arrived as a cut-off reply, a failed read throws its failure again. The outcome is fixed when the
+ *   read ends: a cancel afterwards changes nothing.
+ * - A read ended by the caller's own cancellation (its request's abort, by the reason the signal
+ *   carries) is a cut-off, never a failure: iteration ends without throwing, and `completed()`
+ *   returns what arrived with finish `other`. A failure that only coincided with a cancel stays
+ *   the failure. This is the read only: a request cancelled before a stream exists is refused,
+ *   as `chat()` rejects with the caller's reason.
+ * - While a read is under way, from acquiring the iterator (before its first `next()` too) until it
+ *   ends, `completed()` throws rather than settle a partial. A read ends only when its last
+ *   operation, a `next` or a `return` or `throw` asked for and not yet settled, has finished; a
+ *   `next()` after a `return()` or `throw()` ends without reading.
+ */
+export type StreamingLLMResponse = AsyncIterable<LLMStreamChunk> & {
+    completed(): Promise<ModelResponse>;
+};
+/** What a model provider's client implements; a provider is offered with `registerProvider(ctx, provider, { retry })`. */
+export interface LLMClient {
+    readonly providerName: string;
+    chat(request: ModelRequest): Promise<StreamingLLMResponse>;
+    /** Optional owned transport cleanup; sessions never dispose an injected client override. */
+    dispose?(): void | Promise<void>;
+}
+/** A provider was asked for something it cannot do. Thrown, never silently dropped. */
+export declare class ProviderUnsupportedError extends Error {
+    readonly provider: string;
+    readonly feature: string;
+    constructor(provider: string, feature: string);
+}
+/**
+ * The provider refused or failed a request for exceeding the model's context window.
+ *
+ * Each provider classifies its own, from a rejected request and from a failure inside the stream,
+ * by the structured code where it has one and by its message's wording only where it has none. It
+ * carries no token count, by rule: providers state counts only in prose, if at all, and a number
+ * read from prose whose format may change is not a measurement. The provider's own error is the
+ * `cause`, so its text still reaches the journal. A failure the provider does not classify stays
+ * the error it was. A class of its own so the engine can tell this failure from every other one,
+ * as the one a shorter request can cure.
+ */
+export declare class ContextOverflowError extends Error {
+    readonly provider: string;
+    constructor(provider: string, options: {
+        cause: unknown;
+    });
+}
+/**
+ * Why a response could not be settled: `transport`, the stream ended without the provider's own
+ * evidence that the response was complete; `empty`, it completed with no text and no tool call;
+ * `length`, it had no text and no tool call because the output cap cut it (a reasoning-only reply,
+ * which a repeat would repeat); `other`, it had none for another reason the provider gave, such as a
+ * content filter; `invalid`, it settled but cannot be acted on, as when two of its calls share an id.
+ */
+export type ResponseSettlementKind = 'transport' | 'empty' | 'length' | 'other' | 'invalid';
+/**
+ * A response that cannot be taken as an answer: one the provider never finished, or finished with
+ * nothing, which an adapter's `completed()` throws (never iteration); or one the loop cannot act on,
+ * `invalid`, which the loop throws itself for any client once `completed()` returned.
+ *
+ * Each adapter decides from its provider's terminal evidence, never from a reader that stopped
+ * early: a stream its reader abandoned, or whose request was aborted, still reports what it got,
+ * as a cut-off reply. `partial` is what arrived on a `transport` or `invalid` failure — its text and
+ * reasoning, never a tool call or `provider_state` — and `null` on an `empty` one. The message starts with the
+ * kind, so the journal's error text says which it was.
+ */
+export declare class ResponseSettlementError extends Error {
+    readonly provider: string;
+    readonly kind: ResponseSettlementKind;
+    readonly partial: ConversationMessage | null;
+    readonly providerMetadata: JsonObject;
+    constructor(provider: string, kind: ResponseSettlementKind, partial: ConversationMessage | null, providerMetadata: JsonObject, detail: string);
+}
+/**
+ * A response stream that went `idleMs` without a single event from the provider: the idle deadline
+ * of one attempt, which the engine classifies as `timeout`. It bounds the wait for the first event
+ * too, from the moment the request was sent.
+ */
+export declare class StreamIdleError extends Error {
+    readonly provider: string;
+    readonly idleMs: number;
+    constructor(provider: string, idleMs: number);
+}
+/**
+ * A stream that failed while it was being read, after it had produced output: what arrived (text and
+ * reasoning, never a tool call or `provider_state`), and the failure itself as `cause`, so a reset
+ * after visible text still leaves that text on record. A stream that failed before producing
+ * anything throws its failure unwrapped.
+ */
+export declare class ResponseInterruptedError extends Error {
+    readonly provider: string;
+    readonly partial: ConversationMessage;
+    readonly providerMetadata: JsonObject;
+    constructor(provider: string, partial: ConversationMessage, providerMetadata: JsonObject, options: {
+        cause: unknown;
+    });
+}

package/dist/llm/content.d.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import type { DeepReadonly } from '../util/json.js';
+export declare const ContentPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"image">;
+    url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    data: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    media_type: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    detail: z.ZodDefault<z.ZodEnum<{
+        auto: "auto";
+        low: "low";
+        high: "high";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"file">;
+    file_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    data: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    filename: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    media_type: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>], "type">;
+export type ContentPart = z.infer<typeof ContentPartSchema>;
+/** A part as a caller writes one, with the fields the schema defaults left out. */
+export type ContentPartInput = z.input<typeof ContentPartSchema>;
+export type ContentPartKind = ContentPart['type'];
+/** Accepts what a caller writes — a string, nothing, or parts — and yields parts. */
+export declare const ContentSchema: z.ZodPreprocess<z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"image">;
+    url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    data: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    media_type: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    detail: z.ZodDefault<z.ZodEnum<{
+        auto: "auto";
+        low: "low";
+        high: "high";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"file">;
+    file_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    data: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    filename: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    media_type: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>], "type">>>, unknown>;
+export declare const textPart: (text: string) => ContentPart;
+/** The text of a content list, parts joined. Non-text parts are not text and do not appear. */
+export declare const contentText: (content: readonly DeepReadonly<ContentPart>[]) => string;

package/dist/llm/door.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `@leuduan/lagent/llm`: the model and provider contracts as the package offers them, for a provider
+ * written outside it and a host that calls a model. Every type the contract mentions, and the values
+ * a consumer uses; the schemas and helpers the engine uses itself stay inside (`index.ts`).
+ *
+ * It depends on `zod` alone, so a provider client built on it works in any harness.
+ */
+export { ContextOverflowError, ProviderUnsupportedError, ResponseInterruptedError, ResponseSettlementError, StreamIdleError, } from './client.js';
+export type { LLMClient, ModelCapacity, ModelOption, ResponseSettlementKind, StreamingLLMResponse } from './client.js';
+export { contentText } from './content.js';
+export { ModelCallError } from './failure.js';
+export type { FailureClassification, FailureKind, ModelCallClient, ModelCallHandle } from './failure.js';
+export type { DeepReadonly, ReadonlyJsonValue } from '../util/json.js';
+export type { ContentPart, ContentPartInput, ContentPartKind } from './content.js';
+export { conversationMessage, LLMStreamChunkSchema, messageText, ThinkingEffortSchema } from './primitives.js';
+export type { ConversationMessage, JsonObject, LLMStreamChunk, LLMUsage, MalformedToolCall, MessageRole, ModelResponse, ParsedToolCall, ProviderCall, ProviderState, ResponseFinish, ThinkingEffort, ToolCall, ToolSpec, } from './primitives.js';
+export { renderPromptBlocks } from './prompt.js';
+export type { PromptBlock } from './prompt.js';
+export { defaultRoute } from './provider.js';
+export type { LLMProvider, ModelRoute } from './provider.js';
+export type { ModelRequest, RequestPurpose, ResponseFormat, ToolChoice } from './request.js';

package/dist/llm/door.js

@@ -0,0 +1 @@
+import{b as p,f as d}from"../chunks/TYTQRLTX.js";import{A as l,a as r,b as e,c as o,d as t,e as n,i as m,k as s,t as f,v as a,w as x}from"../chunks/D7E6EWIE.js";export{e as ContextOverflowError,f as LLMStreamChunkSchema,p as ModelCallError,r as ProviderUnsupportedError,n as ResponseInterruptedError,o as ResponseSettlementError,t as StreamIdleError,s as ThinkingEffortSchema,m as contentText,a as conversationMessage,d as defaultRoute,x as messageText,l as renderPromptBlocks};

package/dist/llm/failure.d.ts

@@ -0,0 +1,82 @@
+/**
+ * One vocabulary for how a model call failed, and the one place a failure is given its kind.
+ *
+ * A kind decides whether `ctx.llm` retries a call and informs a host's rerun policy; it does not prove
+ * a rerun is safe. A cancellation is never a failure kind.
+ */
+import { z } from 'zod';
+import type { StreamingLLMResponse } from './client.js';
+import type { LLMProvider } from './provider.js';
+import type { ModelRequest } from './request.js';
+/**
+ * How a model call failed. `transport`, `empty`, `length` and `invalid` come from settlement and the
+ * loop; `overflow` from a `ContextOverflowError`; the rest from the provider's `classify`. Unknown is
+ * `other`.
+ */
+export declare const FAILURE_KINDS: readonly ["rate_limit", "overloaded", "transport", "timeout", "empty", "length", "invalid", "auth", "quota", "overflow", "other"];
+export type FailureKind = (typeof FAILURE_KINDS)[number];
+export declare const FailureKindSchema: z.ZodEnum<{
+    length: "length";
+    other: "other";
+    transport: "transport";
+    empty: "empty";
+    invalid: "invalid";
+    rate_limit: "rate_limit";
+    overloaded: "overloaded";
+    timeout: "timeout";
+    auth: "auth";
+    quota: "quota";
+    overflow: "overflow";
+}>;
+/**
+ * What a provider's `classify` says of a failure it was handed: its kind, and how long the provider
+ * asked the caller to wait, read only from structured fields (a header), never from prose.
+ */
+export type FailureClassification = {
+    kind: FailureKind;
+    retryAfterMs?: number;
+};
+/**
+ * A failed model call, as `ctx.llm`'s clients throw it: the provider, the kind, how many times the
+ * client was called for it, the wait the provider asked for, and the adapter's own error as `cause`.
+ * Its kind is the one authority inside the engine; the typed adapter errors are evidence for it. Its
+ * message is the cause's, so the journal's error text stays the provider's prose; the kind is a field.
+ */
+export declare class ModelCallError extends Error {
+    readonly provider: string;
+    readonly kind: FailureKind;
+    readonly attempts: number;
+    readonly retryAfterMs: number | null;
+    constructor(provider: string, kind: FailureKind, attempts: number, retryAfterMs: number | null, options: {
+        cause: unknown;
+    });
+}
+/**
+ * One model call through `ctx.llm`, handed back before it opens: its response, and how many times
+ * the provider's client has been called for it so far, whatever becomes of it, a refusal or a
+ * cancellation included.
+ */
+export interface ModelCallHandle {
+    readonly response: Promise<StreamingLLMResponse>;
+    readonly attempts: number;
+}
+/**
+ * A client from `ctx.llm`: it retries a failed call by its provider's policy and throws
+ * `ModelCallError` for one that still fails.
+ */
+export interface ModelCallClient {
+    readonly providerName: string;
+    /** Starts one call; the handle is the caller's to keep for its attempt count. */
+    call(request: ModelRequest): ModelCallHandle;
+}
+/**
+ * The kind of a failure from `provider`'s client, from typed evidence first: a settlement failure
+ * keeps its kind, a `ContextOverflowError` is `overflow`, a `StreamIdleError` is `timeout`. Only what neither says reaches the
+ * provider's `classify` (a stream interrupted after output is classified by its cause), so a provider
+ * written from scratch cannot get overflow or settlement wrong. What `classify` returns is checked
+ * before the journal sees it: a kind outside {@link FAILURE_KINDS}, or a `classify` that throws, is
+ * `other`, and a wait that is not a finite, nonnegative number is no wait (a fraction rounds up).
+ */
+export declare function classifyFailure(provider: LLMProvider, error: unknown): FailureClassification;
+/** The first `type` in `error`'s `cause` chain, itself included; middleware may wrap what was thrown. */
+export declare function findCause<T extends Error>(error: unknown, type: abstract new (...args: never[]) => T): T | undefined;

package/dist/llm/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The model layer's entry point inside the package: the model-facing alphabet and the provider
+ * contract, every name its modules export. Outer layers import from here only. What the package
+ * offers others is the narrower `door.ts` (`@leuduan/lagent/llm`).
+ *
+ * It depends on `zod` alone, so a provider client built on it works in any harness, not only in a
+ * lagent session.
+ */
+export * from './client.js';
+export * from './content.js';
+export * from './failure.js';
+export * from './primitives.js';
+export * from './prompt.js';
+export * from './provider.js';
+export * from './readLedger.js';
+export * from './request.js';