@celestea/studio 2.7.1

package/dist/handlers/grants-shape.js

@@ -0,0 +1,130 @@
+/**
+ * Request parsing / response shaping for the grant endpoints (W516 §6).
+ *
+ * Kept apart from the routes so both stay inside the architecture budget: the
+ * error strings here are the FROZEN contract strings of §6.2, and a rejected
+ * scope value is never echoed (§5.4 — it may be a credential).
+ */
+import { unsandboxedAvailable } from "../runtime/engine-grants.js";
+import { DEFAULT_TTL_SEC, isOfferedGrantCap, MAX_TTL_SEC, canonicalScopeHash, knownSecretsOf, looksLikeCredential, validateScope, } from "../store/grants.js";
+import { failJson, numField, objectField, strField } from "./common.js";
+/** Who the grant is attributed to. Server-side constant: never model text. */
+export const GRANT_ACTOR = "ui:operator";
+/** §6.2 body: `{cap, scope?, ttl_sec?, uses_left?, note?}` + the frozen 400s. */
+export function parseGrantRequest(c, body, env) {
+    const known = knownSecretsOf(env);
+    const cap = strField(c, body, "cap");
+    if (!cap.ok)
+        return { ok: false, response: cap.response, reason: "field 'cap' must be a string" };
+    const raw = cap.value ?? "";
+    const chosen = offeredCap(raw, env);
+    if (chosen === null) {
+        const shown = looksLikeCredential(raw, known) ? "<redacted>" : raw;
+        return { ok: false, response: failJson(c, 400, `invalid cap '${shown}'`), reason: `invalid cap '${shown}'` };
+    }
+    const ttl = readTtl(c, body, chosen);
+    if (typeof ttl !== "number")
+        return { ok: false, response: ttl, reason: "ttl_sec out of range" };
+    const scope = readScope(c, body, chosen, known);
+    if (!scope.ok)
+        return { ok: false, response: scope.response, reason: scope.reason };
+    const uses = readUses(c, body, chosen);
+    if (typeof uses === "string")
+        return { ok: false, response: failJson(c, 400, uses), reason: uses };
+    const note = strField(c, body, "note");
+    if (!note.ok)
+        return { ok: false, response: note.response, reason: "field 'note' must be a string" };
+    // §5.4 + scenario 15: a note is user text, but a credential shape is refused
+    // outright (the frozen 400 string) and is never echoed back anywhere.
+    if (note.value !== undefined && looksLikeCredential(note.value, known)) {
+        return { ok: false, response: failJson(c, 400, "value looks like a credential"), reason: "value looks like a credential" };
+    }
+    return {
+        ok: true,
+        value: {
+            cap: chosen,
+            scope: scope.value,
+            ttlSec: ttl,
+            usesLeft: uses,
+            note: note.value ?? "",
+            scopeHash: canonicalScopeHash(chosen, scope.value),
+        },
+    };
+}
+/**
+ * The cap must be known AND offered here: `unsandboxed` only exists behind
+ * `CELESTEA_GRANTS_ALLOW_UNSANDBOXED=1` (§2.2), so without it the cap is simply
+ * not valid — the frozen `invalid cap '<x>'` error, never a special case.
+ */
+export function offeredCap(raw, env) {
+    // W819-8: a cap that exists in the file format but has no consumption point
+    // (RESERVED_GRANT_CAPS) is simply not offered - the frozen 400.
+    if (!isOfferedGrantCap(raw))
+        return null;
+    if (raw === "unsandboxed" && !unsandboxedAvailable(env))
+        return null;
+    return raw;
+}
+/** `ttl_sec`: positive integer, 0 = no expiry, capped per cap (§2.3). */
+export function readTtl(c, body, cap) {
+    const field = numField(c, body, "ttl_sec");
+    if (!field.ok)
+        return field.response;
+    const ttl = field.value ?? DEFAULT_TTL_SEC;
+    if (!Number.isInteger(ttl) || ttl < 0)
+        return failJson(c, 400, "ttl_sec must be a non-negative integer (0 = no expiry)");
+    if (ttl > MAX_TTL_SEC[cap])
+        return failJson(c, 400, `ttl_sec exceeds the maximum for cap '${cap}' (${MAX_TTL_SEC[cap]})`);
+    return ttl;
+}
+function readScope(c, body, cap, known) {
+    const field = objectField(c, body, "scope");
+    if (!field.ok)
+        return { ok: false, response: field.response, reason: "field 'scope' must be an object" };
+    const scope = validateScope(cap, field.value, known);
+    if (!scope.ok) {
+        const reason = `invalid scope for cap '${cap}': ${scope.error}`;
+        return { ok: false, response: failJson(c, 400, reason), reason };
+    }
+    return { ok: true, value: scope.scope };
+}
+/** `uses_left`: positive integer or null; `unsandboxed` is forced to 1 (§2.3). */
+function readUses(c, body, cap) {
+    if (cap === "unsandboxed")
+        return 1;
+    const field = numField(c, body, "uses_left");
+    if (!field.ok)
+        return "uses_left must be a positive integer";
+    const value = field.value;
+    if (value === undefined)
+        return null;
+    if (!Number.isInteger(value) || value < 1)
+        return "uses_left must be a positive integer";
+    return value;
+}
+/** One GET entry: the stored record plus the read-time `expired` flag (§6.1). */
+export function entryJson(record, now) {
+    const expired = record.expires_at !== null && now >= record.expires_at;
+    return {
+        id: record.id,
+        cap: record.cap,
+        scope: record.scope,
+        granted_at: record.granted_at,
+        granted_by: record.granted_by,
+        expires_at: record.expires_at,
+        uses_left: record.uses_left,
+        note: record.note,
+        expired,
+    };
+}
+/** The `effective` snapshot of §6.1 (snake_case; the UI shows it verbatim). */
+export function effectiveJson(grants) {
+    return {
+        network: grants.network,
+        read_roots: [...grants.readRoots],
+        write_roots: [...grants.writeRoots],
+        net_hosts: [...grants.netHosts],
+        tool_extra: [...grants.toolExtra],
+        unsandboxed: grants.unsandboxed,
+    };
+}

package/dist/handlers/grants.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The four grant endpoints (W516 §6): read the session's grants, grant one, a
+ * revoke, and the one-shot confirm token that makes a grant a HUMAN action.
+ *
+ * Threat model in one line: the session's own tools can read/write its
+ * directory and can reach `127.0.0.1`, so a grant may not be a plain POST. A
+ * POST needs `X-Celestea-Grant-Confirm`, that token only comes from the
+ * same-origin-only token endpoint, and it is bound to `(session, cap,
+ * scope_hash)`, lives 60s and burns on first use (§5.5).
+ *
+ * Every grant / revoke / refusal is audited twice (§4.4): the local
+ * append-only `grants-audit.jsonl` is authoritative, the platform channel is
+ * best-effort and its failures are recorded locally as `platform_audit_failed`.
+ */
+import type { Hono } from "hono";
+import type { RouteTable } from "../routes.js";
+import { type EffectiveGrants } from "../runtime/engine-grants.js";
+import { type GrantsServices } from "../store/grants-service.js";
+import { type Deps } from "./common.js";
+export declare function registerGrants(app: Hono, deps: Deps, table: RouteTable): string[];
+export type { EffectiveGrants, GrantsServices };

package/dist/handlers/grants.js

@@ -0,0 +1,267 @@
+/**
+ * The four grant endpoints (W516 §6): read the session's grants, grant one, a
+ * revoke, and the one-shot confirm token that makes a grant a HUMAN action.
+ *
+ * Threat model in one line: the session's own tools can read/write its
+ * directory and can reach `127.0.0.1`, so a grant may not be a plain POST. A
+ * POST needs `X-Celestea-Grant-Confirm`, that token only comes from the
+ * same-origin-only token endpoint, and it is bound to `(session, cap,
+ * scope_hash)`, lives 60s and burns on first use (§5.5).
+ *
+ * Every grant / revoke / refusal is audited twice (§4.4): the local
+ * append-only `grants-audit.jsonl` is authoritative, the platform channel is
+ * best-effort and its failures are recorded locally as `platform_audit_failed`.
+ */
+import { effectiveGrantsOf, netHostsEffective, unsandboxedAvailable } from "../runtime/engine-grants.js";
+import { isOfferedGrantCap, MAX_TTL_SEC, emptyGrantsFile, newGrantId, readGrantsFile, writeGrantsFile } from "../store/grants.js";
+import { CONFIRM_HEADER, SEC_FETCH_MODE, SEC_FETCH_SITE, ORIGIN_HEADER } from "../store/grants-tokens.js";
+import { nowSec } from "../store/grants-service.js";
+import { errText } from "../store/result.js";
+import { entryJson, effectiveJson, parseGrantRequest, GRANT_ACTOR } from "./grants-shape.js";
+import { failJson, readJsonBody, strField, storeFail } from "./common.js";
+const NOT_SAME_ORIGIN_TOO = "grant confirmation is not available over this transport";
+const CONFIRM_REQUIRED = "grant confirmation required";
+/**
+ * W757: the readable half of `net_hosts_effective: false`. `net_hosts` entries
+ * are UNIONed into the allow side and only ever count while the env policy is
+ * active, so on a deployment that sets neither `CELESTEA_HTTP_ALLOW` nor
+ * `CELESTEA_HTTP_DENY` such a grant changes nothing — and must not be read as
+ * "this session is limited to those sites".
+ */
+const NET_HOSTS_INEFFECTIVE = "net_hosts_ineffective: 当前部署未设置站点策略（CELESTEA_HTTP_ALLOW / CELESTEA_HTTP_DENY 均未设置），列出的站点不会改变可访问范围 —— 该授权不生效";
+/**
+ * W819-8: the readable half of "tool_extra is reserved". The cap has no tool
+ * exposure point yet, so a stored entry is echoed but changes nothing; it is
+ * also no longer offered (only revocable).
+ */
+const TOOL_EXTRA_INEFFECTIVE = "tool_extra_ineffective: tool_extra 预留给未来的 browser/net 工具，当前没有任何工具暴露面消费它 —— 该授权不生效（已停止新授，可撤销）";
+/** GET /api/sessions/{id}/grants (§6.1). */
+function registerList(app, deps, table) {
+    const route = table.get("get_session_grants");
+    app.on(route.method, route.honoPath, (c) => {
+        const resolved = deps.sessions.require(c.req.param("id") ?? "");
+        if (!resolved.ok)
+            return storeFail(c, resolved);
+        const seconds = nowSec(deps.grants);
+        const read = readGrantsFile(resolved.value.dir, resolved.value.id);
+        const effective = effectiveGrantsOf(resolved.value.dir, resolved.value.id, deps.grants.env, seconds);
+        const grants = (read.file?.grants ?? []).map((grant) => entryJson(grant, seconds));
+        // W757 (§6.1): report the DEPLOYMENT fact as well as the readable warning —
+        // the verdict comes from the very policy the engine mounts its tools with.
+        const netHosts = netHostsEffective(deps.grants.env, effective.grants);
+        const warnings = [
+            ...effective.warnings,
+            ...(netHosts ? [] : [NET_HOSTS_INEFFECTIVE]),
+            ...(effective.grants.toolExtra.length > 0 ? [TOOL_EXTRA_INEFFECTIVE] : []),
+        ];
+        return c.json({
+            ok: true,
+            session: resolved.value.id,
+            grants,
+            effective: effectiveJson(effective.grants),
+            max_ttl_sec: MAX_TTL_SEC,
+            unsandboxed_available: unsandboxedAvailable(deps.grants.env),
+            net_hosts_effective: netHosts,
+            ...(warnings.length === 0 ? {} : { warnings }),
+        });
+    });
+    return route.id;
+}
+/** POST /api/sessions/{id}/grants (§6.2) — replace-by-cap, one cap one set. */
+function registerCreate(app, deps, table) {
+    const route = table.get("post_session_grants");
+    app.on(route.method, route.honoPath, async (c) => {
+        const resolved = deps.sessions.require(c.req.param("id") ?? "");
+        if (!resolved.ok)
+            return storeFail(c, resolved);
+        const sessionId = resolved.value.id;
+        const services = deps.grants;
+        const limit = services.limits.allow(sessionId);
+        if (!limit.ok)
+            return failJson(c, limit.status, limitMessage(limit), { retry_after: limit.retryAfterSec });
+        const refusal = { deps, sessionId, reason: "" };
+        const read = await readJsonBody(c);
+        if (!read.ok)
+            return denied({ ...refusal, reason: "readable JSON body required" }, read.response);
+        const request = parseGrantRequest(c, read.body, services.env);
+        if (!request.ok)
+            return denied({ ...refusal, reason: request.reason }, request.response);
+        refusal.cap = request.value.cap;
+        const token = c.req.header(CONFIRM_HEADER) ?? "";
+        if (token === "")
+            return denied({ ...refusal, reason: CONFIRM_REQUIRED }, failJson(c, 403, CONFIRM_REQUIRED));
+        const verdict = services.tokens.consume(sessionId, request.value.cap, request.value.scopeHash, token);
+        if (verdict === "invalid")
+            return denied({ ...refusal, reason: CONFIRM_REQUIRED }, failJson(c, 403, CONFIRM_REQUIRED));
+        if (verdict === "used") {
+            return denied({ ...refusal, reason: "confirmation token already used" }, failJson(c, 409, "confirmation token already used"));
+        }
+        return persistGrant(c, deps, resolved.value.dir, sessionId, request.value);
+    });
+    return route.id;
+}
+/** §6.2 `429` / `409` bodies carry the remaining seconds. */
+function limitMessage(limit) {
+    if (limit.status === 429)
+        return `too many grant requests; retry in ${limit.retryAfterSec}s`;
+    return `a grant request was just denied; retry in ${limit.retryAfterSec}s`;
+}
+/** Store the grant, bump the session's epoch, audit, answer (§6.2). */
+function persistGrant(c, deps, dir, sessionId, request) {
+    const services = deps.grants;
+    const seconds = nowSec(services);
+    const existing = readGrantsFile(dir, sessionId);
+    if (existing.exists && existing.file === undefined) {
+        services.audit.write({ session: sessionId, event: "grants_unreadable", reason: existing.error ?? "unreadable" });
+    }
+    const base = existing.file ?? emptyGrantsFile(sessionId, seconds);
+    const record = {
+        id: newGrantId(),
+        cap: request.cap,
+        scope: request.scope,
+        granted_at: seconds,
+        granted_by: GRANT_ACTOR,
+        expires_at: request.ttlSec === 0 ? null : seconds + request.ttlSec,
+        uses_left: request.usesLeft,
+        note: request.note,
+    };
+    const file = { version: 1, session: sessionId, updated_at: seconds, grants: upsert(base, record) };
+    try {
+        writeGrantsFile(dir, file, { env: services.env, now: seconds });
+    }
+    catch (e) {
+        return failJson(c, 500, `cannot persist grants: ${errText(e)}`);
+    }
+    deps.runtime.invalidateSession?.(sessionId);
+    const effective = effectiveGrantsOf(dir, sessionId, services.env, seconds);
+    services.audit.write({
+        session: sessionId,
+        event: "grant",
+        grant_id: record.id,
+        cap: record.cap,
+        scope: record.scope,
+        actor: GRANT_ACTOR,
+        expires_at: record.expires_at,
+        uses_left: record.uses_left,
+        effective_after: effectiveJson(effective.grants),
+    });
+    services.limits.recordSuccess(sessionId);
+    return c.json({ ok: true, grant: entryJson(record, seconds), effective: effectiveJson(effective.grants) });
+}
+/** §6.2: one cap holds exactly one live entry — replace, never stack. */
+function upsert(file, record) {
+    return [...file.grants.filter((grant) => grant.cap !== record.cap), record];
+}
+/** DELETE /api/sessions/{id}/grants (§6.3) — no token: revoking is safe. */
+function registerRevoke(app, deps, table) {
+    const route = table.get("delete_session_grants");
+    app.on(route.method, route.honoPath, async (c) => {
+        const resolved = deps.sessions.require(c.req.param("id") ?? "");
+        if (!resolved.ok)
+            return storeFail(c, resolved);
+        const read = await readJsonBody(c, false);
+        if (!read.ok)
+            return read.response;
+        const cap = strField(c, read.body, "cap");
+        if (!cap.ok)
+            return cap.response;
+        const grantId = strField(c, read.body, "grant_id");
+        if (!grantId.ok)
+            return grantId.response;
+        return revoke(c, deps, { dir: resolved.value.dir, sessionId: resolved.value.id, cap: cap.value, grantId: grantId.value });
+    });
+    return route.id;
+}
+/** Remove the matching entries (all of them when nothing is named). */
+function revoke(c, deps, target) {
+    const { dir, sessionId, cap, grantId } = target;
+    const services = deps.grants;
+    const seconds = nowSec(services);
+    const read = readGrantsFile(dir, sessionId);
+    if (read.exists && read.file === undefined) {
+        services.audit.write({ session: sessionId, event: "grants_unreadable", reason: read.error ?? "unreadable" });
+    }
+    const entries = read.file?.grants ?? [];
+    const matches = (grant) => (cap === undefined || grant.cap === cap) && (grantId === undefined || grant.id === grantId);
+    const revoked = entries.filter(matches);
+    const file = { version: 1, session: sessionId, updated_at: seconds, grants: entries.filter((g) => !matches(g)) };
+    if (revoked.length > 0) {
+        try {
+            writeGrantsFile(dir, file, { env: services.env, now: seconds });
+        }
+        catch (e) {
+            return failJson(c, 500, `cannot persist grants: ${errText(e)}`);
+        }
+        deps.runtime.invalidateSession?.(sessionId);
+    }
+    const effective = effectiveGrantsOf(dir, sessionId, services.env, seconds);
+    for (const grant of revoked) {
+        services.audit.write({ session: sessionId, event: "revoke", grant_id: grant.id, cap: grant.cap, actor: GRANT_ACTOR, effective_after: effectiveJson(effective.grants) });
+    }
+    return c.json({ ok: true, revoked: revoked.map((grant) => grant.id), effective: effectiveJson(effective.grants) });
+}
+/** GET /api/sessions/{id}/grants/confirm-token (§6.4) — same-origin only. */
+function registerConfirmToken(app, deps, table) {
+    const route = table.get("get_session_grants_confirm_token");
+    app.on(route.method, route.honoPath, (c) => {
+        const resolved = deps.sessions.require(c.req.param("id") ?? "");
+        if (!resolved.ok)
+            return storeFail(c, resolved);
+        if (!hasSameOriginEvidence(c))
+            return failJson(c, 403, NOT_SAME_ORIGIN_TOO);
+        const cap = c.req.query("cap") ?? "";
+        const allowed = isOfferedGrantCap(cap);
+        if (!allowed || (cap === "unsandboxed" && !unsandboxedAvailable(deps.grants.env)))
+            return failJson(c, 400, `invalid cap '${cap}'`);
+        const hash = c.req.query("scope_hash") ?? "";
+        if (!/^[0-9a-f]{64}$/.test(hash))
+            return failJson(c, 400, "scope_hash must be a 64-char sha256 hex string");
+        const issued = deps.grants.tokens.issue(resolved.value.id, cap, hash);
+        return c.json({ ok: true, token: issued.token, expires_at: issued.expiresAt });
+    });
+    return route.id;
+}
+/**
+ * §5.5.2: a browser navigation/XHR from our own origin, and nothing a session
+ * tool can forge. `Sec-Fetch-Site: same-origin` is the strong evidence; the
+ * CORS fallback additionally requires an Origin that matches Host.
+ */
+function hasSameOriginEvidence(c) {
+    if ((c.req.header(SEC_FETCH_SITE) ?? "").toLowerCase() === "same-origin")
+        return true;
+    if ((c.req.header(SEC_FETCH_MODE) ?? "").toLowerCase() !== "cors")
+        return false;
+    const origin = c.req.header(ORIGIN_HEADER) ?? "";
+    const host = c.req.header("host") ?? "";
+    if (origin === "")
+        return true;
+    try {
+        return new URL(origin).host === host;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A refused grant counts toward the 3-strikes cooldown (§5.5.5) and is audited
+ * (§4.4). The audited reason is the SAME sanitized text the client got: a
+ * rejected value never reaches the audit file either (§5.4).
+ */
+function denied(ctx, response) {
+    ctx.deps.grants.limits.recordDenial(ctx.sessionId);
+    ctx.deps.grants.audit.write({
+        session: ctx.sessionId,
+        event: "deny",
+        ...(ctx.cap === undefined ? {} : { cap: ctx.cap }),
+        reason: ctx.reason,
+    });
+    return response;
+}
+export function registerGrants(app, deps, table) {
+    return [
+        registerList(app, deps, table),
+        registerCreate(app, deps, table),
+        registerRevoke(app, deps, table),
+        registerConfirmToken(app, deps, table),
+    ];
+}

package/dist/handlers/health.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Health / status / tools — `src/main.rs:860-869`, `src/api.rs:40-83`.
+ *
+ * All three are always 200 with no error branch. `bind` is the ACTUAL
+ * listening address (`host:port`): `startStudioServer` writes it back once the
+ * socket is up, so it follows `--bind`/`--port` (and reports the real port for
+ * `--port 0`) instead of repeating `DEFAULT_BIND`. When the app is composed
+ * without a server (tests), it stays `DEFAULT_BIND`.
+ *
+ * W513: `GET /api/status` reads ONE session's trackers — `?session=<id>`, or the
+ * active session when the query is absent — and reports that session's `busy`
+ * slot alongside the (unchanged) 7 statusline fields.
+ *
+ * W729: `/api/status` adds `mode` (the queried session's mode) and
+ * `/api/health` advertises `capabilities.session_mode = true` (P0: the mode is
+ * fixed at creation, so the capability is a read-only announcement).
+ *
+ * W516: `/api/health` advertises `capabilities.grants = true` (the frontend
+ * hides the permission panel when it is not exactly `true`, so the retired
+ * backend cannot show a panel that does nothing), and `/api/status` adds
+ * `grants_active` — the CAP NAMES in force for that session, never the paths
+ * (an operator can see which session is widened without leaking a filesystem
+ * layout into a status poll).
+ *
+ * W791 (P1): `GET /api/tools` takes `?session=` (absent = the focused session)
+ * and `/api/health` advertises `capabilities.session_mode_tools = true`.
+ *
+ * W785 (E-P1, capability 3 ②): `/api/status` adds `cost` — the session's
+ * engine-side cost estimate read from the append-only usage ledger (§3.2.4). The
+ * key is a PURE ADDITION and is present ONLY when the adapter has a ledger, so a
+ * host with the ledger switched off answers exactly the pre-W785 body and an old
+ * client never receives a `null` it would have to interpret.
+ */
+import type { Hono } from "hono";
+import type { RouteTable } from "../routes.js";
+import { type Deps } from "./common.js";
+export declare function registerHealth(app: Hono, deps: Deps, table: RouteTable): string[];

package/dist/handlers/health.js

@@ -0,0 +1,139 @@
+/**
+ * Health / status / tools — `src/main.rs:860-869`, `src/api.rs:40-83`.
+ *
+ * All three are always 200 with no error branch. `bind` is the ACTUAL
+ * listening address (`host:port`): `startStudioServer` writes it back once the
+ * socket is up, so it follows `--bind`/`--port` (and reports the real port for
+ * `--port 0`) instead of repeating `DEFAULT_BIND`. When the app is composed
+ * without a server (tests), it stays `DEFAULT_BIND`.
+ *
+ * W513: `GET /api/status` reads ONE session's trackers — `?session=<id>`, or the
+ * active session when the query is absent — and reports that session's `busy`
+ * slot alongside the (unchanged) 7 statusline fields.
+ *
+ * W729: `/api/status` adds `mode` (the queried session's mode) and
+ * `/api/health` advertises `capabilities.session_mode = true` (P0: the mode is
+ * fixed at creation, so the capability is a read-only announcement).
+ *
+ * W516: `/api/health` advertises `capabilities.grants = true` (the frontend
+ * hides the permission panel when it is not exactly `true`, so the retired
+ * backend cannot show a panel that does nothing), and `/api/status` adds
+ * `grants_active` — the CAP NAMES in force for that session, never the paths
+ * (an operator can see which session is widened without leaking a filesystem
+ * layout into a status poll).
+ *
+ * W791 (P1): `GET /api/tools` takes `?session=` (absent = the focused session)
+ * and `/api/health` advertises `capabilities.session_mode_tools = true`.
+ *
+ * W785 (E-P1, capability 3 ②): `/api/status` adds `cost` — the session's
+ * engine-side cost estimate read from the append-only usage ledger (§3.2.4). The
+ * key is a PURE ADDITION and is present ONLY when the adapter has a ledger, so a
+ * host with the ledger switched off answers exactly the pre-W785 body and an old
+ * client never receives a `null` it would have to interpret.
+ */
+import { resolveStudioVersion } from "../version.js";
+import { emptyRecoveryView } from "../runtime/recovery-view.js";
+import { activeSession, modeOfSession, sessionModelCovered } from "./common.js";
+import { baseUrlOf } from "./config-shape.js";
+import { effectiveGrantsOf, grantsActiveCaps } from "../runtime/engine-grants.js";
+import { nowSec } from "../store/grants-service.js";
+export function registerHealth(app, deps, table) {
+    const health = table.get("get_health");
+    app.on(health.method, health.honoPath, async (c) => {
+        // W887 + H: git-derived in a checkout, the package version once installed.
+        const version = await resolveStudioVersion();
+        return c.json({
+            ok: true,
+            name: deps.config.name,
+            model: deps.runtime.profile().model,
+            base_url: baseUrlOf(deps),
+            bind: deps.config.bind,
+            // W887: the SAME derived version the frontend shows (PURE ADDITION; a client
+            // that does not see the key degrades to no version line).
+            version,
+            // W725: `context: true` gates the context-ring entry point; a client
+            // that does not see exactly `true` degrades to no context viewer.
+            // W729: `session_mode: true` gates the (P1) mode selector; a client that
+            // does not see exactly `true` must not offer to set a session mode.
+            // W791 (P1, U8): `session_mode_tools: true` additionally promises that the
+            // mode is OBSERVABLE in the tool face (`GET /api/tools?session=`) and that
+            // the mode switch endpoint exists — a legacy-backend client that sees only
+            // `session_mode` must not call `POST /api/sessions/{id}/mode` (TS-only).
+            // W804 (multimodal P0 section 7.1): PURE ADDITION — a client that does not
+            // see exactly true degrades to "no attachment entry points".
+            capabilities: { grants: true, context: true, session_mode: true, session_mode_tools: true, multimodal: true },
+        });
+    });
+    const status = table.get("get_status");
+    app.on(status.method, status.honoPath, (c) => {
+        const asked = c.req.query("session");
+        const session = asked === undefined || asked === "" ? activeSession(deps) : asked;
+        const line = deps.runtime.statusline(session);
+        return c.json({
+            ...line,
+            session,
+            // W729: the mode of the QUERIED session (absent = standard, K8).
+            mode: modeOfSession(deps, session),
+            // W870: whether `model` above is THIS session's own override rather than
+            // the global default (the picker's 「本会话已固定模型」 line reads it).
+            // A PURE ADDITION: a client that does not see the key shows no such line.
+            model_covered: sessionModelCovered(deps, session),
+            busy: deps.runtime.isBusy(session),
+            grants_active: activeGrantCaps(deps, session),
+            ...costField(deps, session),
+            // E §1.3 P1 ② (W787): the session's checkpoint view. A PURE ADDITION, always
+            // present (an adapter without checkpointing answers the empty block), so a
+            // client can rely on the key existing without inventing a default.
+            recovery: recoveryBlockOf(deps, session),
+            // E §4.2.3 #4 (W785): `model` stays the CONFIGURED value; these two are
+            // the only place a downgrade shows. Pure additions, always present.
+            effective_model: fallbackView(deps, session)?.effective_model ?? line.model,
+            fallback: fallbackView(deps, session) ?? {
+                active: false,
+                chain: [],
+                effective_model: null,
+                last_reason: null,
+                targets: [],
+                problems: [],
+            },
+        });
+    });
+    // W791 (P1, §5.2 #5 / S2 / M9): `?session=` answers for THAT session's own
+    // generation — the very registry its Context provides, so an `execution`
+    // session reports its folded face. Absent/blank = the FOCUSED session (the
+    // active one); with nothing active it is the detached default generation,
+    // which is the pre-P1 answer byte for byte.
+    const tools = table.get("get_tools");
+    app.on(tools.method, tools.honoPath, (c) => {
+        const asked = c.req.query("session");
+        const focus = asked === undefined || asked === "" ? activeSession(deps) : asked;
+        if (focus === null)
+            return c.json({ tools: deps.runtime.tools() });
+        return c.json({ tools: deps.runtime.sessionTools?.(focus) ?? deps.runtime.tools() });
+    });
+    return [health.id, status.id, tools.id];
+}
+/** E §4.2.3 #4 (W785): the fallback view of this session (null = not armed). */
+function fallbackView(deps, session) {
+    return deps.runtime.fallbackView?.(session) ?? null;
+}
+/** E §1.3 P1 ②: the `recovery` block of the queried session (never a new endpoint). */
+function recoveryBlockOf(deps, session) {
+    return { ...(deps.runtime.recoveryView?.(session) ?? emptyRecoveryView(session)) };
+}
+/**
+ * W785: the optional `cost` key (see the header). `{}` = no ledger / no estimate,
+ * which keeps the field truly optional instead of a `cost: null` placeholder.
+ */
+function costField(deps, session) {
+    const cost = deps.runtime.costBlock?.(session);
+    return cost === undefined || cost === null ? {} : { cost };
+}
+/** Cap names in force for the session (never paths) — §5.7. */
+function activeGrantCaps(deps, session) {
+    const resolved = session === null ? null : deps.sessions.resolve(session);
+    if (resolved === null || !resolved.ok)
+        return [];
+    const dir = resolved.value.dir;
+    return grantsActiveCaps(effectiveGrantsOf(dir, resolved.value.id, deps.grants.env, nowSec(deps.grants)).grants);
+}

package/dist/handlers/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Handler registry — the ONLY place that knows every endpoint group.
+ *
+ * Each `registerXxx` returns the contract ids it bound, and `app.ts` asserts
+ * the union equals the frozen 47. A route can therefore never be silently
+ * dropped: adding an endpoint to `contracts/endpoints.json` without a handler
+ * fails at startup with the missing id.
+ *
+ * Module map:
+ *   common.ts        error/body/field helpers shared by every handler
+ *   config-shape.ts  the /api/config body assembled from live stores
+ *   health.ts        GET  /api/health | /api/status | /api/tools
+ *   dialog.ts        GET  /api/events (SSE) | POST /api/turn | /api/cancel | /api/clear
+ *   config.ts        GET+POST /api/config
+ *   sessions.ts      GET+POST /api/sessions | {id}/messages | {id}/activate | {id}/context
+ *   context-shape.ts the context snapshot body + the 20k-per-entry wire guard
+ *   session-move.ts  {id}/rename | {id}/branch | {id}/compact | archive | unarchive | batch-*
+ *   workspaces.ts    /api/workspaces (+rename/delete/batch-delete)
+ *   fs.ts            GET /api/fs/browse | GET /api/fs/list
+ *   exec.ts          G2: POST /api/exec (immediate shell, permission-gated)
+ *   providers.ts     /api/providers (+delete/test/models fetch/default)
+ *   prompts.ts       /api/prompts (+delete/default)
+ *   worker.ts        /api/worker/spawn | send | status
+ *   grants.ts        GET+POST+DELETE /api/sessions/{id}/grants | grants/confirm-token
+ *   questions.ts     W783: GET /api/questions | POST /api/questions/{id}/answer
+ *   usage.ts         W785: GET /api/usage/ledger (the ledger's aggregate view)
+ *   permissions.ts   W9: /api/permissions/presets (+{id}) | /api/sessions/{id}/permission
+ *   session-tools.ts W860: GET+PUT /api/sessions/{id}/tools (the session's disabled list)
+ *   session-model.ts W870: PUT /api/sessions/{id}/model (the session-level model switch)
+ *   plugins.ts       W860: GET /api/plugins (the host startup plugin inventory)
+ *   auth.ts          W767: GET /login | POST /auth/login | GET /auth/check
+ *
+ * W725: the context endpoint (44th) lives in sessions.ts; its shaping is in
+ * context-shape.ts.
+ */
+import type { Hono } from "hono";
+import type { RouteTable } from "../routes.js";
+import type { Deps } from "./common.js";
+export declare function registerHandlers(app: Hono, deps: Deps, table: RouteTable): string[];
+export type { Deps } from "./common.js";