@checkstack/ai-backend 0.1.0

package/src/tools/script-context-extract.ts

@@ -0,0 +1,283 @@
+import type {
+  ScriptContextKind,
+  ShellEnvVar,
+} from "@checkstack/ai-common";
+
+/**
+ * Pure extraction of per-context SDK symbols from the generated editor bundle
+ * (§3.1). The single source of truth for script SDK symbols is the GENERATED
+ * `SDK_EDITOR_BUNDLE_DTS` string (`@checkstack/sdk/editor-bundle`) - the SAME
+ * text Monaco mounts. This module pulls the `declare module "<name>" { ... }`
+ * block for a context out of that string by region extraction (no TypeScript
+ * compiler dependency), so it cannot drift from the editor (both derive from
+ * the one generated bundle).
+ *
+ * For shell contexts there is no SDK module: the "symbols" are the reserved
+ * `CHECKSTACK_*` env vars the runner injects, shipped here as a static
+ * descriptor table guarded by a drift test (§3.1 / OQ-2).
+ */
+
+/** Per-context static descriptor that drives extraction + tool output. */
+export interface ScriptContextDescriptor {
+  context: ScriptContextKind;
+  language: "typescript" | "shell";
+  /** SDK module the script imports from (TS contexts only). */
+  sdkModule?: string;
+  /** The define-helper name (TS contexts only). */
+  helper?: string;
+  /** Whether managed npm packages are importable. */
+  allowsManagedPackages: boolean;
+}
+
+export const SCRIPT_CONTEXT_DESCRIPTORS: Readonly<
+  Record<ScriptContextKind, ScriptContextDescriptor>
+> = {
+  "healthcheck-script": {
+    context: "healthcheck-script",
+    language: "typescript",
+    sdkModule: "@checkstack/sdk/healthcheck",
+    helper: "defineHealthCheck",
+    allowsManagedPackages: true,
+  },
+  "automation-action-script": {
+    context: "automation-action-script",
+    language: "typescript",
+    sdkModule: "@checkstack/sdk/integration",
+    helper: "defineIntegration",
+    allowsManagedPackages: true,
+  },
+  "healthcheck-shell": {
+    context: "healthcheck-shell",
+    language: "shell",
+    allowsManagedPackages: false,
+  },
+  "automation-action-shell": {
+    context: "automation-action-shell",
+    language: "shell",
+    allowsManagedPackages: false,
+  },
+};
+
+/**
+ * Reserved `CHECKSTACK_*` env vars the shell health-check collector exposes.
+ * Hand-maintained here (cross-plugin import is deliberately avoided by the
+ * codebase) and guarded by `shell-env-table.test.ts`, which asserts these match
+ * `buildShellRunContextEnv`'s output for a representative sample (OQ-2).
+ */
+export const HEALTHCHECK_SHELL_ENV: readonly ShellEnvVar[] = [
+  {
+    name: "CHECKSTACK_CHECK_ID",
+    description: "The health check configuration id.",
+  },
+  {
+    name: "CHECKSTACK_CHECK_NAME",
+    description: "The health check's display name (falls back to the id).",
+  },
+  {
+    name: "CHECKSTACK_CHECK_INTERVAL_SECONDS",
+    description: "The configured run interval, in seconds.",
+  },
+  { name: "CHECKSTACK_SYSTEM_ID", description: "The system id." },
+  {
+    name: "CHECKSTACK_SYSTEM_NAME",
+    description: "The system's display name (falls back to the id).",
+  },
+  { name: "CHECKSTACK_ENV_ID", description: "The resolved environment id." },
+  {
+    name: "CHECKSTACK_ENV_NAME",
+    description: "The resolved environment's display name.",
+  },
+  {
+    name: "CHECKSTACK_ENV_<FIELD>",
+    description:
+      "One var per environment custom-field: the field key uppercased with non-alphanumeric runs collapsed to '_' (e.g. region -> CHECKSTACK_ENV_REGION).",
+  },
+];
+
+/**
+ * Reserved `CHECKSTACK_*` env vars a `run_shell` automation action exposes.
+ * The runner flattens the trigger event + scope into `CHECKSTACK_*` vars.
+ */
+export const AUTOMATION_SHELL_ENV: readonly ShellEnvVar[] = [
+  {
+    name: "CHECKSTACK_EVENT_ID",
+    description: 'Fully-qualified event id, e.g. "incident.created".',
+  },
+  {
+    name: "CHECKSTACK_EVENT_PAYLOAD",
+    description: "The triggering event payload as a JSON string.",
+  },
+  {
+    name: "CHECKSTACK_TRIGGER_EVENT",
+    description: "The event id that triggered this run.",
+  },
+];
+
+const SHELL_ENV_BY_CONTEXT: Partial<
+  Record<ScriptContextKind, readonly ShellEnvVar[]>
+> = {
+  "healthcheck-shell": HEALTHCHECK_SHELL_ENV,
+  "automation-action-shell": AUTOMATION_SHELL_ENV,
+};
+
+/** Thrown for an unknown context or a missing `declare module` block. */
+export class ScriptContextExtractionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ScriptContextExtractionError";
+  }
+}
+
+/**
+ * Extract the `declare module "<moduleName>" { ... }` block from the bundle
+ * text by brace matching. Pure: no compiler, no I/O. Returns the full block
+ * (including the `declare module` header and the matching closing brace).
+ */
+export function extractDeclareModuleBlock({
+  bundle,
+  moduleName,
+}: {
+  bundle: string;
+  moduleName: string;
+}): string {
+  const header = `declare module "${moduleName}"`;
+  const headerIndex = bundle.indexOf(header);
+  if (headerIndex === -1) {
+    throw new ScriptContextExtractionError(
+      String.raw`SDK editor bundle has no "declare module \"${moduleName}\"" block.`,
+    );
+  }
+  const openBrace = bundle.indexOf("{", headerIndex);
+  if (openBrace === -1) {
+    throw new ScriptContextExtractionError(
+      String.raw`Malformed "declare module \"${moduleName}\"" block: no opening brace.`,
+    );
+  }
+  let depth = 0;
+  for (let i = openBrace; i < bundle.length; i++) {
+    const ch = bundle[i];
+    if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) {
+        return bundle.slice(headerIndex, i + 1);
+      }
+    }
+  }
+  throw new ScriptContextExtractionError(
+    String.raw`Malformed "declare module \"${moduleName}\"" block: unbalanced braces.`,
+  );
+}
+
+/** Render the shell env table into a readable declarations string. */
+export function renderShellEnvDeclarations(
+  envVars: readonly ShellEnvVar[],
+): string {
+  return envVars
+    .map((v) => `# ${v.name}\n#   ${v.description}`)
+    .join("\n");
+}
+
+/** A minimal runnable starter the model can adapt, per context. */
+export function buildStarterExample(context: ScriptContextKind): string {
+  switch (context) {
+    case "healthcheck-script": {
+      return [
+        'import { defineHealthCheck } from "@checkstack/sdk/healthcheck";',
+        "",
+        "export default defineHealthCheck(async (ctx) => {",
+        "  const res = await fetch(String(ctx.config.url));",
+        "  return { success: res.ok, message: `HTTP ${res.status}` };",
+        "});",
+      ].join("\n");
+    }
+    case "automation-action-script": {
+      return [
+        'import { defineIntegration } from "@checkstack/sdk/integration";',
+        "",
+        "export default defineIntegration(async (ctx) => {",
+        "  console.log(`event ${ctx.event.eventId}`);",
+        "  return { id: ctx.event.deliveryId };",
+        "});",
+      ].join("\n");
+    }
+    case "healthcheck-shell": {
+      return [
+        "#!/usr/bin/env bash",
+        "set -euo pipefail",
+        'echo "checking system $CHECKSTACK_SYSTEM_NAME"',
+        "curl -fsS https://example.com/health",
+      ].join("\n");
+    }
+    case "automation-action-shell": {
+      return [
+        "#!/usr/bin/env bash",
+        "set -euo pipefail",
+        'echo "handling event $CHECKSTACK_EVENT_ID"',
+      ].join("\n");
+    }
+  }
+}
+
+/** Result of resolving a context's SDK symbols / declarations. */
+export interface ResolvedScriptContext {
+  context: ScriptContextKind;
+  language: "typescript" | "shell";
+  sdkModule?: string;
+  helper?: string;
+  declarations: string;
+  shellEnv?: readonly ShellEnvVar[];
+  starterExample: string;
+  allowsManagedPackages: boolean;
+}
+
+/**
+ * Resolve the SDK symbols / imports / type signatures for a script context by
+ * PURE extraction from the generated SDK editor bundle. For TS contexts the
+ * `declarations` is the matching `declare module` block; for shell contexts it
+ * is the rendered `CHECKSTACK_*` env table.
+ */
+export function resolveScriptContext({
+  context,
+  bundle,
+}: {
+  context: ScriptContextKind;
+  bundle: string;
+}): ResolvedScriptContext {
+  const descriptor = SCRIPT_CONTEXT_DESCRIPTORS[context];
+  if (!descriptor) {
+    throw new ScriptContextExtractionError(`Unknown script context: ${context}`);
+  }
+
+  if (descriptor.language === "shell") {
+    const shellEnv = SHELL_ENV_BY_CONTEXT[context] ?? [];
+    return {
+      context,
+      language: "shell",
+      declarations: renderShellEnvDeclarations(shellEnv),
+      shellEnv,
+      starterExample: buildStarterExample(context),
+      allowsManagedPackages: descriptor.allowsManagedPackages,
+    };
+  }
+
+  // TS context: pull the matching declare-module block from the generated bundle.
+  if (!descriptor.sdkModule) {
+    throw new ScriptContextExtractionError(
+      `Context ${context} is TypeScript but has no SDK module configured.`,
+    );
+  }
+  const declarations = extractDeclareModuleBlock({
+    bundle,
+    moduleName: descriptor.sdkModule,
+  });
+  return {
+    context,
+    language: "typescript",
+    sdkModule: descriptor.sdkModule,
+    helper: descriptor.helper,
+    declarations,
+    starterExample: buildStarterExample(context),
+    allowsManagedPackages: descriptor.allowsManagedPackages,
+  };
+}

package/src/tools/ssrf-guard.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, test } from "bun:test";
+import { isPrivateIp, parseSafeProbeUrl } from "./ssrf-guard";
+
+describe("isPrivateIp", () => {
+  test("blocks private/reserved IPv4 ranges", () => {
+    for (const ip of [
+      "127.0.0.1",
+      "10.1.2.3",
+      "172.16.0.1",
+      "172.31.255.255",
+      "192.168.1.1",
+      "169.254.169.254", // cloud metadata
+      "100.64.0.1", // CGNAT
+      "0.0.0.0",
+      "224.0.0.1", // multicast
+    ]) {
+      expect(isPrivateIp(ip)).toBe(true);
+    }
+  });
+
+  test("allows public IPv4", () => {
+    for (const ip of ["8.8.8.8", "1.1.1.1", "93.184.216.34"]) {
+      expect(isPrivateIp(ip)).toBe(false);
+    }
+  });
+
+  test("blocks private/reserved IPv6 incl. IPv4-mapped private", () => {
+    for (const ip of ["::1", "::", "fe80::1", "fc00::1", "fd12::3", "::ffff:127.0.0.1"]) {
+      expect(isPrivateIp(ip)).toBe(true);
+    }
+  });
+
+  test("allows public IPv6", () => {
+    expect(isPrivateIp("2606:4700:4700::1111")).toBe(false);
+  });
+});
+
+describe("parseSafeProbeUrl", () => {
+  test("accepts a public http(s) URL", () => {
+    const safe = parseSafeProbeUrl("https://example.com/status");
+    expect(safe.hostname).toBe("example.com");
+    expect(safe.url.pathname).toBe("/status");
+  });
+
+  test("rejects non-http(s) schemes", () => {
+    expect(() => parseSafeProbeUrl("file:///etc/passwd")).toThrow(/http and https/);
+    expect(() => parseSafeProbeUrl("ftp://example.com")).toThrow(/http and https/);
+  });
+
+  test("rejects malformed URLs", () => {
+    expect(() => parseSafeProbeUrl("not a url")).toThrow(/Invalid URL/);
+  });
+
+  test("rejects loopback + internal hostnames", () => {
+    expect(() => parseSafeProbeUrl("http://localhost:8080/")).toThrow(/loopback/);
+    expect(() => parseSafeProbeUrl("http://foo.localhost/")).toThrow(/loopback/);
+    expect(() =>
+      parseSafeProbeUrl("http://metadata.google.internal/"),
+    ).toThrow(/loopback|internal/);
+  });
+
+  test("rejects private IP literals (v4 + v6)", () => {
+    expect(() => parseSafeProbeUrl("http://169.254.169.254/latest/meta-data")).toThrow(
+      /private\/reserved/,
+    );
+    expect(() => parseSafeProbeUrl("http://10.0.0.5/")).toThrow(/private\/reserved/);
+    expect(() => parseSafeProbeUrl("http://[::1]:9000/")).toThrow(/private\/reserved/);
+  });
+});

package/src/tools/ssrf-guard.ts

@@ -0,0 +1,108 @@
+/**
+ * SSRF guards for the `ai.probeUrl` tool. The probe issues an outbound HTTP
+ * request FROM THE CORE BACKEND, so it must never be steerable at internal
+ * services, the loopback interface, or the cloud metadata endpoint. These pure
+ * helpers (URL shape + IP-range classification) are unit-tested; the network
+ * call itself lives in `probe-url.ts` and uses them to validate the URL AND
+ * every DNS-resolved IP before connecting.
+ */
+
+/** Max response body we read from a probe (avoid memory blow-ups). */
+export const PROBE_MAX_BODY_BYTES = 256 * 1024;
+/** Probe request timeout. */
+export const PROBE_TIMEOUT_MS = 5000;
+
+/** Hostnames that must never be probed regardless of DNS. */
+const BLOCKED_HOSTNAMES = new Set([
+  "localhost",
+  "metadata.google.internal",
+]);
+
+/**
+ * Classify an IPv4 literal as private/reserved (must be blocked). Covers the
+ * ranges an SSRF would target: loopback, RFC1918, link-local (incl. the cloud
+ * metadata 169.254.169.254), CGNAT, "this host", and broadcast.
+ */
+function isPrivateIpv4(ip: string): boolean {
+  const parts = ip.split(".");
+  if (parts.length !== 4) return false;
+  const octets = parts.map(Number);
+  if (octets.some((o) => !Number.isInteger(o) || o < 0 || o > 255)) return false;
+  const [a, b] = octets;
+  if (a === 0) return true; // 0.0.0.0/8 "this host"
+  if (a === 10) return true; // 10.0.0.0/8
+  if (a === 127) return true; // 127.0.0.0/8 loopback
+  if (a === 169 && b === 254) return true; // 169.254.0.0/16 link-local + metadata
+  if (a === 172 && b >= 16 && b <= 31) return true; // 172.16.0.0/12
+  if (a === 192 && b === 168) return true; // 192.168.0.0/16
+  if (a === 100 && b >= 64 && b <= 127) return true; // 100.64.0.0/10 CGNAT
+  if (a === 192 && b === 0) return true; // 192.0.0.0/24 + 192.0.2.0/24 (test nets)
+  if (a >= 224) return true; // multicast + reserved/broadcast
+  return false;
+}
+
+/**
+ * Classify an IPv6 literal as private/reserved. Handles loopback, ULA, link-
+ * local, unspecified, and IPv4-mapped/embedded addresses (which would otherwise
+ * smuggle a private IPv4 past an IPv6 check).
+ */
+function isPrivateIpv6(ip: string): boolean {
+  const addr = ip.toLowerCase().split("%")[0]; // strip zone id
+  if (addr === "::1" || addr === "::") return true; // loopback / unspecified
+  // IPv4-mapped (::ffff:a.b.c.d) or IPv4-compatible: validate the embedded v4.
+  const v4Match = addr.match(/(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+  if (v4Match && isPrivateIpv4(v4Match[1])) return true;
+  const head = addr.split(":")[0];
+  if (head.startsWith("fc") || head.startsWith("fd")) return true; // fc00::/7 ULA
+  if (head.startsWith("fe8") || head.startsWith("fe9") || head.startsWith("fea") || head.startsWith("feb")) {
+    return true; // fe80::/10 link-local
+  }
+  return false;
+}
+
+/** True when an IP literal is private/reserved and must NOT be probed. */
+export function isPrivateIp(ip: string): boolean {
+  return ip.includes(":") ? isPrivateIpv6(ip) : isPrivateIpv4(ip);
+}
+
+/** The validated, safe-to-fetch parse of a probe URL. */
+export interface SafeProbeUrl {
+  url: URL;
+  hostname: string;
+}
+
+/**
+ * Validate a probe URL's SHAPE (before DNS): it must be a well-formed http(s)
+ * URL, not a blocked hostname, and not an IP literal in a private range. Throws
+ * with a clear message on rejection. DNS-resolved IPs are checked separately at
+ * fetch time via {@link isPrivateIp} (this catches a hostname that resolves to
+ * a private IP, which the shape check cannot see).
+ */
+export function parseSafeProbeUrl(raw: string): SafeProbeUrl {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error(`Invalid URL: "${raw}".`);
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error(
+      `Only http and https URLs can be probed (got "${url.protocol}").`,
+    );
+  }
+  const hostname = url.hostname.replaceAll(/^\[|\]$/g, "").toLowerCase(); // unwrap [::1]
+  if (!hostname) {
+    throw new Error("URL has no host.");
+  }
+  if (BLOCKED_HOSTNAMES.has(hostname) || hostname.endsWith(".localhost")) {
+    throw new Error(`Refusing to probe a loopback/internal host: "${hostname}".`);
+  }
+  // If the host is an IP literal, reject private ranges up front.
+  const looksLikeIp = /^[\d.]+$/.test(hostname) || hostname.includes(":");
+  if (looksLikeIp && isPrivateIp(hostname)) {
+    throw new Error(
+      `Refusing to probe a private/reserved address: "${hostname}".`,
+    );
+  }
+  return { url, hostname };
+}

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

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test";
+import type { AuthUser } from "@checkstack/backend-api";
+import { aiAccess, pluginMetadata as aiPluginMetadata } from "@checkstack/ai-common";
+import { qualifyAccessRuleId } from "@checkstack/common";
+import { createAiToolRegistry } from "../tool-registry";
+import type { AiToolRegistry } from "../tool-registry";
+import { createAiToolResolver } from "../resolver";
+import { buildCompositeTools } from "./composite-tools";
+
+const CHAT_READ_RULE = qualifyAccessRuleId(aiPluginMetadata, aiAccess.chatUse);
+
+/**
+ * ai-backend's OWN platform tools, built from the SAME shared `buildCompositeTools`
+ * factory the plugin init uses. After the decouple, these are the genuinely
+ * cross-plugin / platform read tools (docs grounding + URL probe) - all gated by
+ * the broad `ai.chat.read` surface. Plugin-specific tools (propose/update/delete,
+ * capability catalogs, script-context) and projected read tools are owned by and
+ * registered FROM their plugins via the extension points, and are covered by
+ * those plugins' OWN tests - ai-backend neither builds nor imports them.
+ */
+function buildOwnRegistry(): AiToolRegistry {
+  const registry = createAiToolRegistry();
+  for (const tool of buildCompositeTools()) {
+    const name = tool.name.includes(".") ? tool.name : `ai.${tool.name}`;
+    registry.register({ ...tool, name });
+  }
+  return registry;
+}
+
+/** An admin-equivalent principal (the `*` escape) - sees every tool. */
+const adminPrincipal: AuthUser = {
+  type: "user",
+  id: "admin",
+  accessRules: ["*"],
+};
+
+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"]) {
+      expect(names).toContain(expected);
+    }
+  });
+
+  test("admin resolves every registered tool", () => {
+    const registry = buildOwnRegistry();
+    const resolver = createAiToolResolver({ registry });
+    expect(resolver.resolveTools(adminPrincipal)).toHaveLength(
+      registry.getTools().length,
+    );
+  });
+
+  test("every own tool is a read tool gated by the broad chat-read surface", () => {
+    // ai-backend's own tools are all platform read tools (docs + probe). A
+    // service-client fan-out read tool would need an in-execute re-check; these
+    // touch only bundled docs or an outbound fetch, so chat-read is the gate.
+    const registry = buildOwnRegistry();
+    for (const tool of registry.getTools()) {
+      expect(tool.effect).toBe("read");
+      expect(tool.requiredAccessRules).toContain(CHAT_READ_RULE);
+    }
+  });
+});

package/src/user-rpc-client.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createUserScopedRpcClient,
+  forwardableAuthHeadersFrom,
+} from "./user-rpc-client";
+
+describe("forwardableAuthHeadersFrom", () => {
+  test("forwards ONLY the session cookie and bearer Authorization", () => {
+    const headers = new Headers({
+      cookie: "session=abc",
+      authorization: "Bearer xyz",
+      // Must NOT be forwarded - only auth-bearing headers are.
+      "x-forwarded-for": "10.0.0.1",
+      "content-type": "application/json",
+    });
+    expect(forwardableAuthHeadersFrom(headers)).toEqual({
+      cookie: "session=abc",
+      authorization: "Bearer xyz",
+    });
+  });
+
+  test("omits absent headers (no empty values)", () => {
+    expect(forwardableAuthHeadersFrom(new Headers({ cookie: "s=1" }))).toEqual({
+      cookie: "s=1",
+    });
+    expect(
+      forwardableAuthHeadersFrom(new Headers({ authorization: "Bearer t" })),
+    ).toEqual({ authorization: "Bearer t" });
+  });
+
+  test("returns an empty object for undefined or empty headers", () => {
+    expect(forwardableAuthHeadersFrom(undefined)).toEqual({});
+    expect(forwardableAuthHeadersFrom(new Headers())).toEqual({});
+  });
+});
+
+describe("createUserScopedRpcClient", () => {
+  test("returns an RpcClient with a forPlugin accessor (no network until used)", () => {
+    const client = createUserScopedRpcClient({
+      internalUrl: "http://localhost:3000",
+      forwardHeaders: { cookie: "session=abc" },
+    });
+    expect(typeof client.forPlugin).toBe("function");
+  });
+});

package/src/user-rpc-client.ts

@@ -0,0 +1,60 @@
+import { createORPCClient } from "@orpc/client";
+import { RPCLink } from "@orpc/client/fetch";
+import type { RpcClient } from "@checkstack/backend-api";
+
+/**
+ * Build a USER-SCOPED `RpcClient` for an AI tool to call plugin procedures AS
+ * THE ORIGINATING USER, never as a trusted service.
+ *
+ * The trusted `coreServices.rpcClient` injects a service JWT, and
+ * `autoAuthMiddleware` SHORT-CIRCUITS all access-rule, single-resource, and
+ * team-scope checks for service principals. So a tool calling the trusted client
+ * would bypass the user's authorization and could read/mutate resources the user
+ * cannot - a privilege-escalation path. Instead, this client re-enters the live
+ * router at `/api` forwarding the user's OWN auth (session cookie and/or bearer),
+ * so the procedure re-authenticates to the SAME principal and runs
+ * `autoAuthMiddleware` (incl. per-resource/team `instanceAccess`) exactly as a
+ * direct UI/RPC call would. It mirrors `createChatReadInvoker` /
+ * `mcp/tool-invoker`, but presents the full typed `RpcClient.forPlugin(...)`
+ * surface so a tool's `execute`/`dryRun` uses it transparently.
+ *
+ * IMPORTANT: only the user's forwardable auth headers (cookie / Authorization)
+ * are forwarded - never arbitrary client headers and never the service JWT.
+ */
+export function createUserScopedRpcClient({
+  internalUrl,
+  forwardHeaders,
+}: {
+  internalUrl: string;
+  forwardHeaders: Record<string, string>;
+}): RpcClient {
+  const link = new RPCLink({
+    url: `${internalUrl}/api`,
+    headers: forwardHeaders,
+  });
+  const client = createORPCClient(link);
+  return {
+    forPlugin(def) {
+      // Same accessor shape as the trusted client in core-services; typing is
+      // provided by the RpcClient interface (InferClient<T>).
+      return (client as Record<string, unknown>)[def.pluginId] as never;
+    },
+  };
+}
+
+/**
+ * Extract the forwardable auth headers from a `Headers` view (the oRPC handler
+ * `context.requestHeaders` for the deferred applyTool/proposeTool path). Only the
+ * session cookie and bearer Authorization are forwarded.
+ */
+export function forwardableAuthHeadersFrom(
+  headers: Headers | undefined,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!headers) return out;
+  const cookie = headers.get("cookie");
+  if (cookie) out.cookie = cookie;
+  const auth = headers.get("authorization");
+  if (auth) out.authorization = auth;
+  return out;
+}

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json",
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../ai-common"
+    },
+    {
+      "path": "../backend-api"
+    },
+    {
+      "path": "../common"
+    },
+    {
+      "path": "../drizzle-helper"
+    },
+    {
+      "path": "../integration-backend"
+    },
+    {
+      "path": "../sdk"
+    }
+  ]
+}