acrylblends 0.9.1 → 0.10.0

package/plugins/agent/agent.ts

@@ -1,6 +1,6 @@
 import type { Context } from '@deepseek-ai/cordis'
 import type {} from './memory.ts'
-import type {} from './model.ts'
+import type { Step } from './model.ts'
 import type {} from './tools.ts'
 
 /** One tool call made during a run. */
@@ -20,8 +20,14 @@ export type RunResult = (
   | { readonly status: 'cancelled' }
 ) & { readonly steps: number; readonly trace: readonly ToolCall[]; readonly task?: string }
 
+/** What a caller may pass to one run. */
+export interface RunOptions {
+  /** Aborting it stops the run: the model call or tool in flight is dropped and the run ends `{ status: 'cancelled' }`. */
+  readonly signal?: AbortSignal
+}
+
 export interface Agent {
-  run(question: string): Promise<RunResult>
+  run(question: string, options?: RunOptions): Promise<RunResult>
 }
 
 /** The step budget of one run, provided inside the run's own fiber. */
@@ -62,6 +68,19 @@ declare module '@deepseek-ai/cordis' {
 
 const message = (error: unknown) => (error instanceof Error ? error.message : String(error))
 
+/** Thrown inside a run when its signal aborts; the run turns it into `cancelled`. */
+class Cancelled extends Error {}
+
+/** The promise, or a rejection with `Cancelled` as soon as the signal aborts (a model or tool that ignores the signal cannot hold the run). */
+function until<T>(work: Promise<T>, signal: AbortSignal): Promise<T> {
+  if (signal.aborted) return Promise.reject(new Cancelled())
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => reject(new Cancelled())
+    signal.addEventListener('abort', onAbort, { once: true })
+    work.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort))
+  })
+}
+
 /**
  * The agent. Every run is its own child fiber that holds the run's budget and is disposed when the run ends, however it ends: a
  * scope per task, written with plain Cordis plugins. A tool that throws does not end the run: the model sees the error as the result.
@@ -74,11 +93,15 @@ export const agent = {
     const limit = config?.steps ?? 6
     let runs = 0
     ctx.provide('agent', {
-      async run(question) {
+      async run(question, options) {
         runs += 1
         const trace: ToolCall[] = []
         const recorder = (ctx.get as (name: string) => unknown)('tasks') as TaskRecorder | undefined
         const record = recorder?.start('agent-run', { question })
+        // The run stops when its task is cancelled or the caller's signal aborts.
+        const signal = AbortSignal.any(
+          [record?.signal, options?.signal].filter((s): s is AbortSignal => s !== undefined),
+        )
         // Assigned inside the run's fiber; `as` keeps TypeScript from narrowing it to this first value.
         let result = { status: 'budget_exceeded', steps: 0, trace } as RunResult
         const task = ctx.plugin({
@@ -89,17 +112,28 @@ export const agent = {
             const budget = scope.budget
             let toolResult: unknown
             while (budget.steps < budget.limit) {
-              if (record?.signal.aborted) {
+              if (signal.aborted) {
+                result = { status: 'cancelled', steps: budget.steps, trace }
+                return
+              }
+              let step: Step
+              try {
+                step = await until(
+                  scope.model.complete({
+                    question,
+                    step: budget.steps,
+                    toolResult,
+                    trace: [...trace],
+                    tools: scope.tools.list(),
+                    signal,
+                  }),
+                  signal,
+                )
+              } catch (error) {
+                if (!(error instanceof Cancelled)) throw error
                 result = { status: 'cancelled', steps: budget.steps, trace }
                 return
               }
-              const step = await scope.model.complete({
-                question,
-                step: budget.steps,
-                toolResult,
-                trace: [...trace],
-                tools: scope.tools.list(),
-              })
               budget.steps += 1
               if (step.tool === undefined) {
                 scope.memory.remember(`${question} => ${step.text}`)
@@ -110,7 +144,10 @@ export const agent = {
                 ? recorder?.start(`tool:${step.tool}`, step.input, { parent: record.id })
                 : undefined
               try {
-                toolResult = await scope.tools.call(step.tool, step.input)
+                toolResult = await until(
+                  scope.tools.call(step.tool, step.input, { signal }),
+                  signal,
+                )
                 trace.push({
                   tool: step.tool,
                   input: step.input,
@@ -119,6 +156,12 @@ export const agent = {
                 })
                 call?.complete(toolResult)
               } catch (error) {
+                if (error instanceof Cancelled) {
+                  trace.push({ tool: step.tool, input: step.input, error: 'cancelled' })
+                  call?.fail('the run was cancelled')
+                  result = { status: 'cancelled', steps: budget.steps, trace }
+                  return
+                }
                 toolResult = { error: message(error) }
                 trace.push({
                   tool: step.tool,
@@ -143,7 +186,10 @@ export const agent = {
         }
         if (result.status === 'completed')
           record?.complete(result.output, { steps: result.steps, trace })
-        else if (result.status === 'budget_exceeded')
+        else if (result.status === 'cancelled') {
+          if (!record?.signal.aborted)
+            record?.fail('the run was cancelled', { steps: result.steps, trace })
+        } else if (result.status === 'budget_exceeded')
           record?.fail('the run used its whole step budget', { steps: result.steps, trace })
         return record ? { ...result, task: record.id } : result
       },

package/plugins/agent/model.ts

@@ -22,6 +22,8 @@ export interface ModelInput {
   }>
   /** The tools the model may call. */
   readonly tools?: ReadonlyArray<{ readonly name: string; readonly description: string }>
+  /** Aborts when the run is cancelled: a provider that can stop its request passes this on. */
+  readonly signal?: AbortSignal
 }
 
 /** What the agent needs from a model. Replace this plugin with a real provider when you have one. */

package/plugins/agent/tools.ts

@@ -3,7 +3,8 @@ import type { Context } from '@deepseek-ai/cordis'
 /** One tool: what it does (for the model) and how to run it. */
 export interface Tool {
   readonly description: string
-  run(input: unknown): unknown | Promise<unknown>
+  /** `options.signal` aborts when the run is cancelled; a tool that can stop its work listens to it. */
+  run(input: unknown, options?: { signal?: AbortSignal }): unknown | Promise<unknown>
 }
 
 /** The tool registry. A plugin registers its tools inside `ctx.effect`, so they leave with it. */
@@ -11,7 +12,7 @@ export interface Tools {
   /** Register a tool. Returns the function that removes it. */
   register(name: string, tool: Tool): () => void
   list(): Array<{ name: string; description: string }>
-  call(name: string, input: unknown): Promise<unknown>
+  call(name: string, input: unknown, options?: { signal?: AbortSignal }): Promise<unknown>
 }
 
 declare module '@deepseek-ai/cordis' {
@@ -31,10 +32,10 @@ export function tools(ctx: Context) {
     },
     list: () =>
       [...table.entries()].map(([name, tool]) => ({ name, description: tool.description })),
-    async call(name, input) {
+    async call(name, input, options) {
       const tool = table.get(name)
       if (!tool) throw new Error(`unknown tool "${name}"`)
-      return await tool.run(input)
+      return await tool.run(input, options)
     },
   }
   ctx.provide('tools', registry)

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
+}

package/plugins/agent-panel/headless.ts

@@ -0,0 +1,154 @@
+/** The panel's own drivers, all `chat`: the app's agent, and the coding agents (`claude`, `codex`, `pi`) started headless in the app folder. */
+import { spawn, spawnSync } from 'node:child_process'
+import type { Context } from '@deepseek-ai/cordis'
+import type { ChatDriver, ChatEvent } from './drivers.ts'
+
+export type HeadlessName = 'claude' | 'codex' | 'pi'
+
+/** The command line of each coding agent started headless in the app folder (the same ones the product test uses). */
+export function command(
+  driver: HeadlessName,
+  message: string,
+  root: string,
+): { file: string; args: string[] } {
+  switch (driver) {
+    case 'claude':
+      return {
+        file: 'claude',
+        args: [
+          '-p',
+          message,
+          '--permission-mode',
+          'acceptEdits',
+          '--allowedTools',
+          'Read,Edit,Write,Glob,Grep,Bash(npm *),Bash(npx *),Bash(node *),Bash(.acryl/bin/acryl *),Bash(curl *)',
+        ],
+      }
+    case 'codex':
+      return {
+        file: 'codex',
+        args: [
+          'exec',
+          '--skip-git-repo-check',
+          '-s',
+          'workspace-write',
+          '-c',
+          'sandbox_workspace_write.network_access=true',
+          '-C',
+          root,
+          message,
+        ],
+      }
+    case 'pi':
+      return {
+        file: 'pi',
+        args: [
+          '-p',
+          message,
+          '--provider',
+          'deepseek',
+          '--model',
+          'deepseek-v4-pro',
+          '--no-session',
+        ],
+      }
+  }
+}
+
+export function onPath(program: string): boolean {
+  const found = spawnSync(process.platform === 'win32' ? 'where' : 'which', [program], {
+    encoding: 'utf8',
+  })
+  return found.status === 0
+}
+
+/** The headless programs this machine can offer: installed (pi also needs its key in the environment). */
+export function availableHeadless(wanted?: readonly HeadlessName[]): HeadlessName[] {
+  const found: HeadlessName[] = []
+  for (const driver of wanted ?? (['claude', 'codex', 'pi'] as const)) {
+    if (driver === 'pi' && !process.env.DEEPSEEK_API_KEY) continue
+    if (onPath(driver)) found.push(driver)
+  }
+  return found
+}
+
+/** The app's own agent as a chat driver: its tool calls, then its answer. Aborting the signal cancels the run. */
+export function agentDriver(ctx: Context): ChatDriver {
+  return {
+    kind: 'chat',
+    name: 'agent',
+    async *start({ message, signal }) {
+      const result = await ctx.agent.run(message, { signal })
+      for (const call of result.trace)
+        yield {
+          event: 'tool',
+          data: {
+            tool: call.tool,
+            input: call.input,
+            ...(call.error ? { error: call.error } : { result: call.result }),
+          },
+        }
+      yield {
+        event: 'text',
+        data: {
+          text:
+            result.status === 'completed'
+              ? result.output
+              : result.status === 'cancelled'
+                ? 'The run was cancelled.'
+                : `The run stopped after ${result.steps} steps without an answer.`,
+        },
+      }
+    },
+  }
+}
+
+/** A coding agent run headless in the app folder: its stdout is the answer, its stderr the tool lines. Aborting the signal ends the program. */
+export function headlessDriver(name: HeadlessName, root: string): ChatDriver {
+  return {
+    kind: 'chat',
+    name,
+    async *start({ message, signal }) {
+      const { file, args } = command(name, message, root)
+      const child = spawn(file, args, {
+        cwd: root,
+        env: process.env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      })
+      const queue: ChatEvent[] = []
+      let wake: (() => void) | undefined
+      let ended = false
+      const push = (event: ChatEvent): void => {
+        queue.push(event)
+        wake?.()
+      }
+      signal.addEventListener('abort', () => child.kill('SIGTERM'), { once: true })
+      child.stdout.on('data', (chunk: Buffer) =>
+        push({ event: 'text', data: { text: chunk.toString() } }),
+      )
+      child.stderr.on('data', (chunk: Buffer) =>
+        push({ event: 'tool', data: { tool: name, info: chunk.toString().slice(0, 500) } }),
+      )
+      child.on('error', () => {
+        ended = true
+        push({ event: 'error', data: { message: `${name} could not be started` } })
+      })
+      child.on('exit', (code) => {
+        ended = true
+        if (code !== 0 && !signal.aborted)
+          push({ event: 'error', data: { message: `${name} ended with exit code ${code ?? 1}` } })
+        else wake?.()
+      })
+      try {
+        for (;;) {
+          const next = queue.shift()
+          if (next) yield next
+          else if (ended) return
+          else await new Promise<void>((resolve) => (wake = resolve))
+        }
+      } finally {
+        if (child.exitCode === null) child.kill('SIGTERM')
+      }
+    },
+  }
+}