@lunora/agent 1.0.0-alpha.9 → 1.0.0-alpha.91

package/dist/packem_shared/sandboxComponent-BtOkUYpY.mjs

@@ -0,0 +1,5 @@
+import{LunoraError as c}from"@lunora/errors";import{initLunora as h}from"@lunora/server";import{v as t}from"@lunora/values";import{t as g}from"./base64-5eyBfWO3.mjs";const{internalAction:w}=h.dataModel().create(),m=()=>globalThis.document?.documentElement?.outerHTML??"",l=1e6,b=20,x=new TextEncoder,y=async(e,n)=>{const o=n.url??"";switch(n.op){case"content":return e.content(o);case"pdf":return{data:g(await e.pdf(o)),encoding:"base64",mediaType:"application/pdf"};case"scrape":return e.scrape(o,m);case"screenshot":{const s=await e.screenshot(o,{...n.fullPage===void 0?{}:{fullPage:n.fullPage},...n.type===void 0?{}:{type:n.type}});return{data:g(s),encoding:"base64",mediaType:n.type==="jpeg"?"image/jpeg":"image/png"}}default:throw new c("INTERNAL",`@lunora/agent: sandbox browser op "${n.op}" is not supported`)}},E=e=>{const n=[`exit code: ${String(e.code)}`];return e.stdout.length>0&&n.push(`stdout:
+${e.stdout}`),e.stderr.length>0&&n.push(`stderr:
+${e.stderr}`),n.join(`
+
+`)},$=async(e,n)=>{const o=e.any();if(n.op==="exec")try{return E(await o.exec(n.command??"",{args:n.args??[]}))}catch(s){return`exec failed: ${s instanceof Error?s.message:String(s)}`}if(n.op==="fetch")return(await o.fetch(n.path??"/",{...n.body===void 0?{}:{body:n.body},method:n.method??"GET"})).text();throw new c("INTERNAL",`@lunora/agent: sandbox container op "${n.op}" is not supported`)},u=e=>{let n=0,o=e.length;for(;n<o&&e[n]==="/";)n+=1;for(;o>n&&e[o-1]==="/";)o-=1;return e.slice(n,o)},T=(e,n)=>{const o=u(e),s=[];for(const r of n.split("/"))if(!(r===""||r===".")){if(r===".."){if(s.length===0)throw new c("BAD_REQUEST","@lunora/agent: fs path escapes the sandbox root");s.pop();continue}s.push(r)}const a=s.join("/");return o&&a?`${o}/${a}`:o||a},S=async(e,n,o)=>{const s=n.length>0?`${n}/`:"",a=o.length>0?o.length+1:0,r=[];let i;for(let d=0;d<b;d+=1){const p=await e.list({prefix:s,...i===void 0?{}:{cursor:i}});for(const f of p.objects)r.push(f.key.slice(a));if(!p.truncated||p.cursor===void 0)return{entries:r,truncated:!1};i=p.cursor}return{entries:r,truncated:!0}},N=async(e,n,o)=>{const s=u(n),a=T(n,o.path??"");switch(o.op){case"ls":{const{entries:r,truncated:i}=await S(e,a,s);return i?{entries:r,truncated:!0}:{entries:r}}case"read":{const r=await e.head(a);if(r&&r.size>l)throw new c("BAD_REQUEST",`@lunora/agent: fs read: "${o.path??""}" is ${String(r.size)} bytes (max ${String(l)})`);const i=await e.get(a);if(!i)throw new c("NOT_FOUND",`@lunora/agent: fs read: no file at "${o.path??""}"`);return i.text()}case"rm":return await e.delete(a),{path:o.path??"",removed:!0};case"stat":{const r=await e.head(a);return r?{exists:!0,size:r.size}:{exists:!1}}case"write":{const r=o.content??"",i=x.encode(r).length;if(i>l)throw new c("BAD_REQUEST",`@lunora/agent: fs write: ${String(i)} bytes exceeds the max (${String(l)})`);return await e.put(a,r),{bytes:i,path:o.path??"",wrote:!0}}default:throw new c("INTERNAL",`@lunora/agent: sandbox fs op "${o.op}" is not supported`)}},_=()=>({invoke:w.input({args:t.optional(t.array(t.string())),body:t.optional(t.string()),bucket:t.optional(t.string()),command:t.optional(t.string()),content:t.optional(t.string()),fullPage:t.optional(t.boolean()),kind:t.union(t.literal("browser"),t.literal("container"),t.literal("fs")),method:t.optional(t.string()),name:t.optional(t.string()),op:t.string(),path:t.optional(t.string()),root:t.optional(t.string()),selector:t.optional(t.string()),type:t.optional(t.string()),url:t.optional(t.string())}).action(async({args:n,ctx:o})=>{const s=o,a=n;if(a.kind==="browser"){if(!s.browser)throw new c("INTERNAL","@lunora/agent: sandbox browser op needs `ctx.browser` — install @lunora/browser and run codegen");return y(s.browser,a)}if(a.kind==="fs"){const d=s.env?.[a.bucket??""];if(!d||typeof d.get!="function")throw new c("INTERNAL",`@lunora/agent: sandbox fs op found no R2 bucket "${a.bucket??""}" on env — declare the r2_bucket binding in wrangler.jsonc and run codegen`);return N(d,a.root??"",a)}const r=a.name??"",i=s.containers?.[r];if(!i)throw new c("INTERNAL",`@lunora/agent: sandbox container op found no ctx.containers["${r}"] — declare the container in lunora/containers.ts and run codegen`);return $(i,a)})});export{T as resolveFsKey,N as runFsOp,_ as sandboxComponent};

package/dist/packem_shared/sentryTelemetry-BHeydiAB.mjs

@@ -0,0 +1 @@
+import{r as n,t as _,s as y,c as I}from"./common-CJSjtsfv.mjs";import{c as x}from"./in-flight-calls-GH1A_1P3.mjs";const g=(c,i)=>typeof c=="string"&&c.length>0?c:i,k=c=>{const{functionId:i,recordInputs:d=!1,recordOutputs:p=!1,Sentry:u}=c,s=x((e,o,a,r)=>{const t={},l=y(n(r,"usage")??n(e.result,"usage"));if(l&&(t["gen_ai.usage.input_tokens"]=l.inputTokens,t["gen_ai.usage.output_tokens"]=l.outputTokens,t["gen_ai.usage.total_tokens"]=l.totalTokens),p){const m=I(n(r,"content")??n(e.result,"content"));m!==void 0&&(t["gen_ai.completion"]=m)}Object.keys(t).length>0&&e.span.setAttributes?.(t),e.span.setStatus?.(o?{code:1}:{code:2,message:a??""}),e.span.end()},e=>{e.span.end()}),f=(e,o,a)=>{const r=n(e,"callId");if(typeof r!="string")return;let t=a;o instanceof Error?t=o.message:typeof o=="string"&&o.length>0&&(t=o),s.close(r,!1,t,void 0)};return{executeLanguageModelCall:e=>{const{callId:o}=e,a={"gen_ai.operation.name":g(i,"language_model_call"),"gen_ai.request.model":n(e,"modelId"),"gen_ai.system":n(e,"provider")};return d&&(a["gen_ai.prompt"]=n(e,"messages")),u.startSpanManual({attributes:a,name:g(i,"language_model_call"),op:"gen_ai.generate"},async r=>{s.open(o,()=>({result:void 0,span:r}));try{const t=await e.execute(),l=s.get(o);return l!==void 0&&(l.result=t),t}catch(t){throw s.close(o,!1,t instanceof Error?t.message:String(t),void 0),t}})},executeTool:e=>{const o=n(n(e,"toolCall"),"toolName"),a={"gen_ai.operation.name":"execute_tool","gen_ai.tool.call.id":n(e,"toolCallId"),"gen_ai.tool.name":o};return d&&(a["gen_ai.tool.input"]=_(e)),u.startSpan({attributes:a,name:`execute_tool ${g(o,"tool")}`,op:"gen_ai.execute_tool"},()=>e.execute())},onAbort:e=>{f(e,n(e,"reason"),"aborted")},onEnd:e=>{s.fromLifecycle(e)},onError:e=>{u.captureException(n(e,"error")??e),f(e,n(e,"error"),"the model call failed")},onLanguageModelCallEnd:e=>{const o=n(e,"callId");typeof o=="string"&&s.close(o,!0,void 0,e)},onStepEnd:e=>{s.fromLifecycle(e)}}};export{k as sentryTelemetry};

package/dist/packem_shared/tool-output-Cmk3JWMG.mjs

@@ -0,0 +1 @@
+const _=4e3,O="… [truncated]",t=T=>T.length<=4e3?T:`${T.slice(0,4e3-O.length)}${O}`;export{_ as M,t as c};

package/dist/packem_shared/{types.d-boAM2Yi1.d.mts → types.d-B8WZl1rU.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,13 +42,26 @@ 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 {
+  /**
+   * How many sub-agent delegations deep this run already is — 0 for a run a
+   * user started, one more per `agent.asTool` hop. The loop copies it off
+   * {@link AgentRunInput.depth}; `agent.asTool` reads it to refuse spawning a
+   * child past the delegation-depth bound (see `as-tool.ts`). Absent is 0.
+   */
+  depth?: number;
   /** The Worker environment bindings. */
   env: Record<string, unknown>;
   /**
@@ -67,6 +80,14 @@ interface AgentToolContext {
   getState: () => Promise<Record<string, unknown> | undefined>;
   /** Deterministic idempotency key — the tool's durable-step name. */
   idempotencyKey: string;
+  /**
+   * Verified owner of the thread this run belongs to (the loop copies it off
+   * {@link AgentRunInput.owner}); `undefined` on an anonymous/single-tenant
+   * thread. `agent.asTool` forwards it to the CHILD run, so a sub-agent thread
+   * under an owned parent inherits the same RLS scope instead of being created
+   * ownerless — which left it readable by anyone who knew its key.
+   */
+  owner?: string;
   /**
    * Emit an EPHEMERAL progress event for this tool call on the agent's live
    * channel — the same live-only sink the streamed token deltas ride. NOT
@@ -102,11 +123,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 +182,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 +315,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 +371,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 +381,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 +427,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 +505,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 +548,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 +625,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 +687,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 +700,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 +729,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 +749,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
@@ -649,8 +821,20 @@ interface AgentVoiceConfig {
   /**
    * Spoken on connect before the first user turn — a fixed greeting synthesized
    * through the TTS model. Omit for a silent-until-spoken-to session.
+   *
+   * Synthesized once per THREAD, not once per socket: the greeting's persisted
+   * row is keyed per thread, and a reconnect onto a thread that already exists
+   * gets the `ready` frame without paying for the same line again.
    */
   greeting?: string;
+  /**
+   * Cap on how many turns one voice socket may run before it is closed with
+   * code `4002`. Every turn is a full LLM generation plus sentence-by-sentence
+   * TTS — billed and persisted — on a hibernatable socket that can live for
+   * days, and the one-turn-in-flight guard throttles nothing. Defaults to 100;
+   * a client that hits the cap reconnects for a fresh budget.
+   */
+  maxTurns?: number;
   /**
    * TTS voice/speaker id forwarded to the TTS model (e.g. a Deepgram Aura voice
    * like `"aura-asteria-en"`). Model-specific; omitted when unset so the model
@@ -685,10 +869,10 @@ interface AgentSubToolInput {
 interface AgentAsToolOptions {
   /** What the sub-agent does — shown to the parent's model (it decides from it). */
   description: string;
-  /** Cap on child-run status polls before giving up. Default 120. */
+  /** Cap on child-run status polls before giving up — a positive integer. Default 600 (with the 500 ms default interval, a five-minute budget). */
   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,11 +909,39 @@ 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
  */
 interface AgentRunInput {
+  /**
+   * Sub-agent delegation depth. A run a user starts omits it (0); each
+   * `agent.asTool` hop stamps its child one deeper, and the tool refuses to
+   * delegate past the bound — `maxTurns` bounds one level's turns, this bounds
+   * the TREE (every hop mints a distinct child `threadKey`, so the per-thread
+   * run-queue cap never applies across them).
+   */
+  depth?: number;
   /** The user message that starts (or continues) the thread. */
   input: string;
   /**
@@ -741,6 +953,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 +987,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;
@@ -824,6 +1049,14 @@ interface AgentMessageRow {
 interface AgentToolCall {
   id: string;
   input: unknown;
+  /**
+   * Why this call was REJECTED before it could run: the model's arguments
+   * failed the tool's input schema, or did not parse as JSON. Present only on
+   * a rejected call — the loop records it as a recoverable tool result and
+   * never executes the tool, because the `input` above is the raw value the
+   * provider sent, not a validated one.
+   */
+  invalid?: string;
   name: string;
 }
 /**
@@ -1078,7 +1311,7 @@ interface AgentRunHandle {
   id: string;
 }
 /**
- * The `ctx.agents.&lt;name>` producer handle.
+ * The `ctx.agents.<name>` producer handle.
  * @experimental
  */
 interface AgentHandle {
@@ -1111,4 +1344,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 };