acrylblends 0.0.0-stage → 0.2.0

package/plugins/manifest/lock.ts

@@ -0,0 +1,94 @@
+/**
+ * `npm run lock`: write `blend.lock.json` (formatVersion 3, the lock ACRYL writes too) next to the manifest, recording what the app is
+ * built from: the manifest's identity and digest, the Blueprint it was resolved over, its resolved parameters and rows, and a content
+ * digest of every plugin folder in `src/plugins/` and every extension in `extensions/`. Commit it; a diff of the lock is a review of
+ * what changed.
+ */
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  type BlendDocument,
+  type BlendLock,
+  digestFolder,
+  generateBlendLock,
+  type LockModule,
+  manifestDigest,
+  parseDefinition,
+  resolveDefinition,
+} from '@webboxes/blends-core'
+import { blueprintsIn } from './index.ts'
+
+export const LOCK_FILE = 'blend.lock.json'
+
+type LockV3 = Extract<BlendLock, { formatVersion: 3 }>
+
+function read(file: string): { text: string; document: BlendDocument } {
+  const text = readFileSync(file, 'utf8')
+  const { document, diagnostics } = parseDefinition(text)
+  if (diagnostics.length > 0)
+    throw new Error(`${file}:\n${diagnostics.map((d) => `${d.path}: ${d.message}`).join('\n')}`)
+  return { text, document: document as BlendDocument }
+}
+
+function localModules(appRoot: string, folder: string): LockModule[] {
+  const directory = join(appRoot, folder)
+  if (!existsSync(directory)) return []
+  return readdirSync(directory, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => ({
+      name: entry.name,
+      origin: 'local' as const,
+      digest: `sha256:${digestFolder(join(directory, entry.name))}`,
+      source: `${folder}/${entry.name}`,
+    }))
+}
+
+export function writeLock(appRoot: string): LockV3 {
+  const blendFile = join(appRoot, 'blend.yaml')
+  const getBlueprint = blueprintsIn(join(appRoot, 'blueprints'))
+  const { text, document } = read(blendFile)
+  const resolved = resolveDefinition(document, {
+    getDefinition: (id) => {
+      const file = getBlueprint(id)
+      return file === undefined ? undefined : read(file).document
+    },
+  })
+  if (resolved.definition === null)
+    throw new Error(
+      `${blendFile}:\n${resolved.diagnostics.map((d) => `${d.path}: ${d.message}`).join('\n')}`,
+    )
+  // A Blend records the Blueprint file it was resolved over, so an upgrade shows up as a lock diff.
+  const lineage = document.spec.lineage
+  const blueprintFile = lineage ? getBlueprint(lineage.blueprint) : undefined
+  const { lock } = generateBlendLock({
+    resolved: resolved.definition,
+    origin: {
+      id: document.metadata.id,
+      kind: document.kind,
+      version: document.metadata.version,
+      digest: manifestDigest(text),
+    },
+    modules: [...localModules(appRoot, 'src/plugins'), ...localModules(appRoot, 'extensions')],
+    ...(lineage
+      ? {
+          lineage: {
+            ...lineage,
+            ...(blueprintFile
+              ? { digest: manifestDigest(readFileSync(blueprintFile, 'utf8')) }
+              : {}),
+          },
+        }
+      : {}),
+  })
+  writeFileSync(join(appRoot, LOCK_FILE), `${JSON.stringify(lock, null, 2)}\n`)
+  return lock as LockV3
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const appRoot = resolve(fileURLToPath(new URL('../../..', import.meta.url)))
+  const locked = writeLock(appRoot)
+  console.log(
+    `wrote ${LOCK_FILE}: ${locked.rows.length} rows, ${locked.modules.length} local plugins`,
+  )
+}

package/plugins/manifest/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "manifest",
+  "description": "The app as data: blend.yaml lists ordered plugin rows with config, parameters and on/off switches; validated, composed and locked.",
+  "requires": [],
+  "inject": [],
+  "provides": [],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4",
+    "yaml": "2.9.0",
+    "@webboxes/blends-core": "0.4.0"
+  },
+  "mount": "in src/app.ts: const manifest = loadManifest(join(chosen.root, 'blend.yaml')); await compose(root, manifest, registry)"
+}

package/plugins/manifest/upgrade-cli.ts

@@ -0,0 +1,70 @@
+/**
+ * `npm run upgrade -- --from <old blueprint file> --to <new blueprint file> [--apply]`
+ *
+ * Plans the upgrade of this app's Blend to a newer version of its Blueprint and prints the plan (exit 1 when it is not safe). With
+ * `--apply` and a safe plan, it moves `spec.lineage.blueprintVersion` and puts the new Blueprint in `blueprints/<id>.yaml`, where the
+ * app finds it. Nothing else is changed; run `npm run lock` afterwards to record the new Blueprint's digest.
+ */
+import { copyFileSync, mkdirSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import { blueprintsIn, ManifestError } from './index.ts'
+import { applyUpgrade, describePlan, planUpgrade } from './upgrade.ts'
+
+export function runUpgrade(
+  argv: readonly string[],
+  appRoot: string,
+  out: (text: string) => void = console.log,
+): number {
+  let args: ReturnType<typeof parse>
+  try {
+    args = parse(argv)
+  } catch (error) {
+    out(`error: ${(error as Error).message}`)
+    return 2
+  }
+  const { from, to, apply } = args.values
+  if (!from || !to) {
+    out('usage: npm run upgrade -- --from <old blueprint file> --to <new blueprint file> [--apply]')
+    return 2
+  }
+  const blueprints = join(appRoot, 'blueprints')
+  try {
+    const blendFile = join(appRoot, 'blend.yaml')
+    const plan = planUpgrade({
+      blendFile,
+      oldBlueprint: resolve(from),
+      newBlueprint: resolve(to),
+      getBlueprint: blueprintsIn(blueprints),
+    })
+    out(describePlan(plan))
+    if (!plan.safe) return 1
+    if (apply) {
+      applyUpgrade(blendFile, plan)
+      mkdirSync(blueprints, { recursive: true })
+      copyFileSync(resolve(to), join(blueprints, `${plan.blueprint}.yaml`))
+      out(`applied: lineage is now ${plan.blueprint} ${plan.to}; run npm run lock to record it`)
+    }
+    return 0
+  } catch (error) {
+    out(
+      `error: ${error instanceof ManifestError ? error.message : error instanceof Error ? error.message : String(error)}`,
+    )
+    return 1
+  }
+}
+
+const parse = (argv: readonly string[]) =>
+  parseArgs({
+    args: [...argv],
+    strict: true,
+    options: { from: { type: 'string' }, to: { type: 'string' }, apply: { type: 'boolean' } },
+  })
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exitCode = runUpgrade(
+    process.argv.slice(2),
+    resolve(fileURLToPath(new URL('../../..', import.meta.url))),
+  )
+}

package/plugins/manifest/upgrade.ts

@@ -0,0 +1,97 @@
+/**
+ * Upgrading a Blend: what happens when its Blueprint moves to a new version. The plan and its application are ACRYL's own
+ * (`@webboxes/blends-core`); this file only reads the Blend and the two Blueprint files and keeps the terminal output.
+ *
+ * An upgrade is a *plan* before it is an action: what the Blueprint changed, what the Blend can no longer do on it (conflicts),
+ * which changes its overrides hide, and how the rows the app mounts would differ. Only a plan with no conflicts is `safe`.
+ * Applying it moves `spec.lineage.blueprintVersion` and nothing else, keeping the file's comments.
+ */
+import { readFileSync, writeFileSync } from 'node:fs'
+import {
+  applyUpgrade as applyToSource,
+  type BlendDocument,
+  type Diagnostic,
+  parseDefinition,
+  planUpgrade as planFromDocuments,
+  type RowChange,
+  type UpgradePlan,
+} from '@webboxes/blends-core'
+import type { LoadOptions } from './index.ts'
+
+export type { RowChange, UpgradePlan }
+
+const refusal = (diagnostics: readonly Diagnostic[], file?: string) =>
+  new Error(
+    `${file ? `${file}:\n` : ''}${diagnostics.map((d) => `${d.path}: ${d.message}`).join('\n')}`,
+  )
+
+function read(file: string): BlendDocument {
+  const { document, diagnostics } = parseDefinition(readFileSync(file, 'utf8'))
+  if (diagnostics.length > 0) throw refusal(diagnostics, file)
+  return document as BlendDocument
+}
+
+/**
+ * Plan the upgrade of the Blend in `blendFile` from the Blueprint file it was made from (`oldBlueprint`) to a newer one
+ * (`newBlueprint`). `getBlueprint` finds the parents of either Blueprint, if they have any. Throws for input that cannot be read
+ * as a plan: a Blueprint file with the wrong id, an old Blueprint whose version is not the Blend's lineage version, or a document
+ * that is not a Blend. Everything the upgrade would break is in the plan.
+ */
+export function planUpgrade(options: {
+  blendFile: string
+  oldBlueprint: string
+  newBlueprint: string
+  getBlueprint?: LoadOptions['getBlueprint']
+  values?: LoadOptions['values']
+}): UpgradePlan {
+  const getDefinition = options.getBlueprint
+    ? (id: string) => {
+        const file = options.getBlueprint?.(id)
+        return file === undefined ? undefined : read(file)
+      }
+    : undefined
+  const { plan, diagnostics } = planFromDocuments({
+    blend: read(options.blendFile),
+    oldBlueprint: read(options.oldBlueprint),
+    newBlueprint: read(options.newBlueprint),
+    ...(getDefinition ? { getDefinition } : {}),
+    ...(options.values ? { parameters: options.values } : {}),
+  })
+  if (plan === null) throw refusal(diagnostics)
+  return plan
+}
+
+/** Move the Blend's lineage to the plan's new version, keeping the file's comments and layout. Refuses an unsafe plan. */
+export function applyUpgrade(blendFile: string, plan: UpgradePlan): void {
+  const { source, diagnostics } = applyToSource(readFileSync(blendFile, 'utf8'), plan)
+  if (source === null) throw refusal(diagnostics)
+  writeFileSync(blendFile, source)
+}
+
+/** A short, readable account of a plan, for a terminal. */
+export function describePlan(plan: UpgradePlan): string {
+  const line = (change: RowChange) =>
+    `  ${change.change.padEnd(7)} ${change.id}${change.fields ? ` (${change.fields.join(', ')})` : ''}`
+  const lines = [`${plan.blueprint}: ${plan.from} -> ${plan.to}`]
+  lines.push(
+    plan.blueprintChanges.length ? 'the Blueprint changed:' : 'the Blueprint has no row changes',
+    ...plan.blueprintChanges.map(line),
+  )
+  if (plan.shadowed.length)
+    lines.push(
+      'your overrides hide some of that:',
+      ...plan.shadowed.map((entry) => `  ${entry.id}: ${entry.keys.join(', ')}`),
+    )
+  if (plan.conflicts.length)
+    lines.push(
+      'this Blend would break:',
+      ...plan.conflicts.map((conflict) => `  ${conflict.path}: ${conflict.message}`),
+    )
+  else
+    lines.push(
+      plan.appChanges.length ? 'your app would change:' : 'your app would not change',
+      ...plan.appChanges.map(line),
+    )
+  lines.push(plan.safe ? 'safe to apply' : 'NOT safe: resolve the conflicts first')
+  return lines.join('\n')
+}

package/plugins/openai/index.ts

@@ -0,0 +1,159 @@
+/**
+ * A real model for the agent: any OpenAI-compatible chat completions API (OpenAI, DeepSeek, Ollama, LM Studio, a local server), called
+ * with `fetch`, no SDK. It provides the same `model` service as the scripted model, so the agent, its tools and the builder do not change.
+ * Each step is stateless: the conversation is rebuilt from the run's question and tool-call trace.
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import type { Model, ModelInput, Step } from '../agent/index.ts'
+import { SYSTEM_PROMPT } from './prompt.ts'
+
+export interface OpenAIConfig {
+  /** For example https://api.openai.com/v1, https://api.deepseek.com/v1, http://127.0.0.1:11434/v1 (Ollama). */
+  baseUrl: string
+  model: string
+  /** Sent as a bearer token. Local servers need none. Keep it out of files the app commits. */
+  apiKey?: string
+  /** Replaces the default system prompt (how to write a Cordis plugin that installs). */
+  system?: string
+  temperature?: number
+}
+
+/** The model configuration from an environment-shaped object, or `undefined` when none is set. Pass it `process.env` in main.ts. */
+export function modelConfigFrom(
+  env: Readonly<Record<string, string | undefined>>,
+): OpenAIConfig | undefined {
+  const baseUrl = env.ACRYLBLENDS_MODEL_URL?.trim()
+  const model = env.ACRYLBLENDS_MODEL?.trim()
+  if (!baseUrl || !model) return undefined
+  const apiKey = env.ACRYLBLENDS_MODEL_KEY?.trim()
+  return { baseUrl, model, ...(apiKey ? { apiKey } : {}) }
+}
+
+interface ToolCallMessage {
+  id: string
+  type: 'function'
+  function: { name: string; arguments: string }
+}
+
+type Message =
+  | { role: 'system' | 'user'; content: string }
+  | {
+      role: 'assistant'
+      content: string | null
+      tool_calls?: ToolCallMessage[]
+      reasoning_content?: string
+    }
+  | { role: 'tool'; tool_call_id: string; content: string }
+
+/** The chat messages for a step: system, the question, then each tool call and its result. */
+export function messagesFor(input: ModelInput, system: string): Message[] {
+  const messages: Message[] = [
+    { role: 'system', content: system },
+    { role: 'user', content: input.question },
+  ]
+  for (const [index, call] of (input.trace ?? []).entries()) {
+    const id = `call_${index}`
+    messages.push({
+      role: 'assistant',
+      content: null,
+      tool_calls: [
+        {
+          id,
+          type: 'function',
+          function: { name: call.tool, arguments: JSON.stringify(call.input ?? {}) },
+        },
+      ],
+      // A thinking model (DeepSeek) refuses the next request unless its reasoning for the call comes back with it.
+      ...(call.reasoning !== undefined ? { reasoning_content: call.reasoning } : {}),
+    })
+    messages.push({
+      role: 'tool',
+      tool_call_id: id,
+      content: JSON.stringify(
+        call.error === undefined ? (call.result ?? null) : { error: call.error },
+      ),
+    })
+  }
+  return messages
+}
+
+export class ModelError extends Error {
+  override name = 'ModelError'
+}
+
+/** One step: ask the API, and turn its answer into a tool call or final text. */
+export async function complete(
+  config: OpenAIConfig,
+  input: ModelInput,
+  signal?: AbortSignal,
+): Promise<Step> {
+  const response = await fetch(`${config.baseUrl.replace(/\/+$/, '')}/chat/completions`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      ...(config.apiKey ? { authorization: `Bearer ${config.apiKey}` } : {}),
+    },
+    body: JSON.stringify({
+      model: config.model,
+      temperature: config.temperature ?? 0,
+      messages: messagesFor(input, config.system ?? SYSTEM_PROMPT),
+      tools: (input.tools ?? []).map((tool) => ({
+        type: 'function',
+        function: {
+          name: tool.name,
+          description: tool.description,
+          parameters: { type: 'object', additionalProperties: true },
+        },
+      })),
+    }),
+    ...(signal ? { signal } : {}),
+  })
+  if (!response.ok)
+    throw new ModelError(
+      `the model API answered ${response.status}: ${(await response.text()).slice(0, 300)}`,
+    )
+  const answer = (await response.json()) as {
+    choices?: Array<{
+      message?: {
+        content?: string | null
+        reasoning_content?: string | null
+        tool_calls?: ToolCallMessage[]
+      }
+    }>
+  }
+  const message = answer.choices?.[0]?.message
+  if (!message) throw new ModelError('the model API answered without a message')
+  const call = message.tool_calls?.[0]
+  if (call) {
+    let parsed: unknown
+    try {
+      parsed = call.function.arguments ? JSON.parse(call.function.arguments) : {}
+    } catch {
+      return {
+        tool: call.function.name,
+        input: { invalidArguments: call.function.arguments },
+        ...(typeof message.reasoning_content === 'string'
+          ? { reasoning: message.reasoning_content }
+          : {}),
+      }
+    }
+    return {
+      tool: call.function.name,
+      input: parsed,
+      ...(typeof message.reasoning_content === 'string'
+        ? { reasoning: message.reasoning_content }
+        : {}),
+    }
+  }
+  return { text: (message.content ?? '').trim() || '(no answer)' }
+}
+
+/** The plugin: provides `model`, in place of the scripted one. */
+export const openai = {
+  name: 'openai',
+  apply(ctx: Context, config: OpenAIConfig) {
+    if (!config?.baseUrl || !config.model)
+      throw new ModelError('openai needs { baseUrl, model } (and apiKey for hosted APIs)')
+    ctx.provide('model', { complete: (input) => complete(config, input) } satisfies Model)
+  },
+}

package/plugins/openai/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "openai",
+  "description": "A real model for the agent: any OpenAI-compatible chat API (OpenAI, DeepSeek, Ollama, LM Studio) over fetch, with tool calls. No SDK.",
+  "requires": ["agent"],
+  "inject": [],
+  "provides": ["model"],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4"
+  },
+  "mount": "use it in place of the scripted model: registry.model = openai, with config { baseUrl, apiKey, model }"
+}

package/plugins/openai/prompt.ts

@@ -0,0 +1,31 @@
+/** What a real model is told: the app is built from Cordis plugins, and how to write one that installs. */
+export const SYSTEM_PROMPT = `You are the agent inside a running app built from Cordis plugins (@deepseek-ai/cordis). You extend the app by writing
+Cordis plugins and installing them while it runs. A plugin is the building unit: every capability is one.
+
+To add a capability:
+1. write_plugin { name, files: { "index.ts": "..." } }  (name: lowercase letters, digits and dashes; it is the folder name)
+2. install_plugin { name }  -> read the result: ok, state ("active", "pending" with "missing" services, or "failed"), errors
+3. If it failed, read the error, fix the files with write_plugin, and install again. A failed update keeps the old version running.
+
+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'
+  export const name = 'hello'            // must equal the folder name
+  export const inject = ['http']          // 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
+  }
+  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')
+  }
+
+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
+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/sandbox/index.ts

@@ -0,0 +1,150 @@
+/**
+ * The sandbox (`ctx.sandbox`): run code you do not trust, such as a tool an agent just wrote, without giving it the host.
+ *
+ * Each call starts a fresh Node child process with the permission model on (`node --permission`):
+ *  - it may read only the tool's own folder (and the runner); every other file read is denied;
+ *  - it may not write files, start child processes or workers, load native addons, or use the inspector;
+ *  - it gets an empty environment, so no keys or paths leak in;
+ *  - it is killed after a time limit, and capped in memory and in output size.
+ *
+ * What this does NOT do: Node 24 has no network permission, so a tool can still reach the network. Where that matters (a hosted tenant),
+ * restrict egress outside the process. The calls are independent: nothing a tool does survives into the next call.
+ */
+import { spawn } from 'node:child_process'
+import { realpathSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import type { Context } from '@deepseek-ai/cordis'
+
+export interface SandboxOptions {
+  /** Extra folders the tool may read, besides its own. */
+  read?: readonly string[]
+  /** Wall-clock limit. Default 5000. */
+  timeoutMs?: number
+  /** Heap limit in MB. Default 128. */
+  memoryMb?: number
+  /** Largest output kept, in bytes. Default 1 MiB. */
+  maxOutputBytes?: number
+}
+
+export type SandboxResult =
+  | { readonly ok: true; readonly output: unknown }
+  | {
+      readonly ok: false
+      readonly kind: 'denied' | 'timeout' | 'crash' | 'error' | 'output'
+      readonly error: string
+    }
+
+export interface Sandbox {
+  /** Run `entry` (a file that exports `run(input)`) with `input`, as described above. Never throws: failures are results. */
+  run(entry: string, input: unknown, options?: SandboxOptions): Promise<SandboxResult>
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    sandbox: Sandbox
+  }
+}
+
+const RUNNER = join(dirname(fileURLToPath(import.meta.url)), 'runner.mjs')
+const MARK = '\n@@acrylblends-result@@'
+
+export const sandbox: Sandbox = {
+  run(entry, input, options = {}) {
+    // The permission system compares real paths (on macOS /var is /private/var), so grant and import real paths.
+    try {
+      entry = realpathSync(entry)
+    } catch {
+      return Promise.resolve({ ok: false, kind: 'error', error: `${entry} does not exist` })
+    }
+    const timeoutMs = options.timeoutMs ?? 5000
+    const maxOutput = options.maxOutputBytes ?? 1024 * 1024
+    const reads = [dirname(entry), ...(options.read ?? [])].map((path) => {
+      try {
+        return realpathSync(path)
+      } catch {
+        return path
+      }
+    })
+    return new Promise((done) => {
+      const child = spawn(
+        process.execPath,
+        [
+          '--permission',
+          `--allow-fs-read=${RUNNER}`,
+          ...reads.map((path) => `--allow-fs-read=${path}`),
+          '--disallow-code-generation-from-strings',
+          `--max-old-space-size=${options.memoryMb ?? 128}`,
+          RUNNER,
+          pathToFileURL(entry).href,
+        ],
+        { env: {}, cwd: dirname(entry), stdio: ['pipe', 'pipe', 'pipe'] },
+      )
+      let out = ''
+      let err = ''
+      let finished = false
+      const finish = (result: SandboxResult) => {
+        if (finished) return
+        finished = true
+        clearTimeout(timer)
+        child.kill('SIGKILL')
+        done(result)
+      }
+      const timer = setTimeout(
+        () => finish({ ok: false, kind: 'timeout', error: `no result within ${timeoutMs} ms` }),
+        timeoutMs,
+      )
+      child.stdout.on('data', (chunk: Buffer) => {
+        out += chunk
+        if (out.length > maxOutput)
+          finish({ ok: false, kind: 'output', error: `more than ${maxOutput} bytes of output` })
+      })
+      child.stderr.on('data', (chunk: Buffer) => {
+        if (err.length < 4000) err += chunk
+      })
+      child.on('error', (error) => finish({ ok: false, kind: 'crash', error: error.message }))
+      child.on('close', (code) => {
+        const at = out.lastIndexOf(MARK)
+        if (at === -1) {
+          const denied = /ERR_ACCESS_DENIED/.test(err)
+          return finish({
+            ok: false,
+            kind: denied ? 'denied' : 'crash',
+            error: (
+              err
+                .trim()
+                .split('\n')
+                .find((line) => /Error/.test(line)) ?? `exited with ${code}`
+            ).slice(0, 300),
+          })
+        }
+        let parsed: { ok: boolean; output?: unknown; error?: string; code?: string }
+        try {
+          parsed = JSON.parse(out.slice(at + MARK.length))
+        } catch {
+          return finish({
+            ok: false,
+            kind: 'crash',
+            error: 'the tool returned something that is not JSON',
+          })
+        }
+        if (parsed.ok) return finish({ ok: true, output: parsed.output ?? null })
+        finish({
+          ok: false,
+          kind: parsed.code === 'ERR_ACCESS_DENIED' ? 'denied' : 'error',
+          error: parsed.error ?? 'the tool failed',
+        })
+      })
+      child.stdin.on('error', () => undefined)
+      child.stdin.end(JSON.stringify({ input }))
+    })
+  },
+}
+
+/** The plugin: provides `ctx.sandbox`. */
+export const sandboxPlugin = {
+  name: 'sandbox',
+  apply(ctx: Context) {
+    ctx.provide('sandbox', sandbox)
+  },
+}

package/plugins/sandbox/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "sandbox",
+  "description": "Run untrusted code (agent-written tools) in a child process under Node's permission model: read only its own folder, no child processes, no env, time and memory limits.",
+  "requires": [],
+  "inject": [],
+  "provides": ["sandbox"],
+  "dependencies": { "@deepseek-ai/cordis": "4.0.4" }
+}

package/plugins/sandbox/runner.mjs

@@ -0,0 +1,18 @@
+// Runs inside the sandbox child process, started with `node --permission`. Reads { input } as JSON from stdin, calls the tool's exported
+// `run(input)`, and prints the result after a marker, so anything the tool itself prints cannot be mistaken for the result.
+const MARK = '\n@@acrylblends-result@@'
+const chunks = []
+for await (const chunk of process.stdin) chunks.push(chunk)
+const { input } = JSON.parse(Buffer.concat(chunks).toString('utf8'))
+let result
+try {
+  const tool = await import(process.argv[2])
+  if (typeof tool.run !== 'function')
+    throw Object.assign(new Error('the tool must export a function named run'), {
+      code: 'E_NO_RUN',
+    })
+  result = { ok: true, output: (await tool.run(input)) ?? null }
+} catch (error) {
+  result = { ok: false, error: String(error?.message ?? error), code: String(error?.code ?? '') }
+}
+process.stdout.write(`${MARK}${JSON.stringify(result)}\n`)

package/plugins/save/cli.ts

@@ -0,0 +1,19 @@
+/** `npm run save -- "message"`: save the app folder this file lives in. Prints the result; exits 1 when the save was refused. */
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { saveFolder } from './index.ts'
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const appRoot = fileURLToPath(new URL('../../..', import.meta.url))
+  const result = saveFolder(appRoot, process.argv.slice(2).join(' ').trim() || 'save the app')
+  if (result.status === 'refused') {
+    console.error(`not saved: ${result.reason}`)
+    for (const finding of result.secrets ?? [])
+      console.error(`  ${finding.path}${finding.line ? `:${finding.line}` : ''}  ${finding.kind}`)
+    process.exitCode = 1
+  } else if (result.status === 'nothing-to-save') console.log('nothing to save')
+  else
+    console.log(
+      `saved ${result.commit.slice(0, 12)}${result.pushed ? ` and pushed to ${result.remote}` : ''}`,
+    )
+}