acrylblends 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "acrylblends",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Scaffold Cordis apps: acrylblends init.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "acrylblends": "./bin/acrylblends.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "templates",
+    "plugins"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "prepack": "pnpm run build && node scripts-pack.mjs copy",
+    "postpack": "node scripts-pack.mjs remove"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/acrylblends/acrylblends.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://acrylblends.github.io",
+  "keywords": [
+    "cordis",
+    "scaffold"
+  ],
+  "private": false,
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

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

package/plugins/agent/tools.ts

@@ -0,0 +1,50 @@
+import type { Context } from '@deepseek-ai/cordis'
+
+/** One tool: what it does (for the model) and how to run it. */
+export interface Tool {
+  readonly description: string
+  run(input: unknown): unknown | Promise<unknown>
+}
+
+/** The tool registry. A plugin registers its tools inside `ctx.effect`, so they leave with it. */
+export interface Tools {
+  /** Register a tool. Returns the function that removes it. */
+  register(name: string, tool: Tool): () => void
+  list(): Array<{ name: string; description: string }>
+  call(name: string, input: unknown): Promise<unknown>
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    tools: Tools
+  }
+}
+
+/** Provides the registry, with one example tool (`add`). */
+export function tools(ctx: Context) {
+  const table = new Map<string, Tool>()
+  const registry: Tools = {
+    register(name, tool) {
+      if (table.has(name)) throw new Error(`tool "${name}" is already registered`)
+      table.set(name, tool)
+      return () => void table.delete(name)
+    },
+    list: () =>
+      [...table.entries()].map(([name, tool]) => ({ name, description: tool.description })),
+    async call(name, input) {
+      const tool = table.get(name)
+      if (!tool) throw new Error(`unknown tool "${name}"`)
+      return await tool.run(input)
+    },
+  }
+  ctx.provide('tools', registry)
+  ctx.effect(() =>
+    registry.register('add', {
+      description: 'Add two numbers: input [a, b].',
+      run: (input) => {
+        const [a = 0, b = 0] = Array.isArray(input) ? (input as number[]) : []
+        return a + b
+      },
+    }),
+  )
+}

package/plugins/builder/index.ts

@@ -0,0 +1,193 @@
+/**
+ * The builder: the agent's tools for extending the app it runs in.
+ *
+ * Extracted from ACRYL's agent tools (`acryl_install_plugin` and its extension docs): the agent writes a plugin into the app's own
+ * extensions folder, installs it, and gets back the real result (`active`, `pending` with what it waits for, or the error, with the
+ * previous version restored). Writes are confined to that folder. The tools register in `ctx.effect`, so they leave with the builder.
+ */
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, extname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import { scripted, type Tools } from '../agent/index.ts'
+import { NAME } from '../extensions/index.ts'
+import type {} from '../instance/index.ts'
+import { builderRules } from './script.ts'
+
+export interface BuilderConfig {
+  /** Where the agent writes extensions. Defaults to `<project>/extensions`. Must be one of the extensions sources. */
+  dir?: string
+  /** Where `package_plugin` writes standalone packages. Defaults to `<project>/plugin-packages`. */
+  packagesDir?: string
+}
+
+/** The package.json of a standalone plugin package: the host framework is a peer, never a second installed copy. */
+export function packageManifest(name: string, description: string): Record<string, unknown> {
+  return {
+    name,
+    version: '0.1.0',
+    description,
+    type: 'module',
+    exports: { '.': './index.ts', './package.json': './package.json' },
+    files: ['*.ts', '**/*.ts', 'README.md'],
+    // ACRYL measured it: a host package listed under dependencies brings a second copy of the framework, and its services stop
+    // matching after a restart. A peer names the version and installs nothing.
+    peerDependencies: { '@deepseek-ai/cordis': '4.0.4' },
+    keywords: ['cordis', 'cordis-plugin', 'acrylblends'],
+  }
+}
+
+const EXTENSIONS = new Set(['.ts', '.js', '.mjs', '.json', '.md'])
+const MAX_BYTES = 256 * 1024
+
+export class BuilderError extends Error {
+  override name = 'BuilderError'
+}
+
+function pluginName(input: unknown): string {
+  const name = (input as { name?: unknown } | undefined)?.name
+  if (typeof name !== 'string' || !NAME.test(name))
+    throw new BuilderError('name must be lowercase letters, digits and dashes')
+  return name
+}
+
+/** A relative file path inside a plugin folder, or an error. */
+function safeFile(path: string): string {
+  const clean = normalize(path)
+  if (isAbsolute(path) || clean.startsWith('..') || clean.split(sep).includes('..'))
+    throw new BuilderError(`"${path}" must be a path inside the plugin folder`)
+  if (!EXTENSIONS.has(extname(clean)))
+    throw new BuilderError(`"${path}": only ${[...EXTENSIONS].join(', ')} files may be written`)
+  return clean
+}
+
+export const builder = {
+  name: 'builder',
+  inject: ['extensions', 'tools', 'appInstance'],
+  apply(ctx: Context, config: BuilderConfig) {
+    const dir = resolve(config?.dir ?? join(ctx.appInstance.root, 'extensions'))
+    if (!ctx.extensions.sources.some((source) => resolve(source.dir) === dir)) {
+      throw new BuilderError(
+        `the builder writes into ${dir}, which is not an extensions source; add it to the extensions plugin's sources`,
+      )
+    }
+    const folder = (name: string) => join(dir, name)
+    const tools: Tools = ctx.tools
+    const register = (name: string, description: string, run: (input: unknown) => unknown) =>
+      ctx.effect(() => tools.register(name, { description, run }))
+
+    register(
+      'list_plugins',
+      'List installed extensions with their state, and folders not installed yet.',
+      () => ({
+        installed: ctx.extensions.list(),
+        notInstalled: ctx.extensions.pending(),
+      }),
+    )
+
+    register(
+      'read_plugin',
+      'Read a file of an extension: input { name, file? } (default index.ts).',
+      (input) => {
+        const name = pluginName(input)
+        const file = safeFile((input as { file?: string }).file ?? 'index.ts')
+        const path = join(folder(name), file)
+        if (!existsSync(path)) throw new BuilderError(`${name}/${file} does not exist`)
+        return { name, file, text: readFileSync(path, 'utf8') }
+      },
+    )
+
+    register(
+      'write_plugin',
+      'Write files of an extension: input { name, files: { "index.ts": "..." } }. The folder is created; other files are kept.',
+      (input) => {
+        const name = pluginName(input)
+        const files = (input as { files?: unknown }).files
+        if (!files || typeof files !== 'object')
+          throw new BuilderError('files must be an object of path to text')
+        const entries = Object.entries(files as Record<string, unknown>)
+        const bytes = entries.reduce(
+          (total, [, text]) => total + Buffer.byteLength(String(text)),
+          0,
+        )
+        if (entries.length === 0) throw new BuilderError('files is empty')
+        if (bytes > MAX_BYTES)
+          throw new BuilderError(`files are ${bytes} bytes; the limit is ${MAX_BYTES}`)
+        const written: string[] = []
+        for (const [path, text] of entries) {
+          if (typeof text !== 'string') throw new BuilderError(`${path}: the content must be text`)
+          const file = safeFile(path)
+          const target = join(folder(name), file)
+          if (relative(folder(name), target).startsWith('..'))
+            throw new BuilderError(`"${path}" leaves the plugin folder`)
+          mkdirSync(dirname(target), { recursive: true })
+          writeFileSync(target, text)
+          written.push(file)
+        }
+        return { ok: true, name, dir: folder(name), written }
+      },
+    )
+
+    register(
+      'install_plugin',
+      'Install or update an extension from its folder: input { name }. Returns its real state.',
+      (input) => ctx.extensions.install(folder(pluginName(input))),
+    )
+
+    register(
+      'remove_plugin',
+      'Remove an installed extension: input { name, deleteSource? }. deleteSource also deletes its folder.',
+      async (input) => {
+        const name = pluginName(input)
+        const result = await ctx.extensions.remove(name)
+        if (
+          (input as { deleteSource?: unknown }).deleteSource === true &&
+          existsSync(folder(name))
+        ) {
+          rmSync(folder(name), { recursive: true, force: true })
+        }
+        return result
+      },
+    )
+
+    const packagesDir = resolve(
+      config?.packagesDir ?? join(ctx.appInstance.root, 'plugin-packages'),
+    )
+    register(
+      'package_plugin',
+      'Turn an extension into a standalone plugin package other apps can use: input { name, description? }. Returns its folder.',
+      (input) => {
+        const name = pluginName(input)
+        if (
+          !existsSync(join(folder(name), 'index.ts')) &&
+          !existsSync(join(folder(name), 'index.js'))
+        ) {
+          throw new BuilderError(`${name} has no index.ts in ${folder(name)}; write it first`)
+        }
+        const description = String(
+          (input as { description?: unknown }).description ?? `The ${name} Cordis plugin.`,
+        )
+        const target = join(packagesDir, name)
+        rmSync(target, { recursive: true, force: true })
+        mkdirSync(packagesDir, { recursive: true })
+        cpSync(folder(name), target, {
+          recursive: true,
+          filter: (path) => !path.includes('node_modules'),
+        })
+        writeFileSync(
+          join(target, 'package.json'),
+          `${JSON.stringify(packageManifest(name, description), null, 2)}\n`,
+        )
+        if (!existsSync(join(target, 'README.md'))) {
+          writeFileSync(
+            join(target, 'README.md'),
+            `# ${name}\n\n${description}\n\nA Cordis plugin. In an ACRYLBLENDS app: \`acrylblends add <this folder>\`.\n`,
+          )
+        }
+        return { ok: true, name, dir: target }
+      },
+    )
+
+    const model = scripted(ctx.get('model'))
+    if (model) ctx.effect(() => model.teach(builderRules))
+  },
+}

package/plugins/builder/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "builder",
+  "description": "The agent's tools for building the app it runs in: write, install, read, list and remove extensions, with real results.",
+  "requires": ["agent", "extensions", "sandbox"],
+  "inject": ["extensions", "tools", "appInstance"],
+  "provides": [],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4"
+  },
+  "mount": "mount it after agent and extensions: root.plugin(builder, { dir: join(root, 'extensions') }); dir must be an extensions source"
+}