@lunora/codegen 1.0.0-alpha.42 → 1.0.0-alpha.44

package/dist/index.d.mts

@@ -122,13 +122,13 @@ interface ExternalSourceIR {
   binding: string;
   /** Whether a `columns` projection allow-list was given. */
   columns?: ReadonlyArray<string>;
-  /** `true` when a `reconcileEveryMs` was given (the incremental-mode delete-visibility companion). */
+  /** `true` when a `reconcileEveryMs` was given — reserved for a future incremental mode's delete-visibility lint; not on the typed `.source()` surface today. */
   hasReconcile?: boolean;
   /** `true` when a `tenantBy` mapper was given — the tenant-isolation boundary the `external_source_unscoped` lint checks. */
   hasTenantBy: boolean;
   /** The `idColumn` literal, when given (defaults to `"id"` at runtime). */
   idColumn?: string;
-  /** Delete-detection mode literal, when given (`"full-pull"` | `"incremental"`). */
+  /** Delete-detection mode literal, when given (`"full-pull"` today). */
   mode?: string;
   /** The membership query literal, when statically knowable. */
   query?: string;
@@ -451,6 +451,64 @@ interface WorkflowIR {
   */
   steps: ReadonlyArray<WorkflowStepIR>;
 }
+/**
+* An agent lifted from a `defineAgent()` export in `lunora/agents.ts`. A
+* `defineAgent` compiles its durable tool-loop onto a Cloudflare Workflow, so —
+* like {@link WorkflowIR} — an agent is NOT a Durable Object: wrangler gets only
+* a `workflows[]` entry, never a `durable_objects` binding or a migration class.
+* Carries what the emitters and the config layer need to wire the generated
+* agent `WorkflowEntrypoint` class (e.g. `SupportAgentWorkflow`), the typed
+* per-agent `ctx.agents` producer, and the reconciled wrangler `workflows[]`
+* entry. Names are derived via `@lunora/agent`'s shared helpers so codegen and
+* the config layer can never disagree.
+*/
+interface AgentIR {
+  /** The Cloudflare `Workflow` binding name, e.g. `AGENT_SUPPORT`. */
+  bindingName: string;
+  /** Generated `WorkflowEntrypoint` class name, e.g. `SupportAgentWorkflow`. */
+  className: string;
+  /** The `lunora/agents.ts` export name, e.g. `support`. */
+  exportName: string;
+  /**
+  * The stable wrangler `workflows[].name`. Defaults to the kebab-cased export
+  * name (`support` → `agent-support`); a static `name:` literal in the
+  * definition overrides it.
+  */
+  name: string;
+  /**
+  * Whether the definition declares an `onEmail` mapper on
+  * `defineAgent({ onEmail: … })`. When `true` the emitter wires this agent
+  * onto the worker's top-level `email()` handler (via `@lunora/agent/inbound`)
+  * so inbound mail starts a durable run. Detected by AST PRESENCE — the
+  * closure is never evaluated — and written to IR only when present, so
+  * email-free agents (and agent-free projects) stay byte-identical.
+  */
+  onEmail?: boolean;
+  /**
+  * Whether the definition opted into public run-starts via
+  * `defineAgent({ publicRun: true })` — emitted into the `ctx.agents` wiring
+  * spec so the public `agents:agentRun` mutation can gate on it fail-closed.
+  * Absent (falsy) means server-side starts only; the field is written to IR
+  * only when the literal is `true`, so agent-free and non-opted-in output is
+  * byte-identical.
+  */
+  publicRun?: boolean;
+  /**
+  * Whether the definition opted into a real-time voice session via a `voice`
+  * block on `defineAgent({ voice: … })`. Unlike the durable loop (a Workflow),
+  * the voice path IS a Durable Object — so when this is `true` the emitter
+  * generates the `voiceClassName` `VoiceSessionDO` subclass and the
+  * `api.agents.{name}Voice` client reference, and the config layer reconciles
+  * a `durable_objects` binding (`voiceBindingName`) + `new_sqlite_classes`
+  * migration. Written to IR only when the literal is present, so voice-free
+  * agents (and agent-free projects) stay byte-identical.
+  */
+  voice?: boolean;
+  /** The voice DO's Cloudflare `DurableObjectNamespace` binding name, e.g. `VOICE_SUPPORT`. Present only when `voice`. */
+  voiceBindingName?: string;
+  /** Generated `VoiceSessionDO` subclass name, e.g. `SupportVoiceDO`. Present only when `voice`. */
+  voiceClassName?: string;
+}
 /** One durable step call lifted from a workflow handler body (the use side of {@link WorkflowIR.steps}). */
 interface WorkflowStepIR {
   /** 1-based line of the durable step call. */
@@ -812,6 +870,15 @@ interface StorageRulesMetadataIR {
 interface HttpRouteIR {
   /** `v.*` validators decoding the JSON request body (`.body({...})`), keyed by field. */
   body: Record<string, ValidatorIR>;
+  /**
+  * Rendered TS type of one SSE chunk — the `R` the `.stream(handler)`
+  * handler yields — inferred from the handler via the type checker. Present
+  * only when {@link HttpRouteIR.stream} is `true`; `"unknown"` when the
+  * checker can't resolve enough context. Feeds the emitted
+  * `HttpStreamRef&lt;Chunk, …>` so the chunk type flows to the client.
+  * @experimental Part of the HTTP-SSE stream surface (the `httpStreams.*` emission).
+  */
+  chunkType?: string;
   /** Export binding name of the route handler (used only for diagnostics / dedupe). */
   exportName: string;
   /** Path relative to `&lt;projectRoot>/lunora/` without extension, e.g. "http". */
@@ -1692,6 +1759,19 @@ declare class CodegenDiagnosticError extends LunoraError {
 * lookup is unaffected.
 */
 declare const diagnosticAt: (node: Node, detail: string, meta?: Record<string, unknown>) => CodegenDiagnosticError;
+/** The only file agents may be declared in — mirrors `lunora/workflows.ts`. */
+declare const AGENTS_FILENAME = "agents.ts";
+/**
+* Discover every agent the project declares: exported `defineAgent()` calls in
+* `lunora/agents.ts`. Returns `[]` when the file doesn't exist. Only four things
+* are read statically — the optional `name` override (wrangler `workflows[].name`),
+* the optional `publicRun` opt-in (the `agents:agentRun` capability gate), the
+* presence of a `voice` block (which turns on the voice-session Durable Object),
+* and the presence of an `onEmail` mapper (which wires the worker `email()`
+* handler); the rest of the agent config (model / tools / memory / voice models /
+* the `onEmail` closure body) is runtime-only, so codegen never evaluates it.
+*/
+declare const discoverAgents: (project: Project, lunoraDirectory: string) => AgentIR[];
 /**
 * Discover `ctx.authApi.&lt;method>(...)` (and bare `authApi.&lt;method>(...)`) calls
 * under the lunora source directory and attribute each to the exported function
@@ -1713,10 +1793,11 @@ declare const discoverContainers: (project: Project, lunoraDirectory: string) =>
 * (`crons.interval(...)`, `crons.daily(...)`, `crons.cron(...)`, …) and lift them
 * into {@link CronJobIR}. Schedules are compiled to standard cron expressions;
 * function references are resolved to their `namespace:fn` dispatch path, while a
-* bare identifier naming a declared workflow (`workflows`) resolves to a durable
-* workflow start. Names must be unique across the project.
+* `workflows.NAME` / `agents.NAME` reference (or a bare identifier naming a
+* declared workflow) resolves to a durable workflow start. Names must be unique
+* across the project.
 */
-declare const discoverCrons: (project: Project, lunoraDirectory: string, workflows?: ReadonlyArray<WorkflowIR>) => CronJobIR[];
+declare const discoverCrons: (project: Project, lunoraDirectory: string, workflows?: ReadonlyArray<WorkflowIR>, agents?: ReadonlyArray<AgentIR>) => CronJobIR[];
 /** The only file a feature-flag provider may be declared in — mirrors `lunora/queues.ts`. */
 declare const FLAGS_FILENAME = "flags.ts";
 /** One statically-discovered flag read: the key plus the value type its `ctx.flags.&lt;type>` call implies. */
@@ -1887,13 +1968,21 @@ declare const GENERATED_HEADER = "// GENERATED by @lunora/codegen — do not edi
 declare const emitDataModel: (schema: SchemaIR, useUmbrella?: boolean) => string;
 /**
 * Emit `_generated/api.ts` — the typed `api.*` registry (public functions), the
-* `internal.*` registry, and (when the project declares workflows) the typed
-* `workflows.*` reference object. `api`/`internal` are the same `anyApi` proxy
+* `internal.*` registry, and (when the project declares them) the typed
+* `workflows.*` / `agents.*` scheduler-target reference objects. `api`/`internal` are the same `anyApi` proxy
 * at runtime (the `__lunoraRef` is identical); visibility is enforced
 * server-side at dispatch, not in the reference. Splitting the *types* keeps
 * internal functions off the client-facing `api` surface.
 */
-declare const emitApi: (functions: ReadonlyArray<FunctionIR>, workflows?: ReadonlyArray<WorkflowIR>, useUmbrella?: boolean) => string;
+interface EmitApiOptions {
+  agents?: ReadonlyArray<AgentIR>;
+  functions: ReadonlyArray<FunctionIR>;
+  /** Typed REST routes; only `.stream()` (SSE) routes emit a `httpStreams.*` reference. */
+  httpRoutes?: ReadonlyArray<HttpRouteIR>;
+  useUmbrella?: boolean;
+  workflows?: ReadonlyArray<WorkflowIR>;
+}
+declare const emitApi: (options: EmitApiOptions) => string;
 /**
 * Emit `_generated/seed.ts` — a project-bound `createSeedClient` with this
 * schema's `InsertModel` and runtime schema pre-applied, so a test or script
@@ -1904,7 +1993,6 @@ declare const emitApi: (functions: ReadonlyArray<FunctionIR>, workflows?: Readon
 * Returns `""` when `@lunora/seed` is not a declared dependency, so projects
 * that don't use it keep a clean `_generated/` and never import the package.
 */
-
 /**
 * Emit `_generated/collections.ts` — one TanStack DB collection factory per
 * `defineShape` in `lunora/shapes.ts` (the local-first partial-replication
@@ -1921,6 +2009,8 @@ declare const emitApi: (functions: ReadonlyArray<FunctionIR>, workflows?: Readon
 */
 declare const emitCollections: (shapes: ReadonlyArray<ShapeIR>, hasDatabase: boolean, useUmbrella?: boolean) => string;
 interface EmitServerOptions {
+  /** Agents declared via `defineAgent` exports — wires the typed `ctx.agents` producers onto Mutation/Action contexts. */
+  agents?: ReadonlyArray<AgentIR>;
   containers?: ReadonlyArray<ContainerIR>;
   /**
   * The single `defineEnv(...)` contract declared in `lunora/env.ts`. When
@@ -1974,6 +2064,7 @@ interface EmitServerOptions {
   workflows?: ReadonlyArray<WorkflowIR>;
 }
 declare const emitServer: ({
+  agents,
   containers,
   env,
   hasAccessFacade,
@@ -1995,7 +2086,17 @@ declare const emitServer: ({
   useUmbrella,
   workflows
 }?: EmitServerOptions) => string;
-declare const emitFunctions: (functions: ReadonlyArray<FunctionIR>, migrations?: ReadonlyArray<MigrationIR>, useUmbrella?: boolean, mutators?: ReadonlyArray<MutatorIR>, shapes?: ReadonlyArray<ShapeIR>) => string;
+interface EmitFunctionsOptions {
+  agents?: ReadonlyArray<AgentIR>;
+  functions: ReadonlyArray<FunctionIR>;
+  migrations?: ReadonlyArray<MigrationIR>;
+  mutators?: ReadonlyArray<MutatorIR>;
+  shapes?: ReadonlyArray<ShapeIR>;
+  /** Import of a sandbox tool (`browserTool`/`containerTool`) auto-registers the `sandbox:invoke` action. */
+  usesSandbox?: boolean;
+  useUmbrella?: boolean;
+}
+declare const emitFunctions: (options: EmitFunctionsOptions) => string;
 /**
 * Storage-column map per table for the file browser: `{ table: [field, …] }` for
 * every field declared `v.storage(...)` (unwrapping `v.optional(...)`). The
@@ -2024,6 +2125,16 @@ declare const emitContainers: (containers: ReadonlyArray<ContainerIR>, jurisdict
 */
 declare const emitWorkflows: (workflows: ReadonlyArray<WorkflowIR>) => string;
 /**
+* Emit `_generated/agents.ts` — one `WorkflowEntrypoint` class per `defineAgent`
+* export, each a thin subclass of `LunoraWorkflow` (`@lunora/workflow/do`)
+* constructed with the compiled agent tool-loop (`compileAgentWorkflow`). Like
+* `_generated/workflows.ts`, the worker entry must re-export these classes:
+* wrangler requires every `workflows[].class_name` to be exported by the
+* deployed worker. Returns "" when the project declares no agents (the file is
+* not written then).
+*/
+declare const emitAgents: (agents: ReadonlyArray<AgentIR>) => string;
+/**
 * Emit `_generated/queues.ts` — the push-consumer registry the worker `queue()`
 * handler dispatches through. Maps each push queue's stable wrangler name (which
 * `batch.queue` carries) to its `defineQueue` definition + export name. Pull
@@ -2033,6 +2144,8 @@ declare const emitWorkflows: (workflows: ReadonlyArray<WorkflowIR>) => string;
 */
 interface EmitShardOptions {
   advisories?: ReadonlyArray<Finding>;
+  /** Agents declared via `defineAgent` exports in `lunora/agents.ts` — wires the typed `ctx.agents` producers. */
+  agents?: ReadonlyArray<AgentIR>;
   containers?: ReadonlyArray<ContainerIR>;
   /** The single `defineEnv(...)` contract declared in `lunora/env.ts` — applies the accessor to the worker `env` to populate `ctx.env`. */
   env?: EnvIR;
@@ -2080,6 +2193,7 @@ interface EmitShardOptions {
 }
 declare const emitShard: ({
   advisories,
+  agents,
   containers,
   env,
   flagKeys,
@@ -2165,6 +2279,16 @@ declare const emitVectors: (vectorIndexes: ReadonlyArray<VectorIndexIR>) => stri
 declare const emitWranglerCronTriggers: (crons: ReadonlyArray<CronJobIR>) => string[];
 /** Which capability methods the generated `defineApp` builder exposes — one flag per package-backed feature the app actually uses. */
 interface EmitAppOptions {
+  /**
+  * Inbound-email agents (`defineAgent({ onEmail })`) → wire the worker's
+  * top-level `email()` handler to `dispatchAgentEmail(...)` (from
+  * `@lunora/agent/inbound`), so received mail starts a durable run. Empty/absent
+  * ⇒ no wiring, byte-identical output for email-free (and agent-free) projects.
+  */
+  emailAgents?: ReadonlyArray<{
+    bindingName: string;
+    exportName: string;
+  }>;
   /** App depends on `@lunora/cloudflare-access` → emit `.access()` (wire the Cloudflare Access `resolveIdentity`, composed ahead of `@lunora/auth` when both are present). */
   hasAccess: boolean;
   /** App uses `@lunora/ai` / `ctx.ai` → emit `.ai()` (override the Workers AI binding backing `ctx.ai`). */
@@ -2209,6 +2333,17 @@ interface EmitAppOptions {
   jurisdiction?: JurisdictionIR;
   /** Project depends on the unscoped `lunorash` umbrella → import the runtime via `lunorash/runtime` instead of `@lunora/runtime`. */
   useUmbrella: boolean;
+  /**
+  * Voice-enabled agents (`defineAgent({ voice: … })`) → wire
+  * `options.voiceAgents`, mapping each agent's export name to its `VOICE_*`
+  * Durable Object namespace binding so the runtime exposes
+  * `/_lunora/voice/&lt;exportName>`. Empty/absent ⇒ no wiring, byte-identical
+  * output for voice-free (and agent-free) projects.
+  */
+  voiceAgents?: ReadonlyArray<{
+    bindingName: string;
+    exportName: string;
+  }>;
   /** An OpenAPI spec is emitted (`openapi.ts`) → wire `openApiSpec` into the worker. */
   wantsOpenApi: boolean;
   /** An OpenRPC spec is emitted (`openrpc.ts`) → wire `openRpcSpec` into the worker. */
@@ -2553,6 +2688,13 @@ interface CodegenResult {
   */
   advisories: ReadonlyArray<Finding>;
   /**
+  * Agents discovered from `defineAgent` exports in `lunora/agents.ts` — the
+  * list the config layer reconciles into wrangler's `workflows[]` array (an
+  * agent compiles onto a Cloudflare Workflow). Agents are NOT Durable Objects,
+  * so this adds no binding or migration. Empty when the project declares none.
+  */
+  agents: ReadonlyArray<AgentIR>;
+  /**
   * Containers discovered from `defineContainer` exports in
   * `lunora/containers.ts` — the list the config layer reconciles into
   * wrangler's `containers[]`, `CONTAINER_*` Durable Object bindings, and
@@ -2566,6 +2708,8 @@ interface CodegenResult {
   */
   cronTriggers: ReadonlyArray<string>;
   generated: {
+    /** WorkflowEntrypoint classes for declared agents (`_generated/agents.ts`); `""` (and not written) when no agents are declared. */
+    agents: string;
     api: string; /** Fluent worker-composition builder (`_generated/app.ts`) — `defineApp()`. Always written. */
     app: string;
     /** Partial-replication collection factories (`_generated/collections.ts`); `""` (and not written) unless the project declares shapes and installs `@lunora/db`. */
@@ -2661,4 +2805,4 @@ declare const secretKindOf: (value: string) => string | undefined;
 /** A redacted preview of a secret value — first 4 chars plus its length, never the full value. */
 declare const redact: (value: string) => string;
 declare const VERSION = "0.0.0";
-export { type AuthApiCallIR, CONTAINERS_FILENAME, CodegenDiagnosticError, type CodegenOptions, type CodegenResult, type ContainerIR, type CronJobIR, type DriftChange, type EmitAppOptions, FLAGS_FILENAME, type FieldSnapshot, type FlagsIR, type FunctionIR, GENERATED_HEADER, type HttpRouteIR, type IndexIR, type IndexSnapshot, type InsertWriteIR, LUNORA_ERROR_CODES, type LintSchemaOptions, MUTATORS_FILENAME, type MaskProcedureIR, type MigrationIR, type MutatorIR, OPENRPC_VERSION, type OpenApiEmitInput, type OpenRpcEmitInput, type ProjectIR, QUEUES_FILENAME, type QueryReadIR, type QueueIR, type R2sqlCallIR, type RelationSnapshot, type RlsMetadataIR, type RlsPolicyIR, type RlsProcedureIR, type RlsRoleIR, SCHEMA_SNAPSHOT_FILENAME, SCHEMA_SNAPSHOT_VERSION, SHAPES_FILENAME, type SchemaDrift, type SchemaDriftDecision, type SchemaIR, type SchemaSnapshot, SchemaSnapshotParseError, type ShapeIR, type StorageRuleIR, type StorageRulesMetadataIR, type TableIR, type TableSnapshot, VERSION, type ValidatorIR, type VectorIndexIR, WORKFLOWS_FILENAME, type WorkflowIR, type WranglerVariableIR, buildOpenApiDocument, buildOpenRpcDocument, buildSchemaSnapshot, createCodegenProject, diagnosticAt, diffSchemaSnapshots, discoverAuthApiCalls, discoverContainers, discoverCrons, discoverFlags, discoverFunctions, discoverHttpRoutes, discoverInserts, discoverMaskProcedures, discoverMigrations, discoverMutators, discoverNondeterministicCalls, discoverQueries, discoverQueues, discoverR2sqlCalls, discoverRlsMetadata, discoverRlsProcedures, discoverSchema, discoverShapes, discoverStorageRulesMetadata, discoverWorkflows, emitApi, emitApp, emitCollections, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitOpenApi, emitOpenApiModule, emitOpenRpc, emitOpenRpcModule, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers, evaluateSchemaDrift, formatAdvisories, lintSchema, parseSchemaSnapshot, redact, refreshCodegenProject, runCodegen, schemaFromIr, secretKindOf, serializeSchemaSnapshot, validatorIrToJsonSchema };
+export { AGENTS_FILENAME, type AgentIR, type AuthApiCallIR, CONTAINERS_FILENAME, CodegenDiagnosticError, type CodegenOptions, type CodegenResult, type ContainerIR, type CronJobIR, type DriftChange, type EmitAppOptions, FLAGS_FILENAME, type FieldSnapshot, type FlagsIR, type FunctionIR, GENERATED_HEADER, type HttpRouteIR, type IndexIR, type IndexSnapshot, type InsertWriteIR, LUNORA_ERROR_CODES, type LintSchemaOptions, MUTATORS_FILENAME, type MaskProcedureIR, type MigrationIR, type MutatorIR, OPENRPC_VERSION, type OpenApiEmitInput, type OpenRpcEmitInput, type ProjectIR, QUEUES_FILENAME, type QueryReadIR, type QueueIR, type R2sqlCallIR, type RelationSnapshot, type RlsMetadataIR, type RlsPolicyIR, type RlsProcedureIR, type RlsRoleIR, SCHEMA_SNAPSHOT_FILENAME, SCHEMA_SNAPSHOT_VERSION, SHAPES_FILENAME, type SchemaDrift, type SchemaDriftDecision, type SchemaIR, type SchemaSnapshot, SchemaSnapshotParseError, type ShapeIR, type StorageRuleIR, type StorageRulesMetadataIR, type TableIR, type TableSnapshot, VERSION, type ValidatorIR, type VectorIndexIR, WORKFLOWS_FILENAME, type WorkflowIR, type WranglerVariableIR, buildOpenApiDocument, buildOpenRpcDocument, buildSchemaSnapshot, createCodegenProject, diagnosticAt, diffSchemaSnapshots, discoverAgents, discoverAuthApiCalls, discoverContainers, discoverCrons, discoverFlags, discoverFunctions, discoverHttpRoutes, discoverInserts, discoverMaskProcedures, discoverMigrations, discoverMutators, discoverNondeterministicCalls, discoverQueries, discoverQueues, discoverR2sqlCalls, discoverRlsMetadata, discoverRlsProcedures, discoverSchema, discoverShapes, discoverStorageRulesMetadata, discoverWorkflows, emitAgents, emitApi, emitApp, emitCollections, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitOpenApi, emitOpenApiModule, emitOpenRpc, emitOpenRpcModule, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers, evaluateSchemaDrift, formatAdvisories, lintSchema, parseSchemaSnapshot, redact, refreshCodegenProject, runCodegen, schemaFromIr, secretKindOf, serializeSchemaSnapshot, validatorIrToJsonSchema };

package/dist/index.d.ts

@@ -122,13 +122,13 @@ interface ExternalSourceIR {
   binding: string;
   /** Whether a `columns` projection allow-list was given. */
   columns?: ReadonlyArray<string>;
-  /** `true` when a `reconcileEveryMs` was given (the incremental-mode delete-visibility companion). */
+  /** `true` when a `reconcileEveryMs` was given — reserved for a future incremental mode's delete-visibility lint; not on the typed `.source()` surface today. */
   hasReconcile?: boolean;
   /** `true` when a `tenantBy` mapper was given — the tenant-isolation boundary the `external_source_unscoped` lint checks. */
   hasTenantBy: boolean;
   /** The `idColumn` literal, when given (defaults to `"id"` at runtime). */
   idColumn?: string;
-  /** Delete-detection mode literal, when given (`"full-pull"` | `"incremental"`). */
+  /** Delete-detection mode literal, when given (`"full-pull"` today). */
   mode?: string;
   /** The membership query literal, when statically knowable. */
   query?: string;
@@ -451,6 +451,64 @@ interface WorkflowIR {
   */
   steps: ReadonlyArray<WorkflowStepIR>;
 }
+/**
+* An agent lifted from a `defineAgent()` export in `lunora/agents.ts`. A
+* `defineAgent` compiles its durable tool-loop onto a Cloudflare Workflow, so —
+* like {@link WorkflowIR} — an agent is NOT a Durable Object: wrangler gets only
+* a `workflows[]` entry, never a `durable_objects` binding or a migration class.
+* Carries what the emitters and the config layer need to wire the generated
+* agent `WorkflowEntrypoint` class (e.g. `SupportAgentWorkflow`), the typed
+* per-agent `ctx.agents` producer, and the reconciled wrangler `workflows[]`
+* entry. Names are derived via `@lunora/agent`'s shared helpers so codegen and
+* the config layer can never disagree.
+*/
+interface AgentIR {
+  /** The Cloudflare `Workflow` binding name, e.g. `AGENT_SUPPORT`. */
+  bindingName: string;
+  /** Generated `WorkflowEntrypoint` class name, e.g. `SupportAgentWorkflow`. */
+  className: string;
+  /** The `lunora/agents.ts` export name, e.g. `support`. */
+  exportName: string;
+  /**
+  * The stable wrangler `workflows[].name`. Defaults to the kebab-cased export
+  * name (`support` → `agent-support`); a static `name:` literal in the
+  * definition overrides it.
+  */
+  name: string;
+  /**
+  * Whether the definition declares an `onEmail` mapper on
+  * `defineAgent({ onEmail: … })`. When `true` the emitter wires this agent
+  * onto the worker's top-level `email()` handler (via `@lunora/agent/inbound`)
+  * so inbound mail starts a durable run. Detected by AST PRESENCE — the
+  * closure is never evaluated — and written to IR only when present, so
+  * email-free agents (and agent-free projects) stay byte-identical.
+  */
+  onEmail?: boolean;
+  /**
+  * Whether the definition opted into public run-starts via
+  * `defineAgent({ publicRun: true })` — emitted into the `ctx.agents` wiring
+  * spec so the public `agents:agentRun` mutation can gate on it fail-closed.
+  * Absent (falsy) means server-side starts only; the field is written to IR
+  * only when the literal is `true`, so agent-free and non-opted-in output is
+  * byte-identical.
+  */
+  publicRun?: boolean;
+  /**
+  * Whether the definition opted into a real-time voice session via a `voice`
+  * block on `defineAgent({ voice: … })`. Unlike the durable loop (a Workflow),
+  * the voice path IS a Durable Object — so when this is `true` the emitter
+  * generates the `voiceClassName` `VoiceSessionDO` subclass and the
+  * `api.agents.{name}Voice` client reference, and the config layer reconciles
+  * a `durable_objects` binding (`voiceBindingName`) + `new_sqlite_classes`
+  * migration. Written to IR only when the literal is present, so voice-free
+  * agents (and agent-free projects) stay byte-identical.
+  */
+  voice?: boolean;
+  /** The voice DO's Cloudflare `DurableObjectNamespace` binding name, e.g. `VOICE_SUPPORT`. Present only when `voice`. */
+  voiceBindingName?: string;
+  /** Generated `VoiceSessionDO` subclass name, e.g. `SupportVoiceDO`. Present only when `voice`. */
+  voiceClassName?: string;
+}
 /** One durable step call lifted from a workflow handler body (the use side of {@link WorkflowIR.steps}). */
 interface WorkflowStepIR {
   /** 1-based line of the durable step call. */
@@ -812,6 +870,15 @@ interface StorageRulesMetadataIR {
 interface HttpRouteIR {
   /** `v.*` validators decoding the JSON request body (`.body({...})`), keyed by field. */
   body: Record<string, ValidatorIR>;
+  /**
+  * Rendered TS type of one SSE chunk — the `R` the `.stream(handler)`
+  * handler yields — inferred from the handler via the type checker. Present
+  * only when {@link HttpRouteIR.stream} is `true`; `"unknown"` when the
+  * checker can't resolve enough context. Feeds the emitted
+  * `HttpStreamRef&lt;Chunk, …>` so the chunk type flows to the client.
+  * @experimental Part of the HTTP-SSE stream surface (the `httpStreams.*` emission).
+  */
+  chunkType?: string;
   /** Export binding name of the route handler (used only for diagnostics / dedupe). */
   exportName: string;
   /** Path relative to `&lt;projectRoot>/lunora/` without extension, e.g. "http". */
@@ -1692,6 +1759,19 @@ declare class CodegenDiagnosticError extends LunoraError {
 * lookup is unaffected.
 */
 declare const diagnosticAt: (node: Node, detail: string, meta?: Record<string, unknown>) => CodegenDiagnosticError;
+/** The only file agents may be declared in — mirrors `lunora/workflows.ts`. */
+declare const AGENTS_FILENAME = "agents.ts";
+/**
+* Discover every agent the project declares: exported `defineAgent()` calls in
+* `lunora/agents.ts`. Returns `[]` when the file doesn't exist. Only four things
+* are read statically — the optional `name` override (wrangler `workflows[].name`),
+* the optional `publicRun` opt-in (the `agents:agentRun` capability gate), the
+* presence of a `voice` block (which turns on the voice-session Durable Object),
+* and the presence of an `onEmail` mapper (which wires the worker `email()`
+* handler); the rest of the agent config (model / tools / memory / voice models /
+* the `onEmail` closure body) is runtime-only, so codegen never evaluates it.
+*/
+declare const discoverAgents: (project: Project, lunoraDirectory: string) => AgentIR[];
 /**
 * Discover `ctx.authApi.&lt;method>(...)` (and bare `authApi.&lt;method>(...)`) calls
 * under the lunora source directory and attribute each to the exported function
@@ -1713,10 +1793,11 @@ declare const discoverContainers: (project: Project, lunoraDirectory: string) =>
 * (`crons.interval(...)`, `crons.daily(...)`, `crons.cron(...)`, …) and lift them
 * into {@link CronJobIR}. Schedules are compiled to standard cron expressions;
 * function references are resolved to their `namespace:fn` dispatch path, while a
-* bare identifier naming a declared workflow (`workflows`) resolves to a durable
-* workflow start. Names must be unique across the project.
+* `workflows.NAME` / `agents.NAME` reference (or a bare identifier naming a
+* declared workflow) resolves to a durable workflow start. Names must be unique
+* across the project.
 */
-declare const discoverCrons: (project: Project, lunoraDirectory: string, workflows?: ReadonlyArray<WorkflowIR>) => CronJobIR[];
+declare const discoverCrons: (project: Project, lunoraDirectory: string, workflows?: ReadonlyArray<WorkflowIR>, agents?: ReadonlyArray<AgentIR>) => CronJobIR[];
 /** The only file a feature-flag provider may be declared in — mirrors `lunora/queues.ts`. */
 declare const FLAGS_FILENAME = "flags.ts";
 /** One statically-discovered flag read: the key plus the value type its `ctx.flags.&lt;type>` call implies. */
@@ -1887,13 +1968,21 @@ declare const GENERATED_HEADER = "// GENERATED by @lunora/codegen — do not edi
 declare const emitDataModel: (schema: SchemaIR, useUmbrella?: boolean) => string;
 /**
 * Emit `_generated/api.ts` — the typed `api.*` registry (public functions), the
-* `internal.*` registry, and (when the project declares workflows) the typed
-* `workflows.*` reference object. `api`/`internal` are the same `anyApi` proxy
+* `internal.*` registry, and (when the project declares them) the typed
+* `workflows.*` / `agents.*` scheduler-target reference objects. `api`/`internal` are the same `anyApi` proxy
 * at runtime (the `__lunoraRef` is identical); visibility is enforced
 * server-side at dispatch, not in the reference. Splitting the *types* keeps
 * internal functions off the client-facing `api` surface.
 */
-declare const emitApi: (functions: ReadonlyArray<FunctionIR>, workflows?: ReadonlyArray<WorkflowIR>, useUmbrella?: boolean) => string;
+interface EmitApiOptions {
+  agents?: ReadonlyArray<AgentIR>;
+  functions: ReadonlyArray<FunctionIR>;
+  /** Typed REST routes; only `.stream()` (SSE) routes emit a `httpStreams.*` reference. */
+  httpRoutes?: ReadonlyArray<HttpRouteIR>;
+  useUmbrella?: boolean;
+  workflows?: ReadonlyArray<WorkflowIR>;
+}
+declare const emitApi: (options: EmitApiOptions) => string;
 /**
 * Emit `_generated/seed.ts` — a project-bound `createSeedClient` with this
 * schema's `InsertModel` and runtime schema pre-applied, so a test or script
@@ -1904,7 +1993,6 @@ declare const emitApi: (functions: ReadonlyArray<FunctionIR>, workflows?: Readon
 * Returns `""` when `@lunora/seed` is not a declared dependency, so projects
 * that don't use it keep a clean `_generated/` and never import the package.
 */
-
 /**
 * Emit `_generated/collections.ts` — one TanStack DB collection factory per
 * `defineShape` in `lunora/shapes.ts` (the local-first partial-replication
@@ -1921,6 +2009,8 @@ declare const emitApi: (functions: ReadonlyArray<FunctionIR>, workflows?: Readon
 */
 declare const emitCollections: (shapes: ReadonlyArray<ShapeIR>, hasDatabase: boolean, useUmbrella?: boolean) => string;
 interface EmitServerOptions {
+  /** Agents declared via `defineAgent` exports — wires the typed `ctx.agents` producers onto Mutation/Action contexts. */
+  agents?: ReadonlyArray<AgentIR>;
   containers?: ReadonlyArray<ContainerIR>;
   /**
   * The single `defineEnv(...)` contract declared in `lunora/env.ts`. When
@@ -1974,6 +2064,7 @@ interface EmitServerOptions {
   workflows?: ReadonlyArray<WorkflowIR>;
 }
 declare const emitServer: ({
+  agents,
   containers,
   env,
   hasAccessFacade,
@@ -1995,7 +2086,17 @@ declare const emitServer: ({
   useUmbrella,
   workflows
 }?: EmitServerOptions) => string;
-declare const emitFunctions: (functions: ReadonlyArray<FunctionIR>, migrations?: ReadonlyArray<MigrationIR>, useUmbrella?: boolean, mutators?: ReadonlyArray<MutatorIR>, shapes?: ReadonlyArray<ShapeIR>) => string;
+interface EmitFunctionsOptions {
+  agents?: ReadonlyArray<AgentIR>;
+  functions: ReadonlyArray<FunctionIR>;
+  migrations?: ReadonlyArray<MigrationIR>;
+  mutators?: ReadonlyArray<MutatorIR>;
+  shapes?: ReadonlyArray<ShapeIR>;
+  /** Import of a sandbox tool (`browserTool`/`containerTool`) auto-registers the `sandbox:invoke` action. */
+  usesSandbox?: boolean;
+  useUmbrella?: boolean;
+}
+declare const emitFunctions: (options: EmitFunctionsOptions) => string;
 /**
 * Storage-column map per table for the file browser: `{ table: [field, …] }` for
 * every field declared `v.storage(...)` (unwrapping `v.optional(...)`). The
@@ -2024,6 +2125,16 @@ declare const emitContainers: (containers: ReadonlyArray<ContainerIR>, jurisdict
 */
 declare const emitWorkflows: (workflows: ReadonlyArray<WorkflowIR>) => string;
 /**
+* Emit `_generated/agents.ts` — one `WorkflowEntrypoint` class per `defineAgent`
+* export, each a thin subclass of `LunoraWorkflow` (`@lunora/workflow/do`)
+* constructed with the compiled agent tool-loop (`compileAgentWorkflow`). Like
+* `_generated/workflows.ts`, the worker entry must re-export these classes:
+* wrangler requires every `workflows[].class_name` to be exported by the
+* deployed worker. Returns "" when the project declares no agents (the file is
+* not written then).
+*/
+declare const emitAgents: (agents: ReadonlyArray<AgentIR>) => string;
+/**
 * Emit `_generated/queues.ts` — the push-consumer registry the worker `queue()`
 * handler dispatches through. Maps each push queue's stable wrangler name (which
 * `batch.queue` carries) to its `defineQueue` definition + export name. Pull
@@ -2033,6 +2144,8 @@ declare const emitWorkflows: (workflows: ReadonlyArray<WorkflowIR>) => string;
 */
 interface EmitShardOptions {
   advisories?: ReadonlyArray<Finding>;
+  /** Agents declared via `defineAgent` exports in `lunora/agents.ts` — wires the typed `ctx.agents` producers. */
+  agents?: ReadonlyArray<AgentIR>;
   containers?: ReadonlyArray<ContainerIR>;
   /** The single `defineEnv(...)` contract declared in `lunora/env.ts` — applies the accessor to the worker `env` to populate `ctx.env`. */
   env?: EnvIR;
@@ -2080,6 +2193,7 @@ interface EmitShardOptions {
 }
 declare const emitShard: ({
   advisories,
+  agents,
   containers,
   env,
   flagKeys,
@@ -2165,6 +2279,16 @@ declare const emitVectors: (vectorIndexes: ReadonlyArray<VectorIndexIR>) => stri
 declare const emitWranglerCronTriggers: (crons: ReadonlyArray<CronJobIR>) => string[];
 /** Which capability methods the generated `defineApp` builder exposes — one flag per package-backed feature the app actually uses. */
 interface EmitAppOptions {
+  /**
+  * Inbound-email agents (`defineAgent({ onEmail })`) → wire the worker's
+  * top-level `email()` handler to `dispatchAgentEmail(...)` (from
+  * `@lunora/agent/inbound`), so received mail starts a durable run. Empty/absent
+  * ⇒ no wiring, byte-identical output for email-free (and agent-free) projects.
+  */
+  emailAgents?: ReadonlyArray<{
+    bindingName: string;
+    exportName: string;
+  }>;
   /** App depends on `@lunora/cloudflare-access` → emit `.access()` (wire the Cloudflare Access `resolveIdentity`, composed ahead of `@lunora/auth` when both are present). */
   hasAccess: boolean;
   /** App uses `@lunora/ai` / `ctx.ai` → emit `.ai()` (override the Workers AI binding backing `ctx.ai`). */
@@ -2209,6 +2333,17 @@ interface EmitAppOptions {
   jurisdiction?: JurisdictionIR;
   /** Project depends on the unscoped `lunorash` umbrella → import the runtime via `lunorash/runtime` instead of `@lunora/runtime`. */
   useUmbrella: boolean;
+  /**
+  * Voice-enabled agents (`defineAgent({ voice: … })`) → wire
+  * `options.voiceAgents`, mapping each agent's export name to its `VOICE_*`
+  * Durable Object namespace binding so the runtime exposes
+  * `/_lunora/voice/&lt;exportName>`. Empty/absent ⇒ no wiring, byte-identical
+  * output for voice-free (and agent-free) projects.
+  */
+  voiceAgents?: ReadonlyArray<{
+    bindingName: string;
+    exportName: string;
+  }>;
   /** An OpenAPI spec is emitted (`openapi.ts`) → wire `openApiSpec` into the worker. */
   wantsOpenApi: boolean;
   /** An OpenRPC spec is emitted (`openrpc.ts`) → wire `openRpcSpec` into the worker. */
@@ -2553,6 +2688,13 @@ interface CodegenResult {
   */
   advisories: ReadonlyArray<Finding>;
   /**
+  * Agents discovered from `defineAgent` exports in `lunora/agents.ts` — the
+  * list the config layer reconciles into wrangler's `workflows[]` array (an
+  * agent compiles onto a Cloudflare Workflow). Agents are NOT Durable Objects,
+  * so this adds no binding or migration. Empty when the project declares none.
+  */
+  agents: ReadonlyArray<AgentIR>;
+  /**
   * Containers discovered from `defineContainer` exports in
   * `lunora/containers.ts` — the list the config layer reconciles into
   * wrangler's `containers[]`, `CONTAINER_*` Durable Object bindings, and
@@ -2566,6 +2708,8 @@ interface CodegenResult {
   */
   cronTriggers: ReadonlyArray<string>;
   generated: {
+    /** WorkflowEntrypoint classes for declared agents (`_generated/agents.ts`); `""` (and not written) when no agents are declared. */
+    agents: string;
     api: string; /** Fluent worker-composition builder (`_generated/app.ts`) — `defineApp()`. Always written. */
     app: string;
     /** Partial-replication collection factories (`_generated/collections.ts`); `""` (and not written) unless the project declares shapes and installs `@lunora/db`. */
@@ -2661,4 +2805,4 @@ declare const secretKindOf: (value: string) => string | undefined;
 /** A redacted preview of a secret value — first 4 chars plus its length, never the full value. */
 declare const redact: (value: string) => string;
 declare const VERSION = "0.0.0";
-export { type AuthApiCallIR, CONTAINERS_FILENAME, CodegenDiagnosticError, type CodegenOptions, type CodegenResult, type ContainerIR, type CronJobIR, type DriftChange, type EmitAppOptions, FLAGS_FILENAME, type FieldSnapshot, type FlagsIR, type FunctionIR, GENERATED_HEADER, type HttpRouteIR, type IndexIR, type IndexSnapshot, type InsertWriteIR, LUNORA_ERROR_CODES, type LintSchemaOptions, MUTATORS_FILENAME, type MaskProcedureIR, type MigrationIR, type MutatorIR, OPENRPC_VERSION, type OpenApiEmitInput, type OpenRpcEmitInput, type ProjectIR, QUEUES_FILENAME, type QueryReadIR, type QueueIR, type R2sqlCallIR, type RelationSnapshot, type RlsMetadataIR, type RlsPolicyIR, type RlsProcedureIR, type RlsRoleIR, SCHEMA_SNAPSHOT_FILENAME, SCHEMA_SNAPSHOT_VERSION, SHAPES_FILENAME, type SchemaDrift, type SchemaDriftDecision, type SchemaIR, type SchemaSnapshot, SchemaSnapshotParseError, type ShapeIR, type StorageRuleIR, type StorageRulesMetadataIR, type TableIR, type TableSnapshot, VERSION, type ValidatorIR, type VectorIndexIR, WORKFLOWS_FILENAME, type WorkflowIR, type WranglerVariableIR, buildOpenApiDocument, buildOpenRpcDocument, buildSchemaSnapshot, createCodegenProject, diagnosticAt, diffSchemaSnapshots, discoverAuthApiCalls, discoverContainers, discoverCrons, discoverFlags, discoverFunctions, discoverHttpRoutes, discoverInserts, discoverMaskProcedures, discoverMigrations, discoverMutators, discoverNondeterministicCalls, discoverQueries, discoverQueues, discoverR2sqlCalls, discoverRlsMetadata, discoverRlsProcedures, discoverSchema, discoverShapes, discoverStorageRulesMetadata, discoverWorkflows, emitApi, emitApp, emitCollections, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitOpenApi, emitOpenApiModule, emitOpenRpc, emitOpenRpcModule, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers, evaluateSchemaDrift, formatAdvisories, lintSchema, parseSchemaSnapshot, redact, refreshCodegenProject, runCodegen, schemaFromIr, secretKindOf, serializeSchemaSnapshot, validatorIrToJsonSchema };
+export { AGENTS_FILENAME, type AgentIR, type AuthApiCallIR, CONTAINERS_FILENAME, CodegenDiagnosticError, type CodegenOptions, type CodegenResult, type ContainerIR, type CronJobIR, type DriftChange, type EmitAppOptions, FLAGS_FILENAME, type FieldSnapshot, type FlagsIR, type FunctionIR, GENERATED_HEADER, type HttpRouteIR, type IndexIR, type IndexSnapshot, type InsertWriteIR, LUNORA_ERROR_CODES, type LintSchemaOptions, MUTATORS_FILENAME, type MaskProcedureIR, type MigrationIR, type MutatorIR, OPENRPC_VERSION, type OpenApiEmitInput, type OpenRpcEmitInput, type ProjectIR, QUEUES_FILENAME, type QueryReadIR, type QueueIR, type R2sqlCallIR, type RelationSnapshot, type RlsMetadataIR, type RlsPolicyIR, type RlsProcedureIR, type RlsRoleIR, SCHEMA_SNAPSHOT_FILENAME, SCHEMA_SNAPSHOT_VERSION, SHAPES_FILENAME, type SchemaDrift, type SchemaDriftDecision, type SchemaIR, type SchemaSnapshot, SchemaSnapshotParseError, type ShapeIR, type StorageRuleIR, type StorageRulesMetadataIR, type TableIR, type TableSnapshot, VERSION, type ValidatorIR, type VectorIndexIR, WORKFLOWS_FILENAME, type WorkflowIR, type WranglerVariableIR, buildOpenApiDocument, buildOpenRpcDocument, buildSchemaSnapshot, createCodegenProject, diagnosticAt, diffSchemaSnapshots, discoverAgents, discoverAuthApiCalls, discoverContainers, discoverCrons, discoverFlags, discoverFunctions, discoverHttpRoutes, discoverInserts, discoverMaskProcedures, discoverMigrations, discoverMutators, discoverNondeterministicCalls, discoverQueries, discoverQueues, discoverR2sqlCalls, discoverRlsMetadata, discoverRlsProcedures, discoverSchema, discoverShapes, discoverStorageRulesMetadata, discoverWorkflows, emitAgents, emitApi, emitApp, emitCollections, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitOpenApi, emitOpenApiModule, emitOpenRpc, emitOpenRpcModule, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers, evaluateSchemaDrift, formatAdvisories, lintSchema, parseSchemaSnapshot, redact, refreshCodegenProject, runCodegen, schemaFromIr, secretKindOf, serializeSchemaSnapshot, validatorIrToJsonSchema };