@lunora/agent 0.0.0 → 1.0.0-alpha.2

package/dist/sandbox.d.mts

@@ -0,0 +1,200 @@
+import { a as AgentToolContext, b as AgentToolDefinition } from "./packem_shared/types.d-BhJFTvz_.mjs";
+import '@lunora/mail/inbound';
+import 'ai';
+/**
+* The model-provided input to a {@link browserTool} call — a discriminated
+* union on `op` so one tool exposes every headless-browser capability.
+* @experimental
+*/
+type BrowserToolInput = {
+  fullPage?: boolean;
+  op: "screenshot";
+  type?: "jpeg" | "png";
+  url: string;
+} | {
+  op: "content";
+  url: string;
+} | {
+  op: "pdf";
+  url: string;
+} | {
+  op: "scrape";
+  selector?: string;
+  url: string;
+};
+/**
+* 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).
+* @experimental
+*/
+type ContainerToolInput = {
+  args?: string[];
+  command?: string;
+  op: "exec";
+} | {
+  body?: string;
+  method?: string;
+  op: "fetch";
+  path: string;
+};
+/**
+* Author-supplied config for `browserTool`.
+* @experimental
+*/
+interface BrowserToolOptions {
+  /** Override the model-facing description (what the tool does). */
+  description?: string;
+  /**
+  * Gate a call behind a human approval. Defaults to **unattended** (no gate),
+  * matching the AI SDK. `browserTool` fetches a model-chosen `url` with no
+  * allowlist, so it is an SSRF surface: a prompt-injected model can point it at
+  * an internal/link-local address and read the response back into context. Pass
+  * a boolean or a predicate to gate it (evaluated from replay-stable input, so
+  * keep it deterministic).
+  */
+  needsApproval?: ((input: BrowserToolInput) => boolean) | boolean;
+}
+/**
+* The model-provided input to a {@link fsTool} call — a discriminated union on
+* `op` over an R2-backed virtual filesystem. Paths are relative to the tool's
+* pinned `root`; a `..` that escapes the root is rejected server-side.
+* @experimental
+*/
+type FsToolInput = {
+  op: "ls";
+  path?: string;
+} | {
+  op: "read";
+  path: string;
+} | {
+  op: "rm";
+  path: string;
+} | {
+  op: "stat";
+  path: string;
+} | {
+  content: string;
+  op: "write";
+  path: string;
+};
+/**
+* Author-supplied config for `fsTool`.
+* @experimental
+*/
+interface FsToolOptions {
+  /** Override the model-facing description (what the tool does). */
+  description?: string;
+  /**
+  * Gate a call behind a human approval. Defaults to gating the WRITING ops
+  * (`write`, `rm`) — a prompt-injected model shouldn't silently overwrite or
+  * delete the sandbox — while `ls`/`read`/`stat` run unattended. Pass a boolean
+  * or a predicate (evaluated from replay-stable input, so keep it deterministic).
+  */
+  needsApproval?: ((input: FsToolInput) => boolean) | boolean;
+  /**
+  * The key prefix every path is scoped under, isolating this tool's files from
+  * the rest of the bucket. Either a fixed string (e.g. `"agents/support"`) or a
+  * function of the tool context — return `` `agents/${ctx.threadKey}` `` (or an
+  * owner-derived prefix) to give each run/user its OWN namespace in a
+  * multi-tenant agent. Default: the bucket root (shared — set a root for
+  * multi-tenant use). The server rejects any `..` that would escape it.
+  */
+  root?: ((context: AgentToolContext) => string) | string;
+}
+/**
+* Author-supplied config for `containerTool`.
+* @experimental
+*/
+interface ContainerToolOptions {
+  /** Override the model-facing description (what the tool does). */
+  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.
+  */
+  needsApproval?: ((input: ContainerToolInput) => boolean) | boolean;
+}
+/**
+* A batteries-included agent tool that drives Cloudflare Browser Rendering. One
+* tool exposes every browser op (screenshot / pdf / content / scrape); the model
+* picks via `op`. The call dispatches to the auto-registered `sandbox:invoke`
+* action — which runs on an action ctx carrying `ctx.browser`. Importing the tool
+* makes codegen register the dispatcher and provision the `BROWSER` binding; like
+* any `ctx.browser` user, the app still supplies a `config.browser` thunk
+* (`createBrowser({ binding: env.BROWSER, launch })` with the optional
+* `@cloudflare/playwright` `launch` peer) to `createShardDO()` — codegen never
+* injects that peer, so the browser op throws a directed error until it is wired.
+*
+* Security: the model chooses the `url` with no allowlist, so this is an SSRF
+* surface — pass `opts.needsApproval` to gate calls a prompt-injected model
+* could aim at internal/link-local endpoints.
+*
+* ```ts
+* import { browserTool, defineAgent } from "@lunora/agent/sandbox";
+*
+* export const researcher = defineAgent({
+*     model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
+*     tools: { browser: browserTool() },
+* });
+* ```
+* @experimental
+*/
+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`
+* 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 `fetch` runs unattended while command execution is gated behind a
+* human approval — 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). Note a `fetch` can still reach any *other* container route
+* unattended, so scope the container's routes accordingly. Pass
+* `opts.needsApproval` to widen or disable the gate.
+*
+* ```ts
+* import { containerTool, defineAgent } from "@lunora/agent/sandbox";
+*
+* export const ops = defineAgent({
+*     model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
+*     tools: { sandbox: containerTool("sandbox") },
+* });
+* ```
+* @experimental
+*/
+declare const containerTool: (name: string, options?: ContainerToolOptions) => AgentToolDefinition<ContainerToolInput, string>;
+/**
+* A batteries-included agent tool exposing a persistent, R2-backed virtual
+* filesystem. `bucket` is the R2 binding name; every path is scoped under the
+* pinned `opts.root` (a `..` that would escape it is rejected). One tool exposes
+* `ls`/`read`/`write`/`rm`/`stat`; the model picks via `op`. The call dispatches
+* to the auto-registered `sandbox:invoke` action, which reads the bucket from
+* `ctx.env`. workerd has no real shell — this is object-store-backed file I/O.
+*
+* By default the writing ops (`write`/`rm`) pause for a human approval while
+* reads run unattended; pass `opts.needsApproval` to change that. Importing the
+* tool registers the dispatcher; the app must declare the `r2_bucket` binding in
+* `wrangler.jsonc` (the fs op throws a directed error until it is wired).
+*
+* ```ts
+* import { defineAgent, fsTool } from "@lunora/agent/sandbox";
+*
+* export const coder = defineAgent({
+*     model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
+*     tools: { fs: fsTool("SANDBOX_BUCKET", { root: "agents/coder" }) },
+* });
+* ```
+* @experimental
+*/
+declare const fsTool: (bucket: string, options?: FsToolOptions) => AgentToolDefinition<FsToolInput>;
+export { type BrowserToolInput, type BrowserToolOptions, type ContainerToolInput, type ContainerToolOptions, type FsToolInput, type FsToolOptions, browserTool, containerTool, fsTool };

package/dist/sandbox.d.ts

@@ -0,0 +1,200 @@
+import { a as AgentToolContext, b as AgentToolDefinition } from "./packem_shared/types.d-BhJFTvz_.js";
+import '@lunora/mail/inbound';
+import 'ai';
+/**
+* The model-provided input to a {@link browserTool} call — a discriminated
+* union on `op` so one tool exposes every headless-browser capability.
+* @experimental
+*/
+type BrowserToolInput = {
+  fullPage?: boolean;
+  op: "screenshot";
+  type?: "jpeg" | "png";
+  url: string;
+} | {
+  op: "content";
+  url: string;
+} | {
+  op: "pdf";
+  url: string;
+} | {
+  op: "scrape";
+  selector?: string;
+  url: string;
+};
+/**
+* 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).
+* @experimental
+*/
+type ContainerToolInput = {
+  args?: string[];
+  command?: string;
+  op: "exec";
+} | {
+  body?: string;
+  method?: string;
+  op: "fetch";
+  path: string;
+};
+/**
+* Author-supplied config for `browserTool`.
+* @experimental
+*/
+interface BrowserToolOptions {
+  /** Override the model-facing description (what the tool does). */
+  description?: string;
+  /**
+  * Gate a call behind a human approval. Defaults to **unattended** (no gate),
+  * matching the AI SDK. `browserTool` fetches a model-chosen `url` with no
+  * allowlist, so it is an SSRF surface: a prompt-injected model can point it at
+  * an internal/link-local address and read the response back into context. Pass
+  * a boolean or a predicate to gate it (evaluated from replay-stable input, so
+  * keep it deterministic).
+  */
+  needsApproval?: ((input: BrowserToolInput) => boolean) | boolean;
+}
+/**
+* The model-provided input to a {@link fsTool} call — a discriminated union on
+* `op` over an R2-backed virtual filesystem. Paths are relative to the tool's
+* pinned `root`; a `..` that escapes the root is rejected server-side.
+* @experimental
+*/
+type FsToolInput = {
+  op: "ls";
+  path?: string;
+} | {
+  op: "read";
+  path: string;
+} | {
+  op: "rm";
+  path: string;
+} | {
+  op: "stat";
+  path: string;
+} | {
+  content: string;
+  op: "write";
+  path: string;
+};
+/**
+* Author-supplied config for `fsTool`.
+* @experimental
+*/
+interface FsToolOptions {
+  /** Override the model-facing description (what the tool does). */
+  description?: string;
+  /**
+  * Gate a call behind a human approval. Defaults to gating the WRITING ops
+  * (`write`, `rm`) — a prompt-injected model shouldn't silently overwrite or
+  * delete the sandbox — while `ls`/`read`/`stat` run unattended. Pass a boolean
+  * or a predicate (evaluated from replay-stable input, so keep it deterministic).
+  */
+  needsApproval?: ((input: FsToolInput) => boolean) | boolean;
+  /**
+  * The key prefix every path is scoped under, isolating this tool's files from
+  * the rest of the bucket. Either a fixed string (e.g. `"agents/support"`) or a
+  * function of the tool context — return `` `agents/${ctx.threadKey}` `` (or an
+  * owner-derived prefix) to give each run/user its OWN namespace in a
+  * multi-tenant agent. Default: the bucket root (shared — set a root for
+  * multi-tenant use). The server rejects any `..` that would escape it.
+  */
+  root?: ((context: AgentToolContext) => string) | string;
+}
+/**
+* Author-supplied config for `containerTool`.
+* @experimental
+*/
+interface ContainerToolOptions {
+  /** Override the model-facing description (what the tool does). */
+  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.
+  */
+  needsApproval?: ((input: ContainerToolInput) => boolean) | boolean;
+}
+/**
+* A batteries-included agent tool that drives Cloudflare Browser Rendering. One
+* tool exposes every browser op (screenshot / pdf / content / scrape); the model
+* picks via `op`. The call dispatches to the auto-registered `sandbox:invoke`
+* action — which runs on an action ctx carrying `ctx.browser`. Importing the tool
+* makes codegen register the dispatcher and provision the `BROWSER` binding; like
+* any `ctx.browser` user, the app still supplies a `config.browser` thunk
+* (`createBrowser({ binding: env.BROWSER, launch })` with the optional
+* `@cloudflare/playwright` `launch` peer) to `createShardDO()` — codegen never
+* injects that peer, so the browser op throws a directed error until it is wired.
+*
+* Security: the model chooses the `url` with no allowlist, so this is an SSRF
+* surface — pass `opts.needsApproval` to gate calls a prompt-injected model
+* could aim at internal/link-local endpoints.
+*
+* ```ts
+* import { browserTool, defineAgent } from "@lunora/agent/sandbox";
+*
+* export const researcher = defineAgent({
+*     model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
+*     tools: { browser: browserTool() },
+* });
+* ```
+* @experimental
+*/
+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`
+* 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 `fetch` runs unattended while command execution is gated behind a
+* human approval — 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). Note a `fetch` can still reach any *other* container route
+* unattended, so scope the container's routes accordingly. Pass
+* `opts.needsApproval` to widen or disable the gate.
+*
+* ```ts
+* import { containerTool, defineAgent } from "@lunora/agent/sandbox";
+*
+* export const ops = defineAgent({
+*     model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
+*     tools: { sandbox: containerTool("sandbox") },
+* });
+* ```
+* @experimental
+*/
+declare const containerTool: (name: string, options?: ContainerToolOptions) => AgentToolDefinition<ContainerToolInput, string>;
+/**
+* A batteries-included agent tool exposing a persistent, R2-backed virtual
+* filesystem. `bucket` is the R2 binding name; every path is scoped under the
+* pinned `opts.root` (a `..` that would escape it is rejected). One tool exposes
+* `ls`/`read`/`write`/`rm`/`stat`; the model picks via `op`. The call dispatches
+* to the auto-registered `sandbox:invoke` action, which reads the bucket from
+* `ctx.env`. workerd has no real shell — this is object-store-backed file I/O.
+*
+* By default the writing ops (`write`/`rm`) pause for a human approval while
+* reads run unattended; pass `opts.needsApproval` to change that. Importing the
+* tool registers the dispatcher; the app must declare the `r2_bucket` binding in
+* `wrangler.jsonc` (the fs op throws a directed error until it is wired).
+*
+* ```ts
+* import { defineAgent, fsTool } from "@lunora/agent/sandbox";
+*
+* export const coder = defineAgent({
+*     model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
+*     tools: { fs: fsTool("SANDBOX_BUCKET", { root: "agents/coder" }) },
+* });
+* ```
+* @experimental
+*/
+declare const fsTool: (bucket: string, options?: FsToolOptions) => AgentToolDefinition<FsToolInput>;
+export { type BrowserToolInput, type BrowserToolOptions, type ContainerToolInput, type ContainerToolOptions, type FsToolInput, type FsToolOptions, browserTool, containerTool, fsTool };

package/dist/sandbox.mjs

@@ -0,0 +1,109 @@
+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 defaultContainerGate = (input) => {
+  if (input.op === "exec") {
+    return true;
+  }
+  return normalizeContainerPath(input.path) === CONTAINER_EXEC_ROUTE;
+};
+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 };

package/dist/telemetry/index.d.mts

@@ -0,0 +1,173 @@
+import { Telemetry } from 'ai';
+/**
+* Privacy options shared by every telemetry integration in this package.
+*
+* Both flags default to **FALSE**. Without an explicit opt-in, no prompt,
+* message, tool input, generated model text, or tool output is ever forwarded
+* to a downstream tracer — only structural metadata (model id, finish reason,
+* token counts, tool name, timing, success/failure) is recorded. This is the
+* privacy-safe default: turn recording on deliberately, per integration.
+* @experimental
+*/
+interface CommonOptions {
+  /**
+  * When `true`, record model/tool **input** — prompts, messages, and tool
+  * call arguments. Default `false`.
+  */
+  recordInputs?: boolean;
+  /**
+  * When `true`, record model/tool **output** — generated text and tool
+  * results. Default `false`.
+  */
+  recordOutputs?: boolean;
+}
+/**
+* The span handle a {@link BraintrustLike.traced} callback receives.
+* @experimental
+*/
+interface BraintrustSpan {
+  /** Attach structured fields to the current span. */
+  log: (event: Record<string, unknown>) => void;
+}
+/**
+* The minimal, **structural** slice of the `braintrust` SDK this bridge needs.
+* `braintrust` is intentionally **not** a dependency — the app passes its own
+* initialized logger, so this package stays dependency-free and works with any
+* compatible Braintrust SDK version.
+* @experimental
+*/
+interface BraintrustLike {
+  /** Run `callback` inside a new traced span and return its result. */
+  traced: <T>(callback: (span: BraintrustSpan) => T, args?: {
+    name?: string;
+    type?: string;
+  }) => T;
+}
+/**
+* Options for {@link braintrustTelemetry}.
+* @experimental
+*/
+interface BraintrustTelemetryOptions extends CommonOptions {
+  /** Span-name prefix for the language-model call (e.g. the agent name). */
+  functionId?: string;
+  /**
+  * The caller's initialized Braintrust logger (dependency-injected). Import
+  * and initialize `braintrust` in your app and pass it as `logger`.
+  */
+  logger: BraintrustLike;
+}
+/**
+* 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.
+*
+* The app owns Braintrust initialization; pass the logger in as `logger`.
+* @experimental
+*/
+declare const braintrustTelemetry: (options: BraintrustTelemetryOptions) => Telemetry;
+/**
+* Combine several {@link Telemetry} integrations into a single one that fans
+* every lifecycle callback out to all of them and nests the two execution
+* wrappers so multiple span-context wrappers compose correctly.
+*
+* Value callbacks (`onStart`, `onStepEnd`, `onToolExecutionEnd`, …) invoke each
+* integration's matching callback (guarding `undefined`) and await them all in
+* parallel. The wrappers (`executeLanguageModelCall`, `executeTool`) are
+* composed by nesting right-to-left; integrations without a wrapper are skipped,
+* and with none defined the plain `execute` still runs.
+* @experimental
+*/
+declare const combineTelemetry: (...integrations: Telemetry[]) => Telemetry;
+/**
+* Severity level passed to a {@link ConsoleLogger}.
+* @experimental
+*/
+type ConsoleLogLevel = "error" | "info" | "warn";
+/**
+* Structured log sink. Receives a level, a static human message, and a bag of
+* structured fields (never interpolated into the message, so log processors can
+* index them). The default sink writes to `globalThis.console`.
+* @experimental
+*/
+type ConsoleLogger = (level: ConsoleLogLevel, message: string, fields: Record<string, unknown>) => void;
+/**
+* Options for {@link consoleTelemetry}.
+* @experimental
+*/
+interface ConsoleTelemetryOptions extends CommonOptions {
+  /**
+  * Identifier prefixed into every log message (e.g. the agent name). Helps
+  * correlate lines when several agents share one process. Optional.
+  */
+  functionId?: string;
+  /**
+  * Sink for structured log lines. Defaults to a `globalThis.console`-backed
+  * writer that routes `info`/`warn`/`error` to the matching console method.
+  */
+  logger?: ConsoleLogger;
+}
+/**
+* A zero-dependency structured tracer for the ai@7 telemetry surface.
+*
+* It maps the generation lifecycle onto {@link ConsoleLogger} calls: operation
+* start/end, per-step start/end, model-call end (model + finish reason +
+* usage), and tool start/end (name, success, timing). By default it records
+* **only structural metadata** — set `recordInputs` to also log prompts / tool
+* arguments, and `recordOutputs` to log generated text / tool results.
+*
+* Every callback is defensive (event fields may be absent) and synchronous.
+* @experimental
+*/
+declare const consoleTelemetry: (options?: ConsoleTelemetryOptions) => Telemetry;
+/**
+* The minimal, **structural** slice of `@sentry/cloudflare` (equivalently
+* `@sentry/node`/`@sentry/browser`) this bridge needs. `@sentry/cloudflare` is
+* intentionally **not** a dependency — the app passes its own already-initialized
+* Sentry namespace, so this package stays dependency-free and works with any
+* compatible Sentry SDK version.
+* @experimental
+*/
+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;
+}
+/**
+* Options for {@link sentryTelemetry}.
+* @experimental
+*/
+interface SentryTelemetryOptions extends CommonOptions {
+  /** Span-name prefix for the language-model call (e.g. the agent name). */
+  functionId?: string;
+  /**
+  * The caller's already-initialized Sentry namespace (dependency-injected).
+  * `import * as Sentry from "@sentry/cloudflare"` and pass it as `Sentry`.
+  */
+  Sentry: SentryLike;
+}
+/**
+* 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.
+*
+* 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 SentryLike, type SentryTelemetryOptions, braintrustTelemetry, combineTelemetry, consoleTelemetry, sentryTelemetry };