app/lib/operator/descriptors.ts

Functions

Imports

It imports no other module of this repo. Imported by app/lib/operator/api.server.ts, app/lib/operator/sync-tools.server.ts, app/lib/operator/upload-media.server.ts.

Source

1// The operator tool surface: the tool names, what each takes and returns, and the result shape every
2// tool answers with. `GET /api/operator` serves the descriptors; check:destructive reads them.
3
4export type ToolResult =
5  | { ok: true; data: unknown }
6  | { ok: false; status: number; error: string; detail?: unknown };
7
8const TOOLS = [
9  "list_posts",
10  "get_post",
11  "save_post",
12  "delete_post",
13  "sync_status",
14  "sync_ask",
15  "sync_media",
16  "sync_posts",
17  "sync_procedures",
18  "sync_dictionary",
19  "sync_pages",
20  "sync_publications",
21  "sync_llms",
22  "sync_cv",
23  "sync_cv_pdf",
24  "sync_roster",
25  "sync_phages",
26  "sync_registry",
27  "backup_media",
28  "backup_d1",
29  "upload_media",
30  "list_mentions",
31  "decide_mention",
32  "list_procedures",
33  "get_procedure",
34  "save_procedure",
35  "list_publications",
36  "get_publication",
37  "refresh_citations",
38  "check_publications",
39  "list_pages",
40  "get_page",
41  "get_llms",
42  "list_cv",
43  "get_cv",
44  "list_dictionary",
45  "get_dictionary",
46  "list_roster",
47  "get_roster",
48  "list_phages",
49  "get_phage",
50  "list_registry",
51  "get_registry",
52  "purge_zero_results",
53] as const;
54
55export type ToolName = (typeof TOOLS)[number];
56
57export function isToolName(value: unknown): value is ToolName {
58  return typeof value === "string" && (TOOLS as readonly string[]).includes(value);
59}
60
61export function toolNames(): readonly ToolName[] {
62  return TOOLS;
63}
64
65// Keyed by `ToolName`, so a missing or extra descriptor is a typecheck failure.
66export const TOOL_DESCRIPTORS: Readonly<
67  Record<ToolName, { args: Record<string, string>; returns: string; policy?: string }>
68> = {
69  list_posts: {
70    args: {},
71    returns:
72      "Every post row in D1, drafts included, with the head sha. `updated` " +
73      "is the revision date the row carries.",
74  },
75  get_post: {
76    args: { slug: "string" },
77    returns: "The complete markdown file, the head sha, and operatorMayPublish.",
78  },
79  save_post: {
80    args: {
81      slug: "string",
82      raw: "string, the complete markdown file including frontmatter",
83      expectedHeadSha: "string, optional, for editor-style conflict detection",
84      isNew: "boolean, optional, inferred from whether the file exists",
85    },
86    returns:
87      "commitSha, and the gate's own message with field and line on rejection. A file identical to the " +
88      "committed one commits nothing: unchanged is true and commitSha is the current head.",
89    policy:
90      "An operator may create, edit, unpublish and republish. It may NOT " +
91      "perform a post's first transition to draft:false; that is reserved " +
92      "to the human admin and is refused with 403 " +
93      "first-publish-requires-admin.",
94  },
95  delete_post: {
96    args: { slug: "string" },
97    returns: "commitSha.",
98    policy:
99      "Deleting a post is reserved to the human admin and is refused with " +
100      "403 delete-requires-admin. Unpublish instead (draft: true).",
101  },
102  sync_status: {
103    args: {},
104    returns: "Repository, D1 and search index counts, reported separately.",
105  },
106  sync_ask: {
107    args: {},
108    returns:
109      "Uploads the full corpus to the Ask index and prunes strays. Idempotent. " +
110      "expected, present, drift and a converged verdict, all read back after " +
111      "the writes rather than taken from the upload's own counters.",
112  },
113  sync_media: {
114    args: {},
115    returns:
116      "Rebuilds the media index from R2 and the asset manifest, through the " +
117      "same derivation the admin button runs. Idempotent. A read-back " +
118      "reconciliation: expected, present, missing and extra keys, and a " +
119      "converged verdict.",
120  },
121  sync_posts: {
122    args: {},
123    returns:
124      "Converges D1 to the repository's markdown: re-renders every post " +
125      "whose file's blob sha differs from its row (or has no row), removes " +
126      "rows whose file is gone, all through the same render door a save " +
127      "uses. Idempotent. A read-back reconciliation: expected, present, and " +
128      "a converged verdict.",
129  },
130  sync_procedures: {
131    args: {},
132    returns:
133      "Converges D1 to the repository's content/procedures files: re-compiles " +
134      "every procedure whose file's blob sha differs from its row (or has no " +
135      "row), removes rows whose file is gone, all through the same compile " +
136      "and write doors save_procedure uses. Refuses an empty file set, and " +
137      "answers 422 naming any file the validator refuses after converging the " +
138      "rest. Idempotent. A read-back reconciliation: expected, present, and a " +
139      "converged verdict.",
140  },
141  sync_dictionary: {
142    args: {},
143    returns:
144      "Converges D1 to the repository's content/dictionary files: re-compiles every entry whose file's blob sha " +
145      "differs from its row (or has no row), removes rows whose file is gone, through the same compile and write " +
146      "doors a dictionary save uses. Each write also re-derives the page the entry opens (its markdown twin and " +
147      "search records) and purges the pages tag, because that page embeds the entry. A file whose path is not a " +
148      "registered Software page, or whose clip is not in the repository, never makes a row. Refuses an empty file " +
149      "set, and answers 422 naming any file the validator refuses after converging the rest. Idempotent. A " +
150      "read-back reconciliation: expected, present, and a converged verdict.",
151  },
152  sync_pages: {
153    args: {},
154    returns:
155      "Converges D1 to the repository's content/pages files: re-compiles every " +
156      "page whose file's blob sha differs from its row (or has no row), removes " +
157      "rows whose file is gone with their search records, through the same " +
158      "compile and write doors a page save uses. A file whose path is not in " +
159      "CONTENT_PAGE_PATHS (or About's own, CONTENT_PAGES_OWN_ROUTE) never makes a row. Refuses an empty file set, and " +
160      "answers 422 naming any file the validator refuses after converging the " +
161      "rest. Idempotent. A read-back reconciliation: expected, present, and a " +
162      "converged verdict.",
163  },
164  sync_publications: {
165    args: {},
166    returns:
167      "Converges D1 to the repository's content/publications files: re-compiles " +
168      "every paper whose file's blob sha differs from its row (or has no row), " +
169      "removes rows whose file is gone with their search record and citation row, " +
170      "through the same compile and write doors a publication save uses. A " +
171      "citation count that exists is never touched; a missing one is seeded from " +
172      "the committed OpenAlex snapshot. Refuses an empty file set, and answers 422 " +
173      "naming any file the validator refuses after converging the rest. " +
174      "Idempotent. A read-back reconciliation: expected, present, and a converged " +
175      "verdict.",
176  },
177  sync_llms: {
178    args: {},
179    returns:
180      "Converges the settings row /llms.txt is served from to the repository's content/llms.txt, through " +
181      "the same validator and write door an llms.txt save uses, and purges /llms.txt. Refuses a repository " +
182      "with no llms.txt rather than deleting the row, and answers 422 naming the checks a file fails. " +
183      "Idempotent. A read-back reconciliation: expected, present, and a converged verdict.",
184  },
185  sync_cv: {
186    args: {},
187    returns:
188      "Converges D1 to the repository's content/cv files: re-compiles every CV file whose blob sha differs " +
189      "from its row (or has no row), removes rows whose file is gone, then rewrites the CV's search records, " +
190      "through the same compile and write doors a CV save uses. Refuses an empty file set, and answers 422 " +
191      "naming any file the validator refuses after converging the rest. Idempotent. A read-back reconciliation: " +
192      "expected, present, and a converged verdict.",
193  },
194  sync_cv_pdf: {
195    args: {},
196    returns:
197      "Makes the stored CV PDF (one object in the OG bucket, served at /dustin-edwards-cv.pdf) the one for the CV D1 " +
198      "holds now: renders it through Browser Run and replaces the object, then purges the cv tag, unless the stored " +
199      "object already carries that CV's fingerprint, in which case it renders nothing. A render that fails is an " +
200      "error and changes nothing stored. Run sync_cv first when cv-drift also fails. Idempotent. A read-back " +
201      "reconciliation: expected, present, and a converged verdict.",
202  },
203  sync_roster: {
204    args: {},
205    returns:
206      "Converges D1 to the repository's content/roster files: re-compiles every cohort whose file's blob sha " +
207      "differs from its row (or has no row), removes rows whose file is gone, through the same compile and write " +
208      "doors a roster save uses, then purges the pages that embed the roster. Refuses an empty file set, and " +
209      "answers 422 naming any file the validator refuses after converging the rest. Idempotent. A read-back " +
210      "reconciliation: expected, present, and a converged verdict.",
211  },
212  sync_phages: {
213    args: {},
214    returns:
215      "Converges D1 to the repository's content/phages files: re-compiles every phage whose file's blob sha " +
216      "differs from its row (or has no row), removes rows whose file is gone, through the same compile and write " +
217      "doors a phage save uses, first re-deriving the page /research/phages (its table, twin and search records) from " +
218      "the final set, then purges the pages tag. Refuses an empty file set, and answers 422 naming any file the " +
219      "validator refuses after converging the rest. Idempotent. A read-back reconciliation: expected, present, and a " +
220      "converged verdict.",
221  },
222  sync_registry: {
223    args: {},
224    returns:
225      "Converges D1 to the repository's content/registry/<kind>/<id>.md files: re-compiles every item whose file's " +
226      "blob sha differs from its row (or has no row), removes rows whose file is gone, through the same compile and " +
227      "write doors a registry save uses, then purges the registry tag. Refuses an empty file set while rows exist, " +
228      "rather than deleting every row; with no files and no rows there is nothing to do and it says so. Answers 422 " +
229      "naming any file the validator refuses after converging the rest. Idempotent. A read-back reconciliation: " +
230      "expected, present, and a converged verdict.",
231  },
232  list_mentions: {
233    args: { status: "string, optional: unverified, pending, approved, rejected or failed" },
234    returns:
235      "Received webmentions, newest first, with id, source, target slug, status, " +
236      "author, excerpt and the received, verified and decided timestamps. " +
237      "Unfiltered when no status is given, which is what the moderation queue " +
238      "shows.",
239  },
240  decide_mention: {
241    args: {
242      id: "number, the mention row id from list_mentions",
243      decision: "string: approve, reject or delete",
244    },
245    returns:
246      "changed, and the target slug when a row moved. Approving or rejecting " +
247      "PURGES that post's cached page, so the change reaches readers on the " +
248      "next fetch rather than within the ten minute shared-cache lifetime.",
249    policy:
250      "Approve and reject need write and are reversible. DELETE is refused " +
251      "with 403 mention-delete-requires-admin: it removes the only copy of " +
252      "what a stranger sent, and there is no repository behind this table. " +
253      "Reject instead.",
254  },
255  list_procedures: {
256    args: {},
257    returns:
258      "Every procedure row in D1 (protocols, recipes, computational procedures), drafts included: " +
259      "slug, path, profile, title, draft (boolean), version, updated, the count of recorded gaps and, for a " +
260      "protocol, biosafetyLevel (BSL-1, BSL-2 or MISSING until Dustin sets it), with the head sha and the " +
261      "number of procedures.",
262  },
263  get_procedure: {
264    args: { slug: "string" },
265    returns:
266      "The complete procedure file (raw), the head sha, the procedure as structured data (front matter, " +
267      "sections, steps with their marks and flags), its recorded gaps, and any validation errors. The " +
268      "format is docs/PROCEDURES.md.",
269  },
270  save_procedure: {
271    args: {
272      slug: "string",
273      raw: "string, the complete procedure file including front matter",
274      expectedHeadSha: "string, optional, the headSha get_procedure returned",
275      isNew: "boolean, optional, inferred from whether the file exists",
276    },
277    returns:
278      "commitSha, path, draft, gaps and unchanged (true when the file is identical to the committed one: " +
279      "nothing is committed or rewritten and commitSha is the current head). The file is validated against its profile by the same code CI " +
280      "runs, committed, and written to D1, so the page changes without a deploy. A file that fails is " +
281      "refused with 422 and detail.errors, every message the validator gave.",
282    policy:
283      "An operator may edit, unpublish and republish a procedure. It may NOT publish one for the first " +
284      "time (draft true to false, or a new procedure saved as published); that is refused with 403 " +
285      "first-publish-requires-admin.",
286  },
287  list_publications: {
288    args: {},
289    returns:
290      "Every publication row in D1, drafts included: slug, doi (null for a manuscript), stage (published or " +
291      "submitted), type, title, year and draft (boolean), with the head sha and the number of publications. " +
292      "A publication is written through Carrel (site-api), never through this surface, so there is no save tool.",
293  },
294  get_publication: {
295    args: { slug: "string, the page slug (the DOI with every run of punctuation a hyphen)" },
296    returns:
297      "The complete publication file (raw), the head sha, draft, the compiled record when the file is valid, " +
298      "and every validation error when it is not. The format is docs/PUBLICATIONS.md.",
299  },
300  refresh_citations: {
301    args: { dois: "array of strings, optional: the DOIs to refresh; every published paper's when omitted" },
302    returns:
303      "refreshed (how many counts were replaced) and failures (doi, stage, detail for each count that could " +
304      "not be read). A DOI that fails keeps the count it had. A partial failure is a 502 with the same " +
305      "detail, so the caller sees it. The watchdog calls this weekly.",
306  },
307  check_publications: {
308    args: {},
309    returns:
310      "Reads ORCID and Crossref and compares them with every publication row: notOnSite (DOIs the ORCID " +
311      "record or a Crossref deposit naming the ORCID lists that no file carries, with title, year and " +
312      "sources), nameMatches (Crossref works of the last 400 days under the owner's name and on no list, to " +
313      "confirm by hand), notOnOrcid (published papers missing from the ORCID record), manuscripts (files " +
314      "with no DOI yet) and failures. Writes nothing. A source that could not be read is a 502 whose detail " +
315      "is the same report from the sources that answered. The watchdog calls this daily.",
316  },
317  list_pages: {
318    args: {},
319    returns:
320      "Every Research, Teaching and Software prose page row in D1, drafts included: path, slug, title and " +
321      "draft, with the count and the head sha. Pages are edited through Carrel, not here.",
322  },
323  get_page: {
324    args: { path: "string, a registered page path such as /research/phages" },
325    returns:
326      "The complete page file (raw), the head sha, the page as structured data (front matter and body), " +
327      "and any validation errors the file has now. The format is docs/PAGES.md. Read only: a page is " +
328      "saved through Carrel.",
329  },
330  get_llms: {
331    args: {},
332    returns:
333      "The complete content/llms.txt (raw) and its size, the head sha, any validation errors the file has " +
334      "now, and whether the row /llms.txt is served from holds exactly this file. The format is " +
335      "docs/LLMS.md. Read only: it is saved through Carrel, as the document llms.",
336  },
337  list_cv: {
338    args: {},
339    returns:
340      "Every file of the CV in D1 (the profile, appointments, education, publications, grants, honors, talks, " +
341      "courses, mentoring, service, development): slug, type and when D1 last wrote it, with the count and the " +
342      "head sha. The CV is edited through Carrel, not here.",
343  },
344  get_cv: {
345    args: { slug: "string, a CV file such as grants or profile" },
346    returns:
347      "The complete CV file (raw), the head sha, the file as structured data and any validation errors the " +
348      "file has now. The format is docs/CV.md. Read only: a CV file is saved through Carrel.",
349  },
350  list_dictionary: {
351    args: {},
352    returns:
353      "Every dictionary entry row in D1, drafts included: key, path (the Software page it opens), term and draft, " +
354      "with the count and the head sha. Entries are edited through Carrel, not here.",
355  },
356  get_dictionary: {
357    args: { key: "string, the entry's file name without .md, such as capsid" },
358    returns:
359      "The complete entry file (raw), the head sha, draft, the entry as the page reads it when the file is valid, " +
360      "and every validation error when it is not. The format is docs/DICTIONARY.md. Read only: an entry is saved " +
361      "through Carrel.",
362  },
363  list_roster: {
364    args: {},
365    returns:
366      "Every Phage Discovery cohort row in D1, newest first: slug (the year), year, the photograph's path and the " +
367      "count of names, with the count of cohorts and the head sha. Only what the public roster page already shows. " +
368      "The roster is edited through Carrel, not here.",
369  },
370  get_roster: {
371    args: { slug: "string, a cohort's file key: its four-digit year, such as 2025" },
372    returns:
373      "The cohort the committed file holds (year, photograph and names, the fields the public page shows), the " +
374      "head sha, and any validation errors the file has now. The format is docs/ROSTER.md. Read only: a cohort " +
375      "is saved through Carrel.",
376  },
377  list_phages: {
378    args: {},
379    returns:
380      "Every phage row in D1, in the page's order (year, then name): slug, name, year, host, county, PhagesDB record, " +
381      "genome-paper slug, former name and note, with the count and the head sha. Only what the public phage table " +
382      "already shows. The table is edited through Carrel, not here.",
383  },
384  get_phage: {
385    args: { slug: "string, a phage's file key: its name in lower case, such as acorn15" },
386    returns:
387      "The phage the committed file holds (the fields the public table shows), its raw file, the head sha, and any " +
388      "validation errors the file has now. The format is docs/PHAGES.md. Read only: a phage is saved through Carrel.",
389  },
390  list_registry: {
391    args: { kind: "string, optional: one registry kind, such as primer" },
392    returns:
393      "Every registry row in D1, in the site's order (kind, then name): kind, id, name, status and the kind's own " +
394      "fields, with the count and the head sha. Drafts are included, marked by status. The registry is edited " +
395      "through Carrel, not here (docs/REGISTRY.md).",
396  },
397  get_registry: {
398    args: { slug: "string, an item's address <kind>/<id>, such as primer/m13-forward" },
399    returns:
400      "The item the committed file holds, its raw file, the head sha, the fields recorded as MISSING (what is " +
401      "waiting for Dustin), and any validation errors the file has now. The format is docs/REGISTRY.md. Read only: " +
402      "an item is saved through Carrel.",
403  },
404  purge_zero_results: {
405    args: {},
406    returns:
407      "purged, the number of zero-result query rows removed: every row whose last_seen is older than " +
408      "ZERO_RESULT_RETENTION_SECONDS. The watchdog calls this daily; there used to be an admin button for it.",
409    policy:
410      "Takes no argument that names a row, so there is nothing to target beyond the fixed retention " +
411      "cutoff: a caller cannot choose what is removed. The rows have no derivation to rebuild them from, " +
412      "which is why this is destructive rather than a sync, but there is no identity-based refusal to " +
413      "document because every caller gets the same unconditional sweep.",
414  },
415  backup_media: {
416    args: {},
417    returns:
418      "Copies every MEDIA object that has no byte-identical twin into " +
419      "MEDIA_BACKUP. COPIES ONLY: it has no delete branch in either bucket, " +
420      "and nothing is ever copied backup to media. Idempotent. A read-back " +
421      "reconciliation: objects, twins, missing and mismatched, counted after " +
422      "the writes rather than from the loop's own counters.",
423  },
424  backup_d1: {
425    args: {},
426    returns:
427      "Dumps every D1 table to the BACKUPS bucket under backups/json/<run id>/, checks the dump against " +
428      "the backup policy (the required non-derived tables are present, nothing credential-bearing is in it, " +
429      "it is not empty), writes the completion marker only if the check passes, then prunes runs outside " +
430      "the retention policy (14 daily, 8 weekly, 6 monthly). Returns run_id, exported_at, tables, rows, " +
431      "kept, pruned and locked (stale runs an R2 bucket lock kept). A failed check answers an error and leaves the run without its marker. The watchdog " +
432      "calls this nightly.",
433  },
434  upload_media: {
435    args: {
436      data: "string, optional, base64 bytes or a full data: URI. Either this or url.",
437      url: "string, optional, an https URL the API fetches server-side. Either this or data.",
438      type: "string, optional, the image MIME type. Defaults to the data: URI's " +
439        "own type or the fetched response's Content-Type.",
440      name: "string, optional, the filename to record as original_name. Defaults " +
441        "to the URL's last path segment, or upload.<ext>.",
442    },
443    returns:
444      "url and key, the same two the editor's upload returns, plus bytes, " +
445      "width, height and `recorded`. The url is what goes in the markdown. " +
446      "Idempotent: the key is a digest of the bytes, so the same image " +
447      "uploaded twice is one object.",
448    policy:
449      "MEDIA is the irreplaceable bucket and there is no delete tool over " +
450      "this token, so an object put here stays until an admin removes it. " +
451      "Accepts only the raster image types in ALLOWED (SVG is refused: it " +
452      "can carry script), refuses anything over " +
453      "MAX_BYTES, and fetches only https URLs.",
454  },
455};