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

A parent funds a child forge's crew: a $ cap per child on the parent's own credential, metered, shown on both forges #10488

Parked opened this in answer to
Closed without merging

mason/forge:mason/10484-a-parent-funds-a-child-forge-s-crew-a-ca → main 4 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
22 files changed +859 −11
docs/features/parent-credit.md added +8
@@ -0,0 +1,8 @@
1 # A parent funds a child's crew (#10484)
2
3 A parent lends a child's crew its own model credential **without the child ever holding it**, up to a dollar cap per child.
4
5 - **Set the cap**: `PUT /api/v1/forges/:name/credit {"usd":200}` (site admin, `rw`), or the "Lend" field on a child's row in `/forges`. `0` withdraws it. `GET` on the same path reads `{ name, capUsd, spentUsd, leftUsd }`.
6 - **How the child reaches it**: the first cap seals a bearer (`fcr.<name>.<secret>`) into the child's own subscription row `from parent`, `api_base` = `<parent>/credit`, granted to its organisation. The parent keeps only the bearer's hash (`<data>/credit/<name>.json`). In a cell, a run is pointed at `FORGE_PARENT_LOCAL` instead (`spawn/credit_reach.ts`), the beat door already relayed in: no host is added to the child's egress, and `children.modelEgress` is untouched.
7 - **The endpoint**: `POST /credit/v1/messages` on the beat door (`spawn/credit_door.ts`). It checks the bearer, refuses past the cap with "NAME's $200 from its parent is spent; the parent's admin can raise it.", forwards on the parent's `ANTHROPIC_API_KEY` (`ANTHROPIC_BASE_URL` if set), and meters by list price (`spawn/list_price.ts`; an unknown model is priced as the dearest). A call that has started may take the spend past the cap; the next is refused.
8 - **Both forges show it**: the parent's `/forges` row and `GET /api/v1/forges` item carry `credit`; the child hears cap and spend on each heartbeat answer and shows "funded by its parent: $X of $200 left" on its crew page and `GET /api/v1/forge/credit`.
scripts/unreached-allow.json −1
@@ -15,7 +15,6 @@
1515 "src/flow/review_rounds.ts",
1616 "src/flow/shared_red.ts",
1717 "src/flow/stale_fold.ts",
18 "src/kernel/why_now.ts",
1918 "src/spawn/pod.ts",
2019 "src/tui/gallery.ts",
2120 "src/tui/ui/qr.ts",
src/contract/openapi/routes/getApiV1ForgeCredit.ts added +3
@@ -0,0 +1,3 @@
1 import type { Route } from "../shared.ts";
2
3 export const route: Route = { method: "get", path: "/api/v1/forge/credit", summary: "What this forge, as a child, last heard of the credit its parent lends its crew (an admin's, ro scope): { capUsd, spentUsd, says }; the parent holds the book and this is a heartbeat old", auth: true, refusals: { not_found: "no parent lends this forge credit", forbidden: "the caller is not an admin" } };
src/contract/openapi/routes/getApiV1ForgesNameCredit.ts added +3
@@ -0,0 +1,3 @@
1 import type { Route } from "../shared.ts";
2
3 export const route: Route = { method: "get", path: "/api/v1/forges/{name}/credit", summary: "What this forge lends a child's crew on its own model credential (a site admin's, ro scope): { name, capUsd, spentUsd, leftUsd }, the spend metered by list price", auth: true, refusals: { not_found: "no credit was set for this forge", forbidden: "the caller is not a site admin" } };
src/contract/openapi/routes/index.ts +3
@@ -83,9 +83,11 @@ export { route as getApiV1FleetOps } from "./getApiV1FleetOps.ts";
8383 export { route as getApiV1FleetOpsId } from "./getApiV1FleetOpsId.ts";
8484 export { route as getApiV1FleetRows } from "./getApiV1FleetRows.ts";
8585 export { route as getApiV1Forge } from "./getApiV1Forge.ts";
86 export { route as getApiV1ForgeCredit } from "./getApiV1ForgeCredit.ts";
8687 export { route as getApiV1ForgeEconomics } from "./getApiV1ForgeEconomics.ts";
8788 export { route as getApiV1ForgeView } from "./getApiV1ForgeView.ts";
8889 export { route as getApiV1Forges } from "./getApiV1Forges.ts";
90 export { route as getApiV1ForgesNameCredit } from "./getApiV1ForgesNameCredit.ts";
8991 export { route as getApiV1ForgesSizes } from "./getApiV1ForgesSizes.ts";
9092 export { route as getApiV1ForgesTemplates } from "./getApiV1ForgesTemplates.ts";
9193 export { route as getApiV1Front } from "./getApiV1Front.ts";
@@ -362,6 +364,7 @@ export { route as putApiV1AdminTeamsSlug } from "./putApiV1AdminTeamsSlug.ts";
362364 export { route as putApiV1BoardsSlug } from "./putApiV1BoardsSlug.ts";
363365 export { route as putApiV1FeaturesSlug } from "./putApiV1FeaturesSlug.ts";
364366 export { route as putApiV1ForgeEconomics } from "./putApiV1ForgeEconomics.ts";
367 export { route as putApiV1ForgesNameCredit } from "./putApiV1ForgesNameCredit.ts";
365368 export { route as putApiV1Front } from "./putApiV1Front.ts";
366369 export { route as putApiV1ReposOwnerNameAppEnvVar } from "./putApiV1ReposOwnerNameAppEnvVar.ts";
367370 export { route as putApiV1ReposOwnerNameAppMembers } from "./putApiV1ReposOwnerNameAppMembers.ts";
src/contract/openapi/routes/putApiV1ForgesNameCredit.ts added +3
@@ -0,0 +1,3 @@
1 import type { Route } from "../shared.ts";
2
3 export const route: Route = { method: "put", path: "/api/v1/forges/{name}/credit", summary: "Set the dollar cap this forge lends a child's crew on its own model credential (a site admin's, rw scope): send { usd } from 0 to 100000, 0 withdraws it. The first cap seals a bearer into the child's own subscription row; the child never holds this forge's credential. Answers { name, capUsd, spentUsd, leftUsd }", auth: true, refusals: { not_found: "no child forge has this name", invalid: "usd is not a number from 0 to 100000", forbidden: "the caller is not a site admin" } };
src/crew/runner.ts +3 −2
@@ -11,6 +11,7 @@
1111 * what the forge has.
1212 */
1313
14 import { reachableBase } from "../spawn/credit_reach.ts";
1415 import { isStrangerPull } from "./stranger.ts";
1516 import { noteMeasure } from "../core/measure.ts";
1617 import { capacityEnv } from "../core/capacity.ts";
@@ -1408,7 +1409,7 @@ async function work(
14081409 FORGE_URL: options.forgeUrl,
14091410 FORGE_TOKEN: token.token,
14101411 ...passportEnv(app.config.dataDir),
1411 ...credentialEnv(picked),
1412 ...credentialEnv(picked.kind === "ready" ? { ...picked, apiBase: reachableBase(picked.apiBase) } : picked),
14121413 ...grant.env,
14131414 ...machineEnv(machine),
14141415 ...(options.configDir === undefined
@@ -1424,7 +1425,7 @@ async function work(
14241425 // since the last one is denied from this one on.
14251426 const hosts = grant.hosts;
14261427 const gatewayHost =
1427 picked.kind === "ready" ? hostOfApiBase(picked.apiBase) : undefined;
1428 picked.kind === "ready" ? hostOfApiBase(reachableBase(picked.apiBase)) : undefined;
14281429 const shellPolicy = () =>
14291430 sandboxPolicy({
14301431 dataDir: app.config.dataDir,
src/http/api.ts +2 −1
@@ -8,6 +8,7 @@
88 * back to continue); errors are `{ error, message }`.
99 */
1010
11 import { creditAnswer } from "../spawn/credit.ts";
1112 import { teamHoldRefusal } from "../core/teams_words.ts";
1213 import { guardedRefusal } from "../crew/stranger.ts";
1314 import { MAX_PASS, passOf } from "../actions/box_pass.ts";
@@ -3515,7 +3516,7 @@ export function apiRoutes(router: Router<Handler>): void {
35153516 if (bytes === "too_large") return apiError("not_found", 404, "no such door");
35163517 const raw = new TextDecoder().decode(bytes);
35173518 const kept = await receiveBeat(ctx.app, raw, ctx.request.headers.get(SIGNATURE_HEADER));
3518 return kept ? json({ ok: true }) : apiError("not_found", 404, "no such door");
3519 return kept ? json({ ok: true, credit: await creditAnswer(ctx.app, raw) }) : apiError("not_found", 404, "no such door");
35193520 });
35203521
35213522 // A mirror's origin saying a pull moved (`origins/hook.ts`). Signed; every
src/http/api/forges.ts +37
@@ -6,6 +6,8 @@
66
77 import { listChildren } from "../../actions/spawn.ts";
88 import { notePhase, takeSessionTime, timePhase, timePhaseAsync } from "../../core/route_timing.ts";
9 import { CREDIT_MAX_USD, creditBody, creditOf, leftWords, setCredit } from "../../spawn/credit.ts";
10 import { creditSeen } from "../../spawn/credit_seen.ts";
911 import { clientRows } from "../../spawn/clients.ts";
1012 import { reissueDoor, spawnDoor } from "../../spawn/door.ts";
1113 import { sizesView } from "../../spawn/sizes.ts";
@@ -71,6 +73,41 @@ export function forgeRoutes(router: Router<Handler>): void {
7173 return json(door.body, door.status);
7274 });
7375
76 // The parent's credit to a child (#10484): the cap and the spend, read and set by an admin.
77 router.add("GET", "/api/v1/forges/:name/credit", async (ctx) => {
78 const denied = requireScope(ctx, "ro");
79 if (denied) return denied;
80 if (!ctx.auth.user?.isAdmin) return forbidden();
81 const c = await creditOf(ctx.app, ctx.params["name"] ?? "");
82 return c === undefined ? apiError("not_found", 404, "this forge has no credit from here") : json(creditBody(ctx.params["name"] ?? "", c));
83 });
84 router.add("PUT", "/api/v1/forges/:name/credit", async (ctx) => {
85 const denied = requireScope(ctx, "rw");
86 if (denied) return denied;
87 if (!ctx.auth.user?.isAdmin) return forbidden();
88 if (crossOrigin(ctx.request, ctx.url, ctx.app.log)) return forbidden();
89 const input = await body(ctx.request);
90 if (typeof input !== "object" || input === null || Array.isArray(input))
91 return apiError("invalid", 422, 'send a JSON object: {"usd": 200}');
92 const name = ctx.params["name"] ?? "";
93 const set = await setCredit(ctx.app, name, (input as Record<string, unknown>)["usd"]);
94 if (set.ok) return json(creditBody(name, set.credit));
95 return set.error === "not_found"
96 ? apiError("not_found", 404, "no such forge was sent from here")
97 : set.error === "invalid"
98 ? apiError("invalid", 422, `usd is a number from 0 to ${CREDIT_MAX_USD}`)
99 : apiError("failed", 500, "the credit could not be lent just now");
100 });
101
102 // What this forge, as a child, last heard of its parent's credit to it.
103 router.add("GET", "/api/v1/forge/credit", async (ctx) => {
104 const denied = requireScope(ctx, "ro");
105 if (denied) return denied;
106 if (!ctx.auth.user?.isAdmin) return forbidden();
107 const c = creditSeen(ctx.app);
108 return c === undefined ? apiError("not_found", 404, "no credit from a parent") : json({ ...c, says: leftWords(c) });
109 });
110
74111 // A new claim link for a child nobody has claimed (#729); the old one dies.
75112 router.add("POST", "/api/v1/forges/:name/claim-link", async (ctx) => {
76113 const denied = requireScope(ctx, "rw");
src/http/server.ts +2 −1
@@ -257,7 +257,7 @@ import {
257257 import { claimFragmentPage, claimOptions, claimSubmit } from "../web/pages/claim.ts";
258258 import { firstAdminOptions, firstAdminPage, firstAdminSubmit } from "../web/pages/first-admin.ts";
259259 import { familyPage } from "../web/pages/family.ts";
260 import { forgeLinkSubmit, forgeRemoveConfirm, forgeRemoveSubmit, forgeStopSubmit, forgesPage } from "../web/pages/forges.ts";
260 import { forgeCreditSubmit, forgeLinkSubmit, forgeRemoveConfirm, forgeRemoveSubmit, forgeStopSubmit, forgesPage } from "../web/pages/forges.ts";
261261 import { forgeItSubmit } from "../web/pages/forge-it.ts";
262262 import { newForgePage, newForgeSubmit } from "../web/pages/new-forge.ts";
263263 import { askedPage } from "../web/studio/asked_page.ts";
@@ -811,6 +811,7 @@ export function buildRouter(): Router<Handler> {
811811 router.add("GET", "/family", familyPage);
812812 router.add("POST", "/forges/:name/claim-link", forgeLinkSubmit);
813813 router.add("POST", "/forges/:name/stop", forgeStopSubmit);
814 router.add("POST", "/forges/:name/credit", forgeCreditSubmit);
814815 router.add("GET", "/forges/:name/remove", forgeRemoveConfirm);
815816 router.add("POST", "/forges/:name/remove", forgeRemoveSubmit);
816817 router.add("GET", "/forges/new", newForgePage);
src/spawn/beat-door.ts +8 −3
@@ -1,12 +1,14 @@
11 /**
22 * The one door a cell child has to its parent: a loopback listener that
3 * answers `POST /api/v1/heartbeat` and nothing else. The child's cell relays
3 * answers `POST /api/v1/heartbeat` and the credit endpoint (`credit_door.ts`), nothing else. The child's cell relays
44 * only this port in, so untrusted child code never reaches the parent's web
55 * surface, and since the door never asks who the client is, no forwarding
66 * header it sends counts for anything.
77 */
88
99 import type { App } from "../app.ts";
10 import { creditAnswer } from "./credit.ts";
11 import { CREDIT_BODY_MAX, serveCredit } from "./credit_door.ts";
1012 import { receiveBeat, SIGNATURE_HEADER } from "./heartbeat.ts";
1113
1214 const MAX_BODY = 1024;
@@ -26,14 +28,17 @@ export function openBeatDoor(app: App): BeatDoor {
2628 const server = Bun.serve({
2729 port: 0,
2830 hostname: "127.0.0.1",
29 maxRequestBodySize: MAX_BODY,
31 // A heartbeat is small (checked below); the credit door takes a model call.
32 maxRequestBodySize: CREDIT_BODY_MAX,
3033 async fetch(req) {
3134 const refused = new Response("no such door", { status: 404 });
35 const credit = await serveCredit(app, req);
36 if (credit !== undefined) return credit;
3237 if (req.method !== "POST" || new URL(req.url).pathname !== "/api/v1/heartbeat") return refused;
3338 const raw = await req.text();
3439 if (raw.length > MAX_BODY) return refused;
3540 const kept = await receiveBeat(app, raw, req.headers.get(SIGNATURE_HEADER));
36 return kept ? Response.json({ ok: true }) : refused;
41 return kept ? Response.json({ ok: true, credit: await creditAnswer(app, raw) }) : refused;
3742 },
3843 });
3944 return { port: server.port!, close: () => server.stop(true) };
src/spawn/clients.ts +5
@@ -14,6 +14,7 @@ import { childDirOf, listChildren, statusTokenOf, type Child } from "../actions/
1414 import { timingSafeEqual } from "node:crypto";
1515 import { sha256 } from "../kernel/hash.ts";
1616 import type { ChildAppsSummary } from "./child-apps.ts";
17 import { creditOf, type Credit } from "./credit.ts";
1718 import { childAwake, hostedChildApps } from "./host.ts";
1819 import { hasAdmin, spawnedOrg } from "./claim.ts";
1920 import { lastHeard, type Beat } from "./heartbeat.ts";
@@ -50,6 +51,8 @@ export interface ClientRow {
5051 readonly spendTodayUsd: number | null;
5152 /** The child's forge cap in dollars; null when none or unsaid. */
5253 readonly ceilingUsd: number | null;
54 /** What this forge lends its crew on its own credential, and what is spent; null when none was set (#10484). */
55 readonly credit?: Credit | null;
5356 /** Its size (`spawn/sizes.ts`). */
5457 readonly size: Size;
5558 /** What it uses against that size: its cell's reading, or "shared" when it is hosted here. */
@@ -196,6 +199,7 @@ export async function clientRows(app: App): Promise<ClientRow[]> {
196199 }),
197200 );
198201 const beats = await Promise.all(children.map((c) => lastHeard(app, c.name)));
202 const credits = await Promise.all(children.map((c) => creditOf(app, c.name)));
199203 return orderRows(
200204 children.map((c, i) => ({
201205 name: c.name,
@@ -211,6 +215,7 @@ export async function clientRows(app: App): Promise<ClientRow[]> {
211215 reach: reachOf(app, c.name) ?? null,
212216 spendTodayUsd: beats[i]?.beat.spendTodayUsd ?? null,
213217 ceilingUsd: beats[i]?.beat.ceilingUsd ?? null,
218 credit: credits[i] ?? null,
214219 size: c.size,
215220 use: forgeUse(c, childDirOf(app, c.bodyId)),
216221 lastHeartbeatAt: beats[i] === undefined ? null : new Date(beats[i]!.receivedAt).toISOString(),
src/spawn/credit.ts added +197
@@ -0,0 +1,197 @@
1 /**
2 * The parent's credit to a child (#10484): a dollar cap per child on the
3 * parent's own model credential, and what the child's crew has spent of it.
4 * The child never holds the credential; it holds a bearer that only this
5 * forge accepts, for its name, and the parent meters each call by list price.
6 *
7 * State is one file per child under `<data>/credit/<name>.json`, written
8 * whole through a rename, one change at a time per name. The bearer is kept
9 * here only as a hash. The child's own copy sits sealed in its subscription
10 * row (`lend`), under the name `FROM_PARENT`.
11 */
12
13 import { timingSafeEqual } from "node:crypto";
14 import { mkdir, rename } from "node:fs/promises";
15 import { join } from "node:path";
16 import { childDirOf, listChildren, STARTER_KEY } from "../actions/spawn.ts";
17 import { createApp, type App } from "../app.ts";
18 import { isChildName } from "../core/proposal_token.ts";
19 import { addSubscription, getSubscriptionByName, setGrants } from "../core/subscriptions.ts";
20 import { sha256 } from "../kernel/hash.ts";
21 import { secret } from "../kernel/id.ts";
22 import { spawnedOrg } from "./claim.ts";
23
24 /** What the child's crew sees the credit as. */
25 export const FROM_PARENT = "from parent";
26 /** The most one child may be lent. */
27 export const CREDIT_MAX_USD = 100_000;
28
29 export interface Credit {
30 readonly capUsd: number;
31 readonly spentUsd: number;
32 }
33
34 interface Doc {
35 capUsd: number;
36 spentUsd: number;
37 /** sha256 of the bearer; absent until the credit is first lent. */
38 tokenHash?: string;
39 }
40
41 const path = (app: App, name: string): string => join(app.config.dataDir, "credit", `${name}.json`);
42
43 async function read(app: App, name: string): Promise<Doc | undefined> {
44 if (!isChildName(name)) return undefined;
45 try {
46 const d = (await Bun.file(path(app, name)).json()) as Record<string, unknown>;
47 const cap = d["capUsd"];
48 const spent = d["spentUsd"];
49 if (typeof cap !== "number" || typeof spent !== "number") return undefined;
50 return { capUsd: cap, spentUsd: spent, ...(typeof d["tokenHash"] === "string" ? { tokenHash: d["tokenHash"] } : {}) };
51 } catch {
52 return undefined;
53 }
54 }
55
56 async function write(app: App, name: string, doc: Doc): Promise<void> {
57 await mkdir(join(app.config.dataDir, "credit"), { recursive: true });
58 await Bun.write(`${path(app, name)}.tmp`, JSON.stringify(doc), { mode: 0o600 });
59 await rename(`${path(app, name)}.tmp`, path(app, name));
60 }
61
62 const turns = new Map<string, Promise<unknown>>();
63
64 /** One change at a time per child, so two calls cannot both read the same spend. */
65 function inTurn<T>(app: App, name: string, work: () => Promise<T>): Promise<T> {
66 const key = `${app.config.dataDir}\0${name}`;
67 const run = (turns.get(key) ?? Promise.resolve()).then(work, work);
68 const tail = run.then(
69 () => undefined,
70 () => undefined,
71 );
72 turns.set(key, tail);
73 void tail.then(() => {
74 if (turns.get(key) === tail) turns.delete(key);
75 });
76 return run;
77 }
78
79 /** The credit a child has, or undefined when none was ever set. */
80 export async function creditOf(app: App, name: string): Promise<Credit | undefined> {
81 const d = await read(app, name);
82 return d === undefined ? undefined : { capUsd: d.capUsd, spentUsd: d.spentUsd };
83 }
84
85 export const money = (usd: number): string => (Number.isInteger(usd) ? `$${usd}` : `$${usd.toFixed(2)}`);
86
87 /** The one sentence a call past the cap is refused with. */
88 export const spentWords = (name: string, capUsd: number): string =>
89 `${name}'s ${money(capUsd)} from its parent is spent; the parent's admin can raise it.`;
90
91 /** The child's page: what is left of the cap. */
92 export const leftWords = (c: Credit): string =>
93 `funded by its parent: ${money(Math.max(0, Math.round((c.capUsd - c.spentUsd) * 100) / 100))} of ${money(c.capUsd)} left`;
94
95 export type SetRefusal = "not_found" | "invalid" | "failed";
96
97 /**
98 * Set a child's cap, in dollars (0 withdraws the credit). The first time a
99 * child is lent anything, it is handed the bearer: sealed in its own
100 * subscription row, granted to its organisation, never shown again.
101 */
102 export async function setCredit(
103 app: App,
104 name: string,
105 usd: unknown,
106 ): Promise<{ ok: true; credit: Credit } | { ok: false; error: SetRefusal }> {
107 if (typeof usd !== "number" || !Number.isFinite(usd) || usd < 0 || usd > CREDIT_MAX_USD)
108 return { ok: false, error: "invalid" };
109 if (!isChildName(name)) return { ok: false, error: "not_found" };
110 const child = (await listChildren(app)).find((c) => c.name === name && c.done);
111 if (child === undefined) return { ok: false, error: "not_found" };
112 const cap = Math.round(usd * 100) / 100;
113 return inTurn(app, name, async () => {
114 const held = await read(app, name);
115 let tokenHash = held?.tokenHash;
116 if (tokenHash === undefined && cap > 0) {
117 const token = `fcr.${name}.${secret()}`;
118 if (!(await lend(app, child.bodyId, token))) return { ok: false as const, error: "failed" as const };
119 tokenHash = sha256(token);
120 }
121 const doc: Doc = { capUsd: cap, spentUsd: held?.spentUsd ?? 0, ...(tokenHash === undefined ? {} : { tokenHash }) };
122 await write(app, name, doc);
123 return { ok: true as const, credit: { capUsd: doc.capUsd, spentUsd: doc.spentUsd } };
124 });
125 }
126
127 /** Seal the bearer into the child's own subscription row and offer it to its crew. */
128 async function lend(app: App, bodyId: string, token: string): Promise<boolean> {
129 const dir = childDirOf(app, bodyId);
130 const child = createApp({ dataDir: dir });
131 try {
132 const spawned = await spawnedOrg(child);
133 if (spawned === undefined) return false;
134 const upstream = app.config.url ?? `http://${app.config.host ?? "localhost"}`;
135 const row = addSubscription(child.db, dir, {
136 name: FROM_PARENT,
137 token,
138 apiBase: `${upstream.replace(/\/+$/, "")}/credit`,
139 });
140 if (!row.ok) return false;
141 // Beside a starter key, never in place of it: the crew works on the nearest grant.
142 if (getSubscriptionByName(child.db, STARTER_KEY) === undefined)
143 setGrants(child.db, spawned.org.id, "", [row.value.id]);
144 return true;
145 } finally {
146 child.close();
147 }
148 }
149
150 /** The child a bearer was minted for, when it is the one this forge holds the hash of. */
151 export async function childOfBearer(app: App, bearer: string): Promise<string | undefined> {
152 const m = /^fcr\.([a-z0-9-]{1,40})\.[A-Za-z0-9_-]{8,100}$/.exec(bearer);
153 const name = m?.[1];
154 if (name === undefined || !isChildName(name)) return undefined;
155 const held = (await read(app, name))?.tokenHash;
156 if (held === undefined) return undefined;
157 const a = Buffer.from(sha256(bearer));
158 const b = Buffer.from(held);
159 return a.length === b.length && timingSafeEqual(a, b) ? name : undefined;
160 }
161
162 /** Whether the child may still spend: ok, or the sentence it is refused with. */
163 export async function mayCharge(app: App, name: string): Promise<{ ok: true } | { ok: false; says: string }> {
164 const c = await creditOf(app, name);
165 if (c === undefined || c.capUsd <= 0) return { ok: false, says: `${name} has no credit from its parent.` };
166 return c.spentUsd >= c.capUsd ? { ok: false, says: spentWords(name, c.capUsd) } : { ok: true };
167 }
168
169 /** Add a metered call's cost to what the child has spent. */
170 export function charge(app: App, name: string, usd: number): Promise<void> {
171 return inTurn(app, name, async () => {
172 const d = await read(app, name);
173 if (d === undefined) return;
174 await write(app, name, { ...d, spentUsd: Math.round((d.spentUsd + usd) * 1e6) / 1e6 });
175 });
176 }
177
178 /** What a heartbeat's answer tells the child of its credit: null when it has none. */
179 export async function creditAnswer(app: App, rawBeat: string): Promise<Credit | null> {
180 let name: unknown;
181 try {
182 name = (JSON.parse(rawBeat) as Record<string, unknown>)["name"];
183 } catch {
184 return null;
185 }
186 if (typeof name !== "string") return null;
187 const c = await creditOf(app, name);
188 return c === undefined || c.capUsd <= 0 ? null : c;
189 }
190
191 /** The cap and the spend as the API reads them back. */
192 export const creditBody = (name: string, c: Credit) => ({
193 name,
194 capUsd: c.capUsd,
195 spentUsd: c.spentUsd,
196 leftUsd: Math.max(0, Math.round((c.capUsd - c.spentUsd) * 100) / 100),
197 });
src/spawn/credit_door.ts added +163
@@ -0,0 +1,163 @@
1 /**
2 * The model endpoint a parent serves to its children (#10484):
3 * `POST /credit/v1/messages` on the beat door, nothing else. A child's crew
4 * reaches it with the bearer minted for that child; the parent checks the
5 * bearer, refuses a child whose cap is spent with one sentence, forwards the
6 * call on its own credential (the child never sees it), and meters what came
7 * back by list price (`list_price.ts`).
8 *
9 * The call is relayed as the provider sends it, streamed or not. The cost is
10 * read from the usage the provider reports on the way through.
11 */
12
13 import type { App } from "../app.ts";
14 import { hostOfApiBase } from "../core/subscriptions.ts";
15 import { charge, childOfBearer, mayCharge } from "./credit.ts";
16 import { listPriceUsd, usageOf, type Usage } from "./list_price.ts";
17
18 export const CREDIT_PATH = "/credit/v1/messages";
19 /** The most one call may carry; a crew's context is large. */
20 export const CREDIT_BODY_MAX = 8 * 1024 * 1024;
21 /** Charged when a provider's answer carried no usage, so a silent answer is never free. */
22 const UNMETERED_USD = 0.01;
23 const DEFAULT_BASE = "https://api.anthropic.com";
24
25 type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
26
27 export interface Upstream {
28 readonly base: string;
29 readonly key: string;
30 readonly fetcher: FetchLike;
31 }
32
33 const upstreams = new WeakMap<App, Upstream>();
34
35 /** Tests swap where the parent's credential is spent. */
36 export function useCreditUpstream(app: App, upstream: Upstream): void {
37 upstreams.set(app, upstream);
38 }
39
40 /** The parent's own model credential, from its environment; undefined when it has none. */
41 function upstreamOf(app: App): Upstream | undefined {
42 const set = upstreams.get(app);
43 if (set !== undefined) return set;
44 const key = (process.env["ANTHROPIC_API_KEY"] ?? "").trim();
45 if (key === "") return undefined;
46 const base = (process.env["ANTHROPIC_BASE_URL"] ?? "").trim() || DEFAULT_BASE;
47 return { base: base.replace(/\/+$/, ""), key, fetcher: fetch };
48 }
49
50 const refuse = (status: number, message: string): Response =>
51 Response.json({ type: "error", error: { type: status === 402 ? "billing_error" : "invalid_request_error", message } }, { status });
52
53 function bearerOf(req: Request): string {
54 const auth = req.headers.get("authorization") ?? "";
55 return auth.startsWith("Bearer ") ? auth.slice(7).trim() : (req.headers.get("x-api-key") ?? "").trim();
56 }
57
58 /** Merge what a stream's events say of usage: later numbers replace earlier ones that were zero. */
59 function merge(a: Usage, b: Usage): Usage {
60 return {
61 input: b.input || a.input,
62 output: b.output || a.output,
63 cacheRead: b.cacheRead || a.cacheRead,
64 cacheWrite: b.cacheWrite || a.cacheWrite,
65 };
66 }
67
68 const none: Usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
69 const seen = (u: Usage): boolean => u.input + u.output + u.cacheRead + u.cacheWrite > 0;
70
71 /** Relay a streamed answer while reading its usage; `done` is told the model and usage at the end. */
72 function metered(body: ReadableStream<Uint8Array>, done: (model: string, use: Usage) => void): ReadableStream<Uint8Array> {
73 const decoder = new TextDecoder();
74 let tail = "";
75 let model = "";
76 let use = none;
77 const take = (line: string): void => {
78 if (!line.startsWith("data:")) return;
79 try {
80 const e = JSON.parse(line.slice(5)) as Record<string, unknown>;
81 const message = e["message"] as Record<string, unknown> | undefined;
82 if (e["type"] === "message_start" && message !== undefined) {
83 if (typeof message["model"] === "string") model = message["model"];
84 use = merge(use, usageOf(message["usage"]));
85 } else if (e["type"] === "message_delta") use = merge(use, usageOf(e["usage"]));
86 } catch {
87 // Not JSON: a comment or a ping; nothing to read.
88 }
89 };
90 return body.pipeThrough(
91 new TransformStream<Uint8Array, Uint8Array>({
92 transform(chunk, controller) {
93 controller.enqueue(chunk);
94 const lines = (tail + decoder.decode(chunk, { stream: true })).split("\n");
95 tail = (lines.pop() ?? "").slice(-65536);
96 for (const l of lines) take(l);
97 },
98 flush() {
99 take(tail);
100 done(model, use);
101 },
102 }),
103 );
104 }
105
106 /** Answer one call to the credit endpoint; undefined when the request is not for it. */
107 export async function serveCredit(app: App, req: Request): Promise<Response | undefined> {
108 if (req.method !== "POST" || new URL(req.url).pathname !== CREDIT_PATH) return undefined;
109 const name = await childOfBearer(app, bearerOf(req));
110 if (name === undefined) return refuse(401, "this credit is not one the parent gave.");
111 const may = await mayCharge(app, name);
112 if (!may.ok) return refuse(402, may.says);
113 const upstream = upstreamOf(app);
114 if (upstream === undefined) return refuse(503, "the parent has no model credential to lend.");
115 const length = Number(req.headers.get("content-length") ?? "0");
116 if (!Number.isFinite(length) || length > CREDIT_BODY_MAX) return refuse(413, "the request is too large.");
117 const raw = await req.text();
118 if (raw.length > CREDIT_BODY_MAX) return refuse(413, "the request is too large.");
119 let sent: Record<string, unknown>;
120 try {
121 const doc: unknown = JSON.parse(raw);
122 if (typeof doc !== "object" || doc === null || Array.isArray(doc)) throw new Error("not an object");
123 sent = doc as Record<string, unknown>;
124 } catch {
125 return refuse(400, "send a JSON object.");
126 }
127 const asked = typeof sent["model"] === "string" && sent["model"].length <= 120 ? sent["model"] : "";
128 if (asked === "") return refuse(400, "name a model.");
129
130 const openrouter = (hostOfApiBase(upstream.base) ?? "").endsWith("openrouter.ai");
131 const headers: Record<string, string> = {
132 "content-type": "application/json",
133 "anthropic-version": (req.headers.get("anthropic-version") ?? "2023-06-01").slice(0, 40),
134 ...(openrouter ? { authorization: `Bearer ${upstream.key}` } : { "x-api-key": upstream.key }),
135 };
136 const beta = req.headers.get("anthropic-beta");
137 if (beta !== null && /^[\w.,-]{1,300}$/.test(beta)) headers["anthropic-beta"] = beta;
138
139 let answer: Response;
140 try {
141 answer = await upstream.fetcher(`${upstream.base}/v1/messages`, { method: "POST", headers, body: raw, redirect: "error" });
142 } catch {
143 return refuse(502, "the parent could not reach its model provider.");
144 }
145 const bill = (model: string, use: Usage): void => {
146 void charge(app, name, seen(use) ? listPriceUsd(model || asked, use) : UNMETERED_USD);
147 };
148 const type = answer.headers.get("content-type") ?? "application/json";
149 // A provider's refusal costs nothing and is passed on as it came.
150 if (!answer.ok || answer.body === null) return new Response(answer.body, { status: answer.status, headers: { "content-type": type } });
151 if (type.includes("text/event-stream"))
152 return new Response(metered(answer.body, bill), { status: answer.status, headers: { "content-type": type, "cache-control": "no-store" } });
153 const text = await answer.text();
154 try {
155 const doc = JSON.parse(text) as Record<string, unknown>;
156 bill(typeof doc["model"] === "string" ? doc["model"] : "", usageOf(doc["usage"]));
157 } catch {
158 bill("", none);
159 }
160 // Charged before the answer returns, so a second call right behind it sees the spend.
161 await charge(app, name, 0);
162 return new Response(text, { status: answer.status, headers: { "content-type": type } });
163 }
src/spawn/credit_reach.ts added +21
@@ -0,0 +1,21 @@
1 /**
2 * Where a child's crew reaches the credit its parent lent (#10484). The row
3 * is sealed with the parent's public address (`<parent>/credit`); inside a
4 * cell that address is out of reach, so a run there is pointed at the
5 * relayed loopback door (`FORGE_PARENT_LOCAL`) instead. Nothing else about
6 * the call changes, and no host is added to the child's egress.
7 */
8
9 import { isParentLocal } from "./beat-door.ts";
10
11 /** The base a run should use for an account's `api_base`. */
12 export function reachableBase<T extends string | null | undefined>(apiBase: T): T | string {
13 if (typeof apiBase !== "string") return apiBase;
14 const local = process.env["FORGE_PARENT_LOCAL"] ?? "";
15 if (!isParentLocal(local)) return apiBase;
16 try {
17 return new URL(apiBase).pathname.replace(/\/+$/, "") === "/credit" ? `${local}/credit` : apiBase;
18 } catch {
19 return apiBase;
20 }
21 }
src/spawn/credit_seen.ts added +40
@@ -0,0 +1,40 @@
1 /**
2 * What a child last heard of the credit its parent lends it (#10484): the
3 * cap and the spend, carried back on the parent's answer to each heartbeat
4 * and kept in one small file, so the child's crew page can say what is left
5 * without asking. The parent is the book; this is a copy that is a beat old.
6 */
7
8 import { readFileSync } from "node:fs";
9 import { mkdir, rename } from "node:fs/promises";
10 import { join } from "node:path";
11 import type { App } from "../app.ts";
12 import type { Credit } from "./credit.ts";
13
14 const file = (app: App): string => join(app.config.dataDir, "credit-from-parent.json");
15
16 /** Keep what the parent said; null (it lends nothing now) removes the copy. */
17 export async function rememberCredit(app: App, said: unknown): Promise<void> {
18 const o = typeof said === "object" && said !== null ? (said as Record<string, unknown>) : undefined;
19 const cap = o?.["capUsd"];
20 const spent = o?.["spentUsd"];
21 if (typeof cap !== "number" || typeof spent !== "number" || !Number.isFinite(cap) || !Number.isFinite(spent) || cap <= 0) {
22 await Bun.file(file(app)).delete().catch(() => undefined);
23 return;
24 }
25 await mkdir(app.config.dataDir, { recursive: true });
26 await Bun.write(`${file(app)}.tmp`, JSON.stringify({ capUsd: cap, spentUsd: spent }));
27 await rename(`${file(app)}.tmp`, file(app));
28 }
29
30 /** The credit the parent last said it lends; undefined when it lends none. */
31 export function creditSeen(app: App): Credit | undefined {
32 try {
33 const d = JSON.parse(readFileSync(file(app), "utf8")) as Record<string, unknown>;
34 return typeof d["capUsd"] === "number" && typeof d["spentUsd"] === "number"
35 ? { capUsd: d["capUsd"], spentUsd: d["spentUsd"] }
36 : undefined;
37 } catch {
38 return undefined;
39 }
40 }
src/spawn/heartbeat.ts +2
@@ -13,6 +13,7 @@
1313 * nothing: unknown children are ignored.
1414 */
1515
16 import { rememberCredit } from "./credit_seen.ts";
1617 import { createHmac, timingSafeEqual } from "node:crypto";
1718 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
1819 import { join } from "node:path";
@@ -314,6 +315,7 @@ export async function sendBeat(
314315 signal: AbortSignal.timeout(5000),
315316 redirect: "error",
316317 });
318 if (res.ok) await rememberCredit(app, ((await res.json().catch(() => ({}))) as { credit?: unknown }).credit);
317319 return res.ok;
318320 } catch {
319321 return false;
src/spawn/list_price.ts added +45
@@ -0,0 +1,45 @@
1 /**
2 * What a model call costs at list price, in dollars, from the usage the
3 * provider reports. A child's credit from its parent is metered by this and
4 * nothing else: the parent never asks the provider what it was billed.
5 * A model this table does not know is priced as the dearest, so the cap
6 * errs towards stopping early.
7 */
8
9 export interface Usage {
10 readonly input: number;
11 readonly output: number;
12 readonly cacheRead: number;
13 readonly cacheWrite: number;
14 }
15
16 /** Dollars per million tokens, input and output. */
17 const FAMILIES: readonly { readonly match: string; readonly input: number; readonly output: number }[] = [
18 { match: "haiku", input: 1, output: 5 },
19 { match: "sonnet", input: 3, output: 15 },
20 { match: "opus", input: 15, output: 75 },
21 ];
22 const DEAREST = { input: 15, output: 75 };
23 /** Cache reads cost a tenth of input; cache writes a quarter more. */
24 const READ = 0.1;
25 const WRITE = 1.25;
26
27 export function listPriceUsd(model: string, use: Usage): number {
28 const m = model.toLowerCase();
29 const rate = FAMILIES.find((f) => m.includes(f.match)) ?? DEAREST;
30 const million = (use.input + use.cacheWrite * WRITE + use.cacheRead * READ) * rate.input + use.output * rate.output;
31 return million / 1_000_000;
32 }
33
34 const count = (v: unknown): number => (typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : 0);
35
36 /** The usage in a provider's `usage` object; zeros for anything it did not say. */
37 export function usageOf(raw: unknown): Usage {
38 const u = typeof raw === "object" && raw !== null ? (raw as Record<string, unknown>) : {};
39 return {
40 input: count(u["input_tokens"]),
41 output: count(u["output_tokens"]),
42 cacheRead: count(u["cache_read_input_tokens"]),
43 cacheWrite: count(u["cache_creation_input_tokens"]),
44 };
45 }
src/web/pages/crew.ts +4
@@ -66,6 +66,8 @@ import { accountSections } from "./origins.ts";
6666 import { markOf } from "../../core/marks.ts";
6767 import { limitValue } from "../../settings/limits.ts";
6868 import { USERNAME_TAKEN } from "../../actions/signup_words.ts";
69 import { leftWords } from "../../spawn/credit.ts";
70 import { creditSeen } from "../../spawn/credit_seen.ts";
6971 import { forgeCeiling } from "../../flow/ceiling.ts";
7072
7173 /** The admin, or the response that turns everyone else away. */
@@ -601,7 +603,9 @@ function crewView(
601603 const usernameError =
602604 error !== undefined && /username/i.test(error) ? error : undefined;
603605 const handover = crewHandover(ctx.app.db);
606 const funded = creditSeen(ctx.app);
604607 return html`${crewReadiness(ctx)}
608 ${funded === undefined ? null : html`<p class="muted" data-funded-by-parent role="status">${leftWords(funded)}</p>`}
605609 ${when(spending.length > 0, () =>
606610 spendingCard(spending, forgeCeiling(ctx.app.config) ?? undefined),
607611 )}
src/web/pages/forges.ts +57 −2
@@ -13,12 +13,13 @@ import { notFoundPage, pageHead } from "../chrome.ts";
1313 import { html, type Html } from "../html.ts";
1414 import { page } from "../layout.ts";
1515 import { reissueDoor } from "../../spawn/door.ts";
16 import { readForm } from "../form.ts";
16 import { field, readForm } from "../form.ts";
1717 import { badge, btn, row, time } from "../ui.ts";
1818 import { noRoom } from "../../spawn/door.ts";
1919 import { sizeWords, useWords } from "../../spawn/usage.ts";
2020 import { listChildren } from "../../actions/spawn.ts";
2121 import { removeForge, stopForge, type Managed } from "../../spawn/manage.ts";
22 import { CREDIT_MAX_USD, money, setCredit } from "../../spawn/credit.ts";
2223 import { claimLinkBody } from "./new-forge.ts";
2324
2425
@@ -41,6 +42,23 @@ function spendNote(r: ClientRow): Html | null {
4142 : html`<span data-spend="ok">${s.words}</span>`;
4243 }
4344
45 /** What it lends its crew: spent of the cap, and the one field that sets it. */
46 function creditNote(r: ClientRow): Html | null {
47 if (!r.made) return null;
48 const c = r.credit ?? null;
49 return html`<span data-credit="${c === null ? "none" : "lent"}"
50 >${c === null || c.capUsd <= 0 ? "no credit lent" : html`credit ${money(c.spentUsd)} of ${money(c.capUsd)} spent`}</span
51 >`;
52 }
53
54 function creditForm(r: ClientRow): Html | null {
55 if (!r.made) return null;
56 return html`<form method="post" action="/forges/${r.name}/credit" class="inline">
57 <input type="number" name="usd" min="0" max="${CREDIT_MAX_USD}" step="1" required aria-label="Dollars lent to ${r.name}'s crew" value="${r.credit?.capUsd ?? 0}" />
58 ${btn("Lend", { size: "sm", title: "Cap, in dollars, on this forge's own model credential; 0 withdraws it" })}
59 </form>`;
60 }
61
4462 function forgeRow(r: ClientRow): Html {
4563 const state = claimState(r);
4664 const meta = [
@@ -51,6 +69,7 @@ function forgeRow(r: ClientRow): Html {
5169 r.made ? html`${sizeWords(r.size)}` : null,
5270 runningNote(r),
5371 spendNote(r),
72 creditNote(r),
5473 r.sentAt === null ? null : html`sent ${time(r.sentAt)}`,
5574 r.lastActivityAt === null
5675 ? null
@@ -78,7 +97,7 @@ function forgeRow(r: ClientRow): Html {
7897 }),
7998 ),
8099 }),
81 trail: html`${r.attention === null
100 trail: html`${creditForm(r)}${r.attention === null
82101 ? null
83102 : html`<span data-attention="${r.attention}">${badge(ATTENTION_WORDS[r.attention], { tone: "attn" })}</span>`}${badge(CLAIM_WORDS[state], {
84103 ...(state === "yes" ? { tone: "success" as const } : { variant: "outline" as const }),
@@ -256,3 +275,39 @@ export async function forgeRemoveConfirm(ctx: Ctx): Promise<Response> {
256275 response.headers.set("cache-control", "no-store");
257276 return response;
258277 }
278
279 // POST /forges/:name/credit — the cap, in dollars, on what this forge lends the child's crew.
280 export async function forgeCreditSubmit(ctx: Ctx): Promise<Response> {
281 const user = ctx.auth.user;
282 if (!user?.isAdmin) return notFoundPage(ctx);
283 const form = await readForm(ctx, "admin");
284 if (form instanceof Response) return form;
285 const name = ctx.params["name"] ?? "";
286 const raw = field(form, "usd").trim();
287 const set = await setCredit(ctx.app, name, /^\d{1,6}(\.\d{1,2})?$/.test(raw) ? Number(raw) : Number.NaN);
288 const says = set.ok
289 ? set.credit.capUsd > 0
290 ? `${name}'s crew may spend ${money(set.credit.capUsd)} of this forge's credential; ${money(set.credit.spentUsd)} is spent.`
291 : `${name}'s crew is lent nothing now.`
292 : set.error === "invalid"
293 ? `Send dollars from 0 to ${CREDIT_MAX_USD}.`
294 : set.error === "not_found"
295 ? "No forge was sent under that name."
296 : "The credit could not be lent just now.";
297 const response = page(
298 {
299 ctx,
300 title: "Credit",
301 body: html`<div class="narrow-wide" data-forges>
302 ${pageHead("Credit")}
303 <section class="settings-block">
304 <p role="status">${says}</p>
305 <p class="mt">${btn("Back to your forges", { href: "/forges", size: "sm" })}</p>
306 </section>
307 </div>`,
308 },
309 set.ok ? 200 : 422,
310 );
311 response.headers.set("cache-control", "no-store");
312 return response;
313 }
test/child-quota.test.ts +1 −1
@@ -101,7 +101,7 @@ describe("child quota", () => {
101101
102102 test("room for small but not large is refused only for large", async () => {
103103 clear();
104 process.env["FORGE_CHILD_MEMORY_MIB"] = "2000";
104 process.env["FORGE_CHILD_MEMORY_MIB"] = "4100";
105105 expect(quotaRefusal(dir, "small")).toBeUndefined();
106106 expect(quotaRefusal(dir, "large")).toContain("memory limit");
107107 });
test/parent-credit.test.ts added +252
@@ -0,0 +1,252 @@
1 /**
2 * A parent funds a child's crew (#10484): a dollar cap per child on the
3 * parent's own credential, metered by list price. The child holds a bearer
4 * only the parent accepts; past the cap a call is refused with one sentence;
5 * the cap and the spend read back on both forges.
6 */
7
8 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
9 import { mkdtemp, readdir, readFile, rm } from "node:fs/promises";
10 import { tmpdir } from "node:os";
11 import { join } from "node:path";
12 import { childDirOf } from "../src/actions/spawn.ts";
13 import { createApp, type App } from "../src/app.ts";
14 import { createToken } from "../src/core/tokens.ts";
15 import { credentialEnvOf, pickSubscription } from "../src/core/subscriptions.ts";
16 import { createUser } from "../src/core/users.ts";
17 import { serve, type Servers } from "../src/http/server.ts";
18 import { openBeatDoor, type BeatDoor } from "../src/spawn/beat-door.ts";
19 import { leftWords, spentWords } from "../src/spawn/credit.ts";
20 import { useCreditUpstream } from "../src/spawn/credit_door.ts";
21 import { reachableBase } from "../src/spawn/credit_reach.ts";
22 import { rememberCredit } from "../src/spawn/credit_seen.ts";
23 import { spawnedOrg } from "../src/spawn/claim.ts";
24 import { firstBoot } from "../src/spawn/first-boot.ts";
25 import { beatKeyOf } from "../src/actions/spawn.ts";
26 import { sign, SIGNATURE_HEADER } from "../src/spawn/heartbeat.ts";
27 import { listPriceUsd } from "../src/spawn/list_price.ts";
28 import { quietLogs } from "./helpers/globals.ts";
29
30 quietLogs();
31
32 const PARENT_KEY = "sk-ant-api03-the-parents-own-key";
33
34 describe("a parent's credit to a child", () => {
35 let dir = "";
36 let parent: App;
37 let child: App;
38 let servers: Servers;
39 let door: BeatDoor;
40 let token = "";
41 let reached: { key: string | null; path: string }[] = [];
42
43 const put = (usd: unknown, name = "maria") =>
44 fetch(`${servers.url}/api/v1/forges/${name}/credit`, {
45 method: "PUT",
46 headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
47 body: JSON.stringify({ usd }),
48 });
49 const read = (name = "maria") =>
50 fetch(`${servers.url}/api/v1/forges/${name}/credit`, { headers: { authorization: `Bearer ${token}` } });
51
52 /** The child's crew, picking its account the way a run does. */
53 let orgId = "";
54 const crewEnv = () => {
55 const picked = pickSubscription(child.db, child.config.dataDir, { repoId: "r", ownerId: orgId, agentId: "a" }, new Date());
56 if (picked.kind !== "ready") throw new Error(`picked ${picked.kind}`);
57 return credentialEnvOf({ ...picked, apiBase: reachableBase(picked.apiBase) });
58 };
59 const call = (env: Record<string, string>, model = "claude-sonnet-5-5") =>
60 fetch(`${env["ANTHROPIC_BASE_URL"]}/v1/messages`, {
61 method: "POST",
62 headers: { "x-api-key": env["ANTHROPIC_API_KEY"] ?? "", "content-type": "application/json" },
63 body: JSON.stringify({ model, max_tokens: 10, messages: [{ role: "user", content: "hi" }] }),
64 });
65
66 beforeAll(async () => {
67 dir = await mkdtemp(join(tmpdir(), "forge-credit-"));
68 parent = createApp({ dataDir: dir, url: "https://forge.test", port: 0 });
69 const alice = await createUser(parent.db, {
70 origin: "seed",
71 trusted: true,
72 username: "alice",
73 email: "[email protected]",
74 password: "a-long-credit-passphrase",
75 isAdmin: true,
76 });
77 if (!alice.ok) throw new Error("user");
78 token = createToken(parent.db, alice.value.id, "rw", "rw").token;
79 servers = await serve(parent);
80 const made = await fetch(`${servers.url}/api/v1/forges`, {
81 method: "POST",
82 headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
83 body: JSON.stringify({ name: "maria", apps: [], dryRun: false }),
84 });
85 if (made.status !== 201) throw new Error(`spawn ${made.status}`);
86 const { bodyId } = (await made.json()) as { bodyId: string };
87 child = createApp({ dataDir: childDirOf(parent, bodyId), port: 0 });
88 await firstBoot(child);
89 orgId = (await spawnedOrg(child))!.org.id;
90 useCreditUpstream(parent, {
91 base: "https://models.test",
92 key: PARENT_KEY,
93 fetcher: async (url, init) => {
94 const headers = init?.headers as Record<string, string>;
95 reached.push({ key: headers["x-api-key"] ?? null, path: new URL(url).pathname });
96 // 100k input and 20k output tokens on Sonnet: $0.30 + $0.30 = $0.60 at list price.
97 return Response.json({ model: "claude-sonnet-5-5", usage: { input_tokens: 100_000, output_tokens: 20_000 } });
98 },
99 });
100 door = openBeatDoor(parent);
101 }, 60_000);
102
103 afterAll(async () => {
104 door.close();
105 servers.stop();
106 child.close();
107 parent.close();
108 await rm(dir, { recursive: true, force: true });
109 });
110
111 test("list price: a family's rate, the dearest for an unknown model, cache priced apart", () => {
112 const use = { input: 1_000_000, output: 1_000_000, cacheRead: 0, cacheWrite: 0 };
113 expect(listPriceUsd("claude-sonnet-5-5", use)).toBeCloseTo(18);
114 expect(listPriceUsd("claude-haiku-5-5", use)).toBeCloseTo(6);
115 expect(listPriceUsd("something-new", use)).toBeCloseTo(90);
116 expect(listPriceUsd("claude-sonnet-5-5", { input: 0, output: 0, cacheRead: 1_000_000, cacheWrite: 0 })).toBeCloseTo(0.3);
117 });
118
119 test("the cap is an admin's to set, and reads back", async () => {
120 expect((await put(1, "nobody")).status).toBe(404);
121 for (const bad of [-1, "200", null, 1e9]) expect((await put(bad)).status).toBe(422);
122 expect((await fetch(`${servers.url}/api/v1/forges/maria/credit`, { method: "PUT", body: '{"usd":1}' })).status).toBeGreaterThanOrEqual(401);
123 expect((await read()).status).toBe(404);
124 const set = await put(1);
125 expect(set.status).toBe(200);
126 expect(await set.json()).toEqual({ name: "maria", capUsd: 1, spentUsd: 0, leftUsd: 1 });
127 expect(await (await read()).json()).toEqual({ name: "maria", capUsd: 1, spentUsd: 0, leftUsd: 1 });
128 });
129
130 test("the child holds a bearer for the parent and none of the parent's credential", async () => {
131 const env = crewEnv();
132 expect(env["ANTHROPIC_BASE_URL"]).toBe("https://forge.test/credit");
133 expect(env["ANTHROPIC_API_KEY"]).toMatch(/^fcr\.maria\./);
134 const files: string[] = [];
135 for (const f of await readdir(child.config.dataDir, { recursive: true, withFileTypes: true }))
136 if (f.isFile()) files.push(join(f.parentPath, f.name));
137 for (const f of files) expect((await readFile(f)).includes(PARENT_KEY)).toBe(false);
138 // The bearer is not in the child's database as plain text either.
139 expect(JSON.stringify(child.db.query("SELECT * FROM subscription").all())).not.toContain(env["ANTHROPIC_API_KEY"]!);
140 });
141
142 test("a run reaches the model through the parent's door, and past the cap is refused in one sentence", async () => {
143 process.env["FORGE_PARENT_LOCAL"] = `http://127.0.0.1:${door.port}`;
144 try {
145 const env = crewEnv();
146 expect(env["ANTHROPIC_BASE_URL"]).toBe(`http://127.0.0.1:${door.port}/credit`);
147 const first = await call(env);
148 expect(first.status).toBe(200);
149 expect(reached).toEqual([{ key: PARENT_KEY, path: "/v1/messages" }]);
150 expect((await (await read()).json()) as object).toMatchObject({ capUsd: 1, leftUsd: 0.4 });
151 // $0.60 spent of $1: one more is let through, and takes it to $1.20.
152 expect((await call(env)).status).toBe(200);
153 const refused = await call(env);
154 expect(refused.status).toBe(402);
155 const said = (await refused.json()) as { error: { message: string } };
156 expect(said.error.message).toBe("maria's $1 from its parent is spent; the parent's admin can raise it.");
157 expect(said.error.message).toBe(spentWords("maria", 1));
158 expect(reached.length).toBe(2);
159 expect(await (await read()).json()).toEqual({ name: "maria", capUsd: 1, spentUsd: 1.2, leftUsd: 0 });
160 // Raised, it runs again.
161 await put(5);
162 expect((await call(env)).status).toBe(200);
163 } finally {
164 delete process.env["FORGE_PARENT_LOCAL"];
165 }
166 });
167
168 test("a bearer that is not the child's, or none, gets nothing and spends nothing", async () => {
169 const before = reached.length;
170 for (const key of ["", "fcr.maria.notthebearernotthebearer", "fcr.other.notthebearernotthebearer", "sk-ant-x"]) {
171 const res = await fetch(`http://127.0.0.1:${door.port}/credit/v1/messages`, {
172 method: "POST",
173 headers: { "x-api-key": key },
174 body: JSON.stringify({ model: "claude-sonnet-5-5" }),
175 });
176 expect(res.status).toBe(401);
177 }
178 expect((await fetch(`http://127.0.0.1:${door.port}/credit/v1/models`)).status).toBe(404);
179 expect(reached.length).toBe(before);
180 });
181
182 test("the door passes a stream's usage through and meters it", async () => {
183 useCreditUpstream(parent, {
184 base: "https://models.test",
185 key: PARENT_KEY,
186 fetcher: async () =>
187 new Response(
188 'event: message_start\ndata: {"type":"message_start","message":{"model":"claude-haiku-5-5","usage":{"input_tokens":1000000,"output_tokens":1}}}\n\n' +
189 'event: message_delta\ndata: {"type":"message_delta","usage":{"output_tokens":1000000}}\n\n',
190 { headers: { "content-type": "text/event-stream" } },
191 ),
192 });
193 process.env["FORGE_PARENT_LOCAL"] = `http://127.0.0.1:${door.port}`;
194 try {
195 const before = (await (await read()).json()) as { spentUsd: number };
196 await put(100);
197 const res = await call(crewEnv());
198 expect(await res.text()).toContain("message_delta");
199 await Bun.sleep(20);
200 const after = (await (await read()).json()) as { spentUsd: number };
201 // Haiku at list price: $1 in and $5 out, per million.
202 expect(after.spentUsd - before.spentUsd).toBeCloseTo(6, 4);
203 } finally {
204 delete process.env["FORGE_PARENT_LOCAL"];
205 }
206 });
207
208 test("the child hears the cap and spend on its next heartbeat, and says so on its API and crew page", async () => {
209 const key = (await beatKeyOf(parent, "maria"))!;
210 const raw = JSON.stringify({ name: "maria", at: Date.now(), version: "0.7.114", openProposals: 0, children: 0 });
211 const res = await fetch(`http://127.0.0.1:${door.port}/api/v1/heartbeat`, {
212 method: "POST",
213 headers: { [SIGNATURE_HEADER]: sign(key, raw) },
214 body: raw,
215 });
216 const answer = (await res.json()) as { credit: { capUsd: number; spentUsd: number } };
217 expect(answer.credit.capUsd).toBe(100);
218 await rememberCredit(child, answer.credit);
219 const childServers = await serve(child);
220 try {
221 const admin = await createUser(child.db, { origin: "seed", trusted: true, username: "bob", email: "[email protected]", password: "a-long-credit-passphrase", isAdmin: true });
222 if (!admin.ok) throw new Error("admin");
223 const t = createToken(child.db, admin.value.id, "ro", "ro").token;
224 const seen = await fetch(`${childServers.url}/api/v1/forge/credit`, { headers: { authorization: `Bearer ${t}` } });
225 const body = (await seen.json()) as { capUsd: number; says: string };
226 expect(body.capUsd).toBe(100);
227 expect(body.says).toBe(leftWords(answer.credit));
228 expect(body.says).toMatch(/^funded by its parent: \$\d+(\.\d\d)? of \$100 left$/);
229 } finally {
230 childServers.stop();
231 }
232 });
233
234 test("the parent's forge list shows spent and cap per child", async () => {
235 const res = await fetch(`${servers.url}/api/v1/forges`, { headers: { authorization: `Bearer ${token}` } });
236 const { items } = (await res.json()) as { items: { name: string; credit: { capUsd: number; spentUsd: number } | null }[] };
237 expect(items.find((i) => i.name === "maria")?.credit?.capUsd).toBe(100);
238 expect(items.find((i) => i.name === "maria")?.credit?.spentUsd).toBeGreaterThan(1);
239 });
240
241 test("0 withdraws the credit: the next call is refused", async () => {
242 process.env["FORGE_PARENT_LOCAL"] = `http://127.0.0.1:${door.port}`;
243 try {
244 const env = crewEnv();
245 await put(0);
246 const res = await call(env);
247 expect(res.status).toBe(402);
248 } finally {
249 delete process.env["FORGE_PARENT_LOCAL"];
250 }
251 });
252 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs