@lunora/agent 1.0.0-alpha.9 → 1.0.0-alpha.91

package/dist/sandbox.d.ts

@@ -1,4 +1,4 @@
-import { a as AgentToolContext, b as AgentToolDefinition } from "./packem_shared/types.d-boAM2Yi1.js";
+import { b as AgentToolContext, c as AgentToolDefinition } from "./packem_shared/types.d-B8WZl1rU.js";
 import '@lunora/mail/inbound';
 import 'ai';
 /**
@@ -25,8 +25,8 @@ type BrowserToolInput = {
 /**
  * The model-provided input to a {@link containerTool} call — a discriminated
  * union on `op`. `fetch` sends an HTTP request to the container; `exec` asks it
- * to run a command (routed as a POST to `/exec`, since the container surface
- * exposes no first-class exec RPC — the container app must serve that route).
+ * to run a command (delegated to `ctx.containers.<name>.exec`, the first-class
+ * exec contract in `@lunora/container`; the container app serves its route).
  * @experimental
  */
 type ContainerToolInput = {
@@ -112,12 +112,13 @@ interface ContainerToolOptions {
   description?: string;
   /**
    * Gate a call behind a human approval. Defaults to gating any command
-   * execution: an `exec`, AND a `fetch` whose path resolves to the privileged
-   * `/exec` route (both reach the same command-execution path in the container,
-   * so gating on the `op` name alone would let a `fetch` to `/exec` run a
-   * command unattended). A plain `fetch` to any other route runs unattended.
-   * Pass a boolean or your own predicate to change that. Evaluated from
-   * replay-stable input, so keep it deterministic.
+   * execution — an `exec` — plus any `fetch` using a non-idempotent method
+   * (POST/PUT/PATCH/DELETE), so a prompt-injected model cannot reach some
+   * other mutating route unattended. A read-only `fetch` runs unattended. The
+   * exec route itself needs no special case: `@lunora/container` reserves
+   * `/__lunora/*` and refuses a `fetch` into it. Pass a boolean or your own
+   * predicate to change that. Evaluated from replay-stable input, so keep it
+   * deterministic.
    */
   needsApproval?: ((input: ContainerToolInput) => boolean) | boolean;
 }
@@ -149,19 +150,19 @@ 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`.
  *
  * By default a read-only (GET/HEAD/OPTIONS, or method-omitted) `fetch` runs
  * unattended while everything else is gated behind a human approval — an
- * `exec`; a `fetch` whose path resolves to the privileged `/exec` route (both
+ * `exec`; a `fetch` whose path resolves to the privileged exec route (both
  * reach the same command-execution path in the container, so gating on the
- * `op` name alone would let a `fetch` to `/exec` run a command unattended);
+ * `op` name alone would let a `fetch` to it run a command unattended);
  * and a `fetch` using a non-idempotent method (POST/PUT/PATCH/DELETE) to ANY
  * route, since a prompt-injected model could otherwise mutate container state
- * through some other privileged route just by avoiding the literal `/exec`
+ * through some other privileged route just by avoiding the literal exec
  * path. A `fetch` can still reach any *other read* route unattended, so scope
  * the container's GET routes accordingly. Pass `opts.needsApproval` to widen
  * or disable the gate.

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 a}from"@lunora/errors";import{jsonSchema as i}from"ai";import{toFunctionReference as p,SANDBOX_INVOKE_PATH as c}from"./packem_shared/AGENT_MODULE-M4D1EejI.mjs";const s=p(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`.',h='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`).',l='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`.',u=e=>e.op==="write"||e.op==="rm",T=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"}),m=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"}),g=new Set(["DELETE","PATCH","POST","PUT"]),f=e=>e.op==="exec"||g.has((e.method??"GET").toUpperCase()),y=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"}),w=(e={})=>({description:e.description??d,execute:(t,r)=>r.run(s,{...t,kind:"browser"}),inputSchema:m,isLunoraAgentTool:!0,...e.needsApproval===void 0?{}:{needsApproval:e.needsApproval}}),O=(e,t={})=>{if(typeof e!="string"||e.length===0)throw new a("INTERNAL","@lunora/agent: containerTool requires a container `name` (the ctx.containers.<name> key from lunora/containers.ts)");const r=t.needsApproval??f;return{description:t.description??h,execute:(o,n)=>n.run(s,{...o,kind:"container",name:e}),inputSchema:y,isLunoraAgentTool:!0,needsApproval:r}},_=(e,t={})=>{if(typeof e!="string"||e.length===0)throw new a("INTERNAL","@lunora/agent: fsTool requires an R2 `bucket` binding name (the r2_bucket declared in wrangler.jsonc)");return{description:t.description??l,execute:(r,o)=>{const n=typeof t.root=="function"?t.root(o):t.root??"";return o.run(s,{...r,bucket:e,kind:"fs",root:n})},inputSchema:T,isLunoraAgentTool:!0,needsApproval:t.needsApproval??u}};export{w as browserTool,O as containerTool,_ as fsTool};

package/dist/skill-markdown.d.mts

@@ -0,0 +1,36 @@
+import { S as SkillMarkdownExtras, d as SkillDefinition } from "./packem_shared/types.d-B8WZl1rU.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, d as SkillDefinition } from "./packem_shared/types.d-B8WZl1rU.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-DGGvDWNq.mjs";const m=/^\uFEFF?[ \t]*---[ \t]*\r?\n/u,h=/^---[ \t]*$/mu,c=t=>{const r=m.exec(t);if(!r)return{body:t.trim(),data:{}};const n=t.slice(r[0].length),e=h.exec(n);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(n.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:n.slice(e.index+e[0].length).trim(),data:typeof a=="object"&&a!==null?a:{}}},w=(t,r={})=>{if(typeof t!="string")throw new o("INTERNAL",`@lunora/agent: skillFromMarkdown expects the markdown SOURCE as a string, got ${typeof t}`);const{body:n,data:e}=c(t);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(n==="")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:n,name:e.name})};export{w as skillFromMarkdown};

package/dist/telemetry/index.d.mts

@@ -60,9 +60,24 @@ interface BraintrustTelemetryOptions extends CommonOptions {
  * A dependency-injected Braintrust bridge for the ai@7 telemetry surface.
  *
  * It wraps model calls (`type: "llm"`) and tool executions (`type: "tool"`) in
- * `logger.traced` spans and logs structural metadata. Prompts / tool arguments
- * are logged only when `recordInputs` is set; generated text / tool results
- * only when `recordOutputs` is set. `onError` opens a span and logs the error.
+ * `logger.traced` spans and logs structural metadata, including the call's token
+ * usage as Braintrust `metrics`. Prompts / tool arguments are logged only when
+ * `recordInputs` is set; generated text / tool results only when `recordOutputs`
+ * is set. `onError` opens a span and logs the error.
+ *
+ * The tool span is driven by the agent LOOP, not by `ai`: Lunora exposes tools
+ * schema-only so the SDK never executes one (see `telemetry/tool-execution.ts`).
+ *
+ * **A model-call span closes when the CALL ends, not when `execute()` resolves.**
+ * On a streamed turn `execute()` resolves the instant `doStream` hands back the
+ * stream — before a token, before any usage — so a span that simply awaited it
+ * measured time-to-first-byte and logged the stream handle instead of the
+ * generation. `execute()` still runs INSIDE the traced callback, which is what
+ * parents the provider's own work under the span; the callback then parks until
+ * the SDK's terminal event for that `callId` arrives, so `traced` finishes the
+ * span at the real end of the call, with the real usage. The caller gets
+ * `execute()`'s value the moment it resolves, exactly as before — the span's
+ * lifetime and the caller's are deliberately separate.
  *
  * The app owns Braintrust initialization; pass the logger in as `logger`.
  * @experimental
@@ -173,36 +188,72 @@ interface OtlpTelemetryOptions extends CommonOptions {
  * 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**
+ * it records each language-model call and each tool execution as 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.
+ * **A model-call span closes when the CALL ends, not when `execute()` resolves.**
+ * On a streamed turn `execute()` resolves the instant `doStream` hands back the
+ * stream — before a single token, before any usage, and before any mid-stream
+ * failure. Closing the span there reported every voice and workflow-streamed turn
+ * as a ~1 ms, zero-token, always-OK call. So the span opens in
+ * `executeLanguageModelCall` (which also owns the failure path, since a rejected
+ * provider call produces no end event) and closes on `onLanguageModelCallEnd`,
+ * which the SDK fires once the response is normalized — after the stream's
+ * `finish` part, where the duration and the token usage actually live.
+ * `onError` / `onAbort` close whatever is still open, so a stream that dies or is
+ * barged in on reports a failure instead of a phantom success.
+ *
+ * **Tool spans come from the agent loop.** Lunora exposes tools to the model
+ * schema-only, so `ai` never runs one and never fires its tool telemetry; the
+ * loop calls `executeTool` itself from the durable step where the tool really
+ * runs (see `telemetry/tool-execution.ts`).
+ *
+ * One span per REAL execution: the agent loop memoizes each `step.do(...)`, so a
+ * Workflow replay returns the cached result without re-invoking the wrapped work
+ * 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.
+ * One deliberate difference from the SDK-backed bridges, which delegate to a host
+ * tracer: 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 span context both `startSpan` and `startSpanManual` are called with. */
+interface SentrySpanContext {
+  attributes?: Record<string, unknown>;
+  name: string;
+  op?: string;
+}
+/**
+ * The subset of a Sentry `Span` this bridge drives. Structural, like
+ * {@link SentryLike} itself — a real `@sentry/*` span satisfies it.
+ * @experimental
+ */
+interface SentrySpan {
+  /** Finish the span. Called once, from whichever terminal event closes the call. */
+  end: () => void;
+  /** Attach attributes discovered after the span started (token usage). */
+  setAttributes?: (attributes: Record<string, unknown>) => unknown;
+  /** `1` = OK, `2` = ERROR (Sentry's `SPAN_STATUS_OK` / `SPAN_STATUS_ERROR`). */
+  setStatus?: (status: {
+    code: 0 | 1 | 2;
+    message?: string;
+  }) => unknown;
+}
 /**
  * The minimal, **structural** slice of `@sentry/cloudflare` (equivalently
  * `@sentry/node`/`@sentry/browser`) this bridge needs. `@sentry/cloudflare` is
@@ -214,16 +265,16 @@ declare const otlpTelemetry: (options: OtlpTelemetryOptions) => Telemetry;
 interface SentryLike {
   /** Capture a thrown value / exception. */
   captureException: (exception: unknown) => unknown;
-  /** Run `callback` inside a new span and return its result. */
-  startSpan: <T>(context: {
-    attributes?: Record<string, unknown>;
-    name: string;
-    op?: string;
-  }, callback: (span: {
-    setStatus?: (status: {
-      code: number;
-    } | string) => void;
-  }) => T) => T;
+  /** Run `callback` inside a new span, finished when the callback settles. */
+  startSpan: <T>(context: SentrySpanContext, callback: (span: SentrySpan) => T) => T;
+  /**
+   * Run `callback` inside a new span that is **not** finished automatically —
+   * the caller owns its lifetime through `span.end()`. Present on every Sentry
+   * SDK built on `@sentry/core` (verified against `@sentry/core@10.55.0`); it is
+   * what lets a streamed model call be measured to the end of the stream while
+   * still nesting the provider's own work under it.
+   */
+  startSpanManual: <T>(context: SentrySpanContext, callback: (span: SentrySpan) => T) => T;
 }
 /**
  * Options for {@link sentryTelemetry}.
@@ -241,14 +292,82 @@ interface SentryTelemetryOptions extends CommonOptions {
 /**
  * A dependency-injected Sentry bridge for the ai@7 telemetry surface.
  *
- * It wraps model calls and tool executions in Sentry spans (via
- * `Sentry.startSpan`) so nested provider/tool work is correctly parented, and
- * routes `onError` to `Sentry.captureException`. Span attributes carry only
- * structural metadata (model, provider, tool name) unless `recordInputs` is
- * set, in which case prompts / tool arguments are attached too.
+ * It wraps model calls and tool executions in Sentry spans so nested
+ * provider/tool work is correctly parented, and routes `onError` to
+ * `Sentry.captureException`. Span attributes carry only structural metadata
+ * (model, provider, tool name, token usage) unless `recordInputs` /
+ * `recordOutputs` are set, in which case prompts, tool arguments and generated
+ * text are attached too.
+ *
+ * The tool span is driven by the agent LOOP, not by `ai`: Lunora exposes tools
+ * schema-only so the SDK never executes one (see `telemetry/tool-execution.ts`).
+ *
+ * **A model-call span closes when the CALL ends, not when `execute()` resolves.**
+ * On a streamed turn `execute()` resolves the instant `doStream` hands back the
+ * stream — before a token, before any usage. The span still OPENS around
+ * `execute()`, because that is what makes it the active span nested provider work
+ * parents to, but it is opened with `startSpanManual` and so is not finished
+ * there: `onLanguageModelCallEnd` ends it, once the response is normalized and
+ * the real duration and token usage are both known. `onAbort` / `onError` end the
+ * call they name as a failure, so a stream that dies or is barged in on reports
+ * one instead of a phantom success.
  *
  * The app owns Sentry initialization; pass the namespace in as `Sentry`.
  * @experimental
  */
 declare const sentryTelemetry: (options: SentryTelemetryOptions) => Telemetry;
-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 };
+export {
+/**
+ * `@lunora/agent/telemetry` — observability integrations for `@lunora/agent`.
+ *
+ * Every export here produces an ai@7 `Telemetry` object suitable for the
+ * `integrations` array of `TelemetryOptions` (`defineAgent({ telemetry: {
+ * isEnabled: true, integrations: [...] } })`). `consoleTelemetry` is a
+ * zero-dependency structured console tracer; `combineTelemetry` fans the
+ * lifecycle out to several integrations and nests their execution wrappers;
+ * `sentryTelemetry` / `braintrustTelemetry` are dependency-injected bridges (the
+ * app passes its own Sentry namespace / Braintrust logger, so the heavy SDKs are
+ * never imported here); and `otlpTelemetry` ships `gen_ai.*` spans 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 the app.
+ *
+ * All integrations are privacy-safe by default (`recordInputs` / `recordOutputs`
+ * both default `false`), so nothing sensitive is recorded without opt-in.
+ */
+type BraintrustLike,
+/**
+ * `@lunora/agent/telemetry` — observability integrations for `@lunora/agent`.
+ *
+ * Every export here produces an ai@7 `Telemetry` object suitable for the
+ * `integrations` array of `TelemetryOptions` (`defineAgent({ telemetry: {
+ * isEnabled: true, integrations: [...] } })`). `consoleTelemetry` is a
+ * zero-dependency structured console tracer; `combineTelemetry` fans the
+ * lifecycle out to several integrations and nests their execution wrappers;
+ * `sentryTelemetry` / `braintrustTelemetry` are dependency-injected bridges (the
+ * app passes its own Sentry namespace / Braintrust logger, so the heavy SDKs are
+ * never imported here); and `otlpTelemetry` ships `gen_ai.*` spans 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 the app.
+ *
+ * All integrations are privacy-safe by default (`recordInputs` / `recordOutputs`
+ * both default `false`), so nothing sensitive is recorded without opt-in.
+ */
+type BraintrustSpan,
+/**
+ * `@lunora/agent/telemetry` — observability integrations for `@lunora/agent`.
+ *
+ * Every export here produces an ai@7 `Telemetry` object suitable for the
+ * `integrations` array of `TelemetryOptions` (`defineAgent({ telemetry: {
+ * isEnabled: true, integrations: [...] } })`). `consoleTelemetry` is a
+ * zero-dependency structured console tracer; `combineTelemetry` fans the
+ * lifecycle out to several integrations and nests their execution wrappers;
+ * `sentryTelemetry` / `braintrustTelemetry` are dependency-injected bridges (the
+ * app passes its own Sentry namespace / Braintrust logger, so the heavy SDKs are
+ * never imported here); and `otlpTelemetry` ships `gen_ai.*` spans 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 the app.
+ *
+ * All integrations are privacy-safe by default (`recordInputs` / `recordOutputs`
+ * both default `false`), so nothing sensitive is recorded without opt-in.
+ */
+type BraintrustTelemetryOptions, type CommonOptions, type ConsoleLogLevel, type ConsoleLogger, type ConsoleTelemetryOptions, type OtlpTelemetryOptions, type SentryLike, type SentrySpan, type SentryTelemetryOptions, braintrustTelemetry, combineTelemetry, consoleTelemetry, otlpTelemetry, sentryTelemetry };