@checkstack/ai-backend 0.1.0

package/src/chat/title-service.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, test } from "bun:test";
+import type { LanguageModel } from "ai";
+import type { AiConversationStore } from "./conversation-store";
+import {
+  applyAutoTitle,
+  generateConversationTitle,
+  type TitleTextGenerator,
+} from "./title-service";
+
+/**
+ * A stand-in model. The title logic only forwards it to the injected `generate`
+ * fake (which ignores it), so a model id string (a valid `LanguageModel`) keeps
+ * tests free of a verbose, version-coupled provider mock.
+ */
+const model: LanguageModel = "test-model";
+
+/** A generate fake that always resolves to `text`. */
+function generates(text: string): TitleTextGenerator {
+  return async () => text;
+}
+
+/** A generate fake that always rejects (simulates a model error). */
+const failsToGenerate: TitleTextGenerator = async () => {
+  throw new Error("model unavailable");
+};
+
+/**
+ * A minimal store stub that records updateConversation calls. applyAutoTitle
+ * only ever calls updateConversation, so we implement just that method and stub
+ * the rest as throwing (the repo's other store tests stub partially too).
+ */
+function storeStub() {
+  const updates: Array<{ id: string; userId: string; title?: string }> = [];
+  const notImplemented = () => {
+    throw new Error("not implemented in stub");
+  };
+  const conversations: AiConversationStore = {
+    updateConversation: async (args) => {
+      updates.push({ id: args.id, userId: args.userId, title: args.title });
+      return undefined;
+    },
+    createConversation: notImplemented,
+    listConversations: notImplemented,
+    getConversation: notImplemented,
+    appendMessage: notImplemented,
+    listMessages: notImplemented,
+    archiveConversation: notImplemented,
+    deleteConversation: notImplemented,
+  };
+  return { conversations, updates };
+}
+
+describe("generateConversationTitle", () => {
+  test("sanitizes a quoted/markdown model reply", async () => {
+    const title = await generateConversationTitle({
+      model,
+      firstMessage: "Summarize the open incidents please",
+      generate: generates('"**Open incidents summary**"'),
+    });
+    expect(title).toBe("Open incidents summary");
+  });
+
+  test("falls back to the heuristic on a model error", async () => {
+    const title = await generateConversationTitle({
+      model,
+      firstMessage: "  Summarize   the open incidents for me today and more  ",
+      generate: failsToGenerate,
+    });
+    // First six words of the collapsed first message.
+    expect(title).toBe("Summarize the open incidents for me");
+  });
+
+  test("falls back to the heuristic when the model returns nothing usable", async () => {
+    const title = await generateConversationTitle({
+      model,
+      firstMessage: "Draft an automation",
+      generate: generates("***"),
+    });
+    expect(title).toBe("Draft an automation");
+  });
+});
+
+describe("applyAutoTitle", () => {
+  test("persists the generated title for a titleless conversation", async () => {
+    const { conversations, updates } = storeStub();
+    await applyAutoTitle({
+      conversations,
+      model,
+      conversationId: "c1",
+      userId: "u1",
+      firstMessage: "Summarize the open incidents",
+      generate: generates("Open incidents summary"),
+    });
+    expect(updates).toHaveLength(1);
+    expect(updates[0]).toEqual({
+      id: "c1",
+      userId: "u1",
+      title: "Open incidents summary",
+    });
+  });
+
+  test("persists the heuristic title when the model errors", async () => {
+    const { conversations, updates } = storeStub();
+    await applyAutoTitle({
+      conversations,
+      model,
+      conversationId: "c1",
+      userId: "u1",
+      firstMessage: "Draft an automation for on-call paging",
+      generate: failsToGenerate,
+    });
+    expect(updates).toHaveLength(1);
+    // "on-call" is a single word, so six words includes "paging".
+    expect(updates[0]?.title).toBe("Draft an automation for on-call paging");
+  });
+
+  test("skips the persist when the title resolves empty", async () => {
+    const { conversations, updates } = storeStub();
+    await applyAutoTitle({
+      conversations,
+      model,
+      conversationId: "c1",
+      userId: "u1",
+      firstMessage: "   ", // empty heuristic too
+      generate: generates("***"),
+    });
+    expect(updates).toHaveLength(0);
+  });
+
+  test("never throws when the store update fails", async () => {
+    const { conversations } = storeStub();
+    conversations.updateConversation = async () => {
+      throw new Error("db down");
+    };
+    await expect(
+      applyAutoTitle({
+        conversations,
+        model,
+        conversationId: "c1",
+        userId: "u1",
+        firstMessage: "hello",
+        generate: generates("A title"),
+      }),
+    ).resolves.toBeUndefined();
+  });
+});

package/src/chat/title-service.ts

@@ -0,0 +1,111 @@
+import { generateText, type LanguageModel } from "ai";
+import { deriveHeuristicTitle, sanitizeGeneratedTitle } from "./title.logic";
+import type { AiConversationStore } from "./conversation-store";
+
+/**
+ * Prompt for the cheap title-generation call. Kept terse so the model returns a
+ * bare title (no quotes/markdown); `sanitizeGeneratedTitle` defends against any
+ * decoration regardless.
+ */
+const TITLE_SYSTEM_PROMPT =
+  "You generate a short title for a chat conversation. Reply with a concise " +
+  "title of at most 6 words that summarizes the user's first message. Do not " +
+  "use quotes, markdown, or trailing punctuation. Reply with the title only.";
+
+/**
+ * The model call used to produce a raw title. Defaults to the AI SDK's
+ * `generateText` against the turn's already-built language model; injectable so
+ * the title logic is unit-testable WITHOUT constructing a provider mock (the
+ * `LanguageModelV3` result shape is verbose and version-coupled).
+ */
+export type TitleTextGenerator = (args: {
+  model: LanguageModel;
+  firstMessage: string;
+}) => Promise<string>;
+
+/** Default generator: a cheap `generateText` call reusing the turn's model. */
+const defaultGenerateTitleText: TitleTextGenerator = async ({
+  model,
+  firstMessage,
+}) => {
+  const { text } = await generateText({
+    model,
+    system: TITLE_SYSTEM_PROMPT,
+    prompt: firstMessage,
+  });
+  return text;
+};
+
+/**
+ * Resolve the title for a new conversation from its first user message.
+ *
+ * Tries a cheap `generateText` call (reusing the turn's resolved connection +
+ * model) and sanitizes the reply. On ANY model/sanitize failure it falls back to
+ * a deterministic heuristic derived from the message. Returns an empty string
+ * only when even the heuristic is empty (caller then leaves the title unset).
+ *
+ * This function NEVER throws: it is invoked fire-and-forget from the streamed
+ * turn, so a title failure must not surface to the chat response.
+ */
+export async function generateConversationTitle({
+  model,
+  firstMessage,
+  generate = defaultGenerateTitleText,
+}: {
+  /** The already-built language model used for the turn (provider-agnostic). */
+  model: LanguageModel;
+  /** The user's first message in the conversation. */
+  firstMessage: string;
+  /** Override the model call (tests inject a fake; defaults to generateText). */
+  generate?: TitleTextGenerator;
+}): Promise<string> {
+  const heuristic = deriveHeuristicTitle(firstMessage);
+  try {
+    const text = await generate({ model, firstMessage });
+    const sanitized = sanitizeGeneratedTitle(text);
+    return sanitized || heuristic;
+  } catch {
+    // Fail closed to the heuristic: a title is a nicety, never worth a throw.
+    return heuristic;
+  }
+}
+
+/**
+ * Generate and PERSIST a title for a still-untitled conversation from its first
+ * user message. Designed to run fire-and-forget from the streamed turn: it never
+ * throws, and skips the persist when the resolved title is empty (so the sidebar
+ * keeps "Untitled chat" rather than storing a blank). Extracted from the chat
+ * service so the persist path is unit-testable with a mocked model + store.
+ */
+export async function applyAutoTitle({
+  conversations,
+  model,
+  conversationId,
+  userId,
+  firstMessage,
+  generate,
+}: {
+  conversations: AiConversationStore;
+  model: LanguageModel;
+  conversationId: string;
+  userId: string;
+  firstMessage: string;
+  /** Override the model call (tests inject a fake; defaults to generateText). */
+  generate?: TitleTextGenerator;
+}): Promise<void> {
+  try {
+    const title = await generateConversationTitle({
+      model,
+      firstMessage,
+      generate,
+    });
+    if (!title) return;
+    await conversations.updateConversation({
+      id: conversationId,
+      userId,
+      title,
+    });
+  } catch {
+    // Best-effort; the conversation simply stays untitled on failure.
+  }
+}

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

@@ -0,0 +1,98 @@
+import { describe, expect, test } from "bun:test";
+import { deriveHeuristicTitle, sanitizeGeneratedTitle } from "./title.logic";
+
+describe("deriveHeuristicTitle", () => {
+  test("collapses whitespace and trims", () => {
+    expect(deriveHeuristicTitle("  hello   world  ")).toBe("hello world");
+  });
+
+  test("collapses newlines/tabs into single spaces", () => {
+    expect(deriveHeuristicTitle("summarize\n\tthe open incidents")).toBe(
+      "summarize the open incidents",
+    );
+  });
+
+  test("keeps at most six words", () => {
+    expect(
+      deriveHeuristicTitle("one two three four five six seven eight"),
+    ).toBe("one two three four five six");
+  });
+
+  test("caps at sixty characters with no trailing-cut whitespace", () => {
+    const long = "word ".repeat(40); // many words, each short
+    const result = deriveHeuristicTitle(long);
+    expect(result.length).toBeLessThanOrEqual(60);
+    expect(result).toBe(result.trimEnd());
+  });
+
+  test("does not append an ellipsis", () => {
+    const result = deriveHeuristicTitle("a".repeat(200));
+    expect(result.endsWith("...")).toBe(false);
+    expect(result.length).toBeLessThanOrEqual(60);
+  });
+
+  test("returns empty string for empty/whitespace input", () => {
+    expect(deriveHeuristicTitle("")).toBe("");
+    expect(deriveHeuristicTitle("   \n\t ")).toBe("");
+  });
+});
+
+describe("sanitizeGeneratedTitle", () => {
+  test("strips surrounding double quotes", () => {
+    expect(sanitizeGeneratedTitle('"Open incidents summary"')).toBe(
+      "Open incidents summary",
+    );
+  });
+
+  test("strips surrounding single and smart quotes", () => {
+    expect(sanitizeGeneratedTitle("'Health check'")).toBe("Health check");
+    expect(sanitizeGeneratedTitle("“Anomaly review”")).toBe("Anomaly review");
+  });
+
+  test("strips nested/repeated wrapping quotes", () => {
+    expect(sanitizeGeneratedTitle("\"'Nested title'\"")).toBe("Nested title");
+  });
+
+  test("strips leading markdown heading marker", () => {
+    expect(sanitizeGeneratedTitle("## Incident triage")).toBe("Incident triage");
+  });
+
+  test("strips leading list markers", () => {
+    expect(sanitizeGeneratedTitle("- Draft automation")).toBe(
+      "Draft automation",
+    );
+    expect(sanitizeGeneratedTitle("1. Draft automation")).toBe(
+      "Draft automation",
+    );
+  });
+
+  test("removes bold/italic/code markers", () => {
+    expect(sanitizeGeneratedTitle("**Bold** title")).toBe("Bold title");
+    expect(sanitizeGeneratedTitle("`code` title")).toBe("code title");
+  });
+
+  test("drops trailing punctuation", () => {
+    expect(sanitizeGeneratedTitle("Summarize incidents.")).toBe(
+      "Summarize incidents",
+    );
+    expect(sanitizeGeneratedTitle("Is it down?!")).toBe("Is it down");
+  });
+
+  test("only keeps the first line of a multi-line reply", () => {
+    expect(sanitizeGeneratedTitle("Open incidents\nmore detail here")).toBe(
+      "Open incidents",
+    );
+  });
+
+  test("caps to six words and sixty chars", () => {
+    expect(
+      sanitizeGeneratedTitle("alpha beta gamma delta epsilon zeta eta"),
+    ).toBe("alpha beta gamma delta epsilon zeta");
+  });
+
+  test("returns empty string when nothing usable remains", () => {
+    expect(sanitizeGeneratedTitle("")).toBe("");
+    expect(sanitizeGeneratedTitle('""')).toBe("");
+    expect(sanitizeGeneratedTitle("***")).toBe("");
+  });
+});

package/src/chat/title.logic.ts

@@ -0,0 +1,102 @@
+/**
+ * Pure, DOM-free helpers for auto-titling a new conversation from its first user
+ * message. Both functions are total (never throw) so the fire-and-forget title
+ * job can always fall back to a deterministic heuristic when the model errors.
+ */
+
+/** Max words kept in a derived/sanitized title. */
+const MAX_TITLE_WORDS = 6;
+/** Hard character cap for a title (keeps the sidebar tidy). */
+const MAX_TITLE_CHARS = 60;
+
+/**
+ * Collapse runs of whitespace into single spaces and trim the ends. Shared by
+ * both helpers so titles never carry newlines or doubled spaces from the raw
+ * model/user text.
+ */
+function collapseWhitespace(value: string): string {
+  return value.replaceAll(/\s+/g, " ").trim();
+}
+
+/**
+ * Cap a single-line string to at most `MAX_TITLE_WORDS` words AND
+ * `MAX_TITLE_CHARS` characters, trimming any trailing whitespace left after the
+ * cut. No ellipsis is appended (the task forbids ellipsis-from-cut weirdness).
+ */
+function capLength(value: string): string {
+  const words = value.split(" ").slice(0, MAX_TITLE_WORDS).join(" ");
+  if (words.length <= MAX_TITLE_CHARS) return words;
+  return words.slice(0, MAX_TITLE_CHARS).trimEnd();
+}
+
+/**
+ * Derive a deterministic fallback title from the first user message: collapse
+ * whitespace, take the first ~6 words, cap at ~60 chars. Returns an empty string
+ * only for empty/whitespace-only input (the caller leaves the title unset in
+ * that case so the sidebar keeps showing "Untitled chat").
+ */
+export function deriveHeuristicTitle(firstMessage: string): string {
+  const normalized = collapseWhitespace(firstMessage);
+  if (!normalized) return "";
+  return capLength(normalized);
+}
+
+/**
+ * Sanitize a model-generated title: strip surrounding quotes, leading markdown
+ * heading/list markers and bold/italic markers, collapse whitespace, drop
+ * trailing punctuation, and cap length. Returns an empty string when nothing
+ * usable remains so the caller can fall back to the heuristic.
+ */
+export function sanitizeGeneratedTitle(raw: string): string {
+  // Take only the first non-empty line of a multi-line model reply BEFORE
+  // collapsing whitespace (collapsing would erase the line breaks).
+  const firstLine = raw
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find((line) => line.length > 0);
+  let value = collapseWhitespace(firstLine ?? "");
+  if (!value) return "";
+
+  // Strip leading markdown heading (#) and list markers (-, *, +, 1.).
+  value = value.replace(/^\s*(?:#{1,6}\s*|[-*+]\s+|\d+\.\s+)/, "");
+
+  // Strip surrounding matching quotes (straight or smart) repeatedly.
+  value = stripWrappingQuotes(value);
+
+  // Remove markdown emphasis markers anywhere (**, __, *, _, `).
+  value = value.replaceAll(/[*_`]+/g, "");
+
+  // Collapse again after marker removal, then strip trailing punctuation.
+  value = collapseWhitespace(value).replace(/[.,!?;:]+$/, "");
+  value = value.trim();
+  if (!value) return "";
+
+  return capLength(value);
+}
+
+/** Strip one or more layers of matching wrapping quotes from a string. */
+function stripWrappingQuotes(value: string): string {
+  const pairs: ReadonlyArray<readonly [string, string]> = [
+    ['"', '"'],
+    ["'", "'"],
+    ["“", "”"],
+    ["‘", "’"],
+    ["`", "`"],
+  ];
+  let current = value.trim();
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const [open, close] of pairs) {
+      if (
+        current.length >= 2 &&
+        current.startsWith(open) &&
+        current.endsWith(close)
+      ) {
+        current = current.slice(open.length, current.length - close.length).trim();
+        changed = true;
+      }
+    }
+  }
+  return current;
+}

package/src/extension-points.ts

@@ -0,0 +1,41 @@
+import { createExtensionPoint } from "@checkstack/backend-api";
+import type { PluginMetadata } from "@checkstack/common";
+import type { RegisteredAiTool } from "./tool-registry";
+import type { ProjectToolInput } from "./projection";
+
+/**
+ * Path 1 — hand-authored composite tools (decision 2b).
+ *
+ * Plugins register coarser/curated tools (e.g. `automation.propose`) here when
+ * the model needs a different surface than raw CRUD. The tool name is qualified
+ * with the registering plugin id before it reaches the registry.
+ */
+export interface AiToolExtensionPoint {
+  registerTool<TInput, TOutput>(
+    tool: RegisteredAiTool<TInput, TOutput>,
+    pluginMetadata: PluginMetadata,
+  ): void;
+}
+
+export const aiToolExtensionPoint = createExtensionPoint<AiToolExtensionPoint>(
+  "ai.toolExtensionPoint",
+);
+
+/**
+ * Path 2 — opt-in projection of an existing oRPC procedure (decision 2a).
+ *
+ * The projected tool reads the procedure's access rules and input schema
+ * verbatim; nothing is duplicated. `effect` is REQUIRED and never inferred.
+ *
+ * The owning plugin metadata lives on `input.sourcePluginMetadata` (it must be
+ * the SOURCE procedure's plugin so qualified access-rule IDs match what
+ * `autoAuthMiddleware` enforces), so `expose` takes no separate metadata arg.
+ */
+export interface AiToolProjectionExtensionPoint {
+  expose<TInput, TOutput>(input: ProjectToolInput<TInput, TOutput>): void;
+}
+
+export const aiToolProjectionExtensionPoint =
+  createExtensionPoint<AiToolProjectionExtensionPoint>(
+    "ai.toolProjectionExtensionPoint",
+  );