@lunora/agent is Lunora's durable-agent primitive. defineAgent declares a
model + tools + memory; the definition compiles onto a Cloudflare Workflow
where each LLM turn and each tool call is a named durable step, and every
message persists idempotently into Durable Object (DO) SQLite thread tables. The client
subscribes to the thread query and watches the conversation stream in live, so
there is no new transport and no HTTP streaming infrastructure to run.
pnpm add @lunora/agentDeclaring an agent
The following file declares a support agent with one tool:
// lunora/agents.ts
import { defineAgent, defineAgentTool, jsonSchema } from "@lunora/agent/core";
export const support = defineAgent({
instructions: "You are a helpful support agent.",
maxTurns: 8,
model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast", // Workers AI id, AI SDK model, or (env) => model
tools: {
getWeather: defineAgentTool({
description: "Look up the current weather for a city.",
execute: async ({ city }, { idempotencyKey, run, threadKey }) => {
// `run` dispatches any Lunora function; `idempotencyKey` is the
// durable step name — dedupe side effects on it.
return run({ __lunoraRef: "weather:lookup" }, { city });
},
inputSchema: jsonSchema({ properties: { city: { type: "string" } }, required: ["city"], type: "object" }),
}),
},
});Declaring an agent is enough: codegen auto-registers the runtime functions the
durable loop persists through (agents:agentAppendMessage, agents:agentEnsureThread,
agents:agentPatchThread, agents:agentResolveApproval) plus the public thread
queries (agents:agentMessages, agents:agentThread, agents:agentApprovalGrants)
and the approval-grant revoke (agents:agentRevokeApprovalGrant), and wires the typed
ctx.agents.<name> producer.
lunora/agents.ts is evaluated when the Worker starts, and Cloudflare rejects a Worker
whose startup takes more than 1 s of CPU. Import from @lunora/agent/core there: it
carries defineAgent, defineAgentTool, defineSkill, functionTool and a jsonSchema
the AI SDK accepts, without the agent loop or the AI SDK (about 325 KiB minified for generateText
and jsonSchema alone, roughly 100 KiB of it zod), which
load on an agent's first run. The @lunora/agent barrel and jsonSchema from ai or
@lunora/ai put all of that back into startup. @lunora/agent/sandbox is light as well;
a tool only the barrel exports (webSearchTool, requestSecretTool, mcpTools,
codeTool, …) still needs the barrel.
Merge the thread tables into your schema. They auto-prefix to
agent_threads / agent_messages and can never collide with app tables:
// lunora/schema.ts
import { defineSchema } from "@lunora/server";
import { agentExtension } from "@lunora/agent/component";
export default defineSchema({/* your tables */}).extend(agentExtension);Scaffold a new agent with the generator (appends to lunora/agents.ts,
creating it if missing, and wires the worker entry):
vis generate lunora-agent --name=supportRunning + observing
The following snippets start a run from a mutation or action, then subscribe to the thread from the client:
// inside a mutation or action:
const { id } = await ctx.agents.support.run({ input: message, owner: ctx.auth.userId, threadKey, title: "Support chat" });
// client: subscribe to the thread — user turns, tool calls, tool results and
// assistant replies stream in as they persist (reactive subscription, so it
// survives reconnects and multiple observers for free):
useSubscription(api.agents.agentMessages, { key: threadKey });Reuse the same threadKey to continue a conversation; the loop reads the
persisted history each turn.
ctx.agents.<name> is the typed producer surface on Mutation/Action ctx:
| Method | Does |
|---|---|
run(params) | Start (or continue) a run; returns { id } (the Workflow instance id). |
cancel(id) | Terminate the in-flight instance and mark the thread "cancelled". |
status(id) | Read the instance's current status. |
sendEvent(id, evt) | Deliver an event to a hibernated run (the primitive that human-in-the-loop (HITL) approvals build on). |
Loop control
defineAgent exposes the AI SDK's loop-shaping seams, evaluated per turn inside
the durable loop:
maxTurns: hard cap on LLM turns. Hitting it stops the run withresult.stopped === "maxTurns".stopWhen: a stop condition (e.g.stopWhen: hasToolCall("finalize")); stopping this way reportsresult.stopped === "stopCondition". A clean final answer (no pending tool calls) reportsresult.stopped === "final".prepareStep: mutate the request just before a turn (swap the model, trim messages, force a tool). Must be deterministic, because it runs on replay.repairToolCall: repair a malformed tool call the model emits (AI SDKexperimental_repairToolCall): given{ toolCall, error, tools, inputSchema }, return a corrected call ornullto give up. Runs inside the turn, so keep it deterministic.compaction: automatic history compaction. Setcompaction: { maxMessages }and once the thread history exceedsmaxMessages, the loop summarizes the older messages (all but the most recentkeepRecent, defaultceil(maxMessages / 2)) into one system-message brief and prompts the model with that brief plus the recent tail, so context stays bounded as a conversation grows. The summary is produced inside the turn's memoized durable step (replay-safe) by a cheapercompaction.modelif set, else the agent's model;prepareStepstill runs after and can override further. Absent, the full history is sent every turn.output: aFlexibleSchema(zod orjsonSchema(...)) for a structured final answer; the typed value is surfaced onresult.output.onStepFinish: a callback after each turn (observability/side channels).usage: token usage is accumulated across turns and surfaced on the run result and persisted onto the thread. Beside the input, output and total counts it carriescacheReadTokens,cacheWriteTokensandreasoningTokenswhen the provider reports them. Those are subsets of the totals and are never added on top. A bucket no turn reported is absent, and a thread written before these fields existed reads as absent too, not as zero.statussays whether the report covers the run:completewhen every turn reported all of its usage,partialwhen some turn reported only part of it, andunavailablewhen no turn reported any. A turn that reported nothing still counts toward the status, so a run with one such turn is never persisted ascomplete. A thread written beforestatusexisted carries none, and reads as unknown.telemetry: an ai@7TelemetryOptionshanded to every turn; settelemetry.integrationsto trace turns and tool calls. The@lunora/agent/telemetrysubpath ships ready-made ones:consoleTelemetry(zero-dependency),combineTelemetry,otlpTelemetry(shipsgen_ai.*spans over OTLP to any collector), and the dependency-injectedsentryTelemetry/braintrustTelemetrybridges (privacy-safe by default, with no prompt/output recorded without opt-in).
import { hasToolCall } from "@lunora/ai";
export const support = defineAgent({
maxTurns: 6,
model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
output: jsonSchema({ properties: { answer: { type: "string" }, confidence: { type: "number" } }, required: ["answer"], type: "object" }),
prepareStep: async ({ stepNumber }) => (stepNumber === 0 ? { toolChoice: "required" } : {}),
stopWhen: hasToolCall("finalize"),
});Telemetry integrations
The @lunora/agent/telemetry subpath ships ready-made Telemetry integrations
for the telemetry.integrations array; each traces every LLM turn and tool call
in the durable loop. They are privacy-safe by default: recordInputs and
recordOutputs both default to false, so no prompt, message, tool argument,
generated text, or tool result is recorded without an explicit opt-in. Only
structural metadata is recorded (model id, finish reason, token counts, tool
name, timing, success/failure).
consoleTelemetry: a zero-dependency structured console tracer.combineTelemetry: fan the lifecycle out to several integrations and nest their execution wrappers (executeLanguageModelCall,executeTool) right-to-left, so the first integration is outermost.sentryTelemetry/braintrustTelemetry: dependency-injected bridges. You pass your own initialized Sentry namespace / Braintrust logger, so the heavy vendor SDK is never imported by Lunora. Sentry turns model calls and tool executions into spans (op: "gen_ai.generate"/"gen_ai.execute_tool") and routes errors toSentry.captureException; Braintrust logstype: "llm"/type: "tool"logger.tracedspans. A model span's token usage goes inmetricsunder Braintrust's names (prompt_tokens,completion_tokens,tokens), withprompt_cached_tokens,prompt_cache_creation_tokensandcompletion_reasoning_tokensadded when the provider reports them. A call whose usage is unavailable logs no metrics, and itsmetadatacarrieslunora.usage.status.otlpTelemetry: ships agen_ai.*generation span per model turn (and a span per tool call) over OTLP-over-HTTP to any collector, the Lunora cloud or your own, so agent generations land in the same trace store as the rest of your app's telemetry. Zero SDK dependency (it justfetches). Pass{ endpoint, token }(read from the injectedLUNORA_OTLP_ENDPOINT/LUNORA_OTLP_TOKENon the platform) and, optionally, atraceIdto group one run's spans into a single trace. Two deliberate differences from the SDK bridges: noonError(a failed span already carriesstatus.code === 2) and flat spans (OTLP has no ambient parent to nest under).
import { defineAgent } from "@lunora/agent";
import { combineTelemetry, consoleTelemetry, otlpTelemetry, sentryTelemetry } from "@lunora/agent/telemetry";
import * as Sentry from "@sentry/cloudflare";
export const support = defineAgent({
name: "support",
telemetry: {
isEnabled: true,
integrations: [combineTelemetry(otlpTelemetry({ endpoint: env.LUNORA_OTLP_ENDPOINT, token: env.LUNORA_OTLP_TOKEN }), consoleTelemetry())],
},
// ...model, tools, loop control
});consoleTelemetry, combineTelemetry, and otlpTelemetry have zero runtime
dependencies; install @sentry/cloudflare / braintrust only if you use those
bridges.
Concurrency + cancellation
Only one run owns a thread at a time: two concurrent runs on the same
threadKey would interleave their messages into the shared per-thread sequence
counter. The onConcurrentRun policy decides what happens when a run starts on
a thread that already has a different instance in flight:
"reject"(default): fail the new run fast with aCONFLICTerror."replace": terminate the in-flight instance and take the thread over."queue": park the new run behind the one in flight (FIFO, up to five deep) and hibernate it until the thread is handed over. Each parked run is a live Workflow instance waiting on an event, so the depth cap is a real resource bound — a sixth start is rejected exactly as"reject"would be, and a parked run waits at most 12 hours for its turn. A"replace"arriving later supersedes the run in flight, not the queue. A dispatch with no instance id (the inbound-email / inbound-channel paths) cannot be parked — nothing later could tell it apart from another such dispatch to wake it — so"queue"rejects those.
A workflow replay re-enters under the same instance id and is never treated as a concurrent run.
Cancel from the server with ctx.agents.<name>.cancel(instanceId), or from the
client through the framework hooks (below). cancel() terminates the in-flight
instance and moves the thread to "cancelled".
Human-in-the-loop approvals
Gate a side-effecting tool behind a human decision with needsApproval (a
boolean, or a per-input predicate; this mirrors the AI SDK's needsApproval):
chargeCard: defineAgentTool({
description: "Charge the customer's saved card.",
execute: async ({ amount }, { run }) => run({ __lunoraRef: "billing:charge" }, { amount }),
inputSchema: jsonSchema({ properties: { amount: { type: "number" } }, required: ["amount"], type: "object" }),
needsApproval: ({ amount }) => amount > 5000,
}),When the gate resolves truthy the run pauses: the thread moves to
"awaiting_input" and the workflow hibernates on approval:<toolCallId>, so
no compute is billed while it waits. A client resolves it via the
auto-registered agents:agentResolveApproval (the framework approve/reject
helpers dispatch it). On approve the tool runs exactly as normal; on reject it
is skipped and a tool result explaining the rejection is persisted so the next
turn recovers. Because needsApproval runs on replay, keep it deterministic
(no Date.now()/Math.random()).
Approve for the thread. agents:agentResolveApproval also accepts
decision: "approve_for_thread": it approves the paused call and records a grant
for that tool, so later calls to the same tool in the same thread run without
pausing. The approved tool result is marked approvalScope: "thread". The grants
are listed by agents:agentApprovalGrants and removed by
agents:agentRevokeApprovalGrant; a revoke applies to calls whose gate has not
resolved yet, never to one already in flight. A grant is per thread, not
per user or per app. Only the thread's verified owner can record one: on a thread
with no owner (an app that sets no identity) a plain approve or reject still
works for any caller, but approve_for_thread is refused, because a grant would
let anyone who knows the thread key skip the gate for every later call.
Once the paused call's approval window closes (approvalTimeout), a late approve_for_thread is
refused too: the run has already rejected that call, and no grant may outlive it.
An unanswered approval is not pending forever. The wait carries a timeout —
approvalTimeout on the agent config, default "3 days", clamped to one
week — and when it elapses the call is recorded as rejected ("approval
timed out") and the run continues down the normal rejection path. It has to: a
wait that outlived the thread's abandoned-run horizon would let a new run
reclaim the thread while the approval was still pending, so the approval could
never be answered at all. Size approvalTimeout to your on-call reality, and do
not assume an approval raised before a long weekend is still waiting on
Monday.
The approvals inbox. agents:agentPendingApprovals lists the caller's own
paused approvals (newest thread first, default 50), each carrying the
threadKey, instanceId and toolCallId that agentResolveApproval takes.
It is owner-scoped: an anonymous caller gets [], and ownerless threads are
never listed. The React useAgentApprovals hook subscribes to it. The inbox is not
exposed over the Model Context Protocol (MCP): MCP clients authenticate with a static deployment token, so a run
started over MCP has no owner and would never be listed.
Human-supplied secrets (requestSecretTool)
A tool that needs a credential the model does not have (an API key, a token)
asks the person for it with requestSecretTool. The run pauses on
awaiting_secret exactly as it does for an approval, and resumes once the owner
calls agents:agentSupplySecret (the value) or agents:agentDeclineSecret.
consumer names the one tool allowed to read the value. A consuming tool reads
it with withSecret:
import { defineAgent, defineAgentTool, requestSecretTool, withSecret } from "@lunora/agent";
import { jsonSchema } from "ai";
export const billing = defineAgent({
model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
tools: {
requestKey: requestSecretTool({ consumer: "charge", description: "Ask the user for their payment API key." }),
charge: defineAgentTool({
description: "Charge the card with the stored key.",
execute: (input, context) =>
withSecret(context, input.secretRef, async (apiKey) => {
const response = await fetch("https://payments.example/charge", { headers: { authorization: `Bearer ${apiKey}` } });
return { status: response.status };
}),
inputSchema: jsonSchema({ properties: { secretRef: { type: "string" } }, required: ["secretRef"], type: "object" }),
}),
},
});Setup: the value is sealed under the Worker secret LUNORA_SECRET_VALUE_KEY
(base64 of 32 bytes, from openssl rand -base64 32). Without it the pause cannot
store the value: put refuses with SecretValueKeyError. lunora deploy treats
the missing key as a required secret, aborting when it runs non-interactively,
and lunora env doctor reports it as an error: missing before .dev.vars has the key, unset while it still holds the placeholder. lunora dev seeds
.dev.vars.example with the key, so the check starts after the first dev run. Rotation,
and what point-in-time recovery does to a discarded value, are in the
platform's Secret values section.
The model receives { "secretRef": "…" } from the request. That ref is the
request's slot (<turn>:<tool-call id>). The client answers the pause with the
tool-call id it sees on it, and the server finds the one pending request for that
id. The slot is not the stored value and not the store's reference, and
the model passes it to the consuming tool. withSecret takes the value inside its
own durable step, returns only what the callback returns, and discards the value
as a second step, but only after a take that succeeded. A callback result that
carries the value (an echoed token, a header built from it) is refused: the call
fails with a LunoraError and the result is not journalled. A callback that throws
an error carrying the value is redacted before the error propagates, so the step's
retry, the failure the loop records and telemetry never see the value.
Each pause writes a request row, which is the authority for the request: pending,
supplied, declined, expired or consumed. Supply, decline, expiry and consumption
are each a compare-and-set on that row, so the owner's answer and the loop's
timeout cannot both win. The wait is armed for approvalTimeout, capped one minute
under a day, plus a 60-second grace, and a supply is refused once the request's deadline has passed, even if the
loop has not yet settled it. When the wait ends, the loop reads the row once. A
supply that landed before the timeout is honoured. A pending request becomes
expired, and a later supply is refused.
Guarantees. The value is absent from the message rows, the workflow journal,
the wake-up event, the supply mutation's return, the request log's redacted
arguments and the request table. The host ref is absent from all of those too:
it lives only in the request row and is never listed. The wake-up carries no
payload. A consuming call claims the value under its own step name: a retry of
that step re-reads it, and any other call gets "no longer available". Only the
tool named by consumer can read the value, and only in the thread that asked for
it. A call from any other tool, or in another thread, is refused without binding
the value, and the declared consumer can still use it afterwards. The consuming
tool fails once, deterministically, with no retry, if the value has expired.
Provider-issued tool-call ids can repeat across runs, so a later run that reuses a
finished run's id starts a new request and discards the old value.
Supplying is owner-only and fails closed: an anonymous caller, and any caller on
an ownerless thread, is refused, because an ownerless thread is readable by anyone
who knows its key. A run with no owner that asks for a secret has nobody who can answer, so the call
is refused at once with a tool result saying so, rather than waiting out its deadline;
pass an owner to any run that uses requestSecretTool. A second supply, a supply after a decline or after a timeout,
or a supply on a thread paused before the request table existed, is a CONFLICT
and stores nothing.
When the wake-up is lost. A supply is committed when agentSupplySecret
returns, whether or not the wake-up that tells the paused run reached it. A wake-up
that fails after the supply committed is not rethrown, and the owner is not asked to
retry, because the retry would be a CONFLICT. If the wake-up truly never arrived,
the run does not notice until its wait ends at the deadline, where the loop reads
the row and honours the supply. The stored value is kept for the longer of 15
minutes and the time left to that deadline plus the grace. The deadline is capped
so that always fits the host's 24-hour ceiling, which is why a secret request waits
at most a day however long approvalTimeout is.
agents:agentSecretRequests({ threadKey }) lists a thread's requests for the
owner, with status, tool name, deadline and the label the model gave the request
(what the secret is for; absent on requests recorded before labels). It never
returns the ref or the value. The label is model-written text, trimmed and cut to
200 characters, and a blank label is refused as a tool error without pausing the
run. Render it as text, never as markup.
The framework chat hooks still derive the pending request from the
awaiting_secret message, and they do not read this list.
From a client. The framework chat hooks answer the request with
supplySecret(toolCallId, value) or declineSecret(toolCallId). The pending
request is an awaiting-secret entry in useAgentToolEvents, and it drops out
once the server retires it. supplySecret always sends onlineOnly: true, so the
value is never queued or persisted and the call rejects with OFFLINE_NOT_QUEUED
while the connection is down. The hook keeps no copy of the value.
const { events } = useAgentToolEvents({ api, threadKey });
const request = events.find((event) => event.type === "awaiting-secret");
if (request?.toolCallId !== undefined) await chat.supplySecret(request.toolCallId, apiKeyFromTheForm);Limits you must design for.
- The plaintext transits the supply mutation's arguments. The
secretargument is markedv.sensitive: the request log masks it, a rejected value is not echoed, and the generated reference is typed as sensitive. Span exporters are not covered by that masking, so do not let one record this mutation's arguments. - Offline queueing would persist the value. The
secretargument isv.sensitive, so the generated reference is always online-only: a directclient.mutation(agentSupplySecret, …)call is refused (OFFLINE_NOT_QUEUED) when the device is offline rather than queued into IndexedDB or AsyncStorage, and passingonlineOnly: falseis a type error and a runtimeBAD_REQUEST. - Point-in-time recovery can bring a discarded value back for the database's recovery window (30 days). Discard removes the value from the store, not from backups.
- "One use" means one claimant, not one read. The value stays readable by the
call that first took it until it is discarded or expires, so the consumer holds
the credential for that long. Within one call, read each request once:
withSecretnames its durable steps by call and request, so a second read returns the first read's result. A call that needs two secrets has two requests. - The value and the request row are not one commit. The host writes the value through its own storage handle, outside the mutation's transaction. The supply therefore stores the value first and then moves the row, and it discards the value if the row write fails or the deadline has passed. A process that dies between the two leaves an unreadable value that expires with its TTL.
- Threads paused before the request table existed have no request row. They fail
closed: a supply is refused with
CONFLICT, and the wait settles as expired. - The consumer must be called by the model directly. A tool reached through a
codeToolscript or anasToolsub-agent runs under another step name or thread, so itswithSecretis refused. The call fails closed with "no longer available". - Rotating the key. Set
LUNORA_SECRET_VALUE_KEY_PREVIOUSto the current key andLUNORA_SECRET_VALUE_KEYto a new one, then deploy. Wait until every value sealed under the old key has expired (a lifetime is at most 24 hours), then unsetLUNORA_SECRET_VALUE_KEY_PREVIOUSand deploy. The platform's Secret values section has the full sequence. - Never return, log or throw the value from
use.traceToolExecutionrecords a tool's input and output, and a thrown error reaches the tool row. - Only shards on a target that rates
secretValuesnative can hold a value (Cloudflare today). Elsewhere the supply mutation refuses withNOT_IMPLEMENTED. - The value lives at least 15 minutes after it is supplied, and longer only up to the request deadline plus the 60-second grace (see Human-supplied secrets). The 15 minutes cover the gap to the model's next turn, not a long pause, so the consuming call has to follow soon after the supply.
Client hooks
Every framework adapter ships two hooks over the same live subscription. The
generated api drives them; you pass the run/send and cancel mutation
references your app exposes.
useAgent(useAgent/createAgent/agent) is the thin driver:{ run, cancel, pending, status, thread }.run(input, args?)dispatches the run mutation with{ input, threadKey }merged overrunArgs;cancel()terminates the in-flight instance (a no-op when nothing is running or no cancel ref was supplied);status/threadflow live fromagents:agentThread.useAgentChatis the batteries-included chat surface:{ send, approve, approveForThread, reject, supplySecret, declineSecret, approvalGrants, revokeGrant, cancel, messages, status, streamingText }.sendappends an optimistic user turn then starts/continues the run;approve/rejectresolve a pending tool approval;messagesis the live thread.approveForThreadisapproveplus a thread grant for that tool.approvalGrantsis the live list of the thread's grants, andrevokeGrant(toolName)removes one, so a grant is never visible without a way out.supplySecret(toolCallId, value)anddeclineSecret(toolCallId)answer arequestSecretToolpause. The value is sent withonlineOnly: true, so it is never queued or persisted, and the hook keeps no copy. A pending secret request is anawaiting-secretentry inuseAgentToolEvents, and it drops out once the server retires its marker.
// React
const chat = useAgentChat({ api, cancel: api.chat.cancelRun, send: api.chat.startRun, threadKey });
chat.send("Refund my last order");
if (chat.status === "awaiting_input") chat.approve(toolCallId);
// A secret request: supply the value (online-only) or refuse it.
await chat.supplySecret(toolCallId, apiKeyFromTheForm);
await chat.declineSecret(toolCallId);The same hooks exist as Vue composables (useAgent/useAgentChat), Solid
primitives (createAgent/createAgentChat), and Svelte store factories
(agent/agentChat).
Token streaming. The turn seam has a streaming counterpart (streamText
via createStreamGenerate) and the hooks expose a stream option feeding
useAgentChat's live streamingText. The server-side token sink
(onTokenDelta → transport) is a wired-but-dormant seam: until it is threaded
onto a live transport the loop takes the byte-identical non-streaming path, so
streamingText stays empty and messages still arrive per-turn over the thread
subscription. Turn-granular streaming works today; sub-turn token streaming is
the remaining follow-up.
Synced state
Beyond the message log, a run carries a small synced state object: a
setState-style scratchpad (the plan, a step counter, a progress summary) that
a tool writes and a client watches live. Seed it with initialState on the
agent (set once, on thread creation, where first writer wins so a replay never
re-seeds), then read and write it from any tool's ctx:
const planner = defineAgent({
initialState: { applied: [], plan: [], step: 0 },
model: "@cf/meta/llama-3.1-8b-instruct",
tools: {
advance: defineAgentTool({
description: "Record the next step of the plan.",
execute: async ({ note }, { getState, idempotencyKey, setState }) => {
const current = (await getState()) ?? { applied: [], plan: [], step: 0 };
const applied = current.applied as string[];
// Idempotent read-modify-write: skip if this durable step already
// applied. A retried step re-reads the ALREADY-written state, so
// dedupe on `idempotencyKey` or the counter double-advances.
if (applied.includes(idempotencyKey)) {
return "recorded";
}
await setState({
applied: [...applied, idempotencyKey],
plan: [...(current.plan as string[]), note],
step: (current.step as number) + 1,
});
return "recorded";
},
inputSchema: jsonSchema({ properties: { note: { type: "string" } }, required: ["note"], type: "object" }),
}),
},
});setState(state) is an absolute replace (not a patch). The value you pass
must be replay-stable: a constant or derived purely from the tool's
input, never from Date.now() / Math.random(). A step that fails mid-body is
retried at-least-once and re-runs the whole execute against state a prior
attempt may already have written, so re-applying a replay-stable value is a
no-op and a replay converges. A value derived from getState() is not
replay-stable: a naive read-modify-write (setState({ step: (await getState()).step + 1 })) double-advances on a retry because the retry
re-reads the already-written value; dedupe it on idempotencyKey as above.
getState() reads the thread's current state through the owner-gated
agents:agentState query, the same identity gate as the message reads, so only
the thread's owner sees it.
On the client, subscribe with useAgentState, a thin wrapper over the
agents:agentState subscription that re-renders whenever a tool calls
setState (a dedicated query with a per-socket JSON memo suppresses no-op
pushes on unrelated thread writes):
// React — generic over your app's state shape
const { state, error } = useAgentState<PlanState>({ api, threadKey });
// state?.step, state?.plan — live, undefined until first seeded/pusheduseAgentState ships in @lunora/react today; the Vue/Solid/Svelte
equivalents are a follow-up (the server surface and the subscription are already
in place). State sync is opt-in: an agent without initialState and tools
that never touch getState/setState behaves exactly as before, and the
state column stays absent on its threads.
Tools from anywhere
Beyond inline defineAgentTool, three helpers pull tools from other surfaces.
Each returns an AgentToolDefinition you drop into the tools map:
functionTool: expose a Lunora function as a tool.executedispatches the referenced function;inputSchemashould mirror its argument validator.agentAsTool: adapt a declared agent into a tool so a supervisor can delegate to specialists. It starts a child run on the child agent's Workflow binding, polls to completion, and returns the child's final answer. ChildthreadKey+ instance id derive from the parent's (replay-stable), so a retried step reuses the same child run (idempotent). Options:name(child export name →AGENT_<NAME>binding),description,maxPolls(default 600),pollIntervalMs(default 500) — together a five-minute wall-clock budget, past which the child is terminated and the parent is told it did not finish. The child thread inherits the parent run'sowner, so it stays under the same row-level security (RLS) scope. A child that runs out of turns reports its turn cap rather than returning an empty answer.mcpTools: adapt the tools an MCP server lists. Pass a pre-connectedclient(the SSE/HTTP transport cannot run in workerd), optionally filtered withonlyand namespaced withprefix.
import { agentAsTool, functionTool, mcpTools } from "@lunora/agent";
tools: {
lookupOrder: functionTool("orders:byId", { description: "Look up an order by id.", inputSchema }),
research: agentAsTool({ description: "Delegate deep research.", name: "researcher" }),
...mcpTools({ client: docsClient, prefix: "docs_" }),
}Sharded apps
A run records the shard its tools use, and only the code that starts the run sets it.
Any shardKey in the run input is dropped, because that input may come from a client,
an email or a webhook.
| Started by | Tools run on |
|---|---|
ctx.agents.<name>.run(...) in a mutation or action | that function's shard |
ctx.scheduler.runAfter / runAt with agents.<name> | the scheduling shard, unless you pass { shardKey } |
an agentAsTool parent | the parent run's shard |
| inbound email / a channel | what your resolveEmailShard / onInbound.resolveShard returns; the default shard without one |
a client's agents:agentRun | the default shard |
| a cron | the shardKey in its args, else the default shard (the args are yours, not a client's) |
functionTool targets and semantic memory sources (memory.source, the agentic
searchMemory / readMemory tools) dispatch to the run's shard, so a tool over a
.shardBy("organizationId") table sees the tenant's rows. A hand-written
defineAgentTool uses the default shard unless it passes the run's shard:
run(api.orders.byId, args, { shardKey: context.shardKey }).
The agent's own state stays on the default shard: threads, messages, synced state,
secrets, and episodic and graph memory. Those are agents:* tables without a tier
modifier, written by the loop on the default shard, and the client hooks subscribe there.
Episodic and graph recall read the same shard their run-end upserts write. Semantic
memory differs because its source is your function over your tables. For the same
reason the worker refuses agents:agentRun (400) on any other shard, including as a
fan-out: its in-flight check reads the thread table. To run a tenant's tools, start the
run from a mutation on the tenant's shard with ctx.agents.<name>.run.
Sandbox tools (batteries-included browser + containers + filesystem)
These tools give an agent a headless browser, a sandboxed container, and
an R2-backed filesystem. Import them from @lunora/agent (or the
@lunora/agent/sandbox subpath) and drop them into tools; codegen does the
rest:
import { browserTool, containerTool, defineAgent, fsTool } from "@lunora/agent";
export const operator = defineAgent({
model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
tools: {
// One tool, every browser op — the model picks via `op`. `bucket` is
// required for `screenshot`/`pdf`: the render goes to R2 and the model
// gets its key back (see below).
browser: browserTool({ bucket: "SANDBOX_BUCKET", root: "renders" }),
// Talks to `ctx.containers.sandbox` (a `lunora/containers.ts` export).
sandbox: containerTool("sandbox"),
// A persistent R2-backed filesystem scoped to `agents/operator`.
fs: fsTool("SANDBOX_BUCKET", { root: "agents/operator" }),
},
});-
browserTool(opts?)exposes Cloudflare Browser Rendering as one tool. The model setsoptoscreenshot|pdf|content|scrapeplus aurl;content/scrapereturn HTML.screenshot/pdfwrite the render toopts.bucketand return{ bytes, key, mediaType }— not the bytes: a tool result is capped at 4000 characters before it is persisted, and base64 of even a small PNG is several times that, so inline bytes arrived truncated mid-string after the render had already been billed. Each render lands at<root>/<threadKey>/<toolCallId>.<ext>, derived only from replay-stable identifiers, so a retried step overwrites its own object instead of leaking one per attempt. Without abucketthose two ops are refused as a tool result and never dispatched, so nothing is billed. The model picks theurlwith no allowlist, so this is a server-side request forgery (SSRF) surface: a prompt-injected model can aim it at an internal/link-local endpoint. It runs unattended by default; passopts.needsApproval(a boolean or a predicate) to gate it. -
containerTool(name, opts?)talks to the declared container atctx.containers.<name>.op: "fetch"sends an HTTP request (path,method,body);op: "exec"runs a command (routed as aPOST /__lunora/execthe container app serves). Command execution is gated behind a human approval by default: anexec, and anyfetchusing a non-idempotent method (POST/PUT/PATCH/DELETE), since a prompt-injected model could otherwise reach some other mutating route unattended. Afetchcannot reach the exec route at all —@lunora/containerreserves/__lunora/*on the handle — so there is no path spelling that runs a command around the gate. AGET/HEAD/OPTIONSfetch(including a method-omitted one) to any other route runs unattended, so scope the container's read routes accordingly. Passopts.needsApproval(a boolean or a predicate over the input) to widen or disable the gate. Anexecthat fails to run at all is returned to the model as text rather than thrown, so a command whose result was lost is not re-executed by its own throw. That is not exactly-once: the tool call reaches the container as a dispatch, and a dispatch whose reply is lost after the command ran fails the tool's durable step, whose retry execs again. The sandbox action takes noidempotencyKey— there is nothing on an action ctx to dedupe one against, and the approval decision is memoized in its own step, so the gate does not re-ask either. Make a command that cannot afford to run twice idempotent, or have it mark its own completion inside the container.Every call is addressed to one instance per thread, not a random pool member, so
exec("pnpm install")andexec("pnpm test")on the same thread share a filesystem. Size the container'smaxInstancesfor the number of threads you expect to be live at once.Time budgets and the ceiling that remains. A dispatch defaults to a 30s cap, and a dispatch that times out answers 503 — transient, so the tool's durable step rethrows and the host retries it, dispatching the same call again while the first is still running. For an
execthat is the command running twice. The sandbox therefore dispatches a browser op with a 150s budget over a 120s navigation deadline, and a container op with a 150s budget over a 120sexecdeadline, so the inner deadline is always the one that fires and the op ends rather than being abandoned. That widens the window; it does not make anexecexactly-once. A command that outlives its 120s deadline is killed, and one that somehow outlives the dispatch budget on top of that is still re-dispatched by the step retry. Removing that ceiling needs a fire-then-poll shape, which needs somewhere durable to record the op id — which an action ctx does not have.A container
fetchreads at most 1MB of the response before the read is cut and the reader cancelled (the result is marked[truncated at … bytes]), the same boundexechas always had: the body is buffered in a 128MB isolate shared with every other in-flight request. -
containerFsTool(name, opts?)has the samels/read/write/rm/statops asfsTool, but on the container's own disk, the onecontainerTool'sexecruns against. It addresses the same per-thread instance, so a file the model writes is the file its next command sees. The container needssandbox: trueinlunora/containers.ts(see the container docs). Paths are scoped underopts.root(default/workspace), awritecreates missing parent directories, and the writing ops are gated by default. -
fsTool(bucket, opts?)exposes a persistent, R2-backed virtual filesystem.opisls/read/write(withcontent) /rm/stat, over the R2 binding namedbucket. Every path is scoped underopts.root(e.g."agents/coder"); a..that would escape the root is rejected server-side, so the model can only touch its own prefix. The writing ops (write/rm) are gated behind a human approval by default; reads run unattended. workerd has no real shell, so this is object-store file I/O, not a POSIX shell. The app must declare ther2_bucketbinding inwrangler.jsonc(the op throws a directed error until it is wired).
Why it needs little wiring: a tool's execute runs inside the durable tool step,
which has no ctx.browser/ctx.containers. Both tools instead dispatch to a
single internal action, sandbox:invoke, that codegen auto-registers the
moment a lunora/ file imports either helper (no re-export boilerplate). That
action runs on an action ctx, which is where ctx.browser lives (and
ctx.containers rides every ctx once you declare a container). Importing
browserTool also makes codegen provision the BROWSER wrangler binding.
browserTool still needs ctx.browser wired the same way a direct
@lunora/browser user does: supply a config.browser thunk
(createBrowser({ binding: env.BROWSER, playwright: () => import("@cloudflare/playwright") }),
loading the optional peer on first use) to createShardDO(); codegen never
wires that peer, so the browser op throws a directed error until it is wired.
Payloads are replay-stable, so a workflow replay re-encodes identical bytes to
identical text.
Web search (webSearchTool)
webSearchTool(opts?) lets the model search the web through the Cloudflare
Web Search API (ctx.ai.websearch in @lunora/ai). The model passes a
query; the tool returns up to limit results (default 5, max 10), each with
a url, a title and, when the provider has one, a description.
import { defineAgent, webSearchTool } from "@lunora/agent";
export const researcher = defineAgent({
model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
tools: { search: webSearchTool({ provider: "exa" }) },
});It calls the AI binding directly from the tool's durable step: a search is a
read, so a step retry only repeats the query, and there is no dispatcher action
to register. A missing binding, a rejected request or an unreadable response
comes back to the model as the tool result, so the run carries on; a throttled
or failed search throws and is retried, and a gateway or credential problem
(UNAUTHORIZED / FORBIDDEN / NOT_FOUND) fails the run so you see it.
A search bills a provider key stored on the gateway (byokAlias, else the
default alias) or, without one, AI Gateway credits; gatewayId overrides
the gateway.
Code mode (codeTool)
Normally the model calls one tool per turn, a round-trip each. codeTool lets
it compose several tool calls in one turn as a script, feeding a later
call's input from an earlier call's output:
import { codeTool, defineAgent, functionTool } from "@lunora/agent";
export const analyst = defineAgent({
model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
tools: {
run: codeTool({
findUser: functionTool("users:byEmail", { description: "Look up a user by email.", inputSchema }),
recentOrders: functionTool("orders:recent", { description: "List a user's recent orders.", inputSchema }),
}),
},
});The model writes steps: [{ id, tool, input }]; a later input references an
earlier output with { "$from": "<stepId>", "$path": "optional.dot.path" }. So
in one turn it can findUser, then feed { "$from": "u", "$path": "id" } into
recentOrders. The whole script runs in a single codeTool call and returns
each step's output plus the final one.
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. This applies to the value a later step reads through
{ "$from": … } exactly 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.
This is a safe interpreted data-flow between the whitelisted tools you hand
codeTool, not arbitrary JavaScript, so there is no eval or isolate and it
runs natively in workerd. Each composed tool still dispatches through the same
durable context a normal call gets, keeping its RLS, and each step's resolved
input goes through the same check a top-level call gets — no more and no less.
That check is only as strong as the tool's own inputSchema: a schema carrying
a validator (a Standard Schema such as zod/valibot, or
jsonSchema(schema, { validate })) rejects a wrong-typed argument before the
tool runs, while a bare jsonSchema(schema) validates nothing — the AI SDK
treats a validator-less schema as pass-through, on this path and on the
top-level one alike. Without a validator the argument reaches the tool and its
own rejection (a dispatched function's 400, say) is recorded as a tool error
the model reads and corrects on its next turn, rather than failing the run.
A composed tool's own needsApproval gate is not carried, because a script
runs its steps in one shot and cannot hibernate mid-way for a human decision.
codeTool therefore refuses at construction to compose any tool that declares
one — the agent module throws on load rather than silently bypassing the gate.
Expose that tool as a normal top-level tool, or gate the whole script with
codeTool's own needsApproval.
The same holds for a requestSecretTool: a script step cannot pause for the owner
to supply the value, so codeTool refuses it too. Expose it as a top-level tool.
Scripts are capped at maxSteps (default 16); a
longer script is rejected (code_tool_too_many_steps) rather than run as a
prefix, so the model can split the work instead of silently losing its trailing
steps. To run model-authored code rather than compose tools, use
jsCodeTool.
Sandboxed JavaScript (jsCodeTool)
jsCodeTool runs a script the model writes — the body of an async function —
in a Worker Loader isolate (Dynamic Workers on Cloudflare and on celld), and
returns what it returns plus its console output:
import { defineAgent, jsCodeTool } from "@lunora/agent";
export const analyst = defineAgent({
model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
tools: { js: jsCodeTool({ cpuMs: 1000 }) },
});
// The tool result is `{ value, logs }`, or `{ error, logs }` when the script
// threw, did not parse, returned something that is not JSON, or ran out of time.The isolate gets no network (globalOutbound: null), no bindings and
no tools, and cpuMs (default 1000) plus a 30-second wall clock bound each
run. So it is for computation over what the model already has — arithmetic,
parsing, reshaping data — not a way to reach anything. A failure is a result,
not a throw, so the durable step does not retry a script that will fail the same
way again.
Importing jsCodeTool in lunora/ makes codegen provision the
worker_loaders binding (LOADER) and gate the target on
the workerLoaders capability: Cloudflare and celld rate it native, and the
Node host has no isolate sandbox, so target: "node" refuses it with a
platform_unsupported_feature diagnostic.
Limits
- A script cannot call the agent's tools. The only way out of a loaded
isolate is a service binding, and a call through one arrives as a fresh
invocation of the worker: it has neither the run's durable step (so nothing
it does is memoized or replay-safe) nor the caller's identity (so RLS would
not apply). To chain tool calls in one turn, use
codeTool; to compute over their results, let the model pass them intojsCodeToolas literals. - Nothing persists between runs. Each call loads a fresh isolate and discards it, so module-level state does not survive to the next call.
- The result must be JSON. A
bigint, a cycle or a function comes back aserror, and aDateas its ISO string. - Output is capped. A result over 256 KiB comes back as
error(the whole result is memoized as a durable step result, which the host caps at 1 MiB), andconsoleoutput at 100 entries of 2,000 characters each. - The isolate is a V8 boundary, not a process or VM one. It scopes what the
script can address; it is not a claim about V8 escape safety. Run code that
needs a kernel boundary in a container (
containerTool) instead. - Dynamic Workers are in open beta on Cloudflare, so the loader API can
still change. On celld a process holds at most 256 live loaded workers, and a
load past that fails the run with
errorset.
Skills
A skill is a reusable bundle many agents can share: an instruction fragment,
tools, and retrieval knowledge. defineSkill packages them;
defineAgent({ skills: [...] }) composes them in. A skill's tools carry the
same AgentToolDefinition shape agents already use
(functionTool / mcpTools / agentAsTool), and knowledge reuses memory's
retrieval verbatim.
import { defineAgent, defineSkill, functionTool } from "@lunora/agent";
import { jsonSchema } from "@lunora/ai";
import { api } from "./_generated/api";
const billing = defineSkill({
name: "billing",
// Merged into the system prompt, after the agent's own instructions.
instructions: "When asked about an invoice, always cite its invoice id.",
// Retrieved as its own durable step, keyed by the skill name.
knowledge: { source: "rag:searchBillingDocs", topK: 4 },
tools: {
lookupInvoice: functionTool(api.billing.invoiceById, {
description: "Look up an invoice by id.",
inputSchema: jsonSchema({ properties: { id: { type: "string" } }, required: ["id"], type: "object" }),
}),
},
});
export const support = defineAgent({
instructions: "You are a helpful support agent.",
memory: { source: "rag:searchDocs", topK: 5 },
model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
skills: [billing],
});defineAgent folds the skills at declaration time:
- Tools merge into one flat namespace. A skill's tools join the agent's own
tools. The model sees a single namespace, so a name collision, between a skill and the agent or between two skills, throws atdefineAgent(name the colliding tool and rename one). This is the strict cousin ofmcpTools'prefix. - Instructions compose in order. The agent's own
instructionscome first, then each skill's fragment inskillsarray order, joined with blank lines. Dynamic fragments (thunks) resolve once at run start, so composition stays replay-stable. - Knowledge retrieves per skill. Each skill's
knowledgebecomes its own memory source, dispatched as a durable step at run start (memory:retrieve:<name>) and injected alongside the agent's ownmemorycontext. The agent'smemorykeeps the historicmemory:retrievestep name, so adding skills never disturbs an in-flight run's replay.
Skills carry no runtime of their own; they are pure config the agent absorbs, so an agent with skills compiles onto the same durable Workflow as one without.
Authoring a skill as markdown
The instructions are the part a non-author reads, reviews and copies between
projects, so they can live in a SKILL.md of their own. skillFromMarkdown
takes the file's source and reads name from its frontmatter:
---
name: triage
description: not read here, but it parses — other tooling uses it
---
Reproduce the report before proposing a cause. Cite the failing test.import { functionTool } from "@lunora/agent";
import { skillFromMarkdown } from "@lunora/agent/skill-markdown";
import { jsonSchema } from "@lunora/ai";
import triage from "../skills/triage/SKILL.md?raw";
import { api } from "./_generated/api";
const triageSkill = skillFromMarkdown(triage, {
tools: {
searchCode: functionTool(api.code.search, {
description: "Search the repository.",
inputSchema: jsonSchema({ properties: { query: { type: "string" } }, required: ["query"], type: "object" }),
}),
},
});skillFromMarkdown lives at its own subpath deliberately: it is the only part
of this package that needs a YAML parser, and the root export is reached by
every app that calls defineAgent. Behind the subpath, only apps that author a
skill in markdown pay for it.
The name travels with the file, so a skill moves between projects without a
matching TypeScript wrapper. Tools and knowledge stay in the second argument,
because they are code. Everything else behaves exactly as the object form,
including the name rules, so a reserved or malformed name fails identically.
Three things worth knowing:
- Pass the source, not a path. A Worker has no filesystem to read one from at
runtime, so the markdown is imported (
?rawunder Vite) and bundled. - The frontmatter is real YAML. Keys this does not read (
description, licences, tool allow-lists meant for other tooling) parse rather than confuse it, including list- and nested-valued ones. - Invalid YAML fails as invalid YAML. It does not degrade to "no
frontmatter", which would report a missing
namefor a file whose real problem is a syntax error and send you to the wrong line.
Scheduling
An agent compiles onto a Cloudflare Workflow, so it can be a cron target
directly. Codegen emits an agents.<name> reference into _generated/api; pass
it to a cronJobs() schedule and each fire starts a fresh durable run with the
trailing object as its AgentRunInput:
import { cronJobs } from "@lunora/scheduler";
import { agents } from "./_generated/api";
const crons = cronJobs();
// Every day at 03:00 UTC, start a fresh `support` run.
crons.daily("nightly sweep", { hourUTC: 3, minuteUTC: 0 }, agents.support, { input: "sweep", threadKey: "cron" });
export default crons;Each fire is an independent run (its own instance id), so give recurring jobs a
stable threadKey only if you want them to share one conversation thread.
For a one-off delay (rather than a recurring cron), pass the same
agents.<name> reference to ctx.scheduler.runAfter/runAt. Each starts a
single durable run when the timer fires, with the trailing object as its
AgentRunInput:
// Kick off a fresh `support` run five minutes from now.
await ctx.scheduler.runAfter(5 * 60_000, agents.support, { input: "follow up", threadKey: "t-1" });Inbound email
Give an agent an onEmail mapper and codegen wires it onto the worker's
top-level email() handler (via @lunora/agent/inbound), so a message routed by
Cloudflare Email Routing
starts a durable run. The mapper turns a parsed InboundEmail into an
AgentRunInput, or returns null/undefined to decline. When several agents
declare onEmail, each received message is offered to them in order and the
first that returns a run claims it:
export const support = defineAgent({
instructions: "You are a helpful support agent.",
model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
onEmail: (email) => {
// The handler has already bounced any message whose `From` domain is not
// vouched for by an ALIGNED DMARC, SPF or DKIM pass — that gate is
// `authenticatesFrom` from `@lunora/mail/inbound`, the same helper to reach
// for in a handler of your own. Never hand-roll it as "did any clause
// pass?": an attacker gets a genuine pass for the domain they control.
//
// Layer your own policy on top of that gate — this is NOT the gate. Here:
// narrow to a full DMARC pass, stricter than the handler's
// DMARC-or-SPF-or-DKIM. It needs no alignment check of its own because a
// DMARC pass already checked alignment at the MX.
if (!email.authentication.dmarc.some((entry) => entry.result === "pass")) {
return null; // declined — no run, no bounce
}
return {
input: wrapUntrusted(`${email.subject ?? "(no subject)"}\n\n${email.text ?? ""}`),
// `owner` gates the thread's reads and the run dispatches RLS-bypassed,
// so derive it from a verified signal (a DKIM-checked address mapped to
// an account) — never blindly from the spoofable sender.
owner: accountForVerifiedSender(email.from),
threadKey: email.messageId ?? email.from,
title: email.subject,
};
},
tools: {/* … */},
});Security: inbound mail is untrusted and a run dispatches privileged.
Cloudflare Email Routing authenticates only the recipient domain, not the
sender: the envelope from, subject, and body are trivially spoofable. Before
any mapper runs, the handler bounces a message unless some reported DMARC, SPF or
DKIM clause both passes and names a domain equal to the From domain
(email.authentication.dkim / .spf / .dmarc are lists, because one header
legitimately reports a method more than once) — alignment is strict
(mail.example.com does not vouch for example.com), and a pass with no
reported domain is rejected. Layer any
stricter policy on email.authentication inside the mapper, and treat every
mapped field as attacker-controlled input. A message no agent claims is
dropped silently; a throw while parsing or dispatching bounces the message with a
fixed generic reason (never reflecting internal error detail back to the sender).
Size. A message over 10 MiB bounces before it is read, since parsing holds the
raw message, its decoded parts and every attachment in memory at once (the
maxRawBytes guard of @lunora/mail/inbound). The auto-wired handler uses that
default. To accept larger mail, register the handler yourself with
dispatchAgentEmail(targets, { maxRawBytes }) from @lunora/agent/inbound.
Shard. A run started from email uses the default shard. To run a tenant's tools,
add resolveEmailShard. It is called after the sender check and after onEmail claimed
the message, with { envelopeTo, email }. Key it on envelopeTo, the SMTP recipient
Email Routing delivered to. Routing only delivers to addresses you configured, so that
field is trustworthy. The parsed headers are not: email.to is the To: header, which a
sender can set to another tenant's inbox, and email.from is only as good as its
authentication verdicts.
export const support = defineAgent({
// …
onEmail: (email) => ({ input: wrapUntrusted(email.text ?? ""), threadKey: email.messageId ?? email.from }),
// Look the routed address up in your own table; never pass a header or body field through.
resolveEmailShard: ({ envelopeTo }) => tenantForInbox(envelopeTo),
});Returning a shard is an authorization decision: the run's tools dispatch past
authorizeShard. A shardKey in the mapped run is always dropped. A hook that throws, or
that returns anything but a non-empty string or undefined, fails the delivery instead of
falling back to the default shard.
The auto-wired handler is registered before any manual .onEmail(...) you add
to the app builder, so a hand-registered handler still wins if you need full
control.
Untrusted text in the prompt. Authentication decides who may start a run; it
does not make the message text safe for the model. Wrap payload text with
wrapUntrusted (from @lunora/agent) before it goes into input. It places the
text in a tag with a random id per call, so the payload cannot forge the closing
tag, escapes < and > in it, and neutralises leading @, $ and / triggers
with a zero-width space (@ and $ not glued to a word, and a leading /). Pass a header map as the second argument to render the
headers too, with credential-like values (authorization, cookie, set-cookie,
x-api-key, and any name containing token or secret) redacted. The helper
appends a one-line note that the enclosed data is not to be followed as
instructions.
Inbound channels (Slack / GitHub / Discord)
Trigger an agent from a verified inbound webhook. Give it an onInbound
config naming the channel, the verification secret (an env var), and a map
mapper, then mount dispatchAgentChannel(...) (from @lunora/agent/channels) on
an HTTP route:
import { defineAgent, wrapUntrusted } from "@lunora/agent";
export const support = defineAgent({
model: "...",
onInbound: {
channel: "slack",
secret: "SLACK_SIGNING_SECRET", // env var — Slack signing secret / GitHub webhook secret / Discord Ed25519 public key (hex)
map: (event) => {
const payload = event.json() as { event?: { text?: string } };
// SECURITY: derive `owner` from the VERIFIED channel identity, never a payload field.
return { input: wrapUntrusted(payload.event?.text ?? ""), owner: "slack-workspace", threadKey: "slack-thread" };
},
},
});// mount on any HTTP route (e.g. an httpRouter POST handler):
import { dispatchAgentChannel } from "@lunora/agent/channels";
// `className` is the agent's generated class — its `ctx.exports` key.
const handler = dispatchAgentChannel([{ agent: support, className: "SupportAgentWorkflow" }]);
// Pass the Worker ctx: on Cloudflare the agent is reached as ctx.exports.SupportAgentWorkflow.
// handler(c.req.raw, c.env, c.executionCtx) → 200 (claimed / Discord PONG), 401 (bad signature), 204 (declined)dispatchAgentChannel detects the channel from the signature headers and
verifies the request over the raw body before any mapper runs: Slack HMAC
over v0:timestamp:body (with a timestamp-freshness replay guard), GitHub HMAC
over the body, Discord Ed25519 over timestamp+body (and it answers the Discord
PING with a PONG). A request that fails verification is rejected 401 and never
reaches map. The verifiers (verifySlack / verifyGithub / verifyDiscord)
are exported too if you wire your own routing.
Security. Trust comes ONLY from the signature check; the payload is attacker-controlled. Derive the run
ownerfrom the verified channel identity (the workspace / installation the secret belongs to), never from an arbitrary payload field; the run dispatches RLS-bypassed under whateverowneryou set.
Shard. A channel run uses the default shard unless onInbound.resolveShard names one.
It runs after map claimed the event and follows the same rules as resolveEmailShard.
It gets { channel, workspaceId } and nothing from the message itself: workspaceId is
the tenant id the provider stamped on the signed body (Slack team_id, GitHub
installation.id, Discord guild_id). The rest of the body is text a member of that
workspace wrote. A throw answers non-2xx, so the provider redelivers.
onInbound: {
channel: "slack",
secret: "SLACK_SIGNING_SECRET",
map: (event) => ({ input: "…", threadKey: "…" }),
resolveShard: ({ workspaceId }) => tenantForSlackTeam(workspaceId),
},Access control
Pass owner: ctx.auth.userId when starting a run. An owned thread's public
queries (agents:agentThread, agents:agentMessages) answer only for a caller
with that verified identity; for anyone else the thread is indistinguishable
from one that doesn't exist, so key-guessing leaks nothing. The owner is
immutable after the first run. Omitting owner leaves the thread readable by
anyone who knows its key, which is only appropriate for single-tenant or
anonymous apps.
The agent tables are RLS-exempt (.public()): under a .rls("required")
schema the auto-registered runtime functions cannot engage app RLS policies,
so access control is enforced inside them instead: the owner gate on reads,
and internal-only visibility on every write.
Replay-safety (the correctness core)
- Completed steps never re-run. Each LLM turn is the durable step
llm:turn:N; each tool call istool:NAME:CALL_ID(the provider's stable call id). Cloudflare Workflows memoizes completed steps by name, so a crashed run resumes without re-charging a card or re-paying for a model call. - Failed steps retry at-least-once. A tool that dies mid-body will run
again, so side-effecting tools receive their step name as
ctx.idempotencyKeyand must dedupe on it. - Messages persist idempotently. Every write is keyed
INSTANCE:ROLE:POSITIONand deduped by a unique index, so replays never duplicate the thread. - The loop's own dispatches are at-least-once. They carry no replay-dedup
id: most of them are made from inside a memoized
step.docallback, so any id numbered by call order is re-issued to a different call on the next activation — and the shard's dedup table, keyed(identity, mutationId)with no function path in it, would answer that call with the first one's cached result. What makes a redelivery harmless instead is that everyagents:*function the loop calls is idempotent on its own key: keyed appends, get-or-create threads, an instance-ownership guard on completion, and absolute (never additive) status/usage/state writes.
Memory (RAG)
Point memory.source at an action that wraps
@lunora/ai/rag's retrieve. The loop runs it as a
durable step at run start and injects the returned context into every
turn's prompt:
// lunora/rag.ts
export const searchDocs = action.input({ query: v.string(), topK: v.optional(v.number()) }).action(async ({ args, ctx }) => {
return docs(ctx).retrieve(args.query, { topK: args.topK });
});
// lunora/agents.ts
export const support = defineAgent({ memory: { source: "rag:searchDocs", topK: 5 }, model: "..." });Dispatching to a real action keeps retrieval inside a fully wired ctx (codegen-resolved vector bindings, RLS, observability) instead of re-plumbing vectors into the workflow runtime.
Agentic retrieval (mode: "agentic")
The default (mode: "inject") fetches top-k context once per run. Set
mode: "agentic" and the loop instead mints a searchMemory tool the model
calls mid-reasoning: it decides for itself what to look up, and searches again
with a refined query if the first hits fall short (multi-hop "read what you
need", à la Recursive-LM). No context is auto-injected; nothing reaches the
prompt until the model asks for it.
export const support = defineAgent({
// The model calls `searchMemory({ query, topK? })` when it needs context.
memory: { mode: "agentic", source: "rag:searchDocs", topK: 5 },
model: "...",
});searchMemory returns a compact projection: ranked { id, sourceId, score, snippet } hits plus deduped sources, with the giant joined .context string
dropped (each snippet is truncated to snippetChars, default 240). The model
reads the snippets and decides what, if anything, to pull in full.
Set read to an opt-in fetch-by-id action ({ id } -> string) and a
companion readMemory tool is minted so the model can pull a hit's full
document:
export const support = defineAgent({
memory: { mode: "agentic", read: "rag:getDoc", source: "rag:searchDocs" },
model: "...",
});Because every tool call is already a memoized durable step
(tool:searchMemory:<id>), multi-hop retrieval is crash-safe for free: a
resume replays completed searches from the journal rather than re-querying. A
skill's agentic knowledge mints the same tools namespaced by skill name
(search_<skill> / read_<skill>).
activeToolsand the memory tools. The memory tools are ordinary tools: subject toactiveTools,toolChoice,stopWhen, and bounded bymaxTurns. If you pinactiveTools, you must list every minted memory tool name (e.g.searchMemory);defineAgentthrows at declaration time ifactiveToolsomits one, rather than silently hiding it and leaving the model unable to retrieve. DropactiveToolsentirely to expose all tools.
Graph memory (kind: "graph")
Semantic memory (the default kind: "semantic") retrieves passages. A
graph memory instead builds structured, persistent knowledge: it extracts
the entities and relations stated in each run and traverses them on the
next one. Set kind: "graph"; no source action is needed, and none of your
own infrastructure either:
export const support = defineAgent({
memory: { graph: { depth: 2, maxSeeds: 4 }, kind: "graph" },
model: "...",
});- Owner-scoped, persists across threads. The graph is keyed by the run's
owner(the verified identity), so a fact learned in one conversation is available in every later conversation that same user has. An anonymous run (noowner) no-ops the graph tier for that run, because the tier is owner-scoped by design. - Owner-scoped, not agent-scoped. The
agent_entities/agent_edgesrows carry anownerbut no agent discriminator, so every graph-memory agent in the deployment shares one graph per owner. A fact one agent extracts is visible to another agent's traversal for the same owner. That is often the point (shared long-term knowledge of the user), but if two agents must not see each other's memory, give them separate deployments or don't enable the graph tier on both. - No external graph DB. Entities and relations live in the agent's own
DO-SQLite as the
agent_entities/agent_edgestables (shipped with theagentschema extension). Nothing to provision. - Auto-extraction on write. After a run answers, a memoized
memory:extractstep runs one LLM call over the exchange (user input + final answer) to pull{ entities, relations }, then idempotently upserts them. Because the step is memoized and the upsert is an absolute set (never an increment), a crash + resume never re-extracts or double-counts. A cheapergraph.extractionModelcan be set for this step. Extraction is best-effort: a failure never fails a run whose answer is already persisted. - Bounded traversal on read. A
memory:traversestep tokenizes the input, matches seed entities, then walks the graph with a bounded JS breadth-first search (depth,maxSeeds,fanOut,maxNodes; defaults 2 / 4 / 8 / 32), rendering deterministic- alice —[works_at]→ acmetriples that are injected like any other memory context. Reads are always bounded; storage is not. - Storage grows unbounded, with no eviction or TTL (yet). Every run appends new
entities/edges, deduped by normalized name / triple. Weight is monotonic,
not last-write-wins: an edge's weight becomes
max(prior, confidence)and an entity's weight is never updated after insert, so a later extraction that lowers a relation's confidence has no effect — a stale high-confidence edge keeps out-ranking underfanOutand cannot be corrected by restating it more weakly. Nothing prunes stale ones. Traversal stays fast because it is bounded by the knobs above, but the tables keep growing over an owner's lifetime; a weight/age-based prune is a planned follow-up. Note too that normalization is light (trim / collapse whitespace / lowercase), so distinct senses of the same string (e.g. two people named "alex") merge into one node, so keep names specific if that matters.
Why JS-BFS, not
WITH RECURSIVE. The loop runs inside a Workflow with no DB handle; it reaches SQLite only by dispatching a registered function whose typedctx.dbexposes indexed reads, not raw SQL. Traversal is therefore one dispatch doing bounded, indexed local reads (replay-stable: noDate.now()or randomness), which keeps the whole graph on one owner-stable shard.
Episodic memory (kind: "episodic")
Where semantic and graph memory recall by relevance, episodic memory recalls
by recency: it summarizes each completed run into one line and, on the next
run, injects the owner's most recent episodes as a short timeline. Set
kind: "episodic"; no source action and no infrastructure:
export const support = defineAgent({
memory: { episodic: { recall: 5 }, kind: "episodic" },
model: "...",
});- Owner-scoped, cross-thread. Episodes live in the agent's own DO-SQLite as
the
agent_episodestable (shipped with theagentschema extension), keyed byowner, so a run recalls the timeline of that user's earlier runs across every thread. An anonymous run (noowner) no-ops the tier. - Auto-summarized on write. After a run answers, a memoized
memory:episodestep runs one LLM call (a cheaperepisodic.extractionModelcan be set) to condense the exchange into a one-sentence episode, then idempotently records it, so a crash + resume never double-records the same run. - Recency recall on read. A
memory:recallstep returns the owner's most recentrecallepisodes (default 5, max 20) rendered oldest → newest as- <summary>lines, injected like any other memory context. - Unlike the graph tier, episodes are capped: every
agentEpisodeUpsertdeletes the owner's oldest rows beyond 200, so the table is bounded but is not an audit log — once an owner passes 200 runs, the earliest episodes are gone.
Testing
@lunora/testing ships agentHarness, an in-memory double over the same
AgentGenerate turn seam the production loop runs on. You script the model
turns (never a real model or network) and assert the persisted thread,
dispatched functions, and run result:
import { agentHarness, finalTurn, toolCallTurn } from "@lunora/testing";
const harness = agentHarness(support, {
// Each entry is one scripted LLM turn, consumed in order.
script: [toolCallTurn("call_1", "getWeather", { city: "Berlin" }), finalTurn("It's sunny in Berlin.")],
});
const result = await harness.run({ input: "weather in Berlin?", threadKey: "t1" });
expect(result.stopped).toBe("final");
expect(harness.messages("t1").map((m) => m.role)).toStrictEqual(["user", "assistant", "tool", "assistant"]);
expect(harness.dispatches).toContainEqual({ args: { city: "Berlin" }, path: "weather:lookup" });finalTurn(text, extra?) and toolCallTurn(id, name, input, text?) build turn
scripts; harness.thread(key) reads the persisted thread record; provide functions
runtime stubs to back the functions your tools dispatch to.
A run that pauses for a human (an approval or a requestSecretTool request) stops
at its wait. Give the run an instanceId (harness.run(params, { instanceId: "run-1" }))
and resolve it with harness.awaitWait("run-1", "secret:0:call_1") to reach the pause, then
harness.supply(threadKey, toolCallId, value), harness.decline(threadKey, toolCallId),
harness.deliver("run-1", name, payload) or harness.expire("run-1", name). Waits are scoped
to their run, so two runs may wait on the same name. The secret
store is harness.secrets, and harness.journalEntries() is what to assert a
supplied value never reached.
Recorded model streams
Scripted turns skip the streaming layer. To test it, pass a recorded stream
instead: recordedModel(turns) replays one turn per model call, each an array of
AI SDK provider stream parts, and the run goes through the production streamText
seam. onTokenDelta receives the text deltas as they are produced.
import { agentHarness, recordedModel } from "@lunora/testing";
const deltas: string[] = [];
const harness = agentHarness(support, {});
const result = await harness.run(
{ input: "where is o_42?", threadKey: "t1" },
{
model: recordedModel([
{
parts: [
{ id: "t0", type: "text-start" },
{ delta: "It ", id: "t0", type: "text-delta" },
{ delta: "shipped.", id: "t0", type: "text-delta" },
{ id: "t0", type: "text-end" },
// `usage` is the provider's usage object (AI SDK `LanguageModelV4Usage`).
{ finishReason: { raw: "stop", unified: "stop" }, type: "finish", usage },
],
},
]),
onTokenDelta: (delta) => deltas.push(delta.text),
},
);- Tool-call arguments arrive as
tool-input-deltachunks. The provider'stool-callpart carries the assembled JSONinput, which is what the loop runs. - Usage is read from the
finishpart, as providers report it at the end. - Mid-stream failure:
error: { after, cause }fails the stream afterafterparts. The run then follows the loop's normal model-error path:harness.runrejects andharness.thread(key)hasstatus: "error". - Pausing:
pause: { after, gate }holds the stream untilgate.release().createStreamGate()exposesgate.reached, so a test can wait for the pause point and check the partial state without sleeping. Aborting thesignalpassed tocreateStreamGenerateresolves to the text streamed so far once the held stream is released. The recorded stream does not watch the signal, so release the gate after aborting.
Provider errors in a stream retry like any model failure. An error part in the
stream, whether it follows text or arrives first, fails the turn the same way a
rejected stream does: the llm:turn:N step throws, the host retries it under its
normal policy, and nothing from the failed attempt (partial text, tool calls) is
persisted. Its billed tokens are the one exception: when the failure reaches the run,
they are added to the thread's usage, though only within the same invocation. A
replayed failure loses them, and a failed attempt's tokens are not carried into the
total of a later successful retry. A stream that closes without its finish part is failed the
same way. So is a finish whose reason is error, the provider's report that it cut
the generation short (Workers AI reports a stream truncated mid-answer this way); a
non-streaming turn with that reason fails too. Every other finish reason, other
included, completes the turn. A retried turn re-streams its deltas from the start, so
a live consumer must reset accumulated text per turn (see AgentTokenSink).
API reference
Each entry gives the signature as your code writes it. Where a section above already explains an export in depth, the entry links to it.
Declaring agents
defineAgent(config)
Type: (config: AgentConfig) => AgentDefinition
Declares a durable agent. Codegen compiles the definition onto a Workflow and
registers the agents:* runtime functions, so you do not export them yourself.
The call throws at declaration time when model is missing. See
details.
AgentConfig
Type: AgentConfig
The options object for defineAgent. The only required key is model. Other
keys you set often are instructions, tools, skills, memory, maxTurns,
output, onConcurrentRun, publicRun, approvalTimeout and voice. Set
publicRun only when an RPC client may start the agent, because it is false
by default.
defineAgentTool(config)
Type: <Input, Output>(config: AgentToolConfig<Input, Output>) => AgentToolDefinition<Input, Output>
Declares one tool inline in the tools map. The description must be a
non-empty string, since the model chooses the tool from it. The execute
function runs inside the loop's durable step, so a completed call is not re-run
when the workflow replays.
AgentToolContext
Type: AgentToolContext
The second argument to a tool's execute. It carries env, run for calling
Lunora functions, setState and getState for the thread's synced state,
reportProgress, threadKey, toolCallId, owner and shardKey.
defineSkill(config)
Type: (config: SkillConfig) => SkillDefinition
Declares a reusable skill from a name, plus optional instructions, tools
and knowledge (an AgentMemoryOptions). Pass the result in
defineAgent({ skills }). The name must be an identifier, and "default" is
reserved. See Skills.
skillFromMarkdown(markdown, extras?)
Type: (markdown: string, extras?: SkillMarkdownExtras) => SkillDefinition
Imported from @lunora/agent/skill-markdown. Builds a skill from a markdown
string whose frontmatter sets the name. The extras argument carries tools
and knowledge. Import the file yourself (for example with ?raw under Vite),
because a Worker has no filesystem to read it from at runtime. See
details.
Tools
functionTool(reference, options)
Type: <Input, Output>(reference: AgentFunctionReference | string, options: FunctionToolOptions<Input>) => AgentToolDefinition<Input, Output>
Exposes a query, mutation or action as an agent tool. The reference is a typed
api.* reference or a "module:name" string. The model's input becomes the
function's arguments, so inputSchema should mirror the function's validator.
See details.
agentAsTool(options)
Type: (options: AgentAsToolOptions) => AgentToolDefinition<AgentSubToolInput, string>
Adapts a declared agent into a tool, so a supervisor agent can delegate to it.
Each call starts a child run, waits for it to finish and returns its final
answer. The name option is the child's export name, and description tells
the parent model when to delegate.
Default: maxPolls is 600 and pollIntervalMs is 500.
See details.
mcpTools(options)
Type: (options: McpToolsOptions) => Promise<Record<string, AgentToolDefinition<Record<string, unknown>>>>
Connects to an MCP server, lists its tools and returns one tool per entry.
Spread the result into tools. Pass a url, or inject a connected client.
The only and prefix options filter and namespace the tools. Every adapted
tool runs without approval unless you set needsApproval. See
details.
webSearchTool(options?)
Type: (options?: WebSearchToolOptions) => AgentToolDefinition<WebSearchToolInput, AiWebSearchItem[] | string>
A batteries-included tool over the Cloudflare Web Search API. A search bills a
provider key stored on the AI Gateway (the byokAlias key, else the default
alias) when there is one, and AI Gateway credits otherwise. The provider
option picks the search backend, gatewayId picks the gateway, and
description overrides the tool's description.
Default: limit is 5.
See details.
codeTool(tools, options?)
Type: (tools: Record<string, AnyAgentTool>, options?: CodeToolOptions) => AgentToolDefinition<ToolScript, ToolScriptResult>
Gives the model one tool that runs a script which composes the given tools in
a single turn. The script can feed one call's output into the next. Tools with
a needsApproval gate are rejected at construction, so gate the whole script
with options.needsApproval instead.
Default: maxSteps is 16.
See details.
jsCodeTool(options?)
Type: (options?: JsCodeToolOptions) => AgentToolDefinition<JsCodeToolInput, JsCodeToolResult>
Runs model-written JavaScript in a Worker Loader isolate. The script has no
network access, no bindings and no tools, so use it for computation only. A
script failure comes back as a result with error set, not as a thrown error.
Importing the tool makes codegen provision the LOADER binding.
Default: cpuMs is 1000.
See details.
requestSecretTool(options)
Type: (options: { consumer: string; description: string }) => AgentToolDefinition<SecretRequestInput, { secretRef: string }>
Asks the human for a secret, such as an API key, and gives the model only an
opaque secretRef. The run pauses until the value is supplied or declined.
The consumer option names the one tool allowed to read the value. See
details.
withSecret(context, secretRef, use)
Type: <Result>(context: AgentToolContext, secretRef: string, use: (secret: string) => Promise<Result> | Result) => Promise<Result>
Reads a supplied secret inside the execute of the consumer tool and passes it
to use. Only the value use returns leaves the callback. The call throws
SecretUnavailableError when the request is unknown, unsupplied, declared for
another consumer or owned by another thread. See
details.
wrapUntrusted(value, headers?)
Type: (value: string, headers?: Headers | Readonly<Record<string, string>>) => string
Wraps untrusted text, such as an email body, for inclusion in a prompt. The text sits inside a tag with a random id, and angle brackets in it are escaped, so the payload cannot close the block. Headers, when given, render above the body with credential-like values redacted. See Inbound email.
Sandbox tools
Imported from @lunora/agent/sandbox. See the
sandbox section
for the approval defaults and the bindings each tool needs.
fsTool(bucket, options?)
Type: (bucket: string, options?: FsToolOptions) => AgentToolDefinition<FsToolInput>
Exposes an R2-backed virtual filesystem under the pinned root. The model
chooses the operation (ls, read, write, rm or stat). The bucket
argument is the name of the r2_bucket binding in wrangler.jsonc. Writes and
deletes pause for approval by default.
containerTool(name, options?)
Type: (name: string, options?: ContainerToolOptions) => AgentToolDefinition<ContainerToolInput, string>
Gives the model fetch and exec operations against a declared container. The
name is the ctx.containers key. Each thread uses one container instance, so
a multi-step session shares a filesystem.
containerFsTool(name, options?)
Type: (name: string, options?: ContainerFsToolOptions) => AgentToolDefinition<FsToolInput>
File operations on a container's own disk, addressed to the same per-thread
instance that containerTool uses. A file the model writes here is the file its
next exec reads, which fsTool does not guarantee.
Default: root is "/workspace".
browserTool(options?)
Type: (options?: BrowserToolOptions) => AgentToolDefinition<BrowserToolInput, BrowserRenderResult | string>
Drives Cloudflare Browser Rendering with content, scrape, screenshot and
pdf operations. The screenshot and pdf operations need a bucket and
return the stored key, not the bytes. The model chooses any URL, so gate calls
with needsApproval when the agent can reach internal endpoints.
Inbound triggers
dispatchAgentEmail(targets)
Type: (targets: ReadonlyArray<AgentEmailTarget>) => InboundAgentEmailHandler
Imported from @lunora/agent/inbound. Builds the worker email() handler. Each
target is { agent, className }. The handler starts a run for the first agent
whose onEmail mapper claims the message. See details.
dispatchAgentChannel(targets)
Type: (targets: ReadonlyArray<AgentChannelTarget>) => InboundChannelHandler
Imported from @lunora/agent/channels. Builds the webhook handler for Slack,
GitHub and Discord. Each target verifies its own signing secret before its
mapper sees the event. The handler returns 401 when no target verifies and
400 for an unrecognized webhook. See
details.
verifySlack(options)
Type: (options: { body: string; signature: string | undefined; signingSecret: string; timestamp: string | undefined; now?: number; tolerance?: number }) => Promise<boolean>
Checks a Slack request signature over the raw body and rejects a stale
timestamp. The now option exists for tests.
Default: tolerance is 300 seconds.
verifyGithub(options)
Type: (options: { body: string; secret: string; signature: string | undefined }) => Promise<boolean>
Checks the sha256= HMAC of the raw request body against the webhook secret.
verifyDiscord(options)
Type: (options: { body: string; publicKey: string; signature: string | undefined; timestamp: string | undefined; now?: number; tolerance?: number }) => Promise<boolean>
Checks a Discord interaction signature, which is Ed25519 over the timestamp and
the body. The publicKey is the application's public key from the Discord
developer portal.
Default: tolerance is 300 seconds.
Telemetry
Imported from @lunora/agent/telemetry. Each factory returns an AI SDK
Telemetry object for the integrations array. See
details.
consoleTelemetry(options?)
Type: (options?: ConsoleTelemetryOptions) => Telemetry
A zero-dependency structured tracer that writes lifecycle events to a console
logger. It records structural metadata only, unless recordInputs or
recordOutputs is set.
Default: recordInputs and recordOutputs are false.
sentryTelemetry(options)
Type: (options: SentryTelemetryOptions) => Telemetry
Wraps model calls and tool executions in Sentry spans, and routes errors to
captureException. Pass your own Sentry namespace as Sentry, because the
package does not import the SDK.
Default: recordInputs and recordOutputs are false.
braintrustTelemetry(options)
Type: (options: BraintrustTelemetryOptions) => Telemetry
Logs model calls and tool executions to Braintrust as traced spans, with token
usage as metrics. Pass your initialized Braintrust logger as logger.
Default: recordInputs and recordOutputs are false.
otlpTelemetry(options)
Type: (options: OtlpTelemetryOptions) => Telemetry
Sends one gen_ai.* span per model call and per tool execution to an
OTLP-over-HTTP collector. The endpoint is required. The optional token and
headers authenticate the export.
Default: recordInputs and recordOutputs are false.
combineTelemetry(...integrations)
Type: (...integrations: Telemetry[]) => Telemetry
Fans every lifecycle callback out to several integrations, so one agent can report to a console, Sentry and OTLP at once.
Runtime handles and results
AgentHandle
Type: AgentHandle
The ctx.agents.<name> producer, available in mutations and actions. Its run
method starts a durable run and returns an AgentRunHandle. The status,
sendEvent and cancel methods act on a run by its instance id. The
publicRun flag reports whether RPC clients may start the agent. See
Running + observing.
AgentRunHandle
Type: { id: string }
The handle run returns. The id is the workflow instance id, which you pass
to cancel, status or sendEvent.
AgentRunResult
Type: AgentRunResult
The output of a completed run. The stopped field is "final",
"maxTurns" or "stopCondition". The text field holds the final assistant
answer and is absent when the run hit maxTurns. The output field is set when
output is configured. The turns and usage fields report the work done.
AgentThreadStatus
Type: "awaiting_input" | "cancelled" | "error" | "idle" | "running"
The value of a thread's status, which agents:agentThread returns. A thread
in "awaiting_input" is paused for a tool approval.
Hooks
AgentPrepareStep
Type: (input: AgentPrepareStepInput) => AgentPrepareStepResult | Promise<AgentPrepareStepResult | undefined> | undefined
Set as prepareStep. It runs before each turn and can change the request for
that turn, such as the model or the tool choice. See Loop control.
AgentOnStepFinish
Type: (info: AgentStepFinishInfo) => Promise<void> | void
Set as onStepFinish. It runs after each turn, for observability or side
effects. See Loop control.
AgentOnReply
Type: (info: AgentReplyInfo) => Promise<void> | void
Set as onReply. It receives the final answer when a run started from a
channel with a replyRef, which is how an inbound-triggered agent answers where
it was asked. See Inbound channels.
AgentTokenSink
Type: (event: AgentLiveEvent) => void
Receives progress and token events from a live run. The server-side token path
is not yet connected to a live transport, so streamingText stays empty and
messages arrive per turn. See Token streaming.
Memory options
AgentMemoryOptions
Type: AgentMemoryOptions
The shape of an agent's memory key, and of a skill's knowledge. The source
names the retrieval action and is required unless kind is "graph" or
"episodic". The topK and snippetChars options bound the retrieved context.
The kind option selects the tier: "semantic" (the default), "graph" or
"episodic". The mode option selects "agentic" or "inject" retrieval.
The graph and episodic objects bound their own tiers. See
Memory (RAG), agentic retrieval,
graph memory and
episodic memory.
Errors
SecretUnavailableError
Type: class SecretUnavailableError extends Error
Thrown by withSecret when the value is no longer available: it expired, a
previous call already used it, it was never supplied, or it was declared for
another consumer or thread. Its code is "SECRET_UNAVAILABLE".
See details.
See also
- @lunora/ai: the model surface (
ctx.ai) +defineRag - @lunora/workflow: the durable-execution engine underneath
@lunora/agent/telemetry: ready-madetelemetry.integrations(console, Sentry, Braintrust)- @lunora/testing:
agentHarnessand the wider test toolkit - @lunora/mcp: expose an agent to external MCP clients as an
agent_<name>tool (see Expose an agent)