acrylblends 0.0.0-stage → 0.3.0

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

package/plugins/builder/script.ts

@@ -0,0 +1,161 @@
+/**
+ * The builder's commands for the offline scripted model, so the whole build-install-update-remove loop runs without a network.
+ * A real model reads the tool descriptions instead and decides for itself.
+ *
+ *   create route <name> <path> <text...>   write a plugin that answers GET <path> with { text }, then install it
+ *   update route <name> <path> <text...>   the same, over the existing plugin
+ *   break plugin <name>                     write a version whose apply throws, then try to install it
+ *   remove plugin <name>                    remove it and delete its folder
+ *   create tool <name> <factor>             write a sandboxed tool that multiplies input.n by factor (its example is its check), install it
+ *   run tool <name> <n>                     call an installed tool
+ *   spy tool <name>                         write a tool that tries to read /etc/hosts, to show the sandbox refusing it
+ *   list plugins                            list installed extensions
+ *   package plugin <name>                   make it a standalone package other apps can add
+ */
+import type { Rule, Step } from '../agent/index.ts'
+
+const PATH = /^\/[a-z0-9/-]*$/
+
+export function routeSource(name: string, path: string, text: string): string {
+  return `import type { Context } from '@deepseek-ai/cordis'
+
+/** Written by the builder: answers GET ${path}, and checks that it does before the install counts. */
+export const name = '${name}'
+export const inject = ['router']
+
+interface Router {
+  get(path: string, handler: (c: { json(body: unknown, status?: number): Response }) => Response): unknown
+  request(path: string): Promise<Response>
+}
+export function apply(ctx: Context) {
+  // A route registered through this plugin's context is removed when the plugin is unloaded.
+  (ctx as unknown as { router: Router }).router.get(${JSON.stringify(path)}, (c) => c.json({ text: ${JSON.stringify(text)} }))
+}
+
+export async function check(ctx: Context) {
+  const reply = await (ctx.get('router') as Router).request(${JSON.stringify(path)})
+  if (!reply.ok) throw new Error(\`GET ${path} answered \${reply.status}\`)
+}
+`
+}
+
+export function brokenSource(name: string): string {
+  return `export const name = '${name}'
+
+export function apply() {
+  throw new Error('${name} refuses to start')
+}
+`
+}
+
+function summary(result: unknown): string {
+  const waiting = (result as { stage?: string; name?: string } | undefined)?.stage === 'approval'
+  if (waiting) return `${(result as { name: string }).name}: waiting for the owner's approval.`
+  const answer = result as {
+    ok?: boolean
+    name?: string
+    action?: string
+    state?: string
+    errors?: string[]
+    restoredPrevious?: boolean
+  }
+  if (answer?.ok === true && answer.action)
+    return `${answer.name}: ${answer.action}, ${answer.state}.`
+  if (answer?.ok === true) return `${answer.name}: done.`
+  const restored =
+    answer?.restoredPrevious === undefined
+      ? ''
+      : ` Previous version restored: ${String(answer.restoredPrevious)}.`
+  return `Refused: ${(answer?.errors ?? ['unknown error']).join('; ')}.${restored}`
+}
+
+/** Write, then install, then report. */
+function writeThenInstall(
+  step: number,
+  toolResult: unknown,
+  name: string,
+  files: Record<string, string>,
+): Step {
+  if (step === 0) return { tool: 'write_plugin', input: { name, files } }
+  if (step === 1) {
+    const written = toolResult as { ok?: boolean; error?: string }
+    if (written?.ok !== true)
+      return { text: `Could not write ${name}: ${written?.error ?? 'unknown error'}` }
+    return { tool: 'install_plugin', input: { name } }
+  }
+  return { text: summary(toolResult) }
+}
+
+export function toolFiles(factor: number): Record<string, string> {
+  return {
+    'index.ts': `/** Written by the builder: multiplies input.n by ${factor}. Runs only in the sandbox. */\nexport function run(input: { n: number }) {\n  return { n: input.n * ${factor} }\n}\n`,
+    'tool.json': JSON.stringify({
+      description: `Multiply a number by ${factor}: input { n }.`,
+      examples: [{ input: { n: 2 }, output: { n: 2 * factor } }],
+    }),
+  }
+}
+
+export function spyFiles(): Record<string, string> {
+  return {
+    'index.ts':
+      "import { readFileSync } from 'node:fs'\nexport function run() {\n  return readFileSync('/etc/hosts', 'utf8').length\n}\n",
+    'tool.json': JSON.stringify({
+      description: 'Reads a file it should not.',
+      examples: [{ input: {}, output: 1 }],
+    }),
+  }
+}
+
+export const builderRules: Rule = ({ question, step, toolResult }) => {
+  const words = question.trim().split(/\s+/)
+  const [verb, noun, name, path, ...text] = words
+  if (
+    (verb === 'create' || verb === 'update') &&
+    noun === 'route' &&
+    name &&
+    path &&
+    PATH.test(path)
+  ) {
+    return writeThenInstall(step, toolResult, name, {
+      'index.ts': routeSource(name, path, text.join(' ') || name),
+    })
+  }
+  if (verb === 'create' && noun === 'tool' && name && path && Number.isFinite(Number(path))) {
+    return writeThenInstall(step, toolResult, name, toolFiles(Number(path)))
+  }
+  if (verb === 'spy' && noun === 'tool' && name)
+    return writeThenInstall(step, toolResult, name, spyFiles())
+  if (verb === 'run' && noun === 'tool' && name && path && Number.isFinite(Number(path))) {
+    return step === 0
+      ? { tool: name, input: { n: Number(path) } }
+      : { text: JSON.stringify(toolResult) }
+  }
+  if (verb === 'break' && noun === 'plugin' && name)
+    return writeThenInstall(step, toolResult, name, { 'index.ts': brokenSource(name) })
+  if (verb === 'remove' && noun === 'plugin' && name) {
+    return step === 0
+      ? { tool: 'remove_plugin', input: { name, deleteSource: true } }
+      : { text: summary(toolResult) }
+  }
+  if (verb === 'package' && noun === 'plugin' && name) {
+    if (step === 0) return { tool: 'package_plugin', input: { name } }
+    const packaged = toolResult as { ok?: boolean; dir?: string; error?: string }
+    return {
+      text: packaged?.ok
+        ? `${name}: packaged in ${packaged.dir}.`
+        : `Could not package ${name}: ${packaged?.error ?? 'unknown error'}`,
+    }
+  }
+  if (verb === 'list' && noun === 'plugins') {
+    if (step === 0) return { tool: 'list_plugins', input: {} }
+    const installed =
+      (toolResult as { installed?: Array<{ name: string; state: string }> })?.installed ?? []
+    return {
+      text: installed.length
+        ? installed.map((entry) => `${entry.name} (${entry.state})`).join(', ')
+        : 'No plugins installed.',
+    }
+  }
+  return undefined
+}