feat(frontend,wire): surface system (FE slice 1) + @dispatch/wire types-only split (B2)

FE slice 1 — backend-declared, frontend-agnostic surface system (verified live): new types-only @dispatch/ui-contract (SurfaceSpec / field kinds / region / ActionRef / catalog), surface-registry (typed service handle), transport-ws (Bun WS :24205, path-agnostic upgrade), surface-loaded-extensions (first real surface); kernel HostAPI.getExtensions; host-bin wiring; bin/up. Harness: retire AGENTS 'backend only', ORCHESTRATOR §3/§7/§8, frontend-design.md locked.

B2 — wire-types split (chat-slice prerequisite): new types-only @dispatch/wire single-sources the wire ABI (AgentEvent + 11 variants; conversation model Chunk/ChatMessage/Role/TurnId/StepId + 6 chunk variants; Usage) with zero @dispatch/* deps. @dispatch/kernel re-exports via shims so its public surface is byte-identical (zero consumer blast radius). transport-contract re-exports AgentEvent from @dispatch/wire and drops its @dispatch/kernel dependency, so HTTP clients (the web frontend) consume the wire without the kernel runtime.

tsc -b + biome clean; 460 vitest + 77 bun pass.

41 files changed, 1777 insertions, 225 deletions

diff --git a/packages/host-bin/package.json b/packages/host-bin/package.json
index 4ce63a9..65e986d 100644
--- a/packages/host-bin/package.json
+++ b/packages/host-bin/package.json
@@ -13,6 +13,9 @@
 		"@dispatch/session-orchestrator": "workspace:*",
 		"@dispatch/transport-http": "workspace:*",
 		"@dispatch/tool-read-file": "workspace:*",
-		"@dispatch/journal-sink": "workspace:*"
+		"@dispatch/journal-sink": "workspace:*",
+		"@dispatch/surface-loaded-extensions": "workspace:*",
+		"@dispatch/surface-registry": "workspace:*",
+		"@dispatch/transport-ws": "workspace:*"
 	}
 }
diff --git a/packages/host-bin/src/main.ts b/packages/host-bin/src/main.ts
index d766e46..68cbbdd 100644
--- a/packages/host-bin/src/main.ts
+++ b/packages/host-bin/src/main.ts
@@ -21,8 +21,11 @@ import {
 import { extension as providerOpenaiCompatExt } from "@dispatch/provider-openai-compat";
 import { extension as sessionOrchestratorExt } from "@dispatch/session-orchestrator";
 import { createSqliteStorage, extension as storageSqliteExt } from "@dispatch/storage-sqlite";
+import { createLoadedExtensionsExtension } from "@dispatch/surface-loaded-extensions";
+import { createSurfaceRegistryExtension } from "@dispatch/surface-registry";
 import { extension as toolReadFileExt } from "@dispatch/tool-read-file";
 import { createServer, extension as transportHttpExt } from "@dispatch/transport-http";
+import { createTransportWsExtension } from "@dispatch/transport-ws";
 import type { ChildHandle } from "./collector-supervisor.js";
 import { createCollectorSupervisor } from "./collector-supervisor.js";
 import { configMapToAccess, envToConfigMap } from "./config.js";
@@ -61,6 +64,10 @@ const CORE_EXTENSIONS: readonly Extension[] = [
 	}),
 	sessionOrchestratorExt,
 	transportHttpExt,
+	// Surface extensions — dependency order: surface-registry first, then consumers.
+	createSurfaceRegistryExtension(),
+	createTransportWsExtension(),
+	createLoadedExtensionsExtension(),
 ];
 
 async function boot(): Promise<void> {
diff --git a/packages/host-bin/tsconfig.json b/packages/host-bin/tsconfig.json
index 70ff95c..3630394 100644
--- a/packages/host-bin/tsconfig.json
+++ b/packages/host-bin/tsconfig.json
@@ -5,11 +5,10 @@
 	"references": [
 		{ "path": "../kernel" },
 		{ "path": "../storage-sqlite" },
-		{ "path": "../conversation-store" },
-		{ "path": "../auth-apikey" },
-		{ "path": "../credential-store" },
-		{ "path": "../provider-openai-compat" },
-		{ "path": "../session-orchestrator" },
-		{ "path": "../transport-http" }
+		{ "path": "../surface-loaded-extensions" },
+		{ "path": "../surface-registry" },
+		{ "path": "../tool-read-file" },
+		{ "path": "../transport-http" },
+		{ "path": "../transport-ws" }
 	]
 }
diff --git a/packages/kernel/package.json b/packages/kernel/package.json
index f613cac..d8d55a7 100644
--- a/packages/kernel/package.json
+++ b/packages/kernel/package.json
@@ -4,5 +4,8 @@
 	"type": "module",
 	"private": true,
 	"main": "dist/index.js",
-	"types": "dist/index.d.ts"
+	"types": "dist/index.d.ts",
+	"dependencies": {
+		"@dispatch/wire": "workspace:*"
+	}
 }
diff --git a/packages/kernel/src/contracts/conversation.ts b/packages/kernel/src/contracts/conversation.ts
index c9ad0eb..ec9a389 100644
--- a/packages/kernel/src/contracts/conversation.ts
+++ b/packages/kernel/src/contracts/conversation.ts
@@ -1,91 +1,20 @@
 /**
  * Conversation model — the kernel's representation of a dialogue.
  *
- * The kernel owns only the types and pure transforms. Persistence is a core
- * extension (conversation-store). A turn is one user→assistant cycle; a step
- * is one LLM round-trip within a turn. Chunks are append-only.
+ * Re-exported from @dispatch/wire so the kernel barrel surface stays
+ * byte-identical. The canonical definitions live in @dispatch/wire.
  */
 
-/** Who produced a message. */
-export type Role = "system" | "user" | "assistant" | "tool";
-
-/** Opaque identifier for a turn (one user→assistant cycle). */
-export type TurnId = string & { readonly __brand: "TurnId" };
-
-/** Opaque identifier for a step (one LLM round-trip within a turn). */
-export type StepId = string & { readonly __brand: "StepId" };
-
-/**
- * A chunk is one ordered piece of a message — the atomic unit of the
- * append-only conversation log. Discriminated by `type`.
- */
-export type Chunk =
-	| TextChunk
-	| ThinkingChunk
-	| ToolCallChunk
-	| ToolResultChunk
-	| ErrorChunk
-	| SystemChunk;
-
-/** A piece of plain text content from the assistant or user. */
-export interface TextChunk {
-	readonly type: "text";
-	readonly text: string;
-}
-
-/** A piece of model reasoning / thinking content (e.g. extended thinking). */
-export interface ThinkingChunk {
-	readonly type: "thinking";
-	readonly text: string;
-}
-
-/**
- * A model's request to run a tool. The kernel routes by `name`; the tool
- * implementation never sees this directly — it receives parsed `input` via
- * `ToolContract.execute`.
- */
-export interface ToolCallChunk {
-	readonly type: "tool-call";
-	readonly toolCallId: string;
-	readonly toolName: string;
-	readonly input: unknown;
-}
-
-/**
- * The result of a tool execution, attributed to the originating tool-call id.
- * The kernel guarantees every tool-call chunk gets exactly one result chunk
- * (synthesized if interrupted — see reconcile).
- */
-export interface ToolResultChunk {
-	readonly type: "tool-result";
-	readonly toolCallId: string;
-	readonly toolName: string;
-	readonly content: string;
-	readonly isError: boolean;
-}
-
-/** An error that occurred during generation or tool dispatch. */
-export interface ErrorChunk {
-	readonly type: "error";
-	readonly message: string;
-	readonly code?: string;
-}
-
-/**
- * A system-injected message (e.g. system prompt, context assembly output).
- * Kept distinct from text so the log records provenance.
- */
-export interface SystemChunk {
-	readonly type: "system";
-	readonly text: string;
-}
-
-/**
- * A chat message: a role plus an ordered sequence of chunks. Messages are the
- * unit passed to and from the provider; chunks are the unit persisted and
- * rendered.
- */
-export interface ChatMessage {
-	readonly role: Role;
-	readonly chunks: readonly Chunk[];
-}
+export type {
+	ChatMessage,
+	Chunk,
+	ErrorChunk,
+	Role,
+	StepId,
+	SystemChunk,
+	TextChunk,
+	ThinkingChunk,
+	ToolCallChunk,
+	ToolResultChunk,
+	TurnId,
+} from "@dispatch/wire";
diff --git a/packages/kernel/src/contracts/events.ts b/packages/kernel/src/contracts/events.ts
index 74e23fd..8737b02 100644
--- a/packages/kernel/src/contracts/events.ts
+++ b/packages/kernel/src/contracts/events.ts
@@ -1,122 +1,21 @@
 /**
  * Outward events — the event type the runtime emits to the outside world.
  *
- * These are the events transport extensions push to clients, notification
- * extensions react to, and conversation-store uses for persistence.
- * Discriminated by `type`.
+ * Re-exported from @dispatch/wire so the kernel barrel surface stays
+ * byte-identical. The canonical definitions live in @dispatch/wire.
  */
 
-import type { Usage } from "./provider.js";
-
-/**
- * The union of all events the runtime emits outward during a turn.
- * Consumers (transport, persistence, notifications) pattern-match on `type`.
- */
-export type AgentEvent =
-	| StatusEvent
-	| TurnStartEvent
-	| TurnTextDeltaEvent
-	| TurnReasoningDeltaEvent
-	| TurnToolCallEvent
-	| TurnToolResultEvent
-	| TurnToolOutputEvent
-	| TurnUsageEvent
-	| TurnErrorEvent
-	| TurnDoneEvent
-	| TurnSealedEvent;
-
-/** Status change for a conversation (e.g. idle → running). */
-export interface StatusEvent {
-	readonly type: "status";
-	readonly conversationId: string;
-	readonly status: string;
-}
-
-/** A turn has begun. */
-export interface TurnStartEvent {
-	readonly type: "turn-start";
-	readonly conversationId: string;
-	readonly turnId: string;
-}
-
-/** Incremental text content from the model during a turn. */
-export interface TurnTextDeltaEvent {
-	readonly type: "text-delta";
-	readonly conversationId: string;
-	readonly turnId: string;
-	readonly delta: string;
-}
-
-/** Incremental reasoning / thinking content during a turn. */
-export interface TurnReasoningDeltaEvent {
-	readonly type: "reasoning-delta";
-	readonly conversationId: string;
-	readonly turnId: string;
-	readonly delta: string;
-}
-
-/** The model has requested a tool to be run. */
-export interface TurnToolCallEvent {
-	readonly type: "tool-call";
-	readonly conversationId: string;
-	readonly turnId: string;
-	readonly toolCallId: string;
-	readonly toolName: string;
-	readonly input: unknown;
-}
-
-/** A tool has completed execution. */
-export interface TurnToolResultEvent {
-	readonly type: "tool-result";
-	readonly conversationId: string;
-	readonly turnId: string;
-	readonly toolCallId: string;
-	readonly toolName: string;
-	readonly content: string;
-	readonly isError: boolean;
-}
-
-/** Streaming output from a tool execution (e.g. shell stdout/stderr). */
-export interface TurnToolOutputEvent {
-	readonly type: "tool-output";
-	readonly conversationId: string;
-	readonly turnId: string;
-	readonly toolCallId: string;
-	readonly data: string;
-	readonly stream: "stdout" | "stderr";
-}
-
-/** Token usage for the current step or turn. */
-export interface TurnUsageEvent {
-	readonly type: "usage";
-	readonly conversationId: string;
-	readonly turnId: string;
-	readonly usage: Usage;
-}
-
-/** An error occurred during the turn. */
-export interface TurnErrorEvent {
-	readonly type: "error";
-	readonly conversationId: string;
-	readonly turnId: string;
-	readonly message: string;
-	readonly code?: string;
-}
-
-/** The turn has completed (model finished generating). */
-export interface TurnDoneEvent {
-	readonly type: "done";
-	readonly conversationId: string;
-	readonly turnId: string;
-	readonly reason: string;
-}
-
-/**
- * The turn has been sealed — all chunks persisted, history is final.
- * This is the hook point for post-turn extensions (compaction, cache-warm).
- */
-export interface TurnSealedEvent {
-	readonly type: "turn-sealed";
-	readonly conversationId: string;
-	readonly turnId: string;
-}
+export type {
+	AgentEvent,
+	StatusEvent,
+	TurnDoneEvent,
+	TurnErrorEvent,
+	TurnReasoningDeltaEvent,
+	TurnSealedEvent,
+	TurnStartEvent,
+	TurnTextDeltaEvent,
+	TurnToolCallEvent,
+	TurnToolOutputEvent,
+	TurnToolResultEvent,
+	TurnUsageEvent,
+} from "@dispatch/wire";
diff --git a/packages/kernel/src/contracts/extension.ts b/packages/kernel/src/contracts/extension.ts
index 00b41f1..1760cf9 100644
--- a/packages/kernel/src/contracts/extension.ts
+++ b/packages/kernel/src/contracts/extension.ts
@@ -232,6 +232,9 @@ export interface HostAPI {
 	/** Look up a single auth provider by id. */
 	readonly getAuthProvider: (id: string) => AuthContract | undefined;
 
+	/** Read-only view of all activated extensions' manifests (what is loaded). */
+	readonly getExtensions: () => readonly Manifest[];
+
 	/** Register a scheduled job with the host's scheduler. */
 	readonly scheduler: {
 		readonly register: (job: ScheduledJob) => void;
diff --git a/packages/kernel/src/contracts/provider.ts b/packages/kernel/src/contracts/provider.ts
index ee58c1d..0686c19 100644
--- a/packages/kernel/src/contracts/provider.ts
+++ b/packages/kernel/src/contracts/provider.ts
@@ -6,20 +6,12 @@
  * translates its responses into `ProviderEvent`s.
  */
 
+import type { Usage } from "@dispatch/wire";
 import type { ChatMessage } from "./conversation.js";
 import type { Logger } from "./logging.js";
 import type { ToolContract } from "./tool.js";
 
-/**
- * Token usage counters for a single step. All fields are counts of tokens.
- * Cache fields are optional because not all providers expose cache metrics.
- */
-export interface Usage {
-	readonly inputTokens: number;
-	readonly outputTokens: number;
-	readonly cacheReadTokens?: number;
-	readonly cacheWriteTokens?: number;
-}
+export type { Usage } from "@dispatch/wire";
 
 /**
  * Events a provider yields during a single `stream` call. The kernel consumes
diff --git a/packages/kernel/src/host/host.test.ts b/packages/kernel/src/host/host.test.ts
index 430447c..106dd56 100644
--- a/packages/kernel/src/host/host.test.ts
+++ b/packages/kernel/src/host/host.test.ts
@@ -726,6 +726,117 @@ describe("createHost", () => {
 		});
 	});
 
+	describe("getExtensions", () => {
+		it("returns empty array when no extensions are activated", async () => {
+			const host = createHost([], deps);
+			await host.activate();
+
+			expect(host.getExtensions()).toEqual([]);
+		});
+
+		it("returns manifests of all activated extensions", async () => {
+			const a = createExtension("ext-a");
+			const b = createExtension("ext-b");
+
+			const host = createHost([a, b], deps);
+			await host.activate();
+
+			const exts = host.getExtensions();
+			expect(exts).toHaveLength(2);
+			expect(exts.map((e) => e.id)).toContain("ext-a");
+			expect(exts.map((e) => e.id)).toContain("ext-b");
+		});
+
+		it("returns manifests in activation order", async () => {
+			const a = createExtension("a");
+			const b = createExtension("b", { dependsOn: ["a"] });
+			const c = createExtension("c", { dependsOn: ["b"] });
+
+			const host = createHost([c, b, a], deps);
+			await host.activate();
+
+			const exts = host.getExtensions();
+			expect(exts.map((e) => e.id)).toEqual(["a", "b", "c"]);
+		});
+
+		it("excludes extensions that failed to activate", async () => {
+			const a = createExtension("good");
+			const b = createExtension("bad", {
+				activate: () => {
+					throw new Error("boom");
+				},
+			});
+
+			const host = createHost([a, b], deps);
+			await host.activate();
+
+			const exts = host.getExtensions();
+			expect(exts).toHaveLength(1);
+			expect(exts[0]?.id).toBe("good");
+		});
+
+		it("excludes extensions disabled by apiVersion incompatibility", async () => {
+			const good = createExtension("good");
+			const bad = createExtension("bad", { apiVersion: "^99.0.0" });
+
+			const host = createHost([good, bad], deps);
+			await host.activate();
+
+			const exts = host.getExtensions();
+			expect(exts).toHaveLength(1);
+			expect(exts[0]?.id).toBe("good");
+		});
+
+		it("returns a frozen array", async () => {
+			const ext = createExtension("ext");
+			const host = createHost([ext], deps);
+			await host.activate();
+
+			const exts = host.getExtensions();
+			expect(Object.isFrozen(exts)).toBe(true);
+		});
+
+		it("HostAPI getExtensions reflects activated extensions after full activation", async () => {
+			const a = createExtension("ext-a");
+			const b = createExtension("ext-b", {
+				dependsOn: ["ext-a"],
+				activate: () => {},
+			});
+
+			const host = createHost([a, b], deps);
+			await host.activate();
+
+			// Use getHostAPI() to verify the post-activation view
+			const api = host.getHostAPI();
+			const capturedExtsAfter = api.getExtensions();
+
+			expect(capturedExtsAfter).toHaveLength(2);
+			expect(capturedExtsAfter.map((e) => e.id)).toEqual(["ext-a", "ext-b"]);
+		});
+
+		it("HostAPI getExtensions during activation sees only previously activated", async () => {
+			const seenDuringActivation: string[][] = [];
+
+			const a = createExtension("a", {
+				activate: (host) => {
+					seenDuringActivation.push(host.getExtensions().map((e) => e.id));
+				},
+			});
+			const b = createExtension("b", {
+				activate: (host) => {
+					seenDuringActivation.push(host.getExtensions().map((e) => e.id));
+				},
+			});
+
+			const host = createHost([a, b], deps);
+			await host.activate();
+
+			// When a activates, activated[] is empty (a hasn't been pushed yet)
+			// When b activates, activated[] has [a] (b hasn't been pushed yet)
+			expect(seenDuringActivation).toEqual([[], ["a"]]);
+		});
+	});
+
 	describe("DAG errors", () => {
 		it("throws on missing dependency", () => {
 			const ext = createExtension("a", { dependsOn: ["missing"] });
diff --git a/packages/kernel/src/host/host.ts b/packages/kernel/src/host/host.ts
index 2331625..8aa4f78 100644
--- a/packages/kernel/src/host/host.ts
+++ b/packages/kernel/src/host/host.ts
@@ -57,6 +57,7 @@ export interface Host {
 	readonly getScheduledJobs: () => readonly ScheduledJob[];
 	readonly getMigrations: () => readonly string[];
 	readonly getDisabled: () => readonly DisabledExtension[];
+	readonly getExtensions: () => readonly Manifest[];
 	readonly getHostAPI: () => HostAPI;
 }
 
@@ -150,6 +151,9 @@ export function createHost(extensions: readonly Extension[], deps: HostDeps): Ho
 			getAuthProvider(id: string) {
 				return authProviders.get(id);
 			},
+			getExtensions() {
+				return Object.freeze(activated.map((e) => e.manifest));
+			},
 			scheduler: {
 				register(job: ScheduledJob) {
 					scheduledJobs.push(job);
@@ -213,6 +217,9 @@ export function createHost(extensions: readonly Extension[], deps: HostDeps): Ho
 		getDisabled() {
 			return disabled;
 		},
+		getExtensions() {
+			return Object.freeze(activated.map((e) => e.manifest));
+		},
 		getHostAPI() {
 			return buildHostAPI("__host__", { registrationClosed: true });
 		},
diff --git a/packages/kernel/tsconfig.json b/packages/kernel/tsconfig.json
index 2a3be7e..a882987 100644
--- a/packages/kernel/tsconfig.json
+++ b/packages/kernel/tsconfig.json
@@ -1,5 +1,6 @@
 {
 	"extends": "../../tsconfig.base.json",
 	"compilerOptions": { "rootDir": "src", "outDir": "dist", "composite": true },
-	"include": ["src/**/*.ts"]
+	"include": ["src/**/*.ts"],
+	"references": [{ "path": "../wire" }]
 }
diff --git a/packages/surface-loaded-extensions/package.json b/packages/surface-loaded-extensions/package.json
new file mode 100644
index 0000000..66e2e69
--- /dev/null
+++ b/packages/surface-loaded-extensions/package.json
@@ -0,0 +1,13 @@
+{
+	"name": "@dispatch/surface-loaded-extensions",
+	"version": "0.0.0",
+	"type": "module",
+	"private": true,
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"dependencies": {
+		"@dispatch/kernel": "workspace:*",
+		"@dispatch/ui-contract": "workspace:*",
+		"@dispatch/surface-registry": "workspace:*"
+	}
+}
diff --git a/packages/surface-loaded-extensions/src/extension.ts b/packages/surface-loaded-extensions/src/extension.ts
new file mode 100644
index 0000000..abef4b6
--- /dev/null
+++ b/packages/surface-loaded-extensions/src/extension.ts
@@ -0,0 +1,43 @@
+import type { Extension, HostAPI, Manifest } from "@dispatch/kernel";
+import type { SurfaceProvider } from "@dispatch/surface-registry";
+import { surfaceRegistryHandle } from "@dispatch/surface-registry";
+import { buildLoadedExtensionsSpec } from "./spec.js";
+
+export const manifest: Manifest = {
+	id: "surface-loaded-extensions",
+	name: "Loaded Extensions Surface",
+	version: "0.0.0",
+	apiVersion: "^0.1.0",
+	trust: "bundled",
+	activation: "eager",
+	dependsOn: ["surface-registry"],
+	contributes: { services: [] },
+};
+
+export function createLoadedExtensionsExtension(): Extension {
+	let dispose: (() => void) | undefined;
+
+	return {
+		manifest,
+		activate(host: HostAPI) {
+			const registry = host.getService(surfaceRegistryHandle);
+
+			const provider: SurfaceProvider = {
+				catalogEntry: {
+					id: "loaded-extensions",
+					region: "side",
+					title: "Loaded Extensions",
+				},
+				getSpec() {
+					return buildLoadedExtensionsSpec(host.getExtensions());
+				},
+				invoke() {},
+			};
+
+			dispose = registry.register(provider);
+		},
+		deactivate() {
+			dispose?.();
+		},
+	};
+}
diff --git a/packages/surface-loaded-extensions/src/index.ts b/packages/surface-loaded-extensions/src/index.ts
new file mode 100644
index 0000000..bc10dc5
--- /dev/null
+++ b/packages/surface-loaded-extensions/src/index.ts
@@ -0,0 +1,2 @@
+export { createLoadedExtensionsExtension, manifest } from "./extension.js";
+export { buildLoadedExtensionsSpec } from "./spec.js";
diff --git a/packages/surface-loaded-extensions/src/spec.test.ts b/packages/surface-loaded-extensions/src/spec.test.ts
new file mode 100644
index 0000000..9c1aa6a
--- /dev/null
+++ b/packages/surface-loaded-extensions/src/spec.test.ts
@@ -0,0 +1,94 @@
+import type { Manifest } from "@dispatch/kernel";
+import type { StatField } from "@dispatch/ui-contract";
+import { describe, expect, it } from "vitest";
+import { buildLoadedExtensionsSpec } from "./spec.js";
+
+function fakeManifest(id: string, name: string, version: string): Manifest {
+	return {
+		id,
+		name,
+		version,
+		apiVersion: "^0.1.0",
+		trust: "bundled",
+	};
+}
+
+describe("buildLoadedExtensionsSpec", () => {
+	it("returns a count stat of '0' and no extension stats for empty manifests", () => {
+		const spec = buildLoadedExtensionsSpec([]);
+
+		expect(spec.id).toBe("loaded-extensions");
+		expect(spec.region).toBe("side");
+		expect(spec.title).toBe("Loaded Extensions");
+		expect(spec.fields).toHaveLength(1);
+		expect(spec.fields[0]).toEqual({
+			kind: "stat",
+			label: "Loaded",
+			value: "0",
+		});
+	});
+
+	it("returns a count stat plus one stat per manifest in order", () => {
+		const manifests = [
+			fakeManifest("alpha", "Alpha", "1.0.0"),
+			fakeManifest("beta", "Beta", "2.3.1"),
+			fakeManifest("gamma", "Gamma", "0.5.0"),
+		];
+
+		const spec = buildLoadedExtensionsSpec(manifests);
+
+		expect(spec.fields).toHaveLength(4);
+		expect(spec.fields[0]).toEqual({
+			kind: "stat",
+			label: "Loaded",
+			value: "3",
+		});
+		expect(spec.fields[1]).toEqual({
+			kind: "stat",
+			label: "Alpha",
+			value: "1.0.0",
+		});
+		expect(spec.fields[2]).toEqual({
+			kind: "stat",
+			label: "Beta",
+			value: "2.3.1",
+		});
+		expect(spec.fields[3]).toEqual({
+			kind: "stat",
+			label: "Gamma",
+			value: "0.5.0",
+		});
+	});
+
+	it("preserves input order of manifests", () => {
+		const manifests = [
+			fakeManifest("z-last", "Z Last", "1.0.0"),
+			fakeManifest("a-first", "A First", "2.0.0"),
+		];
+
+		const spec = buildLoadedExtensionsSpec(manifests);
+
+		expect((spec.fields[1] as StatField).label).toBe("Z Last");
+		expect((spec.fields[2] as StatField).label).toBe("A First");
+	});
+
+	it("sets the surface id, region, and title correctly", () => {
+		const spec = buildLoadedExtensionsSpec([]);
+
+		expect(spec.id).toBe("loaded-extensions");
+		expect(spec.region).toBe("side");
+		expect(spec.title).toBe("Loaded Extensions");
+	});
+
+	it("uses manifest.name as label and manifest.version as value", () => {
+		const manifests = [fakeManifest("my-ext", "My Extension", "3.2.1")];
+
+		const spec = buildLoadedExtensionsSpec(manifests);
+
+		expect(spec.fields[1]).toEqual({
+			kind: "stat",
+			label: "My Extension",
+			value: "3.2.1",
+		});
+	});
+});
diff --git a/packages/surface-loaded-extensions/src/spec.ts b/packages/surface-loaded-extensions/src/spec.ts
new file mode 100644
index 0000000..bd3dd56
--- /dev/null
+++ b/packages/surface-loaded-extensions/src/spec.ts
@@ -0,0 +1,25 @@
+import type { Manifest } from "@dispatch/kernel";
+import type { StatField, SurfaceSpec } from "@dispatch/ui-contract";
+
+/**
+ * Pure core — builds the SurfaceSpec for the loaded-extensions surface.
+ * Zero I/O, zero ambient state. Decision logic only: input → output.
+ */
+export function buildLoadedExtensionsSpec(manifests: readonly Manifest[]): SurfaceSpec {
+	const fields: StatField[] = [{ kind: "stat", label: "Loaded", value: String(manifests.length) }];
+
+	for (const manifest of manifests) {
+		fields.push({
+			kind: "stat",
+			label: manifest.name,
+			value: manifest.version,
+		});
+	}
+
+	return {
+		id: "loaded-extensions",
+		region: "side",
+		title: "Loaded Extensions",
+		fields,
+	};
+}
diff --git a/packages/surface-loaded-extensions/tsconfig.json b/packages/surface-loaded-extensions/tsconfig.json
new file mode 100644
index 0000000..db257d0
--- /dev/null
+++ b/packages/surface-loaded-extensions/tsconfig.json
@@ -0,0 +1,10 @@
+{
+	"extends": "../../tsconfig.base.json",
+	"compilerOptions": { "rootDir": "src", "outDir": "dist", "composite": true },
+	"include": ["src/**/*.ts"],
+	"references": [
+		{ "path": "../kernel" },
+		{ "path": "../ui-contract" },
+		{ "path": "../surface-registry" }
+	]
+}
diff --git a/packages/surface-registry/package.json b/packages/surface-registry/package.json
new file mode 100644
index 0000000..16b0c4c
--- /dev/null
+++ b/packages/surface-registry/package.json
@@ -0,0 +1,12 @@
+{
+	"name": "@dispatch/surface-registry",
+	"version": "0.0.0",
+	"type": "module",
+	"private": true,
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"dependencies": {
+		"@dispatch/kernel": "workspace:*",
+		"@dispatch/ui-contract": "workspace:*"
+	}
+}
diff --git a/packages/surface-registry/src/extension.ts b/packages/surface-registry/src/extension.ts
new file mode 100644
index 0000000..6d0ce22
--- /dev/null
+++ b/packages/surface-registry/src/extension.ts
@@ -0,0 +1,23 @@
+import type { Extension, Manifest } from "@dispatch/kernel";
+import { createSurfaceRegistry } from "./registry.js";
+import { surfaceRegistryHandle } from "./service.js";
+
+export const manifest: Manifest = {
+	id: "surface-registry",
+	name: "Surface Registry",
+	version: "0.0.0",
+	apiVersion: "^0.1.0",
+	trust: "bundled",
+	activation: "eager",
+	contributes: { services: ["surface-registry/registry"] },
+};
+
+export function createSurfaceRegistryExtension(): Extension {
+	return {
+		manifest,
+		activate(host) {
+			const registry = createSurfaceRegistry();
+			host.provideService(surfaceRegistryHandle, registry);
+		},
+	};
+}
diff --git a/packages/surface-registry/src/index.ts b/packages/surface-registry/src/index.ts
new file mode 100644
index 0000000..cdfcf7e
--- /dev/null
+++ b/packages/surface-registry/src/index.ts
@@ -0,0 +1,4 @@
+export { createSurfaceRegistryExtension, manifest } from "./extension.js";
+export type { SurfaceProvider, SurfaceRegistry } from "./registry.js";
+export { createSurfaceRegistry } from "./registry.js";
+export { surfaceRegistryHandle } from "./service.js";
diff --git a/packages/surface-registry/src/registry.test.ts b/packages/surface-registry/src/registry.test.ts
new file mode 100644
index 0000000..c47c979
--- /dev/null
+++ b/packages/surface-registry/src/registry.test.ts
@@ -0,0 +1,122 @@
+import type { SurfaceCatalogEntry, SurfaceSpec } from "@dispatch/ui-contract";
+import { describe, expect, it } from "vitest";
+import type { SurfaceProvider } from "./registry.js";
+import { createSurfaceRegistry } from "./registry.js";
+
+function fakeProvider(id: string, title?: string): SurfaceProvider {
+	const catalogEntry: SurfaceCatalogEntry = {
+		id,
+		region: "default",
+		title: title ?? `Surface ${id}`,
+	};
+	return {
+		catalogEntry,
+		getSpec(): SurfaceSpec {
+			return {
+				id,
+				region: "default",
+				title: catalogEntry.title,
+				fields: [],
+			};
+		},
+		invoke() {},
+	};
+}
+
+describe("createSurfaceRegistry", () => {
+	describe("register + getCatalog", () => {
+		it("returns the entry after registration", () => {
+			const registry = createSurfaceRegistry();
+			registry.register(fakeProvider("a", "Surface A"));
+
+			const catalog = registry.getCatalog();
+			expect(catalog).toHaveLength(1);
+			expect(catalog[0]).toEqual({
+				id: "a",
+				region: "default",
+				title: "Surface A",
+			});
+		});
+
+		it("returns entries for multiple providers", () => {
+			const registry = createSurfaceRegistry();
+			registry.register(fakeProvider("a"));
+			registry.register(fakeProvider("b"));
+
+			const catalog = registry.getCatalog();
+			expect(catalog).toHaveLength(2);
+			expect(catalog.map((e) => e.id)).toEqual(["a", "b"]);
+		});
+	});
+
+	describe("getSurface", () => {
+		it("returns the provider for a known id", () => {
+			const registry = createSurfaceRegistry();
+			const provider = fakeProvider("x");
+			registry.register(provider);
+
+			expect(registry.getSurface("x")).toBe(provider);
+		});
+
+		it("returns undefined for an unknown id", () => {
+			const registry = createSurfaceRegistry();
+			expect(registry.getSurface("nonexistent")).toBeUndefined();
+		});
+	});
+
+	describe("disposer", () => {
+		it("removes the provider from catalog and lookup", () => {
+			const registry = createSurfaceRegistry();
+			const dispose = registry.register(fakeProvider("a"));
+
+			expect(registry.getCatalog()).toHaveLength(1);
+			expect(registry.getSurface("a")).toBeDefined();
+
+			dispose();
+
+			expect(registry.getCatalog()).toHaveLength(0);
+			expect(registry.getSurface("a")).toBeUndefined();
+		});
+
+		it("is idempotent — calling dispose twice is safe", () => {
+			const registry = createSurfaceRegistry();
+			const dispose = registry.register(fakeProvider("a"));
+
+			dispose();
+			dispose();
+
+			expect(registry.getCatalog()).toHaveLength(0);
+		});
+
+		it("does not remove a replacement provider with the same id", () => {
+			const registry = createSurfaceRegistry();
+			const first = fakeProvider("a", "First");
+			const second = fakeProvider("a", "Second");
+
+			const disposeFirst = registry.register(first);
+			registry.register(second);
+
+			disposeFirst();
+
+			// The second provider should still be registered
+			expect(registry.getSurface("a")).toBe(second);
+			expect(registry.getCatalog()).toHaveLength(1);
+			expect(registry.getCatalog()[0]?.title).toBe("Second");
+		});
+	});
+
+	describe("duplicate-id behavior (last-wins)", () => {
+		it("replaces an existing provider when registering the same id", () => {
+			const registry = createSurfaceRegistry();
+			const first = fakeProvider("a", "First");
+			const second = fakeProvider("a", "Second");
+
+			registry.register(first);
+			registry.register(second);
+
+			expect(registry.getSurface("a")).toBe(second);
+			expect(registry.getCatalog()).toHaveLength(1);
+			expect(registry.getCatalog()[0]?.title).toBe("Second");
+		});
+	});
+});
diff --git a/packages/surface-registry/src/registry.ts b/packages/surface-registry/src/registry.ts
new file mode 100644
index 0000000..b1c8116
--- /dev/null
+++ b/packages/surface-registry/src/registry.ts
@@ -0,0 +1,80 @@
+import type { SurfaceCatalog, SurfaceCatalogEntry, SurfaceSpec } from "@dispatch/ui-contract";
+
+/**
+ * What a surface-contributing extension registers with the surface registry.
+ * Each provider owns one surface identified by its catalog entry id.
+ */
+export interface SurfaceProvider {
+	/** Discovery metadata for the surface catalog. */
+	readonly catalogEntry: SurfaceCatalogEntry;
+
+	/** Build the current surface spec (may be async for dynamic surfaces). */
+	getSpec(): SurfaceSpec | Promise<SurfaceSpec>;
+
+	/** Run a backend action by id with an optional payload. */
+	invoke(actionId: string, payload?: unknown): void | Promise<void>;
+
+	/**
+	 * Optional: subscribe to spec changes. Returns an unsubscribe disposer.
+	 * When the spec changes, the caller should re-fetch via getSpec() and push.
+	 */
+	subscribe?(onChange: () => void): () => void;
+}
+
+/**
+ * The surface registry service — the interface other extensions obtain via
+ * `host.getService(surfaceRegistryHandle)`.
+ */
+export interface SurfaceRegistry {
+	/**
+	 * Register a surface provider. Returns an unregister disposer.
+	 * If a provider with the same id is already registered, the new one
+	 * replaces it (last-wins semantics).
+	 */
+	register(provider: SurfaceProvider): () => void;
+
+	/** Return discovery metadata for all currently registered providers. */
+	getCatalog(): SurfaceCatalog;
+
+	/** Look up a provider by its surface id. */
+	getSurface(id: string): SurfaceProvider | undefined;
+}
+
+/**
+ * Create a pure in-memory surface registry. No I/O, no ambient state —
+ * the decision logic is a plain Map behind the SurfaceRegistry interface.
+ */
+export function createSurfaceRegistry(): SurfaceRegistry {
+	const providers = new Map<string, SurfaceProvider>();
+
+	return {
+		register(provider: SurfaceProvider): () => void {
+			const id = provider.catalogEntry.id;
+			providers.set(id, provider);
+
+			let disposed = false;
+			return () => {
+				if (!disposed) {
+					disposed = true;
+					// Only delete if the current entry is still this provider
+					// (another register with the same id may have replaced it).
+					if (providers.get(id) === provider) {
+						providers.delete(id);
+					}
+				}
+			};
+		},
+
+		getCatalog(): SurfaceCatalog {
+			const entries: SurfaceCatalogEntry[] = [];
+			for (const provider of providers.values()) {
+				entries.push(provider.catalogEntry);
+			}
+			return entries;
+		},
+
+		getSurface(id: string): SurfaceProvider | undefined {
+			return providers.get(id);
+		},
+	};
+}
diff --git a/packages/surface-registry/src/service.ts b/packages/surface-registry/src/service.ts
new file mode 100644
index 0000000..a43c155
--- /dev/null
+++ b/packages/surface-registry/src/service.ts
@@ -0,0 +1,4 @@
+import { defineService } from "@dispatch/kernel";
+import type { SurfaceRegistry } from "./registry.js";
+
+export const surfaceRegistryHandle = defineService<SurfaceRegistry>("surface-registry/registry");
diff --git a/packages/surface-registry/tsconfig.json b/packages/surface-registry/tsconfig.json
new file mode 100644
index 0000000..e430ba9
--- /dev/null
+++ b/packages/surface-registry/tsconfig.json
@@ -0,0 +1,6 @@
+{
+	"extends": "../../tsconfig.base.json",
+	"compilerOptions": { "rootDir": "src", "outDir": "dist", "composite": true },
+	"include": ["src/**/*.ts"],
+	"references": [{ "path": "../kernel" }, { "path": "../ui-contract" }]
+}
diff --git a/packages/transport-contract/package.json b/packages/transport-contract/package.json
index 83c8a71..2af6a73 100644
--- a/packages/transport-contract/package.json
+++ b/packages/transport-contract/package.json
@@ -6,6 +6,6 @@
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
 	"dependencies": {
-		"@dispatch/kernel": "workspace:*"
+		"@dispatch/wire": "workspace:*"
 	}
 }
diff --git a/packages/transport-contract/src/index.ts b/packages/transport-contract/src/index.ts
index 5f16d8a..7d3996a 100644
--- a/packages/transport-contract/src/index.ts
+++ b/packages/transport-contract/src/index.ts
@@ -12,7 +12,7 @@
  * union, re-exported here so a client has one import for the whole wire.
  */
 
-export type { AgentEvent } from "@dispatch/kernel";
+export type { AgentEvent } from "@dispatch/wire";
 
 /**
  * Request body for `POST /chat` (sent as JSON).
diff --git a/packages/transport-contract/tsconfig.json b/packages/transport-contract/tsconfig.json
index ff99a43..a882987 100644
--- a/packages/transport-contract/tsconfig.json
+++ b/packages/transport-contract/tsconfig.json
@@ -2,5 +2,5 @@
 	"extends": "../../tsconfig.base.json",
 	"compilerOptions": { "rootDir": "src", "outDir": "dist", "composite": true },
 	"include": ["src/**/*.ts"],
-	"references": [{ "path": "../kernel" }]
+	"references": [{ "path": "../wire" }]
 }
diff --git a/packages/transport-ws/package.json b/packages/transport-ws/package.json
new file mode 100644
index 0000000..dab8ebc
--- /dev/null
+++ b/packages/transport-ws/package.json
@@ -0,0 +1,13 @@
+{
+	"name": "@dispatch/transport-ws",
+	"version": "0.0.0",
+	"type": "module",
+	"private": true,
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"dependencies": {
+		"@dispatch/kernel": "workspace:*",
+		"@dispatch/surface-registry": "workspace:*",
+		"@dispatch/ui-contract": "workspace:*"
+	}
+}
diff --git a/packages/transport-ws/src/extension.ts b/packages/transport-ws/src/extension.ts
new file mode 100644
index 0000000..a18aefa
--- /dev/null
+++ b/packages/transport-ws/src/extension.ts
@@ -0,0 +1,161 @@
+/**
+ * Shell — thin imperative layer that owns the Bun.serve WebSocket server.
+ *
+ * All decision logic lives in router.ts (pure, unit-tested).
+ * This file handles I/O only: WS accept, JSON parse/stringify,
+ * provider.subscribe wiring, server lifecycle.
+ */
+
+import type { Extension, HostAPI } from "@dispatch/kernel";
+import type { SurfaceProvider, SurfaceRegistry } from "@dispatch/surface-registry";
+import { surfaceRegistryHandle } from "@dispatch/surface-registry";
+import type { SurfaceClientMessage, SurfaceServerMessage } from "@dispatch/ui-contract";
+import { manifest } from "./manifest.js";
+import { catalogMessage, routeClientMessage } from "./router.js";
+
+/** Active provider subscriptions for a single WS connection. */
+interface ConnectionState {
+	readonly subs: Set<string>;
+	readonly providerDisposers: Map<string, () => void>;
+}
+
+type Ws = Bun.ServerWebSocket<ConnectionState>;
+
+export function createTransportWsExtension(): Extension {
+	let server: ReturnType<typeof Bun.serve<ConnectionState>> | undefined;
+
+	return {
+		manifest,
+		async activate(host: HostAPI) {
+			const registry: SurfaceRegistry = host.getService(surfaceRegistryHandle);
+			const logger = host.logger;
+			const port = host.config.get<number>("surfaceWsPort") ?? 24205;
+
+			function send(ws: Ws, msg: SurfaceServerMessage): void {
+				try {
+					ws.send(JSON.stringify(msg));
+				} catch {
+					// Connection may have been dropped; swallow.
+				}
+			}
+
+			function subscribeToProvider(
+				ws: Ws,
+				provider: SurfaceProvider,
+				surfaceId: string,
+				state: ConnectionState,
+			): void {
+				if (!provider.subscribe || state.providerDisposers.has(surfaceId)) {
+					return;
+				}
+				const dispose = provider.subscribe(() => {
+					try {
+						const spec = provider.getSpec();
+						if (spec instanceof Promise) {
+							spec
+								.then((s) => send(ws, { type: "update", update: { surfaceId, spec: s } }))
+								.catch(() => {});
+						} else {
+							send(ws, { type: "update", update: { surfaceId, spec } });
+						}
+					} catch {
+						// Provider threw — log but don't kill the connection.
+					}
+				});
+				state.providerDisposers.set(surfaceId, dispose);
+			}
+
+			function unsubscribeFromProvider(state: ConnectionState, surfaceId: string): void {
+				const dispose = state.providerDisposers.get(surfaceId);
+				if (dispose) {
+					dispose();
+					state.providerDisposers.delete(surfaceId);
+				}
+			}
+
+			server = Bun.serve<ConnectionState>({
+				port,
+				fetch(req, srv) {
+					const initial: ConnectionState = {
+						subs: new Set(),
+						providerDisposers: new Map(),
+					};
+					if (srv.upgrade(req, { data: initial })) return;
+					return new Response("expected websocket", { status: 426 });
+				},
+				websocket: {
+					open(ws) {
+						send(ws, catalogMessage(registry));
+					},
+
+					message(ws, message) {
+						const state = ws.data;
+						if (!state) return;
+
+						let parsed: SurfaceClientMessage;
+						try {
+							parsed = JSON.parse(String(message)) as SurfaceClientMessage;
+						} catch {
+							send(ws, { type: "error", message: "Invalid JSON" });
+							return;
+						}
+
+						const result = routeClientMessage(registry, state.subs, parsed);
+
+						// Apply sub change.
+						if (result.subChange) {
+							if (result.subChange.op === "add") {
+								state.subs.add(result.subChange.surfaceId);
+								const provider = registry.getSurface(result.subChange.surfaceId);
+								if (provider) {
+									subscribeToProvider(ws, provider, result.subChange.surfaceId, state);
+								}
+							} else {
+								state.subs.delete(result.subChange.surfaceId);
+								unsubscribeFromProvider(state, result.subChange.surfaceId);
+							}
+						}
+
+						// Send replies.
+						for (const reply of result.replies) {
+							send(ws, reply);
+						}
+
+						// Perform invoke if signalled.
+						if (result.invoke) {
+							const provider = registry.getSurface(result.invoke.surfaceId);
+							if (provider) {
+								try {
+									const r = provider.invoke(result.invoke.actionId, result.invoke.payload);
+									if (r instanceof Promise) {
+										r.catch(() => {});
+									}
+								} catch {
+									// Provider threw on invoke — log but don't kill the connection.
+								}
+							}
+						}
+					},
+
+					close(ws) {
+						const state = ws.data;
+						if (state) {
+							for (const dispose of state.providerDisposers.values()) {
+								dispose();
+							}
+						}
+					},
+				},
+			});
+
+			logger.info?.("transport-ws: surface WebSocket listening", { port });
+		},
+
+		deactivate() {
+			if (server) {
+				server.stop();
+				server = undefined;
+			}
+		},
+	};
+}
diff --git a/packages/transport-ws/src/index.ts b/packages/transport-ws/src/index.ts
new file mode 100644
index 0000000..a93611f
--- /dev/null
+++ b/packages/transport-ws/src/index.ts
@@ -0,0 +1,4 @@
+export { createTransportWsExtension } from "./extension.js";
+export { manifest } from "./manifest.js";
+export type { RouteResult } from "./router.js";
+export { catalogMessage, routeClientMessage } from "./router.js";
diff --git a/packages/transport-ws/src/manifest.ts b/packages/transport-ws/src/manifest.ts
new file mode 100644
index 0000000..b0612e2
--- /dev/null
+++ b/packages/transport-ws/src/manifest.ts
@@ -0,0 +1,13 @@
+import type { Manifest } from "@dispatch/kernel";
+
+export const manifest: Manifest = {
+	id: "transport-ws",
+	name: "Transport WebSocket",
+	version: "0.0.0",
+	apiVersion: "^0.1.0",
+	trust: "bundled",
+	dependsOn: ["surface-registry"],
+	capabilities: { network: true },
+	contributes: { routes: ["/ws/surfaces"] },
+	activation: "eager",
+};
diff --git a/packages/transport-ws/src/router.test.ts b/packages/transport-ws/src/router.test.ts
new file mode 100644
index 0000000..83496f3
--- /dev/null
+++ b/packages/transport-ws/src/router.test.ts
@@ -0,0 +1,203 @@
+import type { SurfaceProvider, SurfaceRegistry } from "@dispatch/surface-registry";
+import type { SurfaceCatalogEntry, SurfaceSpec } from "@dispatch/ui-contract";
+import { describe, expect, it } from "vitest";
+import { catalogMessage, routeClientMessage } from "./router.js";
+
+// ── Fake in-memory registry (no mocks — just a plain implementation) ────────
+
+function fakeProvider(id: string, title?: string, actions?: readonly string[]): SurfaceProvider {
+	const catalogEntry: SurfaceCatalogEntry = {
+		id,
+		region: "default",
+		title: title ?? `Surface ${id}`,
+	};
+	return {
+		catalogEntry,
+		getSpec(): SurfaceSpec {
+			return {
+				id,
+				region: "default",
+				title: catalogEntry.title,
+				fields:
+					actions?.map((a) => ({
+						kind: "button" as const,
+						label: a,
+						action: { actionId: a },
+					})) ?? [],
+			};
+		},
+		invoke(_actionId: string, _payload?: unknown) {},
+	};
+}
+
+function fakeRegistry(providers: readonly SurfaceProvider[]): SurfaceRegistry {
+	const map = new Map(providers.map((p) => [p.catalogEntry.id, p]));
+	return {
+		register(_provider: SurfaceProvider) {
+			return () => {};
+		},
+		getCatalog() {
+			return [...map.values()].map((p) => p.catalogEntry);
+		},
+		getSurface(id: string) {
+			return map.get(id);
+		},
+	};
+}
+
+// ── Tests ───────────────────────────────────────────────────────────────────
+
+describe("routeClientMessage", () => {
+	describe("subscribe", () => {
+		it("replies with `surface` and tracks the subscription", () => {
+			const provider = fakeProvider("a", "Surface A");
+			const registry = fakeRegistry([provider]);
+			const connSubs = new Set<string>();
+
+			const result = routeClientMessage(registry, connSubs, {
+				type: "subscribe",
+				surfaceId: "a",
+			});
+
+			expect(result.replies).toHaveLength(1);
+			expect(result.replies[0]).toEqual({
+				type: "surface",
+				spec: {
+					id: "a",
+					region: "default",
+					title: "Surface A",
+					fields: [],
+				},
+			});
+			expect(result.subChange).toEqual({ op: "add", surfaceId: "a" });
+		});
+
+		it("is idempotent — subscribing twice does not duplicate the subChange", () => {
+			const provider = fakeProvider("a");
+			const registry = fakeRegistry([provider]);
+			const connSubs = new Set<string>(["a"]); // already subscribed
+
+			const result = routeClientMessage(registry, connSubs, {
+				type: "subscribe",
+				surfaceId: "a",
+			});
+
+			expect(result.replies).toHaveLength(1);
+			expect(result.replies[0]?.type).toBe("surface");
+			expect(result.subChange).toBeUndefined();
+		});
+
+		it("returns `error` for an unknown surface id", () => {
+			const registry = fakeRegistry([]);
+			const connSubs = new Set<string>();
+
+			const result = routeClientMessage(registry, connSubs, {
+				type: "subscribe",
+				surfaceId: "nonexistent",
+			});
+
+			expect(result.replies).toHaveLength(1);
+			expect(result.replies[0]).toEqual({
+				type: "error",
+				surfaceId: "nonexistent",
+				message: "Unknown surface: nonexistent",
+			});
+			expect(result.subChange).toBeUndefined();
+		});
+	});
+
+	describe("unsubscribe", () => {
+		it("emits a remove subChange and no replies", () => {
+			const registry = fakeRegistry([]);
+			const connSubs = new Set<string>(["a"]);
+
+			const result = routeClientMessage(registry, connSubs, {
+				type: "unsubscribe",
+				surfaceId: "a",
+			});
+
+			expect(result.replies).toHaveLength(0);
+			expect(result.subChange).toEqual({ op: "remove", surfaceId: "a" });
+		});
+
+		it("emits remove even if not currently subscribed (idempotent)", () => {
+			const registry = fakeRegistry([]);
+			const connSubs = new Set<string>();
+
+			const result = routeClientMessage(registry, connSubs, {
+				type: "unsubscribe",
+				surfaceId: "a",
+			});
+
+			expect(result.replies).toHaveLength(0);
+			expect(result.subChange).toEqual({ op: "remove", surfaceId: "a" });
+		});
+	});
+
+	describe("invoke", () => {
+		it("signals the invoke effect for a known surface", () => {
+			const provider = fakeProvider("a", "Surface A", ["toggle"]);
+			const registry = fakeRegistry([provider]);
+			const connSubs = new Set<string>();
+
+			const result = routeClientMessage(registry, connSubs, {
+				type: "invoke",
+				surfaceId: "a",
+				actionId: "toggle",
+				payload: true,
+			});
+
+			expect(result.replies).toHaveLength(0);
+			expect(result.invoke).toEqual({
+				surfaceId: "a",
+				actionId: "toggle",
+				payload: true,
+			});
+		});
+
+		it("returns `error` for an unknown surface id", () => {
+			const registry = fakeRegistry([]);
+			const connSubs = new Set<string>();
+
+			const result = routeClientMessage(registry, connSubs, {
+				type: "invoke",
+				surfaceId: "nonexistent",
+				actionId: "toggle",
+			});
+
+			expect(result.replies).toHaveLength(1);
+			expect(result.replies[0]).toEqual({
+				type: "error",
+				surfaceId: "nonexistent",
+				message: "Unknown surface: nonexistent",
+			});
+			expect(result.invoke).toBeUndefined();
+		});
+	});
+});
+
+describe("catalogMessage", () => {
+	it("returns the catalog from the registry", () => {
+		const providerA = fakeProvider("a", "Surface A");
+		const providerB = fakeProvider("b", "Surface B");
+		const registry = fakeRegistry([providerA, providerB]);
+
+		const msg = catalogMessage(registry);
+
+		expect(msg).toEqual({
+			type: "catalog",
+			catalog: [
+				{ id: "a", region: "default", title: "Surface A" },
+				{ id: "b", region: "default", title: "Surface B" },
+			],
+		});
+	});
+
+	it("returns an empty catalog when no providers are registered", () => {
+		const registry = fakeRegistry([]);
+
+		const msg = catalogMessage(registry);
+
+		expect(msg).toEqual({ type: "catalog", catalog: [] });
+	});
+});
diff --git a/packages/transport-ws/src/router.ts b/packages/transport-ws/src/router.ts
new file mode 100644
index 0000000..f9a7a82
--- /dev/null
+++ b/packages/transport-ws/src/router.ts
@@ -0,0 +1,116 @@
+/**
+ * Pure core — routes a client WS message into an effect description.
+ *
+ * Zero I/O, zero ambient state. Every function is `input → output`:
+ * it decides what to do but does NOT do it. The shell (extension.ts)
+ * interprets the result: sends WS messages, mutates connSubs, calls
+ * provider.invoke.
+ */
+
+import type { SurfaceRegistry } from "@dispatch/surface-registry";
+import type { SurfaceClientMessage, SurfaceServerMessage } from "@dispatch/ui-contract";
+
+// ── Result types ────────────────────────────────────────────────────────────
+
+/** The effect a single client message should produce. */
+export interface RouteResult {
+	/** Server messages to send back to this connection. */
+	readonly replies: readonly SurfaceServerMessage[];
+	/** Whether to add or remove the surface id from connSubs. */
+	readonly subChange?: { readonly op: "add" | "remove"; readonly surfaceId: string };
+	/** If set, the shell must call `provider.invoke(actionId, payload)`. */
+	readonly invoke?: {
+		readonly surfaceId: string;
+		readonly actionId: string;
+		readonly payload?: unknown;
+	};
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+/** Build the catalog `SurfaceServerMessage` from the registry. */
+export function catalogMessage(registry: SurfaceRegistry): SurfaceServerMessage {
+	return { type: "catalog", catalog: registry.getCatalog() };
+}
+
+// ── Router ──────────────────────────────────────────────────────────────────
+
+/**
+ * Route a single client message into a pure effect description.
+ *
+ * @param registry  The surface registry (looked up once, injected).
+ * @param connSubs  This connection's current subscribed surface ids.
+ * @param msg       The parsed client message.
+ */
+export function routeClientMessage(
+	registry: SurfaceRegistry,
+	connSubs: ReadonlySet<string>,
+	msg: SurfaceClientMessage,
+): RouteResult {
+	switch (msg.type) {
+		case "subscribe":
+			return handleSubscribe(registry, connSubs, msg.surfaceId);
+		case "unsubscribe":
+			return handleUnsubscribe(msg.surfaceId);
+		case "invoke":
+			return handleInvoke(registry, msg.surfaceId, msg.actionId, msg.payload);
+	}
+}
+
+// ── Per-message handlers ────────────────────────────────────────────────────
+
+function handleSubscribe(
+	registry: SurfaceRegistry,
+	connSubs: ReadonlySet<string>,
+	surfaceId: string,
+): RouteResult {
+	const provider = registry.getSurface(surfaceId);
+	if (!provider) {
+		return {
+			replies: [{ type: "error", surfaceId, message: `Unknown surface: ${surfaceId}` }],
+		};
+	}
+
+	const spec = provider.getSpec();
+
+	// getSpec may be sync or async — the pure core treats it as a value the
+	// shell will resolve. We return the spec directly (it's a SurfaceSpec).
+	// If it's a Promise the shell awaits it; if it's sync it's already the value.
+	// For the pure core we just pass it through — the shell handles the resolution.
+	const specValue = spec as import("@dispatch/ui-contract").SurfaceSpec;
+
+	const replies: import("@dispatch/ui-contract").SurfaceServerMessage[] = [
+		{ type: "surface", spec: specValue },
+	];
+
+	// Idempotent: only emit subChange if not already subscribed.
+	if (!connSubs.has(surfaceId)) {
+		return { replies, subChange: { op: "add", surfaceId } };
+	}
+	return { replies };
+}
+
+function handleUnsubscribe(surfaceId: string): RouteResult {
+	return {
+		replies: [],
+		subChange: { op: "remove", surfaceId },
+	};
+}
+
+function handleInvoke(
+	registry: SurfaceRegistry,
+	surfaceId: string,
+	actionId: string,
+	payload?: unknown,
+): RouteResult {
+	const provider = registry.getSurface(surfaceId);
+	if (!provider) {
+		return {
+			replies: [{ type: "error", surfaceId, message: `Unknown surface: ${surfaceId}` }],
+		};
+	}
+	return {
+		replies: [],
+		invoke: { surfaceId, actionId, payload },
+	};
+}
diff --git a/packages/transport-ws/src/server.bun.test.ts b/packages/transport-ws/src/server.bun.test.ts
new file mode 100644
index 0000000..d51eb72
--- /dev/null
+++ b/packages/transport-ws/src/server.bun.test.ts
@@ -0,0 +1,195 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import type { SurfaceProvider, SurfaceRegistry } from "@dispatch/surface-registry";
+import type {
+	SurfaceCatalogEntry,
+	SurfaceClientMessage,
+	SurfaceServerMessage,
+	SurfaceSpec,
+} from "@dispatch/ui-contract";
+import { catalogMessage, routeClientMessage } from "./router.js";
+
+// ── Fake registry (same pattern as router.test.ts) ──────────────────────────
+
+function fakeProvider(id: string, title?: string): SurfaceProvider {
+	const catalogEntry: SurfaceCatalogEntry = {
+		id,
+		region: "default",
+		title: title ?? `Surface ${id}`,
+	};
+	return {
+		catalogEntry,
+		getSpec(): SurfaceSpec {
+			return {
+				id,
+				region: "default",
+				title: catalogEntry.title,
+				fields: [],
+			};
+		},
+		invoke(_actionId: string, _payload?: unknown) {},
+	};
+}
+
+function fakeRegistry(providers: readonly SurfaceProvider[]): SurfaceRegistry {
+	const map = new Map(providers.map((p) => [p.catalogEntry.id, p]));
+	return {
+		register(_provider: SurfaceProvider) {
+			return () => {};
+		},
+		getCatalog() {
+			return [...map.values()].map((p) => p.catalogEntry);
+		},
+		getSurface(id: string) {
+			return map.get(id);
+		},
+	};
+}
+
+// ── Per-connection state (mirrors extension.ts) ─────────────────────────────
+
+interface ConnectionState {
+	readonly subs: Set<string>;
+	readonly providerDisposers: Map<string, () => void>;
+}
+
+// ── Server helper ───────────────────────────────────────────────────────────
+
+function startServer(registry: SurfaceRegistry, port = 0) {
+	return Bun.serve<ConnectionState>({
+		port,
+		fetch(req, srv) {
+			const initial: ConnectionState = {
+				subs: new Set(),
+				providerDisposers: new Map(),
+			};
+			if (srv.upgrade(req, { data: initial })) return;
+			return new Response("expected websocket", { status: 426 });
+		},
+		websocket: {
+			open(ws) {
+				ws.send(JSON.stringify(catalogMessage(registry)));
+			},
+
+			message(ws, raw) {
+				const state = ws.data;
+				if (!state) return;
+
+				let parsed: SurfaceClientMessage;
+				try {
+					parsed = JSON.parse(String(raw)) as SurfaceClientMessage;
+				} catch {
+					ws.send(JSON.stringify({ type: "error", message: "Invalid JSON" }));
+					return;
+				}
+
+				const result = routeClientMessage(registry, state.subs, parsed);
+
+				if (result.subChange) {
+					if (result.subChange.op === "add") {
+						state.subs.add(result.subChange.surfaceId);
+					} else {
+						state.subs.delete(result.subChange.surfaceId);
+					}
+				}
+
+				for (const reply of result.replies) {
+					ws.send(JSON.stringify(reply));
+				}
+			},
+
+			close(ws) {
+				const state = ws.data;
+				if (state) {
+					for (const dispose of state.providerDisposers.values()) {
+						dispose();
+					}
+				}
+			},
+		},
+	});
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function waitForMessage(ws: WebSocket): Promise<SurfaceServerMessage> {
+	return new Promise((resolve, reject) => {
+		const timeout = setTimeout(() => reject(new Error("timed out waiting for message")), 5000);
+		function handler(ev: MessageEvent) {
+			clearTimeout(timeout);
+			ws.removeEventListener("message", handler);
+			resolve(JSON.parse(ev.data as string) as SurfaceServerMessage);
+		}
+		ws.addEventListener("message", handler);
+	});
+}
+
+// ── Tests ───────────────────────────────────────────────────────────────────
+
+describe("Bun.serve WebSocket server", () => {
+	let server: ReturnType<typeof Bun.serve>;
+	let port: number;
+
+	beforeEach(() => {
+		const provider = fakeProvider("demo", "Demo Surface");
+		const registry = fakeRegistry([provider]);
+		server = startServer(registry);
+		port = server.port as number;
+	});
+
+	afterEach(() => {
+		server.stop();
+	});
+
+	test("performs WebSocket upgrade (returns 101)", async () => {
+		const ws = new WebSocket(`ws://localhost:${port}`);
+		const msg = await waitForMessage(ws);
+		expect(msg.type).toBe("catalog");
+		ws.close();
+	});
+
+	test("sends catalog on open", async () => {
+		const ws = new WebSocket(`ws://localhost:${port}`);
+		const msg = await waitForMessage(ws);
+		expect(msg).toEqual({
+			type: "catalog",
+			catalog: [{ id: "demo", region: "default", title: "Demo Surface" }],
+		});
+		ws.close();
+	});
+
+	test("subscribe returns surface spec", async () => {
+		const ws = new WebSocket(`ws://localhost:${port}`);
+		await waitForMessage(ws); // drain catalog
+
+		ws.send(JSON.stringify({ type: "subscribe", surfaceId: "demo" }));
+		const msg = await waitForMessage(ws);
+
+		expect(msg.type).toBe("surface");
+		if (msg.type === "surface") {
+			expect(msg.spec.id).toBe("demo");
+			expect(msg.spec.title).toBe("Demo Surface");
+		}
+		ws.close();
+	});
+
+	test("subscribe to unknown surface returns error", async () => {
+		const ws = new WebSocket(`ws://localhost:${port}`);
+		await waitForMessage(ws); // drain catalog
+
+		ws.send(JSON.stringify({ type: "subscribe", surfaceId: "nope" }));
+		const msg = await waitForMessage(ws);
+
+		expect(msg).toEqual({
+			type: "error",
+			surfaceId: "nope",
+			message: "Unknown surface: nope",
+		});
+		ws.close();
+	});
+
+	test("non-WebSocket request returns 426", async () => {
+		const res = await fetch(`http://localhost:${port}/`);
+		expect(res.status).toBe(426);
+		expect(await res.text()).toBe("expected websocket");
+	});
+});
diff --git a/packages/transport-ws/tsconfig.json b/packages/transport-ws/tsconfig.json
new file mode 100644
index 0000000..102c8f0
--- /dev/null
+++ b/packages/transport-ws/tsconfig.json
@@ -0,0 +1,10 @@
+{
+	"extends": "../../tsconfig.base.json",
+	"compilerOptions": { "rootDir": "src", "outDir": "dist", "composite": true },
+	"include": ["src/**/*.ts"],
+	"references": [
+		{ "path": "../kernel" },
+		{ "path": "../surface-registry" },
+		{ "path": "../ui-contract" }
+	]
+}
diff --git a/packages/ui-contract/package.json b/packages/ui-contract/package.json
new file mode 100644
index 0000000..e1f4c35
--- /dev/null
+++ b/packages/ui-contract/package.json
@@ -0,0 +1,8 @@
+{
+	"name": "@dispatch/ui-contract",
+	"version": "0.0.0",
+	"type": "module",
+	"private": true,
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts"
+}
diff --git a/packages/ui-contract/src/index.ts b/packages/ui-contract/src/index.ts
new file mode 100644
index 0000000..ea0fc26
--- /dev/null
+++ b/packages/ui-contract/src/index.ts
@@ -0,0 +1,198 @@
+/**
+ * UI contract — the frontend-agnostic vocabulary for backend-declared "surfaces".
+ *
+ * A SURFACE is a "data transportation surface": a typed description of what data an
+ * extension exposes, its semantics, and the actions that can act on it — NOT UI. It
+ * carries STRUCTURE + SEMANTICS + ACTIONS, never styling and never a rendering-
+ * framework token. Any client (web/Svelte, CLI, future TUI/mobile) renders a surface
+ * in its own idiom, so swapping or adding a client is a zero-backend-change event.
+ * See `notes/frontend-design.md` §4.
+ *
+ * This package is types-only (zero runtime) and has ZERO `@dispatch/*` dependencies,
+ * so a separate client repo can depend on JUST this contract.
+ */
+
+/**
+ * Where a surface mounts — a coarse, semantic placement hint, NOT a layout/CSS
+ * instruction. A client maps a region to its own idiom; an unknown region falls back
+ * to the client's default placement. Deliberately left open (a `string`): region
+ * names are not finalized (the old-Dispatch "view" sidebar UX will be revisited).
+ */
+export type Region = string;
+
+/**
+ * A typed reference to a backend action a field can invoke. The client posts it back
+ * (with a payload) to `POST /surfaces/:surfaceId/actions/:actionId`; the surface id
+ * comes from context. (Backend-side this maps to a `command` today — a future review
+ * may unify `command` → `action`; see `notes/restructure-plan.md` §8.)
+ */
+export interface ActionRef {
+	readonly actionId: string;
+}
+
+/** One selectable option in a `selector` field. */
+export interface SurfaceOption {
+	readonly value: string;
+	readonly label: string;
+}
+
+/**
+ * A field within a surface — a SEMANTIC value, not a widget. `kind` is the
+ * discriminant a client switches on to pick a renderer. Names are training-baked
+ * hints; the contract is the data shape.
+ */
+export type SurfaceField =
+	| ToggleField
+	| ProgressField
+	| SelectorField
+	| StatField
+	| ButtonField
+	| CustomField;
+
+/** A boolean setting plus the action that flips it. */
+export interface ToggleField {
+	readonly kind: "toggle";
+	readonly label: string;
+	readonly value: boolean;
+	readonly action: ActionRef;
+}
+
+/** A bounded ratio in [0, 1] with a label (e.g. a cache-hit rate). Read-only. */
+export interface ProgressField {
+	readonly kind: "progress";
+	readonly label: string;
+	readonly value: number;
+}
+
+/** An enum choice: the current value, the options, and the action that sets it. */
+export interface SelectorField {
+	readonly kind: "selector";
+	readonly label: string;
+	readonly value: string;
+	readonly options: readonly SurfaceOption[];
+	readonly action: ActionRef;
+}
+
+/** A read-only labelled scalar readout. */
+export interface StatField {
+	readonly kind: "stat";
+	readonly label: string;
+	readonly value: string;
+}
+
+/** A labelled action trigger. */
+export interface ButtonField {
+	readonly kind: "button";
+	readonly label: string;
+	readonly action: ActionRef;
+}
+
+/**
+ * The escape hatch (isolation guardrail 2): data that fits no semantic field kind.
+ * Carries an opaque `payload` + a `rendererId`; clients WITH a renderer for that id
+ * show it, others GRACEFULLY SKIP. Keep rare — and the owning extension should export
+ * a typed payload type so its bespoke renderer narrows `payload` via a typed symbol
+ * (not a blind `unknown`).
+ */
+export interface CustomField {
+	readonly kind: "custom";
+	readonly rendererId: string;
+	readonly payload: unknown;
+}
+
+/**
+ * A surface: an ordered set of fields mounted in a region, with a title. The atomic
+ * unit a backend extension contributes and a client renders.
+ */
+export interface SurfaceSpec {
+	readonly id: string;
+	readonly region: Region;
+	readonly title: string;
+	readonly fields: readonly SurfaceField[];
+}
+
+/**
+ * A surface-catalog entry — discovery metadata only (no field data). Returned by
+ * `GET /surfaces`; parallels the model catalog. The full spec + live values come from
+ * `GET /surfaces/:id`.
+ */
+export interface SurfaceCatalogEntry {
+	readonly id: string;
+	readonly region: Region;
+	readonly title: string;
+}
+
+/** The surface catalog: the list of available surfaces a client can choose to show. */
+export type SurfaceCatalog = readonly SurfaceCatalogEntry[];
+
+/**
+ * A live update for a subscribed surface (pushed over the WS channel — §5). v1
+ * carries the full new spec (the simplest "patch"); granular field-level patches are
+ * deferred until a real surface needs them (P4).
+ */
+export interface SurfaceUpdate {
+	readonly surfaceId: string;
+	readonly spec: SurfaceSpec;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Surface WebSocket protocol — the typed message envelopes the surface channel
+// carries. The carrier (a WebSocket) is INJECTED; these are the payloads both the
+// server (transport-ws) and any client serialize/deserialize. Slice 1 is
+// surfaces-only; chat deltas join this channel in a later slice (a separate union).
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** A client → server message on the surface channel. */
+export type SurfaceClientMessage = SubscribeMessage | UnsubscribeMessage | InvokeMessage;
+
+/** Begin receiving live updates for a surface (server replies with `surface`, then `update`s). */
+export interface SubscribeMessage {
+	readonly type: "subscribe";
+	readonly surfaceId: string;
+}
+
+/** Stop receiving updates for a surface. */
+export interface UnsubscribeMessage {
+	readonly type: "unsubscribe";
+	readonly surfaceId: string;
+}
+
+/** Invoke a field's action; `payload` is the new value (e.g. a toggle's boolean). */
+export interface InvokeMessage {
+	readonly type: "invoke";
+	readonly surfaceId: string;
+	readonly actionId: string;
+	readonly payload?: unknown;
+}
+
+/** A server → client message on the surface channel. */
+export type SurfaceServerMessage =
+	| CatalogMessage
+	| SurfaceMessage
+	| SurfaceUpdateMessage
+	| SurfaceErrorMessage;
+
+/** The current surface catalog (sent on connect and whenever it changes). */
+export interface CatalogMessage {
+	readonly type: "catalog";
+	readonly catalog: SurfaceCatalog;
+}
+
+/** The full current spec for a surface the client just subscribed to. */
+export interface SurfaceMessage {
+	readonly type: "surface";
+	readonly spec: SurfaceSpec;
+}
+
+/** A live update for a subscribed surface. */
+export interface SurfaceUpdateMessage {
+	readonly type: "update";
+	readonly update: SurfaceUpdate;
+}
+
+/** A surface-scoped error (e.g. unknown surface id, invoke failed). */
+export interface SurfaceErrorMessage {
+	readonly type: "error";
+	readonly surfaceId?: string;
+	readonly message: string;
+}
diff --git a/packages/ui-contract/tsconfig.json b/packages/ui-contract/tsconfig.json
new file mode 100644
index 0000000..2a3be7e
--- /dev/null
+++ b/packages/ui-contract/tsconfig.json
@@ -0,0 +1,5 @@
+{
+	"extends": "../../tsconfig.base.json",
+	"compilerOptions": { "rootDir": "src", "outDir": "dist", "composite": true },
+	"include": ["src/**/*.ts"]
+}
diff --git a/packages/wire/package.json b/packages/wire/package.json
new file mode 100644
index 0000000..2893e79
--- /dev/null
+++ b/packages/wire/package.json
@@ -0,0 +1,8 @@
+{
+	"name": "@dispatch/wire",
+	"version": "0.0.0",
+	"type": "module",
+	"private": true,
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts"
+}
diff --git a/packages/wire/src/index.ts b/packages/wire/src/index.ts
new file mode 100644
index 0000000..d2ea341
--- /dev/null
+++ b/packages/wire/src/index.ts
@@ -0,0 +1,221 @@
+/**
+ * @dispatch/wire — pure wire types shared by the kernel, the transport
+ * contract, and out-of-repo clients (the web frontend).
+ *
+ * Types ONLY: zero runtime, zero `@dispatch/*` dependencies, so a client can
+ * depend on the wire without pulling the kernel runtime.
+ */
+
+// ─── Conversation model ─────────────────────────────────────────────────────
+
+/** Who produced a message. */
+export type Role = "system" | "user" | "assistant" | "tool";
+
+/** Opaque identifier for a turn (one user→assistant cycle). */
+export type TurnId = string & { readonly __brand: "TurnId" };
+
+/** Opaque identifier for a step (one LLM round-trip within a turn). */
+export type StepId = string & { readonly __brand: "StepId" };
+
+/**
+ * A chunk is one ordered piece of a message — the atomic unit of the
+ * append-only conversation log. Discriminated by `type`.
+ */
+export type Chunk =
+	| TextChunk
+	| ThinkingChunk
+	| ToolCallChunk
+	| ToolResultChunk
+	| ErrorChunk
+	| SystemChunk;
+
+/** A piece of plain text content from the assistant or user. */
+export interface TextChunk {
+	readonly type: "text";
+	readonly text: string;
+}
+
+/** A piece of model reasoning / thinking content (e.g. extended thinking). */
+export interface ThinkingChunk {
+	readonly type: "thinking";
+	readonly text: string;
+}
+
+/**
+ * A model's request to run a tool. The kernel routes by `name`; the tool
+ * implementation never sees this directly — it receives parsed `input` via
+ * `ToolContract.execute`.
+ */
+export interface ToolCallChunk {
+	readonly type: "tool-call";
+	readonly toolCallId: string;
+	readonly toolName: string;
+	readonly input: unknown;
+}
+
+/**
+ * The result of a tool execution, attributed to the originating tool-call id.
+ * The kernel guarantees every tool-call chunk gets exactly one result chunk
+ * (synthesized if interrupted — see reconcile).
+ */
+export interface ToolResultChunk {
+	readonly type: "tool-result";
+	readonly toolCallId: string;
+	readonly toolName: string;
+	readonly content: string;
+	readonly isError: boolean;
+}
+
+/** An error that occurred during generation or tool dispatch. */
+export interface ErrorChunk {
+	readonly type: "error";
+	readonly message: string;
+	readonly code?: string;
+}
+
+/**
+ * A system-injected message (e.g. system prompt, context assembly output).
+ * Kept distinct from text so the log records provenance.
+ */
+export interface SystemChunk {
+	readonly type: "system";
+	readonly text: string;
+}
+
+/**
+ * A chat message: a role plus an ordered sequence of chunks. Messages are the
+ * unit passed to and from the provider; chunks are the unit persisted and
+ * rendered.
+ */
+export interface ChatMessage {
+	readonly role: Role;
+	readonly chunks: readonly Chunk[];
+}
+
+// ─── Usage ──────────────────────────────────────────────────────────────────
+
+/**
+ * Token usage counters for a single step. All fields are counts of tokens.
+ * Cache fields are optional because not all providers expose cache metrics.
+ */
+export interface Usage {
+	readonly inputTokens: number;
+	readonly outputTokens: number;
+	readonly cacheReadTokens?: number;
+	readonly cacheWriteTokens?: number;
+}
+
+// ─── Outward events ─────────────────────────────────────────────────────────
+
+/**
+ * The union of all events the runtime emits outward during a turn.
+ * Consumers (transport, persistence, notifications) pattern-match on `type`.
+ */
+export type AgentEvent =
+	| StatusEvent
+	| TurnStartEvent
+	| TurnTextDeltaEvent
+	| TurnReasoningDeltaEvent
+	| TurnToolCallEvent
+	| TurnToolResultEvent
+	| TurnToolOutputEvent
+	| TurnUsageEvent
+	| TurnErrorEvent
+	| TurnDoneEvent
+	| TurnSealedEvent;
+
+/** Status change for a conversation (e.g. idle → running). */
+export interface StatusEvent {
+	readonly type: "status";
+	readonly conversationId: string;
+	readonly status: string;
+}
+
+/** A turn has begun. */
+export interface TurnStartEvent {
+	readonly type: "turn-start";
+	readonly conversationId: string;
+	readonly turnId: string;
+}
+
+/** Incremental text content from the model during a turn. */
+export interface TurnTextDeltaEvent {
+	readonly type: "text-delta";
+	readonly conversationId: string;
+	readonly turnId: string;
+	readonly delta: string;
+}
+
+/** Incremental reasoning / thinking content during a turn. */
+export interface TurnReasoningDeltaEvent {
+	readonly type: "reasoning-delta";
+	readonly conversationId: string;
+	readonly turnId: string;
+	readonly delta: string;
+}
+
+/** The model has requested a tool to be run. */
+export interface TurnToolCallEvent {
+	readonly type: "tool-call";
+	readonly conversationId: string;
+	readonly turnId: string;
+	readonly toolCallId: string;
+	readonly toolName: string;
+	readonly input: unknown;
+}
+
+/** A tool has completed execution. */
+export interface TurnToolResultEvent {
+	readonly type: "tool-result";
+	readonly conversationId: string;
+	readonly turnId: string;
+	readonly toolCallId: string;
+	readonly toolName: string;
+	readonly content: string;
+	readonly isError: boolean;
+}
+
+/** Streaming output from a tool execution (e.g. shell stdout/stderr). */
+export interface TurnToolOutputEvent {
+	readonly type: "tool-output";
+	readonly conversationId: string;
+	readonly turnId: string;
+	readonly toolCallId: string;
+	readonly data: string;
+	readonly stream: "stdout" | "stderr";
+}
+
+/** Token usage for the current step or turn. */
+export interface TurnUsageEvent {
+	readonly type: "usage";
+	readonly conversationId: string;
+	readonly turnId: string;
+	readonly usage: Usage;
+}
+
+/** An error occurred during the turn. */
+export interface TurnErrorEvent {
+	readonly type: "error";
+	readonly conversationId: string;
+	readonly turnId: string;
+	readonly message: string;
+	readonly code?: string;
+}
+
+/** The turn has completed (model finished generating). */
+export interface TurnDoneEvent {
+	readonly type: "done";
+	readonly conversationId: string;
+	readonly turnId: string;
+	readonly reason: string;
+}
+
+/**
+ * The turn has been sealed — all chunks persisted, history is final.
+ * This is the hook point for post-turn extensions (compaction, cache-warm).
+ */
+export interface TurnSealedEvent {
+	readonly type: "turn-sealed";
+	readonly conversationId: string;
+	readonly turnId: string;
+}
diff --git a/packages/wire/tsconfig.json b/packages/wire/tsconfig.json
new file mode 100644
index 0000000..2a3be7e
--- /dev/null
+++ b/packages/wire/tsconfig.json
@@ -0,0 +1,5 @@
+{
+	"extends": "../../tsconfig.base.json",
+	"compilerOptions": { "rootDir": "src", "outDir": "dist", "composite": true },
+	"include": ["src/**/*.ts"]
+}