@anvia/core 1.0.0-rc.8 → 1.0.0

package/README.md

@@ -58,7 +58,7 @@ const agent = new Agent({
 });
 
 const result = await agent.generate({ prompt: "What is happening with order A123?" });
-if (result.status === "completed") console.log(result.output);
+if (result.type === "response") console.log(result.output);
 ```
 
 ## Direct Completions
@@ -229,7 +229,7 @@ rather than recursively accumulating failed attempts. Truncated output and reaso
 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.
-Completed Agent results expose the last generation's `finishReason` and `providerFinishReason`, and
+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
@@ -256,30 +256,35 @@ exists; its message never contains the rejected model response. The `completion.
 event records the same safe diagnostics and whether failed output was omitted or previewed, never
 the model output itself.
 
-Agent results are discriminated by `status`. Completed results include typed `output` and `text`;
-guardrail blocks return `status: "blocked"`, `stage`, and `text`; tool approvals and first-class
-questions return a JSON-safe `status: "suspended"` result.
+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 result = await agent.generate({ prompt: "Help with this request." });
-
-if (result.status === "completed") console.log(result.output);
-if (result.status === "blocked") console.log(result.stage, result.text);
-if (result.status === "suspended") {
-  const resumed = await agent.generate({
-    continuation: result.continuation,
-    response:
-      result.interaction.type === "tool-approval"
-        ? { type: "tool-approval", approved: true }
+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",
-            answers: result.interaction.questions.map((question) => ({
+            type: "tool-question" as const,
+            answers: outcome.interaction.questions.map((question) => ({
               questionId: question.id,
               value: "application-provided answer",
             })),
-          },
-  });
-  console.log(resumed.status, resumed.resumedFrom);
+          };
+    const resumed = await agent.resume(outcome.continuation, response);
+    console.log(resumed.type, resumed.resumedFrom);
+    break;
+  }
 }
 ```
 
@@ -300,17 +305,27 @@ import {
 ```
 
 An Agent with `outputSchema` carries that output type through `generate`, `stream`, `asTool`, and
-Pipeline Agent stages. Agent stream finals use the same result shape:
+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
-for await (const event of agent.stream({ prompt: "Help with this request." })) {
-  if (event.type === "final") {
-    if (event.result.status === "completed") console.log(event.result.output);
-    else console.log(event.result.stage, event.result.text);
-  }
+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.
 
 ## Memory
@@ -383,8 +398,8 @@ const agent = new Agent({
     store: memory,
     savePolicy: "message",
     compaction: {
-      trigger: { afterMessages: 50 },
-      retention: { recentUserTurns: 4 },
+      trigger: { afterTokens: 32_000 },
+      retention: { recentTokens: 8_000 },
       compactor,
       conflictRetries: false,
     },
@@ -393,13 +408,50 @@ const agent = new Agent({
 
 for await (const event of agent.stream({ prompt: "What did we decide?", session })) {
   if (event.type === "memory_compaction") {
-    console.log(event.compactedMessageCount, event.usage);
+    console.log({
+      messages: event.compactedMessageCount,
+      beforeTokens: event.originalTokenCount,
+      afterTokens: event.resultTokenCount,
+      usage: event.usage,
+    });
   }
 }
 ```
 
-The trigger is a threshold, not a hard storage limit. Summary-provider retries belong to the
-compactor; full snapshot-to-replacement conflict retries are separately opt-in.
+The trigger includes the stored transcript and the incoming user message. Retention keeps as many
+recent complete user-led turns as fit the configured budget; the newest complete turn is always
+kept and never split, even when it exceeds that budget. When `retention` is omitted, it defaults to
+25% of `afterTokens`.
+
+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: { recentTokens: 8_000 },
+  tokenCounter: (messages) => tokenizer.count(messages),
+  compactor,
+}
+```
+
+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. Summary-provider retries belong to
+the compactor; full snapshot-to-replacement conflict retries are separately opt-in. A streamed
+`memory_compaction` event is emitted only after the store atomically commits the replacement.
 
 ## Structured Extraction
 
@@ -451,6 +503,13 @@ const { runId, output } = await pipeline.run({
 Applications own file discovery, file reads, source metadata, and per-file error policy. Core only
 provides deterministic in-memory chunking and scoped PDF text extraction:
 
+PDF extraction uses the optional `pdfjs-dist` peer dependency. Install it in applications that call
+`extractPdfText`:
+
+```sh
+pnpm add pdfjs-dist
+```
+
 ```ts
 import { readFile } from "node:fs/promises";
 import { chunkText, extractPdfText } from "@anvia/core/documents";
@@ -512,54 +571,17 @@ console.log(transcript.text);
 
 ## MCP
 
-MCP clients own connections. Agents receive immutable server registrations and never own or close
-the underlying transport:
-
-```ts
-import { Agent } from "@anvia/core/agent";
-import { McpClient, McpClientGroup } from "@anvia/core/mcp";
-
-const filesystem = new McpClient({
-  name: "filesystem",
-  transport: {
-    type: "stdio",
-    command: "npx",
-    args: ["-y", "@modelcontextprotocol/server-filesystem", "./workspace"],
-  },
-});
-const github = new McpClient({
-  name: "github",
-  transport: {
-    type: "streamableHttp",
-    url: "https://mcp.example.com/mcp",
-    headers: { authorization: `Bearer ${process.env.MCP_TOKEN}` },
-  },
-  tools: { prefix: "github_" },
-});
-
-const mcp = await McpClientGroup.connect({ clients: [filesystem, github] });
-const agent = new Agent({ id: "assistant", model, mcpServers: mcp.servers });
+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:
 
-try {
-  await agent.generate({ prompt: "Find the issue and update it." });
-} finally {
-  await mcp.close();
-}
+```sh
+pnpm add @anvia/mcp
 ```
 
-Construction performs no I/O. `connect()` discovers every tool page once and returns a frozen
-registration snapshot. Reconnect and rebuild the Agent to adopt changed remote tools. Built-in
-Streamable HTTP connections enforce Anvia URL safety by default and do not accept a custom `fetch`.
-Static request headers are explicit transport configuration; arbitrary Fetch `RequestInit` fields
-are not exposed because the MCP transport owns its HTTP method, body, abort signal, session, and
-protocol headers. Configured headers are sent only to the exact MCP endpoint, are not attached to
-OAuth requests, and cause endpoint redirects to fail instead of forwarding credentials. A static
-`authorization` header cannot be combined with `authProvider`.
-For an intentionally local or private-network server, set `ssrfProtection: "disabled"` on that
-transport. This disables hostname and DNS restrictions for the complete transport, including
-redirects and OAuth discovery, while still requiring HTTP(S). Use it only when the application owns
-and trusts that network boundary. MCP server instructions remain inspectable metadata and are not
-added to Agent instructions.
+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.
 
 ## Public Areas
 
@@ -573,7 +595,7 @@ added to Agent instructions.
 - `embeddings`: embedding helpers and document embedding utilities
 - `vector-store`: in-memory vector search and vector search tools
 - `streaming`: normalized stream helpers
-- `mcp`: lifecycle-owning MCP clients, groups, and immutable Agent registrations
+- `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

package/dist/agent/index.d.ts

@@ -1,27 +1,22 @@
 export { M as ModelCallOptions } from '../model-call-options-CZkSw_xN.js';
 export { R as RetryContext, a as RetryOptions, b as RetrySetting } from '../retry-CjvSlKGW.js';
-export { A as Agent, a as AgentContextInput, b as AgentMemory, c as AgentMemoryOptions, d as AgentOptions, e as AgentToolInput, f as AgentToolOptions, C as CreateHybridVectorContextOptions, g as CreateVectorContextOptions, V as VectorContext, h as VectorContextBaseOptions, i as createVectorContext, j as isVectorContext } from '../agent-XPQBM4rX.js';
+export { A as Agent, a as AgentContextInput, b as AgentMemory, c as AgentMemoryOptions, d as AgentOptions, e as AgentToolInput, f as AgentToolOptions, C as CreateHybridVectorContextOptions, g as CreateVectorContextOptions, V as VectorContext, h as VectorContextBaseOptions, i as createVectorContext, j as isVectorContext } from '../agent-qRKa3ibC.js';
 import { M as Message, U as Usage, C as CompletionFinishReason } from '../types-DgvozfPc.js';
-import { A as AgentBlockedResult, t as AgentSuspendedResult } from '../types-Sue2hb_L.js';
-export { a as AgentChildStreamEvent, b as AgentDeltaEvent, c as AgentErrorEvent, d as AgentErrorStreamEvent, e as AgentFinishEvent, f as AgentInput, g as AgentLifecycle, h as AgentMemoryCompactionEvent, i as AgentPrompt, j as AgentResponse, k as AgentResult, l as AgentRunOptions, m as AgentRunSettings, n as AgentStartEvent, o as AgentSteerInput, p as AgentSteerReceipt, q as AgentStepFinishEvent, r as AgentStream, s as AgentStreamEvent, u as AgentToolCallDeltaEvent, v as AgentToolFinishEvent, w as AgentToolStartEvent } from '../types-Sue2hb_L.js';
+import { A as AgentBlockedOutcome, g as AgentInteractionOutcome } from '../types-CLCLFpAL.js';
+export { a as AgentChildStreamEvent, b as AgentDeltaEvent, c as AgentErrorEvent, d as AgentErrorStreamEvent, e as AgentFinishEvent, f as AgentInput, h as AgentLifecycle, i as AgentMemoryCompactionEvent, j as AgentMemoryCompactionOptions, k as AgentOutcome, l as AgentPrompt, m as AgentResponse, n as AgentRunOptions, o as AgentRunSettings, p as AgentStartEvent, q as AgentSteerInput, r as AgentSteerReceipt, s as AgentStepFinishEvent, t as AgentStream, u as AgentStreamEvent, v as AgentToolCallDeltaEvent, w as AgentToolFinishEvent, x as AgentToolStartEvent } from '../types-CLCLFpAL.js';
 import '../zod-schema-C7F4clpm.js';
 import 'zod';
 import '../types-DhkodEft.js';
 import '../type-utils-CtHVDRn_.js';
-import '../client-DTPl0hZv.js';
-import 'node:child_process';
-import 'node:stream';
-import '@modelcontextprotocol/sdk/client/auth.js';
-import '@modelcontextprotocol/sdk/client/streamableHttp.js';
-import '@modelcontextprotocol/sdk/shared/transport.js';
+import '../types-DjqRHeAi.js';
 import '../tool-BpqpoRSE.js';
+import '../types-CSYt7-It.js';
 import '../middleware-kcF8AusP.js';
-import '../types-DKOXVTcq.js';
+import './interactions/index.js';
 import '../types-DC1U1XwW.js';
 import '../dynamic-tools-aIZlg5x1.js';
 import '../types-Cr4uiYo5.js';
 import '../types-CXNE592e.js';
-import './interactions/index.js';
 
 type AgentStructuredOutputPhase = "truncated" | "content-filter" | "parse" | "schema";
 type AgentStructuredOutputFormat = "raw" | "json-fence" | "unlabeled-fence";
@@ -62,15 +57,15 @@ declare class AgentRunCancelledError extends Error {
     constructor(chatHistory: Message[], reason: string, options?: ErrorOptions);
 }
 declare class AgentRunBlockedError extends Error {
-    readonly result: AgentBlockedResult;
-    constructor(result: AgentBlockedResult);
+    readonly result: AgentBlockedOutcome;
+    constructor(result: AgentBlockedOutcome);
 }
 declare class AgentStreamClosedError extends Error {
     constructor();
 }
 declare class AgentToolSuspensionError extends Error {
-    readonly result: AgentSuspendedResult;
-    constructor(result: AgentSuspendedResult);
+    readonly result: AgentInteractionOutcome;
+    constructor(result: AgentInteractionOutcome);
 }
 
-export { AgentBlockedResult, AgentRunBlockedError, AgentRunCancelledError, AgentStreamClosedError, AgentStructuredOutputError, type AgentStructuredOutputFormat, type AgentStructuredOutputPhase, AgentSuspendedResult, AgentToolSuspensionError, MaxTurnsError };
+export { AgentBlockedOutcome, AgentInteractionOutcome, AgentRunBlockedError, AgentRunCancelledError, AgentStreamClosedError, AgentStructuredOutputError, type AgentStructuredOutputFormat, type AgentStructuredOutputPhase, AgentToolSuspensionError, MaxTurnsError };

package/dist/agent/index.js

@@ -2,10 +2,10 @@ import {
   Agent,
   createVectorContext,
   isVectorContext
-} from "../chunk-YA2655FX.js";
+} from "../chunk-3ZLM6OAZ.js";
 import "../chunk-OJBFDBLG.js";
-import "../chunk-76JLMBVT.js";
-import "../chunk-5C6B6ZRH.js";
+import "../chunk-J6LVLV6P.js";
+import "../chunk-YA7BMX7D.js";
 import "../chunk-6BBOCFHV.js";
 import "../chunk-YK4WAAS4.js";
 import "../chunk-SJMSS5SI.js";
@@ -17,7 +17,7 @@ import {
   AgentStructuredOutputError,
   AgentToolSuspensionError,
   MaxTurnsError
-} from "../chunk-X4LK4ODN.js";
+} from "../chunk-AHLKV6KP.js";
 import "../chunk-ZA564323.js";
 import "../chunk-3RM57ZT2.js";
 import "../chunk-D4PACGPA.js";

package/dist/{agent-XPQBM4rX.d.ts → agent-qRKa3ibC.d.ts}

@@ -2,11 +2,12 @@ import { b as RetrySetting } from './retry-CjvSlKGW.js';
 import { D as Document, c as CompletionModel, P as ProviderTool, J as JsonObject, v as ToolChoice } from './types-DgvozfPc.js';
 import { Z as ZodSchema } from './zod-schema-C7F4clpm.js';
 import { d as GuardrailPolicyInput, c as GuardrailPolicy } from './types-DhkodEft.js';
-import { a as McpServer } from './client-DTPl0hZv.js';
-import { g as AgentLifecycle, E as AgentObservabilityOptions, l as AgentRunOptions, k as AgentResult, r as AgentStream, s as AgentStreamEvent } from './types-Sue2hb_L.js';
+import { a as McpServer } from './types-DjqRHeAi.js';
+import { E as MemoryStore, z as MemorySavePolicy, F as MemoryTokenCounter, n as MemoryCompactor, d as MemoryCompactionConflictRetryOptions, y as MemoryOptions, k as MemoryCompactionResult } from './types-CSYt7-It.js';
+import { h as AgentLifecycle, F as AgentObservabilityOptions, n as AgentRunOptions, k as AgentOutcome, o as AgentRunSettings, t as AgentStream, j as AgentMemoryCompactionOptions } from './types-CLCLFpAL.js';
 import { A as AgentMiddleware } from './middleware-kcF8AusP.js';
 import { A as AnyTool, T as Tool, c as ToolCallContext, N as NormalizedToolOutput } from './tool-BpqpoRSE.js';
-import { D as MemoryStore, y as MemorySavePolicy, m as MemoryCompactor, d as MemoryCompactionConflictRetryOptions, x as MemoryOptions } from './types-DKOXVTcq.js';
+import { AgentContinuation, AgentInteractionResponse } from './agent/interactions/index.js';
 import { a as SkillSet } from './types-DC1U1XwW.js';
 import { T as ToolIndex } from './dynamic-tools-aIZlg5x1.js';
 import { E as EmbeddingModel, c as SparseEmbeddingModel } from './types-Cr4uiYo5.js';
@@ -74,11 +75,12 @@ type AgentMemory = {
     savePolicy: MemorySavePolicy;
     compaction?: {
         trigger: {
-            afterMessages: number;
+            afterTokens: number;
         };
         retention: {
-            recentUserTurns: number;
+            recentTokens: number;
         };
+        tokenCounter: MemoryTokenCounter;
         compactor: MemoryCompactor;
         conflictRetries: false | MemoryCompactionConflictRetryOptions;
     } | undefined;
@@ -138,8 +140,10 @@ declare class Agent<Output = string, M extends CompletionModel = CompletionModel
     readonly middlewares: readonly AgentMiddleware[];
     readonly memory: AgentMemory | undefined;
     constructor(options: AgentOptions<Output, M, ContextDocument>);
-    generate(options: AgentRunOptions<Output, RawResponseOf<M>>): Promise<AgentResult<Output>>;
-    stream(options: AgentRunOptions<Output, RawResponseOf<M>>): AgentStream<AgentStreamEvent<Output, RawResponseOf<M>>>;
+    generate(options: AgentRunOptions<Output, RawResponseOf<M>>): Promise<AgentOutcome<Output>>;
+    resume(continuation: AgentContinuation, response: AgentInteractionResponse, settings?: AgentRunSettings<Output, RawResponseOf<M>>): Promise<AgentOutcome<Output>>;
+    stream(options: AgentRunOptions<Output, RawResponseOf<M>>): AgentStream<Output, RawResponseOf<M>>;
+    compactMemory(options: AgentMemoryCompactionOptions): Promise<MemoryCompactionResult>;
     asTool(options: AgentToolOptions): Tool<{
         prompt: string;
     }, Output>;