@lunora/agent 1.0.0-alpha.1 → 1.0.0-alpha.10

package/dist/sandbox.d.mts

@@ -1,10 +1,11 @@
-import { a as AgentToolContext, b as AgentToolDefinition } from "./packem_shared/types.d-BWG0uUtX.mjs";
+import { a as AgentToolContext, b as AgentToolDefinition } from "./packem_shared/types.d-boAM2Yi1.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.
-*/
+ * 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";
@@ -22,11 +23,12 @@ type BrowserToolInput = {
   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).
-*/
+ * 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;
@@ -37,25 +39,29 @@ type ContainerToolInput = {
   op: "fetch";
   path: string;
 };
-/** Author-supplied config for `browserTool`. */
+/**
+ * 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).
-  */
+   * 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.
-*/
+ * 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;
@@ -73,113 +79,126 @@ type FsToolInput = {
   op: "write";
   path: string;
 };
-/** Author-supplied config for `fsTool`. */
+/**
+ * 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).
-  */
+   * 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.
-  */
+   * 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`. */
+/**
+ * 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.
-  */
+   * 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() },
-* });
-* ```
-*/
+ * 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") },
-* });
-* ```
-*/
+ * 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 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
+ * 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);
+ * 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`
+ * 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.
+ *
+ * ```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" }) },
-* });
-* ```
-*/
+ * 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

@@ -1,10 +1,11 @@
-import { a as AgentToolContext, b as AgentToolDefinition } from "./packem_shared/types.d-BWG0uUtX.js";
+import { a as AgentToolContext, b as AgentToolDefinition } from "./packem_shared/types.d-boAM2Yi1.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.
-*/
+ * 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";
@@ -22,11 +23,12 @@ type BrowserToolInput = {
   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).
-*/
+ * 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;
@@ -37,25 +39,29 @@ type ContainerToolInput = {
   op: "fetch";
   path: string;
 };
-/** Author-supplied config for `browserTool`. */
+/**
+ * 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).
-  */
+   * 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.
-*/
+ * 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;
@@ -73,113 +79,126 @@ type FsToolInput = {
   op: "write";
   path: string;
 };
-/** Author-supplied config for `fsTool`. */
+/**
+ * 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).
-  */
+   * 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.
-  */
+   * 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`. */
+/**
+ * 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.
-  */
+   * 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() },
-* });
-* ```
-*/
+ * 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") },
-* });
-* ```
-*/
+ * 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 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
+ * 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);
+ * 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`
+ * 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.
+ *
+ * ```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" }) },
-* });
-* ```
-*/
+ * 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

@@ -44,11 +44,15 @@ const normalizeContainerPath = (path) => {
   }
   return `/${segments.join("/")}`;
 };
+const NON_IDEMPOTENT_METHODS = /* @__PURE__ */ new Set(["DELETE", "PATCH", "POST", "PUT"]);
 const defaultContainerGate = (input) => {
   if (input.op === "exec") {
     return true;
   }
-  return normalizeContainerPath(input.path) === CONTAINER_EXEC_ROUTE;
+  if (normalizeContainerPath(input.path) === CONTAINER_EXEC_ROUTE) {
+    return true;
+  }
+  return NON_IDEMPOTENT_METHODS.has((input.method ?? "GET").toUpperCase());
 };
 const CONTAINER_TOOL_SCHEMA = jsonSchema({
   properties: {