@lunora/agent 1.0.0-alpha.7 → 1.0.0-alpha.71

package/dist/packem_shared/{types.d-boAM2Yi1.d.mts → types.d-eCuvcLzf.d.mts}

@@ -23,7 +23,7 @@ interface AgentStepLike {
   /**
    * Durably hibernate until an external event of `type` arrives, then return
    * its payload. Used for human-in-the-loop approvals: a run pauses on
-   * `approval:<toolCallId>` until a client resolves it. Like `do`, a resolved
+   * `approval:<toolCallId>` until a client resolves it. Like `do`, a resolved
    * wait is memoized — a replay returns the recorded decision without pausing
    * again. Signature mirrors `@lunora/workflow`'s `WorkflowStepLike`.
    */
@@ -42,10 +42,16 @@ interface AgentStepLike {
  * `idempotencyKey`.
  *
  * The `idempotencyKey` is the deterministic durable-step name
- * (`tool:&lt;name>:&lt;toolCallId>`). A COMPLETED tool step is never re-run on a
- * 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.
+ * (`tool:<name>:<toolCallId>`, further suffixed per script step for a
+ * `codeTool`). A COMPLETED tool step is never re-run on a 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. `functionTool` forwards it to the dispatched
+ * function as `args.idempotencyKey` (pinned after the model input, so it
+ * can't be overridden) — a function that wants to dedupe declares
+ * `idempotencyKey: v.optional(v.string())` in its own args and checks it; a
+ * function that ignores it is unaffected (an undeclared arg field is dropped,
+ * not rejected).
  * @experimental
  */
 interface AgentToolContext {
@@ -102,11 +108,45 @@ interface AgentToolContext {
    * skip the write when it is already present.
    */
   setState: (state: Record<string, unknown>) => Promise<void>;
+  /**
+   * The durable-step handle (`step.do`/`waitForEvent`). ALWAYS present:
+   * `agent-loop.ts` threads it into every tool's context unconditionally, and
+   * it is required rather than optional so a missing handle is a compile
+   * error instead of a silent durability downgrade. `codeTool` uses it to give
+   * each script step its OWN nested durable boundary — see `code-tool.ts` — so
+   * a failure at script step 3 retries only step 3, not steps 1–2's
+   * already-committed side effects. Cloudflare Workflows supports a `step.do`
+   * nested inside another `step.do`'s callback (the codeTool call's own
+   * enclosing step). Most tools never touch this directly; a test driving
+   * `execute`/`runToolScript` by hand passes a pass-through double.
+   */
+  step: AgentStepLike;
   /** The thread this tool call belongs to. */
   threadKey: string;
   /** The provider-issued tool-call id. */
   toolCallId: string;
 }
+/**
+ * The view of {@link AgentToolContext} handed to a `needsApproval` gate
+ * function — every field except `setState`, `step`, and `reportProgress`.
+ *
+ * `setState` is dropped because a gate that mutates thread state is a side
+ * effect inside a decision predicate, and `reportProgress` because emitting a
+ * live event is the same thing in observable form — the decision is what the
+ * loop reports, not the deciding. `step` goes because the loop already runs the
+ * gate inside a durable step of its own, so a gate has no business opening
+ * another.
+ *
+ * `getState` and `run` stay: reads are legitimate gate inputs (gate on the
+ * caller's plan tier, on a spend total), and the gate resolves inside its own
+ * durable step, so they are replay-safe there. Note this makes the type a
+ * NARROWING, not a proof of purity — `run` takes any
+ * {@link AgentFunctionReference}, so a gate can still dispatch a mutation
+ * before approval. Nothing in the type system distinguishes a query reference
+ * from a mutation one; keeping the gate side-effect-free is the author's.
+ * @experimental
+ */
+type AgentApprovalContext = Omit<AgentToolContext, "reportProgress" | "setState" | "step">;
 /**
  * An agent tool. Unlike a raw AI SDK tool, `execute` is NOT handed to the
  * model call — the loop runs it itself inside a named durable step so a
@@ -127,17 +167,25 @@ interface AgentToolDefinition<Input = unknown, Output = unknown> {
    * Gate the tool behind a human approval (mirrors the AI SDK's
    * `needsApproval`). When it resolves truthy the durable run PAUSES — the
    * thread moves to `"awaiting_input"` and the workflow hibernates on
-   * `approval:&lt;toolCallId>` — until a client calls `agents:agentResolveApproval`.
+   * `approval:<toolCallId>` — until a client calls `agents:agentResolveApproval`.
    * On approve the tool runs exactly as normal; on reject it is skipped and a
    * tool result explaining the rejection is persisted so the next turn recovers.
    * A boolean gates statically; a function gates per input. Default: `false`
-   * (unchanged behavior). Evaluated from replay-stable input OUTSIDE the
-   * durable step (it re-runs on every replay), so it must be a PURE predicate:
-   * deterministic (no `Date.now()`/`Math.random()`) and free of side effects —
-   * never call {@link AgentToolContext.setState}/`getState` or a mutating `run`
-   * here; state writes belong only in `execute`, inside the memoized step.
+   * (unchanged behavior).
+   *
+   * The boolean/`undefined` forms are compile-time constants re-derived
+   * identically on every replay — no durable step. The FUNCTION form runs
+   * inside its OWN durable step (`tool:approval-gate:<toolCallId>`, distinct
+   * from the tool's own step), so it now runs exactly once per call, not once
+   * per replay. It must still be otherwise pure: deterministic given its
+   * inputs (no `Date.now()`/`Math.random()`) and free of side effects — the
+   * context it receives is {@link AgentApprovalContext}, which has neither
+   * `setState` nor `reportProgress`; state writes and progress events belong
+   * only in `execute`, inside the tool's own memoized step. It still holds
+   * `run`, which the type cannot narrow to reads — see
+   * {@link AgentApprovalContext}.
    */
-  needsApproval?: ((input: Input, context: AgentToolContext) => boolean | Promise<boolean>) | boolean;
+  needsApproval?: ((input: Input, context: AgentApprovalContext) => boolean | Promise<boolean>) | boolean;
 }
 /**
  * Author-supplied tool config (see {@link AgentToolDefinition}).
@@ -252,7 +300,7 @@ interface AgentMemoryOptions {
  * (`key: "default"`) from {@link AgentConfig.memory}, then one per skill that
  * 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.
+ * source uses `"memory:retrieve:<key>"` — so replay stays deterministic.
  * @experimental
  */
 interface AgentMemorySource extends AgentMemoryOptions {
@@ -308,7 +356,7 @@ interface SkillConfig {
   knowledge?: AgentMemoryOptions;
   /**
    * The skill's identifier — namespaces this skill's `knowledge` memory source
-   * (the durable step `memory:retrieve:&lt;name>`). Must be identifier-shaped.
+   * (the durable step `memory:retrieve:<name>`). Must be identifier-shaped.
    */
   name: string;
   /**
@@ -318,6 +366,12 @@ interface SkillConfig {
    */
   tools?: Record<string, AnyAgentTool>;
 }
+/**
+ * The code-side parts of a markdown-authored skill — everything `SKILL.md`
+ * cannot carry. `name` and `instructions` come from the file itself.
+ * @experimental
+ */
+type SkillMarkdownExtras = Omit<SkillConfig, "instructions" | "name">;
 /**
  * A `defineSkill` result — config plus the brand the agent merge checks.
  * @experimental
@@ -358,11 +412,43 @@ 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
+ * inside a named durable step (`agent:step-finish:<turn>`) so it fires exactly
  * once per turn even across a workflow replay.
  * @experimental
  */
 type AgentOnStepFinish = (info: AgentStepFinishInfo) => Promise<void> | void;
+/**
+ * What {@link AgentConfig.onReply} is called with when a triggered run reaches
+ * its final answer.
+ * @experimental
+ */
+interface AgentReplyInfo {
+  /** The worker `env` — where an outbound credential (a bot token, a mailer binding) lives. */
+  env: Record<string, unknown>;
+  /** Where to reply, captured by the mapper that started this run. */
+  replyRef: AgentReplyRef;
+  /** The run's final answer. */
+  result: AgentRunResult;
+  /** The thread this run belongs to. */
+  threadKey: string;
+}
+/**
+ * Send a triggered run's answer back where it came from — the outbound half of
+ * an `onEmail` / `onInbound` trigger.
+ *
+ * Called once, automatically, when a run started with a `replyRef` produces a
+ * final answer; a run without one (an ordinary in-app `ctx.agents.<name>.run`)
+ * never calls it. It runs inside a named durable step, so a transient failure
+ * is retried and a workflow replay does not send the answer twice.
+ *
+ * Delivery is the app's call, because only the app has the credential: email
+ * has a home already (`replyToEmail(mailer, ref, body)` from
+ * `@lunora/agent/reply`), while Slack/GitHub/Discord bot tokens have no
+ * framework-owned store yet — read them from `info.env` and make the provider
+ * call.
+ * @experimental
+ */
+type AgentOnReply = (info: AgentReplyInfo) => Promise<void> | void;
 /**
  * The input {@link AgentConfig.prepareStep} sees before a turn runs.
  * @experimental
@@ -404,6 +490,39 @@ type AgentPrepareStep = (input: AgentPrepareStepInput) => AgentPrepareStepResult
  * start a run from an inbound email.
  * @experimental
  */
+/**
+ * Where a triggered run should send its answer back to — captured by the
+ * mapper, from fields the verified inbound payload already carries, and carried
+ * through the run so {@link AgentConfig.onReply} can answer in the same place
+ * the question was asked.
+ *
+ * A discriminated union rather than an opaque blob because each channel threads
+ * differently: email by RFC 5322 `In-Reply-To`/`References`, Slack by
+ * `thread_ts`, GitHub by issue number, Discord by channel (plus the triggering
+ * message for a true reply).
+ * @experimental
+ */
+type AgentReplyRef = {
+  channel: "discord";
+  channelId: string;
+  messageId?: string;
+} | {
+  channel: "email";
+  from: string;
+  messageId: string;
+  references?: string;
+  to: string[];
+} | {
+  channel: "github";
+  commentId?: number;
+  issueNumber: number;
+  owner: string;
+  repo: string;
+} | {
+  channel: "slack";
+  channelId: string;
+  threadTs: string;
+};
 interface AgentEmailRun {
   /** The user message that starts (or continues) the thread — the model's prompt. */
   input: string;
@@ -414,6 +533,13 @@ interface AgentEmailRun {
    * `email.from`.
    */
   owner?: string;
+  /**
+   * Where to send the answer — see {@link AgentReplyRef}. Populate it from the
+   * event the mapper already has (`captureEmailReplyRef(email)` does it for
+   * email) and the run calls {@link AgentConfig.onReply} with it once the
+   * final answer is ready. Omit it and the run simply never replies.
+   */
+  replyRef?: AgentReplyRef;
   /** The thread key — reuse to continue a conversation (e.g. a ticket id parsed from the subject). */
   threadKey: string;
   /** Optional thread title, set on first creation. */
@@ -484,6 +610,22 @@ interface AgentInboundChannel {
 interface AgentConfig {
   /** Restrict the tools the model may call, by name. Default: all tools. */
   activeTools?: ReadonlyArray<string>;
+  /**
+   * How long a human-in-the-loop tool approval may stay pending before the
+   * run stops waiting — a Cloudflare Workflows duration: milliseconds, or a
+   * `"<n> <unit>"` string like `"3 days"` (the unit set is the host's, so a
+   * typo is a compile error). Default `"3 days"`.
+   *
+   * On timeout the call is treated as REJECTED (the run records why and
+   * continues down the normal rejection path), so a run whose approver never
+   * answers ends instead of hibernating forever.
+   *
+   * CLAMPED to one week. A longer wait would outlive the thread's
+   * abandoned-run horizon, letting a new run reclaim the thread while the
+   * approval is still pending — which is the exact failure this timeout
+   * exists to prevent, so it cannot be configured back into existence.
+   */
+  approvalTimeout?: `${number} ${"day" | "hour" | "minute" | "month" | "second" | "week" | "year"}${"s" | ""}` | number;
   /**
    * Automatic thread-history compaction. When the persisted history exceeds
    * `maxMessages`, the loop summarizes the older messages (all but the most
@@ -530,7 +672,7 @@ interface AgentConfig {
   model: AgentModelInput;
   /**
    * Optional override for the deployed workflow name (`wrangler.jsonc`
-   * `workflows[].name`). Defaults to `agent-&lt;kebab-cased export name>`. Does
+   * `workflows[].name`). Defaults to `agent-<kebab-cased export name>`. Does
    * NOT change the binding name, which is always derived from the export
    * name (`support` → `AGENT_SUPPORT`).
    */
@@ -543,7 +685,16 @@ interface AgentConfig {
    *
    * - `"reject"` (default) — fail the new run fast with a `CONFLICT` error.
    * - `"replace"` — terminate the in-flight instance and take the thread over.
-   * - `"queue"` — reserved for a future durable queue; currently degrades to `"reject"` (no queue exists yet), tracked as a follow-up.
+   * - `"queue"` — park the new run behind the one in flight (FIFO, up to five deep) and hibernate it until the thread is handed over.
+   *
+   * Each parked run is a live workflow instance waiting on an event, so the
+   * queue's depth cap is a real resource bound: past it, a start is rejected
+   * exactly as `"reject"` would. A `"replace"` arriving later supersedes the
+   * run in FLIGHT, not the queue — parked runs still take their turn after it.
+   *
+   * A dispatch with no instance id (the inbound-email / inbound-channel
+   * paths) cannot be parked, because nothing later can tell it apart from
+   * another such dispatch to wake it; `"queue"` rejects those.
    *
    * A workflow REPLAY re-enters the bootstrap under the SAME instance id and
    * is never a concurrent run (the guard compares the stored instance id).
@@ -563,6 +714,12 @@ interface AgentConfig {
    * signature over the raw body before calling `map`.
    */
   onInbound?: AgentInboundChannel;
+  /**
+   * Called with the final answer when the run was triggered from a channel
+   * that gave it a `replyRef` — see {@link AgentOnReply}. This is how an
+   * inbound-triggered agent answers where it was asked.
+   */
+  onReply?: AgentOnReply;
   /** Called after each LLM turn — see {@link AgentOnStepFinish}. */
   onStepFinish?: AgentOnStepFinish;
   /**
@@ -577,7 +734,7 @@ interface AgentConfig {
    * Opt this agent into being STARTED over the public RPC boundary — i.e. via
    * the auto-registered `agents:agentRun` mutation an HTTP-only client (e.g.
    * the `@lunora/mcp` server) calls. Default `false`: an agent is startable
-   * only from server-side app code (`ctx.agents.&lt;name>.run(...)`), so declaring
+   * only from server-side app code (`ctx.agents.<name>.run(...)`), so declaring
    * an agent does NOT expose it to arbitrary RPC callers. Fail-closed — the run
    * mutation refuses an agent that has not opted in, regardless of any MCP-side
    * `allowAgents` configuration. A started thread is still owner-scoped to
@@ -688,7 +845,7 @@ interface AgentAsToolOptions {
   /** Cap on child-run status polls before giving up. Default 120. */
   maxPolls?: number;
   /**
-   * The child agent's export name — selects its `AGENT_&lt;NAME>` Workflow
+   * The child agent's export name — selects its `AGENT_<NAME>` Workflow
    * binding (e.g. `"researcher"` → `AGENT_RESEARCHER`). The model-facing tool
    * name is the KEY assigned in the parent's `tools` map, not this.
    */
@@ -725,6 +882,26 @@ interface AgentDefinition extends AgentConfig {
    */
   memorySources?: ReadonlyArray<AgentMemorySource>;
 }
+/**
+ * What `agentEnsureThread` reports back to the loop.
+ *
+ * A discriminated union rather than a bag of optional booleans: the four
+ * outcomes are mutually exclusive, and the data each carries only exists for its
+ * own case. `queued` has a position, `replaced` has the instance it took the
+ * thread from, and the other two have nothing — encoding that as five
+ * independent optional fields made every reader re-derive which combination was
+ * legal.
+ * @experimental
+ */
+type EnsureThreadOutcome = {
+  outcome: "continued" | "created";
+} | {
+  outcome: "queued";
+  position: number;
+} | {
+  outcome: "replaced";
+  priorInstanceId: string;
+};
 /**
  * Params of one agent run (the compiled workflow's payload).
  * @experimental
@@ -741,6 +918,8 @@ interface AgentRunInput {
    * the first run.
    */
   owner?: string;
+  /** Where a triggered run sends its answer — see {@link AgentReplyRef}. */
+  replyRef?: AgentReplyRef;
   /** The thread key — reuse to continue a conversation. */
   threadKey: string;
   /** Optional thread title, set on first creation. */
@@ -773,6 +952,17 @@ interface AgentRunResult {
  */
 interface AgentFunctionPaths {
   appendMessage: string;
+  /**
+   * The internal `agents:agentCompleteRun` mutation the loop dispatches at the
+   * end of a run: it writes the terminal status AND hands the thread to the
+   * next queued run in the same mutation.
+   */
+  completeRun: string;
+  /**
+   * The internal `agents:agentDeleteMessage` mutation the loop dispatches to
+   * retire the HITL approval marker once the decision has landed.
+   */
+  deleteMessage: string;
   ensureThread: string;
   /** The internal `agents:agentEpisodeRecall` query the loop dispatches for an episodic-kind read. */
   episodeRecall: string;
@@ -1078,7 +1268,7 @@ interface AgentRunHandle {
   id: string;
 }
 /**
- * The `ctx.agents.&lt;name>` producer handle.
+ * The `ctx.agents.<name>` producer handle.
  * @experimental
  */
 interface AgentHandle {
@@ -1111,4 +1301,4 @@ interface AgentHandle {
   /** Read a run's workflow status by instance id. */
   status: (id: string) => Promise<unknown>;
 }
-export { AgentDefinition as A, AgentGenerateOptions as B, AgentGenerateResult as C, AgentInstructionsContext as D, AgentLiveEvent as E, AgentMemoryOptions as F, AgentMemorySource as G, AgentMessageStatus as H, InboundChannelEvent as I, AgentOnStepFinish as J, AgentPrepareStep as K, AgentPrepareStepInput as L, AgentPrepareStepResult as M, AgentProgressEvent as N, AgentRunHandle as O, AgentStepFinishInfo as P, AgentStepInfo as Q, AgentThreadStatus as R, SkillDefinition as S, AgentTokenDelta as T, AgentToolCall as U, AgentUsage as V, AgentVoiceConfig as W, AgentWorkflowBindingLike as X, AgentWorkflowInstanceLike as Y, AgentToolContext as a, AgentToolDefinition as b, AgentCompact as c, AgentEpisodeExtract as d, AgentGraphExtract as e, AgentGenerate as f, AgentTokenSink as g, AgentRunInput as h, AgentFunctionPaths as i, AgentRunFunction as j, AgentStepLike as k, AgentStreamGenerate as l, AgentRunResult as m, AgentMessageRow as n, AgentConfig as o, AnyAgentTool as p, AgentAsToolOptions as q, AgentSubToolInput as r, AgentBindingSpec as s, AgentHandle as t, AgentToolConfig as u, AgentFunctionReference as v, AgentModelInput as w, SkillConfig as x, AgentEmailMapper as y, AgentEmailRun as z };
+export { AgentVoiceConfig as $, AgentDefinition as A, AgentApprovalContext as B, AgentEmailMapper as C, AgentEmailRun as D, AgentGenerateOptions as E, AgentGenerateResult as F, AgentInstructionsContext as G, AgentLiveEvent as H, InboundChannelEvent as I, AgentMemoryOptions as J, AgentMemorySource as K, AgentMessageStatus as L, AgentOnReply as M, AgentOnStepFinish as N, AgentPrepareStep as O, AgentPrepareStepInput as P, AgentPrepareStepResult as Q, AgentProgressEvent as R, SkillMarkdownExtras as S, AgentReplyInfo as T, AgentRunHandle as U, AgentStepFinishInfo as V, AgentStepInfo as W, AgentThreadStatus as X, AgentTokenDelta as Y, AgentToolCall as Z, AgentUsage as _, AgentReplyRef as a, AgentWorkflowBindingLike as a0, AgentWorkflowInstanceLike as a1, EnsureThreadOutcome as a2, AgentToolContext as b, AgentToolDefinition as c, SkillDefinition as d, AgentCompact as e, AgentEpisodeExtract as f, AgentGraphExtract as g, AgentGenerate as h, AgentTokenSink as i, AgentRunInput as j, AgentFunctionPaths as k, AgentRunFunction as l, AgentStepLike as m, AgentStreamGenerate as n, AgentRunResult as o, AgentMessageRow as p, AgentConfig as q, AnyAgentTool as r, AgentAsToolOptions as s, AgentSubToolInput as t, AgentBindingSpec as u, AgentHandle as v, AgentToolConfig as w, AgentFunctionReference as x, AgentModelInput as y, SkillConfig as z };