@lunora/agent 1.0.0-alpha.1 → 1.0.0-alpha.3

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { A as AgentDefinition, c as AgentCompact, d as AgentEpisodeExtract, e as AgentGraphExtract, f as AgentGenerate, g as AgentTokenSink, h as AgentRunInput, i as AgentFunctionPaths, j as AgentRunFunction, k as AgentStepLike, l as AgentStreamGenerate, m as AgentRunResult, n as AgentMessageRow, o as AgentConfig, S as SkillDefinition, p as AnyAgentTool, q as AgentAsToolOptions, r as AgentSubToolInput, b as AgentToolDefinition, s as AgentBindingSpec, t as AgentHandle, u as AgentToolConfig, v as AgentFunctionReference, w as AgentModelInput, x as SkillConfig } from "./packem_shared/types.d-BWG0uUtX.mjs";
-export type { y as AgentEmailMapper, z as AgentEmailRun, B as AgentGenerateOptions, C as AgentGenerateResult, D as AgentInstructionsContext, E as AgentLiveEvent, F as AgentMemoryOptions, G as AgentMemorySource, H as AgentMessageStatus, J as AgentOnStepFinish, K as AgentPrepareStep, L as AgentPrepareStepInput, M as AgentPrepareStepResult, N as AgentProgressEvent, O as AgentRunHandle, P as AgentStepFinishInfo, Q as AgentStepInfo, R as AgentThreadStatus, T as AgentTokenDelta, U as AgentToolCall, a as AgentToolContext, V as AgentUsage, W as AgentVoiceConfig, X as AgentWorkflowBindingLike, Y as AgentWorkflowInstanceLike } from "./packem_shared/types.d-BWG0uUtX.mjs";
+import { A as AgentDefinition, c as AgentCompact, d as AgentEpisodeExtract, e as AgentGraphExtract, f as AgentGenerate, g as AgentTokenSink, h as AgentRunInput, i as AgentFunctionPaths, j as AgentRunFunction, k as AgentStepLike, l as AgentStreamGenerate, m as AgentRunResult, n as AgentMessageRow, o as AgentConfig, S as SkillDefinition, p as AnyAgentTool, q as AgentAsToolOptions, r as AgentSubToolInput, b as AgentToolDefinition, s as AgentBindingSpec, t as AgentHandle, u as AgentToolConfig, v as AgentFunctionReference, w as AgentModelInput, x as SkillConfig } from "./packem_shared/types.d-BhJFTvz_.mjs";
+export type { y as AgentEmailMapper, z as AgentEmailRun, B as AgentGenerateOptions, C as AgentGenerateResult, D as AgentInstructionsContext, E as AgentLiveEvent, F as AgentMemoryOptions, G as AgentMemorySource, H as AgentMessageStatus, J as AgentOnStepFinish, K as AgentPrepareStep, L as AgentPrepareStepInput, M as AgentPrepareStepResult, N as AgentProgressEvent, O as AgentRunHandle, P as AgentStepFinishInfo, Q as AgentStepInfo, R as AgentThreadStatus, T as AgentTokenDelta, U as AgentToolCall, a as AgentToolContext, V as AgentUsage, W as AgentVoiceConfig, X as AgentWorkflowBindingLike, Y as AgentWorkflowInstanceLike } from "./packem_shared/types.d-BhJFTvz_.mjs";
 export { type AgentComponent, agentComponent, agentExtension } from "./component.mjs";
 import { FlexibleSchema, LanguageModel, ModelMessage } from 'ai';
 export { agentBindingName, agentClassName, agentDefaultName, voiceBindingName, voiceClassName } from "./naming.mjs";
@@ -8,6 +8,10 @@ import { createAi } from '@lunora/ai';
 import { WorkflowDefinition } from '@lunora/workflow';
 import '@lunora/mail/inbound';
 import '@lunora/server';
+/**
+* `AgentLoopOptions` is part of the experimental `@lunora/agent` API and may change without a major version bump.
+* @experimental
+*/
 interface AgentLoopOptions {
   agent: AgentDefinition;
   /**
@@ -63,6 +67,7 @@ interface AgentLoopOptions {
 * `ceil(maxMessages / 2)`). Returns `undefined` when compaction is unset, the
 * history is short enough, or the tail would be the whole history — a PURE
 * decision (no I/O), unit-testable in isolation.
+* @experimental
 */
 declare const splitForCompaction: (history: ReadonlyArray<AgentMessageRow>, compaction: AgentConfig["compaction"]) => {
   older: AgentMessageRow[];
@@ -86,21 +91,31 @@ declare const splitForCompaction: (history: ReadonlyArray<AgentMessageRow>, comp
 * Loop control derives ONLY from persisted step outputs (never fresh
 * `Date.now()`/`Math.random()` at the top level), so replays walk the same
 * step-name sequence.
+* @experimental
 */
 declare const runAgentLoop: (options: AgentLoopOptions) => Promise<AgentRunResult>;
-/** Input the model provides to a minted `searchMemory` tool. */
+/**
+* Input the model provides to a minted `searchMemory` tool.
+* @experimental
+*/
 interface AgentMemorySearchInput {
   /** The natural-language query. */
   query: string;
   /** Per-call retrieval depth (overrides the source's configured `topK`). */
   topK?: number;
 }
-/** Input the model provides to a minted `readMemory` tool. */
+/**
+* Input the model provides to a minted `readMemory` tool.
+* @experimental
+*/
 interface AgentMemoryReadInput {
   /** The chunk/document id from a `searchMemory` hit. */
   id: string;
 }
-/** One ranked hit in a {@link AgentMemorySearchResult}. */
+/**
+* One ranked hit in a {@link AgentMemorySearchResult}.
+* @experimental
+*/
 interface AgentMemorySearchHit {
   id: string;
   score: number;
@@ -113,6 +128,7 @@ interface AgentMemorySearchHit {
 * hits plus deduped source refs, with the giant joined `.context` string
 * DROPPED — the model reads snippets and decides what (if anything) to pull with
 * `readMemory`, which is the whole point of agentic (vs inject) retrieval.
+* @experimental
 */
 interface AgentMemorySearchResult {
   results: AgentMemorySearchHit[];
@@ -123,6 +139,7 @@ interface AgentMemorySearchResult {
 * {@link AgentMemorySearchResult} a minted `searchMemory` tool returns. Defensive
 * against a source action that returns a differently-shaped value (the dispatch
 * boundary is untyped): a missing `chunks`/`sources` degrades to empty.
+* @experimental
 */
 declare const toSearchResults: (retrieved: unknown, snippetChars: number) => AgentMemorySearchResult;
 /**
@@ -136,6 +153,7 @@ declare const toSearchResults: (retrieved: unknown, snippetChars: number) => Age
 * Walks the same two source origins as `collectMemorySources` so the two stay in
 * lockstep; the split is deliberate — inject sources feed retrieval, agentic
 * sources feed tools, and no source is ever on both paths.
+* @experimental
 */
 declare const collectAgenticMemoryTools: (config: AgentConfig, skills: ReadonlyArray<SkillDefinition>) => Record<string, AnyAgentTool>;
 /**
@@ -155,9 +173,13 @@ declare const collectAgenticMemoryTools: (config: AgentConfig, skills: ReadonlyA
 * Workflows has no in-step await-instance primitive), and the answer is read
 * back from the child's persisted thread — the single source of truth — via the
 * shared `agents:agentMessages` runtime function.
+* @experimental
 */
 declare const agentAsTool: (options: AgentAsToolOptions) => AgentToolDefinition<AgentSubToolInput, string>;
-/** One step of a tool-composition script — call `tool` with `input`, bind the result to `id`. */
+/**
+* One step of a tool-composition script — call `tool` with `input`, bind the result to `id`.
+* @experimental
+*/
 interface ToolScriptStep {
   /** A stable name later steps reference the output by. */
   id: string;
@@ -166,11 +188,17 @@ interface ToolScriptStep {
   /** The tool to call — one of the tools handed to {@link codeTool}. */
   tool: string;
 }
-/** The model-provided input to a {@link codeTool} call. */
+/**
+* The model-provided input to a {@link codeTool} call.
+* @experimental
+*/
 interface ToolScript {
   steps: ToolScriptStep[];
 }
-/** The result of running a {@link ToolScript}: each step's output plus the last one. */
+/**
+* The result of running a {@link ToolScript}: each step's output plus the last one.
+* @experimental
+*/
 interface ToolScriptResult {
   final: unknown;
   results: ReadonlyArray<{
@@ -178,7 +206,10 @@ interface ToolScriptResult {
     output: unknown;
   }>;
 }
-/** Author-supplied config for {@link codeTool}. */
+/**
+* Author-supplied config for {@link codeTool}.
+* @experimental
+*/
 interface CodeToolOptions {
   /** Override the model-facing description (the default lists the available tools). */
   description?: string;
@@ -229,6 +260,7 @@ interface CodeToolOptions {
 * });
 * // The model can now, in one turn, `findUser` then feed `{ "$from": "u", "$path": "id" }` into `recentOrders`.
 * ```
+* @experimental
 */
 declare const codeTool: (tools: Record<string, AnyAgentTool>, options?: CodeToolOptions) => AgentToolDefinition<ToolScript, ToolScriptResult>;
 /**
@@ -242,6 +274,7 @@ declare const codeTool: (tools: Record<string, AnyAgentTool>, options?: CodeTool
 * and the env-backed `createDispatchRunner` (the same runner the workflow body
 * uses — it POSTs to `/_lunora/scheduler/dispatch`) is built on demand; tests
 * inject a `dispatch` double.
+* @experimental
 */
 declare const createAgentContext: (env: Record<string, unknown>, specs: ReadonlyArray<AgentBindingSpec>, dispatch?: AgentRunFunction) => Record<string, AgentHandle>;
 /**
@@ -270,17 +303,25 @@ declare const createAgentContext: (env: Record<string, unknown>, specs: Readonly
 *
 * Declaring an agent is enough — codegen auto-registers the `agents:*` runtime
 * functions (from `agentComponent()`) and the `ctx.agents` producer surface.
+* @experimental
 */
 declare const defineAgent: (config: AgentConfig) => AgentDefinition;
-/** Runtime brand check for a {@link AgentDefinition}. */
+/**
+* Runtime brand check for a {@link AgentDefinition}.
+* @experimental
+*/
 declare const isAgentDefinition: (value: unknown) => value is AgentDefinition;
 /**
 * Declare an agent tool — see `AgentToolDefinition` for why `execute` runs in
 * the loop's durable step (with an `AgentToolContext`) rather than inside the
 * model call.
+* @experimental
 */
 declare const defineAgentTool: <Input, Output>(config: AgentToolConfig<Input, Output>) => AgentToolDefinition<Input, Output>;
-/** Author-supplied config for {@link functionTool}. */
+/**
+* Author-supplied config for {@link functionTool}.
+* @experimental
+*/
 interface FunctionToolOptions<Input> {
   /** What the tool does — shown to the model (the model decides from it). */
   description: string;
@@ -312,9 +353,13 @@ interface FunctionToolOptions<Input> {
 * The function reference may be a typed `api.*` reference or a `"module:name"`
 * path. The model-provided input is passed verbatim as the function's args, so
 * `inputSchema` should mirror the referenced function's argument validator.
+* @experimental
 */
 declare const functionTool: <Input extends Record<string, unknown> = Record<string, unknown>, Output = unknown>(reference: AgentFunctionReference | string, options: FunctionToolOptions<Input>) => AgentToolDefinition<Input, Output>;
-/** Resolve the configured model against the Worker env (see `AgentModelInput`). */
+/**
+* Resolve the configured model against the Worker env (see `AgentModelInput`).
+* @experimental
+*/
 declare const resolveAgentModel: (model: AgentModelInput, env: Record<string, unknown>) => LanguageModel;
 /**
 * Build the production LLM-turn seam over AI SDK `generateText`. The agent's
@@ -327,6 +372,7 @@ declare const resolveAgentModel: (model: AgentModelInput, env: Record<string, un
 * `activeTools` / `toolChoice` / `model` overrides (from `prepareStep`) arrive
 * on each call. When `output` is set the model runs with `Output.object` and
 * the parsed answer is returned alongside the text.
+* @experimental
 */
 declare const createAgentGenerate: (agent: AgentDefinition, env: Record<string, unknown>) => AgentGenerate;
 /**
@@ -341,6 +387,7 @@ declare const createAgentGenerate: (agent: AgentDefinition, env: Record<string,
 * workflow replay serves the memoized final value without re-invoking it — no
 * delta is ever re-emitted. The persisted assistant message stays the single
 * source of truth.
+* @experimental
 */
 declare const createStreamGenerate: (agent: AgentDefinition, env: Record<string, unknown>) => AgentStreamGenerate;
 /**
@@ -351,6 +398,7 @@ declare const createStreamGenerate: (agent: AgentDefinition, env: Record<string,
 * model over {@link GRAPH_EXTRACTION_SCHEMA}, and returns the parsed
 * `{ entities, relations }`. Wired by `compileAgentWorkflow` and called inside
 * the loop's memoized `memory:extract` step.
+* @experimental
 */
 declare const createGraphExtract: () => AgentGraphExtract;
 /**
@@ -359,6 +407,7 @@ declare const createGraphExtract: () => AgentGraphExtract;
 * single natural-language summary — so it returns the trimmed model text. Wired
 * by `compileAgentWorkflow` and called inside the loop's memoized
 * `memory:episode` step.
+* @experimental
 */
 declare const createEpisodeExtract: () => AgentEpisodeExtract;
 /**
@@ -367,20 +416,29 @@ declare const createEpisodeExtract: () => AgentEpisodeExtract;
 * returns the brief. Wired by `compileAgentWorkflow` and called inside the loop's
 * memoized `llm:turn:N` step so the summarization is replay-safe.
 */
-/** One text/image/… content part of an MCP `CallToolResult`. */
+/**
+* One text/image/… content part of an MCP `CallToolResult`.
+* @experimental
+*/
 interface McpContentPart {
   [key: string]: unknown;
   text?: string;
   type: string;
 }
-/** The result of an MCP `tools/call` — the structural subset the adapter reads. */
+/**
+* The result of an MCP `tools/call` — the structural subset the adapter reads.
+* @experimental
+*/
 interface McpCallResult {
   [key: string]: unknown;
   content?: ReadonlyArray<McpContentPart>;
   isError?: boolean;
   structuredContent?: unknown;
 }
-/** One entry of an MCP `tools/list` — the structural subset the adapter reads. */
+/**
+* One entry of an MCP `tools/list` — the structural subset the adapter reads.
+* @experimental
+*/
 interface McpToolInfo {
   description?: string;
   inputSchema: {
@@ -395,6 +453,7 @@ interface McpToolInfo {
 * Structural subset of `@modelcontextprotocol/sdk`'s `Client` the adapter uses.
 * Declaring it locally lets tests inject a mock without the real SDK (and its
 * transport) and keeps the heavy dependency behind a lazy dynamic import.
+* @experimental
 */
 interface McpClientLike {
   callTool: (params: {
@@ -407,7 +466,10 @@ interface McpClientLike {
     tools: ReadonlyArray<McpToolInfo>;
   }>;
 }
-/** Options for {@link mcpTools}. */
+/**
+* Options for {@link mcpTools}.
+* @experimental
+*/
 interface McpToolsOptions {
   /**
   * A pre-built (already-connected) MCP client. Takes precedence over `url` —
@@ -438,6 +500,7 @@ interface McpToolsOptions {
 * server's `structuredContent` is returned as-is; otherwise the text parts are
 * joined. An `isError` result is returned as an error STRING (not thrown) so
 * the next LLM turn can recover, consistent with the loop's unknown-tool path.
+* @experimental
 */
 declare const adaptMcpResult: (result: McpCallResult) => unknown;
 /**
@@ -460,6 +523,7 @@ declare const adaptMcpResult: (result: McpCallResult) => unknown;
 * every call. In the Workers runtime only the HTTP/SSE transports run (stdio
 * does not) — pass `url`, or inject an already-connected `client` for a custom
 * transport (also the test seam).
+* @experimental
 */
 declare const mcpTools: (options: McpToolsOptions) => Promise<Record<string, AgentToolDefinition<Record<string, unknown>>>>;
 /**
@@ -467,6 +531,7 @@ declare const mcpTools: (options: McpToolsOptions) => Promise<Record<string, Age
 * retrieved memory context (when any), then the persisted thread history with
 * tool calls/results correlated the way providers expect (assistant tool-call
 * parts answered by tool-result parts sharing the `toolCallId`).
+* @experimental
 */
 declare const buildModelMessages: (options: {
   history: ReadonlyArray<AgentMessageRow>;
@@ -478,6 +543,7 @@ declare const buildModelMessages: (options: {
 * The namespace the agent runtime functions register under. Codegen
 * auto-registers `agentComponent().functions` here whenever `lunora/agents.ts`
 * declares an agent, so the loop's dispatch paths below hold by construction.
+* @experimental
 */
 declare const AGENT_MODULE = "agents";
 /**
@@ -485,13 +551,23 @@ declare const AGENT_MODULE = "agents";
 * under. Codegen auto-registers `sandboxComponent().invoke` here whenever
 * `lunora/` imports a sandbox tool (`browserTool`/`containerTool`), so the
 * tools' `execute` can dispatch to it through the loop's `run` seam.
+* @experimental
 */
 declare const SANDBOX_MODULE = "sandbox";
-/** The dispatch path of the sandbox runtime action (an internal action). */
+/**
+* The dispatch path of the sandbox runtime action (an internal action).
+* @experimental
+*/
 declare const SANDBOX_INVOKE_PATH: "sandbox:invoke";
-/** Default dispatch paths of the agent runtime functions. */
+/**
+* Default dispatch paths of the agent runtime functions.
+* @experimental
+*/
 declare const DEFAULT_AGENT_FUNCTION_PATHS: AgentFunctionPaths;
-/** Mint a dispatchable function reference from a path (or pass one through). */
+/**
+* Mint a dispatchable function reference from a path (or pass one through).
+* @experimental
+*/
 declare const toFunctionReference: (source: AgentFunctionReference | string) => AgentFunctionReference;
 /**
 * Declare a reusable skill: a bundle of expertise — an instruction fragment,
@@ -521,9 +597,13 @@ declare const toFunctionReference: (source: AgentFunctionReference | string) =>
 * ordering, per-skill knowledge retrieval) happens in `defineAgent` — a skill
 * only validates its own `name`; tool-name validation is deferred to the merge,
 * which owns the flat model-facing namespace.
+* @experimental
 */
 declare const defineSkill: (config: SkillConfig) => SkillDefinition;
-/** Runtime brand check for a {@link SkillDefinition}. */
+/**
+* Runtime brand check for a {@link SkillDefinition}.
+* @experimental
+*/
 declare const isSkillDefinition: (value: unknown) => value is SkillDefinition;
 /**
 * A control frame the server sends the client as a JSON text message (audio
@@ -531,6 +611,7 @@ declare const isSkillDefinition: (value: unknown) => value is SkillDefinition;
 * connect; `user_transcript` carries the STT result; `assistant_delta` streams
 * the live LLM text; `assistant_done` is the final turn text; `interrupted`
 * acks a barge-in; `error` reports a non-fatal turn failure.
+* @experimental
 */
 type VoiceServerFrame = {
   audioFormat: "mp3" | "wav";
@@ -550,7 +631,10 @@ type VoiceServerFrame = {
 } | {
   type: "interrupted";
 };
-/** A control frame the client sends the server (audio rides separate binary frames). */
+/**
+* A control frame the client sends the server (audio rides separate binary frames).
+* @experimental
+*/
 type VoiceClientFrame = {
   text: string;
   type: "text";
@@ -559,17 +643,35 @@ type VoiceClientFrame = {
 } | {
   type: "interrupt";
 };
-/** A synthesized-audio source the TTS seam yields — normalized to bytes by {@link toByteIterable}. */
+/**
+* A synthesized-audio source the TTS seam yields — normalized to bytes by {@link toByteIterable}.
+* @experimental
+*/
 type VoiceAudioSource = AsyncIterable<Uint8Array> | ReadableStream<Uint8Array> | Uint8Array;
-/** Transcribe one buffered utterance (16kHz mono 16-bit PCM) to text. */
+/**
+* Transcribe one buffered utterance (16kHz mono 16-bit PCM) to text.
+* @experimental
+*/
 type VoiceTranscribe = (pcm: Uint8Array) => Promise<string>;
-/** Synthesize one sentence to an audio byte stream; honors `signal` for barge-in. */
+/**
+* Synthesize one sentence to an audio byte stream; honors `signal` for barge-in.
+* @experimental
+*/
 type VoiceSynthesize = (text: string, signal: AbortSignal) => Promise<VoiceAudioSource>;
-/** Send a JSON control frame to the client. */
+/**
+* Send a JSON control frame to the client.
+* @experimental
+*/
 type VoiceSend = (frame: VoiceServerFrame) => void;
-/** Send a binary audio frame to the client. */
+/**
+* Send a binary audio frame to the client.
+* @experimental
+*/
 type VoiceSendAudio = (bytes: Uint8Array) => void;
-/** The outcome of one voice turn. */
+/**
+* The outcome of one voice turn.
+* @experimental
+*/
 interface VoiceTurnResult {
   /** The final assistant text (may be partial if `interrupted`). */
   assistantText: string;
@@ -578,7 +680,10 @@ interface VoiceTurnResult {
   /** The transcribed (or typed) user text — empty when the utterance was silence. */
   userText: string;
 }
-/** Options for one {@link runVoiceTurn}. */
+/**
+* Options for one {@link runVoiceTurn}.
+* @experimental
+*/
 interface RunVoiceTurnOptions {
   /** The agent whose thread + models back this session. */
   agent: AgentDefinition;
@@ -631,6 +736,7 @@ interface RunVoiceTurnOptions {
 * frame never duplicates a row; the thread tables are the same ones the durable
 * agent loop and `useAgentChat` read, so a voice session and a text session on
 * the same `threadKey` share one history.
+* @experimental
 */
 declare const runVoiceTurn: (options: RunVoiceTurnOptions) => Promise<VoiceTurnResult>;
 /** Parse the JSON identity envelope forwarded on the `x-lunora-identity` upgrade header. */
@@ -654,6 +760,7 @@ interface VoiceSessionState {
 * `SupportVoiceDO extends VoiceSessionDO`, constructed with the agent
 * definition + its export name) bound under the agent's `VOICE_...` Durable
 * Object binding.
+* @experimental
 */
 declare class VoiceSessionDO {
   protected readonly agent: AgentDefinition;
@@ -733,6 +840,7 @@ declare class VoiceSessionDO {
 *
 * The workflow ctx supplies durability (`step.do`) and the Lunora dispatcher
 * (`run`); the loop supplies determinism (step naming + idempotent persists).
+* @experimental
 */
 declare const compileAgentWorkflow: (agent: AgentDefinition, exportName: string, options?: {
   paths?: AgentFunctionPaths;