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

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

@@ -178,4 +178,4 @@ const dispatchAgentChannel = (targets) => async (request, env) => {
   return verifiedAny ? new Response(void 0, { status: 204 }) : new Response("Invalid signature", { status: 401 });
 };
 
-export { dispatchAgentChannel, verifyDiscord, verifyGithub, verifySlack };
+export { dispatchAgentChannel, isDuplicateInstanceError, verifyDiscord, verifyGithub, 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 };

package/dist/component.d.ts

@@ -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 };

package/dist/component.mjs

@@ -1,8 +1,8 @@
 import { LunoraError } from '@lunora/errors';
 import { defineTable, initLunora, defineSchemaExtension } from '@lunora/server';
 import { v } from '@lunora/values';
-import { a as asInternal, A as AGENT_EXTENSION_KEY, g as graphTables, d as definedColumns, b as graphComponent } from './packem_shared/graph-component-aoUwO-f0.mjs';
-export { n as normalizeEntityName } from './packem_shared/graph-component-aoUwO-f0.mjs';
+import { a as asInternal, A as AGENT_EXTENSION_KEY, g as graphTables, d as definedColumns, b as graphComponent } from './packem_shared/graph-component-Bbaxxymp.mjs';
+export { n as normalizeEntityName } from './packem_shared/graph-component-Bbaxxymp.mjs';
 export { sandboxComponent } from './packem_shared/sandboxComponent-DR3pTwBL.mjs';
 
 const EPISODES_TABLE = "agent_episodes";
@@ -179,7 +179,7 @@ const agentComponent = () => {
         throw new Error(`@lunora/agent: thread "${args.key}" belongs to another owner`);
       }
       const priorInstanceId = existing["instanceId"];
-      const isConcurrentRun = (existing["status"] === "running" || existing["status"] === "awaiting_input") && priorInstanceId !== void 0 && args.instanceId !== void 0 && priorInstanceId !== args.instanceId;
+      const isConcurrentRun = (existing["status"] === "running" || existing["status"] === "awaiting_input") && priorInstanceId !== void 0 && (args.instanceId === void 0 || args.instanceId !== priorInstanceId);
       if (isConcurrentRun) {
         const policy = args.onConcurrentRun ?? "reject";
         if (policy !== "replace") {
@@ -188,7 +188,12 @@ const agentComponent = () => {
             `@lunora/agent: thread "${args.key}" already has a run in flight (instance "${priorInstanceId}") — onConcurrentRun="${policy}"`
           );
         }
-        await context.db.patch(existing["_id"], { error: void 0, instanceId: args.instanceId, status: "running", updatedAt: now });
+        await context.db.patch(existing["_id"], {
+          error: void 0,
+          status: "running",
+          updatedAt: now,
+          ...args.instanceId === void 0 ? {} : { instanceId: args.instanceId }
+        });
         return { created: false, priorInstanceId, replaced: true };
       }
       await context.db.patch(existing["_id"], {
@@ -310,9 +315,11 @@ const agentComponent = () => {
     if (readableThread(thread, context.auth) === void 0) {
       return [];
     }
-    const rows = await context.db.query(MESSAGES_TABLE).withIndex("byThread", (q) => q.eq("threadKey", args.key)).collect();
-    const ordered = rows.toSorted((a, b) => a["seq"] - b["seq"]);
-    return args.limit === void 0 ? ordered : ordered.slice(Math.max(0, ordered.length - args.limit));
+    if (args.limit !== void 0) {
+      const tail = await context.db.query(MESSAGES_TABLE).withIndex("byThread", (q) => q.eq("threadKey", args.key)).order("desc").take(args.limit);
+      return tail.toReversed();
+    }
+    return context.db.query(MESSAGES_TABLE).withIndex("byThread", (q) => q.eq("threadKey", args.key)).collect();
   });
   const agentResolveApproval = mutation.input({
     decision: v.union(v.literal("approve"), v.literal("reject")),
@@ -326,6 +333,9 @@ const agentComponent = () => {
     if (readable === void 0) {
       throw new LunoraError("FORBIDDEN", `@lunora/agent: not allowed to resolve approvals on thread "${args.threadKey}"`);
     }
+    if (readable["instanceId"] !== args.instanceId) {
+      throw new LunoraError("FORBIDDEN", `@lunora/agent: instance "${args.instanceId}" does not own thread "${args.threadKey}"`);
+    }
     const agentName = readable["agent"];
     const { agents } = context;
     const handle = agents?.[agentName];
@@ -336,8 +346,9 @@ const agentComponent = () => {
       );
     }
     await handle.sendEvent(args.instanceId, {
-      payload: { decision: args.decision, ...args.note === void 0 ? {} : { note: args.note } },
-      type: "agent-approval"
+      payload: { decision: args.decision, toolCallId: args.toolCallId, ...args.note === void 0 ? {} : { note: args.note } },
+      // Scoped per tool call — see the doc comment above.
+      type: `agent-approval:${args.toolCallId}`
     });
     return { resolved: true };
   });

package/dist/inbound.d.mts

@@ -1,29 +1,34 @@
-import { A as AgentDefinition } from "./packem_shared/types.d-BWG0uUtX.mjs";
+import { A as AgentDefinition } from "./packem_shared/types.d-boAM2Yi1.mjs";
 import '@lunora/mail/inbound';
 import 'ai';
-/** One agent wired into the inbound `email()` handler. */
+/**
+ * One agent wired into the inbound `email()` handler.
+ * @experimental
+ */
 interface AgentEmailTarget {
   /**
-  * The agent definition — only its `onEmail` mapper is read, deciding whether
-  * this agent claims the message and, if so, the run to start.
-  */
+   * The agent definition — only its `onEmail` mapper is read, deciding whether
+   * this agent claims the message and, if so, the run to start.
+   */
   agent: Pick<AgentDefinition, "onEmail">;
   /** The `AGENT_*` Workflow binding name (off `env`) that starts a run. */
   binding: string;
 }
 /**
-* The worker `email(message, env, ctx)` callback. Typed with `unknown`
-* parameters so it drops straight onto the generated `composed.email` slot
-* without a cast.
-*/
+ * The worker `email(message, env, ctx)` callback. Typed with `unknown`
+ * parameters so it drops straight onto the generated `composed.email` slot
+ * without a cast.
+ * @experimental
+ */
 type InboundAgentEmailHandler = (message: unknown, env: unknown, context: unknown) => Promise<void>;
 /**
-* Build the inbound `email()` handler for one or more `onEmail` agents. The
-* returned callback parses the message, then walks `targets` in order and starts
-* a durable run for the first agent whose `onEmail` mapper returns a run. If the
-* matched agent's Workflow binding is missing from `env` (run codegen/dev so
-* `wrangler.jsonc` declares it) the dispatch throws, and the inbound handler's
-* `onError` rejects (bounces) the message.
-*/
+ * Build the inbound `email()` handler for one or more `onEmail` agents. The
+ * returned callback parses the message, then walks `targets` in order and starts
+ * a durable run for the first agent whose `onEmail` mapper returns a run. If the
+ * matched agent's Workflow binding is missing from `env` (run codegen/dev so
+ * `wrangler.jsonc` declares it) the dispatch throws, and the inbound handler's
+ * `onError` rejects (bounces) the message.
+ * @experimental
+ */
 declare const dispatchAgentEmail: (targets: ReadonlyArray<AgentEmailTarget>) => InboundAgentEmailHandler;
 export { type AgentEmailTarget, type InboundAgentEmailHandler, dispatchAgentEmail };