@celestea/studio 2.7.1

package/dist/handlers/questions.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The two user-question endpoints (W783 §9 item 7).
+ *
+ *   GET  /api/questions                  → every question still answerable
+ *   POST /api/questions/{id}/answer      → the human's answer
+ *
+ * WHY THE ANSWER IS NOT `POST /api/turn`: while the model's `ask_user_question`
+ * call is parked, the session's turn slot is occupied. A message posted to
+ * `/api/turn` is therefore accepted as STEERING, and steering is only drained at
+ * a step boundary — a boundary the parked call never reaches (§2.2). Sending the
+ * answer here instead resolves the pending promise the tool is awaiting, so the
+ * tool wakes with an ordinary result and the turn continues (§4.2).
+ *
+ * The `GET` exists for §7 recovery: the `question` SSE frame can be missed (a
+ * reload, a dropped connection), so the list is the authoritative rebuild source.
+ * Every timing field is judged at READ time, so the client never trusts its own
+ * clock and a long-disconnected tab cannot resurrect an expired question.
+ */
+import type { Hono } from "hono";
+import type { RouteTable } from "../routes.js";
+import { type Deps } from "./common.js";
+/** The two question routes, in contract order. */
+export declare function registerQuestions(app: Hono, deps: Deps, table: RouteTable): string[];

package/dist/handlers/questions.js

@@ -0,0 +1,115 @@
+/**
+ * The two user-question endpoints (W783 §9 item 7).
+ *
+ *   GET  /api/questions                  → every question still answerable
+ *   POST /api/questions/{id}/answer      → the human's answer
+ *
+ * WHY THE ANSWER IS NOT `POST /api/turn`: while the model's `ask_user_question`
+ * call is parked, the session's turn slot is occupied. A message posted to
+ * `/api/turn` is therefore accepted as STEERING, and steering is only drained at
+ * a step boundary — a boundary the parked call never reaches (§2.2). Sending the
+ * answer here instead resolves the pending promise the tool is awaiting, so the
+ * tool wakes with an ordinary result and the turn continues (§4.2).
+ *
+ * The `GET` exists for §7 recovery: the `question` SSE frame can be missed (a
+ * reload, a dropped connection), so the list is the authoritative rebuild source.
+ * Every timing field is judged at READ time, so the client never trusts its own
+ * clock and a long-disconnected tab cannot resurrect an expired question.
+ */
+import { errText } from "../store/result.js";
+import { failJson, readJsonBody, strField } from "./common.js";
+/** Read `answers`: every entry needs a string `id`, a string[] `selected` (optional `custom`). */
+function readAnswers(body) {
+    const raw = body["answers"];
+    if (!Array.isArray(raw))
+        return { ok: false, error: "field 'answers' must be an array" };
+    const out = [];
+    for (const item of raw) {
+        const parsed = readAnswer(item);
+        if (typeof parsed === "string")
+            return { ok: false, error: parsed };
+        out.push(parsed);
+    }
+    return { ok: true, answers: out };
+}
+/** One answer entry, or the reason it is malformed. */
+function readAnswer(item) {
+    if (typeof item !== "object" || item === null || Array.isArray(item))
+        return "each answer must be an object {id,selected[],custom?}";
+    const record = item;
+    if (typeof record["id"] !== "string")
+        return "each answer needs a string 'id'";
+    const selected = record["selected"];
+    if (!Array.isArray(selected) || selected.some((value) => typeof value !== "string")) {
+        return `answer '${record["id"]}' needs 'selected' as an array of strings (option LABELS, never indices)`;
+    }
+    const custom = record["custom"];
+    if (custom !== undefined && custom !== null && typeof custom !== "string") {
+        return `answer '${record["id"]}' has a non-string 'custom'`;
+    }
+    const answer = { id: record["id"], selected: selected };
+    if (typeof custom === "string")
+        answer.custom = custom;
+    return answer;
+}
+/** POST /api/questions/{id}/answer — resolve the parked tool call (§4.2). */
+function registerAnswer(app, deps, table) {
+    const route = table.get("post_question_answer");
+    app.on(route.method, route.honoPath, async (c) => {
+        const requestId = c.req.param("id") ?? "";
+        const read = await readJsonBody(c);
+        if (!read.ok)
+            return read.response;
+        const answers = readAnswers(read.body);
+        if (!answers.ok)
+            return failJson(c, 422, answers.error);
+        // Optional guard: a stale tab must not answer another session's question by
+        // guessing an id (the id alone is not an authorization).
+        const guard = strField(c, read.body, "session");
+        if (!guard.ok)
+            return guard.response;
+        const answer = deps.runtime.answerQuestion;
+        if (answer === undefined)
+            return failJson(c, 404, `unknown or already settled question '${requestId}'`);
+        const outcome = answer.call(deps.runtime, requestId, answers.answers, guard.value);
+        if (!outcome.ok)
+            return refuse(c, requestId, outcome.reason);
+        // `timed_out:false` is a fact, not a placeholder: a REAL answer arrived, so
+        // the §6.2 race is resolved in the user's favour (whoever arrives first wins).
+        return c.json({ ok: true, id: requestId, session: outcome.session, timed_out: false });
+    });
+    return route.id;
+}
+/** The refusal status of one answer attempt (never a silent 200). */
+function refuse(c, requestId, reason) {
+    if (reason === "mismatch")
+        return failJson(c, 409, `question '${requestId}' was asked by another session`);
+    if (reason === "timed_out" || reason === "settled") {
+        return failJson(c, 409, `question '${requestId}' already settled`, { timed_out: reason === "timed_out" });
+    }
+    return failJson(c, 404, `unknown or already settled question '${requestId}'`);
+}
+/** GET /api/questions — the §7 recovery list (pending questions only). */
+function registerList(app, deps, table) {
+    const route = table.get("get_questions");
+    app.on(route.method, route.honoPath, (c) => {
+        const asked = (c.req.query("session") ?? "").trim();
+        const pending = deps.runtime.pendingQuestions;
+        if (pending === undefined)
+            return c.json({ ok: true, questions: [] });
+        try {
+            // An ABSENT filter is not the same as filtering by `null`: the latter would
+            // return only the detached generation's questions. Passing `undefined`
+            // keeps the whole table, which is what a reconnecting client needs.
+            return c.json({ ok: true, questions: pending.call(deps.runtime, asked === "" ? undefined : asked) });
+        }
+        catch (e) {
+            return failJson(c, 500, errText(e));
+        }
+    });
+    return route.id;
+}
+/** The two question routes, in contract order. */
+export function registerQuestions(app, deps, table) {
+    return [registerList(app, deps, table), registerAnswer(app, deps, table)];
+}

package/dist/handlers/session-model.d.ts

@@ -0,0 +1,38 @@
+/**
+ * W870: the session-level MODEL switch endpoint (1).
+ *
+ *   PUT /api/sessions/{id}/model -> rewrite `<session dir>/session.json.model`
+ *                                   (key-preserving; `""` CLEARS the override)
+ *                                   and invalidate THIS session so its next
+ *                                   turn recomposes on the new model.
+ *
+ * Why the endpoint exists (the user-visible bug it fixes): the statusline badge
+ * is `GET /api/status?session=<focus>` polled every 2s, and that answer's `model`
+ * is the SESSION INSTANCE's profile — global base + `session.json.model`
+ * (`runtime/session-compose.ts` `profileFor`). The W750 picker only wrote the
+ * GLOBAL default (`POST /api/config`), so for a session carrying an override the
+ * optimistic badge was bounced back by the next poll (「切换模型后几秒又弹回原状」).
+ *
+ * Product semantic (W870, deliberate): the statusline's picker switches the
+ * FOCUSED SESSION's model — it sits on that session's statusline, so that is what
+ * the user means. The GLOBAL default stays `POST /api/config` and belongs to the
+ * settings page. This endpoint is the session-scoped half.
+ *
+ * Disciplines, all inherited from the endpoints next to it:
+ *   - the write path is W729's `session.json` writer (title / mode / prompt are
+ *     kept), so a switch is the SAME operation `POST /api/sessions {model}` performs;
+ *   - the busy guard is `/compact` and `POST /api/sessions/{id}/mode`'s: 409 while
+ *     THIS session's turn runs, because a half-applied switch (this turn on the old
+ *     model, the next on the new one) is exactly the silent surprise W870 removes;
+ *   - the effect is W516's `invalidateSession`, the same next-turn-boundary hook
+ *     `PUT /api/sessions/{id}/tools` and `PUT /api/sessions/{id}/permission` use.
+ *     Sessions other than this one are untouched.
+ *
+ * The response echoes the RESOLVED value (`model` = override ?? global default)
+ * plus `covered` / `effective.source`, so the client never has to guess whether an
+ * override is in force — that is what the picker's 「本会话已固定模型」 hint reads.
+ */
+import type { Hono } from "hono";
+import type { RouteTable } from "../routes.js";
+import { type Deps } from "./common.js";
+export declare function registerSessionModel(app: Hono, deps: Deps, table: RouteTable): string;

package/dist/handlers/session-model.js

@@ -0,0 +1,105 @@
+/**
+ * W870: the session-level MODEL switch endpoint (1).
+ *
+ *   PUT /api/sessions/{id}/model -> rewrite `<session dir>/session.json.model`
+ *                                   (key-preserving; `""` CLEARS the override)
+ *                                   and invalidate THIS session so its next
+ *                                   turn recomposes on the new model.
+ *
+ * Why the endpoint exists (the user-visible bug it fixes): the statusline badge
+ * is `GET /api/status?session=<focus>` polled every 2s, and that answer's `model`
+ * is the SESSION INSTANCE's profile — global base + `session.json.model`
+ * (`runtime/session-compose.ts` `profileFor`). The W750 picker only wrote the
+ * GLOBAL default (`POST /api/config`), so for a session carrying an override the
+ * optimistic badge was bounced back by the next poll (「切换模型后几秒又弹回原状」).
+ *
+ * Product semantic (W870, deliberate): the statusline's picker switches the
+ * FOCUSED SESSION's model — it sits on that session's statusline, so that is what
+ * the user means. The GLOBAL default stays `POST /api/config` and belongs to the
+ * settings page. This endpoint is the session-scoped half.
+ *
+ * Disciplines, all inherited from the endpoints next to it:
+ *   - the write path is W729's `session.json` writer (title / mode / prompt are
+ *     kept), so a switch is the SAME operation `POST /api/sessions {model}` performs;
+ *   - the busy guard is `/compact` and `POST /api/sessions/{id}/mode`'s: 409 while
+ *     THIS session's turn runs, because a half-applied switch (this turn on the old
+ *     model, the next on the new one) is exactly the silent surprise W870 removes;
+ *   - the effect is W516's `invalidateSession`, the same next-turn-boundary hook
+ *     `PUT /api/sessions/{id}/tools` and `PUT /api/sessions/{id}/permission` use.
+ *     Sessions other than this one are untouched.
+ *
+ * The response echoes the RESOLVED value (`model` = override ?? global default)
+ * plus `covered` / `effective.source`, so the client never has to guess whether an
+ * override is in force — that is what the picker's 「本会话已固定模型」 hint reads.
+ */
+import { readSessionMeta, writeSessionMeta } from "../store/session-meta.js";
+import { errText } from "../store/result.js";
+import { validateModelName } from "../store/validate.js";
+import { failJson, readJsonBody, strField, storeFail } from "./common.js";
+/** The frozen response body (one shape, one construction).
+ *
+ * `model` is the model this session will run next turn; `covered` says whether
+ * that comes from the session's OWN `session.json.model` (`effective.source`
+ * `"session"`) or from the global default (`"global"`, i.e. no override).
+ */
+function sessionModelBody(deps, session, dir) {
+    const override = (readSessionMeta(dir)?.model ?? "").trim();
+    const covered = override !== "";
+    const base = deps.runtime.profile().model;
+    return {
+        ok: true,
+        session,
+        model: covered ? override : base,
+        covered,
+        effective: { model: covered ? override : base, base_model: base, source: covered ? "session" : "global", next_turn: true },
+    };
+}
+export function registerSessionModel(app, deps, table) {
+    const route = table.get("put_session_model");
+    app.on(route.method, route.honoPath, async (c) => {
+        // W815-5: resolve to the CANONICAL id BEFORE the busy guard (`require` trims
+        // and sanitizes the raw path segment, so a `%2F`-encoded id would otherwise
+        // never match the canonical instance and the guard could be bypassed).
+        const resolved = deps.sessions.require(c.req.param("id") ?? "");
+        if (!resolved.ok)
+            return storeFail(c, resolved);
+        const session = resolved.value.id;
+        if (deps.runtime.isBusy(session))
+            return failJson(c, 409, "turn 进行中，无法切换模型");
+        const read = await readJsonBody(c);
+        if (!read.ok)
+            return read.response;
+        const model = strField(c, read.body, "model");
+        if (!model.ok)
+            return model.response;
+        if (model.value === undefined)
+            return failJson(c, 422, "field 'model' must be a string");
+        const asked = model.value.trim();
+        // `""` (or whitespace) is the documented CLEAR: the session falls back to the
+        // global default. Anything else has to be a legal model id.
+        if (asked !== "") {
+            const bad = validateModelName(asked);
+            if (bad !== null)
+                return failJson(c, 400, bad);
+        }
+        try {
+            // W729 write path, key-preserving: title / mode / prompt survive the switch.
+            // An empty model DROPS the key (K8: absent = no override) instead of writing
+            // `"model": ""` — the composer's `sessionModel` hook reads the absent key as
+            // 「no override」 exactly like the empty string.
+            const meta = readSessionMeta(resolved.value.dir) ?? {};
+            if (asked === "")
+                delete meta.model;
+            else
+                meta.model = asked;
+            writeSessionMeta(resolved.value.dir, meta);
+        }
+        catch (e) {
+            return failJson(c, 500, `meta write failed: ${errText(e)}`);
+        }
+        // W516/W860: recompose THIS session at its next boundary (nothing else is touched).
+        deps.runtime.invalidateSession?.(session);
+        return c.json(sessionModelBody(deps, session, resolved.value.dir));
+    });
+    return route.id;
+}

package/dist/handlers/session-move.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Session endpoints, part 2: rename / branch / compact / archive / unarchive /
+ * batch-archive / batch-delete (`src/workspaces.rs:1382-1454,1580-1650`,
+ * `src/compact.rs:505-519`).
+ *
+ * Renaming the ACTIVE session takes the busy slot and re-persists
+ * `active_session`; archiving moves the directory into `.celestea-archived/`
+ * (id-preserving, reversible) while deleting moves it into `.celestea-trash/`
+ * with a timestamp suffix (recoverable, no longer addressable by id).
+ *
+ * W794 (裁决: the active marker is a state label, not a protection): archiving or
+ * deleting the ACTIVE session SUCCEEDS, and the two operations that take a
+ * session's directory away first call `releaseSession` — the engine's own
+ * cut-then-detach — so the model response in flight for that session is aborted
+ * (the same cooperative cancel `POST /api/cancel` sends) and its instance is
+ * released before the directory moves. Every id of a batch is cut the same way,
+ * and the response contract is untouched: still one 200 with per-id `failed[]`.
+ */
+import type { Hono } from "hono";
+import type { RouteTable } from "../routes.js";
+import { type Deps } from "./common.js";
+export declare function registerSessionMoves(app: Hono, deps: Deps, table: RouteTable): string[];

package/dist/handlers/session-move.js

@@ -0,0 +1,188 @@
+/**
+ * Session endpoints, part 2: rename / branch / compact / archive / unarchive /
+ * batch-archive / batch-delete (`src/workspaces.rs:1382-1454,1580-1650`,
+ * `src/compact.rs:505-519`).
+ *
+ * Renaming the ACTIVE session takes the busy slot and re-persists
+ * `active_session`; archiving moves the directory into `.celestea-archived/`
+ * (id-preserving, reversible) while deleting moves it into `.celestea-trash/`
+ * with a timestamp suffix (recoverable, no longer addressable by id).
+ *
+ * W794 (裁决: the active marker is a state label, not a protection): archiving or
+ * deleting the ACTIVE session SUCCEEDS, and the two operations that take a
+ * session's directory away first call `releaseSession` — the engine's own
+ * cut-then-detach — so the model response in flight for that session is aborted
+ * (the same cooperative cancel `POST /api/cancel` sends) and its instance is
+ * released before the directory moves. Every id of a batch is cut the same way,
+ * and the response contract is untouched: still one 200 with per-id `failed[]`.
+ */
+import { EngineError } from "../runtime-adapter.js";
+import { strArrayField, strField, readJsonBody, failJson, storeFail } from "./common.js";
+function isActive(deps, id) {
+    return deps.workspaces.activeSession() === id.trim();
+}
+/**
+ * W794: the engine-side half of taking a session's directory away.
+ *
+ * `releaseSession` (when the injected adapter has one) aborts the session's
+ * in-flight model response and disposes THAT session's instance; it is a no-op
+ * for an id with no live instance, which is why it is safe to call for every id
+ * of a batch — including the unknown ones, whose per-id `failed[]` row below is
+ * exactly what the contract promises.
+ *
+ * A failure inside the engine must not turn a deletion into a 5xx/failed row:
+ * the removal (the directory move) is what the caller asked for and what the
+ * per-id result reports. The instance is released — or, when the teardown threw
+ * halfway, recomposed on demand by the next activate/turn — either way the
+ * session is gone from the listing, which is the observable contract.
+ */
+async function cutEngineSession(deps, id) {
+    try {
+        await deps.runtime.releaseSession?.(id);
+    }
+    catch {
+        // Swallowed on purpose — see above.
+    }
+}
+function registerRename(app, deps, table) {
+    const route = table.get("post_session_rename");
+    app.on(route.method, route.honoPath, async (c) => {
+        // W815-5: canonical id BEFORE the busy guard (raw `%2F`/`%20` segments
+        // bypassed the guard because the runtime keys instances by canonical id).
+        const resolved = deps.sessions.require(c.req.param("id") ?? "");
+        if (!resolved.ok)
+            return storeFail(c, resolved);
+        const session = resolved.value.id;
+        if (deps.runtime.isBusy(session))
+            return failJson(c, 409, "turn in progress; rename applies between turns");
+        const read = await readJsonBody(c);
+        if (!read.ok)
+            return read.response;
+        const title = strField(c, read.body, "new_title");
+        if (!title.ok)
+            return title.response;
+        const res = deps.sessionOps.rename(session, title.value ?? "");
+        if (!res.ok)
+            return storeFail(c, res);
+        if (isActive(deps, session)) {
+            const saved = deps.workspaces.setActiveSession(res.value);
+            if (!saved.ok)
+                return failJson(c, 500, `cannot persist active session: ${saved.error}`);
+        }
+        return c.json({ ok: true, id: res.value });
+    });
+    return route.id;
+}
+function registerBranch(app, deps, table) {
+    const route = table.get("post_session_branch");
+    app.on(route.method, route.honoPath, async (c) => {
+        const read = await readJsonBody(c, false);
+        if (!read.ok)
+            return read.response;
+        const title = strField(c, read.body, "title");
+        if (!title.ok)
+            return title.response;
+        const res = deps.sessionOps.branch(c.req.param("id") ?? "", title.value);
+        if (!res.ok)
+            return storeFail(c, res);
+        return c.json({ ok: true, id: res.value });
+    });
+    return route.id;
+}
+function registerCompact(app, deps, table) {
+    const route = table.get("post_session_compact");
+    app.on(route.method, route.honoPath, async (c) => {
+        // W815-5: canonical id before the two guards.
+        const resolved = deps.sessions.require(c.req.param("id") ?? "");
+        if (!resolved.ok)
+            return storeFail(c, resolved);
+        const session = resolved.value.id;
+        if (deps.runtime.isBusy(session))
+            return failJson(c, 409, "turn 进行中，无法压缩");
+        // W825 P0: a session with LIVE worker work is PINNED — its instance may not
+        // be evicted, so compacting it would rewrite the log under a live descriptor
+        // (the old fd survives the rename and every later append is lost). Refuse up
+        // front, exactly like the busy guard above; the lifecycle refuses again if a
+        // worker appears between this check and the eviction. `workerSessions()` only
+        // reports LIVE instances, which is exactly when a descriptor can be orphaned.
+        if (deps.runtime.workerSessions().some((row) => row.host_session === session && row.status === "RUNNING")) {
+            return failJson(c, 409, "worker 进行中，无法压缩");
+        }
+        try {
+            const out = await deps.runtime.compact(session);
+            deps.bus.emit("compact", 0, { session: out.session, kept_turns: out.kept_turns ?? 0, note: out.note, rebound: out.rebound });
+            const body = { ok: true, compacted: out.compacted, note: out.note };
+            if (out.compacted)
+                body["kept_turns"] = out.kept_turns ?? 0;
+            return c.json(body);
+        }
+        catch (e) {
+            return failJson(c, 500, e instanceof EngineError ? e.message : String(e));
+        }
+    });
+    return route.id;
+}
+function registerMove(app, deps, table, id) {
+    const route = table.get(id);
+    app.on(route.method, route.honoPath, async (c) => {
+        const raw = c.req.param("id") ?? "";
+        // W815-5: the engine cut must name the CANONICAL session. `unarchive` may
+        // address an id whose live dir is absent, so `resolve` (not `require`) is the
+        // right canonicalization; an unresolvable id falls through to the store's own
+        // (identical) error.
+        const resolved = deps.sessions.resolve(raw);
+        const target = resolved.ok ? resolved.value.id : raw;
+        // W794: archiving a LIVE session moves its directory away too, so it cuts the
+        // same way a delete does. `unarchive` restores a directory that has no live
+        // instance by construction (archiving released it) — nothing to cut.
+        if (id === "post_session_archive")
+            await cutEngineSession(deps, target);
+        const res = id === "post_session_archive" ? deps.sessionOps.archive(target) : deps.sessionOps.unarchive(target);
+        if (!res.ok)
+            return storeFail(c, res);
+        return c.json({ ok: true });
+    });
+    return route.id;
+}
+function registerBatch(app, deps, table, id) {
+    const route = table.get(id);
+    app.on(route.method, route.honoPath, async (c) => {
+        const read = await readJsonBody(c);
+        if (!read.ok)
+            return read.response;
+        const ids = strArrayField(c, read.body, "ids");
+        if (!ids.ok)
+            return ids.response;
+        if (ids.value === undefined)
+            return failJson(c, 422, "field 'ids' must be an array of strings");
+        // W794: cut every id before any directory moves. The response shape is
+        // unchanged — one 200, `deleted`/`archived` count plus the per-id `failed[]`
+        // (unknown ids included), so the client's optimistic update can rely on it.
+        // W815-5: cut each id by its CANONICAL form; the store still receives the
+        // caller's ids so the per-id `failed[]` row keeps the id the caller sent.
+        const canonical = ids.value.map((one) => {
+            const resolved = deps.sessions.resolve(one);
+            return resolved.ok ? resolved.value.id : one;
+        });
+        for (const one of canonical)
+            await cutEngineSession(deps, one);
+        if (id === "post_sessions_batch_archive") {
+            const out = deps.sessionOps.batchArchive(ids.value);
+            return c.json({ ok: true, archived: out.archived, failed: out.failed });
+        }
+        const out = deps.sessionOps.batchDelete(ids.value);
+        return c.json({ ok: true, deleted: out.deleted, failed: out.failed });
+    });
+    return route.id;
+}
+export function registerSessionMoves(app, deps, table) {
+    return [
+        registerRename(app, deps, table),
+        registerBranch(app, deps, table),
+        registerCompact(app, deps, table),
+        registerMove(app, deps, table, "post_session_archive"),
+        registerMove(app, deps, table, "post_session_unarchive"),
+        registerBatch(app, deps, table, "post_sessions_batch_archive"),
+        registerBatch(app, deps, table, "post_sessions_batch_delete"),
+    ];
+}

package/dist/handlers/session-tools.d.ts

@@ -0,0 +1,19 @@
+/**
+ * W860: the session-level TOOL SWITCH endpoints (2).
+ *
+ *   GET /api/sessions/{id}/tools -> the stored disabled list + the EFFECTIVE
+ *                                   deny (preset `toolDeny` unioned with it);
+ *   PUT /api/sessions/{id}/tools -> replace the disabled list (validated,
+ *                                   normalized, atomic 0600) and invalidate the
+ *                                   session — the SAME next-turn-boundary hook
+ *                                   `PUT /api/sessions/{id}/permission` uses.
+ *
+ * Storage is `store/session-tools.ts`; the union itself lives in the engine's
+ * ONE grant reader (`runtime/engine-grants.ts`), so this module is the HTTP face
+ * only and the reported `effective.toolDeny` is read back through that reader —
+ * the endpoint cannot drift from what the next turn will actually offer.
+ */
+import type { Hono } from "hono";
+import type { RouteTable } from "../routes.js";
+import { type Deps } from "./common.js";
+export declare function registerSessionTools(app: Hono, deps: Deps, table: RouteTable): string[];

package/dist/handlers/session-tools.js

@@ -0,0 +1,75 @@
+/**
+ * W860: the session-level TOOL SWITCH endpoints (2).
+ *
+ *   GET /api/sessions/{id}/tools -> the stored disabled list + the EFFECTIVE
+ *                                   deny (preset `toolDeny` unioned with it);
+ *   PUT /api/sessions/{id}/tools -> replace the disabled list (validated,
+ *                                   normalized, atomic 0600) and invalidate the
+ *                                   session — the SAME next-turn-boundary hook
+ *                                   `PUT /api/sessions/{id}/permission` uses.
+ *
+ * Storage is `store/session-tools.ts`; the union itself lives in the engine's
+ * ONE grant reader (`runtime/engine-grants.ts`), so this module is the HTTP face
+ * only and the reported `effective.toolDeny` is read back through that reader —
+ * the endpoint cannot drift from what the next turn will actually offer.
+ */
+import { effectiveGrantsOf } from "../runtime/engine-grants.js";
+import { nowSec } from "../store/grants-service.js";
+import { errText } from "../store/result.js";
+import { readSessionTools, writeSessionTools } from "../store/session-tools.js";
+import { failJson, readJsonBody, storeFail } from "./common.js";
+/** The frozen response body of both endpoints (one shape, one construction). */
+function sessionToolsBody(deps, session, dir) {
+    const read = readSessionTools(dir, session);
+    const effective = effectiveGrantsOf(dir, session, deps.grants.env, nowSec(deps.grants));
+    const warnings = [...new Set([...read.warnings, ...effective.warnings])];
+    return {
+        ok: true,
+        session,
+        disabled: [...read.disabled],
+        effective: { toolDeny: [...effective.grants.toolDeny] },
+        ...(warnings.length === 0 ? {} : { warnings }),
+    };
+}
+function registerGetSessionTools(app, deps, table) {
+    const route = table.get("get_session_tools");
+    app.on(route.method, route.honoPath, (c) => {
+        const resolved = deps.sessions.require(c.req.param("id") ?? "");
+        if (!resolved.ok)
+            return storeFail(c, resolved);
+        return c.json(sessionToolsBody(deps, resolved.value.id, resolved.value.dir));
+    });
+    return route.id;
+}
+function registerPutSessionTools(app, deps, table) {
+    const route = table.get("put_session_tools");
+    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 body = await readJsonBody(c);
+        if (!body.ok)
+            return body.response;
+        const raw = body.body["disabled"];
+        if (!Array.isArray(raw) || raw.some((name) => typeof name !== "string")) {
+            return failJson(c, 422, "field 'disabled' must be an array of strings");
+        }
+        if (raw.some((name) => name.trim() === "")) {
+            return failJson(c, 422, "field 'disabled' must not contain an empty tool name");
+        }
+        try {
+            writeSessionTools(resolved.value.dir, resolved.value.id, raw, nowSec(deps.grants));
+        }
+        catch (e) {
+            return failJson(c, 500, "cannot persist session tools: " + errText(e));
+        }
+        // W860: recompose the session at the next boundary — the same hook the
+        // permission switch and the grants writer use (nothing else is touched).
+        deps.runtime.invalidateSession?.(resolved.value.id);
+        return c.json(sessionToolsBody(deps, resolved.value.id, resolved.value.dir));
+    });
+    return route.id;
+}
+export function registerSessionTools(app, deps, table) {
+    return [registerGetSessionTools(app, deps, table), registerPutSessionTools(app, deps, table)];
+}

package/dist/handlers/sessions.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Session endpoints, part 1: list / create / transcript / activate / context.
+ *
+ * `GET /api/sessions` merges two sources: session directories across every
+ * registered workspace, plus the engine's in-memory worker sessions
+ * (`worker:<sid>`, pseudo-workspace "engine", `kind:"worker"`), sorted by id.
+ * W513: every row carries `kind` (`session` | `worker`) and `busy` (that
+ * session's own turn slot), and worker rows carry `wid` / `status` / `state` /
+ * `host_session`, so the UI can list and open them.
+ *
+ * `POST /api/sessions/{id}/activate` is "open this view + make sure the session
+ * HAS a runtime": it composes the instance on demand, persists the active
+ * session as a view preference, and NEVER returns 409 — a session that is
+ * already running is perfectly fine (that is the point of session independence).
+ *
+ * W791 (P1): `POST /api/sessions/{id}/mode` switches the session's working mode
+ * (the W729 `session.json.mode`, rewritten through the same writer) at a turn
+ * boundary — see `registerMode`.
+ *
+ * W791 (B): `GET /api/sessions?archived=1` lists the ARCHIVED sessions (the
+ * `<ws>/.celestea-archived/` rows `list()` skips); the default body is unchanged.
+ *
+ * W725: `GET /api/sessions/{id}/context` is the read-only "what does the model
+ * actually see" snapshot. The body is assembled by the ENGINE (the agent loop's
+ * own `buildRequest`, reached through `runtime.sessionContext`) and the usage
+ * block is the statusline's existing `context_usage`口径 — this handler adds
+ * only the 20k-per-entry wire guard.
+ */
+import type { Hono } from "hono";
+import type { RouteTable } from "../routes.js";
+import { type Deps } from "./common.js";
+export declare function registerSessions(app: Hono, deps: Deps, table: RouteTable): string[];