diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 785c102..522fdf6 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -6,7 +6,7 @@ it, an adapter performs the call, and the result is logged and returned. Everyth described in a plain editable config file — adding or removing a backend is a config edit, not a code change. -This document describes the architecture as of **v0.9.0**. Per-change history lives in +This document describes the architecture as of **v0.15.0**. Per-change history lives in [`CHANGELOG.md`](CHANGELOG.md); how to run it lives in [`README.md`](README.md); the opt-in / bring-your-own-key posture lives in [`DISCLAIMER.md`](DISCLAIMER.md). @@ -149,15 +149,16 @@ extra (`pip install -e ".[delegate]"`). Four tools: orchestrator can also route explicitly by fit. The `delegate` tool's description enumerates the menu, built once at server startup. -These are the first three slices of a [scatter-gather roadmap](https://github.com/Jason-Vaughan/TangleBrain/issues/39): +These complete the [scatter-gather roadmap](https://github.com/Jason-Vaughan/TangleBrain/issues/39): the orchestrator routes a sub-task to any configured backend (by id or capability) and fans batches out concurrently. The **reduce step is deliberately not TangleBrain's** — the orchestrator synthesises the `delegate_many` results itself (it holds the original task context that makes for good synthesis), and offloads the stitch with an ordinary `delegate(task=…)` call when the reduction is mechanical and large. No dedicated reducer tool: the existing primitives cover it, and frontier-side synthesis is the -better default until usage proves otherwise. Delegated sub-calls are now **metered** (see Measurement -below) — the deferred observability landed as a by-backend breakdown; a per-parent-task tree (linking -each delegation to its top-level task across processes) is the remaining stretch. +better default until usage proves otherwise. Delegated sub-calls are **metered** (see Measurement +below) as a by-backend breakdown, and each is **linked back to the specific top-level task that spawned +it** across the process boundary (the per-parent-task tree, below) — so the roadmap is complete, not +just core-complete. ### Measurement — per-task records (`measurement.py`) @@ -176,9 +177,14 @@ each `delegate_many` item, is metered at that single seam). The rollup keeps del the headline** — the parent task already credits the whole job, so counting the sub-calls again would double-count the saving — and aggregates them **separately** into a by-backend breakdown (count, est tokens, informational cloud-equiv) surfaced in `--stats` and the GUI. Concurrent appends (delegate_many -fans out across threads) are serialized by a process-level lock. Linking each delegation to its -*specific* parent task across processes (a true tree) is deferred — it needs a task-id propagated -through the orchestrator CLIs to the MCP child, which can't be verified hermetically. +fans out across threads) are serialized by a process-level lock. Each delegation is also linked to its +*specific* parent task across processes (a true tree): the CLI mints a `task_id` per routed task and +injects it as `TANGLEBRAIN_TASK_ID` into the orchestrator's environment, the orchestrator forwards it +to the MCP delegate child, and `run_delegate` reads it back to stamp each delegate record's +`parent_task_id`. The rollup groups delegates `by_parent` (a "Linked to" tree in `--stats` and the +GUI); a sub-call run outside a propagated task is `unlinked`. The orchestrator-forwards-env hop is +verified live (claude), not hermetically — a delegation that loses the env degrades safely to +`unlinked`, never an error. ### Knob GUI — localhost panel (`gui/`) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1b63705..828464e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Internal + +- **Refreshed README + ARCHITECTURE for the shipped feature set.** The README status line is now + version-agnostic (links the latest release + CHANGELOG instead of a fixed version that drifts), and + the delegation bullet describes the full **scatter-gather** capability (route by id/capability, fan + out concurrently, metered + linked to the parent task) instead of the old local-only phrasing. + `ARCHITECTURE.md` is stamped v0.15.0 and its per-parent-task-tree passages — which still called the + tree "deferred" / "the remaining stretch" — now describe it as **shipped** (the `TANGLEBRAIN_TASK_ID` + propagation mechanism). Docs-only; no code change. + ## [0.15.0] - 2026-06-18 ### Added diff --git a/README.md b/README.md index 7753f6c..81eeb33 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,8 @@ and open to contributors: forks and pull requests are welcome. It's also designe seamlessly alongside [TangleClaw](https://github.com/Jason-Vaughan/TangleClaw) and the wider **Tangle family** of tools, so it works the same whether you run it solo or as part of that ecosystem. -**Status:** v0.10.0 — first public release. +**Status:** publicly released and actively developed — see the +[latest release](https://github.com/Jason-Vaughan/TangleBrain/releases) and [`CHANGELOG.md`](CHANGELOG.md). ## What it does @@ -56,8 +57,11 @@ family** of tools, so it works the same whether you run it solo or as part of th or reorganize backends by editing config. - **Pluggable CLI-backed orchestration** — drive authenticated command-line tools as orchestrators, with rotation and failover across them for resilience. -- **Local sub-task delegation** — an orchestrator can offload bulk sub-tasks to the local backend - through an MCP tool, then review the results. +- **Multi-target sub-task delegation (scatter-gather)** — an orchestrator can decompose a task and + offload sub-tasks through MCP tools: to the free local backend, or to any configured backend **by id + or by capability** (a `good_at` tag), and **fan several out concurrently** in one call. Each + delegated sub-call is metered and linked back to the specific top-level task that spawned it, then + the orchestrator reviews and synthesises the results. - **Cost measurement** — every routed task is logged with an estimated cloud-equivalent cost; `tanglebrain --stats` rolls up what you've spent versus avoided. - **Knob GUI** — a localhost panel to view the roster, pricing, and rollup, edit a focused set of