@celestea/studio 2.7.1

package/dist/handlers/config.d.ts

@@ -0,0 +1,26 @@
+/**
+ * GET/POST `/api/config` — `src/api.rs:56-70,190-372`.
+ *
+ * POST is a two-phase apply: the HOST validates (model charset/length, url,
+ * numeric caps, effort availability) and then hands an accepted patch to the
+ * engine seam (`RuntimeAdapter.configure`). The api_key takes a third path: it
+ * goes only into `process.env[api_key_env]` — never into a response, a store or
+ * a log line.
+ */
+import type { Hono } from "hono";
+import type { RouteTable } from "../routes.js";
+import { type Deps } from "./common.js";
+import type { RuntimeAdapter } from "../runtime-adapter.js";
+/**
+ * W742 §1: is any live instance still driving UNSETTLED workers? Both endpoints
+ * that swap the engine profile (`POST /api/config` here and `POST
+ * /api/providers/default`) must refuse while background work is in flight,
+ * because recomposing an instance disposes the old one — which aborts its workers
+ * and drops their registry rows, i.e. a silent kill the caller never sees.
+ *
+ * This is the UP-FRONT half of the fix; the registry's `rebuildDeferred` is the
+ * second half, because a worker can also appear between this check and the bump
+ * (a turn in another session may spawn one).
+ */
+export declare function workersInFlight(runtime: RuntimeAdapter): boolean;
+export declare function registerConfig(app: Hono, deps: Deps, table: RouteTable): string[];

package/dist/handlers/config.js

@@ -0,0 +1,161 @@
+/**
+ * GET/POST `/api/config` — `src/api.rs:56-70,190-372`.
+ *
+ * POST is a two-phase apply: the HOST validates (model charset/length, url,
+ * numeric caps, effort availability) and then hands an accepted patch to the
+ * engine seam (`RuntimeAdapter.configure`). The api_key takes a third path: it
+ * goes only into `process.env[api_key_env]` — never into a response, a store or
+ * a log line.
+ */
+import { EngineError } from "../runtime-adapter.js";
+import { configView } from "./config-shape.js";
+import { failJson, numField, readJsonBody, strField } from "./common.js";
+import { validateModelName } from "../store/validate.js";
+import { MIN_STEPS } from "../config.js";
+const U32_MAX = 4_294_967_295;
+/**
+ * W742 §1: is any live instance still driving UNSETTLED workers? Both endpoints
+ * that swap the engine profile (`POST /api/config` here and `POST
+ * /api/providers/default`) must refuse while background work is in flight,
+ * because recomposing an instance disposes the old one — which aborts its workers
+ * and drops their registry rows, i.e. a silent kill the caller never sees.
+ *
+ * This is the UP-FRONT half of the fix; the registry's `rebuildDeferred` is the
+ * second half, because a worker can also appear between this check and the bump
+ * (a turn in another session may spawn one).
+ */
+export function workersInFlight(runtime) {
+    return runtime.workerSessions().some((row) => row.status === "RUNNING");
+}
+/** `reasoning_effort` handling: ""/"off" clears; free strings pass through. */
+function effortPatch(patch, raw) {
+    if (raw === undefined)
+        return;
+    const v = raw.trim();
+    patch.reasoning_effort = v === "" || v.toLowerCase() === "off" ? null : v;
+}
+/** Validate + fold the optional numeric fields into the patch. */
+function numericPatch(c, body, patch) {
+    const maxOut = numField(c, body, "max_output_tokens");
+    if (!maxOut.ok)
+        return maxOut.response;
+    if (maxOut.value !== undefined) {
+        if (maxOut.value > U32_MAX)
+            return failJson(c, 400, "max_output_tokens must be <= u32::MAX");
+        patch.max_output_tokens = maxOut.value === 0 ? null : Math.trunc(maxOut.value);
+    }
+    const ctxWindow = numField(c, body, "context_window");
+    if (!ctxWindow.ok)
+        return ctxWindow.response;
+    if (ctxWindow.value !== undefined)
+        patch.context_window = Math.trunc(ctxWindow.value);
+    const steps = numField(c, body, "max_steps");
+    if (!steps.ok)
+        return steps.response;
+    if (steps.value !== undefined) {
+        if (steps.value === 0)
+            return failJson(c, 400, "max_steps must be >= 1");
+        patch.max_steps = Math.max(Math.trunc(steps.value), MIN_STEPS);
+    }
+    return null;
+}
+export function registerConfig(app, deps, table) {
+    const get = table.get("get_config");
+    app.on(get.method, get.honoPath, (c) => c.json(configView(deps)));
+    const post = table.get("post_config");
+    app.on(post.method, post.honoPath, async (c) => {
+        if (deps.runtime.isBusy())
+            return failJson(c, 409, "turn in progress; config applies between turns");
+        if (workersInFlight(deps.runtime))
+            return failJson(c, 409, "a worker is running; config applies between turns");
+        const read = await readJsonBody(c);
+        if (!read.ok)
+            return read.response;
+        const body = read.body;
+        const model = strField(c, body, "model");
+        if (!model.ok)
+            return model.response;
+        const effort = strField(c, body, "reasoning_effort");
+        if (!effort.ok)
+            return effort.response;
+        const baseUrl = strField(c, body, "base_url");
+        if (!baseUrl.ok)
+            return baseUrl.response;
+        const apiKey = strField(c, body, "api_key");
+        if (!apiKey.ok)
+            return apiKey.response;
+        const systemPrompt = strField(c, body, "system_prompt");
+        if (!systemPrompt.ok)
+            return systemPrompt.response;
+        const patch = {};
+        const askedModel = (model.value ?? "").trim();
+        if (askedModel !== "") {
+            const bad = validateModelName(askedModel);
+            if (bad !== null)
+                return failJson(c, 400, bad);
+            patch.model = askedModel;
+        }
+        effortPatch(patch, effort.value);
+        if (patch.reasoning_effort != null && !isReasoningCapable(deps, patch.model ?? deps.runtime.profile().model)) {
+            return failJson(c, 400, `model '${patch.model ?? deps.runtime.profile().model}' is not a reasoning model; reasoning_effort is unavailable`);
+        }
+        if (baseUrl.value !== undefined) {
+            if (baseUrl.value !== "" && !isHttp(baseUrl.value))
+                return failJson(c, 400, "base_url must be an http:// or https:// URL");
+            if (baseUrl.value !== "")
+                patch.base_url = baseUrl.value;
+        }
+        const numericFailure = numericPatch(c, body, patch);
+        if (numericFailure !== null)
+            return numericFailure;
+        const nextSystemPrompt = systemPrompt.value === undefined ? undefined : systemPrompt.value.trim() === "" ? null : systemPrompt.value;
+        if (nextSystemPrompt !== undefined)
+            patch.system_prompt = nextSystemPrompt ?? "";
+        if (apiKey.value !== undefined && apiKey.value !== "") {
+            process.env[deps.config.apiKeyEnv] = apiKey.value;
+        }
+        // W815-3 + N2: validate EVERYTHING first, then commit the two host-side
+        // overrides and the engine patch together inside the shared hot-apply queue.
+        // A rejected configure restores the previous overrides (W815-3: base_url may
+        // no longer stick while the patch that carried it was refused) and two
+        // concurrent writers can no longer roll each other back.
+        return deps.applyQueue.run(async () => {
+            const previousBaseUrl = deps.settings.baseUrlOverride();
+            const previousSystemPrompt = deps.settings.systemPromptOverride();
+            if (baseUrl.value !== undefined)
+                deps.settings.setBaseUrlOverride(baseUrl.value);
+            if (nextSystemPrompt !== undefined)
+                deps.settings.setSystemPromptOverride(nextSystemPrompt ?? "");
+            try {
+                await deps.runtime.configure(patch);
+            }
+            catch (e) {
+                if (baseUrl.value !== undefined)
+                    deps.settings.setBaseUrlOverride(previousBaseUrl ?? "");
+                if (nextSystemPrompt !== undefined)
+                    deps.settings.setSystemPromptOverride(previousSystemPrompt ?? "");
+                const message = e instanceof EngineError ? e.message : String(e);
+                return failJson(c, 500, `compose failed: ${message}`);
+            }
+            return c.json(configView(deps));
+        });
+    });
+    return [get.id, post.id];
+}
+function isHttp(url) {
+    return url.startsWith("http://") || url.startsWith("https://");
+}
+/**
+ * Reasoning availability: a model the providers store lists WITHOUT any
+ * reasoning effort is not reasoning-capable; an unknown id is (the contract's
+ * "custom endpoint friendly" rule, `src/main.rs:135-137`).
+ */
+function isReasoningCapable(deps, model) {
+    for (const p of deps.providers.rows()) {
+        for (const m of p.models) {
+            if (m.id === model)
+                return m.reasoning_efforts.length > 0;
+        }
+    }
+    return true;
+}

package/dist/handlers/context-shape.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `GET /api/sessions/{id}/context` response shaping (W725).
+ *
+ * The only transformation applied here is the wire-size guard the contract
+ * freezes: a single entry longer than [MAX_ENTRY_CHARS] is cut and MARKED, and
+ * the top-level `truncated` reports whether anything was cut — a silently
+ * shortened prompt would make the viewer lie about what the model saw.
+ *
+ * `context` reuses the statusline's existing口径 (`context_usage`): the REAL
+ * prompt-token count once a usage frame has been seen (`estimated:false`), else
+ * the session log's character estimate (`estimated:true`). There is no second
+ * accounting path for this endpoint.
+ */
+import type { SessionContextView } from "../runtime-adapter.js";
+/** Per-entry character cap (contract): one entry never travels longer. */
+export declare const MAX_ENTRY_CHARS = 20000;
+/** The four fields of the statusline's `context_usage` this endpoint reports. */
+export interface ContextUsage {
+    used: number;
+    window: number;
+    ratio: number;
+    estimated: boolean;
+}
+export interface ContextPayloadInput {
+    session: string;
+    view: SessionContextView;
+    usage: ContextUsage;
+}
+/**
+ * The frozen 200 body. `counts` describes the payload as SENT (post-cut), so a
+ * client can reconcile every number with what it received.
+ */
+export declare function contextPayload(input: ContextPayloadInput): Record<string, unknown>;

package/dist/handlers/context-shape.js

@@ -0,0 +1,59 @@
+/**
+ * `GET /api/sessions/{id}/context` response shaping (W725).
+ *
+ * The only transformation applied here is the wire-size guard the contract
+ * freezes: a single entry longer than [MAX_ENTRY_CHARS] is cut and MARKED, and
+ * the top-level `truncated` reports whether anything was cut — a silently
+ * shortened prompt would make the viewer lie about what the model saw.
+ *
+ * `context` reuses the statusline's existing口径 (`context_usage`): the REAL
+ * prompt-token count once a usage frame has been seen (`estimated:false`), else
+ * the session log's character estimate (`estimated:true`). There is no second
+ * accounting path for this endpoint.
+ */
+/** Per-entry character cap (contract): one entry never travels longer. */
+export const MAX_ENTRY_CHARS = 20_000;
+/** Cut one entry to the cap; `truncated` says whether anything was dropped. */
+function cut(text) {
+    if (text.length <= MAX_ENTRY_CHARS)
+        return { text, truncated: false };
+    return { text: text.slice(0, MAX_ENTRY_CHARS), truncated: true };
+}
+function messageJson(message) {
+    const body = cut(message.content);
+    return {
+        role: message.role,
+        content: body.text,
+        ...(message.tool_name === undefined ? {} : { tool_name: message.tool_name }),
+        ...(message.tool_call_id === undefined ? {} : { tool_call_id: message.tool_call_id }),
+        ...(body.truncated ? { truncated: true } : {}),
+    };
+}
+/**
+ * The frozen 200 body. `counts` describes the payload as SENT (post-cut), so a
+ * client can reconcile every number with what it received.
+ */
+export function contextPayload(input) {
+    const system = cut(input.view.system);
+    const messages = input.view.messages.map(messageJson);
+    return {
+        ok: true,
+        session: input.session,
+        model: input.view.model,
+        system: system.text,
+        tools: input.view.tools.map((tool) => ({ name: tool.name, description: tool.description, parameters: tool.parameters })),
+        messages,
+        counts: {
+            system_chars: system.text.length,
+            tool_count: input.view.tools.length,
+            message_count: messages.length,
+        },
+        context: {
+            used: input.usage.used,
+            window: input.usage.window,
+            ratio: input.usage.ratio,
+            estimated: input.usage.estimated,
+        },
+        truncated: system.truncated || messages.some((message) => message["truncated"] === true),
+    };
+}

package/dist/handlers/dialog.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Dialog endpoints — `GET /api/events` (SSE), `POST /api/turn`,
+ * `POST /api/cancel`, `POST /api/clear`.
+ *
+ * W513 session-scoped behaviour:
+ *   - `/api/turn` targets `{session}` (default = active session) and NEVER 409s
+ *     because of a busy session: a running turn takes the input as an
+ *     interjection injected at its next step boundary, and the response says so
+ *     (`{ok:true, injected:true, turn}`). A 409 survives only for the atomic
+ *     re-check race, and only for the target session;
+ *   - `/api/cancel` and `/api/clear` take the same optional `{session}`;
+ *   - `/api/events` streams every session by default (the envelope carries
+ *     `session`), and `?session=<id>` (repeatable) narrows the server side.
+ *
+ * `/api/turn` returns immediately; everything else travels over SSE. The SSE
+ * stream never closes on overflow: a slow subscriber gets ONE `status:lagged`
+ * frame (with the session and the dropped count) and keeps consuming.
+ */
+import type { Hono } from "hono";
+import type { RouteTable } from "../routes.js";
+import { type Deps } from "./common.js";
+export declare function registerDialog(app: Hono, deps: Deps, table: RouteTable): string[];

package/dist/handlers/dialog.js

@@ -0,0 +1,292 @@
+/**
+ * Dialog endpoints — `GET /api/events` (SSE), `POST /api/turn`,
+ * `POST /api/cancel`, `POST /api/clear`.
+ *
+ * W513 session-scoped behaviour:
+ *   - `/api/turn` targets `{session}` (default = active session) and NEVER 409s
+ *     because of a busy session: a running turn takes the input as an
+ *     interjection injected at its next step boundary, and the response says so
+ *     (`{ok:true, injected:true, turn}`). A 409 survives only for the atomic
+ *     re-check race, and only for the target session;
+ *   - `/api/cancel` and `/api/clear` take the same optional `{session}`;
+ *   - `/api/events` streams every session by default (the envelope carries
+ *     `session`), and `?session=<id>` (repeatable) narrows the server side.
+ *
+ * `/api/turn` returns immediately; everything else travels over SSE. The SSE
+ * stream never closes on overflow: a slow subscriber gets ONE `status:lagged`
+ * frame (with the session and the dropped count) and keeps consuming.
+ */
+import { join } from "node:path";
+import { streamSSE } from "hono/streaming";
+import { TurnBusyError } from "@celestea/runtime";
+import { ATTACHMENTS_DIRNAME, createAttachmentStore } from "@celestea/tools";
+import { CapacityError } from "../runtime-adapter.js";
+import { activeSession, capacityJson, errorOnly, failJson, readJsonBody, storeFail, strField } from "./common.js";
+function registerEvents(app, deps, table) {
+    const events = table.get("get_events");
+    app.on(events.method, events.honoPath, (c) => {
+        const asked = c.req.queries("session") ?? [];
+        const response = streamSSE(c, async (stream) => {
+            const sub = deps.bus.subscribe(asked.length === 0 ? {} : { sessions: asked });
+            stream.onAbort(() => sub.close());
+            try {
+                for (;;) {
+                    const frame = await sub.next();
+                    if (frame === null)
+                        break;
+                    await stream.writeSSE({ event: frame.event, data: JSON.stringify(frame.envelope) });
+                }
+            }
+            finally {
+                sub.close();
+            }
+        });
+        response.headers.set("cache-control", "no-cache");
+        return response;
+    });
+    return events.id;
+}
+/** W866: the engine-memory worker session prefix (`worker:<sid>`). */
+const WORKER_SESSION_PREFIX = "worker:";
+/**
+ * W866: the inner session id of an engine-memory worker target, else null.
+ *
+ * A worker conversation lives in its owner session's `WorkerRegistry`, not on
+ * disk: `sessions.require("worker:…")` can only 404 it. Recognising the prefix
+ * HERE is what lets a USER message take the worker route instead of the
+ * filesystem-session route (parity with the DSH-side `worker:<sid>` ids the UI
+ * already lists and renders).
+ */
+function workerSidOf(asked) {
+    if (typeof asked !== "string" || !asked.startsWith(WORKER_SESSION_PREFIX))
+        return null;
+    const sid = asked.slice(WORKER_SESSION_PREFIX.length);
+    return sid === "" ? null : sid;
+}
+/**
+ * W866: deliver one USER message to an engine-memory worker session.
+ *
+ * The delivery itself is the SAME `send_message` tool the model calls (the
+ * worker driver serialises mailbox arrivals into its own turns), so the user
+ * path and the model path cannot drift. Two deliberate refusals before that:
+ * images (the mailbox carries text only) and unknown/settled workers (a message
+ * queued for a worker nobody drives would report success and never be processed).
+ */
+async function workerTurn(c, deps, sid, text, rawAttachments) {
+    if (Array.isArray(rawAttachments) && rawAttachments.length > 0) {
+        return failJson(c, 400, "worker sessions accept text only");
+    }
+    if (text === "")
+        return errorOnly(c, 400, "input must not be empty");
+    const id = WORKER_SESSION_PREFIX + sid;
+    const row = deps.runtime.workerSessions().find((w) => w.id === id);
+    if (row === undefined)
+        return failJson(c, 404, `unknown session '${id}'`);
+    const out = await deps.runtime.workerSend({ target: sid, content: text });
+    if (out["ok"] !== true) {
+        return failJson(c, 404, String(out["error"] ?? `unknown session '${id}'`));
+    }
+    // `status`/`state` let the client say whether the worker is still RUNNING
+    // (idle/in-turn) or settled — the one fact the delivery envelope does not carry.
+    return c.json({
+        ok: true,
+        delivered: true,
+        injected: false,
+        pending: 0,
+        placement: "context",
+        worker: sid,
+        status: row.status ?? "",
+        state: row.state ?? "",
+    });
+}
+/** The turn target: an explicit `{session}`, else the active session. */
+function turnTarget(c, deps, asked) {
+    if (asked === undefined || asked === "")
+        return { ok: true, value: activeSession(deps) };
+    const required = deps.sessions.require(asked);
+    if (!required.ok)
+        return required;
+    return { ok: true, value: required.value.id };
+}
+/** W804: the inline attachments one POST /api/turn may carry (section 7.4 P0). */
+const MAX_TURN_ATTACHMENTS = 20;
+/**
+ * Decode the optional inline base64 `attachments` and store them under
+ * `<session-dir>/attachments/`. P0 adds NO upload endpoint: the bytes ride the
+ * turn body and the session log only ever sees the returned references.
+ */
+async function storeTurnAttachments(c, deps, session, raw) {
+    if (raw === undefined || raw === null)
+        return { ok: true, refs: [] };
+    if (!Array.isArray(raw))
+        return { ok: false, response: errorOnly(c, 400, "attachments must be an array") };
+    if (raw.length === 0)
+        return { ok: true, refs: [] };
+    if (raw.length > MAX_TURN_ATTACHMENTS) {
+        return { ok: false, response: errorOnly(c, 400, `too many attachments (max ${MAX_TURN_ATTACHMENTS})`) };
+    }
+    const resolved = session === null ? null : deps.sessions.resolve(session);
+    const dir = resolved !== null && resolved.ok ? resolved.value.dir : null;
+    if (dir === null)
+        return { ok: false, response: errorOnly(c, 400, "attachments require a resolvable session directory") };
+    const store = createAttachmentStore(join(dir, ATTACHMENTS_DIRNAME));
+    const refs = [];
+    for (const item of raw) {
+        const rec = (typeof item === "object" && item !== null ? item : {});
+        const data = rec["data"];
+        const name = typeof rec["name"] === "string" ? rec["name"] : undefined;
+        if (typeof data !== "string" || data.trim() === "") {
+            return { ok: false, response: errorOnly(c, 400, "each attachment needs a non-empty base64 data string") };
+        }
+        const bytes = Buffer.from(data, "base64");
+        if (bytes.length === 0)
+            return { ok: false, response: errorOnly(c, 400, "attachment data decoded to zero bytes") };
+        try {
+            refs.push(await store.put({ bytes, ...(name === undefined ? {} : { name }) }));
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            return { ok: false, response: errorOnly(c, 400, `attachment rejected: ${message}`) };
+        }
+    }
+    return { ok: true, refs };
+}
+function registerTurn(app, deps, table) {
+    const turn = table.get("post_turn");
+    app.on(turn.method, turn.honoPath, async (c) => {
+        const read = await readJsonBody(c);
+        if (!read.ok)
+            return read.response;
+        const input = strField(c, read.body, "input");
+        const asked = strField(c, read.body, "session");
+        for (const field of [input, asked])
+            if (!field.ok)
+                return field.response;
+        // W847: resolve + validate the delivery lane BEFORE anything is written, so
+        // an illegal mode never leaves an attachment (or a stored turn) behind. An
+        // omitted mode is "steer" — byte-identical to the pre-W847 request.
+        const requestedMode = read.body["mode"];
+        if (requestedMode !== undefined && requestedMode !== null && requestedMode !== "steer" && requestedMode !== "queue") {
+            return failJson(c, 400, 'invalid mode: ' + String(requestedMode) + ' (expected "steer" or "queue")');
+        }
+        const mode = requestedMode === "queue" ? "queue" : "steer";
+        const text = (input.ok ? (input.value ?? "") : "").trim();
+        // W866: an engine-memory worker session (`worker:<sid>`) is NOT a filesystem
+        // session — `turnTarget` could only 404 it, and `startTurn`/`inject` would
+        // compose a ghost runtime for the id (the W833 bug). A user message to a
+        // worker takes the worker route before any of that.
+        const workerSid = workerSidOf(asked.ok ? asked.value : undefined);
+        if (workerSid !== null)
+            return workerTurn(c, deps, workerSid, text, read.body["attachments"]);
+        const target = turnTarget(c, deps, asked.ok ? asked.value : undefined);
+        if (!target.ok)
+            return storeFail(c, target);
+        const session = target.value;
+        // W804: decode + store the optional inline image attachments BEFORE the
+        // empty-input check — a turn may legitimately carry images and no text.
+        // W815-4: a busy session REFUSES image attachments (steering lanes carry
+        // text only), so refuse BEFORE `storeTurnAttachments` writes anything under
+        // <session>/attachments/ — the old order wrote up to 20 * 4 MiB and only then
+        // 409'd, leaking every byte for a turn that was never started.
+        const rawAttachments = read.body["attachments"];
+        if (deps.runtime.isBusy(session) && Array.isArray(rawAttachments) && rawAttachments.length > 0) {
+            return busyAttachmentError(c);
+        }
+        const stored = await storeTurnAttachments(c, deps, session, rawAttachments);
+        if (!stored.ok)
+            return stored.response;
+        const attachments = stored.refs;
+        if (text === "" && attachments.length === 0)
+            return errorOnly(c, 400, "input must not be empty");
+        if (deps.runtime.isBusy(session)) {
+            // W513 steering lanes carry TEXT only: an image must never be silently
+            // dropped, so a busy session refuses rather than pretends.
+            if (attachments.length > 0)
+                return busyAttachmentError(c);
+            return injectInto(c, deps, text, session, mode);
+        }
+        try {
+            const started = await deps.runtime.startTurn({
+                input: text,
+                session,
+                ...(attachments.length === 0 ? {} : { attachments }),
+            });
+            // W515 §2: the turn's own input IS the context the model sees first.
+            return c.json({ turn: started.turn, status: "started", placement: started.placement ?? "context" }, 202);
+        }
+        catch (e) {
+            if (e instanceof TurnBusyError) {
+                if (attachments.length > 0)
+                    return busyAttachmentError(c);
+                return injectInto(c, deps, text, session, mode);
+            }
+            if (e instanceof CapacityError)
+                return capacityJson(c, e);
+            return failJson(c, 500, e instanceof Error ? e.message : String(e));
+        }
+    });
+    return turn.id;
+}
+/** W804: the running-turn refusal (steering cannot carry an image). */
+function busyAttachmentError(c) {
+    return failJson(c, 409, "attachments cannot be injected into a running turn; send them when the turn finishes");
+}
+/**
+ * W513/W847: the session is busy -> the input joins a lane. `mode` = "steer"
+ * injects into the RUNNING turn at its next step boundary; "queue" parks it for
+ * the next turn start. The response shape is unchanged (the caller reads
+ * `placement`, not `injected`, to render the terminal state).
+ */
+function injectInto(c, deps, text, session, mode) {
+    const out = deps.runtime.inject({ input: text, session, mode });
+    return c.json({ ok: true, injected: out.injected, turn: out.turn, pending: out.pending, placement: out.placement, duplicate: out.duplicate });
+}
+async function bodySession(c, deps) {
+    const read = await readJsonBody(c, false);
+    if (!read.ok)
+        return { ok: false, response: read.response };
+    const asked = strField(c, read.body, "session");
+    if (!asked.ok)
+        return { ok: false, response: asked.response };
+    const target = turnTarget(c, deps, asked.value);
+    if (!target.ok)
+        return { ok: false, response: storeFail(c, target) };
+    return { ok: true, session: target.value };
+}
+function registerCancel(app, deps, table) {
+    const cancel = table.get("post_cancel");
+    app.on(cancel.method, cancel.honoPath, async (c) => {
+        const target = await bodySession(c, deps);
+        if (!target.ok)
+            return target.response;
+        return c.json({ ok: true, cancelled: deps.runtime.cancel(target.session) });
+    });
+    return cancel.id;
+}
+function registerClear(app, deps, table) {
+    const clear = table.get("post_clear");
+    app.on(clear.method, clear.honoPath, async (c) => {
+        const target = await bodySession(c, deps);
+        if (!target.ok)
+            return target.response;
+        const session = target.session;
+        try {
+            await deps.runtime.clear(session);
+        }
+        catch (e) {
+            if (e instanceof TurnBusyError)
+                return failJson(c, 409, "a turn is already running");
+            return failJson(c, 500, e instanceof Error ? e.message : String(e));
+        }
+        if (session !== null) {
+            const resolved = deps.sessions.resolve(session);
+            if (resolved.ok)
+                deps.sessions.truncate(resolved.value);
+        }
+        return c.json({ ok: true, cleared: true, session });
+    });
+    return clear.id;
+}
+export function registerDialog(app, deps, table) {
+    return [registerEvents(app, deps, table), registerTurn(app, deps, table), registerCancel(app, deps, table), registerClear(app, deps, table)];
+}

package/dist/handlers/exec.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `POST /api/exec` (iteration G2) — run a shell command NOW, with no model in
+ * the loop. `/run <cmd>` and `!<cmd>` are the UI's callers.
+ *
+ * Three rules from `docs/iteration-g-workbench.md` §1:
+ *   1. it reuses the run_shell execution path — the SAME `selectSandboxDetailed`
+ *      policy, `sessionSandboxConfig` (workdir/root), `sanitizedEnv` allowlist
+ *      and output cap the engine's `run_shell` uses, so isolation cannot fork;
+ *   2. it passes the PERMISSION gate: a preset that denies `run_shell`, or a
+ *      sandbox policy that refuses to execute, is a structured refusal — never a
+ *      silent run;
+ *   3. it is NOT a tool: nothing here touches the model-visible tool face.
+ *
+ * The `sandbox` block carries ONLY the contract fields (provider / net_isolated
+ * / tmp_private / seccomp + optional cpu_sec), never host diagnostics.
+ */
+import type { Hono } from "hono";
+import type { RouteTable } from "../routes.js";
+import { type Deps } from "./common.js";
+/** The structured refusal when this session's preset denies the shell. */
+export declare const SHELL_DENIED_CODE = "shell_denied";
+export declare function registerExec(app: Hono, deps: Deps, table: RouteTable): string[];