@boardwalk-labs/runner 0.1.2

package/dist/runtime/tools/artifacts.d.ts

@@ -0,0 +1,146 @@
+import { z } from "zod";
+import type { BoardwalkTool } from "./types.js";
+declare const artifactsInput: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    op: z.ZodLiteral<"write">;
+    name: z.ZodString;
+    content_type: z.ZodString;
+    body: z.ZodString;
+    encoding: z.ZodOptional<z.ZodEnum<{
+        utf8: "utf8";
+        base64: "base64";
+    }>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"list">;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"signed_url">;
+    artifact_id: z.ZodString;
+    ttl_seconds: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>], "op">;
+type ArtifactsInput = z.infer<typeof artifactsInput>;
+declare const artifactSummary: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    contentType: z.ZodString;
+    sizeBytes: z.ZodNumber;
+    createdAt: z.ZodNumber;
+}, z.core.$strip>;
+export type ArtifactSummary = z.infer<typeof artifactSummary>;
+declare const artifactsData: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    op: z.ZodLiteral<"write">;
+    id: z.ZodString;
+    name: z.ZodString;
+    sizeBytes: z.ZodNumber;
+    signedUrl: z.ZodString;
+    expiresAt: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"list">;
+    artifacts: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        contentType: z.ZodString;
+        sizeBytes: z.ZodNumber;
+        createdAt: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"signed_url">;
+    id: z.ZodString;
+    signedUrl: z.ZodString;
+    expiresAt: z.ZodNumber;
+}, z.core.$strip>], "op">;
+export type ArtifactsData = z.infer<typeof artifactsData>;
+declare const artifactsOutput: z.ZodObject<{
+    kind: z.ZodLiteral<"artifacts">;
+    humanSummary: z.ZodString;
+    data: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        op: z.ZodLiteral<"write">;
+        id: z.ZodString;
+        name: z.ZodString;
+        sizeBytes: z.ZodNumber;
+        signedUrl: z.ZodString;
+        expiresAt: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        op: z.ZodLiteral<"list">;
+        artifacts: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            contentType: z.ZodString;
+            sizeBytes: z.ZodNumber;
+            createdAt: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        op: z.ZodLiteral<"signed_url">;
+        id: z.ZodString;
+        signedUrl: z.ZodString;
+        expiresAt: z.ZodNumber;
+    }, z.core.$strip>], "op">;
+}, z.core.$strip>;
+export type ArtifactsOutput = z.infer<typeof artifactsOutput>;
+/** What the tool asks the store to persist. The store owns the S3 key, content-type neutralization,
+ *  the actual write, and the catalog row — none of which the (untrusted) runner controls. */
+export interface ArtifactWriteInput {
+    name: string;
+    contentType: string;
+    /** The body as a string; `encoding` says how to decode it. */
+    body: string;
+    encoding?: "utf8" | "base64";
+    metadata?: Record<string, unknown>;
+}
+export interface ArtifactWriteResult {
+    id: string;
+    name: string;
+    sizeBytes: number;
+    signedUrl: string;
+    /** Absolute expiry (ms since epoch) of the returned signed URL. */
+    expiresAt: number;
+}
+export interface ArtifactSignResult {
+    signedUrl: string;
+    expiresAt: number;
+}
+/** Phase 1 of the large-artifact path: what the worker asks the broker to presign. The bytes then go
+ *  straight to S3, never through the broker. `sizeBytes` is the decoded body length the runner reports
+ *  (the broker re-validates it against the hard ceiling and rejects an over-cap artifact BEFORE the
+ *  runner uploads). No catalog row is written yet — that happens at commit. */
+export interface ArtifactPresignInput {
+    name: string;
+    contentType: string;
+    sizeBytes: number;
+}
+/** The broker's presign response: where + how to PUT the bytes, and the chosen `s3Key` the worker
+ *  echoes back at commit. No catalog id / download URL yet — the row doesn't exist until the upload
+ *  succeeds and the worker commits. */
+export interface ArtifactPresignResult {
+    /** The S3 key the broker derived (under the run's prefix); echoed back to {@link commitArtifact}. */
+    s3Key: string;
+    /** Presigned S3 PUT URL — the runner uploads the bytes here directly (no broker body cap). */
+    uploadUrl: string;
+    /** Headers the PUT MUST send: the content type is pinned into the presigned signature, so a
+     *  mismatched type is rejected by S3 (the runner can't store an active/XSS-able served type). */
+    uploadHeaders: Record<string, string>;
+    expiresAt: number;
+}
+/** Phase 2 of the large-artifact path: register the catalog row AFTER the bytes have landed in S3.
+ *  The worker echoes the presign's `s3Key`; the broker re-validates the run prefix + re-neutralizes
+ *  the content type server-side. Returns an {@link ArtifactWriteResult} (id + signed download URL). */
+export interface ArtifactCommitInput {
+    s3Key: string;
+    name: string;
+    contentType: string;
+    sizeBytes: number;
+    metadata?: Record<string, unknown>;
+}
+/** The storage backend the tool delegates to. The run is implied (the store is per-run bound —
+ *  brokered: the run token; local: the run's context). */
+export interface ArtifactStore {
+    write(input: ArtifactWriteInput): Promise<ArtifactWriteResult>;
+    list(): Promise<ArtifactSummary[]>;
+    signedUrl(artifactId: string, ttlSeconds: number): Promise<ArtifactSignResult>;
+}
+export interface ArtifactsDeps {
+    store: ArtifactStore;
+    /** Default TTL for the `signed_url` op when the caller doesn't request one. */
+    defaultTtlSeconds?: number;
+}
+export declare function makeArtifactsTool(deps: ArtifactsDeps): BoardwalkTool<ArtifactsInput, ArtifactsOutput>;
+export {};

package/dist/runtime/tools/artifacts.js

@@ -0,0 +1,125 @@
+// artifacts — persist + reference run outputs (MASTER_SPEC §9.1 + §13.6). Available to any agent
+// (no sandbox required). Three operations:
+//   * write(name, content_type, body)   → store a file under the run's prefix; returns id + a signed URL.
+//   * list()                            → artifacts produced in THIS run.
+//   * signed_url(artifact_id, ttl?)     → mint a fresh signed download URL.
+//
+// This tool is a THIN agent-facing surface: it validates input + formats output and delegates the
+// actual storage to an injected `ArtifactStore`. Under the Runner Credential Broker
+// (docs/RUNNER_BROKER.md) the store is broker-backed — the broker computes the S3 key, neutralizes
+// the content type (review #32), PUTs with its own creds, and records the catalog row, so the
+// untrusted runner holds no S3 credential and can't bypass those server-side rules.
+import { z } from "zod";
+import { ARTIFACT_MAX_BYTES } from "../wire/artifact_storage.js";
+// Body cap: a small write travels through the broker's buffered Runner Control endpoint (≤5 MiB
+// wire); a large one takes the presigned-PUT path (docs/RUNNER_BROKER.md §7 step 4) that streams the
+// body straight to S3. Either way the artifact is bounded by ARTIFACT_MAX_BYTES — the cap here is on
+// the body STRING, sized for a full-size binary artifact carried as base64 (~4/3 inflation). The
+// broker re-validates the true byte size server-side (the authoritative check).
+const MAX_BODY_CHARS = Math.ceil(ARTIFACT_MAX_BYTES / 3) * 4;
+const MAX_TTL_SECONDS = 7 * 24 * 60 * 60;
+const DEFAULT_TTL_SECONDS = 3600;
+const artifactsInput = z.discriminatedUnion("op", [
+    z.object({
+        op: z.literal("write"),
+        name: z.string().min(1).max(255),
+        content_type: z.string().min(1).max(200),
+        body: z.string().max(MAX_BODY_CHARS),
+        /** How `body` is encoded. `base64` lets agents persist binary content. */
+        encoding: z.enum(["utf8", "base64"]).optional(),
+        metadata: z.record(z.string(), z.unknown()).optional(),
+    }),
+    z.object({ op: z.literal("list") }),
+    z.object({
+        op: z.literal("signed_url"),
+        artifact_id: z.string().min(1).max(64),
+        ttl_seconds: z.number().int().positive().max(MAX_TTL_SECONDS).optional(),
+    }),
+]);
+const artifactSummary = z.object({
+    id: z.string(),
+    name: z.string(),
+    contentType: z.string(),
+    sizeBytes: z.number(),
+    createdAt: z.number(),
+});
+const artifactsData = z.discriminatedUnion("op", [
+    z.object({
+        op: z.literal("write"),
+        id: z.string(),
+        name: z.string(),
+        sizeBytes: z.number(),
+        signedUrl: z.string(),
+        expiresAt: z.number(),
+    }),
+    z.object({ op: z.literal("list"), artifacts: z.array(artifactSummary) }),
+    z.object({
+        op: z.literal("signed_url"),
+        id: z.string(),
+        signedUrl: z.string(),
+        expiresAt: z.number(),
+    }),
+]);
+const artifactsOutput = z.object({
+    kind: z.literal("artifacts"),
+    humanSummary: z.string(),
+    data: artifactsData,
+});
+export function makeArtifactsTool(deps) {
+    const defaultTtl = deps.defaultTtlSeconds ?? DEFAULT_TTL_SECONDS;
+    return {
+        name: "artifacts",
+        description: "Persist and reference run outputs. write({name, content_type, body}) stores a file; list() shows this run's artifacts; signed_url({artifact_id}) mints a download link.",
+        inputSchema: artifactsInput,
+        outputSchema: artifactsOutput,
+        secretsRequired: [],
+        async invoke(input, _ctx) {
+            switch (input.op) {
+                case "write": {
+                    const writeInput = {
+                        name: input.name,
+                        contentType: input.content_type,
+                        body: input.body,
+                        ...(input.encoding !== undefined ? { encoding: input.encoding } : {}),
+                        ...(input.metadata !== undefined ? { metadata: input.metadata } : {}),
+                    };
+                    const r = await deps.store.write(writeInput);
+                    return {
+                        kind: "artifacts",
+                        humanSummary: `Wrote artifact ${r.name} (${r.sizeBytes.toString()} bytes)`,
+                        data: {
+                            op: "write",
+                            id: r.id,
+                            name: r.name,
+                            sizeBytes: r.sizeBytes,
+                            signedUrl: r.signedUrl,
+                            expiresAt: r.expiresAt,
+                        },
+                    };
+                }
+                case "list": {
+                    const artifacts = await deps.store.list();
+                    return {
+                        kind: "artifacts",
+                        humanSummary: `Listed ${artifacts.length.toString()} artifact(s) for this run`,
+                        data: { op: "list", artifacts },
+                    };
+                }
+                case "signed_url": {
+                    const ttl = input.ttl_seconds ?? defaultTtl;
+                    const r = await deps.store.signedUrl(input.artifact_id, ttl);
+                    return {
+                        kind: "artifacts",
+                        humanSummary: `Minted signed URL for artifact ${input.artifact_id}`,
+                        data: {
+                            op: "signed_url",
+                            id: input.artifact_id,
+                            signedUrl: r.signedUrl,
+                            expiresAt: r.expiresAt,
+                        },
+                    };
+                }
+            }
+        },
+    };
+}

package/dist/runtime/tools/types.d.ts

@@ -0,0 +1,114 @@
+import type { z } from "zod";
+import type { AuthContext } from "../support/index.js";
+import type { SecretRefManifest } from "../wire/manifest.js";
+/**
+ * Per-invocation context the worker threads through to a tool. Equivalent to
+ * Strands' `ToolContext` but typed in Boardwalk's idiom (AuthContext + run id +
+ * secret resolver scoped to this run's permissions).
+ */
+export interface ToolContext {
+    readonly auth: AuthContext;
+    /** Run id (`runs.id`). Used for tagging artifacts + correlation. */
+    readonly runId: string;
+    /** Org-scoped resolver. Returns the secret VALUE, not the ARN. */
+    readonly secrets: SecretResolver;
+}
+export interface SecretResolver {
+    /**
+     * Resolve a manifest secret reference to its plaintext value. Throws
+     * `AppError(FORBIDDEN)` when the reference isn't in the agent's
+     * `permissions.secrets` allowlist, or `AppError(NOT_FOUND)` when the named
+     * secret doesn't exist in the org.
+     */
+    resolve(ref: SecretRefManifest): Promise<string>;
+}
+/**
+ * Boardwalk-side tool interface. Concrete tools either:
+ *   * Return a `ToolReturn` body — synchronous "normal" tools (echo, http,
+ *     web_search). The body lands in the conversation as the assistant's
+ *     tool-result block.
+ *   * Return a `ToolControlSignal` — the legacy Strands-level sleep/workflows.call path. The
+ *     current JS-body worker exposes these as program SDK hooks instead; agent() leaves strip
+ *     control-flow tools before registering model-callable tools.
+ */
+export interface BoardwalkTool<TInput = unknown, TOutput = unknown> {
+    /** Stable tool name — what an `agent()` call names in `AgentOptions.tools`. */
+    readonly name: string;
+    /** Description surfaced to the model. */
+    readonly description: string;
+    /** Zod schema for the tool's input. */
+    readonly inputSchema: z.ZodType<TInput>;
+    /**
+     * Zod schema for the tool's SUCCESS output (the `TOutput` shape — never the
+     * control-signal branch). The adapter validates the tool's return value
+     * against this before it lands in the LLM conversation, per CODE_QUALITY
+     * §2.1/§8.3 (LLM-facing output is treated like untrusted external input).
+     */
+    readonly outputSchema: z.ZodType<TOutput>;
+    /**
+     * Secret names this tool requires (matching entries in the org's secret
+     * store / the manifest's `permissions.secrets` allowlist). Used for
+     * declarative per-tool secret scoping in the sandbox. Most built-ins are
+     * `[]` because they either need no secrets or receive them via `ctx`
+     * (resolved env / `ctx.secrets`); `web_search` declares the Tavily key.
+     */
+    readonly secretsRequired: readonly string[];
+    /**
+     * Optional: normalize the raw LLM-supplied args BEFORE `inputSchema.parse`. Lets a tool accept a
+     * common-but-wrong shape the model tends to emit (e.g. `{command:"clone"}` aliased to the schema's
+     * `{op:"clone"}` discriminator) so the first attempt succeeds instead of bouncing off a `ZodError`
+     * and costing a retry. Keeps `inputSchema` (the model-facing JSON schema) pristine — the alias is
+     * applied at the adapter's parse boundary, never exposed. Must be pure + total (return the input
+     * unchanged when nothing applies).
+     */
+    normalizeInput?(raw: unknown): unknown;
+    /**
+     * Invoke the tool. `input` (LLM-supplied) comes first, `ctx` (worker-supplied)
+     * second — see the `Tool` naming note in SPEC §9. Returns either the typed
+     * `TOutput` body or a `ToolControlSignal` (sleep / workflows.call) the worker
+     * intercepts before serialization.
+     */
+    invoke(input: TInput, ctx: ToolContext): Promise<TOutput | ToolControlSignal>;
+}
+/**
+ * Discriminated union of "I'm not really returning a result; tell the engine
+ * something." Worker checks `result instanceof ToolControlSignal` (well —
+ * structurally on `__signal`) before serializing into the conversation.
+ */
+export type ToolControlSignal = SleepControlSignal | WaitForChildControlSignal;
+export interface SleepControlSignal {
+    readonly __signal: "sleep";
+    /** Wall-clock time to wake at (ms since epoch). */
+    readonly wakeAtMs: number;
+}
+export interface WaitForChildControlSignal {
+    readonly __signal: "wait_for_child";
+    /** The child run id the parent is now blocked on. */
+    readonly childRunId: string;
+}
+export declare function isControlSignal(value: unknown): value is ToolControlSignal;
+/**
+ * Tool registry — maps a tool name to its concrete `BoardwalkTool`. Built once
+ * per worker process; each `agent()` leaf sees a filtered view based on the
+ * tools that call named (`AgentOptions.tools`), materialized via
+ * `materializeFor(grants)`.
+ */
+export declare class ToolRegistry {
+    private readonly tools;
+    register(tool: BoardwalkTool): void;
+    get(name: string): BoardwalkTool | undefined;
+    has(name: string): boolean;
+    /** Names of every registered tool. Used by the `list_tools` MCP tool. */
+    list(): string[];
+    /**
+     * Filter the registry down to the tools granted by a manifest. Names absent
+     * from the registry are returned in `missing` so the worker can fail-loud
+     * before the LLM tries to call something that doesn't exist.
+     */
+    materializeFor(grants: readonly {
+        name: string;
+    }[]): {
+        tools: BoardwalkTool[];
+        missing: string[];
+    };
+}

package/dist/runtime/tools/types.js

@@ -0,0 +1,61 @@
+// Boardwalk's internal Tool contract. Concrete tools (`echo`, `http`, `web_search`, `sleep`,
+// `workflows.call`, …) implement this interface; the worker registers a `ZodTool`-flavored
+// adapter into Strands at agent construction time.
+//
+// Why a Boardwalk-side interface instead of using `ZodTool` directly?
+//   * Tests can drive tool logic without instantiating Strands.
+//   * Control-signal tools (`sleep`, `workflows.call`) need to return a
+//     specially-shaped value the worker interprets — they don't really "run";
+//     they bubble a signal up to the engine. Our adapter (lands with the worker
+//     in Phase 10.5) translates between this interface and the Strands surface.
+//
+// Per MASTER_SPEC §12: tools NEVER see secret values. Secrets resolve to
+// short-lived bearer tokens, ARNs, etc. via the injected `SecretResolver`.
+export function isControlSignal(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "__signal" in value &&
+        typeof value.__signal === "string");
+}
+/**
+ * Tool registry — maps a tool name to its concrete `BoardwalkTool`. Built once
+ * per worker process; each `agent()` leaf sees a filtered view based on the
+ * tools that call named (`AgentOptions.tools`), materialized via
+ * `materializeFor(grants)`.
+ */
+export class ToolRegistry {
+    tools = new Map();
+    register(tool) {
+        if (this.tools.has(tool.name)) {
+            throw new Error(`Tool ${tool.name} is already registered`);
+        }
+        this.tools.set(tool.name, tool);
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+    has(name) {
+        return this.tools.has(name);
+    }
+    /** Names of every registered tool. Used by the `list_tools` MCP tool. */
+    list() {
+        return Array.from(this.tools.keys()).sort();
+    }
+    /**
+     * Filter the registry down to the tools granted by a manifest. Names absent
+     * from the registry are returned in `missing` so the worker can fail-loud
+     * before the LLM tries to call something that doesn't exist.
+     */
+    materializeFor(grants) {
+        const tools = [];
+        const missing = [];
+        for (const grant of grants) {
+            const tool = this.tools.get(grant.name);
+            if (tool === undefined)
+                missing.push(grant.name);
+            else
+                tools.push(tool);
+        }
+        return { tools, missing };
+    }
+}

package/dist/runtime/tools/web_search.d.ts

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import type { BoardwalkTool } from "./types.js";
+/**
+ * Logical secret name this tool depends on (the org/stage prefix is applied by
+ * the resolver — see the file header). Surfaced via `secretsRequired` so the
+ * sandbox can scope secret access declaratively without the value ever entering
+ * the tool's input.
+ */
+export declare const TAVILY_SECRET_NAME = "tavily/api-key";
+export declare const webSearchInput: z.ZodObject<{
+    query: z.ZodString;
+    max_results: z.ZodOptional<z.ZodNumber>;
+    include_content: z.ZodOptional<z.ZodBoolean>;
+    search_depth: z.ZodOptional<z.ZodEnum<{
+        basic: "basic";
+        advanced: "advanced";
+    }>>;
+}, z.core.$strip>;
+export type WebSearchInput = z.infer<typeof webSearchInput>;
+declare const webSearchResult: z.ZodObject<{
+    title: z.ZodString;
+    url: z.ZodString;
+    snippet: z.ZodString;
+    content: z.ZodOptional<z.ZodString>;
+    score: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type WebSearchResult = z.infer<typeof webSearchResult>;
+declare const webSearchOutput: z.ZodObject<{
+    kind: z.ZodLiteral<"web_search">;
+    humanSummary: z.ZodString;
+    data: z.ZodObject<{
+        query: z.ZodString;
+        results: z.ZodArray<z.ZodObject<{
+            title: z.ZodString;
+            url: z.ZodString;
+            snippet: z.ZodString;
+            content: z.ZodOptional<z.ZodString>;
+            score: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        answer: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type WebSearchOutput = z.infer<typeof webSearchOutput>;
+export interface WebSearchDeps {
+    /** Returns the Tavily API key. Cached at the caller (one resolve per cold start). */
+    resolveApiKey: () => Promise<string>;
+    fetchImpl?: typeof fetch;
+}
+export declare function makeWebSearchTool(deps: WebSearchDeps): BoardwalkTool<WebSearchInput, WebSearchOutput>;
+/**
+ * Broker-backed web_search for the runner (docs/RUNNER_BROKER.md): identical name/schemas/behavior
+ * to {@link makeWebSearchTool}, but the Tavily call runs in the broker (which holds the platform key)
+ * — the runner just forwards the query, so it needs NO Tavily secret (`secretsRequired: []`). Wired on
+ * the worker when the control plane is on; the direct tool above is the pre-broker/local path.
+ */
+export declare function makeBrokerWebSearchTool(deps: {
+    search: (input: WebSearchInput) => Promise<WebSearchOutput>;
+}): BoardwalkTool<WebSearchInput, WebSearchOutput>;
+/**
+ * Drop near-duplicate results from the same hostname, keeping the first (highest-ranked, since
+ * Tavily returns by relevance). The agent shouldn't pay tokens for three hits off one site. A
+ * result whose URL won't parse is kept (we can't classify it, so we don't drop it). Exported for
+ * unit testing.
+ */
+export declare function dedupeByDomain(results: WebSearchResult[]): WebSearchResult[];
+export {};

package/dist/runtime/tools/web_search.js

@@ -0,0 +1,165 @@
+// web_search — wraps the Tavily API (https://docs.tavily.com/docs/api-reference).
+//
+// Per MASTER_SPEC §13.5: Tavily is Boardwalk's default web-search provider. API
+// key fetched from Secrets Manager (`boardwalk/<stage>/tavily/api-key`) and
+// cached at the module level per container, NEVER appearing in the agent's
+// conversation.
+//
+// 429 from Tavily → `AppError(RATE_LIMIT)` so Strands' retry strategy handles
+// backoff. 5xx → `AppError(TOOL_ERROR)`. Network-level fetch failures fall
+// back to `TOOL_ERROR`.
+import { z } from "zod";
+import { AppError, ErrorCode } from "../support/index.js";
+const TAVILY_ENDPOINT = "https://api.tavily.com/search";
+const MAX_RESULTS_CAP = 20;
+/**
+ * Logical secret name this tool depends on (the org/stage prefix is applied by
+ * the resolver — see the file header). Surfaced via `secretsRequired` so the
+ * sandbox can scope secret access declaratively without the value ever entering
+ * the tool's input.
+ */
+export const TAVILY_SECRET_NAME = "tavily/api-key";
+export const webSearchInput = z.object({
+    query: z.string().min(1).max(2000),
+    /** Clamped to [1, 20]. */
+    max_results: z.number().int().positive().optional(),
+    /** When true, include raw content alongside the snippet. */
+    include_content: z.boolean().optional(),
+    /**
+     * "basic" (default) | "advanced". Advanced is more thorough at higher
+     * latency; we surface both so agents can pick when accuracy matters.
+     */
+    search_depth: z.enum(["basic", "advanced"]).optional(),
+});
+const webSearchResult = z.object({
+    title: z.string(),
+    url: z.string(),
+    snippet: z.string(),
+    /** Present only when include_content=true. */
+    content: z.string().optional(),
+    /** Tavily's relevance score (0..1). */
+    score: z.number().optional(),
+});
+const webSearchOutput = z.object({
+    kind: z.literal("web_search"),
+    humanSummary: z.string(),
+    data: z.object({
+        query: z.string(),
+        results: z.array(webSearchResult),
+        /** Tavily's optional answer summary. */
+        answer: z.string().optional(),
+    }),
+});
+export function makeWebSearchTool(deps) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    return {
+        name: "web_search",
+        description: "Search the public web via Tavily. Returns up to 20 result rows with title, URL, snippet, and optional raw content.",
+        inputSchema: webSearchInput,
+        outputSchema: webSearchOutput,
+        secretsRequired: [TAVILY_SECRET_NAME],
+        async invoke(input, _ctx) {
+            const apiKey = await deps.resolveApiKey();
+            const maxResults = clamp(input.max_results ?? 5, 1, MAX_RESULTS_CAP);
+            const searchDepth = input.search_depth ?? "basic";
+            const payload = {
+                api_key: apiKey,
+                query: input.query,
+                max_results: maxResults,
+                include_raw_content: input.include_content === true,
+                search_depth: searchDepth,
+                // Advanced mode otherwise returns up to 3 ~500-char chunks per source; one keeps results
+                // lean. Only valid for advanced depth, so send it only then.
+                ...(searchDepth === "advanced" ? { chunks_per_source: 1 } : {}),
+            };
+            let res;
+            try {
+                res = await fetchImpl(TAVILY_ENDPOINT, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify(payload),
+                });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                throw new AppError(ErrorCode.TOOL_ERROR, `Tavily request failed: ${message}`);
+            }
+            if (res.status === 429) {
+                throw new AppError(ErrorCode.RATE_LIMIT, "Tavily rate limit exceeded");
+            }
+            if (!res.ok) {
+                throw new AppError(ErrorCode.TOOL_ERROR, `Tavily returned ${res.status.toString()}`);
+            }
+            const json = (await res.json());
+            const results = dedupeByDomain((json.results ?? []).map((r) => projectResult(r, input.include_content === true)));
+            const summary = `Found ${results.length.toString()} result${results.length === 1 ? "" : "s"} for "${input.query}"`;
+            const data = {
+                query: input.query,
+                results,
+            };
+            if (typeof json.answer === "string" && json.answer.length > 0) {
+                data.answer = json.answer;
+            }
+            return { kind: "web_search", humanSummary: summary, data };
+        },
+    };
+}
+/**
+ * Broker-backed web_search for the runner (docs/RUNNER_BROKER.md): identical name/schemas/behavior
+ * to {@link makeWebSearchTool}, but the Tavily call runs in the broker (which holds the platform key)
+ * — the runner just forwards the query, so it needs NO Tavily secret (`secretsRequired: []`). Wired on
+ * the worker when the control plane is on; the direct tool above is the pre-broker/local path.
+ */
+export function makeBrokerWebSearchTool(deps) {
+    return {
+        name: "web_search",
+        description: "Search the public web via Tavily. Returns up to 20 result rows with title, URL, snippet, and optional raw content.",
+        inputSchema: webSearchInput,
+        outputSchema: webSearchOutput,
+        secretsRequired: [],
+        invoke: (input, _ctx) => deps.search(input),
+    };
+}
+function projectResult(r, includeContent) {
+    const out = {
+        title: r.title ?? "",
+        url: r.url ?? "",
+        snippet: r.content ?? "",
+    };
+    if (typeof r.score === "number")
+        out.score = r.score;
+    if (includeContent && typeof r.raw_content === "string")
+        out.content = r.raw_content;
+    return out;
+}
+function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}
+/**
+ * Drop near-duplicate results from the same hostname, keeping the first (highest-ranked, since
+ * Tavily returns by relevance). The agent shouldn't pay tokens for three hits off one site. A
+ * result whose URL won't parse is kept (we can't classify it, so we don't drop it). Exported for
+ * unit testing.
+ */
+export function dedupeByDomain(results) {
+    const seen = new Set();
+    const out = [];
+    for (const result of results) {
+        const host = domainOf(result.url);
+        if (host !== null) {
+            if (seen.has(host))
+                continue;
+            seen.add(host);
+        }
+        out.push(result);
+    }
+    return out;
+}
+function domainOf(url) {
+    try {
+        return new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return null; // malformed URL — keep it rather than silently dropping
+    }
+}