@checkstack/ai-backend 0.1.0

package/src/mcp/server.ts

@@ -0,0 +1,300 @@
+import { randomUUID } from "node:crypto";
+import { extractErrorMessage } from "@checkstack/common";
+import {
+  opaqueBearerToken,
+  type AuthService,
+  type AuthUser,
+} from "@checkstack/backend-api";
+import { serializeTools } from "../serializer";
+import { hashToolArgs } from "../propose-apply/args-hash";
+import type { AiToolResolver } from "../resolver";
+import type { RegisteredAiTool } from "../tool-registry";
+import type { McpToolInvoker } from "./tool-invoker";
+import type { McpConnectionRegistry } from "./connection-registry";
+
+/**
+ * A read-only tool exposed over MCP, bound to the live oRPC procedure that
+ * actually runs it. The `tool` carries the model-facing schema + the access
+ * rules the resolver filters on; `pluginId` / `procedureKey` route the
+ * `tools/call` re-entry through the live router (handler authz preserved).
+ */
+export interface McpExecutableTool {
+  tool: RegisteredAiTool;
+  pluginId: string;
+  procedureKey: string;
+}
+
+const JSONRPC_VERSION = "2.0";
+const MCP_PROTOCOL_VERSION = "2025-06-18";
+const MCP_SESSION_HEADER = "mcp-session-id";
+
+/** JSON-RPC 2.0 + MCP error codes (named to avoid magic numbers). */
+const RPC_PARSE_ERROR = -32_700;
+const RPC_METHOD_NOT_FOUND = -32_601;
+const RPC_INVALID_PARAMS = -32_602;
+const RPC_UNAUTHORIZED = -32_001;
+const RPC_FORBIDDEN = -32_003;
+/** Custom application error for an exceeded per-principal tool budget (§14.5). */
+const RPC_RATE_LIMITED = -32_010;
+
+/** The subset of an AuthUser the budget keys on. */
+interface BudgetPrincipal {
+  kind: "user" | "application";
+  id: string;
+}
+
+/**
+ * Per-principal tool-budget enforcer (§14.5). Resolves when the call is within
+ * budget; rejects with a {@link Error} when over budget. Optional so the
+ * handler stays testable without a Postgres connection.
+ */
+export type McpBudgetEnforcer = (
+  principal: BudgetPrincipal,
+) => Promise<void>;
+
+/** Records a directly-executed read tool call into the audit log (optional). */
+export type McpRecordExecuted = (args: {
+  principal: BudgetPrincipal;
+  toolName: string;
+  argsHash: string;
+}) => Promise<void>;
+
+interface JsonRpcRequest {
+  jsonrpc: string;
+  id?: string | number | null;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+type JsonRpcId = string | number | null;
+
+function rpcResult(id: JsonRpcId, result: unknown) {
+  return { jsonrpc: JSONRPC_VERSION, id, result };
+}
+
+function rpcError(id: JsonRpcId, code: number, message: string) {
+  return { jsonrpc: JSONRPC_VERSION, id, error: { code, message } };
+}
+
+function jsonResponse(body: unknown, init?: ResponseInit): Response {
+  return Response.json(body, {
+    status: init?.status ?? 200,
+    headers: init?.headers,
+  });
+}
+
+/**
+ * Build the Streamable-HTTP MCP request handler (decision §9 — Streamable HTTP,
+ * NOT the deprecated HTTP+SSE). Handles the read-only surface: `initialize`,
+ * `tools/list`, `tools/call`, and the `notifications/initialized` ack.
+ *
+ * Authentication: the bearer OAuth token is resolved to a NARROWED principal by
+ * the platform auth strategy (`auth.authenticate` → the Bearer-OAuth branch).
+ * Tool visibility is filtered by the resolver (the principal only sees tools it
+ * may call); `tools/call` re-enters the live router as that principal so the
+ * handler re-checks authz. The model never bypasses authorization.
+ */
+export function createMcpRequestHandler({
+  tools,
+  resolver,
+  invoker,
+  auth,
+  connections,
+  enforceBudget,
+  recordExecuted,
+}: {
+  tools: McpExecutableTool[];
+  resolver: AiToolResolver;
+  invoker: McpToolInvoker;
+  auth: AuthService;
+  connections: McpConnectionRegistry;
+  /** Per-principal tool-budget enforcer (§14.5). Refuses over-budget calls. */
+  enforceBudget?: McpBudgetEnforcer;
+  /** Audit-record a directly-executed read tool (matrix #13). */
+  recordExecuted?: McpRecordExecuted;
+}): (req: Request) => Promise<Response> {
+  // Built lazily on first request: the `tools` array is populated in
+  // `afterPluginsReady` (once every plugin has exposed its read projections),
+  // which runs AFTER this handler is created in init. Requests only arrive after
+  // that phase, so the first request sees the complete set.
+  let byName: Map<string, McpExecutableTool> | undefined;
+
+  return async function handleMcpRequest(req: Request): Promise<Response> {
+    byName ??= new Map(tools.map((t) => [t.tool.name, t]));
+    if (req.method === "GET") {
+      // No server-initiated SSE stream for the read-only surface; clients use
+      // POST request/response. (A GET opens an SSE channel in full MCP; not
+      // needed for read-only tools.)
+      return new Response(null, { status: 405 });
+    }
+    if (req.method !== "POST") {
+      return new Response(null, { status: 405 });
+    }
+
+    const bearerToken = opaqueBearerToken(req);
+    const principal: AuthUser | undefined = await auth.authenticate(req);
+
+    let payload: JsonRpcRequest;
+    try {
+      payload = (await req.json()) as JsonRpcRequest;
+    } catch {
+      return jsonResponse(rpcError(null, RPC_PARSE_ERROR, "Parse error"), {
+        status: 400,
+      });
+    }
+
+    const id = payload.id ?? null;
+
+    switch (payload.method) {
+      case "initialize": {
+        // A fresh session id is minted and tracked pod-locally (bookkeeping).
+        const sessionId = randomUUID();
+        if (principal) {
+          connections.open({
+            sessionId,
+            principalId: "id" in principal ? principal.id : "unknown",
+          });
+        }
+        return jsonResponse(
+          rpcResult(id, {
+            protocolVersion: MCP_PROTOCOL_VERSION,
+            capabilities: { tools: { listChanged: false } },
+            serverInfo: { name: "checkstack", version: "1.0.0" },
+          }),
+          { headers: { [MCP_SESSION_HEADER]: sessionId } },
+        );
+      }
+
+      case "notifications/initialized": {
+        // Notification: no response body (id is absent).
+        return new Response(null, { status: 202 });
+      }
+
+      case "tools/list": {
+        if (!principal) {
+          return jsonResponse(rpcError(id, RPC_UNAUTHORIZED, "Unauthorized"), {
+            status: 401,
+          });
+        }
+        // Only read-effect tools are listed: the read-only MCP surface invokes
+        // tools via a bare `tools/call`, which the structural effect-gate
+        // refuses for mutate/destructive tools. Listing a tool that could only
+        // ever be refused would mislead the model, so they are filtered here
+        // (the propose/apply flow surfaces mutating tools separately).
+        const allowed = resolver
+          .resolveTools(principal)
+          .filter((tool) => tool.effect === "read");
+        const descriptors = serializeTools({ tools: allowed }).map((d) => ({
+          name: d.name,
+          description: d.description,
+          inputSchema: d.inputSchema,
+        }));
+        return jsonResponse(rpcResult(id, { tools: descriptors }));
+      }
+
+      case "tools/call": {
+        if (!principal || !bearerToken) {
+          return jsonResponse(rpcError(id, RPC_UNAUTHORIZED, "Unauthorized"), {
+            status: 401,
+          });
+        }
+        const name = payload.params?.name;
+        if (typeof name !== "string") {
+          return jsonResponse(
+            rpcError(id, RPC_INVALID_PARAMS, "Invalid params: missing tool name"),
+          );
+        }
+        const executable = byName.get(name);
+        if (!executable) {
+          return jsonResponse(
+            rpcError(id, RPC_INVALID_PARAMS, `Unknown tool: ${name}`),
+          );
+        }
+        // Resolver gate: the model can only call a tool the principal may see.
+        // (Handler-side authz is the authority and re-runs below; this gate
+        // refuses a misbehaving model server-side BEFORE re-entry.)
+        if (!resolver.isAllowed({ principal, tool: executable.tool })) {
+          return jsonResponse(rpcError(id, RPC_FORBIDDEN, `Forbidden: ${name}`), {
+            status: 403,
+          });
+        }
+        // STRUCTURAL effect-gate (decision §1.6 / §8): a bare `tools/call` may
+        // ONLY run a read-effect tool. Mutating / destructive tools MUST go
+        // through the two-step propose -> apply flow (the proposal token is the
+        // single-use consent gate), never a direct invocation. This makes the
+        // read-only-over-MCP guarantee a structural property of the handler,
+        // independent of which tools happen to be wired into `tools`.
+        if (executable.tool.effect !== "read") {
+          return jsonResponse(
+            rpcError(
+              id,
+              RPC_FORBIDDEN,
+              `Tool "${name}" has effect "${executable.tool.effect}" and cannot be invoked via tools/call; use the propose/apply flow.`,
+            ),
+            { status: 403 },
+          );
+        }
+        const args =
+          (payload.params?.arguments as Record<string, unknown>) ?? {};
+
+        // Per-principal tool budget (§14.5): enforced BEFORE the call so an
+        // over-budget caller is refused. Shared-Postgres counter — cross-pod
+        // correct. The principal kind is "user" | "application" (services never
+        // reach here: they have no access rules and the resolver gate refused).
+        const budgetPrincipal: BudgetPrincipal | undefined =
+          principal.type === "user" || principal.type === "application"
+            ? { kind: principal.type, id: principal.id }
+            : undefined;
+        if (enforceBudget && budgetPrincipal) {
+          try {
+            await enforceBudget(budgetPrincipal);
+          } catch (error) {
+            return jsonResponse(
+              rpcError(id, RPC_RATE_LIMITED, extractErrorMessage(error)),
+              { status: 429 },
+            );
+          }
+        }
+
+        try {
+          const result = await invoker.invoke({
+            pluginId: executable.pluginId,
+            procedureKey: executable.procedureKey,
+            input: args,
+            bearerToken,
+          });
+          // Audit-record the directly-executed read tool (matrix #13). The args
+          // hash is recorded, never the raw args. Best-effort: an audit failure
+          // must not fail the tool call.
+          if (recordExecuted && budgetPrincipal) {
+            await recordExecuted({
+              principal: budgetPrincipal,
+              toolName: name,
+              argsHash: hashToolArgs(args),
+            }).catch(() => {});
+          }
+          return jsonResponse(
+            rpcResult(id, {
+              content: [{ type: "text", text: JSON.stringify(result) }],
+              isError: false,
+            }),
+          );
+        } catch (error) {
+          // Surfaced as an MCP tool error (not a transport error), per spec.
+          return jsonResponse(
+            rpcResult(id, {
+              content: [{ type: "text", text: extractErrorMessage(error) }],
+              isError: true,
+            }),
+          );
+        }
+      }
+
+      default: {
+        return jsonResponse(
+          rpcError(id, RPC_METHOD_NOT_FOUND, `Method not found: ${payload.method}`),
+        );
+      }
+    }
+  };
+}

package/src/mcp/tool-invoker.ts

@@ -0,0 +1,65 @@
+import { createORPCClient } from "@orpc/client";
+import { RPCLink } from "@orpc/client/fetch";
+
+/**
+ * Invokes a projected read-only tool's SOURCE oRPC procedure by re-entering the
+ * live router as the resolved principal, so handler-side authorization runs
+ * exactly as it would for any other caller (decision 5 — the model never
+ * bypasses authz; it is an untrusted caller that happens to pick arguments).
+ *
+ * The re-entry forwards the caller's OWN opaque OAuth bearer token to the
+ * loopback RPC endpoint. The API route handler re-authenticates that token
+ * through the Bearer-OAuth branch (introspect + narrow to the live principal)
+ * and runs `autoAuthMiddleware`. So the tool call is authorized as the NARROWED
+ * principal, server-side, on every call. We deliberately do NOT use the
+ * service-credential `fetch` (that would call as a trusted service and skip the
+ * user's authz).
+ */
+export interface McpToolInvoker {
+  invoke(args: {
+    /** The source procedure's owning plugin id (e.g. "incident"). */
+    pluginId: string;
+    /** The source procedure key (e.g. "listIncidents"). */
+    procedureKey: string;
+    /** Validated tool input. */
+    input: unknown;
+    /** The caller's opaque OAuth bearer token (forwarded verbatim). */
+    bearerToken: string;
+  }): Promise<unknown>;
+}
+
+/** A minimal typed view of the loopback RPC client (per-plugin, per-procedure). */
+type LoopbackClient = Record<
+  string,
+  Record<string, (input: unknown) => Promise<unknown>>
+>;
+
+export function createMcpToolInvoker({
+  internalUrl,
+}: {
+  /** Base URL of this backend for the loopback call (e.g. INTERNAL_URL). */
+  internalUrl: string;
+}): McpToolInvoker {
+  return {
+    async invoke({ pluginId, procedureKey, input, bearerToken }) {
+      // A fresh link per call carries this caller's bearer token; the live
+      // router re-checks authz as the narrowed principal.
+      const link = new RPCLink({
+        url: `${internalUrl}/api`,
+        headers: { authorization: `Bearer ${bearerToken}` },
+      });
+      const client = createORPCClient(link) as LoopbackClient;
+      const pluginClient = client[pluginId];
+      if (!pluginClient) {
+        throw new Error(`No RPC client for plugin "${pluginId}".`);
+      }
+      const procedure = pluginClient[procedureKey];
+      if (typeof procedure !== "function") {
+        throw new TypeError(
+          `Procedure "${pluginId}.${procedureKey}" is not callable.`,
+        );
+      }
+      return procedure(input);
+    },
+  };
+}

package/src/openai-provider.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "bun:test";
+import { OpenAiCompatibleConnectionSchema } from "./openai-provider";
+
+/** Minimal valid connection sans spendCap; spread + override `spendCap` per case. */
+const baseConfig = {
+  baseUrl: "https://openrouter.ai/api/v1",
+  apiKey: "sk-test",
+  defaultModel: "deepseek-v4-flash",
+};
+
+describe("OpenAiCompatibleConnectionSchema spendCap", () => {
+  it("accepts a connection with NO spendCap (unlimited)", () => {
+    const parsed = OpenAiCompatibleConnectionSchema.parse({ ...baseConfig });
+    expect(parsed.spendCap).toBeUndefined();
+  });
+
+  it("treats an empty spendCap object as no cap", () => {
+    const parsed = OpenAiCompatibleConnectionSchema.parse({
+      ...baseConfig,
+      spendCap: {},
+    });
+    expect(parsed.spendCap).toBeUndefined();
+  });
+
+  it("treats blank-string spendCap fields as no cap", () => {
+    const parsed = OpenAiCompatibleConnectionSchema.parse({
+      ...baseConfig,
+      spendCap: { tokenBudget: "", windowMinutes: "" },
+    });
+    expect(parsed.spendCap).toBeUndefined();
+  });
+
+  it("treats an incomplete spendCap (one blank bound) as no cap", () => {
+    expect(
+      OpenAiCompatibleConnectionSchema.parse({
+        ...baseConfig,
+        spendCap: { tokenBudget: 1000 },
+      }).spendCap,
+    ).toBeUndefined();
+    expect(
+      OpenAiCompatibleConnectionSchema.parse({
+        ...baseConfig,
+        spendCap: { windowMinutes: 60 },
+      }).spendCap,
+    ).toBeUndefined();
+  });
+
+  it("keeps a fully-specified spendCap", () => {
+    const parsed = OpenAiCompatibleConnectionSchema.parse({
+      ...baseConfig,
+      spendCap: { tokenBudget: 1000, windowMinutes: 60 },
+    });
+    expect(parsed.spendCap).toEqual({ tokenBudget: 1000, windowMinutes: 60 });
+  });
+
+  it("still rejects a present cap with a non-positive bound", () => {
+    expect(() =>
+      OpenAiCompatibleConnectionSchema.parse({
+        ...baseConfig,
+        spendCap: { tokenBudget: 0, windowMinutes: 60 },
+      }),
+    ).toThrow();
+  });
+});

package/src/openai-provider.ts

@@ -0,0 +1,146 @@
+import { z } from "zod";
+import { Versioned, configString, configNumber } from "@checkstack/backend-api";
+import { extractErrorMessage } from "@checkstack/common";
+import type {
+  IntegrationProvider,
+  TestConnectionResult,
+} from "@checkstack/integration-backend";
+import {
+  OPENAI_COMPATIBLE_DEFAULT_BASE_URL,
+  OPENAI_COMPATIBLE_PROVIDER_LOCAL_ID,
+  type OpenAiCompatibleConnection,
+} from "@checkstack/ai-common";
+
+/**
+ * Connection schema for an OpenAI-compatible LLM provider (OpenAI, Azure,
+ * OpenRouter, Ollama, vLLM, LM Studio, ...). Model choice lives on the
+ * connection (decision §14.6): `defaultModel` is required, `availableModels`
+ * optionally constrains the Phase 4 chat model picker.
+ *
+ * `apiKey` is marked `x-secret`, so the integration platform stores it in the
+ * Secrets Vault and redacts it from every UI / DTO response — the credential
+ * never leaves the backend.
+ */
+/**
+ * Normalize the raw `spendCap` input before validation. A spend cap is OPTIONAL
+ * (absent = unlimited), and the schema-driven connection form always renders the
+ * nested `tokenBudget` / `windowMinutes` fields, so leaving them blank submits a
+ * PRESENT-but-empty object (empty strings / `undefined`) rather than omitting
+ * `spendCap`. Treat any such empty/incomplete cap as "no cap" so an operator can
+ * save a connection without configuring a budget: if either bound is unset or
+ * blank, the whole cap collapses to `undefined` (unlimited). A fully-specified
+ * cap passes through untouched for the object schema to validate.
+ */
+function normalizeSpendCap(value: unknown): unknown {
+  if (value === undefined || value === null || value === "") {
+    return undefined;
+  }
+  if (typeof value === "object" && !Array.isArray(value)) {
+    const cap = value as Record<string, unknown>;
+    const isBlank = (field: unknown): boolean =>
+      field === undefined || field === null || field === "";
+    if (isBlank(cap.tokenBudget) || isBlank(cap.windowMinutes)) {
+      return undefined;
+    }
+  }
+  return value;
+}
+
+export const OpenAiCompatibleConnectionSchema = z.object({
+  baseUrl: configString({})
+    .url()
+    .default(OPENAI_COMPATIBLE_DEFAULT_BASE_URL)
+    .describe("OpenAI-compatible base URL (e.g. https://api.openai.com/v1)"),
+  apiKey: configString({ "x-secret": true }).describe("API key"),
+  defaultModel: configString({})
+    .min(1)
+    .describe("Default model id (e.g. gpt-4o-mini)"),
+  availableModels: z
+    .array(z.string().min(1))
+    .optional()
+    .describe("Optional allowlist of selectable model ids"),
+  spendCap: z
+    .preprocess(
+      normalizeSpendCap,
+      z
+        .object({
+          tokenBudget: configNumber({})
+            .int()
+            .positive()
+            .describe(
+              "Max total tokens (input + output) per user per window before chat is refused",
+            ),
+          windowMinutes: configNumber({})
+            .int()
+            .positive()
+            .describe(
+              "Rolling window length in minutes the token budget resets over",
+            ),
+        })
+        .optional(),
+    )
+    .describe(
+      "Optional LLM spend cap (token-count). Leave both fields blank for no cap. Enforced server-side and counted across all pods.",
+    ),
+}) satisfies z.ZodType<OpenAiCompatibleConnection>;
+
+/**
+ * The OpenAI-compatible integration provider. Registering it through
+ * `integrationProviderExtensionPoint` makes it appear in the generic
+ * Connections settings UI (rendered from `connectionSchema` via `DynamicForm`),
+ * exactly like every other integration provider — no AI-specific Settings page
+ * is required for credential management.
+ */
+export function createOpenAiCompatibleProvider(): IntegrationProvider<OpenAiCompatibleConnection> {
+  return {
+    id: OPENAI_COMPATIBLE_PROVIDER_LOCAL_ID,
+    displayName: "OpenAI-compatible",
+    description:
+      "LLM provider for the AI platform (OpenAI, Azure, OpenRouter, Ollama, vLLM, LM Studio).",
+    icon: "Sparkles",
+    connectionSchema: new Versioned({
+      version: 1,
+      schema: OpenAiCompatibleConnectionSchema,
+    }),
+    documentation: {
+      setupGuide: `
+## OpenAI-compatible provider
+
+Configure credentials for any OpenAI-compatible chat-completions endpoint.
+
+1. Set the base URL (defaults to \`https://api.openai.com/v1\`). For other
+   providers use their base URL, e.g. \`https://openrouter.ai/api/v1\` or a
+   local \`http://localhost:11434/v1\` for Ollama.
+2. Paste an API key. It is stored in the Secrets Vault and never returned to
+   the browser.
+3. Set a default model id (for example \`gpt-4o-mini\`). Optionally add an
+   allowlist of selectable models.
+      `.trim(),
+    },
+    async testConnection(
+      config: OpenAiCompatibleConnection,
+    ): Promise<TestConnectionResult> {
+      try {
+        // Strip trailing slashes without a backtracking-prone regex
+        // (`/\/+$/` is O(n^2) on inputs like "////...x" - CodeQL js/polynomial-redos).
+        let base = config.baseUrl;
+        while (base.endsWith("/")) base = base.slice(0, -1);
+        const response = await fetch(`${base}/models`, {
+          headers: { authorization: `Bearer ${config.apiKey}` },
+        });
+        if (!response.ok) {
+          return {
+            success: false,
+            message: `Provider returned ${response.status} ${response.statusText}`,
+          };
+        }
+        return { success: true, message: "Connection successful" };
+      } catch (error) {
+        return {
+          success: false,
+          message: `Failed to reach provider: ${extractErrorMessage(error)}`,
+        };
+      }
+    },
+  };
+}

package/src/projection.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { access, definePluginMetadata, proc } from "@checkstack/common";
+import type { AnyContractProcedure } from "@orpc/contract";
+import { buildProjectedTool } from "./projection";
+
+const sourcePluginMetadata = definePluginMetadata({ pluginId: "incident" });
+const incidentRead = access("incident", "read", "View incidents");
+
+// A realistic contract procedure with access metadata + an input schema.
+const listIncidents = proc({
+  operationType: "query",
+  userType: "authenticated",
+  access: [incidentRead],
+}).input(z.object({ status: z.string().optional() })) as AnyContractProcedure;
+
+describe("buildProjectedTool", () => {
+  test("requiredAccessRules equals the source procedure's qualified access rules", () => {
+    const t = buildProjectedTool({
+      procedure: listIncidents,
+      sourcePluginMetadata,
+      procedureKey: "listIncidents",
+      description: "List incidents.",
+      effect: "read",
+      execute: () => Promise.resolve({}),
+    });
+
+    // qualifyAccessRuleId: `${pluginId}.${rule.id}` where rule.id = `incident.read`.
+    expect(t.requiredAccessRules).toEqual(["incident.incident.read"]);
+  });
+
+  test("derives the tool name as <sourcePlugin>.<procedureKey> when no name override", () => {
+    const t = buildProjectedTool({
+      procedure: listIncidents,
+      sourcePluginMetadata,
+      procedureKey: "listIncidents",
+      description: "List incidents.",
+      effect: "read",
+      execute: () => Promise.resolve({}),
+    });
+    expect(t.name).toBe("incident.listIncidents");
+  });
+
+  test("honours a name override", () => {
+    const t = buildProjectedTool({
+      procedure: listIncidents,
+      sourcePluginMetadata,
+      procedureKey: "listIncidents",
+      name: "incident.list",
+      description: "List incidents.",
+      effect: "read",
+      execute: () => Promise.resolve({}),
+    });
+    expect(t.name).toBe("incident.list");
+  });
+
+  test("uses the source procedure's input schema", () => {
+    const t = buildProjectedTool({
+      procedure: listIncidents,
+      sourcePluginMetadata,
+      procedureKey: "listIncidents",
+      description: "List incidents.",
+      effect: "read",
+      execute: () => Promise.resolve({}),
+    });
+    // The projected input parses the same shape the procedure declared.
+    expect(t.input.safeParse({ status: "open" }).success).toBe(true);
+    expect(t.input.safeParse({ status: 123 }).success).toBe(false);
+  });
+
+  test("throws when effect is omitted (never inferred from operationType)", () => {
+    expect(() =>
+      buildProjectedTool({
+        procedure: listIncidents,
+        sourcePluginMetadata,
+        procedureKey: "listIncidents",
+        description: "List incidents.",
+        // Force the runtime guard: a JS caller could omit `effect`.
+        effect: undefined as unknown as "read",
+        execute: () => Promise.resolve({}),
+      }),
+    ).toThrow(/effect.*required/i);
+  });
+
+  test("throws when the value is not an oRPC contract procedure", () => {
+    expect(() =>
+      buildProjectedTool({
+        procedure: {} as AnyContractProcedure,
+        sourcePluginMetadata,
+        procedureKey: "bogus",
+        description: "Bogus.",
+        effect: "read",
+        execute: () => Promise.resolve({}),
+      }),
+    ).toThrow(/not an oRPC contract procedure/i);
+  });
+});