cool-workflow 0.1.78
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +20 -0
- package/.codex-plugin/mcp.json +10 -0
- package/.codex-plugin/plugin.json +38 -0
- package/.mcp.json +10 -0
- package/LICENSE +24 -0
- package/README.md +638 -0
- package/apps/architecture-review/app.json +51 -0
- package/apps/architecture-review/workflow.js +116 -0
- package/apps/end-to-end-golden-path/app.json +30 -0
- package/apps/end-to-end-golden-path/workflow.js +33 -0
- package/apps/pr-review-fix-ci/app.json +59 -0
- package/apps/pr-review-fix-ci/workflow.js +90 -0
- package/apps/release-cut/app.json +54 -0
- package/apps/release-cut/workflow.js +82 -0
- package/apps/research-synthesis/app.json +50 -0
- package/apps/research-synthesis/workflow.js +76 -0
- package/apps/workflow-app-framework-demo/app.json +29 -0
- package/apps/workflow-app-framework-demo/workflow.js +44 -0
- package/dist/agent-config.js +223 -0
- package/dist/candidate-scoring.js +715 -0
- package/dist/capability-core.js +630 -0
- package/dist/capability-dispatcher.js +86 -0
- package/dist/capability-registry.js +523 -0
- package/dist/cli.js +1276 -0
- package/dist/collaboration.js +727 -0
- package/dist/commit.js +570 -0
- package/dist/contract-migration.js +234 -0
- package/dist/coordinator.js +1163 -0
- package/dist/daemon.js +44 -0
- package/dist/dispatch.js +201 -0
- package/dist/drive.js +503 -0
- package/dist/error-feedback.js +415 -0
- package/dist/evidence-grounding.js +179 -0
- package/dist/evidence-reasoning.js +733 -0
- package/dist/execution-backend.js +1279 -0
- package/dist/harness.js +61 -0
- package/dist/mcp-server.js +1615 -0
- package/dist/multi-agent-eval.js +857 -0
- package/dist/multi-agent-host.js +764 -0
- package/dist/multi-agent-operator-ux.js +537 -0
- package/dist/multi-agent-trust.js +366 -0
- package/dist/multi-agent.js +1173 -0
- package/dist/node-snapshot.js +270 -0
- package/dist/observability.js +922 -0
- package/dist/operator-ux.js +971 -0
- package/dist/orchestrator/audit-operations.js +182 -0
- package/dist/orchestrator/candidate-operations.js +117 -0
- package/dist/orchestrator/cli-options.js +288 -0
- package/dist/orchestrator/collaboration-operations.js +86 -0
- package/dist/orchestrator/feedback-operations.js +81 -0
- package/dist/orchestrator/host-operations.js +78 -0
- package/dist/orchestrator/lifecycle-operations.js +462 -0
- package/dist/orchestrator/migration-operations.js +44 -0
- package/dist/orchestrator/multi-agent-operations.js +362 -0
- package/dist/orchestrator/report.js +369 -0
- package/dist/orchestrator/topology-operations.js +84 -0
- package/dist/orchestrator.js +874 -0
- package/dist/pipeline-contract.js +92 -0
- package/dist/pipeline-runner.js +285 -0
- package/dist/reclamation.js +882 -0
- package/dist/result-normalize.js +194 -0
- package/dist/run-export.js +64 -0
- package/dist/run-registry.js +1347 -0
- package/dist/run-state-schema.js +67 -0
- package/dist/sandbox-profile.js +471 -0
- package/dist/scheduler.js +266 -0
- package/dist/scheduling.js +184 -0
- package/dist/schema-validate.js +98 -0
- package/dist/state-explosion.js +1213 -0
- package/dist/state-migrations.js +463 -0
- package/dist/state-node.js +301 -0
- package/dist/state.js +308 -0
- package/dist/telemetry-attestation.js +156 -0
- package/dist/telemetry-ledger.js +145 -0
- package/dist/topology.js +527 -0
- package/dist/triggers.js +159 -0
- package/dist/trust-audit.js +475 -0
- package/dist/types/blackboard.js +2 -0
- package/dist/types/boundary.js +29 -0
- package/dist/types/candidate.js +2 -0
- package/dist/types/collaboration.js +2 -0
- package/dist/types/core.js +2 -0
- package/dist/types/drive.js +10 -0
- package/dist/types/error-feedback.js +2 -0
- package/dist/types/evidence-reasoning.js +2 -0
- package/dist/types/execution-backend.js +2 -0
- package/dist/types/multi-agent.js +2 -0
- package/dist/types/observability.js +2 -0
- package/dist/types/pipeline.js +2 -0
- package/dist/types/reclamation.js +8 -0
- package/dist/types/result.js +2 -0
- package/dist/types/run-registry.js +2 -0
- package/dist/types/run.js +2 -0
- package/dist/types/sandbox.js +2 -0
- package/dist/types/schedule.js +2 -0
- package/dist/types/state-node.js +2 -0
- package/dist/types/topology.js +2 -0
- package/dist/types/trust.js +2 -0
- package/dist/types/workbench.js +2 -0
- package/dist/types/worker.js +2 -0
- package/dist/types/workflow-app.js +2 -0
- package/dist/types.js +43 -0
- package/dist/verifier-registry.js +46 -0
- package/dist/verifier.js +78 -0
- package/dist/version.js +8 -0
- package/dist/workbench-host.js +172 -0
- package/dist/workbench.js +190 -0
- package/dist/worker-isolation.js +1028 -0
- package/dist/workflow-api.js +98 -0
- package/dist/workflow-app-framework.js +626 -0
- package/docs/agent-delegation-drive.7.md +190 -0
- package/docs/agent-framework.md +176 -0
- package/docs/candidate-scoring.7.md +106 -0
- package/docs/canonical-workflow-apps.7.md +137 -0
- package/docs/capability-topology-registry.7.md +168 -0
- package/docs/cli-mcp-parity.7.md +373 -0
- package/docs/contract-migration-tooling.7.md +123 -0
- package/docs/control-plane-scheduling.7.md +110 -0
- package/docs/coordinator-blackboard.7.md +183 -0
- package/docs/dogfood/architecture-review-cool-workflow.md +16 -0
- package/docs/dogfood-one-real-repo.7.md +168 -0
- package/docs/durable-state-and-locking.7.md +107 -0
- package/docs/end-to-end-golden-path.7.md +117 -0
- package/docs/error-feedback.7.md +153 -0
- package/docs/evidence-adoption-reasoning-chain.7.md +270 -0
- package/docs/execution-backends.7.md +300 -0
- package/docs/getting-started.md +99 -0
- package/docs/index.md +41 -0
- package/docs/mcp-app-surface.7.md +235 -0
- package/docs/multi-agent-cli-mcp-surface.7.md +265 -0
- package/docs/multi-agent-eval-replay-harness.7.md +302 -0
- package/docs/multi-agent-operator-ux.7.md +314 -0
- package/docs/multi-agent-runtime-core.7.md +231 -0
- package/docs/multi-agent-topologies.7.md +103 -0
- package/docs/multi-agent-trust-policy-audit.7.md +154 -0
- package/docs/node-snapshot-diff-replay.7.md +135 -0
- package/docs/observability-cost-accounting.7.md +194 -0
- package/docs/operator-ux.7.md +180 -0
- package/docs/pipeline-runner.7.md +136 -0
- package/docs/project-index.md +261 -0
- package/docs/real-execution-backends.7.md +142 -0
- package/docs/release-and-migration.7.md +280 -0
- package/docs/release-tooling.7.md +159 -0
- package/docs/routines.md +48 -0
- package/docs/run-registry-control-plane.7.md +312 -0
- package/docs/run-retention-reclamation.7.md +191 -0
- package/docs/sandbox-profiles.7.md +137 -0
- package/docs/scheduled-tasks.md +80 -0
- package/docs/security-trust-hardening.7.md +117 -0
- package/docs/state-explosion-management.7.md +264 -0
- package/docs/state-node.7.md +96 -0
- package/docs/team-collaboration.7.md +207 -0
- package/docs/unix-principles.md +192 -0
- package/docs/verifier-gated-commit.7.md +140 -0
- package/docs/web-desktop-workbench.7.md +215 -0
- package/docs/worker-isolation.7.md +167 -0
- package/docs/workflow-app-framework.7.md +274 -0
- package/manifest/README.md +43 -0
- package/manifest/plugin.manifest.json +316 -0
- package/manifest/pricing.policy.json +14 -0
- package/package.json +79 -0
- package/scripts/agents/claude-p-agent.js +104 -0
- package/scripts/agents/claude-p-agent.sh +9 -0
- package/scripts/agents/cw-attest-keygen.js +55 -0
- package/scripts/agents/cw-attest-wrap.js +143 -0
- package/scripts/block-unapproved-tag.sh +39 -0
- package/scripts/bump-version.js +249 -0
- package/scripts/canonical-apps.js +171 -0
- package/scripts/cw.js +4 -0
- package/scripts/dist-drift-check.js +79 -0
- package/scripts/dogfood-architecture-review.js +237 -0
- package/scripts/dogfood-release.js +624 -0
- package/scripts/forward-ref-docs.js +73 -0
- package/scripts/gen-manifests.js +232 -0
- package/scripts/golden-path.js +300 -0
- package/scripts/mcp-server.js +4 -0
- package/scripts/new-feature.js +121 -0
- package/scripts/parity-check.js +213 -0
- package/scripts/release-check.js +118 -0
- package/scripts/release-flow.js +272 -0
- package/scripts/release-gate.sh +85 -0
- package/scripts/sync-project-index.js +387 -0
- package/scripts/validate-run-state-schema.js +126 -0
- package/scripts/verify-container-selfref.js +64 -0
- package/scripts/version-sync-check.js +237 -0
- package/skills/cool-workflow/SKILL.md +162 -0
- package/skills/cool-workflow/references/commands.md +282 -0
- package/tsconfig.json +16 -0
- package/ui/workbench/app.css +76 -0
- package/ui/workbench/app.js +159 -0
- package/ui/workbench/index.html +32 -0
- package/workflows/architecture-review.workflow.js +84 -0
- package/workflows/research-synthesis.workflow.js +47 -0
|
@@ -0,0 +1,314 @@
|
|
|
1
|
+
# Multi-Agent Operator UX
|
|
2
|
+
|
|
3
|
+
CW v0.1.21 makes multi-agent operator inspection first-class. The feature is a
|
|
4
|
+
read-only userland view over existing run state. It does not create a hidden
|
|
5
|
+
dashboard database and does not infer success when evidence, dependency, or
|
|
6
|
+
lifecycle state is ambiguous.
|
|
7
|
+
CW v0.1.22 adds trust panels to the same operator path so role policy,
|
|
8
|
+
permission decisions, blackboard write audit, message provenance, judge
|
|
9
|
+
rationale, panel decisions, and policy violations are visible beside topology
|
|
10
|
+
and evidence state.
|
|
11
|
+
CW v0.1.24 uses the same operator-derived graph, dependency, failure, evidence,
|
|
12
|
+
trust, and report views as replay comparison inputs for the Multi-Agent Eval &
|
|
13
|
+
Replay Harness.
|
|
14
|
+
CW v0.1.25 layers State Explosion Management on top of these operator views: when
|
|
15
|
+
a run grows large, `summary show`, `multi-agent summarize`, and
|
|
16
|
+
`multi-agent graph --view compact` collapse high-volume records into synthetic
|
|
17
|
+
summary nodes while preserving the critical path, failures, missing evidence,
|
|
18
|
+
policy violations, and judge rationale. See
|
|
19
|
+
[state-explosion-management.7.md](state-explosion-management.7.md).
|
|
20
|
+
|
|
21
|
+
CW v0.1.26 adds the `Adoption Rationale` panel and the `multi-agent reasoning`
|
|
22
|
+
view, which explains *why* each evidence item was adopted. Reasoning steps are on
|
|
23
|
+
the critical path and are never collapsed by compaction. See
|
|
24
|
+
[evidence-adoption-reasoning-chain.7.md](evidence-adoption-reasoning-chain.7.md).
|
|
25
|
+
|
|
26
|
+
CW v0.1.27 adds an additive evidence `disposition` (`adopted` | `inspectable` |
|
|
27
|
+
`blocking`) and an `inspectableEvidence` list. The raw `status` (the adoption
|
|
28
|
+
state) is unchanged; `disposition` is the operator-facing reading of it. Before a
|
|
29
|
+
verifier-gated commit, a missing/pending row genuinely blocks. After a
|
|
30
|
+
verifier-gated commit the selected path is decided, so missing/pending evidence
|
|
31
|
+
for sibling roles that were never driven as separate workers — for example
|
|
32
|
+
undriven judge-panel judges — is inspectable operator state, not a hidden
|
|
33
|
+
failure. The `multi-agent status` "Missing Evidence" header and the `status`
|
|
34
|
+
panel report the blocking-vs-inspectable split so the operator is not misled.
|
|
35
|
+
|
|
36
|
+
The model is derived from:
|
|
37
|
+
|
|
38
|
+
- `WorkflowRun` tasks, dispatches, workers, nodes, feedback, candidates,
|
|
39
|
+
selections, commits, and report paths
|
|
40
|
+
- multi-agent runs, roles, groups, memberships, fanouts, and fanins
|
|
41
|
+
- topology runs and their missing evidence/conflict records
|
|
42
|
+
- blackboard topics, messages, contexts, artifacts, snapshots, and coordinator
|
|
43
|
+
decisions
|
|
44
|
+
- candidate score files, trust audit events, and verifier-gated commit records
|
|
45
|
+
- role policy, blackboard provenance, judge rationale, panel decisions, and
|
|
46
|
+
policy violation audit records
|
|
47
|
+
|
|
48
|
+
## Operator Commands
|
|
49
|
+
|
|
50
|
+
Use the normal status and report commands for the broad view:
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
node scripts/cw.js status <run-id>
|
|
54
|
+
node scripts/cw.js graph <run-id>
|
|
55
|
+
node scripts/cw.js report <run-id> --show
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Use the focused multi-agent views when the operator needs the process table:
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
node scripts/cw.js multi-agent status <run-id>
|
|
62
|
+
node scripts/cw.js multi-agent graph <run-id>
|
|
63
|
+
node scripts/cw.js multi-agent dependencies <run-id>
|
|
64
|
+
node scripts/cw.js multi-agent failures <run-id>
|
|
65
|
+
node scripts/cw.js multi-agent evidence <run-id>
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Every focused command supports deterministic JSON:
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
node scripts/cw.js multi-agent status <run-id> --json
|
|
72
|
+
node scripts/cw.js multi-agent dependencies <run-id> --json
|
|
73
|
+
node scripts/cw.js multi-agent failures <run-id> --format json
|
|
74
|
+
node scripts/cw.js multi-agent evidence <run-id> --json
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
The compact human output uses six stable panels:
|
|
78
|
+
|
|
79
|
+
```text
|
|
80
|
+
Agent Graph
|
|
81
|
+
Dependencies
|
|
82
|
+
Failed / Blocked Agents
|
|
83
|
+
Adopted Evidence
|
|
84
|
+
Missing Evidence
|
|
85
|
+
Next Action
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Graph
|
|
89
|
+
|
|
90
|
+
`multi-agent graph` shows the topology-backed agent graph plus downstream
|
|
91
|
+
acceptance records:
|
|
92
|
+
|
|
93
|
+
- MultiAgentRun, topology run, roles, groups, memberships, fanout, and fanin
|
|
94
|
+
- tasks, dispatches, workers, result nodes, and verifier gates
|
|
95
|
+
- blackboard topics, messages, artifacts, contexts, snapshots, and coordinator
|
|
96
|
+
decisions
|
|
97
|
+
- candidates, score records, selections, verifier-gated commits, and feedback
|
|
98
|
+
|
|
99
|
+
Edges are labeled when the label carries operational meaning:
|
|
100
|
+
|
|
101
|
+
```text
|
|
102
|
+
owns
|
|
103
|
+
depends-on
|
|
104
|
+
dispatches
|
|
105
|
+
reports
|
|
106
|
+
cites
|
|
107
|
+
adopted-by
|
|
108
|
+
rejected-by
|
|
109
|
+
blocks
|
|
110
|
+
scores
|
|
111
|
+
selects
|
|
112
|
+
gates
|
|
113
|
+
commits
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Direction follows the dependency or evidence flow. For example, a membership
|
|
117
|
+
depends on a task and worker, worker output reports into the membership,
|
|
118
|
+
blackboard artifacts are cited by fanin, scores evaluate candidates, selections
|
|
119
|
+
choose scored candidates, and commits record the selected verifier-gated result.
|
|
120
|
+
|
|
121
|
+
## Failures
|
|
122
|
+
|
|
123
|
+
`multi-agent failures` merges the records an operator normally has to inspect
|
|
124
|
+
one at a time:
|
|
125
|
+
|
|
126
|
+
- failed memberships and missing role coverage
|
|
127
|
+
- missing worker output and failed or rejected workers
|
|
128
|
+
- open feedback, including sandbox-policy failures
|
|
129
|
+
- fanin blocked reasons and missing blackboard evidence
|
|
130
|
+
- rejected or failed candidates
|
|
131
|
+
- score, selection, verifier, and commit-gate gaps
|
|
132
|
+
- ambiguous blocked dependencies
|
|
133
|
+
|
|
134
|
+
Each row includes the record id, kind, status, owner or role when known, linked
|
|
135
|
+
task/worker/membership/fanin/candidate when known, the exact reason, and the
|
|
136
|
+
next safe command.
|
|
137
|
+
|
|
138
|
+
## Evidence Adoption
|
|
139
|
+
|
|
140
|
+
`multi-agent evidence` explains why a result was accepted or not accepted. Each
|
|
141
|
+
row includes:
|
|
142
|
+
|
|
143
|
+
- evidence id/ref/path/locator
|
|
144
|
+
- source kind and source id
|
|
145
|
+
- adopted-by ids and rejected-by ids
|
|
146
|
+
- pending consumers
|
|
147
|
+
- candidate, score, selection, and commit links
|
|
148
|
+
- provenance or trust source when available
|
|
149
|
+
- status: `adopted`, `rejected`, `pending`, `superseded`, `conflicting`, or
|
|
150
|
+
`missing`
|
|
151
|
+
|
|
152
|
+
An accepted path should be traceable like this:
|
|
153
|
+
|
|
154
|
+
```text
|
|
155
|
+
worker result -> blackboard artifact/message -> fanin -> candidate score
|
|
156
|
+
-> selection -> verifier-gated commit
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
When any link is missing, CW reports it as pending or missing and recommends the
|
|
160
|
+
next command rather than assuming the run is healthy.
|
|
161
|
+
|
|
162
|
+
## MCP Parity
|
|
163
|
+
|
|
164
|
+
MCP hosts can inspect the same derived data:
|
|
165
|
+
|
|
166
|
+
- `cw_multi_agent_status`
|
|
167
|
+
- `cw_multi_agent_graph`
|
|
168
|
+
- `cw_multi_agent_dependencies`
|
|
169
|
+
- `cw_multi_agent_failures`
|
|
170
|
+
- `cw_multi_agent_evidence`
|
|
171
|
+
|
|
172
|
+
`cw_multi_agent_status` preserves the v0.1.20 host envelope and adds the
|
|
173
|
+
derived operator model under `summaries.multiAgentOperator`.
|
|
174
|
+
|
|
175
|
+
## Example Trace
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
node scripts/cw.js multi-agent graph "$RUN"
|
|
179
|
+
node scripts/cw.js multi-agent dependencies "$RUN" --json
|
|
180
|
+
node scripts/cw.js multi-agent failures "$RUN"
|
|
181
|
+
node scripts/cw.js multi-agent evidence "$RUN"
|
|
182
|
+
node scripts/cw.js audit provenance "$RUN" --candidate "$CANDIDATE"
|
|
183
|
+
node scripts/cw.js commit "$RUN" --selection "$SELECTION" --reason "verified winner"
|
|
184
|
+
node scripts/cw.js report "$RUN" --show
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
The operator can start at an agent membership, follow `depends-on` to its task
|
|
188
|
+
and worker, follow `reports` to the blackboard artifact and fanin, follow
|
|
189
|
+
`scores` to the candidate score, follow `selects` to the selected result, and
|
|
190
|
+
follow `commits` to the verifier-gated state commit.
|
|
191
|
+
|
|
192
|
+
## Smoke Coverage
|
|
193
|
+
|
|
194
|
+
`test/multi-agent-operator-ux-smoke.js` creates a deterministic topology-backed
|
|
195
|
+
run with a successful worker evidence path, a failed worker path, blocked fanin
|
|
196
|
+
evidence, score and selection records, a verifier-gated commit, human CLI
|
|
197
|
+
assertions, JSON CLI assertions, MCP parity assertions, and report assertions.
|
|
198
|
+
It is included in `npm test` and `npm run release:check`.
|
|
199
|
+
## CLI ↔ MCP Parity (v0.1.27)
|
|
200
|
+
|
|
201
|
+
Every command and tool referenced above is declared in the v0.1.27 capability
|
|
202
|
+
registry (`src/capability-registry.ts`) and validated by `npm run parity:check`,
|
|
203
|
+
so `cw <cmd> --json` and the matching `cw_<tool>` result render one data source.
|
|
204
|
+
See [cli-mcp-parity.7.md](cli-mcp-parity.7.md).
|
|
205
|
+
|
|
206
|
+
## Run Registry / Control Plane (v0.1.28)
|
|
207
|
+
|
|
208
|
+
The runs described here are indexed, searchable, resumable, archivable, and
|
|
209
|
+
rerunnable across repos by the v0.1.28 Run Registry / Control Plane, which derives
|
|
210
|
+
a fingerprinted, fail-closed index over the same per-run `.cw/runs/<id>/state.json`
|
|
211
|
+
source of truth. See [run-registry-control-plane.7.md](run-registry-control-plane.7.md).
|
|
212
|
+
|
|
213
|
+
## Execution Backends (v0.1.29)
|
|
214
|
+
|
|
215
|
+
v0.1.29 lifts execution into a pluggable driver layer: one narrow `ExecutionBackend`
|
|
216
|
+
contract with interchangeable `node`/`bun`/`shell`/`container`/`remote`/`ci`
|
|
217
|
+
drivers, selected by `--backend` (parallel to `--sandbox`) and inspected via
|
|
218
|
+
`backend list|show|probe`. The result/evidence envelope is schema-identical across
|
|
219
|
+
backends; the backend id + sandbox attestation are recorded as provenance, so this
|
|
220
|
+
surface is unchanged regardless of which backend executed a run. See
|
|
221
|
+
[execution-backends.7.md](execution-backends.7.md).
|
|
222
|
+
## Web / Desktop Workbench (v0.1.30)
|
|
223
|
+
|
|
224
|
+
v0.1.30 adds the Web / Desktop Workbench: a read-only, localhost-only human
|
|
225
|
+
console that renders this surface (and the other four operator panels — run
|
|
226
|
+
graph, blackboard, worker logs, candidate compare, audit timeline) for any run,
|
|
227
|
+
reading the SAME capability `--json` payloads. It is a THIRD FRONT DOOR alongside
|
|
228
|
+
the CLI and MCP that holds no authoritative state and forks no schema: each panel
|
|
229
|
+
equals its `cw <cmd> --json` payload byte-for-byte (parity-gated), and refresh
|
|
230
|
+
re-derives everything from disk. See
|
|
231
|
+
[web-desktop-workbench.7.md](web-desktop-workbench.7.md).
|
|
232
|
+
|
|
233
|
+
## Observability + Cost Accounting (v0.1.31)
|
|
234
|
+
|
|
235
|
+
v0.1.31 adds Observability + Cost Accounting: `metrics show`/`metrics summary`
|
|
236
|
+
derive durations, failure/verifier/acceptance rates (with sample counts and
|
|
237
|
+
fail-closed `n/a`), and host-attested token/cost from existing durable run state
|
|
238
|
+
— no metrics database, no collector daemon, no hidden counter. Usage is additive
|
|
239
|
+
and optional (absent ⇒ `unreported`, never 0); cost is `attested` (attested usage
|
|
240
|
+
× a recorded pricing policy) or clearly `estimated`, with pricing as policy. Both
|
|
241
|
+
verbs are parity-gated and render read-only in the v0.1.30 Workbench. See
|
|
242
|
+
[observability-cost-accounting.7.md](observability-cost-accounting.7.md).
|
|
243
|
+
|
|
244
|
+
|
|
245
|
+
## Team Collaboration (v0.1.32)
|
|
246
|
+
|
|
247
|
+
v0.1.32 adds Team Collaboration: a host-attested actor and append-only
|
|
248
|
+
approvals/rejections/comments/handoffs provenance-linked to a durable target,
|
|
249
|
+
plus a review gate that STACKS ON the verifier gate — required approvals from
|
|
250
|
+
authorized roles, enforced inside `resolveCommitGate` AFTER the verifier checks
|
|
251
|
+
and never instead of them, failing closed on quorum/authority/self-approval and
|
|
252
|
+
recording who approved the very artifact that shipped. Policy (required approvals,
|
|
253
|
+
authorized roles, self-approval) is data, default off (pre-v0.1.32 behavior
|
|
254
|
+
unchanged). The verbs are parity-gated and render read-only in the v0.1.30
|
|
255
|
+
Workbench. See [Team Collaboration](team-collaboration.7.md).
|
|
256
|
+
|
|
257
|
+
## Release Tooling (v0.1.33)
|
|
258
|
+
|
|
259
|
+
the per-tag mechanical surfaces (version bump across 17 surfaces, feature scaffold, and the forward-reference docs) become deterministic scripts, with a de-duplicated release gate. See release-tooling(7).
|
|
260
|
+
|
|
261
|
+
## Real Execution Backend Integrations (v0.1.34)
|
|
262
|
+
|
|
263
|
+
container/remote/ci backends really execute (docker/podman run, remote/CI POST-and-poll) under the sandbox contract, with byte-stable evidence vs node and fail-closed refusal when a runtime/endpoint is unavailable. See real-execution-backends(7).
|
|
264
|
+
|
|
265
|
+
## Node Snapshot / Diff / Replay (v0.1.35)
|
|
266
|
+
|
|
267
|
+
per-node snapshot, structural diff, and isolated deterministic replay over StateNode, reusing the v0.1.23 eval harness; fail-closed on source drift (valid|stale|absent). See node-snapshot-diff-replay(7).
|
|
268
|
+
|
|
269
|
+
## Contract Migration Tooling (v0.1.36)
|
|
270
|
+
|
|
271
|
+
first-class declared migration registry (run-state + workflow-app) with per-edge compatibility proofs, fail-closed reachability, and a round-trip/non-destruction prover. See contract-migration-tooling(7).
|
|
272
|
+
|
|
273
|
+
## Control-Plane Scheduling (v0.1.37)
|
|
274
|
+
|
|
275
|
+
priority + concurrency limits + lease lifecycle + retry/backoff + fail-closed park over the v0.1.28 Run Registry queue; policy-as-data, deterministic. See control-plane-scheduling(7).
|
|
276
|
+
|
|
277
|
+
## Agent Delegation Drive (v0.1.38)
|
|
278
|
+
|
|
279
|
+
spawn an external agent process per worker, capture result.md + attestation, auto-drive plan->dispatch->fulfill->accept->commit
|
|
280
|
+
|
|
281
|
+
## Run Retention & Provable Reclamation (v0.1.39)
|
|
282
|
+
|
|
283
|
+
tiered, append-only, cryptographically-verifiable run reclamation: seal the audit skeleton, free the reconstructable bulk, prove it
|
|
284
|
+
|
|
285
|
+
## Durable State & Locking (v0.1.40)
|
|
286
|
+
|
|
287
|
+
atomic temp->rename writes + fsync-durability for authoritative stores; portable stale-stealing file lock serializing the cross-process read-modify-write stores
|
|
288
|
+
|
|
289
|
+
## Self-Audit Hardening & Pure-Router Decomposition (v0.1.41)
|
|
290
|
+
|
|
291
|
+
evidence grounding + durable audit append + symlink-hardened containment + deterministic worker ids + recursive redaction; BackendRegistry self-describing drivers (no per-id switches); orchestrator god-object decomposed into per-domain operation modules (pure loadRun->delegate router)
|
|
292
|
+
|
|
293
|
+
## Robust Result Ingest (v0.1.42)
|
|
294
|
+
|
|
295
|
+
capture findings/evidence from any reasonable agent shape (alt keys + prose), CW derives grounded evidence itself, warn on empty capture — closes the v0.1.41 live-drive 'accepted with 0 captured' failure
|
|
296
|
+
|
|
297
|
+
## No-False-Green Gate & Launch Prep (v0.1.43)
|
|
298
|
+
|
|
299
|
+
Hard gate blocking empty-capture verifier-gated commits, plus quickstart and launch-prep docs.
|
|
300
|
+
|
|
301
|
+
## Release-Gate Determinism & Agents Vendor (v0.1.44)
|
|
302
|
+
|
|
303
|
+
Release-readiness checks now validate the committed blob (`git show HEAD:<path>`) instead of the mutable working tree — eliminating false-red/false-green from concurrent working-tree writes (iCloud/Spotlight/editor). Adds the `agents` vendor manifest target: a generated `.agents/plugins/cool-workflow/` adapter giving any non-Claude AI agent one common interface to CW.
|
|
304
|
+
|
|
305
|
+
## P1-P2 Fixes & CI Content Surfaces (v0.1.49)
|
|
306
|
+
|
|
307
|
+
Migration DAG with reversible edges (v0.1.45), capability auto-discovery (v0.1.46), vendor-adapter registry (v0.1.47), state auto-compaction and P2 fixes (v0.1.48), plus CI content-surface determinism hardening (v0.1.49).
|
|
308
|
+
0.1.51
|
|
309
|
+
|
|
310
|
+
0.1.76
|
|
311
|
+
|
|
312
|
+
0.1.77
|
|
313
|
+
|
|
314
|
+
0.1.78
|
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
# Multi-Agent Runtime Core
|
|
2
|
+
|
|
3
|
+
CW v0.1.17 made multi-agent runtime state first-class. Dispatches and worker
|
|
4
|
+
records still exist, but they now have explicit process-table-style state around
|
|
5
|
+
them: `MultiAgentRun`, `AgentRole`, `AgentGroup`, `AgentMembership`,
|
|
6
|
+
`AgentFanout`, and `AgentFanin`.
|
|
7
|
+
|
|
8
|
+
CW v0.1.18 extends these records with blackboard and topic links so fanout,
|
|
9
|
+
worker manifests, accepted worker output, and fanin evidence can cite the
|
|
10
|
+
Coordinator / Blackboard substrate.
|
|
11
|
+
|
|
12
|
+
This release is the runtime core, not an autonomous scheduler. CW records and
|
|
13
|
+
validates the state model. The agent host still executes agents and enforces
|
|
14
|
+
OS/process/network/environment controls.
|
|
15
|
+
|
|
16
|
+
## State Model
|
|
17
|
+
|
|
18
|
+
Multi-agent state lives in durable run state:
|
|
19
|
+
|
|
20
|
+
```text
|
|
21
|
+
.cw/runs/<run-id>/state.json
|
|
22
|
+
multiAgent:
|
|
23
|
+
schemaVersion: 1
|
|
24
|
+
runs: []
|
|
25
|
+
roles: []
|
|
26
|
+
groups: []
|
|
27
|
+
memberships: []
|
|
28
|
+
fanouts: []
|
|
29
|
+
fanins: []
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
CW also mirrors records to local JSON files:
|
|
33
|
+
|
|
34
|
+
```text
|
|
35
|
+
.cw/runs/<run-id>/multi-agent/
|
|
36
|
+
index.json
|
|
37
|
+
runs/<multi-agent-run-id>.json
|
|
38
|
+
roles/<role-id>.json
|
|
39
|
+
groups/<group-id>.json
|
|
40
|
+
memberships/<membership-id>.json
|
|
41
|
+
fanouts/<fanout-id>.json
|
|
42
|
+
fanins/<fanin-id>.json
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
All records carry stable ids, timestamps, schema versions, lifecycle history,
|
|
46
|
+
parent/child links where relevant, and metadata. Records link back to the
|
|
47
|
+
existing workflow run, phase, task, dispatch, worker, result, verifier,
|
|
48
|
+
candidate, commit, and audit surfaces.
|
|
49
|
+
|
|
50
|
+
## Runtime Objects
|
|
51
|
+
|
|
52
|
+
`MultiAgentRun` is the top-level runtime table entry for coordinated agent work.
|
|
53
|
+
Its lifecycle is:
|
|
54
|
+
|
|
55
|
+
```text
|
|
56
|
+
planned -> forming -> running -> collecting -> verifying -> completed
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
It may also move to `failed` or `cancelled`. Invalid lifecycle transitions fail
|
|
60
|
+
closed.
|
|
61
|
+
|
|
62
|
+
`AgentRole` describes responsibility, required evidence, sandbox profile hints,
|
|
63
|
+
expected artifacts, and fanin obligations.
|
|
64
|
+
|
|
65
|
+
`AgentGroup` is a coordinated set of members for a phase or subproblem. Groups
|
|
66
|
+
hold role, task, membership, worker, fanout, and fanin ids.
|
|
67
|
+
|
|
68
|
+
`AgentMembership` binds one role to one task and, once dispatched, one worker.
|
|
69
|
+
A worker can belong to one or more groups only through explicit membership
|
|
70
|
+
records. Duplicate membership for the same group, role, task, and worker fails
|
|
71
|
+
closed.
|
|
72
|
+
|
|
73
|
+
`AgentFanout` records why work was split, which roles/tasks/workers were
|
|
74
|
+
created or attached, concurrency limits, sandbox profile choices, dispatch ids,
|
|
75
|
+
and the expected return shape.
|
|
76
|
+
|
|
77
|
+
`AgentFanin` records aggregation strategy, required roles, reported members,
|
|
78
|
+
missing members, evidence coverage, blocked reasons, and verifier readiness.
|
|
79
|
+
Fanin does not silently accept missing evidence for required roles.
|
|
80
|
+
|
|
81
|
+
## Dispatch Integration
|
|
82
|
+
|
|
83
|
+
Existing dispatch and worker flows remain valid:
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
node scripts/cw.js dispatch <run-id> --limit 1 --sandbox readonly
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
To attach dispatch to explicit multi-agent state:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
node scripts/cw.js multi-agent run <run-id> --id ma-release --objective "release verification"
|
|
93
|
+
node scripts/cw.js multi-agent role <run-id> verifier \
|
|
94
|
+
--multi-agent-run ma-release \
|
|
95
|
+
--responsibility "verify release evidence" \
|
|
96
|
+
--required-evidence "release-check log"
|
|
97
|
+
node scripts/cw.js multi-agent group <run-id> release-group \
|
|
98
|
+
--multi-agent-run ma-release \
|
|
99
|
+
--phase "Verify" \
|
|
100
|
+
--task verify:package
|
|
101
|
+
node scripts/cw.js multi-agent fanout <run-id> release-fanout \
|
|
102
|
+
--group release-group \
|
|
103
|
+
--reason "split release verification" \
|
|
104
|
+
--role verifier \
|
|
105
|
+
--task verify:package \
|
|
106
|
+
--limit 1 \
|
|
107
|
+
--sandbox-choice verifier=readonly
|
|
108
|
+
node scripts/cw.js dispatch <run-id> \
|
|
109
|
+
--limit 1 \
|
|
110
|
+
--sandbox readonly \
|
|
111
|
+
--multi-agent-run ma-release \
|
|
112
|
+
--multi-agent-group release-group \
|
|
113
|
+
--multi-agent-role verifier \
|
|
114
|
+
--multi-agent-fanout release-fanout
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Worker manifests then include:
|
|
118
|
+
|
|
119
|
+
```json
|
|
120
|
+
{
|
|
121
|
+
"multiAgent": {
|
|
122
|
+
"runId": "ma-release",
|
|
123
|
+
"groupId": "release-group",
|
|
124
|
+
"roleId": "verifier",
|
|
125
|
+
"membershipId": "membership-id",
|
|
126
|
+
"fanoutId": "release-fanout"
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
When CW accepts worker output, it updates linked membership evidence and records
|
|
132
|
+
multi-agent trust audit events.
|
|
133
|
+
|
|
134
|
+
## Fanin
|
|
135
|
+
|
|
136
|
+
Collect fanin after worker output:
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
node scripts/cw.js multi-agent fanin <run-id> release-fanin \
|
|
140
|
+
--group release-group \
|
|
141
|
+
--fanout release-fanout \
|
|
142
|
+
--required-role verifier
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
If a required role has no membership, or a membership has not reported evidence,
|
|
146
|
+
the fanin record is `blocked` and `verifierReady=false`. This is intentional:
|
|
147
|
+
missing evidence is a state error, not an implicit success.
|
|
148
|
+
|
|
149
|
+
## Inspect
|
|
150
|
+
|
|
151
|
+
Use normal operator commands:
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
node scripts/cw.js status <run-id>
|
|
155
|
+
node scripts/cw.js graph <run-id>
|
|
156
|
+
node scripts/cw.js report <run-id> --show
|
|
157
|
+
node scripts/cw.js audit summary <run-id>
|
|
158
|
+
node scripts/cw.js audit provenance <run-id>
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
Use focused multi-agent commands:
|
|
162
|
+
|
|
163
|
+
```bash
|
|
164
|
+
node scripts/cw.js multi-agent summary <run-id>
|
|
165
|
+
node scripts/cw.js multi-agent summary <run-id> --json
|
|
166
|
+
node scripts/cw.js multi-agent graph <run-id>
|
|
167
|
+
node scripts/cw.js multi-agent graph <run-id> --json
|
|
168
|
+
node scripts/cw.js multi-agent show <run-id> <multi-agent-run-id>
|
|
169
|
+
node scripts/cw.js multi-agent role <run-id> <role-id>
|
|
170
|
+
node scripts/cw.js multi-agent group <run-id> <group-id>
|
|
171
|
+
node scripts/cw.js multi-agent membership <run-id> <membership-id>
|
|
172
|
+
node scripts/cw.js multi-agent fanout <run-id> <fanout-id>
|
|
173
|
+
node scripts/cw.js multi-agent fanin <run-id> <fanin-id>
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
The status and report Multi-Agent panel shows group status, role coverage,
|
|
177
|
+
membership health, fanout/fanin progress, blocked reasons, and the next
|
|
178
|
+
recommended action.
|
|
179
|
+
|
|
180
|
+
## MCP Parity
|
|
181
|
+
|
|
182
|
+
MCP read/inspect tools:
|
|
183
|
+
|
|
184
|
+
```text
|
|
185
|
+
cw_multi_agent_summary
|
|
186
|
+
cw_multi_agent_graph
|
|
187
|
+
cw_multi_agent_run_show
|
|
188
|
+
cw_multi_agent_role_show
|
|
189
|
+
cw_multi_agent_group_show
|
|
190
|
+
cw_multi_agent_membership_show
|
|
191
|
+
cw_multi_agent_fanout_show
|
|
192
|
+
cw_multi_agent_fanin_show
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Safe write tools:
|
|
196
|
+
|
|
197
|
+
```text
|
|
198
|
+
cw_multi_agent_run_create
|
|
199
|
+
cw_multi_agent_run_transition
|
|
200
|
+
cw_multi_agent_role_create
|
|
201
|
+
cw_multi_agent_group_create
|
|
202
|
+
cw_multi_agent_membership_create
|
|
203
|
+
cw_multi_agent_fanout_create
|
|
204
|
+
cw_multi_agent_fanin_collect
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
There is no MCP-only or CLI-only core model. The dogfood release script remains
|
|
208
|
+
CLI-only because it is a local release-engineering composition of existing CW
|
|
209
|
+
tools, not a new runtime primitive.
|
|
210
|
+
|
|
211
|
+
## Compatibility
|
|
212
|
+
|
|
213
|
+
Older v0.1.16 and earlier run state normalizes with:
|
|
214
|
+
|
|
215
|
+
```json
|
|
216
|
+
{
|
|
217
|
+
"multiAgent": {
|
|
218
|
+
"schemaVersion": 1,
|
|
219
|
+
"runs": [],
|
|
220
|
+
"roles": [],
|
|
221
|
+
"groups": [],
|
|
222
|
+
"memberships": [],
|
|
223
|
+
"fanouts": [],
|
|
224
|
+
"fanins": []
|
|
225
|
+
}
|
|
226
|
+
}
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
Unknown user data is preserved. Fixtures are copied before compatibility tests,
|
|
230
|
+
and fixture files are not mutated.
|
|
231
|
+
0.1.51
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
# Multi-Agent Topologies
|
|
2
|
+
|
|
3
|
+
CW v0.1.19 adds the first official topology layer on top of the Multi-Agent
|
|
4
|
+
Runtime Core and Coordinator / Blackboard.
|
|
5
|
+
|
|
6
|
+
Topologies are userland recipes, not hidden automation. Applying a topology
|
|
7
|
+
materializes ordinary CW records: `MultiAgentRun`, roles, groups, fanouts,
|
|
8
|
+
fanins, blackboard topics, messages, coordinator decisions, audit events,
|
|
9
|
+
candidate links, selections, commits, and graph nodes.
|
|
10
|
+
|
|
11
|
+
## Official Topologies
|
|
12
|
+
|
|
13
|
+
- `map-reduce`: creates mapper roles, a reducer role, mapper fanout, mapper
|
|
14
|
+
output topics, reducer synthesis topics, and fail-closed fanin readiness.
|
|
15
|
+
- `debate`: creates opposing roles, debate round topics, conflict context,
|
|
16
|
+
coordinator claim decisions, and a final synthesis role.
|
|
17
|
+
- `judge-panel`: creates independent judge roles, a panel chair, judge verdict
|
|
18
|
+
topics, score aggregation expectations, and panel decision provenance.
|
|
19
|
+
|
|
20
|
+
## Contract
|
|
21
|
+
|
|
22
|
+
Each topology definition declares:
|
|
23
|
+
|
|
24
|
+
- roles and groups
|
|
25
|
+
- blackboard topics
|
|
26
|
+
- phases
|
|
27
|
+
- fanout and fanin strategy
|
|
28
|
+
- required evidence
|
|
29
|
+
- coordinator decision kinds
|
|
30
|
+
- candidate and scoring expectations
|
|
31
|
+
- verifier gates
|
|
32
|
+
|
|
33
|
+
Durable topology run records live in:
|
|
34
|
+
|
|
35
|
+
```text
|
|
36
|
+
.cw/runs/<run-id>/topologies/index.json
|
|
37
|
+
.cw/runs/<run-id>/topologies/runs/<topology-run-id>.json
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
The topology record links to the generated multi-agent run, roles, groups,
|
|
41
|
+
fanouts, fanins, blackboard topics, messages, coordinator decisions,
|
|
42
|
+
candidates, selections, commits, and trust audit events.
|
|
43
|
+
|
|
44
|
+
## CLI
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
node scripts/cw.js topology list
|
|
48
|
+
node scripts/cw.js topology show map-reduce
|
|
49
|
+
node scripts/cw.js topology validate map-reduce
|
|
50
|
+
node scripts/cw.js topology apply <run-id> map-reduce --task map:server-api --mapper-count 2
|
|
51
|
+
node scripts/cw.js topology summary <run-id>
|
|
52
|
+
node scripts/cw.js topology graph <run-id>
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Apply commands are JSON-first. `summary` and `graph` also support human output
|
|
56
|
+
and `--json`.
|
|
57
|
+
|
|
58
|
+
## MCP
|
|
59
|
+
|
|
60
|
+
MCP parity tools:
|
|
61
|
+
|
|
62
|
+
- `cw_topology_list`
|
|
63
|
+
- `cw_topology_show`
|
|
64
|
+
- `cw_topology_validate`
|
|
65
|
+
- `cw_topology_apply`
|
|
66
|
+
- `cw_topology_summary`
|
|
67
|
+
- `cw_topology_graph`
|
|
68
|
+
|
|
69
|
+
There is no topology behavior that is intentionally CLI-only.
|
|
70
|
+
|
|
71
|
+
## Fail Closed
|
|
72
|
+
|
|
73
|
+
Topology fanin uses the existing `AgentFanin` checks. Required roles without
|
|
74
|
+
memberships, memberships without result evidence, and memberships without
|
|
75
|
+
indexed blackboard evidence remain blocked. A topology run can recommend the
|
|
76
|
+
next command, but it does not silently mark missing evidence as complete.
|
|
77
|
+
|
|
78
|
+
For map-reduce, reducer readiness requires mapper evidence and blackboard
|
|
79
|
+
artifact refs. For debate, synthesis must cite messages, conflict context, and
|
|
80
|
+
coordinator decisions. For judge-panel, no judge output is authoritative until
|
|
81
|
+
fanin and score evidence support a panel decision.
|
|
82
|
+
|
|
83
|
+
## Operator UX
|
|
84
|
+
|
|
85
|
+
`status`, `report --show`, and `graph` include topology progress:
|
|
86
|
+
|
|
87
|
+
- topology id and topology run id
|
|
88
|
+
- generated multi-agent run and blackboard id
|
|
89
|
+
- roles, topics, fanouts, and fanins
|
|
90
|
+
- readiness and missing evidence
|
|
91
|
+
- conflicts
|
|
92
|
+
- deterministic next action
|
|
93
|
+
|
|
94
|
+
Trust audit summaries include topology event counts, and audit provenance can
|
|
95
|
+
follow worker evidence into blackboard artifacts, fanin, candidate selection,
|
|
96
|
+
commits, and reports.
|
|
97
|
+
|
|
98
|
+
CW v0.1.22 adds policy-aware topology inspection. Applying a topology records
|
|
99
|
+
role policies, message provenance, blackboard write audit, judge rationale,
|
|
100
|
+
panel decisions, and policy violations through the same trust-audit log used by
|
|
101
|
+
worker sandbox and evidence provenance records. Judge-panel selection now
|
|
102
|
+
requires evidence-backed judge rationale and panel-chair rationale.
|
|
103
|
+
0.1.51
|