acrylblends 0.9.2 → 0.11.0

package/plugins/acryl-node-server/src/test-websocket.ts

@@ -0,0 +1,110 @@
+/**
+ * An in-process WebSocket pair for tests (spec 047 T009): runs an upgrade route the way the adapters do, with no socket and no network. `testWebSocket(fetch, '/path', { headers })`
+ * answers either a refusal (`status`, no `socket`) or an accepted connection whose client side sends text frames, receives what the handler sent, and closes.
+ *
+ *   const { socket } = await testWebSocket((request, env) => app.fetch(request, env), '/stream', { headers: { origin: 'http://127.0.0.1:3000' } })
+ *   socket.send('hello'); expect(socket.received).toEqual(['echo hello'])
+ */
+import type { IncomingMessage } from 'node:http'
+import { CONNECTION_SYMBOL_KEY, WAIT_FOR_WEBSOCKET_SYMBOL } from './adapter/websocket.ts'
+import type { WebSocketData, WebSocketLike } from './adapter/websocket-types.ts'
+
+type Listener = (...args: never[]) => void
+
+/** The client side of an accepted test connection. */
+export interface TestSocket {
+  /** Frames the handler sent, in order (text only). */
+  readonly received: string[]
+  /** The code and reason the handler closed with, when it did. */
+  readonly closed: { readonly code: number | undefined; readonly reason: string | undefined } | undefined
+  /** Send a text frame to the handler. */
+  send(text: string): void
+  /** Close from the client side. */
+  close(code?: number, reason?: string): void
+}
+
+export interface TestWebSocketOptions {
+  readonly headers?: Record<string, string>
+  /** The socket's peer address and local port, as an adapter would pass them. */
+  readonly connection?: { readonly remoteAddress?: string; readonly localPort?: number }
+  /** The URL origin the request is made against; default `http://127.0.0.1`. */
+  readonly base?: string
+}
+
+export interface TestWebSocketResult {
+  /** The refusal's status, or 101 when the upgrade was accepted. */
+  readonly status: number
+  readonly socket?: TestSocket
+}
+
+/** A fake `ws` socket: events go both ways without a network. */
+class FakeSocket implements WebSocketLike {
+  protocol = ''
+  readyState: 0 | 1 | 2 | 3 = 1
+  bufferedAmount = 0
+  readonly sent: string[] = []
+  closedWith: { code: number | undefined; reason: string | undefined } | undefined
+  private readonly listeners = new Map<string, Listener[]>()
+  on(event: string, listener: Listener): this {
+    this.listeners.set(event, [...(this.listeners.get(event) ?? []), listener])
+    return this
+  }
+  off(event: string, listener: Listener): this {
+    this.listeners.set(event, (this.listeners.get(event) ?? []).filter(l => l !== listener))
+    return this
+  }
+  emit(event: string, ...args: unknown[]): void {
+    for (const listener of this.listeners.get(event) ?? []) (listener as (...a: unknown[]) => void)(...args)
+  }
+  send(data: WebSocketData | ArrayBufferView): void {
+    this.sent.push(typeof data === 'string' ? data : Buffer.from(data as Uint8Array).toString('utf8'))
+  }
+  close(code?: number, reason?: string): void {
+    if (this.readyState === 3) return
+    this.closedWith = { code, reason }
+    this.readyState = 3
+    this.emit('close', code ?? 1005, Buffer.from(reason ?? ''))
+  }
+  ping(): void {}
+  terminate(): void {
+    this.close(1006)
+  }
+}
+
+export async function testWebSocket(
+  fetch: (request: Request, env: object) => Promise<Response>,
+  path: string,
+  options: TestWebSocketOptions = {},
+): Promise<TestWebSocketResult> {
+  const fake = new FakeSocket()
+  let waiter: { connectionSymbol: symbol; resolve: (ws: WebSocketLike) => void } | undefined
+  const incoming = { headers: options.headers ?? {}, socket: { remoteAddress: options.connection?.remoteAddress, localPort: options.connection?.localPort } } as unknown as IncomingMessage
+  const env: Record<symbol | string, unknown> = {
+    incoming,
+    outgoing: undefined,
+    wss: {},
+    [WAIT_FOR_WEBSOCKET_SYMBOL]: (_request: IncomingMessage, connectionSymbol: symbol) =>
+      new Promise<WebSocketLike>(resolve => {
+        waiter = { connectionSymbol, resolve }
+      }),
+  }
+  const headers = new Headers({ upgrade: 'websocket', connection: 'Upgrade', ...options.headers })
+  const response = await fetch(new Request(new URL(path, options.base ?? 'http://127.0.0.1'), { headers }), env)
+  if (!waiter || waiter.connectionSymbol !== env[CONNECTION_SYMBOL_KEY]) return { status: response.status }
+  waiter.resolve(fake)
+  // The handler's open event and buffered messages run on the next turns.
+  await new Promise(resolve => setTimeout(resolve, 0))
+  const socket: TestSocket = {
+    received: fake.sent,
+    get closed() {
+      return fake.closedWith
+    },
+    send: text => fake.emit('message', text, false),
+    close: (code, reason) => {
+      if (fake.readyState === 3) return
+      fake.readyState = 3
+      fake.emit('close', code ?? 1005, Buffer.from(reason ?? ''))
+    },
+  }
+  return { status: 101, socket }
+}

package/plugins/acryl-node-server/src/upgrade-hub.ts

@@ -0,0 +1,152 @@
+/**
+ * WebSocket upgrades for the Cordis adapters (spec 047 T009): one hub per HTTP transport. It owns the `ws` server (text and size limits, no compression), runs the ported
+ * `setupWebSocket` on whatever emits `upgrade` events (a `node:http` server, or the Host web server's exact-path upgrade routes), pings every socket and ends the ones that stop
+ * answering, and gives each mounting plugin an `upgradeWebSocket` whose accepted sockets belong to that plugin: when it unloads they are closed with 1001 within the grace, and
+ * what is left is terminated. The handler sees `close` exactly once.
+ */
+import { EventEmitter } from 'node:events'
+import { createRequire } from 'node:module'
+import type { UpgradeWebSocket } from 'acryl-router/helpers'
+import type { FetchCallback } from './adapter/types.ts'
+import { type UpgradeSource, setupWebSocket, upgradeWebSocket as portedUpgradeWebSocket } from './adapter/websocket.ts'
+import type { WebSocketLike, WebSocketServerLike } from './adapter/websocket-types.ts'
+
+export interface UpgradeHubOptions {
+  /** The largest frame accepted, in bytes; a bigger one closes the socket with 1009. Default 1 MiB. */
+  maxPayload?: number
+  /** Milliseconds between pings; a peer that did not answer the previous one is terminated. Default 30 000; 0 turns the heartbeat off. */
+  heartbeat?: number
+  /** Milliseconds a closing socket gets to finish its close handshake before it is terminated. Default 2000. */
+  grace?: number
+}
+
+type WebSocketServerConstructor = new (options: {
+  noServer: true
+  maxPayload: number
+  perMessageDeflate: false
+}) => WebSocketServerLike
+
+/** The `ws` package, loaded when the first hub is made: an app that never upgrades does not need it. */
+function loadWs(): WebSocketServerConstructor {
+  try {
+    return (createRequire(import.meta.url)('ws') as { WebSocketServer: WebSocketServerConstructor }).WebSocketServer
+  } catch (error) {
+    throw new Error(`WebSocket upgrades need the "ws" package (npm install ws): ${error instanceof Error ? error.message : String(error)}`)
+  }
+}
+
+/** The part of the router a hub calls: run a request with connection facts and the adapter's bindings. */
+export interface UpgradeRouter {
+  fetch(request: Request, connection: { remoteAddress?: string | undefined; localPort?: number | undefined }, bindings?: object): Promise<Response>
+}
+
+/** What a hub needs of a Cordis context: tying a disposer to the plugin that asked. */
+export interface Owner {
+  effect(execute: () => () => unknown, label?: string): unknown
+}
+
+export class UpgradeHub {
+  readonly server: WebSocketServerLike
+  private readonly all = new Set<WebSocketLike>()
+  private readonly alive = new WeakMap<WebSocketLike, boolean>()
+  private readonly grace: number
+  private timer: ReturnType<typeof setInterval> | undefined
+  private closed = false
+
+  constructor(options: UpgradeHubOptions = {}) {
+    const Server = loadWs()
+    this.server = new Server({ noServer: true, maxPayload: options.maxPayload ?? 1024 * 1024, perMessageDeflate: false })
+    this.grace = options.grace ?? 2000
+    this.server.on('connection', ws => {
+      this.all.add(ws)
+      this.alive.set(ws, true)
+      ws.on('pong', () => this.alive.set(ws, true))
+      ws.on('close', () => this.all.delete(ws))
+    })
+    const heartbeat = options.heartbeat ?? 30_000
+    if (heartbeat > 0) {
+      this.timer = setInterval(() => {
+        for (const ws of this.all) {
+          if (this.alive.get(ws) === false) {
+            ws.terminate()
+            continue
+          }
+          this.alive.set(ws, false)
+          ws.ping()
+        }
+      }, heartbeat)
+      this.timer.unref()
+    }
+  }
+
+  /**
+   * Accept upgrades from `source` and answer them with `router`: the request runs through the router's middleware with the socket's peer address and local port as connection
+   * facts (so the same loopback, origin and host checks work), and the upgrade bindings travel in `c.env` for `upgradeWebSocket`.
+   */
+  attach(source: UpgradeSource, router: UpgradeRouter): void {
+    const fetchCallback: FetchCallback = (request, env) => {
+      const { incoming } = env as { incoming: { socket: { remoteAddress?: string; localPort?: number } } }
+      return router.fetch(request, { remoteAddress: incoming.socket.remoteAddress, localPort: incoming.socket.localPort }, env)
+    }
+    setupWebSocket({ server: source, fetchCallback, wss: this.server })
+  }
+
+  /** How many sockets are open. */
+  get size(): number {
+    return this.all.size
+  }
+
+  /** `upgradeWebSocket` for the plugin `owner`: the sockets it accepts are closed with 1001 when that plugin unloads. */
+  upgradeWebSocketFor(owner: Owner): UpgradeWebSocket<WebSocketLike> {
+    const mine = new Set<WebSocketLike>()
+    owner.effect(() => () => this.closeAll(mine, 1001, 'going away'), 'upgrade sockets')
+    const track = (ws: WebSocketLike): void => {
+      mine.add(ws)
+      ws.on('close', () => mine.delete(ws))
+    }
+    const owned = (...args: unknown[]): unknown => {
+      const [first, second, third] = args as [unknown, Record<string, unknown> | undefined, Record<string, unknown> | undefined]
+      return typeof first === 'function'
+        ? (portedUpgradeWebSocket as (...a: unknown[]) => unknown)(first, { ...second, track })
+        : (portedUpgradeWebSocket as (...a: unknown[]) => unknown)(first, second, { ...third, track })
+    }
+    return owned as UpgradeWebSocket<WebSocketLike>
+  }
+
+  /** Close `sockets` with `code`, wait for their close handshakes up to the grace, terminate what is left. */
+  async closeAll(sockets: Iterable<WebSocketLike>, code: number, reason: string): Promise<void> {
+    const open = [...sockets].filter(ws => ws.readyState < 3)
+    await Promise.all(
+      open.map(
+        ws =>
+          new Promise<void>(resolve => {
+            const timer = setTimeout(() => {
+              ws.terminate()
+              resolve()
+            }, this.grace)
+            ws.on('close', () => {
+              clearTimeout(timer)
+              resolve()
+            })
+            if (ws.readyState === 1) ws.close(code, reason)
+            else if (ws.readyState === 3) {
+              clearTimeout(timer)
+              resolve()
+            }
+          }),
+      ),
+    )
+  }
+
+  /** End everything: every socket closes with 1001, the heartbeat stops, the `ws` server closes. */
+  async close(): Promise<void> {
+    if (this.closed) return
+    this.closed = true
+    if (this.timer !== undefined) clearInterval(this.timer)
+    await this.closeAll(this.all, 1001, 'going away')
+    this.server.close()
+  }
+}
+
+/** A stand-in for a server's `upgrade` events, for transports that dispatch upgrades themselves (the Host web server's exact-path routes). */
+export class UpgradeEmitter extends EventEmitter {}

package/plugins/acryl-router/src/core/helper/websocket/index.ts

@@ -54,6 +54,8 @@ export interface WSContextInit<T = unknown> {
 
   raw?: T
   readyState: WSReadyState
+  /** Bytes queued to send and not yet written to the socket; a sender that cares about back-pressure reads it. */
+  bufferedAmount?: number
   url?: string | URL | null
   protocol?: string | null
 }
@@ -84,6 +86,9 @@ export class WSContext<T = unknown> {
   get readyState(): WSReadyState {
     return this.#init.readyState
   }
+  get bufferedAmount(): number {
+    return this.#init.bufferedAmount ?? 0
+  }
   url: URL | null
   protocol: string | null
   close(code?: number, reason?: string) {

package/plugins/acryl-router/src/service.ts

@@ -10,6 +10,7 @@
 import { Context, Service } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
 import type { ConnectionInfo, RouterBindings } from './connection.ts'
+import type { UpgradeWebSocket } from './core/helper/websocket/index.ts'
 import { Acryl } from './core/app.ts'
 import type { ExecutionContext } from './core/context.ts'
 import { HTTPException } from './core/http-exception.ts'
@@ -40,8 +41,19 @@ export const Config: z<Partial<Config>, Config> = z.object({
  * served over HTTP without depending on the adapter package.
  */
 export interface RouterHttpService {
-  /** Serve `prefix` and everything below it through the router; returns a remover. The mount also goes away when the calling plugin unloads. */
-  mount(prefix: string): () => void
+  /**
+   * Serve `prefix` and everything below it through the router; returns a remover. The mount also goes away when the calling plugin unloads.
+   * `options.upgrade` lists the exact paths below the prefix that may be upgraded to a WebSocket (each must be inside the prefix); no other path of the mount accepts an upgrade.
+   */
+  mount(prefix: string, options?: { readonly upgrade?: readonly string[] }): () => void
+  /**
+   * `upgradeWebSocket` for the calling plugin: `app.get('/terminal', upgrade((c) => ({ onMessage(event, ws) { ... } })))` on a route the plugin mounted with `upgrade: ['/terminal']`.
+   * Checks go in ordinary middleware on the route; a handler that returns a `Response` refuses with that status before any handshake. The sockets it accepts belong to the calling
+   * plugin: when it unloads they are closed with 1001 and the handler sees `close` once. Needs the `ws` package.
+   */
+  upgrades(): UpgradeWebSocket
+  /** How many WebSocket connections are open now. */
+  readonly sockets: number
 }
 
 declare module '@deepseek-ai/cordis' {
@@ -260,8 +272,9 @@ export class Router extends Service {
    * Run a request in process. Never throws: failures become a 500, a disposed router answers 503. `connection` describes the transport
    * (an HTTP adapter passes the socket's peer address and local port); an in-process caller omits it. Handlers read it with
    * `connectionOf(c)`, abort with `c.req.raw.signal` and keep the request in flight with `c.executionCtx.waitUntil(task)`.
+   * `bindings` is an object an adapter hands to the handler as `c.env` (an upgrade request's socket hooks, for `upgradeWebSocket`); `connection` is added to it.
    */
-  fetch(request: Request, connection: ConnectionInfo = {}): Promise<Response> {
+  fetch(request: Request, connection: ConnectionInfo = {}, bindings?: object): Promise<Response> {
     if (this.state.closing) return Promise.resolve(new Response('Service Unavailable', { status: 503 }))
     const controller = new AbortController()
     const forward = (): void => controller.abort()
@@ -273,7 +286,8 @@ export class Router extends Service {
       passThroughOnException: () => {},
       props: {},
     }
-    const env: RouterBindings = { connection }
+    // `bindings` is used as `c.env` itself (not copied): the upgrade helper records its handshake state on it, and the adapter reads that state back after the handler answered.
+    const env: RouterBindings = bindings === undefined ? { connection } : Object.assign(bindings, { connection })
     let bodyDone: Promise<void> = Promise.resolve()
     let endBody = (): void => {}
     let resolveSettled!: (value: Promise<unknown>) => void

package/plugins/acryl-router-http/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "acryl-router-http",
-  "description": "The serve() and request bridge that acryl-node-server uses to put the router on node:http. Mounting it as a plugin needs the DSH web server, which a generated app does not have. Vendored from ACRYL.",
-  "requires": ["acryl-router"],
+  "description": "Mounts router prefixes on the ACRYL Host's web server, with exact-path WebSocket upgrades owned by the mounting plugin, and the serve() and request bridge. Mounting it as a plugin needs the Host web server, which a generated app does not have. Vendored from ACRYL.",
+  "requires": ["acryl-router", "acryl-node-server"],
   "inject": ["router"],
   "provides": [],
   "dependencies": {

package/plugins/acryl-router-http/src/index.ts

@@ -5,8 +5,11 @@
  */
 
 import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { Duplex } from 'node:stream'
 import type { RouterHttpService } from 'acryl-router'
+import type { UpgradeWebSocket } from 'acryl-router/helpers'
 import { Context, Service } from '@deepseek-ai/cordis'
+import { UpgradeEmitter, UpgradeHub } from 'acryl-node-server'
 import { serve } from './serve.ts'
 
 /** Stable Cordis plugin name, equal to the package name and the Loader row id. */
@@ -25,6 +28,11 @@ export interface WebServerPort {
     readonly path: string
     readonly handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
   }): () => void
+  /** One exact-path upgrade claim (`WebUpgradeRoute` of the web server); optional because an older web server has none. */
+  registerUpgrade?(route: {
+    readonly path: string
+    readonly handler: (req: IncomingMessage, socket: Duplex, head: Buffer) => void | Promise<void>
+  }): () => void
 }
 
 const PREFIX_PATTERN = /^\/[A-Za-z0-9._~\-/]*[A-Za-z0-9._~-]$/
@@ -32,9 +40,14 @@ const PREFIX_PATTERN = /^\/[A-Za-z0-9._~\-/]*[A-Za-z0-9._~-]$/
 export class RouterHttp extends Service implements RouterHttpService {
   private readonly router: Context['router']
   private readonly web: WebServerPort
+  private hub: UpgradeHub | undefined
+  /** The adapter's own context: the hub lives as long as the adapter, whichever plugin asked for it first (`this.ctx` is the caller's). */
+  private readonly home: Context
+  private readonly upgradesIn = new UpgradeEmitter()
 
   constructor(ctx: Context) {
     super(ctx, 'routerHttp')
+    this.home = ctx
     this.router = ctx.router
     this.web = ctx.get('webServer') as WebServerPort
   }
@@ -42,17 +55,68 @@ export class RouterHttp extends Service implements RouterHttpService {
   /**
    * Serve `prefix` and everything below it through the router. Returns a remover; the mount also goes away when the
    * calling plugin unloads. A prefix another route already claims throws, as the webServer treats it as misconfiguration.
+   * `options.upgrade` names the exact paths that may be upgraded to a WebSocket: each must be inside the prefix, and each is one
+   * exact-path upgrade route of the web server, removed with the mount. No other path of the mount accepts an upgrade.
    */
-  mount(prefix: string): () => void {
+  mount(prefix: string, options: { readonly upgrade?: readonly string[] } = {}): () => void {
     if (!PREFIX_PATTERN.test(prefix)) throw new TypeError(`acryl-router-http: "${prefix}" is not a mountable path prefix`)
-    const remove = this.web.register({
-      kind: 'prefix',
-      path: prefix,
-      handler: (req, res) => serve(this.router, req, res),
-    })
+    const upgrade = options.upgrade ?? []
+    for (const path of upgrade) {
+      if (!PREFIX_PATTERN.test(path) || !(path === prefix || path.startsWith(`${prefix}/`)))
+        throw new TypeError(`acryl-router-http: the upgrade path "${path}" is not inside the prefix "${prefix}"`)
+    }
+    if (upgrade.length > 0 && this.web.registerUpgrade === undefined)
+      throw new TypeError('acryl-router-http: this web server cannot take WebSocket upgrades (it has no registerUpgrade)')
+    const removers: Array<() => void> = []
+    // Claim the upgrade paths first: a duplicate throws before anything is mounted, so a refused mount leaves nothing behind.
+    try {
+      if (upgrade.length > 0) this.ensureHub()
+      for (const path of upgrade) {
+        removers.push(
+          (this.web.registerUpgrade as NonNullable<WebServerPort['registerUpgrade']>)({
+            path,
+            handler: (req, socket, head) => { this.upgradesIn.emit('upgrade', req, socket, head) },
+          }),
+        )
+      }
+      removers.push(
+        this.web.register({
+          kind: 'prefix',
+          path: prefix,
+          handler: (req, res) => serve(this.router, req, res),
+        }),
+      )
+    } catch (error) {
+      for (const remove of removers) remove()
+      throw error
+    }
+    const remove = (): void => { for (const undo of removers.splice(0)) undo() }
     this.ctx.effect(() => () => { remove() }, `acryl-router-http: mount ${prefix}`)
     return remove
   }
+
+  /**
+   * `upgradeWebSocket` for the calling plugin: the sockets its routes accept are closed with 1001 when it unloads. Needs the `ws` package.
+   * The route must be on a path the plugin mounted with `upgrade: [path]`.
+   */
+  upgrades(): UpgradeWebSocket {
+    return this.ensureHub().upgradeWebSocketFor(this.ctx) as unknown as UpgradeWebSocket
+  }
+
+  /** How many WebSocket connections are open now. */
+  get sockets(): number {
+    return this.hub?.size ?? 0
+  }
+
+  private ensureHub(): UpgradeHub {
+    if (!this.hub) {
+      const hub = new UpgradeHub()
+      hub.attach(this.upgradesIn, this.router)
+      this.hub = hub
+      this.home.effect(() => () => hub.close(), 'acryl-router-http: WebSocket hub')
+    }
+    return this.hub
+  }
 }
 
 export function apply(ctx: Context): void {

package/plugins/agent-panel/client/main.ts

@@ -4,7 +4,7 @@ const PREFIX = '/api/agent-panel'
 
 interface Session {
   token: string
-  drivers: string[]
+  drivers: Array<{ name: string; kind: 'chat' | 'terminal' }>
 }
 interface PanelEvent {
   event: string
@@ -42,6 +42,8 @@ section { position: fixed; top: 0; right: 0; bottom: 0; width: min(380px, 100vw)
 section.shown { display: flex }
 header { display: flex; gap: 8px; align-items: center; padding: 8px 12px; border-bottom: 1px solid #e5e7eb }
 header strong { flex: 1 }
+#term { flex: 1; min-height: 0; background: #000 }
+#term[hidden], form[hidden], #log[hidden] { display: none }
 #log { flex: 1; overflow: auto; padding: 12px; display: flex; flex-direction: column; gap: 8px }
 .msg { white-space: pre-wrap; padding: 8px 10px; border-radius: 8px; background: #f3f4f6 }
 .me { background: #dbeafe; align-self: flex-end }
@@ -65,8 +67,13 @@ async function start(): Promise<void> {
   shadow.innerHTML = `<style>${css}</style>
     <button class="open" type="button">Ask the agent</button>
     <section aria-label="Agent panel">
-      <header><strong>Agent</strong><select aria-label="Agent">${session.drivers.map((d) => `<option>${d}</option>`).join('')}</select><button class="close" type="button" aria-label="Close">×</button></header>
+      <header><strong>Agent</strong><select aria-label="Agent">${session.drivers
+        .map((d) => `<option>${d.name}</option>`)
+        .join(
+          '',
+        )}</select><button class="termstop" type="button" hidden>Stop terminal</button><button class="close" type="button" aria-label="Close">×</button></header>
       <div id="log" role="log"></div>
+      <div id="term" hidden></div>
       <form><textarea aria-label="Message" placeholder="What should the app do?"></textarea>
         <div class="row"><button class="send" type="submit">Send</button><button class="stop" type="button" disabled>Stop</button></div></form>
     </section>`
@@ -77,6 +84,54 @@ async function start(): Promise<void> {
   const send = $<HTMLButtonElement>('.send')
   const stop = $<HTMLButtonElement>('.stop')
   const driver = $<HTMLSelectElement>('select')
+  const term = $<HTMLElement>('#term')
+  const termStop = $<HTMLButtonElement>('.termstop')
+  termStop.addEventListener('click', () => void terminal?.stop())
+  const form = $<HTMLFormElement>('form')
+  const kindOf = (name: string): 'chat' | 'terminal' =>
+    session.drivers.find((d) => d.name === name)?.kind ?? 'chat'
+  let terminal: { detach(): void; stop(): Promise<void> } | undefined
+  // A terminal driver swaps the chat for the driver's own terminal (loaded from the plugin that provides it, only when asked for).
+  const choose = async (): Promise<void> => {
+    terminal?.detach()
+    terminal = undefined
+    const isTerminal = kindOf(driver.value) === 'terminal'
+    log.hidden = isTerminal
+    form.hidden = isTerminal
+    term.hidden = !isTerminal
+    termStop.hidden = !isTerminal
+    if (!isTerminal) return
+    try {
+      const url = '/api/driver-pty/client/terminal.ts'
+      const { openTerminal } = (await import(url)) as {
+        openTerminal(options: {
+          container: HTMLElement
+          token: string
+          driver: string
+          status(text: string): void
+          onChange(change: { extension: string; action: string }): void
+        }): Promise<{ detach(): void; stop(): Promise<void> }>
+      }
+      terminal = await openTerminal({
+        container: term,
+        token: session.token,
+        driver: driver.value,
+        status: (text) => line(text, 'tool'),
+        onChange: (change) => {
+          line(`plugin ${change.extension}: ${change.action}`, 'tool')
+          line('Reloading the page to show it.', 'tool')
+          setTimeout(() => location.reload(), 900)
+        },
+      })
+    } catch (error) {
+      line(
+        `The terminal could not open: ${error instanceof Error ? error.message : String(error)}`,
+        'err',
+      )
+      log.hidden = false
+    }
+  }
+  driver.addEventListener('change', () => void choose())
   const show = (open: boolean): void => {
     panel.classList.toggle('shown', open)
     if (open) input.focus()
@@ -154,6 +209,19 @@ async function start(): Promise<void> {
     }
   })
   document.body.append(host)
+  // A terminal that was open before a reload is still running on the server: show it again.
+  try {
+    const remembered = JSON.parse(sessionStorage.getItem('driver-pty-session') ?? 'null') as {
+      driver?: string
+    } | null
+    if (remembered?.driver && kindOf(remembered.driver) === 'terminal') {
+      driver.value = remembered.driver
+      show(true)
+      void choose()
+    }
+  } catch {
+    // No storage: nothing to show again.
+  }
 }
 
 void start()

package/plugins/agent-panel/drivers.ts

@@ -0,0 +1,83 @@
+/**
+ * The drivers the agent panel can offer, in one registry (the `drivers` service the panel provides). A driver is one of two kinds of session:
+ *
+ * - `chat`: a message in, the panel's own events out (`text`, `tool`, `error`). The app's agent, the headless coding agents and a harness chat are chat drivers.
+ * - `terminal`: bytes in, bytes out, a real pseudo-terminal (the `driver-pty` plugin). Nothing is forced to speak bytes.
+ *
+ * The panel lists every registered driver and picks the view by `kind`. A plugin that provides drivers injects `drivers`: with no panel mounted it is pending,
+ * and a panel without such a plugin simply lists none of its drivers.
+ */
+import type { Context } from '@deepseek-ai/cordis'
+
+/** One event of a chat run. The panel adds `change` (a plugin was installed or removed) and `done` itself. */
+export type ChatEvent =
+  | { readonly event: 'text'; readonly data: { readonly text: string } }
+  | { readonly event: 'tool'; readonly data: Record<string, unknown> }
+  | { readonly event: 'error'; readonly data: { readonly message: string } }
+
+export interface ChatDriver {
+  readonly kind: 'chat'
+  readonly name: string
+  /** Runs one message. Aborting `signal` stops the run. */
+  start(options: { message: string; signal: AbortSignal }): AsyncIterable<ChatEvent>
+}
+
+/** A live pseudo-terminal session. */
+export interface TerminalSession {
+  readonly id: string
+  onData(listener: (chunk: string) => void): () => void
+  onExit(listener: (code: number | null) => void): () => void
+  write(data: string): void
+  resize(cols: number, rows: number): void
+  /** Resolves when the process (group) is gone. */
+  kill(): Promise<void>
+}
+
+export interface TerminalDriver {
+  readonly kind: 'terminal'
+  readonly name: string
+  start(options: {
+    cwd: string
+    env: NodeJS.ProcessEnv
+    cols: number
+    rows: number
+  }): TerminalSession
+}
+
+export type Driver = ChatDriver | TerminalDriver
+
+export interface Drivers {
+  /** Add a driver. Returns the function that removes it; a plugin registers inside `ctx.effect` so the driver leaves with it. */
+  register(driver: Driver): () => void
+  list(): Driver[]
+  get(name: string): Driver | undefined
+  /** Whether a request may use the drivers' endpoints: it comes from the app's own page and carries the panel's token. */
+  authorized(headers: Headers): boolean
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    drivers: Drivers
+  }
+}
+
+export function createDrivers(authorized: (headers: Headers) => boolean = () => true): Drivers {
+  const table = new Map<string, Driver>()
+  return {
+    register(driver) {
+      if (table.has(driver.name)) throw new Error(`driver "${driver.name}" is already registered`)
+      table.set(driver.name, driver)
+      return () => void (table.get(driver.name) === driver && table.delete(driver.name))
+    },
+    list: () => [...table.values()],
+    get: (name) => table.get(name),
+    authorized,
+  }
+}
+
+/** Provide the registry on `ctx` (the panel does). */
+export function provideDrivers(ctx: Context, authorized: (headers: Headers) => boolean): Drivers {
+  const registry = createDrivers(authorized)
+  ;(ctx as Context).provide('drivers', registry)
+  return registry
+}