@animalabs/connectome-host 0.3.9 → 0.3.10

package/.env.example

@@ -7,6 +7,13 @@ ANTHROPIC_API_KEY=sk-ant-...
 # OPENAI_API_KEY=sk-...
 # OPENAI_BASE_URL=https://api.openai.com/v1
 
+# For recipes with agent.provider="openai-codex" (ChatGPT subscription):
+# Install the Codex CLI and sign in with ChatGPT. If no login exists,
+# connectome-host will show a device-code login on the first model call.
+# CODEX_BINARY=codex
+# CODEX_HOME=/absolute/path/to/.codex
+# CODEX_BASE_URL=https://chatgpt.com/backend-api/codex
+
 # --- Recipe ${VAR} substitutions ---------------------------------------
 # Recipes in recipes/ reference these via ${VAR}.  Unset = that branch of
 # the recipe fails to load; remove the referencing mcpServers block from

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,26 @@
+## Problem
+
+<!-- What is wrong / missing, and for whom. Link the issue if one exists. -->
+
+## Changes
+
+<!-- What this PR does. For cross-repo or stacked work, list companion PRs
+     and merge-order guidance ("safe in either order because…"). -->
+
+## Tests
+
+<!-- Evidence, not assertion: paste the numbers.
+     e.g. `bun test`: 342 pass / 2 fail — failure count identical to main baseline. -->
+
+## Not verified
+
+<!-- Anything you did not exercise (live integrations, platforms, migration
+     paths). "Nothing — verified end-to-end" is a fine answer; silence is not. -->
+
+---
+
+- [ ] `CHANGELOG.md` updated under `## Unreleased` — or this change is
+      internal-only / test-only / docs-only (apply the `no-changelog` label).
+
+<!-- AI-assisted contributions are welcome and normal here — see
+     CONTRIBUTING.md for the attribution convention (footer + Co-Authored-By). -->

package/.github/workflows/changelog.yml

@@ -0,0 +1,32 @@
+name: Changelog
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+
+permissions:
+  contents: read
+
+jobs:
+  changelog-entry:
+    name: Changelog entry present
+    runs-on: ubuntu-latest
+    if: "!contains(github.event.pull_request.labels.*.name, 'no-changelog')"
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Require CHANGELOG.md update when src/ changes
+        run: |
+          base="${{ github.event.pull_request.base.sha }}"
+          head="${{ github.event.pull_request.head.sha }}"
+          changed=$(git diff --name-only "$base...$head")
+          echo "Changed files:"
+          echo "$changed"
+          if echo "$changed" | grep -q '^src/' && ! echo "$changed" | grep -qx 'CHANGELOG.md'; then
+            echo "::error::This PR touches src/ but not CHANGELOG.md. Add an entry under 'Unreleased' (see CONTRIBUTING.md), or apply the 'no-changelog' label if the change is internal-only."
+            exit 1
+          fi
+          echo "OK"

package/.github/workflows/publish.yml

@@ -53,6 +53,15 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
+      - name: Require changelog section for this release
+        run: |
+          ver="${GITHUB_REF_NAME#v}"
+          esc=$(printf '%s' "$ver" | sed 's/[.]/\\./g')
+          if ! grep -Eq "^## ${esc}([^0-9]|$)" CHANGELOG.md; then
+            echo "::error::CHANGELOG.md has no '## ${ver}' section for tag ${GITHUB_REF_NAME}. Retitle the Unreleased section before tagging (see CONTRIBUTING.md)."
+            exit 1
+          fi
+
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
@@ -68,3 +77,40 @@ jobs:
 
       - name: Publish
         run: npm publish --access public --provenance
+
+  github-release:
+    name: GitHub release notes
+    runs-on: ubuntu-latest
+    needs: build-and-test
+    # Deliberately independent of the npm publish job: some consumers run
+    # github-clone checkouts, and release notes must exist even when npm
+    # publish fails — the two jobs succeed or fail on their own.
+    if: startsWith(github.ref, 'refs/tags/v')
+
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Mirror changelog section into release notes
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          ver="${GITHUB_REF_NAME#v}"
+          # Section header is '## X.Y.Z — YYYY-MM-DD'; match the version
+          # field exactly (string compare, no regex escaping needed).
+          awk -v ver="$ver" '
+            /^## / { if (in_section) exit; if ($2 == ver) { in_section = 1; next } }
+            in_section { print }
+          ' CHANGELOG.md | sed '/./,$!d' > notes.md
+          if ! [ -s notes.md ]; then
+            echo "::error::No CHANGELOG.md section found for ${ver}."
+            exit 1
+          fi
+          if gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1; then
+            gh release edit "$GITHUB_REF_NAME" --notes-file notes.md
+          else
+            gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" \
+              --notes-file notes.md --verify-tag
+          fi

package/CHANGELOG.md

@@ -2,6 +2,65 @@
 
 ## Unreleased
 
+## 0.3.10 — 2026-07-21
+
+### Added
+
+- **Provider transports**: `provider: "bedrock"` for legacy Claude models
+  (3.5 Sonnet 0620/1022, Opus 3) surviving on AWS APAC after Anthropic API
+  retirement — AWS_* env credentials, model-ID mapping via membrane, prompt
+  caching forced off (legacy models reject `cache_control`; verified live).
+  `provider: "openai-codex"` (ChatGPT subscription, device-code login,
+  `/fast` toggle) and `provider: "openrouter"` formalized with validation.
+- **Bedrock wire logging**: `LoggingBedrockAdapter` writes
+  `llm-calls.<iso>.jsonl` on the bedrock path — tool names per request,
+  stop_reason + block shapes per response, raw request retained on errors.
+- **Prefill-era bot migration**: recipe `agent.formatter: "anthropic-xml"`
+  (membrane classic prefill) + `agent.prefillUserMessage` scaffold — together
+  reproduce a chapterx borg's exact prompting structure inside a resident
+  (first used for the Supreme Sonnet isekai, 2026-07-21).
+
+- Contribution policy: `CONTRIBUTING.md` (how changes land, review process,
+  AI-attribution convention, changelog rules — binding for PRs and direct
+  pushes, humans and AIs alike) and a PR template.
+- CI `changelog` check: PRs touching `src/` must also touch `CHANGELOG.md`,
+  opt out with the `no-changelog` label. The publish workflow now refuses to
+  release a `vX.Y.Z` tag with no matching `## X.Y.Z` changelog section.
+- Release mechanics automated: `npm version <level>` cuts `Unreleased` into
+  `## X.Y.Z — date` via the `version` hook (`scripts/release-changelog.ts`),
+  and on release tags CI creates the GitHub release with that section as
+  its notes — independent of the npm publish job, so notes exist for
+  github-clone consumers even when a publish fails.
+- **Web UI observability catch-up**: `ops:alert` traces render as persistent
+  banner rows in the SPA (compression quarantine, refusal streaks,
+  inference-exhausted; `<kind>-clear` stands them down); a Health sidebar tab
+  polls `/healthz` for per-agent status, failure streaks, refusal stats,
+  runtime settings, and quarantine, and reconciles durable-state alerts on
+  connect. New protocol frames `request-branches`/`branches-list` back a
+  Chronicle branch-lineage panel opened from the header branch chip, with
+  checkout via the existing `/checkout` command path (read-only for
+  observers; listing rides the `messages` scope). The `/curve` link now
+  lives in the Context panel header.
+- **TUI modernization**: `p` on an agent inside a fleet child opens an
+  honest per-agent peek — the child's event stream filtered by `agentName`,
+  covering the child's root agent and its subagents (sub-subagents of the
+  parent), with phase/tokens/task header from the tree reducer. `ops:alert`
+  traces from the local framework AND from every fleet child surface as red
+  chat lines plus a persistent `⚠ N alerts` status-bar segment; all-clears
+  stand alerts down. The token line now shows the session cost estimate
+  when priced.
+
+### Fixed
+
+- Dead `PlaceholderPanel` removed from the SPA; stale doc pointers
+  (`WEBUI-PLAN.md`, knowledge-miner references) corrected; README now
+  documents the web UI, headless mode, and current TUI peek semantics.
+
+## 0.3.2 — 2026-07-14
+
+Retro-filed: 0.3.1–0.3.9 predate the changelog policy and were released
+without cutting this file; only the entry below was recorded at the time.
+
 ### Breaking (recipe authors only)
 
 - `modules.fleet.children[].recipe` paths now resolve at recipe-load time

package/CONTRIBUTING.md

@@ -0,0 +1,126 @@
+# Contributing to connectome-host
+
+connectome-host is part of the Connectome ecosystem
+([agent-framework](https://github.com/anima-research/agent-framework),
+[membrane](https://github.com/antra-tess/membrane),
+[context-manager](https://github.com/anima-research/context-manager),
+[chronicle](https://github.com/anima-research/chronicle)). These conventions
+describe how work actually lands here — they codify existing practice rather
+than aspiration. When in doubt, recent merged PRs are the best reference.
+
+Everything below applies to every change however it lands — external PR or
+maintainer direct push — and to human and AI authors identically. There is
+no separate rulebook for either.
+
+## How changes land
+
+- External contributions come as PRs against `main`, from a fork or a repo
+  branch. Maintainers also land small changes directly on `main`; don't be
+  surprised by history that never saw a PR.
+- Branch names: `feat/<kebab-case>`, `fix/<kebab-case>`, `docs/`, `chore/`.
+  Including the issue number is welcome (`fix/43-scope-module-injections`).
+- PRs are merged as **true merge commits** — no squash, no rebase-merge.
+  Because nothing is squashed, keep individual commits coherent.
+- To update a stale branch, rebase onto `main` or merge `main` in; both are
+  accepted.
+- Stacked PRs and cross-repo companion PRs are fine, but **declare them** in
+  the body with merge-order guidance ("stacked on #7 — review that first";
+  "safe to merge in either order because …").
+
+## What a PR should contain
+
+Body shape (the PR template mirrors this): **Problem / Changes / Tests**,
+plus, when applicable, **Not verified**, **Out of scope**, and
+**Companion PRs**. The conventions that matter:
+
+- **Evidence over assertion.** State the test baseline numerically:
+  "`bun test`: N pass / M fail, failure count identical to `main` baseline."
+  A claim like "all tests pass" without the count will be re-verified anyway,
+  so save the reviewer the trip.
+- **Say what you did NOT verify.** An honest "not exercised end-to-end
+  against a live Zulip" is respected; a silent gap that review uncovers is
+  not.
+- **Tests accompany behavior changes.** Review scrutinizes test substance,
+  not mere presence — a test that can't fail on the unfixed code will be
+  called out.
+- **Changelog entry** under `## Unreleased` for anything behavior-affecting
+  (see below).
+
+Conventional-commit-style titles (`feat(recipe): …`, `fix(subagent): …`) are
+the house default; plain descriptive titles are accepted.
+
+## Review process — what to expect
+
+- Review arrives as **ordinary PR comments**, not GitHub review approvals —
+  the comment thread is the gate. Reviews are frequently AI-generated and
+  explicitly labeled as such, with a severity verdict and itemized findings.
+- The reviewer will typically **run your branch** (typecheck, test suite,
+  loading a recipe) and paste transcripts. Claims are checked, not trusted.
+- Respond by pushing fix commits and replying per finding — "Addressed in
+  `<sha>`" — rather than force-pushing a rewritten branch. A re-review then
+  flips the verdict.
+- Maintainers may push small review fixes **directly to your branch** to keep
+  things moving. Say so in the PR body if you'd rather they didn't.
+- PRs are never closed silently: a closed PR gets a one-line disposition
+  comment (usually supersession by another PR).
+
+## AI-assisted contributions
+
+AI-written code is the norm in this ecosystem, welcome from everyone, and
+held to exactly the same evidence standards as anything else. Declare it the
+way we do:
+
+- the `🤖 Generated with [Claude Code](https://claude.com/claude-code)`
+  footer (or equivalent for your tooling) in the PR body, and
+- a `Co-Authored-By:` trailer naming the model in commits.
+
+What earns an automated contribution a changes-requested review is not being
+AI-generated — it's arriving without the suite having been run, with tests
+that don't fail on unfixed code, or with claims the branch itself disproves.
+
+## Changelog
+
+`CHANGELOG.md` keeps a standing `## Unreleased` section with
+`### Breaking` / `### Added` / `### Changed` / `### Fixed` subsections
+(loosely [Keep a Changelog](https://keepachangelog.com/)).
+
+- **The entry lands with the change** — same commit, or at least the same
+  PR. This binds direct pushes to `main` just as much as PRs. On PRs, CI
+  enforces it softly: touching `src/` without touching `CHANGELOG.md` fails
+  the `changelog` check unless the `no-changelog` label is applied.
+- **What needs an entry:** anything an operator, recipe author, or module
+  developer would notice — behavior, config/recipe schema, CLI, tool
+  surfaces, defaults. Internal refactors, test-only, and docs-only changes
+  don't.
+- **Breaking entries are audience-scoped.** Name the audience in the heading
+  (`### Breaking (recipe authors only)`) and cover: **who needs to act**,
+  **migration**, and **unchanged** (what readers might fear broke but
+  didn't). The fleet recipe-path entry in `CHANGELOG.md` is the canonical
+  example of the format.
+- **Releases** (maintainers): `npm version <patch|minor|major>` does the
+  whole cut — the `version` hook retitles `Unreleased` to
+  `## X.Y.Z — YYYY-MM-DD` (keeping a fresh `Unreleased` above it, and
+  refusing to release when there are no entries), then npm commits and tags.
+  `git push --follow-tags` triggers CI, which refuses a tag with no matching
+  changelog section, publishes `@animalabs/connectome-host` to npm, and
+  creates the GitHub release with that section as its notes. The two release
+  jobs are independent: some consumers run github-clone checkouts, so
+  release notes must exist even when npm publish fails. Version bumps are a
+  maintainer release-time action, not part of feature PRs.
+
+## Building and testing
+
+```bash
+bun install
+bun test            # test suite
+bunx tsc --noEmit   # typecheck
+bun src/index.ts    # run (generic assistant)
+```
+
+Push-time CI (`ci.yml`) builds and tests every push and PR on ubuntu and
+macos, installing the web app with a strict lockfile (`npm ci`) — if you
+touched `web/` dependencies, regenerate the lock with `npm run relock:web`
+so it carries both platforms' native binaries.
+
+See `docs/DEV-ENVIRONMENT.md` for the full dev setup and `docs/` generally
+for architecture and operations guides.

package/README.md

@@ -1,13 +1,13 @@
 # connectome-host
 
-A general-purpose agent TUI host with recipe-based configuration. Point it at any use case by loading a recipe — a JSON file that defines the system prompt, MCP servers, modules, and agent settings.
+A general-purpose agent host with recipe-based configuration. Point it at any use case by loading a recipe — a JSON file that defines the system prompt, MCP servers, modules, and agent settings. Interact through the web UI (browser operator console), the interactive TUI, or run headless under a fleet parent.
 
 Built on the Connectome stack: [@animalabs/agent-framework](https://github.com/anima-research/agent-framework) + [@animalabs/context-manager](https://github.com/anima-research/context-manager) + [@animalabs/chronicle](https://github.com/anima-research/chronicle) + [@animalabs/membrane](https://github.com/anima-research/membrane).
 
 ## Quick start
 
 ```bash
-# Prerequisites: Bun, Rust toolchain, Anthropic API key
+# Prerequisites: Bun, Rust toolchain, and provider credentials
 export ANTHROPIC_API_KEY=sk-ant-...
 
 bun install
@@ -96,8 +96,31 @@ Recipe servers merge with `mcpl-servers.json`. The file wins on conflict, so use
 
 See [`recipes/SETUP.md`](recipes/SETUP.md) for a detailed setup guide for the knowledge-miner recipe.
 
+### ChatGPT subscription provider
+
+Install the Codex CLI, sign in with `codex login`, then select the subscription
+transport in a recipe:
+
+```json
+{
+  "agent": {
+    "provider": "openai-codex",
+    "model": "gpt-5.4",
+    "codex": { "fastMode": false },
+    "systemPrompt": "You are a helpful assistant."
+  }
+}
+```
+
+Connectome asks the Codex app-server to refresh the ChatGPT login and starts a
+device-code flow if needed. No `OPENAI_API_KEY` is used for this provider. Use
+`/fast on` or `/fast off` at runtime. Connectome requests Codex's Fast tier and
+warns if the service reports that it fell back to Standard; Fast mode consumes
+subscription credits at a higher rate when applied.
+
 ## What it provides
 
+- **Web UI**: browser operator console (`modules.webui`) — live chat with full interiority (thinking, tool calls, streaming), agent/fleet tree, context makeup + compression coverage, call ledger with cache verdicts and billing-grade costs, health/ops alerts, Chronicle branch tree, lessons, MCPL config, workspace files; scoped read-only observer access via device keys
 - **TUI + readline modes**: OpenTUI interactive terminal or `--no-tui` for pipes/CI
 - **Subagent forking**: Spawn/fork parallel agents with fleet tree view (Tab to toggle)
 - **Persistent lessons**: Knowledge store with confidence scores, tags, and semantic retrieval
@@ -109,7 +132,7 @@ See [`recipes/SETUP.md`](recipes/SETUP.md) for a detailed setup guide for the kn
 ## Prerequisites
 
 - [Node.js](https://nodejs.org/) 20+ and [Bun](https://bun.sh/) runtime
-- An Anthropic API key
+- An Anthropic API key, OpenAI API key, or the Codex CLI signed in with ChatGPT
 
 ### Install
 
@@ -122,7 +145,11 @@ npm install
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `ANTHROPIC_API_KEY` | (required) | Anthropic API key |
-| `MODEL` | from recipe or `claude-opus-4-6` | Override model |
+| `OPENAI_API_KEY` | — | OpenAI Platform key for `openai-responses` recipes |
+| `CODEX_BINARY` | `codex` | Codex CLI executable for `openai-codex` subscription auth |
+| `CODEX_HOME` | `~/.codex` | Codex credential/config directory |
+| `CODEX_BASE_URL` | ChatGPT Codex backend | Optional subscription transport override |
+| `MODEL` | from recipe or provider default | Override model |
 | `DATA_DIR` | `./data` | Session and recipe storage |
 
 ## Running
@@ -130,10 +157,29 @@ npm install
 ```bash
 bun src/index.ts                    # Interactive TUI
 bun src/index.ts --no-tui           # Readline mode
+bun src/index.ts --headless         # Daemon: JSONL IPC over unix socket, no terminal
 echo "Hello" | bun src/index.ts     # Piped mode
 bun --watch src/index.ts            # Dev mode
 ```
 
+## Web UI
+
+Enable with `"modules": { "webui": true }` (or `{ "port": 7340, "host": "0.0.0.0" }`)
+in the recipe. The host serves the SPA and its WebSocket protocol on port 7340;
+non-loopback binds require basic-auth credentials. Build the SPA bundle once with
+`bun run build:web` (also runs on `npm install` via postinstall).
+
+- Chat with full interiority: thinking blocks, tool calls + results, live streaming
+- Sidebar: agent/fleet tree, lessons, MCPL servers, workspace files, context makeup + compression coverage, health (runtime settings, failure streaks, compression quarantine)
+- Header branch chip opens the Chronicle branch lineage tree (checkout from the UI)
+- Ops alerts (compression quarantine, refusal streaks, inference-exhausted) render as persistent banner rows
+- Usage panel: per-agent costs and a billing-grade call ledger with cache verdicts
+- `/curve` — compression-curve visualization; `/healthz` — liveness JSON for doctor/fleet tooling
+- Read-only observer access via Ed25519 device keys with per-grant scopes (see `docs/webui-deployment.md`)
+
+For SPA development: `cd web && bun run dev` proxies the Vite dev server onto a
+locally running host.
+
 ## Slash commands
 
 | Command | Effect |
@@ -156,6 +202,7 @@ bun --watch src/index.ts            # Dev mode
 | `/mcp remove <id>` | Remove a server |
 | `/mcp env <id> KEY=VALUE [...]` | Set env vars on a server |
 | `/budget [tokens]` | Show/set stream token budget |
+| `/fast [on\|off\|status]` | Toggle Codex subscription Fast mode |
 | `/session list\|new\|switch\|rename\|delete` | Session management |
 | `/quit` | Exit |
 
@@ -176,7 +223,7 @@ bun --watch src/index.ts            # Dev mode
 | Up/Down | Navigate tree |
 | Enter/Right | Expand/collapse |
 | Left | Collapse |
-| `p` | Peek at running subagent's stream |
+| `p` | Peek the selected node's live stream — local subagents, fleet children, or a single agent/subagent inside a fleet child |
 | `Delete` | Stop a running subagent |
 
 ## Architecture

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@animalabs/connectome-host",
-  "version": "0.3.9",
+  "version": "0.3.10",
   "description": "General-purpose agent TUI host with recipe-based configuration",
   "type": "module",
   "scripts": {
     "start": "bun src/index.ts",
     "dev": "bun --watch src/index.ts",
     "test": "bun test",
+    "version": "bun scripts/release-changelog.ts && git add CHANGELOG.md",
     "build:web": "npm --prefix web install && npm --prefix web run build",
     "build:web:ci": "npm ci --prefix web && npm --prefix web run build",
     "relock:web": "rm -rf web/node_modules web/package-lock.json && npm --prefix web install",

package/scripts/release-changelog.ts

@@ -0,0 +1,32 @@
+// Runs as npm's `version` lifecycle hook (see package.json): at that point
+// package.json already carries the new version, and files staged here are
+// included in the release commit that `npm version` then creates and tags.
+import { readFileSync, writeFileSync } from "node:fs";
+
+const { version } = JSON.parse(readFileSync("package.json", "utf8"));
+const path = "CHANGELOG.md";
+const text = readFileSync(path, "utf8");
+
+const header = text.match(/^## Unreleased[ \t]*$/m);
+if (!header || header.index === undefined) {
+  console.error("CHANGELOG.md: no '## Unreleased' section — add one before releasing.");
+  process.exit(1);
+}
+
+const escaped = version.replace(/[.]/g, "\\.");
+if (new RegExp(`^## ${escaped}([^0-9]|$)`, "m").test(text)) {
+  console.error(`CHANGELOG.md: a '## ${version}' section already exists.`);
+  process.exit(1);
+}
+
+const afterHeader = text.slice(header.index + header[0].length);
+const nextSection = afterHeader.search(/^## /m);
+const unreleasedBody = nextSection === -1 ? afterHeader : afterHeader.slice(0, nextSection);
+if (!/^\s*[-*] /m.test(unreleasedBody)) {
+  console.error(`CHANGELOG.md: '## Unreleased' has no entries — nothing to release as ${version}.`);
+  process.exit(1);
+}
+
+const date = new Date().toISOString().slice(0, 10);
+writeFileSync(path, text.replace(header[0], `## Unreleased\n\n## ${version} — ${date}`));
+console.log(`CHANGELOG.md: cut Unreleased into '## ${version} — ${date}'.`);