Merge pull request #41 from andreibesleaga/feat/v2.0

Feat/v2.0

Author: andreibesleaga

.env.example

@@ -33,7 +33,13 @@ MESSAGING_DRIVER=bullmq
 # Leave unset to use ConsoleSpanExporter (dev mode — verbose, not suitable for production)
 # OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318/v1/traces
 
-# Comma-separated list of agent IDs this worker node serves (required)
+# Process role for the single combined image (src/main/index.ts dispatches on it).
+#   ROLE=gateway → HTTP / WebSocket / A2A / MCP front door only (no task-consuming actors)
+#   ROLE=worker  → loads the AGENT_IDS pool and wires real LLM-backed handlers
+# Unset defaults to "gateway". (ADR-013 gateway/worker split.)
+# ROLE=gateway
+
+# Comma-separated list of agent IDs this worker node serves (required for ROLE=worker)
 AGENT_IDS=researcher,writer,editor
 
 # LLM Configuration — Standard OpenAI OR OpenRouter (or any OpenAI-compatible API)
@@ -86,6 +92,7 @@ OPENAI_API_KEY=your_openai_api_key_here
 
 # ── Security: Redis password (recommended) ─────────────────────
 # Set this to require a password on the Redis server (matches docker-compose.yml)
+# (compose-only) — consumed by docker-compose, not read directly by src/; fold it into REDIS_URL below.
 # REDIS_PASSWORD=<random 32+ chars>
 # When set, use: REDIS_URL=redis://:${REDIS_PASSWORD}@localhost:6379
 
@@ -98,6 +105,36 @@ OPENAI_API_KEY=your_openai_api_key_here
 # JWT secret for agent/orchestrator service tokens. When set, POST /a2a/rpc requires Bearer token.
 # A2A_JWT_SECRET=<random 32+ bytes, base64-encoded>
 
+# ── Federation: MCP server (Phase M — OFF by default) ──────────────────────────────────────
+# Exposes allow-listed Tools/Resources/Prompts + elicitation (HITL consent) over Streamable HTTP,
+# behind the gateway's security chain (rate-limit + the A2A_JWT_SECRET bearer above). See docs/federation/MCP.md.
+# ⚠ SECURITY: the MCP route is authenticated ONLY when A2A_JWT_SECRET (above) is set. If you enable
+#   MCP in production WITHOUT A2A_JWT_SECRET, the MCP surface (dispatch_task + agent resources) is
+#   UNAUTHENTICATED (still rate-limited + dispatch is elicitation-consent-gated). Set A2A_JWT_SECRET.
+# MCP_SERVER_ENABLED=false               # master switch (default false)
+# MCP_SERVER_PATH=/mcp                   # mount path on the gateway
+# MCP_DISPATCH_CONSENT=true              # require elicitation consent before dispatch_task (fail-closed)
+# Optional least-privilege allow-lists (CSV). Unset ⇒ the full curated set ships; empty ⇒ none of that kind.
+# MCP_ALLOWED_TOOLS=dispatch_task
+# MCP_ALLOWED_RESOURCES=agents,agent-status
+# MCP_ALLOWED_PROMPTS=delegate_task
+
+# ── Economics / FinOps (Phase E — OFF by default) ──────────────────────────────────────────
+# Fleet-wide rate + cost control on top of per-task accounting (which is unchanged). 0 = unlimited.
+# See docs/economics/ECONOMICS.md. The per-task MAX_TOKEN_BUDGET above is separate and still applies.
+# ECONOMICS_ENABLED=false                  # master switch (default false)
+# ECONOMICS_MAX_REQUESTS_PER_WINDOW=0      # request-rate ceiling per scope (0 = unlimited)
+# ECONOMICS_MAX_COST_PER_WINDOW=0          # cost-unit budget per tenant/agent scope (0 = unlimited)
+# ECONOMICS_GLOBAL_COST_CEILING=0          # cost-unit ceiling across ALL scopes (0 = unlimited)
+# ECONOMICS_WINDOW_SECONDS=60              # sliding window length (seconds)
+# ECONOMICS_DEGRADE_THRESHOLD=0.75         # utilization at/above which to DEGRADE (run cheaper)
+
+# ── Governance / Action Gate (Phase G — OFF by default) ────────────────────────────────────
+# Non-bypassable enforcement (firewall + breaker + cost + policy + kill-switch), hash-chained audit,
+# policy-as-code, agent registry/kill-switch, memory RBAC. See docs/governance/GOVERNANCE.md.
+# GOVERNANCE_ENABLED=false                          # master switch (default false → gate is a no-op allow)
+# GOVERNANCE_POLICIES_PATH=/etc/kaiban/policies.yml # optional policy-as-code file (see src/governance/policies.yml)
+
 # ── Security: Redis Channel Signing (optional, strongly recommended in production) ─────────
 # HMAC-SHA256 secret for signing state events on Redis pub/sub. When set, fake state injection
 # from anyone with Redis access is blocked.
@@ -109,13 +146,16 @@ OPENAI_API_KEY=your_openai_api_key_here
 
 # ── Telemetry: OTLP auth (optional) ────────────────────────────
 # When using an authenticated OTLP collector, add an Authorization header:
+# (reserved — not yet wired in code; honored by the OTLP SDK env contract, not parsed by src/)
 # OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <token>
 
 # ── HITL Decision Options ───────────────────────────────────────
 # Comma-separated list of valid human decisions for the HITL gate.
 # The gateway validates incoming board decisions against this list.
-# VIEW is informational only (re-prompts terminal); it does not resolve the gate.
-VALID_HITL_DECISIONS=PUBLISH,REVISE,REJECT,VIEW
+# This matches the code default (src/main/config.ts). Do NOT add VIEW here:
+# VIEW is an interactive terminal-only action that re-prompts the orchestrator
+# prompt — it does not resolve the gate and is NOT a valid board/gateway decision.
+VALID_HITL_DECISIONS=PUBLISH,REVISE,REJECT
 
 # ── Agent Identity (set per-node process / container) ───────────
 # Each agent node reads its own identity from AGENT_ID.
@@ -137,6 +177,11 @@ VALID_HITL_DECISIONS=PUBLISH,REVISE,REJECT,VIEW
 #
 AGENT_ID=researcher
 
+# Public base URL advertised in the A2A AgentCard (/.well-known/agent-card.json).
+# Set this to the gateway's externally-reachable URL for federated deployments
+# behind a public hostname/proxy. Defaults to http://localhost:${PORT}.
+# A2A_PUBLIC_URL=https://agents.example.com
+
 # ── Example Orchestrator Vars (set in docker-compose or shell) ──
 # These are only used by the example orchestrators, not the core library.
 #
@@ -147,6 +192,11 @@ AGENT_ID=researcher
 #   WRITE_WAIT_MS=240000                    # Timeout for write phase (ms)
 #   EDIT_WAIT_MS=300000                     # Timeout for edit phase (ms)
 #
+# WORKFLOW_ID — both example orchestrators read it to namespace the Redis
+# checkpoint (crash-safe resume). Unset → derived from the topic/context, so a
+# restart with the same input RESUMES; set a unique value to force a fresh run.
+#   WORKFLOW_ID=my-run-001
+#
 # Global Research orchestrator:
 #   GATEWAY_URL=http://localhost:3000       # Gateway HTTP endpoint
 #   QUERY=The Future of AI Agents           # Research query
@@ -168,3 +218,9 @@ AGENT_TIMEOUT_MS=300000
 # Max cumulative tokens per AgentStatePublisher instance before it raises an error.
 # Use to cap LLM spend per agent process. 0 = unlimited (default).
 MAX_TOKEN_BUDGET=0
+# Workflow-level spend guard for the example orchestrators (checked between phases
+# and before each revision). Caps the WHOLE workflow's cumulative spend so a runaway
+# (e.g. repeated revisions) stops gracefully instead of draining the budget. The
+# example compose files default MAX_WORKFLOW_COST_USD to 0.50; 0 = unlimited.
+MAX_WORKFLOW_COST_USD=0
+MAX_WORKFLOW_TOKENS=0

.github/workflows/ci.yml

@@ -85,7 +85,10 @@ jobs:
       - name: Dependency audit (fail on HIGH+; moderates triaged in SECURITY.md)
         run: npm audit --audit-level=high
       - name: Generate CycloneDX 1.6 SBOM
-        run: npx --yes @cyclonedx/cyclonedx-npm@latest --output-format JSON --spec-version 1.6 --output-file sbom.json
+        # --ignore-npm-errors: `npm ls` exits non-zero on a harmless dev-only peer
+        # mismatch (madge→precinct wants TypeScript 5.x while the project pins 6.x);
+        # the installed tree is valid, so the SBOM is still complete and accurate.
+        run: npx --yes @cyclonedx/cyclonedx-npm@latest --ignore-npm-errors --output-format JSON --spec-version 1.6 --output-file sbom.json
       - name: Upload SBOM
         uses: actions/upload-artifact@v7
         with:

.github/workflows/release.yml

@@ -29,8 +29,11 @@ jobs:
       - run: npm run test:coverage
       - name: CycloneDX 1.6 SBOM
         run: npx --yes @cyclonedx/cyclonedx-npm@latest --output-format JSON --spec-version 1.6 --output-file sbom.json
-      - name: Pack tarball
-        run: npm pack
+      - name: Pack tarball (from a staging dir → Apache-2.0 LICENSE, no GPL leak)
+        # The published library is Apache-2.0 but the repo root LICENSE is GPL-3.0
+        # (the app/aggregate). `npm pack` force-includes the root LICENSE; pack from
+        # a clean staging dir whose only LICENSE is LICENSE-APACHE. See docs/RELEASE.md.
+        run: bash scripts/pack-staging.sh
       - name: Subject hashes (for provenance)
         id: hash
         run: echo "hashes=$(sha256sum *.tgz sbom.json | base64 -w0)" >> "$GITHUB_OUTPUT"

.gitignore

@@ -10,7 +10,10 @@
 *.swp
 .DS_Store
 
+.agents
 .claude
+.cline
+.clinerules
 .gemini
 .github/skills
 .github/copilot-instructions.md
@@ -22,14 +25,23 @@ coverage
 /agents/
 certs
 runs
+project
+setup-context.sh
 
 # In-repo audit deliverables — kept locally + mirrored in OpenSourceAudit, not published in the repo
 docs/audit/
 
+AGENTS.md
+GEMINI.md
 CHANGES_LOG.md
 CHANGES_GITLOG.md
-
+KAIBAN-v2.0-MASTER-PLAN.md
+BOOTSTRAP_MISSION.md
 
 temp/
 reports/
 .stryker-tmp/
+
+# Phase 4b staging-publish artifacts
+dist-staging/
+*.tgz

CHANGELOG.md

@@ -6,6 +6,95 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [2.0.0] - in progress (`feat/v2.0`)
+
+Major release — breaking changes are documented in `MIGRATION.md`. Authoritative plan:
+`KAIBAN-v2.0-MASTER-PLAN.md`.
+
+### Added
+- **A2A v0.3 federation** via `@a2a-js/sdk`: the gateway answers `message/send`,
+  `message/stream` (SSE), `tasks/get`, `tasks/cancel` on `POST /a2a/rpc`; AgentCard v0.3
+  (object `capabilities` + abilities in `skills[]`). (BETA.1, ADR-015)
+- **MCP server** — first-party Model Context Protocol surface (Tools / Resources / Prompts /
+  Elicitation) over Streamable HTTP. (BETA.2, ADR-017)
+- **Resilience** — the single-active orchestrator is promoted to `src/shared` (reusable, published):
+  Redis checkpoint/resume, liveness/readiness probes, graceful drain, DLQ replay. (BETA.2, ADR-018)
+- **Economics / FinOps** — fleet-wide rate + cost control (token bucket + cost reservation),
+  **default-off**. (BETA.3, ADR-019)
+- **Governance Action Gate** — **default-off, non-bypassable when enabled**: hash-chained audit,
+  policy-as-code, kill-switch; hot-path enforcement wired into `AgentActor`. (BETA.3, ADR-020/021)
+- **Universal AMQP driver seam** — declared `amqplib` seam, unimplemented stub (coverage-excluded).
+  (BETA.1, ADR-016)
+- **`dispatchToAgent`** actor-mailbox primitive in `src/shared` (replaces the removed `tasks.create`
+  RPC). _(The examples also gain a local `parseAgentCardSkills` helper to read v0.3 AgentCards — example
+  code, not a published library export.)_
+- **Workflow budget guard** (`MAX_WORKFLOW_COST_USD` / `MAX_WORKFLOW_TOKENS`) in both example
+  orchestrators — checked between phases and before each revision; **graceful STOPPED on breach**
+  (default `0.50` in the example compose files; `0` = unlimited; separate from per-agent
+  `MAX_TOKEN_BUDGET`).
+- **Playwright visual baselines** for the React board + the two static example viewers
+  (`cd board && npm run test:visual`).
+- **`scripts/smoke-consumer.sh`** — packs the Apache tarball and verifies a fresh consumer can import
+  the public surface from both entry points (`.` and `./shared`).
+- **Packaging:** `./shared` subpath export + two-entry api-extractor; staging-dir `npm pack`
+  (Apache-only artifact, no GPL leak). (BETA.1, ADR-011)
+- **COMPLIANCE** cross-walk and the **v2.1 roadmap**.
+
+### Changed
+- **License (BREAKING):** the published npm library is now **Apache-2.0** (was GPL-3.0); the full
+  application / board / examples remain **GPL-3.0** (dual-license — see `LICENSING.md`, ADR-011).
+- **Dependencies:** KaibanJS 0.24.2, TypeScript 6.0, OpenTelemetry 0.219/0.77, bullmq 5.79, dotenv 17
+  — all latest stable, **0 vulnerabilities** (ADR-012).
+- **gateway / worker ROLE split** — a single image runs as `ROLE=gateway|worker`. (BETA.1, ADR-013)
+- **AbortSignal cancellation** — an in-flight LLM call is aborted on task timeout / `tasks/cancel`
+  (the bridge owns the LLM instance). (BETA.1, ADR-014)
+- **Examples migrated to A2A v0.3** — removed all `tasks.create` / `tasks.get` / `agent.status`
+  usage; both examples dispatch via `dispatchToAgent` and read AgentCard `skills[]`.
+- **Gateway HITL delivery** — the durable per-task BRPOP-list write now precedes the pub/sub
+  publish, and the board is ACK'd only after **both** succeed (a missed pub/sub message stays
+  recoverable via the list fallback).
+- **`CompletionRouter` subscribes lazily** (on the first `wait()`) — a router that never waits no
+  longer consumes the shared completed queue (fixes a competing-consumer hang between the gateway's
+  A2A-executor router and an orchestrator router).
+- **Kafka driver** now throws a clear error on a 2nd `subscribe()` (explicit one-topic-per-driver
+  contract) instead of silently breaking.
+- **BullMQ driver** sets job-retention defaults (`removeOnComplete` / `removeOnFail`, bounding Redis
+  growth) and registers a worker `error` listener.
+- **A2A executor** logs the underlying error server-side on failure (the wire response stays generic).
+
+### Fixed
+- **HITL re-arm loop** — the terminal prompt no longer re-arms after a decision arrives (board OR
+  terminal) or after stdin EOF; fixes the **REVISE** infinite re-prompt spin (100% CPU, process
+  never exits, Ctrl-C ineffective) and restores the second HITL gate on the revised draft.
+- **Board hangs on RUNNING after a hard failure** — both orchestrators now publish a terminal
+  STOPPED state on error, so the board reflects the failure instead of hanging.
+- **Board store** — malformed state deltas with no `agentId` / `taskId` are skipped (the Zustand map
+  is never keyed by `"undefined"`).
+- **Fan-out/fan-in result↔index mismatch** (global-research, plan finding C1/HIGH) — search results
+  are now mapped to their **dispatch** index by `taskId` (was indexed by `waitAll` completion-order
+  position), so searchers that finish out of order get the correct sub-topic, node label and logged
+  taskId.
+- **Governance Action Gate fails closed** on a throwing validator; MCP-without-auth warning.
+- **Byte-accurate data caps** — the 64 KB outbound-message and 20 KB state-event-result caps are now
+  measured in **UTF-8 bytes** (`Buffer.byteLength`), truncating on a codepoint boundary (was UTF-16
+  `.length`, which let multi-byte payloads exceed the byte cap).
+- **Structured agent output** — the KaibanJS bridge now JSON-stringifies a non-string (object) LLM
+  result instead of emitting `"[object Object]"`.
+- **Model-pricing accuracy** — `estimateCost` normalizes OpenRouter slugs / dated suffixes
+  (`openai/gpt-4o-mini`, `gpt-4o-2024-08-06`, `anthropic/claude-3-5-sonnet`) before pricing lookup,
+  and warns on a default-pricing fallback (was exact-match only → slugs silently mis-priced).
+- **Config robustness** — numeric env vars are parsed NaN-safe (`AGENT_TIMEOUT_MS=abc` no longer
+  yields `setTimeout(…, NaN)` / instant timeouts).
+- **Actor robustness** — a timed-out task handler's late rejection no longer surfaces as an
+  `unhandledRejection`.
+- **Global-research budget guard** now runs after **every** phase (search, write, governance,
+  editorial), matching blog-team.
+- A2A input validation hardened; de-stubbed `IDLE` / `TODO` placeholders. (BETA.1)
+
+### Security
+- The published library ships **0 HIGH/CRITICAL advisories**; release flow keeps SBOM + SLSA
+  provenance + cosign signing (ADR-012).
+
 ## [1.5.0-beta] - 2026-06-16
 
 ### Pre-merge hardening pass (audit follow-up)

Dockerfile

@@ -58,8 +58,18 @@ USER kaiban
 ARG PORT=3000
 ENV PORT=${PORT}
 
+# Single image, role chosen at runtime (ADR-013): ROLE=gateway|worker.
+#   gateway → HTTP / WebSocket / A2A front door (exposes /health)
+#   worker  → LLM-backed task-consuming agent pool (no HTTP surface)
+# Default is gateway so the HEALTHCHECK below is valid out of the box; worker
+# deployments override with `-e ROLE=worker` (compose/k8s set it explicitly).
+ARG ROLE=gateway
+ENV ROLE=${ROLE}
+
 EXPOSE ${PORT}
 
+# The /health probe only exists in the gateway role. Worker deployments MUST
+# override or disable this HEALTHCHECK (docker-compose / k8s do).
 HEALTHCHECK --interval=10s --timeout=5s --retries=5 \
   CMD wget -qO- http://localhost:${PORT}/health || exit 1
 

EXAMPLES.md

@@ -407,11 +407,11 @@ docker run -p 3000:3000 \
   kaiban-distributed:latest
 ```
 
-Submit tasks:
+Submit tasks (A2A v0.3 `message/send`; target agent in `metadata.agentId`):
 ```bash
 curl -X POST http://localhost:3000/a2a/rpc \
   -H 'Content-Type: application/json' \
-  -d '{"jsonrpc":"2.0","id":1,"method":"tasks.create","params":{"agentId":"researcher","instruction":"Research AI agent trends 2025","expectedOutput":"A 200-word summary"}}'
+  -d '{"jsonrpc":"2.0","id":1,"method":"message/send","params":{"message":{"kind":"message","role":"user","messageId":"m1","parts":[{"kind":"text","text":"Research AI agent trends 2025"}],"metadata":{"agentId":"researcher","expectedOutput":"A 200-word summary"}}}}'
 ```
 
 ---
@@ -421,20 +421,31 @@ curl -X POST http://localhost:3000/a2a/rpc \
 ```bash
 # Unit tests (no Docker, all mocked)
 npm test
-# → 769 unit tests, 77 files, 100% coverage of src (+146 board tests via `cd board && npm test`)
+# → 108 unit-test files / 1155 tests, 100% coverage of src (board tests run separately via `cd board && npm test`)
 
 # BullMQ E2E (Docker auto-starts Redis)
 npm run test:e2e
-# → 65 tests: task execution, fault tolerance, state sync, A2A protocol
+# → 69 tests: task execution, fault tolerance, state sync, A2A protocol, completion routing
 
 # Kafka E2E (requires Kafka — starts automatically)
 npm run test:e2e:kafka
 # → 3 tests: publish-subscribe round-trip, unsubscribe
 
+# Playwright visual baselines of the board + example viewers (needs the board dev server + gateway)
+cd board && npm run test:visual   # add :update to regenerate baselines
+
 # All quality gates at once
 npm run lint && npm run typecheck && npm run test:coverage
 ```
 
+> **Runaway-spend guard.** Both example orchestrators enforce a workflow-level
+> budget after **every** phase (blog-team: research/write/edit; global-research:
+> search/write/governance/editorial) and before each revision, via
+> `MAX_WORKFLOW_COST_USD` (default `0.50` in the example compose files) and
+> `MAX_WORKFLOW_TOKENS` (`0` = unlimited). On breach the workflow stops gracefully
+> (STOPPED) instead of draining the budget. This is separate from the per-agent
+> `MAX_TOKEN_BUDGET`.
+
 ---
 
 ## Example 5 — Monitor All Streams
@@ -560,7 +571,7 @@ interactive Human-in-the-Loop Approve / Revise / Reject controls.
 ### Prerequisites
 
 - Any kaiban-distributed gateway running (e.g. `./scripts/blog-team.sh start`)
-- Node.js ≥ 18 (board only; gateway still needs ≥ 22)
+- Node.js ≥ 20.19 (board uses Vite 8, which needs Node 20.19+/22.12+; gateway needs ≥ 22)
 
 ### Start