@checkstack/ai-backend 0.1.6 → 0.3.0

package/src/registry-wiring.ts

@@ -2,8 +2,11 @@ import type { PluginMetadata } from "@checkstack/common";
 import type {
   AiToolExtensionPoint,
   AiToolProjectionExtensionPoint,
+  SystemSignalsContributor,
+  SystemSignalsExtensionPoint,
 } from "./extension-points";
 import { buildProjectedTool } from "./projection";
+import { toProviderToolName } from "./tool-name";
 import type { AiToolRegistry } from "./tool-registry";
 
 /**
@@ -57,7 +60,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,
       });
@@ -66,3 +72,25 @@ export function createRegistryExtensionPoints({
 
   return { toolExtensionPoint, projectionExtensionPoint, exposedProjections };
 }
+
+/**
+ * Build the {@link SystemSignalsExtensionPoint} implementation that accumulates
+ * every registered contributor into a shared array, mirroring how {@link
+ * createRegistryExtensionPoints} accumulates `exposedProjections`. The returned
+ * `contributors` array is the SAME reference the `system.issues` tool reads at
+ * execute time, so contributors registered from any plugin's `init` are visible
+ * to the tool by the time it runs.
+ */
+export function createSystemSignalsExtensionPoint(): {
+  systemSignalsExtensionPoint: SystemSignalsExtensionPoint;
+  /** Every contributor registered via the point (populated lazily at init). */
+  contributors: SystemSignalsContributor[];
+} {
+  const contributors: SystemSignalsContributor[] = [];
+  const systemSignalsExtensionPoint: SystemSignalsExtensionPoint = {
+    contribute: (contributor) => {
+      contributors.push(contributor);
+    },
+  };
+  return { systemSignalsExtensionPoint, contributors };
+}

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/system-signals-contributor.test.ts

@@ -0,0 +1,162 @@
+import { describe, test, expect, mock } from "bun:test";
+import { access } from "@checkstack/common";
+import type { AuthUser } from "@checkstack/backend-api";
+import type { SystemSignal, SystemSignalsMap } from "@checkstack/catalog-common";
+import {
+  createGatedSystemSignalsContributor,
+  type SystemAccessResolver,
+} from "./system-signals-contributor";
+
+// A read rule for a fictional "demo" plugin: id "thing.read", qualified
+// "demo.thing.read", qualified resource type "demo.thing".
+const rule = access("thing", "read", "View things", { pluginId: "demo" });
+
+const signal = (source: string): SystemSignal => ({
+  source,
+  tone: "error",
+  label: "Problem",
+});
+
+const globalSignals: SystemSignalsMap = {
+  sysA: [signal("demo")],
+  sysB: [signal("demo")],
+};
+
+/** A resolver that returns a fixed accessible subset and records its args. */
+function stubResolver(accessible: string[]): {
+  resolver: SystemAccessResolver;
+  calls: Array<Parameters<SystemAccessResolver["accessibleSystemIds"]>[0]>;
+} {
+  const calls: Array<
+    Parameters<SystemAccessResolver["accessibleSystemIds"]>[0]
+  > = [];
+  return {
+    calls,
+    resolver: {
+      accessibleSystemIds: async (args) => {
+        calls.push(args);
+        return accessible.filter((id) => args.systemIds.includes(id));
+      },
+    },
+  };
+}
+
+const userWith = (accessRules: string[]): AuthUser => ({
+  type: "user",
+  id: "u1",
+  accessRules,
+});
+
+describe("createGatedSystemSignalsContributor", () => {
+  test("global-rule principal sees every system; resolver is not consulted", async () => {
+    const read = mock(async () => globalSignals);
+    const { resolver, calls } = stubResolver([]);
+    const contributor = createGatedSystemSignalsContributor({
+      sourceId: "demo",
+      accessRule: rule,
+      resolver,
+      readSignals: read,
+    });
+
+    const result = await contributor.read({
+      principal: userWith(["demo.thing.read"]),
+    });
+
+    expect(result.accessible).toBe(true);
+    expect(Object.keys(result.signals).sort()).toEqual(["sysA", "sysB"]);
+    expect(read).toHaveBeenCalledTimes(1);
+    expect(calls).toHaveLength(0); // global access skips the team resolver
+  });
+
+  test("wildcard grant is treated as global", async () => {
+    const contributor = createGatedSystemSignalsContributor({
+      sourceId: "demo",
+      accessRule: rule,
+      resolver: stubResolver([]).resolver,
+      readSignals: async () => globalSignals,
+    });
+    const result = await contributor.read({ principal: userWith(["*"]) });
+    expect(Object.keys(result.signals).sort()).toEqual(["sysA", "sysB"]);
+  });
+
+  test("service principals are trusted (treated as global)", async () => {
+    const contributor = createGatedSystemSignalsContributor({
+      sourceId: "demo",
+      accessRule: rule,
+      resolver: stubResolver([]).resolver,
+      readSignals: async () => globalSignals,
+    });
+    const principal: AuthUser = { type: "service", pluginId: "svc" };
+    const result = await contributor.read({ principal });
+    expect(result.accessible).toBe(true);
+    expect(Object.keys(result.signals).sort()).toEqual(["sysA", "sysB"]);
+  });
+
+  test("a manage grant satisfies the read rule (escalation) and sees all", async () => {
+    const contributor = createGatedSystemSignalsContributor({
+      sourceId: "demo",
+      accessRule: rule,
+      resolver: stubResolver([]).resolver,
+      readSignals: async () => globalSignals,
+    });
+    const result = await contributor.read({
+      principal: userWith(["demo.thing.manage"]),
+    });
+    expect(Object.keys(result.signals).sort()).toEqual(["sysA", "sysB"]);
+  });
+
+  test("non-global user is filtered to team-granted systems (correct resourceType)", async () => {
+    const read = mock(async () => globalSignals);
+    const { resolver, calls } = stubResolver(["sysB"]);
+    const contributor = createGatedSystemSignalsContributor({
+      sourceId: "demo",
+      accessRule: rule,
+      resolver,
+      readSignals: read,
+    });
+
+    const result = await contributor.read({ principal: userWith([]) });
+
+    expect(result.accessible).toBe(true);
+    expect(Object.keys(result.signals)).toEqual(["sysB"]); // sysA filtered out
+    expect(read).toHaveBeenCalledTimes(1);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toMatchObject({
+      userId: "u1",
+      userType: "user",
+      resourceType: "demo.thing", // qualifyResourceType(pluginId, resource)
+      action: "read",
+      hasGlobalAccess: false,
+    });
+    expect(calls[0].systemIds.sort()).toEqual(["sysA", "sysB"]);
+  });
+
+  test("non-global user with no team grants is reported inaccessible", async () => {
+    const { resolver } = stubResolver([]); // grants nothing
+    const contributor = createGatedSystemSignalsContributor({
+      sourceId: "demo",
+      accessRule: rule,
+      resolver,
+      readSignals: async () => globalSignals,
+    });
+
+    const result = await contributor.read({ principal: userWith([]) });
+
+    expect(result).toEqual({ accessible: false, signals: {} });
+  });
+
+  test("globally-clear source: accessible with no signals, resolver not called", async () => {
+    const { resolver, calls } = stubResolver([]);
+    const contributor = createGatedSystemSignalsContributor({
+      sourceId: "demo",
+      accessRule: rule,
+      resolver,
+      readSignals: async () => ({}),
+    });
+
+    const result = await contributor.read({ principal: userWith([]) });
+
+    expect(result).toEqual({ accessible: true, signals: {} });
+    expect(calls).toHaveLength(0);
+  });
+});

package/src/system-signals-contributor.ts

@@ -0,0 +1,129 @@
+import type { AuthUser, RpcClient } from "@checkstack/backend-api";
+import type { AccessRule } from "@checkstack/common";
+import { isAccessRuleSatisfied, qualifyResourceType } from "@checkstack/common";
+import { AuthApi } from "@checkstack/auth-common";
+import type { SystemSignalsMap } from "@checkstack/catalog-common";
+import {
+  principalGrantedRuleIds,
+  type SystemSignalsContributor,
+} from "./extension-points";
+
+/**
+ * Resolves the subset of `systemIds` a non-global principal may see for a
+ * resource type, applying the SAME team/instance grants the RPC middleware
+ * enforces for list/record endpoints (via auth's `getAccessibleResourceIds`).
+ */
+export interface SystemAccessResolver {
+  accessibleSystemIds(args: {
+    userId: string;
+    userType: "user" | "application";
+    resourceType: string;
+    systemIds: string[];
+    action: "read" | "manage";
+    hasGlobalAccess: boolean;
+  }): Promise<string[]>;
+}
+
+/**
+ * Build a {@link SystemAccessResolver} backed by the auth plugin's
+ * `getAccessibleResourceIds` S2S query - the exact primitive the RPC middleware
+ * uses to filter list/record endpoints by team grants. A plugin gets its
+ * `rpcClient` from `coreServices.rpcClient` in `init`.
+ */
+export function createSystemAccessResolver(
+  rpcClient: RpcClient,
+): SystemAccessResolver {
+  const authClient = rpcClient.forPlugin(AuthApi);
+  return {
+    accessibleSystemIds: ({
+      userId,
+      userType,
+      resourceType,
+      systemIds,
+      action,
+      hasGlobalAccess,
+    }) =>
+      authClient.getAccessibleResourceIds({
+        userId,
+        userType,
+        resourceType,
+        resourceIds: systemIds,
+        action,
+        hasGlobalAccess,
+      }),
+  };
+}
+
+/**
+ * Build a {@link SystemSignalsContributor} from a GLOBAL signal reader, applying
+ * the per-source access gate centrally so every source enforces it identically
+ * (and the same way the matching bulk RPC does):
+ *
+ * - A principal holding the global rule - including trusted service principals,
+ *   which {@link principalGrantedRuleIds} maps to the wildcard - sees every
+ *   system the source reports.
+ * - A real user / application WITHOUT the global rule sees only the systems its
+ *   TEAM grants allow, via {@link SystemAccessResolver} (the same instance/team
+ *   filtering the bulk RPC applies), so `system.issues` neither under- nor
+ *   over-reports relative to the per-domain UI.
+ * - Any other principal without the global rule (anonymous, or a service lacking
+ *   the wildcard) sees nothing.
+ *
+ * `readSignals` MUST return problem signals for ALL systems globally; the gate
+ * filters them. It is not called for a principal that can see nothing, so a
+ * no-access principal triggers no query.
+ */
+export function createGatedSystemSignalsContributor({
+  sourceId,
+  accessRule,
+  resolver,
+  readSignals,
+}: {
+  sourceId: string;
+  accessRule: AccessRule;
+  resolver: SystemAccessResolver;
+  readSignals: () => Promise<SystemSignalsMap>;
+}): SystemSignalsContributor {
+  const resourceType = qualifyResourceType(
+    accessRule.pluginId,
+    accessRule.resource,
+  );
+  return {
+    sourceId,
+    read: async ({ principal }: { principal: AuthUser }) => {
+      const hasGlobalAccess = isAccessRuleSatisfied(
+        principalGrantedRuleIds(principal),
+        accessRule,
+      );
+      if (hasGlobalAccess) {
+        return { accessible: true, signals: await readSignals() };
+      }
+      // Only real users / applications can carry per-team instance grants.
+      if (principal.type !== "user" && principal.type !== "application") {
+        return { accessible: false, signals: {} };
+      }
+      const signals = await readSignals();
+      const systemIds = Object.keys(signals);
+      if (systemIds.length === 0) {
+        // Source is globally clear: nothing to report and nothing to hide.
+        return { accessible: true, signals: {} };
+      }
+      const accessibleIds = new Set(
+        await resolver.accessibleSystemIds({
+          userId: principal.id,
+          userType: principal.type,
+          resourceType,
+          systemIds,
+          action: "read",
+          hasGlobalAccess: false,
+        }),
+      );
+      const filtered: SystemSignalsMap = {};
+      for (const [systemId, sigs] of Object.entries(signals)) {
+        if (accessibleIds.has(systemId)) filtered[systemId] = sigs;
+      }
+      // Accessible iff the principal may see at least one affected system.
+      return { accessible: accessibleIds.size > 0, signals: filtered };
+    },
+  };
+}

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", () => {