acrylblends 0.0.0-stage → 0.2.0

package/plugins/save/index.ts

@@ -0,0 +1,55 @@
+/**
+ * The save plugin: gives an agent a `save_app` tool when the app has a tool registry. Saving itself is `saveApp` from
+ * `@webboxes/app-persistence` (ACRYL's own) over the user's own git; `npm run save` runs the same use case from a terminal (cli.ts).
+ */
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import { gitCli, githubHosting, type SaveResult, saveApp } from '@webboxes/app-persistence'
+
+export {
+  findSecrets,
+  type GitPort,
+  gitCli,
+  githubHosting,
+  type HostingPort,
+  PersistenceError,
+  readAppIdentity,
+  type SaveResult,
+  type SecretFinding,
+  saveApp,
+  type Visibility,
+} from '@webboxes/app-persistence'
+
+/** Save the app folder: its blend.yaml decides the visibility. */
+export function saveFolder(appRoot: string, message: string): SaveResult {
+  const manifestText = readFileSync(join(appRoot, 'blend.yaml'), 'utf8')
+  return saveApp({ manifestText, message }, gitCli(appRoot), githubHosting(appRoot))
+}
+
+interface ToolRegistry {
+  register(name: string, tool: { description: string; run(input: unknown): unknown }): () => void
+}
+
+export const save = {
+  name: 'save',
+  inject: ['appInstance'],
+  apply(ctx: Context) {
+    const registry = (ctx.get as (name: string) => unknown)('tools') as ToolRegistry | undefined
+    if (!registry) return
+    const root = (ctx.get as (name: string) => { root: string })('appInstance').root
+    ctx.effect(() =>
+      registry.register('save_app', {
+        description:
+          'Commit the app (and push if it has a remote). Refuses a file that holds a secret. Input { message }.',
+        run: (input) => {
+          const message = (input as { message?: unknown } | undefined)?.message
+          return saveFolder(
+            root,
+            typeof message === 'string' && message.trim() ? message : 'save the app',
+          )
+        },
+      }),
+    )
+  },
+}

package/plugins/save/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "save",
+  "description": "Save the app to its own git repository: refuses a file that holds a secret, and a private app going to a public remote.",
+  "requires": [],
+  "inject": ["appInstance"],
+  "provides": [],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4",
+    "@webboxes/app-persistence": "0.1.0"
+  },
+  "mount": "add a script \"save\": \"node src/plugins/save/cli.ts\" to package.json; mount the plugin to give the agent a save_app tool"
+}

package/plugins/server/index.ts

@@ -0,0 +1,138 @@
+import {
+  createServer,
+  type IncomingMessage,
+  type Server as NodeServer,
+  type ServerResponse,
+} from 'node:http'
+import type { AddressInfo } from 'node:net'
+import type { Context } from '@deepseek-ai/cordis'
+import type { Send, Stream } from '../http/index.ts'
+
+/** Where the server listens. Passed as this plugin's Cordis config. */
+export interface ServerConfig {
+  readonly port: number
+  readonly hostname?: string
+  /** Try the next port when this one is taken (up to 20 more). */
+  readonly scan?: boolean
+}
+
+/** The running server, provided once it listens. */
+export interface Server {
+  readonly url: string
+  readonly port: number
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    server: Server
+  }
+}
+
+const SCAN_LIMIT = 20
+
+async function readJson(
+  request: IncomingMessage,
+): Promise<{ ok: true; body: unknown } | { ok: false }> {
+  const chunks: Buffer[] = []
+  for await (const chunk of request) chunks.push(chunk as Buffer)
+  if (chunks.length === 0) return { ok: true, body: undefined }
+  try {
+    return { ok: true, body: JSON.parse(Buffer.concat(chunks).toString('utf8')) }
+  } catch {
+    return { ok: false }
+  }
+}
+
+function listen(listener: NodeServer, port: number, hostname: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const onError = (error: Error) => {
+      listener.off('listening', onListening)
+      reject(error)
+    }
+    const onListening = () => {
+      listener.off('error', onError)
+      resolve()
+    }
+    listener.once('error', onError)
+    listener.once('listening', onListening)
+    listener.listen(port, hostname)
+  })
+}
+
+const KEEPALIVE_MS = 15_000
+
+/**
+ * Answer with server-sent events. Each event has a rising `id`, a `topic` as its event name and JSON `data`; a comment line every 15 s
+ * keeps proxies from closing an idle stream. When the client leaves (or the server stops) the stream's own cleanup runs.
+ */
+function openStream(request: IncomingMessage, response: ServerResponse, stream: Stream): void {
+  response.writeHead(200, {
+    'content-type': 'text/event-stream',
+    'cache-control': 'no-cache',
+    connection: 'keep-alive',
+  })
+  response.write(': connected\n\n')
+  let id = 0
+  let open = true
+  const send: Send = (topic, data) => {
+    if (!open) return
+    id += 1
+    response.write(`id: ${id}\nevent: ${topic}\ndata: ${JSON.stringify(data)}\n\n`)
+  }
+  const leave = stream(send)
+  const keepalive = setInterval(() => response.write(': keepalive\n\n'), KEEPALIVE_MS)
+  const close = () => {
+    if (!open) return
+    open = false
+    clearInterval(keepalive)
+    leave()
+  }
+  request.on('close', close)
+  response.on('close', close)
+}
+
+/** Serves the `http` router with Node's own `node:http`. The returned disposer closes the server. */
+export const server = {
+  name: 'server',
+  inject: ['http'],
+  async apply(ctx: Context, config: ServerConfig) {
+    const hostname = config.hostname ?? '127.0.0.1'
+    const listener = createServer(async (request, response) => {
+      const send = (status: number, body: unknown) => {
+        response.writeHead(status, { 'content-type': 'application/json' })
+        response.end(JSON.stringify(body))
+      }
+      try {
+        const parsed = await readJson(request)
+        if (!parsed.ok) return send(400, { error: 'invalid JSON' })
+        const path = new URL(request.url ?? '/', 'http://localhost').pathname
+        const reply = await ctx.http.handle({
+          method: request.method ?? 'GET',
+          path,
+          body: parsed.body,
+        })
+        if (reply.stream) return openStream(request, response, reply.stream)
+        send(reply.status, reply.body)
+      } catch (error) {
+        send(500, { error: error instanceof Error ? error.message : String(error) })
+      }
+    })
+    const attempts = config.scan && config.port !== 0 ? SCAN_LIMIT + 1 : 1
+    for (let attempt = 0; ; attempt++) {
+      try {
+        await listen(listener, config.port + attempt, hostname)
+        break
+      } catch (error) {
+        const inUse = (error as NodeJS.ErrnoException).code === 'EADDRINUSE'
+        if (!inUse || attempt + 1 >= attempts) throw error
+      }
+    }
+    const { port } = listener.address() as AddressInfo
+    ctx.provide('server', { url: `http://${hostname}:${port}`, port } satisfies Server)
+    return () =>
+      new Promise<void>((done) => {
+        listener.close(() => done())
+        listener.closeAllConnections()
+      })
+  },
+}

package/plugins/server/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "server",
+  "description": "Serves the http router over node:http; moves to the next free port when asked; closes on stop.",
+  "requires": ["http"],
+  "inject": ["http"],
+  "provides": ["server"],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4"
+  }
+}

package/plugins/settings/index.ts

@@ -0,0 +1,270 @@
+/**
+ * The settings service (`ctx.settings`): per-namespace sections kept in one YAML file in the app's home.
+ *
+ * Extracted from ACRYL (`plugins/acryl-settings`). Plugins register a namespace with a schemastery schema and read the resolved value,
+ * which layers schema defaults, the registrant's `base`, and the stored section, in that order. Writes are validated, atomic (write a
+ * temporary file, then rename) and run one at a time in commit order; watchers see them in that order; an event announces each change.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { type Context, Service } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { parseDocument, stringify } from 'yaml'
+import type {} from '../instance/index.ts'
+import { cloneJsonShaped, deepEqualJson, isPlainObject, mergeLayers } from './merge.ts'
+
+const NAMESPACE_PATTERN = /^[a-z][a-z0-9-]*$/
+export const DEFAULT_FILENAME = 'settings.yaml'
+
+/** When a namespace's changes take effect for its owner. */
+export type SettingsApplies = 'live' | 'restart'
+
+export interface SettingsRegisterOptions<T> {
+  /** Values resolved below the stored layer (for example, what the app's composition chose). */
+  base?: Partial<T>
+  /** When the owner applies a change; shown to settings screens. Defaults to `live`. */
+  applies?: SettingsApplies
+  /** Reject a resolved value the schema cannot express as invalid; a throw refuses the write that produced it. */
+  validate?: (value: T) => void
+}
+
+/** One registered namespace, as a settings screen sees it. */
+export interface SettingsDescriptor {
+  readonly namespace: string
+  /** The schemastery schema, serialized. */
+  readonly schema: unknown
+  readonly value: unknown
+  /** Bumps on every committed write. */
+  readonly revision: number
+  readonly applies: SettingsApplies
+  /** The stored section, when there is one. */
+  readonly user?: unknown
+}
+
+/** The owner's handle on one namespace. */
+export interface SettingsScope<T> {
+  /** Current resolved value: schema defaults, then `base`, then the stored section. */
+  get(): T
+  /** Observe committed changes; callbacks run one at a time in commit order. Returns the function that stops watching. */
+  watch(callback: (next: T, prev: T) => void | Promise<void>): () => void
+  /** Merge a patch into the stored section and persist it. */
+  update(patch: object): Promise<void>
+  /** Replace the stored section; `replace({})` resets every key to its base or default. */
+  replace(section: object): Promise<void>
+}
+
+export interface SettingsConfig {
+  /** Absolute path of the YAML file; empty or absent means `<app home>/settings.yaml`. */
+  filename?: string
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    settings: Settings
+  }
+
+  interface Events {
+    /** A committed change to one namespace's resolved value, after the file was written; never for an equal value. */
+    'settings/updated'(namespace: string, next: unknown, prev: unknown): void
+  }
+}
+
+interface Entry {
+  readonly namespace: string
+  readonly schema: z<unknown>
+  readonly options: SettingsRegisterOptions<unknown>
+  resolved: unknown
+  revision: number
+  readonly watchers: Set<Watcher>
+}
+
+interface Watcher {
+  readonly callback: (next: unknown, prev: unknown) => void | Promise<void>
+  active: boolean
+}
+
+function assertNamespace(value: string): void {
+  if (!NAMESPACE_PATTERN.test(value))
+    throw new TypeError(`settings: namespace "${value}" must match ${String(NAMESPACE_PATTERN)}`)
+}
+
+function readDocument(filename: string): Record<string, unknown> {
+  if (!existsSync(filename)) return {}
+  const parsed = parseDocument(readFileSync(filename, 'utf8'), { prettyErrors: true })
+  if (parsed.errors.length > 0) {
+    throw new Error(
+      `settings: invalid settings file ${filename}: ${parsed.errors.map((error) => error.message).join('; ')}`,
+    )
+  }
+  const value: unknown = parsed.toJS() ?? {}
+  if (!isPlainObject(value))
+    throw new Error(`settings: ${filename} must be a map of namespace sections`)
+  return value
+}
+
+/** The service. One instance serves one app home. */
+export class Settings extends Service {
+  readonly filename: string
+  private document: Record<string, unknown>
+  private readonly entries = new Map<string, Entry>()
+  /** Writes and watcher notifications run one at a time, in commit order. */
+  private tail: Promise<void> = Promise.resolve()
+  private disposed = false
+
+  constructor(ctx: Context, config: SettingsConfig = {}) {
+    super(ctx, 'settings')
+    this.filename = config.filename ? config.filename : join(ctx.appInstance.home, DEFAULT_FILENAME)
+    this.document = readDocument(this.filename)
+    ctx.effect(
+      () => async () => {
+        this.disposed = true
+        await this.tail
+      },
+      'settings: settle pending writes',
+    )
+  }
+
+  /** Register a namespace and return its handle. A stored section that fails the schema rejects the registration. */
+  register<T>(
+    namespace: string,
+    schema: z<T>,
+    options: SettingsRegisterOptions<T> = {},
+  ): SettingsScope<T> {
+    assertNamespace(namespace)
+    if (this.entries.has(namespace))
+      throw new Error(`settings: namespace "${namespace}" is already registered`)
+    const entry: Entry = {
+      namespace,
+      schema: schema as z<unknown>,
+      options: options as SettingsRegisterOptions<unknown>,
+      resolved: undefined,
+      revision: 0,
+      watchers: new Set(),
+    }
+    entry.resolved = this.resolve(entry, this.section(namespace))
+    this.entries.set(namespace, entry)
+    this.ctx.effect(
+      () => () => void this.entries.delete(namespace),
+      `settings: namespace ${namespace}`,
+    )
+    return this.scopeFor<T>(entry)
+  }
+
+  /** The resolved value of a registered namespace, or `undefined` when nobody registered it. */
+  get(namespace: string): unknown {
+    return this.entries.get(namespace)?.resolved
+  }
+
+  /** Merge a patch into a namespace by name (for a settings route that never held the scope). An unregistered namespace is refused. */
+  update(namespace: string, patch: Readonly<Record<string, unknown>>): Promise<void> {
+    const entry = this.entries.get(namespace)
+    if (entry === undefined)
+      return Promise.reject(new Error(`settings: namespace "${namespace}" is not registered`))
+    return this.commit(entry, (current) => mergeLayers(current, cloneJsonShaped({ ...patch })))
+  }
+
+  /** Every registered namespace, for settings screens. */
+  describe(): SettingsDescriptor[] {
+    return [...this.entries.values()].map((entry) => {
+      const stored = this.document[entry.namespace]
+      return {
+        namespace: entry.namespace,
+        schema: entry.schema.toJSON(),
+        value: entry.resolved,
+        revision: entry.revision,
+        applies: entry.options.applies ?? 'live',
+        ...(stored === undefined ? {} : { user: structuredClone(stored) }),
+      }
+    })
+  }
+
+  private section(namespace: string): Record<string, unknown> {
+    const stored = this.document[namespace]
+    if (stored === undefined) return {}
+    if (!isPlainObject(stored))
+      throw new Error(`settings: section "${namespace}" in ${this.filename} must be a map`)
+    return stored
+  }
+
+  private resolve(entry: Entry, user: Record<string, unknown>): unknown {
+    const base = (entry.options.base ?? {}) as Record<string, unknown>
+    const value = entry.schema(mergeLayers(base, user))
+    entry.options.validate?.(value)
+    return value
+  }
+
+  private scopeFor<T>(entry: Entry): SettingsScope<T> {
+    return {
+      get: () => entry.resolved as T,
+      watch: (callback) => {
+        const watcher: Watcher = { callback: callback as Watcher['callback'], active: true }
+        entry.watchers.add(watcher)
+        return () => {
+          watcher.active = false
+          entry.watchers.delete(watcher)
+        }
+      },
+      update: (patch) =>
+        this.commit(entry, (current) =>
+          mergeLayers(current, cloneJsonShaped(patch as Record<string, unknown>)),
+        ),
+      replace: (section) =>
+        this.commit(entry, () => cloneJsonShaped(section as Record<string, unknown>)),
+    }
+  }
+
+  /** One write: compute, validate, persist atomically, then notify. A refused write changes nothing. */
+  private commit(
+    entry: Entry,
+    next: (current: Record<string, unknown>) => Record<string, unknown>,
+  ): Promise<void> {
+    const run = async (): Promise<void> => {
+      if (this.disposed) throw new Error('settings: the service is disposed')
+      const nextSection = next(this.section(entry.namespace))
+      const nextValue = this.resolve(entry, nextSection)
+      const prevValue = entry.resolved
+      const nextDocument = { ...this.document, [entry.namespace]: nextSection }
+      if (Object.keys(nextSection).length === 0) delete nextDocument[entry.namespace]
+      this.persist(nextDocument)
+      this.document = nextDocument
+      entry.revision += 1
+      entry.resolved = nextValue
+      if (deepEqualJson(prevValue, nextValue)) return
+      this.ctx.emit('settings/updated', entry.namespace, nextValue, prevValue)
+      for (const watcher of [...entry.watchers]) {
+        if (!watcher.active) continue
+        try {
+          await watcher.callback(nextValue, prevValue)
+        } catch (cause) {
+          this.ctx.logger?.error?.(
+            `settings: watcher for "${entry.namespace}" failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+          )
+        }
+      }
+    }
+    const result = this.tail.then(run, run)
+    this.tail = result.then(
+      () => undefined,
+      () => undefined,
+    )
+    return result
+  }
+
+  private persist(document: Record<string, unknown>): void {
+    mkdirSync(dirname(this.filename), { recursive: true })
+    const temporary = `${this.filename}.${String(process.pid)}.tmp`
+    writeFileSync(temporary, stringify(document), { mode: 0o600 })
+    renameSync(temporary, this.filename)
+  }
+}
+
+/** The plugin: mount it after `instance`. */
+export const settings = {
+  name: 'settings',
+  inject: ['appInstance'],
+  apply(ctx: Context, config: SettingsConfig) {
+    new Settings(ctx, config ?? {})
+  },
+}
+
+export { z }

package/plugins/settings/merge.ts

@@ -0,0 +1,79 @@
+/** Pure helpers for layering a user section over a base and for detaching JSON data. */
+
+/** Whether a value is a plain data object (not an array, null, or class instance). */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+  const proto: unknown = Object.getPrototypeOf(value)
+  return proto === Object.prototype || proto === null
+}
+
+/**
+ * Deep-merge `patch` over `base`: plain objects merge key by key, every other value (arrays included) replaces,
+ * and `undefined` entries in the patch are skipped.
+ */
+export function mergeLayers(
+  base: Record<string, unknown>,
+  patch: Record<string, unknown>,
+): Record<string, unknown> {
+  const merged: Record<string, unknown> = { ...base }
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === undefined) continue
+    const current = merged[key]
+    merged[key] =
+      isPlainObject(current) && isPlainObject(value) ? mergeLayers(current, value) : value
+  }
+  return merged
+}
+
+/**
+ * Detach one write input and reject anything YAML would distort on a reload round trip: only plain objects, arrays,
+ * strings, finite numbers, booleans and `null` pass.
+ * @throws TypeError naming the `$`-rooted path of the first rejected value.
+ */
+export function cloneJsonShaped(root: Record<string, unknown>): Record<string, unknown> {
+  const visiting = new WeakSet<object>()
+  const clone = (value: unknown, path: string): unknown => {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') return value
+    if (typeof value === 'number') {
+      if (!Number.isFinite(value)) throw new TypeError(`settings: ${path} is a non-finite number`)
+      return value
+    }
+    if (Array.isArray(value)) {
+      if (visiting.has(value)) throw new TypeError(`settings: ${path} is a circular reference`)
+      visiting.add(value)
+      const entries = value.map((entry, index) => clone(entry, `${path}[${String(index)}]`))
+      visiting.delete(value)
+      return entries
+    }
+    if (isPlainObject(value)) {
+      if (visiting.has(value)) throw new TypeError(`settings: ${path} is a circular reference`)
+      visiting.add(value)
+      const out: Record<string, unknown> = {}
+      for (const [key, entry] of Object.entries(value)) {
+        if (entry === undefined) continue
+        out[key] = clone(entry, `${path}.${key}`)
+      }
+      visiting.delete(value)
+      return out
+    }
+    throw new TypeError(
+      `settings: ${path} is ${value === undefined ? 'undefined' : `a ${typeof value}`}, which cannot be stored`,
+    )
+  }
+  return clone(root, '$') as Record<string, unknown>
+}
+
+/** Structural JSON equality for two detached values. */
+export function deepEqualJson(a: unknown, b: unknown): boolean {
+  if (a === b) return true
+  if (Array.isArray(a) && Array.isArray(b))
+    return a.length === b.length && a.every((entry, index) => deepEqualJson(entry, b[index]))
+  if (isPlainObject(a) && isPlainObject(b)) {
+    const keys = Object.keys(a)
+    return (
+      keys.length === Object.keys(b).length &&
+      keys.every((key) => Object.hasOwn(b, key) && deepEqualJson(a[key], b[key]))
+    )
+  }
+  return false
+}

package/plugins/settings/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "settings",
+  "description": "Validated settings per namespace in one YAML file in the app's home: defaults, base and stored layers, watch, update.",
+  "requires": ["instance"],
+  "inject": ["appInstance"],
+  "provides": ["settings"],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/schemastery": "3.18.4",
+    "yaml": "2.9.0"
+  },
+  "mount": "mount it after instance: root.plugin(settings, {}); then ctx.settings.register('my-plugin', Schema)"
+}