acrylblends 0.11.0 → 1.0.0

package/plugins/driver-acp/connection.ts

@@ -0,0 +1,239 @@
+/**
+ * One ACP agent process and the JSON-RPC 2.0 connection to it: newline-delimited messages over its stdin and stdout (the ACP stdio transport). The driver needs a handful of
+ * calls, so this is the whole client: requests with their answers, notifications both ways, and the agent's own requests answered by a handler. `close()` ends the process
+ * the way an ACP agent expects: stdin closed first, then SIGTERM, then a hard kill, and it resolves only once the process is gone.
+ */
+import { type ChildProcessWithoutNullStreams, spawn, spawnSync } from 'node:child_process'
+
+/** How to start an ACP agent: a program and its arguments, and what to add to the app's environment. */
+export interface AcpAgent {
+  readonly command: string
+  readonly args: readonly string[]
+  readonly env?: Readonly<Record<string, string>>
+}
+
+/** An error the agent answered with, or the reason the connection ended. */
+export class AcpError extends Error {
+  /** The JSON-RPC error code, for an error the agent answered with. */
+  readonly code: number | undefined
+
+  constructor(message: string, code?: number) {
+    super(message)
+    this.name = 'AcpError'
+    this.code = code
+  }
+}
+
+/** Answers a request the agent sends (`session/request_permission`); throwing answers with an error. */
+export type AgentRequestHandler = (method: string, params: unknown) => unknown
+
+/** How long each step of `close()` waits before the next, harder one. */
+const GRACE_MS = 2000
+/** The most of the agent's stderr kept, to say why it ended. */
+const STDERR_TAIL = 4000
+
+interface Pending {
+  resolve(value: unknown): void
+  reject(error: Error): void
+}
+
+export class AcpConnection {
+  readonly #child: ChildProcessWithoutNullStreams
+  readonly #pending = new Map<number, Pending>()
+  readonly #listeners = new Set<(method: string, params: unknown) => void>()
+  #nextId = 1
+  #buffer = ''
+  #stderr = ''
+  #ended: AcpError | undefined
+  /** Resolves with the reason once the process is gone. */
+  readonly ended: Promise<AcpError>
+
+  constructor(agent: AcpAgent, cwd: string, handle: AgentRequestHandler) {
+    this.#child = spawn(agent.command, [...agent.args], {
+      cwd,
+      env: { ...process.env, ...agent.env },
+      stdio: ['pipe', 'pipe', 'pipe'],
+      // An npm-installed agent is a `.cmd` shim on Windows, which only a shell can start.
+      shell: process.platform === 'win32',
+      // Its own process group on POSIX, so closing the connection also ends what the agent started (its tools, a shell): nothing is left behind when the plugin unloads.
+      detached: process.platform !== 'win32',
+      windowsHide: true,
+    })
+    this.ended = new Promise((resolve) => {
+      const end = (reason: AcpError): void => {
+        if (this.#ended) return
+        this.#ended = reason
+        for (const pending of this.#pending.values()) pending.reject(reason)
+        this.#pending.clear()
+        resolve(reason)
+      }
+      this.#child.on('error', (error) =>
+        end(new AcpError(`${agent.command} could not be started: ${error.message}`)),
+      )
+      this.#child.on('exit', (code, signal) => {
+        const tail = this.#stderr.trim().split('\n').slice(-3).join(' ').slice(-500)
+        end(
+          new AcpError(
+            `${agent.command} ended (${signal ?? `exit code ${String(code)}`})${tail ? `: ${tail}` : ''}`,
+          ),
+        )
+      })
+    })
+    this.#child.stderr.setEncoding('utf8')
+    this.#child.stderr.on('data', (chunk: string) => {
+      this.#stderr = (this.#stderr + chunk).slice(-STDERR_TAIL)
+    })
+    this.#child.stdout.setEncoding('utf8')
+    this.#child.stdout.on('data', (chunk: string) => {
+      this.#buffer += chunk
+      for (let end = this.#buffer.indexOf('\n'); end !== -1; end = this.#buffer.indexOf('\n')) {
+        const line = this.#buffer.slice(0, end).trim()
+        this.#buffer = this.#buffer.slice(end + 1)
+        if (line) this.#receive(line, handle)
+      }
+    })
+    // A write after the agent went away fails here instead of throwing out of the process.
+    this.#child.stdin.on('error', () => {})
+  }
+
+  /** Sends a request and resolves with its result; rejects with the agent's error, or when the process ends first. */
+  request<T>(method: string, params: unknown): Promise<T> {
+    if (this.#ended) return Promise.reject(this.#ended)
+    const id = this.#nextId++
+    return new Promise<T>((resolve, reject) => {
+      this.#pending.set(id, { resolve: resolve as (value: unknown) => void, reject })
+      this.#send({ jsonrpc: '2.0', id, method, params })
+    })
+  }
+
+  notify(method: string, params: unknown): void {
+    if (!this.#ended) this.#send({ jsonrpc: '2.0', method, params })
+  }
+
+  /** Hears every notification the agent sends; returns the function that stops listening. */
+  onNotification(listener: (method: string, params: unknown) => void): () => void {
+    this.#listeners.add(listener)
+    return () => void this.#listeners.delete(listener)
+  }
+
+  /**
+   * Ends the process and what it started: stdin closed, then SIGTERM, then a hard kill, each to the whole process group on POSIX (the tree, with `taskkill /T`, on Windows).
+   * Resolves once they are gone. Safe to call again, and after the agent ended on its own (its leftovers are still cleared).
+   */
+  async close(): Promise<void> {
+    if (!this.#ended) {
+      const gone = (ms: number) =>
+        Promise.race([
+          this.ended.then(() => true),
+          new Promise<boolean>((done) => setTimeout(() => done(false), ms).unref()),
+        ])
+      this.#child.stdin.end()
+      if (!(await gone(GRACE_MS))) {
+        this.#signal('SIGTERM')
+        if (!(await gone(GRACE_MS))) this.#signal('SIGKILL')
+        await this.ended
+      }
+    }
+    await this.#reapGroup()
+  }
+
+  /** A signal to the agent and, on POSIX, everything in its group. */
+  #signal(signal: 'SIGTERM' | 'SIGKILL'): void {
+    const pid = this.#child.pid
+    if (pid === undefined) return
+    if (process.platform === 'win32') {
+      if (signal === 'SIGKILL')
+        spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { windowsHide: true })
+      else this.#child.kill(signal)
+      return
+    }
+    try {
+      process.kill(-pid, signal)
+    } catch {
+      this.#child.kill(signal)
+    }
+  }
+
+  /** On POSIX, processes the agent left in its group are ended too: SIGTERM, then SIGKILL after the grace. */
+  async #reapGroup(): Promise<void> {
+    const pid = this.#child.pid
+    if (process.platform === 'win32' || pid === undefined) return
+    const groupAlive = (): boolean => {
+      try {
+        process.kill(-pid, 0)
+        return true
+      } catch (error) {
+        return (error as NodeJS.ErrnoException).code === 'EPERM'
+      }
+    }
+    for (const signal of ['SIGTERM', 'SIGKILL'] as const) {
+      if (!groupAlive()) return
+      try {
+        process.kill(-pid, signal)
+      } catch {
+        return
+      }
+      for (let waited = 0; waited < GRACE_MS && groupAlive(); waited += 25)
+        await new Promise((done) => setTimeout(done, 25))
+    }
+  }
+
+  #send(message: unknown): void {
+    this.#child.stdin.write(`${JSON.stringify(message)}\n`)
+  }
+
+  #receive(line: string, handle: AgentRequestHandler): void {
+    let message: {
+      id?: number | string
+      method?: string
+      params?: unknown
+      result?: unknown
+      error?: { code?: number; message?: string }
+    }
+    try {
+      message = JSON.parse(line)
+    } catch {
+      return // Not a protocol frame: an agent may print a stray line; it carries nothing to act on.
+    }
+    if (typeof message.method === 'string') {
+      if (message.id === undefined) {
+        for (const listener of this.#listeners) listener(message.method, message.params)
+        return
+      }
+      const id = message.id
+      Promise.resolve()
+        .then(() => handle(message.method as string, message.params))
+        .then(
+          (result) => this.#answer(id, result),
+          (error: unknown) =>
+            this.#send({
+              jsonrpc: '2.0',
+              id,
+              error:
+                error instanceof AcpError && error.code !== undefined
+                  ? { code: error.code, message: error.message }
+                  : {
+                      code: -32603,
+                      message: error instanceof Error ? error.message : String(error),
+                    },
+            }),
+        )
+      return
+    }
+    const pending = typeof message.id === 'number' ? this.#pending.get(message.id) : undefined
+    if (!pending) return
+    this.#pending.delete(message.id as number)
+    if (message.error)
+      pending.reject(
+        new AcpError(
+          message.error.message ?? 'the agent answered with an error',
+          message.error.code,
+        ),
+      )
+    else pending.resolve(message.result)
+  }
+
+  #answer(id: number | string, result: unknown): void {
+    if (!this.#ended) this.#send({ jsonrpc: '2.0', id, result: result ?? null })
+  }
+}

package/plugins/driver-acp/index.ts

@@ -0,0 +1,65 @@
+/**
+ * The ACP driver (M8, spec 046 T028): any agent that speaks the Agent Client Protocol (ACP v1 over stdio) as a chat driver of the agent panel, started in the app folder.
+ * No agent gets code of its own here: an agent is a preset, a command line that starts its ACP server. `dsh` (DeepSeek Harness, `dsh --profile acp`) is the first preset;
+ * other ACP agents are added by config.
+ *
+ * - The drivers are `chat` entries of the panel's `drivers` service (`acp:dsh`, ...). A panel without this plugin lists none; this plugin without a panel is pending.
+ * - An agent whose command is not on the machine gets no driver, and the plugin says so in one line (as `driver-pty` does without node-pty).
+ * - Every agent process is acquired inside one `ctx.effect`; its disposer ends the process. Unloading or reloading the plugin leaves no agent running.
+ * - Development only, like the panel: with `NODE_ENV=production` (or `ACRYL_DOOR=off`) it starts nothing.
+ */
+import { existsSync } from 'node:fs'
+import { isAbsolute } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import { onPath } from '../agent-panel/headless.ts'
+import type {} from '../agent-panel/registry.ts'
+import { type AcpPermissions, acpDriver, type OpenAgent } from './chat.ts'
+import { type AcpAgent, AcpConnection } from './connection.ts'
+
+export const name = 'driver-acp'
+export const inject = ['drivers', 'appInstance']
+
+export type { AcpPermissions } from './chat.ts'
+export { acpDriver } from './chat.ts'
+export { type AcpAgent, AcpConnection, AcpError } from './connection.ts'
+
+/** The ACP agents this plugin knows by name: the command line that starts each one's ACP server. */
+export const PRESETS: Readonly<Record<string, AcpAgent>> = {
+  dsh: { command: 'dsh', args: ['--profile', 'acp'] },
+}
+
+export interface DriverAcpConfig {
+  /** The agents to offer, by name (the driver is `acp:<name>`). Default: the presets whose command is on the machine. */
+  agents?: Record<string, AcpAgent>
+  /** The answer to an agent's permission request: its "allow once" or its "reject once" option. Default `reject`. */
+  permissions?: AcpPermissions
+}
+
+export function apply(ctx: Context, config: DriverAcpConfig = {}): void {
+  if (process.env.NODE_ENV === 'production' || process.env.ACRYL_DOOR === 'off') return
+  const root = ctx.appInstance.root
+  const open: OpenAgent = (agent, handle) => {
+    let connection!: AcpConnection
+    const close = ctx.effect(() => {
+      connection = new AcpConnection(agent, root, handle)
+      return () => connection.close()
+    }) as () => Promise<void>
+    // An agent that ended on its own gives its effect back at once instead of at unload.
+    void connection.ended.then(() => close())
+    return { connection, close }
+  }
+  for (const [agentName, agent] of Object.entries(config.agents ?? PRESETS)) {
+    if (!(isAbsolute(agent.command) ? existsSync(agent.command) : onPath(agent.command))) {
+      console.warn(`driver-acp: no acp:${agentName} driver, "${agent.command}" is not on the PATH`)
+      continue
+    }
+    const driver = acpDriver({
+      name: `acp:${agentName}`,
+      agent,
+      cwd: root,
+      permissions: config.permissions ?? 'reject',
+      open,
+    })
+    ctx.effect(() => ctx.drivers.register(driver))
+  }
+}

package/plugins/driver-acp/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "driver-acp",
+  "description": "Any agent that speaks the Agent Client Protocol (ACP) as a chat in the agent panel, started in the app folder: DeepSeek Harness (dsh --profile acp) is the first preset, other ACP agents are added by config. Development only; needs the agent panel; opt-in with acrylblends add driver-acp.",
+  "requires": ["agent-panel", "instance"],
+  "inject": ["drivers", "appInstance"],
+  "provides": [],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4"
+  },
+  "mount": "register it in src/app.ts ('driver-acp': driverAcp) and add a row `- id: driver-acp` / `name: driver-acp` to blend.yaml AFTER the agent-panel row; with dsh on the PATH the panel offers acp:dsh",
+  "gitignore": []
+}

package/plugins/driver-acp/provenance.json

@@ -0,0 +1,20 @@
+{
+  "written": "from the specification, not ported: connection.ts and chat.ts are this repository's own code",
+  "protocol": {
+    "name": "Agent Client Protocol",
+    "version": 1,
+    "site": "https://agentclientprotocol.com",
+    "transport": "stdio, newline-delimited JSON-RPC 2.0"
+  },
+  "schema": {
+    "file": "test/acp-v1/schema.json",
+    "from": "npm @agentclientprotocol/sdk@2.0.2, schema/v1/schema.json (the stable v1 schema, not schema.unstable.json)",
+    "repository": "https://github.com/agentclientprotocol/typescript-sdk",
+    "license": "Apache-2.0, Copyright 2025 Zed Industries, Inc. and contributors (test/acp-v1/LICENSE)",
+    "sha256": "4bcd1d2051ff7ed379bd9b234fb9b09c5ab9245478698e9fab805bd9b52a33a6",
+    "modified": false,
+    "used by": "test/conformance.test.ts; the schema is a test fixture and is not copied into apps"
+  },
+  "checked against": "dsh (DeepSeek Harness) 0.2.1-rc.2, dsh --profile acp, 2026-10-28: scripts/verify-agent-panel.mjs --driver acp:dsh",
+  "update": "take schema/v1/schema.json from a newer @agentclientprotocol/sdk, update sha256 and the version here, and run test/conformance.test.ts"
+}

package/plugins/driver-pty/index.ts

@@ -16,6 +16,7 @@ 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 type {} from '../agent-panel/registry.ts'
 import { loadNodePty, type PtySpawn } from './spawn.ts'
 import { terminalDriver } from './terminal.ts'