@checkstack/ai-common 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,75 @@
+# @checkstack/ai-common
+
+## 0.1.0
+
+### Minor Changes
+
+- 9dcc848: AI chat UX: ordered turns, readable diffs, persistent errors, auto-titles, decision acknowledgments, and a smarter topical guard.
+
+  - Turns render as ordered parts (text / tool-call status / confirm card) in chronological order, with inline tool-error lines and a mid-turn "Thinking..." indicator, instead of one text blob plus a flat tool list. The confirm card and tool-step parts no longer vanish after a turn finishes (hydration seeds once per conversation id via `useInitOnceForKey`, so background refetches are no-ops).
+  - Errors persist: in-stream provider errors are lifted into the chat hook's durable error state and shown in a dismissible banner with selectable text and a Copy button (single-line digest, full text on hover); it clears on send / open / new chat. The backend installs an `onError` handler that logs the provider's full HTTP response and returns a readable message, and normalizes the model message history (drop empty rows, merge consecutive same-role rows, strip a leading non-user row) so a single provider hiccup can no longer brick a conversation.
+  - Confirm/applied card diffs render as a GitHub-style split diff (line-number gutters, per-line tint, word-level highlighting, an "Expand" pop-out). `computeFieldDiff` recurses into arrays element-wise so a single changed leaf is pinpointed instead of dumping whole serialized arrays.
+  - Conversations auto-title after the first user message (cheap `generateText` reusing the turn's model, fire-and-forget, heuristic fallback). "New chat" opens immediately and reuses an empty untitled draft instead of spawning duplicates; "Delete" is a soft archive (`archived_at` on `ai_conversations`, data retained). A clean model picker always renders a `Select` of `[defaultModel, ...availableModels]` de-duplicated.
+  - The assistant acknowledges a confirm-card decision (a new `decision` mode -> `streamDecision`) instead of going silent after an apply/decline; the decision note is derived server-side from the stored proposal and is ephemeral.
+  - A cheap topical pre-classifier short-circuits off-topic turns with a canned refusal (fail-open, spend recorded). It marks meta/capability/greeting/how-to questions as ON_TOPIC; only clearly unrelated requests (coding help, creative writing, trivia) are refused.
+  - The chat agent no longer emits duplicate proposals for one request: propose/auto-apply results carry an explicit model-facing "stop and wait" note, and a per-turn `<tool>:<argsHash>` dedupe short-circuits repeated identical mutating calls.
+  - Assistant messages render through the shared `<MarkdownBlock>`: it now parses a SAFE subset of raw HTML (`rehype-raw` + `rehype-sanitize`) so native `<details>`/`<summary>` widgets render, and enables `remark-gfm` so GFM tables, strikethrough, and autolinks render (the assistant often summarizes drafts as tables).
+
+  State and scale: the archive marker, titles, and permission mode all live in the shared `ai_conversations` table, read identically on every pod; the classifier holds no state and its spend is recorded in the shared `ai_spend` ledger. No new pod-local state.
+
+  This is a beta minor.
+
+- 9dcc848: Add the AI platform: a transport-agnostic tool spine, an OAuth Authorization Server + read-only MCP server, a propose/apply flow with audit log, a streaming in-app chat agent, per-conversation permission modes, per-integration spend caps, and user-scoped tool authorization.
+
+  Two new packages, `@checkstack/ai-common` (the `AiTool` contract, `read`/`mutate`/`destructive` effect classification, the `ai.*` access rules, the OpenAI-compatible connection shape, and the wire contracts) and `@checkstack/ai-backend` (the tool registry, extension points, principal-to-tool resolver, shared zod-to-JSON-Schema serializer, and all transports). The OpenAI-compatible integration provider registers through the existing integration provider extension point, so its API key is stored in the Secrets Vault and configured in the generic Connections UI.
+
+  What ships:
+
+  - Tool spine and extension points: `aiToolExtensionPoint.registerTool` (hand-authored composite tools) and `aiToolProjectionExtensionPoint.expose` (opt-in projections of existing oRPC procedures). Authorization mirrors `autoAuthMiddleware` exactly - a tool is surfaced only when every `requiredAccessRules` entry is satisfied, so a scope-narrowed principal can only ever see fewer tools.
+  - OAuth + MCP: Checkstack can act as its own OAuth 2.1 Authorization Server (authorization code + PKCE, consent screen, Dynamic Client Registration) and expose a read-only MCP server over Streamable HTTP at `/api/ai/mcp`. Off by default, enabled by the admin `ai.mcp-oauth` setting. A Bearer OAuth-token branch is added to the auth strategy; token scopes are intersected live with the bound user's access rules on every call. A shared-Postgres rate limiter throttles the DCR endpoint per client IP. `getMcpOAuthSettings` / `setMcpOAuthSettings` contracts added to `@checkstack/auth-common`. A minimal OAuth consent page (`/auth/oauth-consent`) renders the requesting client and scopes.
+  - Propose/apply + audit: a transport-agnostic two-step service - `propose` re-checks authz, runs the tool's `dryRun` without mutating, and returns a single-use proposal token (the `proposed` audit row IS the token store, 10-minute TTL, atomic single-use); `apply` re-parses the server-stored payload, re-checks authz, and atomically commits. The `ai_tool_calls` audit table records every call across both transports with a SHA-256 args hash (never raw arguments) and stamps who proposed and who applied. An `ai.toolCalled` event carries metadata only.
+  - In-app chat: a server-side, provider-agnostic Vercel AI SDK agent loop (OpenAI, Azure, OpenRouter, Ollama, vLLM, LM Studio, ...). The model provider is built on the backend from the integration credentials, so the API key never leaves the backend. The loop offers only resolver-allowed tools, auto-runs read tools (re-entering the live router as the logged-in user) and routes mutating / destructive tools through propose/apply. Durable conversation persistence (`ai_conversations`, `ai_messages`, owner-scoped RPCs) plus a streaming chat UI with a confirm-card component and per-integration model picker.
+  - Per-conversation permission mode (Claude-Code-style approve/auto), a durable `permission_mode` column on `ai_conversations` (default `approve`). `read` always auto-runs in both modes; `mutate` inherits the mode (auto-applies server-side in `auto`, confirm-carded in `approve`); `destructive` ALWAYS requires the human `applyTool` in both modes. Security invariant (structural + tested): the mode is consulted only on the `mutate` branch, so no `(effect, mode)` pair routes a destructive tool to auto-apply.
+  - Per-integration LLM spend cap (optional `spendCap` = `tokenBudget` + `windowMinutes`, default OFF). Spend is tracked in a shared-Postgres `ai_spend` ledger; enforcement is a rolling-window SUM run before each turn (HTTP 429 over budget). Per-principal tool rate-limit budgets are a rolling COUNT over `ai_tool_calls`, enforced on both transports. An absent / empty / incomplete `spendCap` is treated as "no cap" rather than rejected.
+  - Full tool-call replay: `ai_messages.model_messages` (jsonb) persists the canonical AI-SDK `ResponseMessage[]` per turn and replays them verbatim on the next turn; legacy rows fall back to text-only replay.
+  - Enforced no-secret-leak scrubbing: `appendMessage` runs `scrubContent` on every write, redacting credential-shaped keys and high-confidence credential values; a canary regression test asserts injected secrets are stripped. A hardening test suite asserts no secret appears in any AI-surface DTO and that handler-side authz holds when the model misbehaves.
+  - Provider correctness: the chat provider uses `@ai-sdk/openai-compatible`'s `chatModel` (plain `/chat/completions`), so OpenAI-compatible gateways (OpenRouter, DeepSeek, Ollama, vLLM) no longer reject turns with `invalid_prompt`; `@ai-sdk/openai` is removed.
+
+  BREAKING CHANGES:
+
+  - The `AiTool` contract (`@checkstack/ai-common`) gained a `TRpc` type parameter, and both `dryRun` and `execute` now receive a USER-SCOPED `rpcClient` arg bound to the originating user. Every plugin procedure a tool calls re-enters the live router AS THAT USER, so handler-side authorization (access rules AND per-resource/team scope) is enforced exactly as a direct UI/RPC call - closing a prior privilege-escalation where tools captured a trusted service client at construction. A hand-authored tool MUST resolve its plugin client from this per-call arg and MUST NOT capture a trusted service client at factory scope. Tool factories that previously took `{ rpcClient }` should drop that parameter.
+  - `AiToolProjectionExtensionPoint.expose` no longer takes a second `pluginMetadata` argument; the owning metadata lives on `input.sourcePluginMetadata`. Callers must drop the second argument.
+
+  State and scale: conversations, messages, the audit log, proposal tokens, the rate-limit counter, and the spend ledger all live in shared Postgres, so every pod answers identically and the agent loop is resumable on any pod. The only pod-local state is the live MCP connection registry (bookkeeping, never a source of truth). Cross-pod conversation readback, the spend cap, and the tool budget are verified by env-gated two-pod integration tests.
+
+  This is a beta minor.
+
+- 9dcc848: Plugin-owned AI tools: every domain plugin contributes its own AI tools (chat assistant + automation AI action), and `ai-backend` is platform-only.
+
+  Every plugin-specific AI tool is owned by the plugin whose domain it acts on, registered via that plugin's own `aiToolExtensionPoint` / `aiToolProjectionExtensionPoint` from its init - the same path an external plugin author uses. `ai-backend` no longer imports or depends on any capability plugin's `*-common`; the dependency direction is strictly plugin -> ai-platform. Pure helpers (`computeFieldDiff`, capability-summary, `ScriptContextKind`) live in `@checkstack/ai-common`.
+
+  Tools shipped:
+
+  - Health checks and automations: full CRUD - `healthcheck.propose` / `automation.propose` and `*.update` (`mutate`, deep-validated) and `*.delete` (`destructive`, always confirm-gated). `healthcheck.propose`'s dry-run calls the new deep `validateConfiguration` so propose-time validation matches apply-time. Assertions are validated against the collector's result schema and the canonical operator vocabulary. Capability-catalog tools (`ai.listCapabilities`, `ai.getCapabilitySchema`), script context tools (`ai.getScriptContext`, `ai.testScript`), and notify-subscriber tools (`healthcheck.notifySystemSubscribers` / `...GroupSubscribers`).
+  - Catalog: `catalog.createSystem` / `updateSystem` / `createGroup` / `updateGroup` (`mutate`), `catalog.deleteSystem` / `deleteGroup` (`destructive`), membership tools (`mutate`), plus `catalog.listSystems` / `listGroups` read projections.
+  - Incident: `incident.create` / `update` / `addUpdate` / `resolve` / `addLink` (`mutate`), `incident.delete` / `removeLink` (`destructive`), and `incident.get` / `incident.list` read projections.
+  - Maintenance: `maintenance.create` / `update` / `addUpdate` / `close` / `addLink` (`mutate`), `maintenance.delete` / `removeLink` (`destructive`), and `maintenance.list` / `get` read projections.
+  - Read projections for SLO (`slo.listObjectives`), dependency (`dependency.list`), incident (`incident.list`), healthcheck (`healthcheck.status`), and anomaly (`anomaly.explain`), each gated by the source procedure's own access rule and routed as the principal.
+  - Documentation grounding: `ai.searchDocs` / `ai.getDoc` over a build-time bundled docs index (BM25-ish ranking), so the assistant grounds how-to answers in Checkstack's own docs offline.
+  - URL introspection: `ai.probeUrl`, an SSRF-guarded read tool the assistant uses to inspect a real endpoint before drafting a health check. Update tools compute a before -> after field diff rendered on the confirm card (approve mode) or an "Applied" card (auto mode), so a change is never silent.
+
+  `ai_analyze` automation action (automation-backend, with an editor connection picker + audited tool calls): runs a bounded AI agent on the run context as the automation's `runAs` service account, so it can never exceed that identity's permissions; destructive tools are never offered; mutating tools auto-apply through the service account's client. Produces an `automation.analysis` artifact downstream actions can branch on. The agent loop is exposed as a headless `aiAgentRunnerRef` service so automation-backend can drive it without depending on ai-backend.
+
+  `notification.notifyForSubscription` is now callable by user / application principals holding `notification.send` (previously service-only). Every tool routes through the user-scoped client, so handler-side authorization is enforced exactly as a direct UI/RPC action; the resolver gate plus the propose/apply re-check at propose AND apply are the additional authority. A systemic authz regression test asserts every registered tool falls into exactly one safe authorization category.
+
+  A new `ai_transport` enum value `automation` records the AI action's tool calls in the `ai_tool_calls` audit log. No new durable state beyond that; each tool is a thin, deterministic wrapper over an existing RPC, so every pod behaves identically.
+
+  This is a beta minor.
+
+### Patch Changes
+
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+  - @checkstack/common@0.13.0

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@checkstack/ai-common",
+  "version": "0.1.0",
+  "license": "Elastic-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@checkstack/common": "0.12.0",
+    "@orpc/contract": "^1.14.4",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@checkstack/scripts": "0.3.4",
+    "@checkstack/tsconfig": "0.0.7",
+    "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "typecheck": "tsgo -b",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0",
+    "test": "bun test"
+  },
+  "checkstack": {
+    "type": "common"
+  }
+}

package/src/access.ts

@@ -0,0 +1,31 @@
+import { access } from "@checkstack/common";
+
+/**
+ * Access rules for the AI platform plugin.
+ *
+ * These rule IDs share a single vocabulary with OAuth scopes (Phase 2) and the
+ * `autoAuthMiddleware` access-rule checks: a tool that requires `ai.tools-manage`
+ * is gated by exactly the same string the middleware enforces, so the surfaced
+ * tool set can never widen what the principal could already do in the UI.
+ */
+export const aiAccess = {
+  /**
+   * Use the in-app AI chat (Phase 4). Qualified id: `ai.chat.read`.
+   * The `access()` factory only supports `read` / `manage` levels, so the
+   * domain is carried by the resource segment.
+   */
+  chatUse: access("chat", "read", "Use the in-app AI chat"),
+  /** Manage AI tool projections + introspect the registered tool set. Qualified id: `ai.tools.manage`. */
+  toolsManage: access("tools", "manage", "Manage AI tool projections"),
+  /** Manage MCP clients and Dynamic Client Registration settings (Phase 2). Qualified id: `ai.mcp.manage`. */
+  mcpManage: access("mcp", "manage", "Manage MCP clients and DCR settings"),
+};
+
+/**
+ * All AI access rules for registration with the plugin system.
+ */
+export const aiAccessRules = [
+  aiAccess.chatUse,
+  aiAccess.toolsManage,
+  aiAccess.mcpManage,
+];

package/src/capability-summary.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, test } from "bun:test";
+import type { RawCapabilityEntry } from "./capability-summary";
+import {
+  applyCapabilitySizeGate,
+  summarizeConfigSchema,
+  summarizeFieldType,
+  CAPABILITY_SUMMARY_ENTRY_CAP,
+} from "./capability-summary";
+
+describe("summarizeFieldType (pure)", () => {
+  test("maps primitive JSON Schema types", () => {
+    expect(summarizeFieldType({ property: { type: "string" } })).toBe("string");
+    expect(summarizeFieldType({ property: { type: "boolean" } })).toBe(
+      "boolean",
+    );
+    expect(summarizeFieldType({ property: { type: "number" } })).toBe("number");
+    expect(summarizeFieldType({ property: { type: "integer" } })).toBe("number");
+    expect(summarizeFieldType({ property: { type: "array" } })).toBe("array");
+    expect(summarizeFieldType({ property: { type: "object" } })).toBe("object");
+  });
+
+  test("detects enum and union shapes ahead of the base type", () => {
+    expect(
+      summarizeFieldType({ property: { type: "string", enum: ["a", "b"] } }),
+    ).toBe("enum");
+    expect(
+      summarizeFieldType({ property: { anyOf: [{ type: "string" }] } }),
+    ).toBe("union");
+    expect(
+      summarizeFieldType({ property: { oneOf: [{ type: "number" }] } }),
+    ).toBe("union");
+  });
+
+  test("handles array-typed `type` (nullable) and unknown nodes", () => {
+    expect(summarizeFieldType({ property: { type: ["string", "null"] } })).toBe(
+      "string|null",
+    );
+    expect(summarizeFieldType({ property: {} })).toBe("unknown");
+    expect(summarizeFieldType({ property: 42 })).toBe("unknown");
+    expect(summarizeFieldType({ property: null })).toBe("unknown");
+  });
+});
+
+describe("summarizeConfigSchema (pure)", () => {
+  test("derives name + type + required per property", () => {
+    const summary = summarizeConfigSchema({
+      configSchema: {
+        type: "object",
+        properties: {
+          url: { type: "string" },
+          method: { type: "string", enum: ["GET", "POST"] },
+          retries: { type: "integer" },
+          insecure: { type: "boolean" },
+        },
+        required: ["url", "method"],
+      },
+    });
+    expect(summary).toEqual([
+      { name: "url", type: "string", required: true },
+      { name: "method", type: "enum", required: true },
+      { name: "retries", type: "number", required: false },
+      { name: "insecure", type: "boolean", required: false },
+    ]);
+  });
+
+  test("returns undefined for a schema with no properties", () => {
+    expect(
+      summarizeConfigSchema({ configSchema: { type: "object" } }),
+    ).toBeUndefined();
+    expect(
+      summarizeConfigSchema({ configSchema: {} }),
+    ).toBeUndefined();
+  });
+
+  test("returns undefined for non-object / non-schema input", () => {
+    expect(summarizeConfigSchema({ configSchema: null })).toBeUndefined();
+    expect(summarizeConfigSchema({ configSchema: "nope" })).toBeUndefined();
+    expect(summarizeConfigSchema({ configSchema: 7 })).toBeUndefined();
+  });
+
+  test("an empty properties object yields undefined, not []", () => {
+    expect(
+      summarizeConfigSchema({
+        configSchema: { type: "object", properties: {} },
+      }),
+    ).toBeUndefined();
+  });
+});
+
+function makeEntry(id: string): RawCapabilityEntry {
+  return {
+    id,
+    displayName: id,
+    role: "collector",
+    configSummary: [{ name: "x", type: "string", required: true }],
+  };
+}
+
+describe("applyCapabilitySizeGate (pure)", () => {
+  test("keeps summaries and truncated=false at or below the cap", () => {
+    const entries = Array.from({ length: CAPABILITY_SUMMARY_ENTRY_CAP }, (_, i) =>
+      makeEntry(`c${i}`),
+    );
+    const gated = applyCapabilitySizeGate({ entries });
+    expect(gated.truncated).toBe(false);
+    expect(gated.entries).toHaveLength(CAPABILITY_SUMMARY_ENTRY_CAP);
+    expect(gated.entries.every((e) => e.configSummary !== undefined)).toBe(true);
+  });
+
+  test("strips summaries and sets truncated=true above the cap", () => {
+    const entries = Array.from(
+      { length: CAPABILITY_SUMMARY_ENTRY_CAP + 1 },
+      (_, i) => makeEntry(`c${i}`),
+    );
+    const gated = applyCapabilitySizeGate({ entries });
+    expect(gated.truncated).toBe(true);
+    // Identity + role survive; only the per-entry summary is dropped.
+    expect(gated.entries).toHaveLength(CAPABILITY_SUMMARY_ENTRY_CAP + 1);
+    expect(gated.entries.every((e) => e.configSummary === undefined)).toBe(true);
+    expect(gated.entries[0].id).toBe("c0");
+    expect(gated.entries[0].role).toBe("collector");
+  });
+
+  test("honors a custom entry cap", () => {
+    const entries = [makeEntry("a"), makeEntry("b"), makeEntry("c")];
+    const gated = applyCapabilitySizeGate({ entries, entryCap: 2 });
+    expect(gated.truncated).toBe(true);
+    expect(gated.entries.every((e) => e.configSummary === undefined)).toBe(true);
+  });
+
+  test("empty catalog is not truncated", () => {
+    const gated = applyCapabilitySizeGate({ entries: [] });
+    expect(gated.truncated).toBe(false);
+    expect(gated.entries).toEqual([]);
+  });
+});

package/src/capability-summary.ts

@@ -0,0 +1,122 @@
+import { z } from "zod";
+import type { CapabilityEntry, CapabilityFieldSummary } from "./context-tools";
+
+/**
+ * The maximum number of entries a `listCapabilities` catalog may carry a
+ * per-entry `configSummary` for. Above this the summaries are dropped (the
+ * catalog still returns identity + role for every entry) and `truncated` is
+ * flagged, so the broad catalog stays small in the model's context window and
+ * the model pulls a single kind's FULL schema on demand via
+ * `getCapabilitySchema`.
+ */
+export const CAPABILITY_SUMMARY_ENTRY_CAP = 12;
+
+/**
+ * Minimal structural shape of a JSON Schema we read to derive a compact field
+ * summary. We never trust the input to be a full draft - we narrow defensively
+ * and treat anything we cannot read as "no derivable fields".
+ */
+const JsonSchemaShape = z.object({
+  type: z.unknown().optional(),
+  properties: z.record(z.string(), z.unknown()).optional(),
+  required: z.array(z.string()).optional(),
+});
+
+const PropertyShape = z.object({
+  type: z.unknown().optional(),
+  enum: z.array(z.unknown()).optional(),
+  format: z.string().optional(),
+  items: z.unknown().optional(),
+  anyOf: z.array(z.unknown()).optional(),
+  oneOf: z.array(z.unknown()).optional(),
+});
+
+/**
+ * Derive a short, human/model-readable type label from a single JSON Schema
+ * property node. Deterministic and dependency-free - it never pulls in a JSON
+ * Schema library, so it stays trivially testable.
+ */
+export function summarizeFieldType({ property }: { property: unknown }): string {
+  const parsed = PropertyShape.safeParse(property);
+  if (!parsed.success) return "unknown";
+  const node = parsed.data;
+
+  if (Array.isArray(node.enum) && node.enum.length > 0) return "enum";
+  if (Array.isArray(node.anyOf) && node.anyOf.length > 0) return "union";
+  if (Array.isArray(node.oneOf) && node.oneOf.length > 0) return "union";
+
+  const { type } = node;
+  if (typeof type === "string") {
+    if (type === "array") return "array";
+    if (type === "integer") return "number";
+    return type;
+  }
+  // JSON Schema permits `type` to be an array of strings (e.g. ["string", "null"]).
+  if (Array.isArray(type)) {
+    const labels = type.filter((t): t is string => typeof t === "string");
+    if (labels.length > 0) return labels.join("|");
+  }
+  return "unknown";
+}
+
+/**
+ * Derive the COMPACT field summary (name + type + required) for one config
+ * JSON Schema. Returns `undefined` when the schema has no readable object
+ * properties (so callers can omit `configSummary` entirely rather than emit an
+ * empty array). Pure and deterministic - this is the function the catalog and
+ * its tests pin.
+ */
+export function summarizeConfigSchema({
+  configSchema,
+}: {
+  configSchema: unknown;
+}): CapabilityFieldSummary[] | undefined {
+  const parsed = JsonSchemaShape.safeParse(configSchema);
+  if (!parsed.success) return undefined;
+  const { properties, required } = parsed.data;
+  if (!properties) return undefined;
+
+  const requiredSet = new Set<string>(required);
+  const fields: CapabilityFieldSummary[] = Object.keys(properties).map(
+    (name) => ({
+      name,
+      type: summarizeFieldType({ property: properties[name] }),
+      required: requiredSet.has(name),
+    }),
+  );
+  if (fields.length === 0) return undefined;
+  return fields;
+}
+
+/**
+ * A catalog entry BEFORE size-gating: it always carries the derived compact
+ * summary; the gate decides whether the summary survives into the wire output.
+ */
+export interface RawCapabilityEntry extends Omit<CapabilityEntry, "configSummary"> {
+  configSummary?: CapabilityFieldSummary[];
+}
+
+/**
+ * Apply the size gate to a fully-derived catalog. When the catalog has more
+ * than {@link CAPABILITY_SUMMARY_ENTRY_CAP} entries, every entry's
+ * `configSummary` is stripped (identity/role survive) and `truncated` is set.
+ * Otherwise the summaries are kept as-is. Pure - no I/O, deterministic in the
+ * input ordering.
+ */
+export function applyCapabilitySizeGate({
+  entries,
+  entryCap = CAPABILITY_SUMMARY_ENTRY_CAP,
+}: {
+  entries: RawCapabilityEntry[];
+  entryCap?: number;
+}): { entries: CapabilityEntry[]; truncated: boolean } {
+  const overCap = entries.length > entryCap;
+  const gated: CapabilityEntry[] = entries.map((entry) => {
+    if (overCap) {
+      const { configSummary: _omit, ...rest } = entry;
+      return rest;
+    }
+    return entry;
+  });
+  return { entries: gated, truncated: overCap };
+}

package/src/context-tools.ts

@@ -0,0 +1,205 @@
+import { z } from "zod";
+
+/**
+ * Context taxonomy + wire schemas for the AI assistant's context tools (the
+ * script context tools, §2.1-§2.3, and the capability catalog, §2.4, of the
+ * AI-assistant context-tools plan). These are transport-facing zod schemas
+ * only; the builders + handlers live in `@checkstack/ai-backend`.
+ */
+
+/**
+ * WHERE a script lives. The available SDK symbols + the test runner differ per
+ * value, so the model must name the context before it asks for symbols or runs
+ * a draft. The enum carries all four contexts from day one so the wire contract
+ * never has to widen (OQ-1).
+ */
+export const ScriptContextKindSchema = z.enum([
+  "healthcheck-script", // inline TS health-check collector
+  "healthcheck-shell", // shell health-check collector
+  "automation-action-script", // run_script automation action (TS)
+  "automation-action-shell", // run_shell automation action
+]);
+export type ScriptContextKind = z.infer<typeof ScriptContextKindSchema>;
+
+/**
+ * WHICH capability catalog the model wants from `ai.listCapabilities` (Phase 3).
+ * Distinguishes the two registry substrates the editors read from: health-check
+ * strategies/collectors and automation triggers/actions/artifact-types. GitOps
+ * kinds are intentionally out of v1 scope (OQ-5). Defined here alongside the
+ * script taxonomy per §2.1 so the whole context vocabulary lives in one module.
+ */
+export const CapabilityContextKindSchema = z.enum([
+  "healthcheck", // strategies + collectors
+  "automation", // triggers + actions + artifact types
+]);
+export type CapabilityContextKind = z.infer<typeof CapabilityContextKindSchema>;
+
+// ───────────────────────── ai.getScriptContext (§2.2) ─────────────────────
+
+export const GetScriptContextInputSchema = z.object({
+  context: ScriptContextKindSchema,
+});
+export type GetScriptContextInput = z.infer<typeof GetScriptContextInputSchema>;
+
+/** A single injected `CHECKSTACK_*` env var the shell runner exposes. */
+export const ShellEnvVarSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+});
+export type ShellEnvVar = z.infer<typeof ShellEnvVarSchema>;
+
+export const GetScriptContextOutputSchema = z.object({
+  context: ScriptContextKindSchema,
+  /** Editor language for this context. */
+  language: z.enum(["typescript", "shell"]),
+  /** The SDK module the script imports from (TS contexts only). */
+  sdkModule: z.string().optional(),
+  /** The define-helper name (TS contexts only). */
+  helper: z.string().optional(),
+  /**
+   * The relevant `.d.ts` declarations for THIS context, extracted from the
+   * generated SDK editor bundle (the SAME types Monaco mounts). For a TS
+   * context this is the context's `declare module` block; for a shell context
+   * it is a human-readable list of the injected `CHECKSTACK_*` env vars.
+   */
+  declarations: z.string(),
+  /** Injected shell env vars (shell contexts only). */
+  shellEnv: z.array(ShellEnvVarSchema).optional(),
+  /** A minimal runnable starter the model can adapt. */
+  starterExample: z.string(),
+  /** Whether managed npm packages are importable in this context. */
+  allowsManagedPackages: z.boolean(),
+});
+export type GetScriptContextOutput = z.infer<
+  typeof GetScriptContextOutputSchema
+>;
+
+// ───────────────────────── ai.testScript (§2.3) ───────────────────────────
+
+export const TestScriptInputSchema = z.object({
+  context: ScriptContextKindSchema,
+  source: z.string().min(1).max(100_000),
+  /** Collector/action config the script reads via context.config / fields. */
+  config: z.record(z.string(), z.unknown()).optional(),
+  /** Sample runtime context (check/system/environment, or event/subscription). */
+  sampleContext: z.record(z.string(), z.unknown()).optional(),
+  /** Shell-only: extra env. Never carries real secrets (placeholders only). */
+  env: z.record(z.string(), z.string()).optional(),
+  /** Bounded; defaults to a short ceiling well under the runner's max. */
+  timeoutMs: z.number().int().min(100).max(30_000).default(10_000),
+});
+export type TestScriptInput = z.infer<typeof TestScriptInputSchema>;
+
+export const TestScriptOutputSchema = z.object({
+  /** The default-export / return value the script produced (masked). */
+  result: z.unknown().optional(),
+  stdout: z.string(),
+  stderr: z.string(),
+  exitCode: z.number().int().optional(),
+  durationMs: z.number().int().nonnegative(),
+  timedOut: z.boolean(),
+  error: z.string().optional(),
+  /** What the sandbox actually enforced/degraded (surfaced, never silent). */
+  sandboxDowngraded: z.boolean(),
+});
+export type TestScriptOutput = z.infer<typeof TestScriptOutputSchema>;
+
+// ───────────────────────── ai.listCapabilities (§2.4) ──────────────────────
+
+/** The normalized role of a single catalog entry across both registries. */
+export const CapabilityRoleSchema = z.enum([
+  "strategy",
+  "collector",
+  "trigger",
+  "action",
+  "artifact-type",
+]);
+export type CapabilityRole = z.infer<typeof CapabilityRoleSchema>;
+
+/**
+ * A COMPACT description of one config field, derived from the entry's full
+ * JSON Schema. This is what `listCapabilities` returns per entry so the broad
+ * catalog stays small; the model pulls the FULL schema for a single kind via
+ * `getCapabilitySchema` only when it is actually configuring that kind.
+ */
+export const CapabilityFieldSummarySchema = z.object({
+  name: z.string(),
+  /** A short type label derived from the JSON Schema (e.g. "string", "enum"). */
+  type: z.string(),
+  required: z.boolean(),
+});
+export type CapabilityFieldSummary = z.infer<
+  typeof CapabilityFieldSummarySchema
+>;
+
+/** A catalog entry, normalized across both registries. */
+export const CapabilityEntrySchema = z.object({
+  /** Fully-qualified id (e.g. "healthcheck-http.http", "incident.created"). */
+  id: z.string(),
+  displayName: z.string(),
+  description: z.string().optional(),
+  role: CapabilityRoleSchema,
+  category: z.string().optional(),
+  /**
+   * A compact, size-gated summary of the config fields (names + types +
+   * required). Omitted when the entry's schema has no derivable object fields.
+   */
+  configSummary: z.array(CapabilityFieldSummarySchema).optional(),
+});
+export type CapabilityEntry = z.infer<typeof CapabilityEntrySchema>;
+
+export const ListCapabilitiesInputSchema = z.object({
+  context: CapabilityContextKindSchema,
+});
+export type ListCapabilitiesInput = z.infer<typeof ListCapabilitiesInputSchema>;
+
+export const ListCapabilitiesOutputSchema = z.object({
+  context: CapabilityContextKindSchema,
+  entries: z.array(CapabilityEntrySchema),
+  /**
+   * True when per-entry `configSummary` was dropped to fit the context budget
+   * (the catalog had more than the entry cap). Identity/role data is always
+   * returned; the model then pulls a single kind's full schema on demand.
+   */
+  truncated: z.boolean(),
+});
+export type ListCapabilitiesOutput = z.infer<
+  typeof ListCapabilitiesOutputSchema
+>;
+
+export const GetCapabilitySchemaInputSchema = z.object({
+  context: CapabilityContextKindSchema,
+  /** The fully-qualified kind id from a `listCapabilities` entry. */
+  kind: z.string().min(1),
+});
+export type GetCapabilitySchemaInput = z.infer<
+  typeof GetCapabilitySchemaInputSchema
+>;
+
+export const GetCapabilitySchemaOutputSchema = z.object({
+  context: CapabilityContextKindSchema,
+  id: z.string(),
+  displayName: z.string(),
+  description: z.string().optional(),
+  role: CapabilityRoleSchema,
+  /**
+   * The FULL config JSON Schema for this one kind - the same schema that powers
+   * the UI config form, returned intact (field shapes, types, required, enums).
+   */
+  configSchema: z.record(z.string(), z.unknown()),
+  /**
+   * Health-check COLLECTORS only: the result JSON Schema whose top-level fields
+   * are the ASSERTABLE fields. Author an assertion's `field` from these (e.g.
+   * `statusCode`), not a guessed name. Omitted for non-collector kinds.
+   */
+  resultSchema: z.record(z.string(), z.unknown()).optional(),
+  /**
+   * Health-check COLLECTORS only: the valid assertion operators per JSON type
+   * (and `jsonpath`). An assertion's `operator` MUST be one of these full words
+   * (e.g. `equals`, `greaterThanOrEqual`), never an abbreviation like `eq`.
+   */
+  assertionOperators: z.record(z.string(), z.array(z.string())).optional(),
+});
+export type GetCapabilitySchemaOutput = z.infer<
+  typeof GetCapabilitySchemaOutputSchema
+>;

package/src/docs-tools.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+
+/**
+ * Wire contracts for the AI assistant's documentation-grounding tools
+ * (`ai.searchDocs` + `ai.getDoc`, plan §2.5). Both tools are `effect: "read"`
+ * and gated by `ai.chat.read`: any chat user may read the platform's own public
+ * documentation; the docs carry no per-tenant data.
+ *
+ * The docs themselves are a build-time bundled index in `@checkstack/ai-backend`
+ * (plan §3.4) — these schemas live in `-common` so the contract is shared.
+ */
+
+export const SearchDocsInputSchema = z.object({
+  query: z.string().min(1).max(400),
+  /** Max ranked hits to return (capped server-side; see size budget §3.4). */
+  limit: z.number().int().min(1).max(10).default(5),
+});
+export type SearchDocsInput = z.infer<typeof SearchDocsInputSchema>;
+
+/** One ranked doc hit: enough for the model to decide whether to getDoc it. */
+export const DocHitSchema = z.object({
+  /** Slug-based address, e.g. "user-guide/concepts/health-checks". */
+  slug: z.string(),
+  title: z.string(),
+  /** Section heading the snippet came from (when the hit is a sub-section). */
+  heading: z.string().optional(),
+  /** The matching snippet (bounded length), highlighting why it matched. */
+  snippet: z.string(),
+  /** BM25-ish relevance score (opaque ordering hint). */
+  score: z.number(),
+});
+export type DocHit = z.infer<typeof DocHitSchema>;
+
+export const SearchDocsOutputSchema = z.object({
+  hits: z.array(DocHitSchema),
+});
+export type SearchDocsOutput = z.infer<typeof SearchDocsOutputSchema>;
+
+export const GetDocInputSchema = z.object({
+  slug: z.string().min(1),
+});
+export type GetDocInput = z.infer<typeof GetDocInputSchema>;
+
+export const GetDocOutputSchema = z.object({
+  slug: z.string(),
+  title: z.string(),
+  description: z.string().optional(),
+  /** Full page content (markdown, frontmatter stripped), bounded; see §3.4. */
+  content: z.string(),
+  /** True when content was truncated to the size budget. */
+  truncated: z.boolean(),
+});
+export type GetDocOutput = z.infer<typeof GetDocOutputSchema>;

package/src/field-diff.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, test } from "bun:test";
+import { computeFieldDiff } from "./field-diff";
+
+describe("computeFieldDiff", () => {
+  test("no change yields an empty diff", () => {
+    expect(
+      computeFieldDiff({ before: { a: 1, b: "x" }, after: { a: 1, b: "x" } }),
+    ).toEqual([]);
+  });
+
+  test("reports a changed scalar with a dotted path", () => {
+    const diff = computeFieldDiff({
+      before: { intervalSeconds: 60 },
+      after: { intervalSeconds: 30 },
+    });
+    expect(diff).toEqual([{ path: "intervalSeconds", before: 60, after: 30 }]);
+  });
+
+  test("recurses into nested objects with dotted paths", () => {
+    const diff = computeFieldDiff({
+      before: { config: { url: "https://a", method: "GET" } },
+      after: { config: { url: "https://b", method: "GET" } },
+    });
+    expect(diff).toEqual([
+      { path: "config.url", before: "https://a", after: "https://b" },
+    ]);
+  });
+
+  test("recurses into arrays element-wise (added element)", () => {
+    const diff = computeFieldDiff({
+      before: { collectors: [{ id: "a" }] },
+      after: { collectors: [{ id: "a" }, { id: "b" }] },
+    });
+    // The unchanged element [0] produces no row; only the added [1] surfaces.
+    expect(diff).toEqual([
+      { path: "collectors[1]", before: undefined, after: { id: "b" } },
+    ]);
+  });
+
+  test("surfaces a single changed field deep inside an array element", () => {
+    const diff = computeFieldDiff({
+      before: { collectors: [{ id: "a", config: { script: "old" } }] },
+      after: { collectors: [{ id: "a", config: { script: "new" } }] },
+    });
+    expect(diff).toEqual([
+      {
+        path: "collectors[0].config.script",
+        before: "old",
+        after: "new",
+      },
+    ]);
+  });
+
+  test("an element removed from the array surfaces against undefined", () => {
+    const diff = computeFieldDiff({
+      before: { tags: ["a", "b"] },
+      after: { tags: ["a"] },
+    });
+    expect(diff).toEqual([
+      { path: "tags[1]", before: "b", after: undefined },
+    ]);
+  });
+
+  test("a value that changes shape (array <-> scalar) is one diff", () => {
+    const diff = computeFieldDiff({
+      before: { x: [1, 2] },
+      after: { x: "now a string" },
+    });
+    expect(diff).toEqual([
+      { path: "x", before: [1, 2], after: "now a string" },
+    ]);
+  });
+
+  test("captures added and removed fields", () => {
+    const diff = computeFieldDiff({
+      before: { a: 1 },
+      after: { b: 2 },
+    });
+    expect(diff).toEqual([
+      { path: "a", before: 1, after: undefined },
+      { path: "b", before: undefined, after: 2 },
+    ]);
+  });
+
+  test("is order-insensitive for object keys", () => {
+    expect(
+      computeFieldDiff({ before: { a: 1, b: 2 }, after: { b: 2, a: 1 } }),
+    ).toEqual([]);
+  });
+});

package/src/field-diff.ts

@@ -0,0 +1,85 @@
+import type { AiFieldDiff } from "./tool";
+
+/**
+ * Compute a leaf-level before -> after diff between two values, used to show what
+ * an UPDATE proposal actually changes. Walks plain objects recursively (dotted
+ * paths) AND arrays element-wise (`field[i]` paths), so a single changed item in
+ * a list - e.g. one collector's script in `collectors[0].config.script` - is
+ * surfaced on its own instead of dumping the whole array as one opaque blob.
+ * Scalars (and a value that changes shape, e.g. array <-> object) are compared by
+ * value via canonical JSON. Added/removed fields and array elements surface with
+ * `before`/`after` set to `undefined`.
+ *
+ * Pure and total: never throws. Returns an empty array when nothing changed.
+ */
+export function computeFieldDiff({
+  before,
+  after,
+}: {
+  before: unknown;
+  after: unknown;
+}): AiFieldDiff[] {
+  const diffs: AiFieldDiff[] = [];
+  walk({ before, after, path: "", diffs });
+  return diffs;
+}
+
+/** True for a plain object (not null, not an array). */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Deep equality via canonical (sorted-key) JSON - sufficient for config bags. */
+function deepEqual(a: unknown, b: unknown): boolean {
+  return canonical(a) === canonical(b);
+}
+
+function canonical(value: unknown): string {
+  if (value === undefined) return "undefined";
+  if (!isPlainObject(value)) return JSON.stringify(value) ?? "null";
+  const keys = Object.keys(value).toSorted();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`).join(",")}}`;
+}
+
+function walk({
+  before,
+  after,
+  path,
+  diffs,
+}: {
+  before: unknown;
+  after: unknown;
+  path: string;
+  diffs: AiFieldDiff[];
+}): void {
+  if (isPlainObject(before) && isPlainObject(after)) {
+    const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+    for (const key of [...keys].toSorted()) {
+      walk({
+        before: before[key],
+        after: after[key],
+        path: path ? `${path}.${key}` : key,
+        diffs,
+      });
+    }
+    return;
+  }
+  // Arrays recurse element-wise so a single changed item (a collector, an
+  // assertion) is its own diff row, not the whole serialized list. A length
+  // change surfaces the added/removed elements against `undefined`.
+  if (Array.isArray(before) && Array.isArray(after)) {
+    const length = Math.max(before.length, after.length);
+    for (let index = 0; index < length; index += 1) {
+      walk({
+        before: before[index],
+        after: after[index],
+        path: `${path}[${index}]`,
+        diffs,
+      });
+    }
+    return;
+  }
+  if (!deepEqual(before, after)) {
+    diffs.push({ path: path || "(root)", before, after });
+  }
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export * from "./access";
+export * from "./docs-tools";
+export * from "./permission";
+export * from "./plugin-metadata";
+export * from "./tool";
+export * from "./context-tools";
+export * from "./field-diff";
+export * from "./capability-summary";
+export * from "./integration";
+export * from "./rpc-contract";
+export * from "./routes";

package/src/integration.ts

@@ -0,0 +1,47 @@
+/**
+ * Shape of an OpenAI-compatible integration connection.
+ *
+ * The runtime zod schema (with `x-secret` on `apiKey` and the `Versioned`
+ * wrapper) lives in `@checkstack/ai-backend` because it depends on backend-only
+ * helpers (`configString` / `Versioned`). This type is the cross-package
+ * contract for the same shape.
+ *
+ * Model choice is a property of the credential / provider (decision §14.6), so
+ * it lives on the connection, not a separate global setting:
+ * - `baseUrl`     — provider base URL (default `https://api.openai.com/v1`).
+ * - `apiKey`      — secret API key (`x-secret`, stored in the Secrets Vault).
+ * - `defaultModel` — required; used unless a conversation overrides it.
+ * - `availableModels` — optional allowlist; when present the chat model picker
+ *   is constrained to it, otherwise a free-text field is shown (Phase 4).
+ * - `spendCap` — OPTIONAL per-integration LLM spend cap (Phase 6). Off unless
+ *   configured. A token-count budget over a rolling window, enforced server-side
+ *   and counted across all pods from the shared `ai_spend` ledger.
+ */
+export interface OpenAiCompatibleConnection {
+  baseUrl: string;
+  apiKey: string;
+  defaultModel: string;
+  availableModels?: string[];
+  spendCap?: AiSpendCap;
+}
+
+/**
+ * Optional per-integration LLM spend cap (Phase 6). Token-count, not USD:
+ * deterministic and provider-agnostic (OpenAI / Azure / OpenRouter / Ollama /
+ * vLLM all report tokens via the AI SDK; only some have a price table). When set,
+ * the chat agent loop refuses a new turn once the principal's token usage against
+ * this integration in the trailing `windowMinutes` reaches `tokenBudget`. Absent
+ * = no cap.
+ */
+export interface AiSpendCap {
+  /** Max total tokens (input + output) per principal per window. Must be > 0. */
+  tokenBudget: number;
+  /** Rolling window length in minutes the budget is measured over. Must be > 0. */
+  windowMinutes: number;
+}
+
+/** Local provider id; namespaced on registration to `ai.openai-compatible`. */
+export const OPENAI_COMPATIBLE_PROVIDER_LOCAL_ID = "openai-compatible";
+
+/** Default OpenAI-compatible base URL. */
+export const OPENAI_COMPATIBLE_DEFAULT_BASE_URL = "https://api.openai.com/v1";

package/src/permission.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+
+/**
+ * Per-conversation permission mode (Phase 4), Claude-Code-style. Governs ONLY
+ * the `mutate` tool branch; reads and destructive tools are NEVER governed by it
+ * (see the gating tiers below).
+ *
+ * The three gating tiers, keyed on a tool's `effect`:
+ *
+ *  - `read` -> ALWAYS auto-runs, in BOTH modes. Reads are never gated.
+ *  - `mutate` -> INHERITS the mode. `auto` auto-applies SERVER-SIDE (the model's
+ *    `propose` is applied immediately under the SAME `isAllowed` re-check + audit
+ *    the human `applyTool` path uses); `approve` surfaces a confirm card the
+ *    operator must approve via `applyTool`.
+ *  - `destructive` -> ALWAYS requires the human `applyTool`, in BOTH modes. The
+ *    mode is NEVER consulted for destructive tools.
+ *
+ * SECURITY INVARIANT: destructive tools can never auto-apply. The mode has NO
+ * parameter into the destructive apply path - it only governs the `mutate`
+ * branch.
+ */
+export const AiPermissionModeSchema = z.enum(["approve", "auto"]);
+export type AiPermissionMode = z.infer<typeof AiPermissionModeSchema>;
+
+/** Safe-by-default: a new conversation requires human approval for changes. */
+export const DEFAULT_PERMISSION_MODE: AiPermissionMode = "approve";

package/src/plugin-metadata.ts

@@ -0,0 +1,9 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+/**
+ * Plugin metadata for the AI platform plugin.
+ * Exported from the common package so both backend and frontend can reference it.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "ai",
+});

package/src/routes.ts

@@ -0,0 +1,6 @@
+import { createRoutes } from "@checkstack/common";
+
+/** Route definitions for the AI platform frontend (Phase 4 chat). */
+export const aiRoutes = createRoutes("ai", {
+  chat: "/chat",
+});

package/src/rpc-contract.ts

@@ -0,0 +1,214 @@
+import { z } from "zod";
+import { createClientDefinition, proc } from "@checkstack/common";
+import { aiAccess } from "./access";
+import { AiPermissionModeSchema } from "./permission";
+import { pluginMetadata } from "./plugin-metadata";
+import { AiToolDescriptorSchema } from "./tool";
+
+/**
+ * AI platform RPC contract.
+ *
+ * Phase 1 exposes a single read-only introspection endpoint: `listTools`
+ * returns the resolver output for the calling principal (the tools they are
+ * allowed to see). Mutating tool flows (propose / apply), conversations, and
+ * MCP-client management land in later phases and are intentionally absent here.
+ *
+ * `listTools` is gated by `ai.tools-manage`. The returned descriptors carry
+ * only JSON Schema — never an executor or any `x-secret` value.
+ */
+/**
+ * A proposal returned by `proposeTool`. The `token` is the opaque
+ * `propose:<rowId>.<nonce>` consumed by `applyTool` (single-use, 10-min TTL).
+ * The `payload` is the validated, ready-to-apply draft (e.g. an automation
+ * definition) the confirm card / editor renders. No secret ever appears here.
+ */
+export const AiProposalSchema = z.object({
+  token: z.string(),
+  summary: z.string(),
+  payload: z.unknown(),
+  toolCallId: z.string(),
+  expiresAt: z.coerce.date(),
+});
+export type AiProposal = z.infer<typeof AiProposalSchema>;
+
+/**
+ * A selectable AI integration for the chat picker (Phase 4, §14.6). Carries
+ * only non-secret model UX metadata — NEVER the apiKey.
+ */
+export const AiChatIntegrationSchema = z.object({
+  /** Qualified connection id. */
+  connectionId: z.string(),
+  name: z.string(),
+  /** The connection's default model id (the picker defaults to this). */
+  defaultModel: z.string(),
+  /** Optional allowlist constraining the model picker. */
+  availableModels: z.array(z.string()).optional(),
+});
+export type AiChatIntegration = z.infer<typeof AiChatIntegrationSchema>;
+
+/** A chat conversation summary (Phase 4). Never carries a secret. */
+export const AiConversationSchema = z.object({
+  id: z.string(),
+  title: z.string().nullable(),
+  integrationId: z.string().nullable(),
+  model: z.string().nullable(),
+  /**
+   * Per-conversation permission mode (Phase 4). Governs the `mutate` tool branch
+   * only: `auto` auto-applies mutate proposals server-side; `approve` surfaces a
+   * confirm card. Reads always run; destructive always requires human apply.
+   */
+  permissionMode: AiPermissionModeSchema,
+  createdAt: z.coerce.date(),
+  updatedAt: z.coerce.date(),
+});
+export type AiConversation = z.infer<typeof AiConversationSchema>;
+
+/** A persisted chat message (Phase 4). */
+export const AiMessageSchema = z.object({
+  id: z.string(),
+  conversationId: z.string(),
+  role: z.enum(["system", "user", "assistant", "tool"]),
+  content: z.record(z.string(), z.unknown()),
+  toolCalls: z.array(z.record(z.string(), z.unknown())).nullable(),
+  createdAt: z.coerce.date(),
+});
+export type AiMessage = z.infer<typeof AiMessageSchema>;
+
+export const aiContract = {
+  listTools: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [aiAccess.toolsManage],
+  }).output(z.object({ tools: z.array(AiToolDescriptorSchema) })),
+
+  /**
+   * Step 1 of the two-step mutating-tool flow: run the tool's dry-run and
+   * return a proposal token. NEVER mutates. Per-tool authorization is enforced
+   * by the propose/apply service against the tool's `requiredAccessRules`.
+   */
+  proposeTool: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [aiAccess.chatUse],
+  })
+    .input(
+      z.object({
+        toolName: z.string(),
+        input: z.unknown(),
+      }),
+    )
+    .output(AiProposalSchema),
+
+  /**
+   * Step 2: consume a proposal token and commit. Single-use and atomic — a
+   * second apply, an expired token, or a tampered nonce is rejected.
+   */
+  applyTool: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [aiAccess.chatUse],
+  })
+    .input(z.object({ token: z.string() }))
+    .output(z.object({ toolCallId: z.string(), result: z.unknown() })),
+
+  // ─── Phase 4: chat conversation management ──────────────────────────────
+  // The streaming turn itself is a raw HTTP handler at /api/ai/chat (SSE);
+  // these RPCs manage the durable conversation list/transcript (shared Postgres
+  // — continuable from any pod). All are owner-scoped server-side.
+
+  /**
+   * List the AI integrations a chat user may select (§14.6). Gated by
+   * `ai.chat.read` (NOT integration-manage), and returns only non-secret model
+   * UX metadata so a chat-only user can pick a provider + model.
+   */
+  listChatIntegrations: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [aiAccess.chatUse],
+  }).output(z.object({ integrations: z.array(AiChatIntegrationSchema) })),
+
+  listConversations: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [aiAccess.chatUse],
+  }).output(z.object({ conversations: z.array(AiConversationSchema) })),
+
+  createConversation: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [aiAccess.chatUse],
+  })
+    .input(
+      z.object({
+        title: z.string().max(200).optional(),
+        integrationId: z.string().optional(),
+        model: z.string().optional(),
+        permissionMode: AiPermissionModeSchema.optional(),
+      }),
+    )
+    .output(AiConversationSchema),
+
+  getConversation: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [aiAccess.chatUse],
+  })
+    .input(z.object({ id: z.string() }))
+    .output(
+      z.object({
+        conversation: AiConversationSchema,
+        messages: z.array(AiMessageSchema),
+      }),
+    ),
+
+  updateConversation: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [aiAccess.chatUse],
+  })
+    .input(
+      z.object({
+        id: z.string(),
+        title: z.string().max(200).optional(),
+        model: z.string().optional(),
+        permissionMode: AiPermissionModeSchema.optional(),
+      }),
+    )
+    .output(AiConversationSchema),
+
+  /**
+   * SOFT-DELETE a conversation: the user-facing "Delete" action ARCHIVES the
+   * chat (stamps `archivedAt`) so the row + transcript are retained for later
+   * abuse introspection while disappearing from the sidebar. Owner-scoped
+   * server-side, gated identically to the other conversation mutations.
+   */
+  archiveConversation: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [aiAccess.chatUse],
+  })
+    .input(z.object({ id: z.string() }))
+    .output(z.object({ archived: z.boolean() })),
+
+  deleteConversation: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [aiAccess.chatUse],
+  })
+    .input(z.object({ id: z.string() }))
+    .output(z.object({ deleted: z.boolean() })),
+};
+
+export type AiContract = typeof aiContract;
+
+/**
+ * Client definition for typed cross-plugin / frontend access to the AI
+ * contract.
+ */
+export const aiClientDefinition = createClientDefinition(
+  aiContract,
+  pluginMetadata,
+);
+
+/** Conventional `*Api` alias for frontend `usePluginClient(AiApi)` usage. */
+export const AiApi = aiClientDefinition;

package/src/tool.ts

@@ -0,0 +1,127 @@
+import { z } from "zod";
+
+/**
+ * Effect classification for an AI tool. REQUIRED on every tool and never
+ * inferred from the procedure verb — a `mutation` operationType is not the
+ * same as a destructive effect.
+ *
+ * - `read`: pure read; auto-runs in chat and over MCP.
+ * - `mutate`: changes state; gated behind the two-step propose -> apply flow
+ *   (Phase 3).
+ * - `destructive`: irreversible state change; same propose -> apply gate, with
+ *   stronger confirmation UX.
+ */
+export const AiToolEffectSchema = z.enum(["read", "mutate", "destructive"]);
+export type AiToolEffect = z.infer<typeof AiToolEffectSchema>;
+
+/**
+ * One changed field in a before -> after diff, surfaced on a confirm/applied card
+ * so the operator always sees exactly WHAT changed (especially for updates), in
+ * both approve and auto modes. `path` is a dotted field path; a `before` of
+ * `undefined` means the field was added, an `after` of `undefined` means removed.
+ */
+export interface AiFieldDiff {
+  path: string;
+  before: unknown;
+  after: unknown;
+}
+
+/**
+ * Human-readable preview returned by a tool's `dryRun` and shown on a confirm
+ * card (chat) or returned for a follow-up `apply` call (MCP). Phase 3 consumes
+ * the `payload`; Phase 1 only defines the shape.
+ */
+export interface AiProposalPreview<TPayload = unknown> {
+  /** One-line, model/human-facing summary of what `apply` will do. */
+  summary: string;
+  /** The validated, ready-to-apply payload captured at propose time. */
+  payload: TPayload;
+  /**
+   * Optional before -> after diff for an UPDATE proposal. Surfaced on the confirm
+   * card (approve mode) and the applied card (auto mode) so a change is always
+   * visible. Omit for a create (the whole payload is new).
+   */
+  diff?: AiFieldDiff[];
+}
+
+/**
+ * A transport-agnostic, callable AI tool — the spine of the AI platform.
+ *
+ * The same descriptor backs both transports: the internal chat agent loop
+ * (Phase 4) and the external MCP server (Phase 2/3). Its `input` zod schema is
+ * serialized to JSON Schema for both OpenAI function calling and MCP tool defs
+ * via the shared `toJsonSchema()` serializer — there is no second serializer.
+ *
+ * @template TInput  - validated tool input
+ * @template TOutput - tool result shape
+ * @template TPrincipal - the authenticated caller; the backend supplies the
+ *   concrete `AuthUser` type. Kept generic here so `ai-common` does not depend
+ *   on `@checkstack/backend-api`.
+ */
+export interface AiTool<
+  TInput = unknown,
+  TOutput = unknown,
+  TPrincipal = unknown,
+  TRpc = unknown,
+> {
+  /** Auto-qualified by plugin id on registration, e.g. "automation.propose". */
+  name: string;
+  /** Model-facing description (becomes the OpenAI / MCP tool description). */
+  description: string;
+  /** zod input; serialized to JSON Schema via `toJsonSchema()` for both transports. */
+  input: z.ZodType<TInput>;
+  /** Optional zod output; documents the tool result shape to the model. */
+  output?: z.ZodType<TOutput>;
+  /** Effect classification. REQUIRED. Never inferred from the verb. */
+  effect: AiToolEffect;
+  /**
+   * Fully-qualified access-rule IDs the principal must satisfy to see/call
+   * this tool. SAME vocabulary as OAuth scopes AND the `autoAuthMiddleware`
+   * access-rule IDs (`<pluginId>.<resource>.<level>`).
+   */
+  requiredAccessRules: string[];
+  /**
+   * For mutate / destructive tools: optional dry-run used by `propose` (Phase
+   * 3). Returns a human-readable summary plus the validated payload to apply.
+   * Read tools never define this.
+   */
+  dryRun?(args: {
+    input: TInput;
+    principal: TPrincipal;
+    /** USER-scoped RPC client (see `execute`); use it for any plugin call. */
+    rpcClient: TRpc;
+  }): Promise<AiProposalPreview>;
+  /**
+   * The actual call. For mutate / destructive tools this is only reached via
+   * `apply` (Phase 3); read tools call it directly.
+   *
+   * `rpcClient` is a USER-SCOPED client bound to the ORIGINATING user: any
+   * plugin procedure it calls re-enters the live router as that user, so
+   * handler-side authorization (access rules AND per-resource/team scoping) is
+   * enforced exactly as a direct UI/RPC call. A tool MUST use this client for
+   * plugin calls; it must NEVER capture a trusted service client, which would
+   * bypass the user's authorization and broaden access.
+   */
+  execute(args: {
+    input: TInput;
+    principal: TPrincipal;
+    rpcClient: TRpc;
+  }): Promise<TOutput>;
+}
+
+/**
+ * Serialized, transport-facing view of a tool (no executors, no zod). This is
+ * what introspection RPCs and the MCP tool list return — it carries the JSON
+ * Schema for the input, never any executor closure.
+ */
+export const AiToolDescriptorSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  effect: AiToolEffectSchema,
+  /** Input JSON Schema (produced by `toJsonSchema()`). */
+  inputSchema: z.record(z.string(), z.unknown()),
+  /** Output JSON Schema, when the tool declares an `output`. */
+  outputSchema: z.record(z.string(), z.unknown()).optional(),
+  requiredAccessRules: z.array(z.string()),
+});
+export type AiToolDescriptor = z.infer<typeof AiToolDescriptorSchema>;

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "@checkstack/tsconfig/common.json",
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../common"
+    }
+  ]
+}