@retinue/agentkit 0.1.0

package/dist/toolkit/http.js

@@ -0,0 +1,205 @@
+/**
+ * The one HTTP client the first-party tools use — REQ-039 (#188).
+ *
+ * Every outbound tool in the library goes through here, and that is the point. The security properties of an
+ * outbound tool are not properties of the tool; they are properties of whatever makes the request. Spread across
+ * five tools they would hold in four of them.
+ *
+ * This lives in `toolkit/` rather than `tools/` because it performs I/O and boundary rule **R7** forbids that in
+ * the tools layer: an envelope that reached the network itself would be doing the work it exists to delegate.
+ * The tools in `tools/library/` are envelopes over these functions.
+ *
+ * ## What is refused, and why each one
+ *
+ * The egress policy is the platform's own (`validateHttpEgress`), applied to an argument a *model* produced —
+ * which is the difference from an MCP endpoint an operator configured once. It refuses:
+ *
+ * - **Private, loopback and link-local hosts.** `169.254.169.254` is cloud metadata: credentials in plain text
+ *   to anything that can make an HTTP request from inside the network.
+ * - **Every IPv6 literal** unless explicitly allowed, because `::ffff:169.254.169.254` is that same address in a
+ *   form any IPv4-only check waves through.
+ * - **Credentials in the URL** — refused rather than stripped, so the caller never believes it sent one.
+ * - **Anything but https** by default. `file://` reads the disk.
+ *
+ * And two decisions this module adds on top:
+ *
+ * - **Redirects are not followed.** `redirect: "manual"`, always. Following one lets a permitted host bounce the
+ *   request to a forbidden one: the policy checked the URL the model asked for, and the request lands somewhere
+ *   it never saw. That is the standard SSRF bypass, and it is the reason a per-URL allow-list is not sufficient
+ *   on its own. The redirect target is reported so the model can ask for it explicitly and have it checked on
+ *   its own merits.
+ * - **Credentials come from configuration, keyed by host.** `headersFor` is consulted with the *validated* host,
+ *   so a model cannot name the credential it wants used, cannot send one to a host it was not issued for, and
+ *   cannot read one back: a tool's own input schema has no field for it (see `tools/library/http.ts`).
+ */
+import { AgentPlatformError } from "../core/errors.js";
+import { validateHttpEgress } from "../mcp/egress.js";
+import { encloseUntrusted, makeNonce } from "../security/prompt-safety.js";
+/** https only, no private networks, no allow-list. A deployment narrows it; nothing widens it silently. */
+export const DEFAULT_EGRESS_POLICY = {
+    allowedSchemes: ["https"],
+    allowPrivateNetworks: false,
+};
+/**
+ * Bytes are bounded, and the bound is enforced **while reading**.
+ *
+ * `await response.text()` on a multi-gigabyte response buffers all of it before any length check could run, so a
+ * limit applied afterwards protects nothing at all.
+ */
+export const MAX_RESPONSE_BYTES = 200_000;
+/** A model waiting on a hung server is a run holding a worker slot. */
+export const REQUEST_TIMEOUT_MS = 10_000;
+/**
+ * Headers a caller may not set, because they are decided here or by configuration.
+ *
+ * `authorization` and `cookie` are the ones that matter: a tool input that could set them would let a model
+ * choose which credential to spend and where to send it. `host` forges the request target past the policy check.
+ */
+const RESERVED_HEADERS = new Set(["authorization", "cookie", "proxy-authorization", "host", "content-length"]);
+export const createHttpClient = (config = {}) => {
+    const policy = config.policy ?? DEFAULT_EGRESS_POLICY;
+    const doFetch = config.fetchImpl ?? fetch;
+    const maxBytes = config.maxBytes ?? MAX_RESPONSE_BYTES;
+    const timeoutMs = config.timeoutMs ?? REQUEST_TIMEOUT_MS;
+    // A nonce factory is injectable so a test can pin it; the default needs randomness the caller supplies,
+    // because `node:crypto` is an import this layer does not get to make.
+    const nonce = config.nonce ??
+        (config.randomHex !== undefined
+            ? () => makeNonce(config.randomHex)
+            : () => makeNonce(weakHex));
+    return {
+        async request(input) {
+            const method = (input.method ?? "GET").toUpperCase();
+            // The policy first, before any network call. A refusal that still sends the packet is not a refusal.
+            let url;
+            try {
+                url = validateHttpEgress(policy, input.url);
+            }
+            catch (thrown) {
+                const error = thrown;
+                return {
+                    ok: false,
+                    url: input.url,
+                    kind: "forbidden",
+                    reason: error.message ?? "that URL is not permitted",
+                };
+            }
+            const supplied = Object.entries(input.headers ?? {}).filter(([name]) => !RESERVED_HEADERS.has(name.toLowerCase()));
+            const headers = {
+                accept: input.accept ?? "text/html, text/plain;q=0.9, application/json;q=0.9, */*;q=0.1",
+                ...Object.fromEntries(supplied),
+                // Configured headers last: they are the deployment's, and nothing a caller passes may shadow them.
+                ...(config.headersFor?.(url.hostname) ?? {}),
+            };
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            try {
+                const response = await doFetch(url.toString(), {
+                    method,
+                    signal: controller.signal,
+                    redirect: "manual",
+                    headers,
+                    ...(input.body === undefined ? {} : { body: input.body }),
+                });
+                if (response.status >= 300 && response.status < 400) {
+                    const location = response.headers.get("location") ?? "";
+                    return {
+                        ok: false,
+                        url: url.toString(),
+                        kind: "redirected",
+                        status: response.status,
+                        reason: `That URL redirects to ${location || "somewhere unspecified"}. Redirects are not followed ` +
+                            `automatically — ask for that URL directly if you want it, and it will be checked on its own merits.`,
+                    };
+                }
+                const contentType = response.headers.get("content-type") ?? "";
+                const { text, truncated } = await readBounded(response, maxBytes);
+                // A 4xx/5xx is reported as a failure with its status, because "the page returned 404" is what the model
+                // needs to hear. The body still comes back where there is one: an API's error payload is often the only
+                // thing that says what was wrong with the request.
+                if (response.status >= 400) {
+                    return {
+                        ok: false,
+                        url: url.toString(),
+                        kind: "http-error",
+                        status: response.status,
+                        reason: `That URL returned ${response.status}${text.trim() === "" ? "" : `: ${text.slice(0, 500)}`}`,
+                    };
+                }
+                const body = input.fence === false
+                    ? text
+                    : encloseUntrusted({
+                        // Provenance is the URL actually read, after validation, so a model quoting this can say where it
+                        // came from and a reader can check.
+                        provenance: url.toString(),
+                        title: `${method} ${url.hostname} (${response.status})`,
+                        body: text,
+                        nonce: nonce(),
+                    });
+                return { ok: true, url: url.toString(), status: response.status, contentType, truncated, body };
+            }
+            catch (thrown) {
+                // A timeout and a DNS failure are both "could not read that", and neither is worth a stack trace in a
+                // model's context. Named enough to act on, not enough to be noise.
+                const aborted = thrown.name === "AbortError";
+                return aborted
+                    ? {
+                        ok: false,
+                        url: url.toString(),
+                        kind: "timeout",
+                        reason: `That URL did not respond within ${timeoutMs / 1000} seconds.`,
+                    }
+                    : { ok: false, url: url.toString(), kind: "unreachable", reason: "Could not reach that URL." };
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+    };
+};
+/**
+ * A last-resort nonce source.
+ *
+ * Not cryptographic, and named so nobody mistakes it. The nonce's job is to stop *fetched text* from closing the
+ * fence around itself, so it has to be unguessable to the page, not to an attacker who can see this process. A
+ * deployment that cares passes `randomHex` and gets `node:crypto`; the alternative to this fallback is a fixed
+ * nonce, which a page could simply include.
+ */
+const weakHex = (bytes) => {
+    let out = "";
+    for (let i = 0; i < bytes; i += 1)
+        out += Math.floor(Math.random() * 256).toString(16).padStart(2, "0");
+    return out;
+};
+/**
+ * Read at most `maxBytes`, stopping as they arrive, and abandon the rest.
+ *
+ * Without `reader.cancel()` the connection stays open pulling a body nobody wants.
+ */
+export const readBounded = async (response, maxBytes) => {
+    const body = response.body;
+    // No stream — a mock, or a runtime without one. Falling back to `text()` and slicing is honest about being a
+    // weaker bound rather than pretending the ceiling held.
+    if (body === null || body === undefined) {
+        const whole = await response.text();
+        return { text: whole.slice(0, maxBytes), truncated: whole.length > maxBytes };
+    }
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let text = "";
+    let bytes = 0;
+    for (;;) {
+        const { value, done } = await reader.read();
+        if (done)
+            break;
+        bytes += value.byteLength;
+        if (bytes > maxBytes) {
+            text += decoder.decode(value.slice(0, Math.max(0, maxBytes - (bytes - value.byteLength))));
+            await reader.cancel();
+            return { text, truncated: true };
+        }
+        text += decoder.decode(value, { stream: true });
+    }
+    return { text, truncated: false };
+};
+//# sourceMappingURL=http.js.map

package/dist/toolkit/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The deterministic functions the first-party tools delegate to — REQ-039 (#188).
+ *
+ * Why this is a layer of its own: boundary rule **R7** forbids the tools layer from performing I/O, because a
+ * tool is "a thin, agent-facing envelope over a deterministic function" and an envelope that reached the network
+ * itself would be doing the work it exists to delegate. So the network, the parsing and the arithmetic live here,
+ * and `tools/library/` holds envelopes that add authorisation, approval and idempotency and then call these.
+ *
+ * Everything here is directly callable and separately testable, which is the other half of the point: the
+ * interesting behaviour of an outbound tool — what it refuses, where it stops reading — should be provable
+ * without constructing a run.
+ */
+export { DEFAULT_EGRESS_POLICY, MAX_RESPONSE_BYTES, REQUEST_TIMEOUT_MS, createHttpClient, readBounded, } from "./http.js";
+export type { HttpClient, HttpClientConfig, HttpFailure, HttpOutcome, HttpRequest, HttpSuccess } from "./http.js";
+export { DEFAULT_SEARCH_LIMIT, MAX_SNIPPET_CHARS, createFetchJson, createFetchPage, createWebSearch, htmlToText, } from "./web.js";
+export type { JsonResult, PageResult, SearchHit, SearchOutcome, SearchProvider } from "./web.js";
+export { MAX_CELL_CHARS, MAX_CSV_ROWS, MAX_SQL_ROWS, createSqlQuery, createSqlSchema, parseCsv, queryJson, } from "./data.js";
+export type { CsvResult, JsonQueryResult, ReadOnlyQuery, SchemaResult, SqlResult } from "./data.js";
+export { MAX_EXPRESSION_CHARS, calculate, currentTime } from "./compute.js";
+export type { CalculationResult, TimeResult } from "./compute.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/toolkit/index.js

@@ -0,0 +1,17 @@
+/**
+ * The deterministic functions the first-party tools delegate to — REQ-039 (#188).
+ *
+ * Why this is a layer of its own: boundary rule **R7** forbids the tools layer from performing I/O, because a
+ * tool is "a thin, agent-facing envelope over a deterministic function" and an envelope that reached the network
+ * itself would be doing the work it exists to delegate. So the network, the parsing and the arithmetic live here,
+ * and `tools/library/` holds envelopes that add authorisation, approval and idempotency and then call these.
+ *
+ * Everything here is directly callable and separately testable, which is the other half of the point: the
+ * interesting behaviour of an outbound tool — what it refuses, where it stops reading — should be provable
+ * without constructing a run.
+ */
+export { DEFAULT_EGRESS_POLICY, MAX_RESPONSE_BYTES, REQUEST_TIMEOUT_MS, createHttpClient, readBounded, } from "./http.js";
+export { DEFAULT_SEARCH_LIMIT, MAX_SNIPPET_CHARS, createFetchJson, createFetchPage, createWebSearch, htmlToText, } from "./web.js";
+export { MAX_CELL_CHARS, MAX_CSV_ROWS, MAX_SQL_ROWS, createSqlQuery, createSqlSchema, parseCsv, queryJson, } from "./data.js";
+export { MAX_EXPRESSION_CHARS, calculate, currentTime } from "./compute.js";
+//# sourceMappingURL=index.js.map

package/dist/toolkit/web.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Reading the web — REQ-039 (#188).
+ *
+ * Two functions the library's `fetch_url`, `fetch_json` and `web_search` tools delegate to. Both go through
+ * `createHttpClient`, so the egress policy, the redirect refusal, the byte ceiling and the untrusted-content
+ * fence are decided in one place rather than three.
+ */
+import type { HttpClient, HttpClientConfig, HttpOutcome } from "./http.js";
+/**
+ * Strip HTML to something a model can read.
+ *
+ * Crude and openly so: `script` and `style` bodies removed, tags dropped, entities for the five characters that
+ * matter, whitespace collapsed. It is not a parser and does not need to be — the goal is *legible text*, and a
+ * DOM implementation is both a dependency and an attack surface for a tool whose output is prose either way.
+ *
+ * `script` and `style` go **with their contents**; otherwise a page's JavaScript arrives as sentences and the
+ * model reads minified code as content.
+ */
+export declare const htmlToText: (html: string) => string;
+export type PageResult = {
+    readonly ok: true;
+    readonly url: string;
+    readonly status: number;
+    readonly truncated: boolean;
+    readonly content: string;
+} | {
+    readonly ok: false;
+    readonly url: string;
+    readonly reason: string;
+};
+/** Fetch a page and return readable text. HTML is flattened; anything else comes back as it arrived. */
+export declare const createFetchPage: (config?: HttpClientConfig & {
+    readonly client?: HttpClient;
+}) => (rawUrl: string) => Promise<PageResult>;
+export type JsonResult = {
+    readonly ok: true;
+    readonly url: string;
+    readonly status: number;
+    readonly data: unknown;
+} | {
+    readonly ok: false;
+    readonly url: string;
+    readonly reason: string;
+};
+/**
+ * Fetch and parse JSON.
+ *
+ * Requested unfenced, because the body is parsed here and reaches the model as *structured data*, not as prose.
+ * Fencing it would put delimiters inside string values. The safety argument is different in kind: a parsed object
+ * cannot forge a section boundary, and a caller rendering one back into a prompt is the caller that must fence.
+ */
+export declare const createFetchJson: (config?: HttpClientConfig & {
+    readonly client?: HttpClient;
+}) => (rawUrl: string) => Promise<JsonResult>;
+export type SearchHit = {
+    readonly title: string;
+    readonly url: string;
+    readonly snippet: string;
+};
+/**
+ * What a search returned, or why it did not.
+ *
+ * `searched: false` is not an empty result list, and the distinction is the whole type. "I searched and found
+ * nothing" and "I could not search" lead a model to opposite next actions, and collapsing them into `[]` makes it
+ * confidently report that nothing exists.
+ */
+export type SearchOutcome = {
+    readonly searched: true;
+    readonly query: string;
+    readonly hits: readonly SearchHit[];
+} | {
+    readonly searched: false;
+    readonly query: string;
+    readonly reason: "not-configured" | "unavailable" | "timed-out";
+    readonly detail: string;
+};
+/**
+ * A search provider, as configuration.
+ *
+ * Deliberately not a hard-coded vendor. Every usable search API is a GET with a key and a JSON body of results,
+ * so the shape a deployment supplies is: where to send it, and how to read what comes back. `apiKey` is
+ * configuration and never appears in a tool's input schema — a model must not be able to name the credential it
+ * wants spent.
+ */
+export type SearchProvider = {
+    readonly name: string;
+    /** Build the request URL for a query. The key belongs in `headers`, not here, wherever the provider allows it. */
+    readonly endpoint: (query: string, limit: number) => string;
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Read the provider's JSON into hits. Returning `[]` means "searched, found nothing". */
+    readonly parse: (payload: unknown) => readonly SearchHit[];
+};
+export declare const DEFAULT_SEARCH_LIMIT = 5;
+export declare const MAX_SNIPPET_CHARS = 400;
+/**
+ * Web search over a configured provider.
+ *
+ * With no provider this returns `not-configured` rather than throwing or pretending. A stubbed search that
+ * returns plausible-looking results is worse than no search: it is a tool the model trusts and cannot verify.
+ */
+export declare const createWebSearch: (config?: HttpClientConfig & {
+    readonly provider?: SearchProvider;
+    readonly client?: HttpClient;
+    readonly limit?: number;
+}) => (query: string, limit?: number) => Promise<SearchOutcome>;
+export type { HttpOutcome };
+//# sourceMappingURL=web.d.ts.map

package/dist/toolkit/web.js

@@ -0,0 +1,147 @@
+/**
+ * Reading the web — REQ-039 (#188).
+ *
+ * Two functions the library's `fetch_url`, `fetch_json` and `web_search` tools delegate to. Both go through
+ * `createHttpClient`, so the egress policy, the redirect refusal, the byte ceiling and the untrusted-content
+ * fence are decided in one place rather than three.
+ */
+import { createHttpClient } from "./http.js";
+/**
+ * Strip HTML to something a model can read.
+ *
+ * Crude and openly so: `script` and `style` bodies removed, tags dropped, entities for the five characters that
+ * matter, whitespace collapsed. It is not a parser and does not need to be — the goal is *legible text*, and a
+ * DOM implementation is both a dependency and an attack surface for a tool whose output is prose either way.
+ *
+ * `script` and `style` go **with their contents**; otherwise a page's JavaScript arrives as sentences and the
+ * model reads minified code as content.
+ */
+export const htmlToText = (html) => html
+    .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, " ")
+    .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, " ")
+    .replace(/<!--[\s\S]*?-->/g, " ")
+    // Block-level ends become newlines first, so paragraphs do not run together into one wall of text.
+    .replace(/<\/(p|div|h[1-6]|li|tr|section|article|br)\s*>/gi, "\n")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    // Ampersand last: first would turn `&amp;lt;` into `<`, the classic double-decode.
+    .replace(/&amp;/g, "&")
+    .replace(/[ \t]+/g, " ")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+/** Fetch a page and return readable text. HTML is flattened; anything else comes back as it arrived. */
+export const createFetchPage = (config = {}) => {
+    const client = config.client ?? createHttpClient(config);
+    return async (rawUrl) => {
+        const outcome = await client.request({ url: rawUrl, accept: "text/html, text/plain;q=0.9, */*;q=0.1" });
+        if (!outcome.ok)
+            return { ok: false, url: outcome.url, reason: outcome.reason };
+        // Flattening happens after fencing, which is safe: `htmlToText` only removes markup, and the fence's
+        // delimiters are not markup. Doing it the other way would let a page's tags rewrite the fence.
+        const content = /html/i.test(outcome.contentType) ? htmlToText(outcome.body) : outcome.body;
+        return { ok: true, url: outcome.url, status: outcome.status, truncated: outcome.truncated, content };
+    };
+};
+/**
+ * Fetch and parse JSON.
+ *
+ * Requested unfenced, because the body is parsed here and reaches the model as *structured data*, not as prose.
+ * Fencing it would put delimiters inside string values. The safety argument is different in kind: a parsed object
+ * cannot forge a section boundary, and a caller rendering one back into a prompt is the caller that must fence.
+ */
+export const createFetchJson = (config = {}) => {
+    const client = config.client ?? createHttpClient(config);
+    return async (rawUrl) => {
+        const outcome = await client.request({ url: rawUrl, accept: "application/json", fence: false });
+        if (!outcome.ok)
+            return { ok: false, url: outcome.url, reason: outcome.reason };
+        try {
+            return { ok: true, url: outcome.url, status: outcome.status, data: JSON.parse(outcome.body) };
+        }
+        catch {
+            return {
+                ok: false,
+                url: outcome.url,
+                // Named precisely, because "invalid JSON" plus a truncation flag is the difference between a broken
+                // endpoint and a response the ceiling cut in half.
+                reason: outcome.truncated
+                    ? "The response was larger than the byte limit, so what arrived is not parseable JSON."
+                    : "That URL did not return valid JSON.",
+            };
+        }
+    };
+};
+export const DEFAULT_SEARCH_LIMIT = 5;
+export const MAX_SNIPPET_CHARS = 400;
+/**
+ * Web search over a configured provider.
+ *
+ * With no provider this returns `not-configured` rather than throwing or pretending. A stubbed search that
+ * returns plausible-looking results is worse than no search: it is a tool the model trusts and cannot verify.
+ */
+export const createWebSearch = (config = {}) => {
+    const provider = config.provider;
+    const client = config.client ?? createHttpClient(config);
+    const defaultLimit = config.limit ?? DEFAULT_SEARCH_LIMIT;
+    return async (query, limit = defaultLimit) => {
+        if (provider === undefined) {
+            return {
+                searched: false,
+                query,
+                reason: "not-configured",
+                detail: "No web-search provider is configured, so I cannot search. Configure one, or give me a URL to read " +
+                    "directly.",
+            };
+        }
+        const outcome = await client.request({
+            url: provider.endpoint(query, limit),
+            headers: provider.headers,
+            accept: "application/json",
+            fence: false,
+        });
+        if (!outcome.ok) {
+            return {
+                searched: false,
+                query,
+                reason: outcome.kind === "timeout" ? "timed-out" : "unavailable",
+                detail: `${provider.name}: ${outcome.reason}`,
+            };
+        }
+        let payload;
+        try {
+            payload = JSON.parse(outcome.body);
+        }
+        catch {
+            return { searched: false, query, reason: "unavailable", detail: `${provider.name} returned a response that is not JSON.` };
+        }
+        let hits;
+        try {
+            hits = provider.parse(payload);
+        }
+        catch (error) {
+            // A provider that changed its response shape is an operational failure, not an empty search.
+            return {
+                searched: false,
+                query,
+                reason: "unavailable",
+                detail: `${provider.name} returned a shape this configuration cannot read: ${error.message}`,
+            };
+        }
+        return {
+            searched: true,
+            query,
+            hits: hits.slice(0, limit).map((hit) => ({
+                title: hit.title,
+                url: hit.url,
+                // Snippets are bounded here rather than trusting the provider: a "snippet" is whatever the remote decides
+                // it is, and five of them at 40KB each is a context window.
+                snippet: hit.snippet.length > MAX_SNIPPET_CHARS ? `${hit.snippet.slice(0, MAX_SNIPPET_CHARS)}…` : hit.snippet,
+            })),
+        };
+    };
+};
+//# sourceMappingURL=web.js.map

package/dist/tools/define.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Tool authoring helpers — `docs/03` → Tool registry. Ergonomic ways to build a `Tool` and a
+ * `ToolProvider` from a plain spec: you write `execute(input, context) => data` and throw on error;
+ * the helper wraps the result in the shared success/error envelope and fills descriptor defaults
+ * (idempotency is required automatically for external/destructive effects).
+ */
+import type { ExecutionContext } from "../core/context.js";
+import type { ApprovalPolicy, Tool, ToolEffect, ToolProvider } from "./index.js";
+export type ToolSpec<I = unknown, O = unknown> = {
+    readonly name: string;
+    readonly description: string;
+    readonly label?: string;
+    readonly category?: string;
+    readonly effect?: ToolEffect;
+    readonly approvalPolicy?: ApprovalPolicy;
+    readonly inputSchema?: unknown;
+    readonly outputSchema?: unknown;
+    readonly requiresIdempotencyKey?: boolean;
+    execute(input: I, context: ExecutionContext): Promise<O> | O;
+};
+/** Build a `Tool` from a plain spec: `execute` returns data (or throws); the envelope is handled here. */
+export declare const defineTool: <I = unknown, O = unknown>(spec: ToolSpec<I, O>) => Tool<O>;
+/** A `ToolProvider` serving a fixed set of tools. For dynamic per-tenant tools, implement the port. */
+export declare const toolProvider: (id: string, tools: readonly Tool[]) => ToolProvider;
+//# sourceMappingURL=define.d.ts.map

package/dist/tools/define.js

@@ -0,0 +1,45 @@
+/**
+ * Tool authoring helpers — `docs/03` → Tool registry. Ergonomic ways to build a `Tool` and a
+ * `ToolProvider` from a plain spec: you write `execute(input, context) => data` and throw on error;
+ * the helper wraps the result in the shared success/error envelope and fills descriptor defaults
+ * (idempotency is required automatically for external/destructive effects).
+ */
+// One definition of the error envelope, not two. `runtime/retry.ts` already exported
+// `toPlatformError`; this module had a private duplicate, and exporting that for #113's delegating
+// envelope made the package barrel ambiguous about which one it meant — the same collision
+// `DEFAULT_SESSION_STATE_MAX_BYTES` caused in #97. Importing the existing one instead.
+import { toPlatformError } from "../runtime/retry.js";
+/** Build a `Tool` from a plain spec: `execute` returns data (or throws); the envelope is handled here. */
+export const defineTool = (spec) => {
+    const effect = spec.effect ?? "read";
+    const descriptor = {
+        name: spec.name,
+        label: spec.label ?? spec.name,
+        description: spec.description,
+        category: spec.category ?? "general",
+        inputSchema: spec.inputSchema ?? {},
+        outputSchema: spec.outputSchema ?? {},
+        effect,
+        approvalPolicy: spec.approvalPolicy ?? (effect === "external-write" || effect === "destructive" ? "always" : "never"),
+        requiresIdempotencyKey: spec.requiresIdempotencyKey ?? (effect === "external-write" || effect === "destructive"),
+    };
+    return {
+        descriptor,
+        async execute({ context, input }) {
+            try {
+                return { ok: true, data: await spec.execute(input, context) };
+            }
+            catch (error) {
+                return { ok: false, error: toPlatformError(error) };
+            }
+        },
+    };
+};
+/** A `ToolProvider` serving a fixed set of tools. For dynamic per-tenant tools, implement the port. */
+export const toolProvider = (id, tools) => ({
+    id,
+    async listTools() {
+        return tools;
+    },
+});
+//# sourceMappingURL=define.js.map