Public: anyone can read this; the crew can change it.

A refusal leads somewhere: a link to the exact control for the reader who can change it, one button that asks whoever can for the one who cannot #12953

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

trevato/refusals-lead-somewhere → main 1 commit 1 thread · 1 unresolved

  • Merged. trevato/refusals-lead-somewhere was merged into main as c0f6f92.

Review

Sign in to review this change.
75 files changed +1588 −165
docs/features/blocked-by.md +38 −12
@@ -27,21 +27,47 @@ blockedBy({
2727
2828 A button on a page posts the ask as a form to the page's own route, with the action's `body` as its fields, so the page and the agent cannot drift.
2929
30 ## Asking whoever can
31
32 A reader who cannot change it is offered one action, and there are two, by who holds the control:
33
34 - **The host of this forge** (a name its gate has not opened): `POST /api/v1/reach/asks`, `docs/features/ask-to-reach.md`.
35 - **An admin of this forge, or of one repository**: `POST /api/v1/asks/admin { want, subject }` (`src/actions/ask_admin.ts`). `want` is one of a fixed list (`WANTS`, `src/actions/blocked_words.ts`): a model grant, a model account, a spend ceiling, a model key, a private destination, an email verified, membership, the telemetry grant, an agent, a repository's crew. Each names the exact control, with the page's own anchor on the field (`/settings/accounts/bob#f-grant`, `/settings/crew#crew-key`).
36
37 What happens when a person presses the button:
38
39 1. One row is kept (`admin_ask`): who, what, for which account or repository. A repeat is the same ask.
40 2. The one who answers sees it on their home page's line: "bob asks for a model grant for bob (2 minutes ago)", linked to the control, with **Not now** beside it. A forge admin sees the forge's asks; a repository's admin sees that repository's.
41 3. When the thing is there (the grant exists, the key is saved, the email is verified) the ask is done by itself. `GET /api/v1/asks/admin` is how the asker, or an agent, reads how it stands.
42
43 On a page the button is `askButton` (`src/web/blocked.ts`): it submits one hidden form the layout draws for every signed-in reader, so it works inside a paragraph, a flash or another form. An API answer carries `blockedFields`; an MCP refusal is built with `badBlocked` and carries the same fields as `structuredContent`.
44
45 ## A sentence stored before its reader is known
46
47 A run's summary, a park comment and a log line are read by anyone. They are stored as the sentence and who can, in words (`storedText`: "This forge has no model key. An admin of this forge can add one."), never a path or a key name. A surface that knows its reader calls `wayIn(app, reader, text)` and draws the link or the button from it: the run's page does.
48
3049 ## Where it is used
3150
32 - A hosted forge refused by its host's gate (`gateBlocked`, `src/actions/ask_host.ts`; `docs/features/ask-to-reach.md`). The reader cannot change the host's list, so the action asks the host.
33 - No agents on this forge (`noAgentsBlocked`, `src/actions/blocked_words.ts`): the crew settings of a repository, New app and Migrate said it three ways and now say it one way.
34 - This forge sends no mail (`noMailBlocked`): the resend on Settings and `POST /api/v1/user/email/verify`.
51 - Model keys, grants, accounts, ceilings and budgets: a run's stop (`src/crew/runner.ts`, `forge_budget.ts`, `src/core/account_ceiling.ts`, `subscriptions.ts`), the key card on every page that draws it, "Land it as it is", Settings → Connect your AI, and talking to the forge's agent (page, API, MCP `say`).
52 - A private destination an app asks for: both rows on the app's settings, and the gate's own refusal.
53 - Mail: no mail, and the day's mail spent (the resend on Settings, the API, MCP `email_verify`).
54 - A guest proposing a change (membership), no agents on this forge, the telemetry grant (MCP `flow`, `system`, `telemetry_history`), a repository's crew (MCP `crew`).
55 - A hosted forge refused by its host's gate (`gateBlocked`).
3556
36 ## What is left
57 ## What is held
3758
38 There is no action yet by which a person asks the admin of their own forge for something: the two uses above name who can and stop there. That action is the next step, and most of the sentences below wait on it.
59 `test/refusals-lead-somewhere.test.ts` reads every sentence in `src/` that tells its reader to ask someone or says someone else must act. A new one that is not built by the helper fails. Three kinds are allowed, each written down there:
3960
40 These still tell the reader that an admin, an owner or a site admin must do something, with no link for the reader who can and no ask for the one who cannot (67 places, found by reading `src/` for "an admin can", "ask an admin", "ask its owner", "only a site admin" and the like):
61 - **A role statement** ("Only a forge admin sets a budget."): the reader tried another role's act on a door that could not hide it. Nothing is set to let them, so nothing is linked.
62 - **Terminal**, each with its reason: the reader is signed out, the owner is on another host, or the sentence already gives the reader's own way through.
63 - **Waiting**, each with what it waits on: the terminal's row for a private destination, a lost note (no control restores one), a run's ungranted secret, and a hosted forge's lent credit (the host takes no ask for it yet).
4164
42 - **Model budget and grants** (a crew run stops on these, so they are read most): `src/core/account_ceiling.ts:130`, `:136`; `src/core/subscriptions.ts:665`; `src/core/model_grant.ts:153`; `src/crew/forge_budget.ts:81`; `src/crew/runner.ts:284`, `:821`, `:825`, `:1405`; `src/crew/wake.ts:30`; `src/actions/talk.ts:27`; `src/tui/screens/crewbudgets.ts:38`; `src/spawn/credit.ts:109` (a hosted forge's lent credit: the same ask-the-host shape as ask to reach).
43 - **A crew key only an admin adds**: `src/web/studio/crew_key.ts:110`, `:116`, `:124`; `src/web/studio/land_as_is.ts:61`.
44 - **An app's private destination** (a repository's admin reads it, a site admin grants it): `src/apps/egress.ts:430`, `:467`; `src/core/egress_grants.ts:93`; `src/web/studio/blocked.ts:19`; `src/web/pages/settings.ts:1325`, `:1361`, `:1374`, `:1405`, `:1430`; `src/web/pages/search.ts:637`; `src/tui/screens/blocked.ts:26`, `:56`.
45 - **Accounts, links and mail**: `src/actions/verify_words.ts:22`; `src/web/pages/account.ts:358`; `src/actions/account_access.ts:71`; `src/web/pages/passkeys.ts:359`; `src/actions/spawn.ts:752`; `src/web/pages/pricing.ts:52`, `:207`; `src/tui/screens/pricing.ts:148`; `src/settings/signup.ts:19`; `src/actions/first_admin.ts:51`.
46 - **Admin-only settings named without a link**: `src/core/tokens.ts:19`; `src/core/roles.ts:56`; `src/core/capacity.ts:439`; `src/core/everyday.ts:91`; `src/settings/plans.ts:34`; `src/web/settings/plans.ts:43`; `src/spawn/plan.ts:32`; `src/spawn/door.ts:433`; `src/actions/admin_words.ts:9`; `src/actions/follow_sources.ts:41`; `src/actions/migrate.ts:276`; `src/actions/cut_wave.ts:45`; `src/actions/order.ts:37`; `src/web/pages/hooks.ts:47`; `src/http/mcp/trusted_hosts.ts:10`, `:19`; `src/http/mcp/tools/profile.ts:9`; `src/system/telemetry.ts:276`; `src/http/respond.ts:50`; `src/http/api.ts:885`.
47 - **In the terminal**: `src/tui/screens/domains.ts:56`; `src/tui/screens/front.ts:89`, `:105`; `src/tui/screens/labels.ts:25`; `src/tui/screens/packrepos.ts:38`; `src/tui/screens/people.ts:104`; `src/tui/screens/trustedhosts.ts:21`.
65 `test/ask-admin.test.ts` opens every control as the one who can and finds the field the link names, and sends every ask as one who cannot.
66
67 ## A setting that does not lift the refusal
68
69 Found while wiring the links, and not changed here:
70
71 - Talking to the forge's agent refuses "no model account" from subscription grants alone (`pickSubscription`). A model grant in dollars, which is what an admin gives on an account's page and what a crew run accepts, does not lift it. The ask therefore points at Settings → Subscriptions, not at the account's grant.
72 - The crew's limits (`/settings/crew#budgets`) are drawn only on a forge another one hosts, which is also the only place they stop a run, so the link is right where the sentence can appear and nowhere else.
73 - The telemetry grant can be given to an agent only, so a person is told who reads those figures and is offered no ask.
docs/features/org-model-grant.md +3 −2
@@ -1,8 +1,9 @@
11 # An org's model account
22
33 A new organization has no model account, so its crew runs refuse with
4 "the account `<org>` has no model grant; an admin can grant one at
5 /settings/accounts/<org>".
4 "The account `<org>` has no model grant. An admin of this forge can grant one."
5 The run's page links an admin to `/settings/accounts/<org>#f-grant`, and offers
6 anyone else the button that asks one (`docs/features/blocked-by.md`).
67
78 A forge admin grants it there (the "Model budget" card), or with
89 `POST /api/v1/admin/accounts/<org>/model-grant {"usdPerMonth": 20}` (0 or null
docs/features/own-forge-budgets.md +1 −1
@@ -2,7 +2,7 @@
22
33 A forge that is its owner's own (a hosted child) runs its crew on the key its owner added, and on limits its owner sets.
44
5 - **Key.** Add one from the first screen (or `/settings/crew/key`, or the terminal's crew-key screen). Every repository on the forge uses it; no grant on any other forge is consulted, and nothing says "ask an admin". Until the forge has a key, a run stops with "This forge has no model key: add yours at /settings/crew" and its issue is parked.
5 - **Key.** Add one from the first screen (or `/settings/crew/key`, or the terminal's crew-key screen). Every repository on the forge uses it; no grant on any other forge is consulted, and nothing says "ask an admin". Until the forge has a key, a run stops with "This forge has no model key. An admin of this forge can add one." (the run's page links an admin to `/settings/crew#crew-key`) and its issue is parked.
66 - **Budgets.** Settings → Crew → Budgets (`/settings/crew#budgets`, admin only), or the terminal's "Crew budgets" screen (palette entry, forge admins who are people only; j/k choose, enter types dollars), hold spend per run, per UTC day and per UTC month, with what was spent against the day and the month. Defaults: $5 a run, $50 a day, $500 a month. A run a limit stops says which one and links back to that setting. Day and month count the agent runs in the usage ledger (conversations are not counted).
77 - **A ceiling, not a hint.** A run reserves its cap against the day and the month when it starts (`ceiling_reserved_usd` on the run, the column the account ceilings use), so agents starting together share what is left; the reservation goes when the run leaves queued/running. A run cut off mid-way at a cap one of these limits set says which limit in its summary. One thing can still overshoot: a conversation is not counted, and a run's last call may finish a little past its cap, as with every cap on the forge.
88 - **Picked back up.** Adding a key comments once on each open issue whose newest park was for "no model key", "no model account" or "no model grant"; raising a limit does the same for issues a limit of the owner's stopped (`src/crew/wake.ts`, at most 200 issues a wake, found by a query over park notes and not by walking every repository). The comment is in the admin's name; a person's word restarts the park count, so the crew tries the issue again on its next pass. A sealed issue's comment is seen only where the issue is. The owner is told "3 issues picked back up".
src/actions/ask_admin.ts added +204
@@ -0,0 +1,204 @@
1 /**

No terminal door for this action (nothing in src/tui/). Add the screen, with its entry where AGENTS.md says, so the terminal can ask and answer too.

2 * A person asks whoever can change something to change it
3 * (`docs/features/blocked-by.md`). It is the forge's own half of "ask the
4 * host" (`ask_host.ts`): the same `Blocked` value offers it, a repeat is the
5 * same ask, and the one who answers sees it on the home's line with the link
6 * to the exact control.
7 *
8 * - `askAdmin` records the ask. Anyone signed in may ask; what they may ask
9 * for is the fixed list in `blocked_words.ts`, and the subject is checked
10 * (an account that exists, a repository the asker can see).
11 * - `asksToAnswer` is what waits on a viewer: the forge's asks for a forge
12 * admin, a repository's for its admins. An ask whose thing is now there is
13 * finished by itself (`met`), so nobody clears a list by hand.
14 * - `putAsideAsk` is "Not now".
15 *
16 * Every ask and answer is an event (`ask.asked`, `ask.put_aside`,
17 * `ask.done`), for those who answer and the one who asked.
18 */
19
20 import type { App } from "../app.ts";
21 import {
22 adminAsksOf,
23 answerAdminAsk,
24 keepAdminAsk,
25 pruneAdminAsks,
26 waitingAdminAsks,
27 type AdminAsk,
28 } from "../core/admin_ask.ts";
29 import { getModelGrant, ownSubscription } from "../core/model_grant.ts";
30 import { canAdmin, canRead, getRepoById } from "../core/repos.ts";
31 import { roleOf } from "../core/roles.ts";
32 import { crewHasCredential } from "../core/subscriptions.ts";
33 import { getUserByName, isActive, type User } from "../core/users.ts";
34 import { emailVerified } from "../core/verify.ts";
35 import { err, ok, type Result } from "../kernel/result.ts";
36 import { canAnswer, isWant, repoOfSubject, repoSubject, wantDef, type Want } from "./blocked_words.ts";
37
38 export type AskAdminError = "unauthorized" | "unknown_want" | "no_subject" | "already_can";
39
40 export const ASK_ADMIN_WORDS: Record<AskAdminError, string> = {
41 unauthorized: "Sign in first.",
42 unknown_want: "That is not something this forge takes an ask for.",
43 no_subject: "There is no such account or repository here, or it is not visible to you.",
44 already_can: "You can change this yourself: nobody needs to be asked.",
45 };
46
47 /**
48 * One ask with what it means: the sentence the one who answers reads, and the control it is
49 * answered on.
50 */
51 export interface AskView extends AdminAsk {
52 /** "bob asks for a model grant for bob" */
53 readonly sentence: string;
54 /** The exact control. */
55 readonly href: string;
56 readonly label: string;
57 }
58
59 const viewOf = (a: AdminAsk): AskView | undefined => {
60 if (!isWant(a.want)) return undefined;
61 const control = wantDef(a.want).control(a.subject);
62 return { ...a, sentence: `${a.username} ${wantDef(a.want).asks(a.subject)}`, href: control.href, label: control.label };
63 };
64
65 /** The subject as the row keeps it, or why it will not do. */
66 function subjectOf(app: App, asker: User, want: Want, raw: string): Result<{ subject: string; repoId: string | null }, "no_subject"> {
67 const kind = wantDef(want).subject;
68 const text = raw.replace(/[^\x20-\x7e]/g, "").trim().slice(0, 300);
69 if (kind === "none") return ok({ subject: "", repoId: null });
70 if (kind === "account") {
71 const who = getUserByName(app.db, text);
72 return who === undefined || who.removedAt !== null ? err("no_subject") : ok({ subject: who.username, repoId: null });
73 }
74 const repo = repoOfSubject(app, text);
75 if (repo === undefined || !canRead(app.db, repo, asker)) return err("no_subject");
76 const detail = repoSubject(text).detail;
77 return ok({
78 subject: `${repo.ownerName}/${repo.name}${detail === "" ? "" : ` ${detail}`}`,
79 repoId: wantDef(want).audience === "repo" ? repo.id : null,
80 });
81 }
82
83 /**
84 * Ask whoever can. A repeat is the same ask, raised again unless it was put
85 * aside within the day. One who can change it themselves is told so and
86 * nothing is recorded.
87 */
88 export function askAdmin(
89 app: App,
90 actor: User | undefined,
91 input: { readonly want: string; readonly subject?: string },
92 now: number = Date.now(),
93 ): Result<AskView, AskAdminError> {
94 if (actor === undefined || !isActive(actor)) return err("unauthorized");
95 if (!isWant(input.want)) return err("unknown_want");
96 const want = input.want;
97 const about = subjectOf(app, actor, want, input.subject ?? "");
98 if (!about.ok) return about;
99 if (canAnswer(app, actor, want, about.value.subject)) return err("already_can");
100 pruneAdminAsks(app.db, now);
101 const before = adminAsksOf(app.db, actor.id).find((a) => a.want === want && a.subject === about.value.subject);
102 const kept = keepAdminAsk(app.db, { userId: actor.id, want, subject: about.value.subject, repoId: about.value.repoId }, now);
103 // Said when it is new, or raised again: a repeat of a waiting ask is no news.
104 if (kept.state === "asked" && before?.state !== "asked")
105 app.bus.append({
106 kind: "ask.asked",
107 actorId: actor.id,
108 ...(kept.repoId === null ? {} : { repoId: kept.repoId }),
109 payload: { want, subject: kept.subject, who: actor.username },
110 });
111 return ok(viewOf(kept)!);
112 }
113
114 /** Whether the thing asked for is there now, for the wants the forge can read that of. */
115 function met(app: App, a: AdminAsk): boolean {
116 const who = () => getUserByName(app.db, a.subject);
117 switch (a.want as Want) {
118 case "crew_key":
119 return crewHasCredential(app.db);
120 case "model_grant": {
121 const u = who();
122 return u !== undefined && (getModelGrant(app.db, u.id) !== undefined || ownSubscription(app.db, u.id) !== undefined);
123 }
124 case "membership": {
125 const u = who();
126 return u !== undefined && roleOf(app.db, u) !== "guest";
127 }
128 case "verify_email": {
129 const u = who();
130 return u !== undefined && emailVerified(app.db, u.id);
131 }
132 default:
133 return false;
134 }
135 }
136
137 /**
138 * Finish every waiting ask whose thing is there: one read when nothing waits, and a write only
139 * for an ask that is met.
140 */
141 function settle(app: App, now: number): AdminAsk[] {
142 const waiting = waitingAdminAsks(app.db);
143 const open: AdminAsk[] = [];
144 for (const a of waiting) {
145 if (!met(app, a)) {
146 open.push(a);
147 continue;
148 }
149 if (answerAdminAsk(app.db, { userId: a.userId, want: a.want, subject: a.subject, state: "done", by: null }, now))
150 app.bus.append({ kind: "ask.done", actorId: a.userId, ...(a.repoId === null ? {} : { repoId: a.repoId }), payload: { want: a.want, subject: a.subject } });
151 }
152 return open;
153 }
154
155 /** Whether `viewer` is one who answers this ask. */
156 function answers(app: App, viewer: User, a: AdminAsk): boolean {
157 if (viewer.kind !== "user") return false;
158 if (a.repoId === null) return viewer.isAdmin;
159 const repo = getRepoById(app.db, a.repoId);
160 return repo !== undefined && canAdmin(app.db, repo, viewer);
161 }
162
163 /**
164 * What waits on `viewer` to answer, oldest first: the forge's asks for a forge admin, a
165 * repository's for its admins.
166 */
167 export function asksToAnswer(app: App, viewer: User | undefined, now: number = Date.now()): AskView[] {
168 if (viewer === undefined) return [];
169 return settle(app, now)
170 .filter((a) => answers(app, viewer, a))
171 .map(viewOf)
172 .filter((a): a is AskView => a !== undefined);
173 }
174
175 /** One person's own asks and how each stands, newest first. */
176 export function myAdminAsks(app: App, actor: User | undefined, now: number = Date.now()): Result<AskView[], "unauthorized"> {
177 if (actor === undefined) return err("unauthorized");
178 settle(app, now);
179 return ok(adminAsksOf(app.db, actor.id).map(viewOf).filter((a): a is AskView => a !== undefined));
180 }
181
182 /** How one ask stands, in a sentence, for the one who asked. */
183 export function adminAskWords(a: Pick<AdminAsk, "state" | "repoId">, ago: string): string {
184 const who = a.repoId === null ? "An admin of this forge" : "An admin of the repository";
185 if (a.state === "done") return "Done: what you asked for is there now.";
186 if (a.state === "later") return `Asked ${ago}. ${who} put this aside for now.`;
187 return `Asked ${ago}. ${who} has not answered yet.`;
188 }
189
190 /** "Not now": the ask leaves the line of the one who answers, and the asker is told. */
191 export function putAsideAsk(
192 app: App,
193 actor: User | undefined,
194 input: { readonly username: string; readonly want: string; readonly subject: string },
195 now: number = Date.now(),
196 ): Result<true, "not_found"> {
197 if (actor === undefined) return err("not_found");
198 const asker = getUserByName(app.db, input.username);
199 const row = asker === undefined ? undefined : adminAsksOf(app.db, asker.id).find((a) => a.want === input.want && a.subject === input.subject);
200 if (row === undefined || !answers(app, actor, row)) return err("not_found");
201 if (!answerAdminAsk(app.db, { userId: row.userId, want: row.want, subject: row.subject, state: "later", by: actor.id }, now)) return err("not_found");
202 app.bus.append({ kind: "ask.put_aside", actorId: actor.id, ...(row.repoId === null ? {} : { repoId: row.repoId }), payload: { want: row.want, subject: row.subject, who: row.username } });
203 return ok(true);
204 }
src/actions/blocked_words.ts +307 −21
@@ -1,31 +1,317 @@
11 /**
2 * Things that stand in the way and are said in more than one place, each
3 * built once as a `Blocked` (`kernel/blocked.ts`): what it is in the reader's
4 * terms, the link to the control when this reader can change it, and who can
5 * when they cannot. `docs/features/blocked-by.md` lists the sentences still
6 * to be moved here.
2 * Things that stand in the way, each built once as a `Blocked`
3 * (`kernel/blocked.ts`): what it is in the reader's terms, the link to the
4 * exact control when this reader can change it, and the one action that asks
5 * whoever can when they cannot (`docs/features/blocked-by.md`).
6 *
7 * `WANTS` is the list of things a person can be stopped for want of. Each
8 * names the control that grants it, with the page's own anchor on the field,
9 * and how the ask reads to the one who answers. `wayTo` turns one into the
10 * way through for a reader; `wayIn` does the same for a sentence that was
11 * stored before anyone knew who would read it (a run's summary). Every
12 * sentence in `src/` that tells a reader to ask someone or to change a
13 * setting goes through one of the two (`test/deadends.test.ts`).
714 */
815
16 import type { App } from "../app.ts";
17 import { canAdmin, getRepo, type Repo } from "../core/repos.ts";
18 import type { User } from "../core/users.ts";
919 import { blockedBy, type Blocked } from "../kernel/blocked.ts";
1020
11 /** A forge with no agent has no crew to hand work to: an admin adds one on Settings, Crew. */
12 export function noAgentsBlocked(reader: { readonly isAdmin: boolean }): Blocked {
13 return blockedBy({
14 says: "No agents exist on this forge yet.",
15 readerCan: reader.isAdmin,
16 link: { href: "/settings/crew", label: "Add an agent" },
17 who: "an admin of this forge",
21 /** Where an ask to whoever can is sent, and where a person reads how theirs stand. */
22 export const ASK_ADMIN_PATH = "/api/v1/asks/admin";
23 /** The page's own twin of it: a form posts here and lands back where it was. */
24 export const ASK_ADMIN_FORM = "/asks/admin";
25
26 interface WantDef {
27 /** Who answers: the forge's admins, or the admins of the repository the subject names. */
28 readonly audience: "forge" | "repo";
29 /**
30 * What the subject is: nothing, an account's name, or `owner/name` (with a detail after a
31 * space).
32 */
33 readonly subject: "none" | "account" | "repo";
34 /** The exact control, for one who can change it. */
35 readonly control: (subject: string) => { readonly href: string; readonly label: string };
36 /** What they can do about it, after "can". */
37 readonly can: string;
38 /** The button for one who cannot. */
39 readonly ask: string;
40 /** How it reads to the one who answers, after the asker's name. */
41 readonly asks: (subject: string) => string;
42 }
43
44 const account = (subject: string): string => `/settings/accounts/${encodeURIComponent(subject)}`;
45 /** `owner/name` and what follows it, of a repository subject. */
46 export const repoSubject = (subject: string): { readonly path: string; readonly detail: string } => {
47 const [path = "", ...rest] = subject.split(" ");
48 return { path, detail: rest.join(" ") };
49 };
50
51 export const WANTS = {
52 model_grant: {
53 audience: "forge",
54 subject: "account",
55 control: (s) => ({ href: `${account(s)}#f-grant`, label: `Give ${s} a model grant` }),
56 can: "grant one",
57 ask: "Ask an admin for a model grant",
58 asks: (s) => `asks for a model grant for ${s}`,
59 },
60 model_grant_more: {
61 audience: "forge",
62 subject: "account",
63 control: (s) => ({ href: `${account(s)}#f-grant`, label: `Raise ${s}'s model grant` }),
64 can: "raise it",
65 ask: "Ask an admin to raise the grant",
66 asks: (s) => `asks for a larger model grant for ${s}: this month's is spent`,
67 },
68 model_account: {
69 audience: "forge",
70 subject: "account",
71 control: () => ({ href: "/settings/subscriptions", label: "Grant a model account on Subscriptions" }),
72 can: "grant one",
73 ask: "Ask an admin for a model account",
74 asks: (s) => `asks for a model account for ${s}: the forge's agent cannot answer them without one`,
75 },
76 spend_ceiling: {
77 audience: "forge",
78 subject: "account",
79 control: (s) => ({ href: `${account(s)}#f-daily`, label: `Raise ${s}'s spend ceiling` }),
80 can: "raise it",
81 ask: "Ask an admin to raise the ceiling",
82 asks: (s) => `asks for a higher spend ceiling for ${s}`,
83 },
84 model_budget: {
85 audience: "forge",
86 subject: "none",
87 control: () => ({ href: "/settings/subscriptions", label: "Raise the model account's budget" }),
88 can: "raise it",
89 ask: "Ask an admin to raise the budget",
90 asks: () => "asks for a larger budget on the model account: it is spent",
91 },
92 crew_key: {
93 audience: "forge",
94 subject: "none",
95 control: () => ({ href: "/settings/crew#crew-key", label: "Add a model key" }),
1896 can: "add one",
97 ask: "Ask an admin to add a model key",
98 asks: () => "asks for a model key: the crew cannot start without one",
99 },
100 crew_limit: {
101 audience: "forge",
102 subject: "none",
103 control: () => ({ href: "/settings/crew#budgets", label: "Raise the limit" }),
104 can: "raise it",
105 ask: "Ask an admin to raise the limit",
106 asks: () => "asks for a higher crew spending limit: a run was stopped by it",
107 },
108 private_destination: {
109 audience: "forge",
110 subject: "repo",
111 control: (s) => ({ href: `/${repoSubject(s).path}/settings/app#egress`, label: "Grant it on the app's settings" }),
112 can: "grant it",
113 ask: "Ask an admin to grant it",
114 asks: (s) => `asks for ${repoSubject(s).path} to reach ${repoSubject(s).detail || "a private destination"}`,
115 },
116 verify_email: {
117 audience: "forge",
118 subject: "account",
119 control: (s) => ({ href: `${account(s)}#actions`, label: `Verify ${s}'s email` }),
120 can: "verify you",
121 ask: "Ask an admin to verify you",
122 asks: (s) => `asks to have ${s}'s email verified: this forge could not send the link`,
123 },
124 membership: {
125 audience: "forge",
126 subject: "account",
127 control: (s) => ({ href: `${account(s)}#actions`, label: `Make ${s} a member` }),
128 can: "make you one",
129 ask: "Ask an admin to make you a member",
130 asks: (s) => `asks for ${s} to be made a member`,
131 },
132 telemetry_grant: {
133 audience: "forge",
134 subject: "account",
135 control: () => ({ href: "/settings/telemetry", label: "Grant it on Telemetry" }),
136 can: "grant it",
137 ask: "Ask an admin for the grant",
138 asks: (s) => `asks for ${s} to read the forge's pipeline and machine figures`,
139 },
140 agents: {
141 audience: "forge",
142 subject: "none",
143 control: () => ({ href: "/settings/crew#crew-new", label: "Add an agent" }),
144 can: "add one",
145 ask: "Ask an admin to add an agent",
146 asks: () => "asks for an agent: this forge has none, so there is no crew",
147 },
148 repo_crew: {
149 audience: "repo",
150 subject: "repo",
151 control: (s) => ({ href: `/${repoSubject(s).path}/settings/crew`, label: "Open the repository's crew settings" }),
152 can: "change it",
153 ask: "Ask its admin to change the crew",
154 asks: (s) => `asks for a change to the crew of ${repoSubject(s).path}`,
155 },
156 } as const satisfies Record<string, WantDef>;
157
158 export type Want = keyof typeof WANTS;
159 export const isWant = (raw: string): raw is Want => Object.hasOwn(WANTS, raw);
160 export const wantDef = (want: Want): WantDef => WANTS[want];
161
162 /** The repository a repository subject names, when there is one. */
163 export function repoOfSubject(app: App, subject: string): Repo | undefined {
164 const [owner = "", name = ""] = repoSubject(subject).path.split("/");
165 return owner === "" || name === "" ? undefined : getRepo(app.db, owner, name);
166 }
167
168 /**
169 * Whether `reader` can change it themselves: a forge admin for the forge's, an admin of the
170 * repository for a repository's.
171 */
172 export function canAnswer(app: App, reader: User | undefined, want: Want, subject: string): boolean {
173 if (reader === undefined) return false;
174 if (WANTS[want].audience === "forge") return reader.isAdmin;
175 const repo = repoOfSubject(app, subject);
176 return repo !== undefined && canAdmin(app.db, repo, reader);
177 }
178
179 /** Who can, as a noun phrase. */
180 const whoAnswers = (want: Want, subject: string): string =>
181 WANTS[want].audience === "forge" ? "an admin of this forge" : `an admin of ${repoSubject(subject).path}`;
182
183 /**
184 * The way through for `reader`: the link to the control when they can change
185 * it, the action that asks whoever can when they cannot. A reader who is not
186 * signed in is told who can, and nothing is offered: there is nobody to ask
187 * as. `says` is the whole sentence of what stands in the way.
188 */
189 export function wayTo(app: App, reader: User | undefined, want: Want, says: string, subject = ""): Blocked {
190 const def: WantDef = WANTS[want];
191 return blockedBy({
192 says,
193 readerCan: canAnswer(app, reader, want, subject),
194 link: def.control(subject),
195 who: whoAnswers(want, subject),
196 can: def.can,
197 askAction: reader === undefined ? undefined : { method: "POST", path: ASK_ADMIN_PATH, body: { want, subject }, label: def.ask },
198 setting: want,
19199 });
20200 }
21201
22 /** A forge that sends no mail cannot send a verification link: an admin verifies the account by hand on its page. */
23 export function noMailBlocked(reader: { readonly username: string; readonly isAdmin: boolean }): Blocked {
24 return blockedBy({
25 says: "This forge sends no mail yet, so it cannot send you a link.",
26 readerCan: reader.isAdmin,
27 link: { href: `/settings/accounts/${reader.username}`, label: "Verify your email on your account's page" },
28 who: "an admin of this forge",
29 can: "verify you",
30 });
202 /** A forge with no agent has no crew to hand work to: an admin adds one on Settings, Crew. */
203 export function noAgentsBlocked(app: App, reader: User | undefined): Blocked {
204 return wayTo(app, reader, "agents", "No agents exist on this forge yet.");
205 }
206
207 /**
208 * A forge that sends no mail cannot send a verification link: an admin verifies the account by
209 * hand on its page.
210 */
211 export function noMailBlocked(app: App, reader: User): Blocked {
212 return wayTo(app, reader, "verify_email", "This forge sends no mail yet, so it cannot send you a link.", reader.username);
213 }
214
215 /**
216 * The forge has sent all the mail it may for now: the link waits for tomorrow, or an admin
217 * verifies by hand.
218 */
219 export function mailCappedBlocked(app: App, reader: User): Blocked {
220 return wayTo(app, reader, "verify_email", "The forge has sent all the mail it may for now. Try again tomorrow.", reader.username);
221 }
222
223 /** The crew has no model key to start on. */
224 export const NO_KEY_SENTENCE = "This forge has no model key.";
225 export function noKeyBlocked(app: App, reader: User | undefined, says: string = NO_KEY_SENTENCE): Blocked {
226 return wayTo(app, reader, "crew_key", says);
227 }
228
229 /** Talking to the forge's agent runs on a model account granted to the person, or their own. */
230 export const NO_TALK_ACCOUNT = "No model account is granted to you. Add your own subscription on Settings, Connect your AI.";
231 export function noTalkAccountBlocked(app: App, reader: User): Blocked {
232 return wayTo(app, reader, "model_account", NO_TALK_ACCOUNT, reader.username);
233 }
234
235 /** An account with no model budget: its own subscription, or a grant. */
236 export function noBudgetBlocked(app: App, reader: User, about: { readonly username: string }): Blocked {
237 return wayTo(app, reader, "model_grant", "No model budget yet.", about.username);
238 }
239
240 /**
241 * The forge's pipeline and machine figures are an admin's to read, or an
242 * agent's with the grant. Only an agent can be granted it (Settings,
243 * Telemetry lists agents), so only an agent is offered the ask; a person is
244 * told who reads them.
245 */
246 export function noTelemetryBlocked(app: App, reader: User, says: string): Blocked {
247 if (reader.kind === "agent") return wayTo(app, reader, "telemetry_grant", says, reader.username);
248 return blockedBy({ says, readerCan: false, who: "an admin of this forge", can: "read them" });
249 }
250
251 /** A repository's crew is changed by its admins. */
252 export function notCrewAdminBlocked(app: App, reader: User, repo: { readonly ownerName: string; readonly name: string }): Blocked {
253 return wayTo(app, reader, "repo_crew", "Changing this repository's crew is for its admins.", `${repo.ownerName}/${repo.name}`);
254 }
255
256 /** The words a fork is refused a guest with. */
257 export const FORK_NEEDS_MEMBER = "Proposing a change makes a fork, and forks are for members of this forge.";
258
259 /** A fork is a member's to make. */
260 export function notMemberBlocked(app: App, reader: User, says: string): Blocked {
261 return wayTo(app, reader, "membership", says, reader.username);
262 }
263
264 /** A private destination waits for a site admin's grant. */
265 export function privateDestinationBlocked(app: App, reader: User | undefined, repo: { readonly ownerName: string; readonly name: string }, destination: string, says: string): Blocked {
266 return wayTo(app, reader, "private_destination", says, `${repo.ownerName}/${repo.name}${destination === "" ? "" : ` ${destination}`}`);
267 }
268
269 // ---- sentences stored before anyone knew who would read them ----
270
271 /**
272 * What a run is stopped with for want of something an admin holds. The
273 * runner stores the sentence alone (`says`); whoever shows it calls `wayIn`
274 * with the reader, and a log or a comment, read by anyone, prints `saidOf`.
275 */
276 interface Stored {
277 readonly want: Want;
278 /** Recognizes the stored sentence; group 1, when there is one, is the account it names. */
279 readonly re: RegExp;
280 }
281
282 const STORED: readonly Stored[] = [
283 { want: "crew_key", re: /\bhas no model key\b/ },
284 { want: "model_grant", re: /^The account `([^`]+)` has no model grant\b|^the account `([^`]+)` has no model grant\b/ },
285 { want: "model_grant", re: /\bhas no model account\b/ },
286 { want: "model_grant_more", re: /\bmodel grant is spent\b/ },
287 { want: "spend_ceiling", re: /\b(?:daily|per-run) ceiling\b/ },
288 { want: "model_budget", re: /\bbudget is spent\b/ },
289 { want: "crew_limit", re: /\bper (?:run|day|month) limit \(\$[\d.]+\) stopped the run\b/ },
290 ];
291
292 /**
293 * The sentence alone: what a stored reason reads as once the old instruction ("ask an admin…",
294 * "add yours at…") is cut from it.
295 */
296 const sentenceOf = (text: string): string =>
297 text
298 .replace(/\s*[:;]\s*(?:ask an admin to grant one|an admin can (?:grant one|raise it)(?: at \S+)?|add yours at \S+|raise it at \S+)\s*$/i, "")
299 .replace(/\s*An admin of [^.]+ can [^.]+\.\s*$/, "")
300 .replace(/[.\s]+$/, "") + ".";
301
302 /**
303 * The way through for a stored sentence, for this reader, or undefined when
304 * the sentence is not one of these. `about` is whose run it was: the account
305 * a grant or a ceiling is for when the sentence does not name one.
306 */
307 export function wayIn(app: App, reader: User | undefined, text: string, about?: { readonly ownerName: string }): Blocked | undefined {
308 for (const s of STORED) {
309 const m = s.re.exec(text);
310 if (m === null) continue;
311 const def: WantDef = WANTS[s.want];
312 const subject = def.subject === "account" ? (m[1] ?? m[2] ?? about?.ownerName ?? "") : "";
313 if (def.subject === "account" && subject === "") return undefined;
314 return wayTo(app, reader, s.want, sentenceOf(text), subject);
315 }
316 return undefined;
31317 }
src/actions/propose_edit.ts +3 −1
@@ -14,6 +14,8 @@
1414 * says so, as it does for any fork's pull.
1515 */
1616
17 import { FORK_NEEDS_MEMBER } from "./blocked_words.ts";
18 import { storedText } from "../kernel/blocked.ts";
1719 import { GUEST_REFUSALS, isGuestRefusal } from "../core/contribute.ts";
1820 import type { App } from "../app.ts";
1921 import { canWrite, getForkOf, type Repo } from "../core/repos.ts";
@@ -110,7 +112,7 @@ export function proposeEditText(error: ProposeEditError): string {
110112 if (reason === "unverified")
111113 return "Confirm your email first: proposing a change makes a fork, and a fork needs a confirmed address.";
112114 if (reason === "not_member")
113 return "Proposing a change makes a fork, and forks are for members of this forge. Ask its admin to make you one.";
115 return storedText(FORK_NEEDS_MEMBER, "an admin of this forge", "make you one");
114116 if (reason === "limit" || reason === "repository_limit" || reason === "storage_limit")
115117 return "You cannot make another fork right now, so this could not be proposed. Try again later.";
116118 if (isGuestRefusal(reason)) return GUEST_REFUSALS[reason];
src/actions/talk.ts +3 −1
@@ -5,6 +5,8 @@
55 * and hands the words to `crew/conversation.ts`, which runs as that person.
66 */
77
8 import { NO_TALK_ACCOUNT } from "./blocked_words.ts";
9 import { storedText } from "../kernel/blocked.ts";
810 import type { App } from "../app.ts";
911 import { getConversation } from "../core/conversations.ts";
1012 import type { ConversationFile } from "../core/conversation_files.ts";
@@ -24,7 +26,7 @@ export const TALK_WORDS: Readonly<Record<TalkRefusal, readonly [number, string]>
2426 unauthorized: [401, "sign in to talk to the forge"],
2527 empty: [422, "say something"],
2628 too_long: [422, "the message is too long"],
27 no_account: [403, "no Claude account is granted to you; ask an admin for a grant"],
29 no_account: [403, storedText(NO_TALK_ACCOUNT, "an admin of this forge", "grant one")],
2830 resting: [429, "the account that serves you is resting or out of budget; try again later"],
2931 answering: [409, "the forge is still answering; send pictures when it has finished"],
3032 busy: [429, "the forge's agent is answering as many people as it can at once; try again in a minute"],
src/actions/verify_words.ts +2 −1
@@ -2,6 +2,7 @@
22 // MCP, terminal) reads them from here, so the sentence cannot drift between
33 // doors.
44
5 import { storedText } from "../kernel/blocked.ts";
56 import { CAPPED_WORDS } from "./mail.ts";
67
78 /** Refuses a create or a cost (an app, a tell, a token) to an unverified account. */
@@ -19,7 +20,7 @@ export const PROVE_FIRST = "prove your email first";
1920 export const VERIFY_WORDS = {
2021 too_soon: "a link was sent a moment ago; check your inbox, or try again in a few minutes",
2122 failed: "the link could not be sent; try again",
22 no_mail: "this forge sends no mail yet; ask its owner to verify you",
23 no_mail: storedText("This forge sends no mail yet.", "an admin of this forge", "verify you"),
2324 } as const;
2425
2526 /**
src/apps/egress.ts +3 −4
@@ -17,6 +17,7 @@
1717 * second host the first answer did not cover.
1818 */
1919
20 import { storedText } from "../kernel/blocked.ts";
2021 import { lookup } from "node:dns/promises";
2122 import { isIP } from "node:net";
2223 import type { Socket } from "bun";
@@ -451,8 +452,7 @@ export async function decide(
451452 const declared = origin || hostAllowed([...policy.hosts, ...(policy.allowed?.() ?? [])], name, port);
452453 const literalPrivate = isIP(name) !== 0 && !isPublicAddress(name);
453454 const askAdmin =
454 `${name}:${port} is a private destination: ` +
455 "add it to forge.json egress and ask a site admin to grant it";
455 storedText(`${name}:${port} is a private destination: add it to forge.json egress.`, "an admin of this forge", "grant it on the app's settings");
456456 // A grant opens only a destination forge.json names exactly: a wildcard
457457 // entry declares names, it never makes one of them grantable.
458458 const granted =
@@ -488,8 +488,7 @@ export async function decide(
488488 ok: false,
489489 why: literalPrivate
490490 ? askAdmin
491 : `${name} resolves to a private address; add ${name}:${port} ` +
492 "to forge.json egress and ask a site admin to grant it",
491 : storedText(`${name} resolves to a private address: add ${name}:${port} to forge.json egress.`, "an admin of this forge", "grant it on the app's settings"),
493492 policy: { private: true },
494493 };
495494 // A grant opens one destination, never the metadata service or the
src/contract/openapi/routes/getApiV1AsksAdmin.ts added +12
@@ -0,0 +1,12 @@
1 import type { Route } from "../shared.ts";
2
3 export const route: Route = {
4 method: "get",
5 path: "/api/v1/asks/admin",
6 summary: "What this account asked whoever can change something to change, and what waits on this account to answer (ro scope); answers { items, toAnswer, next_cursor }, each item { want, subject, by, state, askedAt, answeredAt, says } with state asked, later or done; each of toAnswer also carries fix { href, label }, the exact control it is answered on; an ask is done by itself once the thing asked for is there, so polling this is how an agent waits",
7 auth: true,
8 role: "member",
9 refusals: {
10 unauthorized: "no valid credentials were sent",
11 },
12 };
src/contract/openapi/routes/index.ts +2
@@ -64,6 +64,7 @@ export { route as getApiV1AppTemplates } from "./getApiV1AppTemplates.ts";
6464 export { route as getApiV1Apps } from "./getApiV1Apps.ts";
6565 export { route as getApiV1Asked } from "./getApiV1Asked.ts";
6666 export { route as getApiV1Asks } from "./getApiV1Asks.ts";
67 export { route as getApiV1AsksAdmin } from "./getApiV1AsksAdmin.ts";
6768 export { route as getApiV1Boards } from "./getApiV1Boards.ts";
6869 export { route as getApiV1BoardsPins } from "./getApiV1BoardsPins.ts";
6970 export { route as getApiV1BoardsSlug } from "./getApiV1BoardsSlug.ts";
@@ -277,6 +278,7 @@ export { route as postApiV1AdminRequestsUsernameAllow } from "./postApiV1AdminRe
277278 export { route as postApiV1AdminRequestsUsernameDecline } from "./postApiV1AdminRequestsUsernameDecline.ts";
278279 export { route as postApiV1Agents } from "./postApiV1Agents.ts";
279280 export { route as postApiV1Apps } from "./postApiV1Apps.ts";
281 export { route as postApiV1AsksAdmin } from "./postApiV1AsksAdmin.ts";
280282 export { route as postApiV1AsksBulk } from "./postApiV1AsksBulk.ts";
281283 export { route as postApiV1AsksBulkIdUndo } from "./postApiV1AsksBulkIdUndo.ts";
282284 export { route as postApiV1AsksDecide } from "./postApiV1AsksDecide.ts";
src/contract/openapi/routes/postApiV1AsksAdmin.ts added +18
@@ -0,0 +1,18 @@
1 import type { Route } from "../shared.ts";
2
3 export const route: Route = {
4 method: "post",
5 path: "/api/v1/asks/admin",
6 summary: "Ask whoever can change something to change it (rw scope): a forge admin, or a repository's admin; a refusal that this caller cannot lift answers with this call ready-made in its `ask` field; `want` is one of the things the forge takes an ask for and `subject` the account or `owner/name` it is for; a repeat refreshes the one ask; answers 201 with the ask { want, subject, by, state, askedAt, answeredAt, says }",
7 auth: true,
8 role: "member",
9 status: 201,
10 body: { want: "string", subject: "string" },
11 refusals: {
12 unauthorized: "no valid credentials were sent",
13 forbidden: "the token's scope is below rw",
14 unknown_want: "422, not something this forge takes an ask for",
15 no_subject: "422, no such account or repository here, or it is not visible to you",
16 already_can: "409, you can change this yourself, so nobody is asked",
17 },
18 };
src/contract/openapi/routes/postApiV1ConversationMessages.ts +1 −1
@@ -16,7 +16,7 @@ export const route: Route = {
1616 file_taken: "an attached file already waits in a queued message (409)",
1717 queue_full: "five messages already wait (429)",
1818 too_large: "the body is over 128000 bytes (413)",
19 no_account: "no Claude account is granted to the person (403)",
19 no_account: "no model account is granted to the person (403); the body carries `says` and `ask`, the call that asks an admin for one",
2020 resting: "the account that serves the person is resting or out of budget (429)",
2121 rate_limited: "more than 12 messages in a minute (429)",
2222 off: "the forge's agent is not running here (503)",
src/core/account_ceiling.ts +3 −2
@@ -9,6 +9,7 @@
99 * together. Pure data; who may set is the action's to decide.
1010 */
1111
12 import { storedText } from "../kernel/blocked.ts";
1213 import type { Database } from "bun:sqlite";
1314
1415 /** The most either ceiling may be, in dollars. */
@@ -127,13 +128,13 @@ export function reserveCeiling(
127128 if (c.perRunUsd < minRunUsd)
128129 return {
129130 ok: false,
130 said: `This account's per-run ceiling ($${c.perRunUsd.toFixed(2)}) is too small to start a run: an admin can raise it`,
131 said: storedText(`This account's per-run ceiling ($${c.perRunUsd.toFixed(2)}) is too small to start a run.`, "an admin of this forge", "raise it"),
131132 };
132133 const left = Math.max(0, c.dailyUsd - daySpent(db, userId, now) - reservedByOthers(db, userId, run.id));
133134 if (left < minRunUsd)
134135 return {
135136 ok: false,
136 said: `This account's daily ceiling ($${c.dailyUsd.toFixed(2)}) is spent for today: an admin can raise it`,
137 said: storedText(`This account's daily ceiling ($${c.dailyUsd.toFixed(2)}) is spent for today.`, "an admin of this forge", "raise it"),
137138 };
138139 const capUsd = Math.min(c.perRunUsd, left, run.wantUsd);
139140 db.query("UPDATE run SET ceiling_reserved_usd = ?1 WHERE id = ?2").run(capUsd, run.id);
src/core/admin_ask.ts added +146
@@ -0,0 +1,146 @@
1 /**
2 * What a person asked whoever can change something to change
3 * (`admin_ask`): one row per person, thing and subject, raised to the
4 * forge's admins, or to one repository's admins when `repoId` is set. Pure
5 * data: who may ask and who may answer is `actions/ask_admin.ts`, and what
6 * each `want` means is `actions/blocked_words.ts`.
7 *
8 * It is the forge's own half of what `core/reach_ask.ts` is for a hosted
9 * forge and its host: the same states where they apply (`asked`, `later`),
10 * and `done` when the thing asked for is there.
11 */
12
13 import type { Database } from "bun:sqlite";
14
15 export type AdminAskState = "asked" | "later" | "done";
16
17 /**
18 * Asks one person may have waiting; the oldest gives way to a new one, so nobody is turned away.
19 */
20 export const ASKS_PER_PERSON = 20;
21 /** An ask put aside is not raised again by a repeat for this long. */
22 const RAISE_AGAIN_MS = 24 * 3_600_000;
23 /** An answered ask stays readable this long; a waiting one this long with nobody repeating it. */
24 const ANSWERED_MS = 7 * 24 * 3_600_000;
25 const WAITING_MS = 30 * 24 * 3_600_000;
26
27 export interface AdminAsk {
28 readonly userId: string;
29 /** Who asked, as the forge names them. */
30 readonly username: string;
31 readonly want: string;
32 readonly subject: string;
33 readonly repoId: string | null;
34 readonly state: AdminAskState;
35 readonly askedAt: string;
36 readonly lastAt: string;
37 readonly answeredAt: string | null;
38 }
39
40 interface Row {
41 user_id: string;
42 username: string;
43 want: string;
44 subject: string;
45 repo_id: string | null;
46 state: AdminAskState;
47 asked_at: string;
48 last_at: string;
49 answered_at: string | null;
50 }
51
52 const SELECT = `SELECT a.user_id, u.username, a.want, a.subject, a.repo_id, a.state, a.asked_at, a.last_at, a.answered_at
53 FROM admin_ask a JOIN user u ON u.id = a.user_id`;
54
55 const askOf = (r: Row): AdminAsk => ({
56 userId: r.user_id,
57 username: r.username,
58 want: r.want,
59 subject: r.subject,
60 repoId: r.repo_id,
61 state: r.state,
62 askedAt: r.asked_at,
63 lastAt: r.last_at,
64 answeredAt: r.answered_at,
65 });
66
67 /**
68 * Keep the ask. A repeat refreshes the one row and raises it again, unless
69 * it was put aside within the day. Past the cap, a person's oldest goes.
70 */
71 export function keepAdminAsk(
72 db: Database,
73 input: { userId: string; want: string; subject: string; repoId: string | null },
74 now: number = Date.now(),
75 ): AdminAsk {
76 const at = new Date(now).toISOString();
77 const again = new Date(now - RAISE_AGAIN_MS).toISOString();
78 db.transaction(() => {
79 db.query(
80 `INSERT INTO admin_ask (user_id, want, subject, repo_id, asked_at, last_at)
81 VALUES (?1, ?2, ?3, ?4, ?5, ?5)
82 ON CONFLICT(user_id, want, subject) DO UPDATE SET
83 repo_id = excluded.repo_id, last_at = excluded.last_at,
84 asked_at = CASE WHEN state = 'done' THEN excluded.asked_at ELSE asked_at END,
85 answered_at = CASE WHEN state = 'later' AND answered_at > ?6 THEN answered_at ELSE NULL END,
86 answered_by = CASE WHEN state = 'later' AND answered_at > ?6 THEN answered_by ELSE NULL END,
87 state = CASE WHEN state = 'later' AND answered_at > ?6 THEN 'later' ELSE 'asked' END`,
88 ).run(input.userId, input.want, input.subject, input.repoId, at, again);
89 db.query(
90 `DELETE FROM admin_ask WHERE user_id = ?1 AND rowid IN (
91 SELECT rowid FROM admin_ask WHERE user_id = ?1 ORDER BY last_at DESC, rowid DESC LIMIT -1 OFFSET ?2)`,
92 ).run(input.userId, ASKS_PER_PERSON);
93 })();
94 return adminAskOf(db, input.userId, input.want, input.subject)!;
95 }
96
97 export function adminAskOf(db: Database, userId: string, want: string, subject: string): AdminAsk | undefined {
98 const row = db
99 .query<Row, [string, string, string]>(`${SELECT} WHERE a.user_id = ?1 AND a.want = ?2 AND a.subject = ?3`)
100 .get(userId, want, subject);
101 return row === null ? undefined : askOf(row);
102 }
103
104 /** One person's asks, newest first. */
105 export function adminAsksOf(db: Database, userId: string): AdminAsk[] {
106 return db
107 .query<Row, [string]>(`${SELECT} WHERE a.user_id = ?1 ORDER BY a.last_at DESC, a.want, a.subject`)
108 .all(userId)
109 .map(askOf);
110 }
111
112 /**
113 * Every ask nobody has answered, oldest first: the forge's (`repoId` null) and every
114 * repository's.
115 */
116 export function waitingAdminAsks(db: Database): AdminAsk[] {
117 return db
118 .query<Row, []>(`${SELECT} WHERE a.state = 'asked' ORDER BY a.last_at, a.want, a.subject LIMIT 200`)
119 .all()
120 .map(askOf);
121 }
122
123 /**
124 * One row moves to `state`, by whoever answered (nobody, when the forge saw the thing was there).
125 * True when a waiting row moved.
126 */
127 export function answerAdminAsk(
128 db: Database,
129 input: { userId: string; want: string; subject: string; state: "later" | "done"; by: string | null },
130 now: number = Date.now(),
131 ): boolean {
132 return (
133 db
134 .query(
135 `UPDATE admin_ask SET state = ?4, answered_by = ?5, answered_at = ?6
136 WHERE user_id = ?1 AND want = ?2 AND subject = ?3 AND state IN ('asked','later') AND state != ?4`,
137 )
138 .run(input.userId, input.want, input.subject, input.state, input.by, new Date(now).toISOString()).changes > 0
139 );
140 }
141
142 /** What time takes: an answered row a week old, and a waiting one nobody repeated in a month. */
143 export function pruneAdminAsks(db: Database, now: number = Date.now()): void {
144 db.query("DELETE FROM admin_ask WHERE state IN ('later','done') AND answered_at <= ?1").run(new Date(now - ANSWERED_MS).toISOString());
145 db.query("DELETE FROM admin_ask WHERE state = 'asked' AND last_at <= ?1").run(new Date(now - WAITING_MS).toISOString());
146 }
src/core/event_audience.ts +3
@@ -303,6 +303,9 @@ export function classifiedAudience(kind: string): EventAudience | undefined {
303303 // Which child forge was moved out of this forge's process, left there or put back, and why:
304304 // what its
305305 // repositories hold is named in the reason (`spawn/move_cell.ts`).
306 // What a person asked whoever can change something to change, and how it was answered, is
307 // theirs to answer (`actions/ask_admin.ts`).
308 kind.startsWith("ask.") ||
306309 kind === "forge.moved" ||
307310 kind === "forge.move_failed" ||
308311 kind === "forge.move_held" ||
src/core/migration-pins/20261114235900-admin-ask.pin added +1
@@ -0,0 +1,1 @@
1 326eee3918dff27c8ab58b72c53a7f84a1df0fcb434b1470fcee8d2af47f003c
src/core/migrations/20261114235900-admin-ask.ts added +19
@@ -0,0 +1,19 @@
1 // What a person asked whoever can change something to change (`docs/features/blocked-by.md`): one
2 // row
3 // per person, thing and subject, raised to the forge's admins, or to a repository's admins when
4 // `repo_id` is set. A repeat refreshes the row. Additive.
5 export default `
6 CREATE TABLE IF NOT EXISTS admin_ask (
7 user_id TEXT NOT NULL,
8 want TEXT NOT NULL,
9 subject TEXT NOT NULL DEFAULT '',
10 repo_id TEXT,
11 state TEXT NOT NULL DEFAULT 'asked' CHECK (state IN ('asked','later','done')),
12 asked_at TEXT NOT NULL,
13 last_at TEXT NOT NULL,
14 answered_by TEXT,
15 answered_at TEXT,
16 PRIMARY KEY (user_id, want, subject)
17 );
18 CREATE INDEX IF NOT EXISTS admin_ask_waiting ON admin_ask (state, last_at);
19 `;
src/core/model_grant.ts +7 −1
@@ -140,6 +140,12 @@ export function addOwnSubscription(
140140 return added;
141141 }
142142
143 /**
144 * What an account with neither a subscription nor a grant reads; its page draws the way to a
145 * grant beside it (`blocked_words.ts` `noBudgetBlocked`).
146 */
147 export const NO_BUDGET_LINE = "Model budget: $0. Add your own subscription, or a grant from an admin pays for it.";
148
143149 /** The one line an account's page says about its model budget. */
144150 export function budgetLine(db: Database, user: { id: string; username: string; isAdmin: boolean }, now: Date): string {
145151 if (user.isAdmin) return "Model budget: the forge's own credential.";
@@ -150,5 +156,5 @@ export function budgetLine(db: Database, user: { id: string; username: string; i
150156 const left = grantLeft(db, user.id, now)!;
151157 return `Model budget: a grant of $${grant.usdPerMonth.toFixed(2)} a month, $${left.toFixed(2)} left.`;
152158 }
153 return "Model budget: $0. Add your own subscription, or ask an admin for a grant.";
159 return NO_BUDGET_LINE;
154160 }
src/core/subscriptions.ts +2 −1
@@ -24,6 +24,7 @@
2424 * none is never offered to the crew (a person's own plan, kept apart).
2525 */
2626
27 import { storedText } from "../kernel/blocked.ts";
2728 import type { Database } from "bun:sqlite";
2829 import { id } from "../kernel/id.ts";
2930 import { err, ok, type Result } from "../kernel/result.ts";
@@ -628,7 +629,7 @@ export function pickSubscription(
628629 return {
629630 kind: "resting",
630631 until: new Date(now.getTime() + BUDGET_RECHECK_MS).toISOString(),
631 said: `its $${first.budget_usd} budget is spent; an admin can raise it`,
632 said: storedText(`its $${first.budget_usd} budget is spent.`, "an admin of this forge", "raise it"),
632633 names: grant.map((r) => r.name),
633634 };
634635 }
src/crew/forge_budget.ts +8 −4
@@ -7,6 +7,7 @@
77 * data: who may set is the action's to decide.
88 */
99
10 import { storedText } from "../kernel/blocked.ts";
1011 import type { Database } from "bun:sqlite";
1112 import { existsSync } from "node:fs";
1213 import { join } from "node:path";
@@ -77,15 +78,18 @@ export type BudgetVerdict =
7778 const dollars = (n: number): string => `$${n.toFixed(2)}`;
7879
7980 /** The words a run is stopped with for want of a key; the runner says them and `wake.ts` reads them. */
80 export const NO_KEY_SAID = "This forge has no model key: add yours at /settings/crew";
81 export const NO_ACCOUNT_SAID = "This repository has no model account: ask an admin to grant one";
81 export const NO_KEY_SAID = storedText("This forge has no model key.", "an admin of this forge", "add one");
82 export const NO_ACCOUNT_SAID = storedText("This repository has no model account.", "an admin of this forge", "grant one");
8283 /** A stop by one of the owner's limits, as `stoppedBy` writes it. */
8384 const LIMIT_STOP = /This forge's per (run|day|month) limit \(\$[\d.]+\) stopped the run/;
8485 export const isLimitStop = (reason: string): boolean => LIMIT_STOP.test(reason);
8586
86 /** The words for a stop by `key`, naming it and where to change it. */
87 /**
88 * The words for a stop by `key`, naming it and who can change it; a page that knows its reader
89 * links `BUDGETS_AT` (`blocked_words.ts` `wayIn`).
90 */
8791 export function stoppedBy(db: Database, key: BudgetKey): string {
88 return `This forge's ${BUDGET_LABEL[key]} limit (${dollars(budgetLimit(db, key))}) stopped the run: raise it at ${BUDGETS_AT}`;
92 return storedText(`This forge's ${BUDGET_LABEL[key]} limit (${dollars(budgetLimit(db, key))}) stopped the run.`, "an admin of this forge", "raise it");
8993 }
9094
9195 /** What a run's summary ends with when it was cut off at the cap and a limit of the owner's set that cap; nothing otherwise. */
src/crew/runner.ts +5 −4
@@ -11,6 +11,7 @@
1111 * what the forge has.
1212 */
1313
14 import { storedText } from "../kernel/blocked.ts";
1415 import { holdsNaming } from "./desk_posts.ts";
1516 import { isStrangerPull } from "./stranger.ts";
1617 import { forgetMeasure, noteMeasure } from "../core/measure.ts";
@@ -288,7 +289,7 @@ function noGrantSaid(app: App, ownerId: string, ownerName: string): string {
288289 .query<{ kind: string }, [string]>("SELECT kind FROM user WHERE id = ?1")
289290 .get(ownerId)?.kind === "org";
290291 return org
291 ? `the account \`${ownerName}\` has no model grant; an admin can grant one at /settings/accounts/${ownerName}`
292 ? storedText(`The account \`${ownerName}\` has no model grant.`, "an admin of this forge", "grant one")
292293 : NO_ACCOUNT_SAID;
293294 }
294295
@@ -843,11 +844,11 @@ const LIVE_MS = 2_000;
843844
844845 /** Said on a run stopped at its grant's cap. */
845846 const GRANT_SPENT =
846 "This month's model grant is spent: the run stopped at the cap; an admin can raise it";
847 storedText("This month's model grant is spent: the run stopped at the cap.", "an admin of this forge", "raise it");
847848
848849 /** Said on a run stopped at its account's daily ceiling. */
849850 const DAILY_SPENT =
850 "This account's daily ceiling is spent: the run stopped; an admin can raise it";
851 storedText("This account's daily ceiling is spent: the run stopped.", "an admin of this forge", "raise it");
851852
852853 /**
853854 * A running session's spend so far, as its `running` line in the ledger,
@@ -1444,7 +1445,7 @@ async function work(
14441445 const said =
14451446 grantCap === undefined
14461447 ? noGrantSaid(app, repo.ownerId, repo.ownerName)
1447 : "This month's model grant is spent: an admin can raise it";
1448 : storedText("This month's model grant is spent.", "an admin of this forge", "raise it");
14481449 write(said);
14491450 return { state: "failed", summary: said };
14501451 }
src/crew/wake.ts +8 −3
@@ -15,7 +15,7 @@ import { PARK_LIKE } from "../core/done_on_main.ts";
1515 import { getIssueById } from "../core/issues.ts";
1616 import { getRepoById } from "../core/repos.ts";
1717 import type { User } from "../core/users.ts";
18 import { isLimitStop, NO_ACCOUNT_SAID, NO_KEY_SAID } from "./forge_budget.ts";
18 import { isLimitStop } from "./forge_budget.ts";
1919 import { parkReasons } from "./parks.ts";
2020
2121 /** Why the issues were woken, for the comment they get. */
@@ -27,9 +27,14 @@ const WORDS: Record<WakeCause, string> = {
2727 };
2828
2929 /** Park reasons a new key can fix: the exact words the runner writes for want of a key, an account or a grant. */
30 const NO_GRANT = /the account `[^`]+` has no model grant; an admin can grant one/;
30 const NO_GRANT = /the account `[^`]+` has no model grant\b/i;
31 /**
32 * As the runner writes them now, and as it wrote them before (`forge_budget.ts`): parks already
33 * on issues are still read.
34 */
35 const NO_KEY = /\bhas no model (?:key|account)\b/;
3136 const MEANS: Record<WakeCause, (reason: string) => boolean> = {
32 key: (r) => r.includes(NO_KEY_SAID) || r.includes(NO_ACCOUNT_SAID) || NO_GRANT.test(r),
37 key: (r) => NO_KEY.test(r) || NO_GRANT.test(r),
3338 limit: isLimitStop,
3439 };
3540
src/http/api.ts +2
@@ -359,6 +359,7 @@ import { COPIES_PER_DAY, makeItYours } from "../actions/make_it_yours.ts";
359359 import { passportRoutes } from "./passport_edge.ts";
360360 import { egressGrantRoutes } from "./api/egress_grants.ts";
361361 import { reachAskRoutes } from "./api/reach_asks.ts";
362 import { adminAskRoutes } from "./api/admin_asks.ts";
362363 import { printRoutes } from "./api/print.ts";
363364 import { timersRoutes } from "./api/timers.ts";
364365 import { jobsRoutes } from "./api/jobs.ts";
@@ -3956,6 +3957,7 @@ export function apiRoutes(router: Router<Handler>): void {
39563957
39573958 egressGrantRoutes(router);
39583959 reachAskRoutes(router);
3960 adminAskRoutes(router);
39593961 printRoutes(router);
39603962 timersRoutes(router);
39613963 schedulesRoutes(router);
src/http/api/admin_asks.ts added +52
@@ -0,0 +1,52 @@
1 /**
2 * Asks to whoever can change something, over the API: `GET` and `POST`
3 * `/api/v1/asks/admin`. The rules live in `actions/ask_admin.ts`; this is the
4 * door an agent uses when a refusal answers with `ask` (`kernel/blocked.ts`).
5 */
6
7 import { ASK_ADMIN_WORDS, adminAskWords, askAdmin, asksToAnswer, myAdminAsks, type AskView } from "../../actions/ask_admin.ts";
8 import { notePhase, takeSessionTime } from "../../core/route_timing.ts";
9 import { agoWords } from "../../kernel/ago.ts";
10 import type { Handler } from "../context.ts";
11 import { apiError, body, json, requireScope, str, unauthorized } from "../respond.ts";
12 import type { Router } from "../router.ts";
13
14 /**
15 * One ask as the API says it: what was asked for, where it stands, and the sentence the page
16 * shows.
17 */
18 export const adminAskJson = (a: AskView) => ({
19 want: a.want,
20 subject: a.subject,
21 by: a.username,
22 state: a.state,
23 askedAt: a.askedAt,
24 answeredAt: a.answeredAt,
25 says: adminAskWords(a, agoWords(a.lastAt)),
26 });
27
28 export function adminAskRoutes(router: Router<Handler>): void {
29 // How this account's asks stand, and what waits on this account to answer.
30 router.add("GET", "/api/v1/asks/admin", (ctx) => {
31 notePhase(ctx.request, "session", takeSessionTime(ctx.request));
32 const denied = requireScope(ctx, "ro");
33 if (denied) return denied;
34 const mine = myAdminAsks(ctx.app, ctx.auth.user);
35 if (!mine.ok) return unauthorized();
36 return json({
37 items: mine.value.map(adminAskJson),
38 toAnswer: asksToAnswer(ctx.app, ctx.auth.user).map((a) => ({ ...adminAskJson(a), says: a.sentence, fix: { href: a.href, label: a.label } })),
39 next_cursor: null,
40 });
41 });
42
43 // Ask whoever can change `want` (for `subject`) to change it. A repeat is the same ask.
44 router.add("POST", "/api/v1/asks/admin", async (ctx) => {
45 const denied = requireScope(ctx, "rw");
46 if (denied) return denied;
47 const input = await body(ctx.request);
48 const asked = askAdmin(ctx.app, ctx.auth.user, { want: str(input.want), subject: str(input.subject) });
49 if (!asked.ok) return asked.error === "unauthorized" ? unauthorized() : apiError(asked.error, asked.error === "already_can" ? 409 : 422, ASK_ADMIN_WORDS[asked.error]);
50 return json(adminAskJson(asked.value), 201);
51 });
52 }
src/http/api/conversation_talk.ts +3
@@ -7,6 +7,8 @@
77 * request is same-origin, and sending is throttled per person (`actions/talk.ts`).
88 */
99
10 import { noTalkAccountBlocked } from "../../actions/blocked_words.ts";
11 import { blockedFields } from "../../kernel/blocked.ts";
1012 import type { App } from "../../app.ts";
1113 import { RateLimiter } from "../../core/ratelimit.ts";
1214 import { cancelTalk, stopTalk, TALK_WORDS, talk } from "../../actions/talk.ts";
@@ -98,6 +100,7 @@ export function conversationTalkRoutes(router: Router<Handler>): void {
98100 const said = talk(ctx.app, user, text, files.value, during === "queue" ? "queue" : during === "steer" ? "interrupt" : "inject", named, typeof input["about"] === "string" ? input["about"] : null);
99101 if (!said.ok) {
100102 const [status, words] = TALK_WORDS[said.error];
103 if (said.error === "no_account") return json({ error: said.error, message: words, ...blockedFields(noTalkAccountBlocked(ctx.app, user)) }, status);
101104 return status === 429 || status === 503 ? tryAgain(said.error, status, words, talkWait(said.error)) : json({ error: said.error, message: words }, status);
102105 }
103106 return json(said.value.queued === undefined ? { how: said.value.how } : { how: said.value.how, queued: said.value.queued }, 202);
src/http/api/user.ts +1 −1
@@ -126,7 +126,7 @@ export function userRoutes(router: Router<Handler>): void {
126126 // The same refusal, with what stands in the way and the next step as data for an agent (`kernel/blocked.ts`).
127127 const refused = tryAgain("no_mail", 503, VERIFY_WORDS.no_mail, NO_MAIL_RETRY);
128128 const said = (await refused.json()) as Record<string, unknown>;
129 return json({ ...said, ...blockedFields(noMailBlocked(ctx.auth.user)) }, 503, Object.fromEntries(refused.headers));
129 return json({ ...said, ...blockedFields(noMailBlocked(ctx.app, ctx.auth.user!)) }, 503, Object.fromEntries(refused.headers));
130130 }
131131 if (sent.error === "capped")
132132 return tryAgain("capped", 429, CAPPED_WORDS, WINDOW.day);
src/http/mcp.ts +3
@@ -269,6 +269,9 @@ function rpcOne(
269269 text: `${answer.error}: ${withNextStep(tool, answer.error, answer.message)}`,
270270 },
271271 ],
272 // What stands in the way, as data: `fix` (the control) or `ask` (the call that
273 // asks whoever can).
274 ...(answer.next === undefined ? {} : { structuredContent: answer.next }),
272275 isError: true,
273276 },
274277 );
src/http/mcp/shared.ts +13 −1
@@ -1,4 +1,5 @@
11 import { SIGN_IN_AS_ADMIN } from "../../core/roles.ts";
2 import { blockedFields, blockedText, type Blocked } from "../../kernel/blocked.ts";
23 import { mayView } from "../../core/sealed.ts";
34 import { getIssue, LIST_LIMIT_MAX } from "../../core/issues.ts";
45 import { canRead, canWrite, getRepo, type Repo } from "../../core/repos.ts";
@@ -17,7 +18,7 @@ import { asksFirst, confirmSentence, tooBigToApprove, undoableWork } from "../..
1718 export type Args = Record<string, unknown>;
1819 export type Answer =
1920 | { ok: true; value: unknown; card?: Record<string, unknown> }
20 | { ok: false; error: string; message: string };
21 | { ok: false; error: string; message: string; next?: Record<string, unknown> };
2122
2223 export const good = (value: unknown): Answer => ({ ok: true, value });
2324 export const attachWords = (error: string): string =>
@@ -46,6 +47,17 @@ export const bad = (error: string, message: string): Answer => ({
4647 message,
4748 });
4849
50 /**
51 * A refusal for something that stands in the way (`kernel/blocked.ts`): the sentence and its way
52 * through as words, and the same as data (`fix` or `ask`).
53 */
54 export const badBlocked = (error: string, blocked: Blocked): Answer => ({
55 ok: false,
56 error,
57 message: blockedText(blocked),
58 next: blockedFields(blocked),
59 });
60
4961 /** The refusal for a `limit` that is not a whole number from 1 to LIST_LIMIT_MAX, as the HTTP list routes say it; undefined when it is absent or fine. */
5062 export const badLimit = (limit: unknown): Answer | undefined =>
5163 limit === undefined ||
src/http/mcp/tools/crew.ts +4 −2
@@ -1,4 +1,6 @@
11 import { scopeAllows } from "../../../core/tokens.ts";
2 import { badBlocked } from "../shared.ts";
3 import { notCrewAdminBlocked } from "../../../actions/blocked_words.ts";
24 import { getAgentByName, isCrew } from "../../../core/agents.ts";
35 import { canAdmin } from "../../../core/repos.ts";
46 import { getUserByName } from "../../../core/users.ts";
@@ -49,7 +51,7 @@ export const tool: Tool = {
4951 if (checked === undefined) return bad("invalid", "`seat` is planner, builder or reviewer and `slots` a whole number from 0 (paused) to 8, the planner 0 or 1");
5052 if (args["dryRun"] !== undefined && typeof args["dryRun"] !== "boolean") return bad("invalid", "`dryRun` is true or false");
5153 if (user.kind === "agent") return bad("forbidden", "changing the crew is a person's call, not an agent's");
52 if (!canAdmin(app.db, repo, user)) return bad("forbidden", "only an admin of this repository changes its crew");
54 if (!canAdmin(app.db, repo, user)) return badBlocked("forbidden", notCrewAdminBlocked(ctx.app, user, repo));
5355 const was = seatSlotsOf(app.db, repo).find((p) => p.role === checked.role)!.slots;
5456 if (args["dryRun"] !== false)
5557 return good({ seat: checked.role, from: was, to: checked.slots, changes: was !== checked.slots, says: `This is the plan; nothing changed. ${seatSlotsSaid(checked.role, checked.slots)} Send dryRun: false to apply.` });
@@ -76,7 +78,7 @@ export const tool: Tool = {
7678 if (user.kind === "agent")
7779 return bad("forbidden", "changing the crew is a person's call, not an agent's");
7880 if (!canAdmin(app.db, repo, user))
79 return bad("forbidden", "only an admin of this repository changes its crew");
81 return badBlocked("forbidden", notCrewAdminBlocked(ctx.app, user, repo));
8082 if (!dryRun && !scopeAllows(ctx.auth.scope ?? "ro", "admin"))
8183 return bad("forbidden", "changing the crew needs an admin token");
8284
src/http/mcp/tools/email_verify.ts +3
@@ -1,4 +1,6 @@
11 import { resendVerification } from "../../../actions/verify.ts";
2 import { badBlocked } from "../shared.ts";
3 import { noMailBlocked } from "../../../actions/blocked_words.ts";
24 import { verifyWords } from "../../../actions/verify_words.ts";
35 import { good, bad, type Tool } from "../shared.ts";
46
@@ -11,6 +13,7 @@ export const tool: Tool = {
1113 async run(ctx, user) {
1214 const sent = await resendVerification(ctx.app, user);
1315 if (sent.ok) return good({ outcome: sent.value, says: verifyWords(sent.value) });
16 if (sent.error === "no_mail") return badBlocked("no_mail", noMailBlocked(ctx.app, user));
1417 return bad(sent.error, verifyWords(sent.error));
1518 },
1619 };
src/http/mcp/tools/flow.ts +3 −1
@@ -1,4 +1,6 @@
11 import { noteRead, telemetryReader } from "../../../actions/telemetry.ts";
2 import { badBlocked } from "../shared.ts";
3 import { noTelemetryBlocked } from "../../../actions/blocked_words.ts";
24 import { getIssue } from "../../../core/issues.ts";
35 import { getPull, pullDir, pullMergeState } from "../../../core/pulls.ts";
46 import { canWrite } from "../../../core/repos.ts";
@@ -131,7 +133,7 @@ export const tool: Tool = {
131133 if (args["repo"] === undefined) {
132134 const reader = telemetryReader(ctx.app, user);
133135 if (!reader)
134 return bad("forbidden", "only an admin of this forge, or an agent granted telemetry:read, reads its pipeline");
136 return badBlocked("forbidden", noTelemetryBlocked(ctx.app, user, "Reading this forge's pipeline takes the telemetry:read grant."));
135137 noteRead(ctx.app, user, reader, "flow");
136138 countRead("flow", user.username);
137139 return good(flowCached(ctx.app, reader));
src/http/mcp/tools/say.ts +3
@@ -1,4 +1,6 @@
11 import { mayView } from "../../../core/sealed.ts";
2 import { badBlocked } from "../shared.ts";
3 import { noTalkAccountBlocked } from "../../../actions/blocked_words.ts";
24 import { addCommentThrough } from "../../../actions/issues.ts";
35 import { getIssue } from "../../../core/issues.ts";
46 import { archiveConversation, createConversation, getConversation, listConversations, renameConversation, TOO_MANY_WORDS } from "../../../core/conversations.ts";
@@ -99,6 +101,7 @@ export const tool: Tool = {
99101 if (text.trim() === "" || text.length > WORDS_MAX) return bad("invalid_text", `text is 1 to ${WORDS_MAX} characters`);
100102 const named = args["conversation"] === undefined ? undefined : str(args["conversation"]);
101103 const talked = talk(ctx.app, user, text, [], "inject", named);
104 if (!talked.ok && talked.error === "no_account") return badBlocked("no_account", noTalkAccountBlocked(ctx.app, user));
102105 if (!talked.ok) return bad(talked.error, TALK_WORDS[talked.error][1]);
103106 return good({ says: talked.value.how === "steered" ? "Said to the forge's agent, mid-answer." : "The forge's agent is answering; read it in GET /api/v1/conversation/turns." });
104107 }
src/http/mcp/tools/system.ts +6 −4
@@ -1,4 +1,6 @@
11 import { noteRead, telemetryReader } from "../../../actions/telemetry.ts";
2 import { badBlocked } from "../shared.ts";
3 import { noTelemetryBlocked } from "../../../actions/blocked_words.ts";
24 import { systemWithReaders } from "../../../system/telemetry.ts";
35 import { scriptErrorCounts } from "../../script_errors.ts";
46 import { violationsByDirective, windowStart } from "../../csp_report.ts";
@@ -28,7 +30,7 @@ export const tool: Tool = {
2830 if (args["kind"] !== undefined) {
2931 if (args["kind"] === "routes") {
3032 const reader = telemetryReader(ctx.app, user);
31 if (!reader) return bad("forbidden", "only an admin of this forge, or an agent granted telemetry:read, reads its route timings");
33 if (!reader) return badBlocked("forbidden", noTelemetryBlocked(ctx.app, user, "Reading this forge's route timings takes the telemetry:read grant."));
3234 noteRead(ctx.app, user, reader, "system");
3335 return good({ routes: slowestRoutes(liveOf(ctx.app).perfRecord, Date.now()) });
3436 }
@@ -39,13 +41,13 @@ export const tool: Tool = {
3941 }
4042 if (args["kind"] === "size") {
4143 const reader = telemetryReader(ctx.app, user);
42 if (!reader) return bad("forbidden", "only an admin of this forge, or an agent granted telemetry:read, reads its database's size");
44 if (!reader) return badBlocked("forbidden", noTelemetryBlocked(ctx.app, user, "Reading this forge's database size takes the telemetry:read grant."));
4345 noteRead(ctx.app, user, reader, "system");
4446 return good(await dbSize.read(ctx.app.db, ctx.app.config.dataDir, undefined, ctx.app.log));
4547 }
4648 if (args["kind"] === "maintenance") {
4749 const reader = telemetryReader(ctx.app, user);
48 if (!reader) return bad("forbidden", "only an admin of this forge, or an agent granted telemetry:read, reads its maintenance workers");
50 if (!reader) return badBlocked("forbidden", noTelemetryBlocked(ctx.app, user, "Reading this forge's maintenance workers takes the telemetry:read grant."));
4951 noteRead(ctx.app, user, reader, "system");
5052 return good({ workers: weekRows(ctx.app.db, duties.map((d) => d.name)) });
5153 }
@@ -66,7 +68,7 @@ export const tool: Tool = {
6668 }
6769 const reader = telemetryReader(ctx.app, user);
6870 if (!reader)
69 return bad("forbidden", "only an admin of this forge, or an agent granted telemetry:read, reads its machine");
71 return badBlocked("forbidden", noTelemetryBlocked(ctx.app, user, "Reading this forge's machine figures takes the telemetry:read grant."));
7072 noteRead(ctx.app, user, reader, "system");
7173 const out = systemWithReaders(ctx.app, reader);
7274 countRead("system", user.username);
src/http/mcp/tools/telemetry_history.ts +3 −1
@@ -1,4 +1,6 @@
11 import { noteRead, telemetryReader } from "../../../actions/telemetry.ts";
2 import { badBlocked } from "../shared.ts";
3 import { noTelemetryBlocked } from "../../../actions/blocked_words.ts";
24 import { historyOver } from "../../../system/telemetry.ts";
35 import { good, bad, type Tool } from "../shared.ts";
46
@@ -17,7 +19,7 @@ export const tool: Tool = {
1719 return bad("invalid", "hours is a whole number from 1 to 72");
1820 const reader = telemetryReader(ctx.app, user);
1921 if (!reader)
20 return bad("forbidden", "only an admin of this forge, or an agent granted telemetry:read, reads its machine");
22 return badBlocked("forbidden", noTelemetryBlocked(ctx.app, user, "Reading this forge's machine figures takes the telemetry:read grant."));
2123 noteRead(ctx.app, user, reader, "history");
2224 return good({ hours, points: historyOver(ctx.app, hours) });
2325 },
src/http/server.ts +4
@@ -307,6 +307,7 @@ import { forgeLinkForm, forgeLinkRevoke, forgeLinkSubmit, forgeLinkUndo, forgeAr
307307 import { billDownload } from "./api/forge_bill.ts";
308308 import { forgesRefusedPage } from "../web/pages/forges-refused.ts";
309309 import { forgeReachAllow, forgeReachLater, forgeReachRevoke } from "../web/pages/hosted-forges.ts";
310 import { askAdminLater, askAdminSubmit } from "../web/studio/ask_admin.ts";
310311 import { forgeItSubmit } from "../web/pages/forge-it.ts";
311312 import { funnelSubmit } from "./funnel.ts";
312313 import { pricingDone, pricingOrder, pricingPage, resendPage, resendSubmit } from "../web/pages/pricing.ts";
@@ -1004,6 +1005,9 @@ export function buildRouter(): Router<Handler> {
10041005 router.add("POST", "/asks/proposal/:id/later", asksProposal("later"));
10051006 router.add("POST", "/asks/proposal/:id/again", asksProposal("again"));
10061007 router.add("POST", "/asks/decide", asksDecide);
1008 // Ask whoever can change something (`web/blocked.ts`), and their "Not now".
1009 router.add("POST", "/asks/admin", askAdminSubmit);
1010 router.add("POST", "/asks/admin/later", askAdminLater);
10071011 router.add("POST", "/asks/give-back", asksGiveBack);
10081012 router.add("POST", "/asks/decide/:id/undo", asksDecideUndo);
10091013 // What people asked of the crew, and what became of it (core/asked.ts).
src/kernel/ago.ts added +9
@@ -0,0 +1,9 @@
1 /** "just now", "2 minutes ago", "3 hours ago", "2 days ago": time as a sentence says it. */
2 export function agoWords(iso: string, now: number = Date.now()): string {
3 const minutes = Math.max(0, Math.floor((now - Date.parse(iso)) / 60_000));
4 const of = (n: number, unit: string): string => `${n} ${unit}${n === 1 ? "" : "s"} ago`;
5 if (!Number.isFinite(minutes) || minutes < 1) return "just now";
6 if (minutes < 60) return of(minutes, "minute");
7 if (minutes < 48 * 60) return of(Math.floor(minutes / 60), "hour");
8 return of(Math.floor(minutes / (24 * 60)), "day");
9 }
src/kernel/blocked.ts +10
@@ -89,6 +89,16 @@ export function whoCan(b: Pick<Blocked, "who" | "can">): string {
8989 : `${capital(b.who)} can ${b.can ?? "change this"}.`;
9090 }
9191
92 /**
93 * A sentence stored before anyone knows who will read it (a run's summary,
94 * a comment): what stands in the way, then who can change it, in words. A
95 * surface that knows its reader draws the way through from it instead
96 * (`actions/blocked_words.ts` `wayIn`).
97 */
98 export function storedText(says: string, who: string, can: string): string {
99 return `${says} ${whoCan({ who, can })}`;
100 }
101
92102 /** For a terminal, a log or a stored summary: the sentence, then the way through. */
93103 export function blockedText(b: Blocked): string {
94104 const next = nextStepText(b);
src/system/telemetry.ts +1 −1
@@ -273,6 +273,6 @@ export function welcome(app: App, now = new Date()) {
273273 "Anyone may propose. The bar decides what merges. A person lands it; an agent never does.",
274274 ],
275275 telemetry:
276 "Ask the owner for the telemetry:read grant to read the pipeline (flow) and the machine (system) from the API (/api/v1/telemetry/flow, /api/v1/telemetry/system) and MCP (tools flow, system), with private repositories and sealed values cut out. Every read is logged.",
276 "The telemetry:read grant lets an agent read the pipeline (flow) and the machine (system); to ask this forge's admins for it, POST /api/v1/asks/admin { want: \"telemetry_grant\", subject: your account's name } with an rw token. It reads from the API (/api/v1/telemetry/flow, /api/v1/telemetry/system) and MCP (tools flow, system), with private repositories and sealed values cut out. Every read is logged.",
277277 };
278278 }
src/web/blocked.ts +61 −24
@@ -5,16 +5,55 @@
55 * can, or, with no such action, who that is. Built from the toast and the
66 * button, so it reads as every other notice on the page does.
77 *
8 * `ask` is where the button posts as a form: the page's own twin of the
9 * action an agent calls with JSON (`Blocked.ask`). Its fields are the
10 * action's body, so the two cannot drift.
8 * The button posts a form: the page's own twin of the action an agent calls
9 * with JSON (`Blocked.ask`), carrying the action's body, so the two cannot
10 * drift. An ask to whoever can on this forge (`actions/ask_admin.ts`) is one
11 * button that submits the one form the layout draws, and lands back on the
12 * page it was pressed on; another ask (the host's) posts where `ask` says.
1113 */
1214
13 import { whoCan, type Blocked } from "../kernel/blocked.ts";
15 import { ASK_ADMIN_FORM, ASK_ADMIN_PATH } from "../actions/blocked_words.ts";
16 import { whoCan, type AskAction, type Blocked } from "../kernel/blocked.ts";
17 import type { Flash } from "./flash.ts";
1418 import { html, type Html } from "./html.ts";
1519 import { icon } from "./icons.ts";
1620 import { btn } from "./ui.ts";
1721
22 const hiddenFields = (fields: Readonly<Record<string, string | number>>): Html[] =>
23 Object.entries(fields).map(([name, value]) => html`<input type="hidden" name="${name}" value="${String(value)}" />`);
24
25 /**
26 * The one form every ask to whoever can on this forge is posted by; the layout draws it once,
27 * on a page that holds such a button.
28 */
29 export const ASK_FORM_ID = "ask-who-can";
30
31 /**
32 * That form: empty but for where to land back. A button anywhere on the page submits it
33 * (`askButton`), inside a paragraph or another form alike.
34 */
35 export function askFormShell(back: string): Html {
36 return html`<form method="post" action="${ASK_ADMIN_FORM}" id="${ASK_FORM_ID}" hidden><input type="hidden" name="back" value="${back}" /></form>`;
37 }
38
39 /** What the button carries: the want, then its subject. */
40 export const askValue = (body: Readonly<Record<string, string | number>>): string => `${body["want"] ?? ""} ${body["subject"] ?? ""}`.trim();
41
42 /** The button that asks whoever can on this forge. */
43 export function askButton(ask: { readonly value: string; readonly label: string }, variant: "primary" | "outline" = "outline"): Html {
44 return btn(ask.label, { size: "sm", variant, form: ASK_FORM_ID, name: "ask", value: ask.value });
45 }
46
47 /**
48 * The way to ask, when the page can offer it: the one button for this forge's own asks, or a form
49 * to the page's own route for another (the host's).
50 */
51 function formFor(ask: AskAction, o: { readonly ask?: string }, variant: "primary" | "outline"): Html | null {
52 if (ask.path === ASK_ADMIN_PATH) return askButton({ value: askValue(ask.body), label: ask.label }, variant);
53 if (o.ask === undefined) return null;
54 return html`<form method="post" action="${o.ask}">${hiddenFields(ask.body)}${btn(ask.label, { size: "sm", variant })}</form>`;
55 }
56
1857 export function blockedNote(
1958 b: Blocked,
2059 o: { readonly id?: string; readonly ask?: string } = {},
@@ -22,24 +61,11 @@ export function blockedNote(
2261 const way =
2362 b.link !== undefined
2463 ? btn(b.link.label, { href: b.link.href, size: "sm", variant: "primary" })
25 : b.ask !== undefined && o.ask !== undefined
26 ? html`<form method="post" action="${o.ask}">
27 ${Object.entries(b.ask.body).map(
28 ([name, value]) =>
29 html`<input
30 type="hidden"
31 name="${name}"
32 value="${String(value)}"
33 />`,
34 )}
35 ${btn(b.ask.label, { size: "sm", variant: "primary" })}
36 </form>`
64 : b.ask !== undefined
65 ? formFor(b.ask, o, "primary")
3766 : null;
3867 // With no action to offer, who can change it is said in words.
39 const who =
40 way === null && b.who !== undefined
41 ? ` ${whoCan(b)}`
42 : "";
68 const who = way === null && b.who !== undefined ? ` ${whoCan(b)}` : "";
4369 return html`<div
4470 class="toast blocked"
4571 data-tone="attn"
@@ -55,10 +81,21 @@ export function blockedNote(
5581
5682 /**
5783 * The way through alone, for a sentence already on the page: the link for a
58 * reader who can change it, or who can for one who cannot.
84 * reader who can change it; for one who cannot, who can, and the button that
85 * asks them.
5986 */
6087 export function blockedWay(b: Blocked): Html {
61 return b.link !== undefined
62 ? html`<a href="${b.link.href}">${b.link.label}</a>.`
63 : html`${whoCan(b)}`;
88 if (b.link !== undefined) return html`<a href="${b.link.href}" data-blocked="fix">${b.link.label}</a>.`;
89 const ask = b.ask === undefined ? null : formFor(b.ask, {}, "outline");
90 return html`${whoCan(b)}${ask === null ? null : html` ${ask}`}`;
91 }
92
93 /**
94 * The same value as a flash: the sentence, then the link, or the button that asks, or who can in
95 * words.
96 */
97 export function blockedFlash(b: Blocked, tone: NonNullable<Flash["tone"]> = "attn"): Flash {
98 if (b.link !== undefined) return { tone, message: b.says, link: b.link };
99 const message = `${b.says} ${whoCan(b)}`.trim();
100 return b.ask !== undefined && b.ask.path === ASK_ADMIN_PATH ? { tone, message, ask: { value: askValue(b.ask.body), label: b.ask.label } } : { tone, message };
64101 }
src/web/flash.ts +18
@@ -24,6 +24,11 @@ export interface Flash {
2424 code?: string;
2525 /** One same-origin link after the message ("see it live"). */
2626 link?: { href: string; label: string };
27 /**
28 * One button after the message that asks whoever can (`web/blocked.ts` `blockedFlash`): what
29 * its button carries, and what it says.
30 */
31 ask?: { value: string; label: string };
2732 }
2833
2934 // Cookies cap out around 4KB; a flash is a sentence, not a payload.
@@ -67,9 +72,22 @@ export function readFlash(request: Request): Flash | undefined {
6772 ? { code: value.code.slice(0, 512) }
6873 : {}),
6974 ...linkOf(value.link),
75 ...askOf(value.ask),
7076 };
7177 }
7278
79 /**
80 * A flash ask read back: what the button carries and a short label, or nothing. The route it
81 * posts to checks the value.
82 */
83 function askOf(value: unknown): { ask?: NonNullable<Flash["ask"]> } {
84 if (typeof value !== "object" || value === null) return {};
85 const { value: carried, label } = value as Record<string, unknown>;
86 if (typeof label !== "string" || label === "" || label.length > 80) return {};
87 if (typeof carried !== "string" || carried === "" || carried.length > 340) return {};
88 return { ask: { value: carried, label } };
89 }
90
7391 /** A flash link read back: a same-origin path and a short label, or nothing. */
7492 function linkOf(value: unknown): { link?: NonNullable<Flash["link"]> } {
7593 if (typeof value !== "object" || value === null) return {};
src/web/layout.ts +10 −1
@@ -63,6 +63,7 @@ import {
6363 import { prefersJson } from "./form.ts";
6464 import { notePhase } from "../core/route_timing.ts";
6565 import { html, raw, when, type Html } from "./html.ts";
66 import { ASK_FORM_ID, askButton, askFormShell } from "./blocked.ts";
6667 import { noRoom } from "../spawn/door.ts";
6768 import { takeNotice } from "../core/access_link.ts";
6869 import { quotaFull } from "../spawn/quota.ts";
@@ -595,6 +596,13 @@ function overlays(): Html {
595596 </dialog>`;
596597 }
597598
599 /**
600 * Whether the page holds a button that asks whoever can (`web/blocked.ts`): only then is its one
601 * form drawn.
602 */
603 const asksWhoCan = (body: Html, flash: Flash | undefined): boolean =>
604 flash?.ask !== undefined || body.text.includes(`form="${ASK_FORM_ID}"`);
605
598606 function flashToast(flash: Flash): Html {
599607 const tone = flash.tone ?? "success";
600608 const glyph =
@@ -606,6 +614,7 @@ function flashToast(flash: Flash): Html {
606614 flash.link,
607615 (link) => html` · <a href="${link.href}">${link.label}</a>`,
608616 )}
617 ${when(flash.ask, (ask) => html` ${askButton(ask)}`)}
609618 ${when(
610619 flash.code,
611620 (code) =>
@@ -781,7 +790,7 @@ export function page(options: PageOptions, status = 200): Response {
781790 : "shell"}"
782791 id="main"
783792 >
784 ${flash ? flashToast(flash) : null}${options.body}
793 ${flash ? flashToast(flash) : null}${options.body}${asksWhoCan(options.body, flash) ? askFormShell(ctx.url.pathname) : null}
785794 </main>
786795 ${options.bare ? null : footer(ctx, options.foot)} ${overlays()}
787796 ${paletteIndex(ctx, options.palette ?? [])}`;
src/web/pages/account.ts +7 −10
@@ -62,8 +62,8 @@ import {
6262 import { accountSections } from "./origins.ts";
6363 import { field, readForm } from "../form.ts";
6464 import { html, when, type Html } from "../html.ts";
65 import { noMailBlocked } from "../../actions/blocked_words.ts";
66 import { whoCan } from "../../kernel/blocked.ts";
65 import { mailCappedBlocked, noMailBlocked } from "../../actions/blocked_words.ts";
66 import { blockedFlash } from "../blocked.ts";
6767 import { planRow } from "../plan_row.ts";
6868 import { coresRow } from "../cores_row.ts";
6969 import { coresLine } from "../../spawn/cores.ts";
@@ -341,12 +341,11 @@ export async function resendVerifyLink(ctx: Ctx): Promise<Response> {
341341 const sent = await resendVerification(ctx.app, ctx.auth.user);
342342 // No mail: said in the reader's terms, with the page that verifies when they are an admin, and who can when they are not (`kernel/blocked.ts`).
343343 if (!sent.ok && sent.error === "no_mail" && ctx.auth.user !== undefined) {
344 const blocked = noMailBlocked(ctx.auth.user);
345 return flashTo(ctx, "/settings", {
346 message: blocked.link === undefined ? `${blocked.says} ${whoCan(blocked)}` : blocked.says,
347 ...(blocked.link === undefined ? {} : { link: blocked.link }),
348 });
344 return flashTo(ctx, "/settings", blockedFlash(noMailBlocked(ctx.app, ctx.auth.user), "success"));
349345 }
346 // The day's mail is spent: tomorrow sends it, or an admin verifies by hand.
347 if (!sent.ok && sent.error === "capped" && ctx.auth.user !== undefined)
348 return flashTo(ctx, "/settings", blockedFlash(mailCappedBlocked(ctx.app, ctx.auth.user), "success"));
350349 const message = sent.ok
351350 ? sent.value === "sent"
352351 ? "A new link is on its way."
@@ -355,9 +354,7 @@ export async function resendVerifyLink(ctx: Ctx): Promise<Response> {
355354 ? "A link was sent a moment ago. Check your inbox, or try again in a few minutes."
356355 : sent.error === "no_mail"
357356 ? "This forge sends no mail yet."
358 : sent.error === "capped"
359 ? "The forge has sent all the mail it may for now. Try again tomorrow, or ask its owner to verify you."
360 : "The link could not be sent. Try again.";
357 : "The link could not be sent. Try again.";
361358 return flashTo(ctx, "/settings", { message });
362359 }
363360
src/web/pages/apps.ts +1 −1
@@ -411,7 +411,7 @@ function newAppForm(
411411 ? html`<p class="muted small mb">
412412 ${icon("bot")} No agents on this forge yet, so this app has no
413413 crew to hand the first issue to.
414 ${blockedWay(noAgentsBlocked(user))}
414 ${blockedWay(noAgentsBlocked(ctx.app, user))}
415415 </p>`
416416 : selectField({
417417 label: "Agent",
src/web/pages/config.ts +7 −2
@@ -20,6 +20,9 @@
2020 * its line.
2121 */
2222
23 import type { Flash } from "../flash.ts";
24 import { blockedFlash } from "../blocked.ts";
25 import { FORK_NEEDS_MEMBER, notMemberBlocked } from "../../actions/blocked_words.ts";
2326 import { editFiles } from "../../actions/contents.ts";
2427 import { proposeEdit, proposeEditText } from "../../actions/propose_edit.ts";
2528 import { canAdmin } from "../../core/repos.ts";
@@ -93,7 +96,7 @@ interface FormState {
9396 readonly found: FoundSchema | undefined;
9497 readonly errors?: ReadonlyMap<string, string>;
9598 readonly typed?: ReadonlyMap<string, string>;
96 readonly flash?: { tone: "danger" | "success"; message: string };
99 readonly flash?: Flash;
97100 }
98101
99102 const hidden = (s: FormState, doc: Json): Html => html`<input type="hidden" name="ref" value="${s.ref}" />
@@ -329,7 +332,9 @@ export async function configSubmit(ctx: Ctx): Promise<Response> {
329332 const proposed = await proposeEdit(ctx.app, user, repo, { base: ref, files, message, title: subject, body: description });
330333 if (!proposed.ok) {
331334 const words = proposeEditText(proposed.error);
332 state = { ...state, flash: { tone: "danger", message: words } };
335 // A guest is told who can make them a member, with the button that asks (`web/blocked.ts`).
336 const guest = proposed.error.step === "fork" && proposed.error.reason === "not_member";
337 state = { ...state, flash: guest ? blockedFlash(notMemberBlocked(ctx.app, user, FORK_NEEDS_MEMBER), "danger") : { tone: "danger", message: words } };
333338 return reviewPage(ctx, scope, state, { before: current, after }, { message: subject, description });
334339 }
335340 const pull = proposed.value.pull;
src/web/pages/home_flow.ts +11 −2
@@ -71,6 +71,8 @@ import type { ReachAsk } from "../../core/child_reach.ts";
7171 import { reachNeeds } from "../../spawn/child_reach.ts";
7272 import { archiveNeeds, type ClientRow } from "../../spawn/clients.ts";
7373 import { reachNeed } from "./hosted-forges.ts";
74 import { adminAskNeed } from "../studio/ask_admin.ts";
75 import { asksToAnswer, type AskView } from "../../actions/ask_admin.ts";
7476 import { inProcessNeed, whereOf } from "../../spawn/where.ts";
7577 import { untoldAnswer, markTold } from "../../core/requests.ts";
7678 import { YOURE_IN_MESSAGE } from "../../actions/users.ts";
@@ -306,6 +308,11 @@ interface StripViewer {
306308 readonly everyday?: boolean;
307309 /** What hosted forges asked to reach and no admin has answered (`spawn/child_reach.ts`); an admin's only. */
308310 readonly reach?: readonly ReachAsk[];
311 /**
312 * What people here asked this viewer, as one who can change it, to change
313 * (`actions/ask_admin.ts`).
314 */
315 readonly asked?: readonly AskView[];
309316 /** Hosted forges proposed for archive (`spawn/archive_proposal.ts`); an admin's only. */
310317 readonly archive?: readonly ClientRow[];
311318 /** Forges that run inside this forge's own process and could be in a sandbox; an admin's only. */
@@ -345,6 +352,8 @@ function needsOf(picture: LanePicture, viewer: StripViewer, dataDir: string, now
345352 ...alarms,
346353 // A person on a hosted forge is stopped until this is answered: first among what can wait.
347354 ...(viewer.isAdmin ? (viewer.reach ?? []).map((a, n) => ({ ...reachNeed(a, n), tone: "notice" as const })) : []),
355 // A person here is stopped until one who can change it does: theirs to answer, admin or not.
356 ...(viewer.asked ?? []).map((a, n) => ({ ...adminAskNeed(a, n), tone: "notice" as const })),
348357 // Proposed, never done by itself: one line, the recommended choice one tap away.
349358 ...(viewer.isAdmin && (viewer.archive ?? []).length > 0 ? [archiveNeed(viewer.archive!)] : []),
350359 // Work hidden inside this forge's own process: one line for all of them, and /forges moves
@@ -567,7 +576,7 @@ export async function homeFlowPage(ctx: Ctx, known?: { readonly spawned: Awaited
567576 // A spawned forge's owner is a client: the forge-wide figures are not theirs to see, whole home or lean.
568577 const spawned = known !== undefined ? known.spawned : await timePhaseAsync(ctx.request, "spawned", () => spawnedForge(ctx.app));
569578 const wide = user.isAdmin && spawned === undefined;
570 const strip = picture === undefined ? readingStrip() : stripRegion(picture, { id: user.id, isAdmin: wide, ...(wide && forgeHasNoKey(ctx.app) ? { noKey: true as const } : {}), everyday: askForEveryday(ctx.app.db, user), ...(wide ? { reach: reachNeeds(ctx.app), archive: archiveNeeds(ctx.app), inProcess: await inProcessForges(ctx.app, now) } : {}) }, ctx.app.config.dataDir, now);
579 const strip = picture === undefined ? readingStrip() : stripRegion(picture, { id: user.id, isAdmin: wide, ...(wide && forgeHasNoKey(ctx.app) ? { noKey: true as const } : {}), everyday: askForEveryday(ctx.app.db, user), asked: asksToAnswer(ctx.app, user), ...(wide ? { reach: reachNeeds(ctx.app), archive: archiveNeeds(ctx.app), inProcess: await inProcessForges(ctx.app, now) } : {}) }, ctx.app.config.dataDir, now);
571580 // What the old home also carried and is not a lane: the box that tells the crew (with Notes and
572581 // Talk), the welcome after an account is allowed, a
573582 // spawned forge's address, and a stranger's request for an account. The everyday-account ask is
@@ -698,7 +707,7 @@ export async function liveStripFragment(ctx: Ctx): Promise<Response> {
698707 const picture = await timePhaseAsync(ctx.request, "picture", () => lanePicture(ctx.app.db, optionsOf(ctx, user), "lane", now));
699708 const rendering = performance.now();
700709 const wide = user.isAdmin && (await spawnedForge(ctx.app)) === undefined;
701 const res = fragment(picture === undefined ? readingStrip() : stripRegion(picture, { id: user.id, isAdmin: wide, ...(wide && forgeHasNoKey(ctx.app) ? { noKey: true as const } : {}), everyday: askForEveryday(ctx.app.db, user), ...(wide ? { reach: reachNeeds(ctx.app), archive: archiveNeeds(ctx.app), inProcess: await inProcessForges(ctx.app, now) } : {}) }, ctx.app.config.dataDir, now), { request: ctx.request });
710 const res = fragment(picture === undefined ? readingStrip() : stripRegion(picture, { id: user.id, isAdmin: wide, ...(wide && forgeHasNoKey(ctx.app) ? { noKey: true as const } : {}), everyday: askForEveryday(ctx.app.db, user), asked: asksToAnswer(ctx.app, user), ...(wide ? { reach: reachNeeds(ctx.app), archive: archiveNeeds(ctx.app), inProcess: await inProcessForges(ctx.app, now) } : {}) }, ctx.app.config.dataDir, now), { request: ctx.request });
702711 notePhase(ctx.request, "render", performance.now() - rendering);
703712 return res;
704713 }
src/web/pages/migrate.ts +1 −1
@@ -509,7 +509,7 @@ function migrateForm(
509509 ? html`<p class="muted small mb">
510510 ${icon("bot")} No agents on this forge yet, so there is no crew to
511511 hand the migration to.
512 ${blockedWay(noAgentsBlocked(user))}
512 ${blockedWay(noAgentsBlocked(ctx.app, user))}
513513 </p>`
514514 : html`${selectField({
515515 label: "Agent",
src/web/pages/model.ts +4 −1
@@ -6,11 +6,14 @@
66 * card). A token is typed once and never shown again.
77 */
88
9 import { blockedWay } from "../blocked.ts";
10 import { noBudgetBlocked } from "../../actions/blocked_words.ts";
911 import { ADD_MESSAGES, addOwnModel, setAccountCeilings, setAccountGrant } from "../../actions/model_grant.ts";
1012 import { SUBSCRIPTION_ADDED } from "../../actions/model_words.ts";
1113 import { CEILING_MAX_USD, dailyLeft, getAccountCeiling } from "../../core/account_ceiling.ts";
1214 import {
1315 budgetLine,
16 NO_BUDGET_LINE,
1417 getModelGrant,
1518 GRANT_MAX_USD,
1619 ownSubscription,
@@ -68,7 +71,7 @@ export function modelPage(ctx: Ctx): Response {
6871 html`<section class="settings-block">
6972 <h2>Your model budget</h2>
7073 ${grant === undefined || own || user.isAdmin
71 ? html`<p class="muted" id="model-budget">${budget}</p>`
74 ? html`<p class="muted" id="model-budget">${budget} ${budget === NO_BUDGET_LINE ? blockedWay(noBudgetBlocked(ctx.app, user, user)) : null}</p>`
7275 : html`<ul class="list setting-list" id="model-budget">${row({
7376 title: "A grant from an admin",
7477 meta: html`${budget}`,
src/web/pages/origin-reach.ts +2 −10
@@ -29,16 +29,8 @@ import { html, type Html } from "../html.ts";
2929 import { flashTo } from "../layout.ts";
3030 import { badge, btn, row } from "../ui.ts";
3131
32 /** "just now", "2 minutes ago", "3 hours ago", "2 days ago": time as a sentence says it. */
33 export function agoWords(iso: string, now: number = Date.now()): string {
34 const minutes = Math.max(0, Math.floor((now - Date.parse(iso)) / 60_000));
35 const of = (n: number, unit: string): string =>
36 `${n} ${unit}${n === 1 ? "" : "s"} ago`;
37 if (!Number.isFinite(minutes) || minutes < 1) return "just now";
38 if (minutes < 60) return of(minutes, "minute");
39 if (minutes < 48 * 60) return of(Math.floor(minutes / 60), "hour");
40 return of(Math.floor(minutes / (24 * 60)), "day");
41 }
32 export { agoWords } from "../../kernel/ago.ts";
33 import { agoWords } from "../../kernel/ago.ts";
4234
4335 /** What the gate's refusal of `host` says to the person on this forge, and the ask it offers. */
4436 export async function gateNote(ctx: Ctx, host: string): Promise<Blocked> {
src/web/pages/search.ts +1 −1
@@ -635,7 +635,7 @@ const DESTRUCTIVE: {
635635 describe: (m) => ({
636636 verb: "Revoke",
637637 title: `Revoke the app's grant on ${decodeURIComponent(m[3] ?? "")}?`,
638 detail: `${m[1]}/${m[2]}'s cells can no longer reach that destination, from their next start. A site admin can grant it again while forge.json still asks for it.`,
638 detail: `${m[1]}/${m[2]}'s cells can no longer reach that destination, from their next start. It can be granted again on the app's settings while forge.json still asks for it.`,
639639 phrase: "",
640640 }),
641641 },
src/web/pages/settings.ts +8 −8
@@ -8,6 +8,8 @@
88 * same-origin POST and every one of them says what happened.
99 */
1010
11 import { blockedWay } from "../blocked.ts";
12 import { privateDestinationBlocked } from "../../actions/blocked_words.ts";
1113 import { templateSaid } from "../../core/template_words.ts";
1214 import { POLISH_SHARE_DEFAULT, POLISH_SHARE_MAX } from "../../crew/polish_share.ts";
1315 import { appLimitWords } from "../../actions/app_limit.ts";
@@ -814,8 +816,8 @@ function appSettingsView(
814816 <div class="mt">
815817 ${appDomainsView(base, domains.ok ? domains.value : undefined)}
816818 </div>
817 ${when(blocked !== undefined, () => html`<div class="mt">${blockedNote(base, blocked!)}</div>`)}
818 ${when(egress !== undefined, () => html`<div class="mt">${appEgressView(base, egress!)}</div>`)}
819 ${when(blocked !== undefined, () => html`<div class="mt">${blockedNote(base, blocked!, (destination) => blockedWay(privateDestinationBlocked(ctx.app, ctx.auth.user, repo, destination, "")))}</div>`)}
820 ${when(egress !== undefined, () => html`<div class="mt">${appEgressView(base, egress!, (destination) => blockedWay(privateDestinationBlocked(ctx.app, ctx.auth.user, repo, destination, "")))}</div>`)}
819821 <div class="mt">
820822 <form method="post" action="${base}/settings">
821823 <input type="hidden" name="card" value="template" />
@@ -1360,7 +1362,7 @@ export async function appDomainDelete(ctx: Ctx): Promise<Response> {
13601362 * granted it; Grant and Revoke only for a site admin. The last few changes
13611363 * follow, so a revoke is still on the page after the grant is gone.
13621364 */
1363 function appEgressView(base: string, egress: EgressView): Html {
1365 function appEgressView(base: string, egress: EgressView, ask: (destination: string) => Html): Html {
13641366 const at = (destination: string) =>
13651367 `${base}/settings/app/egress/${encodeURIComponent(destination)}`;
13661368 const rows = egress.rows.map((r) =>
@@ -1373,7 +1375,7 @@ function appEgressView(base: string, egress: EgressView): Html {
13731375 meta:
13741376 r.granted && r.grantedAt !== null
13751377 ? html`Granted by ${r.grantedBy ?? "someone"} ${time(r.grantedAt)}`
1376 : html`Nothing reaches it until a site admin grants it.`,
1378 : html`Nothing reaches it until it is granted. ${egress.canChange ? null : ask(r.destination)}`,
13771379 trail: egress.canChange
13781380 ? html`<div class="row-fields">
13791381 ${r.granted
@@ -1407,9 +1409,7 @@ function appEgressView(base: string, egress: EgressView): Html {
14071409 </p>`
14081410 : html`<p class="muted small">
14091411 Each is an exact address and port forge.json asks for; every other
1410 host is refused.${egress.canChange
1411 ? null
1412 : " Only a site admin grants or revokes."}
1412 host is refused.
14131413 </p>
14141414 <ul class="list setting-list">
14151415 ${rows}
@@ -1478,7 +1478,7 @@ export function appBlocked(how: "allow" | "ignore") {
14781478
14791479 function blockedMessage(value: string | Allowed): string {
14801480 if (typeof value === "string") return `Ignoring ${value}.`;
1481 if (value.needsGrant) return `${value.entry} is in forge.json; a site admin grants it below.`;
1481 if (value.needsGrant) return `${value.entry} is in forge.json. It is a private destination, so it waits for a grant: see Private destinations asked for, below.`;
14821482 return value.committed
14831483 ? `${value.entry} is allowed now and committed to forge.json.`
14841484 : `${value.entry} is allowed now; forge.json could not be edited, add it by hand.`;
src/web/pages/talk.ts +3
@@ -14,6 +14,8 @@
1414 * their id, the agent acts with their permissions (`crew/conversation.ts`).
1515 */
1616
17 import { blockedFlash } from "../blocked.ts";
18 import { noTalkAccountBlocked } from "../../actions/blocked_words.ts";
1719 import type { Database } from "bun:sqlite";
1820 import { cancelTalk, queuedTalk, TALK_WORDS, talk, talkAgain } from "../../actions/talk.ts";
1921 import { REFUSED, sayNo, sayYes, UNDO_REFUSED, undoReceipt, waitingConfirms } from "../../actions/conversation_confirms.ts";
@@ -430,6 +432,7 @@ export async function talkSend(ctx: Ctx): Promise<Response> {
430432 return flashTo(ctx, `${here}#end`, { tone: "danger", message: `Say something, up to ${WORDS_MAX} characters.` });
431433 const about = form.get("about");
432434 const said = talk(ctx.app, user, text, [], "queue", conversation.id, typeof about === "string" ? about : null);
435 if (!said.ok && said.error === "no_account") return flashTo(ctx, `${here}#end`, blockedFlash(noTalkAccountBlocked(ctx.app, user), "danger"));
433436 if (!said.ok) return flashTo(ctx, `${here}#end`, { tone: "danger", message: TALK_WORDS[said.error][1] });
434437 return flashTo(ctx, `${here}#end`, { tone: "success", message: "Sent. Reload to see the answer." });
435438 }
src/web/studio/ask_admin.ts added +66
@@ -0,0 +1,66 @@
1 /**
2 * The page's side of asking whoever can (`actions/ask_admin.ts`): the form a
3 * blocked note's button posts (`web/blocked.ts`), "Not now" for the one who
4 * answers, and the ask as the home's line says it.
5 */
6
7 import { ASK_ADMIN_WORDS, askAdmin, putAsideAsk, type AskView } from "../../actions/ask_admin.ts";
8 import type { Ctx } from "../../http/context.ts";
9 import { agoWords } from "../../kernel/ago.ts";
10 import { signInFirst } from "../chrome.ts";
11 import { backTo, field, readForm } from "../form.ts";
12 import { html, type Html } from "../html.ts";
13 import { flashTo } from "../layout.ts";
14 import { btn } from "../ui.ts";
15
16 // POST /asks/admin — ask whoever can; back where the person was, with how it stands said once.
17 export async function askAdminSubmit(ctx: Ctx): Promise<Response> {
18 if (ctx.auth.user === undefined) return signInFirst(ctx);
19 const form = await readForm(ctx, "rw");
20 if (form instanceof Response) return form;
21 // The button carries the want, then its subject (`web/blocked.ts` `askValue`).
22 const [want = "", ...subject] = field(form, "ask").split(" ");
23 const asked = askAdmin(ctx.app, ctx.auth.user, { want, subject: subject.join(" ") });
24 return flashTo(
25 ctx,
26 backTo(form, "/"),
27 asked.ok
28 ? {
29 message:
30 asked.value.state === "later"
31 ? "They put this aside earlier today, so it was not raised again. It is still on their list."
32 : `Asked. ${asked.value.repoId === null ? "This forge's admins" : "The repository's admins"} see it on their home page, with the link to where it is changed.`,
33 }
34 : { tone: "danger", message: ASK_ADMIN_WORDS[asked.error] },
35 );
36 }
37
38 // POST /asks/admin/later — "Not now", by one who answers.
39 export async function askAdminLater(ctx: Ctx): Promise<Response> {
40 if (ctx.auth.user === undefined) return signInFirst(ctx);
41 const form = await readForm(ctx, "rw");
42 if (form instanceof Response) return form;
43 const done = putAsideAsk(ctx.app, ctx.auth.user, { username: field(form, "username"), want: field(form, "want"), subject: field(form, "subject") });
44 return flashTo(
45 ctx,
46 backTo(form, "/"),
47 done.ok
48 ? { message: `Put aside. ${field(form, "username")} is told it waits; the control is still where it was.` }
49 : { tone: "danger", message: "That was already answered, or is no longer there." },
50 );
51 }
52
53 /**
54 * One waiting ask as the home's line says it: the sentence links to the exact control, with "Not
55 * now" beside it; `n` keeps the form ids apart.
56 */
57 export function adminAskNeed(a: AskView, n: number): { says: string; href: string; after: Html; forms: Html } {
58 return {
59 says: `${a.sentence} (${agoWords(a.lastAt)})`,
60 href: a.href,
61 after: html`<span class="hf-need-acts">${btn("Not now", { size: "sm", variant: "ghost", form: `ask-later-${n}`, label: `Put aside what ${a.username} asked for` })}</span>`,
62 forms: html`<form method="post" action="/asks/admin/later" id="ask-later-${n}" hidden>
63 <input type="hidden" name="username" value="${a.username}" /><input type="hidden" name="want" value="${a.want}" /><input type="hidden" name="subject" value="${a.subject}" /><input type="hidden" name="back" value="/" />
64 </form>`,
65 };
66 }
src/web/studio/blocked.ts +2 −2
@@ -8,7 +8,7 @@ import type { BlockedView } from "../../actions/egress_refused.ts";
88 import { html, type Html } from "../html.ts";
99 import { btn, row } from "../ui.ts";
1010
11 export function blockedNote(base: string, view: BlockedView): Html | null {
11 export function blockedNote(base: string, view: BlockedView, ask: (destination: string) => Html): Html | null {
1212 if (view.rows.length === 0 && view.liveOnly.length === 0) return null;
1313 const at = (destination: string, verb: string) =>
1414 `${base}/settings/app/blocked/${encodeURIComponent(destination)}/${verb}`;
@@ -16,7 +16,7 @@ export function blockedNote(base: string, view: BlockedView): Html | null {
1616 row({
1717 title: html`${r.line}`,
1818 meta: r.private
19 ? html`<span class="muted small">A private destination: only a site admin allows it.</span>`
19 ? html`<span class="muted small">A private destination. ${view.canAllowPrivate ? null : ask(r.destination)}</span>`
2020 : html``,
2121 trail: html`<div class="row-fields">
2222 ${r.private && !view.canAllowPrivate
src/web/studio/crew.ts +3 −3
@@ -223,7 +223,7 @@ function teamCard(
223223 : team.auto
224224 ? `Auto mode is on (${team.mode}): the team works on its own.`
225225 : "Auto mode is off: the team works when asked. Turn it on under On its own. A list's number is how many work at once; 0 pauses it.";
226 const nobody = crew.length > 0 ? null : nobodyLine(everyone.length > 0, ctx.auth.user?.isAdmin === true);
226 const nobody = crew.length > 0 ? null : nobodyLine(ctx, everyone.length > 0);
227227 return html`<section class="settings-block" id="team">
228228 <h2>Your team</h2>
229229 <p class="small" id="auto-mode" data-auto="${team.auto ? "on" : "off"}">
@@ -295,12 +295,12 @@ function maintainerRow(
295295 * no agent exists on the forge — where one is made (a forge admin) or who
296296 * can make one (anyone else).
297297 */
298 function nobodyLine(agentsExist: boolean, forgeAdmin: boolean): Html {
298 function nobodyLine(ctx: Ctx, agentsExist: boolean): Html {
299299 return html`<p class="small" id="crew-nobody">
300300 <strong>Nobody yet.</strong>
301301 ${agentsExist
302302 ? "Pick an agent in a list below."
303 : html`${noAgentsBlocked({ isAdmin: forgeAdmin }).says} ${blockedWay(noAgentsBlocked({ isAdmin: forgeAdmin }))}`}
303 : html`${noAgentsBlocked(ctx.app, ctx.auth.user).says} ${blockedWay(noAgentsBlocked(ctx.app, ctx.auth.user))}`}
304304 </p>`;
305305 }
306306
src/web/studio/crew_key.ts +5 −3
@@ -7,6 +7,8 @@
77 * echoed, never sent to the host.
88 */
99
10 import { blockedWay } from "../blocked.ts";
11 import { noKeyBlocked } from "../../actions/blocked_words.ts";
1012 import { existsSync } from "node:fs";
1113 import { join } from "node:path";
1214 import type { App } from "../../app.ts";
@@ -99,13 +101,13 @@ export function crewKeyCard(ctx: Ctx, compact = false): Html | null {
99101 if (compact) {
100102 if (crewCanRun(ctx.app)) return null;
101103 return html`<p class="small muted" id="crew-key-note" role="status">${icon("alert")} The crew needs a model key to start.
102 ${admin ? html`<a href="/feed#crew-key-note">Add one on the feed page</a>.` : "Ask this forge's admin to add one."}</p>`;
104 ${blockedWay(noKeyBlocked(ctx.app, ctx.auth.user))}</p>`;
103105 }
104106 const credit = includedCredit(ctx.app);
105107 if (credit !== undefined && credit.leftUsd > 0)
106108 return html`<section class="settings-block" id="crew-key-note" role="status">
107109 <p class="small muted">${icon("key")} The crew is building on ${usdWords(credit.leftUsd)} of ${usdWords(credit.capUsd)} included credit.
108 ${admin ? "Add your own key any time to keep building after it:" : "Its admin can add a key to keep building after it."}</p>
110 ${admin ? "Add your own key any time to keep building after it:" : html`A key keeps it building after that. ${blockedWay(noKeyBlocked(ctx.app, ctx.auth.user))}`}</p>
109111 ${admin ? keyField() : null}
110112 </section>`;
111113 const said =
@@ -113,7 +115,7 @@ export function crewKeyCard(ctx: Ctx, compact = false): Html | null {
113115 ? "The included credit is spent. Add your own key to keep building, or wait for next month."
114116 : "The crew needs a model key to start. Paste yours.";
115117 return html`<section class="settings-block" id="crew-key-note" role="status">
116 <p class="small muted">${icon("alert")} ${said}${admin ? "" : " Ask this forge's admin."}</p>
118 <p class="small muted">${icon("alert")} ${admin ? said : html`${credit !== undefined ? "The included credit is spent. A model key keeps it building, or wait for next month." : "The crew needs a model key to start."} ${blockedWay(noKeyBlocked(ctx.app, ctx.auth.user))}`}</p>
117119 ${admin ? keyField() : null}
118120 </section>`;
119121 }
src/web/studio/land_as_is.ts +3 −1
@@ -9,6 +9,8 @@
99 * refusals.
1010 */
1111
12 import { blockedWay } from "../blocked.ts";
13 import { noKeyBlocked } from "../../actions/blocked_words.ts";
1214 import type { App } from "../../app.ts";
1315 import { requireWriter } from "../../actions/access.ts";
1416 import { getAppByRepo } from "../../core/apps.ts";
@@ -58,7 +60,7 @@ const landForm = (repo: Repo, pull: Pull): Html =>
5860 const keyOffer = (ctx: Ctx): Html =>
5961 ctx.auth.user?.isAdmin === true
6062 ? btn("Add a key", { href: ADD_KEY_HREF, size: "sm" })
61 : html`<span class="muted small">Only this forge's admin can add a key.</span>`;
63 : html`<span class="muted small">${blockedWay(noKeyBlocked(ctx.app, ctx.auth.user))}</span>`;
6264
6365 /** The pull's own page: the sentence, the button, the preview beside it, the key. */
6466 export function landAsIs(ctx: Ctx, repo: Repo, pull: Pull): Html | null {
src/web/studio/run.ts +3
@@ -8,6 +8,8 @@
88 * at `?all=1`.
99 */
1010
11 import { wayIn } from "../../actions/blocked_words.ts";
12 import { blockedWay } from "../blocked.ts";
1113 import { checkSteps, stepWord, type LookVitals } from "../../checks/summary.ts";
1214 import { vitalsTable } from "./vitals.ts";
1315 import { parseTestsRow, testsRowWords } from "../../checks/tests-row.ts";
@@ -199,6 +201,7 @@ export async function runView(
199201 )}
200202 </div>
201203 <p class="mt" id="run-summary">${run.summary}</p>
204 ${when(wayIn(ctx.app, ctx.auth.user, run.summary, repo), (way) => html`<div class="small" id="run-way">${blockedWay(way)}</div>`)}
202205 ${when(
203206 carried.length > 0,
204207 () =>
test/ask-admin.test.ts added +304
@@ -0,0 +1,304 @@
1 /**
2 * A refusal leads somewhere (`docs/features/blocked-by.md`): for the reader
3 * who can change what stands in the way, the link lands on the exact control;
4 * for the one who cannot, the one action asks whoever can, and they see it
5 * with that same link. Walked as a guest, a member, a repository's admin, a
6 * forge admin and the owner of a forge another one hosts, over the page, the
7 * API and MCP.
8 */
9 import { afterAll, beforeAll, expect, test } from "bun:test";
10 import { unlinkSync, writeFileSync } from "node:fs";
11 import { join } from "node:path";
12 import {
13 askAdmin,
14 asksToAnswer,
15 } from "../src/actions/ask_admin.ts";
16 import { gateBlocked, ASK_PATH } from "../src/actions/ask_host.ts";
17 import {
18 ASK_ADMIN_PATH,
19 noKeyBlocked,
20 wantDef,
21 wayIn,
22 wayTo, WANTS, type Want } from "../src/actions/blocked_words.ts";
23 import { NO_ACCOUNT_SAID, NO_KEY_SAID } from "../src/crew/forge_budget.ts";
24 import { blockedFields, blockedText } from "../src/kernel/blocked.ts";
25 import { setAccountGrant } from "../src/actions/model_grant.ts";
26 import { quietLogs } from "./helpers/globals.ts";
27 import { get, hasAnchor, seedWorld, type World } from "./support/deadends.ts";
28
29 quietLogs();
30
31 const WANT_LIST = Object.keys(WANTS) as Want[];
32
33 let world: World;
34 beforeAll(async () => {
35 world = await seedWorld(1);
36 });
37 afterAll(() => world.close());
38
39 const who = (name: "admin" | "member" | "newcomer" | "agent") =>
40 world.viewers[name].user!;
41
42 /** A subject each want can be asked with on the seeded forge. */
43 const subjectFor = (kind: "none" | "account" | "repo"): string =>
44 kind === "none" ? "" : kind === "account" ? "bob" : "bob/notes 10.0.0.5:5432";
45
46 test("for a reader who can change it, every control is a page they can open that holds the field the link names", async () => {
47 const missing: string[] = [];
48 for (const want of WANT_LIST) {
49 // The crew's own limits bind, and are drawn, only on a forge another one hosts: walked below,
50 // as its owner.
51 if (want === "crew_limit") continue;
52 const def = wantDef(want);
53 const subject = subjectFor(def.subject);
54 // The one who answers: a forge admin for the forge's, the repository's own admin for a
55 // repository's.
56 const reader = def.audience === "forge" ? "admin" : "member";
57 const way = wayTo(world.app, who(reader), want, "Something stands in the way.", subject);
58 expect(way.readerCan).toBe(true);
59 expect(way.ask).toBeUndefined();
60 const [path = "", anchor = ""] = way.link!.href.split("#");
61 const page = await get(world, world.viewers[reader], path);
62 if (page.status !== 200) missing.push(`${want}: ${path} answers ${page.status} to the ${reader}`);
63 else if (!hasAnchor(page.body, anchor)) missing.push(`${want}: ${path} holds no #${anchor}`);
64 }
65 expect(missing).toEqual([]);
66 });
67
68 test("a reader who cannot is given the ask, never a link to a page that refuses them, and never a key name in the sentence", () => {
69 for (const want of WANT_LIST) {
70 const def = wantDef(want);
71 const way = wayTo(
72 world.app,
73 who("newcomer"),
74 want,
75 "Something stands in the way.",
76 subjectFor(def.subject),
77 );
78 expect(way.readerCan).toBe(false);
79 expect(way.link).toBeUndefined();
80 expect(way.ask).toMatchObject({ method: "POST", path: ASK_ADMIN_PATH });
81 expect(blockedFields(way)["ask"]).toMatchObject({
82 method: "POST",
83 path: ASK_ADMIN_PATH,
84 body: { want },
85 });
86 expect(blockedFields(way)["fix"]).toBeUndefined();
87 // The internal name rides in `setting`, for an agent or a log; the words a person reads do
88 // not say it.
89 for (const words of [
90 way.says,
91 way.who ?? "",
92 way.ask!.label,
93 def.asks(subjectFor(def.subject)),
94 ])
95 expect(words).not.toContain("_");
96 }
97 // Nobody signed in: who can is said, and nothing is offered, since there is nobody to ask as.
98 const anon = noKeyBlocked(world.app, undefined);
99 expect(anon.ask).toBeUndefined();
100 expect(blockedText(anon)).toBe(
101 "This forge has no model key. An admin of this forge can add one.",
102 );
103 });
104
105 test("a member's ask reaches the forge's admins with the link to the control, once, and is done when the thing is there", () => {
106 const { app } = world;
107 const asked = askAdmin(app, who("member"), {
108 want: "model_grant",
109 subject: "bob",
110 });
111 expect(asked.ok).toBe(true);
112 // A repeat is the same ask.
113 expect(
114 askAdmin(app, who("member"), { want: "model_grant", subject: "bob" }).ok,
115 ).toBe(true);
116 const forAdmin = asksToAnswer(app, who("admin"));
117 expect(forAdmin.map((a) => [a.username, a.want, a.subject, a.href])).toEqual([
118 ["bob", "model_grant", "bob", "/settings/accounts/bob#f-grant"],
119 ]);
120 expect(forAdmin[0]!.sentence).toBe("bob asks for a model grant for bob");
121 // Not theirs to answer: another member, a guest and an agent see nothing.
122 for (const other of ["member", "newcomer", "agent"] as const)
123 expect(asksToAnswer(app, who(other))).toEqual([]);
124 // One who can change it is not asked to ask.
125 expect(
126 askAdmin(app, who("admin"), { want: "model_grant", subject: "bob" }),
127 ).toMatchObject({ ok: false, error: "already_can" });
128 // The admin grants it on the control: the ask is finished by itself.
129 expect(setAccountGrant(app, who("admin"), "bob", 5).ok).toBe(true);
130 expect(asksToAnswer(app, who("admin"))).toEqual([]);
131 expect(
132 app.db
133 .query<
134 { state: string },
135 []
136 >("SELECT state FROM admin_ask WHERE want = 'model_grant'")
137 .get()?.state,
138 ).toBe("done");
139 });
140
141 test("an ask about a repository reaches that repository's admins, and only for a repository the asker can see", () => {
142 const { app } = world;
143 expect(
144 askAdmin(app, who("newcomer"), { want: "repo_crew", subject: "bob/notes" })
145 .ok,
146 ).toBe(true);
147 expect(asksToAnswer(app, who("member")).map((a) => a.sentence)).toEqual([
148 "carol asks for a change to the crew of bob/notes",
149 ]);
150 // A private repository the asker cannot read is the same refusal as one that is not there.
151 expect(
152 askAdmin(app, who("newcomer"), {
153 want: "repo_crew",
154 subject: "bob/diary",
155 }),
156 ).toMatchObject({ ok: false, error: "no_subject" });
157 expect(
158 askAdmin(app, who("newcomer"), {
159 want: "repo_crew",
160 subject: "bob/nothing",
161 }),
162 ).toMatchObject({ ok: false, error: "no_subject" });
163 expect(
164 askAdmin(app, who("newcomer"), { want: "anything_else", subject: "" }),
165 ).toMatchObject({ ok: false, error: "unknown_want" });
166 expect(askAdmin(app, undefined, { want: "crew_key" })).toMatchObject({
167 ok: false,
168 error: "unauthorized",
169 });
170 });
171
172 test("the page: a guest presses the button, the admin's home says it with the link, and Not now puts it aside", async () => {
173 const { app } = world;
174 const form = (fields: Record<string, string>) => ({ method: "POST", body: new URLSearchParams(fields), headers: { "content-type": "application/x-www-form-urlencoded" } });
175 const stateOf = () => app.db.query<{ state: string }, []>("SELECT state FROM admin_ask WHERE want = 'crew_key'").get()?.state;
176 // A page that holds the button carries the one form it submits; a page with nothing to ask
177 // carries none.
178 expect((await get(world, world.viewers.newcomer, "/settings")).body.includes("ask-who-can")).toBe(false);
179 const settings = await get(world, world.viewers.newcomer, "/settings/model");
180 expect(settings.body.includes('action="/asks/admin" id="ask-who-can"')).toBe(true);
181 const pressed = await get(world, world.viewers.newcomer, "/asks/admin", form({ ask: "crew_key", back: "/settings" }));
182 expect(pressed.final).toBe("/settings");
183 expect(stateOf()).toBe("asked");
184 const home = await get(world, world.viewers.admin, "/");
185 expect(home.body.includes("carol asks for a model key: the crew cannot start without one")).toBe(true);
186 expect(home.body.includes('href="/settings/crew#crew-key"')).toBe(true);
187 // A member cannot answer what is the admins'.
188 await get(world, world.viewers.member, "/asks/admin/later", form({ username: "carol", want: "crew_key", subject: "", back: "/" }));
189 expect(stateOf()).toBe("asked");
190 await get(world, world.viewers.admin, "/asks/admin/later", form({ username: "carol", want: "crew_key", subject: "", back: "/" }));
191 expect(stateOf()).toBe("later");
192 expect(asksToAnswer(app, who("admin")).filter((a) => a.want === "crew_key")).toEqual([]);
193 // Asked again the same day, it is not raised again.
194 await get(world, world.viewers.newcomer, "/asks/admin", form({ ask: "crew_key", back: "/settings" }));
195 expect(stateOf()).toBe("later");
196 });
197
198 test("the API and MCP: the refusal carries the ask as data, the call it names works, and the asker reads how it stands", async () => {
199 const api = (path: string, init: { method?: string; body?: string } = {}) =>
200 get(world, world.viewers.agent, path, {
201 accept: "application/json",
202 ...init,
203 ...(init.body === undefined
204 ? {}
205 : { headers: { "content-type": "application/json" } }),
206 });
207 const way = wayTo(
208 world.app,
209 who("agent"),
210 "telemetry_grant",
211 "Reading the forge's pipeline takes a grant.",
212 "scout",
213 );
214 const ask = blockedFields(way)["ask"] as {
215 method: string;
216 path: string;
217 body: Record<string, string>;
218 };
219 const made = await api(ask.path, {
220 method: ask.method,
221 body: JSON.stringify(ask.body),
222 });
223 expect(made.status).toBe(201);
224 expect(JSON.parse(made.body)).toMatchObject({
225 want: "telemetry_grant",
226 subject: "scout",
227 by: "scout",
228 state: "asked",
229 });
230 const mine = JSON.parse((await api(ASK_ADMIN_PATH)).body) as {
231 items: { want: string; says: string }[];
232 toAnswer: unknown[];
233 };
234 expect(mine.items.map((i) => i.want)).toEqual(["telemetry_grant"]);
235 expect(mine.items[0]!.says).toContain(
236 "An admin of this forge has not answered yet.",
237 );
238 expect(mine.toAnswer).toEqual([]);
239 const bad = await api(ASK_ADMIN_PATH, {
240 method: "POST",
241 body: JSON.stringify({ want: "children.originEgress" }),
242 });
243 expect(bad.status).toBe(422);
244 expect(JSON.parse(bad.body)).toMatchObject({ error: "unknown_want" });
245 });
246
247 test("a stored sentence says who can to anyone, and gives each reader their own way through", () => {
248 const { app } = world;
249 // As the runner stores it, read by anyone in a comment or a log: no path, no key name, and who
250 // can.
251 expect(NO_KEY_SAID).toBe(
252 "This forge has no model key. An admin of this forge can add one.",
253 );
254 expect(NO_ACCOUNT_SAID).toBe(
255 "This repository has no model account. An admin of this forge can grant one.",
256 );
257 const repo = { ownerName: "bob" };
258 const forAdmin = wayIn(app, who("admin"), NO_ACCOUNT_SAID, repo)!;
259 expect(forAdmin.says).toBe("This repository has no model account.");
260 expect(forAdmin.link).toEqual({
261 href: "/settings/accounts/bob#f-grant",
262 label: "Give bob a model grant",
263 });
264 const forMember = wayIn(app, who("member"), NO_ACCOUNT_SAID, repo)!;
265 expect(forMember.ask?.body).toEqual({ want: "model_grant", subject: "bob" });
266 // A park written before this change is still read.
267 const old = wayIn(
268 app,
269 who("admin"),
270 "This forge has no model key: add yours at /settings/crew",
271 )!;
272 expect(old.says).toBe("This forge has no model key.");
273 expect(old.link?.href).toBe("/settings/crew#crew-key");
274 expect(
275 wayIn(
276 app,
277 who("admin"),
278 "This forge's per day limit ($5.00) stopped the run. An admin of this forge can raise it.",
279 )?.link?.href,
280 ).toBe("/settings/crew#budgets");
281 expect(wayIn(app, who("admin"), "opened pull #4")).toBeUndefined();
282 });
283
284 test("the owner of a hosted forge: what their own forge holds is a link that lands, what the host holds is the ask to the host", async () => {
285 // On their own forge they are its admin: the key is theirs to add, and the crew's limits are
286 // theirs to raise.
287 expect(noKeyBlocked(world.app, who("admin")).link?.href).toBe("/settings/crew#crew-key");
288 const own = join(world.dir, "parent.json");
289 writeFileSync(own, "{}");
290 try {
291 const way = wayIn(world.app, who("admin"), "This forge's per day limit ($5.00) stopped the run. An admin of this forge can raise it.")!;
292 const [path = "", anchor = ""] = way.link!.href.split("#");
293 const page = await get(world, world.viewers.admin, path);
294 expect(page.status).toBe(200);
295 expect(hasAnchor(page.body, anchor)).toBe(true);
296 } finally {
297 unlinkSync(own);
298 }
299 // The host's list is not theirs: the one action asks the host, by the same value.
300 const gate = gateBlocked("git.example.com", "forge.example.com");
301 expect(gate.readerCan).toBe(false);
302 expect(gate.ask).toMatchObject({ method: "POST", path: ASK_PATH, body: { host: "git.example.com" }, label: "Ask the host to allow git.example.com" });
303 expect(gate.says).not.toContain("originEgress");
304 });
test/crew-nocredential.test.ts +1 −1
@@ -53,7 +53,7 @@ describe("the crew, with a stand-in Claude Code: no credential reaches the repos
5353 (r) => r.issueId === issue.value.id,
5454 );
5555 const said =
56 "This repository has no model account: ask an admin to grant one";
56 "This repository has no model account. An admin of this forge can grant one.";
5757 expect(run.state).toBe("failed");
5858 expect(run.summary).toContain(said);
5959 expect(readRunLog(standIn.dataDir, run.id).lines.join("\n")).toContain(
test/crew-own-forge.test.ts +5 −1
@@ -4,6 +4,7 @@
44 * picks the issue back up once; the host is never asked for model access.
55 */
66
7 import { wayIn } from "../src/actions/blocked_words.ts";
78 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
89 import { existsSync, rmSync, writeFileSync } from "node:fs";
910 import { join } from "node:path";
@@ -104,7 +105,10 @@ describe("a forge of its own: its key, its limits, and the work picked back up",
104105 const stopped = await agentRunSettled(app, repo, (r) => r.issueId === issue.value.id, 60_000);
105106 expect(stopped.state).toBe("failed");
106107 expect(stopped.summary).toContain("per run limit ($0.10)");
107 expect(stopped.summary).toContain("/settings/crew#budgets");
108 // Stored for any reader: who can, in words. The run's page links an admin to the field
109 // (`wayIn`).
110 expect(stopped.summary).toContain("An admin of this forge can raise it.");
111 expect(wayIn(app, undefined, stopped.summary)?.setting).toBe("crew_limit");
108112 expect(existsSync(standIn.argsFile)).toBe(false);
109113 for (let i = 0; i < 100 && parkedCount(app.db, repo, issue.value.id) === 0; i++) await Bun.sleep(100);
110114
test/deadends.test.ts +2 −4
@@ -26,10 +26,8 @@
2626 * child, private and archived repositories, runs, pulls, apps with and
2727 * without a crew; a new finding is shrunk to the smallest forge that shows it.
2828 *
29 * Sentences that send a reader to an admin's page (the reader may not be an
30 * admin; each wants a link or a named admin, a product decision):
31 * `crew/forge_budget.ts:80`, `crew/runner.ts:284`, `core/capacity.ts:439`,
32 * `packs/up.ts:67`, `flow/alarm_release_quiet.ts:30`.
29 * A sentence that tells its reader to ask someone, or that someone else must
30 * act, is held by `test/refusals-lead-somewhere.test.ts`, which every pull runs.
3331 */
3432 import { beforeAll, expect, test } from "bun:test";
3533 import { quietLogs } from "./helpers/globals.ts";
test/egress-grants.test.ts +2 −2
@@ -92,12 +92,12 @@ describe("the proxy's verdict", () => {
9292 test("declared but not granted is refused, saying what to do", async () => {
9393 const v = await decide(policy(["100.89.95.68:8101"]), "100.89.95.68", 8101);
9494 expect(v.ok).toBe(false);
95 if (!v.ok) expect(v.why).toContain("add it to forge.json egress and ask a site admin to grant it");
95 if (!v.ok) expect(v.why).toContain("add it to forge.json egress. An admin of this forge can grant it on the app's settings.");
9696 });
9797 test("granted but not declared is refused", async () => {
9898 const v = await decide(policy([], ["100.89.95.68:8101"]), "100.89.95.68", 8101);
9999 expect(v.ok).toBe(false);
100 if (!v.ok) expect(v.why).toContain("ask a site admin to grant it");
100 if (!v.ok) expect(v.why).toContain("An admin of this forge can grant it on the app's settings.");
101101 });
102102 test("a grant on :8101 does not open :22, nor another address", async () => {
103103 const p = policy(["100.89.95.68:8101", "100.89.95.68:22"], ["100.89.95.68:8101"]);
test/first-ask-new-app.test.ts +2 −2
@@ -140,10 +140,10 @@ test("with the credit spent an app's page says a key is needed, with the link fo
140140 keepFunding(dir, { token: funding.token, capUsd: 2, spentUsd: 2 });
141141 try {
142142 expect(String(crewKeyCard(cardCtx(true), true))).toContain("needs a model key");
143 expect(String(crewKeyCard(cardCtx(true), true))).toContain("/feed#crew-key-note");
143 expect(String(crewKeyCard(cardCtx(true), true))).toContain('href="/settings/crew#crew-key"');
144144 const person = String(crewKeyCard(cardCtx(false), true));
145145 expect(person).toContain("needs a model key");
146 expect(person).not.toContain("/feed#crew-key-note");
146 expect(person).not.toContain('href="/settings/crew#crew-key"');
147147 } finally {
148148 keepFunding(dir, funding);
149149 }
test/land-as-is.test.ts +3 −1
@@ -228,7 +228,9 @@ describe("land it as it is", () => {
228228 const pull = await pullWith("ok", bob.value, made.value);
229229 const page = await fetch(`${base}/bob/bobs/pulls/${pull.number}`, { headers: { cookie: `${bobCookie}; forge_mode=studio` } }).then((r) => r.text());
230230 expect(page).toContain(LAND_AS_IS);
231 expect(page).toContain("Only this forge's admin can add a key.");
231 expect(page).toContain("An admin of this forge can add one.");
232 // And the one button that asks them (`web/blocked.ts`).
233 expect(page).toContain('value="crew_key"');
232234 expect(page).not.toContain('href="/settings/subscriptions"');
233235 // Signed out, nothing is offered.
234236 expect(landable(app, undefined, made.value)).toEqual([]);
test/mcp-flow-why.test.ts +1 −1
@@ -125,7 +125,7 @@ describe("MCP flow with a subject", () => {
125125
126126 test("with no arguments it is the pipeline, for an admin only", async () => {
127127 expect((await call(ownerTok, {})).value.stages).toBeDefined();
128 expect((await call(readerTok, {})).error).toContain("only an admin");
128 expect((await call(readerTok, {})).error).toContain("An admin of this forge");
129129 });
130130
131131 test("a repository with no builder says so", async () => {
test/model-grant-pages.test.ts +3 −1
@@ -61,7 +61,9 @@ describe("a model grant, from the account's page and the API", () => {
6161 test("a new account's page says its budget is zero in one line", async () => {
6262 const bob = await signIn("bob");
6363 const html = await (await fetch(`${servers.url}/settings/model`, { headers: { cookie: bob } })).text();
64 expect(html).toContain("Model budget: $0. Add your own subscription, or ask an admin for a grant.");
64 expect(html).toContain("Model budget: $0. Add your own subscription, or a grant from an admin pays for it.");
65 // With the one button that asks for the grant.
66 expect(html).toContain('value="model_grant bob"');
6567 });
6668
6769 test("an admin sets the grant from the account's page; the page shows it; a person cannot", async () => {
test/model-grant.test.ts +1 −1
@@ -249,7 +249,7 @@ describe("model budget: zero, an own subscription, a capped grant", () => {
249249 const refused = await runOn(founder, repo);
250250 expect(refused.state).toBe("failed");
251251 expect(refused.summary).toBe(
252 "the account `plainorg` has no model grant; an admin can grant one at /settings/accounts/plainorg",
252 "The account `plainorg` has no model grant. An admin of this forge can grant one.",
253253 );
254254
255255 // The admin grants the org explicitly: its runs use the forge's account, up to the grant.
test/model-page-shape.test.ts +1 −1
@@ -51,7 +51,7 @@ test("a new account sees a heading, one sentence and the token form, no card", a
5151 const body = await get(await signIn("bob"));
5252 expect(body).toMatch(heading);
5353 noCard(body);
54 expect(body).toContain("Model budget: $0. Add your own subscription, or ask an admin for a grant.");
54 expect(body).toContain("Model budget: $0. Add your own subscription, or a grant from an admin pays for it.");
5555 expect(body).not.toContain('class="row');
5656 expect(body).toContain('name="token"');
5757 });
test/outsiders-member.test.ts +1 −1
@@ -249,7 +249,7 @@ describe("the member actor and the forge's own model credential", () => {
249249 expect(assignIssue(app, alice, repo, issue.value, bot).ok).toBe(true);
250250 const run = await agentRunSettled(app, repo, (r) => r.issueId === issue.value.id);
251251 expect(run.state).toBe("failed");
252 expect(run.summary).toContain("This repository has no model account: ask an admin to grant one");
252 expect(run.summary).toContain("This repository has no model account. An admin of this forge can grant one.");
253253 expect(existsSync(standIn.argsFile)).toBe(false);
254254 expect(getUsage(app.db, run.id)?.costUsd ?? 0).toBe(0);
255255 expect(run.costUsd).toBe(0);
test/refusals-lead-somewhere.test.ts added +75
@@ -0,0 +1,75 @@
1 /**
2 * A sentence that tells its reader to ask someone, or that someone else must
3 * act, carries its way through (`docs/features/blocked-by.md`): the link to
4 * the exact control for a reader who can change it, the one action that asks
5 * whoever can for one who cannot. This reads every such sentence in `src/`
6 * (`refusals`, `test/support/deadends-words.ts`) and fails on a new one that
7 * is not built by the helper. The few that end where they are, are listed
8 * with why.
9 *
10 * It reads the whole tree, so any pull can break it and none "touches" it:
11 * it is one of the rule tests every fast tier runs (`src/checks/tiers.ts`).
12 * The crawl of a running forge is `test/deadends.test.ts`.
13 *
14 * @tree-scan: reads every file under src/ through test/support/deadends-words.ts.
15 */
16 import { expect, test } from "bun:test";
17 import { refusals } from "./support/deadends-words.ts";
18
19 /**
20 * It says who may do the thing and nothing else: "Only a forge admin sets a
21 * budget." The reader tried an act that is another role's, on a door (the
22 * terminal, a tool, a direct call) that could not hide it; there is no
23 * setting whose change would let them, and the page never offers them the
24 * control (the offered-action walk above). Where there is something to ask
25 * for, the sentence is built by the helper instead and offers the ask.
26 */
27 const ROLE_STATEMENT = /\bonly (?:a|an) (?:site |forge )?(?:admin|person who is an admin)\b/i;
28
29 /**
30 * Sentences that end where they are, each with why. Keyed by file and the sentence's first words,
31 * so a moved line stays listed and a reworded one is looked at again.
32 */
33 const TERMINAL: Readonly<Record<string, string>> = {
34 "src/core/capacity.ts\tenforce refuses a host an app or check did not": "The help beside the control itself, on a page only an admin opens.",
35 "src/core/capacity.ts\t${EGRESS_ENV}=${asked.slice(0, 32)} is ignored": "A boot log line for the operator who set that variable; it names the variable because they typed it.",
36 "src/web/pages/origin-reach.ts\tAsk the host again to allow ${a.host}": "The label of the ask itself, on the button the helper draws.",
37 "src/web/pages/passkeys.ts\tThis link has been used or has expired.": "The reader is signed out and locked out: the link came from an admin outside the forge, and there is no account to ask as.",
38 "src/actions/account_access.ts\tThat link has been used or has expired.": "The same link, for the API and the terminal: no account to ask as.",
39 "src/http/mcp/tools/profile.ts\t`{ displayName?, email?, commitEmail? }`: your own": "A tool's description of what its scope is, not a refusal.",
40 "src/http/api.ts\tthe origin refused: this connection cannot write": "The owner is of a repository on another host; the way through it names is the reader's own (connect again with a token that can write).",
41 "src/http/respond.ts\tUse a token or account with the scope or role": "The hint on every 403, which does not know what was refused; a refusal with something to ask for carries `ask` itself.",
42 "src/http/respond.ts\tYour token's scope or your role on this resource": "The same hint, by code.",
43 "src/actions/migrate.ts\tThat address is inside the network, not a public": "It gives the reader's own way through in the same sentence: connect the host as an origin.",
44 "src/actions/contribute_token.ts\tthis repository does not take outside contributions": "A door its owner chose to keep shut, said as a fact to a stranger with no account here.",
45 "src/actions/spawn.ts\t${name} is already claimed; ask its owner to": "The owner is of another forge (the hosted one), which this forge cannot ask on anyone's behalf.",
46 };
47
48 /**
49 * Real dead ends not fixed yet, each with what it waits on. A line is removed the day it is
50 * fixed.
51 */
52 const WAITING: Readonly<Record<string, string>> = {
53 "src/tui/screens/blocked.ts\tprivate: a site admin allows it": "The terminal has no key for the ask yet; the page's row offers it.",
54 "src/web/pages/iterations.ts\tNot saved: this repository's notes lost a note.": "No control restores a lost note, so there is nothing to link and nothing an ask could point its answerer at; it names a ref.",
55 "src/crew/grant.ts\tthis run asked for ${name}; the forge's owner": "A run's log line; the grant is on the app's settings, which has no anchor on a name yet.",
56 "src/spawn/credit.ts\t${name}'s ${usdWords(capUsd)} from its parent is spent": "The host takes an ask to reach a name and nothing else: an ask for more lent credit needs the host's side.",
57 };
58
59 test("a sentence that sends its reader to someone else goes through the helper, or ends there for a reason", () => {
60 const keyOf = (r: { file: string; text: string }): string | undefined =>
61 [...Object.keys(TERMINAL), ...Object.keys(WAITING)].find((k) => {
62 const [file = "", lead = ""] = k.split("\t");
63 return r.file === file && r.text.replace(/^<[^>]+>\s*/, "").startsWith(lead);
64 });
65 const found = refusals().filter((r) => !r.through);
66 const fresh = found.filter((r) => !ROLE_STATEMENT.test(r.text) && keyOf(r) === undefined);
67 // A new one: build it with `wayTo` or `storedText` (`src/actions/blocked_words.ts`), so it
68 // links the control or offers the ask.
69 expect(fresh.map((r) => `${r.at}: ${r.text.slice(0, 100)}`)).toEqual([]);
70 // And a listed one that is gone is taken off the list.
71 const used = new Set(found.map(keyOf));
72 expect([...Object.keys(TERMINAL), ...Object.keys(WAITING)].filter((k) => !used.has(k))).toEqual([]);
73 // No sentence a person reads names the host's internal key.
74 expect(refusals().filter((r) => /children\.originEgress|cells\.egress/.test(r.text) && !r.file.endsWith("core/capacity.ts")).map((r) => r.at)).toEqual([]);
75 });
test/retry-after.test.ts +1 −1
@@ -30,7 +30,7 @@ const PERF_LINE = `src/http/server.ts: ${readFileSync("src/http/server.ts", "utf
3030
3131 /** Sites that are not a response of their own, each with why it is safe. `file: trimmed line`. */
3232 const EXEMPT: Record<string, string> = {
33 "src/http/api/user.ts: return json({ ...said, ...blockedFields(noMailBlocked(ctx.auth.user)) }, 503, Object.fromEntries(refused.headers));":
33 "src/http/api/user.ts: return json({ ...said, ...blockedFields(noMailBlocked(ctx.app, ctx.auth.user!)) }, 503, Object.fromEntries(refused.headers));":
3434 "the headers are tryAgain's own, spread from refused.headers",
3535 [PERF_LINE]: "a comparison, not a response",
3636 "src/http/respond.ts: if (status === 429 || status === 503) {": "json()'s floor itself",
test/studio-shipping.test.ts +3 −3
@@ -1048,7 +1048,7 @@ describe("the studio's crew panel on a forge with no agents yet", () => {
10481048 ).text();
10491049 expect(settings).toContain("No agents exist on this forge yet.");
10501050 expect(settings).not.toContain("Add an agent below");
1051 expect(settings).toContain('href="/settings/crew"');
1051 expect(settings).toContain('href="/settings/crew#crew-new"');
10521052
10531053 const doorResponse = await get("/settings/crew", ownerCookie);
10541054 expect(doorResponse.status).toBe(200);
@@ -1064,7 +1064,7 @@ describe("the studio's crew panel on a forge with no agents yet", () => {
10641064 expect(settings).toContain(
10651065 "No agents exist on this forge yet. An admin of this forge can add one.",
10661066 );
1067 expect(settings).not.toContain('href="/settings/crew"');
1067 expect(settings).not.toContain('href="/settings/crew#crew-new"');
10681068
10691069 const refused = await get("/settings/crew", teamAdminCookie);
10701070 expect(refused.status).toBe(403);
@@ -1078,7 +1078,7 @@ describe("the studio's crew panel on a forge with no agents yet", () => {
10781078 const settings = await (
10791079 await get("/alice/pad/settings", ownerCookie)
10801080 ).text();
1081 expect(settings).toContain('href="/settings/crew"');
1081 expect(settings).toContain('href="/settings/crew#crew-new"');
10821082
10831083 const door = await get("/settings/crew", ownerCookie);
10841084 expect(door.status).toBe(200);
test/support/deadends-words.ts +41
@@ -147,3 +147,44 @@ export function tabulate(rows: readonly Instruction[]): string {
147147 )
148148 .join("\n");
149149 }
150
151 /**
152 * A sentence that tells its reader to ask someone, or that someone else must
153 * act: "ask an admin", "an admin can raise it", "only a site admin grants
154 * it", "contact the host". Each is a dead end unless it carries its way
155 * through, so each is built by the one helper (`src/kernel/blocked.ts`,
156 * `src/actions/blocked_words.ts`): `through` is whether the line is.
157 */
158 export interface Refusal {
159 readonly file: string;
160 readonly at: string;
161 readonly text: string;
162 readonly through: boolean;
163 }
164
165 const ASKS =
166 /an admin (?:can|must|may|has to|needs to|sets|grants|adds)\b|ask (?:an|your|the|its|a site|a forge|this forge's) ?(?:site |forge )?(?:admin|owner|host)\b|only a (?:site|forge) admin\b|only an admin\b|a site admin (?:can|must|grants|allows)\b|contact (?:the|your|an) (?:host|admin|owner)\b|the (?:forge's |site |parent's |host's )?admin (?:can|must|has)\b|(?:admin|owner|host) (?:has not|hasn't|must|needs to)\b/i;
167 /** A line that builds its sentence with the helper. */
168 const HELPER = /\b(?:storedText|storedSaid|wayTo|blockedBy)\(/;
169 /** The helper's own files: the words every such sentence is made of. */
170 const HELPER_FILES = new Set(["src/kernel/blocked.ts", "src/actions/blocked_words.ts", "src/actions/ask_admin.ts", "src/actions/ask_host.ts"]);
171
172 /** Every such sentence in `src/`, with whether it goes through the helper. */
173 export function refusals(): Refusal[] {
174 const out: Refusal[] = [];
175 for (const file of walk(join(ROOT, "src"))) {
176 const rel = relative(ROOT, file);
177 if (/contract\/openapi\/|migrations\/|\.test\./.test(rel) || HELPER_FILES.has(rel)) continue;
178 const lines = readFileSync(file, "utf8").split("\n");
179 lines.forEach((line, i) => {
180 if (/^\s*(?:\/\/|\*|\/\*)/.test(line) || !ASKS.test(line)) return;
181 // A multi-line call: the helper's name is on the line that opens it.
182 const through = HELPER.test(line) || HELPER.test(lines[i - 1] ?? "") || HELPER.test(lines[i - 2] ?? "");
183 for (const text of literals(line)) if (ASKS.test(text)) out.push({ file: rel, at: `${rel}:${i + 1}`, text: text.replace(/\s+/g, " ").trim(), through });
184 // Markup between tags is words too: a template's own text, outside any quoted segment.
185 if (literals(line).every((t) => !ASKS.test(t)) && />[^<>]*$|^[^<>]*</.test(line) && ASKS.test(line.replace(/\$\{[^}]*\}/g, "")))
186 out.push({ file: rel, at: `${rel}:${i + 1}`, text: line.replace(/\s+/g, " ").trim(), through });
187 });
188 }
189 return out;
190 }
test/web-apps.test.ts +7 −5
@@ -187,11 +187,13 @@ describe("apps, runs and the crew on the web", () => {
187187 // No agents yet: no select, and the admin is told where to make one.
188188 expect(html).not.toContain('name="agent"');
189189 expect(html).toContain("No agents on this forge yet");
190 expect(html).toContain('href="/settings/crew"');
191 // A non-admin is told an admin can, not handed a link that 404s.
192 expect(await bodyOf(bob, "/apps/new")).not.toContain(
193 'href="/settings/crew"',
194 );
190 expect(html).toContain('href="/settings/crew#crew-new"');
191 // A non-admin is told an admin can and given the button that asks one, not handed a link that
192 // 404s.
193 const asBob = await bodyOf(bob, "/apps/new");
194 expect(asBob).not.toContain('href="/settings/crew');
195 expect(asBob).toContain('value="agents"');
196 expect(asBob).toContain('action="/asks/admin" id="ask-who-can"');
195197 });
196198
197199 test("New app: starters are plain links that prefill the box; a hostile description is escaped or ignored", async () => {

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs