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

The docs and the spawn tool's own words stop saying a forge's size "limits nothing": they say what the cell is given #15306

Merged opened this

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

Merged

torque/forge:torque/15304-the-docs-and-the-spawn-tool-s-own-words → main 3 commits fork

  • Merged. torque/15304-the-docs-and-the-spawn-tool-s-own-words was merged into main as b6f66aa.

Review

Sign in to review this change.
5 files changed +34 −5
docs/MCP.md +1 −1
@@ -229,7 +229,7 @@ longer sentences:
229229 - `dryRun`: plans unless it is `false`; anything else changes nothing. `limb` applying takes an admin token.
230230 - `signup`: the terminal's Invite links screen does the same: `s` picks a mode, shows the plan (from → to) and changes it after a confirm, for a forge admin who is a person.
231231 - `tell.from`: a path on this forge the issue links to, like `/alice/notes/pulls/3`. `tell.context`: where this was told from, for the builder.
232 - `spawn.reveal`, `claim_link.reveal`: put the live claim link in the answer (default false); it is a secret, only when its person reads it. `spawn.fresh`: a fresh app beside the copied ones. `spawn.followMode`: `tell-me` (default) tells the owner in their inbox when this forge's code moves; `take-updates` opens a pull with the new code, and a person merges it. `spawn.size`: recorded only, not enforced. `spawn.keepAccess`: stay an owner once claimed. `spawn.config` `{apps:[{repo, mode: fork|autonomous|migration}], budgetUsd?, admin?, domain?}` or `spawn.recipe` (a name saved on the New forge page or `PUT /api/v1/forges/recipes/<name>`) in place of `apps`; a budget applies only beside a model key, which never travels through an agent.
232 - `spawn.reveal`, `claim_link.reveal`: put the live claim link in the answer (default false); it is a secret, only when its person reads it. `spawn.fresh`: a fresh app beside the copied ones. `spawn.followMode`: `tell-me` (default) tells the owner in their inbox when this forge's code moves; `take-updates` opens a pull with the new code, and a person merges it. `spawn.size`: small, medium, large or xlarge; the child's cell is given that CPU, memory and disk (`sizes` lists them), and a spawn over the host's child quota is refused; a hosted child has no cell to hold it. `spawn.keepAccess`: stay an owner once claimed. `spawn.config` `{apps:[{repo, mode: fork|autonomous|migration}], budgetUsd?, admin?, domain?}` or `spawn.recipe` (a name saved on the New forge page or `PUT /api/v1/forges/recipes/<name>`) in place of `apps`; a budget applies only beside a model key, which never travels through an agent.
233233 - `commits.ref`: branch, tag or commit; the default branch when absent. `report.page`: the http(s) address where the problem was seen. `plan.issues.pillar`: the pillar served, as `"P0"` or `"P0 Trust"`; `later: true` means no pillar and needs `why`.
234234 - `here.url`: none means the forge's own page. On `/` or `/settings` this forge's admin also gets `plan: { text, manage? }`, the Plan row's words and its manage-billing address; no plan notice or not an admin, no `plan` key.
235235 - `explore.q`: words, plus `kind:app|person|forge` and `sort:score|forks|ships|likes|use|fresh|name`, `updated:1d|7d|30d` (only what moved in that window), `owner:name` and `archived:yes`. `since` is another name for `updated`. `query` is the same argument; `q` wins when both are given. Each of `kind`, `sort`, `updated`, `owner`, `archived` is also its own argument (and a query parameter on `/explore` and `/api/v1/explore`); it wins over the same key in `q`.
docs/SPAWN.md +2 −2
@@ -74,9 +74,9 @@ A hosted forge gets the same one-click connect for origins its parent holds an O
7474
7575 ## Callers
7676
77 `POST /api/v1/forges {name, apps[], crew[], direction?, keepAccess?, modelKey?, budgetUsd?, size?, template?, dryRun}` (rw token; a person who is signed in, and a paid plan only from an admin, a gift code, or a paid order below) and the MCP `spawn` tool share `src/spawn/door.ts`. `size` is `small` (default), `medium` or `large`; anything else is a 422 on `size`. It is recorded in the plan, the ledger, `parent.json` and `GET /api/v1/forges`, but not enforced yet: it limits nothing. `dryRun` is true unless it is `false`: the answer is the plan, what is left behind, and `firstAdmin` (the caller's username, or `null` for an anonymous plan, where whoever claims the child becomes its admin), and nothing is made. `GET /api/v1/forges` lists the ledger's children. The child's org is its name; `crew` names the agents whose briefs travel. Errors: 401 unauthorized, 403 forbidden / cross_origin, 422 invalid, 409 refused / exists, 500 failed — each with one sentence. The MCP lets an `ro` token plan, never make.
77 `POST /api/v1/forges {name, apps[], crew[], direction?, keepAccess?, modelKey?, budgetUsd?, size?, template?, dryRun}` (rw token; a person who is signed in, and a paid plan only from an admin, a gift code, or a paid order below) and the MCP `spawn` tool share `src/spawn/door.ts`. `size` is `small` (default), `medium`, `large` or `xlarge`; anything else is a 422 on `size`. It is recorded in the plan, the ledger, `parent.json` and `GET /api/v1/forges`, and it is what the child's cell is given: its CPU, memory and disk from `spawn/sizes.ts` (`spawn/cell.ts`), plus a disk bandwidth. A spawn is refused (409 `refused`, reason `quota`) when the size would pass a host child quota the operator declared (`quotaRefusal`). Where the host cannot hold a cell the child is hosted and the cell's limits do not apply (the ledger says which `placement`). `dryRun` is true unless it is `false`: the answer is the plan, what is left behind, and `firstAdmin` (the caller's username, or `null` for an anonymous plan, where whoever claims the child becomes its admin), and nothing is made. `GET /api/v1/forges` lists the ledger's children. The child's org is its name; `crew` names the agents whose briefs travel. Errors: 401 unauthorized, 403 forbidden / cross_origin, 422 invalid, 409 refused / exists, 500 failed — each with one sentence. The MCP lets an `ro` token plan, never make.
7878
79 A spawn may also name a `size`: `small`, `medium` or `large` (`src/spawn/sizes.ts` maps each to CPU, memory and disk). It is recorded in the plan only when given, so a plan without one hashes as it always did, and an unknown size is a 422 on `size`. The New forge page and the terminal form both offer it, small preselected and not sent; the page shows a refusal beside the select, linked with `aria-describedby`. Nothing enforces the limits yet, and the table's numbers are provisional. `GET /api/v1/forges/sizes` (no sign-in, ETag, cached for 5 minutes) and the MCP tool `sizes` give the same answer — each size's CPU, memory and disk, read from that table, and one sentence on what it is for — so a page or an agent offering a size reads it there.
79 A spawn may also name a `size`: `small`, `medium`, `large` or `xlarge` (`src/spawn/sizes.ts` maps each to CPU, memory and disk). It is recorded in the plan only when given, so a plan without one hashes as it always did, and an unknown size is a 422 on `size`. The New forge page and the terminal form both offer it, small preselected and not sent; the page shows a refusal beside the select, linked with `aria-describedby`. The cell enforces them (`apps/contain.ts`): memory is a cap the kernel holds (the child is killed at it), CPU is a quota on its cores (a pause-and-resume duty where the kernel cannot hold one), and disk is a file-size limit plus a watch that stops a child whose data passes its size; disk reads and writes per second are held by size too (`SIZE_IO`). Still only recorded: the table's numbers are provisional, and a hosted child (no cell) is not held to them. `GET /api/v1/forges/sizes` (no sign-in, ETag, cached for 5 minutes) and the MCP tool `sizes` give the same answer — each size's CPU, memory and disk, read from that table, and one sentence on what it is for — so a page or an agent offering a size reads it there.
8080
8181 ## Choosing a template (#7533)
8282
src/http/mcp/tools/spawn.ts +1 −1
@@ -37,7 +37,7 @@ export const tool: Tool = {
3737 size: {
3838 type: "string",
3939 enum: ["small", "medium", "large", "xlarge"],
40 description: "Recorded only.",
40 description: "The cell's CPU, memory, disk; see sizes.",
4141 },
4242 plan: {
4343 type: "string",
src/tui/screens/newforge.ts +1 −1
@@ -49,7 +49,7 @@ const SPECS: readonly Spec[] = [
4949 { key: "modelEndpoint", label: "API base URL", hint: "Omit /v1: https://openrouter.ai/api. Empty = your AI's own service." },
5050 { key: "budgetUsd", label: "Budget in dollars", hint: `${MIN_BUDGET_USD}–${MAX_BUDGET_USD}, for the key's whole life. Needed with a key.` },
5151 { key: "followMode", label: "Follows this forge's code", hint: FOLLOW_LINE },
52 { key: "size", label: "Size", hint: "small (default), medium, large or xlarge: left and right choose, or type it.", choices: SIZE_CHOICES },
52 { key: "size", label: "Size", hint: "small (default), medium, large or xlarge: the cell gets that CPU, memory and disk. Left and right choose.", choices: SIZE_CHOICES },
5353 { key: "template", label: "Template", hint: TEMPLATE_HINT, choices: TEMPLATE_CHOICES },
5454 { key: "migration", label: "Mode of the forked apps", hint: "own (default) or migration: the crew works to run each app natively there with parity to its copy here.", choices: ["own", "migration"] },
5555 { key: "saveAs", label: "Save as recipe", hint: "A name to keep the apps and budget under, saved with the plan. Optional." },
test/size-words.test.ts added +29
@@ -0,0 +1,29 @@
1 import { expect, test } from "bun:test";
2 import { readFileSync } from "node:fs";
3 import { tool as spawn } from "../src/http/mcp/tools/spawn.ts";
4 import { tool as sizes } from "../src/http/mcp/tools/sizes.ts";
5
6 const read = (p: string) => readFileSync(new URL(`../${p}`, import.meta.url), "utf8");
7 // The old claim, in any of its wordings, said of a size.
8 const STALE = /(size[^.\n]{0,160}(not enforced|unenforced|limits nothing|recorded only))|((not enforced|limits nothing|recorded only)[^.\n]{0,40}size)|nothing enforces the limits/i;
9
10 test("while the cell applies a size, no doc or tool says size is unenforced", () => {
11 // The fact the words rest on: the cell is given its size's limits.
12 const cell = read("src/spawn/cell.ts");
13 expect(cell).toContain("limits: cellLimits(input.size)");
14 expect(read("src/actions/spawn.ts")).toContain("quotaRefusal(");
15 const sources: Record<string, string> = {
16 "docs/SPAWN.md": read("docs/SPAWN.md"),
17 "docs/MCP.md": read("docs/MCP.md"),
18 "src/http/api/forges.ts": read("src/http/api/forges.ts"),
19 "src/tui/screens/newforge.ts": read("src/tui/screens/newforge.ts"),
20 "spawn tool": JSON.stringify(spawn),
21 "sizes tool": JSON.stringify(sizes),
22 };
23 for (const [name, text] of Object.entries(sources)) expect(STALE.test(text), `${name} still calls size unenforced`).toBe(false);
24 });
25
26 test("the docs say what the cell is given", () => {
27 expect(read("docs/SPAWN.md")).toContain("what the child's cell is given");
28 expect(read("docs/MCP.md")).toContain("given that CPU, memory and disk");
29 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs