Skip to content

feat(tui): ship production Braid workspace #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
drewstone wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat(tui): ship production Braid workspace #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
64a758d
feat(tui): ship production Braid workspace
drewstone Aug 4, 2026
418cefb
fix(visuals): settle final capture frame
drewstone Aug 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
4 changes: 3 additions & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,17 @@
node_modules/
node_modules
dist/
.test-dist/
coverage/
.tmp/
.braid/
*.log
*.tgz
.env
.env.*
!.env.example
artifacts/verification/**/raw/
artifacts/verification/**/*.cast
artifacts/verification/**/*.ansi
artifacts/verification/**/*.gif
!artifacts/verification/w0/*.gif
artifacts/verification/**/*.mp4
48 changes: 42 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,18 @@ Provider packages own transport to CLI Bridge and Tangle.

## Status

The W0 vertical slice is implemented: one `braid` binary, one reducer, one JSONL control interface, and one real Pi terminal transcript and composer all drive `agent-runtime`.
The packed binary has deterministic keyboard and JSONL proof, but live CLI Bridge and Tangle connections are not implemented yet.
The contract is based on current source inspection of `agent-runtime`, `agent-interface`, `cli-bridge`, `agent-eval`, Pi, Kimi Code, OpenCode, and Hermes Agent on 2026-08-01.

![Braid terminal at 80×24](artifacts/verification/w0/80x24.png)
Braid's production CLI/TUI, encrypted local state, profile and connection setup, runtime dispatch, conversations, branches, graphs, interactions, and analysis commands are implemented.
The terminal and headless surfaces share one command registry, one view model, and one durable operation ledger.
The CLI Bridge path is implemented and was proven from a clean packed install on 2026-08-04 with Pi/GLM-5.2 and Codex through first-run setup, two-turn session continuity, normalized events, process restart, transcript recovery, and a post-restart turn.
The Tangle inference and sandbox paths are implemented against the current provider packages but still require protected live-deployment proof before they are advertised as release-complete.
`/ask`, `/analyze`, `/compare`, trace citations, and analysis promotion are implemented; the semantic evaluation command performs pilot, calibration, and release-case checks when a judge model is configured.
Generalized interaction responses remain capability-disabled because the installed runtime and providers do not expose a run-bound response operation.
The deterministic `MemoryJournal` remains fixture-only; production startup fails closed if the pinned encrypted SQLite binding or credential facility is unavailable.
The storage binding is pinned to `better-sqlite3-multiple-ciphers@12.11.1`, operating-system credentials use `@napi-rs/keyring@1.3.0`, and raw database, WAL, shared-memory, backup, wrong-key, restore-recovery, two-process admission, and forced-kill checks run against the native implementations.
Tangle, supervisor-control, full live-analysis, multi-platform installation, and signed release evidence remain required before the complete release contract is satisfied.
The contract is based on current source inspection of `agent-runtime`, `agent-interface`, `cli-bridge`, `agent-eval`, Pi, Kimi Code, OpenCode, and Hermes Agent through 2026-08-04.

![Braid terminal at 80×24](artifacts/verification/w6/80x24.png)

Run the deterministic slice locally:

Expand All @@ -26,7 +33,35 @@ pnpm run build
node dist/bin/braid.js --fixture deterministic
```

Run `pnpm check`, `pnpm run test:package`, and `pnpm run capture:w0` to reproduce the current checks and terminal captures.
Run the checks with the stable command map below.
Commands marked unavailable fail with exit code 2 and a plain explanation; they do not substitute a narrower test and do not create a release claim.

| Check | Command | Behavior |
| --- | --- | --- |
| repository | `pnpm check` | Runs local format, lint, types, boundaries, dependency/license metadata, deterministic tests, and the release manifest check |
| unit | `pnpm test:unit` | Runs the local unit suite |
| contract | `pnpm test:contract` | Runs the local contract suite |
| coordination | `pnpm test:coordination` | Runs durable effect admission and serialization checks |
| rpc | `pnpm test:rpc` | Runs the JSONL protocol suite |
| rpc (packed) | `pnpm test:rpc:packed` | Runs the packed JSONL protocol suite |
| virtual-terminal | `pnpm test:virtual-terminal` | Runs virtual-terminal state, keyboard, and layout checks |
| pty | `pnpm test:pty` | Runs packed real-terminal checks |
| storage | `pnpm test:storage` | Runs encrypted SQLite journal, projection, and retention checks |
| crash | `pnpm test:crash` | Runs forced-kill, restore-recovery, and two-process admission checks |
| security | `pnpm test:security` | Runs redaction, credential-boundary, and dependency-boundary checks |
| performance | `pnpm test:performance` | Runs the reducer, coordination, and storage performance checks |
| live | `pnpm test:live` | Unavailable without protected live credentials and evidence |
| live-bridge | `pnpm test:live:bridge` | Runs the opt-in packed CLI Bridge and runner flow with `BRAID_LIVE_BRIDGE=1` |
| live-tangle | `pnpm test:live:tangle` | Unavailable without protected live credentials and evidence |
| live-supervisor | `pnpm test:live:supervisor` | Unavailable without protected live credentials and evidence |
| live-analysis | `pnpm test:live:analysis` | Unavailable without protected live credentials and evidence |
| eval | `pnpm test:eval` | Runs pilot, judge calibration, and semantic release cases against `BRAID_EVAL_MODEL` |
| install | `pnpm test:install` | Runs packed install, storage, and keyboard/RPC proof |
| capture | `pnpm test:capture` | Captures the baseline terminal artifacts from the packed binary |
| visual | `pnpm capture:visual` | Captures the required W6 state artifacts from the packed binary |
| release | `pnpm check:release` | Checks the release manifest and evidence set |
| verify:release | `pnpm verify:release` | Runs only in an isolated clean tracked checkout with external signing key and complete evidence |

The complete implementation goal remains every required check in [the delivery plan](docs/09-delivery-plan.md) and [the verification plan](docs/08-verification.md), including real local and cloud runs.

## The central decision
Expand Down Expand Up @@ -68,6 +103,7 @@ That boundary gives Braid a polished interface quickly without creating a second
| [Renderer decision](docs/decisions/001-pi-tui-renderer.md) | Why Braid depends on Pi TUI instead of cloning a whole app |
| [Runtime boundary decision](docs/decisions/002-runtime-boundary.md) | Why execution and interaction control stay upstream |
| [Persistence decision](docs/decisions/003-local-event-journal.md) | What Braid stores and which system remains authoritative |
| [Encrypted storage decision](docs/decisions/005-encrypted-sqlite-and-credential-boundaries.md) | SQLite cipher, content keys, credential facilities, and headless key boundaries |

The ranked source-reuse hypothesis is recorded in [`.agent/hypotheses/2026-08-01-terminal-ui-base.md`](.agent/hypotheses/2026-08-01-terminal-ui-base.md).

Expand Down
172 changes: 172 additions & 0 deletions THIRD_PARTY_LICENSES.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,14 @@
"license": "MIT",
"name": "@hono/node-server"
},
{
"license": "MIT",
"name": "@napi-rs/keyring-linux-x64-gnu"
},
{
"license": "MIT",
"name": "@napi-rs/keyring"
},
{
"license": "MIT",
"name": "@noble/hashes"
Expand All @@ -37,10 +45,22 @@
"license": "Unknown",
"name": "@tangle-network/agent-profile-materialize"
},
{
"license": "MIT",
"name": "@tangle-network/agent-provider-cli-bridge"
},
{
"license": "MIT",
"name": "@tangle-network/agent-provider-tangle"
},
{
"license": "MIT",
"name": "@tangle-network/agent-runtime"
},
{
"license": "MIT",
"name": "@tangle-network/agent-trace-contract"
},
{
"license": "MIT",
"name": "@tangle-network/sandbox"
Expand Down Expand Up @@ -69,10 +89,30 @@
"license": "Apache-2.0",
"name": "bare-url"
},
{
"license": "MIT",
"name": "base64-js"
},
{
"license": "MIT",
"name": "better-sqlite3-multiple-ciphers"
},
{
"license": "CC0-1.0",
"name": "binary-search"
},
{
"license": "MIT",
"name": "bindings"
},
{
"license": "MIT",
"name": "bl"
},
{
"license": "MIT",
"name": "buffer"
},
{
"license": "MIT",
"name": "chalk"
Expand All @@ -81,10 +121,34 @@
"license": "MIT",
"name": "cheminfo-types"
},
{
"license": "ISC",
"name": "chownr"
},
{
"license": "MIT",
"name": "decompress-response"
},
{
"license": "MIT",
"name": "deep-extend"
},
{
"license": "Apache-2.0",
"name": "detect-libc"
},
{
"license": "MIT",
"name": "end-of-stream"
},
{
"license": "Apache-2.0",
"name": "events-universal"
},
{
"license": "(MIT OR WTFPL)",
"name": "expand-template"
},
{
"license": "MIT",
"name": "fast-fifo"
Expand All @@ -93,10 +157,22 @@
"license": "MIT",
"name": "fft.js"
},
{
"license": "MIT",
"name": "file-uri-to-path"
},
{
"license": "MIT",
"name": "fs-constants"
},
{
"license": "MIT",
"name": "get-east-asian-width"
},
{
"license": "MIT",
"name": "github-from-package"
},
{
"license": "ISC",
"name": "graceful-fs"
Expand All @@ -105,6 +181,18 @@
"license": "MIT",
"name": "hono"
},
{
"license": "BSD-3-Clause",
"name": "ieee754"
},
{
"license": "ISC",
"name": "inherits"
},
{
"license": "ISC",
"name": "ini"
},
{
"license": "MIT",
"name": "is-any-array"
Expand All @@ -117,6 +205,18 @@
"license": "MIT",
"name": "marked"
},
{
"license": "MIT",
"name": "mimic-response"
},
{
"license": "MIT",
"name": "minimist"
},
{
"license": "MIT",
"name": "mkdirp-classic"
},
{
"license": "MIT",
"name": "ml-array-max"
Expand All @@ -141,26 +241,70 @@
"license": "MIT",
"name": "ml-xsadd"
},
{
"license": "MIT",
"name": "napi-build-utils"
},
{
"license": "MIT",
"name": "node-abi"
},
{
"license": "ISC",
"name": "once"
},
{
"license": "MIT",
"name": "openapi3-ts"
},
{
"license": "MIT",
"name": "prebuild-install"
},
{
"license": "MIT",
"name": "proper-lockfile"
},
{
"license": "MIT",
"name": "pump"
},
{
"license": "(BSD-2-Clause OR MIT OR Apache-2.0)",
"name": "rc"
},
{
"license": "MIT",
"name": "re2js"
},
{
"license": "MIT",
"name": "readable-stream"
},
{
"license": "MIT",
"name": "retry"
},
{
"license": "MIT",
"name": "safe-buffer"
},
{
"license": "ISC",
"name": "semver"
},
{
"license": "ISC",
"name": "signal-exit"
},
{
"license": "MIT",
"name": "simple-concat"
},
{
"license": "MIT",
"name": "simple-get"
},
{
"license": "CC-BY-3.0",
"name": "spdx-exceptions"
Expand All @@ -177,6 +321,18 @@
"license": "MIT",
"name": "streamx"
},
{
"license": "MIT",
"name": "string_decoder"
},
{
"license": "MIT",
"name": "strip-json-comments"
},
{
"license": "MIT",
"name": "tar-fs"
},
{
"license": "MIT",
"name": "tar-stream"
Expand All @@ -189,6 +345,22 @@
"license": "Apache-2.0",
"name": "text-decoder"
},
{
"license": "Apache-2.0",
"name": "tunnel-agent"
},
{
"license": "MIT",
"name": "undici"
},
{
"license": "MIT",
"name": "util-deprecate"
},
{
"license": "ISC",
"name": "wrappy"
},
{
"license": "ISC",
"name": "yaml"
Expand Down
10 changes: 9 additions & 1 deletion THIRD_PARTY_NOTICES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,13 @@ The implementation is expected to depend on and adapt behavior from the followin

| Project | Planned use | Source inspected | License |
| --- | --- | --- | --- |
| [`@earendil-works/pi-tui`](https://github.com/earendil-works/pi/tree/master/packages/tui) | Runtime dependency for rendering, layout, input, and overlays; planned test-only adaptation of `test/virtual-terminal.ts` if no public testing export exists | `earendil-works/pi@a6f7317dfca61e357aee65faafe012a1be6c3734` | MIT |
| [`@earendil-works/pi-tui`](https://github.com/earendil-works/pi/tree/master/packages/tui) | Runtime dependency for rendering, layout, input, and overlays; test-only adaptation of `test/virtual-terminal.ts` | `earendil-works/pi@a6f7317dfca61e357aee65faafe012a1be6c3734` | MIT |
| [Pi coding agent](https://github.com/earendil-works/pi/tree/master/packages/coding-agent) | Behavioral reference and possible selective adaptation of selectors, transcript components, and session-tree presentation | `earendil-works/pi@a6f7317dfca61e357aee65faafe012a1be6c3734` | MIT |
| [Kimi Code](https://github.com/MoonshotAI/kimi-code/tree/main/apps/kimi-code/src/tui) | Behavioral reference and possible selective adaptation of approval, question, queue, and modal coordination components | `MoonshotAI/kimi-code@e22479a62eed9c3b78a67b313f4332c2c0ba9670` | MIT |
| [OpenCode](https://github.com/anomalyco/opencode) | Architecture and interaction reference only | `anomalyco/opencode@32f278b48f1a495611165d8a9f1ace0b512933e2` | MIT |
| [Hermes Agent](https://github.com/NousResearch/hermes-agent/tree/main/ui-tui) | Client/runtime separation and workflow reference only | `NousResearch/hermes-agent@f88ed6c71768cdc7ea3bfa8cf62d16654792fd2a` | MIT |
| [`better-sqlite3-multiple-ciphers`](https://github.com/m4heshd/better-sqlite3-multiple-ciphers) | Pinned production SQLite binding with SQLCipher-compatible encryption | `better-sqlite3-multiple-ciphers@12.11.1` | MIT |
| [`@napi-rs/keyring`](https://github.com/Brooooooklyn/keyring-node) | Native macOS Keychain, Linux Secret Service, and Windows Credential Manager access without passing secrets through command arguments | `@napi-rs/keyring@1.3.0` | MIT |

## Attribution rule

Expand All @@ -24,4 +26,10 @@ The original copyright and license notice must remain with every substantial cop

A dependency declared in `package.json` does not require a file-level source header, but its license must remain represented in the generated release license inventory.

W5 adds the pinned `better-sqlite3-multiple-ciphers@12.11.1` and `@napi-rs/keyring@1.3.0` production dependencies and no new copied source.

Its coordinator, storage port, credential port, and release scripts use Braid code and Node.js platform APIs around that binding.

The generated `THIRD_PARTY_LICENSES.json` inventory must include both native bindings and all of their transitive production dependencies.

The release process must fail if a copied-source header has no matching notice row or if a production dependency has an unknown or disallowed license.
Loading