@lunora/agent 0.0.0 → 1.0.0-alpha.2

package/LICENSE.md

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, Apache 2.0 Future License
+
+## Abbreviation
+
+FSL-1.1-Apache-2.0
+
+## Notice
+
+Copyright 2026 anolilab and contributors
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or service
+that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software that
+   exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee using
+   the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to the
+infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES, EVEN
+IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following will
+apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -1,45 +1,52 @@
 # @lunora/agent
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+> **Experimental** — this package is outside the Lunora 1.0 stability promise: its API may change in any release, without a major version bump.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+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.
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+```ts
+// lunora/agents.ts
+import { defineAgent, defineAgentTool } from "@lunora/agent";
+import { jsonSchema } from "@lunora/ai";
 
-## Purpose
+export const support = defineAgent({
+    instructions: "You are a helpful support agent.",
+    memory: { source: "rag:searchDocs" }, // an action over @lunora/ai/rag's retrieve
+    model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
+    tools: {
+        getWeather: defineAgentTool({
+            description: "Look up the current weather for a city.",
+            execute: async ({ city }, { idempotencyKey, run }) => run({ __lunoraRef: "weather:lookup" }, { city, key: idempotencyKey }),
+            inputSchema: jsonSchema({ properties: { city: { type: "string" } }, required: ["city"], type: "object" }),
+        }),
+    },
+});
+```
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@lunora/agent`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+Codegen auto-registers the agent runtime functions (`agents:agentMessages`, …) and the
+`ctx.agents.support` producer as soon as an agent is declared — no re-export boilerplate.
 
-## What is OIDC Trusted Publishing?
+```ts
+// lunora/schema.ts — merge the thread tables (auto-prefixed agent_threads / agent_messages):
+export default defineSchema({ ... }).extend(agentExtension);
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+// start a run from a mutation/action:
+const { id } = await ctx.agents.support.run({ input: message, owner: ctx.auth.userId, threadKey });
 
-## Setup Instructions
+// watch it live from the client (every turn, tool call, and reply streams in):
+useSubscription(api.agents.agentMessages, { key: threadKey });
+```
 
-To properly configure OIDC trusted publishing for this package:
+## Why durable
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+- A **completed** step is memoized by Cloudflare Workflows — a resumed run never re-executes a finished tool call (no double-charged card).
+- A **failed** step is retried at-least-once — side-effecting tools receive their deterministic step name as `ctx.idempotencyKey` to dedupe on.
+- Message writes are keyed and idempotent — replays never duplicate the thread.
+- Owned threads (`owner: ctx.auth.userId`) are readable only by their owner — a mismatch looks like a missing thread.
+- The 10-minute action ceiling doesn't exist here: slow tools and long loops are just workflow steps.
 
-## DO NOT USE THIS PACKAGE
+See the package docs for the full API.
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+## License
 
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+FSL-1.1-Apache-2.0

package/dist/channels.d.mts

@@ -0,0 +1,66 @@
+import { A as AgentDefinition } from "./packem_shared/types.d-BhJFTvz_.mjs";
+export type { I as InboundChannelEvent } from "./packem_shared/types.d-BhJFTvz_.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).
+* @experimental
+*/
+declare const verifySlack: (options: {
+  body: string;
+  now?: number;
+  signature: string | undefined;
+  signingSecret: string;
+  timestamp: string | undefined;
+  tolerance?: number;
+}) => Promise<boolean>;
+/**
+* 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).
+* @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.
+* @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.
+* @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.
+* @experimental
+*/
+declare const dispatchAgentChannel: (targets: ReadonlyArray<AgentChannelTarget>) => InboundChannelHandler;
+export { type AgentChannelTarget, type InboundChannelHandler, dispatchAgentChannel, verifyDiscord, verifyGithub, verifySlack };

package/dist/channels.d.ts

@@ -0,0 +1,66 @@
+import { A as AgentDefinition } from "./packem_shared/types.d-BhJFTvz_.js";
+export type { I as InboundChannelEvent } from "./packem_shared/types.d-BhJFTvz_.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).
+* @experimental
+*/
+declare const verifySlack: (options: {
+  body: string;
+  now?: number;
+  signature: string | undefined;
+  signingSecret: string;
+  timestamp: string | undefined;
+  tolerance?: number;
+}) => Promise<boolean>;
+/**
+* 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).
+* @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.
+* @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.
+* @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.
+* @experimental
+*/
+declare const dispatchAgentChannel: (targets: ReadonlyArray<AgentChannelTarget>) => InboundChannelHandler;
+export { type AgentChannelTarget, type InboundChannelHandler, dispatchAgentChannel, verifyDiscord, verifyGithub, verifySlack };

package/dist/channels.mjs

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

package/dist/component.d.mts

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