app/lib/operator/api.server.ts

Functions

Imports

It imports app/db/cv.ts, app/db/dictionary.ts, app/db/index.ts, app/db/pages.ts, app/db/phages.ts, app/db/procedures.ts, app/db/publications.ts, app/db/registry.ts, app/db/roster.ts, app/db/schema.ts, app/kb/procedures/parse.mjs, app/kb/procedures/save.server.ts, app/kb/registry/compile.mjs, app/kb/registry/kinds.mjs, app/kb/registry/save.server.ts, app/lib/backup/d1-backup.server.ts, app/lib/citations.server.ts, app/lib/content/slug.mjs, app/lib/cv/save.server.ts, app/lib/dictionary/save.server.ts, app/lib/editor/converge.mjs, app/lib/editor/github.server.ts, app/lib/editor/publish-policy.mjs, app/lib/editor/publish.server.ts, app/lib/editor/write-path.server.ts, app/lib/error-message.mjs, app/lib/llms/save.server.ts, app/lib/operator/auth.server.ts, app/lib/operator/descriptors.ts, app/lib/operator/sync-tools.server.ts, app/lib/operator/upload-media.server.ts, app/lib/pages/save.server.ts, app/lib/phages/save.server.ts, app/lib/publications/parse.mjs, app/lib/publications/save.server.ts, app/lib/publications/sources.server.ts, app/lib/roster/save.server.ts, app/lib/search/zero-result.server.ts, app/lib/webmention/decide.server.ts. Imported by app/routes/admin._index.tsx, app/routes/api.operator.ts.

Source

1// Every write calls the same functions the browser editor's action calls; nothing here re-implements a gate.
2
3import { DIVERGENCE_ERROR_NAME } from "~/lib/editor/converge.mjs";
4
5import { getAdminPostRow, listPostsForOperator, listWebmentionsForAdmin } from "~/db";
6import { webmentions as webmentionsTable } from "~/db/schema";
7import {
8  currentHead,
9  deletePost,
10  savePost,
11  EditorError,
12  GitHubError,
13  PolicyError,
14  type Actor,
15} from "~/lib/editor/publish.server";
16import { UNCHANGED_NOTE } from "~/lib/editor/write-path.server";
17import { SLUG_MAX_LENGTH, SLUG_PATTERN, postPath } from "~/lib/content/slug.mjs";
18import { decideMention } from "~/lib/webmention/decide.server";
19import { readState } from "~/lib/editor/publish-policy.mjs";
20import { readFile } from "~/lib/editor/github.server";
21
22import { backupD1 } from "~/lib/backup/d1-backup.server";
23import type { OperatorEnv } from "./auth.server";
24import type { ToolName, ToolResult } from "./descriptors";
25import {
26  backupMedia,
27  syncAsk,
28  syncDictionary,
29  syncMedia,
30  syncLlms,
31  syncCv,
32  syncCvPdf,
33  syncPages,
34  syncPosts,
35  syncProcedures,
36  syncPublications,
37  syncPhages,
38  syncRegistry,
39  syncRoster,
40  syncStatus,
41} from "./sync-tools.server";
42import { uploadMediaTool } from "./upload-media.server";
43import { errorMessage } from "~/lib/error-message.mjs";
44import { listProceduresForOperator } from "~/db/procedures";
45import { purgeZeroResults } from "~/lib/search/zero-result.server";
46import { listPublicationIdentities, listPublishedPublications } from "~/db/publications";
47import { refreshCitations } from "~/lib/citations.server";
48import { checkPublicationSources } from "~/lib/publications/sources.server";
49import { compilePublicationFor, fileIsDraft } from "~/lib/publications/save.server";
50import { publicationPath } from "~/lib/publications/parse.mjs";
51import { ProcedureInvalid, readProcedure, saveProcedure } from "~/kb/procedures/save.server";
52import { procedurePath } from "~/kb/procedures/parse.mjs";
53import { listCvRows } from "~/db/cv";
54import { listPageRows } from "~/db/pages";
55import { CvInvalid, readCvFile } from "~/lib/cv/save.server";
56import { listDictionaryRows } from "~/db/dictionary";
57import { readDictionary } from "~/lib/dictionary/save.server";
58import { PageInvalid, readPage } from "~/lib/pages/save.server";
59import { readLlms } from "~/lib/llms/save.server";
60import { listPhageRows } from "~/db/phages";
61import { PHAGE_SLUG, readPhage } from "~/lib/phages/save.server";
62import { listRegistryRows } from "~/db/registry";
63import { parseRegistrySlug } from "~/kb/registry/compile.mjs";
64import { KINDS } from "~/kb/registry/kinds.mjs";
65import { readRegistryItem } from "~/kb/registry/save.server";
66import { listRosterRows } from "~/db/roster";
67import { COHORT_SLUG, readRoster } from "~/lib/roster/save.server";
68
69// Re-exported so the routes keep one import path for the operator surface.
70export { TOOL_DESCRIPTORS, isToolName, toolNames } from "./descriptors";
71export { syncStatus };
72
73// Validated like the write path: the slug goes into a repository path via `encodeURI`, which does not
74// escape `.`, `/` or `?`.
75function readSlug(args: Record<string, unknown>, tool: string) {
76  const slug = String(args.slug ?? "").trim();
77  if (!slug) return { slug: "", error: `${tool} requires a slug.` };
78  if (!SLUG_PATTERN.test(slug)) {
79    return { slug: "", error: `${tool} requires a lowercase kebab-case slug.` };
80  }
81  // The length bound too: a read must not accept a slug the write schema refuses.
82  if (slug.length > SLUG_MAX_LENGTH) {
83    return {
84      slug: "",
85      error: `${tool} requires a slug of at most ${SLUG_MAX_LENGTH} characters.`,
86    };
87  }
88  return { slug, error: "" };
89}
90
91// Unfiltered by default: a queue that hides its failures cannot tell "nothing arrived" from "all refused".
92async function listMentionsTool(
93  env: OperatorEnv,
94  args: Record<string, unknown>,
95): Promise<ToolResult> {
96  const status = typeof args.status === "string" ? args.status.trim() : "";
97
98  // A 400, not `[]`: an agent that mistyped a status would conclude the queue was empty. Checked
99  // before the read, and against the schema's own enum, so a new status cannot be refused here.
100  const allowed: readonly string[] = webmentionsTable.status.enumValues;
101  if (status && !allowed.includes(status)) {
102    return {
103      ok: false,
104      status: 400,
105      error: `Unknown status ${JSON.stringify(status)}. One of: ${allowed.join(", ")}.`,
106    };
107  }
108
109  const rows = await listWebmentionsForAdmin(env);
110
111  const filtered = status ? rows.filter((row) => row.status === status) : rows;
112
113  return {
114    ok: true,
115    data: {
116      status: status || "all",
117      count: filtered.length,
118      mentions: filtered.map((row) => ({
119        id: row.id,
120        source: row.sourceUrl,
121        target: row.targetSlug,
122        status: row.status,
123        author: row.authorName,
124        authorUrl: row.authorUrl,
125        excerpt: row.excerpt,
126        failureReason: row.failureReason,
127        receivedAt: row.receivedAt,
128        verifiedAt: row.verifiedAt,
129        decidedAt: row.decidedAt,
130      })),
131    },
132  };
133}
134
135// Calls `decideMention` only: the write and the cache purge travel together there.
136async function decideMentionTool(
137  env: OperatorEnv,
138  actor: Actor,
139  args: Record<string, unknown>,
140): Promise<ToolResult> {
141  const id = typeof args.id === "number" ? args.id : Number(args.id);
142  if (!Number.isInteger(id) || id <= 0) {
143    return {
144      ok: false,
145      status: 400,
146      error: `decide_mention needs a positive integer id, got ${JSON.stringify(args.id)}. ` +
147        `Call list_mentions for the ids.`,
148    };
149  }
150
151  const decision = typeof args.decision === "string" ? args.decision.trim() : "";
152  if (decision !== "approve" && decision !== "reject" && decision !== "delete") {
153    return {
154      ok: false,
155      status: 400,
156      error: `decide_mention needs a decision of approve, reject or delete, got ` +
157        `${JSON.stringify(args.decision)}.`,
158    };
159  }
160
161  const result = await decideMention(env, id, decision, actor);
162
163  // `changed: false` is an answer, not a 404, so a caller does not retry something that cannot succeed.
164  return {
165    ok: true,
166    data: {
167      id,
168      decision,
169      changed: result.changed,
170      slug: result.slug,
171      purged: result.changed ? `post:${result.slug}` : null,
172      // True when the page's cache purge failed: the change is stored but the page stays stale.
173      purgeFailed: result.purged === false,
174    },
175  };
176}
177
178// Errors are translated, not thrown: a gate rejection returns its own message, field and line, so an
179// agent can fix its own mistake.
180export async function runTool(
181  env: OperatorEnv,
182  actor: Actor,
183  name: ToolName,
184  args: Record<string, unknown>,
185): Promise<ToolResult> {
186  try {
187    switch (name) {
188      case "list_posts":
189        return { ok: true, data: await listPosts(env) };
190      case "get_post":
191        return await getPost(env, args);
192      case "save_post":
193        return await savePostTool(env, actor, args);
194      case "delete_post":
195        return await deletePostTool(env, actor, args);
196      case "sync_status":
197        return { ok: true, data: await syncStatus(env) };
198
199      case "sync_ask":
200        return await syncAsk(env);
201
202      case "sync_media":
203        return await syncMedia(env);
204
205      case "sync_posts":
206        return await syncPosts(env);
207
208      case "sync_procedures":
209        return await syncProcedures(env);
210
211      case "sync_dictionary":
212        return await syncDictionary(env);
213
214      case "sync_pages":
215        return await syncPages(env);
216
217      case "sync_cv":
218        return await syncCv(env);
219
220      case "sync_cv_pdf":
221        return await syncCvPdf(env);
222
223      case "sync_publications":
224        return await syncPublications(env);
225
226      case "sync_llms":
227        return await syncLlms(env);
228
229      case "sync_roster":
230        return await syncRoster(env);
231
232      case "sync_phages":
233        return await syncPhages(env);
234
235      case "sync_registry":
236        return await syncRegistry(env);
237
238      case "backup_media":
239        return await backupMedia(env);
240
241      case "backup_d1":
242        return { ok: true, data: await backupD1(env) };
243
244      case "upload_media":
245        return await uploadMediaTool(env, args);
246
247      case "list_mentions":
248        return await listMentionsTool(env, args);
249
250      case "decide_mention":
251        return await decideMentionTool(env, actor, args);
252
253      case "list_procedures": {
254        const procedures = await listProceduresForOperator(env);
255        return { ok: true, data: { headSha: await currentHead(env), count: procedures.length, procedures } };
256      }
257
258      case "get_procedure":
259        return await getProcedureTool(env, args);
260
261      case "save_procedure":
262        return await saveProcedureTool(env, actor, args);
263
264      case "list_publications": {
265        const rows = await listPublicationIdentities(env);
266        const publications = rows.map((row) => ({
267          slug: row.slug,
268          doi: (JSON.parse(row.record) as { doi: string | null }).doi,
269          stage: row.stage,
270          type: row.type,
271          title: row.title,
272          year: row.year,
273          draft: row.status === "draft",
274        }));
275        return { ok: true, data: { headSha: await currentHead(env), count: publications.length, publications } };
276      }
277
278      case "get_publication":
279        return await getPublicationTool(env, args);
280
281      case "refresh_citations":
282        return await refreshCitationsTool(env, args);
283
284      case "check_publications": {
285        const report = await checkPublicationSources(env);
286        if (report.failures.length > 0) {
287          const names = report.failures.map((f) => `${f.source} (${f.detail})`).join(", ");
288          return { ok: false, status: 502, error: `Not every source could be read: ${names}.`, detail: report };
289        }
290        return { ok: true, data: report };
291      }
292
293      case "list_pages": {
294        const pageRows = await listPageRows(env);
295        return { ok: true, data: { headSha: await currentHead(env), count: pageRows.length, pages: pageRows } };
296      }
297
298      case "get_page":
299        return await getPageTool(env, args);
300
301      case "get_llms":
302        return await getLlmsTool(env);
303
304
305      case "list_cv": {
306        const cvRows = await listCvRows(env);
307        const files = cvRows.map(({ record: _record, ...row }) => row);
308        return { ok: true, data: { headSha: await currentHead(env), count: files.length, files } };
309      }
310
311      case "get_cv":
312        return await getCvTool(env, args);
313      case "list_dictionary": {
314        const entries = await listDictionaryRows(env);
315        return { ok: true, data: { headSha: await currentHead(env), count: entries.length, entries } };
316      }
317
318      case "get_dictionary":
319        return await getDictionaryTool(env, args);
320
321      case "list_roster": {
322        const rows = await listRosterRows(env);
323        return {
324          ok: true,
325          data: {
326            headSha: await currentHead(env),
327            count: rows.length,
328            cohorts: rows.map((row) => ({
329              slug: row.slug,
330              year: row.year,
331              photo: row.cohort.photo?.src ?? null,
332              researchers: row.cohort.researchers.length,
333            })),
334          },
335        };
336      }
337
338      case "get_roster":
339        return await getRosterTool(env, args);
340
341      case "list_phages": {
342        const rows = await listPhageRows(env);
343        return {
344          ok: true,
345          data: {
346            headSha: await currentHead(env),
347            count: rows.length,
348            // Only what the public table already shows: the name, year, host, county, PhagesDB record, paper and notes.
349            phages: rows.map((row) => ({ slug: row.slug, ...row.phage })),
350          },
351        };
352      }
353
354      case "get_phage":
355        return await getPhageTool(env, args);
356
357      case "list_registry": {
358        const kind = String(args.kind ?? "").trim();
359        if (kind && !Object.hasOwn(KINDS, kind)) {
360          return { ok: false, status: 400, error: `"${kind}" is not a registry kind; the kinds are ${Object.keys(KINDS).join(", ") || "none yet"}.` };
361        }
362        const rows = (await listRegistryRows(env)).filter((row) => !kind || row.kind === kind);
363        return {
364          ok: true,
365          data: {
366            headSha: await currentHead(env),
367            count: rows.length,
368            items: rows.map(({ syncedAt: _syncedAt, ...item }) => ({ slug: `${item.kind}/${item.id}`, ...item })),
369          },
370        };
371      }
372
373      case "get_registry":
374        return await getRegistryTool(env, args);
375
376      case "purge_zero_results": {
377        const purged = await purgeZeroResults(env);
378        return { ok: true, data: { purged } };
379      }
380    }
381  } catch (error) {
382    return translate(error);
383  }
384}
385
386function translate(error: unknown): ToolResult {
387  // Every message the validator gave, so an agent can fix its own edit; nothing was committed.
388  if (error instanceof ProcedureInvalid || error instanceof PageInvalid || error instanceof CvInvalid) {
389    return { ok: false, status: 422, error: error.message, detail: { errors: error.errors } };
390  }
391
392  // Names the policy so a caller can branch on it rather than string-match the prose.
393  if (error instanceof PolicyError) {
394    return {
395      ok: false,
396      status: 403,
397      error: error.message,
398      detail: { policy: error.policy },
399    };
400  }
401
402  if (error instanceof EditorError) {
403    return {
404      ok: false,
405      status: 422,
406      error: error.message,
407      detail: { field: error.field ?? null, line: error.line ?? null },
408    };
409  }
410
411  // A divergence means the commit LANDED, so retrying is the one thing that does not help (500: the
412  // caller did nothing wrong). Matched on `name`, not `instanceof`: the module can load in two build graphs.
413  if (error instanceof Error && error.name === DIVERGENCE_ERROR_NAME) {
414    return {
415      ok: false,
416      status: 500,
417      error: error.message,
418      detail: { code: "d1-divergence", committed: true, retrySave: false },
419    };
420  }
421
422  if (error instanceof GitHubError) {
423    return {
424      ok: false,
425      status: error.conflict ? 409 : 502,
426      error: error.message,
427      detail: { conflict: Boolean(error.conflict) },
428    };
429  }
430
431  // Not a recognized failure: logged with its stack, since the caller receives only the message.
432  console.error(JSON.stringify({ alert: "operator-tool-unrecognized-error", detail: errorMessage(error) }));
433  return {
434    ok: false,
435    status: 500,
436    error: errorMessage(error),
437  };
438}
439
440async function listPosts(env: OperatorEnv) {
441  // D1, not the repository: the rows are what the site serves.
442  const rows = await listPostsForOperator(env);
443  return {
444    headSha: await currentHead(env),
445    count: rows.length,
446    posts: rows.map((p) => ({
447      slug: p.slug,
448      title: p.title,
449      description: p.description,
450      date: p.publishAt ? p.publishAt.toISOString().slice(0, 10) : null,
451      publishAt: p.publishAt ? p.publishAt.toISOString() : null,
452      draft: p.status === "draft",
453      tags: p.tags,
454      series: p.series,
455      part: p.part,
456      updated: p.updatedAt ? p.updatedAt.toISOString().slice(0, 10) : null,
457      sourcePath: p.sourcePath,
458    })),
459  };
460}
461
462async function getPost(env: OperatorEnv, args: Record<string, unknown>): Promise<ToolResult> {
463  const parsed = readSlug(args, "get_post");
464  if (parsed.error) return { ok: false, status: 400, error: parsed.error };
465  const slug = parsed.slug;
466
467  const file = await readFile(env, postPath(slug));
468  if (!file) return { ok: false, status: 404, error: `No post exists with slug "${slug}".` };
469  const raw = file.content;
470
471  const record = await getAdminPostRow(env, slug);
472  const state = readState(raw);
473
474  return {
475    ok: true,
476    data: {
477      slug,
478      raw,
479      headSha: await currentHead(env),
480      draft: state.draft,
481      // Answered from the file, so a caller learns it before meeting a 403.
482      firstPublished: state.firstPublished,
483      operatorMayPublish: state.firstPublished !== null,
484      html: record?.html ?? null,
485      readingTimeMinutes: record?.readingTimeMinutes ?? null,
486    },
487  };
488}
489
490async function savePostTool(
491  env: OperatorEnv,
492  actor: Actor,
493  args: Record<string, unknown>,
494): Promise<ToolResult> {
495  const parsed = readSlug(args, "save_post");
496  if (parsed.error) return { ok: false, status: 400, error: parsed.error };
497  const slug = parsed.slug;
498  const raw = typeof args.raw === "string" ? args.raw : "";
499  if (!raw.trim()) {
500    return {
501      ok: false,
502      status: 400,
503      error: "save_post requires `raw`: the complete markdown file, frontmatter included.",
504    };
505  }
506
507  // No `expectedHeadSha` means unconditional, deliberately: an agent has no page to reload.
508  const expectedHeadSha =
509    typeof args.expectedHeadSha === "string" && args.expectedHeadSha
510      ? args.expectedHeadSha
511      : null;
512
513  const existing = await readFile(env, postPath(slug));
514  const isNew = args.isNew === undefined ? existing === null : args.isNew === true;
515
516  const result = await savePost(env, { slug, raw, expectedHeadSha, isNew, actor });
517
518  return {
519    ok: true,
520    data: {
521      slug,
522      commitSha: result.commitSha,
523      unchanged: result.unchanged,
524      ...(result.unchanged ? { note: UNCHANGED_NOTE } : {}),
525      created: isNew,
526      draft: result.record.draft,
527      published: result.published,
528      firstPublished: result.firstPublished,
529      // The AI index cannot fail a save, so its outcome is reported rather than raised.
530      askSync: result.askSync,
531      // Other posts' related and backlinks lists this save rewrote, or why it could not: reported, never raised.
532      neighbours: result.neighbours,
533      purged: result.purged,
534    },
535  };
536}
537
538async function getProcedureTool(env: OperatorEnv, args: Record<string, unknown>): Promise<ToolResult> {
539  const parsed = readSlug(args, "get_procedure");
540  if (parsed.error) return { ok: false, status: 400, error: parsed.error };
541  const procedure = await readProcedure(env, parsed.slug);
542  if (!procedure) return { ok: false, status: 404, error: `No procedure exists with slug "${parsed.slug}".` };
543  return { ok: true, data: { ...procedure, headSha: await currentHead(env) } };
544}
545
546async function getPublicationTool(env: OperatorEnv, args: Record<string, unknown>): Promise<ToolResult> {
547  const slug = String(args.slug ?? "").trim();
548  if (!slug || !SLUG_PATTERN.test(slug)) {
549    return { ok: false, status: 400, error: "get_publication requires a lowercase kebab-case slug." };
550  }
551  const file = await readFile(env, publicationPath(slug));
552  if (!file) return { ok: false, status: 404, error: `No publication exists with slug "${slug}".` };
553  const compiled = await compilePublicationFor(env, slug, file.content);
554  return {
555    ok: true,
556    data: {
557      slug,
558      raw: file.content,
559      headSha: await currentHead(env),
560      draft: compiled.ok ? compiled.draft : fileIsDraft(file.content),
561      record: compiled.ok ? compiled.record : null,
562      errors: compiled.ok ? [] : compiled.errors,
563    },
564  };
565}
566
567/**
568 * The weekly refresh the watchdog calls. Every failure is returned, never swallowed: a partial refresh is a
569 * 502 whose detail names each DOI that kept its old count, and the counts that did refresh are stored.
570 */
571async function refreshCitationsTool(env: OperatorEnv, args: Record<string, unknown>): Promise<ToolResult> {
572  const published = (await listPublishedPublications(env)).flatMap((p) => (p.doi ? [p.doi] : []));
573  let dois: string[];
574  if (args.dois === undefined) {
575    dois = published;
576  } else if (Array.isArray(args.dois) && args.dois.every((d) => typeof d === "string" && d.trim() !== "")) {
577    // Only a paper the site lists has a count to show, so any other DOI would store an orphan row and
578    // spend an outbound call (Grok audit 2026-10-21, DE-7).
579    const key = (doi: string) => doi.trim().toLowerCase();
580    const listed = new Set(published.map(key));
581    const unlisted = (args.dois as string[]).filter((d) => !listed.has(key(d)));
582    if (unlisted.length > 0) {
583      return {
584        ok: false,
585        status: 400,
586        error: `refresh_citations refreshes only published papers' DOIs; not published: ${unlisted.slice(0, 5).join(", ")}.`,
587      };
588    }
589    dois = [...new Set((args.dois as string[]).map(key))];
590  } else {
591    return { ok: false, status: 400, error: "refresh_citations takes dois as a list of DOI strings, or none." };
592  }
593  const result = await refreshCitations(env, dois);
594  if (result.failures.length > 0) {
595    return {
596      ok: false,
597      status: 502,
598      error: `${result.failures.length} of ${dois.length} citation counts did not refresh; each kept the count it had.`,
599      detail: result,
600    };
601  }
602  return { ok: true, data: result };
603}
604
605async function saveProcedureTool(
606  env: OperatorEnv,
607  actor: Actor,
608  args: Record<string, unknown>,
609): Promise<ToolResult> {
610  const parsed = readSlug(args, "save_procedure");
611  if (parsed.error) return { ok: false, status: 400, error: parsed.error };
612  const raw = typeof args.raw === "string" ? args.raw : "";
613  if (!raw.trim()) {
614    return { ok: false, status: 400, error: "save_procedure requires `raw`: the complete procedure file." };
615  }
616  const expectedHeadSha =
617    typeof args.expectedHeadSha === "string" && args.expectedHeadSha ? args.expectedHeadSha : null;
618  const isNew =
619    args.isNew === undefined ? (await readFile(env, procedurePath(parsed.slug))) === null : args.isNew === true;
620  return { ok: true, data: await saveProcedure(env, { slug: parsed.slug, raw, expectedHeadSha, isNew, actor }) };
621}
622
623async function getCvTool(env: OperatorEnv, args: Record<string, unknown>): Promise<ToolResult> {
624  const slug = String(args.slug ?? "").trim();
625  if (!slug) return { ok: false, status: 400, error: "get_cv requires a slug, such as grants or profile." };
626  const file = await readCvFile(env, slug);
627  if (!file) return { ok: false, status: 404, error: `No file exists for the CV file "${slug}".` };
628  return { ok: true, data: { ...file, headSha: await currentHead(env) } };
629}
630
631async function getDictionaryTool(env: OperatorEnv, args: Record<string, unknown>): Promise<ToolResult> {
632  const key = String(args.key ?? "").trim();
633  if (!key || !SLUG_PATTERN.test(key)) {
634    return { ok: false, status: 400, error: "get_dictionary requires a lowercase kebab-case key, such as capsid." };
635  }
636  const entry = await readDictionary(env, key);
637  if (!entry) return { ok: false, status: 404, error: `No dictionary entry has the key "${key}".` };
638  return { ok: true, data: { ...entry, headSha: await currentHead(env) } };
639}
640
641async function getPageTool(env: OperatorEnv, args: Record<string, unknown>): Promise<ToolResult> {
642  const path = String(args.path ?? "").trim();
643  if (!path) return { ok: false, status: 400, error: "get_page requires a path, such as /research/phages." };
644  const page = await readPage(env, path);
645  if (!page) return { ok: false, status: 404, error: `No file exists for the page "${path}".` };
646  return { ok: true, data: { ...page, headSha: await currentHead(env) } };
647}
648
649async function getLlmsTool(env: OperatorEnv): Promise<ToolResult> {
650  const llms = await readLlms(env);
651  if (!llms) return { ok: false, status: 404, error: "No content/llms.txt exists in the repository." };
652  return { ok: true, data: { ...llms, headSha: await currentHead(env) } };
653}
654
655async function getPhageTool(env: OperatorEnv, args: Record<string, unknown>): Promise<ToolResult> {
656  const slug = String(args.slug ?? "").trim();
657  if (!PHAGE_SLUG.test(slug)) {
658    return { ok: false, status: 400, error: "get_phage requires a slug that is a phage's name in lower case, such as acorn15." };
659  }
660  const phage = await readPhage(env, slug);
661  if (!phage) return { ok: false, status: 404, error: `No file exists for the phage ${slug}.` };
662  return { ok: true, data: { ...phage, headSha: await currentHead(env) } };
663}
664
665async function getRegistryTool(env: OperatorEnv, args: Record<string, unknown>): Promise<ToolResult> {
666  const slug = String(args.slug ?? "").trim();
667  const address = parseRegistrySlug(slug);
668  if (!address) {
669    return { ok: false, status: 400, error: "get_registry requires a slug <kind>/<id> in lower-case letters, digits and hyphens, such as primer/m13-forward." };
670  }
671  if (!Object.hasOwn(KINDS, address.kind)) {
672    return { ok: false, status: 400, error: `"${address.kind}" is not a registry kind; the kinds are ${Object.keys(KINDS).join(", ") || "none yet"}.` };
673  }
674  const item = await readRegistryItem(env, slug);
675  if (!item) return { ok: false, status: 404, error: `No file exists for the registry item ${slug}.` };
676  return { ok: true, data: { ...item, headSha: await currentHead(env) } };
677}
678
679async function getRosterTool(env: OperatorEnv, args: Record<string, unknown>): Promise<ToolResult> {
680  const slug = String(args.slug ?? "").trim();
681  if (!COHORT_SLUG.test(slug)) {
682    return { ok: false, status: 400, error: "get_roster requires a slug that is a cohort's four-digit year, such as 2025." };
683  }
684  const cohort = await readRoster(env, slug);
685  if (!cohort) return { ok: false, status: 404, error: `No file exists for the ${slug} cohort.` };
686  return { ok: true, data: { ...cohort, headSha: await currentHead(env) } };
687}
688
689async function deletePostTool(
690  env: OperatorEnv,
691  actor: Actor,
692  args: Record<string, unknown>,
693): Promise<ToolResult> {
694  const parsed = readSlug(args, "delete_post");
695  if (parsed.error) return { ok: false, status: 400, error: parsed.error };
696  const slug = parsed.slug;
697
698  const result = await deletePost(env, {
699    slug,
700    expectedHeadSha:
701      typeof args.expectedHeadSha === "string" && args.expectedHeadSha
702        ? args.expectedHeadSha
703        : null,
704    actor,
705  });
706
707  return {
708    ok: true,
709    data: {
710      slug,
711      commitSha: result.commitSha,
712      purged: result.purged,
713      askRemoval: result.askRemoval,
714    },
715  };
716}