tr-plugin-meta-harness 0.0.0-stage → 0.3.0

package/cli.mjs

@@ -0,0 +1,139 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { ADAPTERS, inspectAgents, getActiveAdapters, getCustomAdaptersDirs, loadCustomAdapters } from './src/worker.mjs';
+import { inspectNode, listTargets, executeCommand, executeOnNode } from './src/executor.mjs';
+import { DOC_SOURCES, documentationStatus, refreshDocumentation, ensureDocumentation, maintainDocumentation, readDocumentation, searchDocumentation } from './src/documentation.mjs';
+import { manageRuntime } from './src/runtime.mjs';
+import { setupIntegrations } from './src/setup.mjs';
+import { inspectUpstreamFleet, getAgentChangelog } from './src/tracker.mjs';
+import { inspectQuotas, getBenchmarks, routeTask } from './src/router.mjs';
+import { coordinateTask } from './src/coordinator.mjs';
+import { recordRunReceipt, learnFromHistory } from './src/learner.mjs';
+
+export async function run(argv = []) {
+  const args = argv.slice(3); const operation = args[0] || 'status';
+  // Help anywhere in the arguments prints usage; it must never run an operation.
+  if (operation === 'help' || args.some(arg => arg === '--help' || arg === '-h')) {
+    const manifest=JSON.parse(fs.readFileSync(new URL('./plugin.json',import.meta.url),'utf8'));
+    console.log('Usage: total-recall cli-agents <operation> [options]\nEvery agent receives Total Recall bootstrap before dispatch. Runtime syntax: runtime <agent> <native-command...> [--node ID].\n');
+    for(const command of manifest.cli.subcommands)console.log(`  ${command.name} ${(command.args || []).map(arg=>arg.flag?`${arg.flag} <${arg.name}>`:`<${arg.name}>`).join(' ')} — ${command.description}`);
+    return;
+  }
+  let result;
+  if (operation === 'status') result = {...await inspectAgents(),documentation:documentationStatus()};
+  else if (operation === 'catalog') result = { adapters: getActiveAdapters(), permissions: ['read', 'write', 'send', 'destructive'] };
+  else if (operation === 'nodes') result = await listTargets();
+  else if (operation === 'quota') {
+    const index = args.indexOf('--node');
+    result = await inspectQuotas({ node: index >= 0 ? args[index + 1] : 'local' });
+  }
+  else if (operation === 'benchmarks') result = getBenchmarks();
+  else if (operation === 'route') {
+    const includeUninstalled = args.includes('--include-uninstalled');
+    const preferLocal = args.includes('--prefer-local');
+    const preferFrontier = args.includes('--prefer-frontier');
+    const task = args.slice(1).filter(a => !a.startsWith('--')).join(' ');
+    if (!task) throw new Error('route requires a task description');
+    result = await routeTask(task, { includeUninstalled, preferLocal, preferFrontier });
+  }
+  else if (operation === 'coordinate') {
+    const modeIdx = args.indexOf('--mode');
+    const mode = modeIdx >= 0 ? args[modeIdx + 1] : 'pipeline';
+    const execute = args.includes('--execute');
+    const task = args.slice(1).filter(a => !a.startsWith('--') && a !== mode).join(' ');
+    if (!task) throw new Error('coordinate requires a task description');
+    result = await coordinateTask(task, { mode, execute });
+  }
+  else if (operation === 'learn') result = learnFromHistory();
+  else if (operation === 'upstream') result = await inspectUpstreamFleet(getActiveAdapters());
+  else if (operation === 'changelog') result = getAgentChangelog(args[1] || 'agy');
+  else if (operation === 'adapter') {
+    const sub = args[1] || 'list';
+    if (sub === 'list') {
+      result = { active: getActiveAdapters(), custom: loadCustomAdapters() };
+    } else if (sub === 'add') {
+      const target = args[2];
+      if (!target) throw new Error('adapter add requires a JSON spec or file path');
+      let spec;
+      try {
+        spec = fs.existsSync(target) ? JSON.parse(fs.readFileSync(target, 'utf8')) : JSON.parse(target);
+      } catch {
+        throw new Error('Invalid adapter JSON specification');
+      }
+      if (!spec.id || !spec.binary) throw new Error('Adapter specification must define id and binary');
+      const dirs = getCustomAdaptersDirs();
+      fs.mkdirSync(dirs[0], { recursive: true });
+      const dest = path.join(dirs[0], `${spec.id}.json`);
+      fs.writeFileSync(dest, JSON.stringify(spec, null, 2), 'utf8');
+      result = { ok: true, added: spec.id, path: dest };
+    } else if (sub === 'remove') {
+      const id = args[2];
+      if (!id) throw new Error('adapter remove requires an adapter identifier');
+      const dirs = getCustomAdaptersDirs();
+      let removed = false;
+      for (const d of dirs) {
+        const dest = path.join(d, `${id}.json`);
+        if (fs.existsSync(dest)) {
+          fs.unlinkSync(dest);
+          removed = true;
+        }
+      }
+      result = { ok: removed, removed: id };
+    }
+  }
+  else if(operation==='docs-sources')result={sources:DOC_SOURCES};
+  else if(operation==='docs-read' || operation==='docs-search') {
+    const option=name=>{const i=args.indexOf(name);if(i<0)return undefined;if(!args[i+1] || args[i+1].startsWith('--'))throw new Error(`${name} requires a value`);return args[i+1];};
+    result=operation==='docs-read'?readDocumentation({agent:option('--agent'),url:option('--url')}):searchDocumentation({agent:option('--agent'),query:option('--query')});
+  }
+  else if(operation==='setup') {
+    const index=args.indexOf('--node');
+    if(index>=0 && (!args[index+1] || args[index+1].startsWith('-')))throw new Error('--node requires a recorded node');
+    result=await setupIntegrations({node:index>=0?args[index+1]:undefined});
+  }
+  else if (['docs-status','docs-refresh','docs-ensure','maintenance'].includes(operation)) {
+    const selected = args.indexOf('--agent');
+    if (selected>=0 && (!args[selected+1] || args[selected+1].startsWith('-'))) throw new Error('--agent requires an adapter identifier');
+    const options = selected>=0 ? {agent:args[selected+1]} : {};
+    if(operation==='maintenance') {
+      const setup=await setupIntegrations();
+      result={...await maintainDocumentation(options),setup};
+    } else result = operation==='docs-status' ? documentationStatus(options) : operation==='docs-ensure' ? await ensureDocumentation(options) : await refreshDocumentation(options);
+    if(!result.ok)process.exitCode=1;
+  }
+  else if (operation === 'runtime') {
+    const runtimeArgs=args.slice(1).filter(arg=>arg!=='--json'), agent=runtimeArgs.shift();
+    const index=runtimeArgs.indexOf('--node'); let node='local';
+    if(index>=0){node=runtimeArgs[index+1];if(!node || node.startsWith('-'))throw new Error('--node requires an identifier');runtimeArgs.splice(index,2);}
+    result = node==='local' ? await manageRuntime(agent,runtimeArgs) : await executeOnNode(node,{operation:'direct',cwd:process.cwd(),argv:['total-recall','cli-agents','runtime',agent,...runtimeArgs,'--json']});
+    if(!result.ok)process.exitCode=1;
+  }
+  else if(operation==='dispatch') {
+    if(!args.includes('--stdin'))throw new Error('Task requests must arrive through stdin');
+    const input=fs.readFileSync(0,'utf8');if(Buffer.byteLength(input)>65536)throw new Error('Task request too large');
+    const request=JSON.parse(input);
+    result=await executeOnNode(request.node || 'local',{...request,operation:'dispatch'});
+    if(!result.ok)process.exitCode=1;
+  }
+  else if (operation === 'inspect') {
+    const index = args.indexOf('--node');
+    if (index >= 0 && (!args[index + 1] || args[index + 1].startsWith('--'))) throw new Error('--node requires a recorded node identifier');
+    result = await inspectNode(index >= 0 ? args[index + 1] : 'local');
+  }
+  else if (operation === 'run-command') {
+    if (!args.includes('--stdin')) throw new Error('Supply the command request through stdin');
+    const input = fs.readFileSync(0, 'utf8'); if (Buffer.byteLength(input) > 65536) throw new Error('Command request is too large');
+    const request = JSON.parse(input);
+    const root = process.env.TR_PACKAGE_ROOT;
+    if (!root) throw new Error('Native host context required');
+    if (!path.isAbsolute(root)) throw new Error('Absolute native host context required');
+    if (JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).name !== 'total-recall-brain') throw new Error('Native host identity mismatch');
+    const { getPlugin } = await import(pathToFileURL(path.join(root, 'src/core/plugin-loader.mjs')));
+    const plugin = getPlugin(request.pluginId, request.projectRoot || process.cwd());
+    result = await executeCommand({ ...request, plugin });
+    if (!result.ok) process.exitCode = 1;
+  } else throw new Error('Unknown CLI-agents operation');
+  console.log(JSON.stringify(result));
+}
+export default run;

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "tr-plugin-meta-harness",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Total Recall Meta Harness plugin",
+  "type": "module",
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "files": [
+    "cli.mjs",
+    "plugin.json",
+    "README.md",
+    "src/",
+    "!src/**/*.spec.mjs",
+    "ui/",
+    "capability/",
+    "skills/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugin.json

@@ -0,0 +1,376 @@
+{
+  "id": "meta-harness",
+  "name": "Meta Harness",
+  "version": "0.3.0",
+  "description": "Discover, configure, document, track, and run coding agent harnesses through Total Recall across mesh nodes.",
+  "cli": {
+    "command": "meta-harness",
+    "alias": "cli-agents",
+    "handler": "cli.mjs",
+    "subcommands": [
+      {
+        "name": "status",
+        "description": "Inspect local agent binaries and authentication metadata",
+        "effect": "read",
+        "output": "json",
+        "args": []
+      },
+      {
+        "name": "catalog",
+        "description": "List documented adapter contracts and source references",
+        "effect": "read",
+        "output": "json",
+        "args": []
+      },
+      {
+        "name": "nodes",
+        "description": "List recorded mesh targets without probing or changing them",
+        "effect": "read",
+        "output": "json",
+        "args": []
+      },
+      {
+        "name": "inspect",
+        "description": "Inspect installed harnesses on a selected node",
+        "effect": "read",
+        "output": "json",
+        "args": [
+          {
+            "name": "node",
+            "flag": "--node",
+            "type": "string",
+            "label": "Mesh node"
+          }
+        ],
+        "timeout_ms": 120000
+      },
+      {
+        "name": "run-command",
+        "description": "Run an explicit plugin command through the selected agent and node using a JSON request on stdin",
+        "effect": "write",
+        "output": "json",
+        "args": [],
+        "timeout_ms": 600000
+      },
+      {
+        "name": "runtime",
+        "description": "Manage any agent runtime; includes Hermes gateway/auth/skills/plugins and DSH observations",
+        "effect": "write",
+        "output": "json",
+        "args": [
+          {
+            "name": "agent",
+            "type": "string",
+            "label": "Agent adapter",
+            "required": true,
+            "positional": true
+          },
+          {
+            "name": "operation",
+            "type": "string",
+            "label": "Native operation",
+            "required": true,
+            "positional": true
+          }
+        ],
+        "timeout_ms": 120000
+      },
+      {
+        "name": "dispatch",
+        "description": "Run a task from stdin after automatic Total Recall bootstrap",
+        "effect": "write",
+        "output": "json",
+        "args": [],
+        "timeout_ms": 120000
+      },
+      {
+        "name": "docs-status",
+        "description": "Verify cached official documentation coverage freshness and hashes",
+        "effect": "read",
+        "output": "json",
+        "args": [
+          {
+            "name": "agent",
+            "flag": "--agent",
+            "type": "string",
+            "label": "Agent adapter"
+          }
+        ],
+        "timeout_ms": 120000
+      },
+      {
+        "name": "docs-refresh",
+        "description": "Download complete official agent documentation and retain last-good content on failure",
+        "effect": "write",
+        "output": "json",
+        "args": [
+          {
+            "name": "agent",
+            "flag": "--agent",
+            "type": "string",
+            "label": "Agent adapter"
+          }
+        ],
+        "timeout_ms": 600000
+      },
+      {
+        "name": "docs-ensure",
+        "description": "Refresh missing or stale documentation automatically",
+        "effect": "write",
+        "output": "json",
+        "args": [
+          {
+            "name": "agent",
+            "flag": "--agent",
+            "type": "string",
+            "label": "Agent adapter"
+          }
+        ],
+        "timeout_ms": 600000
+      },
+      {
+        "name": "maintenance",
+        "description": "Total Recall daemon maintenance: current official documentation and integration surfaces",
+        "effect": "write",
+        "output": "json",
+        "args": [],
+        "timeout_ms": 600000
+      },
+      {
+        "name": "setup",
+        "description": "Configure supported agent instruction surfaces and daemon task placement",
+        "effect": "write",
+        "output": "json",
+        "args": [
+          {
+            "name": "node",
+            "flag": "--node",
+            "type": "string",
+            "label": "Maintenance mesh node"
+          }
+        ],
+        "timeout_ms": 120000
+      },
+      {
+        "name": "docs-sources",
+        "description": "List approved official documentation sources",
+        "effect": "read",
+        "output": "json",
+        "args": []
+      },
+      {
+        "name": "docs-read",
+        "description": "Read integrity-checked cached official documentation",
+        "effect": "read",
+        "output": "json",
+        "args": [
+          {
+            "name": "agent",
+            "flag": "--agent",
+            "type": "string",
+            "label": "Agent"
+          },
+          {
+            "name": "url",
+            "flag": "--url",
+            "type": "string",
+            "label": "Url"
+          }
+        ]
+      },
+      {
+        "name": "docs-search",
+        "description": "Search downloaded official documentation",
+        "effect": "read",
+        "output": "json",
+        "args": [
+          {
+            "name": "agent",
+            "flag": "--agent",
+            "type": "string",
+            "label": "Agent"
+          },
+          {
+            "name": "query",
+            "flag": "--query",
+            "type": "string",
+            "required": true,
+            "label": "Query"
+          }
+        ]
+      },
+      {
+        "name": "upstream",
+        "description": "Probe latest upstream harness versions and update availability",
+        "effect": "read",
+        "output": "json",
+        "args": []
+      },
+      {
+        "name": "changelog",
+        "description": "Inspect recent official changelog highlights for a selected agent",
+        "effect": "read",
+        "output": "json",
+        "args": [
+          {
+            "name": "agent",
+            "type": "string",
+            "label": "Agent identifier",
+            "required": false,
+            "positional": true
+          }
+        ]
+      },
+      {
+        "name": "adapter",
+        "description": "Manage extensible harness adapter definitions (list, add, remove)",
+        "effect": "write",
+        "output": "json",
+        "args": [
+          {
+            "name": "operation",
+            "type": "string",
+            "label": "list | add | remove",
+            "required": true,
+            "positional": true
+          },
+          {
+            "name": "target",
+            "type": "string",
+            "label": "File path, spec JSON, or adapter ID",
+            "required": false,
+            "positional": true
+          }
+        ]
+      },
+      {
+        "name": "quota",
+        "description": "Inspect 5-hour rolling/weekly quotas, credit balances, and host RAM",
+        "effect": "read",
+        "output": "json",
+        "args": [
+          {
+            "name": "node",
+            "flag": "--node",
+            "type": "string",
+            "label": "Mesh node"
+          }
+        ]
+      },
+      {
+        "name": "benchmarks",
+        "description": "Inspect SWE-bench Pro, Terminal-Bench 2.0, and local empirical pass rates",
+        "effect": "read",
+        "output": "json",
+        "args": []
+      },
+      {
+        "name": "route",
+        "description": "Evaluate task complexity and select optimal harness via two-stage RouteLLM classifier",
+        "effect": "read",
+        "output": "json",
+        "args": [
+          {
+            "name": "task",
+            "type": "string",
+            "label": "Task description",
+            "required": true,
+            "positional": true
+          }
+        ]
+      },
+      {
+        "name": "coordinate",
+        "description": "Coordinate multi-agent specialized execution pipelines (pipeline, council, race)",
+        "effect": "write",
+        "output": "json",
+        "args": [
+          {
+            "name": "task",
+            "type": "string",
+            "label": "Task description",
+            "required": true,
+            "positional": true
+          },
+          {
+            "name": "mode",
+            "flag": "--mode",
+            "type": "string",
+            "label": "pipeline | council | race"
+          }
+        ]
+      },
+      {
+        "name": "learn",
+        "description": "Summarize empirical run scorecards and generate memory friction proposals",
+        "effect": "read",
+        "output": "json",
+        "args": []
+      }
+    ]
+  },
+  "runtime": {
+    "modules": {
+      "command-executor": "src/executor.mjs",
+      "documentation": "src/documentation.mjs",
+      "agent-runtime": "src/runtime.mjs",
+      "tracker": "src/tracker.mjs"
+    },
+    "setup_command": "setup"
+  },
+  "branding": {
+    "name": "Meta Harness",
+    "color": "#3b82f6",
+    "accent": "#38bdf8",
+    "background": "#0c1427",
+    "font": "system"
+  },
+  "ui": {
+    "elements": [
+      {
+        "id": "meta-harness-card",
+        "kind": "card",
+        "tag": "meta-harness-card",
+        "module": "ui/card.js",
+        "description": "Meta Harness multi-agent coordination matrix"
+      }
+    ]
+  },
+  "card_face": {
+    "quick_actions": [
+      {
+        "subcommand": "status",
+        "label": "Local agents"
+      },
+      {
+        "subcommand": "nodes",
+        "label": "Mesh nodes"
+      },
+      {
+        "subcommand": "catalog",
+        "label": "Adapters"
+      }
+    ]
+  },
+  "auth": {
+    "plugin": "auth",
+    "methods": [
+      "passkey",
+      "google-oauth2"
+    ],
+    "session_verification": true
+  },
+  "distribution": {
+    "tier": "official",
+    "license": "open"
+  },
+  "tasks": [
+    {
+      "intent": "Keep official agent documentation and Total Recall integrations current",
+      "schedule": "*/15 * * * *",
+      "command": "maintenance",
+      "placement": "selected-node",
+      "timeout_ms": 600000
+    }
+  ]
+}

package/skills/meta-harness/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: meta-harness
+description: Discover, configure, document, track, route, coordinate, and run coding agent harnesses through Total Recall across mesh nodes.
+repo_scoped: false
+---
+
+# Meta Harness
+
+The Meta Harness plugin coordinates 15+ coding agent runtimes (`agy`, `claude`, `codex`, `grok`, `ollama`, `hermes`, `dsh`, `openclaw`, `aider`, `goose`, `openhands`, `cline`, and IDE runners) across local and remote mesh nodes.
+
+## Golden Rules
+1. **Never Hardcode Credential Logic**: All API keys resolve via `total-recall auth secret get <KEY>` using the global encrypted vault.
+2. **Total Recall First**: Every dispatched agent run enforces `total-recall context "<task>"` with `ready:true` and writes a verified preflight receipt.
+3. **Deterministic Complexity Routing**: Use `meta-harness route "<task>"` to classify task complexity and avoid burning frontier quotas on mechanical edits.
+4. **Isolated Verification**: In multi-agent pipelines (`Architect -> Implementer -> Verifier`), the Verifier must execute in an isolated git worktree and employ a distinct model family.
+
+## Command Reference
+
+### Discovery & Upstream Version Tracking
+- `total-recall meta-harness status [--node <id>]`: Check installed binaries, versions, and auth status.
+- `total-recall meta-harness tracking [--node <id>]`: Compare installed versions against upstream release tags and changelogs.
+- `total-recall meta-harness catalog`: List all built-in and custom declarative adapter contracts.
+
+### Smart Routing & Telemetry
+- `total-recall meta-harness quota [--node <id>]`: Inspect 5-hour rolling/weekly quotas, credit balances, and free RAM.
+- `total-recall meta-harness benchmarks`: View SWE-bench Pro, Terminal-Bench 2.0, and local empirical pass rates.
+- `total-recall meta-harness route "<task>"`: Two-stage RouteLLM classifier and gate cascade evaluation.
+
+### Multi-Agent Coordination & Mesh Dispatch
+- `total-recall meta-harness coordinate "<task>" --mode pipeline`: Run Architect -> Implementer -> Verifier pipeline.
+- `total-recall meta-harness coordinate "<task>" --mode council`: Run multi-model consensus review.
+- `total-recall meta-harness dispatch <harness> "<prompt>" [--node <id>]`: Dispatch a single task with preflight receipt.
+
+### Self-Learning & Adapters
+- `total-recall meta-harness learn`: Ingest recent run receipts, update scorecards, and propose memory friction improvements.
+- `total-recall meta-harness adapter add <json-or-file>`: Register custom third-party agent harnesses dynamically.
+- `total-recall meta-harness adapter list`: View custom registered adapters.