Braid v0.3.1

Braid 0.3.1 releases matching versions of @chrok/braid, @chrok/pi-braid, and the new @chrok/dsh-braid integration. This release preserves the existing core and Pi contracts.

Tagged on 2026-10-04; published on 2026-10-05 (Asia/Shanghai).

Features

• Add the @chrok/dsh-braid DeepSeek Harness plugin with background graphs,
  isolated workers, revision-checked updates, pause/resume, cancellation, and
  completion reminders through DSH's native model, tool, and job services
  (#45) — @Epsirom.
• Add a native DSH Web panel with live graphs, execution history, paged outputs,
  usage, and controls. Braid tool cards preserve recorded operation summaries
  and open the corresponding job, node, or execution in the live panel
  (#45) — @Epsirom.

DSH 0.2.0-rc.2 and Node.js 22.19+ are the tested integration baseline. DSH is
in developer preview, so its host peer dependencies are pinned. This release
preserves the existing core and Pi contracts; no migration from 0.3.0 is required.
Pi 1.0.1 remains the pinned Pi validation target.

Documentation

• Introduce Braid with a parallel code-review example and clear installation
  paths, moving release history, migration links, and source setup later in the README
  (#44) — @Epsirom.

New Contributors

No first-time human contributors in this release.

Full comparison.

Install DSH support with dsh plugin --profile web add @chrok/dsh-braid; restart the profile afterward. See the DSH guide.

Braid v0.3.0

Braid 0.3.0 releases matching versions of @chrok/braid and @chrok/pi-braid. Pi 1.0.1 remains the pinned validation target.

Features and breaking changes

• Give writable Pi nodes built-in shell tools for dependency installation, builds,
  tests, and repair. Shell calls participate in cancellation and the workspace
  write barrier before checkpointing; prompts describe workspace boundaries and
  shared resources. Read-only nodes still have no shell, and parent extension/MCP
  tools are not inherited
  (#41) — @Epsirom.
• Checkpoint tracked changes and non-ignored new files using normal Git staging
  semantics. Ignored dependencies, caches, and build outputs are no longer
  automatically archived or passed to successors; already tracked and deliberately
  force-added files remain tracked
  (#41) — @Epsirom.

See the 0.2 → 0.3 migration guide
before upgrading if you rely on shell-free workers or preservation of ignored
outputs. Use read-only nodes or a custom runner to restrict worker capabilities,
and keep successor artifacts in non-ignored or deliberately tracked paths.

Fixes

• Include changes.baseCommit in merge-source previews and explain cumulative
  diffs versus invocation snapshots. Read-only review checkpoints can otherwise
  suggest an empty patch; multi-parent checkpoints also need an explicit
  strategy instead of a bare cherry-pick
  (#42) — @Epsirom.
• Display Pi submission and status errors even when the host supplies empty
  result details; failed graph definitions no longer appear as background jobs
  with an undefined ID/status. Validation errors identify offending nodes/edges
  and explain how to declare feedback cycles
  (#42) — @Epsirom.
• Clarify Pi node requirements, loop/template parameters, and revision controls
  while retaining a flat provider-facing node schema with type-specific core
  validation. Restrict historical execution pins to updates. Submission/update
  replies echo accepted graph types and policies
  (#42) — @Epsirom.
• Deliver Pi completion/pause reminders at the next model step using steering,
  after the current tool batch, instead of queuing follow-ups behind the entire
  foreground task. Clarify that pause reminders need a current-state check
  (#42) — @Epsirom.
• Explain atomic update failures and retrying complete patches: new nodes and
  their edges/loops must be submitted together to avoid starting disconnected
  roots while another execution is paused. Discourage repeated replacement jobs
  when a definition problem recurs
  (#42) — @Epsirom.
• Show the requested execution's output/error in focused Pi status reads and
  include the current revision and paused IDs, separately from its captured
  revision. Preserve this rendering for older saved Pi sessions
  (#42) — @Epsirom.
• Keep errors, control fields, and Pi usage ahead of large status payloads;
  save complete running snapshots and include failed-worker provider usage as
  piUsage in exported final results
  (#42) — @Epsirom.
• Update live status on graph completion/failure and clear resumable pause IDs
  when finalizing, while retaining pause history in the event log. Loop
  validation now names feedback targets and edges that bypass the loop entry
  (#42) — @Epsirom.

New Contributors

No first-time human contributors in this release.

Full comparison.

Braid v0.2.1

Braid 0.2.1 is a maintenance release that validates the Pi integration against Pi 1.0.1 and fixes the repository's vulnerable development dependency tree. There are no Braid API or runtime behavior changes from 0.2.0.

Maintenance

• Upgrade the Pi development dependencies together to 1.0.1 and regenerate the workspace lockfile. Pi's installed minimatch 10.2.6 now resolves the patched brace-expansion 5.0.12; Pi 1.0.1 also removes its published shrinkwrap. Update compatibility fixtures and documentation for the new validation target (#38) — @Epsirom.
• Add a dedicated dependency-security workflow and npm run audit:dependencies, including development, optional, and peer dependencies. Findings and scanner failures both fail the check, with separate diagnostics and regression coverage (#38) — @Epsirom.

Compatibility and installation

Both packages use 0.2.1, and the Pi package installs the exact matching core dependency. Core requires Node.js 22+; the Pi integration requires Node.js 22.19+ and is tested against Pi 1.0.1.

npm install @chrok/braid@0.2.1
pi install npm:@chrok/pi-braid@0.2.1

Updating Braid does not upgrade a separately installed Pi host. Update that host to Pi 1.0.1 and inspect its own dependency tree. Existing Braid source checkouts need the new lockfile followed by npm ci.

No migration is needed from Braid 0.2.0. For upgrades from 0.1, follow the 0.1 → 0.2 migration guide.

New Contributors

No first-time human contributors in this release.

Validation

222 core tests, 66 Pi tests (including real Pi host sessions with an in-memory provider), both type checks, offline examples, isolated consumer package checks, and package-content inspections. The full dependency audit reports zero known vulnerabilities. The Linux/macOS/Windows CI matrix on Node 22/24, the core-minimum check, and CodeQL pass before release. Paid live provider scenarios were not rerun.

See the changelog and full comparison.

Braid v0.2.0

Braid 0.2.0 adds bounded refinement loops, live graph updates, reusable prompt templates, and intermediate completion reminders. This is a breaking release; review the migration guidance before upgrading existing graphs.

Features

• Bounded loops and live execution control. Separate editable node definitions from captured execution instances. Use startBraid for revision-checked graph updates, pauseAfter gates, and atomic update/resume; loops receive finite iteration limits and fresh worktrees per visit. Pi adds braid_update, braid_resume, execution-specific result retrieval, iteration-aware reminders, and live topology updates (#35) — @Epsirom.
• Graph-local prompt templates. Define shared promptTemplates once and reference them with explicit string variables. Core validates and expands literal {{name}} placeholders before execution; Pi accepts the same compact input and runners continue to receive rendered strings (#33) — @Epsirom.
• Opt-in node completion reminders. Set notifyOnCompletion: true for selected intermediate outputs or failures. Pi acknowledges delivery, retries dropped reminders, and exposes full results through braid_status({jobId, nodeId}) or exact executionId retrieval. Skipped nodes stay silent and whole-job reminders remain enabled (#34, #35) — @Epsirom.

Breaking changes and migration

The execution/workspace changes below come from #35 — @Epsirom:

• Replace source-checkout merge nodes with integrate. The new merge combines inputs in a fresh isolated worktree. Add explicit integration nodes where a graph previously relied on automatic final integration.
• Treat nodeId as a definition identity and use executions[executionId] for historical instances. Workspace lookups and finish_merge dispositions now use execution IDs; source checkpoints remain reusable until cleanup.
• Read-only Git executions inspect isolated predecessor snapshots instead of the live source checkout.
• Failures are optional by default. Set requireSuccess: true where a failure must abort siblings and fail the job after writes and cleanup drain.
• Handle repeated execution events and new revision/loop/gate events. Set finite loop limits and maxExecutions (default 1000); deadlines and execution budgets span live updates and paused gates.

Full 0.1 → 0.2 migration guide · Execution-control contract.

Maintenance

• Refresh package/repository metadata, discovery keywords, documentation, and roadmap for the 0.2 execution contract (#36) — @Epsirom.
• Update @types/node from 22.20.2 to 22.20.4 (#17) — @dependabot[bot].
• Standardize PR/author credits and first-time contributor acknowledgements, backfill historical release notes, and prepare 0.2.0 documentation (#39) — @Epsirom.

New Contributors

No first-time human contributors in this release. Thanks to everyone who contributed to earlier releases as well.

Installation and validation

Both packages use 0.2.0; Pi installs the exact matching core dependency. Core requires Node.js 22+; Pi requires Node.js 22.19+ and remains tested against Pi 0.87.1.

npm install @chrok/braid@0.2.0
pi install npm:@chrok/pi-braid@0.2.0

Validation: 218 core tests, 66 Pi tests, strict type checks, offline examples, isolated Pi-only installation/public imports/declarations/background execution, package-content inspections, CodeQL, and the Linux/macOS/Windows CI matrix on Node 22/24. Pi host compatibility tests use an in-memory provider; paid live provider scenarios were not rerun for this release.

See the changelog and full comparison.

Braid v0.1.3

Braid 0.1.3 adds per-node read-only workspaces and avoids unnecessary automatic merge agents for unchanged workspaces.

Features and fixes

• Set workspace: "read-only" on execute/decision nodes to inspect the live source directory with read-only and Git inspection tools, without snapshots, worktrees, or merge sources. Use workspace: "worktree" for implementation nodes. Existing defaults are preserved; explicit read-only metadata appears in results and events (#28) — @Epsirom.
• Skip automatic merging when all remaining workspaces match their snapshots, preserving analysis-only outputs and original node errors. Mixed runs include only changed sources in automatic merging; explicit merge nodes still run for unchanged sources (#27) — @Epsirom.
• Prevent Pi TUI crashes in narrow terminals by fitting the flowchart fallback message to the terminal width (#24) — @powerfooI (First-time contributor).

Maintenance

• Enable CodeQL scanning for fork pull requests (#25) — @Epsirom.
• Make timeout tests independent of workspace timing (#26) — @Epsirom.

New Contributors

• Thanks to @powerfooI for their first contribution in #24!

Both packages use version 0.1.3, and Pi installs the exact matching core dependency. Pi remains tested against 0.87.1 and requires Node 22.19+; core requires Node 22+.

npm install @chrok/braid@0.1.3
pi install npm:@chrok/pi-braid@0.1.3

Validation: 144 core/release tests, 50 Pi tests, offline examples, isolated Pi-only package installation, package contents inspections, CodeQL, and the Linux/macOS/Windows CI matrix on Node 22/24.

See the changelog and full comparison.

Braid v0.1.2

Braid 0.1.2 makes the Pi extension depend on @chrok/braid instead of embedding another copy of the core runtime. Installing the Pi extension automatically installs the exact matching core version.

Features and fixes

• Export shared adapter helpers from the existing @chrok/braid root entry point: formatBudgetReminder, gitToolDefinition, finishMergeToolDefinition, mergeInstructions, parseGitToolArguments, and parseFinishMergeArguments. No package or subpath export is added (#19) — @Epsirom.
• Compile and ship only Pi integration code; keep Git workspace implementation classes private (#19) — @Epsirom.

Build and release maintenance

• Use one npm workspace lockfile and a development-only local core link so unpublished versions can be tested together (#19) — @Epsirom.
• Verify Pi-only installation against an unpublished core tarball, including transitive dependency resolution, public imports, declarations, and a completed background job (#19) — @Epsirom.
• Publish core first and wait for its registry metadata and tarball to become available before publishing Pi (#19) — @Epsirom.

New Contributors

No first-time human contributors in this release.

Existing documented core APIs and Pi tools are unchanged. Pi remains tested against 0.87.1 and requires Node 22.19+.

npm install @chrok/braid@0.1.2
pi install npm:@chrok/pi-braid@0.1.2

Validation: 124 core/release tests, 47 Pi tests, isolated package installation, and the Linux/macOS/Windows CI matrix on Node 22/24.

See the changelog and full comparison.

Braid v0.1.1

Braid 0.1.1 fixes OpenAI-compatible base URL normalization and updates the tested Pi integration to Pi 0.87.1. Both npm packages release together; no API migration is required.

Features and fixes

• Trim trailing slashes in linear time, avoiding excessive regular-expression backtracking on long internal slash sequences (#14) — @Epsirom.
• Clarify Pi tool and context guidance for parallel implementation and merge nodes, including filesystem access within each node's assigned workspace (#15) — @Epsirom.

Maintenance

• Validate Pi 0.87.1 compatibility and update development dependencies and GitHub Actions (#16) — @Epsirom.
• Document repository governance, protected branches and tags, CodeQL checks, and immutable releases (#14) — @Epsirom.

New Contributors

No first-time human contributors in this release.

Install the core:

npm install @chrok/braid@0.1.1

Install the Pi extension (tested with Pi 0.87.1; Node 22.19+):

pi install npm:@chrok/pi-braid@0.1.1

See the changelog and full comparison.

Braid v0.1.0

Braid's first public release provides a small TypeScript DAG runtime for isolated model invocations, plus a Pi extension for background jobs and a live flow panel.

Features and fixes

• Core runtime with conditional routing, bounded concurrency, cancellation, and failure propagation (initial commit) — @Epsirom (First-time contributor).
• Git worktree isolation and agent-driven merge/discard lifecycle for node edits (#4) — @Epsirom.
• Pi background jobs, reminders, and a live flow panel (573a2a4); tools include braid, braid_status, and braid_cancel (#4). The extension bundles its compiled runtime (#5) — @Epsirom.
• Default Pi tool budgets to unlimited and remind workers of finite budgets (#3) — @Epsirom.

Packaging and maintenance

• Documented public ESM exports, clean npm packages, four offline examples, a rendered panel demo, and reproducible benchmarks (#5) — @Epsirom.
• Contribution/security policies, compatibility and resource-limit documentation, issue templates, and CI/release workflows (#5) — @Epsirom.

New Contributors

• Thanks to @Epsirom for starting Braid with the initial commit and contributing #3, #4, and #5.

Validation: 115 core tests and 51 Pi tests locally, clean tarball installation with public imports and TypeScript declarations, a complete installed Pi background job, and seven GitHub CI jobs covering Linux/macOS/Windows and Node 22/24. Live provider tests remain opt-in.

See the README for installation and the changelog for release details.

Install the core:

npm install @chrok/braid@0.1.0

Install the Pi extension (Pi 0.85.1, Node 22.19+):

pi install npm:@chrok/pi-braid@0.1.0

Published packages: @chrok/braid and @chrok/pi-braid.

Release history.