@celestea/studio 2.7.1

package/dist/handlers/sessions.js

@@ -0,0 +1,242 @@
+/**
+ * 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 { CapacityError, EngineError } from "../runtime-adapter.js";
+import { readSessionMeta, writeSessionMeta } from "../store/session-meta.js";
+import { DEFAULT_SESSION_MODE, parseMode, validateMode } from "../store/mode.js";
+import { validateModelName } from "../store/validate.js";
+import { capacityJson, failJson, readJsonBody, strField, storeFail } from "./common.js";
+import { contextPayload } from "./context-shape.js";
+function workerRows(deps) {
+    return deps.runtime.workerSessions();
+}
+/** W513: `busy` is the session's OWN turn slot, never a process-wide flag. */
+function withBusy(deps, row) {
+    return row.kind === "worker" ? row : { ...row, busy: deps.runtime.isBusy(row.id) };
+}
+/**
+ * W791 (B2): `?archived=1` (or `true`) selects the ARCHIVED listing.
+ *
+ * The default listing is untouched — archived sessions still live in a hidden
+ * sibling directory and are therefore absent from it, and the rows below are the
+ * only place an `archived` key ever appears. `0`, `false`, an empty value or an
+ * unrecognised value all read as "the default listing", so a client can poll the
+ * parameter without inventing a second default.
+ */
+function wantsArchived(raw) {
+    if (raw === undefined)
+        return false;
+    const value = raw.trim().toLowerCase();
+    return value === "1" || value === "true";
+}
+function registerList(app, deps, table) {
+    const route = table.get("get_sessions");
+    app.on(route.method, route.honoPath, (c) => {
+        // W791: the ARCHIVED source answers with `listArchived()` only — archived
+        // sessions are filesystem rows, never worker rows, and none of them can be
+        // active or busy. W794: not because archiving REFUSES the active session (it
+        // no longer does) but because archiving CLEARS the marker: a moved session
+        // cannot be the active one, so `active_session` and the rows stay consistent.
+        const rows = wantsArchived(c.req.query("archived"))
+            ? deps.sessions.listArchived()
+            : deps.sessions.list(workerRows(deps)).map((row) => withBusy(deps, row));
+        return c.json({ sessions: rows, active_session: deps.workspaces.activeSession() });
+    });
+    return route.id;
+}
+function registerCreate(app, deps, table) {
+    const route = table.get("post_sessions");
+    app.on(route.method, route.honoPath, async (c) => {
+        const read = await readJsonBody(c);
+        if (!read.ok)
+            return read.response;
+        const title = strField(c, read.body, "title");
+        const workspace = strField(c, read.body, "workspace");
+        const model = strField(c, read.body, "model");
+        const prompt = strField(c, read.body, "prompt");
+        const mode = strField(c, read.body, "mode");
+        for (const f of [title, workspace, model, prompt, mode])
+            if (!f.ok)
+                return f.response;
+        const res = deps.sessions.create({
+            title: title.ok ? (title.value ?? "") : "",
+            workspace: workspace.ok ? workspace.value : undefined,
+            model: model.ok ? model.value : undefined,
+            prompt: prompt.ok ? prompt.value : undefined,
+            mode: mode.ok ? mode.value : undefined,
+        });
+        if (!res.ok)
+            return storeFail(c, res);
+        return c.json({ ok: true, id: res.value });
+    });
+    return route.id;
+}
+function registerMessages(app, deps, table) {
+    const route = table.get("get_session_messages");
+    app.on(route.method, route.honoPath, (c) => {
+        const id = c.req.param("id") ?? "";
+        if (id.startsWith("worker:")) {
+            const messages = deps.runtime.workerMessages(id);
+            if (messages === null)
+                return failJson(c, 404, `unknown session '${id}'`);
+            return c.json({ ok: true, session: id, messages });
+        }
+        const resolved = deps.sessions.require(id);
+        if (!resolved.ok)
+            return storeFail(c, resolved);
+        return c.json({ ok: true, session: id, messages: deps.sessions.messages(resolved.value) });
+    });
+    return route.id;
+}
+/** The session-level model override problem, or null when it is usable. */
+function invalidSessionModel(dir) {
+    const model = readSessionMeta(dir)?.model;
+    if (model === undefined || model === "")
+        return null;
+    return validateModelName(model);
+}
+function registerActivate(app, deps, table) {
+    const route = table.get("post_session_activate");
+    app.on(route.method, route.honoPath, (c) => {
+        const id = c.req.param("id") ?? "";
+        const resolved = deps.sessions.require(id);
+        if (!resolved.ok)
+            return storeFail(c, resolved);
+        const bad = invalidSessionModel(resolved.value.dir);
+        if (bad !== null)
+            return failJson(c, 400, `invalid session model: ${bad}`);
+        let info;
+        try {
+            info = deps.runtime.ensureSession(resolved.value.id);
+        }
+        catch (e) {
+            if (e instanceof CapacityError)
+                return capacityJson(c, e);
+            return failJson(c, 500, `compose failed: ${e instanceof EngineError ? e.message : String(e)}`);
+        }
+        const saved = deps.workspaces.setActiveSession(resolved.value.id);
+        if (!saved.ok)
+            return failJson(c, 500, `cannot persist active session: ${saved.error}`);
+        return c.json({ ok: true, active_session: resolved.value.id, runtime: info.runtime, busy: info.busy, rebuilt: info.rebuilt });
+    });
+    return route.id;
+}
+/**
+ * GET /api/sessions/{id}/context (W725) — the engine's model-visible context.
+ *
+ * A session with no live instance is composed on demand (the same `entryFor`
+ * path activate and a turn use), so the endpoint works on a cold session and
+ * never drives a turn.
+ */
+function registerContext(app, deps, table) {
+    const route = table.get("get_session_context");
+    app.on(route.method, route.honoPath, (c) => {
+        const resolved = deps.sessions.require(c.req.param("id") ?? "");
+        if (!resolved.ok)
+            return storeFail(c, resolved);
+        const session = resolved.value.id;
+        try {
+            const view = deps.runtime.sessionContext(session);
+            return c.json(contextPayload({ session, view, usage: contextUsageOf(deps, session) }));
+        }
+        catch (e) {
+            if (e instanceof CapacityError)
+                return capacityJson(c, e);
+            return failJson(c, 500, `context snapshot failed: ${e instanceof EngineError ? e.message : String(e)}`);
+        }
+    });
+    return route.id;
+}
+/**
+ * POST /api/sessions/{id}/mode (W791, P1 — `docs/modes-standard-vs-execution.md`
+ * §3.1/§5.2 #6, U8): switch the session's WORKING MODE at a turn boundary.
+ *
+ * Three disciplines, all inherited from existing endpoints on purpose:
+ *   - the busy guard is `/compact`'s, in semantics AND in shape (409, and the
+ *     wording is the same sentence with this action's verb) — a mode is a
+ *     property of the generation, so it may not change inside a running turn;
+ *   - the write path is W729's `session.json` writer (the other keys are kept),
+ *     so a switch is the SAME operation `POST /api/sessions {mode}` performs;
+ *   - the effect is W516's: the session's instance is dropped and the next turn
+ *     recomposes it, which is what makes the response's `effective:"next_turn"`
+ *     a fact rather than a promise. Sessions other than this one are untouched.
+ *
+ * TS-only (U8): the retired backend has no such endpoint, so the contract registers
+ * it under `tsOnlyRoutes` and the frontend gates on
+ * `capabilities.session_mode_tools`.
+ */
+function registerMode(app, deps, table) {
+    const route = table.get("post_session_mode");
+    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 `%2F`/`%20` used to produce an id
+        // whose isBusy() lookup never matched the canonical instance (guard bypass).
+        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 mode = strField(c, read.body, "mode");
+        if (!mode.ok)
+            return mode.response;
+        if (mode.value === undefined)
+            return failJson(c, 422, "field 'mode' must be a string");
+        const bad = validateMode(mode.value);
+        if (bad !== null)
+            return failJson(c, 400, bad);
+        try {
+            // W729 write path, key-preserving: title / model / prompt survive the switch.
+            writeSessionMeta(resolved.value.dir, { ...(readSessionMeta(resolved.value.dir) ?? {}), mode: parseMode(mode.value) ?? DEFAULT_SESSION_MODE });
+        }
+        catch (e) {
+            return failJson(c, 500, `meta write failed: ${String(e)}`);
+        }
+        deps.runtime.invalidateSession?.(session);
+        return c.json({ ok: true, session, mode: mode.value, effective: "next_turn" });
+    });
+    return route.id;
+}
+/** The statusline's context口径 (W263) with the `method` discriminator dropped. */
+function contextUsageOf(deps, session) {
+    const usage = deps.runtime.statusline(session).context_usage;
+    return { used: usage.used, window: usage.window, ratio: usage.ratio, estimated: usage.estimated };
+}
+export function registerSessions(app, deps, table) {
+    return [
+        registerList(app, deps, table),
+        registerCreate(app, deps, table),
+        registerMessages(app, deps, table),
+        registerActivate(app, deps, table),
+        registerContext(app, deps, table),
+        registerMode(app, deps, table),
+    ];
+}

package/dist/handlers/usage.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `GET /api/usage/ledger` — the aggregate view of the usage ledger (E §3.2.4, W785 P1 ①).
+ *
+ * The endpoint is a thin, honest SHAPE over the engine seam: the runtime adapter
+ * owns the ledger file and the folding (`queryLedger`), this handler only reads
+ * the query string, rejects a malformed one, and forwards. There is no host-side
+ * aggregation and no cache, so "what the endpoint says" and "what the ledger
+ * holds" cannot drift.
+ *
+ * Two `ok:false` answers are NOT client errors and stay HTTP 200, because the
+ * request was understood and the answer is "there is no ledger here":
+ *   - `usage ledger unavailable` — the adapter has no ledger capability at all
+ *     (an embedded/fake adapter; the `/api/health` style of degradation);
+ *   - `usage ledger disabled`     — the real adapter, `CELESTEA_USAGE_LEDGER=off`.
+ * The `error` field is registered optional in `contracts/endpoints.json`, which is
+ * exactly this case.
+ *
+ * A MALFORMED query is a 422 like every other handler (`field '<name>' must be …`,
+ * `handlers/common.ts` style): `since`/`until` are SECONDS and must be integers
+ * (`ts` of a ledger row), `group_by` must be one of session|turn|model|day.
+ */
+import type { Hono } from "hono";
+import type { RouteTable } from "../routes.js";
+import { type Deps } from "./common.js";
+/** The one aggregate endpoint, in contract order. */
+export declare function registerUsage(app: Hono, deps: Deps, table: RouteTable): string[];

package/dist/handlers/usage.js

@@ -0,0 +1,77 @@
+/**
+ * `GET /api/usage/ledger` — the aggregate view of the usage ledger (E §3.2.4, W785 P1 ①).
+ *
+ * The endpoint is a thin, honest SHAPE over the engine seam: the runtime adapter
+ * owns the ledger file and the folding (`queryLedger`), this handler only reads
+ * the query string, rejects a malformed one, and forwards. There is no host-side
+ * aggregation and no cache, so "what the endpoint says" and "what the ledger
+ * holds" cannot drift.
+ *
+ * Two `ok:false` answers are NOT client errors and stay HTTP 200, because the
+ * request was understood and the answer is "there is no ledger here":
+ *   - `usage ledger unavailable` — the adapter has no ledger capability at all
+ *     (an embedded/fake adapter; the `/api/health` style of degradation);
+ *   - `usage ledger disabled`     — the real adapter, `CELESTEA_USAGE_LEDGER=off`.
+ * The `error` field is registered optional in `contracts/endpoints.json`, which is
+ * exactly this case.
+ *
+ * A MALFORMED query is a 422 like every other handler (`field '<name>' must be …`,
+ * `handlers/common.ts` style): `since`/`until` are SECONDS and must be integers
+ * (`ts` of a ledger row), `group_by` must be one of session|turn|model|day.
+ */
+import { LEDGER_GROUP_BY_VALUES, DEFAULT_LEDGER_GROUP_BY } from "@celestea/runtime";
+import { errText } from "../store/result.js";
+import { failJson } from "./common.js";
+/** `since`/`until` are epoch SECONDS (the `ts` of a row), never ISO strings. */
+function intQuery(c, name) {
+    const raw = (c.req.query(name) ?? "").trim();
+    if (raw === "")
+        return { ok: true, value: null };
+    if (!/^-?\d+$/.test(raw))
+        return { ok: false, error: `field '${name}' must be an integer` };
+    const value = Number.parseInt(raw, 10);
+    if (!Number.isSafeInteger(value))
+        return { ok: false, error: `field '${name}' must be an integer` };
+    return { ok: true, value };
+}
+/** The whole query string; an empty value is the same as an absent one. */
+function readQuery(c) {
+    const session = (c.req.query("session") ?? "").trim();
+    const groupBy = (c.req.query("group_by") ?? "").trim();
+    if (groupBy !== "" && !LEDGER_GROUP_BY_VALUES.includes(groupBy)) {
+        return { ok: false, error: `field 'group_by' must be one of ${LEDGER_GROUP_BY_VALUES.join(", ")}` };
+    }
+    const since = intQuery(c, "since");
+    if (!since.ok)
+        return { ok: false, error: since.error };
+    const until = intQuery(c, "until");
+    if (!until.ok)
+        return { ok: false, error: until.error };
+    const q = { group_by: groupBy === "" ? DEFAULT_LEDGER_GROUP_BY : groupBy };
+    if (session !== "")
+        q.session = session;
+    if (since.value !== null)
+        q.since = since.value;
+    if (until.value !== null)
+        q.until = until.value;
+    return { ok: true, value: q };
+}
+/** The one aggregate endpoint, in contract order. */
+export function registerUsage(app, deps, table) {
+    const route = table.get("get_usage_ledger");
+    app.on(route.method, route.honoPath, (c) => {
+        const read = readQuery(c);
+        if (!read.ok)
+            return failJson(c, 422, read.error);
+        const view = deps.runtime.usageLedger;
+        if (view === undefined)
+            return c.json({ ok: false, error: "usage ledger unavailable" });
+        try {
+            return c.json(view.call(deps.runtime, read.value));
+        }
+        catch (e) {
+            return failJson(c, 500, errText(e));
+        }
+    });
+    return [route.id];
+}

package/dist/handlers/worker.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Worker orchestration — `src/api.rs:437-503`.
+ *
+ * The three endpoints proxy the engine's worker tools so the HTTP surface and
+ * the agent tool surface cannot drift. A tool-level refusal (`{ok:false,…}`) is
+ * still HTTP 200; only a HARD dispatch failure is 502, and a tool that returns
+ * no value at all is 500.
+ */
+import type { Hono } from "hono";
+import type { RouteTable } from "../routes.js";
+import { type Deps } from "./common.js";
+export declare function registerWorker(app: Hono, deps: Deps, table: RouteTable): string[];

package/dist/handlers/worker.js

@@ -0,0 +1,82 @@
+/**
+ * Worker orchestration — `src/api.rs:437-503`.
+ *
+ * The three endpoints proxy the engine's worker tools so the HTTP surface and
+ * the agent tool surface cannot drift. A tool-level refusal (`{ok:false,…}`) is
+ * still HTTP 200; only a HARD dispatch failure is 502, and a tool that returns
+ * no value at all is 500.
+ */
+import { failJson, readJsonBody, strField, storeFail } from "./common.js";
+function registerSpawn(app, deps, table) {
+    const route = table.get("post_worker_spawn");
+    app.on(route.method, route.honoPath, async (c) => {
+        const read = await readJsonBody(c);
+        if (!read.ok)
+            return read.response;
+        const wid = strField(c, read.body, "wid");
+        const brief = strField(c, read.body, "brief");
+        const title = strField(c, read.body, "title");
+        const model = strField(c, read.body, "model");
+        const reportTo = strField(c, read.body, "report_to");
+        const session = strField(c, read.body, "session");
+        for (const f of [wid, brief, title, model, reportTo, session])
+            if (!f.ok)
+                return f.response;
+        if ((wid.ok ? wid.value : undefined) === undefined || (brief.ok ? brief.value : undefined) === undefined) {
+            return failJson(c, 422, "fields 'wid' and 'brief' are required");
+        }
+        // W833 (R3 B7 / W816 F3): an explicit session must RESOLVE before a worker
+        // is composed against it. Passing an unknown id used to compose an in-memory
+        // ghost instance (live slot + autowake loop + worker row) whose receipt no
+        // one could ever receive. Omitted/empty session keeps the detached default.
+        if (session.ok && typeof session.value === "string" && session.value !== "") {
+            const resolved = deps.sessions.require(session.value);
+            if (!resolved.ok)
+                return storeFail(c, resolved);
+        }
+        const out = await deps.runtime.workerSpawn({
+            wid: wid.ok ? wid.value : "",
+            brief: brief.ok ? brief.value : "",
+            title: title.ok ? title.value : undefined,
+            model: model.ok ? model.value : undefined,
+            report_to: reportTo.ok ? reportTo.value : undefined,
+            session: session.ok ? (session.value ?? null) : null,
+        });
+        if (out.ok)
+            return c.json({ ok: true, sessionId: out.sessionId, title: out.title, wid: out.wid });
+        if (out.error === undefined && out.value === undefined)
+            return failJson(c, 500, "tool returned no value");
+        return failJson(c, 502, out.error ?? "worker spawn failed", out.value === undefined ? undefined : { value: out.value });
+    });
+    return route.id;
+}
+function registerSend(app, deps, table) {
+    const route = table.get("post_worker_send");
+    app.on(route.method, route.honoPath, async (c) => {
+        const read = await readJsonBody(c);
+        if (!read.ok)
+            return read.response;
+        const target = strField(c, read.body, "target");
+        const content = strField(c, read.body, "content");
+        for (const f of [target, content])
+            if (!f.ok)
+                return f.response;
+        if ((target.ok ? target.value : undefined) === undefined || (content.ok ? content.value : undefined) === undefined) {
+            return failJson(c, 422, "fields 'target' and 'content' are required");
+        }
+        const out = await deps.runtime.workerSend({ target: target.ok ? target.value : "", content: content.ok ? content.value : "" });
+        return c.json(out);
+    });
+    return route.id;
+}
+function registerStatus(app, deps, table) {
+    const route = table.get("get_worker_status");
+    app.on(route.method, route.honoPath, (c) => {
+        const wid = c.req.query("wid");
+        return c.json(deps.runtime.workerStatus(wid === undefined || wid === "" ? undefined : wid));
+    });
+    return route.id;
+}
+export function registerWorker(app, deps, table) {
+    return [registerSpawn(app, deps, table), registerSend(app, deps, table), registerStatus(app, deps, table)];
+}

package/dist/handlers/workspaces.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Workspace registry endpoints — `src/workspaces.rs:790-966`.
+ *
+ * `POST /api/workspaces` registers a folder by absolute path (the key is the
+ * folder basename and is never stored); `{name}/rename` really renames the
+ * USER folder and returns the whole registry view; `{name}/delete` only
+ * deregisters and never touches the folder.
+ */
+import type { Hono } from "hono";
+import type { RouteTable } from "../routes.js";
+import { type Deps } from "./common.js";
+export declare function registerWorkspaces(app: Hono, deps: Deps, table: RouteTable): string[];

package/dist/handlers/workspaces.js

@@ -0,0 +1,88 @@
+/**
+ * Workspace registry endpoints — `src/workspaces.rs:790-966`.
+ *
+ * `POST /api/workspaces` registers a folder by absolute path (the key is the
+ * folder basename and is never stored); `{name}/rename` really renames the
+ * USER folder and returns the whole registry view; `{name}/delete` only
+ * deregisters and never touches the folder.
+ */
+import { validateWorkspaceName } from "../store/session-id.js";
+import { failJson, readJsonBody, strArrayField, strField, storeFail } from "./common.js";
+/** Busy guard: renaming a workspace that hosts the ACTIVE session re-composes. */
+function activeInWorkspace(deps, name) {
+    const active = deps.workspaces.activeSession();
+    return active !== null && active.split("/")[0] === name;
+}
+function registerList(app, deps, table) {
+    const route = table.get("get_workspaces");
+    app.on(route.method, route.honoPath, (c) => c.json(deps.workspaces.view()));
+    return route.id;
+}
+function registerCreate(app, deps, table) {
+    const route = table.get("post_workspaces");
+    app.on(route.method, route.honoPath, async (c) => {
+        const read = await readJsonBody(c);
+        if (!read.ok)
+            return read.response;
+        const path = strField(c, read.body, "path");
+        if (!path.ok)
+            return path.response;
+        const res = deps.workspaces.register(path.value ?? "");
+        if (!res.ok)
+            return storeFail(c, res);
+        return c.json({ ok: true, name: res.value });
+    });
+    return route.id;
+}
+function registerRename(app, deps, table) {
+    const route = table.get("post_workspace_rename");
+    app.on(route.method, route.honoPath, async (c) => {
+        const name = c.req.param("name") ?? "";
+        if (activeInWorkspace(deps, name) && deps.runtime.isBusy()) {
+            return failJson(c, 409, "turn in progress; rename applies between turns");
+        }
+        const read = await readJsonBody(c);
+        if (!read.ok)
+            return read.response;
+        const newName = strField(c, read.body, "new_name");
+        if (!newName.ok)
+            return newName.response;
+        const checked = validateWorkspaceName(newName.value ?? "");
+        if (!checked.ok)
+            return failJson(c, 400, checked.error);
+        const res = deps.workspaces.renameWorkspace(name, checked.name);
+        if (!res.ok)
+            return storeFail(c, res);
+        return c.json(deps.workspaces.view());
+    });
+    return route.id;
+}
+function registerDelete(app, deps, table) {
+    const route = table.get("post_workspace_delete");
+    app.on(route.method, route.honoPath, (c) => {
+        const res = deps.workspaces.deregister(c.req.param("name") ?? "");
+        if (!res.ok)
+            return storeFail(c, res);
+        return c.json({ ok: true });
+    });
+    return route.id;
+}
+function registerBatchDelete(app, deps, table) {
+    const route = table.get("post_workspaces_batch_delete");
+    app.on(route.method, route.honoPath, async (c) => {
+        const read = await readJsonBody(c);
+        if (!read.ok)
+            return read.response;
+        const names = strArrayField(c, read.body, "names");
+        if (!names.ok)
+            return names.response;
+        if (names.value === undefined)
+            return failJson(c, 422, "field 'names' must be an array of strings");
+        const out = deps.workspaces.batchDelete(names.value);
+        return c.json({ ok: true, deleted: out.deleted, failed: out.failed });
+    });
+    return route.id;
+}
+export function registerWorkspaces(app, deps, table) {
+    return [registerList(app, deps, table), registerCreate(app, deps, table), registerRename(app, deps, table), registerDelete(app, deps, table), registerBatchDelete(app, deps, table)];
+}

package/dist/harness.test-util.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Shared test harness for the Studio HTTP layer.
+ *
+ * Every test gets a THROWAWAY data directory (workspaces/providers/prompts +
+ * one registered workspace holding one session) and a throwaway static root, so
+ * no test can read or write a production data file, and the fake runtime adapter
+ * keeps the engine seam deterministic.
+ */
+import type { Hono } from "hono";
+import { type StudioApp, type StudioAppOptions } from "./app.js";
+import { type FakeRuntimeAdapter } from "./fake-runtime-adapter.js";
+import { type StudioPaths } from "./config.js";
+import type { EngineFactory } from "./plugins.js";
+import type { RuntimeAdapter } from "./runtime-adapter.js";
+/**
+ * A fake adapter that always reports ITS BUSY SLOT as taken: every session is
+ * busy, so the process-wide guards (config / prompts / providers) 409 while
+ * `/api/turn` takes the interjection path and activate reports `busy:true`.
+ * A `Proxy` is used because spreading a class instance would drop its methods.
+ */
+export declare function busyRuntime(base?: FakeRuntimeAdapter): FakeRuntimeAdapter;
+export declare const FIXED_NOW = 1700000000000;
+export declare const FIXED_TS = "1700000000.0";
+export interface StudioHarness {
+    app: Hono;
+    studio: StudioApp;
+    runtime: RuntimeAdapter;
+    /** Throwaway root of all data files + the static build. */
+    root: string;
+    /** Registered workspace folder (empty by default). */
+    workspace: string;
+    staticRoot: string;
+    cleanup(): void;
+}
+export interface HarnessOptions extends Omit<StudioAppOptions, "runtime"> {
+    /** Tests inject a concrete adapter (the fake by default). */
+    runtime?: RuntimeAdapter;
+    /**
+     * Real-engine path: a factory over the composed stores (the adapter it builds
+     * is `studio.services.runtime`, which is what [StudioHarness.runtime] exposes).
+     */
+    engineFactory?: EngineFactory;
+    /** Files planted before the app composes (e.g. a providers.json secret). */
+    files?: Record<string, unknown>;
+    /**
+     * W787: files planted VERBATIM (a TSV worker table, a JSONL log) — unlike
+     * `files`, the value is written as-is instead of JSON-encoded.
+     */
+    rawFiles?: Record<string, string>;
+    /**
+     * Path overrides merged over the throwaway root (W767: the auth password file
+     * and secret file, which must point at a test-controlled location).
+     */
+    paths?: Partial<StudioPaths>;
+    /** Create a session dir in the workspace holding `log` lines. */
+    session?: {
+        name: string;
+        log?: string;
+        meta?: Record<string, string>;
+    };
+}
+export declare function makeHarness(opts?: HarnessOptions): StudioHarness;
+/**
+ * W864: the built-in `full-access` preset now also opens every path
+ * (`allPaths`), so a test that wants to observe the PATH/grants boundary must
+ * pin a baseline that is path-limited. This plants exactly that — network on,
+ * workspace writable, `allPaths` off — as a custom preset in <data dir> and
+ * selects it for the session, through the same two files the engine reads
+ * (`store/permissions.ts`, `runtime/engine-permissions.ts`).
+ */
+export declare const PATH_ONLY_PRESET: {
+    id: string;
+    label: string;
+    network: boolean;
+    workspaceWritable: boolean;
+    toolRootsWritable: boolean;
+    writeRoots: never[];
+    allPaths: boolean;
+    unsandboxed: boolean;
+    toolDeny: never[];
+};
+export declare function pinPathOnly(h: StudioHarness, name?: string): void;
+export declare function jsonRequest(method: string, body?: unknown): RequestInit;
+/**
+ * W516 grant helpers: a grant needs a one-shot token from the same-origin
+ * token endpoint, so every test drives the same two-step handshake the UI does.
+ */
+export declare function grantToken(h: StudioHarness, id: string, cap: string, scope: Record<string, unknown>): Promise<string>;
+/** POST a grant (token minted automatically unless one is passed / `null`). */
+export declare function grant(h: StudioHarness, id: string, body: Record<string, unknown>, token?: string | null): Promise<{
+    status: number;
+    body: Record<string, unknown>;
+}>;
+/** The local (authoritative) grants audit channel of a harness data dir. */
+export declare function auditLines(h: StudioHarness): Array<Record<string, unknown>>;
+export declare function getJson(app: Hono, path: string, init?: RequestInit): Promise<{
+    status: number;
+    body: Record<string, unknown>;
+}>;
+/** W885: file permission bits are meaningful (false on Windows; W883 E10). */
+export declare const FILE_MODES_MEANINGFUL: boolean;