archgraph-argo 0.24.2 → 0.25.0

package/argo/plugins/argo-cost-collector.js

@@ -0,0 +1,35 @@
+// Argo agent-cost collector plugin for opencode.
+//
+// The framework records ONE consolidated agent-cost log per workspace at
+// <workspace>/.argo/temp/agent-cost-log.ndjson, so the user fetches a single
+// file instead of stitching logs from several places. This plugin is the ONLY
+// collector: it sees EVERY tool call the agent makes — MCP interface calls
+// (e.g. getSystemArchitecture), graph writes (e.g. applySystemArchitectureMutation)
+// and repository calls (read / grep / glob) alike — plus assistant token/cost
+// usage, which an MCP-side hook could never observe completely.
+//
+// Recording only observes; it never changes retrieval. Disable with
+// ARGO_COST_PROFILER=0.
+
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+let log = null;
+try {
+  log = require('../scripts/graph-rag/agentCostLog.js');
+} catch {
+  // The shared log module ships next to the plugins under ~/.argo; if it is
+  // missing this plugin is a no-op so it can never break a session.
+  log = null;
+}
+
+export default async function argoCostCollector(input) {
+  if (!log) return {};
+  const workspaceRoot = (input && (input.directory || input.worktree)) || process.cwd();
+  const hooks = log.createHostCollectorHooks(workspaceRoot);
+  return {
+    "tool.execute.before": async (i) => { try { hooks.before(i); } catch { /* best-effort */ } },
+    "tool.execute.after": async (i, o) => { try { hooks.after(i, o); } catch { /* best-effort */ } },
+    event: async (payload) => { try { hooks.event(payload); } catch { /* best-effort */ } },
+  };
+}

package/argo/rules/archgraph.instructions.md

@@ -25,6 +25,7 @@ Non-negotiable red lines (MUST). Never skip, simplify, or silently violate them;
 9. Never duplicate: reuse is the default; a create blocked as an exact or semantic duplicate must be reused, or explicitly overridden with `onConflict: "allowDuplicate"` + justification. See `<GraphDeduplication>`.
 10. Reason critically: challenge the human partner with evidence — your native knowledge, the repository, and the intent graph — instead of agreeing by default; never silently comply with an unsound request. See `<CriticalReasoningGuideline>`.
 11. Never lose content silently: writes that reduce existing content must be lossless (merge/delta) or explicitly acknowledged (`acknowledgeLoss`), and destructive removals are tombstoned. See `<LosslessWrite>`.
+12. Federate by reference, never by copy: register/discover/authorize/read through the federation center (graph MCP surface); a read returns a reference, not a copy; cross-member access is denied by default. See `<FederationGuideline>`.
 </CoreRules>
 
 <Ontology>
@@ -170,6 +171,17 @@ Use `queryNeo4jGraph` for structural/type lookups. It never mutates the canonica
 3. Semantic/context reads (`getSystemArchitecture`, `getIntentElementContext`, `getArchitectureViewContext`) are the PRIORITY path; Cypher is the SECONDARY path per `<QueryPriorityGuideline>`.
 </GraphQueryGuideline>
 
+<FederationGuideline>
+When your project participates in a federation, act through the federation center (one central platform reached over the graph MCP):
+1. Register or exit: register your project with the center to join; deregister it to leave. Do this as the project's own Agent together with your human partner — no separate external approval is required.
+2. Discover before relying: query the center for the members that exist and what each offers (purpose, capabilities, open interfaces).
+3. Authorize before you read: read another member's opened content only after that member explicitly authorizes you; access is denied by default, assume no trust between members.
+4. Reference, not a copy: a read returns a reference, not a copy of another member's content; never persist a copy. The center holds only federation metadata (membership, interfaces, grants); each member's own graph stays the single source of truth.
+5. Never merge graphs: members stay independent; keep your own graph sovereign.
+6. One center: use the single federation center; if it is unreachable, fall back to locally cached discovery/grants and say so.
+7. Surface: do register / deregister / discover / authorize / read through the center's graph MCP tools; never reach the center by a file or SQL path.
+</FederationGuideline>
+
 <Attention>
 Confirm the ARGO MCP server is serving this repository's graph (design/KG/SystemArchitecture.json), not another graph. If it is not, stop and report to your human partner before doing anything else.
 </Attention>

package/argo/scripts/graph-rag/agentCostLog.js

@@ -0,0 +1,179 @@
+'use strict';
+
+// Agent cost LOG (framework, zero-config, background) — the single consolidated
+// store for everything needed to reason about an agent's retrieval cost.
+//
+// WHY ONE FILE: in a real project the agent's scope is the whole repository (an
+// unbounded content source) plus the curated intent graph (KG, only a semantic
+// index / routing layer). Cost is dominated by the agent's round-trips BETWEEN
+// the two backends (graph: getSystemArchitecture / getIntentElementContext /
+// getArchitectureViewContext / queryNeo4jGraph / memory_search; repository:
+// read / grep / glob), not by the size of either backend. To optimise without
+// hurting recall we must measure that — in ONE place the user fetches once:
+//
+//     <workspace>/.argo/temp/agent-cost-log.ndjson
+//
+// WHO WRITES: the OpenCode plugin argo/plugins/argo-cost-collector.js. Every
+// tool call the agent makes — MCP interface calls, graph writes, and repository
+// calls alike — is a host tool, so the plugin records ALL of them, plus the
+// assistant's token/cost usage. There is deliberately NO MCP-side instrumentation
+// (a record without the host side would be incomplete and thus misleading).
+//
+// Posture (mirrors mcpCrashDiagnostics): best-effort, never throws, never logs
+// secret values, and NEVER changes retrieval (it observes results only).
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const LOG_FILE_NAME = 'agent-cost-log.ndjson';
+const DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
+
+const GRAPH_TOOLS = ['getSystemArchitecture', 'getIntentElementContext', 'getArchitectureViewContext', 'queryNeo4jGraph', 'memory_search'];
+const GRAPH_WRITE_TOOLS = [
+  'previewSystemArchitectureMutation', 'applySystemArchitectureMutation',
+  'addArchitectureElement', 'updateArchitectureElement', 'removeArchitectureElement',
+  'addArchitectureRelationship', 'updateArchitectureRelationship', 'removeArchitectureRelationship',
+  'addArchitectureView', 'updateArchitectureView', 'removeArchitectureView',
+];
+const VALIDATOR_TOOLS = ['validateSystemArchitecture', 'runArchitectureTests', 'initializeWorkspace'];
+const REPO_TOOLS = ['read', 'grep', 'glob', 'list', 'bash', 'webfetch', 'edit', 'write'];
+
+function enabled() {
+  return process.env.ARGO_COST_PROFILER !== '0';
+}
+
+function maxBytes() {
+  const n = Number(process.env.ARGO_COST_TRACE_MAX_BYTES);
+  return Number.isFinite(n) && n > 0 ? n : DEFAULT_MAX_BYTES;
+}
+
+function tempDir(workspaceRoot) {
+  return path.join(workspaceRoot, '.argo', 'temp');
+}
+
+function logFilePath(workspaceRoot) {
+  return path.join(tempDir(workspaceRoot), LOG_FILE_NAME);
+}
+
+// Pure, total classification. Host tool names may be prefixed (e.g.
+// mcp__argo__getSystemArchitecture), so match by substring.
+function classifyTool(tool) {
+  const name = String(tool || '');
+  const hit = (list) => list.some(t => name.includes(t));
+  if (hit(GRAPH_WRITE_TOOLS)) return { backend: 'graph', kind: 'write' };
+  if (hit(GRAPH_TOOLS)) return { backend: 'graph', kind: 'read' };
+  if (hit(VALIDATOR_TOOLS)) return { backend: 'framework', kind: 'framework' };
+  if (hit(REPO_TOOLS)) return { backend: 'repo', kind: 'read' };
+  return { backend: 'other', kind: 'other' };
+}
+
+// Deterministic coarse token estimate: CJK ≈ 1 token/char, else ≈ 1/4 chars.
+function estimateTokens(text) {
+  if (!text) return 0;
+  const s = String(text);
+  const cjk = (s.match(/[\u4e00-\u9fff\u3400-\u4dbf\u3000-\u303f\uff00-\uffef]/g) || []).length;
+  return cjk + Math.ceil((s.length - cjk) / 4);
+}
+
+function rotateIfNeeded(file, limit) {
+  try {
+    if (fs.statSync(file).size >= limit) fs.renameSync(file, `${file}.1`);
+  } catch (_) { /* no existing log */ }
+}
+
+// Append one record to the single consolidated log. Best-effort: any failure is
+// swallowed so logging can never affect a tool call.
+function appendRecord(workspaceRoot, record) {
+  if (!enabled() || !workspaceRoot || !record || typeof record !== 'object') return;
+  try {
+    const file = logFilePath(workspaceRoot);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    rotateIfNeeded(file, maxBytes());
+    const line = JSON.stringify({ at: new Date().toISOString(), pid: process.pid, ...record }) + '\n';
+    fs.appendFileSync(file, line, 'utf8');
+  } catch (_) {
+    // best-effort only
+  }
+}
+
+function readLog(workspaceRoot) {
+  const file = logFilePath(workspaceRoot);
+  let raw = '';
+  try { raw = fs.readFileSync(file, 'utf8'); } catch (_) { return { file, records: [] }; }
+  const records = [];
+  for (const line of raw.split('\n')) {
+    const t = line.trim();
+    if (!t.startsWith('{')) continue;
+    try { records.push(JSON.parse(t)); } catch (_) { /* skip malformed */ }
+  }
+  return { file, records };
+}
+
+function byteLen(value) {
+  try {
+    const s = JSON.stringify(value);
+    return (typeof Buffer !== 'undefined') ? Buffer.byteLength(s) : s.length;
+  } catch (_) { return 0; }
+}
+
+function keysOf(value) {
+  return (value && typeof value === 'object' && !Array.isArray(value)) ? Object.keys(value).sort() : [];
+}
+
+// Host-collector hook logic (used by the OpenCode plugin; unit-tested in CJS).
+// It records EVERY host tool call — MCP interface calls, graph writes, and
+// repository calls alike — plus assistant token/cost usage into the single log.
+function createHostCollectorHooks(workspaceRoot) {
+  const starts = new Map();
+  const seenUsage = new Set();
+  return {
+    before(input) {
+      if (!input || !input.callID) return;
+      const args = input.args || {};
+      starts.set(input.callID, { t: Date.now(), keys: keysOf(args), bytes: byteLen(args) });
+    },
+    after(input, output) {
+      if (!input) return;
+      const s = starts.get(input.callID) || {};
+      const cls = classifyTool(input.tool);
+      const out = (output && output.output) || '';
+      appendRecord(workspaceRoot, {
+        source: 'host',
+        type: 'tool',
+        sessionID: input.sessionID,
+        callID: input.callID,
+        tool: input.tool,
+        backend: cls.backend,
+        kind: cls.kind,
+        durationMs: s.t ? (Date.now() - s.t) : 0,
+        ok: true,
+        args: { keys: s.keys || keysOf(input.args), bytes: s.bytes != null ? s.bytes : byteLen(input.args) },
+        resultBytes: String(out).length,
+        resultTokens: estimateTokens(out),
+      });
+      starts.delete(input.callID);
+    },
+    event(payload) {
+      const event = payload && payload.event;
+      const props = (event && event.properties) || {};
+      const info = props.info || (event && event.info) || null;
+      if (info && info.role === 'assistant' && info.tokens && info.id && !seenUsage.has(info.id)) {
+        seenUsage.add(info.id);
+        appendRecord(workspaceRoot, {
+          source: 'host',
+          type: 'usage',
+          sessionID: info.sessionID,
+          messageID: info.id,
+          tokens: info.tokens,
+          cost: info.cost,
+        });
+      }
+    },
+  };
+}
+
+module.exports = {
+  LOG_FILE_NAME,
+  enabled, tempDir, logFilePath, classifyTool, estimateTokens,
+  appendRecord, readLog, createHostCollectorHooks,
+};

package/install-argo.ps1

@@ -1109,5 +1109,14 @@ if (Test-Path $wakeupPluginPath) {
     Write-Host "argo-wakeup plugin registered -> $OpenCodeConfigPath"
 }
 
+# Agent-cost collector: the complete host-side writer of the single consolidated
+# agent-cost log (<workspace>/.argo/temp/agent-cost-log.ndjson).
+$costCollectorPath = Join-Path $PluginsRoot 'argo-cost-collector.js'
+if (Test-Path $costCollectorPath) {
+    Write-Host '==> Registering argo-cost-collector plugin in OpenCode'
+    Register-OpenCodePlugin -ConfigPath $OpenCodeConfigPath -PluginFilePath $costCollectorPath
+    Write-Host "argo-cost-collector plugin registered -> $OpenCodeConfigPath"
+}
+
 Write-Host ''
 Write-Host 'Argo deployment complete.'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgraph-argo",
-  "version": "0.24.2",
+  "version": "0.25.0",
   "description": "Deploy the ArchGraph ARGO toolchain, skills, and rules (schema, scripts, argo-init skill, global rule) with one command.",
   "license": "MIT",
   "bin": {