π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
fix(cli,ruflo-knowledge-graph): causal-edge says when an edge cannot be read back under encryption at rest; kg-traverse uses the read tools (#4135, #4161)
r866f844483f0
diff --git a/plugins/ruflo-knowledge-graph/.claude-plugin/plugin.json b/plugins/ruflo-knowledge-graph/.claude-plugin/plugin.jsonindex 9a200366ef..46b05fb235 100644--- a/plugins/ruflo-knowledge-graph/.claude-plugin/plugin.json+++ b/plugins/ruflo-knowledge-graph/.claude-plugin/plugin.json@@ -1,7 +1,7 @@{"name": "ruflo-knowledge-graph","description": "Knowledge graph construction β entity extraction, relation mapping, and pathfinder graph traversal. As a mod (ADR-445): keeps secrets out of the graph, confirms graph deletes, /kg-mod, and a status file the console shows",- "version": "0.3.5",+ "version": "0.3.6","author": {"name": "ruvnet","url": "https://github.com/ruvnet"diff --git a/plugins/ruflo-knowledge-graph/CHANGELOG.md b/plugins/ruflo-knowledge-graph/CHANGELOG.mdindex 1d15035727..2db9628d2f 100644--- a/plugins/ruflo-knowledge-graph/CHANGELOG.md+++ b/plugins/ruflo-knowledge-graph/CHANGELOG.md@@ -2,6 +2,9 @@Newest first. One `## <version> β <date>` heading per version, then `feat:`, `fix:`, `breaking:` and `chore:` bullets (ADR-478). Built from git history; this is the whole history.+## 0.3.6 β 2026-10-14+- fix: kg-traverse reads edges with `agentdb_graph-query` (k-hop) and `agentdb_graph-pathfinder`, not the write-only `agentdb_causal-edge`; it no longer calls `agentdb_context-synthesize` (entity records are not validated task episodes, so it always answered `no-eligible-episodes`) and says what to do when encryption at rest (RFE1) makes the graph unreadable; the graph-navigator agent lists the same read tools (#4135, #4161, thanks @ronmikailov)+## 0.3.5 β 2026-10-12- fix: the shared text screen now catches `.env` and e-mailed credentials, no longer flags a model's token talk (`--max-tokens`, `/oauth/token`, "token usage"), and no longer flags values that only name where a secret lives (`./service-account.json`, `--set-secrets=NAME=NAME:latest`); every rule stays linear (#4094, thanks @proffesor-for-testing)diff --git a/plugins/ruflo-knowledge-graph/agents/graph-navigator.md b/plugins/ruflo-knowledge-graph/agents/graph-navigator.mdindex e4afaade5f..2b394a14d2 100644--- a/plugins/ruflo-knowledge-graph/agents/graph-navigator.md+++ b/plugins/ruflo-knowledge-graph/agents/graph-navigator.md@@ -40,20 +40,22 @@ You are a knowledge graph navigator agent. Your responsibilities:The pathfinder traversal algorithm finds relevant subgraphs:1. **Seed** -- start from the target entity node-2. **Expand** -- follow causal edges outward (configurable depth, default 3)+2. **Expand** -- follow edges outward with `agentdb_graph-query` mode `k-hop` (configurable depth, default 3)3. **Score** -- compute relevance = edge_weight * semantic_similarity(query, node)4. **Prune** -- remove paths with cumulative score below threshold (default 0.3)5. **Rank** -- return top-K paths sorted by cumulative relevance score### Tools-- `mcp__plugin_ruflo-core_ruflo__agentdb_causal-edge` -- create/query causal edges between entities+- `mcp__plugin_ruflo-core_ruflo__agentdb_causal-edge` -- record a causal edge between entities (write only: it never reads edges back; a `readable: false` result means encryption at rest (RFE1) is on and graph reads cannot open the store)+- `mcp__plugin_ruflo-core_ruflo__agentdb_graph-query` -- read edges: `{ nodeId: "entity:NAME", mode: "k-hop", depth }` (also `pagerank`, `semantic`)+- `mcp__plugin_ruflo-core_ruflo__agentdb_graph-pathfinder` -- scored path search `{ seedNodeId, query, depth, threshold, topK }`- `mcp__plugin_ruflo-core_ruflo__agentdb_hierarchical-store` -- store entity metadata in hierarchical structure- `mcp__plugin_ruflo-core_ruflo__agentdb_hierarchical-recall` -- recall entities by path or query- `mcp__plugin_ruflo-core_ruflo__agentdb_semantic-route` -- semantic similarity routing for graph search (note: `semanticRouter` controller is `enabled: false` in current AgentDB builds β fall back to `agentdb_pattern-search` or `embeddings_generate` + manual cosine; see ruvnet/ruflo#2049)- `mcp__plugin_ruflo-core_ruflo__agentdb_pattern-store` -- store discovered graph patterns- `mcp__plugin_ruflo-core_ruflo__agentdb_pattern-search` -- search for similar graph structures-- `mcp__plugin_ruflo-core_ruflo__agentdb_context-synthesize` -- synthesize context from multiple graph nodes+- `mcp__plugin_ruflo-core_ruflo__agentdb_context-synthesize` -- summarizes validated task episodes only; it answers `no-eligible-episodes` for entity records, so summarize traversal paths yourself- `mcp__plugin_ruflo-core_ruflo__embeddings_generate` -- generate embeddings for entity descriptions### Neural Learningdiff --git a/plugins/ruflo-knowledge-graph/scripts/smoke.sh b/plugins/ruflo-knowledge-graph/scripts/smoke.shindex e15e34af04..cdfa685f69 100755--- a/plugins/ruflo-knowledge-graph/scripts/smoke.sh+++ b/plugins/ruflo-knowledge-graph/scripts/smoke.sh@@ -7,9 +7,9 @@ step() { printf "β %s ... " "$1"; }ok() { printf "PASS\n"; PASS=$((PASS+1)); }bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }-step "1. plugin.json declares 0.3.5 with new keywords"+step "1. plugin.json declares 0.3.6 with new keywords"v=$(grep -E '"version"' "$ROOT/.claude-plugin/plugin.json" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)-if [[ "$v" != "0.3.5" ]]; then bad "expected 0.3.5, got '$v'"; else+if [[ "$v" != "0.3.6" ]]; then bad "expected 0.3.6, got '$v'"; elsemiss=""for k in mcp pathfinder-traversal entity-extraction; dogrep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"diff --git a/plugins/ruflo-knowledge-graph/skills/kg-traverse/SKILL.md b/plugins/ruflo-knowledge-graph/skills/kg-traverse/SKILL.mdindex a4a794a9da..40b2eda07d 100644--- a/plugins/ruflo-knowledge-graph/skills/kg-traverse/SKILL.md+++ b/plugins/ruflo-knowledge-graph/skills/kg-traverse/SKILL.md@@ -2,12 +2,12 @@name: kg-traversedescription: Pathfinder traversal of the knowledge graph starting from a seed entityargument-hint: "<entity> [--depth N]"-allowed-tools: mcp__plugin_ruflo-core_ruflo__agentdb_hierarchical-recall mcp__plugin_ruflo-core_ruflo__agentdb_causal-edge mcp__plugin_ruflo-core_ruflo__agentdb_pattern-search mcp__plugin_ruflo-core_ruflo__agentdb_context-synthesize Bash+allowed-tools: mcp__plugin_ruflo-core_ruflo__agentdb_hierarchical-recall mcp__plugin_ruflo-core_ruflo__agentdb_graph-query mcp__plugin_ruflo-core_ruflo__agentdb_graph-pathfinder mcp__plugin_ruflo-core_ruflo__agentdb_pattern-search Bash---# KG Traverse-Perform pathfinder graph traversal starting from a seed entity. Expands outward through causal edges, scores paths by relevance, and prunes low-similarity branches.+Perform pathfinder graph traversal starting from a seed entity. Expands outward through the graph's edges, scores paths by relevance, and prunes low-scoring branches.## When to use@@ -15,13 +15,15 @@ When you need to explore the knowledge graph starting from a specific entity --## Steps-1. **Seed** -- call `mcp__plugin_ruflo-core_ruflo__agentdb_hierarchical-recall` to look up the target entity by name-2. **Expand** -- call `mcp__plugin_ruflo-core_ruflo__agentdb_causal-edge` to find all edges connected to the seed entity, then recursively expand outward to the specified depth (default: 3)-3. **Score** -- for each path, compute relevance: `cumulative_score = product(edge_weight * keyword_similarity(query, node))` using `mcp__plugin_ruflo-core_ruflo__agentdb_pattern-search` (the `semanticRouter` controller is `enabled: false` in current AgentDB builds; pattern-search is the available substitute and works fine for entity-name + relation-type keyword matches β see ruvnet/ruflo#2049). For higher-fidelity semantic similarity, callers can fall back to `mcp__plugin_ruflo-core_ruflo__embeddings_generate` + manual cosine, but that's not required for step 3 to function.-4. **Prune** -- remove paths with cumulative score below 0.3-5. **Rank** -- sort remaining paths by cumulative score descending-6. **Synthesize** -- call `mcp__plugin_ruflo-core_ruflo__agentdb_context-synthesize` to combine the top paths into a coherent summary-7. **Report** -- display the top 10 paths with: path (entity chain), relation types, cumulative score, and synthesized context+1. **Seed** -- call `mcp__plugin_ruflo-core_ruflo__agentdb_hierarchical-recall` to look up the target entity by name (one word is the most reliable query: the recall matches the whole query as a substring). Graph node ids are domain-prefixed, for example `entity:router-account`.+2. **Expand** -- call `mcp__plugin_ruflo-core_ruflo__agentdb_graph-query` with `{ nodeId: "entity:NAME", mode: "k-hop", depth: N }` (default depth 3, the SQL path applies at most 3 and reports `appliedDepth` and `truncated`; add `relation` to filter by relation type). `agentdb_causal-edge` only records an edge, never use it to read one.+3. **Score and rank** -- call `mcp__plugin_ruflo-core_ruflo__agentdb_graph-pathfinder` with `{ seedNodeId: "entity:NAME", query: "<what the user wants to know>", depth: N, threshold: 0.3, topK: 10 }`. It expands from the seed, scores each path by cumulative relevance, drops paths under the threshold and returns the top paths. If it returns nothing useful, score the k-hop neighbours yourself with `mcp__plugin_ruflo-core_ruflo__agentdb_pattern-search` on entity names and relation types (the `semanticRouter` controller is `enabled: false` in current AgentDB builds; see ruvnet/ruflo#2049).+4. **Synthesize** -- write the summary yourself from the returned paths. Do not call `agentdb_context-synthesize`: it summarizes validated task episodes and answers `no-eligible-episodes` for entity records written by `kg-extract`.+5. **Report** -- display the top 10 paths with: path (entity chain), relation types, cumulative score, and your summary.++## When the graph cannot be read++With `CLAUDE_FLOW_ENCRYPT_AT_REST=1` the graph read tools answer `graph_edges DB is encrypted at rest (RFE1)` (#2889, #4135): edges recorded by `kg-extract` are stored but cannot be read back yet. Say so in the report. Your data is intact: do not run `memory init`. Fall back to the entity records only (`agentdb_hierarchical-recall`) and tell the user that relations are unavailable. An `agentdb_causal-edge` result with `readable: false` already warns about this at write time.## CLI alternativediff --git a/v3/@claude-flow/cli/__tests__/causal-edge-unreadable-under-encryption-4135.test.ts b/v3/@claude-flow/cli/__tests__/causal-edge-unreadable-under-encryption-4135.test.tsnew file mode 100644index 0000000000..be7673b702--- /dev/null+++ b/v3/@claude-flow/cli/__tests__/causal-edge-unreadable-under-encryption-4135.test.ts@@ -0,0 +1,59 @@+/**+ * #4135 / #4161: with encryption at rest on, agentdb_causal-edge writes to the graph-node+ * backend and reports success, but the read tools (graph-query, graph-pathfinder) need+ * the RFE1-encrypted graph_edges database and refuse. The write must say so instead of+ * implying the edge can be read back, and k-hop must report the real reason.+ */+import { beforeEach, describe, expect, it, vi } from 'vitest';++let encrypted = false;++vi.mock('../src/ruvector/graph-backend.js', () => ({+ isGraphBackendAvailable: async () => true,+ recordCausalEdge: async () => ({ success: true, backend: 'graph-node' }),+}));+vi.mock('../src/memory/memory-bridge.js', () => ({+ bridgeRecordCausalEdge: async () => ({ success: true }),+}));+vi.mock('../src/memory/memory-initializer.js', () => ({+ generateEmbedding: async () => null,+}));+vi.mock('../src/memory/graph-edge-writer.js', () => ({+ isBridgeDbEncryptedAtRest: () => encrypted,+ getBridgeDb: async () => null,+ insertGraphEdge: async () => undefined,+}));++const edge = { sourceId: 'entity:router-account', targetId: 'entity:account-service', relation: 'imports', weight: 0.9 };++describe('agentdb_causal-edge when the graph cannot be read back (#4135)', () => {+ beforeEach(() => { encrypted = false; });++ it('flags the write as unreadable when graph_edges is encrypted at rest', async () => {+ encrypted = true;+ const { agentdbCausalEdge } = await import('../src/mcp-tools/agentdb-tools.js');+ const result = await agentdbCausalEdge.handler(edge) as Record<string, unknown>;+ expect(result.success).toBe(true);+ expect(result.readable).toBe(false);+ expect(String(result.warning)).toMatch(/encrypted at rest/i);+ expect(String(result.warning)).toMatch(/graph-query|graph-pathfinder/);+ });++ it('does not add the warning on a readable (unencrypted) store', async () => {+ encrypted = false;+ const { agentdbCausalEdge } = await import('../src/mcp-tools/agentdb-tools.js');+ const result = await agentdbCausalEdge.handler(edge) as Record<string, unknown>;+ expect(result.success).toBe(true);+ expect(result.readable).not.toBe(false);+ expect(result.warning ?? '').not.toMatch(/encrypted at rest/i);+ });++ it('k-hop names the encrypted store, not a generic unavailable backend', async () => {+ encrypted = true;+ const { agentdbGraphQuery } = await import('../src/mcp-tools/agentdb-tools.js');+ const result = await agentdbGraphQuery.handler({ nodeId: 'entity:router-account', mode: 'k-hop', depth: 2 }) as Record<string, unknown>;+ expect(result.success).toBe(false);+ expect(String(result.error)).toMatch(/encrypted at rest \(RFE1\)/);+ expect(String(result.error)).not.toMatch(/Retained SQL graph_edges backend is unavailable/);+ });+});diff --git a/v3/@claude-flow/cli/src/mcp-tools/agentdb-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/agentdb-tools.tsindex b43e43ee30..98157b08a4 100644--- a/v3/@claude-flow/cli/src/mcp-tools/agentdb-tools.ts+++ b/v3/@claude-flow/cli/src/mcp-tools/agentdb-tools.ts@@ -98,6 +98,19 @@ async function bridgeUnavailableResult(): Promise<{ error: string; hint: stringhint: 'Check Node version + try `ruflo memory init` to initialize manually.',};}+// #4135 / #4161: graph reads (agentdb_graph-query, agentdb_graph-pathfinder) open the+// graph_edges database; under encryption at rest that file is an RFE1 blob they cannot+// open. A recorded edge is then unreadable even though the write reports success, so the+// write says so instead of letting a caller assume it can read the edge back.+async function unreadableEdgeWarning(): Promise<string | undefined> {+ try {+ const { isBridgeDbEncryptedAtRest } = await getGraphEdgeWriter();+ if (!isBridgeDbEncryptedAtRest()) return undefined;+ return 'Edge recorded, but graph reads (agentdb_graph-query, agentdb_graph-pathfinder) cannot open the graph_edges database because it is encrypted at rest (RFE1), so this edge cannot be read back yet. Your data is intact (#2889, #4135).';+ } catch {+ return undefined;+ }+}let memInitMod: typeof import('../memory/memory-initializer.js') | null = null;async function getMemInit() {if (!memInitMod) memInitMod = await import('../memory/memory-initializer.js');@@ -568,7 +581,9 @@ export const agentdbCausalEdge: MCPTool = {// Also record in AgentDB bridge for compatibilityconst bridge = await getBridge();await bridge.bridgeRecordCausalEdge({ sourceId, targetId, relation, weight: typeof params.weight === 'number' ? validateScore(params.weight, 0.5) : undefined }).catch(() => {});- return { ...graphResult, _graphNodeBackend: true, ...(legacyWarning && { warning: legacyWarning }) };+ const unreadable = await unreadableEdgeWarning();+ const warning = [legacyWarning, unreadable].filter(Boolean).join(' ');+ return { ...graphResult, _graphNodeBackend: true, ...(unreadable && { readable: false }), ...(warning && { warning }) };}}} catch { /* graph-node not available, fall through */ }@@ -581,7 +596,9 @@ export const agentdbCausalEdge: MCPTool = {weight: typeof params.weight === 'number' ? validateScore(params.weight, 0.5) : undefined,});const baseResult = result ?? { success: false, error: 'AgentDB bridge not available. Use memory_store/memory_search instead.' };- return legacyWarning ? { ...baseResult, warning: legacyWarning } : baseResult;+ const unreadable = baseResult.success === false ? undefined : await unreadableEdgeWarning();+ const warning = [legacyWarning, unreadable].filter(Boolean).join(' ');+ return warning ? { ...baseResult, ...(unreadable && { readable: false }), warning } : baseResult;} catch (error) {return { success: false, error: sanitizeError(error) };}@@ -1138,6 +1155,9 @@ export const agentdbGraphQuery: MCPTool = {} catch (error) {return { success: false, error: `Retained SQL graph query failed: ${sanitizeError(error)}`, mode, nodeId };}+ // #4135: name the real reason when the retained store is encrypted at rest.+ const encryptedAtRest = await getGraphEdgeWriter().then((w) => w.isBridgeDbEncryptedAtRest()).catch(() => false);+ if (encryptedAtRest) return { success: false, ...(await bridgeUnavailableResult()), mode, nodeId };return { success: false, error: 'Retained SQL graph_edges backend is unavailable for k-hop query', mode, nodeId };}