Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
5.8 KB
Raw Blame

agent-voice — reference bundle

This directory is a reference, not a runtime gbrain dependency. The gbrain compiled binary does NOT load anything under recipes/agent-voice/code/, recipes/agent-voice/skills/, or recipes/agent-voice/tests/. Those exist to be COPIED into the operator's host agent repo via gbrain integrations install agent-voice --target <host-repo>.

The paradigm

Aspect Legacy skillpack (local-managed) Reference skillpack (copy-into-host-repo)
Where code lives ~/.gbrain/skills/<name>/ <host-repo>/services/voice-agent/
Who owns edits gbrain (managed block) Operator (host repo)
Update path Overwrite or skip Diff-and-propose against manifest hashes
Resolver registration ~/.gbrain/skills/RESOLVER.md <host-repo>/RESOLVER.md or AGENTS.md
Identity of updates gbrain pushes Operator pulls per release cadence
Bisect / blame / history gbrain's git history Operator's host repo git history

The install_kind discriminator in the recipe frontmatter routes between the two paths inside gbrain integrations install.

Sibling-directory convention (for future copy-into-host-repo recipes)

This recipe pioneers the layout future copy-into-host-repo recipes should follow:

recipes/<name>.md                       # registered entrypoint (loader sees this)
recipes/<name>/
├── README.md                           # paradigm doc; gbrain-side only (not copied)
├── package.json                        # top-of-bundle; copied to <host>/services/<name>/package.json
├── code/                               # copied to <host>/services/<name>/code/
├── tests/
│   ├── unit/                           # copied to <host>/services/<name>/tests/unit/
│   ├── e2e/                            # gbrain-side only (puppeteer + live-API costs)
│   └── evals/                          # gbrain-side only (LLM-judge suites)
├── skills/                             # copied to <host>/skills/<skill-name>/
├── install/                            # gbrain-side only; install metadata
│   ├── manifest.json                   # src → target map + per-file SHA-256
│   ├── refresh-algorithm.md            # diff-and-propose semantics
│   └── post-install-hint.md            # next-step prompts for the install agent
└── docs/                               # any extra docs the operator should see post-install

Three rules for new recipes following this shape:

  1. Topology preservation. Tests at recipes/<name>/tests/unit/x.test.mjs MUST import code via ../../code/.... That relative path is preserved when copied to <host>/services/<name>/tests/unit/x.test.mjs → <host>/services/<name>/code/.... The installer is NOT in the business of rewriting imports.

  2. PII guard scope. Every file under recipes/<name>/ is scanned by scripts/check-no-pii-in-agent-voice.sh (or future equivalent), PLUS the top-level recipes/<name>.md. The single source of truth for the blocklist is a JSON file inside the bundle.

  3. install_kind: copy-into-host-repo in frontmatter routes to the copy path. Without it, the recipe defaults to local-managed (legacy ~/.gbrain/skills/ install).

Files (gbrain-side only — NOT copied to host)

  • README.md — this doc.
  • install/manifest.json — declares src → target paths + permissions; the install command computes SHA-256 at copy time.
  • install/refresh-algorithm.md — the diff-and-propose contract.
  • install/post-install-hint.md — what the install agent prints when copy completes.
  • code/lib/personas/private-name-blocklist.json — privacy guard source of truth (read by the shipped guard script and by host-side prompt-shape tests).
  • code/lib/personas/context-builder.contract.md — API the operator implements for live brain context.

Provider notes

  • Cartesia TTS (code/pipeline.mjs, the deferred DIY pipeline): the default model is sonic-3.6. Cartesia switched sonic-english off on 2026-06-01 and requests naming it return an error (#5905). Pass modelId to CartesiaTtsAdapter or set CARTESIA_MODEL_ID to pin another current model (sonic-3.5, sonic-3). tests/unit/cartesia-default-model.test.mjs pins the default without calling the API.

Files (in bundle = code/ + tests/unit/ + skills/ + package.json) — copied to host repo

The install subcommand reads install/manifest.json and copies each listed file to its target path under the host repo. SHA-256s computed at copy time get persisted into <host>/services/<name>/.gbrain-source.json so --refresh can do three-way classification (unchanged-identical / unchanged-stale / locally-modified) without re-walking the entire bundle.

Reading order

If you're new to this paradigm and want to understand the moving parts:

  1. recipes/agent-voice.md — the registered recipe, top-level explainer + install steps.
  2. This file — the paradigm + sibling-directory convention.
  3. install/manifest.json — the literal src → target file map.
  4. install/refresh-algorithm.md — what --refresh does and how to extend it.
  5. code/tools.mjs — the load-bearing trust-boundary code (D14-A read-only allow-list).
  6. code/lib/personas/mars.mjs + code/lib/personas/venus.mjs — the persona prompts.
  7. code/public/call.html — the WebRTC client with ?test=1 instrumentation.
  8. code/server.mjs — the minimal voice server.