@lunora/agent 1.0.0-alpha.5 → 1.0.0-alpha.51

package/dist/packem_shared/{types.d-boAM2Yi1.d.ts → types.d-PMYeuDE7.d.ts}

@@ -23,7 +23,7 @@ interface AgentStepLike {
   /**
    * Durably hibernate until an external event of `type` arrives, then return
    * its payload. Used for human-in-the-loop approvals: a run pauses on
-   * `approval:<toolCallId>` until a client resolves it. Like `do`, a resolved
+   * `approval:<toolCallId>` until a client resolves it. Like `do`, a resolved
    * wait is memoized — a replay returns the recorded decision without pausing
    * again. Signature mirrors `@lunora/workflow`'s `WorkflowStepLike`.
    */
@@ -42,7 +42,7 @@ interface AgentStepLike {
  * `idempotencyKey`.
  *
  * The `idempotencyKey` is the deterministic durable-step name
- * (`tool:&lt;name>:&lt;toolCallId>`). A COMPLETED tool step is never re-run on a
+ * (`tool:<name>:<toolCallId>`). A COMPLETED tool step is never re-run on a
  * workflow replay (native step memoization) — but a step that FAILS mid-body
  * is retried at-least-once, so a side-effecting tool (charge a card, send a
  * mail) must dedupe on this key itself.
@@ -107,6 +107,17 @@ interface AgentToolContext {
   /** The provider-issued tool-call id. */
   toolCallId: string;
 }
+/**
+ * The READ-ONLY view of {@link AgentToolContext} handed to a `needsApproval`
+ * gate function — every field except `setState`. A gate that mutates thread
+ * state is a side effect inside a decision predicate, which this type makes a
+ * compile-time error rather than a documented-but-unenforced rule: `getState`
+ * and `run` stay available (reads are legitimate gate inputs, and the
+ * function form is resolved inside its own durable step, so they are
+ * replay-safe there too).
+ * @experimental
+ */
+type AgentApprovalContext = Omit<AgentToolContext, "setState">;
 /**
  * An agent tool. Unlike a raw AI SDK tool, `execute` is NOT handed to the
  * model call — the loop runs it itself inside a named durable step so a
@@ -127,17 +138,23 @@ interface AgentToolDefinition<Input = unknown, Output = unknown> {
    * Gate the tool behind a human approval (mirrors the AI SDK's
    * `needsApproval`). When it resolves truthy the durable run PAUSES — the
    * thread moves to `"awaiting_input"` and the workflow hibernates on
-   * `approval:&lt;toolCallId>` — until a client calls `agents:agentResolveApproval`.
+   * `approval:<toolCallId>` — until a client calls `agents:agentResolveApproval`.
    * 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.
    * A boolean gates statically; a function gates per input. Default: `false`
-   * (unchanged behavior). Evaluated from replay-stable input OUTSIDE the
-   * durable step (it re-runs on every replay), so it must be a PURE predicate:
-   * deterministic (no `Date.now()`/`Math.random()`) and free of side effects —
-   * never call {@link AgentToolContext.setState}/`getState` or a mutating `run`
-   * here; state writes belong only in `execute`, inside the memoized step.
+   * (unchanged behavior).
+   *
+   * The boolean/`undefined` forms are compile-time constants re-derived
+   * identically on every replay — no durable step. The FUNCTION form runs
+   * inside its OWN durable step (`tool:approval-gate:<toolCallId>`, distinct
+   * from the tool's own step), so it now runs exactly once per call, not once
+   * per replay. It must still be otherwise pure: deterministic given its
+   * inputs (no `Date.now()`/`Math.random()`) and free of side effects — the
+   * context it receives is {@link AgentApprovalContext}, which has no
+   * `setState`; state writes belong only in `execute`, inside the tool's own
+   * memoized step.
    */
-  needsApproval?: ((input: Input, context: AgentToolContext) => boolean | Promise<boolean>) | boolean;
+  needsApproval?: ((input: Input, context: AgentApprovalContext) => boolean | Promise<boolean>) | boolean;
 }
 /**
  * Author-supplied tool config (see {@link AgentToolDefinition}).
@@ -252,7 +269,7 @@ interface AgentMemoryOptions {
  * (`key: "default"`) from {@link AgentConfig.memory}, then one per skill that
  * carries `knowledge` (keyed by the skill's name). The key names the durable
  * step — the default source keeps the historic `"memory:retrieve"`, a skill
- * source uses `"memory:retrieve:&lt;key>"` — so replay stays deterministic.
+ * source uses `"memory:retrieve:<key>"` — so replay stays deterministic.
  * @experimental
  */
 interface AgentMemorySource extends AgentMemoryOptions {
@@ -308,7 +325,7 @@ interface SkillConfig {
   knowledge?: AgentMemoryOptions;
   /**
    * The skill's identifier — namespaces this skill's `knowledge` memory source
-   * (the durable step `memory:retrieve:&lt;name>`). Must be identifier-shaped.
+   * (the durable step `memory:retrieve:<name>`). Must be identifier-shaped.
    */
   name: string;
   /**
@@ -318,6 +335,12 @@ interface SkillConfig {
    */
   tools?: Record<string, AnyAgentTool>;
 }
+/**
+ * The code-side parts of a markdown-authored skill — everything `SKILL.md`
+ * cannot carry. `name` and `instructions` come from the file itself.
+ * @experimental
+ */
+type SkillMarkdownExtras = Omit<SkillConfig, "instructions" | "name">;
 /**
  * A `defineSkill` result — config plus the brand the agent merge checks.
  * @experimental
@@ -358,7 +381,7 @@ interface AgentStepFinishInfo {
 }
 /**
  * Called after each LLM turn with that turn's text, tool calls, and usage. Runs
- * inside a named durable step (`agent:step-finish:&lt;turn>`) so it fires exactly
+ * inside a named durable step (`agent:step-finish:<turn>`) so it fires exactly
  * once per turn even across a workflow replay.
  * @experimental
  */
@@ -530,7 +553,7 @@ interface AgentConfig {
   model: AgentModelInput;
   /**
    * Optional override for the deployed workflow name (`wrangler.jsonc`
-   * `workflows[].name`). Defaults to `agent-&lt;kebab-cased export name>`. Does
+   * `workflows[].name`). Defaults to `agent-<kebab-cased export name>`. Does
    * NOT change the binding name, which is always derived from the export
    * name (`support` → `AGENT_SUPPORT`).
    */
@@ -577,7 +600,7 @@ interface AgentConfig {
    * Opt this agent into being STARTED over the public RPC boundary — i.e. via
    * the auto-registered `agents:agentRun` mutation an HTTP-only client (e.g.
    * the `@lunora/mcp` server) calls. Default `false`: an agent is startable
-   * only from server-side app code (`ctx.agents.&lt;name>.run(...)`), so declaring
+   * only from server-side app code (`ctx.agents.<name>.run(...)`), so declaring
    * an agent does NOT expose it to arbitrary RPC callers. Fail-closed — the run
    * mutation refuses an agent that has not opted in, regardless of any MCP-side
    * `allowAgents` configuration. A started thread is still owner-scoped to
@@ -688,7 +711,7 @@ interface AgentAsToolOptions {
   /** Cap on child-run status polls before giving up. Default 120. */
   maxPolls?: number;
   /**
-   * The child agent's export name — selects its `AGENT_&lt;NAME>` Workflow
+   * The child agent's export name — selects its `AGENT_<NAME>` Workflow
    * binding (e.g. `"researcher"` → `AGENT_RESEARCHER`). The model-facing tool
    * name is the KEY assigned in the parent's `tools` map, not this.
    */
@@ -1078,7 +1101,7 @@ interface AgentRunHandle {
   id: string;
 }
 /**
- * The `ctx.agents.&lt;name>` producer handle.
+ * The `ctx.agents.<name>` producer handle.
  * @experimental
  */
 interface AgentHandle {
@@ -1111,4 +1134,4 @@ interface AgentHandle {
   /** Read a run's workflow status by instance id. */
   status: (id: string) => Promise<unknown>;
 }
-export { AgentDefinition as A, AgentGenerateOptions as B, AgentGenerateResult as C, AgentInstructionsContext as D, AgentLiveEvent as E, AgentMemoryOptions as F, AgentMemorySource as G, AgentMessageStatus as H, InboundChannelEvent as I, AgentOnStepFinish as J, AgentPrepareStep as K, AgentPrepareStepInput as L, AgentPrepareStepResult as M, AgentProgressEvent as N, AgentRunHandle as O, AgentStepFinishInfo as P, AgentStepInfo as Q, AgentThreadStatus as R, SkillDefinition as S, AgentTokenDelta as T, AgentToolCall as U, AgentUsage as V, AgentVoiceConfig as W, AgentWorkflowBindingLike as X, AgentWorkflowInstanceLike as Y, AgentToolContext as a, AgentToolDefinition as b, AgentCompact as c, AgentEpisodeExtract as d, AgentGraphExtract as e, AgentGenerate as f, AgentTokenSink as g, AgentRunInput as h, AgentFunctionPaths as i, AgentRunFunction as j, AgentStepLike as k, AgentStreamGenerate as l, AgentRunResult as m, AgentMessageRow as n, AgentConfig as o, AnyAgentTool as p, AgentAsToolOptions as q, AgentSubToolInput as r, AgentBindingSpec as s, AgentHandle as t, AgentToolConfig as u, AgentFunctionReference as v, AgentModelInput as w, SkillConfig as x, AgentEmailMapper as y, AgentEmailRun as z };
+export { AgentDefinition as A, AgentEmailMapper as B, AgentEmailRun as C, AgentGenerateOptions as D, AgentGenerateResult as E, AgentInstructionsContext as F, AgentLiveEvent as G, AgentMemoryOptions as H, InboundChannelEvent as I, AgentMemorySource as J, AgentMessageStatus as K, AgentOnStepFinish as L, AgentPrepareStep as M, AgentPrepareStepInput as N, AgentPrepareStepResult as O, AgentProgressEvent as P, AgentRunHandle as Q, AgentStepFinishInfo as R, SkillMarkdownExtras as S, AgentStepInfo as T, AgentThreadStatus as U, AgentTokenDelta as V, AgentToolCall as W, AgentUsage as X, AgentVoiceConfig as Y, AgentWorkflowBindingLike as Z, AgentWorkflowInstanceLike as _, AgentToolContext as a, AgentToolDefinition as b, SkillDefinition as c, AgentCompact as d, AgentEpisodeExtract as e, AgentGraphExtract as f, AgentGenerate as g, AgentTokenSink as h, AgentRunInput as i, AgentFunctionPaths as j, AgentRunFunction as k, AgentStepLike as l, AgentStreamGenerate as m, AgentRunResult as n, AgentMessageRow as o, AgentConfig as p, AnyAgentTool as q, AgentAsToolOptions as r, AgentSubToolInput as s, AgentBindingSpec as t, AgentHandle as u, AgentToolConfig as v, AgentFunctionReference as w, AgentModelInput as x, SkillConfig as y, AgentApprovalContext as z };

package/dist/packem_shared/voice-turn-DzRKyf-x.mjs

@@ -0,0 +1 @@
+import{s as $,o as z}from"./base64-B_qZ_Tyh.mjs";import{buildModelMessages as B}from"./buildModelMessages-Dm2wVNQy.mjs";import{toFunctionReference as b}from"./AGENT_MODULE-BXx-tSCe.mjs";const D=new TextDecoder;new TextEncoder;const K="=",G=t=>{if(t)try{const e=t[0]==="{"?t:D.decode($(t)),n=JSON.parse(e);if(n&&typeof n=="object"&&!Array.isArray(n))return n}catch{}},nt=t=>{if(t){if(!t.startsWith(K))return t;try{return D.decode($(t.slice(K.length)))}catch{return}}},rt=t=>{const e=Number(t);return Number.isFinite(e)&&e>0?e:void 0},st=t=>typeof t=="number"&&Date.now()>=t,it=t=>{try{t.send(JSON.stringify({code:"TOKEN_EXPIRED",error:{code:"TOKEN_EXPIRED",message:"authentication token expired"},type:"error"})),t.close?.(4001,"token_expired")}catch{}},q=16e3,C=1,H=16,N=/[^.!?]*[.!?]+\s+/u,Q=async function*(t){if(t instanceof Uint8Array){yield t;return}if(t instanceof ReadableStream){const e=t.getReader();try{for(;;){const{done:n,value:i}=await e.read();if(n)break;yield i}}finally{e.releaseLock()}return}yield*t},at=(t,e=q,n=C,i=H)=>{const u=n*i/8,y=e*u,d=new ArrayBuffer(44+t.byteLength),r=new DataView(d),s=(U,l)=>{for(let g=0;g<l.length;g+=1)r.setUint8(U+g,l.codePointAt(g)??0)};s(0,"RIFF"),r.setUint32(4,36+t.byteLength,!0),s(8,"WAVE"),s(12,"fmt "),r.setUint32(16,16,!0),r.setUint16(20,1,!0),r.setUint16(22,n,!0),r.setUint32(24,e,!0),r.setUint32(28,y,!0),r.setUint16(32,u,!0),r.setUint16(34,i,!0),s(36,"data"),r.setUint32(40,t.byteLength,!0);const f=new Uint8Array(d);return f.set(t,44),f},Y=t=>{const e=[];let n=t,i=N.exec(n);for(;i&&i[0].length>0;){const u=i[0],y=u.trim();y.length>0&&e.push(y),n=n.slice(u.length),i=N.exec(n)}return{rest:n,sentences:e}},ot=async t=>{const{agent:e,connectionId:n,env:i,exportName:u,owner:y,paths:d,pcm:r,run:s,send:f,sendAudio:U,signal:l,streamGenerate:g,synthesize:_,text:F,threadKey:c,transcribe:I,turn:k,waitForDrain:L}=t,p=()=>l.aborted,E=b(d.appendMessage),M=b(d.ensureThread),P=b(d.listMessages),A=b(d.patchThread),w=(F??(r?await I(r):"")).trim();if(w.length===0)return{assistantText:"",interrupted:!1,userText:""};f({text:w,type:"user_transcript"}),await s(M,{agent:u,key:c,...e.initialState===void 0?{}:{initialState:e.initialState},...y===void 0?{}:{owner:y}}),await s(E,{content:w,messageKey:`voice:${n}:${String(k)}:user`,role:"user",threadKey:c}),await s(A,{key:c,status:"running"});const T=typeof e.instructions=="function"?e.instructions({env:i,input:w,threadKey:c}):e.instructions,O=await s(P,{key:c}),j=B({history:O,...T===void 0?{}:{instructions:T}});let h="",x="",S=Promise.resolve();const J=async a=>{if(p()||a.length===0)return;let m=!1;try{for await(const o of Q(await _(a,l))){if(p()||(await L?.(),p()))break;U(o),m=!0}}catch(o){f({message:o instanceof Error?o.message:String(o),type:"error"})}m&&(x=x.length>0?`${x} ${a}`:a)},R=a=>{S=S.then(async()=>J(a))};try{const a=await g({messages:j,signal:l},v=>{if(p())return;f({text:v,type:"assistant_delta"}),h+=v;const{rest:V,sentences:W}=Y(h);h=V;for(const X of W)R(X)});!p()&&h.trim().length>0&&R(h.trim()),h="",await S;const m=p(),o=m?x:a.text;return await s(E,{content:o,messageKey:`voice:${n}:${String(k)}:assistant`,role:"assistant",threadKey:c}),await s(A,{key:c,status:"idle"}),f(m?{type:"interrupted"}:{text:o,type:"assistant_done"}),{assistantText:o,interrupted:m,userText:w}}catch(a){throw await s(A,{key:c,status:"idle"}),a}},ct=t=>G(t),ut=t=>{if(typeof t=="object"&&t!==null&&"text"in t){const{text:e}=t;return typeof e=="string"?e:""}return""},yt=t=>{if(t instanceof Uint8Array||t instanceof ReadableStream)return t;if(t instanceof Response&&t.body)return t.body;if(typeof t=="object"&&t!==null&&"audio"in t){const{audio:e}=t;if(typeof e=="string")return z(e);if(e instanceof ReadableStream||e instanceof Uint8Array)return e}return new Uint8Array(0)};export{it as E,Q as P,ot as Q,ct as X,at as Y,ut as Z,yt as e,rt as g,nt as l,st as p};

package/dist/sandbox.d.mts

@@ -1,4 +1,4 @@
-import { a as AgentToolContext, b as AgentToolDefinition } from "./packem_shared/types.d-boAM2Yi1.mjs";
+import { a as AgentToolContext, b as AgentToolDefinition } from "./packem_shared/types.d-PMYeuDE7.mjs";
 import '@lunora/mail/inbound';
 import 'ai';
 /**
@@ -149,7 +149,7 @@ interface ContainerToolOptions {
 declare const browserTool: (options?: BrowserToolOptions) => AgentToolDefinition<BrowserToolInput, string>;
 /**
  * A batteries-included agent tool that talks to a declared Cloudflare
- * Container. `name` is the `ctx.containers.&lt;name>` key (the `lunora/containers.ts`
+ * Container. `name` is the `ctx.containers.<name>` key (the `lunora/containers.ts`
  * export). One tool exposes `fetch` (HTTP request) and `exec` (run a command);
  * the model picks via `op`. The call dispatches to the auto-registered
  * `sandbox:invoke` action, which carries `ctx.containers`.

package/dist/sandbox.d.ts

@@ -1,4 +1,4 @@
-import { a as AgentToolContext, b as AgentToolDefinition } from "./packem_shared/types.d-boAM2Yi1.js";
+import { a as AgentToolContext, b as AgentToolDefinition } from "./packem_shared/types.d-PMYeuDE7.js";
 import '@lunora/mail/inbound';
 import 'ai';
 /**
@@ -149,7 +149,7 @@ interface ContainerToolOptions {
 declare const browserTool: (options?: BrowserToolOptions) => AgentToolDefinition<BrowserToolInput, string>;
 /**
  * A batteries-included agent tool that talks to a declared Cloudflare
- * Container. `name` is the `ctx.containers.&lt;name>` key (the `lunora/containers.ts`
+ * Container. `name` is the `ctx.containers.<name>` key (the `lunora/containers.ts`
  * export). One tool exposes `fetch` (HTTP request) and `exec` (run a command);
  * the model picks via `op`. The call dispatches to the auto-registered
  * `sandbox:invoke` action, which carries `ctx.containers`.

package/dist/sandbox.mjs

@@ -1,113 +1 @@
-import { LunoraError } from '@lunora/errors';
-import { jsonSchema } from 'ai';
-import { toFunctionReference, SANDBOX_INVOKE_PATH } from './packem_shared/AGENT_MODULE-Dnt_-AAT.mjs';
-
-const SANDBOX_REF = toFunctionReference(SANDBOX_INVOKE_PATH);
-const DEFAULT_BROWSER_DESCRIPTION = 'Drive a headless browser: screenshot a page, render it to PDF, read its HTML content, or scrape it. Set `op` to "screenshot" | "pdf" | "content" | "scrape" and pass the target `url`.';
-const DEFAULT_CONTAINER_DESCRIPTION = 'Talk to a sandboxed container: `fetch` an HTTP path on it, or `exec` a command inside it. Set `op` to "fetch" (with `path`) or "exec" (with `command`).';
-const DEFAULT_FS_DESCRIPTION = 'Read and write files in a persistent sandbox filesystem. Set `op` to "ls" (list a directory), "read", "write" (with `content`), "rm", or "stat", and pass `path`.';
-const defaultFsGate = (input) => input.op === "write" || input.op === "rm";
-const FS_TOOL_SCHEMA = jsonSchema({
-  properties: {
-    content: { description: "write: the file contents.", type: "string" },
-    op: { description: "The filesystem operation to run.", enum: ["ls", "read", "write", "rm", "stat"], type: "string" },
-    path: { description: "The file or directory path, relative to the sandbox root.", type: "string" }
-  },
-  required: ["op"],
-  type: "object"
-});
-const BROWSER_TOOL_SCHEMA = jsonSchema({
-  properties: {
-    fullPage: { description: "screenshot: capture the full scrollable page rather than just the viewport.", type: "boolean" },
-    op: { description: "The browser operation to run.", enum: ["screenshot", "scrape", "pdf", "content"], type: "string" },
-    selector: { description: "scrape: optional CSS selector hint to narrow the extraction.", type: "string" },
-    type: { description: "screenshot: image encoding (default png).", enum: ["png", "jpeg"], type: "string" },
-    url: { description: "The URL to operate on.", type: "string" }
-  },
-  required: ["op", "url"],
-  type: "object"
-});
-const CONTAINER_EXEC_ROUTE = "/exec";
-const CONTAINER_PATH_QUERY_SPLIT = /[?#]/u;
-const normalizeContainerPath = (path) => {
-  const [raw = ""] = (path ?? "").split(CONTAINER_PATH_QUERY_SPLIT);
-  const segments = [];
-  for (const segment of raw.split("/")) {
-    if (segment === "" || segment === ".") {
-      continue;
-    }
-    if (segment === "..") {
-      segments.pop();
-      continue;
-    }
-    segments.push(segment);
-  }
-  return `/${segments.join("/")}`;
-};
-const NON_IDEMPOTENT_METHODS = /* @__PURE__ */ new Set(["DELETE", "PATCH", "POST", "PUT"]);
-const defaultContainerGate = (input) => {
-  if (input.op === "exec") {
-    return true;
-  }
-  if (normalizeContainerPath(input.path) === CONTAINER_EXEC_ROUTE) {
-    return true;
-  }
-  return NON_IDEMPOTENT_METHODS.has((input.method ?? "GET").toUpperCase());
-};
-const CONTAINER_TOOL_SCHEMA = jsonSchema({
-  properties: {
-    args: { description: "exec: command arguments.", items: { type: "string" }, type: "array" },
-    body: { description: "fetch: request body.", type: "string" },
-    command: { description: "exec: the command to run.", type: "string" },
-    method: { description: "fetch: HTTP method (default GET).", type: "string" },
-    op: { description: "The container operation to run.", enum: ["fetch", "exec"], type: "string" },
-    path: { description: "fetch: request path on the container (e.g. /health).", type: "string" }
-  },
-  required: ["op"],
-  type: "object"
-});
-const browserTool = (options = {}) => {
-  return {
-    description: options.description ?? DEFAULT_BROWSER_DESCRIPTION,
-    // Pin `kind` LAST so out-of-schema model input can never override it.
-    execute: (input, context) => context.run(SANDBOX_REF, { ...input, kind: "browser" }),
-    inputSchema: BROWSER_TOOL_SCHEMA,
-    isLunoraAgentTool: true,
-    ...options.needsApproval === void 0 ? {} : { needsApproval: options.needsApproval }
-  };
-};
-const containerTool = (name, options = {}) => {
-  if (typeof name !== "string" || name.length === 0) {
-    throw new LunoraError("INTERNAL", "@lunora/agent: containerTool requires a container `name` (the ctx.containers.<name> key from lunora/containers.ts)");
-  }
-  const needsApproval = options.needsApproval ?? defaultContainerGate;
-  return {
-    description: options.description ?? DEFAULT_CONTAINER_DESCRIPTION,
-    // Pin `kind`/`name` LAST so out-of-schema model input can never override
-    // the authoritative container the author pinned.
-    execute: (input, context) => context.run(SANDBOX_REF, { ...input, kind: "container", name }),
-    inputSchema: CONTAINER_TOOL_SCHEMA,
-    isLunoraAgentTool: true,
-    needsApproval
-  };
-};
-const fsTool = (bucket, options = {}) => {
-  if (typeof bucket !== "string" || bucket.length === 0) {
-    throw new LunoraError("INTERNAL", "@lunora/agent: fsTool requires an R2 `bucket` binding name (the r2_bucket declared in wrangler.jsonc)");
-  }
-  return {
-    description: options.description ?? DEFAULT_FS_DESCRIPTION,
-    // Pin kind/bucket/root LAST so out-of-schema model input can never override
-    // the authoritative bucket + sandbox root the author pinned. `root` may be
-    // a function of the ctx (per-run/owner isolation), resolved here.
-    execute: (input, context) => {
-      const root = typeof options.root === "function" ? options.root(context) : options.root ?? "";
-      return context.run(SANDBOX_REF, { ...input, bucket, kind: "fs", root });
-    },
-    inputSchema: FS_TOOL_SCHEMA,
-    isLunoraAgentTool: true,
-    needsApproval: options.needsApproval ?? defaultFsGate
-  };
-};
-
-export { browserTool, containerTool, fsTool };
+import{LunoraError as p}from"@lunora/errors";import{jsonSchema as i}from"ai";import{toFunctionReference as a,SANDBOX_INVOKE_PATH as c}from"./packem_shared/AGENT_MODULE-BXx-tSCe.mjs";const s=a(c),d='Drive a headless browser: screenshot a page, render it to PDF, read its HTML content, or scrape it. Set `op` to "screenshot" | "pdf" | "content" | "scrape" and pass the target `url`.',u='Talk to a sandboxed container: `fetch` an HTTP path on it, or `exec` a command inside it. Set `op` to "fetch" (with `path`) or "exec" (with `command`).',h='Read and write files in a persistent sandbox filesystem. Set `op` to "ls" (list a directory), "read", "write" (with `content`), "rm", or "stat", and pass `path`.',l=e=>e.op==="write"||e.op==="rm",m=i({properties:{content:{description:"write: the file contents.",type:"string"},op:{description:"The filesystem operation to run.",enum:["ls","read","write","rm","stat"],type:"string"},path:{description:"The file or directory path, relative to the sandbox root.",type:"string"}},required:["op"],type:"object"}),g=i({properties:{fullPage:{description:"screenshot: capture the full scrollable page rather than just the viewport.",type:"boolean"},op:{description:"The browser operation to run.",enum:["screenshot","scrape","pdf","content"],type:"string"},selector:{description:"scrape: optional CSS selector hint to narrow the extraction.",type:"string"},type:{description:"screenshot: image encoding (default png).",enum:["png","jpeg"],type:"string"},url:{description:"The URL to operate on.",type:"string"}},required:["op","url"],type:"object"}),f="/exec",y=/[?#]/u,T=e=>{const[t=""]=(e??"").split(y),o=[];for(const r of t.split("/"))if(!(r===""||r===".")){if(r===".."){o.pop();continue}o.push(r)}return`/${o.join("/")}`},w=new Set(["DELETE","PATCH","POST","PUT"]),b=e=>e.op==="exec"||T(e.path)===f?!0:w.has((e.method??"GET").toUpperCase()),x=i({properties:{args:{description:"exec: command arguments.",items:{type:"string"},type:"array"},body:{description:"fetch: request body.",type:"string"},command:{description:"exec: the command to run.",type:"string"},method:{description:"fetch: HTTP method (default GET).",type:"string"},op:{description:"The container operation to run.",enum:["fetch","exec"],type:"string"},path:{description:"fetch: request path on the container (e.g. /health).",type:"string"}},required:["op"],type:"object"}),E=(e={})=>({description:e.description??d,execute:(t,o)=>o.run(s,{...t,kind:"browser"}),inputSchema:g,isLunoraAgentTool:!0,...e.needsApproval===void 0?{}:{needsApproval:e.needsApproval}}),L=(e,t={})=>{if(typeof e!="string"||e.length===0)throw new p("INTERNAL","@lunora/agent: containerTool requires a container `name` (the ctx.containers.<name> key from lunora/containers.ts)");const o=t.needsApproval??b;return{description:t.description??u,execute:(r,n)=>n.run(s,{...r,kind:"container",name:e}),inputSchema:x,isLunoraAgentTool:!0,needsApproval:o}},j=(e,t={})=>{if(typeof e!="string"||e.length===0)throw new p("INTERNAL","@lunora/agent: fsTool requires an R2 `bucket` binding name (the r2_bucket declared in wrangler.jsonc)");return{description:t.description??h,execute:(o,r)=>{const n=typeof t.root=="function"?t.root(r):t.root??"";return r.run(s,{...o,bucket:e,kind:"fs",root:n})},inputSchema:m,isLunoraAgentTool:!0,needsApproval:t.needsApproval??l}};export{E as browserTool,L as containerTool,j as fsTool};

package/dist/skill-markdown.d.mts

@@ -0,0 +1,36 @@
+import { S as SkillMarkdownExtras, c as SkillDefinition } from "./packem_shared/types.d-PMYeuDE7.mjs";
+import '@lunora/mail/inbound';
+import 'ai';
+/**
+ * Declare a skill whose prose lives in a markdown file.
+ *
+ * ```ts
+ * import triage from "./skills/triage/SKILL.md?raw";
+ * import { functionTool } from "@lunora/agent";
+ * import { skillFromMarkdown } from "@lunora/agent/skill-markdown";
+ *
+ * export const triageSkill = skillFromMarkdown(triage, {
+ *     tools: { searchCode: functionTool(api.code.search, { ... }) },
+ * });
+ * ```
+ *
+ * ```md
+ * ---
+ * name: triage
+ * ---
+ * Reproduce the report before proposing a cause. Cite the failing test.
+ * ```
+ *
+ * The split is the point: the instructions are the part a non-author reads,
+ * reviews and copies between projects, so they belong in a file that is legible
+ * on its own — and the `name` travels WITH that file, so a skill can move
+ * without a matching TypeScript wrapper. Tools and `knowledge` stay in code,
+ * because they are code.
+ *
+ * Getting the markdown here is the caller's job (`?raw` under Vite, a build-time
+ * import elsewhere) — a Worker has no filesystem to read it from at runtime, so
+ * this takes the string rather than a path.
+ * @experimental
+ */
+declare const skillFromMarkdown: (markdown: string, extras?: SkillMarkdownExtras) => SkillDefinition;
+export { type SkillMarkdownExtras, skillFromMarkdown };

package/dist/skill-markdown.d.ts

@@ -0,0 +1,36 @@
+import { S as SkillMarkdownExtras, c as SkillDefinition } from "./packem_shared/types.d-PMYeuDE7.js";
+import '@lunora/mail/inbound';
+import 'ai';
+/**
+ * Declare a skill whose prose lives in a markdown file.
+ *
+ * ```ts
+ * import triage from "./skills/triage/SKILL.md?raw";
+ * import { functionTool } from "@lunora/agent";
+ * import { skillFromMarkdown } from "@lunora/agent/skill-markdown";
+ *
+ * export const triageSkill = skillFromMarkdown(triage, {
+ *     tools: { searchCode: functionTool(api.code.search, { ... }) },
+ * });
+ * ```
+ *
+ * ```md
+ * ---
+ * name: triage
+ * ---
+ * Reproduce the report before proposing a cause. Cite the failing test.
+ * ```
+ *
+ * The split is the point: the instructions are the part a non-author reads,
+ * reviews and copies between projects, so they belong in a file that is legible
+ * on its own — and the `name` travels WITH that file, so a skill can move
+ * without a matching TypeScript wrapper. Tools and `knowledge` stay in code,
+ * because they are code.
+ *
+ * Getting the markdown here is the caller's job (`?raw` under Vite, a build-time
+ * import elsewhere) — a Worker has no filesystem to read it from at runtime, so
+ * this takes the string rather than a path.
+ * @experimental
+ */
+declare const skillFromMarkdown: (markdown: string, extras?: SkillMarkdownExtras) => SkillDefinition;
+export { type SkillMarkdownExtras, skillFromMarkdown };

package/dist/skill-markdown.mjs

@@ -0,0 +1 @@
+import{LunoraError as o}from"@lunora/errors";import{parse as s}from"yaml";import{defineSkill as l}from"./packem_shared/defineSkill-DfJxCwfZ.mjs";const m=/^\uFEFF?[ \t]*---[ \t]*\r?\n/u,d=/^---[ \t]*$/mu,h=n=>{const r=m.exec(n);if(!r)return{body:n.trim(),data:{}};const t=n.slice(r[0].length),e=d.exec(t);if(!e)throw new o("INTERNAL","@lunora/agent: the skill markdown opens with `---` but never closes the frontmatter block. Add a closing `---` on its own line.");let a;try{a=s(t.slice(0,e.index))}catch(i){throw new o("INTERNAL",`@lunora/agent: the skill markdown has invalid YAML frontmatter — ${i instanceof Error?i.message:String(i)}`)}return{body:t.slice(e.index+e[0].length).trim(),data:typeof a=="object"&&a!==null?a:{}}},c=(n,r={})=>{if(typeof n!="string")throw new o("INTERNAL",`@lunora/agent: skillFromMarkdown expects the markdown SOURCE as a string, got ${typeof n}`);const{body:t,data:e}=h(n);if(e.name!==void 0&&typeof e.name!="string")throw new o("INTERNAL",`@lunora/agent: the skill markdown's \`name\` must be a string, got ${Array.isArray(e.name)?"array":typeof e.name}. Quote it if the value looks like a number or a boolean (\`name: "2fa"\`).`);if(typeof e.name!="string")throw new o("INTERNAL","@lunora/agent: skillFromMarkdown found no `name` in the markdown frontmatter. Open the file with a `---` line, put `name: <identifier>` on its own line, and close it with `---`. Other keys are parsed and ignored — only `name` is read here.");if(t==="")throw new o("INTERNAL",`@lunora/agent: the skill markdown for "${e.name}" has no body — the instructions below the closing \`---\` are what the skill contributes.`);return l({...r,instructions:t,name:e.name})};export{c as skillFromMarkdown};

package/dist/telemetry/index.d.mts

@@ -122,6 +122,87 @@ interface ConsoleTelemetryOptions extends CommonOptions {
  * @experimental
  */
 declare const consoleTelemetry: (options?: ConsoleTelemetryOptions) => Telemetry;
+/**
+ * Options for {@link otlpTelemetry}.
+ * @experimental
+ */
+interface OtlpTelemetryOptions extends CommonOptions {
+  /**
+   * Conversation / session id to tag each generation span with, emitted as the
+   * `gen_ai.conversation.id` semantic-convention attribute so a multi-turn
+   * conversation's model turns group in the trace store. On a deployed agent the
+   * platform wiring passes the run's `threadKey` here automatically (one thread =
+   * one conversation). Omitted → the attribute is absent (backward-compatible),
+   * and each turn's span is ungrouped.
+   */
+  conversationId?: string;
+  /**
+   * The OTLP-over-HTTP collector base endpoint (e.g. the Lunora Cloud's `/v1`
+   * base). Spans are POSTed to `${endpoint}/v1/traces`; a trailing slash is
+   * tolerated. On the platform this is the injected `LUNORA_OTLP_ENDPOINT`.
+   */
+  endpoint: string;
+  /**
+   * Extra headers merged onto every POST — typically the correlation headers
+   * the platform injects. `Content-Type: application/json` is set by default.
+   */
+  headers?: Record<string, string>;
+  /** `service.name` resource attribute on every span. Defaults to `lunora`. */
+  serviceName?: string;
+  /**
+   * Bearer token added as `Authorization: Bearer` (wins over any authorization
+   * in `headers`) — the injected `LUNORA_OTLP_TOKEN`. Omit for an
+   * unauthenticated collector.
+   */
+  token?: string;
+  /**
+   * Trace id (32-hex) to hang every span of this run under, so one agent run
+   * reads as one trace. Pass a stable id derived from the run (e.g. the
+   * workflow run id). Omitted → each span mints its own trace id (still valid,
+   * just ungrouped).
+   */
+  traceId?: string;
+  /**
+   * The Worker request's `waitUntil`, so a fire-and-forget export survives
+   * isolate teardown after the turn returns. Omit and the send degrades to
+   * best-effort.
+   */
+  waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+ * An OTLP-over-HTTP telemetry integration for `@lunora/agent`.
+ *
+ * The OTLP counterpart to the `sentryTelemetry` / `braintrustTelemetry` bridges:
+ * it wraps each language-model call and tool execution in an OTLP **span**
+ * (`gen_ai.*` semantic-convention attributes — model, provider, token usage,
+ * tool name) and ships it to a collector, so agent generations land in the same
+ * trace store as the rest of an app's telemetry (the Lunora Cloud, or any OTel
+ * collector). Plug it into `defineAgent({ telemetry: { isEnabled: true,
+ * integrations: [otlpTelemetry({ endpoint, token })] } })`.
+ *
+ * Emitting inside the turn's execution wrapper means one span per **real** turn:
+ * the agent loop memoizes each `step.do('llm:turn:N')`, so a Workflow replay
+ * returns the cached result without re-invoking `execute`, and no duplicate span
+ * is emitted. Privacy-safe by default — `recordInputs`/`recordOutputs` both
+ * default `false`, so no prompt or generated text leaves the worker without an
+ * explicit opt-in; only structural metadata + token counts are recorded.
+ *
+ * Each export is fire-and-forget (registered with `waitUntil` when supplied);
+ * every rejection is swallowed so a flaky collector never surfaces to the run.
+ *
+ * Two deliberate differences from the SDK-backed bridges, which delegate to a
+ * host tracer. First, no `onError`: a failed call already emits a span with
+ * `status.code === 2`, so the failure is on the trace and there is no host client
+ * to also notify. Second, flat not nested: every span gets `traceId` (shared when
+ * `traceId` is set) but no `parentSpanId`, so model-call and tool spans are
+ * siblings under the run rather than a tree — OTLP has no ambient span context to
+ * parent to here.
+ * @param options `endpoint` (+ optional `token`/`headers`/`serviceName`),
+ * `traceId` to group a run's spans, `waitUntil`, and the `recordInputs`/
+ * `recordOutputs` privacy flags.
+ * @experimental
+ */
+declare const otlpTelemetry: (options: OtlpTelemetryOptions) => Telemetry;
 /**
  * The minimal, **structural** slice of `@sentry/cloudflare` (equivalently
  * `@sentry/node`/`@sentry/browser`) this bridge needs. `@sentry/cloudflare` is
@@ -170,4 +251,4 @@ interface SentryTelemetryOptions extends CommonOptions {
  * @experimental
  */
 declare const sentryTelemetry: (options: SentryTelemetryOptions) => Telemetry;
-export { type BraintrustLike, type BraintrustSpan, type BraintrustTelemetryOptions, type CommonOptions, type ConsoleLogLevel, type ConsoleLogger, type ConsoleTelemetryOptions, type SentryLike, type SentryTelemetryOptions, braintrustTelemetry, combineTelemetry, consoleTelemetry, sentryTelemetry };
+export { type BraintrustLike, type BraintrustSpan, type BraintrustTelemetryOptions, type CommonOptions, type ConsoleLogLevel, type ConsoleLogger, type ConsoleTelemetryOptions, type OtlpTelemetryOptions, type SentryLike, type SentryTelemetryOptions, braintrustTelemetry, combineTelemetry, consoleTelemetry, otlpTelemetry, sentryTelemetry };

package/dist/telemetry/index.d.ts

@@ -122,6 +122,87 @@ interface ConsoleTelemetryOptions extends CommonOptions {
  * @experimental
  */
 declare const consoleTelemetry: (options?: ConsoleTelemetryOptions) => Telemetry;
+/**
+ * Options for {@link otlpTelemetry}.
+ * @experimental
+ */
+interface OtlpTelemetryOptions extends CommonOptions {
+  /**
+   * Conversation / session id to tag each generation span with, emitted as the
+   * `gen_ai.conversation.id` semantic-convention attribute so a multi-turn
+   * conversation's model turns group in the trace store. On a deployed agent the
+   * platform wiring passes the run's `threadKey` here automatically (one thread =
+   * one conversation). Omitted → the attribute is absent (backward-compatible),
+   * and each turn's span is ungrouped.
+   */
+  conversationId?: string;
+  /**
+   * The OTLP-over-HTTP collector base endpoint (e.g. the Lunora Cloud's `/v1`
+   * base). Spans are POSTed to `${endpoint}/v1/traces`; a trailing slash is
+   * tolerated. On the platform this is the injected `LUNORA_OTLP_ENDPOINT`.
+   */
+  endpoint: string;
+  /**
+   * Extra headers merged onto every POST — typically the correlation headers
+   * the platform injects. `Content-Type: application/json` is set by default.
+   */
+  headers?: Record<string, string>;
+  /** `service.name` resource attribute on every span. Defaults to `lunora`. */
+  serviceName?: string;
+  /**
+   * Bearer token added as `Authorization: Bearer` (wins over any authorization
+   * in `headers`) — the injected `LUNORA_OTLP_TOKEN`. Omit for an
+   * unauthenticated collector.
+   */
+  token?: string;
+  /**
+   * Trace id (32-hex) to hang every span of this run under, so one agent run
+   * reads as one trace. Pass a stable id derived from the run (e.g. the
+   * workflow run id). Omitted → each span mints its own trace id (still valid,
+   * just ungrouped).
+   */
+  traceId?: string;
+  /**
+   * The Worker request's `waitUntil`, so a fire-and-forget export survives
+   * isolate teardown after the turn returns. Omit and the send degrades to
+   * best-effort.
+   */
+  waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+ * An OTLP-over-HTTP telemetry integration for `@lunora/agent`.
+ *
+ * The OTLP counterpart to the `sentryTelemetry` / `braintrustTelemetry` bridges:
+ * it wraps each language-model call and tool execution in an OTLP **span**
+ * (`gen_ai.*` semantic-convention attributes — model, provider, token usage,
+ * tool name) and ships it to a collector, so agent generations land in the same
+ * trace store as the rest of an app's telemetry (the Lunora Cloud, or any OTel
+ * collector). Plug it into `defineAgent({ telemetry: { isEnabled: true,
+ * integrations: [otlpTelemetry({ endpoint, token })] } })`.
+ *
+ * Emitting inside the turn's execution wrapper means one span per **real** turn:
+ * the agent loop memoizes each `step.do('llm:turn:N')`, so a Workflow replay
+ * returns the cached result without re-invoking `execute`, and no duplicate span
+ * is emitted. Privacy-safe by default — `recordInputs`/`recordOutputs` both
+ * default `false`, so no prompt or generated text leaves the worker without an
+ * explicit opt-in; only structural metadata + token counts are recorded.
+ *
+ * Each export is fire-and-forget (registered with `waitUntil` when supplied);
+ * every rejection is swallowed so a flaky collector never surfaces to the run.
+ *
+ * Two deliberate differences from the SDK-backed bridges, which delegate to a
+ * host tracer. First, no `onError`: a failed call already emits a span with
+ * `status.code === 2`, so the failure is on the trace and there is no host client
+ * to also notify. Second, flat not nested: every span gets `traceId` (shared when
+ * `traceId` is set) but no `parentSpanId`, so model-call and tool spans are
+ * siblings under the run rather than a tree — OTLP has no ambient span context to
+ * parent to here.
+ * @param options `endpoint` (+ optional `token`/`headers`/`serviceName`),
+ * `traceId` to group a run's spans, `waitUntil`, and the `recordInputs`/
+ * `recordOutputs` privacy flags.
+ * @experimental
+ */
+declare const otlpTelemetry: (options: OtlpTelemetryOptions) => Telemetry;
 /**
  * The minimal, **structural** slice of `@sentry/cloudflare` (equivalently
  * `@sentry/node`/`@sentry/browser`) this bridge needs. `@sentry/cloudflare` is
@@ -170,4 +251,4 @@ interface SentryTelemetryOptions extends CommonOptions {
  * @experimental
  */
 declare const sentryTelemetry: (options: SentryTelemetryOptions) => Telemetry;
-export { type BraintrustLike, type BraintrustSpan, type BraintrustTelemetryOptions, type CommonOptions, type ConsoleLogLevel, type ConsoleLogger, type ConsoleTelemetryOptions, type SentryLike, type SentryTelemetryOptions, braintrustTelemetry, combineTelemetry, consoleTelemetry, sentryTelemetry };
+export { type BraintrustLike, type BraintrustSpan, type BraintrustTelemetryOptions, type CommonOptions, type ConsoleLogLevel, type ConsoleLogger, type ConsoleTelemetryOptions, type OtlpTelemetryOptions, type SentryLike, type SentryTelemetryOptions, braintrustTelemetry, combineTelemetry, consoleTelemetry, otlpTelemetry, sentryTelemetry };

package/dist/telemetry/index.mjs

@@ -1,4 +1 @@
-export { braintrustTelemetry } from '../packem_shared/braintrustTelemetry-wuGDErob.mjs';
-export { combineTelemetry } from '../packem_shared/combineTelemetry-DCyaaWAI.mjs';
-export { consoleTelemetry } from '../packem_shared/consoleTelemetry-z2MiP1jt.mjs';
-export { sentryTelemetry } from '../packem_shared/sentryTelemetry-CgqFJyLO.mjs';
+import{braintrustTelemetry as o}from"../packem_shared/braintrustTelemetry-CnOI5WAw.mjs";import{combineTelemetry as m}from"../packem_shared/combineTelemetry-oLCV_EPV.mjs";import{consoleTelemetry as p}from"../packem_shared/consoleTelemetry-C_85CaZ7.mjs";import{otlpTelemetry as f}from"../packem_shared/otlpTelemetry-DcW9mOLV.mjs";import{sentryTelemetry as T}from"../packem_shared/sentryTelemetry-Dr2aPuvl.mjs";export{o as braintrustTelemetry,m as combineTelemetry,p as consoleTelemetry,f as otlpTelemetry,T as sentryTelemetry};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/agent",
-  "version": "1.0.0-alpha.5",
+  "version": "1.0.0-alpha.51",
   "description": "Durable AI agents for Lunora: defineAgent compiles a replay-safe tool-loop onto Cloudflare Workflows, with DO SQLite threads and live message subscriptions",
   "keywords": [
     "agent",
@@ -62,6 +62,10 @@
       "types": "./dist/naming.d.ts",
       "import": "./dist/naming.mjs"
     },
+    "./skill-markdown": {
+      "types": "./dist/skill-markdown.d.ts",
+      "import": "./dist/skill-markdown.mjs"
+    },
     "./sandbox": {
       "types": "./dist/sandbox.d.ts",
       "import": "./dist/sandbox.mjs"
@@ -76,14 +80,15 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/ai": "1.0.0-alpha.17",
-    "@lunora/errors": "1.0.0-alpha.6",
-    "@lunora/mail": "1.0.0-alpha.16",
-    "@lunora/server": "1.0.0-alpha.28",
-    "@lunora/values": "1.0.0-alpha.9",
-    "@lunora/workflow": "1.0.0-alpha.11",
+    "@lunora/ai": "1.0.0-alpha.56",
+    "@lunora/errors": "1.0.0-alpha.20",
+    "@lunora/mail": "1.0.0-alpha.47",
+    "@lunora/server": "1.0.0-alpha.70",
+    "@lunora/values": "1.0.0-alpha.25",
+    "@lunora/workflow": "1.0.0-alpha.26",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "ai": "7.0.31"
+    "ai": "7.0.37",
+    "yaml": "^2.9.0"
   },
   "engines": {
     "node": "^22.15.0 || >=24.11.0"