acrylblends 0.9.2 → 0.10.0

package/plugins/driver-pty/index.ts

@@ -0,0 +1,249 @@
+/**
+ * The PTY driver (M8, spec 046 T029): `claude`, `codex`, `pi` or any program in a real terminal inside the app folder, shown as a terminal tab of the agent panel. The agent
+ * acts through the door as it does headless; the person sees and types into its own interactive mode.
+ *
+ * - The drivers are `terminal` entries of the panel's `drivers` service (`pty:claude`, ...). A panel without this plugin lists none; this plugin without a panel is pending.
+ * - Transport is server-sent events down and POST up (no WebSocket): `POST /api/driver-pty/sessions`, `GET /api/driver-pty/<id>/output` (events with ids; a reconnect replays
+ *   from `Last-Event-ID`, from a ring buffer of at least 64 KB), `POST .../input`, `.../resize`, `.../stop`. Same origin check and token as the panel, development only.
+ * - Every process is acquired inside one `ctx.effect`; its disposer ends the process (group), closes the streams and writes the audit line. Unloading or reloading the
+ *   plugin with a session open leaves no process behind.
+ */
+import { appendFileSync, mkdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import { clientModules } from '../acryl-node-server/src/client-modules.ts'
+import { streamSSE } from '../acryl-router/src/helpers/index.ts'
+import { Acryl } from '../acryl-router/src/index.ts'
+import type { TerminalDriver, TerminalSession } from '../agent-panel/drivers.ts'
+import { onPath } from '../agent-panel/headless.ts'
+import { loadNodePty, type PtySpawn } from './spawn.ts'
+import { terminalDriver } from './terminal.ts'
+
+export const name = 'driver-pty'
+export const inject = ['drivers', 'router', 'appInstance']
+
+export type { PtyProcess, PtySpawn } from './spawn.ts'
+export { terminalDriver } from './terminal.ts'
+
+const PREFIX = '/api/driver-pty'
+const CLIENT_DIR = join(import.meta.dirname, 'client')
+/** The least output a reconnecting page can be given again. */
+const SCROLLBACK = 64 * 1024
+
+export interface DriverPtyConfig {
+  /** Programs to offer, by name: the arguments to start them with. Default: `claude`, `codex` and `pi`, the ones found on the machine. */
+  programs?: Record<string, string[]>
+  /** The PTY implementation; default node-pty. Tests give a fake. */
+  spawn?: PtySpawn
+}
+
+interface Chunk {
+  readonly id: number
+  readonly text: string
+}
+type Item = Chunk | { exit: number | null } | { change: { extension: string; action: string } }
+interface Live {
+  readonly id: string
+  readonly driver: string
+  readonly session: TerminalSession
+  readonly chunks: Chunk[]
+  size: number
+  next: number
+  exit?: { code: number | null }
+  readonly listeners: Set<
+    (
+      item: Chunk | { exit: number | null } | { change: { extension: string; action: string } },
+    ) => Promise<void> | void
+  >
+  dispose(): Promise<void>
+}
+
+export async function apply(ctx: Context, config: DriverPtyConfig = {}): Promise<void> {
+  if (process.env.NODE_ENV === 'production' || process.env.ACRYL_DOOR === 'off') return
+  const root = ctx.appInstance.root
+  let spawn = config.spawn
+  if (!spawn) {
+    try {
+      spawn = await loadNodePty()
+    } catch (error) {
+      // No PTY here (no prebuilt binary, a sandbox): the panel lists no `pty:*` drivers, and says why.
+      console.warn(
+        `driver-pty: no terminal drivers, ${error instanceof Error ? error.message : String(error)}`,
+      )
+      return
+    }
+  }
+  const programs =
+    config.programs ??
+    Object.fromEntries(
+      (['claude', 'codex', 'pi'] as const).filter(onPath).map((p) => [p, [] as string[]]),
+    )
+  for (const [program, args] of Object.entries(programs))
+    ctx.effect(() => ctx.drivers.register(terminalDriver(`pty:${program}`, program, args, spawn)))
+
+  const auditFile = join(root, '.acryl', 'audit', 'driver-pty.jsonl')
+  const audit = (entry: Record<string, unknown>): void => {
+    try {
+      mkdirSync(dirname(auditFile), { recursive: true })
+      appendFileSync(auditFile, `${JSON.stringify({ at: new Date().toISOString(), ...entry })}\n`)
+    } catch {
+      // The audit never stops a session.
+    }
+  }
+
+  let live: Live | undefined
+  const refuse = (c: { json: (body: unknown, status: 403) => Response }) =>
+    c.json({ error: "only the app's own page may use the terminal" }, 403)
+  const find = (id: string): Live | undefined => (live?.id === id ? live : undefined)
+
+  /** Starts a session; the process is acquired in one effect whose disposer ends it, however the session ends. */
+  const startSession = (driver: TerminalDriver, cols: number, rows: number): Live => {
+    let state!: Live
+    let release!: () => Promise<void>
+    let notified = false
+    let finished = false
+    /** Tells every open stream the session ended (once), and ends it for later readers. */
+    const notify = async (code: number | null): Promise<void> => {
+      if (notified) return
+      notified = true
+      state.exit = { code }
+      const writes = [...state.listeners].map((listener) => listener({ exit: code }))
+      state.listeners.clear()
+      // Each write is accepted once its reader has taken it; a reader that went away must not hold the unload.
+      await Promise.race([
+        Promise.allSettled(writes),
+        new Promise((done) => setTimeout(done, 1000)),
+      ])
+    }
+    const finish = (code: number | null): void => {
+      void notify(code)
+      if (finished) return
+      finished = true
+      audit({ session: 'end', driver: driver.name, code })
+    }
+    release = ctx.effect(() => {
+      const session = driver.start({ cwd: root, env: process.env, cols, rows })
+      state = {
+        id: session.id,
+        driver: driver.name,
+        session,
+        chunks: [],
+        size: 0,
+        next: 1,
+        listeners: new Set(),
+        dispose: () => release(),
+      }
+      session.onData((text) => {
+        const chunk = { id: state.next++, text }
+        state.chunks.push(chunk)
+        state.size += text.length
+        while (state.chunks.length > 1 && state.size - state.chunks[0]!.text.length >= SCROLLBACK)
+          state.size -= state.chunks.shift()!.text.length
+        for (const listener of state.listeners) listener(chunk)
+      })
+      session.onExit((code) => finish(code))
+      return async () => {
+        // The streams are told first: unloading the plugin also takes its routes (and their open requests) down, and the page should hear why.
+        await notify(null)
+        await session.kill()
+        finish(null)
+      }
+    }) as () => Promise<void>
+    audit({ session: 'start', driver: driver.name })
+    return state
+  }
+
+  // A plugin installed or removed while a terminal is open (by the agent, through the door): the page is told, so it reloads and shows the new feature.
+  const off = ctx.on('extensions/changed', (extension: string, action: string) => {
+    if (live && !live.exit)
+      for (const listener of live.listeners) void listener({ change: { extension, action } })
+  })
+  ctx.effect(() => off)
+
+  const app = new Acryl()
+    .route(`${PREFIX}/client`, clientModules({ root: CLIENT_DIR }))
+    .post(`${PREFIX}/sessions`, async (c) => {
+      if (!ctx.drivers.authorized(c.req.raw.headers)) return refuse(c)
+      const body = (await c.req.json().catch(() => ({}))) as {
+        driver?: unknown
+        cols?: unknown
+        rows?: unknown
+      }
+      const driver = typeof body.driver === 'string' ? ctx.drivers.get(body.driver) : undefined
+      if (driver?.kind !== 'terminal')
+        return c.json({ error: `"${String(body.driver)}" is not a terminal driver here` }, 400)
+      if (live && !live.exit)
+        return c.json({ error: 'a terminal is already open; stop it first' }, 409)
+      const num = (value: unknown, fallback: number) =>
+        typeof value === 'number' && value >= 1 && value <= 1000 ? Math.floor(value) : fallback
+      live = startSession(driver, num(body.cols, 80), num(body.rows, 24))
+      return c.json({ id: live.id })
+    })
+    .get(`${PREFIX}/:id/output`, (c) => {
+      if (!ctx.drivers.authorized(c.req.raw.headers)) return refuse(c)
+      const current = find(c.req.param('id'))
+      if (!current) return c.json({ error: 'no such terminal' }, 404)
+      const last = Number(c.req.header('last-event-id') ?? 0)
+      return streamSSE(c, async (stream) => {
+        const send = (chunk: Chunk): Promise<void> =>
+          stream.writeSSE({ event: 'data', id: String(chunk.id), data: JSON.stringify(chunk.text) })
+        // A reconnect that is older than the buffer starts over: the page clears its terminal first.
+        const oldest = current.chunks[0]?.id ?? current.next
+        if (last !== 0 && last + 1 < oldest) await stream.writeSSE({ event: 'reset', data: '{}' })
+        for (const chunk of current.chunks) if (chunk.id > last) await send(chunk)
+        if (current.exit) {
+          await stream.writeSSE({
+            event: 'exit',
+            data: JSON.stringify({ code: current.exit.code }),
+          })
+          return
+        }
+        await new Promise<void>((done) => {
+          const listener = async (item: Item): Promise<void> => {
+            if ('change' in item)
+              return stream.writeSSE({ event: 'change', data: JSON.stringify(item.change) })
+            if (!('exit' in item)) return send(item)
+            await stream
+              .writeSSE({ event: 'exit', data: JSON.stringify({ code: item.exit }) })
+              .finally(done)
+          }
+          current.listeners.add(listener)
+          stream.onAbort(() => {
+            current.listeners.delete(listener)
+            done()
+          })
+        })
+      })
+    })
+    .post(`${PREFIX}/:id/input`, async (c) => {
+      if (!ctx.drivers.authorized(c.req.raw.headers)) return refuse(c)
+      const current = find(c.req.param('id'))
+      if (!current || current.exit) return c.json({ error: 'no such terminal' }, 404)
+      const { data } = (await c.req.json().catch(() => ({}))) as { data?: unknown }
+      if (typeof data !== 'string' || data.length > 64 * 1024)
+        return c.json({ error: 'input is a string of at most 64 KB' }, 400)
+      current.session.write(data)
+      return c.json({ ok: true })
+    })
+    .post(`${PREFIX}/:id/resize`, async (c) => {
+      if (!ctx.drivers.authorized(c.req.raw.headers)) return refuse(c)
+      const current = find(c.req.param('id'))
+      if (!current || current.exit) return c.json({ error: 'no such terminal' }, 404)
+      const { cols, rows } = (await c.req.json().catch(() => ({}))) as {
+        cols?: number
+        rows?: number
+      }
+      if (typeof cols !== 'number' || typeof rows !== 'number')
+        return c.json({ error: 'cols and rows are numbers' }, 400)
+      current.session.resize(cols, rows)
+      return c.json({ ok: true })
+    })
+    .post(`${PREFIX}/:id/stop`, async (c) => {
+      if (!ctx.drivers.authorized(c.req.raw.headers)) return refuse(c)
+      const current = find(c.req.param('id'))
+      if (!current) return c.json({ error: 'no such terminal' }, 404)
+      await current.dispose()
+      return c.json({ ok: true })
+    })
+  ctx.router.route('/', app)
+}

package/plugins/driver-pty/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "driver-pty",
+  "description": "A coding agent (claude, codex, pi, any program) in a real terminal inside the running app: the panel gets a terminal tab, the agent builds through the door in its own interactive mode. Development only; needs the agent panel; opt-in with acrylblends add driver-pty.",
+  "requires": ["acryl-router", "acryl-node-server", "agent-panel", "instance"],
+  "inject": ["drivers", "router", "appInstance"],
+  "provides": [],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4",
+    "node-pty": "1.2.0-beta.15"
+  },
+  "mount": "register it in src/app.ts ('driver-pty': driverPty) and add a row `- id: driver-pty` / `name: driver-pty` to blend.yaml AFTER the agent-panel row; open the panel and pick a `pty:` agent to get its terminal",
+  "gitignore": [".acryl/"]
+}

package/plugins/driver-pty/spawn.ts

@@ -0,0 +1,36 @@
+/** The one place that touches `node-pty`, a native module. Everything else works on this small seam, so tests run on a fake process. */
+
+export interface PtyProcess {
+  readonly pid: number
+  onData(listener: (chunk: string) => void): void
+  onExit(listener: (exit: { exitCode: number }) => void): void
+  write(data: string): void
+  resize(cols: number, rows: number): void
+  /** Ends the process; on Windows this is how it ends (ConPTY has no process groups). */
+  kill(): void
+}
+
+export type PtySpawn = (
+  file: string,
+  args: string[],
+  options: { cwd: string; env: NodeJS.ProcessEnv; cols: number; rows: number },
+) => PtyProcess
+
+/** Loads node-pty. Rejects with the reason (the error and the platform), so a log says why the driver is not offered. */
+export async function loadNodePty(): Promise<PtySpawn> {
+  try {
+    const pty = await import('node-pty')
+    return (file, args, options) =>
+      pty.spawn(file, args, {
+        name: 'xterm-256color',
+        cwd: options.cwd,
+        env: options.env as Record<string, string>,
+        cols: options.cols,
+        rows: options.rows,
+      })
+  } catch (error) {
+    throw new Error(
+      `node-pty could not be loaded on ${process.platform}/${process.arch}: ${error instanceof Error ? error.message : String(error)}`,
+    )
+  }
+}

package/plugins/driver-pty/terminal.ts

@@ -0,0 +1,84 @@
+/** A terminal driver: a program started in a pseudo-terminal, ended as a whole (the process group on POSIX, the console on Windows). */
+import { delimiter, join } from 'node:path'
+import type { TerminalDriver, TerminalSession } from '../agent-panel/drivers.ts'
+import type { PtySpawn } from './spawn.ts'
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+/** Whether any process of the group `pid` leads is still alive. */
+function groupAlive(pid: number): boolean {
+  try {
+    process.kill(process.platform === 'win32' ? pid : -pid, 0)
+    return true
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
+let counter = 0
+
+export function terminalDriver(
+  name: string,
+  program: string,
+  args: string[],
+  spawn: PtySpawn,
+): TerminalDriver {
+  return {
+    kind: 'terminal',
+    name,
+    start({ cwd, env, cols, rows }): TerminalSession {
+      // The agent runs `acryl look` without the folder prefix.
+      const path = [join(cwd, '.acryl', 'bin'), env.PATH].filter(Boolean).join(delimiter)
+      const proc = spawn(program, args, { cwd, env: { ...env, PATH: path }, cols, rows })
+      const dataListeners = new Set<(chunk: string) => void>()
+      const exitListeners = new Set<(code: number | null) => void>()
+      let exited = false
+      proc.onData((chunk) => {
+        for (const listener of dataListeners) listener(chunk)
+      })
+      proc.onExit(({ exitCode }) => {
+        exited = true
+        for (const listener of exitListeners) listener(exitCode)
+      })
+      const signalGroup = (signal: NodeJS.Signals): void => {
+        try {
+          process.kill(-proc.pid, signal)
+        } catch {
+          // The group is already gone.
+        }
+      }
+      const gone = async (ms: number): Promise<boolean> => {
+        for (let waited = 0; waited < ms; waited += 25) {
+          if (process.platform === 'win32' ? exited : !groupAlive(proc.pid)) return true
+          await sleep(25)
+        }
+        return process.platform === 'win32' ? exited : !groupAlive(proc.pid)
+      }
+      return {
+        id: `${name}-${++counter}`,
+        onData(listener) {
+          dataListeners.add(listener)
+          return () => void dataListeners.delete(listener)
+        },
+        onExit(listener) {
+          exitListeners.add(listener)
+          return () => void exitListeners.delete(listener)
+        },
+        write: (data) => proc.write(data),
+        resize: (c, r) => proc.resize(Math.max(1, c), Math.max(1, r)),
+        async kill() {
+          if (await gone(0)) return
+          if (process.platform === 'win32') {
+            proc.kill()
+            await gone(2000)
+            return
+          }
+          signalGroup('SIGHUP')
+          if (await gone(2000)) return
+          signalGroup('SIGKILL')
+          await gone(2000)
+        },
+      }
+    },
+  }
+}