@anvia/core 1.5.1 → 1.6.1

package/README.md

@@ -1,1108 +1,67 @@
 # @anvia/core
 
-Small, explicit, embeddable runtime contracts for Anvia agents, tools, structured extraction, pipelines, streaming, RAG, MCP, skills, and observability.
+Build provider-independent AI agents and workflows with typed tools, streaming, structured output,
+and application-owned memory. Core runs the model/tool loop while your application chooses providers,
+credentials, storage, and delivery.
 
-This package is provider-neutral. Pair it with a provider adapter such as `@anvia/openai`, `@anvia/anthropic`, or `@anvia/gemini` to create runnable model objects, then pass those objects into agents, extractors, pipelines, or direct completion helpers.
-
-## Design Philosophy
-
-`@anvia/core` owns the model/tool loop and the runtime contracts around it. Your application owns provider client construction, credentials, product data access, permissions, storage, deployment, observability backends, and response shape.
-
-The package is dependency-injection oriented: create provider models, typed tools, memory stores, vector indexes, observers, and services in application code, then pass the relevant objects into agents, prompt requests, runners, or adapters. Core receives those objects and coordinates the run without taking over product architecture.
-
-## Installation
-
-Anvia 1.0 is currently published on npm under the `rc` tag. The unqualified `latest` tag remains
-on the maintenance-only v0 line until 1.0 reaches general availability. Keep Core and every Anvia
-adapter on the same release channel.
-
-```sh
-pnpm add @anvia/core@rc
-```
-
-### Bun
-
-Bun 1.3.14 is the currently tested and supported runtime baseline. Install Core on the same
-release channel as the rest of your Anvia packages:
+## Install
 
 ```sh
-bun add @anvia/core@rc
+pnpm add @anvia/core @anvia/openai zod
 ```
 
-The repository itself remains a pnpm workspace; Bun support applies to applications consuming the
-published package.
+This example uses OpenAI. Other provider adapters work with the same Core APIs.
 
-See the repository's [1.0 release policy](../../docs/releases/v1.md) for channel and support
-details.
+## Quickstart
 
-In this monorepo, the package is available through the workspace:
-
-```sh
-pnpm --filter @anvia/core build
-```
-
-## Usage
+Set `OPENAI_API_KEY` in your server environment, then create an agent with a typed tool:
 
 ```ts
-import { z } from "zod";
 import { Agent, createTool } from "@anvia/core";
 import { OpenAIClient } from "@anvia/openai";
+import { z } from "zod";
 
-const client = new OpenAIClient({
-  apiKey,
-});
-
-const model = client.completionModel({ modelId: "gpt-5", api: "responses" });
-
+const apiKey = process.env.OPENAI_API_KEY;
+if (!apiKey) throw new Error("Set OPENAI_API_KEY.");
+const client = new OpenAIClient({ apiKey });
 const lookupOrder = createTool({
   name: "lookup_order",
-  description: "Look up an order by id.",
+  description: "Look up an order by ID.",
   inputSchema: z.object({ orderId: z.string() }),
   execute: async ({ orderId }) => ({ orderId, status: "processing" }),
 });
 
 const agent = new Agent({
   id: "support",
-  model,
+  model: client.completionModel({ modelId: "gpt-5", api: "responses" }),
   instructions: "Help customers with order questions.",
-  maxTurns: 4,
   tools: [lookupOrder],
+  maxTurns: 4,
 });
 
 const result = await agent.generate({ prompt: "What is happening with order A123?" });
 if (result.type === "response") console.log(result.output);
 ```
 
-## Agent teams
-
-`AgentTeam` coordinates ordinary `Agent` definitions and gives each spawned instance its own
-conversation and inbox. The coordinator chooses when to spawn members and can create multiple
-instances of the same definition. Tools keep the usual `tools: []` shape; members receive only their
-own configured tools and the runtime's communication tools.
-
-```ts
-import { Agent, AgentTeam } from "@anvia/core/agent";
-
-// model, readFileTool, and searchTool are application-owned objects.
-const researcher = new Agent({
-  id: "researcher",
-  model,
-  description: "Research a specific question and report evidence.",
-  instructions: "Ask your parent for clarification when needed.",
-  tools: [readFileTool, searchTool],
-});
-
-const reviewer = new Agent({
-  id: "reviewer",
-  model,
-  description: "Review findings for errors and unsupported claims.",
-  tools: [readFileTool],
-});
-
-const team = new AgentTeam({
-  id: "research-team",
-  model,
-  instructions: [
-    "Delegate research to researcher instances.",
-    "Send their findings to a reviewer and incorporate its feedback.",
-    "Answer the user after the work is complete.",
-  ].join("\n"),
-  members: [researcher, reviewer],
-  limits: {
-    maxDepth: 3,
-    maxConcurrentAgents: 4,
-    maxAgentInstances: 12,
-    maxTotalTurns: 100,
-    maxBufferedEvents: 1024,
-  },
-});
-
-const result = await team.generate({ prompt: "Investigate the proposed architecture." });
-if (result.type === "response") console.log(result.output);
-console.log(result.teamRunId, result.usage, result.members);
-```
-
-The coordinator supports normal Agent configuration, including `outputSchema`, context, tools,
-guardrails, middleware, and lifecycle callbacks. Its schema determines the team's output type.
-Each member preserves its own configuration. Run-level options apply to the coordinator; the
-abort signal, interaction resolver, and team limits apply to the whole execution.
-
-The runtime adds these model-callable tools:
-
-| Tool                | Available to                      | Input                         |
-| ------------------- | --------------------------------- | ----------------------------- |
-| `spawn_<member.id>` | Coordinator and permitted parents | `{ prompt, name? }`           |
-| `send_message`      | All instances                     | `{ to, content, replyTo? }`   |
-| `wait_for_agent`    | All instances                     | `{ instanceId?, timeoutMs? }` |
-| `list_agents`       | All instances                     | `{}`                          |
-| `cancel_agent`      | Instances with spawn permissions  | `{ instanceId, reason? }`     |
-
-Spawning returns an `instanceId` immediately. A definition's `agentId` stays the same across its
-instances; each assignment or resumed interaction has a distinct `runId`. Member IDs must contain
-1–58 letters, digits, underscores, or hyphens so generated tool names are valid. Configured tools
-must not use reserved coordination names.
-
-Routing is between a parent and its children by default. A member can use `to: "parent"`;
-parents address children by instance ID. Enable sibling communication and recursive spawning
-with explicit permissions:
-
-```ts
-const team = new AgentTeam({
-  id: "research-team",
-  model,
-  members: [researcher, reviewer],
-  communication: { siblings: true },
-  spawning: [{ from: researcher, to: [researcher, reviewer] }],
-  limits: { maxDepth: 3, maxConcurrentAgents: 4, maxAgentInstances: 12, maxTotalTurns: 100 },
-});
-```
-
-`members` is the definition catalog available to the coordinator. A spawn rule allows every
-instance of `from` to create only the definitions in `to`, using their generated spawn tools.
-Use the same Agent objects registered in `members`; duplicate rules or targets are rejected.
-Rules and communication options are snapshotted at construction. Without rules, only the
-coordinator can spawn. A self-reference enables recursion; each child has its own conversation
-and its definition's tools, without inheriting the parent's tools.
-
-With `communication.siblings: true`, instances sharing the same parent instance can discover,
-message, and wait for one another. Cousins and other branches remain inaccessible. `list_agents`
-includes self, parent, direct children, and enabled siblings, with `parentInstanceId` and `depth`.
-Sibling access does not grant cancellation or approval authority. Only a parent can cancel its
-direct child; cancellation also stops that child's entire subtree, including idle descendants.
-
-`send_message` returns a queued receipt, not a reply. Messages arrive at safe turn/tool boundaries,
-are explicitly attributed to their sender, and cannot satisfy a tool approval. Sending to an idle
-member starts a follow-up run with its retained conversation. Failed or cancelled members cannot
-receive follow-ups. Each inbox accepts at most 128 pending inputs.
-
-`wait_for_agent` wakes on a relevant message, outcome, cancellation, or timeout (default 30 seconds,
-maximum 5 minutes). Waiting agents and agents awaiting application input release their concurrency
-slot. Every parent waits automatically for its own children before finalizing and receives their
-outcomes as attributed messages. A member failure is reported to its immediate parent; failure or
-blocking cancels its descendants. A coordinator error or team cancellation rejects the execution.
-Guardrail blocking remains a `blocked` outcome. The final `members` array includes all descendants,
-with `parentInstanceId` and `depth` to reconstruct the tree.
-
-The limits in the first example are the defaults. `maxDepth` is a positive integer; the coordinator
-is depth 0 and direct children are depth 1. Concurrent and total instance limits include the coordinator.
-The instance limit counts all instances created during this execution, including completed or
-cancelled ones. The turn budget covers all instances and follow-ups; provider retries remain
-governed by normal retry settings. Reaching the turn budget fails the team. Reaching the instance
-or depth limit rejects the spawn tool call so the parent can use existing members. All budgets are
-shared across the whole tree; spawning does not reset them. Tools within one
-instance execute sequentially; different instances can execute concurrently.
-
-### Team streaming and steering
-
-```ts
-const stream = team.stream({ prompt: "Investigate the proposed architecture." });
-
-// Call from the application's user-input handler while the team is running:
-// stream.steer({ prompt: "Also consider deployment complexity." });
-// stream.cancel("User cancelled.");
-
-for await (const event of stream.events) {
-  if (event.type === "agent_event" && event.event.type === "text_delta") {
-    console.log(event.instanceId, event.event.delta);
-  }
-}
-const outcome = await stream.result;
-```
-
-`events` is an attributed union of agent events, member state changes, queued/delivered messages,
-interactions, and the terminal team outcome. New members emit `agent_queued` before acquiring a
-concurrency slot. `textStream` yields coordinator text only, including
-provisional turns before its final answer. `text` resolves to the final text. Choose one event or text
-consumer; final promises can be read alongside it. Reading only a final promise consumes the run
-without buffering unused events. Non-streaming models also work and emit complete response text
-instead of provider deltas. Closing the event iterator cancels unfinished work.
-
-Streaming buffers at most `limits.maxBufferedEvents` unread events (default 1,024). If a consumer
-falls behind and fills that buffer, the team cancels its running work, discards unread events, and
-rejects both the iterator and final promises with `AgentTeamLimitError` whose `limit` is
-`"maxBufferedEvents"`. This bounds queued event count, not the byte size of individual events.
-Increase the limit when your application needs to tolerate longer pauses between reads.
-Result-only consumption does not buffer events and is unaffected by this limit.
-
-### Team approvals and questions
-
-Only the application resolves interactions. A coordinator or reviewer cannot approve another
-member's protected tool through a message. Existing tool `requiresApproval` and question tools use
-the same interaction contracts as `Agent`:
-
-```ts
-import type { AgentTeamInteraction } from "@anvia/core/agent";
-import type { AgentInteractionResponse } from "@anvia/core/agent/interactions";
-
-// Implement this with your application's authenticated approval/question UI.
-declare function askUser(request: AgentTeamInteraction): Promise<AgentInteractionResponse>;
-
-const result = await team.generate({
-  prompt: "Investigate and propose changes.",
-  resolveInteraction: (request) => askUser(request),
-});
-```
-
-The resolver receives `teamRunId`, `instanceId`, `runId`, the interaction request, and an abort
-signal. A missing, throwing, or invalid resolver fails the team with `AgentTeamInteractionError`
-before the protected action executes. Approval denial follows the ordinary Agent behavior: the
-tool is skipped and its member can continue. Other members may continue while an interaction is
-pending. The application must decide who may approve; agent-generated content is not authorization.
-
-Teams currently live in one process for one execution. Each `generate` or `stream` call creates
-fresh instances. Pass `messages` instead of `prompt` to supply coordinator history. Member
-conversations are retained only within that execution; team session persistence and durable
-checkpoint/resume are not provided. Cancellation signals reach running models, tools, and
-resolvers; work owned by the application must honor its signal to stop external activity.
-Studio provides a team playground with member activity, messages, and approval/question controls.
-
-## Direct Completions
-
-Use `generateCompletion` for one provider call without Agent turns, memory, or local tool
-execution. The model and input are part of one options object:
-
-```ts
-import { generateCompletion } from "@anvia/core";
-import { OpenAIClient } from "@anvia/openai";
-
-const model = new OpenAIClient({ apiKey }).completionModel({ modelId: "gpt-5", api: "responses" });
-
-const result = await generateCompletion({
-  model,
-  prompt: "Summarize Anvia in one sentence.",
-  instructions: "Answer clearly and concisely.",
-});
-
-console.log(result.output); // string
-```
-
-Use `messages` when the application already owns the transcript. Exactly one of `prompt` or
-`messages` is required:
-
-```ts
-import { generateCompletion, type Message } from "@anvia/core";
-
-const result = await generateCompletion({
-  model,
-  messages: [
-    { role: "system", content: "You are concise." },
-    { role: "user", content: "Explain Anvia." },
-  ] satisfies readonly Message[],
-  maxTokens: 300,
-  providerOptions: {
-    reasoning: { effort: "low" },
-  },
-});
-```
-
-Messages are plain, readonly `{ role, content }` objects. Use structural literals with
-`satisfies Message` or `satisfies readonly Message[]`; there is no message factory namespace.
-Multimodal user content uses `text`, `image`, and `file` parts, while assistant tool calls use
-`{ type: "tool-call", toolCallId, toolName, input }`. At external boundaries, validate with
-`parseMessage`, `parseMessages`, `messageSchema`, or an application-specific
-`createMessageSchema({ metadataSchema })`.
-
-Add `outputSchema` to the same function for typed, schema-validated output:
-
-```ts
-import { generateCompletion } from "@anvia/core";
-import { z } from "zod";
-
-const result = await generateCompletion({
-  model,
-  prompt: "Extract: Acme reports a high-priority checkout failure.",
-  outputSchema: z.object({
-    customer: z.string(),
-    priority: z.enum(["low", "medium", "high"]),
-  }),
-});
-
-console.log(result.output.priority); // fully typed
-```
-
-`outputSchema` accepts any [Standard Schema](https://standardschema.dev) — Zod, Valibot, ArkType, and
-other implementing libraries, including transformed schemas whose validation input and output
-differ (for example `string -> number`). Zod uses its built-in JSON Schema conversion. Valibot
-requires the optional converter `@valibot/to-json-schema` (install it alongside `valibot`);
-unsupported Valibot actions surface as conversion errors before any model call. Other libraries
-must either implement the Standard JSON Schema interface (`~standard.jsonSchema`) or convert to a
-supported library. Providers receive the schema's input representation — the raw response is what
-`~standard.validate` accepts — while the validated, possibly transformed value becomes
-`result.output`. For Zod, the output representation is used only when it describes the same
-accepted values as the input side, so its strict-object refinements (`additionalProperties:
-false`, required by provider strict modes such as OpenAI structured outputs) are preserved;
-otherwise the input representation is sent. Object nodes without an explicit
-`additionalProperties` are completed with `false` in every provider payload for the same reason.
-Schema validation of the provider output is synchronous; asynchronous schemas are rejected with a
-`CompletionStructuredOutputError` in the `schema` phase.
-
-`CompletionResult` consistently contains `output`, the original `text`, normalized `content`,
-`usage`, and `rawResponse`, plus optional message, context, source, provider-tool, and finish-reason
-metadata. First-party adapters normalize provider termination into `finishReason` (`stop`, `length`,
-`content-filter`, `tool-calls`, or `other`) while preserving the provider value separately as
-`providerFinishReason`.
-
-Schema-backed completion checks termination before JSON parsing. `finishReason: "length"` throws
-`CompletionStructuredOutputError` with `phase: "truncated"`; `finishReason: "content-filter"`
-throws it with `phase: "content-filter"` and is not retried by the default policy. Ordinary text
-completion remains intentional: partial text is returned unchanged with its finish reason so the
-application decides whether to display, continue, or discard it. A direct structured stream can
-similarly end with one typed error event after any already-emitted deltas; it does not silently
-retract public stream progress.
-
-Use `streamCompletion` for the streaming form:
-
-```ts
-import { streamCompletion } from "@anvia/core";
-
-for await (const event of streamCompletion({
-  model,
-  prompt: "Write a short launch note.",
-})) {
-  if (event.type === "text_delta") process.stdout.write(event.delta);
-  if (event.type === "final") console.log(event.result.usage);
-  if (event.type === "error") console.error(event.error);
-}
-```
-
-Tool-call deltas are always emitted when a provider supplies them; there is no opt-in flag. A
-high-level stream emits at most one terminal `error` event and then closes. Provider model adapters
-use the lower-level `CompletionModelStreamEvent`, whose terminal event is `{ type: "final",
-response }`; `streamCompletion` normalizes it to `{ type: "final", result }`.
-
-Client requests carry core `Message[]`, so an endpoint can validate and pass them directly:
-
-```ts
-import { completionToClientStream, parseClientStreamRequest } from "@anvia/client";
-import { streamCompletion } from "@anvia/core";
-import { createClientStreamResponse } from "@anvia/server";
-
-const body = parseClientStreamRequest(await request.json());
-const events = completionToClientStream({
-  events: streamCompletion({ model, messages: body.messages }),
-});
-return createClientStreamResponse({ events });
-```
-
-Core does not own UI messages, HTTP transports, or the public wire protocol. Those boundaries live
-in `@anvia/client`, `@anvia/server`, and framework packages such as `@anvia/react`.
-
-## Retries, Provider Options, and Cancellation
-
-Direct completion and media calls accept `retries?: RetryOptions | false`. An omitted or `false`
-value makes one provider attempt; `{}` enables the default retry policy. Only retry-safe provider
-calls are repeated.
-
-```ts
-const controller = new AbortController();
-
-const result = await generateCompletion({
-  model,
-  prompt: "Summarize this incident.",
-  retries: { maxAttempts: 3, initialDelayMs: 100, maxDelayMs: 1_000 },
-  abortSignal: controller.signal,
-  controls: { reasoningEffort: "medium" },
-});
-```
-
-Completion models can advertise typed, provider-neutral `controls`. Reasoning-capable adapters use
-the `reasoningEffort` select control, so supported values are inferred from the model returned by
-`completionModel()`. An Agent can set control defaults, and a generate or stream call can override
-them for that run:
-
-```ts
-const agent = new Agent({ model, controls: { reasoningEffort: "medium" } });
-await agent.generate({ prompt: "Solve this.", controls: { reasoningEffort: "high" } });
-```
-
-Omitting a control means “Default”: the Agent default applies when configured, otherwise the
-provider chooses. Invalid control names and values are rejected before the provider call.
-
-`providerOptions` remains the escape hatch for a strict JSON object passed to an adapter. Runtime values such as
-`undefined`, non-finite numbers, cycles, a top-level array, and class instances are rejected rather
-than coerced. Nested arrays are valid JSON. Canonical Anvia fields such as model, input,
-temperature, tools, controls, dimensions, text, and voice take precedence over conflicting provider keys.
-Cancellation is forwarded to provider SDK calls and is never retried.
-
-## Agents
-
-Agents own their default retry policy. A run with no `retries` value inherits the Agent setting;
-`false` disables it for that run; an object replaces it for that run. Retries apply to the current
-completion only, so completed tools and earlier turns are never replayed. `maxAttempts` is the
-total number of model attempts for that completion, including the initial attempt; it is not the
-number of additional retries.
-
-```ts
-const agent = new Agent({
-  id: "support",
-  model,
-  retries: { maxAttempts: 3 },
-});
-
-await agent.generate({ prompt: "Try normally." });
-await agent.generate({ prompt: "Do not retry this run.", retries: false });
-await agent.generate({
-  prompt: "Use one custom policy.",
-  retries: { maxAttempts: 2, initialDelayMs: 0, maxDelayMs: 0 },
-});
-```
-
-When an Agent has `outputSchema`, truncation, JSON parsing, and schema-validation failures use the
-same retry budget when retries are explicitly enabled. Each retry starts from the original request
-rather than recursively accumulating failed attempts. Truncated output and reasoning are omitted;
-parse and schema repairs include only a bounded, text-only preview of the latest failed response.
-The correction asks for shorter raw JSON matching the schema, without Markdown or commentary.
-Transport failures and structured-output failures therefore cannot exceed `maxAttempts` in total.
-Agent response outcomes expose the last generation's `finishReason` and `providerFinishReason`, and
-the same fields remain attached to each assistant message's Anvia generation metadata.
-
-Malformed, incomplete, or non-JSON provider tool arguments fail with
-`CompletionProviderOutputError`. The default policy retries only explicitly retry-safe provider
-output failures when retries are enabled; it does not make arbitrary `SyntaxError` instances
-retryable. Tool calls are validated as a complete set before any tool executes, and filtered tool
-calls are never retried by default. Raw provider arguments are not retained in the error or retry
-metadata. A no-argument tool call must still contain the JSON value `{}`; blank argument text is
-malformed provider output and is never replaced with invented input.
-
-Streaming attempts are retried only before any provider event has been exposed. Once progress has
-been emitted, Anvia returns the failure without starting another provider attempt, because replaying
-the stream could duplicate text, tool-call deltas, or other observable events. Applications that
-want post-progress recovery must buffer attempts and define their own reset or resume protocol.
+Replace the sample tool body with your application's data access. Agent outcomes distinguish a
+response, a guardrail block, and an interaction that needs application input.
 
-Structured output remains strict: Core trims surrounding whitespace, parses JSON, and validates the
-result with the configured Zod schema. As a compatibility fallback for OpenAI-compatible providers
-that violate strict JSON mode, Core also accepts a response consisting entirely of one lowercase
-`json` Markdown fence or one unlabeled Markdown fence. It does not search prose for JSON, accept
-content before or after a fence, or bypass schema validation. `AgentStructuredOutputError` reports
-the `truncated`, `content-filter`, `parse`, or `schema` phase, attempt counts, output length/format
-metadata, per-attempt and cumulative usage, finish reasons, and the original `cause` when one
-exists; its message never contains the rejected model response. The `completion.retry` observer
-event records the same safe diagnostics and whether failed output was omitted or previewed, never
-the model output itself.
-
-Agent outcomes are discriminated by `type`. Successful responses include typed `output` and `text`;
-guardrail blocks return `type: "blocked"`, `stage`, `reason`, and an optional `message`; tool
-approvals and first-class questions return a JSON-safe `type: "interaction"` outcome.
-
-```ts
-const outcome = await agent.generate({ prompt: "Help with this request." });
-
-switch (outcome.type) {
-  case "response":
-    console.log(outcome.output);
-    break;
-  case "blocked":
-    console.log(outcome.stage, outcome.reason);
-    break;
-  case "interaction": {
-    const response =
-      outcome.interaction.type === "tool-approval"
-        ? { type: "tool-approval" as const, approved: true }
-        : {
-            type: "tool-question" as const,
-            answers: outcome.interaction.questions.map((question) => ({
-              questionId: question.id,
-              value: "application-provided answer",
-            })),
-          };
-    const resumed = await agent.resume(outcome.continuation, response);
-    console.log(resumed.type, resumed.resumedFrom);
-    break;
-  }
-}
-```
+## What you can build
 
-Keep continuations server-side. A resumed phase receives a new `runId`; Core validates the
-continuation and current Agent/tool registration but does not provide a durable continuation store
-or exactly-once execution. Use `createQuestionTool({ name, description })` when a model must ask for
-structured free-text or choice answers.
-
-Import JSON-safe interaction contracts and parsers from their browser-safe subpath. This entrypoint
-does not load the Agent runtime, MCP clients, or Node infrastructure:
-
-```ts
-import {
-  type AgentInteractionResponse,
-  parseAgentInteractionRequest,
-  parseAgentInteractionResponse,
-} from "@anvia/core/agent/interactions";
-```
-
-An Agent with `outputSchema` carries that output type through `generate`, `stream`, `asTool`, and
-Pipeline Agent stages. `stream()` returns a handle with one event consumer plus final-value
-promises, steering, and cancellation. Terminal agent events are the flattened outcomes themselves;
-there is no extra `final.result` wrapper:
-
-```ts
-const stream = agent.stream({ prompt: "Help with this request." });
-
-for await (const event of stream.events) {
-  if (event.type === "text_delta") process.stdout.write(event.delta);
-  if (event.type === "response") console.log(event.output);
-  if (event.type === "interaction") console.log(event.interaction);
-  if (event.type === "blocked") console.log(event.reason);
-}
-
-const outcome = await stream.result;
-console.log(outcome.type, await stream.text);
-```
-
-Use `stream.textStream` instead of `stream.events` when only text deltas are needed. Event and text
-iteration share one underlying stream and therefore cannot be consumed independently.
-
-Pass `abortSignal` on a run to cancel the active provider call, tools, and nested Agent tools.
-Run observers receive terminal errors with `status: "cancelled"` for cancellation and
-`status: "failed"` for other failures.
-
-### Prompt attribution
-
-Set `trace.promptRef` on `generate()` or `stream()` to identify the prompt used by a run and
-default its generation attribution. The core `AgentRunPromptRef` contract is
-`{ readonly name: string; readonly version?: number }`; use the registry's resolved numeric version
-when available, not the requested label. This identity does not contain templates or variables.
-
-For runs that change prompts between turns, completion-request middleware is the explicit
-generation override boundary:
-
-```ts
-await agent.generate({
-  prompt: "Summarize the ticket",
-  trace: { promptRef: { name: "support", version: 7 } },
-  middlewares: [
-    {
-      onCompletionRequest: ({ request, turn }) => {
-        if (turn === 0) {
-          return { request, promptRef: { name: "planner", version: 3 } };
-        }
-        return { request, promptRef: null };
-      },
-    },
-  ],
-});
-```
+- Agents with typed tools, approvals, questions, guardrails, and streaming responses.
+- Agent teams with isolated conversations, delegation, and coordinated cancellation.
+- Direct completions and schema-validated extraction without an agent loop.
+- Sequential or parallel pipelines and evaluations with built-in or custom metrics.
+- Stateful conversations using memory adapters and explicit compaction policies.
+- RAG with document chunking, embeddings, and vector-store contracts.
+- Image generation, speech, transcription, MCP tools, and local Agent Skills.
 
-The middleware receives the current `promptRef`. Returning a reference overrides that generation;
-`null` clears it, while omission preserves it. Each turn starts again with the run default, and
-later middleware sees earlier overrides. Set attribution alongside any request changes that select
-another prompt: attribution itself does not change the model input. It is a runtime side channel,
-not a provider request field or global current-prompt setting.
+Use `@anvia/client`, `@anvia/server`, and `@anvia/react` to deliver agent output to an application UI.
+Use provider, memory, vector-store, and observability adapters for the infrastructure you choose.
 
-## Memory
+## Learn more
 
-Configure durable conversation memory on the Agent, then run through a session:
-
-```ts
-import { Agent, type MemoryStore, type Message } from "@anvia/core";
-import type { MemoryAppendOptions, MemoryScope } from "@anvia/core/memory";
-
-class AppMemoryStore implements MemoryStore {
-  private readonly sessions = new Map<string, Message[]>();
-
-  async load({ scope }: { scope: MemoryScope }): Promise<Message[]> {
-    return [...(this.sessions.get(scope.sessionId) ?? [])];
-  }
-
-  async append(input: MemoryAppendOptions): Promise<void> {
-    const current = this.sessions.get(input.scope.sessionId) ?? [];
-    this.sessions.set(input.scope.sessionId, [...current, ...input.messages]);
-  }
-
-  async clear({ scope }: { scope: MemoryScope }): Promise<void> {
-    this.sessions.delete(scope.sessionId);
-  }
-}
-
-const memory = new AppMemoryStore();
-const agent = new Agent({
-  id: "support",
-  model: model,
-  memory: { store: memory },
-});
-
-const session = { sessionId: "thread_123", userId: "user_456" };
-await agent.generate({ prompt: "Remember my plan.", session });
-await agent.generate({ prompt: "What is my plan?", session });
-```
-
-Memory defaults to `savePolicy: "message"`, which saves the user prompt, each completed assistant message, and each completed tool result as soon as they are ready. You can choose `"turn"` or `"run"` at configuration time:
-
-```ts
-new Agent({
-  id: "support",
-  model,
-  memory: { store: memory, savePolicy: "turn" },
-});
-```
-
-Without `session`, the same Agent is stateless. Pass `{ messages }` when the caller already owns a
-complete transcript; transcripts cannot be combined with persisted sessions.
-
-Compaction is an explicit Agent policy over a store capability. The store preserves the canonical
-message history for `load()` and inspectors, and persists one latest compaction checkpoint
-separately. Future model calls receive the checkpoint summary (a system message tagged with
-`metadata.anvia.memoryCompaction`) plus the unsummarized tail, not the individual messages already
-covered by that summary:
-
-```ts
-import { createSummaryMemoryCompactor } from "@anvia/core/memory";
-
-const compactor = createSummaryMemoryCompactor({
-  model: summaryModel,
-  maxTokens: 1024,
-  retries: { maxAttempts: 2 },
-});
-
-const agent = new Agent({
-  id: "support",
-  model,
-  memory: {
-    store: memory,
-    savePolicy: "message",
-    compaction: {
-      trigger: { afterTokens: 32_000 },
-      retention: { recentTurns: 4 },
-      compactor,
-      conflictRetries: false,
-    },
-  },
-});
-
-for await (const event of agent.stream({ prompt: "What did we decide?", session })) {
-  if (event.type === "memory_compaction") {
-    console.log({
-      messages: event.compactedMessageCount,
-      beforeTokens: event.originalTokenCount,
-      afterTokens: event.resultTokenCount,
-      usage: event.usage,
-    });
-  }
-}
-```
-
-### Retention API design
-
-- **Public option:** `retention: { recentTurns: N }`.
-- **Counting unit:** a user-led turn, not an individual message. Each `user` message starts a turn;
-  every following `assistant`, `tool`, or `system` message belongs to it until the next `user`
-  message. Tool calls and results therefore cannot be split at the compaction boundary.
-- **Default:** omitting `retention` resolves to `{ recentTurns: 1 }`.
-- **Validation:** `N` must be a nonnegative safe integer. Fractions, negative values, infinity, and
-  specifying both retention modes are rejected.
-- **Boundaries:** exactly the last `N` complete stored turns remain unsummarized. `N = 0` summarizes
-  the whole stored transcript when it contains a user-led turn. If at most `N` turns exist,
-  compaction is a no-op.
-- **Leading messages:** messages before the first `user` do not count as a turn. When older turns
-  are summarized, this leading prefix is summarized with them.
-- **Trigger interaction:** the stored transcript plus incoming user message is compared with
-  `afterTokens`, but the incoming message is not part of the stored-turn retention count.
-  `afterTokens` remains only the automatic trigger threshold and does not cap retained turns.
-- **Compatibility:** deprecated `{ recentTokens: N }` remains supported with its previous
-  whole-turn semantics. It is mutually exclusive with `recentTurns`.
-
-The built-in token counter is a lightweight provider-neutral estimate. Pass `tokenCounter` when you
-have a model-specific tokenizer or counting service. A custom counter may be async, can be called
-multiple times, and must return deterministic, monotonic, nonnegative safe integers:
-
-```ts
-compaction: {
-  trigger: { afterTokens: 32_000 },
-  retention: { recentTurns: 4 },
-  tokenCounter: (messages) => tokenizer.count(messages),
-  compactor,
-}
-```
-
-For migration, the deprecated `retention: { recentTokens: N }` form remains supported with its
-previous semantics: it keeps as many complete recent user-led turns as fit the token budget and
-always keeps the newest turn. `recentTokens` must be positive and less than `afterTokens`.
-`recentTurns` and `recentTokens` are mutually exclusive; use `recentTurns` for deterministic
-count-based retention. Omitting `retention` previously used
-`Math.floor(afterTokens / 4)` as a token budget and now retains one turn. To preserve the old
-implicit behavior during migration, set that value explicitly as `recentTokens`.
-
-You can force the configured policy without starting an Agent run. The result makes a no-op
-explicit rather than throwing:
-
-```ts
-const result = await agent.compactMemory({ session });
-
-if (result.type === "compacted") {
-  console.log(result.originalTokenCount, result.resultTokenCount);
-} else {
-  console.log(result.reason); // "nothing_to_compact"
-}
-```
-
-The automatic trigger is a threshold, not a hard storage limit. Omitting `compaction` keeps the
-full canonical history model-facing. Summary-provider retries belong to the compactor; full
-snapshot-to-checkpoint conflict retries are separately opt-in. A streamed `memory_compaction`
-event is emitted only after the store atomically commits the checkpoint.
-
-## Structured Extraction
-
-```ts
-import { extract } from "@anvia/core/extractor";
-import { z } from "zod";
-
-const ticketSchema = z.object({
-  customer: z.string(),
-  priority: z.enum(["low", "medium", "high"]),
-  summary: z.string(),
-});
-
-const { output: ticket } = await extract({
-  model,
-  text: "Acme Co. reports checkout failures. Priority is high.",
-  outputSchema: ticketSchema,
-  retries: { maxAttempts: 2 },
-});
-```
-
-## Pipelines
-
-```ts
-import { Pipeline } from "@anvia/core/pipeline";
-import { z } from "zod";
-
-const pipeline = new Pipeline({ id: "support-flow", inputSchema: z.string() })
-  .agent({
-    id: "draft",
-    agent,
-    suspension: "reject",
-    request: ({ input }) => ({ prompt: `Draft a reply for this ticket:\n\n${input}` }),
-  })
-  .extract({
-    id: "parse",
-    model,
-    outputSchema: ticketSchema,
-    text: ({ input }) => input,
-  });
-
-const { runId, output } = await pipeline.run({
-  input: "Customer cannot complete checkout.",
-});
-```
-
-Pipelines use the same named observability configuration as Agents. Pipeline observers receive the
-root run and every composed, parallel, Agent, extraction, and custom stage. A primary stage trace is
-propagated into an Agent stage so its generations and tools become children of that stage. This
-requires the Pipeline and Agent `primaryTrace` names to match. When they differ, Anvia leaves the
-Agent trace unchanged without raising an error:
-
-```ts
-const pipeline = new Pipeline({
-  id: "support-flow",
-  inputSchema: z.string(),
-  observability: {
-    observers: { telemetry: pipelineObserver },
-    primaryTrace: "telemetry",
-  },
-}).agent({
-  id: "draft",
-  agent,
-  suspension: "reject",
-  request: ({ input }) => ({ prompt: input }),
-});
-
-const result = await pipeline.run({
-  input: "Customer cannot complete checkout.",
-  trace: { sessionId: "support-session" },
-});
-
-console.log(result.trace);
-```
-
-The `observer` passed to `pipeline.run()` remains a separate stage-event sink intended for Studio,
-logging, and other operational consumers. Its errors are isolated unless `failOnObserverError` is
-enabled.
-
-`observability.errorPolicy` controls named observer failures instead. It accepts `"ignore"` or
-`"throw"` and defaults to `"ignore"`. With `"throw"`, the run rejects with a
-`PipelineObserverDispatchError` containing the failed phase and per-observer failures.
-
-Pipeline run and batch options also accept `trace.promptRef`. This identifies the pipeline root;
-it does not stamp every stage or Agent with that prompt. Select each Agent's relevant prompt with
-`request: ({ input }) => ({ prompt: input, trace: { promptRef } })`, especially when a pipeline uses
-multiple prompts. Trace parent propagation and prompt identity are independent.
-
-## Documents
-
-Applications own file discovery, file reads, document parsing, source metadata, and per-file error
-policy. Core only provides deterministic in-memory text chunking:
-
-```ts
-import { readFile } from "node:fs/promises";
-import { chunkText } from "@anvia/core/documents";
-
-const text = await readFile("guide.txt", "utf8");
-const chunks = chunkText({
-  text,
-  strategy: "recursive",
-  maxSize: 1_000,
-  overlap: 100,
-  separators: ["\n\n", "\n", " "],
-});
-```
-
-Use `strategy: "fixed"` for deterministic sliding windows. Recursive chunking requires an explicit
-separator order and falls back to fixed-size splitting when none of those separators can divide an
-oversized section. Chunk offsets use JavaScript string indices and always identify the exact source
-slice.
-
-For the common vector ingestion path, embed and upsert raw text with one call:
-
-```ts
-import { ingestVectorText } from "@anvia/core/vector-store";
-
-await ingestVectorText({
-  store,
-  document: {
-    id: "incident-42",
-    text,
-    metadata: { tenant: "acme" },
-  },
-  embeddingModel,
-  chunking: {
-    strategy: "recursive",
-    maxSize: 1_000,
-    overlap: 100,
-    separators: ["\n\n", "\n", " "],
-  },
-});
-```
-
-`ingestVectorDocuments()` accepts the same document shape for batches. Without `chunking`, each
-source document is embedded as one chunk. Chunk embeddings remain grouped under the source document
-ID so re-ingestion replaces its complete vector representation instead of leaving stale chunks.
-
-## Media
-
-Media helpers follow the same one-object API and share `providerOptions`, `retries`, and
-`abortSignal`:
-
-```ts
-import { generateImage, generateSpeech, transcribe } from "@anvia/core";
-
-const image = await generateImage({
-  model: client.imageGenerationModel({ modelId: "gpt-image-1" }),
-  prompt: "A compact robot drawing an architecture diagram.",
-  width: 1024,
-  height: 1024,
-});
-console.log(image.images[0].data);
-
-const speech = await generateSpeech({
-  model: client.speechGenerationModel({ modelId: "gpt-4o-mini-tts" }),
-  text: "Hello from Anvia.",
-  voice: "alloy",
-});
-
-const transcript = await transcribe({
-  model: client.transcriptionModel({ modelId: "gpt-4o-mini-transcribe" }),
-  audio: {
-    data: speech.audio.data,
-    filename: "speech.mp3",
-    mediaType: speech.audio.mediaType,
-  },
-});
-console.log(transcript.text);
-```
-
-## MCP
-
-MCP clients live in the optional `@anvia/mcp` package. Core retains the lightweight registration
-contracts that let agents receive immutable MCP server snapshots without owning or closing their
-underlying transports:
-
-```sh
-pnpm add @anvia/mcp
-```
-
-Import `McpClient` and `McpClientGroup` from `@anvia/mcp`, connect them, and pass the resulting
-`servers` to `new Agent({ mcpServers })`. See the `@anvia/mcp` README for transport configuration,
-connection ownership, URL safety, and cleanup.
-
-## Evaluations
-
-Import evaluation APIs from `@anvia/core/evals`. A suite contains cases, a target, and one or more
-metrics. Required metric failures make a case fail; infrastructure or evaluation errors produce an
-`invalid` outcome.
-
-```ts
-import { contains, exactMatch, runEvalSuite } from "@anvia/core/evals";
-
-const result = await runEvalSuite({
-  name: "support answers",
-  cases: [
-    {
-      id: "refund-window",
-      input: "When can I request a refund?",
-      expected: "Refunds are available for 30 days.",
-    },
-  ],
-  target: async (input) => answerSupportQuestion(input),
-  metrics: [exactMatch(), contains({ expected: "30 days" })],
-});
-
-console.log(result.cases);
-console.log(result.results[0]?.scores.exact_match);
-```
-
-`runEvalSuite` infers the case input, target output, expected value, metric names, and score types.
-Metrics that implicitly read `case.expected`, `case.context`, or `case.retrievalContext` require
-those fields at compile time. Supplying an explicit metric value or selector removes the matching
-case requirement.
-
-Set `run: { promptRef: { name: "support", version: 7 } }` on `runEvalSuite()` to attribute the
-evaluation run. The reference is preserved in `result.run` and the reporter's run-start, per-metric,
-and run-end contexts. It does not automatically attribute the target Agent or judge generations;
-configure those runs' `trace.promptRef` separately when relevant.
-
-### Built-in metrics
-
-Deterministic metrics do not call a model:
-
-- `exactMatch`, `contains`, `notContains`, `containsAll`, and `containsAny`
-- `matches`, `doesNotMatch`, `maxLength`, and `requiredFields`
-- `semanticSimilarity`, which uses an embedding model
-
-Judge metrics call a completion model and record their evaluation token usage:
-
-- `llmJudge` and `llmScore`
-- `answerRelevancy`, `promptAlignment`, `jsonCorrectness`, and `summarization`
-- `hallucination`, `faithfulness`, and `abstention`
-- `gEval`, `turnRelevancy`, and `knowledgeRetention`
-
-Numeric thresholds use values from `0` through `1`. `strictMode` requires a perfect higher-is-better
-score or a zero lower-is-better score. Judge metrics default to including a final explanation;
-setting `includeReason: false` saves that extra judge call when the explanation is unnecessary.
-
-### Typed custom metrics
-
-Use `createEvalTypes` to bind input, output, and expected types once when defining multiple custom
-metrics:
-
-```ts
-import { createEvalTypes, EvalOutcome } from "@anvia/core/evals";
-
-const supportEvals = createEvalTypes<string, { answer: string }, string>();
-
-const noHandoff = supportEvals.defineMetric({
-  name: "no_handoff",
-  dataType: "BOOLEAN",
-  evaluate: ({ output, signal }) =>
-    signal.aborted || output.answer.includes("contact support")
-      ? EvalOutcome.fail(false)
-      : EvalOutcome.pass(true),
-});
-```
-
-Custom metrics return `EvalOutcome.pass`, `EvalOutcome.fail`, or `EvalOutcome.invalid`. Thrown metric
-errors are converted to structured invalid outcomes containing the error kind and original error.
-
-### Execution controls
-
-Evaluation targets receive an optional third argument containing the case `AbortSignal`.
-
-```ts
-const result = await runEvalSuite({
-  // cases, target, and metrics...
-  name: "release gate",
-  cases,
-  target: async (input, testCase, context) =>
-    generateAnswer(input, { signal: context?.signal, metadata: testCase.metadata }),
-  metrics,
-  targetConcurrency: 4,
-  metricConcurrency: 2,
-  caseTimeoutMs: 30_000,
-  signal: deploymentSignal,
-  failFast: true,
-  caseIds: ["refund-window", "billing-owner"],
-  shard: { index: 0, count: 4 },
-  onProgress(event) {
-    console.log(event.type);
-  },
-});
-```
-
-- `concurrency` remains the shorthand for both target and metric concurrency.
-- `targetConcurrency` and `metricConcurrency` can limit them independently.
-- `caseTimeoutMs` covers the target and its metrics. Cooperative targets and metrics should observe
-  the supplied signal; the runner still stops awaiting work that ignores it.
-- Aborting the suite-level `signal` stops scheduling cases and rejects the run with the abort reason.
-- `caseIds`, `caseFilter`, and `shard` select cases before execution.
-- `failFast` throws `EvalFailFastError` after the first completed required failure or invalid case.
-- `onProgress` receives case, target, metric, and case-completion events.
-
-Use `selectEvalCaseIds(previousResult)` to select failed and invalid cases for a rerun.
-
-### Results, usage, and failures
-
-Every case result includes `targetStatus`, target and total durations, per-case usage and optional
-cost. Every metric result includes its duration, optional cost, outcome, and reporter errors. A
-successful target that returns `undefined` has `targetStatus: "succeeded"` and retains its `output`
-property, so it is distinct from a failed target.
-
-The suite aggregates metric totals, case totals, target and evaluation usage, costs, duration, and
-all reporter errors. Invalid outcomes may include these `kind` values: `target`, `metric`,
-`configuration`, `provider`, or `timeout`.
-
-### CI output and expectations
-
-`runEvalCli` prints a result and can set `process.exitCode`. Exit code `1` means a required metric
-failed; `2` means a required metric was invalid. Use `defineEvalExpectations` with a defined suite to
-type-check case and metric names.
-
-```ts
-import { defineEvalExpectations, defineEvalSuite, exactMatch, runEvalCli } from "@anvia/core/evals";
-
-const suite = defineEvalSuite({
-  name: "release gate",
-  cases: [{ id: "refund", input: "refund", expected: "30 days" }],
-  target: async () => "30 days",
-  metrics: [exactMatch({ name: "correct" })],
-});
-
-await runEvalCli({
-  ...suite,
-  expectations: defineEvalExpectations(suite, {
-    outcomes: { refund: { correct: "pass" } },
-  }),
-  exitCode: true,
-  maxValueLength: 2_000,
-  redact: (value, context) => (context.kind === "input" ? "[redacted]" : value),
-});
-```
-
-Use `formatEvalResult` for pure pretty or JSON formatting without writing to stdout. Both
-`formatEvalResult` and `runEvalCli` support value truncation and redaction. JSON output otherwise
-contains cases, outputs, metadata, and error details, so redact sensitive data before writing it to
-shared CI logs.
-
-## Public Areas
-
-- `agent`: typed Agent runtime, retries, and stream events
-- `agent/interactions`: browser-safe interaction contracts, schemas, assertions, and parsers
-- `tool`: typed tool creation and tool sets
-- `completion`: direct completion helpers and provider-neutral model contracts
-- `memory`: durable session memory interfaces and in-memory store
-- `extractor`: schema-first structured extraction
-- `pipeline`: typed sequential and parallel workflows
-- `embeddings`: embedding helpers and document embedding utilities
-- `vector-store`: in-memory vector search and vector search tools
-- `streaming`: normalized stream helpers
-- `mcp`: lightweight MCP tool and server registration contracts used by Agent
-- `skills`: local skill loading
-- `observability`: observer interfaces for runs, generations, and tool calls
-- `evals`: evaluation helpers and reporters
-- `redaction`: PII patterns and deep value redaction shared by observability adapters
-- `documents`: deterministic in-memory text chunking
-- `speech-generation`, `image-generation`, `transcription`: provider-neutral media interfaces
-
-## Development
-
-```sh
-pnpm --filter @anvia/core typecheck
-pnpm --filter @anvia/core test
-pnpm --filter @anvia/core build
-```
+- [Core guide and API examples](https://github.com/anvia-hq/anvia/blob/main/docs/packages/core.md)
+- [Runnable cookbook](https://github.com/anvia-hq/anvia/tree/main/cookbook)
+- [Package catalog](https://github.com/anvia-hq/anvia#readme)
+- [Contributing](https://github.com/anvia-hq/anvia/blob/main/CONTRIBUTING.md)