@checkstack/ai-backend 0.1.0

package/src/chat/conversation-store.ts

@@ -0,0 +1,237 @@
+import { and, asc, desc, eq, isNull } from "drizzle-orm";
+import type { SafeDatabase } from "@checkstack/backend-api";
+import type { AiPermissionMode } from "@checkstack/ai-common";
+import * as schema from "../schema";
+import type {
+  AiConversationRow,
+  AiMessageRow,
+} from "../schema";
+import { scrubContent, scrubModelMessages } from "./scrub-content";
+
+type AiDatabase = SafeDatabase<typeof schema>;
+
+/** A persisted chat message role (AI-SDK roles). */
+export type AiMessageRole = "system" | "user" | "assistant" | "tool";
+
+/**
+ * Durable conversation + message persistence (plan §4, state-and-scale §9).
+ *
+ * All chat state lives in shared Postgres so any pod can list, continue, or
+ * append to a conversation — the agent loop is resumable on whichever pod
+ * handles the next turn. Nothing about a conversation is pod-local. Ownership is
+ * enforced at the handler via the session principal (the store always filters by
+ * `userId` so one user can never read another's chat).
+ */
+export interface AiConversationStore {
+  createConversation(args: {
+    userId: string;
+    title?: string;
+    integrationId?: string;
+    model?: string;
+    /** Permission mode for the conversation; defaults to `approve` when omitted. */
+    permissionMode?: AiPermissionMode;
+  }): Promise<AiConversationRow>;
+
+  /** List a user's conversations, most-recently-updated first. */
+  listConversations(args: { userId: string }): Promise<AiConversationRow[]>;
+
+  /** Fetch one conversation IF it belongs to the user, else undefined. */
+  getConversation(args: {
+    id: string;
+    userId: string;
+  }): Promise<AiConversationRow | undefined>;
+
+  /**
+   * Append a message; bumps the conversation's `updatedAt`. The `content`,
+   * `toolCalls`, and `modelMessages` bags are SCRUBBED of any credential-shaped
+   * key/value before they hit Postgres (see `scrubContent`), so a secret can
+   * never be persisted into message content — an enforced, not merely
+   * architectural, invariant.
+   */
+  appendMessage(args: {
+    conversationId: string;
+    role: AiMessageRole;
+    content: Record<string, unknown>;
+    toolCalls?: Array<Record<string, unknown>>;
+    /**
+     * AI-SDK `ResponseMessage[]` for tool-call REPLAY (assistant tool-call +
+     * tool-result parts). Persisted verbatim (after scrubbing) so a resumed
+     * conversation replays the full prior tool interaction to the model.
+     */
+    modelMessages?: Array<Record<string, unknown>>;
+  }): Promise<AiMessageRow>;
+
+  /** All messages for a conversation, oldest-first (the loop's history). */
+  listMessages(args: {
+    conversationId: string;
+  }): Promise<AiMessageRow[]>;
+
+  /** Update mutable conversation metadata (title / model / permission mode). */
+  updateConversation(args: {
+    id: string;
+    userId: string;
+    title?: string;
+    model?: string;
+    permissionMode?: AiPermissionMode;
+  }): Promise<AiConversationRow | undefined>;
+
+  /**
+   * SOFT-DELETE (archive) a conversation IF it belongs to the user: stamps
+   * `archivedAt = now` so the row + its messages are RETAINED (later abuse
+   * introspection) but the chat disappears from `listConversations`. This is the
+   * user-facing "Delete" action. Returns true when an owned, not-yet-archived row
+   * was stamped, false otherwise (wrong owner / already archived / missing).
+   */
+  archiveConversation(args: { id: string; userId: string }): Promise<boolean>;
+
+  /**
+   * HARD-delete a conversation (cascades to messages) IF it belongs to the user.
+   * NOT exposed to the user-facing delete action (that archives); retained only
+   * for non-user callers such as a retention sweep.
+   */
+  deleteConversation(args: { id: string; userId: string }): Promise<boolean>;
+}
+
+export function createAiConversationStore({
+  db,
+}: {
+  db: AiDatabase;
+}): AiConversationStore {
+  return {
+    async createConversation({
+      userId,
+      title,
+      integrationId,
+      model,
+      permissionMode,
+    }) {
+      const [row] = await db
+        .insert(schema.aiConversations)
+        // `permissionMode` omitted -> the column default ("approve") applies.
+        .values({ userId, title, integrationId, model, permissionMode })
+        .returning();
+      return row;
+    },
+
+    async listConversations({ userId }) {
+      // Archived (soft-deleted) conversations are retained in the table but
+      // excluded from the sidebar list.
+      return db
+        .select()
+        .from(schema.aiConversations)
+        .where(
+          and(
+            eq(schema.aiConversations.userId, userId),
+            isNull(schema.aiConversations.archivedAt),
+          ),
+        )
+        .orderBy(desc(schema.aiConversations.updatedAt));
+    },
+
+    async getConversation({ id, userId }) {
+      const rows = await db
+        .select()
+        .from(schema.aiConversations)
+        .where(
+          and(
+            eq(schema.aiConversations.id, id),
+            eq(schema.aiConversations.userId, userId),
+          ),
+        )
+        .limit(1);
+      return rows[0];
+    },
+
+    async appendMessage({
+      conversationId,
+      role,
+      content,
+      toolCalls,
+      modelMessages,
+    }) {
+      // Scrub credential-shaped keys/values from EVERY bag on the write path:
+      // the no-secret-leak guarantee is enforced here, not merely assumed.
+      const [row] = await db
+        .insert(schema.aiMessages)
+        .values({
+          conversationId,
+          role,
+          content: scrubContent(content),
+          toolCalls: toolCalls ? scrubModelMessages(toolCalls) : toolCalls,
+          modelMessages: modelMessages
+            ? scrubModelMessages(modelMessages)
+            : modelMessages,
+        })
+        .returning();
+      // Bump the owning conversation so list order reflects activity.
+      await db
+        .update(schema.aiConversations)
+        .set({ updatedAt: new Date() })
+        .where(eq(schema.aiConversations.id, conversationId));
+      return row;
+    },
+
+    async listMessages({ conversationId }) {
+      return db
+        .select()
+        .from(schema.aiMessages)
+        .where(eq(schema.aiMessages.conversationId, conversationId))
+        .orderBy(asc(schema.aiMessages.createdAt));
+    },
+
+    async updateConversation({ id, userId, title, model, permissionMode }) {
+      const set: Partial<{
+        title: string;
+        model: string;
+        permissionMode: AiPermissionMode;
+        updatedAt: Date;
+      }> = {
+        updatedAt: new Date(),
+      };
+      if (title !== undefined) set.title = title;
+      if (model !== undefined) set.model = model;
+      if (permissionMode !== undefined) set.permissionMode = permissionMode;
+      const [row] = await db
+        .update(schema.aiConversations)
+        .set(set)
+        .where(
+          and(
+            eq(schema.aiConversations.id, id),
+            eq(schema.aiConversations.userId, userId),
+          ),
+        )
+        .returning();
+      return row;
+    },
+
+    async archiveConversation({ id, userId }) {
+      // Owner-scoped soft delete: only stamp a row that is owned AND not already
+      // archived, so a repeat archive is a no-op (returns false).
+      const archived = await db
+        .update(schema.aiConversations)
+        .set({ archivedAt: new Date() })
+        .where(
+          and(
+            eq(schema.aiConversations.id, id),
+            eq(schema.aiConversations.userId, userId),
+            isNull(schema.aiConversations.archivedAt),
+          ),
+        )
+        .returning({ id: schema.aiConversations.id });
+      return archived.length > 0;
+    },
+
+    async deleteConversation({ id, userId }) {
+      const deleted = await db
+        .delete(schema.aiConversations)
+        .where(
+          and(
+            eq(schema.aiConversations.id, id),
+            eq(schema.aiConversations.userId, userId),
+          ),
+        )
+        .returning({ id: schema.aiConversations.id });
+      return deleted.length > 0;
+    },
+  };
+}

package/src/chat/decision.logic.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import { buildDecisionNote } from "./decision.logic";
+
+describe("buildDecisionNote", () => {
+  test("apply note states it is live, uses the summary, and forbids re-proposing", () => {
+    const note = buildDecisionNote({
+      decision: "apply",
+      toolName: "healthcheck.propose",
+      summary: 'Create health check "google-com-http" running every 60s',
+    });
+    expect(note).toContain("APPLIED");
+    expect(note).toContain("now live");
+    expect(note).toContain('Create health check "google-com-http"');
+    expect(note).toContain("Do NOT propose it again");
+  });
+
+  test("decline note states nothing changed and asks what to adjust", () => {
+    const note = buildDecisionNote({
+      decision: "decline",
+      toolName: "healthcheck.propose",
+      summary: "Create health check X",
+    });
+    expect(note).toContain("DECLINED");
+    expect(note).toContain("Nothing was changed");
+    expect(note).toContain("adjust");
+    expect(note).toContain("Do NOT re-propose");
+  });
+
+  test("falls back to the tool name when no summary is stored", () => {
+    const note = buildDecisionNote({
+      decision: "apply",
+      toolName: "automation.propose",
+    });
+    expect(note).toContain('the proposed "automation.propose" action');
+  });
+
+  test("ignores a blank summary and falls back to the tool name", () => {
+    const note = buildDecisionNote({
+      decision: "decline",
+      toolName: "automation.propose",
+      summary: "   ",
+    });
+    expect(note).toContain('the proposed "automation.propose" action');
+  });
+});

package/src/chat/decision.logic.ts

@@ -0,0 +1,54 @@
+/**
+ * Pure helpers for the post-confirm-card "decision acknowledgment" turn.
+ *
+ * When the operator applies or declines a confirm card, the actual apply runs
+ * through the unchanged `applyTool` propose/apply path. This turn is purely the
+ * MODEL's reaction: it is told the operator's decision and streams a short
+ * acknowledgment so the conversation does not dead-end on "waiting for your
+ * confirmation". The note is built SERVER-SIDE from the stored proposal (tool
+ * name + the summary captured at propose time) - no client-supplied text ever
+ * reaches the model - and is EPHEMERAL: it is appended to the model-call history
+ * for this turn only, never persisted. The assistant's reply carries the
+ * outcome forward into the persisted transcript.
+ */
+
+/** A human decision on a proposed mutate/destructive tool's confirm card. */
+export type DecisionKind = "apply" | "decline";
+
+/**
+ * Build the ephemeral note that informs the model of the operator's decision.
+ * `summary` is the proposal's stored one-line summary (e.g. "Create health
+ * check ..."); when absent we fall back to the tool name so the note is still
+ * meaningful.
+ */
+export function buildDecisionNote({
+  decision,
+  toolName,
+  summary,
+}: {
+  decision: DecisionKind;
+  toolName: string;
+  summary?: string;
+}): string {
+  const what =
+    summary && summary.trim().length > 0
+      ? summary.trim()
+      : `the proposed "${toolName}" action`;
+
+  if (decision === "apply") {
+    return [
+      "[system note] The operator APPROVED your previous proposal and it has",
+      "been APPLIED successfully and is now live:",
+      `${what}.`,
+      "Confirm to the operator in one or two short sentences what is now in",
+      "effect, then suggest a sensible next step. Do NOT propose it again.",
+    ].join(" ");
+  }
+
+  return [
+    "[system note] The operator DECLINED your previous proposal",
+    `(${what}). Nothing was changed.`,
+    "Acknowledge briefly and ask what they would like to adjust.",
+    "Do NOT re-propose it unless the operator asks.",
+  ].join(" ");
+}

package/src/chat/llm-provider.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from "bun:test";
+import type { OpenAiCompatibleConnection } from "@checkstack/ai-common";
+import { resolveModelId, buildLanguageModel } from "./llm-provider";
+
+const conn = (over: Partial<OpenAiCompatibleConnection> = {}): OpenAiCompatibleConnection => ({
+  baseUrl: "https://api.openai.com/v1",
+  apiKey: "sk-secret",
+  defaultModel: "gpt-4o-mini",
+  ...over,
+});
+
+describe("resolveModelId (§14.6 per-integration model UX)", () => {
+  test("falls back to defaultModel when nothing requested", () => {
+    expect(resolveModelId({ connection: conn(), requested: undefined })).toBe(
+      "gpt-4o-mini",
+    );
+  });
+
+  test("uses the requested model when no allowlist constrains it", () => {
+    expect(resolveModelId({ connection: conn(), requested: "gpt-4o" })).toBe(
+      "gpt-4o",
+    );
+  });
+
+  test("honours a requested model that is in the allowlist", () => {
+    const c = conn({ availableModels: ["gpt-4o-mini", "gpt-4o"] });
+    expect(resolveModelId({ connection: c, requested: "gpt-4o" })).toBe("gpt-4o");
+  });
+
+  test("rejects a requested model outside a non-empty allowlist (untrusted input)", () => {
+    const c = conn({ availableModels: ["gpt-4o-mini"] });
+    // The model id arrives over the wire and is untrusted, so an out-of-list
+    // value falls back to the default rather than being passed through.
+    expect(resolveModelId({ connection: c, requested: "evil-model" })).toBe(
+      "gpt-4o-mini",
+    );
+  });
+});
+
+describe("buildLanguageModel coerces the model in the live path (P4 review item 1)", () => {
+  /** Read the resolved model id from the provider model the SDK returns. */
+  const modelIdOf = (model: ReturnType<typeof buildLanguageModel>): string =>
+    typeof model === "string" ? model : model.modelId;
+
+  test("an out-of-allowlist model id is coerced to defaultModel, not passed through", () => {
+    const c = conn({ availableModels: ["gpt-4o-mini"] });
+    // This is the LIVE path the chat service uses; it must not honour an
+    // arbitrary wire-supplied model id.
+    const model = buildLanguageModel({ connection: c, model: "evil-model" });
+    expect(modelIdOf(model)).toBe("gpt-4o-mini");
+  });
+
+  test("an allowlisted model id is honoured", () => {
+    const c = conn({ availableModels: ["gpt-4o-mini", "gpt-4o"] });
+    const model = buildLanguageModel({ connection: c, model: "gpt-4o" });
+    expect(modelIdOf(model)).toBe("gpt-4o");
+  });
+
+  test("no requested model uses defaultModel", () => {
+    const model = buildLanguageModel({ connection: conn(), model: undefined });
+    expect(modelIdOf(model)).toBe("gpt-4o-mini");
+  });
+});

package/src/chat/llm-provider.ts

@@ -0,0 +1,67 @@
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import type { LanguageModel } from "ai";
+import type { OpenAiCompatibleConnection } from "@checkstack/ai-common";
+
+/**
+ * Build a provider-agnostic language model from an OpenAI-compatible connection
+ * (decision §14.6). The `baseURL` override is what makes this work against
+ * OpenAI, Azure, OpenRouter, Ollama, vLLM, LM Studio, etc. - any endpoint that
+ * speaks the OpenAI CHAT-COMPLETIONS wire format.
+ *
+ * Why `@ai-sdk/openai-compatible` and NOT `@ai-sdk/openai`: the strict OpenAI
+ * provider (`@ai-sdk/openai` v3) defaults to OpenAI's `/responses` API, which
+ * sends `reasoning` / `reasoning_text` message parts that third-party gateways
+ * (OpenRouter, DeepSeek, Ollama, ...) do not implement - they reject it with
+ * HTTP 400 `invalid_prompt` "Invalid Responses API request". The compatible
+ * provider talks plain `/chat/completions` and omits OpenAI-only request fields,
+ * which is exactly what an "OpenAI-compatible connection" needs.
+ *
+ * CRITICAL (security): the credential (`apiKey`) is read here, on the BACKEND,
+ * and handed to the SDK provider (as a `Bearer` Authorization header). It never
+ * crosses an RPC/DTO boundary to the browser - the chat UI only ever receives
+ * streamed tokens + tool events.
+ *
+ * The requested model id is ALWAYS coerced through {@link resolveModelId}
+ * against the connection's `availableModels` allowlist, so a model id from the
+ * wire (untrusted) can never bypass the per-integration model/cost control. The
+ * model id used by the provider is the resolved one, never the raw request.
+ */
+export function buildLanguageModel({
+  connection,
+  model,
+}: {
+  connection: OpenAiCompatibleConnection;
+  /** Conversation-selected model id; revalidated against the connection. */
+  model?: string;
+}): LanguageModel {
+  const provider = createOpenAICompatible({
+    name: "checkstack-openai-compatible",
+    baseURL: connection.baseUrl,
+    apiKey: connection.apiKey,
+  });
+  const modelId = resolveModelId({ connection, requested: model });
+  // `.chatModel` pins the `/chat/completions` API (see the Responses-API note
+  // above), the lingua franca every OpenAI-compatible gateway supports.
+  return provider.chatModel(modelId);
+}
+
+/**
+ * Resolve the effective model id for a conversation against the connection's
+ * allowlist (§14.6). A requested model not in a non-empty `availableModels`
+ * allowlist falls back to `defaultModel` (the model picker is constrained UI
+ * side, but the model is untrusted input from the wire, so we re-check).
+ */
+export function resolveModelId({
+  connection,
+  requested,
+}: {
+  connection: OpenAiCompatibleConnection;
+  requested?: string;
+}): string {
+  if (!requested) return connection.defaultModel;
+  const allow = connection.availableModels;
+  if (allow && allow.length > 0 && !allow.includes(requested)) {
+    return connection.defaultModel;
+  }
+  return requested;
+}

package/src/chat/model-error.logic.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "bun:test";
+import { APICallError } from "ai";
+import { formatModelError } from "./model-error.logic";
+
+describe("formatModelError", () => {
+  test("surfaces an APICallError's status + response body (the masked detail)", () => {
+    const error = new APICallError({
+      message: "Bad Request",
+      url: "https://openrouter.ai/api/v1/chat/completions",
+      requestBodyValues: {},
+      statusCode: 400,
+      responseBody: '{"error":{"code":"invalid_prompt","message":"bad"}}',
+    });
+    const { userMessage, logDetail } = formatModelError({ error });
+    expect(userMessage).toContain("HTTP 400");
+    expect(userMessage).toContain("invalid_prompt");
+    expect(logDetail.kind).toBe("APICallError");
+    expect(logDetail.statusCode).toBe(400);
+    expect(logDetail.responseBody).toContain("invalid_prompt");
+  });
+
+  test("falls back to the error message when the API error has no body", () => {
+    const error = new APICallError({
+      message: "upstream timeout",
+      url: "https://example.com",
+      requestBodyValues: {},
+      statusCode: 504,
+    });
+    const { userMessage } = formatModelError({ error });
+    expect(userMessage).toContain("HTTP 504");
+    expect(userMessage).toContain("upstream timeout");
+  });
+
+  test("truncates an oversized provider body", () => {
+    const huge = "x".repeat(5000);
+    const error = new APICallError({
+      message: "big",
+      url: "https://example.com",
+      requestBodyValues: {},
+      statusCode: 400,
+      responseBody: huge,
+    });
+    const { userMessage } = formatModelError({ error });
+    expect(userMessage).toContain("(truncated)");
+    expect(userMessage.length).toBeLessThan(huge.length);
+  });
+
+  test("handles a generic Error without leaking internals", () => {
+    const { userMessage, logDetail } = formatModelError({
+      error: new Error("something broke"),
+    });
+    expect(userMessage).toContain("something broke");
+    expect(logDetail.kind).toBe("error");
+  });
+
+  test("handles a non-Error throw (string / unknown)", () => {
+    const { userMessage } = formatModelError({ error: "weird" });
+    expect(userMessage.length).toBeGreaterThan(0);
+  });
+});

package/src/chat/model-error.logic.ts

@@ -0,0 +1,65 @@
+import { APICallError } from "ai";
+import { extractErrorMessage } from "@checkstack/common";
+
+/**
+ * Turn an error thrown by the model provider (or the agent loop) into a
+ * USER-FACING message plus a STRUCTURED log detail. Pure + total: never throws.
+ *
+ * The AI SDK masks streaming errors by default (the UI gets a generic "An error
+ * occurred"), which hid the provider's real HTTP response. We surface it
+ * instead: an `APICallError` carries the provider's `statusCode` and
+ * `responseBody`, which is exactly what an operator needs to forward to their
+ * model provider when a turn fails (for example a 400 `invalid_prompt`).
+ *
+ * SECURITY: `responseBody` is the provider's ERROR payload, not our request, so
+ * it never contains the integration credential. The request body (which carries
+ * the api key in headers, never the body) is deliberately NOT echoed.
+ */
+export interface FormattedModelError {
+  /** Shown in the chat UI in place of the SDK's masked generic error. */
+  userMessage: string;
+  /** Structured fields for the server log (never rendered verbatim to a user). */
+  logDetail: Record<string, unknown>;
+}
+
+/** Cap the provider body we echo so a huge payload can't flood the UI or log. */
+const MAX_LENGTH = 2000;
+
+function truncate({ value }: { value: string }): string {
+  return value.length > MAX_LENGTH
+    ? `${value.slice(0, MAX_LENGTH)}... (truncated)`
+    : value;
+}
+
+export function formatModelError({
+  error,
+}: {
+  error: unknown;
+}): FormattedModelError {
+  if (APICallError.isInstance(error)) {
+    const status = error.statusCode ?? "unknown";
+    const body =
+      typeof error.responseBody === "string" && error.responseBody.length > 0
+        ? truncate({ value: error.responseBody })
+        : error.message;
+    return {
+      userMessage: `The AI provider rejected the request (HTTP ${status}). ${body}`,
+      logDetail: {
+        kind: "APICallError",
+        statusCode: error.statusCode,
+        url: error.url,
+        isRetryable: error.isRetryable,
+        responseBody: error.responseBody,
+        message: error.message,
+      },
+    };
+  }
+
+  // Any other error (agent-loop bug, network, unknown): surface its message via
+  // the shared extractor (handles Error, string, and unknown shapes uniformly).
+  const message = extractErrorMessage(error);
+  return {
+    userMessage: `The assistant hit an error: ${truncate({ value: message })}`,
+    logDetail: { kind: "error", message },
+  };
+}