@lunora/agent 0.0.0 → 1.0.0-alpha.2

package/dist/component.d.ts

@@ -0,0 +1,115 @@
+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.
+*/
+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.
+* @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.
+* @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.
+* @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.
+* @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: {
+    agentAppendMessage: AgentRegisteredFunction;
+    agentEnsureThread: AgentRegisteredFunction;
+    agentEpisodeRecall: AgentRegisteredFunction;
+    agentEpisodeUpsert: AgentRegisteredFunction;
+    agentGraphTraverse: AgentRegisteredFunction;
+    agentGraphUpsert: AgentRegisteredFunction;
+    agentMessages: AgentRegisteredFunction;
+    agentPatchThread: AgentRegisteredFunction;
+    agentResolveApproval: AgentRegisteredFunction;
+    agentRun: AgentRegisteredFunction;
+    agentSetState: AgentRegisteredFunction;
+    agentState: AgentRegisteredFunction;
+    agentThread: AgentRegisteredFunction;
+  };
+}
+/**
+* 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

@@ -0,0 +1,407 @@
+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';
+export { sandboxComponent } from './packem_shared/sandboxComponent-DR3pTwBL.mjs';
+
+const EPISODES_TABLE = "agent_episodes";
+const DEFAULT_EPISODE_RECALL = 5;
+const MAX_EPISODE_RECALL = 20;
+const MAX_EPISODE_SUMMARY_CHARS = 500;
+const MAX_EPISODE_RETENTION = 200;
+const WHITESPACE_RUN = /\s+/gu;
+const clampRecall = (value) => {
+  if (value === void 0 || !Number.isFinite(value)) {
+    return DEFAULT_EPISODE_RECALL;
+  }
+  return Math.min(MAX_EPISODE_RECALL, Math.max(1, Math.trunc(value)));
+};
+const episodeTables = {
+  /**
+   * One episode per completed run — a short natural-language summary of the
+   * exchange, time-ordered for recency recall. `messageKey` (the extract
+   * step's instance-scoped key) is the idempotency key so a workflow replay
+   * never double-records the same run.
+   */
+  episodes: defineTable({
+    createdAt: v.number(),
+    messageKey: v.string(),
+    owner: v.string(),
+    /** A one/two-sentence summary of the run, injected as a memory-log line. */
+    summary: v.string(),
+    /** The thread the episode came from (provenance; not used for recall scope). */
+    threadKey: v.optional(v.string())
+  }).index("byOwnerCreatedAt", ["owner", "createdAt"]).index("byOwnerMessageKey", ["owner", "messageKey"], { unique: true }).public()
+};
+const { mutation: mutation$1, query: query$1 } = initLunora.dataModel().create();
+const episodicComponent = () => {
+  const agentEpisodeUpsert = mutation$1.input({
+    createdAt: v.optional(v.number()),
+    messageKey: v.string(),
+    owner: v.string(),
+    summary: v.string(),
+    threadKey: v.optional(v.string())
+  }).mutation(async ({ args, ctx: context }) => {
+    const summary = args.summary.replaceAll(WHITESPACE_RUN, " ").trim().slice(0, MAX_EPISODE_SUMMARY_CHARS);
+    if (summary.length === 0) {
+      return { recorded: false };
+    }
+    const existing = await context.db.query(EPISODES_TABLE).withIndex("byOwnerMessageKey", (q) => q.eq("owner", args.owner).eq("messageKey", args.messageKey)).first();
+    if (existing) {
+      return { recorded: false };
+    }
+    await context.db.insert(EPISODES_TABLE, {
+      createdAt: args.createdAt ?? Date.now(),
+      messageKey: args.messageKey,
+      owner: args.owner,
+      summary,
+      ...args.threadKey === void 0 ? {} : { threadKey: args.threadKey }
+    });
+    const overflow = await context.db.query(EPISODES_TABLE).withIndex("byOwnerCreatedAt", (q) => q.eq("owner", args.owner)).order("asc").take(MAX_EPISODE_RETENTION + 1);
+    for (const stale of overflow.slice(0, Math.max(0, overflow.length - MAX_EPISODE_RETENTION))) {
+      await context.db.delete(stale["_id"]);
+    }
+    return { recorded: true };
+  });
+  const agentEpisodeRecall = query$1.input({
+    limit: v.optional(v.number()),
+    owner: v.string()
+  }).query(async ({ args, ctx: context }) => {
+    const recent = await context.db.query(EPISODES_TABLE).withIndex("byOwnerCreatedAt", (q) => q.eq("owner", args.owner)).order("desc").take(clampRecall(args.limit));
+    if (recent.length === 0) {
+      return { context: "" };
+    }
+    return {
+      context: recent.toReversed().map((row) => `- ${row["summary"]}`).join("\n")
+    };
+  });
+  return {
+    agentEpisodeRecall: asInternal(agentEpisodeRecall),
+    agentEpisodeUpsert: asInternal(agentEpisodeUpsert)
+  };
+};
+
+const THREADS_BARE_TABLE = "threads";
+const MESSAGES_BARE_TABLE = "messages";
+const THREADS_TABLE = `${AGENT_EXTENSION_KEY}_${THREADS_BARE_TABLE}`;
+const MESSAGES_TABLE = `${AGENT_EXTENSION_KEY}_${MESSAGES_BARE_TABLE}`;
+const agentExtension = defineSchemaExtension(AGENT_EXTENSION_KEY, {
+  tables: {
+    [MESSAGES_BARE_TABLE]: defineTable({
+      content: v.string(),
+      createdAt: v.number(),
+      messageKey: v.string(),
+      role: v.union(v.literal("user"), v.literal("assistant"), v.literal("tool"), v.literal("system")),
+      seq: v.number(),
+      /**
+       * Human-in-the-loop approval marker: `"awaiting_approval"` on the
+       * placeholder written while a run pauses on a gated tool, then
+       * `"approved"`/`"rejected"` on the tool result once resolved. Optional
+       * so ordinary messages (and pre-existing rows) are unaffected.
+       */
+      status: v.optional(v.union(v.literal("awaiting_approval"), v.literal("approved"), v.literal("rejected"))),
+      stepName: v.optional(v.string()),
+      threadKey: v.string(),
+      toolCallId: v.optional(v.string()),
+      toolCalls: v.optional(v.array(v.object({ id: v.string(), input: v.any(), name: v.string() }))),
+      toolName: v.optional(v.string())
+    }).index("byThread", ["threadKey", "seq"]).index("byMessageKey", ["threadKey", "messageKey"], { unique: true }).public(),
+    [THREADS_BARE_TABLE]: defineTable({
+      agent: v.string(),
+      createdAt: v.number(),
+      error: v.optional(v.string()),
+      /**
+       * The workflow instance id of the run that currently owns this
+       * thread. The concurrency guard compares it to a starting run's own
+       * instance id — a match is a replay (allow), a mismatch while
+       * `status === "running"` is a genuine second run (apply
+       * `onConcurrentRun`). Also the target for `cancel`/`replace`. Optional
+       * so pre-existing threads (written before this column) are unaffected.
+       */
+      instanceId: v.optional(v.string()),
+      key: v.string(),
+      // Next message seq — incremented on every append (see above).
+      messageCount: v.number(),
+      /**
+       * Verified identity of the thread owner (pass `ctx.auth.userId`
+       * when starting a run). When set, the public queries only answer
+       * for a caller with that identity; when absent the thread is
+       * readable by anyone who knows its key (single-tenant/anonymous
+       * apps). First writer wins — a later run may not change it.
+       */
+      owner: v.optional(v.string()),
+      /**
+       * The thread's synced agent state — a JSON object written by the
+       * internal `agentSetState` mutation (absolute REPLACE) and read by the
+       * public `agentState` query (`ctx.getState` / `useAgentState`). Seeded
+       * from `defineAgent({ initialState })` on thread creation. Optional so
+       * agent-free apps and pre-existing threads (written before this column)
+       * are unaffected.
+       */
+      state: v.optional(v.any()),
+      status: v.union(v.literal("idle"), v.literal("running"), v.literal("error"), v.literal("cancelled"), v.literal("awaiting_input")),
+      title: v.optional(v.string()),
+      updatedAt: v.number(),
+      /**
+       * Cumulative token usage for the latest run on this thread, patched
+       * at run end. Optional so agent-free apps and pre-existing threads
+       * (written before this column existed) are unaffected.
+       */
+      usage: v.optional(v.object({ inputTokens: v.optional(v.number()), outputTokens: v.optional(v.number()), totalTokens: v.optional(v.number()) }))
+    }).index("byKey", ["key"], { unique: true }).index("byAgent", ["agent"]).index("byInstance", ["instanceId"]).public(),
+    // The owner-scoped graph-memory tables (`agent_entities`/`agent_edges`)
+    // live in graph-component.ts alongside the functions that read/write
+    // them; spread in here so the app still merges one `agentExtension`.
+    ...graphTables,
+    // The owner-scoped episodic-memory table (`agent_episodes`) lives in
+    // episodic-component.ts alongside its functions; spread in here too.
+    ...episodeTables
+  }
+});
+const { mutation, query } = initLunora.dataModel().create();
+const agentComponent = () => {
+  const agentEnsureThread = mutation.input({
+    agent: v.string(),
+    // Seed the thread's synced state — set on the INSERT branch only
+    // (first writer wins, like owner/title), so a replay never re-seeds.
+    initialState: v.optional(v.any()),
+    instanceId: v.optional(v.string()),
+    key: v.string(),
+    onConcurrentRun: v.optional(v.union(v.literal("reject"), v.literal("queue"), v.literal("replace"))),
+    owner: v.optional(v.string()),
+    title: v.optional(v.string())
+  }).mutation(async ({ args, ctx: context }) => {
+    const now = Date.now();
+    const existing = await context.db.query(THREADS_TABLE).withIndex("byKey", (q) => q.eq("key", args.key)).first();
+    if (existing) {
+      if (existing["owner"] !== args.owner && args.owner !== void 0) {
+        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;
+      if (isConcurrentRun) {
+        const policy = args.onConcurrentRun ?? "reject";
+        if (policy !== "replace") {
+          throw new LunoraError(
+            "CONFLICT",
+            `@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 });
+        return { created: false, priorInstanceId, replaced: true };
+      }
+      await context.db.patch(existing["_id"], {
+        error: void 0,
+        status: "running",
+        updatedAt: now,
+        ...args.instanceId === void 0 ? {} : { instanceId: args.instanceId }
+      });
+      return { created: false };
+    }
+    await context.db.insert(THREADS_TABLE, {
+      agent: args.agent,
+      createdAt: now,
+      key: args.key,
+      messageCount: 0,
+      status: "running",
+      updatedAt: now,
+      ...definedColumns({ instanceId: args.instanceId, owner: args.owner, state: args.initialState, title: args.title })
+    });
+    return { created: true };
+  });
+  const agentAppendMessage = mutation.input({
+    content: v.string(),
+    messageKey: v.string(),
+    role: v.union(v.literal("user"), v.literal("assistant"), v.literal("tool"), v.literal("system")),
+    status: v.optional(v.union(v.literal("awaiting_approval"), v.literal("approved"), v.literal("rejected"))),
+    stepName: v.optional(v.string()),
+    threadKey: v.string(),
+    toolCallId: v.optional(v.string()),
+    toolCalls: v.optional(v.array(v.object({ id: v.string(), input: v.any(), name: v.string() }))),
+    toolName: v.optional(v.string())
+  }).mutation(async ({ args, ctx: context }) => {
+    const existing = await context.db.query(MESSAGES_TABLE).withIndex("byMessageKey", (q) => q.eq("threadKey", args.threadKey).eq("messageKey", args.messageKey)).first();
+    if (existing) {
+      return { seq: existing["seq"] };
+    }
+    const thread = await context.db.query(THREADS_TABLE).withIndex("byKey", (q) => q.eq("key", args.threadKey)).first();
+    if (!thread) {
+      throw new Error(`@lunora/agent: cannot append to unknown thread "${args.threadKey}" — run agentEnsureThread first`);
+    }
+    const seq = thread["messageCount"];
+    const now = Date.now();
+    await context.db.insert(MESSAGES_TABLE, {
+      content: args.content,
+      createdAt: now,
+      messageKey: args.messageKey,
+      role: args.role,
+      seq,
+      threadKey: args.threadKey,
+      ...args.status === void 0 ? {} : { status: args.status },
+      ...args.stepName === void 0 ? {} : { stepName: args.stepName },
+      ...args.toolCallId === void 0 ? {} : { toolCallId: args.toolCallId },
+      ...args.toolCalls === void 0 ? {} : { toolCalls: args.toolCalls },
+      ...args.toolName === void 0 ? {} : { toolName: args.toolName }
+    });
+    await context.db.patch(thread["_id"], { messageCount: seq + 1, updatedAt: now });
+    return { seq };
+  });
+  const agentPatchThread = mutation.input({
+    error: v.optional(v.string()),
+    // Target by thread key (the loop) OR by workflow instance id (cancel,
+    // which only knows the instance it terminated). Exactly one is set.
+    instanceId: v.optional(v.string()),
+    key: v.optional(v.string()),
+    status: v.optional(v.union(v.literal("idle"), v.literal("running"), v.literal("error"), v.literal("cancelled"), v.literal("awaiting_input"))),
+    title: v.optional(v.string()),
+    usage: v.optional(v.object({ inputTokens: v.optional(v.number()), outputTokens: v.optional(v.number()), totalTokens: v.optional(v.number()) }))
+  }).mutation(async ({ args, ctx: context }) => {
+    const { instanceId, key } = args;
+    let thread;
+    if (key !== void 0) {
+      thread = await context.db.query(THREADS_TABLE).withIndex("byKey", (q) => q.eq("key", key)).first();
+    } else if (instanceId !== void 0) {
+      thread = await context.db.query(THREADS_TABLE).withIndex("byInstance", (q) => q.eq("instanceId", instanceId)).first();
+    }
+    if (!thread) {
+      return;
+    }
+    await context.db.patch(thread["_id"], {
+      updatedAt: Date.now(),
+      ...args.error === void 0 ? {} : { error: args.error },
+      ...args.status === void 0 ? {} : { status: args.status },
+      ...args.title === void 0 ? {} : { title: args.title },
+      // The loop patches a per-run cumulative total; setting it (rather
+      // than adding) keeps the write idempotent under workflow replay.
+      ...args.usage === void 0 ? {} : { usage: args.usage }
+    });
+  });
+  const agentSetState = mutation.input({
+    key: v.string(),
+    state: v.any()
+  }).mutation(async ({ args, ctx: context }) => {
+    const thread = await context.db.query(THREADS_TABLE).withIndex("byKey", (q) => q.eq("key", args.key)).first();
+    if (!thread) {
+      return;
+    }
+    await context.db.patch(thread["_id"], { state: args.state, updatedAt: Date.now() });
+  });
+  const readableThread = (thread, auth) => {
+    if (!thread) {
+      return void 0;
+    }
+    const { owner } = thread;
+    if (owner !== void 0 && owner !== (auth.userId ?? void 0)) {
+      return void 0;
+    }
+    return thread;
+  };
+  const agentThread = query.input({ key: v.string() }).query(async ({ args, ctx: context }) => {
+    const thread = await context.db.query(THREADS_TABLE).withIndex("byKey", (q) => q.eq("key", args.key)).first();
+    return readableThread(thread, context.auth);
+  });
+  const agentState = query.input({ key: v.string() }).query(async ({ args, ctx: context }) => {
+    const thread = await context.db.query(THREADS_TABLE).withIndex("byKey", (q) => q.eq("key", args.key)).first();
+    return readableThread(thread, context.auth)?.["state"];
+  });
+  const agentMessages = query.input({ key: v.string(), limit: v.optional(v.number()) }).query(async ({ args, ctx: context }) => {
+    const thread = await context.db.query(THREADS_TABLE).withIndex("byKey", (q) => q.eq("key", args.key)).first();
+    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));
+  });
+  const agentResolveApproval = mutation.input({
+    decision: v.union(v.literal("approve"), v.literal("reject")),
+    instanceId: v.string(),
+    note: v.optional(v.string()),
+    threadKey: v.string(),
+    toolCallId: v.string()
+  }).mutation(async ({ args, ctx: context }) => {
+    const thread = await context.db.query(THREADS_TABLE).withIndex("byKey", (q) => q.eq("key", args.threadKey)).first();
+    const readable = readableThread(thread, context.auth);
+    if (readable === void 0) {
+      throw new LunoraError("FORBIDDEN", `@lunora/agent: not allowed to resolve approvals on thread "${args.threadKey}"`);
+    }
+    const agentName = readable["agent"];
+    const { agents } = context;
+    const handle = agents?.[agentName];
+    if (typeof handle?.sendEvent !== "function") {
+      throw new LunoraError(
+        "INTERNAL",
+        `@lunora/agent: no ctx.agents["${agentName}"] producer to resolve the approval — run codegen/dev so the agent binding is wired`
+      );
+    }
+    await handle.sendEvent(args.instanceId, {
+      payload: { decision: args.decision, ...args.note === void 0 ? {} : { note: args.note } },
+      type: "agent-approval"
+    });
+    return { resolved: true };
+  });
+  const agentRun = mutation.input({
+    agent: v.string(),
+    input: v.string(),
+    threadKey: v.string(),
+    title: v.optional(v.string())
+  }).mutation(async ({ args, ctx: context }) => {
+    const { agents } = context;
+    const handle = agents?.[args.agent];
+    if (typeof handle?.run !== "function") {
+      throw new LunoraError(
+        "INTERNAL",
+        `@lunora/agent: no ctx.agents["${args.agent}"] producer to start a run — run codegen/dev so the agent binding is wired, and check the agent name`
+      );
+    }
+    if (handle.publicRun !== true) {
+      throw new LunoraError(
+        "FORBIDDEN",
+        `@lunora/agent: agent "${args.agent}" is not enabled for public runs — set defineAgent({ publicRun: true }) to allow an external client (e.g. the @lunora/mcp server) to start it`
+      );
+    }
+    const owner = context.auth.userId ?? void 0;
+    const inflight = await context.db.query(THREADS_TABLE).withIndex("byKey", (q) => q.eq("key", args.threadKey)).first();
+    if (inflight) {
+      const status = inflight["status"];
+      const inflightInstanceId = inflight["instanceId"];
+      const inflightOwner = inflight["owner"];
+      if ((status === "running" || status === "awaiting_input") && inflightInstanceId !== void 0 && (inflightOwner === void 0 || inflightOwner === owner)) {
+        return { id: inflightInstanceId, threadKey: args.threadKey };
+      }
+      if (inflightOwner !== owner && owner !== void 0) {
+        throw new LunoraError("FORBIDDEN", `@lunora/agent: thread "${args.threadKey}" belongs to another owner`);
+      }
+    }
+    const { id } = await handle.run({
+      input: args.input,
+      threadKey: args.threadKey,
+      ...owner === void 0 ? {} : { owner },
+      ...args.title === void 0 ? {} : { title: args.title }
+    });
+    return { id, threadKey: args.threadKey };
+  });
+  const graph = graphComponent();
+  const episodic = episodicComponent();
+  return {
+    extension: agentExtension,
+    functions: {
+      agentAppendMessage: asInternal(agentAppendMessage),
+      agentEnsureThread: asInternal(agentEnsureThread),
+      agentEpisodeRecall: episodic.agentEpisodeRecall,
+      agentEpisodeUpsert: episodic.agentEpisodeUpsert,
+      agentGraphTraverse: graph.agentGraphTraverse,
+      agentGraphUpsert: graph.agentGraphUpsert,
+      agentMessages,
+      agentPatchThread: asInternal(agentPatchThread),
+      agentResolveApproval,
+      agentRun,
+      agentSetState: asInternal(agentSetState),
+      agentState,
+      agentThread
+    }
+  };
+};
+
+export { agentComponent, agentExtension };

package/dist/inbound.d.mts

@@ -0,0 +1,34 @@
+import { A as AgentDefinition } from "./packem_shared/types.d-BhJFTvz_.mjs";
+import '@lunora/mail/inbound';
+import 'ai';
+/**
+* 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.
+  */
+  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.
+* @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.
+* @experimental
+*/
+declare const dispatchAgentEmail: (targets: ReadonlyArray<AgentEmailTarget>) => InboundAgentEmailHandler;
+export { type AgentEmailTarget, type InboundAgentEmailHandler, dispatchAgentEmail };

package/dist/inbound.d.ts

@@ -0,0 +1,34 @@
+import { A as AgentDefinition } from "./packem_shared/types.d-BhJFTvz_.js";
+import '@lunora/mail/inbound';
+import 'ai';
+/**
+* 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.
+  */
+  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.
+* @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.
+* @experimental
+*/
+declare const dispatchAgentEmail: (targets: ReadonlyArray<AgentEmailTarget>) => InboundAgentEmailHandler;
+export { type AgentEmailTarget, type InboundAgentEmailHandler, dispatchAgentEmail };

package/dist/inbound.mjs

@@ -0,0 +1,32 @@
+import { LunoraError } from '@lunora/errors';
+import { createInboundEmailHandler, parseInboundEmail } from '@lunora/mail/inbound';
+
+const dispatchAgentEmail = (targets) => {
+  const handler = createInboundEmailHandler({
+    dispatch: async (email, context) => {
+      for (const target of targets) {
+        const mapper = target.agent.onEmail;
+        if (!mapper) {
+          continue;
+        }
+        const run = await mapper(email);
+        if (run === null || run === void 0) {
+          continue;
+        }
+        const binding = context.env[target.binding];
+        if (!binding || typeof binding.create !== "function") {
+          throw new LunoraError(
+            "INTERNAL",
+            `@lunora/agent: no Workflow binding "${target.binding}" on env for an inbound agent — run codegen/dev so wrangler.jsonc declares it`
+          );
+        }
+        await binding.create({ params: run });
+        return;
+      }
+    },
+    parse: parseInboundEmail
+  });
+  return async (message, env, context) => handler(message, env, context);
+};
+
+export { dispatchAgentEmail };