acrylblends 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,101 @@
+/**
+ * The ACRYL state service (`ctx.state`): observable cells owned by plugins. A cell created from a plugin's context is removed
+ * when that plugin unloads, so a surface never keeps a value alive for a plugin that is gone. In process the cells are read
+ * and subscribed to directly (the terminal UI); with a router present they are also readable as JSON and streamable as
+ * server-sent events (Web and Desktop), read-only: only the Host plugin that owns a cell writes it.
+ */
+
+import { Context, Service } from '@deepseek-ai/cordis'
+import type { RouteContext } from '../../acryl-router/src/index.ts'
+import { streamSSE } from '../../acryl-router/src/helpers/index.ts'
+import { loopbackOnly } from '../../acryl-router/src/middleware/index.ts'
+import { createCell, createDerived, type Cell, type ReadonlyCell } from './cell.ts'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    state: State
+  }
+}
+
+/** Stable Cordis plugin name, equal to the package name and the Loader row id. */
+export const name = 'acryl-state'
+
+const KEY_PATTERN = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)*$/
+
+export class State extends Service {
+  private readonly cells = new Map<string, ReadonlyCell<unknown>>()
+
+  constructor(ctx: Context) {
+    super(ctx, 'state')
+  }
+
+  private claim(key: string): void {
+    if (!KEY_PATTERN.test(key)) throw new TypeError(`acryl-state: key "${key}" must be dotted lowercase words, like "market.sources"`)
+    if (this.cells.has(key)) throw new Error(`acryl-state: key "${key}" is already in use`)
+  }
+
+  private report = (error: unknown): void => {
+    this.ctx.logger.error(`acryl-state: a subscriber failed: ${error instanceof Error ? error.message : String(error)}`)
+  }
+
+  /** Create a writable cell owned by the calling plugin. The key must be new. */
+  cell<T>(key: string, initial: T): Cell<T> {
+    this.claim(key)
+    const cell = createCell(key, initial, this.report)
+    this.cells.set(key, cell as ReadonlyCell<unknown>)
+    this.ctx.effect(() => () => { this.cells.delete(key) }, `acryl-state: cell ${key}`)
+    return cell
+  }
+
+  /** Create a read-only cell computed from other cells, owned by the calling plugin. */
+  derive<D extends readonly ReadonlyCell<unknown>[], T>(
+    key: string,
+    inputs: D,
+    compute: (...values: { [K in keyof D]: D[K] extends ReadonlyCell<infer V> ? V : never }) => T,
+  ): ReadonlyCell<T> {
+    this.claim(key)
+    const derived = createDerived(key, inputs, compute, this.report)
+    this.cells.set(key, derived.cell as ReadonlyCell<unknown>)
+    this.ctx.effect(() => () => { derived.dispose(); this.cells.delete(key) }, `acryl-state: derived ${key}`)
+    return derived.cell
+  }
+
+  /** A cell by key, if one is live. */
+  find<T = unknown>(key: string): ReadonlyCell<T> | undefined {
+    return this.cells.get(key) as ReadonlyCell<T> | undefined
+  }
+
+  keys(): string[] {
+    return [...this.cells.keys()].sort()
+  }
+
+  /**
+   * The current value of `key` as a server-sent event stream: the value now, then one event per change, until the request is aborted, the client
+   * cancels, or the router is disposed. `streamSSE` holds the request in flight until then, so the router waits for the stream.
+   */
+  stream(key: string, c: RouteContext): Response | undefined {
+    const cell = this.find(key)
+    if (cell === undefined) return undefined
+    return streamSSE(c, stream => {
+      stream.send(cell.get(), { event: 'value' })
+      return cell.subscribe(value => { stream.send(value, { event: 'value' }) })
+    })
+  }
+}
+
+export function apply(ctx: Context): void {
+  const state = new State(ctx)
+  // The same cells on the router, read-only, for any surface; present only where a router is. A request over a socket must come from this machine to this
+  // app; the terminal calls the router in process and is the host's own code.
+  ctx.inject(['router'], inner => {
+    const api = inner.router.group('/api/state', loopbackOnly({ inProcess: 'allow' }))
+    api.get('/', c => c.json({ keys: state.keys() }))
+    api.get('/:key', c => {
+      const cell = state.find(c.param('key') ?? '')
+      return cell === undefined ? c.json({ error: 'no such state' }, 404) : c.json({ key: cell.key, value: cell.get() })
+    })
+    api.get('/:key/events', c => state.stream(c.param('key') ?? '', c) ?? c.json({ error: 'no such state' }, 404))
+    // Over HTTP only where an adapter exists (Web and Desktop); the terminal needs none.
+    inner.inject(['routerHttp'], http => { http.routerHttp.mount('/api/state') })
+  })
+}

package/plugins/acryl-state/tests/cell.spec.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createCell, createDerived } from '../src/cell.ts'
+
+describe('cells', () => {
+  it('holds a value, notifies on change with the previous value, and ignores a set to an equal value', () => {
+    const cell = createCell('a.b', 1)
+    const seen: Array<[number, number]> = []
+    cell.subscribe((value, previous) => seen.push([value, previous]))
+    cell.set(2)
+    cell.set(2)
+    cell.update(n => n + 1)
+    expect(cell.get()).toBe(3)
+    expect(seen).toEqual([[2, 1], [3, 2]])
+  })
+
+  it('stops notifying after unsubscribe, and unsubscribing twice is harmless', () => {
+    const cell = createCell('a', 0)
+    const listener = vi.fn()
+    const stop = cell.subscribe(listener)
+    cell.set(1)
+    stop()
+    stop()
+    cell.set(2)
+    expect(listener).toHaveBeenCalledTimes(1)
+  })
+
+  it('isolates a failing subscriber: the others still run and the error is reported', () => {
+    const report = vi.fn()
+    const cell = createCell('a', 0, report)
+    const after = vi.fn()
+    cell.subscribe(() => { throw new Error('boom') })
+    cell.subscribe(after)
+    cell.set(1)
+    expect(after).toHaveBeenCalledWith(1, 0)
+    expect(report).toHaveBeenCalledTimes(1)
+  })
+
+  it('lets a subscriber unsubscribe itself while being notified', () => {
+    const cell = createCell('a', 0)
+    const calls: number[] = []
+    const stop = cell.subscribe(value => { calls.push(value); stop() })
+    cell.subscribe(value => calls.push(value * 10))
+    cell.set(1)
+    cell.set(2)
+    expect(calls).toEqual([1, 10, 20])
+  })
+})
+
+describe('derived cells', () => {
+  it('recomputes from its inputs, notifies only when its own value changes, and detaches on dispose', () => {
+    const a = createCell('a', 2)
+    const b = createCell('b', 3)
+    const { cell: sum, dispose } = createDerived('sum', [a, b] as const, (x, y) => x + y)
+    const seen: number[] = []
+    sum.subscribe(value => seen.push(value))
+    expect(sum.get()).toBe(5)
+    a.set(10)
+    b.set(1)
+    expect(seen).toEqual([13, 11])
+    const parity = createDerived('parity', [a] as const, x => x % 2 === 0).cell
+    const flips: boolean[] = []
+    parity.subscribe(value => flips.push(value))
+    a.set(12)
+    a.set(14)
+    expect(flips).toEqual([])
+    dispose()
+    a.set(100)
+    // Detached: it keeps the last value it computed (14 + 1), not 100 + 1.
+    expect(sum.get()).toBe(15)
+  })
+})

package/plugins/acryl-state/tests/react.spec.ts

@@ -0,0 +1,39 @@
+// @vitest-environment jsdom
+import { act, cleanup, render } from '@testing-library/react'
+import { createElement } from 'react'
+import { afterEach, describe, expect, it } from 'vitest'
+import { createCell } from '../src/cell.ts'
+import { useCell } from '../src/react.ts'
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+afterEach(cleanup)
+
+function Counter({ cell }: { cell: ReturnType<typeof createCell<number>> }) {
+  return createElement('span', { 'data-testid': 'v' }, String(useCell(cell)))
+}
+
+describe('useCell', () => {
+  it('renders the current value and re-renders when the cell changes', () => {
+    const cell = createCell('r.count', 1)
+    const view = render(createElement(Counter, { cell }))
+    expect(view.getByTestId('v').textContent).toBe('1')
+    act(() => { cell.set(2) })
+    expect(view.getByTestId('v').textContent).toBe('2')
+  })
+
+  it('unsubscribes on unmount, and a second component on the same cell stays in step', () => {
+    const cell = createCell('r.count', 0)
+    let live = 0
+    const watched = { ...cell, subscribe: (listener: Parameters<typeof cell.subscribe>[0]) => { live += 1; const stop = cell.subscribe(listener); return () => { live -= 1; stop() } } }
+    const a = render(createElement(Counter, { cell: watched }))
+    const b = render(createElement(Counter, { cell: watched }))
+    expect(live).toBe(2)
+    act(() => { cell.set(7) })
+    expect(a.container.querySelector('[data-testid=v]')?.textContent).toBe('7')
+    expect(b.container.querySelector('[data-testid=v]')?.textContent).toBe('7')
+    a.unmount()
+    expect(live).toBe(1)
+    b.unmount()
+    expect(live).toBe(0)
+  })
+})

package/plugins/acryl-state/tests/service.spec.ts

@@ -0,0 +1,132 @@
+/**
+ * The state service through a real Cordis `Context`: cells are owned by the plugin that made them, readable and
+ * subscribable in process, and streamed through the router as server-sent events, with cancellation and disposal.
+ */
+
+import { Context } from '@deepseek-ai/cordis'
+import { apply as routerApply, name as routerName } from '../../acryl-router/src/index.ts'
+import { afterEach, describe, expect, it } from 'vitest'
+import { apply, name } from '../src/index.ts'
+
+const contexts: Context[] = []
+const settle = (ms = 0): Promise<void> => new Promise(resolve => setTimeout(resolve, ms))
+afterEach(async () => {
+  while (contexts.length > 0) await contexts.pop()?.fiber.dispose()
+})
+
+async function system(withRouter = true): Promise<Context> {
+  const ctx = new Context()
+  contexts.push(ctx)
+  if (withRouter) ctx.plugin({ name: routerName, apply: routerApply }, { trailingSlash: 'strict' })
+  ctx.plugin({ name, apply })
+  await settle()
+  return ctx
+}
+
+/** A tiny SSE reader over a Response body. */
+async function events(response: Response, count: number): Promise<string[]> {
+  const reader = response.body!.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ''
+  const out: string[] = []
+  while (out.length < count) {
+    const { done, value } = await reader.read()
+    if (done) break
+    buffer += decoder.decode(value, { stream: true })
+    for (let at = buffer.indexOf('\n\n'); at !== -1; at = buffer.indexOf('\n\n')) {
+      out.push(buffer.slice(0, at))
+      buffer = buffer.slice(at + 2)
+    }
+  }
+  reader.releaseLock()
+  return out
+}
+
+describe('acryl-state', () => {
+  it('creates cells owned by the calling plugin and removes them when it unloads', async () => {
+    const ctx = await system()
+    const fiber = ctx.plugin({ name: 'owner', inject: ['state'], apply(c: Context) { c.state.cell('owner.count', 1) } })
+    await settle()
+    expect(ctx.state.keys()).toEqual(['owner.count'])
+    expect(ctx.state.find<number>('owner.count')?.get()).toBe(1)
+    await fiber.dispose()
+    await settle()
+    expect(ctx.state.keys()).toEqual([])
+    expect(ctx.state.find('owner.count')).toBeUndefined()
+  })
+
+  it('rejects a bad or duplicate key', async () => {
+    const ctx = await system()
+    ctx.state.cell('ok.key', 0)
+    expect(() => ctx.state.cell('ok.key', 1)).toThrow(/already in use/)
+    expect(() => ctx.state.cell('Bad Key', 1)).toThrow(/dotted lowercase/)
+    expect(() => ctx.state.derive('ok.key', [], () => 1)).toThrow(/already in use/)
+  })
+
+  it('derives a cell from others and detaches it when its owner unloads', async () => {
+    const ctx = await system()
+    const a = ctx.state.cell<number>('n.a', 1)
+    const fiber = ctx.plugin({ name: 'deriver', inject: ['state'], apply(c: Context) { c.state.derive('n.double', [a] as const, x => x * 2) } })
+    await settle()
+    expect(ctx.state.find<number>('n.double')?.get()).toBe(2)
+    a.set(5)
+    expect(ctx.state.find<number>('n.double')?.get()).toBe(10)
+    await fiber.dispose()
+    await settle()
+    expect(ctx.state.find('n.double')).toBeUndefined()
+  })
+
+  it('serves keys and values as JSON on the router, read-only', async () => {
+    const ctx = await system()
+    ctx.state.cell('app.title', 'hello')
+    const keys = await ctx.router.fetch(new Request('http://acryl.test/api/state'))
+    expect(await keys.json()).toEqual({ keys: ['app.title'] })
+    const one = await ctx.router.fetch(new Request('http://acryl.test/api/state/app.title'))
+    expect(await one.json()).toEqual({ key: 'app.title', value: 'hello' })
+    expect((await ctx.router.fetch(new Request('http://acryl.test/api/state/none'))).status).toBe(404)
+    expect((await ctx.router.fetch(new Request('http://acryl.test/api/state/app.title', { method: 'PUT', body: '"x"' }))).status).toBe(405)
+    expect(ctx.state.find('app.title')?.get()).toBe('hello')
+  })
+
+  it('streams the value now and every change as server-sent events, and ends when the caller aborts', async () => {
+    const ctx = await system()
+    const cell = ctx.state.cell<number>('app.count', 0)
+    const controller = new AbortController()
+    const response = await ctx.router.fetch(new Request('http://acryl.test/api/state/app.count/events', { signal: controller.signal }))
+    expect(response.headers.get('content-type')).toContain('text/event-stream')
+    const reading = events(response, 3)
+    await settle(5)
+    cell.set(1)
+    cell.set(2)
+    expect(await reading).toEqual(['event: value\ndata: 0', 'event: value\ndata: 1', 'event: value\ndata: 2'])
+    controller.abort()
+    await settle(5)
+    // After the abort the stream no longer holds a subscription on the cell.
+    let notified = 0
+    const probe = ctx.state.find<number>('app.count')!.subscribe(() => { notified += 1 })
+    cell.set(3)
+    probe()
+    expect(notified).toBe(1)
+  })
+
+  it('closes every open stream when the router is disposed', async () => {
+    const ctx = await system()
+    ctx.state.cell<number>('app.count', 0)
+    const routerFiber = [...[...ctx.registry.values()].find(runtime => runtime.name === routerName)!.fibers][0]!
+    const response = await ctx.router.fetch(new Request('http://acryl.test/api/state/app.count/events'))
+    const reader = response.body!.getReader()
+    await reader.read()
+    const ended = reader.read()
+    await routerFiber.dispose()
+    await expect(ended).resolves.toMatchObject({ done: true })
+  })
+
+  it('works with no router: cells and subscriptions only, no routes', async () => {
+    const ctx = await system(false)
+    const cell = ctx.state.cell<string>('plain.value', 'a')
+    const seen: string[] = []
+    cell.subscribe(value => seen.push(value))
+    cell.set('b')
+    expect(seen).toEqual(['b'])
+  })
+})

package/plugins/acryl-state/upstream.json

@@ -0,0 +1,20 @@
+{
+  "source": {
+    "repo": "acryldev/acryl",
+    "path": "plugins/acryl-state",
+    "commit": "11fed295161c0282d144b5ac62616988b58d8189"
+  },
+  "vendored": [
+    "src",
+    "tests",
+    "LICENSE"
+  ],
+  "rewrittenSpecifiers": 4,
+  "digest": "sha256:528bdc35dbbe22dfae8822fe054cfbfccae9554b9e06089dd7e269f44e27add4",
+  "testsNotRun": {
+    "tests/react.spec.ts": "needs react and @testing-library/react, which generated apps do not install"
+  },
+  "notice": [
+    "LICENSE"
+  ]
+}

package/plugins/agent/agent.ts

@@ -0,0 +1,152 @@
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from './memory.ts'
+import type {} from './model.ts'
+import type {} from './tools.ts'
+
+/** One tool call made during a run. */
+export interface ToolCall {
+  readonly tool: string
+  readonly input: unknown
+  readonly result?: unknown
+  readonly error?: string
+  /** The thinking model's reasoning for this call, kept so the next step can send it back. */
+  readonly reasoning?: string
+}
+
+/** How a run ended, with every tool call it made. `task` is its durable record's id when the app records tasks. */
+export type RunResult = (
+  | { readonly status: 'completed'; readonly output: string }
+  | { readonly status: 'budget_exceeded' }
+  | { readonly status: 'cancelled' }
+) & { readonly steps: number; readonly trace: readonly ToolCall[]; readonly task?: string }
+
+export interface Agent {
+  run(question: string): Promise<RunResult>
+}
+
+/** The step budget of one run, provided inside the run's own fiber. */
+export interface Budget {
+  steps: number
+  readonly limit: number
+}
+
+export interface AgentConfig {
+  /** Steps per run before it stops. */
+  steps?: number
+}
+
+/**
+ * The part of a task recorder the agent uses. Optional: when an app mounts the `tasks` plugin, each run is a durable task and each
+ * tool call a task it owns; without it, runs work the same and leave no record.
+ */
+interface TaskRecorder {
+  start(
+    kind: string,
+    input: unknown,
+    options?: { parent?: string },
+  ): {
+    readonly id: string
+    readonly signal: AbortSignal
+    progress(detail: unknown): void
+    complete(result: unknown, detail?: unknown): void
+    fail(error: unknown, detail?: unknown): void
+  }
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    agent: Agent
+    budget: Budget
+  }
+}
+
+const message = (error: unknown) => (error instanceof Error ? error.message : String(error))
+
+/**
+ * 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.
+ * When the app records tasks, the run's record is written before the answer is returned, and cancelling it stops the run.
+ */
+export const agent = {
+  name: 'agent',
+  inject: ['model', 'tools', 'memory'],
+  apply(ctx: Context, config?: AgentConfig) {
+    const limit = config?.steps ?? 6
+    let runs = 0
+    ctx.provide('agent', {
+      async run(question) {
+        runs += 1
+        const trace: ToolCall[] = []
+        const recorder = (ctx.get as (name: string) => unknown)('tasks') as TaskRecorder | undefined
+        const record = recorder?.start('agent-run', { question })
+        // 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({
+          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
+            while (budget.steps < budget.limit) {
+              if (record?.signal.aborted) {
+                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}`)
+                result = { status: 'completed', output: step.text, steps: budget.steps, trace }
+                return
+              }
+              const call = record
+                ? recorder?.start(`tool:${step.tool}`, step.input, { parent: record.id })
+                : undefined
+              try {
+                toolResult = await scope.tools.call(step.tool, step.input)
+                trace.push({
+                  tool: step.tool,
+                  input: step.input,
+                  result: toolResult,
+                  ...(step.reasoning !== undefined ? { reasoning: step.reasoning } : {}),
+                })
+                call?.complete(toolResult)
+              } catch (error) {
+                toolResult = { error: message(error) }
+                trace.push({
+                  tool: step.tool,
+                  input: step.input,
+                  error: message(error),
+                  ...(step.reasoning !== undefined ? { reasoning: step.reasoning } : {}),
+                })
+                call?.fail(error)
+              }
+              record?.progress({ steps: budget.steps, trace })
+            }
+            result = { status: 'budget_exceeded', steps: budget.steps, trace }
+          },
+        })
+        try {
+          await task.await()
+        } catch (error) {
+          record?.fail(error, { trace })
+          throw error
+        } finally {
+          await task.dispose()
+        }
+        if (result.status === 'completed')
+          record?.complete(result.output, { 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
+      },
+    } satisfies Agent)
+  },
+}

package/plugins/agent/index.ts

@@ -0,0 +1,20 @@
+/** The offline agent: a scripted model, a tool registry, in-process memory, and one child fiber per run. */
+export {
+  type Agent,
+  type AgentConfig,
+  agent,
+  type Budget,
+  type RunResult,
+  type ToolCall,
+} from './agent.ts'
+export { type Memory, memory } from './memory.ts'
+export {
+  type Model,
+  type ModelInput,
+  model,
+  type Rule,
+  type ScriptedModel,
+  type Step,
+  scripted,
+} from './model.ts'
+export { type Tool, type Tools, tools } from './tools.ts'

package/plugins/agent/memory.ts

@@ -0,0 +1,24 @@
+import type { Context } from '@deepseek-ai/cordis'
+
+/** Long-term memory for the agent. */
+export interface Memory {
+  remember(text: string): void
+  recall(): string[]
+  size(): number
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    memory: Memory
+  }
+}
+
+/** In-process memory. Replace it with a plugin backed by storage when you need persistence. */
+export function memory(ctx: Context) {
+  const items: string[] = []
+  ctx.provide('memory', {
+    remember: (text) => void items.push(text),
+    recall: () => [...items],
+    size: () => items.length,
+  } satisfies Memory)
+}

package/plugins/agent/model.ts

@@ -0,0 +1,79 @@
+import type { Context } from '@deepseek-ai/cordis'
+
+/** One model step: final text, or a tool to call with its input. `reasoning` is a thinking model's reasoning for the call; it must be given back on the next step, so the run keeps it. */
+export type Step =
+  | { readonly text: string; readonly tool?: undefined }
+  | { readonly tool: string; readonly input: unknown; readonly reasoning?: string }
+
+/** What a model sees at each step of a run. */
+export interface ModelInput {
+  readonly question: string
+  /** 0 for the first step of a run. */
+  readonly step: number
+  /** The previous tool's result, if the previous step called one. */
+  readonly toolResult?: unknown
+  /** Every tool call of this run so far, in order: a real model rebuilds the conversation from it. */
+  readonly trace?: ReadonlyArray<{
+    readonly tool: string
+    readonly input: unknown
+    readonly result?: unknown
+    readonly error?: string
+    readonly reasoning?: string
+  }>
+  /** The tools the model may call. */
+  readonly tools?: ReadonlyArray<{ readonly name: string; readonly description: string }>
+}
+
+/** What the agent needs from a model. Replace this plugin with a real provider when you have one. */
+export interface Model {
+  complete(input: ModelInput): Promise<Step>
+}
+
+/** A rule of the scripted model: a step for the input, or `undefined` when it does not apply. */
+export type Rule = (input: ModelInput) => Step | undefined
+
+/** The deterministic model. Other plugins teach it rules for their commands, so whole flows are tested without a network. */
+export interface ScriptedModel extends Model {
+  /** Add a rule, tried before the built-in ones. Returns the function that removes it. */
+  teach(rule: Rule): () => void
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    model: Model
+  }
+}
+
+const builtIn: Rule[] = [
+  ({ toolResult, step }) =>
+    step > 0 ? { text: `The answer is ${String(toolResult)}.` } : undefined,
+  ({ question }) => {
+    const sum = /^add\s+(-?\d+)\s+(-?\d+)$/.exec(question.trim())
+    return sum ? { tool: 'add', input: [Number(sum[1]), Number(sum[2])] } : undefined
+  },
+]
+
+/** A deterministic model: no keys, no network, the same answer every time. */
+export function model(ctx: Context) {
+  const taught: Rule[] = []
+  ctx.provide('model', {
+    teach(rule) {
+      taught.push(rule)
+      return () => void taught.splice(taught.indexOf(rule), 1)
+    },
+    complete(input) {
+      for (const rule of [...taught, ...builtIn]) {
+        const step = rule(input)
+        if (step) return Promise.resolve(step)
+      }
+      return Promise.resolve({ text: `You said: ${input.question}` })
+    },
+  } satisfies ScriptedModel)
+}
+
+/** The scripted model, when the app runs one (a real provider has no `teach`). */
+export function scripted(model: Model | undefined): ScriptedModel | undefined {
+  return model && typeof (model as Partial<ScriptedModel>).teach === 'function'
+    ? (model as ScriptedModel)
+    : undefined
+}

package/plugins/agent/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "agent",
+  "description": "An offline agent: deterministic model, tools, memory, and a child fiber per run that holds the run's step budget.",
+  "requires": [],
+  "inject": ["model", "tools", "memory"],
+  "provides": ["agent", "model", "tools", "memory"],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4"
+  }
+}