src/tool-annotations.ts

Functions

Imports

It imports no other module of this repo. Imported by src/tools/surface.ts.

Source

1// One honest set of hints per served tool,
2// so a client can confirm before acting. A tool's hints hold for every action it takes:
3// a tool with one action that writes is not read-only. test/tool-annotations.test.ts
4// derives each flag and fails both directions:
5// - readOnlyHint is true iff every action needs only the read grant (TOOL_GRANTS and
6//   TOOL_ACTION_GRANTS in src/scope.ts): "read", or "admin_read" for an admin tool
7//   that only reads.
8// - destructiveHint is true iff some action can overwrite or remove existing state.
9// - openWorldHint is true iff some operation the tool runs calls into src/github* or
10//   the Cloudflare API, directly or through a named module.
11// - idempotentHint is true for every read-only tool, and for a write only when a
12//   repeat of any of its actions changes nothing further.
13// The protocol's defaults when a hint is omitted are idempotent false and open world
14// true, so both are stated for every tool rather than left to a client's reading.
15
16export interface ToolHints {
17  readOnlyHint: boolean;
18  destructiveHint: boolean;
19  idempotentHint: boolean;
20  openWorldHint: boolean;
21}
22
23// What a call reaches and whether repeating it changes anything. Optional so an
24// entry written with a bare constructor still compiles; the defaults are the
25// conservative ones (repeatable effects, open world), and the test refuses an entry
26// that leaves either unstated.
27interface Reach {
28  idempotent?: boolean;
29  openWorld?: boolean;
30}
31
32const reach = (r: Reach) => ({ idempotentHint: r.idempotent ?? false, openWorldHint: r.openWorld ?? true });
33
34const read = (r: Reach = {}): ToolHints => ({ readOnlyHint: true, destructiveHint: false, ...reach(r) });
35const additive = (r: Reach = {}): ToolHints => ({ readOnlyHint: false, destructiveHint: false, ...reach(r) });
36const destructive = (r: Reach = {}): ToolHints => ({ readOnlyHint: false, destructiveHint: true, ...reach(r) });
37
38export const TOOL_HINTS: Record<string, ToolHints> = {
39  // ---- Capsid (14)
40  capsid_start_session: read({ idempotent: true, openWorld: false }),
41  capsid_find_docs: read({ idempotent: true, openWorld: false }),
42  capsid_read_doc: read({ idempotent: true, openWorld: false }),
43  // write's replace and patch overwrite, restore overwrites the live body, and move
44  // removes the old path. append adds again and every overwrite snapshots a new
45  // version, so a repeat is not a no-op.
46  capsid_write_doc: destructive({ idempotent: false, openWorld: false }),
47  // A repeat finds nothing to delete and is refused.
48  capsid_delete_doc: destructive({ idempotent: true, openWorld: false }),
49  // gather reads the repo tree from GitHub; finalize archives by rewriting the path
50  // column; a second report the same day snapshots the first.
51  capsid_lint_namespace: destructive({ idempotent: false, openWorld: true }),
52  capsid_read_repo: read({ idempotent: true, openWorld: true }),
53  // The live site check fetches the site; the rest read GitHub.
54  capsid_inspect_repo: read({ idempotent: true, openWorld: true }),
55  // Every file write is a new commit, or a new pull request in pr mode.
56  capsid_change_repo: destructive({ idempotent: false, openWorld: true }),
57  // A comment posts a new comment on every call, and a repeat open after a close
58  // opens another pull request. Nothing existing is overwritten.
59  capsid_open_pr: additive({ idempotent: false, openWorld: true }),
60  // merge and close end a pull request, delete removes a branch, and a release
61  // publishes; a repeat release or tag is refused by GitHub, but a repeat close of a
62  // reopened pull request is not a no-op.
63  capsid_close_pr: destructive({ idempotent: false, openWorld: true }),
64  // Every call starts a new workflow run.
65  capsid_run_ci: additive({ idempotent: false, openWorld: true }),
66  // complete, fail and block overwrite result_summary and move a job out of claimed;
67  // post and record create a job each call; evidence is checked against GitHub.
68  capsid_work_jobs: destructive({ idempotent: false, openWorld: true }),
69  // Status only: Capsid's state from this Worker's own stores.
70  capsid_run_improve: read({ idempotent: true, openWorld: false }),
71
72  // ---- Capsid Admin (8)
73  // Reads the queue, the Portal's stored state and GitHub's open pull requests.
74  capsid_admin_whats_next: read({ idempotent: true, openWorld: true }),
75  // update replaces the mapping, delete removes the namespace and, with cascade, its
76  // documents; register creates one each call.
77  capsid_admin_manage_namespaces: destructive({ idempotent: false, openWorld: false }),
78  // revoke and update_scopes overwrite existing state; mint issues a new credential.
79  capsid_admin_manage_agents: destructive({ idempotent: false, openWorld: false }),
80  // Reads claims and their checks, never writes.
81  capsid_admin_read_claims: read({ idempotent: true, openWorld: false }),
82  // The watcher's pass from KV, and Cloudflare's API for Access, Email Routing and
83  // Workers Builds.
84  capsid_admin_read_ops: read({ idempotent: true, openWorld: true }),
85  // perform can revoke an agent, fail a job or remove a site, and a confirmed token is
86  // spent, so a repeat is refused rather than repeated. Closing a pull request calls
87  // GitHub, and a site repair calls the site's operator API.
88  capsid_admin_run_controls: destructive({ idempotent: false, openWorld: true }),
89  // sign_policy overwrites a policy document (snapshotted), breaker_reset and overnight
90  // overwrite their switches, and mint_operator_key issues a key each call. Only this
91  // Worker's own stores.
92  capsid_admin_control_improve: destructive({ idempotent: false, openWorld: false }),
93  // Replaces a site's key on the site Worker and on Carrel through the Cloudflare API.
94  capsid_admin_set_site_key: destructive({ idempotent: false, openWorld: true }),
95};
96
97// Object.hasOwn, not a bare index: "constructor" is not a missing tool.
98export function hintsFor(tool: string): ToolHints {
99  if (!Object.hasOwn(TOOL_HINTS, tool)) {
100    // Fail closed: a new tool is under-claimed until the table catches up.
101    return { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true };
102  }
103  return TOOL_HINTS[tool];
104}