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

package/README.md

@@ -1,5 +1,7 @@
 # @lunora/agent
 
+> **Experimental** — this package is outside the Lunora 1.0 stability promise: its API may change in any release, without a major version bump.
+
 Durable AI agents for [Lunora](https://lunora.sh): `defineAgent` compiles a replay-safe tool-loop onto Cloudflare Workflows — each LLM turn and each tool call is a named durable step, thread messages persist idempotently in DO SQLite, and clients watch the conversation live over Lunora's reactive subscriptions.
 
 ```ts

package/dist/channels.d.mts

@@ -1,12 +1,13 @@
-import { A as AgentDefinition } from "./packem_shared/types.d-BWG0uUtX.mjs";
-export type { I as InboundChannelEvent } from "./packem_shared/types.d-BWG0uUtX.mjs";
+import { A as AgentDefinition } from "./packem_shared/types.d-boAM2Yi1.mjs";
+export type { I as InboundChannelEvent } from "./packem_shared/types.d-boAM2Yi1.mjs";
 import '@lunora/mail/inbound';
 import 'ai';
 /**
-* Verify a Slack request signature (`x-slack-signature` = `v0=` + HMAC over
-* `v0:timestamp:body`), rejecting a stale timestamp to bound replay. `now` is
-* injectable for deterministic tests (defaults to the wall clock).
-*/
+ * Verify a Slack request signature (`x-slack-signature` = `v0=` + HMAC over
+ * `v0:timestamp:body`), rejecting a stale timestamp to bound replay. `now` is
+ * injectable for deterministic tests (defaults to the wall clock).
+ * @experimental
+ */
 declare const verifySlack: (options: {
   body: string;
   now?: number;
@@ -15,40 +16,59 @@ declare const verifySlack: (options: {
   timestamp: string | undefined;
   tolerance?: number;
 }) => Promise<boolean>;
-/** Verify a GitHub webhook signature (`x-hub-signature-256` = `sha256=` + HMAC over the body). */
+/**
+ * Verify a GitHub webhook signature (`x-hub-signature-256` = `sha256=` + HMAC over the body).
+ * @experimental
+ */
 declare const verifyGithub: (options: {
   body: string;
   secret: string;
   signature: string | undefined;
 }) => Promise<boolean>;
 /**
-* Verify a Discord interaction signature: Ed25519 over `timestamp + body`,
-* `x-signature-ed25519` (hex) against the application's `publicKey` (hex).
-*/
+ * Verify a Discord interaction signature: Ed25519 over `timestamp + body`,
+ * `x-signature-ed25519` (hex) against the application's `publicKey` (hex).
+ * @experimental
+ */
 declare const verifyDiscord: (options: {
   body: string;
   publicKey: string;
   signature: string | undefined;
   timestamp: string | undefined;
 }) => Promise<boolean>;
-/** One agent wired into the inbound channel HTTP handler. */
+/**
+ * One agent wired into the inbound channel HTTP handler.
+ * @experimental
+ */
 interface AgentChannelTarget {
   /** The agent definition — only its `onInbound` config is read. */
   agent: Pick<AgentDefinition, "onInbound">;
   /** The `AGENT_*` Workflow binding name (off `env`) that starts a run. */
   binding: string;
 }
-/** The HTTP handler `dispatchAgentChannel` returns — mount it on a webhook route. */
+/**
+ * The HTTP handler `dispatchAgentChannel` returns — mount it on a webhook route.
+ * @experimental
+ */
 type InboundChannelHandler = (request: Request, env: Record<string, unknown>) => Promise<Response>;
 /**
-* Build an HTTP handler that starts a durable agent run from a verified inbound
-* webhook. The channel is detected from the signature headers; EACH eligible
-* target is verified against ITS OWN secret before its mapper is offered the
-* event (so one app's valid signature can't trigger another app's agent), and
-* the first target that both verifies and claims starts a run on its Workflow
-* binding. Returns `401` when NO target's signature verifies, `200` on a claim
-* (or a Discord PONG), `204` when a verified event is declined by every mapper,
-* and `400` for an unrecognized webhook.
-*/
+ * Whether a `workflow.create()` rejection is a duplicate-instance-id error — the
+ * idempotency signal — as opposed to a transient/config failure (Workflows
+ * service error, instance-creation quota, bad params). Only the former may be
+ * acked; every other failure MUST surface so the handler returns non-2xx and the
+ * provider redelivers, rather than silently dropping the event.
+ */
+declare const isDuplicateInstanceError: (error: unknown) => boolean;
+/**
+ * Build an HTTP handler that starts a durable agent run from a verified inbound
+ * webhook. The channel is detected from the signature headers; EACH eligible
+ * target is verified against ITS OWN secret before its mapper is offered the
+ * event (so one app's valid signature can't trigger another app's agent), and
+ * the first target that both verifies and claims starts a run on its Workflow
+ * binding. Returns `401` when NO target's signature verifies, `200` on a claim
+ * (or a Discord PONG), `204` when a verified event is declined by every mapper,
+ * and `400` for an unrecognized webhook.
+ * @experimental
+ */
 declare const dispatchAgentChannel: (targets: ReadonlyArray<AgentChannelTarget>) => InboundChannelHandler;
-export { type AgentChannelTarget, type InboundChannelHandler, dispatchAgentChannel, verifyDiscord, verifyGithub, verifySlack };
+export { type AgentChannelTarget, type InboundChannelHandler, dispatchAgentChannel, isDuplicateInstanceError, verifyDiscord, verifyGithub, verifySlack };

package/dist/channels.d.ts

@@ -1,12 +1,13 @@
-import { A as AgentDefinition } from "./packem_shared/types.d-BWG0uUtX.js";
-export type { I as InboundChannelEvent } from "./packem_shared/types.d-BWG0uUtX.js";
+import { A as AgentDefinition } from "./packem_shared/types.d-boAM2Yi1.js";
+export type { I as InboundChannelEvent } from "./packem_shared/types.d-boAM2Yi1.js";
 import '@lunora/mail/inbound';
 import 'ai';
 /**
-* Verify a Slack request signature (`x-slack-signature` = `v0=` + HMAC over
-* `v0:timestamp:body`), rejecting a stale timestamp to bound replay. `now` is
-* injectable for deterministic tests (defaults to the wall clock).
-*/
+ * Verify a Slack request signature (`x-slack-signature` = `v0=` + HMAC over
+ * `v0:timestamp:body`), rejecting a stale timestamp to bound replay. `now` is
+ * injectable for deterministic tests (defaults to the wall clock).
+ * @experimental
+ */
 declare const verifySlack: (options: {
   body: string;
   now?: number;
@@ -15,40 +16,59 @@ declare const verifySlack: (options: {
   timestamp: string | undefined;
   tolerance?: number;
 }) => Promise<boolean>;
-/** Verify a GitHub webhook signature (`x-hub-signature-256` = `sha256=` + HMAC over the body). */
+/**
+ * Verify a GitHub webhook signature (`x-hub-signature-256` = `sha256=` + HMAC over the body).
+ * @experimental
+ */
 declare const verifyGithub: (options: {
   body: string;
   secret: string;
   signature: string | undefined;
 }) => Promise<boolean>;
 /**
-* Verify a Discord interaction signature: Ed25519 over `timestamp + body`,
-* `x-signature-ed25519` (hex) against the application's `publicKey` (hex).
-*/
+ * Verify a Discord interaction signature: Ed25519 over `timestamp + body`,
+ * `x-signature-ed25519` (hex) against the application's `publicKey` (hex).
+ * @experimental
+ */
 declare const verifyDiscord: (options: {
   body: string;
   publicKey: string;
   signature: string | undefined;
   timestamp: string | undefined;
 }) => Promise<boolean>;
-/** One agent wired into the inbound channel HTTP handler. */
+/**
+ * One agent wired into the inbound channel HTTP handler.
+ * @experimental
+ */
 interface AgentChannelTarget {
   /** The agent definition — only its `onInbound` config is read. */
   agent: Pick<AgentDefinition, "onInbound">;
   /** The `AGENT_*` Workflow binding name (off `env`) that starts a run. */
   binding: string;
 }
-/** The HTTP handler `dispatchAgentChannel` returns — mount it on a webhook route. */
+/**
+ * The HTTP handler `dispatchAgentChannel` returns — mount it on a webhook route.
+ * @experimental
+ */
 type InboundChannelHandler = (request: Request, env: Record<string, unknown>) => Promise<Response>;
 /**
-* Build an HTTP handler that starts a durable agent run from a verified inbound
-* webhook. The channel is detected from the signature headers; EACH eligible
-* target is verified against ITS OWN secret before its mapper is offered the
-* event (so one app's valid signature can't trigger another app's agent), and
-* the first target that both verifies and claims starts a run on its Workflow
-* binding. Returns `401` when NO target's signature verifies, `200` on a claim
-* (or a Discord PONG), `204` when a verified event is declined by every mapper,
-* and `400` for an unrecognized webhook.
-*/
+ * Whether a `workflow.create()` rejection is a duplicate-instance-id error — the
+ * idempotency signal — as opposed to a transient/config failure (Workflows
+ * service error, instance-creation quota, bad params). Only the former may be
+ * acked; every other failure MUST surface so the handler returns non-2xx and the
+ * provider redelivers, rather than silently dropping the event.
+ */
+declare const isDuplicateInstanceError: (error: unknown) => boolean;
+/**
+ * Build an HTTP handler that starts a durable agent run from a verified inbound
+ * webhook. The channel is detected from the signature headers; EACH eligible
+ * target is verified against ITS OWN secret before its mapper is offered the
+ * event (so one app's valid signature can't trigger another app's agent), and
+ * the first target that both verifies and claims starts a run on its Workflow
+ * binding. Returns `401` when NO target's signature verifies, `200` on a claim
+ * (or a Discord PONG), `204` when a verified event is declined by every mapper,
+ * and `400` for an unrecognized webhook.
+ * @experimental
+ */
 declare const dispatchAgentChannel: (targets: ReadonlyArray<AgentChannelTarget>) => InboundChannelHandler;
-export { type AgentChannelTarget, type InboundChannelHandler, dispatchAgentChannel, verifyDiscord, verifyGithub, verifySlack };
+export { type AgentChannelTarget, type InboundChannelHandler, dispatchAgentChannel, isDuplicateInstanceError, verifyDiscord, verifyGithub, verifySlack };

package/dist/channels.mjs

@@ -1,181 +1 @@
-import { LunoraError } from '@lunora/errors';
-
-const DEFAULT_TIMESTAMP_TOLERANCE = 300;
-const NON_HEX = /[^0-9a-f]/iu;
-const encoder = new TextEncoder();
-const utf8 = (value) => new Uint8Array(encoder.encode(value));
-const hexToBytes = (hex) => {
-  if (hex.length % 2 !== 0 || NON_HEX.test(hex)) {
-    throw new LunoraError("BAD_REQUEST", "@lunora/agent: malformed hex signature");
-  }
-  const bytes = new Uint8Array(hex.length / 2);
-  for (let index = 0; index < bytes.length; index += 1) {
-    bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
-  }
-  return bytes;
-};
-const verifyHmacSha256 = async (secret, message, signatureHex) => {
-  try {
-    const key = await crypto.subtle.importKey("raw", utf8(secret), { hash: "SHA-256", name: "HMAC" }, false, ["verify"]);
-    return await crypto.subtle.verify("HMAC", key, hexToBytes(signatureHex), utf8(message));
-  } catch {
-    return false;
-  }
-};
-const isFreshTimestamp = (timestampSeconds, nowSeconds, tolerance) => Number.isFinite(timestampSeconds) && Math.abs(nowSeconds - timestampSeconds) <= tolerance;
-const verifySlack = async (options) => {
-  const { body, now = Date.now() / 1e3, signature, signingSecret, timestamp, tolerance = DEFAULT_TIMESTAMP_TOLERANCE } = options;
-  if (!signature || !timestamp || !signature.startsWith("v0=")) {
-    return false;
-  }
-  if (!isFreshTimestamp(Number(timestamp), now, tolerance)) {
-    return false;
-  }
-  return verifyHmacSha256(signingSecret, `v0:${timestamp}:${body}`, signature.slice("v0=".length));
-};
-const verifyGithub = async (options) => {
-  const { body, secret, signature } = options;
-  if (!signature?.startsWith("sha256=")) {
-    return false;
-  }
-  return verifyHmacSha256(secret, body, signature.slice("sha256=".length));
-};
-const verifyDiscord = async (options) => {
-  const { body, publicKey, signature, timestamp } = options;
-  if (!signature || !timestamp) {
-    return false;
-  }
-  try {
-    const key = await crypto.subtle.importKey("raw", hexToBytes(publicKey), { name: "Ed25519" }, false, ["verify"]);
-    return await crypto.subtle.verify({ name: "Ed25519" }, key, hexToBytes(signature), utf8(timestamp + body));
-  } catch {
-    return false;
-  }
-};
-const detectChannel = (headers) => {
-  if (headers.has("x-slack-signature")) {
-    return "slack";
-  }
-  if (headers.has("x-hub-signature-256")) {
-    return "github";
-  }
-  if (headers.has("x-signature-ed25519")) {
-    return "discord";
-  }
-  return void 0;
-};
-const resolveSecret = (secret, env) => {
-  if (typeof secret === "function") {
-    return secret(env);
-  }
-  const value = env[secret];
-  return typeof value === "string" ? value : void 0;
-};
-const verifyChannel = async (channel, secret, headers, body) => {
-  switch (channel) {
-    case "discord": {
-      return verifyDiscord({
-        body,
-        publicKey: secret,
-        signature: headers.get("x-signature-ed25519") ?? void 0,
-        timestamp: headers.get("x-signature-timestamp") ?? void 0
-      });
-    }
-    case "github": {
-      return verifyGithub({ body, secret, signature: headers.get("x-hub-signature-256") ?? void 0 });
-    }
-    case "slack": {
-      return verifySlack({
-        body,
-        signature: headers.get("x-slack-signature") ?? void 0,
-        signingSecret: secret,
-        timestamp: headers.get("x-slack-request-timestamp") ?? void 0
-      });
-    }
-    default: {
-      return false;
-    }
-  }
-};
-const discordPongResponse = (channel, body) => {
-  if (channel !== "discord") {
-    return void 0;
-  }
-  try {
-    if (JSON.parse(body).type === 1) {
-      return Response.json({ type: 1 });
-    }
-  } catch {
-  }
-  return void 0;
-};
-const UNSAFE_INSTANCE_ID = /[^\w-]/gu;
-const DUPLICATE_INSTANCE = /already[\s-]?exists/iu;
-const ack = () => new Response(void 0, { status: 200 });
-const isDuplicateInstanceError = (error) => DUPLICATE_INSTANCE.test(error instanceof Error ? error.message : String(error));
-const deliveryId = (channel, headers, body) => {
-  if (channel === "github") {
-    return headers.get("x-github-delivery") ?? void 0;
-  }
-  try {
-    const parsed = JSON.parse(body);
-    const raw = channel === "slack" ? parsed.event_id : parsed.id;
-    return typeof raw === "string" ? raw : void 0;
-  } catch {
-    return void 0;
-  }
-};
-const startChannelRun = async (workflow, run, channel, id) => {
-  const sanitizedId = id === void 0 ? "" : id.replaceAll(UNSAFE_INSTANCE_ID, "");
-  if (sanitizedId === "") {
-    await workflow.create({ params: run });
-    return ack();
-  }
-  try {
-    await workflow.create({ id: `${channel}-${sanitizedId}`.slice(0, 60), params: run });
-  } catch (error) {
-    if (isDuplicateInstanceError(error)) {
-      return ack();
-    }
-    throw error;
-  }
-  return ack();
-};
-const dispatchAgentChannel = (targets) => async (request, env) => {
-  const body = await request.text();
-  const channel = detectChannel(request.headers);
-  if (channel === void 0) {
-    return new Response("Unrecognized webhook", { status: 400 });
-  }
-  const eligible = targets.map((target) => {
-    return { config: target.agent.onInbound, target };
-  }).filter((entry) => entry.config?.channel === channel);
-  const event = { channel, headers: request.headers, json: () => JSON.parse(body), rawBody: body };
-  let verifiedAny = false;
-  for (const { config, target } of eligible) {
-    const secret = resolveSecret(config.secret, env);
-    if (secret === void 0 || !await verifyChannel(channel, secret, request.headers, body)) {
-      continue;
-    }
-    verifiedAny = true;
-    const pong = discordPongResponse(channel, body);
-    if (pong) {
-      return pong;
-    }
-    const run = await config.map(event);
-    if (!run) {
-      continue;
-    }
-    const workflow = env[target.binding];
-    if (!workflow || typeof workflow.create !== "function") {
-      throw new LunoraError(
-        "INTERNAL",
-        `@lunora/agent: no Workflow binding "${target.binding}" on env for an inbound-channel agent — run codegen/dev so wrangler.jsonc declares it`
-      );
-    }
-    return await startChannelRun(workflow, run, channel, deliveryId(channel, request.headers, body));
-  }
-  return verifiedAny ? new Response(void 0, { status: 204 }) : new Response("Invalid signature", { status: 401 });
-};
-
-export { dispatchAgentChannel, verifyDiscord, verifyGithub, verifySlack };
+import{LunoraError as w}from"@lunora/errors";const m=300,v=/[^0-9a-f]/iu,x=new TextEncoder,d=e=>new Uint8Array(x.encode(e)),g=e=>{if(e.length%2!==0||v.test(e))throw new w("BAD_REQUEST","@lunora/agent: malformed hex signature");const t=new Uint8Array(e.length/2);for(let r=0;r<t.length;r+=1)t[r]=Number.parseInt(e.slice(r*2,r*2+2),16);return t},b=async(e,t,r)=>{try{const s=await crypto.subtle.importKey("raw",d(e),{hash:"SHA-256",name:"HMAC"},!1,["verify"]);return await crypto.subtle.verify("HMAC",s,g(r),d(t))}catch{return!1}},k=(e,t,r)=>Number.isFinite(e)&&Math.abs(t-e)<=r,A=async e=>{const{body:t,now:r=Date.now()/1e3,signature:s,signingSecret:n,timestamp:a,tolerance:o=m}=e;return!s||!a||!s.startsWith("v0=")||!k(Number(a),r,o)?!1:b(n,`v0:${a}:${t}`,s.slice(3))},E=async e=>{const{body:t,secret:r,signature:s}=e;return s?.startsWith("sha256=")?b(r,t,s.slice(7)):!1},S=async e=>{const{body:t,publicKey:r,signature:s,timestamp:n}=e;if(!s||!n)return!1;try{const a=await crypto.subtle.importKey("raw",g(r),{name:"Ed25519"},!1,["verify"]);return await crypto.subtle.verify({name:"Ed25519"},a,g(s),d(n+t))}catch{return!1}},N=e=>{if(e.has("x-slack-signature"))return"slack";if(e.has("x-hub-signature-256"))return"github";if(e.has("x-signature-ed25519"))return"discord"},R=(e,t)=>{if(typeof e=="function")return e(t);const r=t[e];return typeof r=="string"?r:void 0},I=async(e,t,r,s)=>{switch(e){case"discord":return S({body:s,publicKey:t,signature:r.get("x-signature-ed25519")??void 0,timestamp:r.get("x-signature-timestamp")??void 0});case"github":return E({body:s,secret:t,signature:r.get("x-hub-signature-256")??void 0});case"slack":return A({body:s,signature:r.get("x-slack-signature")??void 0,signingSecret:t,timestamp:r.get("x-slack-request-timestamp")??void 0});default:return!1}},D=(e,t)=>{if(e==="discord")try{if(JSON.parse(t).type===1)return Response.json({type:1})}catch{}},K=/[^\w-]/gu,U=/already[\s-]?exists/iu,u=()=>new Response(void 0,{status:200}),$=e=>U.test(e instanceof Error?e.message:String(e)),C=(e,t,r)=>{if(e==="github")return t.get("x-github-delivery")??void 0;try{const s=JSON.parse(r),n=e==="slack"?s.event_id:s.id;return typeof n=="string"?n:void 0}catch{return}},H=async(e,t,r,s)=>{const n=s===void 0?"":s.replaceAll(K,"");if(n==="")return await e.create({params:t}),u();try{await e.create({id:`${r}-${n}`.slice(0,60),params:t})}catch(a){if($(a))return u();throw a}return u()},j=e=>async(t,r)=>{const s=await t.text(),n=N(t.headers);if(n===void 0)return new Response("Unrecognized webhook",{status:400});const a=e.map(i=>({config:i.agent.onInbound,target:i})).filter(i=>i.config?.channel===n),o={channel:n,headers:t.headers,json:()=>JSON.parse(s),rawBody:s};let f=!1;for(const{config:i,target:l}of a){const y=R(i.secret,r);if(y===void 0||!await I(n,y,t.headers,s))continue;f=!0;const h=D(n,s);if(h)return h;const p=await i.map(o);if(!p)continue;const c=r[l.binding];if(!c||typeof c.create!="function")throw new w("INTERNAL",`@lunora/agent: no Workflow binding "${l.binding}" on env for an inbound-channel agent — run codegen/dev so wrangler.jsonc declares it`);return await H(c,p,n,C(n,t.headers,s))}return f?new Response(void 0,{status:204}):new Response("Invalid signature",{status:401})};export{j as dispatchAgentChannel,$ as isDuplicateInstanceError,S as verifyDiscord,E as verifyGithub,A as verifySlack};

package/dist/component.d.mts

@@ -1,71 +1,73 @@
 import { SchemaExtension } from '@lunora/server';
 /**
-* Loose structural view of a registered Lunora function — wide enough for any
-* concrete `RegisteredMutation`/`RegisteredQuery` (whose precise validator-map
-* generics make them invariant), narrow enough for re-export, dispatch, and
-* tests. Codegen registers the runtime value; it never needs the generics.
-*/
+ * Loose structural view of a registered Lunora function — wide enough for any
+ * concrete `RegisteredMutation`/`RegisteredQuery` (whose precise validator-map
+ * generics make them invariant), narrow enough for re-export, dispatch, and
+ * tests. Codegen registers the runtime value; it never needs the generics.
+ */
 interface AgentRegisteredFunction {
   readonly args: unknown;
   readonly handler: (context: unknown, args: never) => unknown;
   readonly kind: "mutation" | "query";
   readonly visibility?: "internal" | "public";
 }
-/** Stamp a registered function internal — server-side callable only. */
-
 /**
-* The per-owner dedup key for an entity name: trim, collapse internal
-* whitespace, lowercase. Deterministic (no locale) so a workflow replay or
-* retry writes the exact same key — the graph upsert stays idempotent.
-*/
+ * The per-owner dedup key for an entity name: trim, collapse internal
+ * whitespace, lowercase. Deterministic (no locale) so a workflow replay or
+ * retry writes the exact same key — the graph upsert stays idempotent.
+ * @experimental
+ */
 declare const normalizeEntityName: (name: string) => string;
-/** The two internal graph-memory functions the durable loop dispatches to. */
-
 /**
-* Loose structural view of the registered sandbox action — wide enough for the
-* concrete `RegisteredAction`, narrow enough for re-export + dispatch. Codegen
-* registers the runtime value; it never needs the precise generics.
-*/
+ * Loose structural view of the registered sandbox action — wide enough for the
+ * concrete `RegisteredAction`, narrow enough for re-export + dispatch. Codegen
+ * registers the runtime value; it never needs the precise generics.
+ * @experimental
+ */
 interface SandboxRegisteredFunction {
   readonly args: unknown;
   readonly handler: (context: unknown, args: never) => unknown;
   readonly kind: "action";
   readonly visibility?: "internal" | "public";
 }
+/**
+ * `SandboxComponent` is part of the experimental `@lunora/agent` API and may change without a major version bump.
+ * @experimental
+ */
 interface SandboxComponent {
   invoke: SandboxRegisteredFunction;
 }
 /**
-* Resolve a model-supplied `path` to an absolute R2 key UNDER `root`, rejecting
-* any `..` that would escape the sandbox root. Every returned key is guaranteed
-* to start with the normalized `root`, so the model can never read or write
-* outside its own prefix — the fs sandbox's core isolation guarantee.
-*/
-/**
-* Build the sandbox runtime component: the single internal action the
-* batteries-included `browserTool`/`containerTool` dispatch to. Codegen
-* auto-registers it at `sandbox:invoke` whenever `lunora/` imports a sandbox
-* tool. It runs as an **action** because that is the only ctx codegen attaches
-* `ctx.browser` to (and `ctx.containers` rides every ctx once a container is
-* declared) — the durable tool step itself has neither.
-*/
+ * Build the sandbox runtime component: the single internal action the
+ * batteries-included `browserTool`/`containerTool` dispatch to. Codegen
+ * auto-registers it at `sandbox:invoke` whenever `lunora/` imports a sandbox
+ * tool. It runs as an **action** because that is the only ctx codegen attaches
+ * `ctx.browser` to (and `ctx.containers` rides every ctx once a container is
+ * declared) — the durable tool step itself has neither.
+ * @experimental
+ */
 declare const sandboxComponent: () => SandboxComponent;
 /**
-* The agent thread tables, shipped as a schema extension so an app merges
-* them with one call and they can never collide with app tables:
-*
-* ```ts
-* // lunora/schema.ts
-* export default defineSchema({ ... }).extend(agentExtension);
-* ```
-*
-* Message ordering follows the Convex-agent model: `seq` is the monotonic
-* per-thread position (allocated from the thread's `messageCount` counter, so
-* allocation is O(1) inside the serialized mutation), and `messageKey` is the
-* deterministic idempotency key — a workflow replay that re-persists the same
-* message is a no-op instead of a duplicate.
-*/
+ * The agent thread tables, shipped as a schema extension so an app merges
+ * them with one call and they can never collide with app tables:
+ *
+ * ```ts
+ * // lunora/schema.ts
+ * export default defineSchema({ ... }).extend(agentExtension);
+ * ```
+ *
+ * Message ordering follows the Convex-agent model: `seq` is the monotonic
+ * per-thread position (allocated from the thread's `messageCount` counter, so
+ * allocation is O(1) inside the serialized mutation), and `messageKey` is the
+ * deterministic idempotency key — a workflow replay that re-persists the same
+ * message is a no-op instead of a duplicate.
+ * @experimental
+ */
 declare const agentExtension: SchemaExtension;
+/**
+ * `AgentComponent` is part of the experimental `@lunora/agent` API and may change without a major version bump.
+ * @experimental
+ */
 interface AgentComponent {
   extension: SchemaExtension;
   functions: {
@@ -85,17 +87,18 @@ interface AgentComponent {
   };
 }
 /**
-* Build the agent runtime component: the thread schema extension plus the
-* functions the durable loop dispatches to (and the client subscribes to).
-* Codegen auto-registers them under the `agents:*` namespace whenever
-* `lunora/agents.ts` declares an agent — the loop's dispatch paths assume
-* that namespace, and apps never re-export these by hand.
-*
-* Most mutations are **internal** (only the workflow's admin-authenticated
-* dispatch may call them); the queries are public so a client can subscribe
-* to `agents:agentMessages` for a live thread view. Two mutations are public:
-* `agentResolveApproval` (a client resolves a HITL approval) and `agentRun`
-* (an HTTP client starts a durable run) — both owner-gated.
-*/
+ * Build the agent runtime component: the thread schema extension plus the
+ * functions the durable loop dispatches to (and the client subscribes to).
+ * Codegen auto-registers them under the `agents:*` namespace whenever
+ * `lunora/agents.ts` declares an agent — the loop's dispatch paths assume
+ * that namespace, and apps never re-export these by hand.
+ *
+ * Most mutations are **internal** (only the workflow's admin-authenticated
+ * dispatch may call them); the queries are public so a client can subscribe
+ * to `agents:agentMessages` for a live thread view. Two mutations are public:
+ * `agentResolveApproval` (a client resolves a HITL approval) and `agentRun`
+ * (an HTTP client starts a durable run) — both owner-gated.
+ * @experimental
+ */
 declare const agentComponent: () => AgentComponent;
 export { AgentComponent, type SandboxComponent, type SandboxRegisteredFunction, agentComponent, agentExtension, normalizeEntityName, sandboxComponent };