diff --git a/CHANGELOG.md b/CHANGELOG.md index 90f8566..e5de8ac 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,19 +2,35 @@ ## Unreleased +## 0.3.1 — 2026-10-04 + ### 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. + completion reminders through DSH's native model, tool, and job services + ([#45](https://github.com/Epsirom/braid/pull/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. + and open the corresponding job, node, or execution in the live panel + ([#45](https://github.com/Epsirom/braid/pull/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. + paths, moving release history, migration links, and source setup later in the README + ([#44](https://github.com/Epsirom/braid/pull/44)) — @Epsirom. + +### New Contributors + +No first-time human contributors in this release. + +[Full comparison](https://github.com/Epsirom/braid/compare/v0.3.0...v0.3.1). ## 0.3.0 — 2026-10-04 diff --git a/README.md b/README.md index 1834542..3c418a1 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@ Use it as a TypeScript/JavaScript library or as a plugin for Pi or DeepSeek Harn [![CI](https://github.com/Epsirom/braid/actions/workflows/ci.yml/badge.svg)](https://github.com/Epsirom/braid/actions/workflows/ci.yml) [![npm core](https://img.shields.io/npm/v/%40chrok%2Fbraid?label=%40chrok%2Fbraid)](https://www.npmjs.com/package/@chrok/braid) [![npm Pi](https://img.shields.io/npm/v/%40chrok%2Fpi-braid?label=%40chrok%2Fpi-braid)](https://www.npmjs.com/package/@chrok/pi-braid) +[![npm DSH](https://img.shields.io/npm/v/%40chrok%2Fdsh-braid?label=%40chrok%2Fdsh-braid)](https://www.npmjs.com/package/@chrok/dsh-braid) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) ## Why Braid? @@ -37,7 +38,7 @@ and [execution control](docs/execution-control.md) when you need those features. | --- | --- | | In your own application | [Install `@chrok/braid`](#install-in-your-application) and supply a model runner | | In Pi | [Install `@chrok/pi-braid`](#install-in-pi) to run agents in the background and inspect them in a live panel | -| In DeepSeek Harness | [Install `@chrok/dsh-braid` from source](integrations/dsh/README.md#install) for background agents and a native Web graph panel | +| In DeepSeek Harness | [Install `@chrok/dsh-braid`](#install-in-deepseek-harness) for background agents and a native Web graph panel | ## Install in your application @@ -98,6 +99,21 @@ This snapshot uses the actual panel renderer and fake responses. See the [Pi guide](integrations/pi/README.md) for background jobs, cancellation, and local installation, and [compatibility](docs/compatibility.md) for the tested versions. +## Install in DeepSeek Harness + +Requires Node.js 22.19+ and DeepSeek Harness 0.2.0-rc.2, the pinned developer-preview +host version. DSH support starts with Braid 0.3.1; the npm badge shows availability. + +```sh +dsh plugin --profile web add @chrok/dsh-braid +``` + +Restart the profile, ask DSH to run a task with Braid, and open **Braid** in the +session header or right sidebar. Use your own profile name in place of `web`. +npm installs the matching core dependency automatically. See the +[DSH guide](integrations/dsh/README.md) for tools, live controls, the Web panel, +and installation from a local checkout. + ## API After installing the package, submit the graph in one call; diff --git a/ROADMAP.md b/ROADMAP.md index 78b135b..74ca1e9 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -7,11 +7,13 @@ and thin host adapters. This is a direction for discussion, not a delivery sched ## Release status 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 +execution-control foundation. The 0.3.1 release adds DeepSeek Harness integration +and a native Web graph panel. 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. +[@chrok/braid](https://www.npmjs.com/package/@chrok/braid), +[@chrok/pi-braid](https://www.npmjs.com/package/@chrok/pi-braid), and +[@chrok/dsh-braid](https://www.npmjs.com/package/@chrok/dsh-braid) for published versions. ## 0.3 implemented changes @@ -21,6 +23,10 @@ separate milestones. Check - [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. +- [x] DeepSeek Harness integration with background graphs, isolated workers, + live controls, native jobs, and completion/pause reminders. +- [x] Native DSH Web panel and tool cards for live graphs, execution history, + outputs, usage, and controls, targeting DSH 0.2.0-rc.2. Read the [0.2 → 0.3 migration guide](docs/compatibility.md#migrating-from-02-to-03) for workspace capabilities and artifact preservation. @@ -47,7 +53,7 @@ See [execution control](docs/execution-control.md) for the contract and Each release follows the [release checklist](docs/releasing.md): validate the supported Node/platform matrix and isolated package installation, credit PR -authors and first-time contributors, then verify both registry versions, +authors and first-time contributors, then verify all registry versions, provenance, and clean installation before marking publication complete. ## Next candidates @@ -68,7 +74,7 @@ provenance, and clean installation before marking publication complete. requests, and in-flight calls before adding enforcement. - Improve provider diagnostics and add adapters backed by real compatibility tests. Keep SDK dependencies outside the core. -- Migrate both packages from TypeScript 5 to 7 in one dedicated change. Explicitly +- Migrate all packages from TypeScript 5 to 7 in one dedicated change. Explicitly load Node types, review compiler default changes, and validate public declaration consumption, package builds, and the complete Node/platform matrix. Keep Node declarations on 22.x while Node 22 remains the minimum supported runtime. diff --git a/docs/compatibility.md b/docs/compatibility.md index d001a47..08b6575 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -4,9 +4,10 @@ | --- | --- | | Core runtime | Node.js 22+, ESM imports, TypeScript declarations, no runtime dependencies | | 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 | +| DSH package | Node.js 22.19+, DeepSeek Harness 0.2.0-rc.2 is the pinned developer-preview host target; native Web panel | +| CI | Core minimum Node 22.0; all three 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.3 | +| Browsers / CommonJS | No standalone core browser build or CommonJS entry point in 0.3; the DSH `./client` export is loaded by DSH's Web host | The CI matrix describes configured checks; see actual workflow results for each commit. Offline HTTP fixtures validate the adapter contract. They do not prove @@ -28,6 +29,13 @@ 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 its runtime and does not need a source checkout. +The DSH integration starts at 0.3.1 and pins host peers to DSH 0.2.0-rc.2 because +the host is in developer preview. It installs the exact matching core version +and uses DSH's model, tool, and job services. Its browser entry is a native DSH +Web plugin, not a standalone browser runtime. See the +[DSH guide](../integrations/dsh/README.md) for installation and host requirements. +Existing 0.3.0 core and Pi users need no migration for 0.3.1. + 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 @@ -102,7 +110,7 @@ paused execution because the reminder describes the state when it was queued. ## Versioning -Core and Pi release together with matching versions. During 0.x, patch releases +Core, Pi, and DSH release together with matching versions. During 0.x, patch releases preserve documented behavior; breaking API or semantic changes require a minor version bump, a changelog entry, and migration guidance. New optional fields or fixes that restore the documented contract may ship in a patch. diff --git a/docs/releasing.md b/docs/releasing.md index f90e0bf..53c2b9f 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -6,9 +6,10 @@ an exact `@chrok/braid` dependency and includes its own compiled integration cod ## Registry and source association -The public packages are [@chrok/braid](https://www.npmjs.com/package/@chrok/braid) -and [@chrok/pi-braid](https://www.npmjs.com/package/@chrok/pi-braid) on npmjs. -`@chrok/dsh-braid` is a new package awaiting its first publication. +The public packages are [@chrok/braid](https://www.npmjs.com/package/@chrok/braid), +[@chrok/pi-braid](https://www.npmjs.com/package/@chrok/pi-braid), and +[@chrok/dsh-braid](https://www.npmjs.com/package/@chrok/dsh-braid) on npmjs. +DSH joins the coordinated release starting with 0.3.1. Keep `publishConfig.registry` set to `https://registry.npmjs.org`. All manifests link to `Epsirom/braid`; integration `repository.directory` values are `integrations/pi` and `integrations/dsh`. diff --git a/docs/repository-settings.md b/docs/repository-settings.md index 46cb79f..35ce88a 100644 --- a/docs/repository-settings.md +++ b/docs/repository-settings.md @@ -12,24 +12,25 @@ The GitHub About section describes the current `main` capabilities: > TypeScript runtime for LLM agent graphs with bounded loops, live updates, > isolated Git worktrees, and explicit integration. Framework-agnostic core, -> OpenAI-compatible runner, and Pi extension. +> OpenAI-compatible runner, and plugins for Pi and DeepSeek Harness. The repository website points to [@chrok/braid on npm](https://www.npmjs.com/package/@chrok/braid). The root README -links both published packages and displays their npm version badges. Topics are +links all packages and displays their npm version badges. Topics are `llm`, `ai-agents`, `agent-runtime`, `agent-orchestration`, `multi-agent`, `graph-execution`, `bounded-loops`, `git-worktree`, `parallel-execution`, -`typescript`, `nodejs`, `openai-compatible`, and `pi-package`. +`typescript`, `nodejs`, `openai-compatible`, `pi-package`, and `dsh-plugin`. The old DAG-only and workflow-engine labels do not describe the 0.2 scope. -Both packages publish to `https://registry.npmjs.org`: +All packages publish to `https://registry.npmjs.org`: | Package | Repository location | | --- | --- | | [@chrok/braid](https://www.npmjs.com/package/@chrok/braid) | Repository root | | [@chrok/pi-braid](https://www.npmjs.com/package/@chrok/pi-braid) | `integrations/pi` | +| [@chrok/dsh-braid](https://www.npmjs.com/package/@chrok/dsh-braid) | `integrations/dsh` | -Each manifest declares `repository`, `homepage`, and `bugs`; Pi additionally sets +Each manifest declares `repository`, `homepage`, and `bugs`; integrations additionally set `repository.directory`. These fields link npm pages back to the correct source and issue tracker. Descriptions and keywords take effect on npm when a new version is published; editing `main` does not change existing registry versions. diff --git a/integrations/dsh/README.md b/integrations/dsh/README.md index 7fb4482..b8d1c48 100644 --- a/integrations/dsh/README.md +++ b/integrations/dsh/README.md @@ -1,5 +1,7 @@ # Braid for DeepSeek Harness (`@chrok/dsh-braid`) +[![npm](https://img.shields.io/npm/v/%40chrok%2Fdsh-braid?label=%40chrok%2Fdsh-braid)](https://www.npmjs.com/package/@chrok/dsh-braid) + A native DeepSeek Harness plugin for background Braid graphs, bounded loops, isolated Git worktrees, live updates, pause/resume, and completion reminders. It uses DSH's provider routing and credentials through `ctx.llm`; it has no Pi @@ -8,7 +10,13 @@ DSH is in developer preview, so host peer versions are pinned to this baseline. ## Install -From this repository: +DSH support starts with Braid 0.3.1; the npm badge shows availability. + +```sh +dsh plugin --profile web add @chrok/dsh-braid +``` + +For development, install this repository checkout instead: ```sh npm ci @@ -21,12 +29,6 @@ Restart the DSH profile after installation or rebuilding. The package includes It requires the `tools`, `llm`, `commands`, `systemPrompt`, and `jobs` services, which the standard DSH composition provides. Custom profiles must provide them. -Once published, the planned npm installation command is: - -```sh -dsh plugin --profile web add @chrok/dsh-braid -``` - Use your own profile name in place of `web`. Core `@chrok/braid` is installed automatically at the matching version. No API keys belong in plugin configuration; configure models through DSH. A node's `model` is an exact `provider/model-id`, diff --git a/integrations/dsh/package.json b/integrations/dsh/package.json index ed05de0..70aa6c7 100644 --- a/integrations/dsh/package.json +++ b/integrations/dsh/package.json @@ -1,11 +1,11 @@ { "name": "@chrok/dsh-braid", - "version": "0.3.0", + "version": "0.3.1", "license": "MIT", "description": "DeepSeek Harness plugin for Braid: background agent graphs, bounded loops, live updates, and execution progress", "type": "module", "dependencies": { - "@chrok/braid": "0.3.0", + "@chrok/braid": "0.3.1", "@sinclair/typebox": "^0.34.41" }, "peerDependencies": { diff --git a/integrations/pi/README.md b/integrations/pi/README.md index eaa11e4..6f91e20 100644 --- a/integrations/pi/README.md +++ b/integrations/pi/README.md @@ -278,7 +278,7 @@ The extension loads its own compiled `dist/` and the Pi host dependencies. `npm ci` at the repository root installs the pinned workspace development environment, including a local link to core. Use `npm install --workspace @chrok/pi-braid ` when updating Pi dependencies; -both packages share the root lockfile. The adapter uses the `grok-mermaid` terminal renderer for Mermaid flowcharts. +all packages share the root lockfile. The adapter uses the `grok-mermaid` terminal renderer for Mermaid flowcharts. The local install is trusted code: Pi extensions execute with the process's full permissions. diff --git a/integrations/pi/package.json b/integrations/pi/package.json index 0f06259..b1efb9b 100644 --- a/integrations/pi/package.json +++ b/integrations/pi/package.json @@ -1,12 +1,12 @@ { "name": "@chrok/pi-braid", - "version": "0.3.0", + "version": "0.3.1", "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.3.0" + "@chrok/braid": "0.3.1" }, "peerDependencies": { "@earendil-works/pi-ai": "*", diff --git a/package-lock.json b/package-lock.json index f665993..8edffe4 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@chrok/braid", - "version": "0.3.0", + "version": "0.3.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@chrok/braid", - "version": "0.3.0", + "version": "0.3.1", "license": "MIT", "workspaces": [ "integrations/pi", @@ -24,10 +24,10 @@ }, "integrations/dsh": { "name": "@chrok/dsh-braid", - "version": "0.3.0", + "version": "0.3.1", "license": "MIT", "dependencies": { - "@chrok/braid": "0.3.0", + "@chrok/braid": "0.3.1", "@sinclair/typebox": "^0.34.41" }, "devDependencies": { @@ -561,10 +561,10 @@ }, "integrations/pi": { "name": "@chrok/pi-braid", - "version": "0.3.0", + "version": "0.3.1", "license": "MIT", "dependencies": { - "@chrok/braid": "0.3.0", + "@chrok/braid": "0.3.1", "grok-mermaid": "^0.2.2" }, "devDependencies": { diff --git a/package.json b/package.json index 3ca8962..ebf7a91 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@chrok/braid", - "version": "0.3.0", + "version": "0.3.1", "license": "MIT", "description": "TypeScript runtime for LLM agent graphs with bounded loops, live updates, and isolated Git worktrees", "type": "module",