acrylblends 0.2.0 → 0.4.0

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

@@ -0,0 +1,119 @@
+/**
+ * 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 { App, type Context as RequestContext } from '../../acryl-router/src/index.ts'
+import { streamSSE } from '../../acryl-router/src/helpers/index.ts'
+import { loopbackOnly, methodNotAllowed } 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
+  }
+}
+
+const KEEP_ALIVE_MS = 15_000
+
+/** 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 client cancels or the router
+   * is disposed (both abort the stream). A comment line goes out every 15 seconds so proxies and browsers keep an idle stream open.
+   */
+  stream(key: string, c: RequestContext): Response | undefined {
+    const cell = this.find(key)
+    if (cell === undefined) return undefined
+    return streamSSE(c, async stream => {
+      const ended = new Promise<void>(resolve => { stream.onAbort(resolve) })
+      // Writes are asynchronous; chaining them keeps events in the order the cell changed.
+      let queue: Promise<unknown> = Promise.resolve()
+      const send = (value: unknown): void => {
+        queue = queue.then(() => stream.writeSSE({ event: 'value', data: typeof value === 'string' ? value : JSON.stringify(value) })).catch(() => {})
+      }
+      send(cell.get())
+      const unsubscribe = cell.subscribe(send)
+      const keepAlive = setInterval(() => { queue = queue.then(() => stream.write(': keepalive\n\n')).catch(() => {}) }, KEEP_ALIVE_MS)
+      keepAlive.unref()
+      try {
+        await ended
+      } finally {
+        clearInterval(keepAlive)
+        unsubscribe()
+      }
+    })
+  }
+}
+
+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 = new App()
+    api.use(loopbackOnly({ inProcess: 'allow' }), methodNotAllowed({ app: api }))
+      .get('/', c => c.json({ keys: state.keys() }))
+      .get('/:key', c => {
+        const cell = state.find(c.req.param('key'))
+        return cell === undefined ? c.json({ error: 'no such state' }, 404) : c.json({ key: cell.key, value: cell.get() })
+      })
+      .get('/:key/events', c => state.stream(c.req.param('key'), c) ?? c.json({ error: 'no such state' }, 404))
+    inner.router.route('/api/state', api)
+    // 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,22 @@
+{
+  "source": {
+    "repo": "acryldev/acryl",
+    "path": "plugins/acryl-state",
+    "commit": "df79b188398b6d4f8cceda35a72b88300a10a9ce"
+  },
+  "vendored": [
+    "src",
+    "tests",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "rewrittenSpecifiers": 4,
+  "digest": "sha256:8feb067a67ea2628ff31a9fd2201361be4be5a8c217be3b7169277c0ce472b69",
+  "testsNotRun": {
+    "tests/react.spec.ts": "needs react and @testing-library/react, which generated apps do not install"
+  },
+  "notice": [
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/plugins/builder/script.ts

@@ -18,24 +18,20 @@ const PATH = /^\/[a-z0-9/-]*$/
 
 export function routeSource(name: string, path: string, text: string): string {
   return `import type { Context } from '@deepseek-ai/cordis'
+import { App } from 'acryl-router'
 
 /** Written by the builder: answers GET ${path}, and checks that it does before the install counts. */
 export const name = '${name}'
-export const inject = ['http']
-
-interface Http {
-  route(method: string, path: string, handler: () => { body: unknown }): () => void
-  handle(request: { method: string; path: string; body: unknown }): Promise<{ status: number; body: unknown }>
-}
+export const inject = ['router']
 
 export function apply(ctx: Context) {
-  const http = ctx.get('http') as Http
-  ctx.effect(() => http.route('GET', ${JSON.stringify(path)}, () => ({ body: { text: ${JSON.stringify(text)} } })))
+  // The app is mounted through this plugin's context, so the route is removed when the plugin is unloaded.
+  ctx.router.route('/', new App().get(${JSON.stringify(path)}, (c) => c.json({ text: ${JSON.stringify(text)} })))
 }
 
 export async function check(ctx: Context) {
-  const reply = await (ctx.get('http') as Http).handle({ method: 'GET', path: ${JSON.stringify(path)}, body: undefined })
-  if (reply.status !== 200) throw new Error(\`GET ${path} answered \${reply.status}\`)
+  const reply = await ctx.get('router')!.request(${JSON.stringify(path)})
+  if (!reply.ok) throw new Error(\`GET ${path} answered \${reply.status}\`)
 }
 `
 }

package/plugins/extensions/index.ts

@@ -32,7 +32,7 @@ import { type Context, type Fiber, Service } from '@deepseek-ai/cordis'
 import type {} from '../instance/index.ts'
 import type { Sandbox } from '../sandbox/index.ts'
 import { appendLedger, type LedgerEntry, readLedger } from './ledger.ts'
-import { resolveFromApp } from './resolve.ts'
+import { resolveFromApp, routerAliases } from './resolve.ts'
 import { hashFolder, prune, stage } from './stage.ts'
 
 /** A fiber's lifecycle state, by name (Cordis's own enum is a `const enum`, which does not exist at run time). */
@@ -181,6 +181,11 @@ function injected(module: PluginModule): string[] {
 }
 
 /** The service. One instance serves one app home. */
+/** The slice of the state service this plugin uses, by name, so it imports nothing from acryl-state. */
+interface StateService {
+  cell<T>(key: string, initial: T): { set(value: T): void }
+}
+
 export class Extensions extends Service {
   readonly sources: readonly ExtensionSource[]
   readonly stageRoot: string
@@ -195,9 +200,15 @@ export class Extensions extends Service {
   private readonly requests = new Map<string, { dir: string; version: string }>()
   private tail: Promise<unknown> = Promise.resolve()
   private disposed = false
+  /**
+   * The context the service was constructed with. Inside a service method `this.ctx` is Cordis's shadow context, which resolves services as the
+   * service's own fiber, so a plugin mounted from it would read `ctx.router` from the installer's fiber and fail. Extensions mount from this one.
+   */
+  private readonly owner: Context
 
   constructor(ctx: Context, config: ExtensionsConfig = {}) {
     super(ctx, 'extensions')
+    this.owner = ctx
     const { home, root } = ctx.appInstance
     this.sources = (config.sources ?? [{ dir: join(home, 'extensions'), trust: 'install' }]).map(
       (source) => ({
@@ -210,7 +221,7 @@ export class Extensions extends Service {
     this.ledgerFile = join(home, 'extensions-ledger.jsonl')
     // Effects run their disposers newest first: settle pending operations, then dispose every mounted extension, then drop the hook.
     ctx.effect(
-      () => resolveFromApp(this.stageRoot, root),
+      () => resolveFromApp(this.stageRoot, root, routerAliases()),
       'extensions: resolve staged imports from the app',
     )
     ctx.effect(
@@ -228,6 +239,12 @@ export class Extensions extends Service {
       },
       'extensions: settle pending operations',
     )
+    // With the state service mounted, what is installed is also a cell: any surface reads it as JSON or streams its changes (`/api/state/extensions`).
+    ctx.inject(['state'], (inner) => {
+      const state = (inner as unknown as { state: StateService }).state
+      const cell = state.cell('extensions', this.list())
+      inner.on('extensions/changed', () => cell.set(this.list()))
+    })
     this.ready = this.serial(() => this.startup())
   }
 
@@ -512,7 +529,7 @@ export class Extensions extends Service {
   /** Mount a module as a child fiber and wait until it settles. */
   private async mount(module: PluginModule): Promise<{ fiber: Fiber; error?: unknown }> {
     // An extension is a plugin module whose config, if any, comes from its own defaults.
-    const fiber = this.ctx.plugin(module as unknown as Parameters<Context['plugin']>[0])
+    const fiber = this.owner.plugin(module as unknown as Parameters<Context['plugin']>[0])
     try {
       await fiber.await()
       return { fiber }

package/plugins/extensions/resolve.ts

@@ -3,20 +3,45 @@
  * `@deepseek-ai/cordis` would not find the app's `node_modules`. This resolve hook leaves resolution alone, and only when it fails for a
  * module inside the staging folder, resolves the same name from the app's project folder. Uses Node's public `module.registerHooks`
  * (ACRYL needed the same fallback on Deno); the returned function removes the hook.
+ *
+ * The framework plugins are not packages in an app (they are source under `src/plugins/`), so `aliases` names the files a framework specifier such as
+ * `acryl-router` stands for. A staged plugin then imports the same module the app itself runs, so `App` is the very class the router mounts.
  */
-import { mkdirSync, realpathSync } from 'node:fs'
+import { existsSync, mkdirSync, realpathSync } from 'node:fs'
 import { registerHooks } from 'node:module'
 import { join } from 'node:path'
-import { pathToFileURL } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 
 const isBare = (specifier: string) => !/^[./]/.test(specifier) && !specifier.includes(':')
 
-export function resolveFromApp(stageRoot: string, appRoot: string): () => void {
+/** The router's specifiers, as files of the vendored plugin that sits beside this one; empty when the app has no router. */
+export function routerAliases(): Record<string, string> {
+  const src = new URL('../acryl-router/src/', import.meta.url)
+  const files = {
+    'acryl-router': 'index.ts',
+    'acryl-router/middleware': 'middleware/index.ts',
+    'acryl-router/helpers': 'helpers/index.ts',
+  }
+  return Object.fromEntries(
+    Object.entries(files)
+      .map(([specifier, file]) => [specifier, fileURLToPath(new URL(file, src))] as const)
+      .filter(([, path]) => existsSync(path)),
+  )
+}
+
+export function resolveFromApp(
+  stageRoot: string,
+  appRoot: string,
+  aliases: Record<string, string> = {},
+): () => void {
   mkdirSync(stageRoot, { recursive: true })
   const staged = pathToFileURL(`${realpathSync(stageRoot)}/`).href
   const parentURL = pathToFileURL(join(realpathSync(appRoot), 'package.json')).href
   const hook = registerHooks({
     resolve(specifier, context, nextResolve) {
+      const alias = aliases[specifier]
+      if (alias !== undefined && context.parentURL?.startsWith(staged))
+        return nextResolve(pathToFileURL(alias).href, context)
       try {
         return nextResolve(specifier, context)
       } catch (error) {

package/plugins/openai/prompt.ts

@@ -10,22 +10,28 @@ To add a capability:
 A plugin's index.ts is TypeScript that Node runs directly (erasable syntax only: no enums, no parameter properties):
 
   import type { Context } from '@deepseek-ai/cordis'
+  import { App } from 'acryl-router'
   export const name = 'hello'            // must equal the folder name
-  export const inject = ['http']          // services it needs; it waits (pending) until they exist
+  export const inject = ['router']        // services it needs; it waits (pending) until they exist
   export function apply(ctx: Context) {
-    const http = ctx.get('http') as { route(method: string, path: string, handler: (request: { body: unknown }) => { status?: number; body: unknown }): () => void }
-    ctx.effect(() => http.route('GET', '/hello', () => ({ body: { text: 'Hello' } })))   // in ctx.effect: removed when the plugin is
+    ctx.router.route('/', new App().get('/hello', (c) => c.json({ text: 'Hello' })))   // removed when the plugin is unloaded
   }
   export async function check(ctx: Context) {   // optional: must pass, or the install is rolled back
-    const http = ctx.get('http') as { handle(r: { method: string; path: string; body: unknown }): Promise<{ status: number }> }
-    if ((await http.handle({ method: 'GET', path: '/hello', body: undefined })).status !== 200) throw new Error('GET /hello failed')
+    const reply = await ctx.get('router')!.request('/hello')
+    if (!reply.ok) throw new Error('GET /hello failed')
   }
 
+The router: build an App (import { App } from 'acryl-router'), register routes on it with app.get/post/put/patch/delete(path, handler) and mount it with
+ctx.router.route(prefix, app). A path parameter is :id and is read with c.req.param('id'); c.json(body, status) answers JSON, c.text(...) answers text,
+await c.req.json() reads a JSON body, throw new HTTPException(404, { message }) (also from 'acryl-router') answers an error. Routes added to an app
+after route() are not served: build the whole app first. ctx.get('router')!.request('/path', { method: 'POST', body: ... }) calls a route in process (use it in
+check). The mount goes away when the plugin is unloaded.
+
 For a capability that is a pure function of data (parse, convert, compute), write a sandboxed TOOL instead of a plugin. It cannot touch the
 host: it runs in a separate process that can read only its own folder. Files: index.ts exporting  run(input)  and  tool.json:
   { "description": "what it does and its input", "examples": [ { "input": {...}, "output": {...} } ] }
 The examples are run in the sandbox at install and must match exactly, or the install is refused. Use write_plugin and install_plugin for tools too.
 
-Rules: import only relative files, node: built-ins and @deepseek-ai/cordis. Provide services with ctx.provide(name, value) and
+Rules: import only relative files, node: built-ins, @deepseek-ai/cordis and acryl-router. Provide services with ctx.provide(name, value) and
 use others with ctx.get(name). Put timers, listeners and routes inside ctx.effect(() => cleanup). Use list_plugins and
 read_plugin to see what exists. When you are done, answer in one or two plain sentences saying what you built.`

package/plugins/tasks/index.ts

@@ -69,6 +69,14 @@ declare module '@deepseek-ai/cordis' {
 type Change = Partial<TaskRecord> & { readonly id: string }
 const changeOf = (change: TaskChange) => change as unknown as Change
 
+/** The slice of the state service the tasks plugin uses, by name, so it imports nothing from acryl-state. */
+interface StateService {
+  cell<T>(key: string, initial: T): { set(value: T): void }
+}
+
+/** How many of the newest tasks the state cell holds. */
+const STATE_LIMIT = 100
+
 const FINAL: ReadonlySet<TaskStatus> = new Set(['completed', 'failed', 'cancelled', 'interrupted'])
 const message = (error: unknown) => (error instanceof Error ? error.message : String(error))
 
@@ -111,6 +119,12 @@ export class Tasks extends Service {
       },
       'tasks: cancel running work',
     )
+    // With the state service mounted, the latest tasks are also a cell: any surface reads them as JSON or streams their changes (`/api/state/tasks`).
+    ctx.inject(['state'], (inner) => {
+      const state = (inner as unknown as { state: StateService }).state
+      const cell = state.cell('tasks', this.list().slice(0, STATE_LIMIT))
+      inner.on('tasks/changed', () => cell.set(this.list().slice(0, STATE_LIMIT)))
+    })
   }
 
   /** Start a task. The record is written before this returns. */

package/plugins/tsconfig.json

@@ -1,12 +1,10 @@
 {
   "compilerOptions": {
-    "target": "ES2023",
-    "lib": ["ES2023"],
+    "target": "ES2024",
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
     "strict": true,
-    "noUncheckedIndexedAccess": true,
-    "exactOptionalPropertyTypes": true,
     "noImplicitOverride": true,
     "verbatimModuleSyntax": true,
     "erasableSyntaxOnly": true,
@@ -15,5 +13,16 @@
     "skipLibCheck": true,
     "types": ["node"]
   },
-  "include": ["*/**/*.ts"]
+  "include": ["*/**/*.ts"],
+  "exclude": [
+    "acryl-*/src/**/*.test.ts",
+    "acryl-*/src/**/*.case.ts",
+    "acryl-node-server/tests/adapter",
+    "acryl-router/tests/loader.spec.ts",
+    "acryl-state/src/react.ts",
+    "acryl-state/tests/react.spec.ts",
+    "acryl-router-http/tests/adapter.spec.ts",
+    "acryl-router-http/tests/stream.spec.ts",
+    "acryl-router-http/tests/surfaces.spec.ts"
+  ]
 }

package/templates/agent/blend.yaml

@@ -34,12 +34,10 @@ spec:
       name: agent
       config:
         steps: "{{parameters.steps}}"
-    - id: http
-      name: http
-    - id: events
-      name: events
-      config:
-        topics: [tasks/changed, extensions/changed]
+    - id: router
+      name: acryl-router
+    - id: state
+      name: acryl-state
     - id: sandbox
       name: sandbox
     - id: extensions
@@ -53,6 +51,6 @@ spec:
     - id: routes
       name: routes
     - id: server
-      name: server
+      name: acryl-node-server
       config:
         hostname: "{{parameters.hostname}}"