@rynx-ai/server 0.1.0

package/dist/control-api.js

@@ -0,0 +1,834 @@
+/**
+ * Control-plane HTTP surface: a JSON + SSE API (and the static console) for
+ * managing **channels** (a plugin type + its credentials) and **instances** (a
+ * channel bound to an agent), plus declarative agents. Mounted by
+ * {@link import("./server.js").createApp} only when control deps are injected.
+ *
+ * Channel and instance are separate objects:
+ *  - a **channel** is configured/authorized on its own (`/api/channels` +
+ *    `/api/channels/:id/authorize`); credentials live in its `options`.
+ *  - an **instance** binds a channel to an agent (`/api/instances`); it's what
+ *    the daemon mounts and runs.
+ *
+ * The server is channel-agnostic: available channel *types* (with their declared
+ * config schema / authorize capability) come from {@link ControlPlaneDeps.listChannelTypes},
+ * which the daemon derives from loaded plugins. Plugins themselves are managed
+ * via the CLI, not here. The daemon owns the db-backed mutators (injected as
+ * {@link ControlPlaneDeps}); the server owns the {@link ChannelManager}.
+ */
+import { randomUUID } from "node:crypto";
+import Router from "@koa/router";
+import { agentSpecSchema, newSessionId, persistSessionEvent, skillInstallRecipeSchema, } from "@rynx-ai/core";
+import { ensureCodexResumeRollout } from "@rynx-ai/runtime";
+export function createControlRouter(opts) {
+    const { manager, deps, runtime, sessionBus, sessionLog, runnerManager, sessionStore } = opts;
+    const router = new Router();
+    // claude-native PermissionRequest long-polls: approvalId → resolve the held
+    // hook response with claude's verdict. The hook POST blocks until the web user
+    // answers via `/approvals/:approvalId`, or the hook client disconnects.
+    const claudeApprovals = new Map();
+    /** The instance (if any) bound to a channel — used to reload after a config change. */
+    const instanceForChannel = (channelId) => deps.listInstancesConfig().find((i) => i.channelId === channelId);
+    router.get("/api/meta", (ctx) => {
+        const meta = {
+            channelTypes: deps.listChannelTypes().map((t) => t.type),
+        };
+        ctx.body = meta;
+    });
+    router.get("/api/channel-types", (ctx) => {
+        ctx.body = { channelTypes: deps.listChannelTypes() };
+    });
+    // ── channels ───────────────────────────────────────────────────────────
+    router.get("/api/channels", (ctx) => {
+        ctx.body = {
+            channels: deps.listChannels().map((c) => ({
+                id: c.id,
+                name: c.name,
+                type: c.type,
+                options: redact(deps, c.type, c.options),
+            })),
+        };
+    });
+    router.post("/api/channels", async (ctx) => {
+        const body = await readJson(ctx);
+        const name = asString(body.name);
+        const type = asString(body.type);
+        if (!name)
+            return bad(ctx, "missing channel name");
+        if (!type)
+            return bad(ctx, "missing channel type");
+        const { id } = deps.createChannel({ name, type, options: asRecord(body.options) });
+        ctx.body = { ok: true, id };
+    });
+    router.put("/api/channels/:id", async (ctx) => {
+        const id = ctx.params.id;
+        const body = await readJson(ctx);
+        deps.setChannel(id, {
+            ...(body.name !== undefined ? { name: asString(body.name) } : {}),
+            ...(body.options !== undefined ? { options: asRecord(body.options) } : {}),
+        });
+        const bound = instanceForChannel(id);
+        if (bound)
+            await manager.reloadInstance(bound.id);
+        ctx.body = { ok: true };
+    });
+    router.delete("/api/channels/:id", async (ctx) => {
+        const id = ctx.params.id;
+        const bound = instanceForChannel(id);
+        if (bound)
+            await manager.stopInstance(bound.id); // its row cascades on channel delete
+        deps.removeChannel(id);
+        ctx.body = { ok: true };
+    });
+    // Authorize (config mode 2): run the channel type's flow over SSE, persist the
+    // resolved options on the channel, reload the bound instance (if any).
+    router.post("/api/channels/:id/authorize", async (ctx) => {
+        const id = ctx.params.id;
+        const channel = deps.listChannels().find((c) => c.id === id);
+        if (!channel)
+            return notFound(ctx, "channel not found");
+        await streamEvents(ctx, async (send, signal) => {
+            send("status", { text: `authorizing ${channel.type}…` });
+            const options = await deps.authorizeChannel(channel.type, (m) => send(m.kind, m), signal);
+            deps.setChannel(id, { options });
+            const bound = instanceForChannel(id);
+            if (bound)
+                await manager.reloadInstance(bound.id);
+            send("done", { id });
+        });
+    });
+    // ── instances ──────────────────────────────────────────────────────────
+    router.get("/api/instances", (ctx) => {
+        const statuses = new Map(manager.list().map((status) => [status.instanceId, status]));
+        const instances = deps.listInstancesConfig().map((inst) => {
+            const status = statuses.get(inst.id);
+            return {
+                id: inst.id,
+                channelId: inst.channelId,
+                channelName: inst.channelName,
+                type: inst.type,
+                agent: inst.agent,
+                enabled: inst.enabled,
+                running: status?.running ?? false,
+                connected: status?.connected ?? null,
+                lastError: status?.lastError ?? null,
+                lastEventAt: status?.lastEventAt ?? null,
+            };
+        });
+        ctx.body = { instances };
+    });
+    router.post("/api/instances", async (ctx) => {
+        const body = await readJson(ctx);
+        const channelId = asString(body.channelId);
+        if (!channelId)
+            return bad(ctx, "missing channelId");
+        let id;
+        try {
+            ({ id } = deps.createInstance({ channelId, agent: asString(body.agent) }));
+        }
+        catch (error) {
+            return bad(ctx, error instanceof Error ? error.message : String(error));
+        }
+        await manager.reloadInstance(id);
+        ctx.body = { ok: true, id };
+    });
+    router.put("/api/instances/:id", async (ctx) => {
+        const id = ctx.params.id;
+        const body = await readJson(ctx);
+        deps.setInstance(id, {
+            ...(body.agent !== undefined ? { agent: asString(body.agent) } : {}),
+            ...(body.enabled !== undefined ? { enabled: Boolean(body.enabled) } : {}),
+        });
+        await manager.reloadInstance(id);
+        ctx.body = { ok: true };
+    });
+    router.post("/api/instances/:id/enable", async (ctx) => {
+        const id = ctx.params.id;
+        deps.setInstance(id, { enabled: true });
+        await manager.startInstance(id);
+        ctx.body = { ok: true };
+    });
+    router.post("/api/instances/:id/disable", async (ctx) => {
+        const id = ctx.params.id;
+        deps.setInstance(id, { enabled: false });
+        await manager.stopInstance(id);
+        ctx.body = { ok: true };
+    });
+    router.post("/api/instances/:id/restart", async (ctx) => {
+        await manager.reloadInstance(ctx.params.id);
+        ctx.body = { ok: true };
+    });
+    router.delete("/api/instances/:id", async (ctx) => {
+        const id = ctx.params.id;
+        await manager.stopInstance(id);
+        deps.removeInstance(id);
+        ctx.body = { ok: true };
+    });
+    // ── agents ─────────────────────────────────────────────────────────────
+    router.get("/api/agents", async (ctx) => {
+        ctx.body = { agents: await deps.listAgents() };
+    });
+    router.get("/api/agents/:id", async (ctx) => {
+        const spec = await deps.getAgent(ctx.params.id);
+        if (!spec)
+            return notFound(ctx, "agent not found");
+        ctx.body = spec;
+    });
+    router.post("/api/agents", async (ctx) => {
+        const body = await readJson(ctx);
+        const id = asString(body.id);
+        if (!id)
+            return bad(ctx, "missing agent id");
+        try {
+            deps.writeAgent(id, body);
+        }
+        catch (error) {
+            return bad(ctx, error instanceof Error ? error.message : String(error));
+        }
+        ctx.body = { ok: true };
+    });
+    router.delete("/api/agents/:id", (ctx) => {
+        ctx.body = { ok: deps.removeAgent(ctx.params.id) };
+    });
+    // ── skills catalog (global, ~/.rynx/skills) ──────────────────────────────
+    router.get("/api/skills", async (ctx) => {
+        ctx.body = { skills: await deps.listSkills() };
+    });
+    router.get("/api/skills/:name/file", async (ctx) => {
+        const file = asString(ctx.query.path);
+        if (!file)
+            return bad(ctx, "missing path");
+        try {
+            ctx.body = await deps.readSkillFile(ctx.params.name, file);
+        }
+        catch (error) {
+            return bad(ctx, error instanceof Error ? error.message : String(error));
+        }
+    });
+    router.get("/api/skills/:name", async (ctx) => {
+        const detail = await deps.getSkill(ctx.params.name);
+        if (!detail)
+            return notFound(ctx, "skill not found");
+        ctx.body = detail;
+    });
+    router.post("/api/skills", async (ctx) => {
+        // The body is a full SkillInstallRecipe — the same object a receipt records
+        // and a SkillRef declares. Adding a new install method never changes this API.
+        const body = await readJson(ctx);
+        const recipe = skillInstallRecipeSchema.safeParse(body);
+        if (!recipe.success) {
+            return bad(ctx, `invalid install recipe: ${recipe.error.issues.map((i) => i.message).join("; ")}`);
+        }
+        try {
+            ctx.body = { skills: await deps.installSkill(recipe.data) };
+        }
+        catch (error) {
+            return bad(ctx, error instanceof Error ? error.message : String(error));
+        }
+    });
+    router.delete("/api/skills/:name", async (ctx) => {
+        try {
+            ctx.body = { ok: await deps.removeSkill(ctx.params.name) };
+        }
+        catch (error) {
+            return bad(ctx, error instanceof Error ? error.message : String(error));
+        }
+    });
+    router.get("/api/logs", async (ctx) => {
+        const instance = asString(ctx.query.instance);
+        const lines = Number(ctx.query.lines) || 200;
+        ctx.body = { logs: await deps.tailLogs(instance, lines) };
+    });
+    // ── emulator proxy ───────────────────────────────────────────────────────
+    // These endpoints deliberately live in the daemon/control process. Sandboxed
+    // agent children can call localhost while daemon owns macOS CoreSimulator/adb.
+    const emulatorOr404 = (ctx) => {
+        if (!deps.emulator) {
+            notFound(ctx, "emulator API is not available on this server");
+            return null;
+        }
+        return deps.emulator;
+    };
+    const emulatorResult = async (ctx, run) => {
+        const emulator = emulatorOr404(ctx);
+        if (!emulator)
+            return;
+        try {
+            ctx.body = await run(emulator);
+        }
+        catch (error) {
+            bad(ctx, error instanceof Error ? error.message : String(error));
+        }
+    };
+    // Per-session device scoping (orca's per-worktree active emulator, keyed by
+    // rynx session id riding the `x-rynx-session` header): an attach from a
+    // session binds it to the attached device; later session commands without an
+    // explicit `device` resolve against the binding. Sharing is allowed (N
+    // sessions → one device); explicit `device` always wins; sessions without a
+    // binding fall back to the global active. In-memory by design: on a daemon
+    // restart agents just re-attach (the skill mandates attach-before-use).
+    const emulatorSessionDevices = new Map();
+    const emulatorSessionOf = (ctx) => ctx.get("x-rynx-session")?.trim() || undefined;
+    const emulatorScopedDevice = (ctx, body) => {
+        const explicit = asString(body.device);
+        if (explicit)
+            return explicit;
+        const sessionId = emulatorSessionOf(ctx);
+        return sessionId ? emulatorSessionDevices.get(sessionId) : undefined;
+    };
+    const emulatorUnbindDevice = (device) => {
+        for (const [sessionId, bound] of emulatorSessionDevices) {
+            if (bound === device)
+                emulatorSessionDevices.delete(sessionId);
+        }
+    };
+    router.get("/api/emulator/doctor", async (ctx) => {
+        await emulatorResult(ctx, (emulator) => emulator.doctor());
+    });
+    router.get("/api/emulator/devices", async (ctx) => {
+        await emulatorResult(ctx, async (emulator) => ({ devices: await emulator.devices() }));
+    });
+    router.get("/api/emulator/active", async (ctx) => {
+        await emulatorResult(ctx, async (emulator) => {
+            const device = emulatorScopedDevice(ctx, {});
+            if (device && emulator.deviceSession) {
+                return { active: await emulator.deviceSession({ device }) };
+            }
+            return { active: await emulator.active() };
+        });
+    });
+    router.post("/api/emulator/attach", async (ctx) => {
+        const body = await readJson(ctx);
+        const sessionId = emulatorSessionOf(ctx);
+        await emulatorResult(ctx, async (emulator) => {
+            const session = (await emulator.attach(asString(body.device)));
+            if (sessionId && typeof session?.deviceUdid === "string") {
+                emulatorSessionDevices.set(sessionId, session.deviceUdid);
+            }
+            return session;
+        });
+    });
+    router.post("/api/emulator/tap", async (ctx) => {
+        const body = await readJson(ctx);
+        const x = asNumber(body.x);
+        const y = asNumber(body.y);
+        if (x == null || y == null)
+            return bad(ctx, "tap requires numeric x and y");
+        await emulatorResult(ctx, (emulator) => emulator.tap({ x, y, device: emulatorScopedDevice(ctx, body) }));
+    });
+    router.post("/api/emulator/type", async (ctx) => {
+        const body = await readJson(ctx);
+        const text = asString(body.text);
+        if (!text)
+            return bad(ctx, "type requires text");
+        await emulatorResult(ctx, (emulator) => emulator.type({ text, device: emulatorScopedDevice(ctx, body), mode: asString(body.mode) }));
+    });
+    router.post("/api/emulator/button", async (ctx) => {
+        const body = await readJson(ctx);
+        await emulatorResult(ctx, (emulator) => emulator.button({ name: asString(body.name), device: emulatorScopedDevice(ctx, body) }));
+    });
+    router.post("/api/emulator/rotate", async (ctx) => {
+        const body = await readJson(ctx);
+        const orientation = asString(body.orientation);
+        if (!orientation)
+            return bad(ctx, "rotate requires orientation");
+        await emulatorResult(ctx, (emulator) => emulator.rotate({ orientation, device: emulatorScopedDevice(ctx, body) }));
+    });
+    router.post("/api/emulator/launch", async (ctx) => {
+        const body = await readJson(ctx);
+        const appId = asString(body.appId) ?? asString(body.bundleId) ?? asString(body.packageName);
+        if (!appId)
+            return bad(ctx, "launch requires appId");
+        await emulatorResult(ctx, (emulator) => emulator.launch({ appId, device: emulatorScopedDevice(ctx, body) }));
+    });
+    router.post("/api/emulator/gesture", async (ctx) => {
+        const body = await readJson(ctx);
+        const points = body.points;
+        if (!Array.isArray(points))
+            return bad(ctx, "gesture requires points");
+        await emulatorResult(ctx, (emulator) => emulator.gesture({ points, device: emulatorScopedDevice(ctx, body) }));
+    });
+    router.post("/api/emulator/exec", async (ctx) => {
+        const body = await readJson(ctx);
+        const command = asString(body.command);
+        if (!command)
+            return bad(ctx, "exec requires command");
+        await emulatorResult(ctx, (emulator) => emulator.exec({ command, device: emulatorScopedDevice(ctx, body) }));
+    });
+    router.post("/api/emulator/screenshot", async (ctx) => {
+        const body = await readJson(ctx);
+        await emulatorResult(ctx, (emulator) => emulator.screenshot({ device: emulatorScopedDevice(ctx, body), out: asString(body.out) }));
+    });
+    router.get("/api/emulator/frame", async (ctx) => {
+        const emulator = emulatorOr404(ctx);
+        if (!emulator)
+            return;
+        if (!emulator.frame) {
+            return notFound(ctx, "emulator frame API is not available on this server");
+        }
+        const body = { device: asString(ctx.query.device) };
+        try {
+            const frame = await emulator.frame({ device: emulatorScopedDevice(ctx, body) });
+            ctx.type = frame.contentType;
+            ctx.set("Cache-Control", "no-store");
+            ctx.body = frame.data;
+        }
+        catch (error) {
+            bad(ctx, error instanceof Error ? error.message : String(error));
+        }
+    });
+    router.get("/api/emulator/video", async (ctx) => {
+        const emulator = emulatorOr404(ctx);
+        if (!emulator)
+            return;
+        if (!emulator.video) {
+            return notFound(ctx, "emulator video API is not available on this server");
+        }
+        const body = { device: asString(ctx.query.device) };
+        try {
+            const video = await emulator.video({ device: emulatorScopedDevice(ctx, body) });
+            let stopped = false;
+            const stop = () => {
+                if (stopped)
+                    return;
+                stopped = true;
+                video.stop();
+            };
+            ctx.respond = false;
+            const res = ctx.res;
+            res.statusCode = 200;
+            res.setHeader("Content-Type", video.contentType);
+            res.setHeader("Cache-Control", "no-store");
+            res.setHeader("X-Content-Type-Options", "nosniff");
+            res.on("close", stop);
+            video.stream.on("end", stop);
+            video.stream.on("error", (error) => {
+                stop();
+                if (!res.destroyed)
+                    res.destroy(error);
+            });
+            video.stream.pipe(res);
+        }
+        catch (error) {
+            bad(ctx, error instanceof Error ? error.message : String(error));
+        }
+    });
+    router.get("/api/emulator/screenshot-file", async (ctx) => {
+        const emulator = emulatorOr404(ctx);
+        if (!emulator)
+            return;
+        if (!emulator.readScreenshotFile) {
+            return notFound(ctx, "screenshot file API is not available on this server");
+        }
+        const file = asString(ctx.query.file);
+        if (!file)
+            return bad(ctx, "missing file");
+        try {
+            const image = await emulator.readScreenshotFile({ file });
+            if (!image)
+                return notFound(ctx, "screenshot not found");
+            ctx.type = image.contentType;
+            ctx.set("Cache-Control", "private, max-age=300");
+            ctx.body = image.data;
+        }
+        catch (error) {
+            bad(ctx, error instanceof Error ? error.message : String(error));
+        }
+    });
+    router.post("/api/emulator/kill", async (ctx) => {
+        const body = await readJson(ctx);
+        await emulatorResult(ctx, async (emulator) => {
+            const result = (await emulator.kill({ device: emulatorScopedDevice(ctx, body) }));
+            if (typeof result?.device === "string")
+                emulatorUnbindDevice(result.device);
+            return result;
+        });
+    });
+    router.post("/api/emulator/shutdown", async (ctx) => {
+        const body = await readJson(ctx);
+        await emulatorResult(ctx, async (emulator) => {
+            const result = (await emulator.shutdown({ device: emulatorScopedDevice(ctx, body) }));
+            if (typeof result?.device === "string")
+                emulatorUnbindDevice(result.device);
+            return result;
+        });
+    });
+    // ── sessions (channel-agnostic agent runs) ───────────────────────────────
+    // Create a session bound to a preset agent (`agent`) or an inline spec
+    // (`config`, the config-driven / remote-ready path), then drive it with
+    // messages over SSE. omnigent-style: create carries no message.
+    // One unified list: every session is a machine-session record. The registry
+    // (console + every channel) supplies identity — `source` is a plain field, not
+    // parsed from the id — and the canonical log supplies recency. A legacy session
+    // present only in the log (pre-migration) lists with source "unknown". Every
+    // session is observable, replayable, and continuable the same way.
+    router.get("/api/sessions", async (ctx) => {
+        const metaById = new Map(deps.listSessionMetas().map((m) => [m.id, m]));
+        const logged = sessionLog ? await sessionLog.listSessions() : [];
+        const logById = new Map(logged.map((s) => [s.sessionId, s]));
+        const ids = new Set([...metaById.keys(), ...logById.keys()]);
+        const sessions = [...ids].map((id) => {
+            const meta = metaById.get(id);
+            const log = logById.get(id);
+            const createdAt = meta?.createdAt ?? new Date(log?.createdAt ?? Date.now()).toISOString();
+            const updatedAt = log ? new Date(log.updatedAt).toISOString() : (meta?.updatedAt ?? createdAt);
+            return {
+                id,
+                agent: meta?.agent,
+                title: meta?.title,
+                status: "idle",
+                createdAt,
+                updatedAt,
+                source: meta?.source ?? "unknown",
+            };
+        });
+        sessions.sort((a, b) => (b.updatedAt ?? b.createdAt).localeCompare(a.updatedAt ?? a.createdAt));
+        ctx.body = { sessions };
+    });
+    router.post("/api/sessions", async (ctx) => {
+        if (!runtime)
+            return bad(ctx, "session runs are not available on this server");
+        const body = await readJson(ctx);
+        const agent = asString(body.agent);
+        let config;
+        if (body.config != null) {
+            const parsed = agentSpecSchema.safeParse(body.config);
+            if (!parsed.success) {
+                return bad(ctx, `invalid config: ${parsed.error.issues.map((i) => i.message).join("; ")}`);
+            }
+            config = parsed.data;
+        }
+        if (!agent && !config)
+            return bad(ctx, "provide an agent id or an inline config");
+        const id = newSessionId();
+        deps.createSessionMeta({
+            id,
+            source: "console",
+            agent,
+            config,
+            model: asString(body.model),
+            reasoningEffort: asString(body.reasoningEffort),
+            title: asString(body.title),
+            createdAt: new Date().toISOString(),
+        });
+        ctx.body = { sessionId: id };
+    });
+    router.post("/api/sessions/:id/messages", async (ctx) => {
+        const id = ctx.params.id;
+        if (!runtime)
+            return bad(ctx, "session runs are not available on this server");
+        const body = await readJson(ctx);
+        const message = asString(body.message);
+        if (!message)
+            return bad(ctx, "missing message");
+        const meta = deps.getSessionMeta(id);
+        // A console session carries its agent/config inline. Any other session — a
+        // channel session, or one only in the canonical log — resumes on the runtime
+        // binding recorded in the shared store (its original runtime/model/cwd). The
+        // turn lands in the same canonical log + LLM session, so the channel sees it
+        // in history — but no card is pushed (channels don't subscribe to the bus).
+        const consoleMeta = meta?.source === "console" ? meta : undefined;
+        const bound = consoleMeta ? null : ((await sessionStore?.get(id)) ?? null);
+        if (!meta && !bound)
+            return notFound(ctx, "session not found");
+        // First message names a console session (omnigent-style: the message,
+        // truncated). Channel sessions keep their own title elsewhere — skip.
+        if (consoleMeta && !consoleMeta.title)
+            deps.setSessionTitle(id, synthesizeSessionTitle(message));
+        // codex-native live mode (single writer): bring up the session's persistent
+        // forwarder + TUI, then INJECT this turn into the shared app-server thread
+        // (turn/start | turn/steer) and return immediately. The forwarder mirrors the
+        // output onto the bus; the web renders it from the persistent `/stream`. No
+        // per-`/messages` normalize/persist here — that would double-write the turn.
+        if (runnerManager?.ensureLiveSession && runnerManager.injectMessage) {
+            // Resolve the session's runtime from its agent spec (as the run path does),
+            // so live co-drive picks the right backend PER AGENT — the live path
+            // bypasses ConversationRuntime's own resolution, so without this it would
+            // fall back to the global default and mis-route (e.g. a claude agent onto codex).
+            const liveRuntime = await runtime.resolveRuntime({
+                agentName: consoleMeta?.agent,
+                agentSpec: consoleMeta?.config,
+                provider: bound?.runtime,
+            });
+            // codex RESUME with a missing local rollout (fork / cross-machine): synthesize
+            // one from the session log so the app-server's thread/resume finds it. No-op
+            // when the rollout already exists (the normal single-machine case). The bound
+            // thread record is fetched directly — `bound` above is null for console
+            // sessions, but a console session still resumes a stored codex thread.
+            if (liveRuntime === "codex" && sessionLog) {
+                const codexRecord = await sessionStore?.get(id);
+                if (codexRecord?.codexSessionId) {
+                    ensureCodexResumeRollout({
+                        // `id` (the rynx localThreadId) resolves the per-session CODEX_HOME —
+                        // the SAME id the runner child gets via `RYNX_RUNNER_SESSION`, so the
+                        // synthesized rollout lands where that session's app-server reads.
+                        sessionId: id,
+                        threadId: codexRecord.codexSessionId,
+                        cwd: codexRecord.cwd ?? process.cwd(),
+                        items: await sessionLog.snapshot(id),
+                    });
+                }
+            }
+            const live = await runnerManager.ensureLiveSession(id, {
+                ...(bound?.cwd ? { cwd: bound.cwd } : {}),
+                runtime: liveRuntime,
+                // Carry the agent identity so the live launch applies the agent spec's
+                // model / skills / instructions (not just the runtime). A preset agent
+                // rides its id; an inline-config console session rides its spec.
+                ...(consoleMeta?.agent ? { agentName: consoleMeta.agent } : {}),
+                ...(consoleMeta?.config ? { agentSpec: consoleMeta.config } : {}),
+            });
+            if (!live) {
+                // A live-runtime (codex/claude-native) session whose forwarder couldn't come
+                // up. omnigent reports this as a failure and NEVER falls through to a second
+                // output path — falling through would run+persist the turn while the forwarder
+                // also mirrors it (the double-write). Report + stop.
+                ctx.status = 503;
+                ctx.body = { error: `live session unavailable (${liveRuntime})` };
+                return;
+            }
+            const outcome = await runnerManager.injectMessage(id, message);
+            if (outcome === "injected") {
+                ctx.body = { ok: true, injected: true };
+                return;
+            }
+            // notLive / notReady / failed → hard error. NEVER fall through to run+stream:
+            // the second path would double-write the turn alongside the forwarder
+            // (omnigent: inject failure ⇒ response.failed, no local re-run).
+            ctx.status = 503;
+            ctx.body = { error: `live injection ${outcome}` };
+            return;
+        }
+        // Native-only: a turn can only run on a live runner (codex app-server / claude
+        // TUI). With no runner there is nothing to inject into, and there is no non-live
+        // programmatic fallback (that path was removed) — report + stop.
+        ctx.status = 503;
+        ctx.body = { error: "session runs require a live runner" };
+    });
+    // Stop the session's active turn (the web Stop button). For a live native
+    // session this interrupts the running turn at its source — codex app-server
+    // `turn/interrupt`, or an Escape into the claude pane — which the non-live path
+    // (aborting the streaming POST) cannot do once the turn is injected. Best-effort:
+    // `interrupted:false` when there was no active live turn.
+    router.post("/api/sessions/:id/interrupt", async (ctx) => {
+        const id = ctx.params.id;
+        const interrupted = runnerManager?.interruptLiveSession
+            ? await runnerManager.interruptLiveSession(id)
+            : false;
+        ctx.body = { ok: true, interrupted };
+    });
+    // No meta gate: a channel session (Lark, …) has canonical-log history regardless
+    // of its registry row — it must be replayable too. Unknown ids snapshot to [].
+    router.get("/api/sessions/:id/history", async (ctx) => {
+        const id = ctx.params.id;
+        ctx.body = { sessionId: id, items: sessionLog ? await sessionLog.snapshot(id) : [] };
+    });
+    // Persistent live event stream (codex-native): one SSE per session, held for
+    // its whole lifetime, tailing the canonical bus. Sees EVERY turn — web-injected
+    // AND co-driving-TUI-initiated — since the forwarder is the single writer. The
+    // bus has no replay; the client reconciles pre-subscribe state via `/history`
+    // + item-id dedupe. Ends when the client disconnects.
+    router.get("/api/sessions/:id/stream", async (ctx) => {
+        const id = ctx.params.id;
+        if (!sessionBus)
+            return bad(ctx, "session streaming is not available on this server");
+        await streamEvents(ctx, async (send, signal) => {
+            const iterator = sessionBus.subscribe(id)[Symbol.asyncIterator]();
+            const disconnected = new Promise((resolve) => {
+                if (signal.aborted)
+                    resolve(null);
+                else
+                    signal.addEventListener("abort", () => resolve(null), { once: true });
+            });
+            try {
+                for (;;) {
+                    const next = await Promise.race([iterator.next(), disconnected]);
+                    if (next === null)
+                        break; // client went away
+                    if (next.done)
+                        break; // bus closed for this session
+                    send("event", next.value);
+                }
+            }
+            finally {
+                await iterator.return?.();
+            }
+        });
+    });
+    // claude-native approvals: the PermissionRequest hook POSTs here and BLOCKS.
+    // Surface a `response.approval.requested` (the same event + ApprovalCard the
+    // codex path uses), hold the response until the web user answers, then relay
+    // claude's `{hookSpecificOutput:{decision:{behavior}}}` verdict to the hook.
+    router.post("/api/sessions/:id/hooks/permission-request", async (ctx) => {
+        const id = ctx.params.id;
+        if (!sessionBus)
+            return bad(ctx, "session streaming is not available on this server");
+        const payload = await readJson(ctx);
+        const toolName = asString(payload.tool_name) ?? "tool";
+        const toolInput = payload.tool_input && typeof payload.tool_input === "object"
+            ? payload.tool_input
+            : {};
+        const cwd = asString(payload.cwd);
+        const approvalId = `claude_${randomUUID()}`;
+        const kind = /edit|write|patch|apply|notebook/i.test(toolName)
+            ? "patch"
+            : "exec";
+        const command = asString(toolInput.command) ?? asString(toolInput.file_path) ?? toolName;
+        const event = {
+            type: "response.approval.requested",
+            responseId: `resp_claude_permission_${approvalId}`,
+            approvalId,
+            kind,
+            ...(command ? { command } : {}),
+            ...(cwd ? { cwd } : {}),
+        };
+        await persistSessionEvent(id, event, { sessionLog, sessionBus });
+        const verdict = await new Promise((resolve) => {
+            claudeApprovals.set(approvalId, resolve);
+            ctx.req.on("close", () => {
+                if (claudeApprovals.delete(approvalId))
+                    resolve({ behavior: "deny" });
+            });
+        });
+        ctx.body = { hookSpecificOutput: { hookEventName: "PermissionRequest", decision: verdict } };
+    });
+    // Resolve an interactive approval (Phase D): the user's decision for a
+    // `response.approval.requested` event, routed to the session's runner (codex)
+    // or the held claude PermissionRequest long-poll.
+    router.post("/api/sessions/:id/approvals/:approvalId", async (ctx) => {
+        const id = ctx.params.id;
+        const approvalId = ctx.params.approvalId;
+        const body = await readJson(ctx);
+        const decision = asString(body.decision);
+        if (decision !== "acceptForSession" &&
+            decision !== "accept" &&
+            decision !== "decline" &&
+            decision !== "cancel") {
+            ctx.status = 400;
+            ctx.body = { error: "decision must be acceptForSession | accept | decline | cancel" };
+            return;
+        }
+        const claudeResolve = claudeApprovals.get(approvalId);
+        if (claudeResolve) {
+            claudeApprovals.delete(approvalId);
+            claudeResolve(decision === "decline" || decision === "cancel" ? { behavior: "deny" } : { behavior: "allow" });
+            ctx.body = { ok: true };
+            return;
+        }
+        runnerManager?.resolveApproval?.(id, approvalId, decision);
+        ctx.body = { ok: true };
+    });
+    router.delete("/api/sessions/:id", async (ctx) => {
+        const id = ctx.params.id;
+        runnerManager?.stopRunner(id);
+        sessionBus?.close(id);
+        deps.removeSessionMeta(id);
+        // Hard-delete the transcript too — the session list is meta ∪ log, so
+        // dropping only the meta would leave the session showing as an UNKNOWN
+        // ghost. Both together make it fully disappear.
+        await sessionLog?.deleteSession(id);
+        // Unbind only the scope mapping — the device (and its helper) stays attached
+        // for the web panel / other sessions sharing it (orca's unregisterWorktree).
+        emulatorSessionDevices.delete(id);
+        ctx.body = { ok: true };
+    });
+    return router;
+}
+/**
+ * Stream Server-Sent Events for `run`. `send(event, data)` writes one frame;
+ * `signal` aborts when the client disconnects. Takes over the raw response so
+ * frames flush immediately; a thrown error is reported as an `error` event.
+ */
+async function streamEvents(ctx, run) {
+    ctx.status = 200;
+    ctx.set("Content-Type", "text/event-stream");
+    ctx.set("Cache-Control", "no-cache, no-transform");
+    ctx.set("Connection", "keep-alive");
+    ctx.respond = false;
+    const res = ctx.res;
+    res.flushHeaders?.();
+    const controller = new AbortController();
+    ctx.req.on("close", () => controller.abort());
+    const send = (event, data) => {
+        if (!res.writableEnded)
+            res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+    };
+    try {
+        await run(send, controller.signal);
+    }
+    catch (error) {
+        send("error", { message: error instanceof Error ? error.message : String(error) });
+    }
+    finally {
+        if (!res.writableEnded)
+            res.end();
+    }
+}
+/** Derive a one-line session title from the first user message: collapse
+ *  whitespace, trim, and truncate to `limit` chars + an ellipsis (omnigent's
+ *  rule — no LLM call). */
+export function synthesizeSessionTitle(message, limit = 60) {
+    const collapsed = message.replace(/\s+/g, " ").trim();
+    if (collapsed.length <= limit)
+        return collapsed;
+    return `${collapsed.slice(0, limit - 1).trimEnd()}…`;
+}
+async function readJson(ctx) {
+    const raw = await new Promise((resolve, reject) => {
+        let data = "";
+        ctx.req.on("data", (chunk) => (data += chunk));
+        ctx.req.on("end", () => resolve(data));
+        ctx.req.on("error", reject);
+    });
+    if (!raw.trim())
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Mask secret-ish option values so the page never echoes credentials back. A
+ * value is masked when its key is a `type: "secret"` field in the channel type's
+ * declared schema, or matches the secret-name heuristic as a fallback.
+ */
+function redact(deps, type, options) {
+    if (!options)
+        return undefined;
+    const schema = deps.listChannelTypes().find((t) => t.type === type)?.configSchema;
+    const secretKeys = new Set((schema ?? []).filter((f) => f.type === "secret").map((f) => f.key));
+    const out = {};
+    for (const [key, value] of Object.entries(options)) {
+        const secret = secretKeys.has(key) || /secret|token|key/i.test(key);
+        out[key] = secret && value ? "***" : value;
+    }
+    return out;
+}
+function asString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function asNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string" && value.trim()) {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function bad(ctx, message) {
+    ctx.status = 400;
+    ctx.body = { error: message };
+}
+function notFound(ctx, message) {
+    ctx.status = 404;
+    ctx.body = { error: message };
+}