@checkstack/ai-backend 0.1.5 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # @checkstack/ai-backend
 
+## 0.2.0
+
+### Minor Changes
+
+- 2428bfc: fix(ai): make AI tool names provider-safe (no "." in names)
+
+  LLM providers (and the MCP spec) require tool names to match
+  `^[a-zA-Z0-9_-]+$`, but our tool names are qualified as `<plugin>.<tool>`
+  (e.g. `incident.list`, `dependency.list`). The "." caused the model backend to
+  reject the tool list, so chat tool-calling failed after deploy.
+
+  Tool names are now normalized to a provider-safe form at the single
+  registration chokepoint (the tool registry) and in the projection-routing
+  table: the "." namespace separator is mapped to "\_" (so `incident.list`
+  becomes `incident_list`). The registry key, the name serialized out to the
+  model / MCP client, and the name the model echoes back in a tool call are all
+  the same normalized string, so the round-trip needs no reverse lookup. Any
+  other illegal character is an authoring mistake and is now rejected at
+  registration rather than silently rewritten.
+
+  BREAKING: AI tool names exposed over the MCP `tools/list` endpoint change from
+  the dotted form (`incident.list`) to the underscored form (`incident_list`).
+  MCP clients that referenced tools by their dotted names must update to the
+  underscored names. (Chat was already broken by the provider rejection, so this
+  only changes the working MCP surface.)
+
+## 0.1.6
+
+### Patch Changes
+
+- f9cfdae: fix(dependency): gate the dependency map behind its own non-public access rule
+
+  Anonymous users could see the "Dependency Map" nav entry and open the page
+  (which then rendered empty) because the map was gated by `dependency.read`,
+  which is public so that dependency _warning_ badges stay visible on the
+  catalog and dashboard.
+
+  The full topology map is now gated by a dedicated `dependency.map` access
+  rule that is granted to authenticated users by default but is NOT public, so
+  anonymous visitors no longer see the nav entry or reach the page. The
+  `getAllDependencies`, `getNodePositions`, and `saveNodePositions` endpoints
+  move to this rule too, and the dashboard dependency signal now renders as
+  plain text (not a map link) for users without map access. Per-system
+  dependency warnings stay on the public `dependency.read` rule, so warning
+  badges/alerts/signals remain visible to everyone as before.
+
+  Admins can still grant `dependency.map` to the anonymous role to make the
+  map public again.
+
+  Note: the default-rule sync is add-only, so on existing deployments the
+  anonymous role keeps any rules already granted. Since `dependency.map` is a
+  brand-new rule the anonymous role never had it, so the map is hidden from
+  anonymous users immediately after upgrade with no admin action required.
+
+  - @checkstack/sdk@0.101.1
+
 ## 0.1.5
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/ai-backend",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -21,7 +21,7 @@
     "@checkstack/common": "0.15.0",
     "@checkstack/drizzle-helper": "0.0.5",
     "@checkstack/integration-backend": "0.4.5",
-    "@checkstack/sdk": "0.100.1",
+    "@checkstack/sdk": "0.102.0",
     "@orpc/client": "^1.14.4",
     "@orpc/contract": "^1.14.4",
     "@orpc/server": "^1.14.4",

package/src/agent-runner.test.ts

@@ -47,14 +47,14 @@ describe("createAgentRunner", () => {
     const registry = createAiToolRegistry();
     const calls: string[] = [];
     registry.register(
-      readTool("plugin.read", async () => {
-        calls.push("plugin.read");
+      readTool("plugin_read", async () => {
+        calls.push("plugin_read");
         return { ok: true };
       }),
     );
     // A destructive tool must NOT be offered.
     registry.register({
-      name: "plugin.delete",
+      name: "plugin_delete",
       description: "delete",
       effect: "destructive",
       input: z.object({}),
@@ -63,7 +63,7 @@ describe("createAgentRunner", () => {
     } as RegisteredAiTool);
     // A projected read (deferred sentinel) must NOT be offered in v1.
     registry.register({
-      name: "plugin.projected",
+      name: "plugin_projected",
       description: "projected",
       effect: "read",
       input: z.object({}),
@@ -77,7 +77,7 @@ describe("createAgentRunner", () => {
     const generateText = mock(async (args: { tools?: Record<string, unknown> }) => {
       offeredToolNames = Object.keys(args.tools ?? {});
       // Simulate the model calling the read tool once.
-      const t = (args.tools ?? {})["plugin.read"] as {
+      const t = (args.tools ?? {})["plugin_read"] as {
         execute: (i: unknown) => Promise<unknown>;
       };
       await t.execute({});
@@ -102,11 +102,11 @@ describe("createAgentRunner", () => {
       outputSchema: z.object({ severity: z.string() }),
     });
 
-    expect(offeredToolNames.sort()).toEqual(["plugin.read"]);
-    expect(calls).toEqual(["plugin.read"]);
+    expect(offeredToolNames.sort()).toEqual(["plugin_read"]);
+    expect(calls).toEqual(["plugin_read"]);
     expect(result.text).toBe("done");
     expect(result.object).toEqual({ severity: "high" });
-    expect(result.toolCalls).toEqual([{ tool: "plugin.read", ok: true }]);
+    expect(result.toolCalls).toEqual([{ tool: "plugin_read", ok: true }]);
   });
 
   it("hands the model a date-safe schema for tools with Date inputs (no throw)", async () => {
@@ -116,7 +116,7 @@ describe("createAgentRunner", () => {
     // chat. The runner must gate date inputs through dateSafeModelSchema too.
     const registry = createAiToolRegistry();
     registry.register({
-      name: "plugin.history",
+      name: "plugin_history",
       description: "history",
       effect: "read",
       input: z.object({ since: z.date() }),
@@ -130,7 +130,7 @@ describe("createAgentRunner", () => {
       async (args: {
         tools?: Record<string, { inputSchema: unknown }>;
       }) => {
-        const t = (args.tools ?? {})["plugin.history"];
+        const t = (args.tools ?? {})["plugin_history"];
         // Exactly what the SDK does internally to build the model request; this
         // threw before the fix.
         offeredSchema = await asSchema(t.inputSchema as never).jsonSchema;
@@ -161,7 +161,7 @@ describe("createAgentRunner", () => {
   it("offers a projected read tool and routes it through the principal's client", async () => {
     const registry = createAiToolRegistry();
     registry.register({
-      name: "incident.list",
+      name: "incident_list",
       description: "list incidents",
       effect: "read",
       input: z.object({}),
@@ -186,7 +186,7 @@ describe("createAgentRunner", () => {
     let offered: string[] = [];
     const generateText = mock(async (args: { tools?: Record<string, unknown> }) => {
       offered = Object.keys(args.tools ?? {});
-      const t = (args.tools ?? {})["incident.list"] as {
+      const t = (args.tools ?? {})["incident_list"] as {
         execute: (i: unknown) => Promise<unknown>;
       };
       await t.execute({ status: "open" });
@@ -197,7 +197,7 @@ describe("createAgentRunner", () => {
       resolver,
       resolveConnection: async () => connection,
       getProjectionRoute: (name) =>
-        name === "incident.list"
+        name === "incident_list"
           ? { pluginId: "incident", procedureKey: "listIncidents" }
           : undefined,
       modelFns: { generateText: generateText as never },
@@ -210,15 +210,15 @@ describe("createAgentRunner", () => {
       prompt: "go",
     });
 
-    expect(offered).toEqual(["incident.list"]);
+    expect(offered).toEqual(["incident_list"]);
     expect(procCalls).toEqual([{ status: "open" }]);
-    expect(result.toolCalls).toEqual([{ tool: "incident.list", ok: true }]);
+    expect(result.toolCalls).toEqual([{ tool: "incident_list", ok: true }]);
   });
 
   it("records a tool failure and surfaces it to the model instead of aborting", async () => {
     const registry = createAiToolRegistry();
     registry.register(
-      readTool("plugin.boom", async () => {
+      readTool("plugin_boom", async () => {
         throw new Error("missing access: plugin.read");
       }),
     );
@@ -226,7 +226,7 @@ describe("createAgentRunner", () => {
 
     let toolResult: unknown;
     const generateText = mock(async (args: { tools?: Record<string, unknown> }) => {
-      const t = (args.tools ?? {})["plugin.boom"] as {
+      const t = (args.tools ?? {})["plugin_boom"] as {
         execute: (i: unknown) => Promise<unknown>;
       };
       toolResult = await t.execute({});
@@ -247,15 +247,15 @@ describe("createAgentRunner", () => {
     });
 
     expect(toolResult).toEqual({ error: "missing access: plugin.read" });
-    expect(result.toolCalls).toEqual([{ tool: "plugin.boom", ok: false }]);
+    expect(result.toolCalls).toEqual([{ tool: "plugin_boom", ok: false }]);
     expect(result.object).toBeUndefined();
   });
 
   it("calls recordToolCall for each invocation (ok and failure)", async () => {
     const registry = createAiToolRegistry();
-    registry.register(readTool("plugin.ok", async () => ({ ok: true })));
+    registry.register(readTool("plugin_ok", async () => ({ ok: true })));
     registry.register(
-      readTool("plugin.boom", async () => {
+      readTool("plugin_boom", async () => {
         throw new Error("nope");
       }),
     );
@@ -273,8 +273,8 @@ describe("createAgentRunner", () => {
 
     const generateText = mock(async (args: { tools?: Record<string, unknown> }) => {
       const tools = args.tools ?? {};
-      await (tools["plugin.ok"] as { execute: (i: unknown) => Promise<unknown> }).execute({});
-      await (tools["plugin.boom"] as { execute: (i: unknown) => Promise<unknown> }).execute({});
+      await (tools["plugin_ok"] as { execute: (i: unknown) => Promise<unknown> }).execute({});
+      await (tools["plugin_boom"] as { execute: (i: unknown) => Promise<unknown> }).execute({});
       return { text: "x", usage: {} };
     });
 
@@ -287,12 +287,12 @@ describe("createAgentRunner", () => {
     await runner({ principal, rpcClient, connectionId: "c", prompt: "go" });
 
     expect(recorded).toContainEqual({
-      toolName: "plugin.ok",
+      toolName: "plugin_ok",
       ok: true,
       effect: "read",
     });
     expect(recorded).toContainEqual({
-      toolName: "plugin.boom",
+      toolName: "plugin_boom",
       ok: false,
       effect: "read",
     });

package/src/chat/agent-loop.test.ts

@@ -28,9 +28,9 @@ function tool(
 
 function setup() {
   const registry = createAiToolRegistry();
-  const read = tool("incident.list", "read", "incident.incident.read");
-  const mutate = tool("automation.propose", "mutate", "automation.automation.manage");
-  const destroy = tool("incident.delete", "destructive", "incident.incident.manage");
+  const read = tool("incident_list", "read", "incident.incident.read");
+  const mutate = tool("automation_propose", "mutate", "automation.automation.manage");
+  const destroy = tool("incident_delete", "destructive", "incident.incident.manage");
   registry.register(read);
   registry.register(mutate);
   registry.register(destroy);
@@ -57,15 +57,15 @@ describe("agent loop tool gating (matrix #14)", () => {
   test("the loop only offers resolver-allowed tools", () => {
     const { resolver } = setup();
     const offered = offeredTools({ principal: limited, resolver }).map((t) => t.name);
-    expect(offered).toEqual(["incident.list"]);
-    expect(offered).not.toContain("automation.propose");
-    expect(offered).not.toContain("incident.delete");
+    expect(offered).toEqual(["incident_list"]);
+    expect(offered).not.toContain("automation_propose");
+    expect(offered).not.toContain("incident_delete");
   });
 
   test("a model-requested tool OUTSIDE the principal's set is refused server-side", () => {
     const { resolver, registry } = setup();
     const d = disposeAgentTool({
-      toolName: "automation.propose",
+      toolName: "automation_propose",
       principal: limited,
       resolver,
       getTool: (n) => registry.getTool(n),
@@ -87,7 +87,7 @@ describe("agent loop tool gating (matrix #14)", () => {
   test("a read tool auto-runs", () => {
     const { resolver, registry } = setup();
     const d = disposeAgentTool({
-      toolName: "incident.list",
+      toolName: "incident_list",
       principal: limited,
       resolver,
       getTool: (n) => registry.getTool(n),
@@ -98,7 +98,7 @@ describe("agent loop tool gating (matrix #14)", () => {
   test("a mutate tool requires a confirm card (never silently mutates)", () => {
     const { resolver, registry } = setup();
     const d = disposeAgentTool({
-      toolName: "automation.propose",
+      toolName: "automation_propose",
       principal: power,
       resolver,
       getTool: (n) => registry.getTool(n),
@@ -109,7 +109,7 @@ describe("agent loop tool gating (matrix #14)", () => {
   test("a destructive tool requires a confirm card", () => {
     const { resolver, registry } = setup();
     const d = disposeAgentTool({
-      toolName: "incident.delete",
+      toolName: "incident_delete",
       principal: power,
       resolver,
       getTool: (n) => registry.getTool(n),

package/src/chat/auto-apply.test.ts

@@ -129,7 +129,7 @@ function mutatingTool(): {
     created: input.value,
   }));
   const tool: RegisteredAiTool<{ value: string }, { created: string }> = {
-    name: "demo.mutate",
+    name: "demo_mutate",
     description: "demo mutating tool",
     effect: "mutate",
     input: ManageInput,
@@ -208,7 +208,7 @@ describe("AUTO-mode mutate auto-apply path", () => {
     // proposed -> applied, with the applier stamped. Not a weaker/parallel path.
     const applied = [...store.rows.values()].filter((r) => r.status === "applied");
     expect(applied).toHaveLength(1);
-    expect(applied[0]?.toolName).toBe("demo.mutate");
+    expect(applied[0]?.toolName).toBe("demo_mutate");
     expect(applied[0]?.effect).toBe("mutate");
     expect(applied[0]?.appliedById).toBe("u1");
     expect(applied[0]?.id).toBe(result.toolCallId);

package/src/generated/docs-index.ts

@@ -2244,7 +2244,7 @@ export const DOCS_INDEX: readonly DocsIndexEntry[] = [
       "Where this maps in the data model",
       "Where to go next"
     ],
-    "content": "The catalog is the backbone of Checkstack. Everything else (health checks, incidents, maintenances, notifications) attaches to a System. This page explains what a System is, how Groups organise them, and how Dependencies model real-world impact between Systems.\n\n## Systems\n\nA **System** is the smallest unit you monitor. It usually maps to one logical service in your stack: a database, an API, a worker, a third-party endpoint, a Minecraft server, a Jenkins controller, anything you want to know the health of.\n\nEvery system carries:\n\n- A **name** (required) and an optional **description**.\n- **Contacts**, which are either platform users or free-form mailboxes (email addresses). Contacts surface on the system detail page so anyone responding to an incident knows who owns it.\n- **Links**, which are free-form URL hotlinks (runbooks, Jira boards, dashboards) shown alongside the system.\n- Membership in zero or more **Groups**.\n\n> [!TIP]\n> Be ruthless about what counts as a System. One System per service is the right granularity. If you find yourself making a \"Foo - production\" and \"Foo - staging\" pair, that is fine; if you start making \"Foo - login flow\" and \"Foo - checkout flow\", you have probably blurred the line between a System and a health check.\n\n### What a System is not\n\nA System is not the same as a host, an environment, or a Kubernetes pod. It is the *logical* thing you care about. The health check is what decides \"this URL on this host is the way I observe it\".\n\n## Groups\n\nA **Group** is a flat label that bundles related systems together. Use groups to model:\n\n- **Teams.** \"Payments\", \"Identity\", \"Platform\".\n- **Tiers.** \"Tier 1\", \"Customer-facing\", \"Internal-only\".\n- **Domains.** \"Production\", \"Staging\" (though you can also model environments as separate systems).\n\nGroups are flat. Checkstack does not nest groups inside other groups today. A system can belong to multiple groups, so you can cross-cut by team and by tier at the same time.\n\n> [!NOTE]\n> Subscribing to notifications for a group automatically catches every system in that group. When the catalog adds or removes a system from the group, group subscribers update instantly without you re-subscribing per system.\n\nGroups are managed under **Catalog -> Groups** in the UI. You can drag systems between groups, rename groups in place, and delete them when they become empty. The management page carries the same toolbar as the browse view, so you can search and filter the systems and groups lists while you arrange them.\n\n> [!TIP]\n> Drag-and-drop assignment is keyboard-operable. Focus a system's drag handle, press Space or Enter to pick it up, move between groups with the arrow keys, and press Space or Enter again to drop it (Escape cancels). The assign button on each system row is an equivalent pointer-free alternative.\n\n## Dependencies\n\nA **Dependency** is a directional edge between two systems: \"Payment API depends on Payment DB\". When the upstream system is unhealthy, the downstream system's effective state reflects that impact.\n\nEach dependency carries an **impact type**:\n\n- **`informational`** records the link in the dependency map but does not change downstream state.\n- **`degraded`** marks the downstream system as degraded if the upstream is unhealthy.\n- **`critical`** marks the downstream system as unhealthy if the upstream is unhealthy.\n\n```\n            depends on\nPayment API  ---------->  Payment DB\n   (downstream)            (upstream)\n   impactType: critical\n```\n\nYou can attach optional **per-health-check rules** to a dependency. By default the impact applies whenever the upstream system is unhealthy on any of its checks; with rules you can scope the impact to specific checks only. For example, \"Payment API only goes degraded when Payment DB's TLS check fails, not when its replication-lag check fails.\"\n\nA dependency can also be marked **transitive** to let it cascade further down the chain.\n\n> [!IMPORTANT]\n> Dependencies do not auto-open incidents. They affect derived health state and which alerts get suppressed in cascades, nothing more. See [Incidents](/checkstack/user-guide/concepts/incidents/) for the human workflow.\n\nThe dependency map lives under **Catalog -> Dependencies**. Node positions are saved per user, so your layout follows you across devices.\n\n## Putting it together\n\nA small example of how the pieces compose for an e-commerce stack:\n\n```\nGroups:\n  - \"Payments team\": [Payment API, Payment DB, Stripe webhook]\n  - \"Tier 1\":        [Payment API, Checkout API, Storefront]\n\nSystems:\n  Storefront    ----(critical)---> Checkout API\n  Checkout API  ----(critical)---> Payment API\n  Payment API   ----(critical)---> Payment DB\n                ----(degraded)---> Stripe webhook\n```\n\nA failing Payment DB now drives the derived state for Payment API, Checkout API, and Storefront. A failing Stripe webhook only degrades Payment API. Anyone subscribed to the \"Payments team\" group sees the relevant notifications; anyone subscribed to \"Tier 1\" sees the customer-facing ones.\n\n## Browsing the catalog\n\nThe catalog home page is a read-only, group-first browse view. It is the landing page for everyone with catalog read access, managers and non-managers alike. It is built to stay legible at hundreds of systems across many groups.\n\nThe view organises systems into collapsible **group sections**. Each section header shows the group name and its member count. A synthetic **Ungrouped** section collects systems that belong to no group. Because a system can belong to several groups, it appears under each group it is a member of.\n\n### Inline health rollups\n\nWhen a health source such as the healthcheck plugin is installed, each group header also shows a **health rollup** pill summarising its members at a glance: \"All healthy\", \"N degraded\", or \"N unhealthy\" (the worst member status wins, with a count). Individual unhealthy or degraded systems still show their own badge on the row; healthy systems show none, so the absence of a badge means healthy or not yet measured.\n\nThe rollup drives the default open state: groups where every member is healthy start **collapsed** so your attention goes to the groups that need it, while any group with a degraded, unhealthy, or not-yet-measured member starts **expanded**. You can always toggle a section open or closed yourself, and that choice is captured in the URL. With no health source installed, headers show member counts only and every group starts expanded.\n\nThe **Health** filter then lets you narrow to a single state. Selecting `unknown` shows systems with no measured health (no checks wired yet); a system with no reported health is never silently counted as healthy.\n\nA toolbar above the sections lets you narrow what you see:\n\n- **Search** matches systems and groups by name and description, case-insensitively. A match inside a collapsed group auto-expands that group; groups with no match drop out while you are searching.\n- **Group**, **Health**, and **Tag** filters narrow the list further. Filters compose: applying more than one shows only the systems that satisfy all of them. (The Health filter activates once a health source such as the healthcheck plugin is installed.)\n- **Density** switches rows between Comfortable (descriptions shown inline) and Compact (single-line rows, descriptions on hover).\n\nEvery part of the view state lives in the URL, so a filtered, searched view is a shareable link. For example:\n\n```text\n/catalog/?q=checkout&group=payments&density=compact\n```\n\nopens the catalog pre-filtered to the Payments group, searching for \"checkout\", in compact density. Open or closed group sections are captured in the link too, so a teammate opening it sees exactly what you see.\n\nManagers see a **Manage catalog** link in the header that jumps to the management page below.\n\n## UI tour\n\n| Where to go | What you do there |\n|-------------|-------------------|\n| **Catalog** (home) | Browse, search, and filter every system, grouped by team or domain. Read-only. |\n| **Catalog -> Systems** | Create, edit, and delete systems. Set contacts and hotlinks. |\n| **Catalog -> Groups** | Create groups, drag systems in and out. |\n| **Catalog -> Dependencies** | Visual graph editor. Click a system to connect it to another. |\n| **System detail page** | See attached health checks, recent runs, contacts, links, and the systems that depend on it. |\n\n## Where this maps in the data model\n\nFor operators who want to peek behind the curtain:\n\n- Systems live in the `catalog-backend` plugin's schema, in the `systems` table.\n- Groups live in the `groups` table; the join is `systems_groups`.\n- Hotlinks and contacts live in `system_links` and `system_contacts`.\n- Dependencies are stored by `dependency-backend` in the `dependencies` table.\n\nYou should rarely need to query these directly, but the structure is open: every read happens through the platform's typed RPC and respects [Teams and access](/checkstack/user-guide/concepts/teams-and-access/).\n\n## Where to go next\n\n- **First system, first check.** Walk through [Set up your first health check](/checkstack/user-guide/guides/first-health-check/).\n- **Notifications.** Read [Notifications](/checkstack/user-guide/concepts/notifications/) to understand how group membership drives delivery.\n- **YAML-as-code.** The [GitOps](/checkstack/user-guide/concepts/gitops/) flow lets you express systems, groups, and dependencies as YAML in a Git repo.",
+    "content": "The catalog is the backbone of Checkstack. Everything else (health checks, incidents, maintenances, notifications) attaches to a System. This page explains what a System is, how Groups organise them, and how Dependencies model real-world impact between Systems.\n\n## Systems\n\nA **System** is the smallest unit you monitor. It usually maps to one logical service in your stack: a database, an API, a worker, a third-party endpoint, a Minecraft server, a Jenkins controller, anything you want to know the health of.\n\nEvery system carries:\n\n- A **name** (required) and an optional **description**.\n- **Contacts**, which are either platform users or free-form mailboxes (email addresses). Contacts surface on the system detail page so anyone responding to an incident knows who owns it.\n- **Links**, which are free-form URL hotlinks (runbooks, Jira boards, dashboards) shown alongside the system.\n- Membership in zero or more **Groups**.\n\n> [!TIP]\n> Be ruthless about what counts as a System. One System per service is the right granularity. If you find yourself making a \"Foo - production\" and \"Foo - staging\" pair, that is fine; if you start making \"Foo - login flow\" and \"Foo - checkout flow\", you have probably blurred the line between a System and a health check.\n\n### What a System is not\n\nA System is not the same as a host, an environment, or a Kubernetes pod. It is the *logical* thing you care about. The health check is what decides \"this URL on this host is the way I observe it\".\n\n## Groups\n\nA **Group** is a flat label that bundles related systems together. Use groups to model:\n\n- **Teams.** \"Payments\", \"Identity\", \"Platform\".\n- **Tiers.** \"Tier 1\", \"Customer-facing\", \"Internal-only\".\n- **Domains.** \"Production\", \"Staging\" (though you can also model environments as separate systems).\n\nGroups are flat. Checkstack does not nest groups inside other groups today. A system can belong to multiple groups, so you can cross-cut by team and by tier at the same time.\n\n> [!NOTE]\n> Subscribing to notifications for a group automatically catches every system in that group. When the catalog adds or removes a system from the group, group subscribers update instantly without you re-subscribing per system.\n\nGroups are managed under **Catalog -> Groups** in the UI. You can drag systems between groups, rename groups in place, and delete them when they become empty. The management page carries the same toolbar as the browse view, so you can search and filter the systems and groups lists while you arrange them.\n\n> [!TIP]\n> Drag-and-drop assignment is keyboard-operable. Focus a system's drag handle, press Space or Enter to pick it up, move between groups with the arrow keys, and press Space or Enter again to drop it (Escape cancels). The assign button on each system row is an equivalent pointer-free alternative.\n\n## Dependencies\n\nA **Dependency** is a directional edge between two systems: \"Payment API depends on Payment DB\". When the upstream system is unhealthy, the downstream system's effective state reflects that impact.\n\nEach dependency carries an **impact type**:\n\n- **`informational`** records the link in the dependency map but does not change downstream state.\n- **`degraded`** marks the downstream system as degraded if the upstream is unhealthy.\n- **`critical`** marks the downstream system as unhealthy if the upstream is unhealthy.\n\n```\n            depends on\nPayment API  ---------->  Payment DB\n   (downstream)            (upstream)\n   impactType: critical\n```\n\nYou can attach optional **per-health-check rules** to a dependency. By default the impact applies whenever the upstream system is unhealthy on any of its checks; with rules you can scope the impact to specific checks only. For example, \"Payment API only goes degraded when Payment DB's TLS check fails, not when its replication-lag check fails.\"\n\nA dependency can also be marked **transitive** to let it cascade further down the chain.\n\n> [!IMPORTANT]\n> Dependencies do not auto-open incidents. They affect derived health state and which alerts get suppressed in cascades, nothing more. See [Incidents](/checkstack/user-guide/concepts/incidents/) for the human workflow.\n\nThe dependency map lives under **Workspace -> Dependency Map**. Node positions are saved per user, so your layout follows you across devices.\n\n> [!NOTE]\n> The full dependency map is gated by its own access rule and is shown to signed-in users by default, not to anonymous visitors. Per-system dependency *warnings* (the badges and dashboard signals) stay public, so anonymous visitors still see when a system is affected by an upstream problem - they just do not get the full topology view. Admins can grant the map to the anonymous role under **Teams & access** to make it public.\n\n## Putting it together\n\nA small example of how the pieces compose for an e-commerce stack:\n\n```\nGroups:\n  - \"Payments team\": [Payment API, Payment DB, Stripe webhook]\n  - \"Tier 1\":        [Payment API, Checkout API, Storefront]\n\nSystems:\n  Storefront    ----(critical)---> Checkout API\n  Checkout API  ----(critical)---> Payment API\n  Payment API   ----(critical)---> Payment DB\n                ----(degraded)---> Stripe webhook\n```\n\nA failing Payment DB now drives the derived state for Payment API, Checkout API, and Storefront. A failing Stripe webhook only degrades Payment API. Anyone subscribed to the \"Payments team\" group sees the relevant notifications; anyone subscribed to \"Tier 1\" sees the customer-facing ones.\n\n## Browsing the catalog\n\nThe catalog home page is a read-only, group-first browse view. It is the landing page for everyone with catalog read access, managers and non-managers alike. It is built to stay legible at hundreds of systems across many groups.\n\nThe view organises systems into collapsible **group sections**. Each section header shows the group name and its member count. A synthetic **Ungrouped** section collects systems that belong to no group. Because a system can belong to several groups, it appears under each group it is a member of.\n\n### Inline health rollups\n\nWhen a health source such as the healthcheck plugin is installed, each group header also shows a **health rollup** pill summarising its members at a glance: \"All healthy\", \"N degraded\", or \"N unhealthy\" (the worst member status wins, with a count). Individual unhealthy or degraded systems still show their own badge on the row; healthy systems show none, so the absence of a badge means healthy or not yet measured.\n\nThe rollup drives the default open state: groups where every member is healthy start **collapsed** so your attention goes to the groups that need it, while any group with a degraded, unhealthy, or not-yet-measured member starts **expanded**. You can always toggle a section open or closed yourself, and that choice is captured in the URL. With no health source installed, headers show member counts only and every group starts expanded.\n\nThe **Health** filter then lets you narrow to a single state. Selecting `unknown` shows systems with no measured health (no checks wired yet); a system with no reported health is never silently counted as healthy.\n\nA toolbar above the sections lets you narrow what you see:\n\n- **Search** matches systems and groups by name and description, case-insensitively. A match inside a collapsed group auto-expands that group; groups with no match drop out while you are searching.\n- **Group**, **Health**, and **Tag** filters narrow the list further. Filters compose: applying more than one shows only the systems that satisfy all of them. (The Health filter activates once a health source such as the healthcheck plugin is installed.)\n- **Density** switches rows between Comfortable (descriptions shown inline) and Compact (single-line rows, descriptions on hover).\n\nEvery part of the view state lives in the URL, so a filtered, searched view is a shareable link. For example:\n\n```text\n/catalog/?q=checkout&group=payments&density=compact\n```\n\nopens the catalog pre-filtered to the Payments group, searching for \"checkout\", in compact density. Open or closed group sections are captured in the link too, so a teammate opening it sees exactly what you see.\n\nManagers see a **Manage catalog** link in the header that jumps to the management page below.\n\n## UI tour\n\n| Where to go | What you do there |\n|-------------|-------------------|\n| **Catalog** (home) | Browse, search, and filter every system, grouped by team or domain. Read-only. |\n| **Catalog -> Systems** | Create, edit, and delete systems. Set contacts and hotlinks. |\n| **Catalog -> Groups** | Create groups, drag systems in and out. |\n| **Catalog -> Dependencies** | Visual graph editor. Click a system to connect it to another. |\n| **System detail page** | See attached health checks, recent runs, contacts, links, and the systems that depend on it. |\n\n## Where this maps in the data model\n\nFor operators who want to peek behind the curtain:\n\n- Systems live in the `catalog-backend` plugin's schema, in the `systems` table.\n- Groups live in the `groups` table; the join is `systems_groups`.\n- Hotlinks and contacts live in `system_links` and `system_contacts`.\n- Dependencies are stored by `dependency-backend` in the `dependencies` table.\n\nYou should rarely need to query these directly, but the structure is open: every read happens through the platform's typed RPC and respects [Teams and access](/checkstack/user-guide/concepts/teams-and-access/).\n\n## Where to go next\n\n- **First system, first check.** Walk through [Set up your first health check](/checkstack/user-guide/guides/first-health-check/).\n- **Notifications.** Read [Notifications](/checkstack/user-guide/concepts/notifications/) to understand how group membership drives delivery.\n- **YAML-as-code.** The [GitOps](/checkstack/user-guide/concepts/gitops/) flow lets you express systems, groups, and dependencies as YAML in a Git repo.",
     "truncated": false
   },
   {
@@ -3019,4 +3019,4 @@ export const DOCS_INDEX: readonly DocsIndexEntry[] = [
 ];
 
 /** A content hash of the source tree, so a CI check can detect drift. */
-export const DOCS_INDEX_HASH = "a37429cd2e6f71d57ce52a8084d890e51b47d6c5e662a6ab576e4a05875528d8";
+export const DOCS_INDEX_HASH = "eb86869a0791795f24c6cad94a2025f66e1314c631a2a320bf5658428d8d157d";

package/src/hardening/handler-authz.test.ts

@@ -154,7 +154,7 @@ describe("HARDENING: a misbehaving model cannot escape the resolver gate", () =>
   test("isAllowed refuses a tool whose rule the principal lacks", () => {
     const registry = createAiToolRegistry();
     let ran = false;
-    const adminTool = readTool("ai.secrets", "ai.tools.manage", () => {
+    const adminTool = readTool("ai_secrets", "ai.tools.manage", () => {
       ran = true;
     });
     registry.register(adminTool);
@@ -168,7 +168,7 @@ describe("HARDENING: a misbehaving model cannot escape the resolver gate", () =>
 
   test("a service principal (no access rules) is refused every tool", () => {
     const registry = createAiToolRegistry();
-    const tool = readTool("incident.list", "incident.incident.read", () => {});
+    const tool = readTool("incident_list", "incident.incident.read", () => {});
     registry.register(tool);
     const resolver = createAiToolResolver({ registry });
     const service: AuthUser = { type: "service", pluginId: "svc" };
@@ -181,7 +181,7 @@ describe("HARDENING: propose refuses a model-picked out-of-scope tool BEFORE dry
     const registry = createAiToolRegistry();
     let dryRan = false;
     let executed = false;
-    const tool = mutateTool("billing.refund", "billing.billing.manage", {
+    const tool = mutateTool("billing_refund", "billing.billing.manage", {
       onDryRun: () => {
         dryRan = true;
       },
@@ -200,7 +200,7 @@ describe("HARDENING: propose refuses a model-picked out-of-scope tool BEFORE dry
     await expect(
       service.propose({
         principal: limited, // lacks billing.billing.manage
-        toolName: "billing.refund",
+        toolName: "billing_refund",
         input: { amount: 100 },
         transport: "chat",
         rpcClient,
@@ -217,7 +217,7 @@ describe("HARDENING: bad model-supplied args are rejected (no execution on garba
   test("propose rejects args that fail the tool's own zod schema", async () => {
     const registry = createAiToolRegistry();
     let dryRan = false;
-    const tool = mutateTool("incident.escalate", "incident.incident.read", {
+    const tool = mutateTool("incident_escalate", "incident.incident.read", {
       onDryRun: () => {
         dryRan = true;
       },
@@ -237,7 +237,7 @@ describe("HARDENING: bad model-supplied args are rejected (no execution on garba
     await expect(
       service.propose({
         principal: limited,
-        toolName: "incident.escalate",
+        toolName: "incident_escalate",
         input: { amount: -5 },
         transport: "chat",
         rpcClient,
@@ -253,9 +253,9 @@ describe("HARDENING: scope-narrowing can never WIDEN the surfaced toolset", () =
   // only ever shrink the visible tools — never add one the principal lacks.
   test("narrowing the principal's rules monotonically shrinks the visible tools", () => {
     const registry = createAiToolRegistry();
-    registry.register(readTool("incident.list", "incident.incident.read", () => {}));
-    registry.register(readTool("hc.status", "healthcheck.config.read", () => {}));
-    registry.register(readTool("ai.secrets", "ai.tools.manage", () => {}));
+    registry.register(readTool("incident_list", "incident.incident.read", () => {}));
+    registry.register(readTool("hc_status", "healthcheck.config.read", () => {}));
+    registry.register(readTool("ai_secrets", "ai.tools.manage", () => {}));
     const resolver = createAiToolResolver({ registry });
 
     const wide: AuthUser = {
@@ -274,8 +274,8 @@ describe("HARDENING: scope-narrowing can never WIDEN the surfaced toolset", () =
 
     // Narrowed is a strict subset — never a superset.
     for (const name of narrowNames) expect(wideNames.has(name)).toBe(true);
-    expect(narrowNames.has("hc.status")).toBe(false);
-    expect(narrowNames.has("ai.secrets")).toBe(false);
+    expect(narrowNames.has("hc_status")).toBe(false);
+    expect(narrowNames.has("ai_secrets")).toBe(false);
     // And the narrowing never invented a tool outside the wide set.
     expect([...narrowNames].every((n) => wideNames.has(n))).toBe(true);
   });

package/src/mcp/server.test.ts

@@ -47,12 +47,12 @@ function buildHandler({
   }) => Promise<void>;
 }) {
   const registry = createAiToolRegistry();
-  const incidentTool = readTool("incident.list", "incident.incident.read");
-  const adminTool = readTool("ai.secrets", "ai.tools.manage");
+  const incidentTool = readTool("incident_list", "incident.incident.read");
+  const adminTool = readTool("ai_secrets", "ai.tools.manage");
   // A mutating tool the limited principal IS allowed for (same access rule as
   // incident.list). The ONLY thing that may refuse a bare tools/call for it is
   // the structural effect-gate, not the resolver.
-  const mutating = mutateTool("incident.close", "incident.incident.read");
+  const mutating = mutateTool("incident_close", "incident.incident.read");
   registry.register(incidentTool);
   registry.register(adminTool);
   registry.register(mutating);
@@ -121,8 +121,8 @@ describe("MCP server (read-only Streamable-HTTP)", () => {
     );
     const json = await res.json();
     const names = json.result.tools.map((t: { name: string }) => t.name);
-    expect(names).toEqual(["incident.list"]);
-    expect(names).not.toContain("ai.secrets");
+    expect(names).toEqual(["incident_list"]);
+    expect(names).not.toContain("ai_secrets");
   });
 
   test("tools/list returns 401 for an unauthenticated caller", async () => {
@@ -150,7 +150,7 @@ describe("MCP server (read-only Streamable-HTTP)", () => {
         jsonrpc: "2.0",
         id: 4,
         method: "tools/call",
-        params: { name: "ai.secrets", arguments: {} },
+        params: { name: "ai_secrets", arguments: {} },
       }),
     );
     expect(res.status).toBe(403);
@@ -175,7 +175,7 @@ describe("MCP server (read-only Streamable-HTTP)", () => {
           jsonrpc: "2.0",
           id: 5,
           method: "tools/call",
-          params: { name: "incident.list", arguments: { status: "open" } },
+          params: { name: "incident_list", arguments: { status: "open" } },
         },
         "tok-123",
       ),
@@ -205,7 +205,7 @@ describe("MCP server (read-only Streamable-HTTP)", () => {
         jsonrpc: "2.0",
         id: 7,
         method: "tools/call",
-        params: { name: "incident.close", arguments: {} },
+        params: { name: "incident_close", arguments: {} },
       }),
     );
     expect(res.status).toBe(403);
@@ -221,8 +221,8 @@ describe("MCP server (read-only Streamable-HTTP)", () => {
     );
     const json = await res.json();
     const names = json.result.tools.map((t: { name: string }) => t.name);
-    expect(names).toContain("incident.list");
-    expect(names).not.toContain("incident.close");
+    expect(names).toContain("incident_list");
+    expect(names).not.toContain("incident_close");
   });
 
   // §14.5: per-principal tool budget enforced on tools/call (shared-Postgres).
@@ -241,7 +241,7 @@ describe("MCP server (read-only Streamable-HTTP)", () => {
         jsonrpc: "2.0",
         id: 9,
         method: "tools/call",
-        params: { name: "incident.list", arguments: {} },
+        params: { name: "incident_list", arguments: {} },
       }),
     );
     expect(res.status).toBe(429);
@@ -264,12 +264,12 @@ describe("MCP server (read-only Streamable-HTTP)", () => {
         jsonrpc: "2.0",
         id: 10,
         method: "tools/call",
-        params: { name: "incident.list", arguments: { status: "open" } },
+        params: { name: "incident_list", arguments: { status: "open" } },
       }),
     );
     expect(res.status).toBe(200);
     expect(recorded).toHaveLength(1);
-    expect(recorded[0]?.toolName).toBe("incident.list");
+    expect(recorded[0]?.toolName).toBe("incident_list");
     // The args hash is a SHA-256 hex digest, never the raw args.
     expect(recorded[0]?.argsHash).toMatch(/^[0-9a-f]{64}$/);
   });

package/src/propose-apply/service.test.ts

@@ -135,7 +135,7 @@ function mutatingTool(
 ): RegisteredAiTool<{ value: string }, { created: string }> {
   let executed = 0;
   const tool: RegisteredAiTool<{ value: string }, { created: string }> = {
-    name: "demo.mutate",
+    name: "demo_mutate",
     description: "demo mutating tool",
     effect: "mutate",
     input: ManageInput,
@@ -200,7 +200,7 @@ describe("propose/apply lifecycle (matrix #11)", () => {
 
     const proposal = await service.propose({
       principal: allowed,
-      toolName: "demo.mutate",
+      toolName: "demo_mutate",
       input: { value: "alpha" },
       transport: "chat",
     });
@@ -222,7 +222,7 @@ describe("propose/apply lifecycle (matrix #11)", () => {
 
     const proposal = await service.propose({
       principal: allowed,
-      toolName: "demo.mutate",
+      toolName: "demo_mutate",
       input: { value: "beta" },
       transport: "chat",
     });
@@ -239,7 +239,7 @@ describe("propose/apply lifecycle (matrix #11)", () => {
     const { service } = setup(tool);
     const proposal = await service.propose({
       principal: allowed,
-      toolName: "demo.mutate",
+      toolName: "demo_mutate",
       input: { value: "gamma" },
       transport: "chat",
     });
@@ -265,7 +265,7 @@ describe("propose/apply authorization (matrix #11 / decision 5)", () => {
     await expect(
       service.propose({
         principal: notAllowed,
-        toolName: "demo.mutate",
+        toolName: "demo_mutate",
         input: { value: "x" },
         transport: "chat",
       }),
@@ -277,7 +277,7 @@ describe("propose/apply authorization (matrix #11 / decision 5)", () => {
     const { service } = setup(tool);
     const proposal = await service.propose({
       principal: allowed,
-      toolName: "demo.mutate",
+      toolName: "demo_mutate",
       input: { value: "x" },
       transport: "chat",
     });
@@ -294,7 +294,7 @@ describe("propose/apply authorization (matrix #11 / decision 5)", () => {
     await expect(
       service.propose({
         principal: allowed,
-        toolName: "demo.mutate",
+        toolName: "demo_mutate",
         input: { value: "x" },
         transport: "chat",
       }),
@@ -306,7 +306,7 @@ describe("propose/apply authorization (matrix #11 / decision 5)", () => {
     await expect(
       service.propose({
         principal: { type: "service", pluginId: "x" },
-        toolName: "demo.mutate",
+        toolName: "demo_mutate",
         input: { value: "x" },
         transport: "chat",
       }),
@@ -320,7 +320,7 @@ describe("propose does NOT mutate (matrix #12)", () => {
     const { service } = setup(tool);
     await service.propose({
       principal: allowed,
-      toolName: "demo.mutate",
+      toolName: "demo_mutate",
       input: { value: "x" },
       transport: "chat",
     });
@@ -334,7 +334,7 @@ describe("audit rows (matrix #13)", () => {
     const { service, store } = setup(tool);
     const proposal = await service.propose({
       principal: allowed,
-      toolName: "demo.mutate",
+      toolName: "demo_mutate",
       input: { value: "x" },
       transport: "chat",
     });
@@ -358,7 +358,7 @@ describe("audit rows (matrix #13)", () => {
     // Proposed by u1.
     const proposal = await service.propose({
       principal: allowed,
-      toolName: "demo.mutate",
+      toolName: "demo_mutate",
       input: { value: "x" },
       transport: "chat",
     });
@@ -386,7 +386,7 @@ describe("audit rows (matrix #13)", () => {
     const { service, store } = setup(tool);
     const proposal = await service.propose({
       principal: allowed,
-      toolName: "demo.mutate",
+      toolName: "demo_mutate",
       input: { value: "x" },
       transport: "chat",
     });
@@ -411,7 +411,7 @@ describe("audit rows (matrix #13)", () => {
     const { service, store } = setup(tool, () => current);
     const proposal = await service.propose({
       principal: allowed,
-      toolName: "demo.mutate",
+      toolName: "demo_mutate",
       input: { value: "x" },
       transport: "chat",
     });

package/src/registry-wiring.test.ts

@@ -30,7 +30,7 @@ function handAuthoredTool(): RegisteredAiTool {
 }
 
 describe("createRegistryExtensionPoints (end-to-end registration)", () => {
-  test("registerTool qualifies an unqualified name with the plugin id", () => {
+  test("registerTool qualifies an unqualified name, registered provider-safe", () => {
     const registry = createAiToolRegistry();
     const { toolExtensionPoint } = createRegistryExtensionPoints({ registry });
 
@@ -39,11 +39,15 @@ describe("createRegistryExtensionPoints (end-to-end registration)", () => {
       definePluginMetadata({ pluginId: "automation" }),
     );
 
-    expect(registry.hasTool("automation.propose")).toBe(true);
-    expect(registry.getTool("automation.propose")?.effect).toBe("mutate");
+    // Qualified to `automation.propose`, then normalized to the provider-safe
+    // name set (the "." the provider rejects becomes "_").
+    expect(registry.hasTool("automation_propose")).toBe(true);
+    expect(registry.getTool("automation_propose")?.effect).toBe("mutate");
+    // The dotted form is NOT a key (the provider would never send it).
+    expect(registry.hasTool("automation.propose")).toBe(false);
   });
 
-  test("registerTool leaves an already-qualified name unchanged", () => {
+  test("registerTool leaves an already-qualified name unchanged (modulo sanitization)", () => {
     const registry = createAiToolRegistry();
     const { toolExtensionPoint } = createRegistryExtensionPoints({ registry });
 
@@ -52,8 +56,10 @@ describe("createRegistryExtensionPoints (end-to-end registration)", () => {
       definePluginMetadata({ pluginId: "different" }),
     );
 
-    expect(registry.hasTool("automation.propose")).toBe(true);
-    expect(registry.hasTool("different.automation.propose")).toBe(false);
+    // Already qualified, so it is not re-prefixed with "different"; only "."
+    // is sanitized to "_".
+    expect(registry.hasTool("automation_propose")).toBe(true);
+    expect(registry.hasTool("different_automation_propose")).toBe(false);
   });
 
   test("expose builds and registers a projected tool from a contract procedure", () => {
@@ -72,7 +78,8 @@ describe("createRegistryExtensionPoints (end-to-end registration)", () => {
       execute: () => Promise.resolve({}),
     });
 
-    const tool = registry.getTool("incident.list");
+    // The authored name "incident.list" is normalized to the provider-safe key.
+    const tool = registry.getTool("incident_list");
     expect(tool).toBeDefined();
     // Access rules read verbatim from the source procedure, qualified.
     expect(tool?.requiredAccessRules).toEqual(["incident.incident.read"]);
@@ -98,9 +105,10 @@ describe("createRegistryExtensionPoints (end-to-end registration)", () => {
       execute: () => Promise.resolve({}),
     });
 
+    // Registry keys/names are the provider-safe form of each authored name.
     expect(registry.getTools().map((t) => t.name).sort()).toEqual([
-      "automation.propose",
-      "incident.list",
+      "automation_propose",
+      "incident_list",
     ]);
   });
 

package/src/registry-wiring.ts

@@ -4,6 +4,7 @@ import type {
   AiToolProjectionExtensionPoint,
 } from "./extension-points";
 import { buildProjectedTool } from "./projection";
+import { toProviderToolName } from "./tool-name";
 import type { AiToolRegistry } from "./tool-registry";
 
 /**
@@ -57,7 +58,10 @@ export function createRegistryExtensionPoints({
       const tool = buildProjectedTool(input);
       registry.register(tool);
       exposedProjections.push({
-        toolName: tool.name,
+        // Match the registry's canonical (provider-safe) key so the chat
+        // read-loop and MCP transport resolve this route by the same name the
+        // model is given and echoes back.
+        toolName: toProviderToolName(tool.name),
         pluginId: input.sourcePluginMetadata.pluginId,
         procedureKey: input.procedureKey,
       });

package/src/resolver.test.ts

@@ -26,24 +26,24 @@ describe("createAiToolResolver.resolveTools", () => {
   test("a principal lacking automation.manage never sees automation.propose", () => {
     const registry = createAiToolRegistry();
     registry.register(
-      tool("automation.propose", ["automation.automation.manage"]),
+      tool("automation_propose", ["automation.automation.manage"]),
     );
-    registry.register(tool("incident.list", ["incident.incident.read"]));
+    registry.register(tool("incident_list", ["incident.incident.read"]));
     const resolver = createAiToolResolver({ registry });
 
     const principal = userWith(["incident.incident.read"]);
     const names = resolver.resolveTools(principal).map((t) => t.name);
 
-    expect(names).toEqual(["incident.list"]);
-    expect(names).not.toContain("automation.propose");
+    expect(names).toEqual(["incident_list"]);
+    expect(names).not.toContain("automation_propose");
   });
 
   test("an admin (accessRules ['*']) sees all tools", () => {
     const registry = createAiToolRegistry();
     registry.register(
-      tool("automation.propose", ["automation.automation.manage"]),
+      tool("automation_propose", ["automation.automation.manage"]),
     );
-    registry.register(tool("incident.list", ["incident.incident.read"]));
+    registry.register(tool("incident_list", ["incident.incident.read"]));
     const resolver = createAiToolResolver({ registry });
 
     const names = resolver
@@ -51,12 +51,12 @@ describe("createAiToolResolver.resolveTools", () => {
       .map((t) => t.name)
       .sort();
 
-    expect(names).toEqual(["automation.propose", "incident.list"]);
+    expect(names).toEqual(["automation_propose", "incident_list"]);
   });
 
   test("a service principal (no access rules) sees no tools", () => {
     const registry = createAiToolRegistry();
-    registry.register(tool("incident.list", ["incident.incident.read"]));
+    registry.register(tool("incident_list", ["incident.incident.read"]));
     const resolver = createAiToolResolver({ registry });
 
     const service: AuthUser = { type: "service", pluginId: "automation" };

package/src/tool-name.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+import { PROVIDER_TOOL_NAME_PATTERN, toProviderToolName } from "./tool-name";
+
+describe("toProviderToolName", () => {
+  test("maps the '.' namespace separator to '_'", () => {
+    expect(toProviderToolName("incident.list")).toBe("incident_list");
+    expect(toProviderToolName("catalog.listSystems")).toBe(
+      "catalog_listSystems",
+    );
+    expect(toProviderToolName("dependency.list")).toBe("dependency_list");
+  });
+
+  test("maps every '.' in a multi-dot name", () => {
+    expect(toProviderToolName("a.b.c")).toBe("a_b_c");
+  });
+
+  test("leaves an already provider-safe name unchanged", () => {
+    expect(toProviderToolName("incident_list")).toBe("incident_list");
+    expect(toProviderToolName("get-status")).toBe("get-status");
+    expect(toProviderToolName("Tool_123")).toBe("Tool_123");
+  });
+
+  test("the result always matches the provider pattern", () => {
+    for (const name of ["incident.list", "a.b.c", "get-status", "x"]) {
+      expect(PROVIDER_TOOL_NAME_PATTERN.test(toProviderToolName(name))).toBe(
+        true,
+      );
+    }
+  });
+
+  test("throws on an illegal character rather than silently rewriting it", () => {
+    expect(() => toProviderToolName("foo$bar")).toThrow(/Invalid AI tool name/);
+    expect(() => toProviderToolName("with space")).toThrow(
+      /Invalid AI tool name/,
+    );
+    expect(() => toProviderToolName("emoji😀")).toThrow(/Invalid AI tool name/);
+  });
+
+  test("throws on an empty name", () => {
+    expect(() => toProviderToolName("")).toThrow(/Invalid AI tool name/);
+  });
+});

package/src/tool-name.ts

@@ -0,0 +1,37 @@
+/**
+ * Provider tool-name constraint.
+ *
+ * LLM providers (and the MCP spec) require tool names to match
+ * `^[a-zA-Z0-9_-]+$`.
+ */
+export const PROVIDER_TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
+
+/**
+ * Convert a canonical tool name to its provider-safe form.
+ *
+ * Tool names are qualified as `<plugin>.<tool>` - the "." is the namespace
+ * separator of the naming convention, which the provider rejects. It is mapped
+ * deterministically to "_" (so `incident.list` -> `incident_list`).
+ *
+ * Any OTHER disallowed character is an authoring mistake in the tool
+ * definition, not stray input, so it is NOT silently rewritten: this throws so
+ * the bad name surfaces at registration (startup) instead of being masked.
+ *
+ * The mapping is applied at the single registration chokepoint (the tool
+ * registry) and the projection-routing table, so the registry key, the name
+ * sent to the model / MCP client, and the name the model echoes back in a tool
+ * call are all identical - the round-trip (name-out === name-in) holds without
+ * any reverse lookup.
+ */
+export function toProviderToolName(name: string): string {
+  const normalized = name.replaceAll(".", "_");
+  if (!PROVIDER_TOOL_NAME_PATTERN.test(normalized)) {
+    throw new Error(
+      `Invalid AI tool name "${name}": after normalizing the "." separator to ` +
+        `"_" it must match ${String(PROVIDER_TOOL_NAME_PATTERN)} (letters, ` +
+        `digits, "_" and "-" only). Rename the tool to use only those ` +
+        `characters, with "." reserved for the <plugin>.<tool> separator.`,
+    );
+  }
+  return normalized;
+}

package/src/tool-registry.ts

@@ -1,5 +1,6 @@
 import type { AuthUser, RpcClient } from "@checkstack/backend-api";
 import type { AiTool } from "@checkstack/ai-common";
+import { toProviderToolName } from "./tool-name";
 
 /**
  * A tool whose executors run with a Checkstack {@link AuthUser} principal and
@@ -21,7 +22,12 @@ export type RegisteredAiTool<TInput = unknown, TOutput = unknown> = AiTool<
  * registry, so no capability is implemented twice.
  *
  * Tool names are already fully qualified (`<plugin>.<tool>`) by the extension
- * points before they reach `register`.
+ * points before they reach `register`. `register` then maps the name to its
+ * provider-safe form (see {@link toProviderToolName}) and uses that as the
+ * canonical key, so every consumer (serializer, chat SDK tools, MCP
+ * `tools/list`, and the tool-call resolution path) sees and resolves the same
+ * provider-safe name. A name with an illegal character (beyond the "."
+ * separator) is rejected here rather than rewritten.
  */
 export interface AiToolRegistry {
   register(tool: RegisteredAiTool): void;
@@ -35,12 +41,16 @@ export function createAiToolRegistry(): AiToolRegistry {
 
   return {
     register(tool: RegisteredAiTool): void {
-      if (tools.has(tool.name)) {
+      // Map to the provider-safe name (e.g. `incident.list` -> `incident_list`)
+      // and key the registry on it, so the name sent to the model and the name
+      // it echoes back both match this entry. Throws on an illegal name.
+      const name = toProviderToolName(tool.name);
+      if (tools.has(name)) {
         throw new Error(
-          `AI tool ${tool.name} already registered — likely a duplicate registration.`,
+          `AI tool ${name} already registered — likely a duplicate registration.`,
         );
       }
-      tools.set(tool.name, tool);
+      tools.set(name, name === tool.name ? tool : { ...tool, name });
     },
 
     getTools(): RegisteredAiTool[] {

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

@@ -120,7 +120,7 @@ describe("docs tools registration + resolution", () => {
       .resolveTools(userWith(["ai.chat.read"]))
       .map((t) => t.name)
       .sort();
-    expect(names).toEqual(["ai.getDoc", "ai.searchDocs"]);
+    expect(names).toEqual(["ai_getDoc", "ai_searchDocs"]);
   });
 
   test("a principal without ai.chat.read sees neither docs tool", () => {

package/src/tools/tool-set.e2e.test.ts

@@ -38,7 +38,7 @@ describe("ai-backend's own platform tool set", () => {
   test("docs + probe tools are registered and qualified", () => {
     const registry = buildOwnRegistry();
     const names = registry.getTools().map((t) => t.name);
-    for (const expected of ["ai.searchDocs", "ai.getDoc", "ai.probeUrl"]) {
+    for (const expected of ["ai_searchDocs", "ai_getDoc", "ai_probeUrl"]) {
       expect(names).toContain(expected);
     }
   });