acrylblends 1.1.0 → 1.3.0

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

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

@@ -0,0 +1,51 @@
+/**
+ * The ACRYL frame's view as the app page sees it (ide/acryl-blends-frame/src/client/frame-view.ts): the frame's canvas hides the app's own build-time
+ * controls in Build and shows what production shows in Preview. The page is same-origin with the frame, so it reads the handle the frame publishes on
+ * its window through `window.parent`; a page opened directly has no such parent and keeps its own behavior.
+ */
+
+export const FRAME_VIEW_KEY: symbol = Symbol.for('acryl.frame.view')
+export const FRAME_MODE_EVENT = 'acryl:frame-mode'
+
+/** What the app page reads from `window.parent[FRAME_VIEW_KEY]`. */
+export interface FrameViewHandle {
+  readonly mode: 'build' | 'preview'
+}
+
+/**
+ * The frame's view handle when this page runs in the frame's canvas.
+ * @param win - the page's window.
+ * @returns the handle, or undefined when the page is the top window or its parent is cross-origin.
+ */
+export function frameViewOf(win: Window = window): FrameViewHandle | undefined {
+  try {
+    if (win.parent === win) return undefined
+    return (win.parent as unknown as Record<symbol, FrameViewHandle | undefined>)[FRAME_VIEW_KEY]
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Whether the panel is the production Assistant: the Host itself is the Assistant, or the app's production environment names it (ACRYL_ASSISTANT=on)
+ * and the page runs in the frame, whose Preview shows the app as production would.
+ * @param session - the panel's session from its Host.
+ * @param frame - the frame's view handle, if any.
+ */
+export function panelVariant(
+  session: { readonly assistant?: boolean; readonly assistantInProduction?: boolean },
+  frame: FrameViewHandle | undefined,
+): boolean {
+  if (session.assistant === true) return true
+  return frame !== undefined && session.assistantInProduction === true
+}
+
+/**
+ * Whether the panel shows at all: on a page opened directly, yes; in the frame, only in Preview, and only as the Assistant. Build is the builder's
+ * screen, where the app's own panel has no place over the canvas.
+ * @param frame - the frame's view handle, if any.
+ * @param assistant - whether this panel is the production Assistant (see {@link panelVariant}).
+ */
+export function panelVisible(frame: FrameViewHandle | undefined, assistant: boolean): boolean {
+  return frame === undefined || (frame.mode === 'preview' && assistant)
+}