@code-yeongyu/senpi 2026.7.5-2 → 2026.7.9

package/docs/neo.md

@@ -0,0 +1,110 @@
+# neo (Go TUI) — coding-agent integration notes
+
+> Minimal scaffold. Expanded by plan task 22 (docs + infra-sync). This file
+> currently covers only the pieces landed by task 15 (the TypeScript daemon).
+
+## Overview
+
+`senpi --neo` launches a Go-native terminal UI that drives the existing agent
+runtime over the JSONL RPC protocol. Multiple neo windows in the SAME cwd share
+one backend via a small TypeScript **daemon**, instead of each spawning its own
+runtime. `--neo-isolated` opts out of sharing (per-instance stdio backend).
+
+## Daemon architecture (task 15)
+
+### Process model
+
+- `senpi --listen <socket>` runs the daemon **supervisor**. It binds the socket,
+  self-registers, and serves connections. It does NOT construct an
+  `AgentSessionRuntime` in the supervisor process.
+- Each accepted connection is served by its own child `senpi --mode rpc`
+  **worker** process, spawned with the connection's cwd and its own
+  `SENPI_CODING_AGENT_DIR`. The worker is a standard single-connection rpc
+  runtime with its own module state and its own `AuthStorage`.
+
+### Why one worker process per connection (isolation)
+
+Running N `createAgentSessionRuntime` instances concurrently in ONE node process
+is not safe: pi-ai keeps a **process-global provider registry** that
+`ModelRegistry.refresh()` / `AgentSession.reload()` reset
+(`resetApiProviders()` / `resetOAuthProviders()`), and pi-agent-core mints entry
+IDs from a **module-level UUIDv7 counter**. Two concurrent in-process runtimes
+would cross-talk through both. Both live in shared libraries that are out of
+scope to change, so the daemon uses child-process workers instead — real
+concurrency, full isolation, and `--api-key` that can never leak across
+connections. See `.omo/evidence/task-15-neo-go-tui.md` §1 for the full spike.
+
+### Handshake
+
+A connection's first line is a `hello`:
+
+```json
+{"type":"hello","token":"<registry token>","version":1,"capabilities":[],"runtimeOptions":{...}}
+```
+
+The daemon replies `{"type":"welcome","version":1}` or
+`{"type":"refuse","code":"bad_token|version_mismatch|unsupported_options|malformed_hello","reason":"..."}`.
+`runtimeOptions` is the typed `NeoRuntimeOptions` payload (every classic runtime
+flag: provider/model/models/thinking/api-key, session selection, approval, tool
+scoping, resource loading, extension flags, and raw initial inputs). Its field
+set is generated from the classic runtime-construction path by an extraction
+test — a new consumer of a `parsed.*` field fails the test until it is threaded
+through the payload or documented as a carve-out.
+
+**Carve-out:** piped-stdin input never reaches the daemon — a TTY-less
+`senpi --neo` falls back to classic print-mode in the launcher.
+
+### Registry / race protocol
+
+- The daemon binds the socket FIRST — the bind is the mutex. The race loser gets
+  `EADDRINUSE` and its client attaches to the winner.
+- After a successful `listen`, and only with `--register`, the daemon atomically
+  writes `~/.senpi/agent/neo-daemon/<cwd-key>.json` (temp file + `rename`, mode
+  `0600`) as the LAST listen step. `<cwd-key>` uses the same safe-path scheme as
+  the session manager. Clients NEVER write the registry.
+- On spawn, a stale record (dead pid) and its leftover socket file are cleaned up
+  before binding.
+
+### Connection lifecycle
+
+There is no live-reattach lease. A socket disconnect aborts that connection's
+in-flight turn and disposes its worker. Sessions persist incrementally to disk,
+so recovery is resume-from-file (the Go client reloads via `get_state` +
+`get_entries{since}`). The daemon shuts down after a configurable no-connection
+idle period (`neoDaemon.idleShutdownMs` setting, default 30 minutes; `0`
+disables). The last client does NOT kill the daemon — the idle timer owns
+lifecycle.
+
+## Project-trust semantics in the daemon
+
+Each worker runs `--mode rpc`, which is **non-interactive**. In rpc mode the
+project-trust context has `hasUI: false`, so `resolveProjectTrusted` returns
+`false` for project-local resources unless:
+
+- the global `defaultProjectTrust` setting is `"always"`, or
+- the connection passes `--approve` (`projectTrustOverride: true`) in its
+  `runtimeOptions`.
+
+This is the same behavior as classic `senpi --mode rpc` today (the daemon adds no
+new trust surface). The classic **interactive** TUI prompts for trust; the neo
+client is responsible for surfacing an equivalent confirm through the
+extension-UI bridge and forwarding the user's choice as `--approve`/`--no-approve`
+(wired in plan task 13). No project-local code is trusted implicitly by the
+daemon.
+
+## cwd-threading audit (per-user-daemon safety)
+
+Verdict: **per-cwd, child-per-connection is safe** with respect to cwd.
+
+- There are **zero** `process.chdir()` calls in `packages/coding-agent/src`.
+- Tool execution is closure-captured: each tool is created with an explicit
+  `cwd` (from `AgentSession.config.cwd`) and threads it to every spawn/path call.
+  The bash tool passes `cwd` explicitly to `spawn(...)`; it never inherits
+  `process.cwd()`.
+- `resolvePath()` / `SessionManager` fall back to `process.cwd()` only as a
+  default when no explicit base/cwd is given; the runtime path always passes one.
+- Because each connection is its own child process spawned with an explicit
+  `cwd`, the child's `process.cwd()` is already the client's directory, so even
+  the fallback paths resolve correctly. No cross-connection cwd hazard remains.
+
+Per-cwd remains the default regardless (one daemon serves one cwd).

package/docs/sdk.md

@@ -1101,6 +1101,17 @@ await runRpcMode(runtime);
 
 See [RPC documentation](rpc.md) for the JSON protocol.
 
+### App Server Mode
+
+App Server mode is a CLI run mode for Codex-compatible app and editor integrations. Use it when a client expects the Codex app-server JSON-RPC method names, notification stream, and thread lifecycle instead of senpi's SDK object model.
+
+```bash
+senpi app-server --listen ws://127.0.0.1:18990
+senpi app-server --listen stdio://
+```
+
+See [App Server documentation](app-server.md) for activation, framing, method coverage, and compatibility notes.
+
 ## RPC Mode Alternative
 
 For subprocess-based integration without building with the SDK, use the CLI directly:

package/docs/terminal-tools.md

@@ -0,0 +1,69 @@
+# Persistent terminal tools
+
+Senpi's `bash` tool is backed by a real PTY, and ships four companion tools for
+long-lived, interactive shell sessions. This is the built-in `terminal` extension,
+powered by the in-house `@earendil-works/pi-pty` native module (with a
+`child_process` pipe fallback when no native prebuild is available for your
+platform/runtime).
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `bash` | Run a command in a PTY. `run_in_background: true` starts a persistent session and returns a `bash_id` immediately. Foreground `timeout` (seconds) is a kill deadline. |
+| `bash_output` | Read new output from a session, or `wait_for` a regex / exit / timeout. `filter` regex-filters lines; `view: "screen"` returns the rendered xterm grid. |
+| `bash_input` | Send stdin (`input`) or named keys (`keys: ["ctrl+c"]`, `["enter"]`, `["up"]`) to steer a REPL or interrupt a process. |
+| `bash_resize` | Resize a session's PTY (`cols`, `rows`) so full-screen TUIs reflow. |
+| `kill_bash` | Tree-kill one session (`bash_id`) or all (`all: true`), leaving no orphans. |
+
+Background sessions are NEVER killed by `timeout` (they live until they exit or you
+call `kill_bash`), even though the bash-timeout extension injects a default `timeout`
+into every `bash` call. Foreground calls behave like the classic `bash` tool.
+
+Typical flow: start with `run_in_background: true`, subscribe with `bash_output`
+(`wait_for`), steer with `bash_input`, then `kill_bash` when done.
+
+## Mutual exclusion with native Anthropic bash
+
+When `PI_ANTHROPIC_BASH` is enabled and the active model uses the
+`anthropic-messages` API, senpi injects Anthropic's native, stateless `bash` tool.
+In that mode the four persistent companions step aside (they are deactivated so none
+dangle without a usable persistent `bash`), and a one-line notice is shown. Disable
+`PI_ANTHROPIC_BASH` or switch to a non-Anthropic model to re-enable persistent
+sessions.
+
+## Settings
+
+Configure the suite under `terminal` in `settings.json` (global
+`~/.senpi/agent/settings.json` or project `.senpi/settings.json`):
+
+```json
+{
+  "terminal": {
+    "defaultCols": 120,
+    "defaultRows": 40,
+    "scrollback": 10000,
+    "maxSessions": 32,
+    "timeoutAction": "background",
+    "notify": "wake"
+  }
+}
+```
+
+- `defaultCols` / `defaultRows` — PTY size for new sessions (default 120 x 40).
+- `scrollback` — xterm scrollback lines per session (default 10000).
+- `maxSessions` — concurrent sessions before least-recently-used exited sessions are pruned (default 32).
+- `timeoutAction` — fate of a foreground timeout (default `background`).
+- `notify` — async completion behavior: `wake` (wake an idle interactive agent once), `next-turn`, or `off` (default `wake`). Non-interactive `-p` / `--print` / `--mode json` runs never wake.
+
+## Windows
+
+The PTY runs natively on Windows via ConPTY. Shell resolution:
+
+- Set `SENPI_GIT_BASH_PATH` to point at a specific `bash.exe` — it wins over the
+  Git Bash auto-detection.
+- An explicit shell path (`shellPath` in settings, or `SENPI_GIT_BASH_PATH`) is
+  resolved by kind: `cmd.exe` uses `/c`, PowerShell/`pwsh` use `-NoProfile -Command`,
+  and bash/sh use `-c` (or WSL bash `-s` via stdin).
+
+No shell is bundled; install Git for Windows or point senpi at your shell.

package/node_modules/@code-yeongyu/senpi-codemode/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+
+- Added the source-only `@code-yeongyu/senpi-codemode` workspace package scaffold.
+- Added codemode settings loading, interpreter detection, prompt generation, loopback bridge helpers, and persistent JS/Python/Ruby/Julia kernel building blocks.
+
+### Changed
+
+- Documented that the current exported extension factory is still a no-op until the `eval` tool and bundled host loading land.
+
+### Fixed
+
+- Fixed the bundled `eval` extension failing to load in packaged installs: `completion/handler.ts` imported peer symbols via the monorepo source path `../../../ai/src/*`, which only resolves inside the workspace and threw `Cannot find module` once packed. It now imports from the `@earendil-works/pi-ai/compat` package entry, so `eval` loads in the shipped Node package.
+- Fixed a temporal-dead-zone crash in the `eval` tool: subprocess kernels (py/rb/jl) emit their `ready` frame synchronously during kernel startup, which invoked the message handler before the `kernel` binding initialized and crashed the whole agent process. The self-referential binding is now hoisted so startup frames no longer throw.
+- Fixed cell-output misattribution on reused persistent kernels: `getKernel` now rebinds the per-cell `onMessage` on every call, so a second (and later) cell's streamed `text`/`display`/`log` output is delivered to that cell instead of the previous one.
+- Fixed the Ruby kernel corrupting its JSONL protocol channel: user `puts`/`print` output is now captured via a redirected `$stdout` and emitted as `text` frames instead of being written directly onto the shared stdout stream.

package/node_modules/@code-yeongyu/senpi-codemode/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Mario Zechner (upstream pi-mono)
+Copyright (c) 2026 Yeongyu Kim and senpi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/@code-yeongyu/senpi-codemode/README.md

@@ -0,0 +1,102 @@
+# @code-yeongyu/senpi-codemode
+
+Source-only senpi extension package for codemode: an in-progress port of
+oh-my-pi feature 01, "Code execution w/ tool-calling".
+
+The current package ships the codemode building blocks: settings loading,
+interpreter detection, bridge protocol/server helpers, prompt text, persistent
+language kernels, and prelude helpers. The exported extension factory is still a
+no-op in this Wave 3 source, so installing this package does not yet register an
+`eval` tool.
+
+## Kernels
+
+JavaScript is implemented with a Node.js worker and is always available when the
+package runs on the supported Node version. Python, Ruby, and Julia are optional
+runtime interpreters:
+
+| Language | Default | Interpreter |
+|----------|---------|-------------|
+| `js` | enabled | Node.js worker |
+| `py` | enabled | `python3` or `python` on POSIX; `python`, `py -3`, or `python3` on Windows |
+| `rb` | disabled | `ruby` |
+| `jl` | disabled | `julia` |
+
+Missing optional interpreters should be treated as runtime capability gaps, not
+install failures.
+
+## Settings
+
+Codemode reads standalone JSON config files. Project config wins over global
+config:
+
+1. `.senpi/codemode.json`
+2. `~/.senpi/agent/codemode.json`
+3. built-in defaults
+
+```json
+{
+  "languages": {
+    "py": true,
+    "js": true,
+    "rb": false,
+    "jl": false
+  },
+  "cellTimeoutSeconds": 30,
+  "parallelPoolWidth": 4
+}
+```
+
+Invalid JSON or invalid schema falls back to defaults with a warning. These are
+package-local settings; senpi's main `settings.json` has no `codemode` key in the
+current source.
+
+## Prelude API
+
+The prompt and kernels expose a shared prelude contract for cells. Availability
+depends on the language implementation and on whether the future `eval` tool is
+wired into the host.
+
+| Helper | Purpose |
+|--------|---------|
+| `display(value)` | Emit a cell result or rich display payload. |
+| `print(value, ...)` | Emit text output. |
+| `read(path, offset?, limit?)` | Read a text file with optional 1-indexed line slicing. |
+| `write(path, content)` | Write a file, creating parent directories. |
+| `env(key?, value?)` | Read or set environment values inside the kernel. |
+| `tool.<name>(args)` | Call an active senpi tool through the host bridge. |
+| `completion(prompt, ...)` | Request a one-shot host completion. |
+| `parallel(thunks)` | Run thunks through a bounded pool while preserving result order. |
+| `pipeline(items, ...stages)` | Map items through sequential pipeline stages. |
+| `log(message)` | Emit a progress line. |
+| `phase(title)` | Start a progress phase. |
+
+Cells are intended to be incremental: one call is one logical step, and
+top-level state persists per language until reset or kernel restart.
+
+## Security
+
+Kernels run locally with the same user permissions as senpi. The loopback bridge
+binds to `127.0.0.1` and authenticates each request with a per-session bearer
+token. Tool calls routed through `tool.<name>` are designed to pass through
+senpi's normal permission system and extension hook pipeline via
+`pi.executeTool`; that host integration is not yet wired in this package's
+factory in the current source.
+
+## Disable
+
+Because the current factory registers no tools, there is nothing to disable yet.
+After the planned `eval` tool and bundled loader land, the intended disable
+surfaces are:
+
+- `--exclude-tools eval`
+- `disabledBuiltinExtensions: ["codemode"]` in senpi settings
+
+## Troubleshooting
+
+| Symptom | Check |
+|---------|-------|
+| Python, Ruby, or Julia cells are unavailable | Confirm the interpreter is installed and visible on `PATH`; optional interpreters are not npm dependencies. |
+| A cell times out | Increase `cellTimeoutSeconds` or the future per-call timeout only for genuinely long work. |
+| State disappeared | The language kernel was reset, restarted, or crashed; rerun only the setup needed for that language. |
+| `tool.<name>` or `completion()` is unavailable | The host `eval` tool integration is deferred in the current Wave 3 source. |

package/node_modules/@code-yeongyu/senpi-codemode/package.json

@@ -0,0 +1,57 @@
+{
+	"name": "@code-yeongyu/senpi-codemode",
+	"version": "2026.7.9",
+	"description": "Source-only senpi extension package for codemode evaluation tools",
+	"type": "module",
+	"main": "./src/index.ts",
+	"types": "./src/index.ts",
+	"exports": {
+		".": "./src/index.ts",
+		"./package.json": "./package.json"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"CHANGELOG.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"test": "npx tsx ../../node_modules/vitest/dist/cli.js --run test/",
+		"clean": "node -e \"\"",
+		"build": "node -e \"\""
+	},
+	"pi": {
+		"extensions": [
+			"./src/index.ts"
+		]
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@earendil-works/pi-ai": "^2026.7.9",
+		"typebox": "1.1.38"
+	},
+	"peerDependencies": {
+		"@code-yeongyu/senpi": "*"
+	},
+	"devDependencies": {
+		"@code-yeongyu/senpi": "2026.7.9"
+	},
+	"keywords": [
+		"senpi",
+		"pi",
+		"extension",
+		"codemode"
+	],
+	"author": "Yeongyu Kim",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/code-yeongyu/senpi.git",
+		"directory": "packages/senpi-codemode"
+	},
+	"engines": {
+		"node": ">=24.0.0"
+	}
+}

package/node_modules/@code-yeongyu/senpi-codemode/src/bridge/http-server.ts

@@ -0,0 +1,236 @@
+import { once } from "node:events";
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import type { AddressInfo, Socket } from "node:net";
+import { type BridgeError, generateBridgeToken, verifyBridgeToken } from "./protocol.ts";
+
+const DEFAULT_BODY_LIMIT_BYTES = 1024 * 1024;
+const LOOPBACK_HOST = "127.0.0.1";
+
+export interface BridgeHttpCallRequest {
+	callId: string;
+	toolName: string;
+	args: unknown;
+	signal: AbortSignal;
+}
+
+export interface BridgeHttpCompletionRequest {
+	prompt: string;
+	opts?: unknown;
+	signal: AbortSignal;
+}
+
+export type BridgeHttpEmitEvent =
+	| { kind: "text"; stream: "stdout" | "stderr"; data: string }
+	| { kind: "display"; mimeType: string; dataBase64: string }
+	| { kind: "log"; message: string }
+	| { kind: "phase"; title: string };
+
+export interface BridgeServerOptions {
+	token?: string;
+	bodyLimitBytes?: number;
+	onCall: (request: BridgeHttpCallRequest) => Promise<unknown>;
+	onEmit: (event: BridgeHttpEmitEvent, signal: AbortSignal) => Promise<void>;
+	onCompletion: (request: BridgeHttpCompletionRequest) => Promise<unknown>;
+}
+
+export interface BridgeServerHandle {
+	port: number;
+	token: string;
+	close: () => Promise<void>;
+}
+
+type JsonReply = { ok: true; value: unknown } | { ok: false; error: BridgeError };
+type Route = "/call" | "/emit" | "/completion";
+
+export async function startBridgeServer(options: BridgeServerOptions): Promise<BridgeServerHandle> {
+	const token = options.token ?? generateBridgeToken();
+	const sockets = new Set<Socket>();
+	let closing: Promise<void> | undefined;
+	const server = createServer((request, response) => {
+		void handleRequest(request, response, token, options);
+	});
+	server.on("connection", (socket) => {
+		sockets.add(socket);
+		socket.on("close", () => sockets.delete(socket));
+	});
+	server.listen(0, LOOPBACK_HOST);
+	await once(server, "listening");
+	const address = server.address();
+	if (!address || typeof address === "string") throw new Error("Bridge server did not bind to a TCP port");
+
+	return {
+		port: (address as AddressInfo).port,
+		token,
+		close: async () => {
+			closing ??= closeServer(server, sockets);
+			await closing;
+		},
+	};
+}
+
+async function handleRequest(
+	request: IncomingMessage,
+	response: ServerResponse,
+	token: string,
+	options: BridgeServerOptions,
+): Promise<void> {
+	const abortController = new AbortController();
+	request.on("close", () => abortController.abort());
+	if (request.method !== "POST") {
+		sendJson(response, 404, { ok: false, error: transportError("not_found", "Bridge route was not found") });
+		return;
+	}
+	const route = routeFromUrl(request.url ?? "");
+	if (!route) {
+		sendJson(response, 404, { ok: false, error: transportError("not_found", "Bridge route was not found") });
+		return;
+	}
+	const auth = parseBearerToken(request.headers.authorization);
+	if (!auth || !verifyBridgeToken(token, auth).ok) {
+		sendJson(response, 401, { ok: false, error: transportError("unauthorized", "Bridge authorization failed") });
+		return;
+	}
+
+	const parsed = await readJsonBody(request, options.bodyLimitBytes ?? DEFAULT_BODY_LIMIT_BYTES);
+	if (!parsed.ok) {
+		sendJson(response, parsed.status, { ok: false, error: transportError(parsed.code, parsed.message) });
+		return;
+	}
+
+	if (route === "/emit") {
+		const event = parseEmitEvent(parsed.value);
+		if (!event.ok) {
+			sendJson(response, 400, { ok: false, error: transportError("invalid_request", event.message) });
+			return;
+		}
+		try {
+			await options.onEmit(event.event, abortController.signal);
+			response.writeHead(204).end();
+		} catch (error) {
+			sendJson(response, 200, { ok: false, error: bridgeError(error) });
+		}
+		return;
+	}
+
+	const reply =
+		route === "/call"
+			? await dispatchCall(parsed.value, options, abortController.signal)
+			: await dispatchCompletion(parsed.value, options, abortController.signal);
+	sendJson(response, 200, reply);
+}
+
+async function dispatchCall(body: unknown, options: BridgeServerOptions, signal: AbortSignal): Promise<JsonReply> {
+	if (!isRecord(body) || typeof body.callId !== "string" || typeof body.toolName !== "string" || !("args" in body)) {
+		return { ok: false, error: transportError("invalid_request", "Bridge call request was invalid") };
+	}
+	try {
+		return {
+			ok: true,
+			value: await options.onCall({ callId: body.callId, toolName: body.toolName, args: body.args, signal }),
+		};
+	} catch (error) {
+		return { ok: false, error: bridgeError(error) };
+	}
+}
+
+async function dispatchCompletion(
+	body: unknown,
+	options: BridgeServerOptions,
+	signal: AbortSignal,
+): Promise<JsonReply> {
+	if (!isRecord(body) || typeof body.prompt !== "string") {
+		return { ok: false, error: transportError("invalid_request", "Bridge completion request was invalid") };
+	}
+	try {
+		return { ok: true, value: await options.onCompletion({ prompt: body.prompt, opts: body.opts, signal }) };
+	} catch (error) {
+		return { ok: false, error: bridgeError(error) };
+	}
+}
+
+async function readJsonBody(
+	request: IncomingMessage,
+	limit: number,
+): Promise<{ ok: true; value: unknown } | { ok: false; status: number; code: string; message: string }> {
+	let raw = "";
+	for await (const chunk of request) {
+		raw += String(chunk);
+		if (Buffer.byteLength(raw, "utf8") > limit) {
+			return {
+				ok: false,
+				status: 413,
+				code: "body_too_large",
+				message: `Bridge request body exceeds ${limit} bytes`,
+			};
+		}
+	}
+	try {
+		return { ok: true, value: JSON.parse(raw) as unknown };
+	} catch {
+		return { ok: false, status: 400, code: "invalid_json", message: "Bridge request body was not valid JSON" };
+	}
+}
+
+function parseEmitEvent(value: unknown): { ok: true; event: BridgeHttpEmitEvent } | { ok: false; message: string } {
+	if (!isRecord(value) || typeof value.kind !== "string")
+		return { ok: false, message: "Bridge emit request was invalid" };
+	if (
+		value.kind === "text" &&
+		(value.stream === "stdout" || value.stream === "stderr") &&
+		typeof value.data === "string"
+	) {
+		return { ok: true, event: { kind: value.kind, stream: value.stream, data: value.data } };
+	}
+	if (value.kind === "display" && typeof value.mimeType === "string" && typeof value.dataBase64 === "string") {
+		return { ok: true, event: { kind: value.kind, mimeType: value.mimeType, dataBase64: value.dataBase64 } };
+	}
+	if (value.kind === "log" && typeof value.message === "string") {
+		return { ok: true, event: { kind: value.kind, message: value.message } };
+	}
+	if (value.kind === "phase" && typeof value.title === "string") {
+		return { ok: true, event: { kind: value.kind, title: value.title } };
+	}
+	return { ok: false, message: "Bridge emit request was invalid" };
+}
+
+function routeFromUrl(rawUrl: string): Route | undefined {
+	const path = new URL(rawUrl, "http://127.0.0.1").pathname;
+	if (path === "/call" || path === "/emit" || path === "/completion") return path;
+	return undefined;
+}
+
+function parseBearerToken(header: string | undefined): string | undefined {
+	const prefix = "Bearer ";
+	if (!header?.startsWith(prefix)) return undefined;
+	return header.slice(prefix.length);
+}
+
+function sendJson(response: ServerResponse, status: number, body: JsonReply): void {
+	if (response.destroyed) return;
+	response.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+	response.end(JSON.stringify(body));
+}
+
+function bridgeError(error: unknown): BridgeError {
+	if (error instanceof Error) return { name: error.name, message: error.message, stack: error.stack };
+	return { message: String(error) };
+}
+
+function transportError(code: string, message: string): BridgeError {
+	return { code, message };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+async function closeServer(server: ReturnType<typeof createServer>, sockets: Set<Socket>): Promise<void> {
+	server.closeAllConnections?.();
+	for (const socket of sockets) socket.destroy();
+	await new Promise<void>((resolve, reject) => {
+		server.close((error) => {
+			if (error && "code" in error && error.code !== "ERR_SERVER_NOT_RUNNING") reject(error);
+			else resolve();
+		});
+	});
+}