acrylblends 1.1.0 → 1.2.0

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

@@ -7,6 +7,8 @@
  * response body still streaming and waits for all of it to settle.
  */
 
+import { appendFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
 import { Context, Service } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
 import type { ConnectionInfo, RouterBindings } from './connection.ts'
@@ -21,6 +23,27 @@ import type { ErrorHandler, H, NotFoundHandler } from './core/types.ts'
 
 const DEFAULT_DISPOSE_GRACE_MS = 2000
 
+/** How long disposal waits for the flights it had to abort after the drain, before it continues without them. */
+const ABORT_SETTLE_MS = 300
+
+/** Set by ACRYL_ROUTER_TRACE=1: append request-signal lifecycle lines to ACRYL_ROUTER_TRACE_FILE (the CI artifact) - diagnostics for the abort-reaches-handler defect. */
+const traceFile = (): string => process.env.ACRYL_ROUTER_TRACE_FILE ?? `${tmpdir()}/acryl-router-trace.log`
+const trace = (line: string): void => {
+  if (process.env.ACRYL_ROUTER_TRACE !== '1') return
+  try { appendFileSync(traceFile(), `${String(Date.now())} [${String(process.pid)}] ${line}\n`) } catch { /* tracing never affects a request */ }
+}
+let flightSeq = 0
+const SIGNAL_TAG = Symbol.for('acryl.router.signalTag')
+const tagOf = (signal: AbortSignal | undefined): string => {
+  if (signal === undefined) return 'none'
+  const tag = (signal as unknown as Record<symbol, unknown>)[SIGNAL_TAG]
+  return typeof tag === 'string' ? tag : 'untagged'
+}
+const tagSignal = (signal: AbortSignal, tag: string): void => {
+  try { (signal as unknown as Record<symbol, unknown>)[SIGNAL_TAG] = tag } catch { /* a frozen signal keeps no tag */ }
+}
+
+
 /** How a trailing slash is read: `strict` keeps `/a` and `/a/` distinct, `ignore` treats them as one path. */
 export type TrailingSlash = 'strict' | 'ignore'
 
@@ -105,6 +128,10 @@ interface RouterState {
 
 interface Flight {
   readonly controller: AbortController
+  /** The request the handlers run on (the caller's request with the flight's signal): held strongly for the flight's lifetime, so its signal cannot be collected under a listener. */
+  readonly inner: Request
+  /** Names the flight in the ACRYL_ROUTER_TRACE diagnostics. */
+  readonly tag: string
   /** How many of each mount's handlers are running for this request right now (a middleware counts until its `next()` returns). */
   readonly running: Map<Mount, number>
   /** The mount whose handler produced the response; its body is that mount's code still running. */
@@ -150,8 +177,8 @@ export class Router extends Service {
     }
     ctx.effect(() => async () => {
       this.state.closing = true
-      await this.end([...this.flights], 'disposal')
-    }, 'acryl-router: abort and settle in-flight requests')
+      await this.drain()
+    }, 'acryl-router: drain in-flight requests, then abort what is left')
   }
 
   /** Registrations currently held (mounts, and the router-wide error and not-found handlers); a leak check for reload tests. */
@@ -168,12 +195,16 @@ export class Router extends Service {
     const mount = this.snapshot(path, app)
     this.state.mounts.add(mount)
     this.state.composed = undefined
-    // Removing a mount ends the requests its code is still serving: their signals abort, a body it produced is cancelled, and the
-    // plugin's unload waits for them (bounded by `disposeGraceMs`), so nothing a plugin started outlives it.
+    // Removing a mount ends the requests its code is still serving: they get the grace to finish first (a save being written when its plugin unloads,
+    // or when the whole app stops and every plugin unloads together, must not be cut), and only then are their signals aborted, their bodies cancelled
+    // and their settle awaited, so nothing a plugin started outlives it by more than that bounded grace.
     const remove = (): Promise<void> => {
       if (!this.state.mounts.delete(mount)) return Promise.resolve()
       this.state.composed = undefined
-      return this.end([...this.flights].filter(flight => (flight.running.get(mount) ?? 0) > 0 || flight.producer === mount), `removing ${path}`)
+      return this.drainFlights(
+        [...this.flights].filter(flight => (flight.running.get(mount) ?? 0) > 0 || flight.producer === mount),
+        `removing ${path}`,
+      )
     }
     // Each route the mount serves is a child effect of it, labeled on its own, so the inspector can report routes without asking the
     // router and no label grows with the size of the app (`ALL` is middleware or `all`). The children hold nothing: the mount does.
@@ -215,6 +246,7 @@ export class Router extends Service {
       const handler: H = async (c, next) => {
         const flight = this.flightOf.get(c.req.raw)
         if (flight === undefined) return inner(c, next)
+        trace(`handler ${flight.tag} requestTag=${tagOf(c.req.raw.signal)} innerTag=${tagOf(flight.inner.signal)} sameSignal=${String(c.req.raw.signal === flight.inner.signal)} aborted=${String(c.req.raw.signal.aborted)}`)
         let calledNext = false
         flight.running.set(mount, (flight.running.get(mount) ?? 0) + 1)
         try {
@@ -234,18 +266,46 @@ export class Router extends Service {
     return mount
   }
 
-  /** Abort `flights`, cut their bodies short and wait for them to settle, at most `disposeGraceMs`. */
-  private async end(flights: readonly Flight[], why: string): Promise<void> {
+  /**
+   * The router's own disposal: let the flights already in flight finish within `disposeGraceMs` - a save being written when the app stops must not be cut
+   * by the router beneath it - then abort what is left and settle it for a moment, so disposal does not wait a second full grace on code that ignores
+   * its abort signal.
+   */
+  private async drain(): Promise<void> {
+    await this.drainFlights([...this.flights], 'disposal')
+  }
+
+  /** The one draining rule: let `flights` finish inside the grace, then abort and settle what is left. */
+  private async drainFlights(flights: readonly Flight[], why: string): Promise<void> {
+    trace(`drain ${why} chosen=[${flights.map(flight => flight.tag).join(', ')}]`)
+    if (flights.length === 0) return
+    if (await this.settledWithin(flights, this.graceMs)) { trace(`drain ${why} settled inside the grace`); return }
+    const left = flights.filter(flight => this.flights.has(flight))
+    trace(`drain ${why} grace over left=[${left.map(flight => flight.tag).join(', ')}]`)
+    if (left.length > 0) await this.end(left, why, ABORT_SETTLE_MS)
+  }
+
+  /** Resolve true when every flight settled inside `ms`, false at the deadline. */
+  private async settledWithin(flights: readonly Flight[], ms: number): Promise<boolean> {
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const gaveUp = new Promise<false>(resolve => { timer = setTimeout(() => { resolve(false) }, ms) })
+    const outcome = await Promise.race([Promise.allSettled(flights.map(flight => flight.settled)).then(() => true as const), gaveUp])
+    clearTimeout(timer)
+    return outcome
+  }
+
+  /** Abort `flights`, cut their bodies short and wait for them to settle, at most `settleMs`. */
+  private async end(flights: readonly Flight[], why: string, settleMs: number = this.graceMs): Promise<void> {
     if (flights.length === 0) return
     for (const flight of flights) {
+      trace(`abort ${flight.tag} before=${String(flight.controller.signal.aborted)}`)
       flight.controller.abort()
+      trace(`abort ${flight.tag} after=${String(flight.controller.signal.aborted)} innerAborted=${String(flight.inner.signal.aborted)}`)
+      queueMicrotask(() => { trace(`post-abort ${flight.tag} innerAborted=${String(flight.inner.signal.aborted)}`) })
       flight.endBody()
     }
-    let timer: ReturnType<typeof setTimeout> | undefined
-    const gaveUp = new Promise<'gave-up'>(resolve => { timer = setTimeout(() => { resolve('gave-up') }, this.graceMs) })
-    const outcome = await Promise.race([Promise.allSettled(flights.map(flight => flight.settled)).then(() => 'settled' as const), gaveUp])
-    clearTimeout(timer)
-    if (outcome === 'gave-up') this.ctx.logger.warn(`acryl-router: ${String(flights.length)} request(s) did not finish ${String(this.graceMs)} ms after abort (${why}); continued without them`)
+    if (await this.settledWithin(flights, settleMs)) return
+    this.ctx.logger.warn(`acryl-router: ${String(flights.length)} request(s) did not finish ${String(settleMs)} ms after abort (${why}); continued without them`)
   }
 
   /** Turn errors no mounted app handled into responses. One handler per router; the calling plugin owns it. */
@@ -292,7 +352,7 @@ export class Router extends Service {
    * `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 = {}, bindings?: object): Promise<Response> {
-    if (this.state.closing) return Promise.resolve(new Response('Service Unavailable', { status: 503 }))
+    if (this.state.closing) return Promise.resolve(new Response('Service Unavailable', { status: 503, headers: { connection: 'close' } }))
     const controller = new AbortController()
     const forward = (): void => controller.abort()
     if (request.signal.aborted) controller.abort()
@@ -308,8 +368,11 @@ export class Router extends Service {
     let bodyDone: Promise<void> = Promise.resolve()
     let endBody = (): void => {}
     let resolveSettled!: (value: Promise<unknown>) => void
-    const flight: Flight = { controller, running: new Map(), producer: undefined, endBody: () => { endBody() }, settled: new Promise(resolve => { resolveSettled = resolve }) }
+    const tag = `f${String(++flightSeq)}`
     const inner = new Request(request, { signal: controller.signal })
+    tagSignal(inner.signal, tag)
+    const flight: Flight = { controller, inner, tag, running: new Map(), producer: undefined, endBody: () => { endBody() }, settled: new Promise(resolve => { resolveSettled = resolve }) }
+    trace(`create ${tag} ${request.method} ${new URL(request.url).pathname}`)
     this.flightOf.set(inner, flight)
     // The caller gets the Response the moment the handler returns it; the flight lasts until its body ends and every waitUntil task settles.
     const response = this.dispatch(inner, env, executionCtx).then(raw => {

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

@@ -41,6 +41,10 @@ export class RouterHttp extends Service implements RouterHttpService {
   private readonly router: Context['router']
   private readonly web: WebServerPort
   private hub: UpgradeHub | undefined
+  /** One upgrade helper per calling context: a fresh wrapper per call made every service event look like an owner change. */
+  private readonly upgradeHelpers = new WeakMap<object, UpgradeWebSocket>()
+  /** A stable identity for this service instance's hub: a caller that must recognize the same owner across calls keys on this, not on a helper. */
+  private readonly hubIdentity: object = {}
   /** 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()
@@ -99,8 +103,18 @@ export class RouterHttp extends Service implements RouterHttpService {
    * `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]`.
    */
+  /** Stable for this service's lifetime; a re-provided adapter has a new one, which is how a caller sees a new owner. */
+  hubToken(): object {
+    return this.hubIdentity
+  }
+
   upgrades(): UpgradeWebSocket {
-    return this.ensureHub().upgradeWebSocketFor(this.ctx) as unknown as UpgradeWebSocket
+    const owner = this.ctx
+    const cached = this.upgradeHelpers.get(owner)
+    if (cached !== undefined) return cached
+    const created = this.ensureHub().upgradeWebSocketFor(owner) as unknown as UpgradeWebSocket
+    this.upgradeHelpers.set(owner, created)
+    return created
   }
 
   /** How many WebSocket connections are open now. */

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

@@ -6,6 +6,35 @@ export interface FetchRouter {
   fetch(request: Request, connection?: { readonly remoteAddress?: string | undefined, readonly localPort?: number | undefined }): Promise<Response>
 }
 
+/** How long a refusal waits for a request body the handler never read. */
+export const REQUEST_BODY_SETTLE_MS = 1_000
+
+/**
+ * Read and discard a request body the handler left unread (a guard's 403, a 415, a body over its limit), so the client can finish sending and
+ * read the answer. Ending a response while request data is still arriving makes Node close the socket with that data pending, and the peer sees a
+ * reset instead of the answer: reliably on Windows (the workspace git worktree test's read ECONNRESET) and on other systems under load. Bounded:
+ * a client that stops sending waits at most `ms`, then loses the socket as before.
+ */
+export function settleRequestBody(req: IncomingMessage, ms: number = REQUEST_BODY_SETTLE_MS): Promise<void> {
+  if (req.readableEnded || req.destroyed) return Promise.resolve()
+  return new Promise<void>((resolve) => {
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const done = (): void => {
+      if (timer !== undefined) clearTimeout(timer)
+      req.off('end', done)
+      req.off('close', done)
+      req.off('error', done)
+      resolve()
+    }
+    timer = setTimeout(done, ms)
+    timer.unref?.()
+    req.once('end', done)
+    req.once('close', done)
+    req.once('error', done)
+    req.resume()
+  })
+}
+
 /**
  * Serve one node request through the router and write the result. The request's abort signal fires when the client
  * disconnects before the response finished; the socket's peer address and local port travel as connection info, never in the request.
@@ -20,5 +49,7 @@ export async function serve(router: FetchRouter, req: IncomingMessage, res: Serv
   } catch {
     response = new Response('Internal Server Error', { status: 500 })
   }
+  // The handler may have answered without reading the body; let the client finish sending before the answer ends the connection.
+  if (method !== 'GET' && method !== 'HEAD') await settleRequestBody(req)
   await sendResponse(res, response, method)
 }

package/plugins/acryl-web-server/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "acryl-web-server",
+  "description": "The webServer port of a framework-hosted app: the node request/upgrade interface DSH's driver rows register on, backed by acryl-node-server's raw routes. Ours, so the chat driver's connection and gateway run on our host without DSH's web server.",
+  "requires": ["acryl-node-server"],
+  "inject": ["nodeServer"],
+  "provides": ["webServer"],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4"
+  },
+  "mount": "mount it before the DSH driver rows that inject webServer (the chat connection and its gateway); the framework's page serving applies its index taps",
+  "entries": {
+    "": "src/index.ts"
+  }
+}

package/plugins/acryl-web-server/src/index.ts

@@ -0,0 +1,164 @@
+/**
+ * The `webServer` port for a framework-hosted app. DSH's driver rows (the chat's connection and its remote gateway) register node handlers with
+ * `webServer.register` and `webServer.registerUpgrade`; this plugin serves them on the framework's own node server, so those rows run unchanged
+ * while the HTTP host, the page and the client-module serving stay ours.
+ *
+ * It is the inverse of `acryl-router-http`: there the Host's web server serves a router prefix; here our node server presents the web-server
+ * interface a DSH row expects. The surface is deliberately small: `host` and `port` (what `acryl-web` reads), `register` (exact or prefix),
+ * `registerUpgrade` (one exact path), and the index taps the page serving applies. A row that needs more of DSH's interface gets the extra
+ * method here, named with the row that needs it - so this seam can shrink when a row goes away.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { Duplex } from 'node:stream'
+import { Context, Service } from '@deepseek-ai/cordis'
+import type { NodeServer, RawRoute, RawUpgradeRoute } from 'acryl-node-server'
+
+/** Stable Cordis plugin name, equal to the package name and the Loader row id. */
+export const name = 'acryl-web-server'
+
+/** Hard requirement: the node server whose raw routes carry these handlers. */
+export const inject = ['nodeServer']
+
+/** A node handler at a path `exact` (the pathname itself) or a `prefix` (the path and everything below it). */
+export interface WebServerRoute {
+  readonly kind: 'prefix' | 'exact'
+  readonly path: string
+  readonly handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
+}
+
+/** One exact-path upgrade handler; the socket belongs to the handler once its path matches. */
+export interface WebServerUpgradeRoute {
+  readonly path: string
+  readonly handler: (req: IncomingMessage, socket: Duplex, head: Buffer) => void | Promise<void>
+}
+
+/** Transforms the served index document, in registration order. */
+export type IndexTap = (html: string) => string
+
+/** What a driver row (or `acryl-web`) reads from `webServer`. */
+export interface WebServerService {
+  /** The address the node server bound. */
+  readonly host: string
+  readonly port: number
+  /** Serve `route` until the returned remover runs or the calling plugin unloads. A path already served throws. */
+  register(route: WebServerRoute): () => void
+  /** Claim `route.path` for an upgrade until the returned remover runs or the calling plugin unloads. */
+  registerUpgrade(route: WebServerUpgradeRoute): () => void
+  /** Transform the served index document while the caller lives; returns its remover. */
+  tapIndex(transform: IndexTap): () => void
+  /** The document with the structured injection rows (the client modules' boot wire) and then every live tap applied. */
+  index(html: string): string
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    webServer: WebServerService
+  }
+}
+
+/** One structured index-injection row (DSH's contract): the kinds the client modules and a door script use. */
+interface IndexRow {
+  readonly kind?: string
+  readonly placement?: 'head' | 'body'
+  readonly text?: string
+  readonly src?: string
+  readonly name?: string
+  readonly value?: unknown
+}
+
+/** The boot-readiness tail the client shell waits for, as DSH renders it. */
+const READY_MARKUP = '<script>(globalThis.__DSH_BOOT_READY__ ??= Promise.withResolvers()).resolve()</script>'
+
+/** A JSON literal safe inside a `<script>`: a sequence like `</script>` must not end it. */
+const scriptJson = (value: unknown): string => JSON.stringify(value).replaceAll('</', '<\\/')
+
+/** Render one row; an unknown kind is skipped rather than emitted as broken markup. */
+function rowMarkup(row: IndexRow): string {
+  if (row.kind === 'script') return `<script>${row.text ?? ''}</script>`
+  if (row.kind === 'script-src') return `<script type="module" crossorigin src="${row.src ?? ''}"></script>`
+  if (row.kind === 'script-preload') return `<link rel="modulepreload" crossorigin href="${row.src ?? ''}" />`
+  if (row.kind === 'global') return `<script>globalThis[${scriptJson(row.name ?? '')}] = ${scriptJson(row.value)}</script>`
+  return ''
+}
+
+/** Insert each group after its opening tag, as DSH's served index does; a document without the tag gets the group first. */
+export function renderIndexRows(html: string, rows: readonly IndexRow[]): string {
+  let head = ''
+  let body = ''
+  for (const row of rows) {
+    const markup = rowMarkup(row)
+    if (markup === '') continue
+    if (row.placement === 'body') body += markup
+    else head += markup
+  }
+  body += READY_MARKUP
+  let document = html
+  const headOpen = /<head(?:\s[^>]*)?>/iu.exec(document)
+  if (head !== '') {
+    const at = headOpen === null ? 0 : headOpen.index + headOpen[0].length
+    document = `${document.slice(0, at)}${head}${document.slice(at)}`
+  }
+  const bodyOpen = /<body(?:\s[^>]*)?>/iu.exec(document)
+  if (body !== '') {
+    const at = bodyOpen === null ? document.length : bodyOpen.index + bodyOpen[0].length
+    document = `${document.slice(0, at)}${body}${document.slice(at)}`
+  }
+  return document
+}
+
+/** The port, backed by `nodeServer`'s raw routes; every registration belongs to the plugin that made it. */
+export class WebServer extends Service implements WebServerService {
+  private readonly taps: IndexTap[] = []
+
+  constructor(ctx: Context) {
+    super(ctx, 'webServer')
+  }
+
+  get host(): string {
+    return this.ctx.nodeServer.hostname
+  }
+
+  get port(): number {
+    return this.ctx.nodeServer.port
+  }
+
+  register(route: WebServerRoute): () => void {
+    const remove = this.ctx.nodeServer.registerRaw(route as RawRoute)
+    this.ctx.effect(() => () => { remove() }, `acryl-web-server: ${route.kind} ${route.path}`)
+    return remove
+  }
+
+  registerUpgrade(route: WebServerUpgradeRoute): () => void {
+    const remove = this.ctx.nodeServer.registerRawUpgrade(route as RawUpgradeRoute)
+    this.ctx.effect(() => () => { remove() }, `acryl-web-server: upgrade ${route.path}`)
+    return remove
+  }
+
+  tapIndex(transform: IndexTap): () => void {
+    this.taps.push(transform)
+    const remove = (): void => {
+      const at = this.taps.indexOf(transform)
+      if (at >= 0) this.taps.splice(at, 1)
+    }
+    this.ctx.effect(() => () => { remove() }, 'acryl-web-server: index tap')
+    return remove
+  }
+
+  index(html: string): string {
+    // The rows are DSH's index-injection contract (`webserver/index-inject`): the client-module row pushes its boot wire there. The rows render
+    // first, the string taps after, the same order DSH's own web server uses.
+    const rows: IndexRow[] = []
+    ;(this.ctx as unknown as { emit(name: string, table: IndexRow[]): void }).emit('webserver/index-inject', rows)
+    let document = renderIndexRows(html, rows)
+    for (const tap of [...this.taps]) document = tap(document)
+    return document
+  }
+}
+
+/** Provide `webServer` on this context; the node server must already be up (the plugin injects it). */
+export function apply(ctx: Context): void {
+  new WebServer(ctx)
+}
+
+/** Re-exported for callers that shape their own routes: the raw types the port is built on. */
+export type { NodeServer, RawRoute, RawUpgradeRoute }

package/plugins/agent/agent.ts

@@ -24,6 +24,8 @@ export type RunResult = (
 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
+  /** The door's id of the page the run was asked from: every tool call carries it, so the page tools drive that page and no other (a production assistant serves many visitors). */
+  readonly page?: string
 }
 
 export interface Agent {
@@ -39,6 +41,16 @@ export interface Budget {
 export interface AgentConfig {
   /** Steps per run before it stops. */
   steps?: number
+  /**
+   * The only tools a run may see and call; absent: every tool in the registry. A production assistant gets the page tools alone (`door_look`, `door_act`), so whatever
+   * a visitor asks, the agent can use the app and never change it. A call to any other name fails as an unknown tool would.
+   */
+  tools?: readonly string[]
+  /**
+   * The tool whose result an answer must come right after. When the model answers after another tool call (it acted and did not look), the agent calls this tool
+   * itself, once, and asks the model again with what it shows. The production assistant sets `door_look`, so what it tells a visitor is what the page shows now.
+   */
+  answerAfter?: string
 }
 
 /**
@@ -91,6 +103,8 @@ export const agent = {
   inject: ['model', 'tools', 'memory'],
   apply(ctx: Context, config?: AgentConfig) {
     const limit = config?.steps ?? 6
+    const allowed = config?.tools === undefined ? undefined : new Set(config.tools)
+    const answerAfter = config?.answerAfter
     let runs = 0
     ctx.provide('agent', {
       async run(question, options) {
@@ -104,13 +118,15 @@ export const agent = {
         )
         // 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({
+        // Each run's `budget` is its own: runs may overlap (the production Assistant serves visitors at once), and a service name is shared unless isolated.
+        const task = ctx.isolate('budget').plugin({
           name: `task-${runs}`,
           inject: ['model', 'tools', 'memory'],
           async apply(scope: Context) {
             scope.provide('budget', { steps: 0, limit } satisfies Budget)
             const budget = scope.budget
             let toolResult: unknown
+            let looked = false
             while (budget.steps < budget.limit) {
               if (signal.aborted) {
                 result = { status: 'cancelled', steps: budget.steps, trace }
@@ -124,7 +140,7 @@ export const agent = {
                     step: budget.steps,
                     toolResult,
                     trace: [...trace],
-                    tools: scope.tools.list(),
+                    tools: scope.tools.list().filter((tool) => allowed?.has(tool.name) ?? true),
                     signal,
                   }),
                   signal,
@@ -136,16 +152,31 @@ export const agent = {
               }
               budget.steps += 1
               if (step.tool === undefined) {
-                scope.memory.remember(`${question} => ${step.text}`)
-                result = { status: 'completed', output: step.text, steps: budget.steps, trace }
-                return
-              }
+                const last = trace.at(-1)
+                const unseen =
+                  answerAfter !== undefined &&
+                  last !== undefined &&
+                  last.tool !== answerAfter &&
+                  !looked
+                if (!unseen) {
+                  scope.memory.remember(`${question} => ${step.text}`)
+                  result = { status: 'completed', output: step.text, steps: budget.steps, trace }
+                  return
+                }
+                step = { tool: answerAfter, input: {} }
+                looked = true
+              } else looked = false
               const call = record
                 ? recorder?.start(`tool:${step.tool}`, step.input, { parent: record.id })
                 : undefined
               try {
+                if (allowed !== undefined && !allowed.has(step.tool))
+                  throw new Error(`no tool named "${step.tool}" is allowed in this run`)
                 toolResult = await until(
-                  scope.tools.call(step.tool, step.input, { signal }),
+                  scope.tools.call(step.tool, step.input, {
+                    signal,
+                    ...(options?.page === undefined ? {} : { page: options.page }),
+                  }),
                   signal,
                 )
                 trace.push({

package/plugins/agent/index.ts

@@ -17,4 +17,4 @@ export {
   type Step,
   scripted,
 } from './model.ts'
-export { type Tool, type Tools, tools } from './tools.ts'
+export { type CallOptions, type Tool, type Tools, tools } from './tools.ts'

package/plugins/agent/model.ts

@@ -52,8 +52,16 @@ declare module '@deepseek-ai/cordis' {
 }
 
 const builtIn: Rule[] = [
-  ({ toolResult, step }) =>
-    step > 0 ? { text: `The answer is ${String(toolResult)}.` } : undefined,
+  ({ toolResult, step }) => {
+    if (step === 0) return undefined
+    // A failed call comes back as `{ error }`: say what failed, not "[object Object]".
+    const failed = typeof toolResult === 'object' && toolResult !== null && 'error' in toolResult
+    return {
+      text: failed
+        ? `That did not work: ${String(toolResult.error)}.`
+        : `The answer is ${String(toolResult)}.`,
+    }
+  },
   ({ question }) => {
     const sum = /^add\s+(-?\d+)\s+(-?\d+)$/.exec(question.trim())
     return sum ? { tool: 'add', input: [Number(sum[1]), Number(sum[2])] } : undefined

package/plugins/agent/tools.ts

@@ -1,12 +1,18 @@
 import type { Context } from '@deepseek-ai/cordis'
 
+/** What a run passes with each call: its signal, and the door's id of the page it was asked from (the page tools drive only that page). */
+export interface CallOptions {
+  readonly signal?: AbortSignal
+  readonly page?: string
+}
+
 /** One tool: what it does (for the model) and how to run it. */
 export interface Tool {
   readonly description: string
   /** The JSON Schema of the input (an object schema), sent to a real model so it knows which fields the tool takes. A tool without one takes any object. */
   readonly parameters?: Readonly<Record<string, 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>
+  /** `options.signal` aborts when the run is cancelled; a tool that can stop its work listens to it. `options.page` is the page the run was asked from, when it was. */
+  run(input: unknown, options?: CallOptions): unknown | Promise<unknown>
 }
 
 /** The tool registry. A plugin registers its tools inside `ctx.effect`, so they leave with it. */
@@ -18,7 +24,7 @@ export interface Tools {
     description: string
     parameters?: Readonly<Record<string, unknown>>
   }>
-  call(name: string, input: unknown, options?: { signal?: AbortSignal }): Promise<unknown>
+  call(name: string, input: unknown, options?: CallOptions): Promise<unknown>
 }
 
 declare module '@deepseek-ai/cordis' {

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

@@ -42,3 +42,60 @@ export function describeTool(data: Record<string, unknown>): string | undefined
   const failed = data.error ? ` failed: ${clip(String(data.error))}` : ''
   return `${tool}${input}${failed}`
 }
+
+/** What an act touched, from its result: the door's chat tool answers `done: link "My tasks" (detail); look again before the next act`, its verb `{ target }`. */
+function targetOf(result: unknown): { role?: string; name?: string } {
+  if (typeof result === 'string') {
+    const match = /^done: (\S+) "(.*)"(?: \(.*\))?; look again/u.exec(result)
+    return match === null ? {} : { role: match[1], name: match[2] }
+  }
+  if (typeof result !== 'object' || result === null) return {}
+  const target = (result as { target?: unknown }).target
+  if (typeof target !== 'object' || target === null) return {}
+  const { role, name } = target as { role?: unknown; name?: unknown }
+  return {
+    ...(typeof role === 'string' ? { role } : {}),
+    ...(typeof name === 'string' ? { name } : {}),
+  }
+}
+
+/**
+ * The Assistant's step on the page, as the person reads it under the answer: what it did, named the way the page names it. `ui.open("My tasks")`,
+ * `ui.fill("Due", "This week")`, `ui.click("Save")`, `ui.press("Enter")`. A look changes nothing, so it is left out unless it failed. The control's name comes from the
+ * act's result (the page says what it acted on); the ref is the fallback.
+ */
+export function describePageStep(data: Record<string, unknown>): string | undefined {
+  const failed = data.error ? ' failed' : ''
+  if (data.tool === 'door_look') return failed === '' ? undefined : 'ui.look() failed'
+  if (data.tool !== 'door_act') return describeTool(data)
+  const input = (typeof data.input === 'object' && data.input !== null ? data.input : {}) as Record<
+    string,
+    unknown
+  >
+  const target = targetOf(data.result)
+  const quoted = (value: unknown): string => JSON.stringify(clip(String(value ?? '')))
+  const op = typeof input.op === 'string' ? input.op : 'act'
+  const named =
+    typeof target.name === 'string' && target.name !== ''
+      ? quoted(target.name)
+      : typeof input.ref === 'string'
+        ? input.ref
+        : undefined
+  const [verb, args]: [string, readonly (string | undefined)[]] =
+    op === 'navigate'
+      ? ['open', [quoted(input.path)]]
+      : op === 'click' && target.role === 'link'
+        ? ['open', [named]]
+        : op === 'type'
+          ? ['fill', [named, quoted(input.text)]]
+          : op === 'select'
+            ? ['fill', [named, quoted(input.option)]]
+            : op === 'press'
+              ? ['press', [quoted(input.key)]]
+              : op === 'scroll'
+                ? ['scroll', [input.direction === undefined ? undefined : quoted(input.direction)]]
+                : op === 'wait'
+                  ? ['wait', [quoted(input.text ?? input.name)]]
+                  : [op, [named]]
+  return `ui.${verb}(${args.filter((arg) => arg !== undefined).join(', ')})${failed}`
+}

package/plugins/agent-panel/client/driver-pick.ts

@@ -0,0 +1,22 @@
+/**
+ * Which driver pick a finished terminal open may apply to. `choose()` can be in flight when the person picks
+ * another driver (the panel also restores a remembered terminal at start), and only the latest pick may win: a
+ * stale terminal must not replace the form the person chose.
+ */
+export interface PickGeneration {
+  /** Start a pick and return the token its result is settled with. */
+  begin(): number
+  /** True only while `generation` is still the latest pick. */
+  isCurrent(generation: number): boolean
+}
+
+export function createPickGeneration(): PickGeneration {
+  let generation = 0
+  return {
+    begin: () => {
+      generation += 1
+      return generation
+    },
+    isCurrent: (candidate) => candidate === generation,
+  }
+}