diff --git a/CHANGELOG.md b/CHANGELOG.md index 906474f..c73ad77 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,52 +2,71 @@ ## Unreleased -### Features and behavior changes +## 0.3.0 — 2026-10-04 + +### 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. + tools are not inherited + ([#41](https://github.com/Epsirom/braid/pull/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. + force-added files remain tracked + ([#41](https://github.com/Epsirom/braid/pull/41)) — @Epsirom. -These changes require the next minor release under the compatibility policy. -See [migration guidance](docs/compatibility.md#upcoming-workspace-capability-changes) -for callers relying on shell-free workers or preservation of ignored outputs. +See the [0.2 → 0.3 migration guide](docs/compatibility.md#migrating-from-02-to-03) +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. + strategy instead of a bare cherry-pick + ([#42](https://github.com/Epsirom/braid/pull/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. + and explain how to declare feedback cycles + ([#42](https://github.com/Epsirom/braid/pull/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. + replies echo accepted graph types and policies + ([#42](https://github.com/Epsirom/braid/pull/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. + foreground task. Clarify that pause reminders need a current-state check + ([#42](https://github.com/Epsirom/braid/pull/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. + when a definition problem recurs + ([#42](https://github.com/Epsirom/braid/pull/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. + revision. Preserve this rendering for older saved Pi sessions + ([#42](https://github.com/Epsirom/braid/pull/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. + `piUsage` in exported final results + ([#42](https://github.com/Epsirom/braid/pull/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. + validation now names feedback targets and edges that bypass the loop entry + ([#42](https://github.com/Epsirom/braid/pull/42)) — @Epsirom. + +### New Contributors + +No first-time human contributors in this release. + +[Full comparison](https://github.com/Epsirom/braid/compare/v0.2.1...v0.3.0). ## 0.2.1 — 2026-10-04 diff --git a/README.md b/README.md index a650df0..36b1d85 100644 --- a/README.md +++ b/README.md @@ -11,20 +11,38 @@ checkpoints; explicit `integrate` nodes apply selected work to the source checko [![npm Pi](https://img.shields.io/npm/v/%40chrok%2Fpi-braid?label=%40chrok%2Fpi-braid)](https://www.npmjs.com/package/@chrok/pi-braid) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) -**0.2 API:** Experimental, Node.js 22+, ESM. The framework-agnostic core +**0.3 API:** Experimental, Node.js 22+, ESM. The framework-agnostic core has no runtime dependencies; the OpenAI-compatible runner and Pi extension are optional integrations. The npm badges show published versions; see [GitHub releases](https://github.com/Epsirom/braid/releases) for release notes. -Read the [0.1 → 0.2 migration guide](docs/compatibility.md#migrating-from-01-to-02) -before upgrading. For the previous API, use the -[0.1.3 documentation](https://github.com/Epsirom/braid/tree/v0.1.3). +Read the [0.2 → 0.3 migration guide](docs/compatibility.md#migrating-from-02-to-03) +before upgrading; users coming from 0.1 also need the +[0.1 → 0.2 guide](docs/compatibility.md#migrating-from-01-to-02). +For the previous release, use the +[0.2.1 documentation](https://github.com/Epsirom/braid/tree/v0.2.1). | Package | Purpose | | --- | --- | | [@chrok/braid](https://www.npmjs.com/package/@chrok/braid) | Core runtime and optional OpenAI-compatible runner | | [@chrok/pi-braid](https://www.npmjs.com/package/@chrok/pi-braid) | Pi background jobs, execution controls, reminders, and live flow panel; installs the matching core dependency | -## What changed in 0.2? +## What changed in 0.3? + +- **Shell tools in writable Pi nodes.** Workers can install dependencies, build, + test, and repair in their assigned workspaces. Read-only nodes remain shell-free; + worktrees use host permissions and are not security sandboxes. +- **Git-aware checkpoints.** Tracked changes and non-ignored new files are + checkpointed. Keep artifacts needed by successors in non-ignored or deliberately + tracked paths; ignored dependencies and build outputs are no longer preserved. +- **Pi reminders between steps.** Completion and pause reminders arrive after + the current response and tool batch, before the next model step. +- **Clearer errors and status.** Invalid graphs show actionable errors; focused + reads show the selected execution's output/error and current control state. + Full status exports retain snapshots and failed-worker usage. + +See the [changelog](CHANGELOG.md#030--2026-10-04) for all fixes and credits. + +## Execution-control foundation from 0.2 - **Editable graphs, captured executions.** `startBraid` exposes revision-checked updates and pause/resume; `executionId` identifies a particular invocation, diff --git a/ROADMAP.md b/ROADMAP.md index d5e8b52..78b135b 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -6,12 +6,25 @@ and thin host adapters. This is a direction for discussion, not a delivery sched ## Release status -The 0.2 execution-control foundation is implemented. Source availability and npm -availability are separate milestones. Check +The 0.3 workspace and Pi reliability changes are implemented on top of the 0.2 +execution-control foundation. Source availability and npm availability are +separate milestones. Check [GitHub releases](https://github.com/Epsirom/braid/releases), [@chrok/braid](https://www.npmjs.com/package/@chrok/braid), and [@chrok/pi-braid](https://www.npmjs.com/package/@chrok/pi-braid) for published versions. +## 0.3 implemented changes + +- [x] Shell tools for writable Pi nodes, with cancellation and checkpoint write + barriers; keep read-only nodes shell-free. +- [x] Git-aware checkpoints that preserve tracked changes and non-ignored files. +- [x] Pi completion/pause reminders between model steps, with actionable graph + errors and complete focused status reads and exports. +- [x] Cumulative merge-source baselines and atomic update/retry guidance. + +Read the [0.2 → 0.3 migration guide](docs/compatibility.md#migrating-from-02-to-03) +for workspace capabilities and artifact preservation. + ## 0.2 implemented foundation - [x] Separate editable node definitions from captured execution instances, @@ -41,9 +54,10 @@ provenance, and clean installation before marking publication complete. - Exercise real edit → review → refine → integrate tasks and use the results to improve migration examples, update-conflict diagnostics, and recovery guidance. -- Refresh scheduler measurements for 0.2 before optimizing data structures. - Include execution history, updates, and loops; measure Git workspace costs - separately. The [checked-in benchmark](docs/benchmark.md) is a 0.1 baseline. +- Refresh scheduler measurements for the current execution model before + optimizing data structures. Include execution history, updates, and loops; + measure Git workspace costs separately. The [checked-in benchmark](docs/benchmark.md) + is a 0.1 baseline. - Explore explicit retention and cleanup policies for execution history, Git recovery refs, and Pi temporary result files without breaking result retrieval, reusable checkpoints, or usage accounting. @@ -59,7 +73,7 @@ provenance, and clean installation before marking publication complete. consumption, package builds, and the complete Node/platform matrix. Keep Node declarations on 22.x while Node 22 remains the minimum supported runtime. -## Scope after 0.2 +## Scope after 0.3 The original fixed-DAG-only boundary no longer applies. Bounded loops, live graph changes, parent-controlled pause/resume, and execution history are part of diff --git a/docs/compatibility.md b/docs/compatibility.md index a7952a3..d001a47 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -6,7 +6,7 @@ | Pi package | Node.js 22.19+, Pi 1.0.1 is the pinned validation target | | CI | Core minimum Node 22.0; both packages on Node 22.19 and 24 on Linux, macOS, Windows | | OpenAI-compatible runner | Chat Completions text and function-tool calls; decisions and merge/integrate nodes require tool calling | -| Browsers / CommonJS | No supported browser build or CommonJS entry point in 0.2 | +| Browsers / CommonJS | No supported browser build or CommonJS entry point in 0.3 | The CI matrix describes configured checks; see actual workflow results for each commit. Offline HTTP fixtures validate the adapter contract. They do not prove @@ -19,10 +19,10 @@ The wildcard is a loader/distribution convention, **not a claim that every Pi version works**. Test the whole Pi suite before updating the supported target. The offline host compatibility test loads the extension into a real Pi session with an in-memory model provider. It checks worker prompt/tool normalization and -exactly one automatic continuation per node/job reminder delivered during -`agent_settled`, including retrieval of a node output while its job still runs. -This covers the Pi 0.86/0.87 transcript and settling changes without provider -credentials or network model calls. Version 0.1.0 was originally validated with +reminder delivery between model steps after the current tool batch, idle +continuation, and acknowledgement, including retrieval of a node output while +its job still runs. These fixtures run without provider credentials or network +model calls. Version 0.1.0 was originally validated with Pi 0.85.1; the current checkout's pinned validation target is 1.0.1. The Pi npm package declares an exact dependency on the matching `@chrok/braid` release. npm installs the core automatically; Pi does not bundle another copy of @@ -32,7 +32,7 @@ Git must be installed for workspace execution inside a Git checkout. Non-Git text-only runs do not require Git workspace management. ## Migrating from 0.1 to 0.2 -This release deliberately changes the execution and workspace contracts: +Version 0.2 deliberately changed the execution and workspace contracts: - Replace old source-checkout `merge` nodes with `integrate`. The new `merge` combines inputs in a fresh isolated worktree. @@ -71,9 +71,9 @@ separate gate reminder; when both preferences are enabled it supplies the single completion reminder for that instance. Cancellation still sends failure reminders for opted-in running instances. -## Upcoming workspace capability changes +## Migrating from 0.2 to 0.3 -The Unreleased changes target the next minor release; they are not part of 0.2.1: +Version 0.3 changes workspace capabilities and checkpoint contents: - Writable Pi nodes now receive `bash` and, on Windows, `powershell`, allowing dependency installation, builds, and tests within a node. If a graph relies on @@ -94,7 +94,11 @@ The Unreleased changes target the next minor release; they are not part of 0.2.1 one foreground command and clean it up before returning. Detached daemons and external services are not contained by this lifecycle. -No graph field, result shape, or event schema changes are required. +No graph field, result shape, or event schema migration is required. Pi now +delivers completion/pause reminders after the current assistant response and +tool batch, before the next model step, rather than waiting for the entire +foreground task to finish. Fetch current status before updating or resuming a +paused execution because the reminder describes the state when it was queued. ## Versioning diff --git a/integrations/pi/README.md b/integrations/pi/README.md index dd8713d..eaa11e4 100644 --- a/integrations/pi/README.md +++ b/integrations/pi/README.md @@ -5,11 +5,15 @@ This optional Pi extension runs Braid agent graphs as background jobs with bounded loops, live updates, pause/resume, and a live flow panel. -**0.2 API:** The npm badge shows the published version; see +**0.3 API:** The npm badge shows the published version; see [GitHub releases](https://github.com/Epsirom/braid/releases) for release notes. -Review the [migration guide](https://github.com/Epsirom/braid/blob/v0.2.0/docs/compatibility.md#migrating-from-01-to-02) -before upgrading an existing graph. For the previous API, use the -[0.1.3 guide](https://github.com/Epsirom/braid/blob/v0.1.3/integrations/pi/README.md). +Review the [0.2 → 0.3 migration guide](https://github.com/Epsirom/braid/blob/v0.3.0/docs/compatibility.md#migrating-from-02-to-03) +before upgrading: writable nodes now have shell tools, checkpoints exclude +untracked ignored outputs, and reminders can interrupt work between model steps. +Users coming from 0.1 also need the +[0.1 → 0.2 guide](https://github.com/Epsirom/braid/blob/v0.3.0/docs/compatibility.md#migrating-from-01-to-02). +For the previous release, use the +[0.2.1 guide](https://github.com/Epsirom/braid/blob/v0.2.1/integrations/pi/README.md). It registers: diff --git a/integrations/pi/package.json b/integrations/pi/package.json index a2bdd78..0f06259 100644 --- a/integrations/pi/package.json +++ b/integrations/pi/package.json @@ -1,12 +1,12 @@ { "name": "@chrok/pi-braid", - "version": "0.2.1", + "version": "0.3.0", "license": "MIT", "description": "Pi extension for Braid: background agent graphs, bounded loops, live updates, and a flow panel", "type": "module", "dependencies": { "grok-mermaid": "^0.2.2", - "@chrok/braid": "0.2.1" + "@chrok/braid": "0.3.0" }, "peerDependencies": { "@earendil-works/pi-ai": "*", diff --git a/package-lock.json b/package-lock.json index c33c616..434e96a 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@chrok/braid", - "version": "0.2.1", + "version": "0.3.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@chrok/braid", - "version": "0.2.1", + "version": "0.3.0", "license": "MIT", "workspaces": [ "integrations/pi" @@ -23,10 +23,10 @@ }, "integrations/pi": { "name": "@chrok/pi-braid", - "version": "0.2.1", + "version": "0.3.0", "license": "MIT", "dependencies": { - "@chrok/braid": "0.2.1", + "@chrok/braid": "0.3.0", "grok-mermaid": "^0.2.2" }, "devDependencies": { diff --git a/package.json b/package.json index ea258f9..eea2534 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@chrok/braid", - "version": "0.2.1", + "version": "0.3.0", "license": "MIT", "description": "TypeScript runtime for LLM agent graphs with bounded loops, live updates, and isolated Git worktrees", "type": "module",