@checkstack/ai-backend 0.1.0

package/src/serializer.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { toJsonSchema, configString } from "@checkstack/backend-api";
+import type { RegisteredAiTool } from "./tool-registry";
+import { serializeTool, serializeTools } from "./serializer";
+
+describe("serializeTool", () => {
+  const inputSchema = z.object({ status: z.string().optional() });
+  const tool: RegisteredAiTool = {
+    name: "incident.list",
+    description: "List incidents.",
+    effect: "read",
+    input: inputSchema,
+    requiredAccessRules: ["incident.incident.read"],
+    execute: () => Promise.resolve({}),
+  };
+
+  test("produces the SAME JSON Schema as toJsonSchema (no second serializer drift)", () => {
+    const descriptor = serializeTool({ tool });
+    // The serializer must wrap the platform's toJsonSchema verbatim, so a tool
+    // input schema and the same schema run through the OpenAPI substrate agree.
+    expect(descriptor.inputSchema).toEqual(toJsonSchema(inputSchema));
+  });
+
+  test("carries name, description, effect, and requiredAccessRules", () => {
+    const descriptor = serializeTool({ tool });
+    expect(descriptor.name).toBe("incident.list");
+    expect(descriptor.description).toBe("List incidents.");
+    expect(descriptor.effect).toBe("read");
+    expect(descriptor.requiredAccessRules).toEqual(["incident.incident.read"]);
+  });
+
+  test("includes outputSchema only when the tool declares an output", () => {
+    expect(serializeTool({ tool }).outputSchema).toBeUndefined();
+    const withOutput: RegisteredAiTool = {
+      ...tool,
+      output: z.object({ count: z.number() }),
+    };
+    expect(serializeTool({ tool: withOutput }).outputSchema).toEqual(
+      toJsonSchema(z.object({ count: z.number() })),
+    );
+  });
+
+  test("never emits a secret VALUE into the descriptor", () => {
+    // A tool whose input has an x-secret field: the schema describes the field
+    // but the descriptor must never contain a concrete secret value.
+    const secretTool: RegisteredAiTool = {
+      name: "thing.configure",
+      description: "Configure a thing.",
+      effect: "read",
+      input: z.object({ apiKey: configString({ "x-secret": true }) }),
+      requiredAccessRules: ["ai.tools.manage"],
+      execute: () => Promise.resolve({}),
+    };
+    const serialized = JSON.stringify(serializeTool({ tool: secretTool }));
+    // The descriptor is pure schema metadata — it carries no runtime values.
+    expect(serialized).not.toContain("super-secret");
+    // The x-secret marker IS preserved (so transports can mask), but no value.
+    expect(serialized).toContain("x-secret");
+  });
+});
+
+describe("serializeTools", () => {
+  test("serializes each tool", () => {
+    const tools: RegisteredAiTool[] = [
+      {
+        name: "a.one",
+        description: "a",
+        effect: "read",
+        input: z.object({}),
+        requiredAccessRules: [],
+        execute: () => Promise.resolve({}),
+      },
+      {
+        name: "b.two",
+        description: "b",
+        effect: "mutate",
+        input: z.object({}),
+        requiredAccessRules: ["b.x.manage"],
+        execute: () => Promise.resolve({}),
+      },
+    ];
+    expect(serializeTools({ tools }).map((d) => d.name)).toEqual([
+      "a.one",
+      "b.two",
+    ]);
+  });
+});

package/src/serializer.ts

@@ -0,0 +1,42 @@
+import { toJsonSchema } from "@checkstack/backend-api";
+import type { AiTool, AiToolDescriptor } from "@checkstack/ai-common";
+
+/**
+ * Serialize a registered {@link AiTool} into its transport-facing descriptor.
+ *
+ * This is the ONE serializer shared by both transports (OpenAI function
+ * schemas and MCP tool defs). It wraps the platform's `toJsonSchema()`
+ * (which itself wraps zod v4's native `toJSONSchema()` and stamps the `x-*`
+ * registry metadata), so the schema a tool exposes is byte-for-byte the same
+ * substrate the OpenAPI generator emits for the source procedure — there is no
+ * second serializer to drift.
+ *
+ * The descriptor deliberately carries NO executor closure and NO zod object,
+ * only JSON Schema + metadata, so it is safe to return over an RPC or MCP wire.
+ */
+export function serializeTool({
+  tool,
+}: {
+  tool: AiTool;
+}): AiToolDescriptor {
+  return {
+    name: tool.name,
+    description: tool.description,
+    effect: tool.effect,
+    inputSchema: toJsonSchema(tool.input),
+    outputSchema: tool.output ? toJsonSchema(tool.output) : undefined,
+    requiredAccessRules: [...tool.requiredAccessRules],
+  };
+}
+
+/**
+ * Serialize many tools at once (convenience for the introspection RPC and the
+ * MCP `list_tools` response).
+ */
+export function serializeTools({
+  tools,
+}: {
+  tools: AiTool[];
+}): AiToolDescriptor[] {
+  return tools.map((tool) => serializeTool({ tool }));
+}

package/src/tool-registry.ts

@@ -0,0 +1,58 @@
+import type { AuthUser, RpcClient } from "@checkstack/backend-api";
+import type { AiTool } from "@checkstack/ai-common";
+
+/**
+ * A tool whose executors run with a Checkstack {@link AuthUser} principal and
+ * receive a USER-SCOPED {@link RpcClient} (bound to the originating user) for any
+ * plugin call - so handler-side authz + per-resource/team scoping always apply.
+ */
+export type RegisteredAiTool<TInput = unknown, TOutput = unknown> = AiTool<
+  TInput,
+  TOutput,
+  AuthUser,
+  RpcClient
+>;
+
+/**
+ * Registry for AI tools — the spine of the AI platform. Plugins contribute
+ * tools through `aiToolExtensionPoint` (hand-authored composite tools) and
+ * `aiToolProjectionExtensionPoint` (opt-in projections of existing oRPC
+ * procedures). Both transports (chat, MCP) resolve tools from this one
+ * registry, so no capability is implemented twice.
+ *
+ * Tool names are already fully qualified (`<plugin>.<tool>`) by the extension
+ * points before they reach `register`.
+ */
+export interface AiToolRegistry {
+  register(tool: RegisteredAiTool): void;
+  getTools(): RegisteredAiTool[];
+  getTool(name: string): RegisteredAiTool | undefined;
+  hasTool(name: string): boolean;
+}
+
+export function createAiToolRegistry(): AiToolRegistry {
+  const tools = new Map<string, RegisteredAiTool>();
+
+  return {
+    register(tool: RegisteredAiTool): void {
+      if (tools.has(tool.name)) {
+        throw new Error(
+          `AI tool ${tool.name} already registered — likely a duplicate registration.`,
+        );
+      }
+      tools.set(tool.name, tool);
+    },
+
+    getTools(): RegisteredAiTool[] {
+      return [...tools.values()];
+    },
+
+    getTool(name: string): RegisteredAiTool | undefined {
+      return tools.get(name);
+    },
+
+    hasTool(name: string): boolean {
+      return tools.has(name);
+    },
+  };
+}

package/src/tools/composite-tools.ts

@@ -0,0 +1,24 @@
+import type { RegisteredAiTool } from "../tool-registry";
+import { createDocsTools } from "./docs-tools";
+import { createProbeUrlTool } from "./probe-url";
+
+/**
+ * ai-backend's OWN platform AI tools, registered through `aiToolExtensionPoint`.
+ * These are genuinely cross-plugin / platform tools with no single owning plugin:
+ * documentation grounding (bundled docs) and URL probing.
+ *
+ * Plugin-specific tools (health-check / automation propose-update-delete,
+ * capability catalogs, and script-context tools) are owned by and registered
+ * FROM their plugins via the same `aiToolExtensionPoint` - ai-backend does not
+ * depend on any plugin's `*-common` to build them. The systemic-authz test in
+ * `tool-set.e2e.test.ts` covers this set plus the projected read tools.
+ */
+export function buildCompositeTools(): RegisteredAiTool[] {
+  return [
+    // Docs grounding (effect: "read"; composes the bundled docs index).
+    ...createDocsTools(),
+    // URL introspection (effect: "read"): probe a public URL to see what it
+    // returns before drafting check assertions. SSRF-guarded (no internal hosts).
+    createProbeUrlTool(),
+  ];
+}

package/src/tools/docs-tools.test.ts

@@ -0,0 +1,150 @@
+import { describe, expect, test } from "bun:test";
+import type { AuthUser, RpcClient } from "@checkstack/backend-api";
+import {
+  SearchDocsOutputSchema,
+  GetDocOutputSchema,
+} from "@checkstack/ai-common";
+import type { DocsIndexEntry } from "../generated/docs-index";
+import { createAiToolRegistry } from "../tool-registry";
+import { createAiToolResolver } from "../resolver";
+import { createRegistryExtensionPoints } from "../registry-wiring";
+import { pluginMetadata as aiPluginMetadata } from "@checkstack/ai-common";
+import {
+  createDocsTools,
+  createGetDocTool,
+  createSearchDocsTool,
+} from "./docs-tools";
+
+const FIXTURE_INDEX: DocsIndexEntry[] = [
+  {
+    slug: "user-guide/concepts/health-checks",
+    title: "Health checks",
+    description: "How health checks work",
+    headings: ["Strategies", "Collectors"],
+    content: "A health check probes a target on a schedule.",
+    truncated: false,
+  },
+  {
+    slug: "developer-guide/ai/context-tools",
+    title: "Assistant context tools",
+    headings: ["searchDocs", "getDoc"],
+    content: "The assistant can search and read the docs.",
+    truncated: true,
+  },
+];
+
+/** A user with exactly the given access rules. */
+function userWith(accessRules: string[]): AuthUser {
+  return { type: "user", id: "u1", accessRules };
+}
+
+const PRINCIPAL = userWith(["ai.chat.read"]);
+
+// The docs tools read the bundled docs index, never the RPC client, so a
+// never-called stub satisfies the user-scoped `rpcClient` arg of `execute`.
+const rpcClient = {
+  forPlugin: () => {
+    throw new Error("docs tools must not call the RPC client");
+  },
+} as unknown as RpcClient;
+
+describe("ai.searchDocs tool", () => {
+  test("returns DocHit[] validating the wire schema", async () => {
+    const tool = createSearchDocsTool({ index: FIXTURE_INDEX });
+    const out = await tool.execute({
+      input: { query: "health check", limit: 5 },
+      principal: PRINCIPAL,
+      rpcClient,
+    });
+    expect(() => SearchDocsOutputSchema.parse(out)).not.toThrow();
+    expect(out.hits.length).toBeGreaterThan(0);
+    expect(out.hits[0]?.slug).toBe("user-guide/concepts/health-checks");
+  });
+
+  test("honours the limit cap", async () => {
+    const tool = createSearchDocsTool({ index: FIXTURE_INDEX });
+    const out = await tool.execute({
+      input: { query: "docs the assistant health", limit: 1 },
+      principal: PRINCIPAL,
+      rpcClient,
+    });
+    expect(out.hits.length).toBe(1);
+  });
+
+  test("is effect:read and gated by ai.chat.read", () => {
+    const tool = createSearchDocsTool();
+    expect(tool.effect).toBe("read");
+    expect(tool.requiredAccessRules).toEqual(["ai.chat.read"]);
+    expect(tool.dryRun).toBeUndefined();
+  });
+});
+
+describe("ai.getDoc tool", () => {
+  test("returns a known slug's content + truncated flag (schema-valid)", async () => {
+    const tool = createGetDocTool({ index: FIXTURE_INDEX });
+    const out = await tool.execute({
+      input: { slug: "developer-guide/ai/context-tools" },
+      principal: PRINCIPAL,
+      rpcClient,
+    });
+    expect(() => GetDocOutputSchema.parse(out)).not.toThrow();
+    expect(out.title).toBe("Assistant context tools");
+    expect(out.truncated).toBe(true);
+    expect(out.content).toContain("search and read the docs");
+  });
+
+  test("an unknown slug throws a clear, recoverable error", async () => {
+    const tool = createGetDocTool({ index: FIXTURE_INDEX });
+    await expect(
+      tool.execute({ input: { slug: "does/not/exist" }, principal: PRINCIPAL, rpcClient }),
+    ).rejects.toThrow(/searchDocs/);
+  });
+
+  test("is effect:read and gated by ai.chat.read", () => {
+    const tool = createGetDocTool();
+    expect(tool.effect).toBe("read");
+    expect(tool.requiredAccessRules).toEqual(["ai.chat.read"]);
+  });
+});
+
+describe("docs tools registration + resolution", () => {
+  test("both qualify to ai.* and a chat user sees them", () => {
+    const registry = createAiToolRegistry();
+    const { toolExtensionPoint } = createRegistryExtensionPoints({ registry });
+    for (const tool of createDocsTools({ index: FIXTURE_INDEX })) {
+      toolExtensionPoint.registerTool(tool, aiPluginMetadata);
+    }
+    const resolver = createAiToolResolver({ registry });
+
+    const names = resolver
+      .resolveTools(userWith(["ai.chat.read"]))
+      .map((t) => t.name)
+      .sort();
+    expect(names).toEqual(["ai.getDoc", "ai.searchDocs"]);
+  });
+
+  test("a principal without ai.chat.read sees neither docs tool", () => {
+    const registry = createAiToolRegistry();
+    const { toolExtensionPoint } = createRegistryExtensionPoints({ registry });
+    for (const tool of createDocsTools({ index: FIXTURE_INDEX })) {
+      toolExtensionPoint.registerTool(tool, aiPluginMetadata);
+    }
+    const resolver = createAiToolResolver({ registry });
+
+    const names = resolver
+      .resolveTools(userWith(["incident.incident.read"]))
+      .map((t) => t.name);
+    expect(names).toEqual([]);
+  });
+
+  test("the bundled production index powers searchDocs (smoke test)", async () => {
+    // Uses the real DOCS_INDEX default; the AI docs page must be findable.
+    const tool = createSearchDocsTool();
+    const out = await tool.execute({
+      input: { query: "AI assistant documentation tools", limit: 10 },
+      principal: PRINCIPAL,
+      rpcClient,
+    });
+    expect(out.hits.length).toBeGreaterThan(0);
+  });
+});

package/src/tools/docs-tools.ts

@@ -0,0 +1,115 @@
+import { qualifyAccessRuleId } from "@checkstack/common";
+import {
+  aiAccess,
+  pluginMetadata as aiPluginMetadata,
+  SearchDocsInputSchema,
+  SearchDocsOutputSchema,
+  GetDocInputSchema,
+  GetDocOutputSchema,
+  type SearchDocsInput,
+  type SearchDocsOutput,
+  type GetDocInput,
+  type GetDocOutput,
+} from "@checkstack/ai-common";
+import { DOCS_INDEX, type DocsIndexEntry } from "../generated/docs-index";
+import { rankDocs } from "./rank-docs";
+import type { RegisteredAiTool } from "../tool-registry";
+
+/**
+ * Documentation-grounding tools (`ai.searchDocs` + `ai.getDoc`, plan §2.5).
+ * Both are composite `effect: "read"` tools: they compose the BUILD-TIME bundled
+ * docs index (`DOCS_INDEX`, plan §3.4) rather than projecting a single oRPC
+ * procedure, so they run their own `execute` in the chat loop's composite-read
+ * path. Gated by `ai.chat.read`: any chat user may read the platform's own
+ * public documentation; the docs carry no per-tenant data.
+ *
+ * The bundled index is identical on every pod (it is part of the same build
+ * artifact), so a read returns the same answer everywhere — no pod-local state
+ * (plan §7.2).
+ */
+
+/** The qualified access rule both docs tools require: `ai.chat.read`. */
+const AI_CHAT_READ = qualifyAccessRuleId(aiPluginMetadata, aiAccess.chatUse);
+
+/**
+ * Builds `ai.searchDocs`: keyword/BM25-ish ranking over the bundled index. The
+ * ranking itself is the pure, unit-tested {@link rankDocs}; this builder only
+ * adapts the input/output to the wire contract.
+ *
+ * `index` is injectable for tests; production uses the bundled `DOCS_INDEX`.
+ */
+export function createSearchDocsTool({
+  index = DOCS_INDEX,
+}: {
+  index?: readonly DocsIndexEntry[];
+} = {}): RegisteredAiTool<SearchDocsInput, SearchDocsOutput> {
+  return {
+    name: "searchDocs",
+    description:
+      "Search Checkstack's own documentation by keyword and return the most " +
+      "relevant pages with a short snippet from each. Use this FIRST to ground " +
+      "any how-to or conceptual answer about Checkstack in the real docs, then " +
+      "call getDoc to read a promising page in full. Read-only.",
+    effect: "read",
+    input: SearchDocsInputSchema,
+    output: SearchDocsOutputSchema,
+    requiredAccessRules: [AI_CHAT_READ],
+    async execute({ input }) {
+      const hits = rankDocs({ index, query: input.query, limit: input.limit });
+      return { hits };
+    },
+  };
+}
+
+/**
+ * Builds `ai.getDoc`: returns one documentation page's full (frontmatter-
+ * stripped, byte-capped) content by slug. An unknown slug yields a clear error
+ * the model can recover from (it can re-`searchDocs`).
+ */
+export function createGetDocTool({
+  index = DOCS_INDEX,
+}: {
+  index?: readonly DocsIndexEntry[];
+} = {}): RegisteredAiTool<GetDocInput, GetDocOutput> {
+  return {
+    name: "getDoc",
+    description:
+      "Read one Checkstack documentation page in full by its slug (as returned " +
+      "by searchDocs, e.g. \"user-guide/concepts/health-checks\"). Use this " +
+      "after searchDocs to ground an answer in the page's actual content. " +
+      "Read-only.",
+    effect: "read",
+    input: GetDocInputSchema,
+    output: GetDocOutputSchema,
+    requiredAccessRules: [AI_CHAT_READ],
+    async execute({ input }) {
+      const entry = index.find((e) => e.slug === input.slug);
+      if (!entry) {
+        throw new Error(
+          `No documentation page with slug "${input.slug}". Use searchDocs to ` +
+            "find a valid slug.",
+        );
+      }
+      return {
+        slug: entry.slug,
+        title: entry.title,
+        ...(entry.description ? { description: entry.description } : {}),
+        content: entry.content,
+        truncated: entry.truncated,
+      };
+    },
+  };
+}
+
+/**
+ * Builds both docs-grounding tools (the Phase 1 registration unit). Returns the
+ * erased `RegisteredAiTool` form so callers can iterate + register uniformly
+ * (the two tools have different input/output shapes).
+ */
+export function createDocsTools({
+  index = DOCS_INDEX,
+}: {
+  index?: readonly DocsIndexEntry[];
+} = {}): RegisteredAiTool[] {
+  return [createSearchDocsTool({ index }), createGetDocTool({ index })];
+}

package/src/tools/probe-url.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from "bun:test";
+import type { AuthUser, RpcClient } from "@checkstack/backend-api";
+import { createProbeUrlTool } from "./probe-url";
+
+const principal: AuthUser = {
+  type: "user",
+  id: "u1",
+  accessRules: ["ai.chat.read"],
+};
+
+// probeUrl never touches the RPC client (it only issues an outbound fetch), so a
+// never-called stub satisfies the user-scoped `rpcClient` arg of `execute`.
+const rpcClient = {
+  forPlugin: () => {
+    throw new Error("probeUrl must not call the RPC client");
+  },
+} as unknown as RpcClient;
+
+describe("ai.probeUrl tool", () => {
+  test("is a read tool gated by the chat-read surface", () => {
+    const tool = createProbeUrlTool();
+    expect(tool.name).toBe("probeUrl");
+    expect(tool.effect).toBe("read");
+    expect(tool.requiredAccessRules).toEqual(["ai.chat.read"]);
+  });
+
+  test("refuses an internal/loopback target before any network call", async () => {
+    const tool = createProbeUrlTool();
+    await expect(
+      tool.execute({ input: { url: "http://localhost:8080/", method: "GET" }, principal, rpcClient }),
+    ).rejects.toThrow(/loopback|internal/);
+  });
+
+  test("refuses the cloud metadata IP before any network call", async () => {
+    const tool = createProbeUrlTool();
+    await expect(
+      tool.execute({
+        input: { url: "http://169.254.169.254/latest/meta-data", method: "GET" },
+        principal,
+        rpcClient,
+      }),
+    ).rejects.toThrow(/private\/reserved/);
+  });
+
+  test("refuses a non-http(s) scheme", async () => {
+    const tool = createProbeUrlTool();
+    await expect(
+      tool.execute({ input: { url: "file:///etc/passwd", method: "GET" }, principal, rpcClient }),
+    ).rejects.toThrow(/http and https/);
+  });
+});

package/src/tools/probe-url.ts

@@ -0,0 +1,146 @@
+import { lookup } from "node:dns/promises";
+import { z } from "zod";
+import { qualifyAccessRuleId } from "@checkstack/common";
+import type { AuthUser } from "@checkstack/backend-api";
+import { aiAccess, pluginMetadata as aiPluginMetadata } from "@checkstack/ai-common";
+import type { RegisteredAiTool } from "../tool-registry";
+import {
+  isPrivateIp,
+  parseSafeProbeUrl,
+  PROBE_MAX_BODY_BYTES,
+  PROBE_TIMEOUT_MS,
+} from "./ssrf-guard";
+
+/** Input for `ai.probeUrl`: the URL to introspect and the HTTP method. */
+export const ProbeUrlInputSchema = z.object({
+  url: z.string().min(1),
+  method: z.enum(["GET", "HEAD"]).default("GET"),
+});
+export type ProbeUrlInput = z.infer<typeof ProbeUrlInputSchema>;
+
+/** What a probe reports back to the model (no secrets, body capped). */
+export const ProbeUrlOutputSchema = z.object({
+  url: z.string(),
+  status: z.number(),
+  statusText: z.string(),
+  /** True for a 3xx; `location` carries the redirect target (not followed). */
+  redirected: z.boolean(),
+  location: z.string().optional(),
+  contentType: z.string().optional(),
+  /** A safe, small subset of response headers. */
+  headers: z.record(z.string(), z.string()),
+  /** Up to PROBE_MAX_BODY_BYTES of the body, decoded as text. */
+  bodySample: z.string(),
+  bodyTruncated: z.boolean(),
+});
+export type ProbeUrlOutput = z.infer<typeof ProbeUrlOutputSchema>;
+
+/** Response headers we surface (never set-cookie / auth-bearing headers). */
+const SAFE_HEADERS = ["content-type", "content-length", "server", "location"];
+
+/** Read up to PROBE_MAX_BODY_BYTES of a response body as text (capped). */
+async function readCappedText(
+  response: Response,
+): Promise<{ text: string; truncated: boolean }> {
+  if (!response.body) return { text: "", truncated: false };
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  let truncated = false;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (!value) continue;
+    const remaining = PROBE_MAX_BODY_BYTES - total;
+    if (value.length >= remaining) {
+      chunks.push(value.slice(0, remaining));
+      total += remaining;
+      truncated = true;
+      await reader.cancel();
+      break;
+    }
+    chunks.push(value);
+    total += value.length;
+  }
+  const merged = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    merged.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return { text: new TextDecoder().decode(merged), truncated };
+}
+
+/**
+ * `ai.probeUrl` - issue ONE outbound HTTP GET/HEAD so the assistant can see what
+ * a URL actually returns (status, content type, a body sample) before drafting a
+ * health check's assertions. `effect: "read"` (auto-runs).
+ *
+ * SSRF DEFENSE (the request leaves the CORE BACKEND): the URL shape is validated
+ * (`parseSafeProbeUrl` - http(s) only, no loopback/internal host, no private IP
+ * literal), the hostname is then DNS-resolved and EVERY resolved IP is checked
+ * against the private/reserved ranges (catching a public name that resolves to a
+ * private IP), redirects are NOT followed (a 3xx only reports its `location`),
+ * the request carries no credentials, times out at PROBE_TIMEOUT_MS, and the body
+ * is read capped at PROBE_MAX_BODY_BYTES.
+ */
+export function createProbeUrlTool(): RegisteredAiTool<
+  ProbeUrlInput,
+  ProbeUrlOutput
+> {
+  return {
+    name: "probeUrl",
+    description:
+      "Make ONE outbound HTTP GET or HEAD request to a public URL and return its status code, content type, response headers, and a sample of the body. Use this to inspect what an endpoint returns (e.g. what GET https://foo.bar/status responds with) BEFORE drafting a health check's assertions, so you assert on the real response. Redirects are not followed (a 3xx returns its Location). Cannot reach private/internal addresses.",
+    effect: "read",
+    input: ProbeUrlInputSchema,
+    output: ProbeUrlOutputSchema,
+    // Same broad chat-read surface as the docs/capability read tools.
+    requiredAccessRules: [qualifyAccessRuleId(aiPluginMetadata, aiAccess.chatUse)],
+    async execute({ input }: { input: ProbeUrlInput; principal: AuthUser }) {
+      const { url, hostname } = parseSafeProbeUrl(input.url);
+
+      // DNS re-check: a public-looking hostname must not resolve to a private IP.
+      const resolved = await lookup(hostname, { all: true });
+      for (const { address } of resolved) {
+        if (isPrivateIp(address)) {
+          throw new Error(
+            `Refusing to probe "${hostname}": it resolves to a private/reserved address (${address}).`,
+          );
+        }
+      }
+
+      const response = await fetch(url, {
+        method: input.method,
+        redirect: "manual",
+        signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+        // No credentials/cookies; advertise a benign accept.
+        headers: { accept: "*/*" },
+      });
+
+      const headers: Record<string, string> = {};
+      for (const name of SAFE_HEADERS) {
+        const value = response.headers.get(name);
+        if (value !== null) headers[name] = value;
+      }
+
+      const redirected = response.status >= 300 && response.status < 400;
+      const { text, truncated } =
+        input.method === "HEAD"
+          ? { text: "", truncated: false }
+          : await readCappedText(response);
+
+      return {
+        url: url.toString(),
+        status: response.status,
+        statusText: response.statusText,
+        redirected,
+        location: response.headers.get("location") ?? undefined,
+        contentType: response.headers.get("content-type") ?? undefined,
+        headers,
+        bodySample: text,
+        bodyTruncated: truncated,
+      };
+    },
+  };
+}