@arnilo/prism-tools 0.0.0-stage → 0.13.1

package/openapi/src/config.ts

@@ -0,0 +1,73 @@
+import type { JsonSchema } from "@arnilo/prism";
+
+import type { OpenApiLimits } from "./limits.js";
+
+/** One OpenAPI 3.1 document the package compiles into tools. */
+export interface ToolsOpenapiSpecConfig {
+  /** Tool-name prefix: every operation compiles as `<id>_<operationId>`. */
+  readonly id: string;
+  /** Path to a local JSON document, or an `https:` URL fetched once at setup through pinned fetch. */
+  readonly source: string;
+  /** Pinned origin for the compiled operations. Defaults to the document's first absolute `servers[0].url`. */
+  readonly baseUrl?: string;
+  /** Header name → `env:NAME` or `keyring:NAME`. Resolved per request; a literal fails config validation. */
+  readonly headers?: Readonly<Record<string, string>>;
+  /** Allow-listed operationIds. Omit to compile every operation the document declares. */
+  readonly include?: readonly string[];
+  /** operationIds to skip when `include` is absent. */
+  readonly exclude?: readonly string[];
+}
+
+/** Validated `packageConfig` for `@arnilo/prism-tools/openapi`. */
+export interface ToolsOpenapiConfig {
+  /** Required; an empty list registers nothing and notes why. */
+  readonly specs?: readonly ToolsOpenapiSpecConfig[];
+  /** Byte, retry, pagination, and body bounds shared by every spec. */
+  readonly limits?: OpenApiLimits;
+}
+
+const secretString: JsonSchema = {
+  type: "string",
+  minLength: 1,
+  maxLength: 4096,
+  pattern: "^(env|keyring):",
+  "x-prism-secret": true,
+};
+
+const limitProperties: Readonly<Record<string, JsonSchema>> = {
+  maxDocumentBytes: { type: "number", minimum: 1 },
+  maxOperations: { type: "number", minimum: 1 },
+  maxSchemaDepth: { type: "number", minimum: 1 },
+  maxRefs: { type: "number", minimum: 1 },
+  maxBodyBytes: { type: "number", minimum: 1 },
+  maxResponseBytes: { type: "number", minimum: 1 },
+  maxPages: { type: "number", minimum: 1 },
+  maxPaginationItems: { type: "number", minimum: 1 },
+  maxRetries: { type: "number", minimum: 0 },
+};
+
+/**
+ * The config schema. `specs` is deliberately not declared `required`: a required field with no
+ * default would fail package conformance, so `setup` checks it and names the field instead.
+ * `headers` values are ref-only secret fields; a literal fails validation.
+ */
+export const toolsOpenapiConfigSchema: JsonSchema = {
+  type: "object",
+  properties: {
+    specs: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          id: { type: "string", minLength: 1, maxLength: 64, pattern: "^[A-Za-z0-9][A-Za-z0-9._-]*$" },
+          source: { type: "string", minLength: 1, maxLength: 4096 },
+          baseUrl: { type: "string", minLength: 1, maxLength: 4096 },
+          headers: { type: "object", additionalProperties: secretString },
+          include: { type: "array", items: { type: "string", minLength: 1 } },
+          exclude: { type: "array", items: { type: "string", minLength: 1 } },
+        },
+      },
+    },
+    limits: { type: "object", properties: limitProperties },
+  },
+};

package/openapi/src/errors.ts

@@ -0,0 +1,16 @@
+export type OpenApiToolErrorCode =
+  | "ERR_PRISM_OPENAPI_DOCUMENT_BOUNDS"
+  | "ERR_PRISM_OPENAPI_OPERATION_UNKNOWN"
+  | "ERR_PRISM_OPENAPI_SERVER_DRIFT"
+  | "ERR_PRISM_OPENAPI_SCHEMA_BOUNDS"
+  | "ERR_PRISM_OPENAPI_RESPONSE_BOUNDS"
+  | "ERR_PRISM_OPENAPI_RETRY_EXHAUSTED";
+
+export class OpenApiToolError extends Error {
+  readonly code: OpenApiToolErrorCode;
+  constructor(code: OpenApiToolErrorCode, message: string) {
+    super(message);
+    this.name = "OpenApiToolError";
+    this.code = code;
+  }
+}

package/openapi/src/execute.ts

@@ -0,0 +1,241 @@
+import { UNTRUSTED_EXTERNAL_TRUST, type JsonObject, type SecretRedactor, type ToolExecutionContext, type ToolResult } from "@arnilo/prism";
+import type { CompiledOperation } from "./compile.js";
+import { OpenApiToolError } from "./errors.js";
+import type { ResolvedOpenApiLimits } from "./limits.js";
+import type { OpenApiCredentialResolver, OpenApiPagination, OpenApiPolicyCheck } from "./types.js";
+
+export interface ExecuteOpenApiOperationOptions {
+  readonly operation: CompiledOperation;
+  readonly server: string;
+  readonly toolName: string;
+  readonly args: JsonObject;
+  readonly context: ToolExecutionContext;
+  readonly credentials?: OpenApiCredentialResolver;
+  readonly policy?: OpenApiPolicyCheck;
+  readonly redactor?: SecretRedactor;
+  readonly pagination?: OpenApiPagination;
+  readonly idempotencyKeyHeader?: boolean;
+  readonly limits: ResolvedOpenApiLimits;
+  readonly fetchImpl: typeof globalThis.fetch;
+}
+
+function buildRequestUrl(
+  operation: CompiledOperation,
+  server: string,
+  args: JsonObject,
+  credentialQuery: Readonly<Record<string, string>> | undefined,
+): string {
+  let path = operation.path;
+  for (const name of operation.pathParams) {
+    const value = args[name];
+    if (value === undefined || value === null) {
+      throw new OpenApiToolError("ERR_PRISM_OPENAPI_SCHEMA_BOUNDS", `missing path parameter: ${name}`);
+    }
+    path = path.replace(`{${name}}`, encodeURIComponent(String(value)));
+  }
+  const url = new URL(`${server.replace(/\/+$/, "")}${path}`);
+  for (const param of operation.queryParams) {
+    const value = args[param.name];
+    if (value === undefined || value === null) continue;
+    url.searchParams.set(param.name, String(value));
+  }
+  if (credentialQuery) {
+    for (const [key, value] of Object.entries(credentialQuery)) url.searchParams.set(key, value);
+  }
+  return url.href;
+}
+
+function buildHeaders(
+  operation: CompiledOperation,
+  args: JsonObject,
+  credentialHeaders: Readonly<Record<string, string>> | undefined,
+  idempotencyKey: string | undefined,
+): Record<string, string> {
+  const headers: Record<string, string> = {};
+  for (const param of operation.headerParams) {
+    const value = args[param.name];
+    if (value === undefined || value === null) continue;
+    headers[param.name] = String(value);
+  }
+  if (operation.bodyParam && args[operation.bodyParam.name] !== undefined) headers["content-type"] = "application/json";
+  if (idempotencyKey !== undefined && operation.effect.kind !== "none") headers["idempotency-key"] = idempotencyKey;
+  if (credentialHeaders) {
+    for (const [key, value] of Object.entries(credentialHeaders)) headers[key] = value;
+  }
+  return headers;
+}
+
+function buildBody(operation: CompiledOperation, args: JsonObject, maxBodyBytes: number): string | undefined {
+  if (!operation.bodyParam) return undefined;
+  const value = args[operation.bodyParam.name];
+  if (value === undefined) return undefined;
+  const text = JSON.stringify(value);
+  if (text === undefined) {
+    throw new OpenApiToolError("ERR_PRISM_OPENAPI_RESPONSE_BOUNDS", "request body is not JSON-serializable");
+  }
+  if (Buffer.byteLength(text, "utf8") > maxBodyBytes) {
+    throw new OpenApiToolError("ERR_PRISM_OPENAPI_RESPONSE_BOUNDS", "request body exceeds maxBodyBytes");
+  }
+  return text;
+}
+
+async function readBoundedText(response: Response, maxBytes: number): Promise<string> {
+  if (!response.body) return "";
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > maxBytes) {
+      await reader.cancel();
+      throw new OpenApiToolError("ERR_PRISM_OPENAPI_RESPONSE_BOUNDS", "response exceeds maxResponseBytes");
+    }
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function pointer(record: Record<string, unknown>, path: string): unknown {
+  let current: unknown = record;
+  for (const part of path.split(".")) {
+    if (typeof current !== "object" || current === null) return undefined;
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+function nextToken(record: Record<string, unknown>, nextPath: string | undefined): string | undefined {
+  const paths = nextPath ? [nextPath] : ["next", "nextPageToken"];
+  for (const path of paths) {
+    const value = pointer(record, path);
+    if (typeof value === "string" && value) return value;
+  }
+  return undefined;
+}
+
+function result(options: ExecuteOpenApiOperationOptions, value: unknown): ToolResult {
+  // No banner here: the kernel wraps untrusted results (UNTRUSTED_EXTERNAL_TRUST) in its envelope.
+  return {
+    toolCallId: options.context.toolCallId,
+    name: options.toolName,
+    value,
+    metadata: {
+      trust: UNTRUSTED_EXTERNAL_TRUST,
+      source: openApiSource(options),
+      operationId: options.operation.operationId,
+      method: options.operation.method,
+      path: options.operation.path,
+    },
+  };
+}
+
+/** The request URL without query or credentials — enough for the envelope's `source` attribute. */
+function openApiSource(options: ExecuteOpenApiOperationOptions): string | undefined {
+  const source = `${options.server.replace(/\/+$/, "")}${options.operation.path}`;
+  try {
+    const { protocol } = new URL(source);
+    return protocol === "http:" || protocol === "https:" ? source : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function executeOpenApiOperation(options: ExecuteOpenApiOperationOptions): Promise<ToolResult> {
+  const { operation, context, limits } = options;
+  await options.policy?.(
+    { operationId: operation.operationId, method: operation.method, path: operation.path, args: options.args },
+    context,
+  );
+  const credential = await options.credentials?.(
+    { operationId: operation.operationId, method: operation.method, path: operation.path },
+    context,
+  );
+  const url = buildRequestUrl(operation, options.server, options.args, credential?.query);
+  const headers = buildHeaders(
+    operation,
+    options.args,
+    credential?.headers,
+    options.idempotencyKeyHeader === true ? context.idempotencyKey : undefined,
+  );
+  const body = buildBody(operation, options.args, limits.maxBodyBytes);
+
+  const fetchPage = async (pageUrl: string, pageHeaders: Record<string, string>, pageBody: string | undefined): Promise<Response> => {
+    for (let attempt = 0; ; attempt++) {
+      let response: Response;
+      try {
+        response = await options.fetchImpl(pageUrl, {
+          method: operation.method,
+          headers: pageHeaders,
+          body: pageBody,
+          signal: context.signal,
+          redirect: "manual",
+        });
+      } catch (error) {
+        if (context.signal?.aborted) throw error;
+        if (attempt < limits.maxRetries) continue;
+        throw new OpenApiToolError(
+          "ERR_PRISM_OPENAPI_RETRY_EXHAUSTED",
+          `request failed after ${limits.maxRetries} retries: ${String(error)}`,
+        );
+      }
+      if (response.status >= 500 && attempt < limits.maxRetries) continue;
+      return response;
+    }
+  };
+
+  if (options.pagination && operation.paginatable) {
+    const { pageParam, pageSizeParam, pageSize, nextPath, itemsPath } = options.pagination;
+    const items: unknown[] = [];
+    let token: string | undefined;
+    let pageCount = 0;
+    for (;;) {
+      pageCount += 1;
+      if (pageCount > limits.maxPages) {
+        throw new OpenApiToolError("ERR_PRISM_OPENAPI_RESPONSE_BOUNDS", "pagination exceeded maxPages");
+      }
+      const pageUrl = new URL(url);
+      if (token !== undefined) pageUrl.searchParams.set(pageParam, token);
+      if (pageSizeParam !== undefined && pageSize !== undefined) pageUrl.searchParams.set(pageSizeParam, String(pageSize));
+      const response = await fetchPage(pageUrl.href, headers, body);
+      const text = await readBoundedText(response, limits.maxResponseBytes);
+      const safe = options.redactor ? options.redactor.redact(text) : text;
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(safe);
+      } catch {
+        throw new OpenApiToolError("ERR_PRISM_OPENAPI_RESPONSE_BOUNDS", "pagination response is not JSON");
+      }
+      if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new OpenApiToolError("ERR_PRISM_OPENAPI_RESPONSE_BOUNDS", "pagination response must be a JSON object");
+      }
+      const record = parsed as Record<string, unknown>;
+      const pageItems = pointer(record, itemsPath ?? "items");
+      if (!Array.isArray(pageItems)) {
+        throw new OpenApiToolError("ERR_PRISM_OPENAPI_RESPONSE_BOUNDS", `pagination items path ${itemsPath ?? "items"} is not an array`);
+      }
+      items.push(...pageItems);
+      if (items.length > limits.maxPaginationItems) {
+        throw new OpenApiToolError("ERR_PRISM_OPENAPI_RESPONSE_BOUNDS", "pagination exceeded maxPaginationItems");
+      }
+      const next = nextToken(record, nextPath);
+      if (next === undefined) return result(options, { status: response.status, pageCount, items });
+      token = next;
+    }
+  }
+
+  const response = await fetchPage(url, headers, body);
+  const text = await readBoundedText(response, limits.maxResponseBytes);
+  const safe = options.redactor ? options.redactor.redact(text) : text;
+  const contentType = response.headers.get("content-type") ?? "";
+  let value: unknown = safe;
+  if (/json/i.test(contentType)) {
+    try {
+      value = JSON.parse(safe);
+    } catch {
+      value = safe;
+    }
+  }
+  return result(options, { status: response.status, body: value });
+}

package/openapi/src/index.ts

@@ -0,0 +1,124 @@
+/**
+ * `@arnilo/prism-tools/openapi` — compile host-selected OpenAPI 3.1 operations into bounded tools.
+ *
+ * Config lists `specs`; each spec is read once at setup (a local JSON file, or an `https:` URL
+ * through the kernel's pinned fetch) and compiled into `<id>_<operationId>` tools. GET/HEAD
+ * operations declare `["network"]`; every other method declares `["network", "external"]`. A spec
+ * that fails to load or compile notes why and is skipped, and the other specs still register.
+ *
+ * Header values are ref-only (`env:`/`keyring:`) and resolved per request through
+ * `prism.credentials.resolve`, so the resolved value joins the agent's secret set and is redacted
+ * from events, notes, logs, errors, and tool results.
+ *
+ * ```ts
+ * import toolsOpenapi from "@arnilo/prism-tools/openapi";
+ * import { createAgent } from "@arnilo/prism";
+ *
+ * const agent = await createAgent({
+ *   model,
+ *   packages: [toolsOpenapi({ specs: [{ id: "petstore", source: "./petstore.json" }] })],
+ * });
+ * ```
+ */
+
+import { definePackage, type PackageAPI, type PackageInstance, type ToolDefinition } from "@arnilo/prism";
+import manifest from "../../package.json" with { type: "json" };
+
+import { type ToolsOpenapiConfig, type ToolsOpenapiSpecConfig, toolsOpenapiConfigSchema } from "./config.js";
+import { OpenApiToolError } from "./errors.js";
+import { resolveOpenApiLimits } from "./limits.js";
+import { firstServerUrl, loadSpecDocument, selectOperations } from "./specs.js";
+import { createOpenApiTools } from "./tools.js";
+import type { OpenApiCredentialResolver } from "./types.js";
+
+export type { ToolsOpenapiConfig, ToolsOpenapiSpecConfig } from "./config.js";
+export { toolsOpenapiConfigSchema } from "./config.js";
+export { OpenApiToolError, type OpenApiToolErrorCode } from "./errors.js";
+export type { OpenApiLimits, ResolvedOpenApiLimits } from "./limits.js";
+export { DEFAULT_OPENAPI_LIMITS, HARD_OPENAPI_LIMITS, resolveOpenApiLimits } from "./limits.js";
+export { firstServerUrl, listOperationIds, loadSpecDocument, selectOperations } from "./specs.js";
+export { createOpenApiTools, effectsForMethod } from "./tools.js";
+export type {
+  OpenApiCredentialInput,
+  OpenApiCredentialResolver,
+  OpenApiPagination,
+  OpenApiPolicyCheck,
+  OpenApiToolsOptions,
+} from "./types.js";
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** A per-request resolver over one spec's ref-only header config. */
+function createHeaderResolver(prism: PackageAPI<ToolsOpenapiConfig>, spec: ToolsOpenapiSpecConfig): OpenApiCredentialResolver | undefined {
+  const entries = Object.entries(spec.headers ?? {});
+  if (entries.length === 0) return undefined;
+  return async () => {
+    const headers: Record<string, string> = {};
+    for (const [name, ref] of entries) {
+      const secret = await prism.credentials.resolve(ref);
+      if (secret === undefined) {
+        throw new OpenApiToolError("ERR_PRISM_OPENAPI_DOCUMENT_BOUNDS", `unresolved credential ref for header ${name}`);
+      }
+      headers[name] = secret.value;
+    }
+    return { headers };
+  };
+}
+
+const definition = definePackage<ToolsOpenapiConfig>({
+  name: "@arnilo/prism-tools/openapi",
+  version: manifest.version,
+  description:
+    "OpenAPI 3.1 operation compiler: pinned-origin, allow-listed, schema-bounded tools with per-method effects and ref-only header credentials.",
+  requires: { api: 1 },
+  capabilities: ["credentials"],
+  config: toolsOpenapiConfigSchema,
+  setup: async (prism) => {
+    const specs = prism.config.specs ?? [];
+    if (specs.length === 0) {
+      prism.status.note("warn", "openapi: config needs specs (at least one { id, source })");
+      return;
+    }
+    const limits = resolveOpenApiLimits(prism.config.limits);
+    for (const spec of specs) {
+      let tools: readonly ToolDefinition[];
+      try {
+        const document = await loadSpecDocument(spec, limits);
+        const server = spec.baseUrl ?? firstServerUrl(document);
+        if (server === undefined) {
+          throw new OpenApiToolError("ERR_PRISM_OPENAPI_SERVER_DRIFT", `spec ${spec.id} has no absolute servers url; set baseUrl`);
+        }
+        const operations = selectOperations(document, spec);
+        if (operations.length === 0) {
+          prism.status.note("warn", `openapi: spec ${spec.id} matched no operations`);
+          continue;
+        }
+        tools = createOpenApiTools({
+          document,
+          operations,
+          server,
+          namePrefix: `${spec.id}_`,
+          limits,
+          credentials: createHeaderResolver(prism, spec),
+        });
+      } catch (error) {
+        prism.status.note("warn", `openapi: spec ${spec.id} skipped: ${errorMessage(error)}`);
+        continue;
+      }
+      // Registration stays outside the try: a cross-spec tool-name collision fails closed.
+      for (const tool of tools) prism.tools.register(tool);
+    }
+  },
+});
+
+/** The package definition. Pass config through `packageConfig` or use {@link toolsOpenapi}. */
+export default definition;
+
+/** The package with config baked in, for `packages: [toolsOpenapi({ specs })]`. */
+export function toolsOpenapi(config: ToolsOpenapiConfig): PackageInstance {
+  return definition(config);
+}
+
+export const packageName = "@arnilo/prism-tools/openapi";

package/openapi/src/limits.ts

@@ -0,0 +1,63 @@
+import { OpenApiToolError } from "./errors.js";
+
+export interface OpenApiLimits {
+  readonly maxDocumentBytes?: number;
+  readonly maxOperations?: number;
+  readonly maxSchemaDepth?: number;
+  readonly maxRefs?: number;
+  readonly maxBodyBytes?: number;
+  readonly maxResponseBytes?: number;
+  readonly maxPages?: number;
+  readonly maxPaginationItems?: number;
+  readonly maxRetries?: number;
+}
+
+export interface ResolvedOpenApiLimits {
+  readonly maxDocumentBytes: number;
+  readonly maxOperations: number;
+  readonly maxSchemaDepth: number;
+  readonly maxRefs: number;
+  readonly maxBodyBytes: number;
+  readonly maxResponseBytes: number;
+  readonly maxPages: number;
+  readonly maxPaginationItems: number;
+  readonly maxRetries: number;
+}
+
+export const DEFAULT_OPENAPI_LIMITS: ResolvedOpenApiLimits = {
+  maxDocumentBytes: 2 * 1024 * 1024,
+  maxOperations: 256,
+  maxSchemaDepth: 32,
+  maxRefs: 1024,
+  maxBodyBytes: 1024 * 1024,
+  maxResponseBytes: 1024 * 1024,
+  maxPages: 20,
+  maxPaginationItems: 1000,
+  maxRetries: 0,
+};
+
+export const HARD_OPENAPI_LIMITS: ResolvedOpenApiLimits = {
+  maxDocumentBytes: 16 * 1024 * 1024,
+  maxOperations: 1024,
+  maxSchemaDepth: 128,
+  maxRefs: 8192,
+  maxBodyBytes: 16 * 1024 * 1024,
+  maxResponseBytes: 16 * 1024 * 1024,
+  maxPages: 100,
+  maxPaginationItems: 10000,
+  maxRetries: 3,
+};
+
+export function resolveOpenApiLimits(input: OpenApiLimits = {}): ResolvedOpenApiLimits {
+  const resolved = { ...DEFAULT_OPENAPI_LIMITS, ...input };
+  for (const [key, value] of Object.entries(resolved)) {
+    const min = key === "maxRetries" ? 0 : 1;
+    if (!Number.isSafeInteger(value) || value < min) {
+      throw new OpenApiToolError("ERR_PRISM_OPENAPI_DOCUMENT_BOUNDS", `openapi limit ${key} must be a safe integer >= ${min}`);
+    }
+    if (value > HARD_OPENAPI_LIMITS[key as keyof ResolvedOpenApiLimits]) {
+      throw new OpenApiToolError("ERR_PRISM_OPENAPI_DOCUMENT_BOUNDS", `openapi limit ${key} exceeds its hard cap`);
+    }
+  }
+  return resolved;
+}

package/openapi/src/specs.ts

@@ -0,0 +1,86 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { type JsonObject } from "@arnilo/prism";
+import { pinnedFetch } from "@arnilo/prism/net";
+
+import type { ToolsOpenapiSpecConfig } from "./config.js";
+import { OpenApiToolError } from "./errors.js";
+import type { ResolvedOpenApiLimits } from "./limits.js";
+
+const HTTP_METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace"] as const;
+
+function isHttpUrl(value: string): boolean {
+  return /^https?:\/\//i.test(value);
+}
+
+/**
+ * Read one spec once at setup: a local JSON file, or an `https:` URL through the kernel's
+ * DNS-pinned, redirect-free, byte-bounded fetch. YAML documents are not supported.
+ */
+export async function loadSpecDocument(spec: ToolsOpenapiSpecConfig, limits: ResolvedOpenApiLimits): Promise<JsonObject> {
+  let text: string;
+  if (isHttpUrl(spec.source)) {
+    const response = await pinnedFetch(new URL(spec.source), undefined, {
+      maxResponseBytes: limits.maxDocumentBytes,
+      errorPrefix: "OpenAPI spec",
+    });
+    text = await response.text();
+  } else {
+    const data = readFileSync(resolve(spec.source));
+    if (data.byteLength > limits.maxDocumentBytes) {
+      throw new OpenApiToolError("ERR_PRISM_OPENAPI_DOCUMENT_BOUNDS", `spec ${spec.id} exceeds maxDocumentBytes`);
+    }
+    text = data.toString("utf8");
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new OpenApiToolError("ERR_PRISM_OPENAPI_DOCUMENT_BOUNDS", `spec ${spec.id} is not valid JSON`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new OpenApiToolError("ERR_PRISM_OPENAPI_DOCUMENT_BOUNDS", `spec ${spec.id} must be a JSON object`);
+  }
+  return parsed as JsonObject;
+}
+
+/** The first absolute `servers[].url`, used as the pinned origin when `baseUrl` is absent. */
+export function firstServerUrl(document: JsonObject): string | undefined {
+  const servers = document.servers;
+  if (!Array.isArray(servers)) return undefined;
+  for (const entry of servers) {
+    const url = typeof entry === "object" && entry !== null ? (entry as Record<string, unknown>).url : undefined;
+    if (typeof url !== "string" || url.length === 0) continue;
+    try {
+      const parsed = new URL(url);
+      if (parsed.protocol === "https:" || parsed.protocol === "http:") return url;
+    } catch {
+      // Relative server URLs resolve against the pinned base, so they cannot supply one.
+    }
+  }
+  return undefined;
+}
+
+/** Every `operationId` the document declares, in path/method order. */
+export function listOperationIds(document: JsonObject): string[] {
+  const paths = document.paths;
+  if (typeof paths !== "object" || paths === null || Array.isArray(paths)) return [];
+  const ids: string[] = [];
+  for (const pathItem of Object.values(paths as Record<string, unknown>)) {
+    if (typeof pathItem !== "object" || pathItem === null) continue;
+    for (const method of HTTP_METHODS) {
+      const operation = (pathItem as Record<string, unknown>)[method];
+      if (typeof operation !== "object" || operation === null) continue;
+      const operationId = (operation as Record<string, unknown>).operationId;
+      if (typeof operationId === "string" && operationId.length > 0) ids.push(operationId);
+    }
+  }
+  return ids;
+}
+
+/** `include` wins; otherwise every operation minus `exclude`. */
+export function selectOperations(document: JsonObject, spec: ToolsOpenapiSpecConfig): string[] {
+  if (spec.include !== undefined) return [...spec.include];
+  const excluded = new Set(spec.exclude ?? []);
+  return listOperationIds(document).filter((id) => !excluded.has(id));
+}

package/openapi/src/tools.ts

@@ -0,0 +1,60 @@
+import type { ToolCapabilityKind, ToolDefinition } from "@arnilo/prism";
+import { compileOpenApiDocument } from "./compile.js";
+import { executeOpenApiOperation } from "./execute.js";
+import { resolveOpenApiLimits } from "./limits.js";
+import type { OpenApiToolsOptions } from "./types.js";
+
+const READ_EFFECTS: readonly ToolCapabilityKind[] = ["network"];
+const MUTATING_EFFECTS: readonly ToolCapabilityKind[] = ["network", "external"];
+
+/** GET/HEAD reach the network only; every other method also mutates an external system. */
+export function effectsForMethod(method: string): readonly ToolCapabilityKind[] {
+  return method === "GET" || method === "HEAD" ? READ_EFFECTS : MUTATING_EFFECTS;
+}
+
+/**
+ * Compile host-selected OpenAPI 3.1 operations into bounded Prism `ToolDefinition`s.
+ *
+ * Only the explicitly listed `operationIds` compile; the pinned `server` origin must
+ * match every document/path/operation `servers` entry; schemas are resolved with
+ * depth/ref bounds and no external refs; mutating methods carry
+ * `{ kind: "external_mutation", idempotency: "required" }` so the core run loop gates
+ * approval and deduplicates via the effect store. Responses are untrusted data.
+ */
+export function createOpenApiTools(options: OpenApiToolsOptions): readonly ToolDefinition[] {
+  const limits = resolveOpenApiLimits(options.limits);
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  const prefix = options.namePrefix ?? "";
+  const compiled = compileOpenApiDocument({
+    document: options.document,
+    operations: options.operations,
+    server: options.server,
+    limits,
+    pagination: options.pagination,
+  });
+  return compiled.map((operation) => {
+    const toolName = `${prefix}${operation.toolName}`;
+    return {
+      name: toolName,
+      description: operation.description,
+      parameters: operation.parameters,
+      effect: operation.effect,
+      effects: effectsForMethod(operation.method),
+      execute: (args, context) =>
+        executeOpenApiOperation({
+          operation,
+          server: options.server,
+          toolName,
+          args,
+          context,
+          credentials: options.credentials,
+          policy: options.policy,
+          redactor: options.redactor,
+          pagination: options.pagination,
+          idempotencyKeyHeader: options.idempotencyKeyHeader,
+          limits,
+          fetchImpl,
+        }),
+    } satisfies ToolDefinition;
+  });
+}