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

package/dist/packem_shared/{types.d-BWG0uUtX.d.mts → types.d-BhJFTvz_.d.mts}

@@ -4,13 +4,20 @@ import { FlexibleSchema, LanguageModel, ModelMessage, ToolSet, ToolChoice, ToolC
 * Structural mirror of the Lunora function reference (`{ __lunoraRef }`).
 * Declared locally so the loop can mint references to the agent runtime
 * functions by path without importing `@lunora/dispatch`.
+* @experimental
 */
 interface AgentFunctionReference {
   __lunoraRef: string;
 }
-/** `ctx.run`-shaped dispatcher the loop uses to call Lunora functions. */
+/**
+* `ctx.run`-shaped dispatcher the loop uses to call Lunora functions.
+* @experimental
+*/
 type AgentRunFunction = (reference: AgentFunctionReference, args?: Record<string, unknown>) => Promise<unknown>;
-/** Structural subset of the Cloudflare Workflows durable-step API the loop needs. */
+/**
+* Structural subset of the Cloudflare Workflows durable-step API the loop needs.
+* @experimental
+*/
 interface AgentStepLike {
   do: <T>(name: string, callback: () => Promise<T>) => Promise<T>;
   /**
@@ -39,6 +46,7 @@ interface AgentStepLike {
 * workflow replay (native step memoization) — but a step that FAILS mid-body
 * is retried at-least-once, so a side-effecting tool (charge a card, send a
 * mail) must dedupe on this key itself.
+* @experimental
 */
 interface AgentToolContext {
   /** The Worker environment bindings. */
@@ -104,6 +112,7 @@ interface AgentToolContext {
 * model call — the loop runs it itself inside a named durable step so a
 * completed call never re-runs on replay, and passes the
 * {@link AgentToolContext} alongside the input.
+* @experimental
 */
 interface AgentToolDefinition<Input = unknown, Output = unknown> {
   /** What the tool does — shown to the model. */
@@ -130,19 +139,24 @@ interface AgentToolDefinition<Input = unknown, Output = unknown> {
   */
   needsApproval?: ((input: Input, context: AgentToolContext) => boolean | Promise<boolean>) | boolean;
 }
-/** Author-supplied tool config (see {@link AgentToolDefinition}). */
+/**
+* Author-supplied tool config (see {@link AgentToolDefinition}).
+* @experimental
+*/
 type AgentToolConfig<Input = unknown, Output = unknown> = Omit<AgentToolDefinition<Input, Output>, "isLunoraAgentTool">;
 /**
 * Generic-erased tool for tool maps. `Input` sits in both a covariant
 * (`inputSchema`) and a contravariant (`execute`) position, so no single
 * non-`any` instantiation admits every concrete tool — the same reason the AI
 * SDK's `ToolSet` erases its generics.
+* @experimental
 */
 type AnyAgentTool = AgentToolDefinition<any, any>;
 /**
 * The model an agent runs on: a Workers AI model id (resolved via `env.AI`),
 * a prebuilt AI SDK {@link LanguageModel}, or a thunk building one from the
 * Worker env (for providers that need API keys off `env`).
+* @experimental
 */
 type AgentModelInput = LanguageModel | ((env: Record<string, unknown>) => LanguageModel);
 /**
@@ -158,6 +172,7 @@ type AgentModelInput = LanguageModel | ((env: Record<string, unknown>) => Langua
 * `"agentic"` skips auto-injection; the source instead mints a `searchMemory`
 * tool the MODEL calls mid-reasoning (Recursive-LM / "read what you need") — each
 * call a memoized durable step, so multi-hop retrieval is crash-safe for free.
+* @experimental
 */
 interface AgentMemoryOptions {
   /**
@@ -238,12 +253,16 @@ interface AgentMemoryOptions {
 * carries `knowledge` (keyed by the skill's name). The key names the durable
 * step — the default source keeps the historic `"memory:retrieve"`, a skill
 * source uses `"memory:retrieve:&lt;key>"` — so replay stays deterministic.
+* @experimental
 */
 interface AgentMemorySource extends AgentMemoryOptions {
   /** Stable source key: `"default"` for `memory`, else the contributing skill's name. */
   key: string;
 }
-/** Cumulative or per-turn token usage — AI SDK `LanguageModelUsage` field names. */
+/**
+* Cumulative or per-turn token usage — AI SDK `LanguageModelUsage` field names.
+* @experimental
+*/
 interface AgentUsage {
   /** Prompt (input) tokens. */
   inputTokens?: number;
@@ -252,7 +271,10 @@ interface AgentUsage {
   /** Input + output tokens. */
   totalTokens?: number;
 }
-/** Context handed to a dynamic {@link AgentConfig.instructions} function. */
+/**
+* Context handed to a dynamic {@link AgentConfig.instructions} function.
+* @experimental
+*/
 interface AgentInstructionsContext {
   /** The Worker environment bindings. */
   env: Record<string, unknown>;
@@ -268,6 +290,7 @@ interface AgentInstructionsContext {
 * the SAME {@link AnyAgentTool} shape agents already use
 * (`functionTool`/`mcpTools`/`agentAsTool`), and `knowledge` reuses the
 * {@link AgentMemoryOptions} retrieval verbatim.
+* @experimental
 */
 interface SkillConfig {
   /**
@@ -295,12 +318,18 @@ interface SkillConfig {
   */
   tools?: Record<string, AnyAgentTool>;
 }
-/** A `defineSkill` result — config plus the brand the agent merge checks. */
+/**
+* A `defineSkill` result — config plus the brand the agent merge checks.
+* @experimental
+*/
 interface SkillDefinition extends SkillConfig {
   /** Runtime brand check (see `isSkillDefinition`). */
   readonly isLunoraSkill: true;
 }
-/** One prior turn, as {@link AgentConfig.prepareStep} and `stopWhen` observe it. */
+/**
+* One prior turn, as {@link AgentConfig.prepareStep} and `stopWhen` observe it.
+* @experimental
+*/
 interface AgentStepInfo {
   /** The assistant text of the turn. */
   text: string;
@@ -313,7 +342,10 @@ interface AgentStepInfo {
   /** The turn's token usage, when the model reported it. */
   usage?: AgentUsage;
 }
-/** The turn summary handed to {@link AgentConfig.onStepFinish}. */
+/**
+* The turn summary handed to {@link AgentConfig.onStepFinish}.
+* @experimental
+*/
 interface AgentStepFinishInfo {
   /** The assistant text produced this turn. */
   text: string;
@@ -328,9 +360,13 @@ interface AgentStepFinishInfo {
 * Called after each LLM turn with that turn's text, tool calls, and usage. Runs
 * inside a named durable step (`agent:step-finish:&lt;turn>`) so it fires exactly
 * once per turn even across a workflow replay.
+* @experimental
 */
 type AgentOnStepFinish = (info: AgentStepFinishInfo) => Promise<void> | void;
-/** The input {@link AgentConfig.prepareStep} sees before a turn runs. */
+/**
+* The input {@link AgentConfig.prepareStep} sees before a turn runs.
+* @experimental
+*/
 interface AgentPrepareStepInput {
   /** The messages assembled for this turn (instructions + memory + history). */
   messages: ReadonlyArray<ModelMessage>;
@@ -343,6 +379,7 @@ interface AgentPrepareStepInput {
 * Per-turn overrides {@link AgentConfig.prepareStep} may return. A returned
 * `messages` array **replaces** the assembled history for that turn — the seam
 * where history compaction lives.
+* @experimental
 */
 interface AgentPrepareStepResult {
   /** Restrict the tools exposed to the model this turn (by name). */
@@ -359,11 +396,13 @@ interface AgentPrepareStepResult {
 /**
 * Adjust the next turn before it runs — mirrors AI SDK's `prepareStep`. Invoked
 * inside the turn's durable step so its effect is memoized on replay.
+* @experimental
 */
 type AgentPrepareStep = (input: AgentPrepareStepInput) => AgentPrepareStepResult | Promise<AgentPrepareStepResult | undefined> | undefined;
 /**
 * The subset of {@link AgentRunInput} an {@link AgentEmailMapper} returns to
 * start a run from an inbound email.
+* @experimental
 */
 interface AgentEmailRun {
   /** The user message that starts (or continues) the thread — the model's prompt. */
@@ -390,13 +429,17 @@ interface AgentEmailRun {
 * is dispatched with RLS bypassed. Gate on `email.authentication` (DKIM/SPF/DMARC
 * verdicts) here before returning a run, and treat every returned field as
 * untrusted input.
+* @experimental
 */
 type AgentEmailMapper = (email: InboundEmail) => AgentEmailRun | null | Promise<AgentEmailRun | null | undefined> | undefined;
 /** The inbound webhook channels an agent can be triggered from — see `@lunora/agent/channels`. */
 type AgentInboundChannelKind = "discord" | "github" | "slack";
 /** The run-input an inbound-channel mapper returns — the same shape as {@link AgentEmailRun}. */
 type AgentChannelRun = AgentEmailRun;
-/** The verified, parsed webhook event handed to an {@link AgentInboundChannel.map} mapper. */
+/**
+* The verified, parsed webhook event handed to an {@link AgentInboundChannel.map} mapper.
+* @experimental
+*/
 interface InboundChannelEvent {
   /** Which channel delivered it. */
   channel: AgentInboundChannelKind;
@@ -434,6 +477,10 @@ interface AgentInboundChannel {
   */
   secret: string | ((env: Record<string, unknown>) => string | undefined);
 }
+/**
+* `AgentConfig` is part of the experimental `@lunora/agent` API and may change without a major version bump.
+* @experimental
+*/
 interface AgentConfig {
   /** Restrict the tools the model may call, by name. Default: all tools. */
   activeTools?: ReadonlyArray<string>;
@@ -590,6 +637,7 @@ interface AgentConfig {
 * and get NO Workflow tool-loop — tool calls are deferred. All fields are
 * optional; the defaults target Workers AI (`@cf/openai/whisper-large-v3-turbo`
 * for STT, `@cf/deepgram/aura-1` for TTS).
+* @experimental
 */
 interface AgentVoiceConfig {
   /**
@@ -622,12 +670,18 @@ interface AgentVoiceConfig {
   */
   tts?: string;
 }
-/** The input the parent model provides when delegating to a sub-agent tool. */
+/**
+* The input the parent model provides when delegating to a sub-agent tool.
+* @experimental
+*/
 interface AgentSubToolInput {
   /** The task or question to hand to the sub-agent. */
   prompt: string;
 }
-/** Options for {@link AgentDefinition.asTool} (`agent.asTool(...)`). */
+/**
+* Options for {@link AgentDefinition.asTool} (`agent.asTool(...)`).
+* @experimental
+*/
 interface AgentAsToolOptions {
   /** What the sub-agent does — shown to the parent's model (it decides from it). */
   description: string;
@@ -647,7 +701,10 @@ interface AgentAsToolOptions {
   */
   wait?: (ms: number) => Promise<void>;
 }
-/** A `defineAgent` result — config plus the brand codegen discovers. */
+/**
+* A `defineAgent` result — config plus the brand codegen discovers.
+* @experimental
+*/
 interface AgentDefinition extends AgentConfig {
   /**
   * Adapt this agent into a tool a PARENT agent can call: the returned tool's
@@ -668,7 +725,10 @@ interface AgentDefinition extends AgentConfig {
   */
   memorySources?: ReadonlyArray<AgentMemorySource>;
 }
-/** Params of one agent run (the compiled workflow's payload). */
+/**
+* Params of one agent run (the compiled workflow's payload).
+* @experimental
+*/
 interface AgentRunInput {
   /** The user message that starts (or continues) the thread. */
   input: string;
@@ -686,7 +746,10 @@ interface AgentRunInput {
   /** Optional thread title, set on first creation. */
   title?: string;
 }
-/** Output of one agent run (the compiled workflow's return value). */
+/**
+* Output of one agent run (the compiled workflow's return value).
+* @experimental
+*/
 interface AgentRunResult {
   /** The parsed structured answer, when {@link AgentConfig.output} is set. */
   output?: unknown;
@@ -706,6 +769,7 @@ interface AgentRunResult {
 * Function paths of the agent runtime functions (the `agentComponent()`
 * functions the app re-exports from `lunora/agents.ts`, so codegen registers
 * them under the `agents:` namespace).
+* @experimental
 */
 interface AgentFunctionPaths {
   appendMessage: string;
@@ -736,9 +800,13 @@ interface AgentFunctionPaths {
 * placeholder written while a run pauses on a gated tool, then `"approved"` /
 * `"rejected"` on the tool result once a client resolves it. Absent on ordinary
 * messages. `"awaiting_approval"` rows are filtered out of the model prompt.
+* @experimental
 */
 type AgentMessageStatus = "approved" | "awaiting_approval" | "rejected";
-/** One persisted thread message, as the loop reads it back. */
+/**
+* One persisted thread message, as the loop reads it back.
+* @experimental
+*/
 interface AgentMessageRow {
   content: string;
   role: "assistant" | "system" | "tool" | "user";
@@ -749,13 +817,19 @@ interface AgentMessageRow {
   toolCalls?: ReadonlyArray<AgentToolCall>;
   toolName?: string;
 }
-/** One model-issued tool call. */
+/**
+* One model-issued tool call.
+* @experimental
+*/
 interface AgentToolCall {
   id: string;
   input: unknown;
   name: string;
 }
-/** Normalized result of one LLM turn (the `generate` seam's return value). */
+/**
+* Normalized result of one LLM turn (the `generate` seam's return value).
+* @experimental
+*/
 interface AgentGenerateResult {
   /** The parsed structured answer, when {@link AgentConfig.output} is set. */
   output?: unknown;
@@ -764,7 +838,10 @@ interface AgentGenerateResult {
   /** Token usage the model reported for this turn. */
   usage?: AgentUsage;
 }
-/** Options passed to the {@link AgentGenerate} seam for one LLM turn. */
+/**
+* Options passed to the {@link AgentGenerate} seam for one LLM turn.
+* @experimental
+*/
 interface AgentGenerateOptions {
   /** Restrict the tools exposed to the model this turn (by name). */
   activeTools?: ReadonlyArray<string>;
@@ -785,6 +862,7 @@ interface AgentGenerateOptions {
 /**
 * The LLM-turn seam: given the assembled conversation, return the model's
 * decision. Production wires AI SDK `generateText`; tests inject a script.
+* @experimental
 */
 type AgentGenerate = (options: AgentGenerateOptions) => Promise<AgentGenerateResult>;
 /**
@@ -867,6 +945,7 @@ type AgentEpisodeExtract = (input: {
 * persisted assistant message is the single source of truth). Keyed by
 * `threadKey` + the zero-based `turn` so a client can correlate a delta to the
 * in-flight turn.
+* @experimental
 */
 interface AgentTokenDelta {
   /**
@@ -890,6 +969,7 @@ interface AgentTokenDelta {
 * replayed. Correlated to the in-flight tool call (and its persisted tool row)
 * by `toolCallId` rather than a turn index, since a single turn can fan out many
 * tool calls.
+* @experimental
 */
 interface AgentProgressEvent {
   /** The arbitrary, JSON-serializable payload the tool reported. */
@@ -907,6 +987,7 @@ interface AgentProgressEvent {
 * (`toolCallId`-keyed). Both are ephemeral and never replayed — the persisted
 * thread messages remain the single source of truth. Discriminate on `kind`
 * (`"progress"` for the progress arm; token deltas leave it unset).
+* @experimental
 */
 type AgentLiveEvent = AgentProgressEvent | AgentTokenDelta;
 /**
@@ -923,6 +1004,7 @@ type AgentLiveEvent = AgentProgressEvent | AgentTokenDelta;
 * of a completed turn. Consumers should therefore reset/dedupe accumulated text
 * per `threadKey`+`turn` boundary so a step retry cannot visually double-append;
 * the persisted assistant message remains the single source of truth.
+* @experimental
 */
 type AgentTokenSink = (event: AgentLiveEvent) => void;
 /**
@@ -932,9 +1014,13 @@ type AgentTokenSink = (event: AgentLiveEvent) => void;
 * durable `llm:turn:N` step memoizes (and persists) is identical whether the
 * turn streamed or not. Production wires AI SDK `streamText`; tests inject a
 * script. Deltas are live-only — a workflow replay never re-invokes the seam.
+* @experimental
 */
 type AgentStreamGenerate = (options: AgentGenerateOptions, onDelta: (text: string) => void) => Promise<AgentGenerateResult>;
-/** Spec entry codegen emits per agent: `{ binding: "AGENT_SUPPORT", exportName: "support" }`. */
+/**
+* Spec entry codegen emits per agent: `{ binding: "AGENT_SUPPORT", exportName: "support" }`.
+* @experimental
+*/
 interface AgentBindingSpec {
   binding: string;
   exportName: string;
@@ -954,9 +1040,13 @@ interface AgentBindingSpec {
 * {@link AgentHandle.cancel}, and `"awaiting_input"` while the run is paused on
 * a human-in-the-loop tool approval. Mirrored by the `status` `v.union` in
 * `component.ts`.
+* @experimental
 */
 type AgentThreadStatus = "awaiting_input" | "cancelled" | "error" | "idle" | "running";
-/** Structural subset of a Cloudflare Workflow instance the producer surface needs. */
+/**
+* Structural subset of a Cloudflare Workflow instance the producer surface needs.
+* @experimental
+*/
 interface AgentWorkflowInstanceLike {
   /** Deliver an external event to the running instance (resumes a `waitForEvent`). */
   sendEvent: (event: {
@@ -966,7 +1056,10 @@ interface AgentWorkflowInstanceLike {
   status: () => Promise<unknown>;
   terminate: () => Promise<void>;
 }
-/** Structural subset of a Cloudflare Workflow binding the producer surface needs. */
+/**
+* Structural subset of a Cloudflare Workflow binding the producer surface needs.
+* @experimental
+*/
 interface AgentWorkflowBindingLike {
   create: (options?: {
     id?: string;
@@ -976,12 +1069,18 @@ interface AgentWorkflowBindingLike {
   }>;
   get: (id: string) => Promise<AgentWorkflowInstanceLike>;
 }
-/** A started agent run (a workflow instance). */
+/**
+* A started agent run (a workflow instance).
+* @experimental
+*/
 interface AgentRunHandle {
   /** The workflow instance id. */
   id: string;
 }
-/** The `ctx.agents.&lt;name>` producer handle. */
+/**
+* The `ctx.agents.&lt;name>` producer handle.
+* @experimental
+*/
 interface AgentHandle {
   /**
   * Cancel a run by its workflow instance id: terminate the instance and mark