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

package/dist/component.mjs

@@ -1,418 +1,2 @@
-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-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";
-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 || args.instanceId !== priorInstanceId);
-      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,
-          status: "running",
-          updatedAt: now,
-          ...args.instanceId === void 0 ? {} : { instanceId: args.instanceId }
-        });
-        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 [];
-    }
-    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")),
-    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}"`);
-    }
-    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];
-    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, 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 };
-  });
-  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 };
+import{LunoraError as g}from"@lunora/errors";import{defineTable as v,initLunora as D,defineSchemaExtension as j}from"@lunora/server";import{v as e}from"@lunora/values";import{a as f,A as k,c as P,d as F}from"./packem_shared/component-shared-IZozysYq.mjs";import{graphTables as G,graphComponent as H}from"./packem_shared/normalizeEntityName-Ce0X6Afj.mjs";import{normalizeEntityName as pe}from"./packem_shared/normalizeEntityName-Ce0X6Afj.mjs";import{sandboxComponent as we}from"./packem_shared/sandboxComponent-BtOkUYpY.mjs";const A="agent_episodes",X=5,Q=20,Y=500,x=200,z=/\s+/gu,V=u=>u===void 0||!Number.isFinite(u)?X:Math.min(Q,Math.max(1,Math.trunc(u))),W={episodes:v({createdAt:e.number(),messageKey:e.string(),owner:e.string(),summary:e.string(),threadKey:e.optional(e.string())}).index("byOwnerCreatedAt",["owner","createdAt"]).index("byOwnerMessageKey",["owner","messageKey"],{unique:!0}).public()},{mutation:J,query:Z}=D.dataModel().create(),ee=()=>{const u=J.input({createdAt:e.optional(e.number()),messageKey:e.string(),owner:e.string(),summary:e.string(),threadKey:e.optional(e.string())}).mutation(async({args:s,ctx:y})=>{const w=s.summary.replaceAll(z," ").trim().slice(0,Y);if(w.length===0)return{recorded:!1};if(await y.db.query(A).withIndex("byOwnerMessageKey",h=>h.eq("owner",s.owner).eq("messageKey",s.messageKey)).first())return{recorded:!1};await y.db.insert(A,{createdAt:s.createdAt??Date.now(),messageKey:s.messageKey,owner:s.owner,summary:w,...s.threadKey===void 0?{}:{threadKey:s.threadKey}});const m=await y.db.query(A).withIndex("byOwnerCreatedAt",h=>h.eq("owner",s.owner)).order("asc").take(x+1);for(const h of m.slice(0,Math.max(0,m.length-x)))await y.db.delete(h._id);return{recorded:!0}}),o=Z.input({limit:e.optional(e.number()),owner:e.string()}).query(async({args:s,ctx:y})=>{const w=await y.db.query(A).withIndex("byOwnerCreatedAt",I=>I.eq("owner",s.owner)).order("desc").take(V(s.limit));return w.length===0?{context:""}:{context:w.toReversed().map(I=>`- ${I.summary}`).join(`
+`)}});return{agentEpisodeRecall:f(o),agentEpisodeUpsert:f(u)}},S="threads",$="messages",M="run_queue",p=`${k}_${S}`,K=`${k}_${$}`,E=`${k}_${M}`,N=5,te=780*60*1e3,ne=j(k,{tables:{[$]:v({content:e.string(),createdAt:e.number(),messageKey:e.string(),role:e.union(e.literal("user"),e.literal("assistant"),e.literal("tool"),e.literal("system")),seq:e.number(),status:e.optional(e.union(e.literal("awaiting_approval"),e.literal("approved"),e.literal("rejected"))),stepName:e.optional(e.string()),threadKey:e.string(),toolCallId:e.optional(e.string()),toolCalls:e.optional(e.array(e.object({id:e.string(),input:e.any(),name:e.string()}))),toolName:e.optional(e.string())}).index("byThread",["threadKey","seq"]).index("byMessageKey",["threadKey","messageKey"],{unique:!0}).public(),[S]:v({agent:e.string(),createdAt:e.number(),error:e.optional(e.string()),instanceId:e.optional(e.string()),key:e.string(),messageCount:e.number(),owner:e.optional(e.string()),state:e.optional(e.any()),status:e.union(e.literal("idle"),e.literal("running"),e.literal("error"),e.literal("cancelled"),e.literal("awaiting_input")),title:e.optional(e.string()),updatedAt:e.number(),usage:e.optional(e.object({inputTokens:e.optional(e.number()),outputTokens:e.optional(e.number()),totalTokens:e.optional(e.number())}))}).index("byKey",["key"],{unique:!0}).index("byAgent",["agent"]).index("byInstance",["instanceId"]).public(),[M]:v({agent:e.string(),enqueuedAt:e.number(),instanceId:e.string(),position:e.number(),threadKey:e.string()}).index("byThread",["threadKey","position"]).index("byThreadInstance",["threadKey","instanceId"],{unique:!0}).public(),...G,...W}}),{mutation:b,query:T}=D.dataModel().create(),ie=async(u,o,s)=>{if(o.instanceId===void 0)throw new g("CONFLICT",`@lunora/agent: thread "${o.key}" already has a run in flight (instance "${o.priorInstanceId}") — cannot queue a dispatch with no instance id`);const{instanceId:y}=o,w=await u.query(E).withIndex("byThreadInstance",h=>h.eq("threadKey",o.key).eq("instanceId",y)).first();if(w)return{outcome:"queued",position:w.position};const I=await u.query(E).withIndex("byThread",h=>h.eq("threadKey",o.key)).collect();if(I.length>=N)throw new g("CONFLICT",`@lunora/agent: thread "${o.key}" run queue is full (depth ${String(N)}) — rejecting instance "${y}"`);const m=(I.at(-1)?.position??-1)+1;return await u.insert(E,{agent:o.agent,enqueuedAt:s,instanceId:y,position:m,threadKey:o.key}),{outcome:"queued",position:m}},ae=async(u,o,s)=>{if(o.policy==="queue")return ie(u,{agent:o.agent,instanceId:o.instanceId,key:o.key,priorInstanceId:o.priorInstanceId},s);if(o.policy!=="replace")throw new g("CONFLICT",`@lunora/agent: thread "${o.key}" already has a run in flight (instance "${o.priorInstanceId}") — onConcurrentRun="${o.policy}"`);return await u.patch(o.existingId,{error:void 0,status:"running",updatedAt:s,...o.instanceId===void 0?{}:{instanceId:o.instanceId}}),{outcome:"replaced",priorInstanceId:o.priorInstanceId}},le=()=>{const u=b.input({agent:e.string(),initialState:e.optional(e.any()),instanceId:e.optional(e.string()),key:e.string(),onConcurrentRun:e.optional(e.union(e.literal("reject"),e.literal("queue"),e.literal("replace"))),owner:e.optional(e.string()),title:e.optional(e.string())}).mutation(async({args:t,ctx:n})=>{const a=Date.now(),i=await n.db.query(p).withIndex("byKey",r=>r.eq("key",t.key)).first();if(i){if(i.owner!==t.owner&&t.owner!==void 0)throw new Error(`@lunora/agent: thread "${t.key}" belongs to another owner`);const r=i.instanceId,d=typeof i.updatedAt=="number"?i.updatedAt:0,c=i.status==="awaiting_input"?P:te;return!(a-d>c)&&(i.status==="running"||i.status==="awaiting_input")&&r!==void 0&&(t.instanceId===void 0||t.instanceId!==r)?ae(n.db,{agent:t.agent,existingId:i._id,instanceId:t.instanceId,key:t.key,policy:t.onConcurrentRun??"reject",priorInstanceId:r},a):(await n.db.patch(i._id,{error:void 0,status:"running",updatedAt:a,...t.instanceId===void 0?{}:{instanceId:t.instanceId}}),{outcome:"continued"})}return await n.db.insert(p,{agent:t.agent,createdAt:a,key:t.key,messageCount:0,status:"running",updatedAt:a,...F({instanceId:t.instanceId,owner:t.owner,state:t.initialState,title:t.title})}),{outcome:"created"}}),o=b.input({content:e.string(),messageKey:e.string(),role:e.union(e.literal("user"),e.literal("assistant"),e.literal("tool"),e.literal("system")),status:e.optional(e.union(e.literal("awaiting_approval"),e.literal("approved"),e.literal("rejected"))),stepName:e.optional(e.string()),threadKey:e.string(),toolCallId:e.optional(e.string()),toolCalls:e.optional(e.array(e.object({id:e.string(),input:e.any(),name:e.string()}))),toolName:e.optional(e.string())}).mutation(async({args:t,ctx:n})=>{const a=await n.db.query(K).withIndex("byMessageKey",c=>c.eq("threadKey",t.threadKey).eq("messageKey",t.messageKey)).first();if(a)return{seq:a.seq};const i=await n.db.query(p).withIndex("byKey",c=>c.eq("key",t.threadKey)).first();if(!i)throw new Error(`@lunora/agent: cannot append to unknown thread "${t.threadKey}" — run agentEnsureThread first`);const r=i.messageCount,d=Date.now();return await n.db.insert(K,{content:t.content,createdAt:d,messageKey:t.messageKey,role:t.role,seq:r,threadKey:t.threadKey,...t.status===void 0?{}:{status:t.status},...t.stepName===void 0?{}:{stepName:t.stepName},...t.toolCallId===void 0?{}:{toolCallId:t.toolCallId},...t.toolCalls===void 0?{}:{toolCalls:t.toolCalls},...t.toolName===void 0?{}:{toolName:t.toolName}}),await n.db.patch(i._id,{messageCount:r+1,updatedAt:d}),{seq:r}}),s=b.input({messageKey:e.string(),threadKey:e.string()}).mutation(async({args:t,ctx:n})=>{const a=await n.db.query(K).withIndex("byMessageKey",i=>i.eq("threadKey",t.threadKey).eq("messageKey",t.messageKey)).first();a&&await n.db.delete(a._id)}),y=b.input({error:e.optional(e.string()),instanceId:e.optional(e.string()),key:e.optional(e.string()),status:e.optional(e.union(e.literal("idle"),e.literal("running"),e.literal("error"),e.literal("cancelled"),e.literal("awaiting_input"))),title:e.optional(e.string()),usage:e.optional(e.object({inputTokens:e.optional(e.number()),outputTokens:e.optional(e.number()),totalTokens:e.optional(e.number())}))}).mutation(async({args:t,ctx:n})=>{const{instanceId:a,key:i}=t;let r;i!==void 0?r=await n.db.query(p).withIndex("byKey",d=>d.eq("key",i)).first():a!==void 0&&(r=await n.db.query(p).withIndex("byInstance",d=>d.eq("instanceId",a)).first()),r&&await n.db.patch(r._id,{updatedAt:Date.now(),...t.error===void 0?{}:{error:t.error},...t.status===void 0?{}:{status:t.status},...t.title===void 0?{}:{title:t.title},...t.usage===void 0?{}:{usage:t.usage}})}),w=b.input({error:e.optional(e.string()),instanceId:e.string(),key:e.string(),status:e.union(e.literal("idle"),e.literal("error"),e.literal("cancelled")),usage:e.optional(e.object({inputTokens:e.optional(e.number()),outputTokens:e.optional(e.number()),totalTokens:e.optional(e.number())}))}).mutation(async({args:t,ctx:n})=>{const a=Date.now(),i=await n.db.query(p).withIndex("byKey",l=>l.eq("key",t.key)).first();if(i?.instanceId!==t.instanceId){const l=await n.db.query(E).withIndex("byThreadInstance",q=>q.eq("threadKey",t.key).eq("instanceId",t.instanceId)).first();return l&&await n.db.delete(l._id),{}}const d=(await n.db.query(E).withIndex("byThread",l=>l.eq("threadKey",t.key)).collect())[0];if(!d)return await n.db.patch(i._id,{status:t.status,updatedAt:a,...t.error===void 0?{}:{error:t.error},...t.usage===void 0?{}:{usage:t.usage}}),{};const c=d.instanceId;return await n.db.delete(d._id),await n.db.patch(i._id,{instanceId:c,status:"running",updatedAt:a,...t.error===void 0?{}:{error:t.error},...t.usage===void 0?{}:{usage:t.usage}}),{dequeued:c}}),I=b.input({key:e.string(),state:e.any()}).mutation(async({args:t,ctx:n})=>{const a=await n.db.query(p).withIndex("byKey",i=>i.eq("key",t.key)).first();a&&await n.db.patch(a._id,{state:t.state,updatedAt:Date.now()})}),m=(t,n)=>{if(!t)return;const{owner:a}=t;if(!(a!==void 0&&a!==(n.userId??void 0)))return t},h=T.input({key:e.string()}).query(async({args:t,ctx:n})=>{const a=await n.db.query(p).withIndex("byKey",i=>i.eq("key",t.key)).first();return m(a,n.auth)}),O=T.input({key:e.string()}).query(async({args:t,ctx:n})=>{const a=await n.db.query(p).withIndex("byKey",i=>i.eq("key",t.key)).first();return m(a,n.auth)?.state}),L=T.input({key:e.string(),limit:e.optional(e.number())}).query(async({args:t,ctx:n})=>{const a=await n.db.query(p).withIndex("byKey",i=>i.eq("key",t.key)).first();return m(a,n.auth)===void 0?[]:t.limit!==void 0?(await n.db.query(K).withIndex("byThread",r=>r.eq("threadKey",t.key)).order("desc").take(t.limit)).toReversed():n.db.query(K).withIndex("byThread",i=>i.eq("threadKey",t.key)).collect()}),U=b.input({decision:e.union(e.literal("approve"),e.literal("reject")),instanceId:e.string(),note:e.optional(e.string()),threadKey:e.string(),toolCallId:e.string()}).mutation(async({args:t,ctx:n})=>{const a=await n.db.query(p).withIndex("byKey",l=>l.eq("key",t.threadKey)).first(),i=m(a,n.auth);if(i===void 0)throw new g("FORBIDDEN",`@lunora/agent: not allowed to resolve approvals on thread "${t.threadKey}"`);if(i.instanceId!==t.instanceId)throw new g("FORBIDDEN",`@lunora/agent: instance "${t.instanceId}" does not own thread "${t.threadKey}"`);const r=i.agent,{agents:d}=n,c=d?.[r];if(typeof c?.sendEvent!="function")throw new g("INTERNAL",`@lunora/agent: no ctx.agents["${r}"] producer to resolve the approval — run codegen/dev so the agent binding is wired`);return await c.sendEvent(t.instanceId,{payload:{decision:t.decision,toolCallId:t.toolCallId,...t.note===void 0?{}:{note:t.note}},type:`agent-approval:${t.toolCallId}`}),{resolved:!0}}),B=b.input({agent:e.string(),input:e.string(),threadKey:e.string(),title:e.optional(e.string())}).mutation(async({args:t,ctx:n})=>{const{agents:a}=n,i=a?.[t.agent];if(typeof i?.run!="function")throw new g("INTERNAL",`@lunora/agent: no ctx.agents["${t.agent}"] producer to start a run — run codegen/dev so the agent binding is wired, and check the agent name`);if(i.publicRun!==!0)throw new g("FORBIDDEN",`@lunora/agent: agent "${t.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 r=n.auth.userId??void 0,d=await n.db.query(p).withIndex("byKey",l=>l.eq("key",t.threadKey)).first();if(d){const l=d.status,q=d.instanceId,_=d.owner;if((l==="running"||l==="awaiting_input")&&q!==void 0&&(_===void 0||_===r))return{id:q,threadKey:t.threadKey};if(_!==r&&r!==void 0)throw new g("FORBIDDEN",`@lunora/agent: thread "${t.threadKey}" belongs to another owner`)}const{id:c}=await i.run({input:t.input,threadKey:t.threadKey,...r===void 0?{}:{owner:r},...t.title===void 0?{}:{title:t.title}});return{id:c,threadKey:t.threadKey}}),C=H(),R=ee();return{extension:ne,functions:{agentAppendMessage:f(o),agentCompleteRun:f(w),agentEnsureThread:f(u),agentEpisodeRecall:R.agentEpisodeRecall,agentEpisodeUpsert:R.agentEpisodeUpsert,agentGraphTraverse:C.agentGraphTraverse,agentGraphUpsert:C.agentGraphUpsert,agentMessages:L,agentDeleteMessage:f(s),agentPatchThread:f(y),agentResolveApproval:U,agentRun:B,agentSetState:f(I),agentState:O,agentThread:h}}};export{le as agentComponent,ne as agentExtension,pe as normalizeEntityName,we as sandboxComponent};

package/dist/inbound.d.mts

@@ -1,4 +1,4 @@
-import { A as AgentDefinition } from "./packem_shared/types.d-boAM2Yi1.mjs";
+import { A as AgentDefinition } from "./packem_shared/types.d-eCuvcLzf.mjs";
 import '@lunora/mail/inbound';
 import 'ai';
 /**

package/dist/inbound.d.ts

@@ -1,4 +1,4 @@
-import { A as AgentDefinition } from "./packem_shared/types.d-boAM2Yi1.js";
+import { A as AgentDefinition } from "./packem_shared/types.d-eCuvcLzf.js";
 import '@lunora/mail/inbound';
 import 'ai';
 /**

package/dist/inbound.mjs

@@ -1,32 +1 @@
-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 };
+import{LunoraError as i}from"@lunora/errors";import{createInboundEmailHandler as d,parseInboundEmail as u}from"@lunora/mail/inbound";import{h as f,B as l}from"./packem_shared/branch-marker-boZ00zmk.mjs";const E=c=>{const s=d({dispatch:async(a,o)=>{for(const n of c){const t=n.agent.onEmail;if(!t)continue;const r=await t(a);if(r==null)continue;const e=o.env[n.binding];if(!e||typeof e.create!="function")throw new i("INTERNAL",`@lunora/agent: no Workflow binding "${n.binding}" on env for an inbound agent — run codegen/dev so wrangler.jsonc declares it`);if(f(r))throw new i("BAD_REQUEST",`@lunora/agent: inbound run params ${l}`);await e.create({params:r});return}},parse:u});return async(a,o,n)=>s(a,o,n)};export{E as dispatchAgentEmail};

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { A as AgentDefinition, c as AgentCompact, d as AgentEpisodeExtract, e as AgentGraphExtract, f as AgentGenerate, g as AgentTokenSink, h as AgentRunInput, i as AgentFunctionPaths, j as AgentRunFunction, k as AgentStepLike, l as AgentStreamGenerate, m as AgentRunResult, n as AgentMessageRow, o as AgentConfig, S as SkillDefinition, p as AnyAgentTool, q as AgentAsToolOptions, r as AgentSubToolInput, b as AgentToolDefinition, s as AgentBindingSpec, t as AgentHandle, u as AgentToolConfig, v as AgentFunctionReference, w as AgentModelInput, x as SkillConfig } from "./packem_shared/types.d-boAM2Yi1.mjs";
-export type { y as AgentEmailMapper, z as AgentEmailRun, B as AgentGenerateOptions, C as AgentGenerateResult, D as AgentInstructionsContext, E as AgentLiveEvent, F as AgentMemoryOptions, G as AgentMemorySource, H as AgentMessageStatus, J as AgentOnStepFinish, K as AgentPrepareStep, L as AgentPrepareStepInput, M as AgentPrepareStepResult, N as AgentProgressEvent, O as AgentRunHandle, P as AgentStepFinishInfo, Q as AgentStepInfo, R as AgentThreadStatus, T as AgentTokenDelta, U as AgentToolCall, a as AgentToolContext, V as AgentUsage, W as AgentVoiceConfig, X as AgentWorkflowBindingLike, Y as AgentWorkflowInstanceLike } from "./packem_shared/types.d-boAM2Yi1.mjs";
+import { A as AgentDefinition, e as AgentCompact, f as AgentEpisodeExtract, g as AgentGraphExtract, h as AgentGenerate, i as AgentTokenSink, j as AgentRunInput, k as AgentFunctionPaths, l as AgentRunFunction, m as AgentStepLike, n as AgentStreamGenerate, o as AgentRunResult, p as AgentMessageRow, q as AgentConfig, d as SkillDefinition, r as AnyAgentTool, s as AgentAsToolOptions, t as AgentSubToolInput, c as AgentToolDefinition, u as AgentBindingSpec, v as AgentHandle, w as AgentToolConfig, x as AgentFunctionReference, y as AgentModelInput, z as SkillConfig } from "./packem_shared/types.d-eCuvcLzf.mjs";
+export type { B as AgentApprovalContext, C as AgentEmailMapper, D as AgentEmailRun, E as AgentGenerateOptions, F as AgentGenerateResult, G as AgentInstructionsContext, H as AgentLiveEvent, J as AgentMemoryOptions, K as AgentMemorySource, L as AgentMessageStatus, M as AgentOnReply, N as AgentOnStepFinish, O as AgentPrepareStep, P as AgentPrepareStepInput, Q as AgentPrepareStepResult, R as AgentProgressEvent, T as AgentReplyInfo, a as AgentReplyRef, U as AgentRunHandle, V as AgentStepFinishInfo, W as AgentStepInfo, X as AgentThreadStatus, Y as AgentTokenDelta, Z as AgentToolCall, b as AgentToolContext, _ as AgentUsage, $ as AgentVoiceConfig, a0 as AgentWorkflowBindingLike, a1 as AgentWorkflowInstanceLike, a2 as EnsureThreadOutcome } from "./packem_shared/types.d-eCuvcLzf.mjs";
 export { type AgentComponent, agentComponent, agentExtension } from "./component.mjs";
 import { FlexibleSchema, LanguageModel, ModelMessage } from 'ai';
 export { agentBindingName, agentClassName, agentDefaultName, voiceBindingName, voiceClassName } from "./naming.mjs";
@@ -183,7 +183,7 @@ declare const agentAsTool: (options: AgentAsToolOptions) => AgentToolDefinition<
 interface ToolScriptStep {
   /** A stable name later steps reference the output by. */
   id: string;
-  /** The tool's input; values may embed `{ "$from": "&lt;stepId>", "$path": "a.b" }` refs. */
+  /** The tool's input; values may embed `{ "$from": "<stepId>", "$path": "a.b" }` refs. */
   input?: Record<string, unknown>;
   /** The tool to call — one of the tools handed to {@link codeTool}. */
   tool: string;
@@ -239,6 +239,16 @@ interface CodeToolOptions {
  * keep approval-gated tools as normal top-level tools. Gate the whole script via
  * `opts.needsApproval` instead.
  *
+ * STEP-OUTPUT CONTRACT — **every step's output must be JSON-serializable.** Each
+ * step runs inside its own durable `step.do`, so the workflow host serializes
+ * the returned value before the next step (or the tool result) ever sees it. A
+ * `Date` comes back as an ISO string, a `Map`/`Set` as `{}`, `undefined` as
+ * `null` or a dropped key, and a `bigint` throws outright. That applies to the
+ * value a later step reads through `{ "$from": … }` just as much as to the
+ * returned `results` — the hand-off is durable state, not an in-memory one. A
+ * composed tool that wants to pass a rich value should return its JSON form
+ * (`date.toISOString()`, `[...map]`) and let the consuming step rebuild it.
+ *
  * ```ts
  * import { codeTool, defineAgent, functionTool } from "@lunora/agent";
  *
@@ -344,8 +354,14 @@ interface FunctionToolOptions<Input> {
  * ```
  *
  * The function reference may be a typed `api.*` reference or a `"module:name"`
- * path. The model-provided input is passed verbatim as the function's args, so
- * `inputSchema` should mirror the referenced function's argument validator.
+ * path. The model-provided input is passed as the function's args, so
+ * `inputSchema` should mirror the referenced function's argument validator —
+ * PLUS the call's `idempotencyKey`, pinned onto the args after the model
+ * input (so out-of-schema model input can never override it). A function
+ * that wants to dedupe a side-effecting call across an at-least-once step
+ * retry declares `idempotencyKey: v.optional(v.string())` in its own args
+ * and checks it; a function that ignores it is unaffected — an args field
+ * the function's own validator doesn't declare is dropped, not rejected.
  * @experimental
  */
 declare const functionTool: <Input extends Record<string, unknown> = Record<string, unknown>, Output = unknown>(reference: AgentFunctionReference | string, options: FunctionToolOptions<Input>) => AgentToolDefinition<Input, Output>;
@@ -471,6 +487,17 @@ interface McpToolsOptions {
   command?: string;
   /** Identify this client to the server on connect. Default `"lunora-agent"`. */
   name?: string;
+  /**
+   * Gate an adapted tool's call behind a human approval. Defaults to
+   * **unattended** (no gate) — matching today's behavior. An MCP tool's
+   * result feeds back into the model's context (`adaptMcpResult`), so a
+   * hostile downstream server can pair indirect prompt injection with an
+   * unattended mutating tool call; pass a boolean to gate every adapted
+   * tool the same way, or a predicate `(toolName, input) => boolean` to
+   * gate per tool (evaluated from replay-stable input, so keep it
+   * deterministic).
+   */
+  needsApproval?: ((toolName: string, input: Record<string, unknown>) => boolean) | boolean;
   /** Only adapt these tool names (default: every tool the server lists). */
   only?: ReadonlyArray<string>;
   /** Prefix added to each adapted tool's key (disambiguate multiple servers). */
@@ -510,6 +537,9 @@ declare const adaptMcpResult: (result: McpCallResult) => unknown;
  * every call. In the Workers runtime only the HTTP/SSE transports run (stdio
  * does not) — pass `url`, or inject an already-connected `client` for a custom
  * transport (also the test seam).
+ *
+ * Every adapted tool runs UNATTENDED by default (no approval gate) — pass
+ * `opts.needsApproval` to change that; see {@link McpToolsOptions.needsApproval}.
  * @experimental
  */
 declare const mcpTools: (options: McpToolsOptions) => Promise<Record<string, AgentToolDefinition<Record<string, unknown>>>>;
@@ -808,15 +838,15 @@ declare class VoiceSessionDO {
 }
 /**
  * Compile a `defineAgent` definition into the workflow the generated
- * `&lt;Name>AgentWorkflow` entrypoint class runs. Codegen emits, per agent:
+ * `<Name>AgentWorkflow` entrypoint class runs. Codegen emits, per agent:
  *
  * ```ts
  * import LunoraWorkflow from "@lunora/workflow/do";
  * import { compileAgentWorkflow } from "@lunora/agent";
  * import { support } from "../agents.js";
  *
- * export class SupportAgentWorkflow extends LunoraWorkflow&lt;AgentRunInput, AgentRunResult> {
- *     public constructor(ctx: ConstructorParameters&lt;typeof LunoraWorkflow>[0], env: Record&lt;string, unknown>) {
+ * export class SupportAgentWorkflow extends LunoraWorkflow<AgentRunInput, AgentRunResult> {
+ *     public constructor(ctx: ConstructorParameters<typeof LunoraWorkflow>[0], env: Record<string, unknown>) {
  *         super(ctx, env, compileAgentWorkflow(support, "support"), "support");
  *     }
  * }