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

package/README.md

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

package/dist/channels.d.mts

@@ -1,11 +1,12 @@
-import { A as AgentDefinition } from "./packem_shared/types.d-BWG0uUtX.mjs";
-export type { I as InboundChannelEvent } from "./packem_shared/types.d-BWG0uUtX.mjs";
+import { A as AgentDefinition } from "./packem_shared/types.d-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;
@@ -15,7 +16,10 @@ declare const verifySlack: (options: {
   timestamp: string | undefined;
   tolerance?: number;
 }) => Promise<boolean>;
-/** Verify a GitHub webhook signature (`x-hub-signature-256` = `sha256=` + HMAC over the body). */
+/**
+* Verify a GitHub webhook signature (`x-hub-signature-256` = `sha256=` + HMAC over the body).
+* @experimental
+*/
 declare const verifyGithub: (options: {
   body: string;
   secret: string;
@@ -24,6 +28,7 @@ declare const verifyGithub: (options: {
 /**
 * 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;
@@ -31,14 +36,20 @@ declare const verifyDiscord: (options: {
   signature: string | undefined;
   timestamp: string | undefined;
 }) => Promise<boolean>;
-/** One agent wired into the inbound channel HTTP handler. */
+/**
+* One agent wired into the inbound channel HTTP handler.
+* @experimental
+*/
 interface AgentChannelTarget {
   /** The agent definition — only its `onInbound` config is read. */
   agent: Pick<AgentDefinition, "onInbound">;
   /** The `AGENT_*` Workflow binding name (off `env`) that starts a run. */
   binding: string;
 }
-/** The HTTP handler `dispatchAgentChannel` returns — mount it on a webhook route. */
+/**
+* The HTTP handler `dispatchAgentChannel` returns — mount it on a webhook route.
+* @experimental
+*/
 type InboundChannelHandler = (request: Request, env: Record<string, unknown>) => Promise<Response>;
 /**
 * Build an HTTP handler that starts a durable agent run from a verified inbound
@@ -49,6 +60,7 @@ type InboundChannelHandler = (request: Request, env: Record<string, unknown>) =>
 * 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

@@ -1,11 +1,12 @@
-import { A as AgentDefinition } from "./packem_shared/types.d-BWG0uUtX.js";
-export type { I as InboundChannelEvent } from "./packem_shared/types.d-BWG0uUtX.js";
+import { A as AgentDefinition } from "./packem_shared/types.d-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;
@@ -15,7 +16,10 @@ declare const verifySlack: (options: {
   timestamp: string | undefined;
   tolerance?: number;
 }) => Promise<boolean>;
-/** Verify a GitHub webhook signature (`x-hub-signature-256` = `sha256=` + HMAC over the body). */
+/**
+* Verify a GitHub webhook signature (`x-hub-signature-256` = `sha256=` + HMAC over the body).
+* @experimental
+*/
 declare const verifyGithub: (options: {
   body: string;
   secret: string;
@@ -24,6 +28,7 @@ declare const verifyGithub: (options: {
 /**
 * 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;
@@ -31,14 +36,20 @@ declare const verifyDiscord: (options: {
   signature: string | undefined;
   timestamp: string | undefined;
 }) => Promise<boolean>;
-/** One agent wired into the inbound channel HTTP handler. */
+/**
+* One agent wired into the inbound channel HTTP handler.
+* @experimental
+*/
 interface AgentChannelTarget {
   /** The agent definition — only its `onInbound` config is read. */
   agent: Pick<AgentDefinition, "onInbound">;
   /** The `AGENT_*` Workflow binding name (off `env`) that starts a run. */
   binding: string;
 }
-/** The HTTP handler `dispatchAgentChannel` returns — mount it on a webhook route. */
+/**
+* The HTTP handler `dispatchAgentChannel` returns — mount it on a webhook route.
+* @experimental
+*/
 type InboundChannelHandler = (request: Request, env: Record<string, unknown>) => Promise<Response>;
 /**
 * Build an HTTP handler that starts a durable agent run from a verified inbound
@@ -49,6 +60,7 @@ type InboundChannelHandler = (request: Request, env: Record<string, unknown>) =>
 * 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/component.d.mts

@@ -17,6 +17,7 @@ interface AgentRegisteredFunction {
 * 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. */
@@ -25,6 +26,7 @@ declare const normalizeEntityName: (name: string) => string;
 * 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;
@@ -32,6 +34,10 @@ interface SandboxRegisteredFunction {
   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;
 }
@@ -41,6 +47,7 @@ interface SandboxComponent {
 * 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
@@ -48,6 +55,7 @@ interface SandboxComponent {
 * 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;
 /**
@@ -64,8 +72,13 @@ declare const sandboxComponent: () => SandboxComponent;
 * 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: {
@@ -96,6 +109,7 @@ interface AgentComponent {
 * to `agents:agentMessages` for a live thread view. Two mutations are public:
 * `agentResolveApproval` (a client resolves a HITL approval) and `agentRun`
 * (an HTTP client starts a durable run) — both owner-gated.
+* @experimental
 */
 declare const agentComponent: () => AgentComponent;
 export { AgentComponent, type SandboxComponent, type SandboxRegisteredFunction, agentComponent, agentExtension, normalizeEntityName, sandboxComponent };

package/dist/component.d.ts

@@ -17,6 +17,7 @@ interface AgentRegisteredFunction {
 * 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. */
@@ -25,6 +26,7 @@ declare const normalizeEntityName: (name: string) => string;
 * 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;
@@ -32,6 +34,10 @@ interface SandboxRegisteredFunction {
   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;
 }
@@ -41,6 +47,7 @@ interface SandboxComponent {
 * 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
@@ -48,6 +55,7 @@ interface SandboxComponent {
 * 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;
 /**
@@ -64,8 +72,13 @@ declare const sandboxComponent: () => SandboxComponent;
 * 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: {
@@ -96,6 +109,7 @@ interface AgentComponent {
 * 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/inbound.d.mts

@@ -1,7 +1,10 @@
-import { A as AgentDefinition } from "./packem_shared/types.d-BWG0uUtX.mjs";
+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. */
+/**
+* One agent wired into the inbound `email()` handler.
+* @experimental
+*/
 interface AgentEmailTarget {
   /**
   * The agent definition — only its `onEmail` mapper is read, deciding whether
@@ -15,6 +18,7 @@ interface AgentEmailTarget {
 * 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>;
 /**
@@ -24,6 +28,7 @@ type InboundAgentEmailHandler = (message: unknown, env: unknown, context: unknow
 * 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

@@ -1,7 +1,10 @@
-import { A as AgentDefinition } from "./packem_shared/types.d-BWG0uUtX.js";
+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. */
+/**
+* One agent wired into the inbound `email()` handler.
+* @experimental
+*/
 interface AgentEmailTarget {
   /**
   * The agent definition — only its `onEmail` mapper is read, deciding whether
@@ -15,6 +18,7 @@ interface AgentEmailTarget {
 * 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>;
 /**
@@ -24,6 +28,7 @@ type InboundAgentEmailHandler = (message: unknown, env: unknown, context: unknow
 * 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 };