a3f9fb2 · e360500 · 75df857 · 171a098 · d8980aa · 53dc155
@@ -161,6 +161,8 @@
src/
              scope floors, pagination, `securityFloor` — the headers every
              response leaves with), api (every /api/v1 route), server
              (auth resolution, git smart HTTP, web routes, hook socket), sse
              mcp (the MCP protocol and dispatch; one file per tool under
              mcp/tools/, gathered by a generated index)
  design/     shared design tokens: themes (palettes both surfaces render)
  origins/    other forges as one Provider interface: discover (version-endpoint
              probe), providers/{github,forgejo} (+ http: paging, ETags, rate
@@ -254,6 +256,9 @@
flag exists only in the stdio dev runner and is never reachable over SSH.
  Describe it in OpenAPI as one file, `contract/openapi/routes/<operationId>.ts`,
  exporting `route`; then `bun scripts/openapi-routes.ts` writes its line in the
  generated index. Never list it by hand.
- **Add an MCP tool:** one file, `http/mcp/tools/<name>.ts`, exporting `tool`;
  then `bun scripts/mcp-tools.ts` writes its line in the index and its row in
  docs/MCP.md (docs/MCP.md, "Adding a tool"). Never list it by hand.
- **Add a TUI screen:** one file under `tui/screens/`, exporting
  `(f: Session, ctx: Ctx, …) => Screen`. Compose `ui/widgets`; take navigation
  from `screens/common.ts` (`ListState`, `Scroll`, `Filter`, `drawList`,
@@ -25,107 +25,122 @@
for a tunnel and a forge that sleeps.
## Tools
| tool           | does                                                                                              | writes |
| -------------- | ------------------------------------------------------------------------------------------------- | ------ |
| `apps`         | the apps you can see: live or not, where served, how each runs itself, what is working            |        |
| `app_deploy`   | `{ repo, env, action }`: `redeploy` or `stop` an app's `production` or a pull's `pull-N` preview; a writer's, queued as `POST …/app/:env/redeploy` and `…/stop` are; answers `{ queued, run }` or `{ stopped }` | yes    |
| `new_app`      | `{ name, description?, owner?, visibility?, agent?, pick? }`: make an app from a sentence; answers `{ repo, url, issue, agent, run }` (`run` is the first run's state, or `none`) and draws the `ui://forge/app` card: name, production URL, first issue, agent, first run; refused as `POST /api/v1/apps` is (unverified, app_limit, no_such_agent, name_taken) | yes    |
| `repo`         | `{ repo }`: one repository's description, visibility, autonomy, `audience { level, sentence }` and `provenance` (where a migrated one came from, `null` when hidden), the same as `GET /api/v1/repos/:owner/:name` |        |
| `repo_settings` | `{ repo, description?, visibility? }` (admin token): change a repository's description and visibility as `PATCH /api/v1/repos/:owner/:name` does, for the same callers (a repository admin); answers `{ repo, description, visibility }`; a visibility other than public or private is `invalid` | yes    |
| `tell`         | a sentence becomes an issue, a builder is picked, a run starts on the crew's next tick            | yes    |
| `thought` | `{ id }`: where one of your thoughts went (its id comes from `tell` without a repo): the placement, and the earlier thoughts it repeats or takes back and the later ones that did the same; not yours and not there answer alike, `not_found` |  |
| `say`          | speak on an issue or a pull; a working builder hears it as its next step                          | yes    |
| `issue`        | `{ repo, number }`: one issue's title, state, closeReason, body, labels, assignee, comments (author, authorIsAgent, body, at) and blockedBy/blocks, as `GET …/issues/:number`; a sealed one you cannot see is not found |        |
| `pull`         | `{ repo, number }`: a pull's title, state, head and base, and for an open pull whether it merges into the base's current head (`mergeable`) and the paths that stop it (`conflicts`), and `check: { state, baseOid }`: the latest check's state and the base tip it was merged with (empty when it merged nothing); `mergeable` and `conflicts` are the same fields as `GET …/pulls/:number`, `check` is `state` and `run.baseOid` from `GET …/pulls/:number/checks`; draws the `ui://forge/pull` card: `#N title`, state with check and conflicts while open, `head → base` linked to the pull, and the preview link when the pull has an environment |        |
| `preview`      | `{ url }`: what the forge pill says of an app host's URL (production or a pull's preview): `{ app, environment, pull: { number, title } \| null, check: "green" \| "red" \| "running" \| null, firstFailure, logUrl, working: [names] }`; `firstFailure` is the check's first failing test or its summary, `logUrl` is set only for someone who may read the log (a writer), `working` names the agents with a run going; a URL that is not one of this forge's app hosts is `invalid`, an app you cannot read is `not_found` and a pull you cannot see is `no_such_pull`, as `repo` and `pull` say |        |
| `edit`         | a new title or body for an issue or a pull: its author's, or a writer's; an agent edits only what it wrote | yes    |
| `close`        | `{ repo, number, state?, reason?, into? }`: close an issue or a pull (`state` closed by default) or reopen it (`open`); the same rules and refusals as `PATCH …/issues/:number`: an agent closes only what the rules give it and reopens nothing; answers `state` and `closeReason` | yes    |
| `pulls`        | `{ repo, state?, limit? }`: a repository's pulls, newest first, one brief line each: `number`, `title`, `author`, `head`, `check` (state), `approvals`, `changesRequested`, `mergeable` (null once closed); `state` open (default) or closed, `limit` 1-50 (default 20); no bodies, no diffs | no     |
| `read_file`    | a file (utf-8, or base64 for binary) or a directory listing at a ref, as GET …/contents | no     |
| `seal`         | `{ repo, number, sealed }`: seal a security report (and the pull that fixes it) so only writers and the crew see it, or unseal it for every reader; a writer's, recorded | yes    |
| `secrets`      | `{ scope, ref?, action, name?, value? }` (forge admin): `list` the names and timestamps of the forge's sealed secrets, `set` or `remove` one; `scope` is forge, org or repo, `ref` the org or `owner/name`; a value is never read back | yes    |
| `mirror_set`   | `{ action, endpoint?, bucket?, region?, accessKey?, secretKey? }` (forge admin, admin-scope token): `set` seals the off-box snapshot mirror, `forget` clears it; the Backups page's rules and refusals, a blank field keeps what was sealed; answers `{ place, says }`, never a key | yes    |
| `org_teams`    | `{ org, action, team, user?, permission? }` (admin-scope token, an org owner): `create` a team (`permission` read, write or admin; read by default), `add_member` a `user`, or `remove` the team; the same as POST/DELETE `/api/v1/orgs/:org/teams` | yes    |
| `now`          | what the crew is doing right now: who, on what, since when, at what cost; a planner that declined the direction and waits for you comes first (`run: null`, its words in `says`) |        |
| `next_steps` | on a spawned forge, your first three steps and whether each is done; empty elsewhere or for anyone but its owner |  |
| `returns` | `{ repo?, days? }`: what the crew's tokens bought over the last `days` (1–90, default 7): dollars, runs, changes landed, cost per change; `repo` narrows it to one app of yours |  |
| `stop`         | stop one run by its id from `now`                                                                 | yes    |
| `health`       | how this forge is: the version and commit it runs, draining or not, the rollout and its incidents |        |
| `system`       | the machine the forge runs on, now: CPU, load, memory, disk, network, processes; a forge admin, or an agent granted `telemetry:read` |        |
| `telemetry_grant` | `{ agent, on }`: grant an agent `telemetry:read`, or take it back with `false`, as the Telemetry page does; a person admin's, with an admin token; answers `says` | yes    |
| `cloud_accounts` | the forge's cloud accounts, each attached provider token with its use, verification, write permission and today's calls; a forge admin only (counted as a write so a `ro` token never lists them) | yes    |
| `cloud_account` | `{ verb, provider, name, value?, to?, allowed?, repo? }`: change a cloud account: `attach` or `rotate` a token (`value`), `verify` it, `rename` it (`to`), `remove` it, `allow_writes` (`allowed` true or false) or `audit` (`repo` owner/name); a forge admin with an admin-scope token; answers a one-line `says` | yes    |
| `audit`        | who can do what, per app, read from its contract.json in git: yes, own or no per door, and whether outsiders may direct its crew (`crewOutsiders`) |        |
| `account_verify` | `{ username }`: mark a person's email verified, as `POST …/admin/accounts/:username/verify` does; a person admin's, with an admin token | yes    |
| `outsiders`    | `{ repo, on?, dryRun? }`: whether people who cannot write may direct the crew; with `on`, planned first (`dryRun` is true unless `false`); set only by the app's admin with an admin token, never an agent | yes    |
| `origins`      | `{ action, id? }`: `list` your connected origins, `repos` the repositories one holds (`id`; `mirroredAs` says which are already here), or `sync` one now; the same as `GET /api/v1/user/origins`, `…/:id/repos` and `POST …/:id/sync`, for you only, an admin token as there; never a credential in an answer | yes    |
| `decisions_by` | `{ repo, by?, dryRun? }`: the standing rule for a repository's hand-overs (`me`, `decider`, `decider_tell`); with `by`, planned first (`dryRun` is true unless `false`); set only by the app's admin with an admin token, never an agent | yes    |
| `archive`      | `{ repo | repos, archived?, dryRun? }`: archive (true) or wake (false) a repository, by name; planned first (`dryRun` is true unless `false`); only the repository's admin with an admin token, never an agent. `repos` (at most 50) runs the fleet `archive` operation over them, answers each one's outcome and the `operation` id; `limb` with `action: "undo"`, that `operation` and any one of the repositories as `app` reverts it for a day | yes    |
| `events`       | `{ repo, limit?, cursor? }`: the repository's events, newest first, as you may see them (a webhook's URL and an app's variable names are the admins'): `{ items, next_cursor }`, `limit` 1 to 200 (default 50), `cursor` from `next_cursor` | no     |
| `reports`      | `{ repo, id?, action? }`: the waiting reports from outsiders, each `from: "outside"` (their words are unchecked); with `id` and `action` (`accept` opens it as an issue marked as from outside, `dismiss` closes it). A person who writes the repository only; needs an `rw` token | yes    |
| `trail`        | `{ repo, shown?, dryRun? }`: where a migrated repository came from (`provenance`: source, sourceUrl, parents, migratedAt) and whether it is shown; with `shown`, shows or hides the trail — planned first (`dryRun` is true unless `false`), only the repository's admin with an admin token, never an agent. Hiding keeps the record; a hidden one reads `null` to anyone but an admin | yes    |
| `branches`     | `{ repo, name?, action?, from?, kind? }`: without `name`, lists the branches; `kind: "tags"` lists the tags instead (as GET `/api/v1/repos/:owner/:name/tags` does, newest first; no `name` or `action`); with `name` and `action` (`create` from `from`, or `delete`) it does what the branches page does: the default branch is never deleted, only a writer may act | yes    |
| `migrate`      | `{ url, name?, crew? }` brings a public repository in by URL (history only; nothing reaches back) and answers `{ job, state, url }`; `{ job }` alone reads that job. Same validation, scope (`rw`) and private-address refusal as `POST /api/v1/migrate` | yes    |
| `commits`      | `{ repo, ref?, limit?, oid? }`: a branch's recent commits, newest first (`limit` 1–100, default 30; refused outside that, where REST clamps), as `GET …/commits` answers; with `oid` (4–64 hex) one commit with its diff and its check, as `GET …/commits/{oid}` and `…/check` answer |        |
| `probe`        | knock on a running app's doors as nobody, a user and an admin; the ones that disobey its contract |        |
| `following`    | where a fork stands against what it follows, and what the crew is doing about it                  |        |
| `family`       | the forge that sent this one and, for a site admin, those it sent, with state and version         |        |
| `forges`       | an admin's list of the forges sent from here: name, address, whom for, apps, claimed or not, last activity |        |
| `follow_mode`  | `{ repo, … }`: choose how a spawned forge follows its parent, `tell-me` or `take-updates`; its `forge` repository's admin only | yes    |
| `sever`        | `{ repo }`: cut a spawned forge's link to the forge its code came from; its `forge` repository's owner only; deletes nothing | yes    |
| `propose_to_parent_forge` | `{ repo }`: offer this forge's landed change to its parent as a pull on `child/<name>/…`; the same tip answers with that pull | yes    |
| `forge_proposals` | `{ repo }`: what this forge proposed to its parent, newest first; `reachable` is false if the parent did not answer |        |
| `contribute`   | for any arriving agent: what this forge is, its bottleneck, open “help wanted” issues, how to propose |        |
| `spawn`        | `{ name, apps?, crew?, dryRun? }`: a child forge, planned first (`dryRun` is true unless `false`); an admin's, and an `ro` token may plan but not make | yes    |
| `agent`        | `{ action, username, … }`: `create` a crew agent, `update` its `model`, `brief` or `budgetUsd`, or `remove` it; an admin's, with an `admin` token, as `/api/v1/agents` | yes    |
| `claim_link`   | `{ name }`: a new claim link for a child you spawned that nobody has claimed; the old one stops working. An admin's | yes    |
| `upstream`     | `{ repo, enabled?, url?, branch?, check? }`: the repository a fork follows (an admin reads it); with `enabled` sets it, with `check: true` checks it now; setting and checking need an admin token | yes    |
| `take_updates` | a fork takes its parent's updates when git can do it alone; a conflict is refused. On a spawned forge's code repository it opens the one `forge/take-updates` pull and never moves the default branch | yes    |
| `converge`     | the fork's crew merges where both sides changed the same files; comes back as a pull              | yes    |
| `asked`        | `{ repo?, show?, order? }`: what people asked the crew for, by default nothing merged yet and oldest first: who and when, the pulls that close it, the crew's last activity, waiting/building/shipped/closed, stale when not shipped in three days and flagged when stale with nothing built; repositories you can write |        |
| `assigned`     | `{ limit? }`: the open issues and pulls assigned to you in every repository you can still read (repository, number, title, kind, state), as `GET /api/v1/user/assigned` |        |
| `app_members`  | `{ repo, members?, dryRun? }`: the people a private app names, who may enter it and its previews and nothing else; a writer (never an agent) changes the list with an admin-scope token | yes    |
| `egress_grants` | `{ repo, op?, destination? }`: the private `host:port` destinations an app's forge.json asks for and which are granted; `op` grant or revoke by a site admin (never an agent), and every op needs an admin-scope token; the same as the settings page and `/api/v1/repos/:owner/:name/egress-grants` | yes    |
| `explore`      | `{ query? }`: the apps and people you can see, ranked by forks, ships, use and freshness, with their numbers; `kind:` `sort:` and words in one line |        |
| `search`       | `{ q, kind?, repo? }`: issues, pulls, repositories and code you can read, the same results as /search; `repo` keeps to one | |
| `feed`         | `{ limit?, cursor? }`: your home timeline — tells, replies, runs, changes and looks — ranked, with who, what, why and a link; the same items as `GET /api/v1/feed` |        |
<!-- tools:begin: generated by `bun scripts/mcp-tools.ts` from each tool's `doc` -->
| tool | does | writes |
| ---- | ---- | ------ |
| `access` | `{ since?, ua?, path? }`: what outside agents tried: the redacted log of non-browser requests to public paths, newest first; `since` an ISO time (default a day, at most 14 days), `ua` part of the user agent, `path` a prefix; a forge admin's | yes |
| `account_role` | `{ username, role, usdPerMonth?, dryRun? }`: make a person a `member`, or a `guest` again, with an optional starter allowance (`usdPerMonth`, 0.01 to 10000, promoting only); planned first (`dryRun` is true unless `false`) | yes |
| `account_suspend` | `{ username, suspended }`: suspend a person's account, or unsuspend it with `false`; their sessions and tokens stop at once; the API's rules (not yourself, another admin or an agent; not the only owner of an organization); an admin token | yes |
| `account_verify` | `{ username }`: mark a person's email verified, as `POST …/admin/accounts/:username/verify` does; a person admin's, with an admin token | yes |
| `agent` | `{ action, username, … }`: `create` a crew agent, `update` its `model`, `brief` or `budgetUsd`, or `remove` it; an admin's, with an `admin` token, as `/api/v1/agents` | yes |
| `app_deploy` | `{ repo, env, action }`: `redeploy` or `stop` an app's `production` or a pull's `pull-N` preview; a writer's, queued as `POST …/app/:env/redeploy` and `…/stop` are; answers `{ queued, run }` or `{ stopped }` | yes |
| `app_env` | `{ repo, action, name?, value?, scope? }`: `list` an app's variable names and scopes, `set` one, or `unset` it, in `all` (default), `production` or `preview`; the API's rules and errors, an admin of the repository with an admin-scope token; a value is never read back | yes |
| `app_members` | `{ repo, members?, dryRun? }`: the people a private app names, who may enter it and its previews and nothing else; a writer (never an agent) changes the list with an admin-scope token | yes |
| `apps` | the apps you can see: live or not, where served, how each runs itself, what is working |  |
| `archive` | `{ repo | repos, archived?, dryRun? }`: archive (true) or wake (false) a repository, by name; planned first (`dryRun` is true unless `false`); only the repository's admin with an admin token, never an agent. `repos` (at most 50) runs the fleet `archive` operation over them, answers each one's outcome and the `operation` id; `limb` with `action: "undo"`, that `operation` and any one of the repositories as `app` reverts it for a day | yes |
| `asked` | `{ repo?, show?, order? }`: what people asked the crew for, by default nothing merged yet and oldest first: who and when, the pulls that close it, the crew's last activity, waiting/building/shipped/closed, stale when not shipped in three days and flagged when stale with nothing built; repositories you can write |  |
| `assigned` | `{ limit? }`: the open issues and pulls assigned to you in every repository you can still read (repository, number, title, kind, state), as `GET /api/v1/user/assigned` |  |
| `audit` | who can do what, per app, read from its contract.json in git: yes, own or no per door, and whether outsiders may direct its crew (`crewOutsiders`) |  |
| `board_delete` | `{ slug }` (person admins): delete a board by slug; its history keeps it | yes |
| `board_pins` | `{ op?, slug?, title?, by? }` (person admins): without `op`, the panels pinned to your home (`slug`, `title`); `pin` or `unpin` a panel by board `slug` and panel `title`, or `move` it up or down with `by` (-1 or 1) | yes |
| `board_write` | `{ slug, board }` (person admins): write a whole board under a slug, made or replaced: `{ title, range, refresh, panels: [{ title, chart, query, w, h }] }` | yes |
| `boards` | `{ slug?, panel?, from?, to?, step? }` (person admins): without `slug`, lists the forge's boards (slug, title, range, refresh, panels); with `slug`, that board; with `panel` (place from 0, up to 23), that panel's data over the `from`/`to` window and `step` |  |
| `branches` | `{ repo, name?, action?, from?, kind? }`: without `name`, lists the branches; `kind: "tags"` lists the tags instead (as GET `/api/v1/repos/:owner/:name/tags` does, newest first; no `name` or `action`); with `name` and `action` (`create` from `from`, or `delete`) it does what the branches page does: the default branch is never deleted, only a writer may act | yes |
| `claim_link` | `{ name }`: a new claim link for a child you spawned that nobody has claimed; the old one stops working. An admin's | yes |
| `close` | `{ repo, number, state?, reason?, into? }`: close an issue or a pull (`state` closed by default) or reopen it (`open`); the same rules and refusals as `PATCH …/issues/:number`: an agent closes only what the rules give it and reopens nothing; answers `state` and `closeReason` | yes |
| `cloud_account` | `{ verb, provider, name, value?, to?, allowed?, repo? }`: change a cloud account: `attach` or `rotate` a token (`value`), `verify` it, `rename` it (`to`), `remove` it, `allow_writes` (`allowed` true or false) or `audit` (`repo` owner/name); a forge admin with an admin-scope token; answers a one-line `says` | yes |
| `cloud_accounts` | the forge's cloud accounts, each attached provider token with its use, verification, write permission and today's calls; a forge admin only (counted as a write so a `ro` token never lists them) | yes |
| `commits` | `{ repo, ref?, limit?, oid? }`: a branch's recent commits, newest first (`limit` 1–100, default 30; refused outside that, where REST clamps), as `GET …/commits` answers; with `oid` (4–64 hex) one commit with its diff and its check, as `GET …/commits/{oid}` and `…/check` answer |  |
| `confirm_wait` | `{ app, issue, blocker }`: a person says `issue` may go ahead although `blocker` closed as dropped or split; the API's confirm action, so writers only and never the crew | yes |
| `contribute` | for any arriving agent: what this forge is, its bottleneck, open “help wanted” issues, how to propose |  |
| `converge` | the fork's crew merges where both sides changed the same files; comes back as a pull | yes |
| `decisions_by` | `{ repo, by?, dryRun? }`: the standing rule for a repository's hand-overs (`me`, `decider`, `decider_tell`); with `by`, planned first (`dryRun` is true unless `false`); set only by the app's admin with an admin token, never an agent | yes |
| `edit` | a new title or body for an issue or a pull: its author's, or a writer's; an agent edits only what it wrote | yes |
| `egress_grants` | `{ repo, op?, destination? }`: the private `host:port` destinations an app's forge.json asks for and which are granted; `op` grant or revoke by a site admin (never an agent), and every op needs an admin-scope token; the same as the settings page and `/api/v1/repos/:owner/:name/egress-grants` | yes |
| `email_verify` | no input: send the caller a new verification email, with the API's rate limit and errors; the answer never carries the link | yes |
| `events` | `{ repo, limit?, cursor? }`: the repository's events, newest first, as you may see them (a webhook's URL and an app's variable names are the admins'): `{ items, next_cursor }`, `limit` 1 to 200 (default 50), `cursor` from `next_cursor` |  |
| `explore` | `{ query? }`: the apps and people you can see, ranked by forks, ships, use and freshness, with their numbers; `kind:` `sort:` and words in one line |  |
| `family` | the forge that sent this one and, for a site admin, those it sent, with state and version |  |
| `feed` | `{ limit?, cursor? }`: your home timeline — tells, replies, runs, changes and looks — ranked, with who, what, why and a link; the same items as `GET /api/v1/feed` |  |
| `feed_chips` | `{ kind?, value?, hidden? }`: the feed chips you switched off, which `feed` and `asks` leave out; with `kind` (`kind` or `person`), `value` and `hidden` it switches one off or on | yes |
| `make_it_yours` | `{ repo, name?, visibility?, dryRun? }`: a fork of an app you can see, as your own app, following the original; code and history copied, data and secrets not; private unless `visibility` is public (a public original only); at most 5 copies an account a day; plans unless `dryRun` is false | yes    |
| `origin_apps`  | `{ action, id?, host?, kind?, clientId?, clientSecret? }`: `list` your OAuth apps for connecting origins, `add` one (a `host`, or `kind` github), or `remove` one by `id`; the API's rules and errors, an admin-scope token; a secret is never read back, only `hasSecret` | yes    |
| `front_page`   | `{ pinned?, hidden?, weights?, dryRun? }`: the front page as a stranger sees it, ranked, with numbers; a site admin sets what is pinned (first public one featured), hidden, and what counts (weights of forks, ships, use, fresh, 0 to 10) | yes    |
| `invites`      | `{ action, id? }`: `list` the outstanding invites (state and expiry, never a link) or `revoke` one by `id`; a person admin with an admin token, stricter than the API's list, which an `ro` token may read | yes    |
| `map`          | an app's plan: ready now, waiting on what, the critical path, where the crew is, parked twice and why (`app`); draws the `ui://forge/map` card |        |
| `milestones`   | `{ app, issue? }`: how far each thing asked for is (and, with `issue`, whether you watch it: `watching`), from the dependency tree: the plan's limbs with their weights, or one milestone opened (who is building, what is blocked and on what, what merged in 7 days, an estimate, and for an owner `spend`: dollars, changes landed ever, the costliest three issues) |        |
| `limb`         | `{ app, issue, action, reason?, pillar?, operation?, dryRun? }`: defer, resume or close a whole limb as not doing, or undo an operation; plans unless `dryRun` is false, and applying takes an admin token | yes    |
| `watch`        | `{ app, issue, watch? }`: watch a milestone, or stop with `watch: false`: one item in your feed that follows it, and one push to your phone when it lands | yes    |
| `runs`         | `{ repo, limit? }`: the repository's recent runs, newest first (id, kind, state, issue or pull number, started, ended), 1–50, default 20; read as the runs page reads them |        |
| `run_log`      | `{ repo, run, tail? }`: a run's log, or its last `tail` lines (1–2000), with the REST route's access: a hidden log or unreadable repository is not found |        |
| `review`       | `{ repo, number, verdict, reason? }`: approve a pull (`approve`) or request changes (`changes`, with a `reason`), as the page does; a writer's or the crew's, and never your own pull | yes    |
| `threads`      | `{ repo, number, anchor?, resolved? }`: a pull's review threads with their comments; with `anchor` (from the list) resolve it (`resolved` true, the default) or reopen it (false), by the API's rules: a writer or someone who commented in the thread | yes    |
| `usage`        | `{ repo, days? }`: what the crew's runs spent — tokens, cost, wall time — by subscription, agent, issue, and each account's 5-hour and weekly standing; a writer's |        |
| `ssh_keys`     | `{ action?, title?, key?, id? }`: list your own SSH keys (default), add one (`key` is an authorized_keys line, `title` optional) or remove one by `id`; the API's rules and errors, add and remove need an `rw` token | yes    |
| `boards`       | `{ slug?, panel?, from?, to?, step? }` (person admins): without `slug`, lists the forge's boards (slug, title, range, refresh, panels); with `slug`, that board; with `panel` (place from 0, up to 23), that panel's data over the `from`/`to` window and `step` |        |
| `board_write`  | `{ slug, board }` (person admins): write a whole board under a slug, made or replaced: `{ title, range, refresh, panels: [{ title, chart, query, w, h }] }` | yes    |
| `board_delete` | `{ slug }` (person admins): delete a board by slug; its history keeps it                          | yes    |
| `board_pins`   | `{ op?, slug?, title?, by? }` (person admins): without `op`, the panels pinned to your home (`slug`, `title`); `pin` or `unpin` a panel by board `slug` and panel `title`, or `move` it up or down with `by` (-1 or 1) | yes    |
| `labels`       | `{ repo, number, labels }`: set an issue's or a pull's labels to exactly these (`[]` clears); only labels the repository has, by a writer | yes    |
| `repo_labels`  | `{ repo, action?, name?, color?, id? }`: list (`list`, the default; a read-only token may), create (`create`, `name`, `color` six hex digits) or remove (`remove`, `id`) the repository's labels, as `GET`/`POST …/labels` and `DELETE …/labels/:id`; create and remove need an admin token and a repository admin | yes    |
| `hooks`        | `{ repo, action, url, secret, kinds, id }`: `list`, `add` (`secret`, 16–200 characters, is required) or `remove` the repository's webhooks, as `…/hooks`; an admin-scope token on a repository you administer, and a secret is never shown | yes    |
| `subscription_budget` | `{ id, usd }`: set an account's whole-life budget in dollars (up to the `subscription.budget_max_usd` limit), or clear it with `usd: null`, as the Subscriptions page does; a locked budget can only be lowered; a forge admin with an admin token | yes    |
| `wait_for`     | `{ app, issue, blockedBy, stop? }`: the issue waits for another, or stops with `stop: true`; the page's rules, and the answer carries the issue's URL | yes    |
| `confirm_wait`  | `{ app, issue, blocker }`: a person says `issue` may go ahead although `blocker` closed as dropped or split; the API's confirm action, so writers only and never the crew | yes    |
| `hold`         | `{ app, pull, why?, release?, dryRun? }`: hold a pull so no rule reviews or lands it, or let it go; a person who can write, never an agent; plans unless `dryRun: false` | yes    |
| `app_env`      | `{ repo, action, name?, value?, scope? }`: `list` an app's variable names and scopes, `set` one, or `unset` it, in `all` (default), `production` or `preview`; the API's rules and errors, an admin of the repository with an admin-scope token; a value is never read back | yes    |
| `email_verify` | no input: send the caller a new verification email, with the API's rate limit and errors; the answer never carries the link | yes    |
| `plan`         | `{ app, issues }`: open up to 12 linked issues, all or none (see below)                           | yes    |
| `prompts`      | `{ repo, action, kind?, token?, at?, id? }`: list, add, run or remove an app's prompt sources (Instagram), as the `…/prompts` API does; the token goes in once and is never shown; listed only for an admin-scope token, and only the repository's admin may use it | yes    |
| `account_suspend` | `{ username, suspended }`: suspend a person's account, or unsuspend it with `false`; their sessions and tokens stop at once; the API's rules (not yourself, another admin or an agent; not the only owner of an organization); an admin token | yes    |
| `parent_unlink` | no input: stop signing in through the parent forge, as Settings does; refused when it is the account's last way in, and "Nothing to unlink." when nothing is linked; an admin token | yes    |
| `account_role` | `{ username, role, usdPerMonth?, dryRun? }`: make a person a `member`, or a `guest` again, with an optional starter allowance (`usdPerMonth`, 0.01 to 10000, promoting only); planned first (`dryRun` is true unless `false`) | yes    |
| `mint_invite`  | `{ days? }`: mint a single-use invite link that expires in `days` (1–30, default 7) and is shown once; a person admin's, with an admin token | yes    |
| `signup`       | `{ mode?, dryRun? }`: who may sign up: `open` (default), `invite` (only a person with an open invite link) or `closed` (no new accounts); without `mode` it reads the setting, with `mode` it plans first (`dryRun` is true unless `false`), and applying needs an admin token | yes    |
| `access`       | `{ since?, ua?, path? }`: what outside agents tried: the redacted log of non-browser requests to public paths, newest first; `since` an ISO time (default a day, at most 14 days), `ua` part of the user agent, `path` a prefix; a forge admin's | yes    |
| `whoami_can`   | `{ kind? }`: your role and that role's row of the roles table, each ability yes or no; `kind: "passkeys"` lists your own passkeys (`{ items }`: id, name, created, lastUsed), people only |        |
| `follow_mode` | `{ repo, … }`: choose how a spawned forge follows its parent, `tell-me` or `take-updates`; its `forge` repository's admin only | yes |
| `following` | where a fork stands against what it follows, and what the crew is doing about it |  |
| `forge_proposals` | `{ repo }`: what this forge proposed to its parent, newest first; `reachable` is false if the parent did not answer |  |
| `forges` | an admin's list of the forges sent from here: name, address, whom for, apps, claimed or not, last activity |  |
| `front_page` | `{ pinned?, hidden?, weights?, dryRun? }`: the front page as a stranger sees it, ranked, with numbers; a site admin sets what is pinned (first public one featured), hidden, and what counts (weights of forks, ships, use, fresh, 0 to 10) | yes |
| `health` | how this forge is: the version and commit it runs, draining or not, the rollout and its incidents |  |
| `hold` | `{ app, pull, why?, release?, dryRun? }`: hold a pull so no rule reviews or lands it, or let it go; a person who can write, never an agent; plans unless `dryRun: false` | yes |
| `hooks` | `{ repo, action, url, secret, kinds, id }`: `list`, `add` (`secret`, 16–200 characters, is required) or `remove` the repository's webhooks, as `…/hooks`; an admin-scope token on a repository you administer, and a secret is never shown | yes |
| `invites` | `{ action, id? }`: `list` the outstanding invites (state and expiry, never a link) or `revoke` one by `id`; a person admin with an admin token, stricter than the API's list, which an `ro` token may read | yes |
| `issue` | `{ repo, number }`: one issue's title, state, closeReason, body, labels, assignee, comments (author, authorIsAgent, body, at) and blockedBy/blocks, as `GET …/issues/:number`; a sealed one you cannot see is not found |  |
| `labels` | `{ repo, number, labels }`: set an issue's or a pull's labels to exactly these (`[]` clears); only labels the repository has, by a writer | yes |
| `limb` | `{ app, issue, action, reason?, pillar?, operation?, dryRun? }`: defer, resume or close a whole limb as not doing, or undo an operation; plans unless `dryRun` is false, and applying takes an admin token | yes |
| `make_it_yours` | `{ repo, name?, visibility?, dryRun? }`: a fork of an app you can see, as your own app, following the original; code and history copied, data and secrets not; private unless `visibility` is public (a public original only); at most 5 copies an account a day; plans unless `dryRun` is false | yes |
| `map` | an app's plan: ready now, waiting on what, the critical path, where the crew is, parked twice and why (`app`); draws the `ui://forge/map` card |  |
| `migrate` | `{ url, name?, crew? }` brings a public repository in by URL (history only; nothing reaches back) and answers `{ job, state, url }`; `{ job }` alone reads that job. Same validation, scope (`rw`) and private-address refusal as `POST /api/v1/migrate` | yes |
| `milestones` | `{ app, issue? }`: how far each thing asked for is (and, with `issue`, whether you watch it: `watching`), from the dependency tree: the plan's limbs with their weights, or one milestone opened (who is building, what is blocked and on what, what merged in 7 days, an estimate, and for an owner `spend`: dollars, changes landed ever, the costliest three issues) |  |
| `mint_invite` | `{ days? }`: mint a single-use invite link that expires in `days` (1–30, default 7) and is shown once; a person admin's, with an admin token | yes |
| `mirror_set` | `{ action, endpoint?, bucket?, region?, accessKey?, secretKey? }` (forge admin, admin-scope token): `set` seals the off-box snapshot mirror, `forget` clears it; the Backups page's rules and refusals, a blank field keeps what was sealed; answers `{ place, says }`, never a key | yes |
| `new_app` | `{ name, description?, owner?, visibility?, agent?, pick? }`: make an app from a sentence; answers `{ repo, url, issue, agent, run }` (`run` is the first run's state, or `none`) and draws the `ui://forge/app` card: name, production URL, first issue, agent, first run; refused as `POST /api/v1/apps` is (unverified, app_limit, no_such_agent, name_taken) | yes |
| `next_steps` | on a spawned forge, your first three steps and whether each is done; empty elsewhere or for anyone but its owner |  |
| `now` | what the crew is doing right now: who, on what, since when, at what cost; a planner that declined the direction and waits for you comes first (`run: null`, its words in `says`) |  |
| `org_teams` | `{ org, action, team, user?, permission? }` (admin-scope token, an org owner): `create` a team (`permission` read, write or admin; read by default), `add_member` a `user`, or `remove` the team; the same as POST/DELETE `/api/v1/orgs/:org/teams` | yes |
| `origin_apps` | `{ action, id?, host?, kind?, clientId?, clientSecret? }`: `list` your OAuth apps for connecting origins, `add` one (a `host`, or `kind` github), or `remove` one by `id`; the API's rules and errors, an admin-scope token; a secret is never read back, only `hasSecret` | yes |
| `origins` | `{ action, id? }`: `list` your connected origins, `repos` the repositories one holds (`id`; `mirroredAs` says which are already here), or `sync` one now; the same as `GET /api/v1/user/origins`, `…/:id/repos` and `POST …/:id/sync`, for you only, an admin token as there; never a credential in an answer | yes |
| `outsiders` | `{ repo, on?, dryRun? }`: whether people who cannot write may direct the crew; with `on`, planned first (`dryRun` is true unless `false`); set only by the app's admin with an admin token, never an agent | yes |
| `parent_unlink` | no input: stop signing in through the parent forge, as Settings does; refused when it is the account's last way in, and "Nothing to unlink." when nothing is linked; an admin token | yes |
| `plan` | `{ app, issues }`: open up to 12 linked issues, all or none (see below) | yes |
| `preview` | `{ url }`: what the forge pill says of an app host's URL (production or a pull's preview): `{ app, environment, pull: { number, title } \| null, check: "green" \| "red" \| "running" \| null, firstFailure, logUrl, working: [names] }`; `firstFailure` is the check's first failing test or its summary, `logUrl` is set only for someone who may read the log (a writer), `working` names the agents with a run going; a URL that is not one of this forge's app hosts is `invalid`, an app you cannot read is `not_found` and a pull you cannot see is `no_such_pull`, as `repo` and `pull` say |  |
| `probe` | knock on a running app's doors as nobody, a user and an admin; the ones that disobey its contract |  |
| `prompts` | `{ repo, action, kind?, token?, at?, id? }`: list, add, run or remove an app's prompt sources (Instagram), as the `…/prompts` API does; the token goes in once and is never shown; listed only for an admin-scope token, and only the repository's admin may use it | yes |
| `propose_to_parent_forge` | `{ repo }`: offer this forge's landed change to its parent as a pull on `child/<name>/…`; the same tip answers with that pull | yes |
| `pull` | `{ repo, number }`: a pull's title, state, head and base, and for an open pull whether it merges into the base's current head (`mergeable`) and the paths that stop it (`conflicts`), and `check: { state, baseOid }`: the latest check's state and the base tip it was merged with (empty when it merged nothing); `mergeable` and `conflicts` are the same fields as `GET …/pulls/:number`, `check` is `state` and `run.baseOid` from `GET …/pulls/:number/checks`; draws the `ui://forge/pull` card: `#N title`, state with check and conflicts while open, `head → base` linked to the pull, and the preview link when the pull has an environment |  |
| `pulls` | `{ repo, state?, limit? }`: a repository's pulls, newest first, one brief line each: `number`, `title`, `author`, `head`, `check` (state), `approvals`, `changesRequested`, `mergeable` (null once closed); `state` open (default) or closed, `limit` 1-50 (default 20); no bodies, no diffs |  |
| `read_file` | a file (utf-8, or base64 for binary) or a directory listing at a ref, as GET …/contents |  |
| `repo` | `{ repo }`: one repository's description, visibility, autonomy, `audience { level, sentence }` and `provenance` (where a migrated one came from, `null` when hidden), the same as `GET /api/v1/repos/:owner/:name` |  |
| `repo_labels` | `{ repo, action?, name?, color?, id? }`: list (`list`, the default; a read-only token may), create (`create`, `name`, `color` six hex digits) or remove (`remove`, `id`) the repository's labels, as `GET`/`POST …/labels` and `DELETE …/labels/:id`; create and remove need an admin token and a repository admin | yes |
| `repo_settings` | `{ repo, description?, visibility? }` (admin token): change a repository's description and visibility as `PATCH /api/v1/repos/:owner/:name` does, for the same callers (a repository admin); answers `{ repo, description, visibility }`; a visibility other than public or private is `invalid` | yes |
| `reports` | `{ repo, id?, action? }`: the waiting reports from outsiders, each `from: "outside"` (their words are unchecked); with `id` and `action` (`accept` opens it as an issue marked as from outside, `dismiss` closes it). A person who writes the repository only; needs an `rw` token | yes |
| `returns` | `{ repo?, days? }`: what the crew's tokens bought over the last `days` (1–90, default 7): dollars, runs, changes landed, cost per change; `repo` narrows it to one app of yours |  |
| `review` | `{ repo, number, verdict, reason? }`: approve a pull (`approve`) or request changes (`changes`, with a `reason`), as the page does; a writer's or the crew's, and never your own pull | yes |
| `run_log` | `{ repo, run, tail? }`: a run's log, or its last `tail` lines (1–2000), with the REST route's access: a hidden log or unreadable repository is not found |  |
| `runs` | `{ repo, limit? }`: the repository's recent runs, newest first (id, kind, state, issue or pull number, started, ended), 1–50, default 20; read as the runs page reads them |  |
| `say` | speak on an issue or a pull; a working builder hears it as its next step | yes |
| `seal` | `{ repo, number, sealed }`: seal a security report (and the pull that fixes it) so only writers and the crew see it, or unseal it for every reader; a writer's, recorded | yes |
| `search` | `{ q, kind?, repo? }`: issues, pulls, repositories and code you can read, the same results as /search; `repo` keeps to one |  |
| `secrets` | `{ scope, ref?, action, name?, value? }` (forge admin): `list` the names and timestamps of the forge's sealed secrets, `set` or `remove` one; `scope` is forge, org or repo, `ref` the org or `owner/name`; a value is never read back | yes |
| `sever` | `{ repo }`: cut a spawned forge's link to the forge its code came from; its `forge` repository's owner only; deletes nothing | yes |
| `signup` | `{ mode?, dryRun? }`: who may sign up: `open` (default), `invite` (only a person with an open invite link) or `closed` (no new accounts); without `mode` it reads the setting, with `mode` it plans first (`dryRun` is true unless `false`), and applying needs an admin token | yes |
| `spawn` | `{ name, apps?, crew?, dryRun? }`: a child forge, planned first (`dryRun` is true unless `false`); an admin's, and an `ro` token may plan but not make | yes |
| `ssh_keys` | `{ action?, title?, key?, id? }`: list your own SSH keys (default), add one (`key` is an authorized_keys line, `title` optional) or remove one by `id`; the API's rules and errors, add and remove need an `rw` token | yes |
| `stop` | stop one run by its id from `now` | yes |
| `subscription_budget` | `{ id, usd }`: set an account's whole-life budget in dollars (up to the `subscription.budget_max_usd` limit), or clear it with `usd: null`, as the Subscriptions page does; a locked budget can only be lowered; a forge admin with an admin token | yes |
| `system` | the machine the forge runs on, now: CPU, load, memory, disk, network, processes; a forge admin, or an agent granted `telemetry:read` |  |
| `take_updates` | a fork takes its parent's updates when git can do it alone; a conflict is refused. On a spawned forge's code repository it opens the one `forge/take-updates` pull and never moves the default branch | yes |
| `telemetry_grant` | `{ agent, on }`: grant an agent `telemetry:read`, or take it back with `false`, as the Telemetry page does; a person admin's, with an admin token; answers `says` | yes |
| `tell` | a sentence becomes an issue, a builder is picked, a run starts on the crew's next tick | yes |
| `thought` | `{ id }`: where one of your thoughts went (its id comes from `tell` without a repo): the placement, and the earlier thoughts it repeats or takes back and the later ones that did the same; not yours and not there answer alike, `not_found` |  |
| `threads` | `{ repo, number, anchor?, resolved? }`: a pull's review threads with their comments; with `anchor` (from the list) resolve it (`resolved` true, the default) or reopen it (false), by the API's rules: a writer or someone who commented in the thread | yes |
| `trail` | `{ repo, shown?, dryRun? }`: where a migrated repository came from (`provenance`: source, sourceUrl, parents, migratedAt) and whether it is shown; with `shown`, shows or hides the trail — planned first (`dryRun` is true unless `false`), only the repository's admin with an admin token, never an agent. Hiding keeps the record; a hidden one reads `null` to anyone but an admin | yes |
| `upstream` | `{ repo, enabled?, url?, branch?, check? }`: the repository a fork follows (an admin reads it); with `enabled` sets it, with `check: true` checks it now; setting and checking need an admin token | yes |
| `usage` | `{ repo, days? }`: what the crew's runs spent — tokens, cost, wall time — by subscription, agent, issue, and each account's 5-hour and weekly standing; a writer's |  |
| `wait_for` | `{ app, issue, blockedBy, stop? }`: the issue waits for another, or stops with `stop: true`; the page's rules, and the answer carries the issue's URL | yes |
| `watch` | `{ app, issue, watch? }`: watch a milestone, or stop with `watch: false`: one item in your feed that follows it, and one push to your phone when it lands | yes |
| `whoami_can` | `{ kind? }`: your role and that role's row of the roles table, each ability yes or no; `kind: "passkeys"` lists your own passkeys (`{ items }`: id, name, created, lastUsed), people only |  |
<!-- tools:end -->
### Adding a tool
One tool, one file (#5924): `src/http/mcp/tools/<name>.ts` exports `tool`,
its definition and `run`, and nothing else; its arguments' shared helpers
are in `src/http/mcp/shared.ts`. Its row in the table above is its `doc`.
Then run `bun scripts/mcp-tools.ts`: it adds one line to the sorted
`tools/index.ts` and one row to the table, so two pulls adding two tools
edit no line in common. `test/mcp-tools.test.ts` holds every tool file to
the same contract and goes red when either generated file is stale; the
tool's own behaviour is tested in `test/mcp-<name>.test.ts`.
### Room for a new tool
@@ -207,7 +222,7 @@
can call `apps` and is refused `tell`.
`src/http/oauth.ts`, `src/core/oauth.ts`, `src/web/pages/oauth.ts`,
`test/oauth-flow.test.ts`.
`src/http/mcp.ts`, `src/actions/tell.ts`, `test/mcp.test.ts`.
`src/http/mcp.ts`, `src/http/mcp/tools/`, `src/actions/tell.ts`, `test/mcp.test.ts`.
## `plan`
@@ -0,0 +1,81 @@
/**
 * Writes the MCP tools' generated files from `src/http/mcp/tools/*.ts` (#5924):
 *
 * - `src/http/mcp/tools/index.ts`: one sorted line per tool file, so a pull
 *   that adds a tool adds one line and never edits another pull's.
 * - the `## Tools` table in `docs/MCP.md`, between its `tools:begin` and
 *   `tools:end` markers, from each tool's `doc` and `writes`.
 *
 *   bun scripts/mcp-tools.ts          write both
 *   bun scripts/mcp-tools.ts --check  exit 1, naming the file, when either is stale
 *
 * `test/mcp-tools.test.ts` runs the check, so a pull that adds a tool file
 * without running this goes red with the command to run.
 */
import { readdirSync, readFileSync, writeFileSync } from "node:fs";
import { join } from "node:path";
const ROOT = join(import.meta.dir, "..");
const DIR = join(ROOT, "src/http/mcp/tools");
const INDEX = join(DIR, "index.ts");
const DOC = join(ROOT, "docs/MCP.md");
const BEGIN = "<!-- tools:begin: generated by `bun scripts/mcp-tools.ts` from each tool's `doc` -->";
const END = "<!-- tools:end -->";
/** The tool files, by name: every `<name>.ts` here but the index. */
export function toolFiles(dir = DIR): string[] {
  return readdirSync(dir)
    .filter((f) => /^[a-z][a-z0-9_]*\.ts$/.test(f) && f !== "index.ts")
    .map((f) => f.slice(0, -3))
    .sort();
}
export function indexText(names: readonly string[]): string {
  return [
    "// Generated by `bun scripts/mcp-tools.ts` from the files beside it; do not edit.",
    "// One line per tool, sorted: a new tool is a new file and one new line here.",
    ...names.map((n) => `export { tool as ${n} } from "./${n}.ts";`),
    "",
  ].join("\n");
}
type Documented = { readonly name: string; readonly doc?: string; readonly writes: boolean };
export function tableText(tools: readonly Documented[]): string {
  const rows = [...tools]
    .filter((t) => t.doc !== undefined)
    .sort((a, b) => a.name.localeCompare(b.name))
    .map((t) => `| \`${t.name}\` | ${t.doc} | ${t.writes ? "yes" : ""} |`);
  return [BEGIN, "", "| tool | does | writes |", "| ---- | ---- | ------ |", ...rows, "", END].join("\n");
}
/** docs/MCP.md with its table replaced by `table`. */
export function withTable(md: string, table: string): string {
  const from = md.indexOf(BEGIN);
  const to = md.indexOf(END);
  if (from < 0 || to < from) throw new Error(`docs/MCP.md has no ${BEGIN} … ${END} markers`);
  return md.slice(0, from) + table + md.slice(to + END.length);
}
if (import.meta.main) {
  const check = process.argv.includes("--check");
  const stale: string[] = [];
  const index = indexText(toolFiles());
  if (readFileSync(INDEX, "utf8") !== index) {
    stale.push("src/http/mcp/tools/index.ts");
    if (!check) writeFileSync(INDEX, index);
  }
  // After the index is current, so a new file's row is in the table.
  const { TOOLS } = await import("../src/http/mcp/tools.ts");
  const md = readFileSync(DOC, "utf8");
  const doc = withTable(md, tableText(TOOLS));
  if (md !== doc) {
    stale.push("docs/MCP.md");
    if (!check) writeFileSync(DOC, doc);
  }
  if (check && stale.length > 0) {
    console.error(`stale: ${stale.join(", ")}; run \`bun scripts/mcp-tools.ts\``);
    process.exit(1);
  }
  if (!check) console.log(stale.length > 0 ? `wrote ${stale.join(", ")}` : "current");
}
@@ -0,0 +1,220 @@
import { mayView } from "../../core/sealed.ts";
import { getIssue } from "../../core/issues.ts";
import { canRead, getRepo, type Repo } from "../../core/repos.ts";
import { scopeAllows } from "../../core/tokens.ts";
import { getUserByName, type User } from "../../core/users.ts";
import { applyFleetIds, previewFleetIds } from "../../actions/fleet.ts";
import { KIND_CHIPS, parseChipArgs } from "../../core/feed_chips.ts";
import type { Ctx } from "../context.ts";
import type { BoardError } from "../../actions/boards.ts";
import { BOARD_NOT_SAVED } from "../../actions/board_words.ts";
export type Args = Record<string, unknown>;
export type Answer =
  | { ok: true; value: unknown; card?: Record<string, unknown> }
  | { ok: false; error: string; message: string };
export const good = (value: unknown): Answer => ({ ok: true, value });
export const attachWords = (error: string): string =>
  ({
    forbidden: "attaching a look is for a person who can write this app",
    not_open: "only an open pull takes a look",
    no_app: "this repository has no app, so its pulls have no looks",
    bad_width: "width is phone or desktop",
    bad_note: "say what it shows in one line, at most 200 characters (says)",
    bad_image: "image must be a PNG or JPEG, base64, that reads",
    too_large: "the picture is over 5 MB",
  })[error] ?? "refused";
export const bad = (error: string, message: string): Answer => ({
  ok: false,
  error,
  message,
});
export interface Tool {
  readonly name: string;
  /** Its row in docs/MCP.md's tool table: markdown, one line; absent, the tool has no row yet. */
  readonly doc?: string;
      
        sentinelcrew
        19d ago
        
      
      Non-blocking: because doc is optional, a new tool file can land with no row in docs/MCP.md, and nothing goes red. 21 tools have no doc today (asks*, capacity, flow, quotas, …), the same as on main, so this is not a regression. A follow-up could make doc required and give those 21 rows, so the generated table stays complete by construction.
    
  readonly description: string;
  readonly inputSchema: Record<string, unknown>;
  /** Whether it changes anything: `rw` scope, and said so to the client. */
  readonly writes: boolean;
  /** Listed, and callable, for a forge admin only. */
  readonly adminOnly?: true;
  /** Listed, and callable, only with a token of this scope. */
  readonly needsAdminScope?: true;
  /** With this argument absent the tool only reads, whatever the token. */
  readonly readsWithout?: string;
  /** A call this accepts only reads, whatever the token. */
  readonly readsWhen?: (args: Args) => boolean;
  /** A write that only plans (`dryRun` not false) is a read: `ro` may ask. */
  readonly dryByDefault?: true;
  run(ctx: Ctx, user: User, args: Args): Promise<Answer> | Answer;
}
/** Whether this caller is shown the tool and may call it: one rule for the manifest and dispatch. */
export const visible = (tool: Tool, ctx: Ctx, user: User): boolean =>
  (tool.adminOnly !== true || user.isAdmin) &&
  (tool.needsAdminScope !== true || scopeAllows(ctx.auth.scope ?? "ro", "admin"));
/** Whether this call only plans or reads, so a read-only token may make it. */
export const plansOnly = (tool: Tool, args: Args): boolean =>
  (tool.dryByDefault === true && args["dryRun"] !== false) ||
  (tool.readsWithout !== undefined && args[tool.readsWithout] === undefined) ||
  tool.readsWhen?.(args) === true;
export const CHIP_ARGS = {
  hide_kinds: {
    type: "array",
    items: { type: "string", enum: [...KIND_CHIPS] },
    maxItems: 50,
    description: "Kinds to hide.",
  },
  hide_people: {
    type: "array",
    items: { type: "string", maxLength: 39 },
    maxItems: 50,
    description: "Usernames to hide.",
  },
} as const;
/** The filter a call names, or undefined for the viewer's saved one. */
export function chipArgs(ctx: Ctx, args: Record<string, unknown>) {
  return parseChipArgs(args, (name) => {
    const who = getUserByName(ctx.app.db, name.trim());
    return who && who.kind !== "org" ? who.id : undefined;
  });
}
export const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
export const REPO_ARG = { type: "string" } as const;
/** A repository the caller may read, by `owner/name`; a wrong one is answered with that form. */
export function repoArg(ctx: Ctx, user: User, args: Args): Repo | Answer {
  const [owner, name, ...rest] = str(args["repo"]).split("/");
  const repo =
    owner && name && rest.length === 0
      ? getRepo(ctx.app.db, owner, name)
      : undefined;
  // One answer for "no such repository" and "not yours to see".
  return repo !== undefined && canRead(ctx.app.db, repo, user)
    ? repo
    : bad("not_found", "no such app or repository (owner/name)");
}
export const MAX_ARCHIVE_REPOS = 50;
/** `archive` over `repos`: the fleet's own operation, each row's outcome and the id to undo. */
export async function archiveMany(ctx: Ctx, user: User, args: Args): Promise<Answer> {
  const names = args["repos"];
  if (
    !Array.isArray(names) ||
    names.length === 0 ||
    names.length > MAX_ARCHIVE_REPOS ||
    names.some((n) => typeof n !== "string")
  )
    return bad("invalid", `\`repos\` is one to ${MAX_ARCHIVE_REPOS} names, owner/name each`);
  if (args["repo"] !== undefined)
    return bad("invalid", "give `repo` or `repos`, not both");
  if (args["archived"] !== undefined && typeof args["archived"] !== "boolean")
    return bad("invalid", "`archived` is true or false");
  const archived = args["archived"] ?? true;
  const dryRun = args["dryRun"] !== false;
  if (user.kind === "agent")
    return bad("forbidden", "archiving or waking is a person's call, not an agent's");
  if (!dryRun && !scopeAllows(ctx.auth.scope ?? "ro", "admin"))
    return bad("forbidden", "archiving or waking needs an admin token");
  const ids: string[] = [];
  const missing: string[] = [];
  for (const name of new Set(names as string[])) {
    const repo = repoArg(ctx, user, { repo: name });
    if (isAnswer(repo)) missing.push(name);
    else ids.push(repo.id);
  }
  const query = `mcp: ${ids.length + missing.length} named`;
  const action = { verb: "archive", value: archived };
  const unknown = missing.map((repo) => ({
    repo,
    outcome: "refused",
    reason: "no such app or repository (owner/name)",
  }));
  const rowsOf = (rows: readonly { label: string; outcome: string; reason: string }[]) => [
    ...rows.map((r) => ({ repo: r.label, outcome: r.outcome, reason: r.reason })),
    ...unknown,
  ];
  if (dryRun) {
    const plan = previewFleetIds(ctx.app, user, "repo", ids, query, action);
    if (!plan.ok) return bad(plan.error.code, plan.error.message);
    return good({
      dryRun: true,
      archived,
      rows: rowsOf(plan.value.rows),
      says: "This is the plan; nothing changed. Send dryRun: false to do it.",
    });
  }
  const op = await applyFleetIds(ctx.app, user, "repo", ids, query, action);
  if (!op.ok) return bad(op.error.code, op.error.message);
  return good({
    dryRun: false,
    archived,
    operation: op.value.id,
    rows: rowsOf(op.value.rows),
    says: `Done. The \`limb\` tool with action undo and operation ${op.value.id} reverts it for 24 hours.`,
  });
}
// tools/list is held under 40 KB (test/mcp-size.test.ts). The server checks
// every length at the boundary, so the listing leaves the maxLength hints out.
export function lean(schema: unknown): unknown {
  if (Array.isArray(schema)) return schema.map(lean);
  if (schema === null || typeof schema !== "object") return schema;
  return Object.fromEntries(
    Object.entries(schema).filter(([k]) => k !== "maxLength").map(([k, v]) => [k, lean(v)]),
  );
}
export const APP_ARG = { type: "string" } as const;
// A child's claim link is a live secret: whoever holds it takes the child.
// It stays out of an agent's conversation unless asked for there on purpose
// (#839); a person admin of this forge gets a fresh one on /forges, in their
// own browser, and hands it over.
export const REVEAL_ARG = {
  type: "boolean",
  description:
    "true: show the secret link.",
} as const;
export const LINK_KEPT =
  "The claim link is a secret, so it is not in this conversation: a person admin of this forge gets a fresh one on /forges (Send a fresh link) and hands it to the child's person. Send reveal: true only to have it here on purpose.";
export const LINK_REVEALED =
  "claimUrl is a live secret, now in this conversation: whoever holds it takes the child. Hand it only to the child's person; the secret is in its #fragment, so send it whole.";
/** The app a plan tool names, under `app`, read like any repository. */
export const planRepo = (ctx: Ctx, user: User, args: Args): Repo | Answer =>
  repoArg(ctx, user, { repo: args["app"] });
/** The issue a plan tool names by number, in that repository. */
export function issueArg(ctx: Ctx, repo: Repo, args: Args, key: string) {
  const n = args[key];
  const issue =
    typeof n === "number" && Number.isInteger(n) && n > 0
      ? getIssue(ctx.app.db, repo.id, n)
      : undefined;
  // A sealed report is not there for anyone who may not see it.
  return issue !== undefined && mayView(ctx.app.db, repo, issue, ctx.auth.user)
    ? issue
    : bad("no_such_issue", `no issue #${String(n)}`);
}
export const isAnswer = (v: Repo | Answer): v is Answer => "ok" in v;
/** Boards are a forge admin's who is a person, as the API gates them: anyone else is forbidden, not told what is there. */
export const boardRefused = (): Answer => bad("forbidden", "boards are for a forge admin who is a person");
export const mayBoards = (user: User): boolean => user.isAdmin && user.kind !== "agent";
export function boardFailed(e: BoardError): Answer {
  if (e === "not_found") return bad("not_found", "no such board");
  if (typeof e === "object") return bad("refused", e.refused);
  return bad(e, BOARD_NOT_SAVED);
}
@@ -0,0 +1,9 @@
/**
 * Every MCP tool but `report`, by name: one file each under `tools/`,
 * gathered by the generated `tools/index.ts` (`bun scripts/mcp-tools.ts`).
 * A new tool is a new file there, so pulls adding tools do not collide (#5924).
 */
import type { Tool } from "./shared.ts";
import * as each from "./tools/index.ts";
export const TOOLS: readonly Tool[] = Object.values(each).sort((a, b) => a.name.localeCompare(b.name));
@@ -0,0 +1,32 @@
import { listAccess } from "../../../actions/access_log.ts";
import { good, bad, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "access",
  doc: "`{ since?, ua?, path? }`: what outside agents tried: the redacted log of non-browser requests to public paths, newest first; `since` an ISO time (default a day, at most 14 days), `ua` part of the user agent, `path` a prefix; a forge admin's",
  description:
    "Non-browser public-path requests, redacted, newest first (max 500). Forge admin.",
  inputSchema: {
    type: "object",
    properties: {
      since: { type: "string", maxLength: 40, description: "ISO time." },
      ua: { type: "string", maxLength: 100, description: "User agent part." },
      path: { type: "string", maxLength: 200, description: "Path prefix." },
    },
  },
  writes: true,
  run(ctx, user, args) {
    const text = (k: string): string | undefined =>
      typeof args[k] === "string" && args[k] !== "" ? (args[k] as string) : undefined;
    const since = text("since");
    const ua = text("ua");
    const path = text("path");
    const listed = listAccess(ctx.app, user, {
      ...(since === undefined ? {} : { since: since.slice(0, 40) }),
      ...(ua === undefined ? {} : { ua: ua.slice(0, 100) }),
      ...(path === undefined ? {} : { path: path.slice(0, 200) }),
    });
    if (!listed.ok) return bad("not_found", "no such tool here");
    return good({ requests: listed.value });
  },
};
@@ -0,0 +1,52 @@
import { SPEND_WORDS } from "../../../actions/spend_words.ts";
import { setRole } from "../../../actions/roles.ts";
import { scopeAllows } from "../../../core/tokens.ts";
import { good, bad, type Tool, mayBoards } from "../shared.ts";
export const tool: Tool = {
  name: "account_role",
  doc: "`{ username, role, usdPerMonth?, dryRun? }`: make a person a `member`, or a `guest` again, with an optional starter allowance (`usdPerMonth`, 0.01 to 10000, promoting only); planned first (`dryRun` is true unless `false`)",
  description:
    "Make a person a member, or a guest again; promoting may give a monthly `usdPerMonth` allowance.",
  inputSchema: {
    type: "object",
    properties: {
      username: { type: "string" },
      role: { type: "string", enum: ["member", "guest"] },
      usdPerMonth: { type: ["number", "null"], description: "0.01–10000 or none." },
      dryRun: { type: "boolean", description: "false to apply" },
    },
    required: ["username", "role"],
  },
  writes: true,
  dryByDefault: true,
  run(ctx, user, args) {
    const { username, role, usdPerMonth } = args;
    if (
      typeof username !== "string" ||
      (role !== "member" && role !== "guest") ||
      !(usdPerMonth === undefined || usdPerMonth === null || (typeof usdPerMonth === "number" && Number.isFinite(usdPerMonth)))
    )
      return bad("invalid", 'send a username and a role, "member" or "guest"');
    if (!mayBoards(user)) return bad("forbidden", "a role is a forge admin's to set");
    const usd = typeof usdPerMonth === "number" ? usdPerMonth : null;
    if (args["dryRun"] !== false)
      return good({
        username,
        role,
        usdPerMonth: usd,
        says: "This is the plan; nothing changed. Send dryRun: false to set it.",
      });
    if (!scopeAllows(ctx.auth.scope ?? "ro", "admin"))
      return bad("forbidden", "a role needs an admin token");
    const set = setRole(ctx.app, user, username, role, usd);
    if (!set.ok)
      return bad(
        set.error === "invalid_amount" ? "invalid" : "forbidden",
        set.error === "invalid_amount"
          ? SPEND_WORDS.usdPerMonth
          : "no such person, or not one a role is for",
      );
    return good(set.value);
  },
};
@@ -0,0 +1,32 @@
import { suspendAccount, unsuspendAccount } from "../../../actions/accounts.ts";
import { scopeAllows } from "../../../core/tokens.ts";
import { lastOwnerSays } from "../../../core/orgs.ts";
import { ADMIN_WORDS } from "../../../actions/admin_words.ts";
import { good, bad, type Tool, mayBoards } from "../shared.ts";
export const tool: Tool = {
  name: "account_suspend",
  doc: "`{ username, suspended }`: suspend a person's account, or unsuspend it with `false`; their sessions and tokens stop at once; the API's rules (not yourself, another admin or an agent; not the only owner of an organization); an admin token",
  description: "Suspend an account, or `suspended: false` to lift it.",
  inputSchema: {
    type: "object",
    properties: { username: { type: "string" }, suspended: { type: "boolean" } },
    required: ["username", "suspended"],
  },
  writes: true,
  async run(ctx, user, args) {
    const { username, suspended } = args;
    if (typeof username !== "string" || typeof suspended !== "boolean")
      return bad("invalid", "send a username and suspended, true or false");
    if (!mayBoards(user)) return bad("forbidden", "an account is a forge admin's to suspend");
    if (!scopeAllows(ctx.auth.scope ?? "ro", "admin"))
      return bad("forbidden", "suspending needs an admin token");
    const done = suspended
      ? await suspendAccount(ctx.app, user, username)
      : unsuspendAccount(ctx.app, user, username);
    if (done.ok) return good({ username: done.value.username, suspendedAt: done.value.suspendedAt });
    if (done.error === "not_found") return bad("not_found", "no such person");
    if (done.error === "last_owner") return bad("last_owner", lastOwnerSays(ctx.app.db, username));
    return bad("not_allowed", ADMIN_WORDS.selfSuspend);
  },
};
@@ -0,0 +1,27 @@
import { verifyAccount } from "../../../actions/accounts.ts";
import { scopeAllows } from "../../../core/tokens.ts";
import { good, bad, type Tool, mayBoards } from "../shared.ts";
export const tool: Tool = {
  name: "account_verify",
  doc: "`{ username }`: mark a person's email verified, as `POST …/admin/accounts/:username/verify` does; a person admin's, with an admin token",
  description: "Mark a person's email verified (admin).",
  inputSchema: {
    type: "object",
    properties: { username: { type: "string" } },
    required: ["username"],
  },
  writes: true,
  run(ctx, user, args) {
    const { username } = args;
    if (typeof username !== "string") return bad("invalid", "send a username");
    if (!mayBoards(user)) return bad("forbidden", "verifying a person is a forge admin's call");
    if (!scopeAllows(ctx.auth.scope ?? "ro", "admin"))
      return bad("forbidden", "verifying a person needs an admin token");
    const done = verifyAccount(ctx.app, user, username);
    if (done.ok) return good({ username: done.value.username, verified: true });
    return done.error === "not_found"
      ? bad("not_found", "no such account")
      : bad("invalid", "an agent or a removed account has no email to verify");
  },
};
@@ -0,0 +1,63 @@
import { createAgent, deleteAgent, updateAgent } from "../../../actions/crew.ts";
import type { Agent } from "../../../core/agents.ts";
import { good, bad, type Tool, str } from "../shared.ts";
export const tool: Tool = {
  name: "agent",
  doc: "`{ action, username, … }`: `create` a crew agent, `update` its `model`, `brief` or `budgetUsd`, or `remove` it; an admin's, with an `admin` token, as `/api/v1/agents`",
  description: "Admin: create|update|remove an agent.",
  inputSchema: {
    type: "object",
    properties: {
      action: { type: "string" },
      username: { type: "string" },
      displayName: { type: "string" },
      model: { type: "string" },
      brief: { type: "string" },
      budgetUsd: { type: "number" },
    },
    required: ["action", "username"],
  },
  writes: true,
  adminOnly: true,
  needsAdminScope: true,
  async run(ctx, user, args) {
    const username = str(args["username"]);
    const model = args["model"];
    const brief = args["brief"];
    const budgetUsd = args["budgetUsd"];
    const fields = {
      ...(typeof model === "string" ? { model } : {}),
      ...(typeof brief === "string" ? { brief } : {}),
      ...(typeof budgetUsd === "number" ? { budgetUsd } : {}),
    };
    const shown = (a: Agent) => ({
      username: a.user.username,
      displayName: a.user.displayName,
      model: a.model,
      brief: a.brief,
      budgetUsd: a.budgetUsd,
      createdAt: a.createdAt,
    });
    const action = args["action"];
    if (action === "create") {
      const made = await createAgent(ctx.app, user, {
        username,
        ...(typeof args["displayName"] === "string"
          ? { displayName: args["displayName"] }
          : {}),
        ...fields,
      });
      return made.ok ? good(shown(made.value)) : bad(made.error, made.error);
    }
    if (action === "update") {
      const done = updateAgent(ctx.app, user, username, fields);
      return done.ok ? good(shown(done.value)) : bad(done.error, done.error);
    }
    if (action === "remove") {
      const gone = deleteAgent(ctx.app, user, username);
      return gone.ok ? good({ removed: username }) : bad(gone.error, gone.error);
    }
    return bad("invalid", "action is create, update or remove");
  },
};
@@ -0,0 +1,37 @@
import { redeployEnv, stopEnv } from "../../../actions/apps.ts";
import { good, bad, type Tool, str, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "app_deploy",
  doc: "`{ repo, env, action }`: `redeploy` or `stop` an app's `production` or a pull's `pull-N` preview; a writer's, queued as `POST …/app/:env/redeploy` and `…/stop` are; answers `{ queued, run }` or `{ stopped }`",
  description:
    "Redeploy or stop production or a pull-N preview.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      env: { type: "string" },
      action: { type: "string", enum: ["redeploy", "stop"] },
    },
    required: ["repo", "env", "action"],
  },
  writes: true,
  async run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const env = str(args["env"]);
    const action = str(args["action"]);
    if (action !== "redeploy" && action !== "stop")
      return bad("invalid_action", "action is redeploy or stop");
    if (action === "stop") {
      const stopped = await stopEnv(ctx.app, user, repo, env);
      return stopped.ok
        ? good({ stopped: true })
        : bad(stopped.error, `refused: ${stopped.error}`);
    }
    const queued = await redeployEnv(ctx.app, user, repo, env);
    return queued.ok
      ? good({ queued: true, run: queued.value?.id ?? null })
      : bad(queued.error, `refused: ${queued.error}`);
  },
};
@@ -0,0 +1,50 @@
import { scopeAllows } from "../../../core/tokens.ts";
import { deleteAppEnvVar, listAppEnv, setAppEnvVar } from "../../../actions/apps.ts";
import { type Answer, good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "app_env",
  doc: "`{ repo, action, name?, value?, scope? }`: `list` an app's variable names and scopes, `set` one, or `unset` it, in `all` (default), `production` or `preview`; the API's rules and errors, an admin of the repository with an admin-scope token; a value is never read back",
  description:
    "An app's environment variables: list names, set or unset one by scope; values are write-only. Admin.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      action: { type: "string", enum: ["list", "set", "unset"] },
      name: { type: "string" },
      value: { type: "string" },
      scope: { type: "string", enum: ["all", "production", "preview"] },
    },
    required: ["repo", "action"],
  },
  writes: true,
  async run(ctx, user, args) {
    if (!scopeAllows(ctx.auth.scope ?? "ro", "admin"))
      return bad("forbidden", "an app's environment needs an admin-scope token");
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const action = args["action"];
    const scope = typeof args["scope"] === "string" ? args["scope"] : "all";
    const name = typeof args["name"] === "string" ? args["name"] : "";
    // The API's errors, by code: never the value.
    const refused = (error: string): Answer =>
      error === "not_found"
        ? bad("not_found", "no such app or repository (owner/name)")
        : bad(error, error);
    if (action === "list") {
      const listed = listAppEnv(ctx.app, user, repo);
      return listed.ok ? good({ items: listed.value, next_cursor: null }) : refused(listed.error);
    }
    if (action === "set") {
      const value = typeof args["value"] === "string" ? args["value"] : "";
      const set = await setAppEnvVar(ctx.app, user, repo, name, value, scope);
      return set.ok ? good(set.value) : refused(set.error);
    }
    if (action === "unset") {
      const removed = await deleteAppEnvVar(ctx.app, user, repo, name, scope);
      return removed.ok ? good({}) : refused(removed.error);
    }
    return bad("invalid", "`action` is list, set or unset");
  },
};
@@ -0,0 +1,43 @@
import { scopeAllows } from "../../../core/tokens.ts";
import { readAppMembers, setAppMembersThrough } from "../../../actions/app_members.ts";
import { type Answer, good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "app_members",
  doc: "`{ repo, members?, dryRun? }`: the people a private app names, who may enter it and its previews and nothing else; a writer (never an agent) changes the list with an admin-scope token",
  description:
    "The people a private app names, who may enter it and its previews. With `members`, plans.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      members: { type: "array", items: { type: "string" } },
      dryRun: { type: "boolean" },
    },
    required: ["repo"],
  },
  writes: true,
  dryByDefault: true,
  run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const members = args["members"];
    const answer = (
      result: ReturnType<typeof readAppMembers> | ReturnType<typeof setAppMembersThrough>,
    ): Answer =>
      result.ok
        ? good(result.value)
        : result.error.kind === "invalid"
          ? bad("invalid", result.error.message)
          : result.error.kind === "forbidden"
            ? bad("forbidden", "the people an app names are its writers' to choose")
            : bad("not_found", "no such app or repository (owner/name)");
    if (members === undefined) return answer(readAppMembers(ctx.app, user, repo));
    if (!Array.isArray(members) || !members.every((m) => typeof m === "string"))
      return bad("invalid", "members is a list of usernames");
    const dryRun = args["dryRun"] !== false;
    if (!dryRun && !scopeAllows(ctx.auth.scope ?? "ro", "admin"))
      return bad("forbidden", "changing who may enter an app needs an admin-scope token");
    return answer(setAppMembersThrough(ctx.app, user, repo, { members, dryRun }));
  },
};
@@ -0,0 +1,37 @@
import { appsRuntime, envsFor } from "../../../apps/runtime.ts";
import { listActiveRuns } from "../../../core/runs.ts";
import { appsOf } from "../../../web/studio/asks.ts";
import { good, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "apps",
  doc: "the apps you can see: live or not, where served, how each runs itself, what is working",
  description:
    "The apps here you can see: live or not, where served, how each runs, what is working.",
  inputSchema: { type: "object", properties: {} },
  writes: false,
  async run(ctx, user) {
    const { repos, records } = appsOf(ctx, user);
    const runtime = appsRuntime(ctx.app);
    const active = listActiveRuns(
      ctx.app.db,
      repos.map((r) => r.id),
    );
    return good(
      repos.map((repo) => {
        const record = records.get(repo.id)!;
        const production = envsFor(ctx.app, user, record).find(
          (e) => e.env === "production",
        );
        return {
          app: `${repo.ownerName}/${repo.name}`,
          description: repo.description,
          live: production?.state ?? "stopped",
          url: runtime?.urlFor(record, "production") ?? null,
          autonomy: repo.autonomy,
          working: active.filter((r) => r.repoId === repo.id).length,
        };
      }),
    );
  },
};
@@ -0,0 +1,52 @@
import { scopeAllows } from "../../../core/tokens.ts";
import { setArchived } from "../../../actions/repos.ts";
import { good, bad, type Tool, REPO_ARG, repoArg, MAX_ARCHIVE_REPOS, archiveMany, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "archive",
  doc: "`{ repo | repos, archived?, dryRun? }`: archive (true) or wake (false) a repository, by name; planned first (`dryRun` is true unless `false`); only the repository's admin with an admin token, never an agent. `repos` (at most 50) runs the fleet `archive` operation over them, answers each one's outcome and the `operation` id; `limb` with `action: \"undo\"`, that `operation` and any one of the repositories as `app` reverts it for a day",
  description:
    "Archive a repository or wake it (`archived` true/false); deletes nothing. Plans first; admin token.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      repos: {
        type: "array",
        items: { type: "string" },
        maxItems: MAX_ARCHIVE_REPOS,
        description: "owner/name list, one operation.",
      },
      archived: { type: "boolean" },
      dryRun: {
        type: "boolean",
        description: "false to apply",
      },
    },
  },
  writes: true,
  dryByDefault: true,
  async run(ctx, user, args) {
    if (args["repos"] !== undefined) return archiveMany(ctx, user, args);
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const archived = args["archived"];
    if (archived === undefined) return good({ archived: repo.archivedAt !== null });
    if (typeof archived !== "boolean")
      return bad("invalid", "`archived` is true or false");
    const dryRun = args["dryRun"] !== false;
    if (!dryRun && !scopeAllows(ctx.auth.scope ?? "ro", "admin"))
      return bad("forbidden", "archiving or waking needs an admin token");
    const set = await setArchived(ctx.app, user, repo, archived, dryRun);
    if (!set.ok)
      return bad("forbidden", "only an admin of this repository archives or wakes it");
    return good({
      ...set.value,
      says: dryRun
        ? `This is the plan; nothing changed. It is ${set.value.was ? "archived" : "awake"} now; send dryRun: false to ${set.value.archived ? "archive" : "wake"} it.`
        : set.value.archived
          ? "Archived: put away, not deleted."
          : "Awake again.",
    });
  },
};
@@ -0,0 +1,35 @@
import { askedIn, askedJson, askedRepos, isAskedOrder, isAskedShow } from "../../../core/asked.ts";
import { streamJson, thoughtStream } from "../../../core/thought_stream.ts";
import { good, bad, type Tool, str, REPO_ARG } from "../shared.ts";
export const tool: Tool = {
  name: "asked",
  doc: "`{ repo?, show?, order? }`: what people asked the crew for, by default nothing merged yet and oldest first: who and when, the pulls that close it, the crew's last activity, waiting/building/shipped/closed, stale when not shipped in three days and flagged when stale with nothing built; repositories you can write",
  description:
    "What people asked the crew for where you write: by default nothing merged yet, oldest first.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      show: { type: "string", enum: ["unshipped", "flagged", "all"] },
      order: { type: "string", enum: ["oldest", "newest"] },
    },
  },
  writes: false,
  run(ctx, user, args) {
    const show = args["show"] ?? "unshipped";
    if (!isAskedShow(show))
      return bad("invalid_show", "show is unshipped, flagged or all");
    const order = args["order"] ?? "oldest";
    if (!isAskedOrder(order))
      return bad("invalid_order", "order is oldest or newest");
    const spec = args["repo"] === undefined ? null : str(args["repo"]);
    const repos = askedRepos(ctx.app.db, user, spec);
    if (spec !== null && repos.length === 0)
      return bad("not_found", "no such app or repository you can write (owner/name)");
    return good({
      asked: askedIn(ctx.app.db, repos, { show, order }).map(askedJson),
      thoughts: thoughtStream(ctx.app.db, user).map(streamJson),
    });
  },
};
@@ -0,0 +1,15 @@
import { asksAnswer } from "../../../web/studio/asks.ts";
import { good, bad, type Tool, CHIP_ARGS, chipArgs } from "../shared.ts";
export const tool: Tool = {
  name: "asks",
  description:
    "What waits on you, most important first: decision, options, cost of inaction; saved filter applies",
  inputSchema: { type: "object", properties: { ...CHIP_ARGS } },
  writes: false,
  run(ctx, user, args) {
    const chips = chipArgs(ctx, args);
    if (chips && "error" in chips) return bad("invalid", chips.error);
    return good(asksAnswer(ctx, user, chips));
  },
};
@@ -0,0 +1,27 @@
import { applyAsksBulk, previewAsksBulk } from "../../../actions/asks_bulk.ts";
import { good, bad, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "asks_act",
  description:
    "Decide asks (`items`: ask ids, `issue:<id>`): dismiss, decline, ship (final), close (`reason`), mute, replan",
  inputSchema: {
    type: "object",
    properties: {
      action: { type: "string", enum: ["dismiss", "decline", "mute", "ship", "close", "replan"] },
      items: { type: "array", items: { type: "string" }, maxItems: 100 },
      reason: { type: "string", maxLength: 300 },
      dryRun: { type: "boolean", description: "false to apply" },
    },
    required: ["action", "items"],
  },
  writes: true,
  dryByDefault: true,
  async run(ctx, user, args) {
    const answer =
      args["dryRun"] === false
        ? await applyAsksBulk(ctx.app, user, args["action"], args["items"], args["reason"])
        : previewAsksBulk(ctx.app, user, args["action"], args["items"], args["reason"]);
    return answer.ok ? good(answer.value) : bad(answer.error.code, answer.error.message);
  },
};
@@ -0,0 +1,18 @@
import { decideAsk } from "../../../actions/asks_decide.ts";
import { good, bad, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "asks_decide",
  description:
    "Let the decider answer a hand-over (`item`: `parked:<id>`); only a sure set_aside (70%+) clears it.",
  inputSchema: {
    type: "object",
    properties: { item: { type: "string", maxLength: 80 } },
    required: ["item"],
  },
  writes: true,
  async run(ctx, user, args) {
    const done = await decideAsk(ctx.app, user, args["item"]);
    return done.ok ? good(done.value) : bad(done.error.code, done.error.message);
  },
};
@@ -0,0 +1,24 @@
import { actOnProposal, isProposalVerb, PROPOSAL_VERBS } from "../../../actions/proposals.ts";
import { good, bad, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "asks_proposal",
  description:
    "Act on a wave proposal (`asks` row): `approve`, `redirect` (`words`), `later` (`again`). Owner.",
  inputSchema: {
    type: "object",
    properties: {
      id: { type: "string", maxLength: 80 },
      verb: { type: "string", enum: [...PROPOSAL_VERBS] },
      words: { type: "string", maxLength: 65536 },
    },
    required: ["id", "verb"],
  },
  writes: true,
  run(ctx, user, args) {
    const verb = args["verb"];
    if (!isProposalVerb(verb)) return bad("invalid", `verb is ${PROPOSAL_VERBS.join(", ")}`);
    const done = actOnProposal(ctx.app, user, verb, args["id"], args["words"]);
    return done.ok ? good(done.value ?? { ok: true }) : bad(done.error.code, done.error.message);
  },
};
@@ -0,0 +1,18 @@
import { undoDecideAsk } from "../../../actions/asks_decide.ts";
import { good, bad, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "asks_undecide",
  description:
    "Put a card the decider set aside back on your board, within a day. `id` is from `asks_decide`.",
  inputSchema: {
    type: "object",
    properties: { id: { type: "string", maxLength: 80 } },
    required: ["id"],
  },
  writes: true,
  run(ctx, user, args) {
    const done = undoDecideAsk(ctx.app, user, args["id"]);
    return done.ok ? good(done.value) : bad(done.error.code, done.error.message);
  },
};
@@ -0,0 +1,30 @@
import { mayView } from "../../../core/sealed.ts";
import { listAssignedTo } from "../../../core/issues.ts";
import { canRead, getReposByIds } from "../../../core/repos.ts";
import { good, bad, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "assigned",
  doc: "`{ limit? }`: the open issues and pulls assigned to you in every repository you can still read (repository, number, title, kind, state), as `GET /api/v1/user/assigned`",
  description: "Open issues and pulls assigned to you.",
  inputSchema: {
    type: "object",
    properties: { limit: { type: "integer", minimum: 1, maximum: 50 } },
  },
  writes: false,
  run(ctx, user, args) {
    const limit = args["limit"] ?? 50;
    if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1 || limit > 50)
      return bad("invalid", "`limit` is a whole number from 1 to 50");
    const db = ctx.app.db;
    const issues = listAssignedTo(db, user.id, limit);
    const repos = getReposByIds(db, issues.map((i) => i.repoId));
    const items = [];
    for (const issue of issues) {
      const repo = repos.get(issue.repoId);
      if (!repo || !canRead(db, repo, user) || !mayView(db, repo, issue, user)) continue;
      items.push({ ...issue, repo: { owner: repo.ownerName, name: repo.name } });
    }
    return good({ items, next_cursor: null });
  },
};
@@ -0,0 +1,59 @@
import { attachLook } from "../../../actions/attach_look.ts";
import { lookUrl } from "../../../core/looks.ts";
import { getPull } from "../../../core/pulls.ts";
import { good, attachWords, bad, type Tool, str, APP_ARG, planRepo, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "attach_look",
  description:
    "Attach a PNG or JPEG (base64 `image`, max 5 MB) to an open pull: `phone` or `desktop`, `says`.",
  inputSchema: {
    type: "object",
    properties: {
      app: APP_ARG,
      pull: { type: "integer" },
      width: { type: "string", enum: ["phone", "desktop"] },
      says: {
        type: "string",
      },
      image: { type: "string" },
      dryRun: {
        type: "boolean",
        description: "false to apply",
      },
    },
    required: ["app", "pull", "width", "says", "image"],
  },
  writes: true,
  dryByDefault: true,
  run(ctx, user, args) {
    const repo = planRepo(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const n = args["pull"];
    const pull =
      typeof n === "number" && Number.isInteger(n) && n > 0
        ? getPull(ctx.app.db, repo.id, n)
        : undefined;
    if (pull === undefined)
      return bad("no_such_pull", `no pull #${String(n)}`);
    const input = {
      width: str(args["width"]),
      note: str(args["says"]),
      image: typeof args["image"] === "string" ? args["image"] : "",
    };
    const name = `${repo.ownerName}/${repo.name}#${pull.number}`;
    const dry = args["dryRun"] !== false;
    const attached = attachLook(ctx.app, user, repo, pull, input, dry);
    if (!attached.ok) return bad(attached.error, attachWords(attached.error));
    if (dry)
      return good({
        says: `Would attach a ${input.width} look to ${name}. Nothing changed; send dryRun: false to do it.`,
        dryRun: true,
      });
    return good({
      says: `Attached a ${input.width} look to ${name}.`,
      url: lookUrl(`/${repo.ownerName}/${repo.name}`, attached.value),
      dryRun: false,
    });
  },
};
@@ -0,0 +1,53 @@
import { audit } from "../../../contract/audit.ts";
import { appsOf } from "../../../web/studio/asks.ts";
import { good, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "audit",
  doc: "who can do what, per app, read from its contract.json in git: yes, own or no per door, and whether outsiders may direct its crew (`crewOutsiders`)",
  description:
    "Who can do what in every app you can see, from each contract.json: resource × verb, yes, own or no.",
  inputSchema: {
    type: "object",
    properties: {
      repo: {
        ...REPO_ARG,
        description:
          "owner/name; all when absent.",
      },
    },
  },
  writes: false,
  async run(ctx, user, args) {
    const one =
      typeof args["repo"] === "string" ? repoArg(ctx, user, args) : undefined;
    if (one !== undefined && isAnswer(one)) return one;
    const repos = one === undefined ? appsOf(ctx, user).repos : [one];
    const audited = await Promise.all(
      repos.map((repo) => audit(ctx.app.reposRoot, repo)),
    );
    return good(
      audited.map((a) => ({
        app: `${a.repo.ownerName}/${a.repo.name}`,
        commit: a.oid ?? null,
        // Who may direct the crew is part of who can do what here.
        crewOutsiders: a.repo.crewOutsiders,
        standing: a.standing.kind,
        ...(a.standing.kind === "unsound"
          ? { problems: a.standing.problems }
          : a.standing.kind === "sound"
            ? {
                identities: a.standing.identities,
                open: a.standing.open.map((c) => `${c.resource}.${c.verb}`),
                cells: a.standing.cells.map((c) => ({
                  resource: c.resource,
                  verb: c.verb,
                  as: c.as,
                  answer: c.answer,
                })),
              }
            : {}),
      })),
    );
  },
};
@@ -0,0 +1,20 @@
import { deleteBoard } from "../../../actions/boards.ts";
import { good, type Tool, str, boardRefused, mayBoards, boardFailed } from "../shared.ts";
export const tool: Tool = {
  name: "board_delete",
  doc: "`{ slug }` (person admins): delete a board by slug; its history keeps it",
  description:
    "Delete a board by slug (history keeps it). Person admins only.",
  inputSchema: {
    type: "object",
    properties: { slug: { type: "string", maxLength: 40 } },
    required: ["slug"],
  },
  writes: true,
  async run(ctx, user, args) {
    if (!mayBoards(user)) return boardRefused();
    const done = await deleteBoard(ctx.app, user, str(args["slug"]));
    return done.ok ? good({ deleted: str(args["slug"]) }) : boardFailed(done.error);
  },
};
@@ -0,0 +1,35 @@
import { listPinned as listPinnedPanels, movePinned, pinPanel, unpinPanel } from "../../../actions/board-pins.ts";
import { good, bad, type Tool, boardRefused, mayBoards } from "../shared.ts";
export const tool: Tool = {
  name: "board_pins",
  doc: "`{ op?, slug?, title?, by? }` (person admins): without `op`, the panels pinned to your home (`slug`, `title`); `pin` or `unpin` a panel by board `slug` and panel `title`, or `move` it up or down with `by` (-1 or 1)",
  description:
    "The panels pinned to the caller's home (person admins). No `op` lists them.",
  inputSchema: {
    type: "object",
    properties: {
      op: { type: "string", enum: ["pin", "unpin", "move"] },
      slug: { type: "string", maxLength: 40 },
      title: { type: "string", maxLength: 80 },
      by: { type: "integer", enum: [-1, 1] },
    },
  },
  writes: true,
  async run(ctx, user, args) {
    if (!mayBoards(user)) return boardRefused();
    const op = args["op"];
    if (op === undefined) {
      const listed = await listPinnedPanels(ctx.app, user);
      return listed.ok ? good({ pins: listed.value.map((p) => ({ slug: p.slug, title: p.title })) }) : boardRefused();
    }
    const [slug, title] = [args["slug"], args["title"]];
    const done =
      op === "pin" ? await pinPanel(ctx.app, user, slug, title)
      : op === "unpin" ? unpinPanel(ctx.app, user, slug, title)
      : op === "move" ? movePinned(ctx.app, user, slug, title, args["by"])
      : undefined;
    if (!done) return bad("invalid", "op must be pin, unpin or move");
    return done.ok ? good({ ...done.value }) : bad(done.error, "that could not be pinned");
  },
};
@@ -0,0 +1,23 @@
import { writeBoard } from "../../../actions/boards.ts";
import { good, type Tool, str, boardRefused, mayBoards, boardFailed } from "../shared.ts";
export const tool: Tool = {
  name: "board_write",
  doc: "`{ slug, board }` (person admins): write a whole board under a slug, made or replaced: `{ title, range, refresh, panels: [{ title, chart, query, w, h }] }`",
  description:
    "Write a whole board under a slug: {title, range, refresh, panels: [{title, chart, query, w, h}]}.",
  inputSchema: {
    type: "object",
    properties: {
      slug: { type: "string", maxLength: 40 },
      board: { type: "object" },
    },
    required: ["slug", "board"],
  },
  writes: true,
  async run(ctx, user, args) {
    if (!mayBoards(user)) return boardRefused();
    const done = await writeBoard(ctx.app, user, str(args["slug"]), args["board"]);
    return done.ok ? good({ slug: str(args["slug"]), ...done.value }) : boardFailed(done.error);
  },
};
@@ -0,0 +1,47 @@
import { listAllBoards, showBoard } from "../../../actions/boards.ts";
import { panelData, parseWindow } from "../../../boards/panel_data.ts";
import { good, bad, type Tool, str, boardRefused, mayBoards, boardFailed } from "../shared.ts";
export const tool: Tool = {
  name: "boards",
  doc: "`{ slug?, panel?, from?, to?, step? }` (person admins): without `slug`, lists the forge's boards (slug, title, range, refresh, panels); with `slug`, that board; with `panel` (place from 0, up to 23), that panel's data over the `from`/`to` window and `step`",
  description:
    "The forge's boards for person admins: slug, title, range, refresh and panels.",
  inputSchema: {
    type: "object",
    properties: {
      slug: { type: "string", maxLength: 40 },
      panel: { type: "integer", minimum: 0, maximum: 23, description: "One panel, from 0." },
      from: { type: "string", maxLength: 64 },
      to: { type: "string", maxLength: 64 },
      step: { type: "string", maxLength: 16, description: "With panel: seconds per bucket, or 5m." },
    },
  },
  writes: false,
  async run(ctx, user, args) {
    if (!mayBoards(user)) return boardRefused();
    if (args["slug"] === undefined) {
      const listed = await listAllBoards(ctx.app, user);
      return listed.ok
        ? good({ boards: listed.value.map((b) => ({ slug: b.slug, ...b.board })) })
        : boardFailed(listed.error);
    }
    const shown = await showBoard(ctx.app, user, str(args["slug"]));
    if (!shown.ok) return boardFailed(shown.error);
    if (args["panel"] === undefined) return good({ slug: str(args["slug"]), ...shown.value });
    const index = args["panel"];
    const panel = typeof index === "number" && Number.isInteger(index) ? shown.value.panels[index] : undefined;
    if (!panel) return bad("not_found", "that board has no panel there");
    const asked = new URLSearchParams();
    for (const k of ["from", "to", "step"]) {
      const v = args[k];
      if (v !== undefined) asked.set(k, typeof v === "number" ? String(v) : str(v));
    }
    const window = parseWindow(asked);
    if (!window.ok) return bad("invalid_window", window.error);
    const data = panelData(ctx.app.db, shown.value, panel, window.window);
    if (!data.ok) return bad("bad_query", data.error);
    const { ok: _, ...out } = data;
    return good({ board: str(args["slug"]), panel: index, title: panel.title, chart: panel.chart, ...out });
  },
};
@@ -0,0 +1,89 @@
import { createBranch, deleteBranch } from "../../../actions/branches.ts";
import { listBranches } from "../../../git/branches.ts";
import { listRefs } from "../../../git/read.ts";
import { repoDir } from "../../../git/repos.ts";
import { runGit } from "../../../git/env.ts";
import { CREATE_ERRORS, DELETE_ERRORS } from "../../../web/pages/branches.ts";
import { BRANCH_NOT_CREATED, BRANCH_NOT_DELETED } from "../../../actions/branch_words.ts";
import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "branches",
  doc: "`{ repo, name?, action?, from?, kind? }`: without `name`, lists the branches; `kind: \"tags\"` lists the tags instead (as GET `/api/v1/repos/:owner/:name/tags` does, newest first; no `name` or `action`); with `name` and `action` (`create` from `from`, or `delete`) it does what the branches page does: the default branch is never deleted, only a writer may act",
  description:
    "A repository's branches; `name` and `action` create (from `from`) or delete one, not the default.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      name: { type: "string", maxLength: 255 },
      action: { type: "string", enum: ["create", "delete"] },
      from: { type: "string", maxLength: 255 },
      kind: { type: "string", enum: ["branches", "tags"], description: "tags: newest first" },
    },
    required: ["repo"],
  },
  writes: true,
  readsWithout: "name",
  async run(ctx, user, args) {
    const kind = args["kind"] ?? "branches";
    if (kind !== "branches" && kind !== "tags") return bad("invalid", "`kind` is branches or tags");
    if (kind === "tags" && (args["name"] !== undefined || args["action"] !== undefined))
      return bad("invalid", "`kind: tags` only lists; leave out `name` and `action`");
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    if (kind === "tags") {
      const dir = repoDir(ctx.app.reposRoot, repo.ownerName, repo.name);
      const refs = await listRefs(dir, "refs/tags/");
      if (!refs.ok) return good({ tags: [] });
      const order = await runGit(
        ["for-each-ref", "--sort=-creatordate", "--format=%(refname)", "--", "refs/tags/"],
        { cwd: dir },
      );
      const rank = new Map((order.ok ? order.value.split("\n") : []).map((n, i) => [n, i]));
      refs.value.sort((a, b) => (rank.get(a.name) ?? 0) - (rank.get(b.name) ?? 0));
      return good({
        tags: refs.value.map((r) => ({
          name: r.name.replace("refs/tags/", ""),
          oid: r.oid,
          commit: r.peeled ?? r.oid,
        })),
      });
    }
    const base = `/${repo.ownerName}/${repo.name}/branches`;
    if (args["name"] === undefined) {
      const listed = await listBranches(
        repoDir(ctx.app.reposRoot, repo.ownerName, repo.name),
        repo.defaultBranch,
      );
      return good({
        branches: listed.ok
          ? listed.value.branches.map((b) => ({ name: b.name, default: b.isDefault, ahead: b.ahead, behind: b.behind }))
          : [],
        url: base,
      });
    }
    const name = args["name"];
    const action = args["action"];
    const from = args["from"];
    if (typeof name !== "string" || name.length > 255)
      return bad("invalid", "`name` is a branch name");
    if (action !== "create" && action !== "delete")
      return bad("invalid", "`action` is create or delete");
    if (from !== undefined && (typeof from !== "string" || from.length > 255))
      return bad("invalid", "`from` is a branch, tag or commit");
    if (action === "create") {
      const made = await createBranch(ctx.app, user, repo, {
        name,
        ...(from === undefined || from === "" ? {} : { from }),
      });
      if (!made.ok)
        return bad(made.error, CREATE_ERRORS[made.error] ?? BRANCH_NOT_CREATED);
      return good({ says: `Created ${made.value.name} at ${made.value.oid.slice(0, 7)}.`, url: base });
    }
    const gone = await deleteBranch(ctx.app, user, repo, name);
    if (!gone.ok)
      return bad(gone.error, DELETE_ERRORS[gone.error] ?? BRANCH_NOT_DELETED);
    return good({ says: `Deleted ${gone.value.name}.`, url: base });
  },
};
@@ -0,0 +1,43 @@
import { changeCapacity, listCapacity } from "../../../actions/capacity.ts";
import { scopeAllows } from "../../../core/tokens.ts";
import { good, bad, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "capacity",
  description:
    "The forge's capacity and guards, live. With `key` and `value` (\"\" restores default), plans.",
  inputSchema: {
    type: "object",
    properties: {
      key: {
        type: "string",
        enum: ["crew.concurrency", "checks.concurrency", "checks.shards", "cells.egress", "guard_new_accounts", "signin.edge"],
      },
      value: { type: "string", maxLength: 16 },
      dryRun: { type: "boolean", description: "false to apply" },
    },
  },
  writes: true,
  dryByDefault: true,
  run(ctx, user, args) {
    const listed = listCapacity(ctx.app, user);
    if (!listed.ok) return bad("not_found", "no such tool here");
    const key = typeof args["key"] === "string" ? args["key"] : undefined;
    if (key === undefined) return good(listed.value);
    const value = typeof args["value"] === "string" ? args["value"] : "";
    const now = listed.value.settings.find((s) => s.key === key);
    if (now === undefined) return bad("no_such_setting", `no capacity setting ${key}`);
    if (args["dryRun"] !== false)
      return good({
        says: `Would set ${key} from ${now.value || "auto"} to ${value || "its default"}. Send dryRun: false to change it.`,
      });
    if (!scopeAllows(ctx.auth.scope ?? "ro", "admin"))
      return bad("forbidden", "changing the forge's capacity needs an admin-scope token");
    const changed = changeCapacity(ctx.app, user, key, value);
    if (!changed.ok) return bad(changed.error, "that value is outside what this setting takes");
    return good({
      says: `${key}: ${changed.value.from || "auto"} → ${changed.value.to || "auto"}, from the next pick on.`,
      ...changed.value,
    });
  },
};
@@ -0,0 +1,26 @@
import { reissueDoor } from "../../../spawn/door.ts";
import { good, bad, type Tool, str, REVEAL_ARG, LINK_KEPT, LINK_REVEALED } from "../shared.ts";
export const tool: Tool = {
  name: "claim_link",
  doc: "`{ name }`: a new claim link for a child you spawned that nobody has claimed; the old one stops working. An admin's",
  description:
    "A new claim link for an unclaimed child forge, only with `reveal: true`; the old one stops at once.",
  inputSchema: {
    type: "object",
    properties: {
      name: { type: "string" },
      reveal: REVEAL_ARG,
    },
    required: ["name"],
  },
  writes: true,
  async run(ctx, user, args) {
    if (args["reveal"] !== true)
      return good({ says: `Nothing changed. ${LINK_KEPT}`, reissued: false });
    const door = await reissueDoor(ctx, user, str(args["name"]));
    if (door.status >= 400)
      return bad(String(door.body["error"]), String(door.body["message"]));
    return good({ says: LINK_REVEALED, ...door.body });
  },
};
@@ -0,0 +1,53 @@
import { closingFrom, setIssueStateThrough } from "../../../actions/issues.ts";
import { CLOSE_REASONS } from "../../../core/issues.ts";
import { good, bad, type Tool, REPO_ARG, repoArg, issueArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "close",
  doc: "`{ repo, number, state?, reason?, into? }`: close an issue or a pull (`state` closed by default) or reopen it (`open`); the same rules and refusals as `PATCH …/issues/:number`: an agent closes only what the rules give it and reopens nothing; answers `state` and `closeReason`",
  description:
    "Close or reopen (`state` open) an issue or pull. `reason`: done, dropped, split (`into`).",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      number: { type: "integer", minimum: 1 },
      state: { type: "string", enum: ["closed", "open"] },
      reason: { type: "string", enum: [...CLOSE_REASONS] },
      into: {
        type: "array",
        items: { type: "integer", minimum: 1 },
        maxItems: 50,
      },
    },
    required: ["repo", "number"],
  },
  writes: true,
  async run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const issue = issueArg(ctx, repo, args, "number");
    if ("ok" in issue) return issue;
    const state = args["state"] ?? "closed";
    if (state !== "closed" && state !== "open")
      return bad("invalid_state", "state is closed or open");
    // The PATCH route's own check of `reason` and `into`.
    const closing = closingFrom(args);
    if (closing === undefined)
      return bad("invalid_reason", "a reason is done, dropped, or split (with `into`: up to 50 issue numbers)");
    const changed = await setIssueStateThrough(ctx.app, user, repo, issue, state, closing);
    if (!changed.ok)
      return bad(
        changed.error,
        changed.error === "forbidden"
          ? "this is not yours to close or reopen"
          : "that state could not be set",
      );
    return good({
      says: `#${issue.number} is ${changed.value.state}.`,
      number: issue.number,
      state: changed.value.state,
      closeReason: changed.value.closeReason,
    });
  },
};
@@ -0,0 +1,61 @@
import { addAccount, allowWrite, auditAccount, removeAccount, renameAccount, reverify, rotateAccount } from "../../../actions/cloud.ts";
import { PROVIDERS } from "../../../cloud/providers.ts";
import { scopeAllows } from "../../../core/tokens.ts";
import { good, bad, type Tool, str } from "../shared.ts";
export const tool: Tool = {
  name: "cloud_account",
  doc: "`{ verb, provider, name, value?, to?, allowed?, repo? }`: change a cloud account: `attach` or `rotate` a token (`value`), `verify` it, `rename` it (`to`), `remove` it, `allow_writes` (`allowed` true or false) or `audit` (`repo` owner/name); a forge admin with an admin-scope token; answers a one-line `says`",
  description:
    "Change a cloud account (admin token) by `verb`.",
  inputSchema: {
    type: "object",
    properties: {
      verb: { type: "string", enum: ["attach", "verify", "rotate", "rename", "remove", "allow_writes", "audit"] },
      provider: { type: "string", enum: [...PROVIDERS] },
      name: { type: "string", maxLength: 32 },
      value: { type: "string", maxLength: 4096, description: "For attach, rotate." },
      to: { type: "string", maxLength: 32 },
      allowed: { type: "boolean", description: "For allow_writes." },
      repo: { type: "string", maxLength: 200, description: "For audit." },
    },
    required: ["verb", "provider", "name"],
  },
  writes: true,
  async run(ctx, user, args) {
    if (!user.isAdmin) return bad("not_found", "no such tool here");
    if (!scopeAllows(ctx.auth.scope ?? "ro", "admin"))
      return bad("forbidden", "changing cloud accounts needs an admin-scope token");
    const verb = str(args["verb"]);
    const [provider, name] = [str(args["provider"]), str(args["name"])];
    const value = str(args["value"]);
    if (str(args["verb"]) === "allow_writes" && typeof args["allowed"] !== "boolean")
      return bad("bad_args", "allow_writes needs allowed: true or false");
    const done =
      verb === "attach"
        ? await addAccount(ctx.app, user, provider, name, value)
        : verb === "rotate"
          ? await rotateAccount(ctx.app, user, provider, name, value)
          : verb === "verify"
            ? await reverify(ctx.app, user, provider, name)
            : verb === "rename"
              ? renameAccount(ctx.app, user, provider, name, str(args["to"]))
              : verb === "remove"
                ? removeAccount(ctx.app, user, provider, name)
                : verb === "allow_writes"
                  ? allowWrite(ctx.app, user, provider, name, args["allowed"] === true)
                  : verb === "audit"
                    ? await auditAccount(ctx.app, user, provider, name, str(args["repo"]))
                    : undefined;
    if (done === undefined) return bad("bad_verb", "verb is attach, verify, rotate, rename, remove, allow_writes or audit");
    if (!done.ok) return bad("refused", done.error);
    const v = done.value as unknown;
    const said =
      typeof v === "string"
        ? v
        : verb === "audit"
          ? `${(v as { opened: number }).opened} issue(s) opened, ${(v as { found: number }).found} found`
          : "done";
    return good({ says: `${verb} ${provider}/${name}: ${said}.` });
  },
};
@@ -0,0 +1,21 @@
import { usesByVendor, type VendorUse } from "../../../cloud/declared.ts";
import { cloudOverview } from "../../../cloud/overview.ts";
import { good, bad, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "cloud_accounts",
  doc: "the forge's cloud accounts, each attached provider token with its use, verification, write permission and today's calls; a forge admin only (counted as a write so a `ro` token never lists them)",
  description:
    "Cloud accounts (forge admin): each provider token's use, verification, write permission, calls today.",
  inputSchema: { type: "object", properties: {} },
  // A read, but marked a write so a `ro` token never lists the accounts; it
  // is a forge admin's and the audit rows name every vendor call.
  writes: true,
  async run(ctx, user) {
    if (!user.isAdmin) return bad("not_found", "no such tool here");
    const uses = await usesByVendor(ctx.app.db, ctx.app.reposRoot, user).catch(() => new Map<string, VendorUse[]>());
    const seen = cloudOverview(ctx.app, user, uses);
    if (!seen.ok) return bad("not_found", "no such tool here");
    return good(seen.value);
  },
};
@@ -0,0 +1,54 @@
import { commitLog } from "../../../git/read.ts";
import { diffCommit } from "../../../git/diff.ts";
import { repoDir } from "../../../git/repos.ts";
import { isSafeRef } from "../../../git/guard.ts";
import { checkOfCommit } from "../../../actions/runs.ts";
import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "commits",
  doc: "`{ repo, ref?, limit?, oid? }`: a branch's recent commits, newest first (`limit` 1–100, default 30; refused outside that, where REST clamps), as `GET …/commits` answers; with `oid` (4–64 hex) one commit with its diff and its check, as `GET …/commits/{oid}` and `…/check` answer",
  description:
    "Recent commits; `oid`: one commit, diff and check.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      ref: { type: "string", maxLength: 255, description: "Branch, tag or commit." },
      limit: { type: "integer", minimum: 1, maximum: 100 },
      oid: { type: "string", minLength: 4, maxLength: 64, },
    },
    required: ["repo"],
  },
  writes: false,
  async run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const oid = args["oid"];
    if (oid !== undefined) {
      if (typeof oid !== "string" || !/^[0-9a-fA-F]{4,64}$/.test(oid))
        return bad("invalid", "`oid` is 4 to 64 hex digits");
      const dir = repoDir(ctx.app.reposRoot, repo.ownerName, repo.name);
      const log = await commitLog(dir, oid, { limit: 1 });
      const commit = log.ok ? log.value[0] : undefined;
      if (!commit) return bad("not_found", "no such commit");
      const diff = await diffCommit(dir, commit.oid);
      const check = await checkOfCommit(ctx.app, user, repo, commit.oid);
      const files = diff.ok ? diff.value : { files: [], additions: 0, deletions: 0 };
      return good({
        says: `${commit.oid.slice(0, 7)} ${commit.subject}: ${files.files.length} file(s) changed.`,
        ...commit,
        diff: files,
        check: check.ok ? check.value : null,
      });
    }
    const ref = args["ref"] ?? repo.defaultBranch;
    if (typeof ref !== "string" || ref.length > 255 || !isSafeRef(ref))
      return bad("invalid", "`ref` is a branch, tag or commit");
    const limit = args["limit"] ?? 30;
    if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1 || limit > 100)
      return bad("invalid", "`limit` is a whole number from 1 to 100");
    const log = await commitLog(repoDir(ctx.app.reposRoot, repo.ownerName, repo.name), ref, { limit });
    return good({ commits: log.ok ? log.value : [] });
  },
};
@@ -0,0 +1,37 @@
import { confirmIssue } from "../../../actions/dependencies.ts";
import { good, bad, type Tool, APP_ARG, planRepo, issueArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "confirm_wait",
  doc: "`{ app, issue, blocker }`: a person says `issue` may go ahead although `blocker` closed as dropped or split; the API's confirm action, so writers only and never the crew",
  description:
    "Let an issue go ahead though its blocker closed dropped or split.",
  inputSchema: {
    type: "object",
    properties: {
      app: APP_ARG,
      issue: { type: "integer" },
      blocker: { type: "integer" },
    },
    required: ["app", "issue", "blocker"],
  },
  writes: true,
  run(ctx, user, args) {
    const repo = planRepo(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const issue = issueArg(ctx, repo, args, "issue");
    if ("ok" in issue) return issue;
    const blocker = issueArg(ctx, repo, args, "blocker");
    if ("ok" in blocker) return blocker;
    const done = confirmIssue(ctx.app, user, repo, issue, blocker);
    if (!done.ok)
      return bad(
        done.error,
        "You need write access, and not a place on the crew, to confirm a wait.",
      );
    return good({
      says: `#${issue.number} may go ahead without #${blocker.number}.`,
      url: `${ctx.url.origin}/${repo.ownerName}/${repo.name}/issues/${issue.number}`,
    });
  },
};
@@ -0,0 +1,12 @@
import { welcome } from "../../../system/telemetry.ts";
import { good, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "contribute",
  doc: "for any arriving agent: what this forge is, its bottleneck, open “help wanted” issues, how to propose",
  description:
    "For an arriving agent: what this forge is, its bottleneck, “help wanted” issues, how to propose.",
  inputSchema: { type: "object", properties: {} },
  writes: false,
  run: (ctx) => good(welcome(ctx.app)),
};
@@ -0,0 +1,34 @@
import { NOT_A_MEMBER } from "../../../core/roles.ts";
import { ARCHIVED_WHY, forkParentFor } from "../../../core/repos.ts";
import { convergeFork } from "../../../crew/converge.ts";
import { DIRECTION_NOTE } from "../../../crew/direct.ts";
import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "converge",
  doc: "the fork's crew merges where both sides changed the same files; comes back as a pull",
  description:
    "Have a fork's crew merge the parent's updates where both changed the same files, as a pull.",
  inputSchema: {
    type: "object",
    properties: { repo: REPO_ARG },
    required: ["repo"],
  },
  writes: true,
  async run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const parent = forkParentFor(ctx.app.db, repo, user);
    if (parent === undefined)
      return bad("not_a_fork", "this repository follows nothing");
    const outcome = await convergeFork(ctx.app, repo, parent, user);
    if (outcome.kind === "forbidden") return bad("forbidden", DIRECTION_NOTE);
    if (outcome.kind === "not_member") return bad("not_member", NOT_A_MEMBER);
    if (outcome.kind === "archived") return bad("archived", ARCHIVED_WHY);
    return good({
      kind: outcome.kind,
      issue: "issue" in outcome ? outcome.issue.number : null,
      pull: "pull" in outcome ? outcome.pull.number : null,
    });
  },
};
@@ -0,0 +1,45 @@
import { isDecisionsBy } from "../../../core/repos.ts";
import { scopeAllows } from "../../../core/tokens.ts";
import { setDecisionsBy } from "../../../actions/repos.ts";
import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "decisions_by",
  doc: "`{ repo, by?, dryRun? }`: the standing rule for a repository's hand-overs (`me`, `decider`, `decider_tell`); with `by`, planned first (`dryRun` is true unless `false`); set only by the app's admin with an admin token, never an agent",
  description:
    "Who decides a repository's parked hand-over cards: `me`, `decider`, `decider_tell`. No `by` reads it.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      by: { type: "string", enum: ["me", "decider", "decider_tell"] },
      dryRun: {
        type: "boolean",
        description: "false to apply",
      },
    },
    required: ["repo"],
  },
  writes: true,
  dryByDefault: true,
  async run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const by = args["by"];
    if (by === undefined) return good({ by: repo.decisionsBy });
    if (!isDecisionsBy(by))
      return bad("bad_action", "`by` is me, decider or decider_tell");
    const dryRun = args["dryRun"] !== false;
    if (!dryRun && !scopeAllows(ctx.auth.scope ?? "ro", "admin"))
      return bad("forbidden", "setting the standing rule needs an admin token");
    const set = await setDecisionsBy(ctx.app, user, repo, by, dryRun);
    if (!set.ok)
      return bad("forbidden", "only an admin of this app sets its standing rule");
    return good({
      ...set.value,
      says: dryRun
        ? `This is the plan; nothing changed. Decisions go by "${set.value.was}" now; send dryRun: false to make it "${set.value.by}".`
        : `Decisions here now go by "${set.value.by}".`,
    });
  },
};
@@ -0,0 +1,48 @@
import { editIssue, TAKEN_UP } from "../../../actions/issues.ts";
import { good, bad, type Tool, REPO_ARG, repoArg, issueArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "edit",
  doc: "a new title or body for an issue or a pull: its author's, or a writer's; an agent edits only what it wrote",
  description:
    "Retitle or rewrite an issue or pull: yours, or any where you write; an agent edits only its own.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      number: { type: "integer", minimum: 1 },
      title: { type: "string", maxLength: 256 },
      body: { type: "string", maxLength: 65536 },
    },
    required: ["repo", "number"],
  },
  writes: true,
  run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    // The same door the plan tools use for an issue by number, so what
    // it comes to refuse (a sealed one, say) is refused here too.
    const issue = issueArg(ctx, repo, args, "number");
    if ("ok" in issue) return issue;
    const edited = editIssue(ctx.app, user, repo, issue, {
      title: typeof args["title"] === "string" ? args["title"] : undefined,
      body: typeof args["body"] === "string" ? args["body"] : undefined,
    });
    if (!edited.ok)
      return bad(
        edited.error,
        edited.error === "forbidden"
          ? "only the author, or a person who writes here, edits this"
          : edited.error === "taken_up"
            ? TAKEN_UP
            : edited.error === "nothing_to_change"
            ? "send a title, a body, or both"
            : "that could not be changed",
      );
    return good({
      says: `Edited #${issue.number}: ${edited.value.title}`,
      number: issue.number,
      title: edited.value.title,
    });
  },
};
@@ -0,0 +1,51 @@
import { scopeAllows } from "../../../core/tokens.ts";
import { egressView, grantAppEgress, revokeAppEgress } from "../../../actions/egress_grants.ts";
import { FORBIDDEN_MESSAGE } from "../../respond.ts";
import { type Answer, good, bad, type Tool, str, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "egress_grants",
  doc: "`{ repo, op?, destination? }`: the private `host:port` destinations an app's forge.json asks for and which are granted; `op` grant or revoke by a site admin (never an agent), and every op needs an admin-scope token; the same as the settings page and `/api/v1/repos/:owner/:name/egress-grants`",
  description:
    "An app's private destinations and their grants: list, grant or revoke (site admin). See docs/MCP.md.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      op: { type: "string", enum: ["list", "grant", "revoke"] },
      destination: { type: "string" },
    },
    required: ["repo"],
  },
  writes: true,
  readsWithout: "op",
  async run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const op = args["op"] === undefined ? "list" : str(args["op"]);
    if (op !== "list" && op !== "grant" && op !== "revoke")
      return bad("invalid", "op is list, grant or revoke");
    // The API's rule: reading or changing grants takes an admin-scope token.
    if (!scopeAllows(ctx.auth.scope ?? "ro", "admin"))
      return bad("forbidden", "egress grants need an admin-scope token");
    const refused = (error: string): Answer => {
      if (error === "not_found")
        return bad("not_found", "no such app or repository (owner/name)");
      if (error === "forbidden") return bad("forbidden", FORBIDDEN_MESSAGE);
      return bad(error, error);
    };
    if (op === "list") {
      const view = await egressView(ctx.app, user, repo);
      return view.ok
        ? good({ items: view.value.rows, changes: view.value.changes })
        : refused(view.error);
    }
    const destination = str(args["destination"]);
    if (op === "grant") {
      const granted = await grantAppEgress(ctx.app, user, repo, destination);
      return granted.ok ? good(granted.value) : refused(granted.error);
    }
    const revoked = revokeAppEgress(ctx.app, user, repo, destination);
    return revoked.ok ? good({ revoked: revoked.value }) : refused(revoked.error);
  },
};
@@ -0,0 +1,27 @@
import { resendVerification } from "../../../actions/verify.ts";
import { CAPPED_WORDS } from "../../../actions/mail.ts";
import { VERIFY_WORDS } from "../../../actions/verify_words.ts";
import { good, bad, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "email_verify",
  doc: "no input: send the caller a new verification email, with the API's rate limit and errors; the answer never carries the link",
  description: "Send yourself a new verification link.",
  inputSchema: { type: "object", properties: {} },
  writes: true,
  async run(ctx, user) {
    const sent = await resendVerification(ctx.app, user);
    if (sent.ok)
      return good({
        outcome: sent.value,
        says: sent.value === "sent" ? "A new verification email is on its way." : "Your email is already verified.",
      });
    if (sent.error === "too_soon")
      return bad("too_soon", VERIFY_WORDS.too_soon);
    if (sent.error === "no_mail")
      return bad("no_mail", VERIFY_WORDS.no_mail);
    if (sent.error === "capped") return bad("capped", CAPPED_WORDS);
    if (sent.error === "unauthorized") return bad("unauthorized", "sign in first");
    return bad("failed", VERIFY_WORDS.failed);
  },
};
@@ -0,0 +1,28 @@
import { EVENTS_LIMIT_MAX, eventsLimit, eventsPage, validEventsCursor } from "../../../core/events_page.ts";
import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "events",
  doc: "`{ repo, limit?, cursor? }`: the repository's events, newest first, as you may see them (a webhook's URL and an app's variable names are the admins'): `{ items, next_cursor }`, `limit` 1 to 200 (default 50), `cursor` from `next_cursor`",
  description: "Repository events.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      limit: { type: "integer" },
      cursor: { type: "string" },
    },
    required: ["repo"],
  },
  writes: false,
  run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const limit = eventsLimit(args["limit"]);
    if (limit === undefined) return bad("invalid", `limit is 1 to ${EVENTS_LIMIT_MAX}`);
    const given = args["cursor"];
    if (given !== undefined && (typeof given !== "string" || !validEventsCursor(given)))
      return bad("invalid", "that cursor was not issued here");
    return good(eventsPage(ctx.app.db, repo.id, user, limit, given));
  },
};
@@ -0,0 +1,27 @@
import { explore, exploreLine, parseExploreQuery } from "../../../actions/explore.ts";
import { good, type Tool, str } from "../shared.ts";
export const tool: Tool = {
  name: "explore",
  doc: "`{ query? }`: the apps and people you can see, ranked by forks, ships, use and freshness, with their numbers; `kind:` `sort:` and words in one line",
  description:
    "The apps, people (and for a site admin, spawned forges) you can see, ranked.",
  inputSchema: {
    type: "object",
    properties: {
      query: {
        type: "string",
        maxLength: 200,
        description: "Words; kind:, sort: filters.",
      },
    },
  },
  writes: false,
  async run(ctx, user, args) {
    const query = parseExploreQuery(str(args["query"]));
    return good({
      query: exploreLine(query),
      items: await explore(ctx.app, user, query),
    });
  },
};
@@ -0,0 +1,14 @@
import { familyView } from "../../../spawn/family.ts";
import { good, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "family",
  doc: "the forge that sent this one and, for a site admin, those it sent, with state and version",
  description:
    "The forge that sent this one and, for a site admin, those it sent, with state and version.",
  inputSchema: { type: "object", properties: {} },
  writes: false,
  async run(ctx, user) {
    return good(await familyView(ctx.app, user.isAdmin === true));
  },
};
@@ -0,0 +1,37 @@
import { FEED_LIMIT_DEFAULT, FEED_LIMIT_MAX, parseCursor, readFeed } from "../../../feed/feed.ts";
import { good, bad, type Tool, CHIP_ARGS, chipArgs, str } from "../shared.ts";
export const tool: Tool = {
  name: "feed",
  doc: "`{ limit?, cursor? }`: your home timeline — tells, replies, runs, changes and looks — ranked, with who, what, why and a link; the same items as `GET /api/v1/feed`",
  description:
    "Your ranked home timeline across visible apps; `cursor` pages; saved filter (`feed_chips`) applies.",
  inputSchema: {
    type: "object",
    properties: {
      limit: { type: "integer", minimum: 1, maximum: FEED_LIMIT_MAX },
      cursor: { type: "string" },
      ...CHIP_ARGS,
    },
  },
  writes: false,
  run(ctx, user, args) {
    const chips = chipArgs(ctx, args);
    if (chips && "error" in chips) return bad("invalid", chips.error);
    const raw = args["limit"];
    const limit = raw === undefined ? FEED_LIMIT_DEFAULT : Number(raw);
    if (!Number.isInteger(limit) || limit < 1 || limit > FEED_LIMIT_MAX)
      return bad("invalid", `limit is 1 to ${FEED_LIMIT_MAX}`);
    const given = args["cursor"];
    const cursor = given === undefined ? undefined : parseCursor(str(given));
    if (given !== undefined && cursor === undefined)
      return bad("invalid", "that cursor was not issued here");
    return good(
      readFeed(ctx.app.db, user, {
        limit,
        ...(chips === undefined ? {} : { chips }),
        ...(cursor === undefined ? {} : { cursor }),
      }),
    );
  },
};
@@ -0,0 +1,42 @@
import { getUserByName, getUsersByIds } from "../../../core/users.ts";
import { chipsOf, isKindChip, setChip } from "../../../core/feed_chips.ts";
import { good, bad, type Tool, str } from "../shared.ts";
export const tool: Tool = {
  name: "feed_chips",
  doc: "`{ kind?, value?, hidden? }`: the feed chips you switched off, which `feed` and `asks` leave out; with `kind` (`kind` or `person`), `value` and `hidden` it switches one off or on",
  description:
    "Feed chips you switched off in `feed` and `asks`. With `kind`, `value` and `hidden`, sets one.",
  inputSchema: {
    type: "object",
    properties: {
      kind: { type: "string", enum: ["kind", "person"] },
      value: { type: "string", maxLength: 100 },
      hidden: { type: "boolean" },
    },
  },
  writes: true,
  readsWithout: "kind",
  run(ctx, user, args) {
    if (args["kind"] !== undefined) {
      const value = str(args["value"]);
      const hidden = args["hidden"];
      if (typeof hidden !== "boolean") return bad("invalid", "hidden is true or false");
      if (args["kind"] === "kind") {
        if (!isKindChip(value)) return bad("invalid", "that kind has no chip");
        setChip(ctx.app.db, user.id, { kind: "kind", value }, hidden);
      } else if (args["kind"] === "person") {
        const who = getUserByName(ctx.app.db, value);
        if (!who || who.kind === "org") return bad("not_found", "no such person");
        setChip(ctx.app.db, user.id, { kind: "person", value: who.id }, hidden);
      } else return bad("invalid", "kind is `kind` or `person`");
    }
    const chips = chipsOf(ctx.app.db, user.id);
    return good({
      kinds: [...chips.kinds].sort(),
      people: [...getUsersByIds(ctx.app.db, [...chips.people]).values()]
        .map((u) => u.username)
        .sort(),
    });
  },
};
@@ -0,0 +1,18 @@
import { noteRead, telemetryReader } from "../../../actions/telemetry.ts";
import { flowFor } from "../../../system/telemetry.ts";
import { good, bad, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "flow",
  description:
    "Pipeline (forge admin): stage counts, `oldestWaiting`, `capacity`, bottleneck, `queue`, `reviewing`.",
  inputSchema: { type: "object", properties: {} },
  writes: false,
  run(ctx, user) {
    const reader = telemetryReader(ctx.app, user);
    if (!reader)
      return bad("forbidden", "only an admin of this forge, or an agent granted telemetry:read, reads its pipeline");
    noteRead(ctx.app, user, reader, "flow");
    return good(flowFor(ctx.app, reader));
  },
};
@@ -0,0 +1,26 @@
import { FOLLOW_MODE_REFUSALS, setFollowMode } from "../../../actions/follow.ts";
import { FOLLOW_MODES } from "../../../spawn/chain.ts";
import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "follow_mode",
  doc: "`{ repo, … }`: choose how a spawned forge follows its parent, `tell-me` or `take-updates`; its `forge` repository's admin only",
  description:
    "How a spawned forge follows its parent: `tell-me` or `take-updates`. Its `forge` repository's admin.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      mode: { type: "string", enum: [...FOLLOW_MODES] },
    },
    required: ["repo", "mode"],
  },
  writes: true,
  async run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const set = await setFollowMode(ctx.app, user, repo, args["mode"]);
    if (set.ok) return good({ says: `Now following in ${set.value} mode.`, mode: set.value });
    return bad(set.error, FOLLOW_MODE_REFUSALS[set.error].message);
  },
};
@@ -0,0 +1,46 @@
import { upstreamPayload } from "../../../spawn/upstream.ts";
import { relationOf } from "../../../actions/forks.ts";
import { chainOfRepo } from "../../../spawn/chain.ts";
import { convergeState } from "../../../crew/converge.ts";
import { parentForgeFor } from "../../../core/parent_releases.ts";
import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "following",
  doc: "where a fork stands against what it follows, and what the crew is doing about it",
  description:
    "Where a fork stands against what it follows: in step, behind, ahead, diverged; files to decide.",
  inputSchema: {
    type: "object",
    properties: { repo: REPO_ARG },
    required: ["repo"],
  },
  writes: false,
  async run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const relation = await relationOf(ctx.app, user, repo);
    const chain = await chainOfRepo(ctx.app, repo);
    if (relation === undefined)
      return chain === undefined
        ? bad("not_a_fork", "this repository follows nothing")
        : good({ chain: chain.lines, severedAt: chain.severedAt, upstream: await upstreamPayload(ctx.app) });
    const converge =
      relation.state === "diverged" && !relation.clean
        ? convergeState(ctx.app, repo, relation.parent)
        : undefined;
    return good({
      chain: chain?.lines ?? null,
      severedAt: chain?.severedAt ?? null,
      upstream: chain === undefined ? null : await upstreamPayload(ctx.app),
      parent: `${relation.parent.ownerName}/${relation.parent.name}`,
      state: relation.state,
      behind: relation.behind,
      ahead: relation.ahead,
      clean: relation.clean,
      conflicts: relation.conflicts,
      parentForge: parentForgeFor(ctx.app.config),
      converge: converge?.kind ?? null,
    });
  },
};
@@ -0,0 +1,21 @@
import { forgeProposalLine, forgeProposals } from "../../../actions/upstream.ts";
import { good, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "forge_proposals",
  doc: "`{ repo }`: what this forge proposed to its parent, newest first; `reachable` is false if the parent did not answer",
  description:
    "What this forge proposed to its parent, newest first; `reachable` false if it did not answer.",
  inputSchema: {
    type: "object",
    properties: { repo: REPO_ARG },
    required: ["repo"],
  },
  writes: false,
  async run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const items = await forgeProposals(ctx.app, repo, Date.now(), true);
    return good({ items: items.map((p) => ({ ...p, says: forgeProposalLine(p) })) });
  },
};
@@ -0,0 +1,23 @@
import { clientRows } from "../../../spawn/clients.ts";
import { good, bad, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "forges",
  doc: "an admin's list of the forges sent from here: name, address, whom for, apps, claimed or not, last activity",
  description:
    "The forges sent from here (admin): name, address, for, apps, claimed, spendTodayUsd, ceilingUsd.",
  inputSchema: { type: "object", properties: {} },
  writes: false,
  async run(ctx, user) {
    if (!user.isAdmin)
      return bad("forbidden", "only an admin of this forge sees the forges it sent");
    const forges = await clientRows(ctx.app);
    return good({
      says:
        forges.length === 0
          ? "This forge has sent no forges yet."
          : `${forges.length} forge${forges.length === 1 ? "" : "s"} sent from here.`,
      forges,
    });
  },
};
@@ -0,0 +1,51 @@
import { frontInput, frontJson, setFront } from "../../../actions/front.ts";
import { ADMIN_WORDS } from "../../../actions/admin_words.ts";
import { good, bad, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "front_page",
  doc: "`{ pinned?, hidden?, weights?, dryRun? }`: the front page as a stranger sees it, ranked, with numbers; a site admin sets what is pinned (first public one featured), hidden, and what counts (weights of forks, ships, use, fresh, 0 to 10)",
  description:
    "The front page as a stranger sees it; a site admin also gets and sets `pinned`, `hidden`, `weights`.",
  inputSchema: {
    type: "object",
    properties: {
      pinned: { type: "array", items: { type: "string" } },
      hidden: { type: "array", items: { type: "string" } },
      weights: {
        type: "object",
        description: "0–10 each.",
        properties: {
          forks: { type: "number", minimum: 0, maximum: 10 },
          ships: { type: "number", minimum: 0, maximum: 10 },
          use: { type: "number", minimum: 0, maximum: 10 },
          fresh: { type: "number", minimum: 0, maximum: 10 },
        },
      },
      dryRun: { type: "boolean" },
    },
  },
  writes: true,
  dryByDefault: true,
  run(ctx, user, args) {
    if (
      args["pinned"] === undefined &&
      args["hidden"] === undefined &&
      args["weights"] === undefined
    )
      return good(frontJson(ctx.app, user));
    const picks = frontInput(ctx.app, args);
    if (picks === undefined)
      return bad("invalid", "pinned and hidden are lists of owner/name; weights an object of forks, ships, use, fresh");
    const set = setFront(ctx.app, user, picks, args["dryRun"] !== false);
    if (!set.ok)
      return set.error.kind === "forbidden"
        ? bad("forbidden", ADMIN_WORDS.frontPage)
        : bad("invalid", set.error.message);
    return good({
      dryRun: args["dryRun"] !== false,
      picks: set.value,
      ...(args["dryRun"] === false ? { front: frontJson(ctx.app, user) } : {}),
    });
  },
};
@@ -0,0 +1,12 @@
import { readHealth } from "../../../actions/health.ts";
import { good, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "health",
  doc: "how this forge is: the version and commit it runs, draining or not, the rollout and its incidents",
  description:
    "How this forge is: version, commit, draining or not, rollout, incidents.",
  inputSchema: { type: "object", properties: {} },
  writes: false,
  run: (ctx, user) => good(readHealth(ctx.app, user)),
};
@@ -0,0 +1,30 @@
import { manifestFor } from "../../../actions/here.ts";
import { good, bad, type Tool, str } from "../shared.ts";
export const tool: Tool = {
  name: "here",
  description:
    "What you can do on a forge page, as who you are: each open action with its HTTP route and MCP tool.",
  inputSchema: {
    type: "object",
    properties: { url: { type: "string", maxLength: 2000 } },
    required: ["url"],
  },
  writes: false,
  run(ctx, user, args) {
    const raw = str(args["url"]);
    const parsed = URL.parse(raw, ctx.url.origin);
    if (parsed === null || parsed.origin !== ctx.url.origin)
      return bad("not_found", "not a page of this forge");
    const found = manifestFor(
      ctx.app,
      user,
      ctx.auth.via === "token" ? ctx.auth.scope : undefined,
      ctx.url.origin,
      parsed.pathname,
    );
    return found.ok
      ? good(found.value)
      : bad("not_found", "no such page here, or it is not visible to you");
  },
};
@@ -0,0 +1,80 @@
import { holdPull, releasePull } from "../../../actions/holds.ts";
import { getPull } from "../../../core/pulls.ts";
import { good, bad, type Tool, str, APP_ARG, planRepo, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "hold",
  doc: "`{ app, pull, why?, release?, dryRun? }`: hold a pull so no rule reviews or lands it, or let it go; a person who can write, never an agent; plans unless `dryRun: false`",
  description:
    "Hold a pull (`why`) or let it go (`release: true`): while held nothing reviews or lands it. Writers.",
  inputSchema: {
    type: "object",
    properties: {
      app: APP_ARG,
      pull: { type: "integer" },
      why: {
        type: "string",
        description: "Why, one line.",
      },
      release: {
        type: "boolean",
      },
      dryRun: {
        type: "boolean",
        description: "false to apply",
      },
    },
    required: ["app", "pull"],
  },
  writes: true,
  dryByDefault: true,
  run(ctx, user, args) {
    const repo = planRepo(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const n = args["pull"];
    const pull =
      typeof n === "number" && Number.isInteger(n) && n > 0
        ? getPull(ctx.app.db, repo.id, n)
        : undefined;
    if (pull === undefined)
      return bad("no_such_pull", `no pull #${String(n)}`);
    const dry = args["dryRun"] !== false;
    const name = `${repo.ownerName}/${repo.name}#${pull.number}`;
    const hint = "Nothing changed; send dryRun: false to do it.";
    if (args["release"] === true) {
      const released = releasePull(ctx.app, user, repo, pull, dry);
      if (!released.ok)
        return bad(
          released.error,
          "holding and releasing are for a person who can write this app",
        );
      return good({
        says: !released.value
          ? `Nothing holds ${name}.`
          : dry
            ? `Would release ${name}. ${hint}`
            : `Released ${name}. The rules take it from here.`,
        held: dry ? released.value : false,
        dryRun: dry,
      });
    }
    const held = holdPull(ctx.app, user, repo, pull, str(args["why"]), dry);
    if (!held.ok)
      return bad(
        held.error,
        held.error === "not_open"
          ? "only an open pull can be held"
          : held.error === "empty_why" || held.error === "why_too_long"
            ? "say why in one line, at most 200 characters (why)"
            : "holding and releasing are for a person who can write this app",
      );
    return good({
      says: dry
        ? `Would hold ${name}: "${held.value.why}". ${hint}`
        : `Held ${name}. No rule reviews or lands it until it is released.`,
      held: !dry,
      hold: { by: held.value.heldByName, why: held.value.why },
      dryRun: dry,
    });
  },
};
@@ -0,0 +1,72 @@
import { canAdmin } from "../../../core/repos.ts";
import { listWebhooks } from "../../../core/webhooks.ts";
import { createWebhook, deleteWebhook } from "../../../actions/repos.ts";
import { good, bad, type Answer, type Args, type Tool, REPO_ARG, repoArg, isAnswer, str } from "../shared.ts";
const HOOK_LIMITS = { url: 2048, kinds: 200, secret: 200, id: 64 } as const;
/** The refusal for a `hooks` argument that is not text or is over its declared length. */
function hookTooLong(args: Args): Answer | undefined {
  for (const [key, max] of Object.entries(HOOK_LIMITS)) {
    const v = args[key];
    if (v !== undefined && (typeof v !== "string" || v.length > max))
      return bad("invalid", `${key} is text of at most ${max} characters`);
  }
  return undefined;
}
const notAdmin = (): Answer => bad("not_found", "no such app or repository, or you do not administer it");
export const tool: Tool = {
  name: "hooks",
  doc: "`{ repo, action, url, secret, kinds, id }`: `list`, `add` (`secret`, 16–200 characters, is required) or `remove` the repository's webhooks, as `…/hooks`; an admin-scope token on a repository you administer, and a secret is never shown",
  description: "List, add (`url`, `secret`, `kinds`) or remove (`id`) a repository's webhooks; admins only, a secret is never shown.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      action: { type: "string", enum: ["list", "add", "remove"] },
      url: { type: "string", maxLength: 2048 },
      kinds: { type: "string", maxLength: 200 },
      secret: { type: "string", maxLength: 200 },
      id: { type: "string", maxLength: 64 },
    },
    required: ["repo", "action"],
  },
  writes: true,
  needsAdminScope: true,
  run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const action = args["action"];
    if (action === "list") {
      if (!canAdmin(ctx.app.db, repo, user)) return notAdmin();
      return good(listWebhooks(ctx.app.db, repo.id));
    }
    if (action === "add") {
      const long = hookTooLong(args);
      if (long !== undefined) return long;
      const secret = args["secret"];
      if (typeof secret !== "string" || secret.length < 16)
        return bad("invalid", "secret is required: 16 to 200 characters, the key deliveries are signed with");
      const created = createWebhook(ctx.app, user, repo, {
        url: str(args["url"]),
        kinds: str(args["kinds"]) || "*",
        secret,
      });
      if (!created.ok)
        return created.error === "invalid_url"
          ? bad("invalid_url", "a webhook url is https://…")
          : notAdmin();
      // Unlike the API's one-time reveal, the secret is never echoed here.
      return good(created.value.webhook);
    }
    if (action === "remove") {
      const long = hookTooLong(args);
      if (long !== undefined) return long;
      const removed = deleteWebhook(ctx.app, user, repo, str(args["id"]));
      return removed.ok ? good({}) : bad("not_found", "no such webhook here");
    }
    return bad("invalid", "action is list, add or remove");
  },
};
@@ -0,0 +1,122 @@
// Generated by `bun scripts/mcp-tools.ts` from the files beside it; do not edit.
// One line per tool, sorted: a new tool is a new file and one new line here.
export { tool as access } from "./access.ts";
export { tool as account_role } from "./account_role.ts";
export { tool as account_suspend } from "./account_suspend.ts";
export { tool as account_verify } from "./account_verify.ts";
export { tool as agent } from "./agent.ts";
export { tool as app_deploy } from "./app_deploy.ts";
export { tool as app_env } from "./app_env.ts";
export { tool as app_members } from "./app_members.ts";
export { tool as apps } from "./apps.ts";
export { tool as archive } from "./archive.ts";
export { tool as asked } from "./asked.ts";
export { tool as asks } from "./asks.ts";
export { tool as asks_act } from "./asks_act.ts";
export { tool as asks_decide } from "./asks_decide.ts";
export { tool as asks_proposal } from "./asks_proposal.ts";
export { tool as asks_undecide } from "./asks_undecide.ts";
export { tool as assigned } from "./assigned.ts";
export { tool as attach_look } from "./attach_look.ts";
export { tool as audit } from "./audit.ts";
export { tool as board_delete } from "./board_delete.ts";
export { tool as board_pins } from "./board_pins.ts";
export { tool as board_write } from "./board_write.ts";
export { tool as boards } from "./boards.ts";
export { tool as branches } from "./branches.ts";
export { tool as capacity } from "./capacity.ts";
export { tool as claim_link } from "./claim_link.ts";
export { tool as close } from "./close.ts";
export { tool as cloud_account } from "./cloud_account.ts";
export { tool as cloud_accounts } from "./cloud_accounts.ts";
export { tool as commits } from "./commits.ts";
export { tool as confirm_wait } from "./confirm_wait.ts";
export { tool as contribute } from "./contribute.ts";
export { tool as converge } from "./converge.ts";
export { tool as decisions_by } from "./decisions_by.ts";
export { tool as edit } from "./edit.ts";
export { tool as egress_grants } from "./egress_grants.ts";
export { tool as email_verify } from "./email_verify.ts";
export { tool as events } from "./events.ts";
export { tool as explore } from "./explore.ts";
export { tool as family } from "./family.ts";
export { tool as feed } from "./feed.ts";
export { tool as feed_chips } from "./feed_chips.ts";
export { tool as flow } from "./flow.ts";
export { tool as follow_mode } from "./follow_mode.ts";
export { tool as following } from "./following.ts";
export { tool as forge_proposals } from "./forge_proposals.ts";
export { tool as forges } from "./forges.ts";
export { tool as front_page } from "./front_page.ts";
export { tool as health } from "./health.ts";
export { tool as here } from "./here.ts";
export { tool as hold } from "./hold.ts";
export { tool as hooks } from "./hooks.ts";
export { tool as invites } from "./invites.ts";
export { tool as issue } from "./issue.ts";
export { tool as issue_teams } from "./issue_teams.ts";
export { tool as labels } from "./labels.ts";
export { tool as limb } from "./limb.ts";
export { tool as limits } from "./limits.ts";
export { tool as make_it_yours } from "./make_it_yours.ts";
export { tool as map } from "./map.ts";
export { tool as migrate } from "./migrate.ts";
export { tool as milestones } from "./milestones.ts";
export { tool as mint_invite } from "./mint_invite.ts";
export { tool as mirror_set } from "./mirror_set.ts";
export { tool as model_ceiling } from "./model_ceiling.ts";
export { tool as model_grant } from "./model_grant.ts";
export { tool as new_app } from "./new_app.ts";
export { tool as next_steps } from "./next_steps.ts";
export { tool as now } from "./now.ts";
export { tool as org_teams } from "./org_teams.ts";
export { tool as origin_apps } from "./origin_apps.ts";
export { tool as origins } from "./origins.ts";
export { tool as outsiders } from "./outsiders.ts";
export { tool as parent_unlink } from "./parent_unlink.ts";
export { tool as plan } from "./plan.ts";
export { tool as preview } from "./preview.ts";
export { tool as probe } from "./probe.ts";
export { tool as prompts } from "./prompts.ts";
export { tool as proposal_tokens } from "./proposal_tokens.ts";
export { tool as propose_to_parent_forge } from "./propose_to_parent_forge.ts";
export { tool as pull } from "./pull.ts";
export { tool as pulls } from "./pulls.ts";
export { tool as quotas } from "./quotas.ts";
export { tool as read_file } from "./read_file.ts";
export { tool as repo } from "./repo.ts";
export { tool as repo_labels } from "./repo_labels.ts";
export { tool as repo_settings } from "./repo_settings.ts";
export { tool as reports } from "./reports.ts";
export { tool as returns } from "./returns.ts";
export { tool as review } from "./review.ts";
export { tool as run_log } from "./run_log.ts";
export { tool as runs } from "./runs.ts";
export { tool as say } from "./say.ts";
export { tool as scorecard } from "./scorecard.ts";
export { tool as seal } from "./seal.ts";
export { tool as search } from "./search.ts";
export { tool as secrets } from "./secrets.ts";
export { tool as sever } from "./sever.ts";
export { tool as share } from "./share.ts";
export { tool as signup } from "./signup.ts";
export { tool as sizes } from "./sizes.ts";
export { tool as spawn } from "./spawn.ts";
export { tool as spend } from "./spend.ts";
export { tool as ssh_keys } from "./ssh_keys.ts";
export { tool as stop } from "./stop.ts";
export { tool as subscription_budget } from "./subscription_budget.ts";
export { tool as system } from "./system.ts";
export { tool as take_updates } from "./take_updates.ts";
export { tool as teams } from "./teams.ts";
export { tool as telemetry_grant } from "./telemetry_grant.ts";
export { tool as tell } from "./tell.ts";
export { tool as thought } from "./thought.ts";
export { tool as threads } from "./threads.ts";
export { tool as trail } from "./trail.ts";
export { tool as upstream } from "./upstream.ts";
export { tool as usage } from "./usage.ts";
export { tool as variant } from "./variant.ts";
export { tool as wait_for } from "./wait_for.ts";
export { tool as watch } from "./watch.ts";
export { tool as whoami_can } from "./whoami_can.ts";
@@ -0,0 +1,35 @@
import { list as listInviteLinks, revoke as revokeInviteLink } from "../../../actions/invites.ts";
import { scopeAllows } from "../../../core/tokens.ts";
import { good, bad, type Tool, mayBoards } from "../shared.ts";
export const tool: Tool = {
  name: "invites",
  doc: "`{ action, id? }`: `list` the outstanding invites (state and expiry, never a link) or `revoke` one by `id`; a person admin with an admin token, stricter than the API's list, which an `ro` token may read",
  description: "List open invites, or revoke one by `id`.",
  inputSchema: {
    type: "object",
    properties: {
      action: { type: "string", enum: ["list", "revoke"] },
      id: { type: "string" },
    },
    required: ["action"],
  },
  writes: true,
  run(ctx, user, args) {
    if (!mayBoards(user)) return bad("forbidden", "invites are a forge admin's");
    if (!scopeAllows(ctx.auth.scope ?? "ro", "admin"))
      return bad("forbidden", "invites need an admin token");
    const action = args["action"];
    if (action === "list") {
      const listed = listInviteLinks(ctx.app, user);
      return listed.ok ? good({ items: listed.value }) : bad("forbidden", "invites are a forge admin's");
    }
    if (action === "revoke") {
      const id = args["id"];
      if (typeof id !== "string" || id === "") return bad("invalid", "revoke needs an invite id");
      const done = revokeInviteLink(ctx.app, user, id);
      return done.ok ? good(done.value) : bad("not_found", "no such open invite");
    }
    return bad("invalid", 'action is "list" or "revoke"');
  },
};
@@ -0,0 +1,78 @@
import { mayView } from "../../../core/sealed.ts";
import { getIssue, labelsFor, listComments } from "../../../core/issues.ts";
import { isCrew } from "../../../core/agents.ts";
import { dependenciesOf } from "../../../core/dependencies.ts";
import { getUsersByIds } from "../../../core/users.ts";
import { markReaders } from "../../../crew/direct.ts";
import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "issue",
  doc: "`{ repo, number }`: one issue's title, state, closeReason, body, labels, assignee, comments (author, authorIsAgent, body, at) and blockedBy/blocks, as `GET …/issues/:number`; a sealed one you cannot see is not found",
  description:
    "One issue with comments, `blockedBy`, `blocks`; crew agents get `untrusted: true` on non-writers' text.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      number: { type: "integer", minimum: 1 },
    },
    required: ["repo", "number"],
  },
  writes: false,
  async run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const n = args["number"];
    const issue =
      typeof n === "number" && Number.isInteger(n) && n > 0
        ? getIssue(ctx.app.db, repo.id, n)
        : undefined;
    if (issue === undefined || !mayView(ctx.app.db, repo, issue, user))
      return bad("not_found", `no issue #${String(n)}`);
    // Seen only after the sealed check, so a sealed pull is not told apart.
    if (issue.kind !== "issue") return good({ kind: "pull", tool: "pull" });
    const db = ctx.app.db;
    // Marked only for a crew agent, as the API does: to anyone else the
    // mark would say which commenters cannot write.
    const marking = user.kind === "agent" && isCrew(db, repo.id, user.id);
    const mark = <T extends { authorName: string; originAuthor: string | null }>(
      items: readonly T[],
    ): (T & { untrusted?: string })[] =>
      marking ? markReaders(db, repo, items) : [...items];
    const comments = mark(listComments(db, issue.id));
    const authors = getUsersByIds(db, [...new Set(comments.map((c) => c.authorId))]);
    const deps = dependenciesOf(db, issue.id);
    const brief = (i: typeof issue) => ({
      number: i.number,
      title: i.title,
      state: i.state,
      ...(i.closeReason === null ? {} : { closeReason: i.closeReason }),
    });
    const seen = (i: typeof issue) => mayView(db, repo, i, user);
    const flag = (x: { untrusted?: string }) =>
      x.untrusted === undefined ? {} : { untrusted: true };
    const [self] = mark([issue]);
    return good({
      number: issue.number,
      title: issue.title,
      state: issue.state,
      closeReason: issue.closeReason,
      body: issue.body,
      author: issue.authorName,
      authorIsAgent: issue.authorIsAgent,
      ...flag(self!),
      labels: labelsFor(db, issue.id).map((l) => l.name),
      assignee: issue.assigneeName,
      comments: comments.map((c) => ({
        author: c.authorName,
        authorIsAgent: authors.get(c.authorId)?.kind === "agent",
        body: c.body,
        at: c.createdAt,
        ...flag(c),
      })),
      blockedBy: deps.blockedBy.filter(seen).map(brief),
      blocks: deps.blocks.filter(seen).map(brief),
    });
  },
};
@@ -0,0 +1,36 @@
import { ISSUE_TEAMS_SAY, nameTeams } from "../../../actions/issue_teams.ts";
import { teamsOfIssue } from "../../../core/issue_teams.ts";
import { good, bad, type Tool, REPO_ARG, repoArg, issueArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "issue_teams",
  description:
    "Name up to two crew teams (design, data-science, security, platform) to review an issue's pull.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      number: { type: "integer", minimum: 1 },
      teams: { type: "array", maxItems: 2, items: { type: "string", maxLength: 64 } },
    },
    required: ["repo", "number"],
  },
  writes: true,
  run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const issue = issueArg(ctx, repo, args, "number");
    if ("ok" in issue) return issue;
    const teams = args["teams"];
    if (teams === undefined) return good({ number: issue.number, teams: teamsOfIssue(ctx.app.db, issue.id) });
    if (!Array.isArray(teams) || !teams.every((t) => typeof t === "string"))
      return bad("invalid", "teams is a list of team slugs");
    const set = nameTeams(ctx.app, user, repo, issue, teams);
    if (!set.ok) return bad(set.error, ISSUE_TEAMS_SAY[set.error] ?? "that could not be changed");
    return good({
      number: issue.number,
      teams: set.value,
      says: set.value.length === 0 ? `#${issue.number} names no team.` : `#${issue.number} names ${set.value.join(" and ")}.`,
    });
  },
};
@@ -0,0 +1,63 @@
import { THREAD_SAYS } from "../../../actions/thread_words.ts";
import { setIssueLabelsThrough } from "../../../actions/issues.ts";
import { originError } from "../../../web/pages/thread.ts";
import { good, bad, type Tool, REPO_ARG, repoArg, issueArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "labels",
  doc: "`{ repo, number, labels }`: set an issue's or a pull's labels to exactly these (`[]` clears); only labels the repository has, by a writer",
  description:
    "Set an issue's or pull's labels to exactly these (none clears), from the repository's. Writers.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      number: { type: "integer", minimum: 1 },
      labels: {
        type: "array",
        items: { type: "string", maxLength: 64 },
        maxItems: 50,
      },
    },
    required: ["repo", "number", "labels"],
  },
  writes: true,
  async run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const chosen = args["labels"];
    if (
      !Array.isArray(chosen) ||
      chosen.length > 50 ||
      !chosen.every((l) => typeof l === "string" && l.length <= 64)
    )
      return bad("invalid_labels", "labels is a list of up to 50 label names");
    const issue = issueArg(ctx, repo, args, "number");
    if ("ok" in issue) return issue;
    // The permission is the action's to check, as on the page.
    const applied = await setIssueLabelsThrough(
      ctx.app,
      user,
      repo,
      issue,
      chosen,
    );
    if (!applied.ok)
      return bad(
        applied.error,
        originError(applied.error) ??
          (applied.error === "unknown_label"
            ? THREAD_SAYS.unknownLabel
            : THREAD_SAYS.labelsForbidden),
      );
    const names = applied.value.map((l) => l.name);
    return good({
      says:
        names.length === 0
          ? `Cleared the labels of #${issue.number}.`
          : `Labels of #${issue.number} set to ${names.join(", ")}.`,
      labels: names,
      url: `${ctx.url.origin}/${repo.ownerName}/${repo.name}/${issue.kind === "pull" ? "pulls" : "issues"}/${issue.number}`,
    });
  },
};
@@ -0,0 +1,100 @@
import { scopeAllows } from "../../../core/tokens.ts";
import { undoFleetOp } from "../../../actions/fleet.ts";
import { applyLimb, isLimbAction, previewLimb } from "../../../actions/limbs.ts";
import { isReplanAction, previewReplan, replanLimb, takeBackLimb } from "../../../actions/limb_replan.ts";
import { good, bad, type Tool, str, APP_ARG, planRepo, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "limb",
  doc: "`{ app, issue, action, reason?, pillar?, operation?, dryRun? }`: defer, resume or close a whole limb as not doing, or undo an operation; plans unless `dryRun` is false, and applying takes an admin token",
  description:
    "Act on a limb by `action`; `close` takes `reason`.",
  inputSchema: {
    type: "object",
    properties: {
      app: APP_ARG,
      issue: {
        type: "integer",
        minimum: 1,
      },
      action: { type: "string", enum: ["defer", "resume", "close", "raise", "lower", "replan", "takeback", "undo"] },
      reason: {
        type: "string",
        description: "For close: why.",
      },
      pillar: {
        type: "string",
        description:
          "For resume.",
      },
      under: {
        type: "string",
        description:
          "`top` or a milestone number.",
      },
      operation: {
        type: "string",
      },
      dryRun: {
        type: "boolean",
        description: "false to apply",
      },
    },
    required: ["app", "action"],
  },
  writes: true,
  dryByDefault: true,
  async run(ctx, user, args) {
    const repo = planRepo(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const dry = args["dryRun"] !== false;
    // The fleet's rule: a read credential plans, an admin one applies.
    if (!dry && !scopeAllows(ctx.auth.scope ?? "ro", "admin"))
      return bad("forbidden", "applying a limb action takes an admin token");
    const refused = (e: { code: string; message: string }) =>
      bad(e.code, e.message);
    if (args["action"] === "undo") {
      if (dry) return bad("invalid", "undo is not a dry run: pass dryRun false");
      const undone = await undoFleetOp(ctx.app, user, str(args["operation"]));
      return undone.ok ? good(undone.value) : refused(undone.error);
    }
    const number = args["issue"];
    if (
      isReplanAction(args["action"]) &&
      typeof number === "number" &&
      Number.isInteger(number) &&
      number > 0
    ) {
      if (dry) {
        const plan = previewReplan(ctx.app, user, repo, number);
        return plan.ok ? good({ dryRun: true, ...plan.value }) : refused(plan.error);
      }
      const done =
        args["action"] === "replan"
          ? replanLimb(ctx.app, user, repo, number)
          : takeBackLimb(ctx.app, user, repo, number);
      return done.ok ? good({ dryRun: false, ...done.value }) : refused(done.error);
    }
    if (
      !isLimbAction(args["action"]) ||
      typeof number !== "number" ||
      !Number.isInteger(number) ||
      number < 1
    )
      return bad("invalid", "give the limb's issue number and an action: defer, resume, close, raise, lower, replan, takeback or undo");
    const request = {
      action: args["action"],
      ...(typeof args["reason"] === "string" ? { reason: args["reason"] } : {}),
      ...(typeof args["pillar"] === "string" ? { pillar: args["pillar"] } : {}),
      ...(typeof args["under"] === "string" || typeof args["under"] === "number"
        ? { under: String(args["under"]) }
        : {}),
    };
    if (dry) {
      const plan = previewLimb(ctx.app, user, repo, number, request);
      return plan.ok ? good({ dryRun: true, ...plan.value }) : refused(plan.error);
    }
    const op = await applyLimb(ctx.app, user, repo, number, request);
    return op.ok ? good({ dryRun: false, ...op.value }) : refused(op.error);
  },
};
@@ -0,0 +1,41 @@
import { changeLimit, listLimits } from "../../../actions/limits.ts";
import { LIMIT_KEYS } from "../../../settings/limits.ts";
import { scopeAllows } from "../../../core/tokens.ts";
import { good, bad, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "limits",
  description:
    "Every limit the forge's owner can hit, value and bounds. `key` and `value` (\"\" restores) plan.",
  inputSchema: {
    type: "object",
    properties: {
      key: { type: "string", enum: [...LIMIT_KEYS] },
      value: { type: "string", maxLength: 16 },
      dryRun: { type: "boolean", description: "false to apply" },
    },
  },
  writes: true,
  dryByDefault: true,
  run(ctx, user, args) {
    const listed = listLimits(ctx.app, user);
    if (!listed.ok) return bad("not_found", "no such tool here");
    const key = typeof args["key"] === "string" ? args["key"] : undefined;
    if (key === undefined) return good(listed.value);
    const value = typeof args["value"] === "string" ? args["value"] : "";
    const now = listed.value.limits.find((l) => l.key === key);
    if (now === undefined) return bad("no_such_limit", `no limit ${key}`);
    if (args["dryRun"] !== false)
      return good({
        says: `Would set ${key} from ${now.value} to ${value || `its default, ${now.defaultValue}`}. Send dryRun: false to change it.`,
      });
    if (!scopeAllows(ctx.auth.scope ?? "ro", "admin"))
      return bad("forbidden", "changing the forge's limits needs an admin-scope token");
    const changed = changeLimit(ctx.app, user, key, value === "" ? null : value);
    if (!changed.ok) return bad(changed.error.kind, changed.error.kind === "out_of_bounds" ? changed.error.message : "no such limit");
    return good({
      says: `${key}: ${changed.value.from} → ${changed.value.to}, from the next use on.`,
      ...changed.value,
    });
  },
};
@@ -0,0 +1,56 @@
import { APP_ALREADY_YOURS } from "../../../actions/origin_app_words.ts";
import { NOT_A_MEMBER } from "../../../core/roles.ts";
import { COPIES_PER_DAY, makeItYours } from "../../../actions/make_it_yours.ts";
import { good, bad, type Tool, str, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "make_it_yours",
  doc: "`{ repo, name?, visibility?, dryRun? }`: a fork of an app you can see, as your own app, following the original; code and history copied, data and secrets not; private unless `visibility` is public (a public original only); at most 5 copies an account a day; plans unless `dryRun` is false",
  description:
    "Fork an app you can see: its code and history, following the original; nothing else is copied.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      name: { type: "string" },
      visibility: { type: "string", enum: ["private", "public"], description: "Private by default." },
      dryRun: { type: "boolean" },
    },
    required: ["repo"],
  },
  writes: true,
  dryByDefault: true,
  async run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const name = str(args["name"]);
    const visibility = str(args["visibility"]);
    if (visibility !== "" && visibility !== "public" && visibility !== "private")
      return bad("invalid", "visibility is public or private");
    const made = await makeItYours(ctx.app, user, repo, {
      dryRun: args["dryRun"] !== false,
      ...(name === "" ? {} : { name }),
      ...(visibility === "" ? {} : { visibility }),
    });
    if (!made.ok)
      return made.error.kind === "limit"
        ? bad("limit", `at most ${COPIES_PER_DAY} copies a day; another after ${made.error.resetsAt}`)
        : made.error.kind === "repository_limit"
        ? bad("repository_limit", made.error.message)
        : made.error.kind === "storage_limit"
        ? bad("storage_limit", made.error.message)
        : made.error.kind === "invalid"
        ? bad("invalid", made.error.message)
        : made.error.kind === "own"
          ? bad("own", APP_ALREADY_YOURS)
          : made.error.kind === "not_member"
            ? bad("not_member", NOT_A_MEMBER)
          : made.error.kind === "unverified"
            ? bad("unverified", "prove your email first")
            : bad("not_found", "no such app or repository (owner/name)");
    const { made: done, ...plan } = made.value;
    return good(
      done === undefined ? plan : { ...plan, url: `/${done.repo.ownerName}/${done.repo.name}` },
    );
  },
};
@@ -0,0 +1,42 @@
import { sealedScope } from "../../../core/sealed.ts";
import { repoGraph } from "../../../core/dependencies.ts";
import { pillarView } from "../../../core/pillars.ts";
import { askToLiveFor } from "../../../web/ask_to_live.ts";
import { listActiveRuns } from "../../../core/runs.ts";
import { mapJson, marksFor } from "../../../web/pages/map.ts";
import { good, type Tool, APP_ARG, planRepo, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "map",
  doc: "an app's plan: ready now, waiting on what, the critical path, where the crew is, parked twice and why (`app`); draws the `ui://forge/map` card",
  description:
    "An app's plan: open issues ready or waiting, critical path, edges, where the crew is, `parkedTwice`.",
  inputSchema: {
    type: "object",
    properties: { app: APP_ARG },
    required: ["app"],
  },
  writes: false,
  async run(ctx, user, args) {
    const repo = planRepo(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const graph = repoGraph(ctx.app.db, repo.id, {
      ...sealedScope(ctx.app.db, repo, user),
    });
    const pillars = pillarView(ctx.app.db, repo);
    return good(
      mapJson(
        repo,
        graph,
        marksFor(
          ctx.app.db,
          repo.id,
          graph,
          listActiveRuns(ctx.app.db, [repo.id]),
        ),
        pillars,
        askToLiveFor(ctx.app, repo, pillars, user),
      ),
    );
  },
};
@@ -0,0 +1,64 @@
import { migrateMessage, migrateRepo, migrationJobFor } from "../../../actions/migrate.ts";
import type { MirrorJob } from "../../../origins/jobs.ts";
import { repositoryLimitMessage } from "../../../actions/repos.ts";
import { storageLimitMessage } from "../../../core/storage.ts";
import { good, bad, type Tool, str } from "../shared.ts";
export const tool: Tool = {
  name: "migrate",
  doc: "`{ url, name?, crew? }` brings a public repository in by URL (history only; nothing reaches back) and answers `{ job, state, url }`; `{ job }` alone reads that job. Same validation, scope (`rw`) and private-address refusal as `POST /api/v1/migrate`",
  description:
    "Bring a repository in by public `url` (`name`, `crew`), history and all. With `job`, its state.",
  inputSchema: {
    type: "object",
    properties: {
      url: { type: "string", maxLength: 2048 },
      name: { type: "string", maxLength: 100 },
      crew: { type: "string", maxLength: 39, description: "Agent to put on it" },
      job: { type: "string", maxLength: 64 },
    },
  },
  writes: true,
  readsWithout: "url",
  async run(ctx, user, args) {
    const migration = (job: MirrorJob) => ({
      job: job.id,
      state: job.stage,
      detail: job.detail,
      url:
        job.repo === undefined || job.stage === "failed"
          ? null
          : `${ctx.url.origin}/${job.repo.ownerName}/${job.repo.name}`,
      error: job.error ?? null,
    });
    const url = args["url"];
    if (url === undefined) {
      const id = str(args["job"]);
      if (id === "") return bad("invalid", "send `url` to migrate, or `job` to read one");
      const found = migrationJobFor(user, id);
      return found.ok ? good(migration(found.value)) : bad("not_found", "no such migration");
    }
    if (typeof url !== "string") return bad("invalid", "`url` is a string");
    const name = args["name"];
    const crew = args["crew"];
    if (name !== undefined && typeof name !== "string") return bad("invalid", "`name` is a string");
    if (crew !== undefined && typeof crew !== "string") return bad("invalid", "`crew` is a string");
    const started = await migrateRepo(ctx.app, user, {
      source: { url },
      ...(name === undefined ? {} : { name }),
      ...(crew === undefined ? {} : { crew: { agent: crew, autonomous: false } }),
    });
    if (!started.ok)
      return started.error === "unauthorized"
        ? bad("unauthorized", "sign in to migrate")
        : started.error === "repository_limit"
          ? bad("repository_limit", repositoryLimitMessage(ctx.app, user))
          : started.error === "storage_limit"
            ? bad("storage_limit", storageLimitMessage(ctx.app, user.id))
            : bad(started.error, migrateMessage(started.error));
    return good({
      ...migration(started.value.job),
      url: `${ctx.url.origin}/${started.value.repo.ownerName}/${started.value.repo.name}`,
    });
  },
};
@@ -0,0 +1,40 @@
import { milestoneData, milestonesJson } from "../../../web/pages/milestones.ts";
import { good, bad, type Tool, APP_ARG, planRepo, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "milestones",
  doc: "`{ app, issue? }`: how far each thing asked for is (and, with `issue`, whether you watch it: `watching`), from the dependency tree: the plan's limbs with their weights, or one milestone opened (who is building, what is blocked and on what, what merged in 7 days, an estimate, and for an owner `spend`: dollars, changes landed ever, the costliest three issues)",
  description:
    "How far each thing asked for is. With `app`: top-level limbs, done/total, building, recent merges.",
  inputSchema: {
    type: "object",
    properties: {
      app: APP_ARG,
      issue: {
        type: "integer",
        minimum: 1,
        description:
          "Issue number; limbs if absent.",
      },
    },
    required: ["app"],
  },
  writes: false,
  async run(ctx, user, args) {
    const repo = planRepo(ctx, user, args);
    if (isAnswer(repo)) return repo;
    if (args["issue"] === undefined)
      return good(await milestonesJson(ctx, repo));
    const number = args["issue"];
    const data =
      typeof number === "number" && Number.isInteger(number) && number > 0
        ? await milestoneData(ctx, repo, number)
        : undefined;
    return data === undefined
      ? bad(
          "not_a_milestone",
          "no issue by that number waits for others here",
        )
      : good(data);
  },
};
@@ -0,0 +1,27 @@
import { SPEND_WORDS } from "../../../actions/spend_words.ts";
import { inviteLink, mint as mintInviteLink } from "../../../actions/invites.ts";
import { scopeAllows } from "../../../core/tokens.ts";
import { good, bad, type Tool, mayBoards } from "../shared.ts";
export const tool: Tool = {
  name: "mint_invite",
  doc: "`{ days? }`: mint a single-use invite link that expires in `days` (1–30, default 7) and is shown once; a person admin's, with an admin token",
  description:
    "Mint a single-use invite link, shown once, expiring in `days` (1–30, default 7). Person admins.",
  inputSchema: {
    type: "object",
    properties: {
      days: { type: "integer", minimum: 1, maximum: 30 },
    },
  },
  writes: true,
  run(ctx, user, args) {
    if (!mayBoards(user)) return bad("forbidden", "an invite is a forge admin's to mint");
    if (!scopeAllows(ctx.auth.scope ?? "ro", "admin"))
      return bad("forbidden", "an invite needs an admin token");
    const made = mintInviteLink(ctx.app, user, args["days"]);
    if (!made.ok) return bad("invalid", SPEND_WORDS.inviteDays);
    const origin = ctx.app.config.url ?? ctx.url.origin;
    return good({ ...made.value.invite, link: inviteLink(origin, made.value.token) });
  },
};
@@ -0,0 +1,48 @@
import { forgetMirror, saveMirror } from "../../../actions/mirror.ts";
import { snapshotsOf } from "../../../snapshot/service.ts";
import { good, bad, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "mirror_set",
  doc: "`{ action, endpoint?, bucket?, region?, accessKey?, secretKey? }` (forge admin, admin-scope token): `set` seals the off-box snapshot mirror, `forget` clears it; the Backups page's rules and refusals, a blank field keeps what was sealed; answers `{ place, says }`, never a key",
  description: "Admin: set or forget the off-box snapshot mirror.",
  inputSchema: {
    type: "object",
    properties: {
      action: { type: "string" },
      endpoint: { type: "string" },
      bucket: { type: "string" },
      region: { type: "string" },
      accessKey: { type: "string" },
      secretKey: { type: "string" },
    },
  },
  writes: true,
  adminOnly: true,
  needsAdminScope: true,
  run(ctx, user, args) {
    const place = (): string | null => snapshotsOf(ctx.app)?.mirror?.where ?? null;
    if (args["action"] === "forget") {
      const gone = forgetMirror(ctx.app, user);
      if (!gone.ok) return bad("not_found", "not found");
      return good({ place: place(), says: "The sealed mirror is cleared." });
    }
    if (args["action"] !== "set") return bad("invalid", "action is set or forget");
    const field = (k: string): string | undefined => {
      const v = args[k];
      return v === undefined ? "" : typeof v === "string" ? v.trim() : undefined;
    };
    const input = {
      endpoint: field("endpoint"),
      bucket: field("bucket"),
      region: field("region"),
      accessKey: field("accessKey"),
      secretKey: field("secretKey"),
    };
    if (Object.values(input).some((v) => v === undefined))
      return bad("invalid", "the fields are strings");
    const saved = saveMirror(ctx.app, user, input as Record<keyof typeof input, string>);
    if (!saved.ok) return bad(saved.error === "not_found" ? "not_found" : "invalid", saved.error);
    return good({ place: place(), says: saved.value });
  },
};
@@ -0,0 +1,47 @@
import { SPEND_WORDS } from "../../../actions/spend_words.ts";
import { setAccountCeilings } from "../../../actions/model_grant.ts";
import { scopeAllows } from "../../../core/tokens.ts";
import { good, bad, type Tool, mayBoards } from "../shared.ts";
export const tool: Tool = {
  name: "model_ceiling",
  description:
    "Set an account's daily and per-run model spend ceilings in dollars; a run past one does not start.",
  inputSchema: {
    type: "object",
    properties: {
      username: { type: "string" },
      dailyUsd: { type: ["number", "null"], description: "0.01–10000; null clears." },
      perRunUsd: { type: ["number", "null"], description: "0.01–10000; null clears." },
      dryRun: { type: "boolean", description: "false to apply" },
    },
    required: ["username", "dailyUsd", "perRunUsd"],
  },
  writes: true,
  dryByDefault: true,
  run(ctx, user, args) {
    const { username, dailyUsd, perRunUsd } = args;
    if (
      typeof username !== "string" ||
      !(dailyUsd === null || (typeof dailyUsd === "number" && Number.isFinite(dailyUsd))) ||
      !(perRunUsd === null || (typeof perRunUsd === "number" && Number.isFinite(perRunUsd)))
    )
      return bad("invalid", "send a username, dailyUsd and perRunUsd in dollars (both null takes them back)");
    if (!mayBoards(user)) return bad("forbidden", "a ceiling is a forge admin's to set");
    if (args["dryRun"] !== false)
      return good({
        username,
        dailyUsd,
        perRunUsd,
        says: "This is the plan; nothing changed. Send dryRun: false to set it.",
      });
    if (!scopeAllows(ctx.auth.scope ?? "ro", "admin"))
      return bad("forbidden", "a ceiling needs an admin token");
    const set = setAccountCeilings(ctx.app, user, username, dailyUsd, perRunUsd);
    if (!set.ok)
      return set.error === "invalid_amount"
        ? bad("invalid", SPEND_WORDS.ceilings)
        : bad("forbidden", "no such account");
    return good(set.value);
  },
};
@@ -0,0 +1,46 @@
import { SPEND_WORDS } from "../../../actions/spend_words.ts";
import { setAccountGrant } from "../../../actions/model_grant.ts";
import { scopeAllows } from "../../../core/tokens.ts";
import { good, bad, type Tool, mayBoards } from "../shared.ts";
export const tool: Tool = {
  name: "model_grant",
  description:
    "Give a person a capped monthly model grant (`usdPerMonth`, 0 takes it back). Person admins.",
  inputSchema: {
    type: "object",
    properties: {
      username: { type: "string" },
      usdPerMonth: { type: "number", description: "0.01–10000; 0 revokes." },
      dryRun: { type: "boolean", description: "false to apply" },
    },
    required: ["username", "usdPerMonth"],
  },
  writes: true,
  dryByDefault: true,
  run(ctx, user, args) {
    const usd = args["usdPerMonth"];
    const username = args["username"];
    if (typeof username !== "string" || typeof usd !== "number" || !Number.isFinite(usd))
      return bad("invalid", "send a username and usdPerMonth in dollars");
    if (!mayBoards(user)) return bad("forbidden", "a model grant is a forge admin's to give");
    const dryRun = args["dryRun"] !== false;
    if (dryRun)
      return good({
        username,
        usdPerMonth: usd === 0 ? null : usd,
        says: "This is the plan; nothing changed. Send dryRun: false to set it.",
      });
    if (!scopeAllows(ctx.auth.scope ?? "ro", "admin"))
      return bad("forbidden", "a model grant needs an admin token");
    const set = setAccountGrant(ctx.app, user, username, usd === 0 ? null : usd);
    if (!set.ok)
      return bad(
        set.error === "invalid_amount" ? "invalid" : "forbidden",
        set.error === "invalid_amount"
          ? SPEND_WORDS.usdPerMonth
          : "no such person, or not one a grant is for",
      );
    return good(set.value);
  },
};
@@ -0,0 +1,68 @@
import { appsRuntime } from "../../../apps/runtime.ts";
import { listActiveRuns } from "../../../core/runs.ts";
import { getUserByName } from "../../../core/users.ts";
import { repositoryLimitMessage } from "../../../actions/repos.ts";
import { newApp } from "../../../actions/apps.ts";
import { appLimitWords } from "../../../actions/app_limit.ts";
import { storageLimitMessage } from "../../../core/storage.ts";
import { good, bad, type Tool, str } from "../shared.ts";
export const tool: Tool = {
  name: "new_app",
  doc: "`{ name, description?, owner?, visibility?, agent?, pick? }`: make an app from a sentence; answers `{ repo, url, issue, agent, run }` (`run` is the first run's state, or `none`) and draws the `ui://forge/app` card: name, production URL, first issue, agent, first run; refused as `POST /api/v1/apps` is (unverified, app_limit, no_such_agent, name_taken)",
  description:
    "Make an app from a sentence: a repository, production started, and with `description` a first issue.",
  inputSchema: {
    type: "object",
    properties: {
      name: { type: "string", maxLength: 100 },
      description: { type: "string", maxLength: 4000, description: "The first issue." },
      owner: { type: "string", maxLength: 39 },
      visibility: { type: "string", enum: ["public", "private"], description: "Default private." },
      agent: { type: "string", maxLength: 39, description: "Agent for the first issue." },
      pick: { type: "boolean", description: "Pick the agent from the text." },
    },
    required: ["name"],
  },
  writes: true,
  async run(ctx, user, args) {
    const text = (k: string) => (typeof args[k] === "string" ? (args[k] as string) : undefined);
    const visibility = args["visibility"];
    const owner = text("owner");
    const description = text("description");
    const agent = text("agent");
    const made = await newApp(ctx.app, user, {
      name: str(args["name"]),
      ...(owner === undefined ? {} : { owner }),
      ...(description === undefined ? {} : { description }),
      ...(visibility === "public" || visibility === "private" ? { visibility } : {}),
      ...(agent === undefined ? {} : { agent }),
      ...(args["pick"] === true ? { pickAgent: true } : {}),
    });
    if (!made.ok) {
      switch (made.error) {
        case "unverified":
          return bad("unverified", "verify your email first");
        case "app_limit": {
          const who = getUserByName(ctx.app.db, owner || user.username);
          return bad("app_limit", who ? appLimitWords(ctx.app, who.id) : "App limit reached.");
        }
        case "repository_limit":
          return bad("repository_limit", repositoryLimitMessage(ctx.app, user));
        case "storage_limit":
          return bad("storage_limit", storageLimitMessage(ctx.app, user.id));
        default:
          return bad(made.error, made.error);
      }
    }
    const { repo, app: record, issue } = made.value;
    const first = listActiveRuns(ctx.app.db, [repo.id])[0];
    return good({
      repo: `${repo.ownerName}/${repo.name}`,
      url: appsRuntime(ctx.app)?.urlFor(record, "production") ?? null,
      issue: issue === undefined ? null : issue.number,
      agent: issue?.assigneeName ?? null,
      run: first?.state ?? "none",
    });
  },
};
@@ -0,0 +1,15 @@
import { nextStepsFor } from "../../../core/next-steps.ts";
import { good, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "next_steps",
  doc: "on a spawned forge, your first three steps and whether each is done; empty elsewhere or for anyone but its owner",
  description:
    "On a spawned forge, its owner's first three steps and whether each is done. Empty elsewhere.",
  inputSchema: { type: "object", properties: {} },
  writes: false,
  async run(ctx, user) {
    const steps = await nextStepsFor(ctx.app, user);
    return good({ steps: steps ?? [] });
  },
};
@@ -0,0 +1,105 @@
import { mayViewId } from "../../../core/sealed.ts";
import { getIssueById, listOpenAgentPullsVisibleTo } from "../../../core/issues.ts";
import { waitsForPerson } from "../../../crew/review.ts";
import { getPull } from "../../../core/pulls.ts";
import { ownerFactRepoIds } from "../../../core/repos.ts";
import { plannerDeclines } from "../../../crew/autonomy.ts";
import { listActiveRuns } from "../../../core/runs.ts";
import { getUsersByIds } from "../../../core/users.ts";
import { appsOf } from "../../../web/studio/asks.ts";
import { mayReadRuns, runForReader } from "../../../actions/runs.ts";
import { placementWords } from "../../../checks/placement.ts";
import { good, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "now",
  doc: "what the crew is doing right now: who, on what, since when, at what cost; a planner that declined the direction and waits for you comes first (`run: null`, its words in `says`)",
  description:
    "What the crew is doing across your apps: who, on what, since when, cost; what waits on your review.",
  inputSchema: { type: "object", properties: {} },
  writes: false,
  run(ctx, user) {
    const { repos } = appsOf(ctx, user);
    const byId = new Map(repos.map((r) => [r.id, r]));
    // A private app's runs are for those who may enter it (`mayReadRuns`).
    // A run on a sealed report is for those who may see the report.
    const runs = listActiveRuns(
      ctx.app.db,
      repos.filter((r) => mayReadRuns(ctx.app, user, r)).map((r) => r.id),
    ).filter((r) =>
      mayViewId(ctx.app.db, byId.get(r.repoId)!, r.issueId, user),
    );
    const actors = getUsersByIds(
      ctx.app.db,
      runs.map((r) => r.actorId).filter((id): id is string => id !== null),
    );
    // A planner that declined the direction is the crew waiting on you:
    // it rides the same list, as a row with no run.
    // Owner facts only: a stranger's public app never shows its planner here.
    const owned = ownerFactRepoIds(ctx.app.db, repos, user);
    const waiting = plannerDeclines(
      ctx.app.db,
      repos.filter((r) => owned.has(r.id)),
    ).map((d) => ({
      run: null,
      app: `${d.repo.ownerName}/${d.repo.name}`,
      who: "the planner",
      on: `#${d.issue.number} ${d.issue.title}`,
      why: "declined",
      state: "waiting for you",
      says: d.words,
      since: d.at,
      costUsd: 0,
    }));
    // An agent's green pull that waits for a person's review (#597): no
    // reviewer on the crew, or one that lapsed — with its age, never silent.
    const ownRepos = repos.filter((r) => owned.has(r.id));
    const reviewWaits = listOpenAgentPullsVisibleTo(ctx.app.db, user, 200)
      .filter((i) => ownRepos.some((r) => r.id === i.repoId))
      .flatMap((issue) => {
        const pull = getPull(ctx.app.db, issue.repoId, issue.number);
        const repo = byId.get(issue.repoId);
        const wait = pull && repo ? waitsForPerson(ctx.app.db, repo.id, pull) : undefined;
        return wait === undefined || repo === undefined
          ? []
          : [
              {
                run: null,
                app: `${repo.ownerName}/${repo.name}`,
                who: "you",
                on: `#${issue.number} ${issue.title}`,
                why: "review",
                state: "waiting for your review",
                says: wait.why === "lapsed" ? "the reviewer did not answer" : "no reviewer on the crew",
                since: wait.since,
                costUsd: 0,
              },
            ];
      });
    return good([
      ...waiting,
      ...reviewWaits,
      ...runs.map((run) => {
        const repo = byId.get(run.repoId)!;
        // As this caller may read it (`runForReader`): cost and node are
        // the owner's facts.
        const r = runForReader(ctx.app, user, repo)(run);
        const issue =
          r.issueId === null
            ? undefined
            : getIssueById(ctx.app.db, r.issueId);
        return {
          run: r.id,
          app: `${repo.ownerName}/${repo.name}`,
          who: (r.actorId && actors.get(r.actorId)?.username) || "the crew",
          on: issue === undefined ? null : `#${issue.number} ${issue.title}`,
          why: r.reason,
          state: r.state,
          since: r.startedAt ?? r.createdAt,
          costUsd: r.costUsd,
          ...(placementWords(r) === "" ? {} : { ran: placementWords(r) }),
        };
      }),
    ]);
  },
};
@@ -0,0 +1,46 @@
import { addTeamMember, createTeam, deleteTeam } from "../../../actions/orgs.ts";
import { getOrg, listTeams, type Permission } from "../../../core/orgs.ts";
import { good, bad, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "org_teams",
  doc: "`{ org, action, team, user?, permission? }` (admin-scope token, an org owner): `create` a team (`permission` read, write or admin; read by default), `add_member` a `user`, or `remove` the team; the same as POST/DELETE `/api/v1/orgs/:org/teams`",
  description: "An organization's teams: create, add a member, remove.",
  inputSchema: {
    type: "object",
    properties: {
      org: { type: "string", maxLength: 64 },
      action: { type: "string", enum: ["create", "add_member", "remove"] },
      team: { type: "string", maxLength: 64 },
      user: { type: "string", maxLength: 64, description: "add_member" },
      permission: { type: "string", enum: ["read", "write", "admin"], description: "create" },
    },
    required: ["org", "action", "team"],
  },
  writes: true,
  needsAdminScope: true,
  run(ctx, user, args) {
    const org = getOrg(ctx.app.db, typeof args["org"] === "string" ? args["org"] : "");
    if (!org) return bad("not_found", "no such organization");
    const name = typeof args["team"] === "string" ? args["team"] : "";
    const action = args["action"];
    if (action === "create") {
      const p = args["permission"];
      const permission: Permission = p === "write" || p === "admin" ? p : "read";
      const made = createTeam(ctx.app, user, org, name, permission);
      return made.ok ? good(made.value) : bad(made.error, made.error);
    }
    const wanted = name.toLowerCase();
    const team = listTeams(ctx.app.db, org.id).find((t) => t.name.toLowerCase() === wanted);
    if (!team) return bad("not_found", "no such team");
    if (action === "add_member") {
      const added = addTeamMember(ctx.app, user, org, team, typeof args["user"] === "string" ? args["user"] : "");
      return added.ok ? good(added.value) : bad(added.error, added.error);
    }
    if (action === "remove") {
      const gone = deleteTeam(ctx.app, user, org, team);
      return gone.ok ? good({ removed: team.name }) : bad(gone.error, gone.error);
    }
    return bad("invalid", "action is create, add_member or remove");
  },
};
@@ -0,0 +1,59 @@
import { scopeAllows } from "../../../core/tokens.ts";
import { deleteOriginApp, listOriginApps, registerOriginApp } from "../../../actions/origins.ts";
import { connectMessage } from "../../api.ts";
import { good, bad, type Tool, str } from "../shared.ts";
export const tool: Tool = {
  name: "origin_apps",
  doc: "`{ action, id?, host?, kind?, clientId?, clientSecret? }`: `list` your OAuth apps for connecting origins, `add` one (a `host`, or `kind` github), or `remove` one by `id`; the API's rules and errors, an admin-scope token; a secret is never read back, only `hasSecret`",
  description:
    "Your origin OAuth apps: list, add, remove.",
  inputSchema: {
    type: "object",
    properties: {
      action: { type: "string" },
      id: { type: "string" },
      host: { type: "string" },
      kind: { type: "string" },
      clientId: { type: "string" },
      clientSecret: { type: "string" },
    },
  },
  writes: true,
  async run(ctx, user, args) {
    if (!scopeAllows(ctx.auth.scope ?? "ro", "admin"))
      return bad("forbidden", "origin apps need an admin-scope token");
    const action = args["action"];
    // Never the secret: an app is shown as `hasSecret`, and errors are codes.
    const shown = (a: ReturnType<typeof listOriginApps>[number]) => {
      const { userId: _owner, ...rest } = a;
      return rest;
    };
    if (action === "list")
      return good({ items: listOriginApps(ctx.app, user).map(shown), next_cursor: null });
    if (action === "add") {
      const kind = str(args["kind"]);
      const clientId = str(args["clientId"]);
      if (kind !== "" && kind !== "github" && kind !== "forgejo" && kind !== "gitea")
        return bad("invalid", "kind is github, forgejo or gitea");
      if (clientId === "") return bad("invalid", "`clientId` is required");
      const host = str(args["host"]) || kind;
      if (host === "") return bad("invalid", "`host` or `kind` is required");
      const secret = args["clientSecret"];
      const saved = await registerOriginApp(ctx.app, user, {
        host,
        ...(kind === "" ? {} : { kind }),
        clientId,
        ...(typeof secret === "string" ? { clientSecret: secret } : {}),
      });
      return saved.ok ? good(shown(saved.value)) : bad(saved.error, connectMessage(saved.error));
    }
    if (action === "remove") {
      const id = str(args["id"]);
      if (id === "") return bad("invalid", "`id` is required");
      const removed = deleteOriginApp(ctx.app, user, id);
      return removed.ok ? good({}) : bad("not_found", "no such origin app");
    }
    return bad("invalid", "`action` is list, add or remove");
  },
};
@@ -0,0 +1,45 @@
import { listRemoteRepos, listUserOrigins, syncOriginNow } from "../../../actions/origins.ts";
import { originJson, remoteRepoJson } from "../../api.ts";
import { ORIGIN_UNREACHABLE } from "../../../actions/origin_app_words.ts";
import { scopeAllows } from "../../../core/tokens.ts";
import { good, bad, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "origins",
  doc: "`{ action, id? }`: `list` your connected origins, `repos` the repositories one holds (`id`; `mirroredAs` says which are already here), or `sync` one now; the same as `GET /api/v1/user/origins`, `…/:id/repos` and `POST …/:id/sync`, for you only, an admin token as there; never a credential in an answer",
  description:
    "Your connected origins: list, repos of one, or sync it.",
  inputSchema: {
    type: "object",
    properties: {
      action: { type: "string", enum: ["list", "repos", "sync"] },
      id: { type: "string" },
    },
    required: ["action"],
  },
  writes: true,
  readsWithout: "id",
  async run(ctx, user, args) {
    const action = args["action"];
    const id = args["id"];
    if (action !== "list" && action !== "repos" && action !== "sync")
      return bad("bad_action", "`action` is list, repos or sync");
    if (action !== "list" && (typeof id !== "string" || id === ""))
      return bad("invalid", "send the origin's `id`, from list");
    if (!scopeAllows(ctx.auth.scope ?? "ro", "admin"))
      return bad("forbidden", "origins spend your credential elsewhere and need an admin token");
    if (action === "list")
      return good(listUserOrigins(ctx.app, user).map(originJson));
    const origin = id as string;
    if (action === "sync") {
      const synced = await syncOriginNow(ctx.app, user, origin);
      return synced.ok ? good(synced.value) : bad("not_found", "no such origin");
    }
    const listed = await listRemoteRepos(ctx.app, user, origin);
    if (!listed.ok)
      return listed.error === "unreachable"
        ? bad("origin_unreachable", ORIGIN_UNREACHABLE)
        : bad("not_found", "no such origin");
    return good(listed.value.map((row) => remoteRepoJson(ctx, row)));
  },
};
@@ -0,0 +1,45 @@
import { scopeAllows } from "../../../core/tokens.ts";
import { DIRECTION_NOTE, directionNote, OUTSIDERS_NOTE } from "../../../crew/direct.ts";
import { setCrewOutsiders } from "../../../actions/repos.ts";
import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "outsiders",
  doc: "`{ repo, on?, dryRun? }`: whether people who cannot write may direct the crew; with `on`, planned first (`dryRun` is true unless `false`); set only by the app's admin with an admin token, never an agent",
  description:
    "Whether people who cannot write an app may direct its crew (off by default). No `on` reads it.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      on: { type: "boolean" },
      dryRun: {
        type: "boolean",
        description: "false to apply",
      },
    },
    required: ["repo"],
  },
  writes: true,
  dryByDefault: true,
  async run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    if (typeof args["on"] !== "boolean")
      return good({ on: repo.crewOutsiders, says: directionNote(repo) });
    const dryRun = args["dryRun"] !== false;
    if (!dryRun && !scopeAllows(ctx.auth.scope ?? "ro", "admin"))
      return bad("forbidden", "setting who directs the crew needs an admin token");
    const set = await setCrewOutsiders(ctx.app, user, repo, args["on"], dryRun);
    if (!set.ok)
      return bad("forbidden", "only an admin of this app sets who directs its crew");
    return good({
      ...set.value,
      says: dryRun
        ? `This is the plan; nothing changed. Outsiders ${set.value.was ? "may" : "may not"} trigger the crew now; send dryRun: false to ${set.value.on ? "let them" : "stop them"}.`
        : set.value.on
          ? OUTSIDERS_NOTE
          : DIRECTION_NOTE,
    });
  },
};
@@ -0,0 +1,20 @@
import { scopeAllows } from "../../../core/tokens.ts";
import { LAST_WAY_IN, parentIssuerOf, unlinkParent } from "../../../core/federation.ts";
import { good, bad, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "parent_unlink",
  doc: "no input: stop signing in through the parent forge, as Settings does; refused when it is the account's last way in, and \"Nothing to unlink.\" when nothing is linked; an admin token",
  description: "Unlink parent-forge sign-in.",
  inputSchema: { type: "object", properties: {} },
  writes: true,
  run(ctx, user) {
    if (!scopeAllows(ctx.auth.scope ?? "ro", "admin")) return bad("forbidden", "unlinking needs an admin token");
    const issuer = parentIssuerOf(ctx.app.config);
    const done = issuer === undefined ? undefined : unlinkParent(ctx.app.db, user.id, issuer);
    if (done === undefined || (done.ok && done.value === "none")) return good({ says: "Nothing to unlink." });
    if (!done.ok) return bad("last_way_in", LAST_WAY_IN);
    ctx.app.bus.append({ kind: "account.parent_unlinked", actorId: user.id });
    return good({ says: "Unlinked." });
  },
};
@@ -0,0 +1,81 @@
import { openPlan, parsePlan, PLAN_MAX, proposePlan } from "../../../actions/plan.ts";
import { good, bad, type Tool, APP_ARG, planRepo, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "plan",
  doc: "`{ app, issues }`: open up to 12 linked issues, all or none (see below)",
  description: `Open and link small issues, all or none (max ${PLAN_MAX}); each has \`pillar\` or \`later: true\` with \`why\`.`,
  inputSchema: {
    type: "object",
    properties: {
      app: APP_ARG,
      title: { type: "string", maxLength: 256 },
      why: { type: "string", maxLength: 65536 },
      issues: {
        type: "array",
        minItems: 1,
        maxItems: PLAN_MAX,
        items: {
          type: "object",
          properties: {
            key: {
              type: "string",
            },
            title: { type: "string" },
            body: { type: "string" },
            blockedBy: {
              type: "array",
              items: { type: ["string", "integer"] },
            },
            pillar: {
              type: "string",
              description: 'Pillar, "P0".',
            },
            later: {
              type: "boolean",
              description: "No pillar; needs why.",
            },
            why: {
              type: "string",
              description: "With later: why.",
            },
          },
          required: ["key", "title"],
        },
      },
    },
    required: ["app", "issues"],
  },
  writes: true,
  run(ctx, user, args) {
    const repo = planRepo(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const items = parsePlan(args["issues"]);
    if (!items.ok) return bad(items.error.error, items.error.message);
    if (repo.plansNeedNod) {
      const proposed = proposePlan(ctx.app, user, repo, items.value, {
        title: args["title"],
        why: args["why"],
      });
      if (!proposed.ok)
        return bad(proposed.error.error, proposed.error.message);
      return good({
        says: `Proposed plan ${proposed.value.id}: nothing is opened until a person nods.`,
        ...proposed.value,
      });
    }
    const planned = openPlan(ctx.app, user, repo, items.value);
    if (!planned.ok) return bad(planned.error.error, planned.error.message);
    const { opened, ready, later, gate } = planned.value;
    const waits =
      gate === undefined
        ? ""
        : ` ${later.map((n) => `#${n}`).join(", ")} wait${later.length === 1 ? "s" : ""} behind the Later gate #${gate}.`;
    return good({
      says: `Opened ${opened.length} issue${opened.length === 1 ? "" : "s"}: ${opened.map((o) => `${o.key} is #${o.number}`).join(", ")}.${waits}`,
      opened,
      ready,
      later,
    });
  },
};
@@ -0,0 +1,23 @@
import { appsRuntime } from "../../../apps/runtime.ts";
import { previewOf } from "../../../apps/preview_view.ts";
import { good, bad, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "preview",
  doc: "`{ url }`: what the forge pill says of an app host's URL (production or a pull's preview): `{ app, environment, pull: { number, title } \\| null, check: \"green\" \\| \"red\" \\| \"running\" \\| null, firstFailure, logUrl, working: [names] }`; `firstFailure` is the check's first failing test or its summary, `logUrl` is set only for someone who may read the log (a writer), `working` names the agents with a run going; a URL that is not one of this forge's app hosts is `invalid`, an app you cannot read is `not_found` and a pull you cannot see is `no_such_pull`, as `repo` and `pull` say",
  description:
    "An app URL's pull, check, first failure, log.",
  inputSchema: {
    type: "object",
    properties: { url: { type: "string" } },
    required: ["url"],
  },
  writes: false,
  run(ctx, user, args) {
    const seen = previewOf(ctx.app, appsRuntime(ctx.app)?.options.domain, user, ctx.url.origin, args["url"]);
    if (seen.ok) return good(seen.value);
    if (seen.error === "foreign") return bad("invalid", "`url` is one of this forge's app hosts");
    if (seen.error === "no_such_pull") return bad("no_such_pull", `no pull #${String(seen.number)}`);
    return bad("not_found", "no such app or repository (owner/name)");
  },
};
@@ -0,0 +1,41 @@
import { appsRuntime } from "../../../apps/runtime.ts";
import { getAppByRepo } from "../../../core/apps.ts";
import { canWrite } from "../../../core/repos.ts";
import { probeApp } from "../../../contract/probes.ts";
import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "probe",
  doc: "knock on a running app's doors as nobody, a user and an admin; the ones that disobey its contract",
  description:
    "Try every door of a running app as nobody, a user and an admin against its contract.json; read-only.",
  inputSchema: {
    type: "object",
    properties: { repo: REPO_ARG },
    required: ["repo"],
  },
  writes: false,
  async run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    if (!canWrite(ctx.app.db, repo, user))
      return bad("forbidden", "you need write access to knock");
    const record = getAppByRepo(ctx.app.db, repo.id);
    const runtime = appsRuntime(ctx.app);
    if (record === undefined || runtime === undefined)
      return bad("not_an_app", "nothing is serving that app here");
    const row = await probeApp(ctx.app, runtime, record);
    if (row === undefined)
      return bad(
        "no_contract",
        "that app has no sound contract to compare with",
      );
    return good({
      verdict: row.verdict,
      commit: row.commitOid,
      said: row.said,
      asked: row.knocks.filter((k) => k.verdict !== "unprobed").length,
      unprobed: row.knocks.filter((k) => k.verdict === "unprobed").length,
    });
  },
};
@@ -0,0 +1,54 @@
import { addPromptSource, listPromptSources, removePromptSource, runPromptSource } from "../../../actions/prompts.ts";
import { good, bad, type Tool, str, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "prompts",
  doc: "`{ repo, action, kind?, token?, at?, id? }`: list, add, run or remove an app's prompt sources (Instagram), as the `…/prompts` API does; the token goes in once and is never shown; listed only for an admin-scope token, and only the repository's admin may use it",
  description:
    "An app's prompt sources (Instagram): list, add (`kind`, `token`, `at`), run or remove (`id`). Repository admin token.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      action: { type: "string", enum: ["list", "add", "run", "remove"] },
      kind: { type: "string", description: "add: instagram" },
      token: { type: "string", description: "add: sealed, never shown again" },
      at: { type: "string", description: "add: HH:MM UTC" },
      id: { type: "string", description: "run, remove" },
    },
    required: ["repo", "action"],
  },
  writes: true,
  needsAdminScope: true,
  async run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const refuse = (error: string) =>
      error === "not_found"
        ? bad("not_found", "no such app or repository (owner/name)")
        : bad(error, error.replaceAll("_", " "));
    const action = args["action"];
    if (action === "list") {
      const listed = listPromptSources(ctx.app, user, repo);
      return listed.ok ? good({ items: listed.value }) : refuse(listed.error);
    }
    if (action === "add") {
      const added = addPromptSource(ctx.app, user, repo, {
        kind: str(args["kind"]),
        token: str(args["token"]),
        at: str(args["at"]),
      });
      return added.ok ? good(added.value) : refuse(added.error);
    }
    const id = str(args["id"]);
    if (action === "run") {
      const ran = await runPromptSource(ctx.app, user, repo, id);
      return ran.ok ? good(ran.value) : refuse(ran.error);
    }
    if (action === "remove") {
      const removed = removePromptSource(ctx.app, user, repo, id);
      return removed.ok ? good({ removed: true }) : refuse(removed.error);
    }
    return bad("bad_action", "`action` is list, add, run or remove");
  },
};
@@ -0,0 +1,39 @@
import { listProposals, mintProposal, repoByName, revokeProposal } from "../../../actions/proposal_tokens.ts";
import { good, bad, type Tool, REPO_ARG } from "../shared.ts";
export const tool: Tool = {
  name: "proposal_tokens",
  description:
    "A child's propose-only credential: `mint` (`child`, `origin`), `list`, `revoke` (`id`). Writers.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      verb: { type: "string", enum: ["mint", "list", "revoke"] },
      child: { type: "string", maxLength: 40 },
      origin: { type: "string", maxLength: 200 },
      childRepo: { type: "string", maxLength: 200 },
      id: { type: "string", maxLength: 80 },
    },
    required: ["repo", "verb"],
  },
  writes: true,
  run(ctx, user, args) {
    const repo = repoByName(ctx.app, args["repo"]);
    const verb = args["verb"];
    const done =
      verb === "mint"
        ? mintProposal(ctx.app, user, repo, {
            child: args["child"],
            origin: args["origin"],
            childRepo: args["childRepo"],
          })
        : verb === "list"
          ? listProposals(ctx.app, user, repo)
          : verb === "revoke"
            ? revokeProposal(ctx.app, user, repo, args["id"])
            : undefined;
    if (done === undefined) return bad("invalid", "verb is mint, list or revoke");
    return done.ok ? good(done.value ?? { ok: true }) : bad(done.error.code, done.error.message);
  },
};
@@ -0,0 +1,36 @@
import { FAMILY_WORDS } from "../../../actions/family_words.ts";
import { proposeToParentForge } from "../../../actions/upstream.ts";
import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "propose_to_parent_forge",
  doc: "`{ repo }`: offer this forge's landed change to its parent as a pull on `child/<name>/…`; the same tip answers with that pull",
  description:
    "Offer this forge's landed change to its parent as a pull on `child/<name>/…`",
  inputSchema: {
    type: "object",
    properties: { repo: REPO_ARG },
    required: ["repo"],
  },
  writes: true,
  async run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const made = await proposeToParentForge(ctx.app, user, repo);
    if (made.ok)
      return good({
        says: made.value.opened
          ? `Proposed to the parent forge as #${made.value.number}.`
          : `Already proposed to the parent forge as #${made.value.number}.`,
        opened: made.value.opened,
        proposal: made.value,
      });
    const e = made.error;
    if (e === "no_parent_forge") return bad(e, "this forge has no parent forge to propose to");
    if (e === "nothing_to_propose") return bad(e, FAMILY_WORDS.nothing_to_propose);
    if (typeof e === "string") return bad(e, "you need write access to propose from here");
    return e.kind === "unreachable"
      ? bad("parent_unreachable", "parent unreachable: nothing was proposed")
      : bad("refused", `the parent forge did not take the proposal: ${e.reason}`);
  },
};
@@ -0,0 +1,68 @@
import { mayView } from "../../../core/sealed.ts";
import { pullProposalOf } from "../../../core/proposal_token.ts";
import { resolveOid } from "../../../git/merge.ts";
import { getPull, pullDir, pullMergeState } from "../../../core/pulls.ts";
import { previewEnv } from "../../../apps/data.ts";
import { checkStale } from "../../../checks/stale.ts";
import { checkSummary } from "../../../core/runs.ts";
import { appView } from "../../../actions/apps.ts";
import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "pull",
  doc: "`{ repo, number }`: a pull's title, state, head and base, and for an open pull whether it merges into the base's current head (`mergeable`) and the paths that stop it (`conflicts`), and `check: { state, baseOid }`: the latest check's state and the base tip it was merged with (empty when it merged nothing); `mergeable` and `conflicts` are the same fields as `GET …/pulls/:number`, `check` is `state` and `run.baseOid` from `GET …/pulls/:number/checks`; draws the `ui://forge/pull` card: `#N title`, state with check and conflicts while open, `head → base` linked to the pull, and the preview link when the pull has an environment",
  description:
    "Read a pull: title, state, head, base; open: `mergeable`, `conflicts`, `proposal`, `checkStale`, `check`.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      number: { type: "integer", minimum: 1 },
    },
    required: ["repo", "number"],
  },
  writes: false,
  async run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const n = args["number"];
    const pull =
      typeof n === "number" && Number.isInteger(n) && n > 0
        ? getPull(ctx.app.db, repo.id, n)
        : undefined;
    if (pull === undefined || !mayView(ctx.app.db, repo, pull, user))
      return bad("no_such_pull", `no pull #${String(n)}`);
    const dir = await pullDir(ctx.app.db, ctx.app.reposRoot, repo, pull);
    const state = await pullMergeState(dir, pull);
    const check = checkSummary(ctx.app.db, pull.id, pull.headOid);
    const stale =
      pull.state === "open" &&
      pull.mergedAt === null &&
      checkStale(check.run, await resolveOid(dir, `refs/heads/${pull.baseBranch}`));
    const answer = good({
      number: pull.number,
      title: pull.title,
      state: pull.mergedAt !== null ? "merged" : pull.state,
      base: pull.baseBranch,
      head: pull.headBranch,
      proposal: pullProposalOf(ctx.app.db, pull.id) ?? null,
      check: { state: check.state, baseOid: check.run?.baseOid ?? "" },
      checkStale: stale,
      ...(state ?? {}),
    });
    // What the card needs and the text does not say: where the pull lives
    // and its preview, only when that environment exists — the pull page's
    // door, `previewCard`, reads the same `appView`.
    const view = appView(ctx.app, user, repo);
    const env = view.ok
      ? view.value.environments.find((e) => e.env === previewEnv(pull.number))
      : undefined;
    return {
      ...answer,
      card: {
        repo: `${repo.ownerName}/${repo.name}`,
        ...(env === undefined ? {} : { preview: env.url }),
      },
    };
  },
};
@@ -0,0 +1,51 @@
import { sealedScope } from "../../../core/sealed.ts";
import { reviewSummariesFor } from "../../../core/reviews.ts";
import { listPulls, pullDir, pullMergeStates } from "../../../core/pulls.ts";
import { checkSummary } from "../../../core/runs.ts";
import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "pulls",
  doc: "`{ repo, state?, limit? }`: a repository's pulls, newest first, one brief line each: `number`, `title`, `author`, `head`, `check` (state), `approvals`, `changesRequested`, `mergeable` (null once closed); `state` open (default) or closed, `limit` 1-50 (default 20); no bodies, no diffs",
  description:
    "A repository's pulls, newest first. `state` open (default) or closed; `limit` 1-50 (default 20).",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      state: { type: "string", enum: ["open", "closed"] },
      limit: { type: "integer", minimum: 1, maximum: 50 },
    },
    required: ["repo"],
  },
  writes: false,
  async run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const state = args["state"] ?? "open";
    if (state !== "open" && state !== "closed")
      return bad("invalid", "`state` is open or closed");
    const limit = args["limit"] ?? 20;
    if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1 || limit > 50)
      return bad("invalid", "`limit` is a whole number from 1 to 50");
    const db = ctx.app.db;
    const pulls = listPulls(db, repo.id, { state, limit, ...sealedScope(db, repo, user) });
    const reviews = reviewSummariesFor(db, pulls);
    const dirs = await Promise.all(
      pulls.map((p) => pullDir(db, ctx.app.reposRoot, repo, p)),
    );
    const merge = await pullMergeStates(pulls.map((pull, i) => ({ dir: dirs[i]!, pull })));
    return good({
      pulls: pulls.map((p, i) => ({
        number: p.number,
        title: p.title,
        author: p.authorName,
        head: p.headBranch,
        check: checkSummary(db, p.id, p.headOid).state,
        approvals: reviews.get(p.id)?.approvals ?? 0,
        changesRequested: reviews.get(p.id)?.changesRequested ?? 0,
        mergeable: merge[i]?.mergeable ?? null,
      })),
    });
  },
};
@@ -0,0 +1,43 @@
import { changeQuotas, readQuotas } from "../../../actions/quotas.ts";
import { QUOTA_KEYS } from "../../../settings/quotas.ts";
import { scopeAllows } from "../../../core/tokens.ts";
import { good, bad, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "quotas",
  description:
    "Per-account repo and app quotas (number or null; unenforced). With `key`, `value` (\"\" clears).",
  inputSchema: {
    type: "object",
    properties: {
      key: { type: "string", enum: [...QUOTA_KEYS] },
      value: { type: "string", maxLength: 16 },
      dryRun: { type: "boolean", description: "false to apply" },
    },
  },
  writes: true,
  dryByDefault: true,
  run(ctx, user, args) {
    const read = readQuotas(ctx.app, user);
    if (!read.ok) return bad("not_found", "no such tool here");
    const key = typeof args["key"] === "string" ? args["key"] : undefined;
    if (key === undefined) return good(read.value);
    const value = typeof args["value"] === "string" ? args["value"] : "";
    if (!(QUOTA_KEYS as readonly string[]).includes(key))
      return bad("no_such_quota", `no quota ${key}`);
    const now = read.value.quotas[key as (typeof QUOTA_KEYS)[number]];
    if (args["dryRun"] !== false)
      return good({
        says: `Would set ${key} from ${now ?? "no limit"} to ${value || "no limit"}. Send dryRun: false to change it.`,
      });
    if (!scopeAllows(ctx.auth.scope ?? "ro", "admin"))
      return bad("forbidden", "changing the forge's quotas needs an admin-scope token");
    const changed = changeQuotas(ctx.app, user, { [key]: value });
    if (!changed.ok)
      return bad(changed.error, "a quota is a positive whole number, or empty for no limit");
    return good({
      says: `${key}: ${now ?? "no limit"} → ${changed.value[key as (typeof QUOTA_KEYS)[number]] ?? "no limit"}.`,
      quotas: changed.value,
    });
  },
};
@@ -0,0 +1,59 @@
import { repoDir } from "../../../git/repos.ts";
import { runGit } from "../../../git/env.ts";
import { isSafeRef, isSafeTreePath } from "../../../git/guard.ts";
import { blobForRender, listTree } from "../../../git/read.ts";
import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "read_file",
  doc: "a file (utf-8, or base64 for binary) or a directory listing at a ref, as GET …/contents",
  description:
    "Read a file or list a directory at a ref (default branch); over 5 MB answers tooLarge.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      path: { type: "string", maxLength: 1024 },
      ref: { type: "string", maxLength: 256 },
    },
    required: ["repo", "path"],
  },
  writes: false,
  async run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const rawRef = args["ref"];
    const rawPath = args["path"];
    if (
      (rawRef !== undefined && typeof rawRef !== "string") ||
      typeof rawPath !== "string"
    )
      return bad("invalid", "path and ref are strings");
    const ref = rawRef || repo.defaultBranch;
    if (!isSafeRef(ref) || (rawPath !== "" && !isSafeTreePath(rawPath)))
      return bad("not_found", "no such path at that ref");
    const dir = repoDir(ctx.app.reposRoot, repo.ownerName, repo.name);
    const spec = rawPath === "" ? ref : `${ref}:${rawPath}`;
    const type = await runGit(["cat-file", "-t", spec], { cwd: dir });
    if (rawPath === "" || (type.ok && type.value === "tree")) {
      const tree = await listTree(dir, ref, rawPath);
      if (!tree.ok) return bad("not_found", "no such path at that ref");
      return good({ type: "dir", ref, path: rawPath, entries: tree.value });
    }
    const blob = await blobForRender(dir, ref, rawPath, 5_000_000);
    if (blob.kind === "missing") return bad("not_found", "no such path at that ref");
    if (blob.kind === "too_large")
      return good({ type: "file", tooLarge: true, size: blob.size });
    const binary = blob.kind === "binary";
    return good({
      type: "file",
      ref,
      path: rawPath,
      size: blob.size,
      encoding: binary ? "base64" : "utf-8",
      content: binary
        ? Buffer.from(blob.body).toString("base64")
        : new TextDecoder().decode(blob.body),
    });
  },
};
@@ -0,0 +1,35 @@
import { provenanceFacts } from "../../../core/provenance.ts";
import { forkParentFor } from "../../../core/repos.ts";
import { audienceFor } from "../../../core/audience.ts";
import { upstreamFacts } from "../../../actions/upstream_follow.ts";
import { good, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "repo",
  doc: "`{ repo }`: one repository's description, visibility, autonomy, `audience { level, sentence }` and `provenance` (where a migrated one came from, `null` when hidden), the same as `GET /api/v1/repos/:owner/:name`",
  description:
    "One repository you can read, as GET /api/v1/repos/:owner/:name.",
  inputSchema: {
    type: "object",
    properties: { repo: REPO_ARG },
    required: ["repo"],
  },
  writes: false,
  run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    return good({
      repo: `${repo.ownerName}/${repo.name}`,
      description: repo.description,
      visibility: repo.visibility,
      autonomy: repo.autonomy,
      audience: audienceFor(ctx.app.db, repo, user),
      provenance: provenanceFacts(
        ctx.app.db,
        repo,
        forkParentFor(ctx.app.db, repo, user),
      ),
      upstream: upstreamFacts(ctx.app.db, repo, user),
    });
  },
};
@@ -0,0 +1,63 @@
import { listLabels } from "../../../core/issues.ts";
import { scopeAllows } from "../../../core/tokens.ts";
import { createLabel, deleteLabel } from "../../../actions/repos.ts";
import { LABEL_WORDS } from "../../../actions/label_words.ts";
import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "repo_labels",
  doc: "`{ repo, action?, name?, color?, id? }`: list (`list`, the default; a read-only token may), create (`create`, `name`, `color` six hex digits) or remove (`remove`, `id`) the repository's labels, as `GET`/`POST …/labels` and `DELETE …/labels/:id`; create and remove need an admin token and a repository admin",
  description:
    "Repo labels: list (default), create, remove (admin token).",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      action: { type: "string" },
      name: { type: "string" },
      color: { type: "string" },
      id: { type: "string" },
    },
    required: ["repo"],
  },
  writes: true,
  // Listing, named or by default, is a read: a read-only token may.
  readsWhen: (args) => args["action"] === undefined || args["action"] === "list",
  run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const action = args["action"] ?? "list";
    if (action === "list") return good({ items: listLabels(ctx.app.db, repo.id) });
    if (action !== "create" && action !== "remove")
      return bad("invalid", "action is list, create or remove");
    // The API asks for an admin token on both routes; so does this.
    if (!scopeAllows(ctx.auth.scope ?? "ro", "admin"))
      return bad("forbidden", "changing labels needs an admin token");
    if (action === "create") {
      const name = args["name"];
      const color = args["color"] ?? "6b7280";
      if (typeof name !== "string" || name.trim() === "" || name.length > 64)
        return bad("invalid", "name is one to 64 characters");
      if (typeof color !== "string" || !/^[0-9a-fA-F]{6}$/.test(color))
        return bad("invalid", "color is six hex digits, like 6b7280");
      const made = createLabel(ctx.app, user, repo, name, color);
      if (!made.ok)
        return bad(
          made.error,
          made.error === "taken"
            ? "A label with that name already exists."
            : made.error === "invalid"
              ? LABEL_WORDS.shape
              : "no such app or repository (owner/name)",
        );
      return good({ says: `Created the label ${made.value.name}.`, label: made.value });
    }
    const id = args["id"];
    if (typeof id !== "string" || id === "" || id.length > 64)
      return bad("invalid", "id is the label's id, from list");
    const gone = deleteLabel(ctx.app, user, repo, id);
    return gone.ok
      ? good({ says: "Removed the label.", removed: id })
      : bad("not_found", "no such label, or you are not this repository's admin");
  },
};
@@ -0,0 +1,40 @@
import { updateRepoSettings } from "../../../actions/repos.ts";
import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "repo_settings",
  doc: "`{ repo, description?, visibility? }` (admin token): change a repository's description and visibility as `PATCH /api/v1/repos/:owner/:name` does, for the same callers (a repository admin); answers `{ repo, description, visibility }`; a visibility other than public or private is `invalid`",
  description:
    "Change a repository's description or visibility, as PATCH /api/v1/repos/:owner/:name (admin token).",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      description: { type: "string", maxLength: 2000 },
      visibility: { type: "string", enum: ["public", "private"] },
    },
    required: ["repo"],
  },
  writes: true,
  needsAdminScope: true,
  async run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const { description, visibility } = args;
    if (description !== undefined && typeof description !== "string")
      return bad("invalid", "description is text");
    if (visibility !== undefined && visibility !== "public" && visibility !== "private")
      return bad("invalid", "visibility is public or private");
    const updated = await updateRepoSettings(ctx.app, user, repo, {
      ...(visibility !== undefined ? { visibility } : {}),
      ...(description !== undefined ? { description } : {}),
    });
    if (!updated.ok)
      return bad(updated.error === "not_found" ? "not_found" : "forbidden", updated.error);
    return good({
      repo: `${updated.value.ownerName}/${updated.value.name}`,
      description: updated.value.description,
      visibility: updated.value.visibility,
    });
  },
};
@@ -0,0 +1,69 @@
import { REPORT_ALREADY_DECIDED } from "../../../actions/origin_app_words.ts";
import { originError } from "../../../web/pages/thread.ts";
import { acceptReport, dismissReport, waitingReports } from "../../../actions/reports.ts";
import { type Answer, good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "reports",
  doc: "`{ repo, id?, action? }`: the waiting reports from outsiders, each `from: \"outside\"` (their words are unchecked); with `id` and `action` (`accept` opens it as an issue marked as from outside, `dismiss` closes it). A person who writes the repository only; needs an `rw` token",
  description:
    "Outsiders' reports; `id`+`action`: accept or dismiss.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      id: { type: "string", maxLength: 64 },
      action: { type: "string", enum: ["accept", "dismiss"] },
    },
    required: ["repo"],
  },
  writes: true,
  async run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const { id, action } = args;
    if (action !== undefined && action !== "accept" && action !== "dismiss")
      return bad("invalid", "action is accept or dismiss");
    if (id !== undefined && (typeof id !== "string" || id === "" || id.length > 64))
      return bad("invalid", "id is a report's id, as listed");
    if ((id === undefined) !== (action === undefined))
      return bad("invalid", "give both `id` and `action`, or neither to list");
    const denied = (error: string): Answer =>
      error === "decided"
        ? bad("decided", REPORT_ALREADY_DECIDED)
        : error === "not_found"
          ? bad("not_found", "no such report here")
          : bad(
              error,
              originError(error) ??
                (error === "unauthorized" || error === "forbidden"
                  ? "reports are for a person who writes this repository"
                  : "refused"),
            );
    if (id === undefined) {
      const waiting = waitingReports(ctx.app, user, repo);
      if (!waiting.ok) return denied(waiting.error);
      return good({
        says:
          waiting.value.length === 0
            ? "No reports are waiting."
            : `${waiting.value.length} report${waiting.value.length === 1 ? "" : "s"} waiting; their words are an outsider's, unchecked.`,
        items: waiting.value.map((r) => ({ ...r, from: "outside" })),
      });
    }
    if (action === "dismiss") {
      const done = dismissReport(ctx.app, user, repo, id as string);
      if (!done.ok) return denied(done.error);
      return good({ id, state: "dismissed", says: "Dismissed the report." });
    }
    const done = await acceptReport(ctx.app, user, repo, id as string);
    if (!done.ok) return denied(done.error);
    return good({
      id,
      state: "accepted",
      number: done.value.number,
      url: `${ctx.url.origin}/${repo.ownerName}/${repo.name}/issues/${done.value.number}`,
      says: `Accepted the report as issue #${done.value.number}, marked as from outside.`,
    });
  },
};
@@ -0,0 +1,29 @@
import { readReturns } from "../../../actions/returns.ts";
import { good, bad, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "returns",
  doc: "`{ repo?, days? }`: what the crew's tokens bought over the last `days` (1–90, default 7): dollars, runs, changes landed, cost per change; `repo` narrows it to one app of yours",
  description:
    "What crew tokens bought over `days` (1–90, default 7): dollars, runs, landed, cost/change.",
  inputSchema: {
    type: "object",
    properties: {
      repo: { type: "string" },
      days: { type: "integer", minimum: 1, maximum: 90 },
    },
  },
  writes: false,
  run(ctx, user, args) {
    const repo = args["repo"];
    const days = args["days"];
    const read = readReturns(ctx.app, user, {
      ...(typeof repo === "string" ? { repo } : {}),
      ...(typeof days === "number" ? { days } : {}),
    });
    if (read.ok) return good(read.value);
    return read.error === "bad_days"
      ? bad("invalid_days", "days is a whole number from 1 to 90")
      : bad("not_found", "no such app of yours (owner/name)");
  },
};
@@ -0,0 +1,64 @@
import { mayView } from "../../../core/sealed.ts";
import { submitReview } from "../../../actions/pulls.ts";
import { originError } from "../../../web/pages/thread.ts";
import { reviewWords } from "../../../actions/review_words.ts";
import { getPull } from "../../../core/pulls.ts";
import { good, bad, type Tool, str, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "review",
  doc: "`{ repo, number, verdict, reason? }`: approve a pull (`approve`) or request changes (`changes`, with a `reason`), as the page does; a writer's or the crew's, and never your own pull",
  description:
    "Approve a pull, or request changes with a `reason` (required for changes); your own pull is refused.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      number: { type: "integer", minimum: 1 },
      verdict: { type: "string", enum: ["approve", "changes"] },
      reason: { type: "string", maxLength: 65536 },
    },
    required: ["repo", "number", "verdict"],
  },
  writes: true,
  async run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const verdict = args["verdict"];
    if (verdict !== "approve" && verdict !== "changes")
      return bad("invalid", "verdict is approve or changes");
    const reason = str(args["reason"]);
    if (verdict === "changes" && reason === "")
      return bad("invalid", "say what to change (reason)");
    const n = args["number"];
    const pull =
      typeof n === "number" && Number.isInteger(n) && n > 0
        ? getPull(ctx.app.db, repo.id, n)
        : undefined;
    if (pull === undefined || !mayView(ctx.app.db, repo, pull, user))
      return bad("no_such_pull", `no pull #${String(n)}`);
    const state = verdict === "approve" ? "approved" : "changes_requested";
    const sent = await submitReview(ctx.app, user, repo, pull, {
      state,
      ...(reason === "" ? {} : { body: reason }),
    });
    if (!sent.ok) {
      const error = sent.error;
      return bad(
        "refused",
        originError(error) ??
          (error === "self_review"
            ? reviewWords.selfReview
            : error === "forbidden"
              ? reviewWords.forbidden
              : error === "body_too_long"
                ? reviewWords.tooLong
                : "That review could not be recorded."),
      );
    }
    return good({
      says: verdict === "approve" ? "Approved." : "Changes requested.",
      url: `/${repo.ownerName}/${repo.name}/pulls/${pull.number}`,
    });
  },
};
@@ -0,0 +1,50 @@
import { runLog } from "../../../actions/runs.ts";
import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "run_log",
  doc: "`{ repo, run, tail? }`: a run's log, or its last `tail` lines (1–2000), with the REST route's access: a hidden log or unreadable repository is not found",
  description:
    "A run's log, or its last `tail` lines, as GET /api/v1/repos/:owner/:name/runs/:id/log.",
  inputSchema: {
    type: "object",
    properties: {
      repo: { ...REPO_ARG, maxLength: 140 },
      run: { type: "string", maxLength: 80 },
      tail: {
        type: "integer",
        minimum: 1,
        maximum: 2000,
      },
    },
    required: ["repo", "run"],
  },
  writes: false,
  run(ctx, user, args) {
    const tail = args["tail"];
    if (
      typeof args["run"] !== "string" ||
      args["run"].length === 0 ||
      args["run"].length > 80 ||
      (tail !== undefined &&
        (typeof tail !== "number" ||
          !Number.isInteger(tail) ||
          tail < 1 ||
          tail > 2000))
    )
      return bad("invalid", "`run` is a run id; `tail` is 1 to 2000 lines");
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const found = runLog(ctx.app, user, repo, args["run"]);
    // A hidden log is not found, as on the REST route.
    if (!found.ok || found.value.logHidden)
      return bad("not_found", "no such run here");
    const all = found.value.lines;
    const lines = tail === undefined ? all : all.slice(-tail);
    return good({
      run: found.value.run.id,
      lines,
      truncated: found.value.truncated || lines.length < all.length,
    });
  },
};
@@ -0,0 +1,44 @@
import { listRepoRuns } from "../../../actions/runs.ts";
import { getIssueById } from "../../../core/issues.ts";
import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "runs",
  doc: "`{ repo, limit? }`: the repository's recent runs, newest first (id, kind, state, issue or pull number, started, ended), 1–50, default 20; read as the runs page reads them",
  description:
    "A repository's runs, newest first: id, kind, state, the issue or pull number, started and ended.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      limit: {
        type: "integer",
        minimum: 1,
        maximum: 50,
        description: "1–50, default 20.",
      },
    },
    required: ["repo"],
  },
  writes: false,
  run(ctx, user, args) {
    const limit = args["limit"] ?? 20;
    if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1 || limit > 50)
      return bad("bad_limit", "limit is a whole number from 1 to 50");
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const runs = listRepoRuns(ctx.app, user, repo, { limit });
    if (!runs.ok) return bad("not_found", "no such app or repository (owner/name)");
    return good({
      runs: runs.value.map((r) => ({
        id: r.id,
        kind: r.kind,
        state: r.state,
        number:
          r.issueId === null ? null : (getIssueById(ctx.app.db, r.issueId)?.number ?? null),
        startedAt: r.startedAt,
        endedAt: r.finishedAt,
      })),
    });
  },
};
@@ -0,0 +1,38 @@
import { mayView } from "../../../core/sealed.ts";
import { addCommentThrough } from "../../../actions/issues.ts";
import { getIssue } from "../../../core/issues.ts";
import { good, bad, type Tool, str, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
export const tool: Tool = {
  name: "say",
  doc: "speak on an issue or a pull; a working builder hears it as its next step",
  description:
    "Say something on an issue or pull. A working builder hears it next; otherwise the next run does.",
  inputSchema: {
    type: "object",
    properties: {
      repo: REPO_ARG,
      number: { type: "integer", minimum: 1 },
      text: { type: "string", maxLength: 8000 },
    },
    required: ["repo", "number", "text"],
  },
  writes: true,
  async run(ctx, user, args) {
    const repo = repoArg(ctx, user, args);
    if (isAnswer(repo)) return repo;
    const issue = getIssue(ctx.app.db, repo.id, Number(args["number"]));
    if (issue === undefined || !mayView(ctx.app.db, repo, issue, user))
      return bad("not_found", "no issue or pull by that number");
    const said = await addCommentThrough(
      ctx.app,
      user,
      repo,
      issue,
      str(args["text"]),
    );
    return said.ok
      ? good({ says: `Said on #${issue.number}.` })
      : bad("refused", "that could not be said here");
  },
};
		@@ -161,6 +161,8 @@ src/
161	161	scope floors, pagination, `securityFloor` — the headers every
162	162	response leaves with), api (every /api/v1 route), server
163	163	(auth resolution, git smart HTTP, web routes, hook socket), sse
	164	mcp (the MCP protocol and dispatch; one file per tool under
	165	mcp/tools/, gathered by a generated index)
164	166	design/ shared design tokens: themes (palettes both surfaces render)
165	167	origins/ other forges as one Provider interface: discover (version-endpoint
166	168	probe), providers/{github,forgejo} (+ http: paging, ETags, rate
		@@ -254,6 +256,9 @@ flag exists only in the stdio dev runner and is never reachable over SSH.
254	256	Describe it in OpenAPI as one file, `contract/openapi/routes/<operationId>.ts`,
255	257	exporting `route`; then `bun scripts/openapi-routes.ts` writes its line in the
256	258	generated index. Never list it by hand.
	259	- Add an MCP tool: one file, `http/mcp/tools/<name>.ts`, exporting `tool`;
	260	then `bun scripts/mcp-tools.ts` writes its line in the index and its row in
	261	docs/MCP.md (docs/MCP.md, "Adding a tool"). Never list it by hand.
257	262	- Add a TUI screen: one file under `tui/screens/`, exporting
258	263	`(f: Session, ctx: Ctx, …) => Screen`. Compose `ui/widgets`; take navigation
259	264	from `screens/common.ts` (`ListState`, `Scroll`, `Filter`, `drawList`,
		@@ -0,0 +1,81 @@
	1	/**
	2	* Writes the MCP tools' generated files from `src/http/mcp/tools/*.ts` (#5924):
	3	*
	4	* - `src/http/mcp/tools/index.ts`: one sorted line per tool file, so a pull
	5	* that adds a tool adds one line and never edits another pull's.
	6	* - the `## Tools` table in `docs/MCP.md`, between its `tools:begin` and
	7	* `tools:end` markers, from each tool's `doc` and `writes`.
	8	*
	9	* bun scripts/mcp-tools.ts write both
	10	* bun scripts/mcp-tools.ts --check exit 1, naming the file, when either is stale
	11	*
	12	* `test/mcp-tools.test.ts` runs the check, so a pull that adds a tool file
	13	* without running this goes red with the command to run.
	14	*/
	15	import { readdirSync, readFileSync, writeFileSync } from "node:fs";
	16	import { join } from "node:path";
	17
	18	const ROOT = join(import.meta.dir, "..");
	19	const DIR = join(ROOT, "src/http/mcp/tools");
	20	const INDEX = join(DIR, "index.ts");
	21	const DOC = join(ROOT, "docs/MCP.md");
	22	const BEGIN = "<!-- tools:begin: generated by `bun scripts/mcp-tools.ts` from each tool's `doc` -->";
	23	const END = "<!-- tools:end -->";
	24
	25	/** The tool files, by name: every `<name>.ts` here but the index. */
	26	export function toolFiles(dir = DIR): string[] {
	27	return readdirSync(dir)
	28	.filter((f) => /^[a-z][a-z0-9_]*\.ts$/.test(f) && f !== "index.ts")
	29	.map((f) => f.slice(0, -3))
	30	.sort();
	31	}
	32
	33	export function indexText(names: readonly string[]): string {
	34	return [
	35	"// Generated by `bun scripts/mcp-tools.ts` from the files beside it; do not edit.",
	36	"// One line per tool, sorted: a new tool is a new file and one new line here.",
	37	...names.map((n) => `export { tool as ${n} } from "./${n}.ts";`),
	38	"",
	39	].join("\n");
	40	}
	41
	42	type Documented = { readonly name: string; readonly doc?: string; readonly writes: boolean };
	43
	44	export function tableText(tools: readonly Documented[]): string {
	45	const rows = [...tools]
	46	.filter((t) => t.doc !== undefined)
	47	.sort((a, b) => a.name.localeCompare(b.name))
	48	.map((t) => `\| \`${t.name}\` \| ${t.doc} \| ${t.writes ? "yes" : ""} \|`);
	49	return [BEGIN, "", "\| tool \| does \| writes \|", "\| ---- \| ---- \| ------ \|", ...rows, "", END].join("\n");
	50	}
	51
	52	/** docs/MCP.md with its table replaced by `table`. */
	53	export function withTable(md: string, table: string): string {
	54	const from = md.indexOf(BEGIN);
	55	const to = md.indexOf(END);
	56	if (from < 0 \|\| to < from) throw new Error(`docs/MCP.md has no ${BEGIN} … ${END} markers`);
	57	return md.slice(0, from) + table + md.slice(to + END.length);
	58	}
	59
	60	if (import.meta.main) {
	61	const check = process.argv.includes("--check");
	62	const stale: string[] = [];
	63	const index = indexText(toolFiles());
	64	if (readFileSync(INDEX, "utf8") !== index) {
	65	stale.push("src/http/mcp/tools/index.ts");
	66	if (!check) writeFileSync(INDEX, index);
	67	}
	68	// After the index is current, so a new file's row is in the table.
	69	const { TOOLS } = await import("../src/http/mcp/tools.ts");
	70	const md = readFileSync(DOC, "utf8");
	71	const doc = withTable(md, tableText(TOOLS));
	72	if (md !== doc) {
	73	stale.push("docs/MCP.md");
	74	if (!check) writeFileSync(DOC, doc);
	75	}
	76	if (check && stale.length > 0) {
	77	console.error(`stale: ${stale.join(", ")}; run \`bun scripts/mcp-tools.ts\``);
	78	process.exit(1);
	79	}
	80	if (!check) console.log(stale.length > 0 ? `wrote ${stale.join(", ")}` : "current");
	81	}
		@@ -0,0 +1,220 @@
	1	import { mayView } from "../../core/sealed.ts";
	2	import { getIssue } from "../../core/issues.ts";
	3	import { canRead, getRepo, type Repo } from "../../core/repos.ts";
	4	import { scopeAllows } from "../../core/tokens.ts";
	5	import { getUserByName, type User } from "../../core/users.ts";
	6	import { applyFleetIds, previewFleetIds } from "../../actions/fleet.ts";
	7	import { KIND_CHIPS, parseChipArgs } from "../../core/feed_chips.ts";
	8	import type { Ctx } from "../context.ts";
	9	import type { BoardError } from "../../actions/boards.ts";
	10	import { BOARD_NOT_SAVED } from "../../actions/board_words.ts";
	11
	12	export type Args = Record<string, unknown>;
	13	export type Answer =
	14	\| { ok: true; value: unknown; card?: Record<string, unknown> }
	15	\| { ok: false; error: string; message: string };
	16
	17	export const good = (value: unknown): Answer => ({ ok: true, value });
	18	export const attachWords = (error: string): string =>
	19	({
	20	forbidden: "attaching a look is for a person who can write this app",
	21	not_open: "only an open pull takes a look",
	22	no_app: "this repository has no app, so its pulls have no looks",
	23	bad_width: "width is phone or desktop",
	24	bad_note: "say what it shows in one line, at most 200 characters (says)",
	25	bad_image: "image must be a PNG or JPEG, base64, that reads",
	26	too_large: "the picture is over 5 MB",
	27	})[error] ?? "refused";
	28
	29	export const bad = (error: string, message: string): Answer => ({
	30	ok: false,
	31	error,
	32	message,
	33	});
	34
	35	export interface Tool {
	36	readonly name: string;
	37	/** Its row in docs/MCP.md's tool table: markdown, one line; absent, the tool has no row yet. */
	38	readonly doc?: string;
		sentinelcrew 19d ago Non-blocking: because `doc` is optional, a new tool file can land with no row in docs/MCP.md, and nothing goes red. 21 tools have no `doc` today (asks*, capacity, flow, quotas, …), the same as on main, so this is not a regression. A follow-up could make `doc` required and give those 21 rows, so the generated table stays complete by construction.
	39	readonly description: string;
	40	readonly inputSchema: Record<string, unknown>;
	41	/** Whether it changes anything: `rw` scope, and said so to the client. */
	42	readonly writes: boolean;
	43	/** Listed, and callable, for a forge admin only. */
	44	readonly adminOnly?: true;
	45	/** Listed, and callable, only with a token of this scope. */
	46	readonly needsAdminScope?: true;
	47	/** With this argument absent the tool only reads, whatever the token. */
	48	readonly readsWithout?: string;
	49	/** A call this accepts only reads, whatever the token. */
	50	readonly readsWhen?: (args: Args) => boolean;
	51	/** A write that only plans (`dryRun` not false) is a read: `ro` may ask. */
	52	readonly dryByDefault?: true;
	53	run(ctx: Ctx, user: User, args: Args): Promise<Answer> \| Answer;
	54	}
	55
	56	/** Whether this caller is shown the tool and may call it: one rule for the manifest and dispatch. */
	57	export const visible = (tool: Tool, ctx: Ctx, user: User): boolean =>
	58	(tool.adminOnly !== true \|\| user.isAdmin) &&
	59	(tool.needsAdminScope !== true \|\| scopeAllows(ctx.auth.scope ?? "ro", "admin"));
	60
	61	/** Whether this call only plans or reads, so a read-only token may make it. */
	62	export const plansOnly = (tool: Tool, args: Args): boolean =>
	63	(tool.dryByDefault === true && args["dryRun"] !== false) \|\|
	64	(tool.readsWithout !== undefined && args[tool.readsWithout] === undefined) \|\|
	65	tool.readsWhen?.(args) === true;
	66
	67	export const CHIP_ARGS = {
	68	hide_kinds: {
	69	type: "array",
	70	items: { type: "string", enum: [...KIND_CHIPS] },
	71	maxItems: 50,
	72	description: "Kinds to hide.",
	73	},
	74	hide_people: {
	75	type: "array",
	76	items: { type: "string", maxLength: 39 },
	77	maxItems: 50,
	78	description: "Usernames to hide.",
	79	},
	80	} as const;
	81
	82	/** The filter a call names, or undefined for the viewer's saved one. */
	83	export function chipArgs(ctx: Ctx, args: Record<string, unknown>) {
	84	return parseChipArgs(args, (name) => {
	85	const who = getUserByName(ctx.app.db, name.trim());
	86	return who && who.kind !== "org" ? who.id : undefined;
	87	});
	88	}
	89
	90	export const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
	91
	92	export const REPO_ARG = { type: "string" } as const;
	93
	94	/** A repository the caller may read, by `owner/name`; a wrong one is answered with that form. */
	95	export function repoArg(ctx: Ctx, user: User, args: Args): Repo \| Answer {
	96	const [owner, name, ...rest] = str(args["repo"]).split("/");
	97	const repo =
	98	owner && name && rest.length === 0
	99	? getRepo(ctx.app.db, owner, name)
	100	: undefined;
	101	// One answer for "no such repository" and "not yours to see".
	102	return repo !== undefined && canRead(ctx.app.db, repo, user)
	103	? repo
	104	: bad("not_found", "no such app or repository (owner/name)");
	105	}
	106
	107	export const MAX_ARCHIVE_REPOS = 50;
	108
	109	/** `archive` over `repos`: the fleet's own operation, each row's outcome and the id to undo. */
	110	export async function archiveMany(ctx: Ctx, user: User, args: Args): Promise<Answer> {
	111	const names = args["repos"];
	112	if (
	113	!Array.isArray(names) \|\|
	114	names.length === 0 \|\|
	115	names.length > MAX_ARCHIVE_REPOS \|\|
	116	names.some((n) => typeof n !== "string")
	117	)
	118	return bad("invalid", `\`repos\` is one to ${MAX_ARCHIVE_REPOS} names, owner/name each`);
	119	if (args["repo"] !== undefined)
	120	return bad("invalid", "give `repo` or `repos`, not both");
	121	if (args["archived"] !== undefined && typeof args["archived"] !== "boolean")
	122	return bad("invalid", "`archived` is true or false");
	123	const archived = args["archived"] ?? true;
	124	const dryRun = args["dryRun"] !== false;
	125	if (user.kind === "agent")
	126	return bad("forbidden", "archiving or waking is a person's call, not an agent's");
	127	if (!dryRun && !scopeAllows(ctx.auth.scope ?? "ro", "admin"))
	128	return bad("forbidden", "archiving or waking needs an admin token");
	129	const ids: string[] = [];
	130	const missing: string[] = [];
	131	for (const name of new Set(names as string[])) {
	132	const repo = repoArg(ctx, user, { repo: name });
	133	if (isAnswer(repo)) missing.push(name);
	134	else ids.push(repo.id);
	135	}
	136	const query = `mcp: ${ids.length + missing.length} named`;
	137	const action = { verb: "archive", value: archived };
	138	const unknown = missing.map((repo) => ({
	139	repo,
	140	outcome: "refused",
	141	reason: "no such app or repository (owner/name)",
	142	}));
	143	const rowsOf = (rows: readonly { label: string; outcome: string; reason: string }[]) => [
	144	...rows.map((r) => ({ repo: r.label, outcome: r.outcome, reason: r.reason })),
	145	...unknown,
	146	];
	147	if (dryRun) {
	148	const plan = previewFleetIds(ctx.app, user, "repo", ids, query, action);
	149	if (!plan.ok) return bad(plan.error.code, plan.error.message);
	150	return good({
	151	dryRun: true,
	152	archived,
	153	rows: rowsOf(plan.value.rows),
	154	says: "This is the plan; nothing changed. Send dryRun: false to do it.",
	155	});
	156	}
	157	const op = await applyFleetIds(ctx.app, user, "repo", ids, query, action);
	158	if (!op.ok) return bad(op.error.code, op.error.message);
	159	return good({
	160	dryRun: false,
	161	archived,
	162	operation: op.value.id,
	163	rows: rowsOf(op.value.rows),
	164	says: `Done. The \`limb\` tool with action undo and operation ${op.value.id} reverts it for 24 hours.`,
	165	});
	166	}
	167
	168	// tools/list is held under 40 KB (test/mcp-size.test.ts). The server checks
	169	// every length at the boundary, so the listing leaves the maxLength hints out.
	170	export function lean(schema: unknown): unknown {
	171	if (Array.isArray(schema)) return schema.map(lean);
	172	if (schema === null \|\| typeof schema !== "object") return schema;
	173	return Object.fromEntries(
	174	Object.entries(schema).filter(([k]) => k !== "maxLength").map(([k, v]) => [k, lean(v)]),
	175	);
	176	}
	177
	178	export const APP_ARG = { type: "string" } as const;
	179
	180	// A child's claim link is a live secret: whoever holds it takes the child.
	181	// It stays out of an agent's conversation unless asked for there on purpose
	182	// (#839); a person admin of this forge gets a fresh one on /forges, in their
	183	// own browser, and hands it over.
	184	export const REVEAL_ARG = {
	185	type: "boolean",
	186	description:
	187	"true: show the secret link.",
	188	} as const;
	189	export const LINK_KEPT =
	190	"The claim link is a secret, so it is not in this conversation: a person admin of this forge gets a fresh one on /forges (Send a fresh link) and hands it to the child's person. Send reveal: true only to have it here on purpose.";
	191	export const LINK_REVEALED =
	192	"claimUrl is a live secret, now in this conversation: whoever holds it takes the child. Hand it only to the child's person; the secret is in its #fragment, so send it whole.";
	193
	194	/** The app a plan tool names, under `app`, read like any repository. */
	195	export const planRepo = (ctx: Ctx, user: User, args: Args): Repo \| Answer =>
	196	repoArg(ctx, user, { repo: args["app"] });
	197
	198	/** The issue a plan tool names by number, in that repository. */
	199	export function issueArg(ctx: Ctx, repo: Repo, args: Args, key: string) {
	200	const n = args[key];
	201	const issue =
	202	typeof n === "number" && Number.isInteger(n) && n > 0
	203	? getIssue(ctx.app.db, repo.id, n)
	204	: undefined;
	205	// A sealed report is not there for anyone who may not see it.
	206	return issue !== undefined && mayView(ctx.app.db, repo, issue, ctx.auth.user)
	207	? issue
	208	: bad("no_such_issue", `no issue #${String(n)}`);
	209	}
	210
	211	export const isAnswer = (v: Repo \| Answer): v is Answer => "ok" in v;
	212
	213	/** Boards are a forge admin's who is a person, as the API gates them: anyone else is forbidden, not told what is there. */
	214	export const boardRefused = (): Answer => bad("forbidden", "boards are for a forge admin who is a person");
	215	export const mayBoards = (user: User): boolean => user.isAdmin && user.kind !== "agent";
	216	export function boardFailed(e: BoardError): Answer {
	217	if (e === "not_found") return bad("not_found", "no such board");
	218	if (typeof e === "object") return bad("refused", e.refused);
	219	return bad(e, BOARD_NOT_SAVED);
	220	}
		@@ -0,0 +1,9 @@
	1	/**
	2	* Every MCP tool but `report`, by name: one file each under `tools/`,
	3	* gathered by the generated `tools/index.ts` (`bun scripts/mcp-tools.ts`).
	4	* A new tool is a new file there, so pulls adding tools do not collide (#5924).
	5	*/
	6	import type { Tool } from "./shared.ts";
	7	import * as each from "./tools/index.ts";
	8
	9	export const TOOLS: readonly Tool[] = Object.values(each).sort((a, b) => a.name.localeCompare(b.name));
		@@ -0,0 +1,32 @@
	1	import { listAccess } from "../../../actions/access_log.ts";
	2	import { good, bad, type Tool } from "../shared.ts";
	3
	4	export const tool: Tool = {
	5	name: "access",
	6	doc: "`{ since?, ua?, path? }`: what outside agents tried: the redacted log of non-browser requests to public paths, newest first; `since` an ISO time (default a day, at most 14 days), `ua` part of the user agent, `path` a prefix; a forge admin's",
	7	description:
	8	"Non-browser public-path requests, redacted, newest first (max 500). Forge admin.",
	9	inputSchema: {
	10	type: "object",
	11	properties: {
	12	since: { type: "string", maxLength: 40, description: "ISO time." },
	13	ua: { type: "string", maxLength: 100, description: "User agent part." },
	14	path: { type: "string", maxLength: 200, description: "Path prefix." },
	15	},
	16	},
	17	writes: true,
	18	run(ctx, user, args) {
	19	const text = (k: string): string \| undefined =>
	20	typeof args[k] === "string" && args[k] !== "" ? (args[k] as string) : undefined;
	21	const since = text("since");
	22	const ua = text("ua");
	23	const path = text("path");
	24	const listed = listAccess(ctx.app, user, {
	25	...(since === undefined ? {} : { since: since.slice(0, 40) }),
	26	...(ua === undefined ? {} : { ua: ua.slice(0, 100) }),
	27	...(path === undefined ? {} : { path: path.slice(0, 200) }),
	28	});
	29	if (!listed.ok) return bad("not_found", "no such tool here");
	30	return good({ requests: listed.value });
	31	},
	32	};
		@@ -0,0 +1,52 @@
	1	import { SPEND_WORDS } from "../../../actions/spend_words.ts";
	2	import { setRole } from "../../../actions/roles.ts";
	3	import { scopeAllows } from "../../../core/tokens.ts";
	4	import { good, bad, type Tool, mayBoards } from "../shared.ts";
	5
	6	export const tool: Tool = {
	7	name: "account_role",
	8	doc: "`{ username, role, usdPerMonth?, dryRun? }`: make a person a `member`, or a `guest` again, with an optional starter allowance (`usdPerMonth`, 0.01 to 10000, promoting only); planned first (`dryRun` is true unless `false`)",
	9	description:
	10	"Make a person a member, or a guest again; promoting may give a monthly `usdPerMonth` allowance.",
	11	inputSchema: {
	12	type: "object",
	13	properties: {
	14	username: { type: "string" },
	15	role: { type: "string", enum: ["member", "guest"] },
	16	usdPerMonth: { type: ["number", "null"], description: "0.01–10000 or none." },
	17	dryRun: { type: "boolean", description: "false to apply" },
	18	},
	19	required: ["username", "role"],
	20	},
	21	writes: true,
	22	dryByDefault: true,
	23	run(ctx, user, args) {
	24	const { username, role, usdPerMonth } = args;
	25	if (
	26	typeof username !== "string" \|\|
	27	(role !== "member" && role !== "guest") \|\|
	28	!(usdPerMonth === undefined \|\| usdPerMonth === null \|\| (typeof usdPerMonth === "number" && Number.isFinite(usdPerMonth)))
	29	)
	30	return bad("invalid", 'send a username and a role, "member" or "guest"');
	31	if (!mayBoards(user)) return bad("forbidden", "a role is a forge admin's to set");
	32	const usd = typeof usdPerMonth === "number" ? usdPerMonth : null;
	33	if (args["dryRun"] !== false)
	34	return good({
	35	username,
	36	role,
	37	usdPerMonth: usd,
	38	says: "This is the plan; nothing changed. Send dryRun: false to set it.",
	39	});
	40	if (!scopeAllows(ctx.auth.scope ?? "ro", "admin"))
	41	return bad("forbidden", "a role needs an admin token");
	42	const set = setRole(ctx.app, user, username, role, usd);
	43	if (!set.ok)
	44	return bad(
	45	set.error === "invalid_amount" ? "invalid" : "forbidden",
	46	set.error === "invalid_amount"
	47	? SPEND_WORDS.usdPerMonth
	48	: "no such person, or not one a role is for",
	49	);
	50	return good(set.value);
	51	},
	52	};
		@@ -0,0 +1,32 @@
	1	import { suspendAccount, unsuspendAccount } from "../../../actions/accounts.ts";
	2	import { scopeAllows } from "../../../core/tokens.ts";
	3	import { lastOwnerSays } from "../../../core/orgs.ts";
	4	import { ADMIN_WORDS } from "../../../actions/admin_words.ts";
	5	import { good, bad, type Tool, mayBoards } from "../shared.ts";
	6
	7	export const tool: Tool = {
	8	name: "account_suspend",
	9	doc: "`{ username, suspended }`: suspend a person's account, or unsuspend it with `false`; their sessions and tokens stop at once; the API's rules (not yourself, another admin or an agent; not the only owner of an organization); an admin token",
	10	description: "Suspend an account, or `suspended: false` to lift it.",
	11	inputSchema: {
	12	type: "object",
	13	properties: { username: { type: "string" }, suspended: { type: "boolean" } },
	14	required: ["username", "suspended"],
	15	},
	16	writes: true,
	17	async run(ctx, user, args) {
	18	const { username, suspended } = args;
	19	if (typeof username !== "string" \|\| typeof suspended !== "boolean")
	20	return bad("invalid", "send a username and suspended, true or false");
	21	if (!mayBoards(user)) return bad("forbidden", "an account is a forge admin's to suspend");
	22	if (!scopeAllows(ctx.auth.scope ?? "ro", "admin"))
	23	return bad("forbidden", "suspending needs an admin token");
	24	const done = suspended
	25	? await suspendAccount(ctx.app, user, username)
	26	: unsuspendAccount(ctx.app, user, username);
	27	if (done.ok) return good({ username: done.value.username, suspendedAt: done.value.suspendedAt });
	28	if (done.error === "not_found") return bad("not_found", "no such person");
	29	if (done.error === "last_owner") return bad("last_owner", lastOwnerSays(ctx.app.db, username));
	30	return bad("not_allowed", ADMIN_WORDS.selfSuspend);
	31	},
	32	};
		@@ -0,0 +1,27 @@
	1	import { verifyAccount } from "../../../actions/accounts.ts";
	2	import { scopeAllows } from "../../../core/tokens.ts";
	3	import { good, bad, type Tool, mayBoards } from "../shared.ts";
	4
	5	export const tool: Tool = {
	6	name: "account_verify",
	7	doc: "`{ username }`: mark a person's email verified, as `POST …/admin/accounts/:username/verify` does; a person admin's, with an admin token",
	8	description: "Mark a person's email verified (admin).",
	9	inputSchema: {
	10	type: "object",
	11	properties: { username: { type: "string" } },
	12	required: ["username"],
	13	},
	14	writes: true,
	15	run(ctx, user, args) {
	16	const { username } = args;
	17	if (typeof username !== "string") return bad("invalid", "send a username");
	18	if (!mayBoards(user)) return bad("forbidden", "verifying a person is a forge admin's call");
	19	if (!scopeAllows(ctx.auth.scope ?? "ro", "admin"))
	20	return bad("forbidden", "verifying a person needs an admin token");
	21	const done = verifyAccount(ctx.app, user, username);
	22	if (done.ok) return good({ username: done.value.username, verified: true });
	23	return done.error === "not_found"
	24	? bad("not_found", "no such account")
	25	: bad("invalid", "an agent or a removed account has no email to verify");
	26	},
	27	};
		@@ -0,0 +1,63 @@
	1	import { createAgent, deleteAgent, updateAgent } from "../../../actions/crew.ts";
	2	import type { Agent } from "../../../core/agents.ts";
	3	import { good, bad, type Tool, str } from "../shared.ts";
	4
	5	export const tool: Tool = {
	6	name: "agent",
	7	doc: "`{ action, username, … }`: `create` a crew agent, `update` its `model`, `brief` or `budgetUsd`, or `remove` it; an admin's, with an `admin` token, as `/api/v1/agents`",
	8	description: "Admin: create\|update\|remove an agent.",
	9	inputSchema: {
	10	type: "object",
	11	properties: {
	12	action: { type: "string" },
	13	username: { type: "string" },
	14	displayName: { type: "string" },
	15	model: { type: "string" },
	16	brief: { type: "string" },
	17	budgetUsd: { type: "number" },
	18	},
	19	required: ["action", "username"],
	20	},
	21	writes: true,
	22	adminOnly: true,
	23	needsAdminScope: true,
	24	async run(ctx, user, args) {
	25	const username = str(args["username"]);
	26	const model = args["model"];
	27	const brief = args["brief"];
	28	const budgetUsd = args["budgetUsd"];
	29	const fields = {
	30	...(typeof model === "string" ? { model } : {}),
	31	...(typeof brief === "string" ? { brief } : {}),
	32	...(typeof budgetUsd === "number" ? { budgetUsd } : {}),
	33	};
	34	const shown = (a: Agent) => ({
	35	username: a.user.username,
	36	displayName: a.user.displayName,
	37	model: a.model,
	38	brief: a.brief,
	39	budgetUsd: a.budgetUsd,
	40	createdAt: a.createdAt,
	41	});
	42	const action = args["action"];
	43	if (action === "create") {
	44	const made = await createAgent(ctx.app, user, {
	45	username,
	46	...(typeof args["displayName"] === "string"
	47	? { displayName: args["displayName"] }
	48	: {}),
	49	...fields,
	50	});
	51	return made.ok ? good(shown(made.value)) : bad(made.error, made.error);
	52	}
	53	if (action === "update") {
	54	const done = updateAgent(ctx.app, user, username, fields);
	55	return done.ok ? good(shown(done.value)) : bad(done.error, done.error);
	56	}
	57	if (action === "remove") {
	58	const gone = deleteAgent(ctx.app, user, username);
	59	return gone.ok ? good({ removed: username }) : bad(gone.error, gone.error);
	60	}
	61	return bad("invalid", "action is create, update or remove");
	62	},
	63	};
		@@ -0,0 +1,37 @@
	1	import { redeployEnv, stopEnv } from "../../../actions/apps.ts";
	2	import { good, bad, type Tool, str, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
	3
	4	export const tool: Tool = {
	5	name: "app_deploy",
	6	doc: "`{ repo, env, action }`: `redeploy` or `stop` an app's `production` or a pull's `pull-N` preview; a writer's, queued as `POST …/app/:env/redeploy` and `…/stop` are; answers `{ queued, run }` or `{ stopped }`",
	7	description:
	8	"Redeploy or stop production or a pull-N preview.",
	9	inputSchema: {
	10	type: "object",
	11	properties: {
	12	repo: REPO_ARG,
	13	env: { type: "string" },
	14	action: { type: "string", enum: ["redeploy", "stop"] },
	15	},
	16	required: ["repo", "env", "action"],
	17	},
	18	writes: true,
	19	async run(ctx, user, args) {
	20	const repo = repoArg(ctx, user, args);
	21	if (isAnswer(repo)) return repo;
	22	const env = str(args["env"]);
	23	const action = str(args["action"]);
	24	if (action !== "redeploy" && action !== "stop")
	25	return bad("invalid_action", "action is redeploy or stop");
	26	if (action === "stop") {
	27	const stopped = await stopEnv(ctx.app, user, repo, env);
	28	return stopped.ok
	29	? good({ stopped: true })
	30	: bad(stopped.error, `refused: ${stopped.error}`);
	31	}
	32	const queued = await redeployEnv(ctx.app, user, repo, env);
	33	return queued.ok
	34	? good({ queued: true, run: queued.value?.id ?? null })
	35	: bad(queued.error, `refused: ${queued.error}`);
	36	},
	37	};