@anvia/core 1.0.0-rc.2 → 1.0.0-rc.4

package/README.md

@@ -12,10 +12,17 @@ The package is dependency-injection oriented: create provider models, typed tool
 
 ## 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
+pnpm add @anvia/core@rc
 ```
 
+See the repository's [1.0 release policy](../../docs/releases/v1.md) for channel and support
+details.
+
 In this monorepo, the package is available through the workspace:
 
 ```sh
@@ -202,16 +209,37 @@ await agent.generate({
 ```
 
 Agent results are discriminated by `status`. Completed results include typed `output` and `text`;
-guardrail blocks return `status: "blocked"`, `stage`, and `text`; tool approval can return
-`status: "approval_required"`.
+guardrail blocks return `status: "blocked"`, `stage`, and `text`; tool approvals and first-class
+questions return a JSON-safe `status: "suspended"` result.
 
 ```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 }
+        : {
+            type: "tool-question",
+            answers: result.interaction.questions.map((question) => ({
+              questionId: question.id,
+              value: "application-provided answer",
+            })),
+          },
+  });
+  console.log(resumed.status, resumed.resumedFrom);
+}
 ```
 
+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.
+
 An Agent with `outputSchema` carries that output type through `generate`, `stream`, `asTool`, and
 Pipeline Agent stages. Agent stream finals use the same result shape:
 
@@ -344,7 +372,7 @@ const pipeline = new Pipeline({ id: "support-flow", inputSchema: z.string() })
   .agent({
     id: "draft",
     agent,
-    approval: "reject",
+    suspension: "reject",
     request: ({ input }) => ({ prompt: `Draft a reply for this ticket:\n\n${input}` }),
   })
   .extract({
@@ -359,6 +387,37 @@ const { runId, output } = await pipeline.run({
 });
 ```
 
+## Documents
+
+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:
+
+```ts
+import { readFile } from "node:fs/promises";
+import { chunkText, extractPdfText } 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", " "],
+});
+
+const { pages } = await extractPdfText({
+  data: new Uint8Array(await readFile("guide.pdf")),
+  abortSignal,
+});
+```
+
+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. PDF pages are one-based, and the parser task is disposed before extraction settles.
+If parsing or abort handling fails together with parser cleanup, extraction rejects with an
+`AggregateError` containing the operation failure first and the cleanup failure second.
+
 ## Media
 
 Media helpers follow the same one-object API and share `providerOptions`, `retries`, and
@@ -414,7 +473,7 @@ const github = new McpClient({
   transport: {
     type: "streamableHttp",
     url: "https://mcp.example.com/mcp",
-    requestInit: { headers: { authorization: `Bearer ${process.env.MCP_TOKEN}` } },
+    headers: { authorization: `Bearer ${process.env.MCP_TOKEN}` },
   },
   tools: { prefix: "github_" },
 });
@@ -431,13 +490,21 @@ try {
 
 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 and do not accept a custom `fetch`; use the
-explicit caller-owned `custom` transport only when you intentionally own that security boundary.
-MCP server instructions remain inspectable metadata and are not added to Agent instructions.
+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.
 
 ## Public Areas
 
-- `agent`: typed Agent runtime, run results, approvals, retries, and stream events
+- `agent`: typed Agent runtime, continuations, interactions, retries, and stream events
 - `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
@@ -450,7 +517,7 @@ MCP server instructions remain inspectable metadata and are not added to Agent i
 - `skills`: local skill loading
 - `observability`: observer interfaces for runs, generations, and tool calls
 - `evals`: evaluation helpers and reporters
-- `loaders`: document loading utilities
+- `documents`: in-memory text chunking and PDF text extraction
 - `speech-generation`, `image-generation`, `transcription`: provider-neutral media interfaces
 
 ## Development

package/dist/agent/index.d.ts

@@ -1,26 +1,26 @@
 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-yBG8e9Jj.js';
-import { M as Message } from '../types-CQ_ioXWK.js';
-import { c as AgentBlockedResult } from '../types-3x3mOLHU.js';
-export { A as AgentApprovalDecision, a as AgentApprovalRequiredEvent, b as AgentApprovalRequiredResult, d as AgentChildStreamEvent, e as AgentDeltaEvent, f as AgentErrorEvent, g as AgentErrorStreamEvent, h as AgentFinishEvent, i as AgentInput, j as AgentLifecycle, k as AgentMemoryCompactionEvent, l as AgentPrompt, m as AgentResponse, n as AgentResult, o as AgentRunOptions, p as AgentRunSettings, q as AgentStartEvent, r as AgentSteerInput, s as AgentStepFinishEvent, t as AgentStream, u as AgentStreamEvent, v as AgentToolApprovalRequest, w as AgentToolCallDeltaEvent, x as AgentToolFinishEvent, y as AgentToolStartEvent } from '../types-3x3mOLHU.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-CXScUOpX.js';
+import { M as Message } from '../types-D9rKQ_as.js';
+import { A as AgentBlockedResult, t as AgentSuspendedResult } from '../types-CElwurHZ.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-CElwurHZ.js';
+export { A as AgentContinuation, a as AgentInteractionRequest, b as AgentInteractionResponse, d as AgentQuestionAnswer, e as AgentQuestionChoice, f as AgentQuestionPrompt, g as AgentToolApprovalRequest, h as AgentToolQuestionRequest, p as agentContinuationSchema, q as agentInteractionRequestSchema, r as agentInteractionResponseSchema, w as assertAgentInteractionResponse, t as parseAgentContinuation, u as parseAgentInteractionRequest, v as parseAgentInteractionResponse } from '../interactions-csssHYcN.js';
 import '../zod-schema-C7F4clpm.js';
 import 'zod';
-import '../guardrails/index.js';
+import '../types-CIPaIbZo.js';
 import '../type-utils-CtHVDRn_.js';
-import '../client-B8DT1vUG.js';
+import '../client-DvUatElp.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 '../tool--Mz4v1eL.js';
-import '../middleware-C7PdmKF7.js';
-import '../types-BVzM4RsC.js';
-import '../types-DiJqJejp.js';
-import '../dynamic-tools-KwEGRbHp.js';
+import '../tool-r62gf3QY.js';
+import '../types-DbolvLtZ.js';
+import '../types-RT3cuyRk.js';
+import '../dynamic-tools-AEBOTgu1.js';
 import '../types-Cr4uiYo5.js';
-import '../types-Dld1TpWj.js';
+import '../types-C3gv9EX6.js';
 
 declare class MaxTurnsError extends Error {
     readonly maxTurns: number;
@@ -37,5 +37,12 @@ declare class AgentRunBlockedError extends Error {
     readonly result: AgentBlockedResult;
     constructor(result: AgentBlockedResult);
 }
+declare class AgentStreamClosedError extends Error {
+    constructor();
+}
+declare class AgentToolSuspensionError extends Error {
+    readonly result: AgentSuspendedResult;
+    constructor(result: AgentSuspendedResult);
+}
 
-export { AgentBlockedResult, AgentRunBlockedError, AgentRunCancelledError, MaxTurnsError };
+export { AgentBlockedResult, AgentRunBlockedError, AgentRunCancelledError, AgentStreamClosedError, AgentSuspendedResult, AgentToolSuspensionError, MaxTurnsError };

package/dist/agent/index.js

@@ -1,30 +1,51 @@
 import {
   Agent,
-  AgentRunBlockedError,
-  AgentRunCancelledError,
-  MaxTurnsError,
+  agentContinuationSchema,
+  agentInteractionRequestSchema,
+  agentInteractionResponseSchema,
+  assertAgentInteractionResponse,
   createVectorContext,
-  isVectorContext
-} from "../chunk-DBSCKTUL.js";
+  isVectorContext,
+  parseAgentContinuation,
+  parseAgentInteractionRequest,
+  parseAgentInteractionResponse
+} from "../chunk-5GXSQYQT.js";
+import "../chunk-FXAIYTRE.js";
+import "../chunk-KFR4CDGK.js";
+import "../chunk-VKYZZXP5.js";
 import "../chunk-YK4WAAS4.js";
-import "../chunk-EINTGEGY.js";
 import "../chunk-CQNNSZPG.js";
-import "../chunk-D37WMSP6.js";
-import "../chunk-77AIYARB.js";
-import "../chunk-OJH6HWHX.js";
-import "../chunk-CWM7B2OO.js";
-import "../chunk-FMHLROPQ.js";
+import "../chunk-J2W63PJI.js";
+import "../chunk-XYTPYUGB.js";
+import {
+  AgentRunBlockedError,
+  AgentRunCancelledError,
+  AgentStreamClosedError,
+  AgentToolSuspensionError,
+  MaxTurnsError
+} from "../chunk-TRQ3XRFD.js";
+import "../chunk-GQL5KRAH.js";
+import "../chunk-3RM57ZT2.js";
 import "../chunk-MGNTXGTX.js";
-import "../chunk-KR3RCCHJ.js";
-import "../chunk-TIZYTPJO.js";
-import "../chunk-KIDGIJM7.js";
+import "../chunk-D2ECOWN5.js";
+import "../chunk-PK5LKOFL.js";
 import "../chunk-FN7HLLAZ.js";
+import "../chunk-AZB6N7P4.js";
 export {
   Agent,
   AgentRunBlockedError,
   AgentRunCancelledError,
+  AgentStreamClosedError,
+  AgentToolSuspensionError,
   MaxTurnsError,
+  agentContinuationSchema,
+  agentInteractionRequestSchema,
+  agentInteractionResponseSchema,
+  assertAgentInteractionResponse,
   createVectorContext,
-  isVectorContext
+  isVectorContext,
+  parseAgentContinuation,
+  parseAgentInteractionRequest,
+  parseAgentInteractionResponse
 };
 //# sourceMappingURL=index.js.map

package/dist/{agent-yBG8e9Jj.d.ts → agent-CXScUOpX.d.ts}

@@ -1,16 +1,16 @@
 import { b as RetrySetting } from './retry-CjvSlKGW.js';
-import { D as Document, C as CompletionModel, P as ProviderTool, J as JsonObject, u as ToolChoice } from './types-CQ_ioXWK.js';
+import { D as Document, C as CompletionModel, P as ProviderTool, J as JsonObject, u as ToolChoice } from './types-D9rKQ_as.js';
 import { Z as ZodSchema } from './zod-schema-C7F4clpm.js';
-import { GuardrailPolicyInput, GuardrailPolicy } from './guardrails/index.js';
-import { a as McpServer } from './client-B8DT1vUG.js';
-import { j as AgentLifecycle, G as AgentObservabilityOptions, o as AgentRunOptions, n as AgentResult, t as AgentStream, u as AgentStreamEvent, b as AgentApprovalRequiredResult, A as AgentApprovalDecision, a as AgentApprovalRequiredEvent } from './types-3x3mOLHU.js';
-import { A as AgentMiddleware } from './middleware-C7PdmKF7.js';
-import { A as AnyTool, T as Tool, c as ToolCallContext, N as NormalizedToolOutput } from './tool--Mz4v1eL.js';
-import { D as MemoryStore, y as MemorySavePolicy, m as MemoryCompactor, d as MemoryCompactionConflictRetryOptions, x as MemoryOptions } from './types-BVzM4RsC.js';
-import { a as SkillSet } from './types-DiJqJejp.js';
-import { T as ToolIndex } from './dynamic-tools-KwEGRbHp.js';
+import { d as GuardrailPolicyInput, c as GuardrailPolicy } from './types-CIPaIbZo.js';
+import { a as McpServer } from './client-DvUatElp.js';
+import { g as AgentLifecycle, E as AgentObservabilityOptions, l as AgentRunOptions, k as AgentResult, r as AgentStream, s as AgentStreamEvent } from './types-CElwurHZ.js';
+import { c as AgentMiddleware } from './interactions-csssHYcN.js';
+import { A as AnyTool, T as Tool, c as ToolCallContext, N as NormalizedToolOutput } from './tool-r62gf3QY.js';
+import { D as MemoryStore, y as MemorySavePolicy, m as MemoryCompactor, d as MemoryCompactionConflictRetryOptions, x as MemoryOptions } from './types-DbolvLtZ.js';
+import { a as SkillSet } from './types-RT3cuyRk.js';
+import { T as ToolIndex } from './dynamic-tools-AEBOTgu1.js';
 import { E as EmbeddingModel, c as SparseEmbeddingModel } from './types-Cr4uiYo5.js';
-import { V as VectorFilter, a as VectorSearchResult, d as VectorStore, H as HybridVectorStore, e as VectorFusion } from './types-Dld1TpWj.js';
+import { V as VectorFilter, a as VectorSearchResult, d as VectorStore, H as HybridVectorStore, e as VectorFusion } from './types-C3gv9EX6.js';
 
 type VectorContextBaseOptions<T = unknown> = {
     topK: number;
@@ -109,6 +109,7 @@ type ResolvedAgentOptions<Output = string, M extends CompletionModel = Completio
 };
 type AgentToolOptions = {
     name: string;
+    suspension: "reject";
     description?: string | undefined;
     maxTurns?: number | undefined;
     stream?: boolean | undefined;
@@ -139,15 +140,11 @@ declare class Agent<Output = string, M extends CompletionModel = CompletionModel
     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>>>;
-    resume(pending: AgentApprovalRequiredResult, decision: AgentApprovalDecision): Promise<AgentResult<Output>>;
-    resume(pending: AgentApprovalRequiredEvent, decision: AgentApprovalDecision): AgentStream<AgentStreamEvent<Output, RawResponseOf<M>>>;
     asTool(options: AgentToolOptions): Tool<{
         prompt: string;
     }, Output>;
     getTool(toolName: string): AnyTool | undefined;
     callTool(toolName: string, args: string, context?: ToolCallContext): Promise<NormalizedToolOutput>;
 }
-declare function createResolvedAgent<Output = string, M extends CompletionModel = CompletionModel, ContextDocument = unknown>(options: ResolvedAgentOptions<Output, M, ContextDocument>): Agent<Output, M, ContextDocument>;
-declare function getResolvedAgentOptions<Output, M extends CompletionModel, ContextDocument>(agent: Agent<Output, M, ContextDocument>): ResolvedAgentOptions<Output, M, ContextDocument>;
 
-export { Agent as A, type CreateHybridVectorContextOptions as C, type ResolvedAgentOptions as R, type VectorContext as V, type AgentContextInput as a, type AgentMemory as b, type AgentMemoryOptions as c, type AgentOptions as d, type AgentToolInput as e, type AgentToolOptions as f, type CreateVectorContextOptions as g, type VectorContextBaseOptions as h, createVectorContext as i, isVectorContext as j, createResolvedAgent as k, getResolvedAgentOptions as l };
+export { Agent as A, type CreateHybridVectorContextOptions as C, type ResolvedAgentOptions as R, type VectorContext as V, type AgentContextInput as a, type AgentMemory as b, type AgentMemoryOptions as c, type AgentOptions as d, type AgentToolInput as e, type AgentToolOptions as f, type CreateVectorContextOptions as g, type VectorContextBaseOptions as h, createVectorContext as i, isVectorContext as j };

package/dist/chunk-3RM57ZT2.js

@@ -0,0 +1,31 @@
+// src/internal/concurrency.ts
+async function mapWithConcurrency(inputs, concurrency, mapper) {
+  if (!Number.isSafeInteger(concurrency) || concurrency <= 0) {
+    throw new RangeError("concurrency must be a positive safe integer.");
+  }
+  const limit = concurrency;
+  const results = new Array(inputs.length);
+  let nextIndex = 0;
+  let firstFailure;
+  async function worker() {
+    while (firstFailure === void 0 && nextIndex < inputs.length) {
+      const index = nextIndex;
+      nextIndex += 1;
+      try {
+        results[index] = await mapper(inputs[index]);
+      } catch (error) {
+        firstFailure ??= { error };
+      }
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(limit, inputs.length) }, () => worker()));
+  if (firstFailure !== void 0) {
+    throw firstFailure.error;
+  }
+  return results;
+}
+
+export {
+  mapWithConcurrency
+};
+//# sourceMappingURL=chunk-3RM57ZT2.js.map

package/dist/chunk-3RM57ZT2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/concurrency.ts"],"sourcesContent":["export async function mapWithConcurrency<Input, Output>(\n  inputs: readonly Input[],\n  concurrency: number,\n  mapper: (input: Input) => Promise<Output>,\n): Promise<Output[]> {\n  if (!Number.isSafeInteger(concurrency) || concurrency <= 0) {\n    throw new RangeError(\"concurrency must be a positive safe integer.\");\n  }\n  const limit = concurrency;\n  const results = new Array<Output>(inputs.length);\n  let nextIndex = 0;\n  let firstFailure: { error: unknown } | undefined;\n\n  async function worker(): Promise<void> {\n    while (firstFailure === undefined && nextIndex < inputs.length) {\n      const index = nextIndex;\n      nextIndex += 1;\n      try {\n        results[index] = await mapper(inputs[index] as Input);\n      } catch (error) {\n        firstFailure ??= { error };\n      }\n    }\n  }\n\n  await Promise.all(Array.from({ length: Math.min(limit, inputs.length) }, () => worker()));\n  if (firstFailure !== undefined) {\n    throw firstFailure.error;\n  }\n  return results;\n}\n"],"mappings":";AAAA,eAAsB,mBACpB,QACA,aACA,QACmB;AACnB,MAAI,CAAC,OAAO,cAAc,WAAW,KAAK,eAAe,GAAG;AAC1D,UAAM,IAAI,WAAW,8CAA8C;AAAA,EACrE;AACA,QAAM,QAAQ;AACd,QAAM,UAAU,IAAI,MAAc,OAAO,MAAM;AAC/C,MAAI,YAAY;AAChB,MAAI;AAEJ,iBAAe,SAAwB;AACrC,WAAO,iBAAiB,UAAa,YAAY,OAAO,QAAQ;AAC9D,YAAM,QAAQ;AACd,mBAAa;AACb,UAAI;AACF,gBAAQ,KAAK,IAAI,MAAM,OAAO,OAAO,KAAK,CAAU;AAAA,MACtD,SAAS,OAAO;AACd,yBAAiB,EAAE,MAAM;AAAA,MAC3B;AAAA,IACF;AAAA,EACF;AAEA,QAAM,QAAQ,IAAI,MAAM,KAAK,EAAE,QAAQ,KAAK,IAAI,OAAO,OAAO,MAAM,EAAE,GAAG,MAAM,OAAO,CAAC,CAAC;AACxF,MAAI,iBAAiB,QAAW;AAC9B,UAAM,aAAa;AAAA,EACrB;AACA,SAAO;AACT;","names":[]}