mirror of
https://github.com/ruvnet/ruflo.git
synced 2026-09-14 14:01:28 +08:00
v3.38.21
4 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 rUv
|
ef73a1616f |
feat(ruflo-agent): rename ruflo-wasm → ruflo-agent + Claude Managed Agents (cloud) runtime — ADR-115 (proposed→accepted, implemented) (#1929)
* docs(adr): ADR-115 — Claude Managed Agents as a cloud backend for rvagent (explored + validated)
Records the proposal to add `runtime: "managed"` to ruflo's rvagent
interface (ruflo-wasm / @ruvector/rvagent-wasm / wasm_agent_* MCP tools),
backed by Anthropic's Claude Managed Agents API (beta), as a second backend
alongside the local WASM sandbox — mirroring the ConsensusTransport
LocalTransport|FederationTransport pattern (ADR-095 G2 / ADR-104). The
agent/environment/session/events model maps ~1:1 to wasm_agent_create/
prompt/files/terminate + the gallery.
Validated live against api.anthropic.com/v1 with the org's Anthropic key
(GCP claude-flow/anthropic-api-key): created an agent + environment + session,
sent a bash task, observed the full event log (status_running → user.message
→ tool_use(bash) → tool_result → agent.message("Done.") → status_idle,
stop_reason end_turn), cleaned up. ~7s for a trivial Haiku task.
High-value combos noted: ruflo's own MCP server as a Managed Agent tool
source (cloud-hosted ruflo, zero local infra); Managed Agent session as a
third task_assign executor (closes #1916 items 3/4); long-running/async work;
skills + define-outcomes parity. Constraints: opt-in/off-by-default, needs
ANTHROPIC_API_KEY + beta access, plugin-level @anthropic-ai/sdk dep,
cost-tracking + orphaned-session GC, beta churn, branding.
Status: proposed. Registered in AgentDB (adr-ADR-115) + adr-patterns.
Co-Authored-By: RuFlo <ruv@ruv.net>
* refactor(plugins): rename ruflo-wasm → ruflo-agent (agent-runtimes home; ADR-115 prep)
`ruflo-wasm` only covered local WASM-sandboxed agents (rvagent —
@ruvector/rvagent-wasm, the wasm_agent_*/wasm_gallery_* MCP tools). It's
becoming the home for *all* ruflo agent runtimes: the existing local-WASM
backend plus Anthropic's Claude Managed Agents as a cloud backend (ADR-115),
behind one interface — same local-vs-cloud pattern as ConsensusTransport.
- git mv plugins/ruflo-wasm → plugins/ruflo-agent
- plugin.json: name ruflo-wasm → ruflo-agent; description/keywords now span
both runtimes (rvagent/wasm + managed-agents/anthropic/cloud)
- .claude-plugin/marketplace.json entry renamed
- README / plugins/README / docs/index / cli README / ruflo README /
discover-plugins SKILL / verification/inventory.json / ADR-115 — refs updated
- wasm_agent_* / wasm_gallery_* MCP tool names are unchanged (they stay; the
plugin is just renamed). managed_agent_* tools land next per ADR-115.
(Left `ruflo-wasm-mcp` in ruvocal/workerClient.ts alone — unrelated worker MCP name.)
Co-Authored-By: RuFlo <ruv@ruv.net>
* feat(cli): managed_agent_* MCP tools — Claude Managed Agents cloud runtime (ADR-115)
Six new MCP tools wrapping Anthropic's Claude Managed Agents REST API (beta,
`anthropic-beta: managed-agents-2026-04-01`) via plain fetch — no new SDK dep:
managed_agent_create agents.create + environments.create + sessions.create ↔ wasm_agent_create (CLOUD counterpart)
managed_agent_prompt events.send(user.message) + poll events until idle ↔ wasm_agent_prompt
managed_agent_status GET /v1/sessions/{id}
managed_agent_events GET /v1/sessions/{id}/events (full transcript) ↔ wasm_agent_files
managed_agent_list GET /v1/sessions
managed_agent_terminate DELETE /v1/sessions/{id} (+ optionally the env) ↔ wasm_agent_terminate
Needs ANTHROPIC_API_KEY (or CLAUDE_API_KEY); every tool degrades gracefully
with a structured "use wasm_agent_* for a local no-key runtime" error when the
key is absent — the CLI/MCP server stays up. ADR-112-compliant descriptions
(each says when wasm_agent_* / native is the right call instead). Registered
in mcp-client.ts. Lives conceptually in the `ruflo-agent` plugin (the
`ruflo-wasm`→`ruflo-agent` rename in the prior commit).
Validated live against api.anthropic.com with the org's Anthropic key (GCP
claude-flow/anthropic-api-key) via `ruflo mcp exec -t managed_agent_*`:
create (haiku) → prompt ("echo … > /tmp/r.txt && cat") → got finished:true,
status:idle, stopReason:end_turn, assistantText:"Done.", toolUses:[bash],
13 events → terminate (sessionDeleted+environmentDeleted). No-key path returns
the graceful error. audit-cli-mcp-tools 311 registered/0 dangling;
audit-tool-descriptions 0 no-guidance; cli build clean.
Co-Authored-By: RuFlo <ruv@ruv.net>
* feat(ruflo-agent): wire the managed-agent (cloud) runtime into the plugin + CI smoke
- skills/managed-agent/SKILL.md — drives the cloud runtime: managed_agent_create
/ prompt / status / events / list / terminate, with the WASM-vs-managed
decision table, the ANTHROPIC_API_KEY prereq + graceful fallback, the
mcpServers-reachability caveat, and the cost/cleanup discipline (a cloud
session bills until terminated). Explicit allowed-tools (no wildcard).
- commands/managed-agent.md — quick "list cloud sessions / status / transcript
/ clean up" command (the cloud sibling of /wasm).
- plugin.json — kept rvagent-wasm + ruvllm-wasm keywords (still built on those);
added managed-agents/anthropic/cloud.
- smoke.sh: step 1 now also asserts name=ruflo-agent + the managed-agents
keywords; step 10 expects ADR-0001 status `Accepted` (was stale `Proposed`,
pre-existing red); new step 12 — managed-agent skill+command exist + all 6
managed_agent_* tools referenced + the skill keeps an explicit allowed-tools
list + offers the wasm_agent_create fallback. 12 passed / 0 failed.
- .github/workflows/ruflo-agent-smoke.yml — new CI job running smoke.sh on any
plugins/ruflo-agent/** change (the plugin had no CI gate before).
Validated: `claude --plugin-dir plugins/ruflo-agent` loads the plugin and lists
its skills (managed-agent, wasm-agent, wasm-gallery); plugin.json + all skill
frontmatters parse; smoke.sh 12/0.
Co-Authored-By: RuFlo <ruv@ruv.net>
* docs(adr): ADR-115 → Accepted + Implementation section (managed_agent_* landed)
Status Proposed → Accepted. Added an Implementation (2026-05-12) section:
the ruflo-wasm→ruflo-agent rename, the 6 managed_agent_* MCP tools (plain
fetch, no new SDK dep, graceful no-key degradation, ADR-112 descriptions),
the managed-agent skill+command, the smoke.sh/ruflo-agent-smoke.yml CI guard,
the live e2e validation (create→prompt→terminate against api.anthropic.com
with the GCP anthropic-api-key) and `claude --plugin-dir` validation, and the
called-out follow-ups (runtime:"managed" unification, deployed HTTP ruflo MCP
server for the cloud-hosted-ruflo combo, task_assign/federation dispatch to a
Managed Agent session, cost-tracking + orphaned-session GC, multiagent/outcomes).
Tracking issue: #1931.
Co-Authored-By: RuFlo <ruv@ruv.net>
* test(cli): no-network guard for managed_agent_* tools (ADR-115)
__tests__/managed-agent-tools.test.ts (10 cases): the 6 managed_agent_*
tools are registered; each has an object inputSchema + a ≥80-char,
ADR-112-ish, unique description that names the wasm_agent_*/native fallback;
and — crucially — every handler degrades gracefully with no ANTHROPIC_API_KEY/
CLAUDE_API_KEY: no throw, structured error mentioning the key + the
wasm_agent_create fallback, no network call (so the CLI/MCP server stays up
offline). Plus managed_agent_prompt's missing-sessionId/message validation.
Co-Authored-By: RuFlo <ruv@ruv.net>
* docs(adr): ADR-115 — add the third runtime (Claude Agent SDK) to the picture
ADR-115 adds the *cloud* runtime (Managed Agents); add a section noting the
natural *third* runtime — the Claude Agent SDK (@anthropic-ai/claude-agent-sdk,
"Claude Code as a library": query()/ClaudeSDKClient, hooks, subagents, MCP,
permission modes, sessions, loads .claude/ config + plugins; runs in-process,
full host trust). ruflo-agent → three runtimes behind one model:
WASM (rvagent) local sandbox, no host fs/net untrusted/portable/offline
SDK (future) your process, your filesystem a real Claude agent loop on the local repo — the in-process `claude -p`
Managed Anthropic cloud container long-running/async, no local infra
The SDK runtime's killer combo: `mcpServers: { ruflo: { command: "npx", args: ["ruflo","mcp","start"] } }` — a *local* stdio MCP server, so the agent gets ruflo's 314 tools with zero deployment (vs Managed Agents needing a reachable URL). Anthropic positions SDK→Managed as prototype→production. Costs: heavy dep (bundles a Claude Code binary), full host trust (no sandbox — least isolated), needs an API key. Implementing it = a follow-up, likely ADR-116 (tracked in #1931).
Co-Authored-By: RuFlo <ruv@ruv.net>
---------
Co-authored-by: Reuven <cohen@ruv-mac-mini.local>
|
||
|
rUv
|
8aac1b2ccc |
feat(mcp): ADR-112 — 285/285 tool descriptions have 'Use when …' guidance + CI guard + #1892 statusline (#1897)
* docs(adr-095): status update — G1/G3/G4/G6/benchmark remediated (verification receipts)
External re-audit (AlphaSignal AI, May 7) surfaced ADR-095 gaps publicly.
Verification pass on current main shows 4 of 7 named gaps already
quietly fixed by the v3.7.0-alpha work:
G1 — agent_spawn intentionally registry-only; real execution wire is
agent_execute → agent-execute-core.ts:117 → Anthropic Messages API
G3 — workflow_execute has a real step executor (workflow-tools.ts:308+);
the 'Workflow not found' error is correct missing-ID handling
G4 — promptWasmAgent (agent-wasm.ts:154) detects echo stub + routes
through callAnthropicMessages when ANTHROPIC_API_KEY set
G6 — refuted via direct measurement: hook is a single routing call,
no trigram/Jaccard symbols, 8 backend entries observed
Bench — simulate_benchmarks.py removed; '84.8% SWE' claim cleaned
from tracked docs
Preserves original ADR text. Adds 'Status update — 2026-05-11' section
at the bottom with file-path receipts. Still open: G2, G5 (→ADR-094),
G7 (per-controller), #1748 (tool descriptions).
Related: #1896 (external audit response)
Co-Authored-By: RuFlo <ruv@ruv.net>
* feat(mcp): ADR-112 — every tool description now has "Use when … is wrong because …" guidance + CI guard + #1892 statusline fix
External audit (AlphaSignal AI, May 7) measured 237/300 MCP tool
descriptions lacked guidance for when Claude should pick Ruflo's tool
over native (Bash/Read/Grep/Glob/Task/TodoWrite). Re-measurement on
current main was actually 279/285 — worse. Now: 0/285.
## ADR-112 + bulk fix
- New ADR documenting the rule: every description must answer
"use this over native when?" with concrete value-add (cost
attribution / learning persistence / coordination / witness chain /
sandbox isolation), and honestly state when native is fine.
- 7 agent-tools.ts descriptions hand-edited (the P1 native-Task overlap).
- 272 remaining descriptions bulk-updated via category-aware suffixes
in scripts/bulk-fix-tool-descriptions.mjs — each tool category
(memory/agentdb/embeddings/swarm/hive-mind/hooks/workflow/browser/
cost/intelligence/aidefence/security/federation/iot/wasm/ruvllm/
config/system/mcp/status/doctor/performance/analyze/progress/transfer/
guidance/claims/terminal/daemon/causal/graph/reasoningbank/search)
gets its own honest "Use when … is wrong because …" suffix.
## CI guard (every tool's description checked)
- scripts/audit-tool-descriptions.mjs scans every MCPTool definition and
enforces three gates per tool:
1. "Use when ..." guidance present (the original ADR-112 check)
2. Description length ≥ 80 chars (catches near-empty descriptions)
3. Description unique across all tools (catches lazy copy-paste)
All three baselines stored in verification/mcp-tool-baseline.json
and are monotone-decreasing — CI fails on any regression.
- .github/workflows/v3-ci.yml gains a `tool-descriptions-audit` job
wired into witness-verify needs[] so the release pipeline gates on it.
## #1892 — UI version mismatch
- v3/@claude-flow/cli/.claude/helpers/statusline.js was hardcoded
to "RuFlo V3.5"; now reads from installed @claude-flow/cli's
package.json at runtime via resolveBannerVersion() so the UI matches
`ruflo doctor` output. Resolves across local-checkout / npm-installed /
globally-installed layouts.
## Witness manifest
- verification/witness-fixes.json: ADR-111, ADR-112, #1892 markers added.
- verification/macos/manifest.md.json regen'd — 102/102 fixes verified,
Ed25519 signature valid.
## Tests
- 1963 federation+cli tests pass on this branch.
- Build clean.
- Audit: 285/285 tools with guidance, 0 too-short, 0 duplicates.
Resolves #1748 (tool discoverability)
Resolves #1892 (UI version mismatch)
Tracks #1896 (external audit response)
Co-Authored-By: RuFlo <ruv@ruv.net>
* docs(verification): README — current 102/102 fix count + ADR-112 baseline + Layer 1 smoke jobs
- Folder layout adds mcp-tool-baseline.json (ADR-112)
- Example manifest summary updated 82→102 fixes, alpha.18→alpha.21
- Manifest schema example: added missing 'signature' field
- Integration table expanded with the 5 Layer 1 smoke jobs that exist
today: install, hook, mcp-protocol, memory-import, tool-descriptions
Co-Authored-By: RuFlo <ruv@ruv.net>
* chore(verification): lock ADR-112 baseline at all-zeros for noGuidance, tooShort, duplicates
The enhanced audit-tool-descriptions.mjs now tracks three gates instead
of one. Baseline file was carrying only the original noGuidance count;
running --update-baseline writes all three so future regressions in
any gate fail CI.
Co-Authored-By: RuFlo <ruv@ruv.net>
* ci: fix Performance Verification — download phantom artifact
Long-standing latent bug masked by download-artifact@v3's warning
behavior, surfaced as a hard error by @v4. The job tried to download
build-artifacts-<verification-id> but no job in the workflow has
ever uploaded an artifact under that name; build-verification only
runs npm pack and uploads nothing.
Fix: build the CLI locally inside the perf job (same pattern the
other jobs use) instead of relying on a phantom artifact. Memory-leak
smoke now probes the v3 cli dist binary with a graceful fallback if
the build skipped — keeps the job informational, not blocking.
Affected run: https://github.com/ruvnet/ruflo/actions/runs/25648092044
Triggered by main push of
|
||
|
Reuven
|
7ed18b8335 |
feat: upgrade neural-trader, ruvector, rag-memory plugins to wrap npm packages
- ruflo-neural-trader: wrap npx neural-trader (v2.7+), add market-analyst and backtest-engineer agents, add trader-regime/train/risk skills (4 agents, 6 skills) - ruflo-ruvector: wrap npx ruvector — FlashAttention-3, Graph RAG, hybrid search, DiskANN, 103 MCP tools, Brain AGI - ruflo-rag-memory: SOTA upgrade — hybrid search (sparse+dense RRF), Graph RAG multi-hop, MMR diversity, adaptive chunking, consolidation - plugins/README.md: add npm package integration section Co-Authored-By: claude-flow <ruv@ruv.net> |
||
|
Reuven
|
f25bcf2073 |
feat: add 10 new ruflo plugins, optimize all 32, add READMEs and user guide
New plugins: ruflo-adr (ADR lifecycle), ruflo-ddd (domain-driven design), ruflo-sparc (SPARC methodology), ruflo-neural-trader (trading strategies), ruflo-ruvector (vector embeddings), ruflo-knowledge-graph (entity graphs), ruflo-market-data (OHLCV ingestion), ruflo-migrations (schema management), ruflo-observability (logging/tracing), ruflo-cost-tracker (token budgets). Optimizations across all 32 plugins: - All pass `claude plugin validate` (removed invalid manifest arrays) - 51/51 skills have argument-hint frontmatter - Model routing: 4 haiku, 24 sonnet, 2 opus (cost-optimized) - Neural learning hooks on 25/30 agents - Cross-references between 6 related plugin pairs - Pathfinder graph traversal algo for researcher agent - READMEs for all 32 plugins + plugins/README.md catalog - discover-plugins skill updated with full 32-plugin catalog Co-Authored-By: claude-flow <ruv@ruv.net> |