@anvia/core 1.2.1 → 1.3.0

package/dist/{types-CiHjqE6J.d.ts → types-DYqZKDA8.d.ts}

@@ -1,21 +1,33 @@
 import { M as ModelCallOptions } from './model-call-options-CZkSw_xN.js';
 
 type JsonPrimitive = string | number | boolean | null;
+/** Any JSON-compatible value: primitives, objects, or readonly arrays of JSON values. */
 type JsonValue = JsonPrimitive | JsonObject | readonly JsonValue[];
 type JsonObject = {
     [key: string]: JsonValue;
 };
+/** A retrievable text document passed to a completion as grounding context. */
 type Document = {
     id: string;
     text: string;
+    /** String metadata rendered as a `<metadata ... />` header above the text when documents are serialized into prompts. */
     additionalProps?: Record<string, string>;
 };
+/**
+ * A text segment, optionally carrying a provider reasoning signature.
+ */
 type TextPart = Readonly<{
     type: "text";
     text: string;
+    /** Provider signature preserved so reasoning can be replayed on later turns. */
     signature?: string;
 }>;
+/** Image input fidelity hint forwarded to providers that support it. */
 type ImageDetail = "auto" | "low" | "high";
+/**
+ * File payload for image/file parts: a remote URL, base64 data, or literal text
+ * interpreted as a document.
+ */
 type FileData = Readonly<{
     type: "url";
     url: string;
@@ -26,6 +38,7 @@ type FileData = Readonly<{
     type: "text";
     text: string;
 }>;
+/** Image input with an optional media type override and detail hint. */
 type ImagePart = Readonly<{
     type: "image";
     image: Exclude<FileData, Readonly<{
@@ -35,18 +48,27 @@ type ImagePart = Readonly<{
     mediaType?: string;
     detail?: ImageDetail;
 }>;
+/** Document/file input part; non-text data is rejected by models without `documentInput`. */
 type FilePart = Readonly<{
     type: "file";
     data: FileData;
     mediaType: string;
     filename?: string;
 }>;
+/** Model reasoning content, replayable across turns to preserve thinking state. */
 type ReasoningPart = Readonly<{
     type: "reasoning";
     text: string;
     id?: string;
     details?: readonly ReasoningDetail[];
 }>;
+/**
+ * Reasoning detail variants:
+ *
+ * - `text` / `summary`: displayable reasoning text
+ * - `encrypted` / `redacted`: opaque payloads that can only be echoed back to
+ *   the provider; their content is not readable by the application
+ */
 type ReasoningDetail = Readonly<{
     type: "text";
     text: string;
@@ -62,6 +84,7 @@ type ReasoningDetail = Readonly<{
     data: string;
 }>;
 type ReasoningContentType = ReasoningDetail["type"];
+/** A tool call requested by the model; `signature` preserves provider replay state. */
 type ToolCallPart = Readonly<{
     type: "tool-call";
     toolCallId: string;
@@ -70,7 +93,17 @@ type ToolCallPart = Readonly<{
     input: JsonValue;
     signature?: string;
 }>;
+/** The content variants allowed inside a tool result payload. */
 type ToolResultContentPart = TextPart | FilePart;
+/**
+ * Outcome of one tool execution, as recorded in tool messages:
+ *
+ * - `text` / `json`: successful result as plain text or JSON
+ * - `content`: successful result as mixed content parts
+ * - `execution-denied`: the call was blocked (e.g. by a required approval)
+ * - `error-text` / `error-json`: failure surfaced to the model so the run can
+ *   continue instead of aborting
+ */
 type ToolResultOutput = Readonly<{
     type: "text";
     value: string;
@@ -90,6 +123,7 @@ type ToolResultOutput = Readonly<{
     type: "error-json";
     value: JsonValue;
 }>;
+/** Tool result reported back to the model, matched to its call via `toolCallId`. */
 type ToolResultPart = Readonly<{
     type: "tool-result";
     toolCallId: string;
@@ -97,6 +131,7 @@ type ToolResultPart = Readonly<{
     toolName: string;
     output: ToolResultOutput;
 }>;
+/** Human decision on a tool call that required approval before execution. */
 type ToolApprovalResponsePart = Readonly<{
     type: "tool-approval-response";
     interactionId: string;
@@ -106,10 +141,12 @@ type ToolApprovalResponsePart = Readonly<{
     approved: boolean;
     reason?: string;
 }>;
+/** Answer to one question asked by a tool suspended on a human interaction. */
 type ToolQuestionAnswer = Readonly<{
     questionId: string;
     value: string;
 }>;
+/** Answers to tool questions, delivered back through the suspended run. */
 type ToolQuestionResponsePart = Readonly<{
     type: "tool-question-response";
     interactionId: string;
@@ -118,8 +155,11 @@ type ToolQuestionResponsePart = Readonly<{
     toolName: string;
     answers: readonly ToolQuestionAnswer[];
 }>;
+/** A tool or human-interaction response delivered inside a `role: "tool"` message. */
 type ToolInteractionResponsePart = ToolApprovalResponsePart | ToolQuestionResponsePart;
+/** Content parts allowed in user messages. */
 type UserContentPart = TextPart | ImagePart | FilePart;
+/** Content parts allowed in assistant messages, including replayed reasoning and tool calls. */
 type AssistantContentPart = TextPart | ImagePart | FilePart | ReasoningPart | ToolCallPart;
 type SystemMessage<Metadata extends JsonObject = JsonObject> = Readonly<{
     role: "system";
@@ -142,12 +182,25 @@ type ToolMessage<Metadata extends JsonObject = JsonObject> = Readonly<{
     content: readonly (ToolResultPart | ToolInteractionResponsePart)[];
     metadata?: Metadata;
 }>;
+/**
+ * A conversation message from the system, user, assistant, or tool role.
+ *
+ * Framework-generated metadata (provider, model, usage of the generation that
+ * produced an assistant message) is stored under the `anvia` key of `metadata`;
+ * read it back with {@link getAssistantGenerationMetadata}.
+ */
 type Message<Metadata extends JsonObject = JsonObject> = SystemMessage<Metadata> | UserMessage<Metadata> | AssistantMessage<Metadata> | ToolMessage<Metadata>;
+/** Joins the human-readable text of a reasoning part or its details. */
 declare function reasoningDisplayText(reasoning: ReasoningPart | readonly ReasoningDetail[]): string;
+/**
+ * How the model may call tools: freely, mandatorily, never, or a named function.
+ * Requires the model's `toolChoice` capability.
+ */
 type ToolChoice = "auto" | "required" | "none" | {
     type: "function";
     name: string;
 };
+/** JSON Schema-shaped tool description sent to the model (a local tool's public face). */
 type ToolDefinition = {
     name: string;
     description: string;
@@ -166,7 +219,9 @@ type ProviderTool = {
     configuration?: JsonObject;
 };
 type CompletionTool = ToolDefinition | ProviderTool;
+/** Narrows an unknown value to a well-formed {@link ProviderTool}. */
 declare function isProviderTool(value: unknown): value is ProviderTool;
+/** A grounding source (e.g. web result) returned by the provider, with optional text offsets. */
 type CompletionSource = {
     type: "url";
     url: string;
@@ -175,6 +230,7 @@ type CompletionSource = {
     startIndex?: number;
     endIndex?: number;
 };
+/** A tool call executed on the provider side, surfaced for observability. */
 type ProviderToolCall = {
     id: string;
     name: string;
@@ -188,15 +244,18 @@ type ProviderToolCall = {
  * only aggregate key and should equal the sum of the other buckets.
  */
 type UsageDetails = Record<string, number>;
+/** Model context window bounds; unset input/output caps fall back to the window. */
 type ModelContextLimits = {
     contextWindow: number;
     maxInputTokens?: number;
     maxOutputTokens?: number;
 };
+/** Identifies a model together with its context limits. */
 type CompletionModelInfo = {
     modelId: string;
     context: ModelContextLimits;
 };
+/** Snapshot of how much of a model's context window a request consumed. */
 type ContextUsage = {
     model: CompletionModelInfo;
     usedTokens: number;
@@ -204,9 +263,13 @@ type ContextUsage = {
     usedPercent: number;
     remainingPercent: number;
 };
+/** Computes context usage, or undefined when the model or usage data is unusable. */
 declare function calculateContextUsage(usage: Usage, model: CompletionModelInfo | undefined): ContextUsage | undefined;
+/** Attaches context usage to a response when model limits are known. */
 declare function withContextUsage<RawResponse>(response: CompletionResponse<RawResponse>, model: CompletionModelInfo | undefined): CompletionResponse<RawResponse>;
+/** Resolves a model's context limits: explicit override wins over catalog lookup. */
 declare function resolveModelContextLimits(modelId: string, catalog: Readonly<Record<string, ModelContextLimits>>, override?: ModelContextLimits): ModelContextLimits | undefined;
+/** Provider/model/usage metadata embedded in assistant message metadata by the runtime. */
 type AssistantGenerationMetadata = {
     provider: string;
     modelId: string;
@@ -217,6 +280,13 @@ type AssistantGenerationMetadata = {
     sources?: CompletionSource[];
     providerToolCalls?: ProviderToolCall[];
 };
+/**
+ * Token usage for one or more generations.
+ *
+ * `cachedInputTokens` counts input tokens served from the provider's prompt
+ * cache; `cacheCreationInputTokens` counts input tokens billed for writing to
+ * that cache. Both are subsets of `inputTokens`.
+ */
 type Usage = {
     inputTokens: number;
     outputTokens: number;
@@ -225,12 +295,26 @@ type Usage = {
     cacheCreationInputTokens: number;
     details?: UsageDetails;
 };
+/**
+ * Helpers for constructing and combining token usage.
+ */
 declare const Usage: {
+    /** Returns an all-zero usage value. */
     empty(): Usage;
+    /**
+     * Sums two usage values bucket by bucket. `details` are merged only when
+     * both sides carry them; if either side omits them, the result omits them.
+     */
     add(left: Usage, right: Usage): Usage;
+    /** Returns true when every bucket, including `details`, is zero. */
     isEmpty(usage: Usage): boolean;
 };
+/**
+ * Reads the generation metadata the runtime embeds in assistant messages, when
+ * present and structurally valid.
+ */
 declare function getAssistantGenerationMetadata(message: Message): AssistantGenerationMetadata | undefined;
+/** Provider-agnostic completion request assembled by the runtime for adapters. */
 type CompletionRequest = {
     instructions?: string;
     chatHistory: Message[];
@@ -240,25 +324,45 @@ type CompletionRequest = {
     temperature?: number;
     maxTokens?: number;
     toolChoice?: ToolChoice;
+    /** Values for the model's declared completion controls; validated before sending. */
     controls?: Readonly<Record<string, string>>;
+    /** Provider-specific passthrough options; never validated by the core runtime. */
     providerOptions?: JsonObject;
+    /** JSON Schema the output must conform to; requires the `outputSchema` capability. */
     outputSchema?: JsonObject;
 };
+/** Normalized finish reasons:
+ *
+ * - `stop`: the model finished naturally
+ * - `length`: an output token limit was hit
+ * - `content-filter`: output was blocked by a safety filter
+ * - `tool-calls`: the model stopped to request tool calls
+ * - `other`: any provider-specific reason
+ */
 type CompletionFinishReason = "stop" | "length" | "content-filter" | "tool-calls" | "other";
+/** A provider's raw completion response: normalized parts plus usage and metadata. */
 type CompletionResponse<RawResponse = unknown> = {
     choice: AssistantContentPart[];
     usage: Usage;
     finishReason?: CompletionFinishReason;
     providerFinishReason?: string;
     contextUsage?: ContextUsage;
+    /** The provider SDK's original response object, unmodified. */
     rawResponse: RawResponse;
     messageId?: string;
     sources?: CompletionSource[];
     providerToolCalls?: ProviderToolCall[];
 };
+/** Final result of a completion: typed output, plain text, full content, and usage. */
 type CompletionResult<Output = string, RawResponse = unknown> = {
+    /**
+     * The typed output. When an output schema was requested this is the parsed,
+     * validated object; otherwise it is the plain text.
+     */
     output: Output;
+    /** The generated text, joined from the response's text parts. */
     text: string;
+    /** Every content part the model produced, including reasoning and tool calls. */
     content: readonly AssistantContentPart[];
     usage: Usage;
     finishReason?: CompletionFinishReason;
@@ -269,6 +373,7 @@ type CompletionResult<Output = string, RawResponse = unknown> = {
     sources?: readonly CompletionSource[];
     providerToolCalls?: readonly ProviderToolCall[];
 };
+/** Feature flags a model declares; requests are validated against these at runtime. */
 type CompletionModelCapabilities = {
     streaming: boolean;
     tools: boolean;
@@ -279,6 +384,7 @@ type CompletionModelCapabilities = {
     reasoning: boolean;
     providerTools?: boolean;
 };
+/** A selectable model control exposed to applications (e.g. "reasoning effort"). */
 type CompletionModelSelectControl<Option extends string = string> = Readonly<{
     type: "select";
     label: string;
@@ -286,24 +392,50 @@ type CompletionModelSelectControl<Option extends string = string> = Readonly<{
     description?: string | undefined;
     defaultValue?: Option | undefined;
 }>;
+/** Named set of controls a model supports, keyed by control id. */
 type CompletionModelControls = Readonly<Record<string, CompletionModelSelectControl<string>>>;
+/** Marker type for models that accept no completion controls. */
 type NoCompletionModelControls = Readonly<Record<string, never>>;
+/** The option values a model's controls accept, keyed by control id. */
 type CompletionControlValues<Controls extends CompletionModelControls> = Readonly<Partial<{
     [Key in keyof Controls]: Controls[Key] extends CompletionModelSelectControl<infer Option> ? Option : never;
 }>>;
+/** Extracts a model's control types, defaulting to the open controls record. */
 type CompletionModelControlsOf<Model> = Model extends CompletionModel<unknown, infer Controls> ? Controls : CompletionModelControls;
+/**
+ * The provider-agnostic model contract every adapter implements: non-streaming
+ * completions plus capability, context, and control metadata.
+ */
 interface CompletionModel<RawResponse = unknown, Controls extends CompletionModelControls = CompletionModelControls> {
     readonly provider: string;
     readonly modelId: string;
     readonly contextLimits?: ModelContextLimits | undefined;
     readonly capabilities: CompletionModelCapabilities;
     readonly controls?: Controls | undefined;
+    /**
+     * Returns a JSON-safe representation of the outgoing request for
+     * observability traces, or undefined to omit the trace payload. Errors
+     * thrown here are swallowed by the runtime and recorded as a trace error.
+     */
     traceRequest?(request: CompletionRequest, options?: {
         stream?: boolean | undefined;
     }): JsonObject | undefined;
     completion(request: CompletionRequest, options?: ModelCallOptions): Promise<CompletionResponse<RawResponse>>;
 }
+/** How a `tool_call_delta` updates arguments: append to, or replace, accumulated JSON. */
 type ToolCallArgumentsMode = "append" | "replace";
+/**
+ * Incremental completion stream content:
+ *
+ * - `text_delta` / `reasoning_delta`: incremental text or reasoning content
+ * - `tool_call_delta`: partial tool call input; argument fragments accumulate
+ *   according to `argumentsMode` (`append` continues the JSON string, `replace`
+ *   restarts it)
+ * - `tool_call`: a complete tool call
+ * - `source`: a grounding source discovered during generation
+ * - `provider_tool_call`: progress on a provider-executed tool
+ * - `message_id`: the id of the message being generated
+ */
 type CompletionStreamPart = {
     type: "text_delta";
     delta: string;
@@ -312,6 +444,7 @@ type CompletionStreamPart = {
     delta: string;
     id?: string;
     contentType?: ReasoningContentType;
+    /** Provider signature preserved for reasoning replay. */
     signature?: string;
 } | {
     type: "tool_call_delta";
@@ -334,6 +467,7 @@ type CompletionStreamPart = {
     type: "message_id";
     id: string;
 };
+/** Raw model stream events: stream parts, the final response, or a terminal error. */
 type CompletionModelStreamEvent<RawResponse = unknown> = CompletionStreamPart | {
     type: "final";
     response: CompletionResponse<RawResponse>;
@@ -342,6 +476,7 @@ type CompletionModelStreamEvent<RawResponse = unknown> = CompletionStreamPart |
     error: unknown;
     usage?: Usage;
 };
+/** High-level stream events: stream parts, the final typed result, or a terminal error. */
 type CompletionStreamEvent<Output = string, RawResponse = unknown> = CompletionStreamPart | {
     type: "final";
     result: CompletionResult<Output, RawResponse>;
@@ -350,16 +485,21 @@ type CompletionStreamEvent<Output = string, RawResponse = unknown> = CompletionS
     error: unknown;
     usage: Usage;
 };
+/** A completion model that can additionally stream events as they are produced. */
 interface StreamingCompletionModel<RawResponse = unknown, Controls extends CompletionModelControls = CompletionModelControls> extends CompletionModel<RawResponse, Controls> {
     streamCompletion(request: CompletionRequest, options?: ModelCallOptions): AsyncIterable<CompletionModelStreamEvent<RawResponse>>;
 }
+/** Thrown when a request uses a capability the target model does not declare. */
 declare class CompletionCapabilityError extends Error {
     constructor(message: string);
 }
+/** Validates a request against a model's declared capabilities; throws {@link CompletionCapabilityError}. */
 declare function assertCompletionRequestSupported(model: CompletionModel, request: CompletionRequest, options?: {
     streaming?: boolean | undefined;
 }): void;
+/** Validates control values against a model's controls; throws {@link CompletionCapabilityError}. */
 declare function assertCompletionControlsSupported(model: CompletionModel, controls: Readonly<Record<string, string | undefined>> | undefined): void;
+/** Joins the text parts of assistant content with newlines. */
 declare function textFromAssistantContent(content: readonly AssistantContentPart[]): string;
 
 export { type CompletionStreamPart as $, type AssistantContentPart as A, type ToolDefinition as B, type CompletionControlValues as C, type Document as D, type ToolMessage as E, type FileData as F, type ToolResultContentPart as G, type ToolResultOutput as H, type ImageDetail as I, type JsonObject as J, type ToolResultPart as K, type UserContentPart as L, type Message as M, type NoCompletionModelControls as N, type UserMessage as O, type ProviderTool as P, calculateContextUsage as Q, type ReasoningContentType as R, type SystemMessage as S, type TextPart as T, Usage as U, getAssistantGenerationMetadata as V, isProviderTool as W, resolveModelContextLimits as X, withContextUsage as Y, CompletionCapabilityError as Z, type CompletionModelCapabilities as _, type AssistantGenerationMetadata as a, type StreamingCompletionModel as a0, type ToolApprovalResponsePart as a1, type ToolCallArgumentsMode as a2, type ToolInteractionResponsePart as a3, type ToolQuestionAnswer as a4, type ToolQuestionResponsePart as a5, type UsageDetails as a6, assertCompletionControlsSupported as a7, assertCompletionRequestSupported as a8, reasoningDisplayText as a9, textFromAssistantContent as aa, type AssistantMessage as b, type CompletionFinishReason as c, type CompletionModel as d, type CompletionModelControls as e, type CompletionModelControlsOf as f, type CompletionModelInfo as g, type CompletionModelSelectControl as h, type CompletionModelStreamEvent as i, type CompletionRequest as j, type CompletionResponse as k, type CompletionResult as l, type CompletionSource as m, type CompletionStreamEvent as n, type CompletionTool as o, type ContextUsage as p, type FilePart as q, type ImagePart as r, type JsonPrimitive as s, type JsonValue as t, type ModelContextLimits as u, type ProviderToolCall as v, type ReasoningDetail as w, type ReasoningPart as x, type ToolCallPart as y, type ToolChoice as z };

package/dist/{types-CafU6Ux5.d.ts → types-DhWxTobb.d.ts}

@@ -1,19 +1,31 @@
-import { U as Usage, J as JsonObject, M as Message, S as SystemMessage, d as CompletionModel } from './types-CiHjqE6J.js';
+import { U as Usage, J as JsonObject, M as Message, S as SystemMessage, d as CompletionModel } from './types-DYqZKDA8.js';
 import { b as RetrySetting } from './retry-CjvSlKGW.js';
 
+/**
+ * Granularity at which produced messages are persisted:
+ *
+ * - `message`: after each individual message
+ * - `turn`: after each agent turn completes
+ * - `run`: once when the run finishes
+ */
 type MemorySavePolicy = "message" | "turn" | "run";
+/** Identifies a conversation within a memory store. */
 type MemoryScope = {
     sessionId: string;
     userId?: string | undefined;
     metadata?: JsonObject | undefined;
 };
+/** Options controlling how a memory scope is reduced to a storage key. */
 type MemoryScopeKeyOptions = {
+    /** Includes `scope.userId` in the derived key. */
     includeUserId?: boolean | undefined;
+    /** Metadata entries (by key) included in the derived key. */
     metadataKeys?: readonly string[] | undefined;
 };
 type CreateMemoryScopeKeyOptions = MemoryScopeKeyOptions & {
     scope: MemoryScope;
 };
+/** Either key-derivation options or a custom resolver function. */
 type MemoryScopeKeyResolver = MemoryScopeKeyOptions | ((options: {
     scope: MemoryScope;
 }) => string);
@@ -42,6 +54,7 @@ type MemoryConversationListOptions = {
 type MemoryConversationGetOptions = {
     ref: string;
 };
+/** Persisted summary of a stored conversation. */
 type MemoryConversationSummary = {
     /** Opaque, store-specific reference used to retrieve this exact conversation. */
     ref: string;
@@ -52,6 +65,7 @@ type MemoryConversationSummary = {
     updatedAt: string;
     messageCount: number;
 };
+/** One stored message with its position and originating run/turn. */
 type MemoryConversationMessage = {
     position: number;
     runId: string;
@@ -59,6 +73,7 @@ type MemoryConversationMessage = {
     createdAt: string;
     message: Message;
 };
+/** A full stored conversation: summary plus replayable messages. */
 type MemoryConversation = MemoryConversationSummary & {
     messages: MemoryConversationMessage[];
 };
@@ -67,6 +82,11 @@ interface MemoryInspector {
     listConversations(options: MemoryConversationListOptions): Promise<MemoryConversationSummary[]>;
     getConversation(options: MemoryConversationGetOptions): Promise<MemoryConversation | undefined>;
 }
+/**
+ * Append-only conversation storage. The runtime loads history at run start,
+ * appends produced messages per the configured {@link MemorySavePolicy}, and
+ * clears on demand. `load` must return the canonical, replayable history.
+ */
 interface MemoryStore {
     readonly inspector?: MemoryInspector | undefined;
     readonly compaction?: MemoryCompactionCapability | undefined;
@@ -74,12 +94,16 @@ interface MemoryStore {
     load(options: MemoryLoadOptions): Promise<Message[]>;
     append(options: MemoryAppendOptions): Promise<void>;
     clear(options: MemoryClearOptions): Promise<void>;
+    /** Records a failed run for debugging; unsupported stores may omit it. */
     recordError?(options: MemoryErrorOptions): Promise<void>;
 }
+/** Metadata embedded in a compaction summary message. */
 type MemoryCompactionMetadata = {
+    /** Schema version of the compaction marker. */
     version: 1;
     compactedMessageCount: number;
 };
+/** A system message that stores a summary checkpoint in the conversation history. */
 type MemoryCompactionMessage = Omit<SystemMessage, "metadata"> & {
     metadata: {
         anvia: {
@@ -104,6 +128,7 @@ type MemoryCompactionReplacePrefixOptions = {
     replacement: MemoryCompactionMessage;
     runId: string;
 };
+/** Result of a prefix replacement: `conflict` means the revision was stale and the replacement was rejected. */
 type MemoryCompactionReplacePrefixResult = {
     status: "committed" | "conflict";
 };
@@ -126,9 +151,11 @@ type MemoryCompactorResult = {
     summary: string;
     usage?: Usage | undefined;
 };
+/** Summarizes a list of messages into a compact replacement. */
 type MemoryCompactor = (input: MemoryCompactorInput) => Promise<MemoryCompactorResult>;
 /** Counts the approximate or exact model tokens represented by a message list. */
 type MemoryTokenCounter = (messages: readonly Message[]) => number | Promise<number>;
+/** Options for the built-in, model-backed summary compactor. */
 type CreateSummaryMemoryCompactorOptions = {
     model: CompletionModel;
     instructions?: string | undefined;
@@ -140,21 +167,29 @@ type CreateSummaryMemoryCompactorOptions = {
 type MemoryCompactionConflictRetryOptions = {
     maxAttempts: number;
 };
+/** When and how session memory is compacted. */
 type MemoryCompactionOptions = {
     trigger: {
+        /** Compaction runs when the projected context exceeds this token count. */
         afterTokens: number;
     };
     retention?: {
+        /** Messages within this token budget of the end stay unsummarized. */
         recentTokens?: number | undefined;
     };
+    /** Overrides the default approximate counter; use a model counter for exact budgets. */
     tokenCounter?: MemoryTokenCounter | undefined;
     compactor: MemoryCompactor;
+    /** `false` disables retrying when a store reports a revision conflict. */
     conflictRetries?: false | MemoryCompactionConflictRetryOptions | undefined;
 };
+/** Memory settings for an agent. */
 type MemoryOptions = {
+    /** @default "message" */
     savePolicy?: MemorySavePolicy | undefined;
     compaction?: MemoryCompactionOptions | undefined;
 };
+/** Measurements recorded for one compaction attempt. */
 type MemoryCompactionInfo = {
     originalMessageCount: number;
     compactedMessageCount: number;
@@ -166,6 +201,7 @@ type MemoryCompactionInfo = {
     attempts: number;
     usage: Usage;
 };
+/** Outcome of a compaction attempt: performed, or skipped because there was nothing to compact. */
 type MemoryCompactionResult = ({
     type: "compacted";
 } & MemoryCompactionInfo) | {

package/dist/vector-store/index.d.ts

@@ -1,9 +1,9 @@
 import { V as VectorMetadata, b as VectorMetadataValue, E as EmbeddingModel, a as EmbeddedDocument } from '../types-Cr4uiYo5.js';
-import { T as Tool } from '../tool-DQMZpZSS.js';
-import { V as VectorFilter, d as VectorStore, R as RetrieveDocumentsOptions, a as VectorSearchResult, f as RetrieveHybridDocumentsOptions, I as IndexStrategy, g as VectorStoreUpsertOptions, h as VectorSearchRequest, b as VectorInspectRequest, c as VectorInspectPage, i as VectorSearchToolOptions } from '../types-CODGMHnp.js';
-export { D as DenseVectorSearchToolOptions, j as HybridVectorSearchRequest, k as HybridVectorSearchToolOptions, H as HybridVectorStore, L as LshOptions, l as RetrieveDocumentsBaseOptions, e as VectorFusion, m as VectorInspectItem, n as VectorMetric, o as VectorSearchToolBaseOptions } from '../types-CODGMHnp.js';
+import { T as Tool } from '../tool-D_jV3cRZ.js';
+import { V as VectorFilter, d as VectorStore, R as RetrieveDocumentsOptions, a as VectorSearchResult, f as RetrieveHybridDocumentsOptions, I as IndexStrategy, g as VectorStoreUpsertOptions, h as VectorSearchRequest, b as VectorInspectRequest, c as VectorInspectPage, i as VectorSearchToolOptions } from '../types-ChyQISt-.js';
+export { D as DenseVectorSearchToolOptions, j as HybridVectorSearchRequest, k as HybridVectorSearchToolOptions, H as HybridVectorStore, L as LshOptions, l as RetrieveDocumentsBaseOptions, e as VectorFusion, m as VectorInspectItem, n as VectorMetric, o as VectorSearchToolBaseOptions } from '../types-ChyQISt-.js';
 import { b as RetrySetting } from '../retry-CjvSlKGW.js';
-import { J as JsonObject } from '../types-CiHjqE6J.js';
+import { J as JsonObject } from '../types-DYqZKDA8.js';
 import { T as TextDocument, b as TextDocumentChunkingOptions } from '../text-document-B-X7Vxq1.js';
 import '../model-call-options-CZkSw_xN.js';
 

package/dist/vector-store/index.js

@@ -1,7 +1,11 @@
 import {
   InMemoryVectorStore,
   createVectorSearchTool
-} from "../chunk-72LBHKYP.js";
+} from "../chunk-JWD43K7W.js";
+import {
+  ingestVectorDocuments,
+  ingestVectorText
+} from "../chunk-QHGYCYV6.js";
 import "../chunk-ESOFEAYK.js";
 import {
   retrieveDocuments
@@ -10,10 +14,6 @@ import {
   matchesVectorFilter,
   vectorFilter
 } from "../chunk-5WLIHNNJ.js";
-import {
-  ingestVectorDocuments,
-  ingestVectorText
-} from "../chunk-QHGYCYV6.js";
 import "../chunk-ERN7P6Q4.js";
 import "../chunk-7F53DOML.js";
 import "../chunk-HHMLE3TZ.js";
@@ -23,10 +23,10 @@ import "../chunk-KO5NMTAM.js";
 import "../chunk-TFIOU6UR.js";
 import "../chunk-GPVXCY5I.js";
 import "../chunk-5V533R7F.js";
-import "../chunk-XV3DH5GC.js";
+import "../chunk-Y365ABZY.js";
+import "../chunk-647TQE3E.js";
 import "../chunk-YZVFIW5D.js";
-import "../chunk-MHOJJYDK.js";
-import "../chunk-47NTHIVB.js";
+import "../chunk-SCFWN3T2.js";
 import "../chunk-J6S6MT7O.js";
 import "../chunk-BONQTXRQ.js";
 import "../chunk-4C7AXYOM.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anvia/core",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Core runtime primitives for context-aware Anvia agents.",
   "author": "anvia",
   "license": "MIT",
@@ -113,12 +113,20 @@
     "yaml": "^2.9.0"
   },
   "peerDependencies": {
+    "@valibot/to-json-schema": "^1.7.1",
     "zod": "^4.4.0"
   },
+  "peerDependenciesMeta": {
+    "@valibot/to-json-schema": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/node": "^24.9.1",
+    "@valibot/to-json-schema": "^1.7.1",
     "tsup": "^8.5.0",
     "typescript": "^5.9.3",
+    "valibot": "^1.5.0",
     "vitest": "^4.0.8",
     "zod": "^4.5.4"
   },

package/dist/chunk-47NTHIVB.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/tool/tool.ts"],"sourcesContent":["import { isJsonValue } from \"../completion/json\";\nimport { parseMessage } from \"../completion/message-schema\";\nimport type {\n  JsonObject,\n  JsonValue,\n  ToolDefinition,\n  ToolResultContentPart,\n  ToolResultOutput,\n} from \"../completion/types\";\n\nexport type ToolApprovalRunContext = {\n  agentId: string;\n  runId: string;\n  sessionId?: string;\n  metadata?: JsonObject;\n};\n\nexport type ToolApprovalContext<Args = unknown> = {\n  toolName: string;\n  args: Args;\n  rawArgs: string;\n  toolCallId: string;\n  callId?: string;\n  internalCallId: string;\n  run: ToolApprovalRunContext;\n};\n\nexport type ToolApprovalRequirement = {\n  reason?: string | undefined;\n};\n\nexport type ToolRequiresApproval<Args = unknown> =\n  | boolean\n  | ToolApprovalRequirement\n  | ((\n      args: Args,\n      context: ToolApprovalContext<Args>,\n    ) => boolean | ToolApprovalRequirement | Promise<boolean | ToolApprovalRequirement>);\n\nexport type ToolCallStreamEvent = {\n  agentId: string;\n  agentName?: string | undefined;\n  event: unknown;\n};\n\nexport type ToolCallContext = {\n  emitStreamEvent?(event: ToolCallStreamEvent): void | Promise<void>;\n  abortSignal?: AbortSignal | undefined;\n};\n\nexport interface Tool<Args = unknown, Output = unknown> {\n  readonly name: string;\n  readonly requiresApproval?: ToolRequiresApproval<Args>;\n  definition(prompt: string): ToolDefinition | Promise<ToolDefinition>;\n  call(args: Args, context?: ToolCallContext): Output | Promise<Output>;\n  parseInput?(args: JsonValue): Args;\n}\n\nexport type AnyTool = Omit<Tool<unknown, unknown>, \"requiresApproval\"> & {\n  readonly requiresApproval?: unknown;\n};\n\nconst richToolOutput: unique symbol = Symbol.for(\"anvia.tool-output.content\");\n\nexport type RichToolOutput = Readonly<{\n  [richToolOutput]: true;\n  content: readonly ToolResultContentPart[];\n}>;\n\nexport type NormalizedToolOutput = ToolResultOutput;\n\nexport class ToolResultSerializationError extends TypeError {\n  constructor(readonly output: unknown) {\n    super(\"Tool output must be a string, a strict JSON value, or ToolOutput.content(...).\");\n    this.name = \"ToolResultSerializationError\";\n  }\n}\n\nexport const ToolOutput = {\n  content(content: readonly ToolResultContentPart[]): RichToolOutput {\n    return { [richToolOutput]: true, content };\n  },\n};\n\nexport function normalizeToolResultOutput(output: unknown): NormalizedToolOutput {\n  if (typeof output === \"string\") {\n    return { type: \"text\", value: output };\n  }\n  if (isRichToolOutput(output)) {\n    try {\n      const message = parseMessage({\n        role: \"tool\",\n        content: [\n          {\n            type: \"tool-result\",\n            toolCallId: \"validation\",\n            toolName: \"validation\",\n            output: { type: \"content\", value: output.content },\n          },\n        ],\n      });\n      if (message.role !== \"tool\") throw new TypeError(\"Unexpected message role\");\n      const result = message.content[0];\n      if (result?.type !== \"tool-result\") throw new TypeError(\"Unexpected tool result part\");\n      if (result?.output.type !== \"content\") throw new TypeError(\"Unexpected tool output\");\n      return result.output;\n    } catch {\n      throw new ToolResultSerializationError(output);\n    }\n  }\n  if (isJsonValue(output)) {\n    return { type: \"json\", value: output };\n  }\n  throw new ToolResultSerializationError(output);\n}\n\nexport function toolResultContentToText(content: readonly ToolResultContentPart[]): string {\n  return content\n    .map((item) => (item.type === \"text\" ? item.text : `[file:${item.mediaType}]`))\n    .join(\"\\n\");\n}\n\nfunction isRichToolOutput(value: unknown): value is RichToolOutput {\n  if (typeof value !== \"object\" || value === null) return false;\n  return Object.getOwnPropertyDescriptor(value, richToolOutput)?.value === true;\n}\n\nexport function parseToolArgs(args: string): JsonValue {\n  const value: unknown = JSON.parse(args);\n  if (!isJsonValue(value)) {\n    throw new TypeError(\"Tool arguments must be a JSON value.\");\n  }\n  return value;\n}\n"],"mappings":";;;;;;;;AA8DA,IAAM,iBAAgC,uBAAO,IAAI,2BAA2B;AASrE,IAAM,+BAAN,cAA2C,UAAU;AAAA,EAC1D,YAAqB,QAAiB;AACpC,UAAM,gFAAgF;AADnE;AAEnB,SAAK,OAAO;AAAA,EACd;AAAA,EAHqB;AAIvB;AAEO,IAAM,aAAa;AAAA,EACxB,QAAQ,SAA2D;AACjE,WAAO,EAAE,CAAC,cAAc,GAAG,MAAM,QAAQ;AAAA,EAC3C;AACF;AAEO,SAAS,0BAA0B,QAAuC;AAC/E,MAAI,OAAO,WAAW,UAAU;AAC9B,WAAO,EAAE,MAAM,QAAQ,OAAO,OAAO;AAAA,EACvC;AACA,MAAI,iBAAiB,MAAM,GAAG;AAC5B,QAAI;AACF,YAAM,UAAU,aAAa;AAAA,QAC3B,MAAM;AAAA,QACN,SAAS;AAAA,UACP;AAAA,YACE,MAAM;AAAA,YACN,YAAY;AAAA,YACZ,UAAU;AAAA,YACV,QAAQ,EAAE,MAAM,WAAW,OAAO,OAAO,QAAQ;AAAA,UACnD;AAAA,QACF;AAAA,MACF,CAAC;AACD,UAAI,QAAQ,SAAS,OAAQ,OAAM,IAAI,UAAU,yBAAyB;AAC1E,YAAM,SAAS,QAAQ,QAAQ,CAAC;AAChC,UAAI,QAAQ,SAAS,cAAe,OAAM,IAAI,UAAU,6BAA6B;AACrF,UAAI,QAAQ,OAAO,SAAS,UAAW,OAAM,IAAI,UAAU,wBAAwB;AACnF,aAAO,OAAO;AAAA,IAChB,QAAQ;AACN,YAAM,IAAI,6BAA6B,MAAM;AAAA,IAC/C;AAAA,EACF;AACA,MAAI,YAAY,MAAM,GAAG;AACvB,WAAO,EAAE,MAAM,QAAQ,OAAO,OAAO;AAAA,EACvC;AACA,QAAM,IAAI,6BAA6B,MAAM;AAC/C;AAEO,SAAS,wBAAwB,SAAmD;AACzF,SAAO,QACJ,IAAI,CAAC,SAAU,KAAK,SAAS,SAAS,KAAK,OAAO,SAAS,KAAK,SAAS,GAAI,EAC7E,KAAK,IAAI;AACd;AAEA,SAAS,iBAAiB,OAAyC;AACjE,MAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AACxD,SAAO,OAAO,yBAAyB,OAAO,cAAc,GAAG,UAAU;AAC3E;AAEO,SAAS,cAAc,MAAyB;AACrD,QAAM,QAAiB,KAAK,MAAM,IAAI;AACtC,MAAI,CAAC,YAAY,KAAK,GAAG;AACvB,UAAM,IAAI,UAAU,sCAAsC;AAAA,EAC5D;AACA,SAAO;AACT;","names":[]}