app/lib/ai.server.ts

Functions

Imports

It imports app/db/schema.ts, app/lib/content.server.ts, app/lib/people.server.ts, app/lib/projects.server.ts, app/lib/roles.ts, app/lib/sites.server.ts, app/lib/social/queue.server.ts. Imported by app/components/editor/flags-panel.tsx, app/lib/books.server.ts, app/lib/mcp/call-log.ts, app/lib/mcp/tools.ts, app/routes/ai-draft.preview.ts, app/routes/ai-draft.tsx, app/routes/book.file.tsx, app/routes/book.history.tsx, app/routes/editor.tsx, app/routes/history.tsx, app/routes/preview.ts, app/routes/project.flags.tsx, app/routes/unpublish.tsx.

Source

1// What AI sessions may do beyond what the buttons do, and the rules around it (design decision 2 and
2// section 5, "MCP tools"). The writes still go through content.server.ts, the same functions as the
3// buttons, so every role rule applies unchanged; this adds the AI-only rules on top:
4//
5// - an AI session is an AI client acting for a person, known by the door it came through;
6// - a reviewer (another company's agent) reads and flags, and never writes text or publishes;
7// - an AI draft is saved beside the person's own draft, never over it or to the site;
8// - publish is the Owner's own sessions only, refused while any flag on the item is open, recorded
9//   as "published by <client> on Dustin's instruction", and emailed to Dustin with an unpublish link.
10
11import { and, asc, desc, eq, sql } from "drizzle-orm";
12import { drizzle } from "drizzle-orm/d1";
13
14import { aiDrafts, aiPublications, findings, siteItems } from "~/db/schema";
15import { readDoc, writeToSite, type ProjectRole, type WriteOutcome } from "~/lib/content.server";
16import type { Viewer } from "~/lib/people.server";
17import type { SiteProject } from "~/lib/projects.server";
18import { can } from "~/lib/roles";
19import { siteEntry } from "~/lib/sites.server";
20import { draftForEvent, draftSocialPost } from "~/lib/social/queue.server";
21
22/**
23 * An AI client acting for a person, known by the door it came through: the person the OAuth grant
24 * belongs to, and the client that holds the grant (its CIMD name), credited on every change.
25 */
26export type AiSession = { viewer: Viewer; client: string };
27
28/** A refusal an AI tool reports back to the client as its answer, never a crash. */
29export class AiRefusal extends Error {
30  constructor(message: string) {
31    super(message);
32    this.name = "AiRefusal";
33  }
34}
35
36// ---------- flags on an item
37
38export type ItemFinding = {
39  id: number;
40  check: string;
41  message: string;
42  excerpt: string | null;
43  status: "open" | "dismissed";
44  createdAt: string;
45};
46
47export async function itemFindings(db: D1Database, project: ProjectRole, itemId: string): Promise<ItemFinding[]> {
48  if (!can(project.role, "read")) throw new Response("Forbidden", { status: 403 });
49  return drizzle(db)
50    .select({
51      id: findings.id,
52      check: findings.checkName,
53      message: findings.message,
54      excerpt: findings.excerpt,
55      status: findings.status,
56      createdAt: findings.createdAt,
57    })
58    .from(findings)
59    .where(and(eq(findings.projectId, project.id), eq(findings.path, itemId)))
60    .orderBy(desc(findings.createdAt), desc(findings.id))
61    .all();
62}
63
64async function fingerprint(parts: (string | null)[]): Promise<string> {
65  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify(parts)));
66  return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
67}
68
69/**
70 * A flag from an AI session, a reviewer's above all (design B6: reviewers write findings, never
71 * text). Anyone who may comment may flag. The same flag twice is one flag.
72 */
73export async function addFinding(
74  db: D1Database,
75  project: ProjectRole,
76  session: AiSession,
77  itemId: string,
78  input: { message: string; excerpt?: string | null },
79): Promise<{ id: number; duplicate: boolean }> {
80  if (!can(project.role, "comment")) throw new AiRefusal("You may not flag anything on this project.");
81  const message = input.message.trim();
82  if (!message || message.length > 2000) throw new AiRefusal("A flag needs a message of up to 2,000 characters.");
83  const excerpt = input.excerpt?.trim() || null;
84  const check = session.viewer.isReviewer ? "review" : "ai";
85  const full = `${message} (from ${session.client})`;
86  const key = await fingerprint([check, full, excerpt]);
87  const d = drizzle(db);
88  const inserted = await d
89    .insert(findings)
90    .values({ projectId: project.id, path: itemId, checkName: check, message: full, excerpt, fingerprint: key })
91    .onConflictDoNothing()
92    .returning({ id: findings.id });
93  if (inserted[0]) return { id: inserted[0].id, duplicate: false };
94  const existing = await d
95    .select({ id: findings.id })
96    .from(findings)
97    .where(and(eq(findings.projectId, project.id), eq(findings.path, itemId), eq(findings.fingerprint, key)))
98    .get();
99  return { id: existing!.id, duplicate: true };
100}
101
102export type ProjectFlag = ItemFinding & { itemId: string; title: string | null; onSite: boolean };
103
104/**
105 * Every flag on a site project, open first then newest first, including flags on items the site does
106 * not have (a proof item, a post since deleted), which no editor page can reach. `onSite` says whether
107 * Carrel's index of the site has the item.
108 */
109export async function projectFlags(db: D1Database, project: ProjectRole): Promise<ProjectFlag[]> {
110  if (!can(project.role, "read")) throw new Response("Forbidden", { status: 403 });
111  const rows = await drizzle(db)
112    .select({
113      id: findings.id,
114      itemId: findings.path,
115      check: findings.checkName,
116      message: findings.message,
117      excerpt: findings.excerpt,
118      status: findings.status,
119      createdAt: findings.createdAt,
120      title: siteItems.title,
121    })
122    .from(findings)
123    .leftJoin(siteItems, and(eq(siteItems.projectId, findings.projectId), eq(siteItems.itemId, findings.path)))
124    .where(eq(findings.projectId, project.id))
125    .orderBy(asc(sql`${findings.status} = 'dismissed'`), desc(findings.createdAt), desc(findings.id))
126    .all();
127  return rows.map((r) => ({ ...r, onSite: r.title !== null }));
128}
129
130/** Checks and reviewers flag; a person decides. Dismissing clears a flag for publish, so it is the Owner's. */
131export async function dismissItemFinding(db: D1Database, project: ProjectRole, viewer: Viewer, itemId: string, id: number, now = new Date()) {
132  if (!can(project.role, "publish")) throw new Response("Forbidden", { status: 403 });
133  const result = await drizzle(db)
134    .update(findings)
135    .set({ status: "dismissed", dismissedBy: viewer.id, dismissedAt: now.toISOString() })
136    .where(and(eq(findings.id, id), eq(findings.projectId, project.id), eq(findings.path, itemId)))
137    .returning({ id: findings.id });
138  if (result.length === 0) throw new Response("Not found", { status: 404 });
139}
140
141// ---------- AI drafts, beside the person's own
142
143export async function saveAiDraft(
144  env: Env,
145  project: SiteProject,
146  session: AiSession,
147  itemId: string,
148  input: { source: string; note?: string },
149  fetcher?: typeof fetch,
150): Promise<{ id: number; baseVersion: string | null }> {
151  if (session.viewer.isReviewer) throw new AiRefusal("A reviewer flags; it does not write text. Use carrel_add_finding.");
152  if (!can(project.role, "edit")) throw new AiRefusal("You may not write drafts on this project.");
153  if (!input.source.trim()) throw new AiRefusal("The draft is empty.");
154  let baseVersion: string | null = null;
155  try {
156    baseVersion = (await readDoc(env, project, itemId, fetcher))?.version ?? null;
157  } catch {
158    // The site not answering does not stop a draft that lives only in Carrel.
159  }
160  const [row] = await drizzle(env.DB)
161    .insert(aiDrafts)
162    .values({
163      projectId: project.id,
164      itemId,
165      personId: session.viewer.id,
166      client: session.client,
167      source: input.source.replace(/\r\n/g, "\n"),
168      baseVersion,
169      note: (input.note ?? "").trim().slice(0, 500),
170    })
171    .returning({ id: aiDrafts.id });
172  return { id: row!.id, baseVersion };
173}
174
175export type AiDraftSummary = { id: number; client: string; note: string; createdAt: string; baseVersion: string | null; words: number };
176
177/** The AI drafts a person's own sessions saved for this item, newest first. Private to the person, as drafts are. */
178export async function listAiDrafts(db: D1Database, project: ProjectRole, viewer: Viewer, itemId: string): Promise<AiDraftSummary[]> {
179  if (!can(project.role, "read")) throw new Response("Forbidden", { status: 403 });
180  const rows = await drizzle(db)
181    .select({ id: aiDrafts.id, client: aiDrafts.client, note: aiDrafts.note, createdAt: aiDrafts.createdAt, baseVersion: aiDrafts.baseVersion, source: aiDrafts.source })
182    .from(aiDrafts)
183    .where(and(eq(aiDrafts.projectId, project.id), eq(aiDrafts.itemId, itemId), eq(aiDrafts.personId, viewer.id)))
184    .orderBy(desc(aiDrafts.createdAt), desc(aiDrafts.id))
185    .all();
186  return rows.map(({ source, ...r }) => ({ ...r, words: source.split(/\s+/).filter(Boolean).length }));
187}
188
189export async function readAiDraft(db: D1Database, project: ProjectRole, viewer: Viewer, itemId: string, id: number) {
190  if (!can(project.role, "read")) throw new Response("Forbidden", { status: 403 });
191  const row = await drizzle(db)
192    .select()
193    .from(aiDrafts)
194    .where(and(eq(aiDrafts.id, id), eq(aiDrafts.projectId, project.id), eq(aiDrafts.itemId, itemId), eq(aiDrafts.personId, viewer.id)))
195    .get();
196  if (!row) throw new Response("Not found", { status: 404 });
197  return row;
198}
199
200// ---------- publish by instruction
201
202export type AiPublishResult = { ok: true; version: string; changeId: string; emailed: boolean } | { ok: false; message: string };
203
204/** The line the record, the email and the editor all use (decision 2c). */
205export function publishedByLine(client: string): string {
206  return `Published by ${client} on Dustin's instruction.`;
207}
208
209/**
210 * Publishes the item as it stands on the site at `expectedVersion`: no text travels with it, so an
211 * AI can only publish what a person saved. Every refusal comes before the site is asked anything.
212 */
213export async function aiPublish(
214  env: Env,
215  project: SiteProject,
216  session: AiSession,
217  itemId: string,
218  expectedVersion: string,
219  opts: { fetcher?: typeof fetch; carrelOrigin: string },
220): Promise<AiPublishResult> {
221  if (session.viewer.isReviewer) throw new AiRefusal("A reviewer never publishes.");
222  // Owner only, whatever a shared person's role: decision 2a gives publish to Dustin's sessions alone.
223  if (!session.viewer.isOwner || project.role !== "owner") throw new AiRefusal("Only the Owner's own sessions may publish.");
224  const open = (await itemFindings(env.DB, project, itemId)).filter((f) => f.status === "open");
225  if (open.length > 0) {
226    throw new AiRefusal(
227      `Publish is refused while ${open.length} flag${open.length === 1 ? " is" : "s are"} open on this post: ${open
228        .map((f) => f.message)
229        .join(" | ")} Dustin fixes the text or dismisses each flag in Carrel first.`,
230    );
231  }
232
233  const outcome: WriteOutcome = await writeToSite(env, project, session.viewer, itemId, { action: "publish", expectedVersion }, opts.fetcher, {
234    client: session.client,
235  });
236  if (!outcome.ok) return { ok: false, message: outcome.message };
237
238  const d = drizzle(env.DB);
239  await d.insert(aiPublications).values({
240    changeId: outcome.changeId,
241    projectId: project.id,
242    itemId,
243    personId: session.viewer.id,
244    client: session.client,
245    version: outcome.version,
246  });
247
248  // The email goes out now; if it cannot, the record keeps the error and the health check reports it.
249  let emailed = false;
250  try {
251    const doc = await readDoc(env, project, itemId, opts.fetcher).catch(() => null);
252    const title = doc?.title || itemId;
253    const unpublish = `${opts.carrelOrigin}/p/${encodeURIComponent(project.slug)}/e/${encodeURIComponent(itemId)}/unpublish`;
254    await env.EMAIL.send({
255      from: env.ALERT_FROM,
256      to: env.ALERT_EMAIL,
257      subject: `Carrel: ${session.client} published "${title}"`,
258      text: [
259        publishedByLine(session.client),
260        "",
261        `${title} on ${siteEntry(project.site).name}${doc?.path ? `: ${doc.path}` : ""}`,
262        `Version ${outcome.version}, change ${outcome.changeId}.`,
263        "",
264        `Unpublish it: ${unpublish}`,
265        "",
266      ].join("\n"),
267    });
268    emailed = true;
269    await d.update(aiPublications).set({ emailedAt: new Date().toISOString() }).where(eq(aiPublications.changeId, outcome.changeId));
270  } catch (error) {
271    const message = error instanceof Error ? error.message : String(error);
272    console.error(JSON.stringify({ aiPublish: "email-failed", changeId: outcome.changeId, error: message }));
273    await d.update(aiPublications).set({ emailError: message }).where(eq(aiPublications.changeId, outcome.changeId));
274  }
275  return { ok: true, version: outcome.version, changeId: outcome.changeId, emailed };
276}
277
278/** The last AI publish of an item, for the editor to show who published it. */
279export async function lastAiPublication(db: D1Database, project: SiteProject, itemId: string) {
280  return (
281    (await drizzle(db)
282      .select({ client: aiPublications.client, publishedAt: aiPublications.publishedAt, emailedAt: aiPublications.emailedAt })
283      .from(aiPublications)
284      .where(and(eq(aiPublications.projectId, project.id), eq(aiPublications.itemId, itemId)))
285      .orderBy(desc(aiPublications.publishedAt))
286      .get()) ?? null
287  );
288}
289
290// ---------- social posts, drafted by the session that finished the piece (decision 5)
291
292/**
293 * Stores an AI session's drafted social post for the queue, by the event id the routine was given or
294 * by account and item. Social posts are Dustin's alone, so only his own sessions may draft them.
295 */
296export async function aiDraftSocialPost(
297  db: D1Database,
298  session: AiSession,
299  input: { eventId: number; text: string } | { accountKey: string; projectId: number; itemId: string; text: string },
300): Promise<{ postId: number }> {
301  if (session.viewer.isReviewer || !session.viewer.isOwner) throw new AiRefusal("Social posts are Dustin's: only his own sessions may draft them.");
302  const result =
303    "eventId" in input
304      ? await draftForEvent(db, { eventId: input.eventId, text: input.text, createdBy: session.client })
305      : await draftSocialPost(db, { ...input, createdBy: session.client });
306  if (!result.ok) throw new AiRefusal(result.error);
307  return { postId: result.postId };
308}