@hybridlabor-api/aos 4.6.6 → 4.7.0

package/mcps/mcsc/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@hybridlabor-api/mcsc",
+  "version": "0.1.0",
+  "description": "Multi-CLI Subagent Configurator (MCSC) MCP Server for local subagent delegation",
+  "type": "module",
+  "main": "server.js",
+  "bin": {
+    "mcsc": "./packages/core/bin/mcsc.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "js-yaml": "^5.4.1"
+  }
+}

package/mcps/mcsc/packages/core/bin/mcsc.js

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+
+// NOTE: an earlier draft of this file used a `node:module` loader hook
+// (`register()`) to monkey-patch detect/inventory.js and detect/cache.js at
+// import time instead of fixing their actual bugs (a dead `CliHealth` runtime
+// import, and wrong-module imports for `homedir`/`performance`). That hack
+// is gone — those files are fixed directly (they're our own code, not a
+// vendor CLI wrapper, so "wrap don't patch" §7 doesn't apply here).
+
+async function run() {
+  const fs = (await import('fs')).default;
+  const path = (await import('path')).default;
+  const os = (await import('os')).default;
+  const { fileURLToPath } = await import('url');
+
+  const { loadRulebook } = await import('../src/rulebook/load.js');
+  const { decide } = await import('../src/rulebook/resolve.js');
+  const { runInventory } = await import('../src/detect/inventory.js');
+  const { getCached, setCached } = await import('../src/detect/cache.js');
+  const { buildOfferTable } = await import('../src/capabilities/buildOfferTable.js');
+
+  const { delegate: agyDelegate } = await import('../src/adapters/agy.js');
+  const { delegate: opencodeDelegate } = await import('../src/adapters/opencode.js');
+  const { delegate: nativeDelegate } = await import('../src/adapters/native.js');
+
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = path.dirname(__filename);
+
+  const CLI_IDS = ['agy', 'opencode', 'codex', 'native'];
+  const TTL_MS = 24 * 60 * 60 * 1000;
+
+  async function getInventory() {
+    const cliHealthMap = new Map();
+    const missingCliIds = [];
+
+    for (const cliId of CLI_IDS) {
+      const cached = await getCached(cliId);
+      if (cached) {
+        cliHealthMap.set(cliId, cached);
+      } else {
+        missingCliIds.push(cliId);
+      }
+    }
+
+    if (missingCliIds.length > 0) {
+      const newHealthMap = await runInventory({ cliIds: missingCliIds, maxAgeMs: TTL_MS });
+      for (const [cliId, health] of newHealthMap.entries()) {
+        cliHealthMap.set(cliId, health);
+        await setCached(cliId, health, TTL_MS);
+      }
+    }
+
+    return cliHealthMap;
+  }
+
+  const argv = process.argv;
+  const subcommand = argv[2];
+
+  let taskType = null;
+  let promptText = null;
+  let isJson = false;
+
+  for (let i = 3; i < argv.length; i++) {
+    if (argv[i] === '--task-type' && i + 1 < argv.length) {
+      taskType = argv[++i];
+    } else if (argv[i] === '--prompt' && i + 1 < argv.length) {
+      promptText = argv[++i];
+    } else if (argv[i] === '--json') {
+      isJson = true;
+    }
+  }
+
+  if (subcommand === 'detect') {
+    const inventoryMap = await getInventory();
+    const inventoryObj = Object.fromEntries(inventoryMap);
+    if (isJson) {
+      console.log(JSON.stringify(inventoryObj, null, 2));
+    } else {
+      console.log(inventoryObj);
+    }
+    return;
+  }
+
+  if (subcommand === 'route' || subcommand === 'exec') {
+    const inventoryMap = await getInventory();
+    
+    const defaultsPath = path.resolve(__dirname, '../rulebook.default.yaml');
+    const overridePath = path.resolve(os.homedir(), '.config/mcsc/rulebook.yaml');
+    
+    let rules = [];
+    try {
+      rules = await loadRulebook({
+        defaultsPath,
+        overridePath: fs.existsSync(overridePath) ? overridePath : undefined
+      });
+    } catch (e) {
+      console.error('Failed to load rulebook:', e);
+      process.exit(1);
+    }
+
+    const now = Date.now();
+    const offerTable = await buildOfferTable(rules, inventoryMap, now);
+    
+    const inventorySnapshot = { cliHealth: Object.fromEntries(inventoryMap) };
+    const taskDescriptor = { task_type: taskType };
+    
+    const decision = decide(taskDescriptor, rules, inventorySnapshot, offerTable, now);
+    
+    if (subcommand === 'route') {
+      if (isJson) {
+        console.log(JSON.stringify(decision, null, 2));
+      } else {
+        console.log(decision);
+      }
+      if (decision.kind === 'refuse') {
+        process.exit(1);
+      }
+      return;
+    }
+
+    if (subcommand === 'exec') {
+      if (decision.kind === 'refuse') {
+        console.error(JSON.stringify(decision, null, 2));
+        process.exit(1);
+      }
+
+      if (decision.kind === 'route') {
+        const delegateReq = {
+          taskType,
+          prompt: promptText,
+          model: decision.offer.modelId,
+          cwd: process.cwd()
+        };
+
+        let result;
+        try {
+          if (decision.cliId === 'agy') {
+            result = await agyDelegate(delegateReq);
+          } else if (decision.cliId === 'opencode') {
+            result = await opencodeDelegate(delegateReq);
+          } else if (decision.cliId === 'native') {
+            result = await nativeDelegate(delegateReq);
+          } else {
+            console.error('No adapter for CLI:', decision.cliId);
+            process.exit(1);
+          }
+
+          console.log(result.output);
+          process.exit(result.exit);
+        } catch (e) {
+          console.error(e);
+          process.exit(1);
+        }
+      }
+    }
+  }
+}
+
+run().catch(e => {
+  console.error(e);
+  process.exit(1);
+});

package/mcps/mcsc/packages/core/rulebook.default.yaml

@@ -0,0 +1,49 @@
+version: 1
+# Model ids are the SHORT ids agy reports in `agy models` (left column) --
+# e.g. "gemini-3.8-flash-medium", not "Gemini 3.8 Flash (Medium)" and not
+# "gemini-flash-3.8". Verify with `agy models` after any agy upgrade; the
+# ids carry both the version AND the effort suffix (-low/-medium/-high),
+# so dropping the suffix does not resolve.
+rules:
+  # Media + fast/mechanical coding -> newest Flash. Cheap, quick, and the
+  # tier that actually has media capability.
+  - id: media-generation
+    match: {task_type: [image-gen, video-gen, media]}
+    candidates:
+      - {cli: agy, model: "gemini-3.8-flash-medium"}
+      - {cli: native}
+
+  - id: fast-coding
+    match: {task_type: [boilerplate, quick-check, scaffold, mechanical-edit]}
+    candidates:
+      - {cli: agy, model: "gemini-3.8-flash-medium"}
+      - {cli: opencode, model_select: {provider: opencode, prefer: [free]}}
+      - {cli: native}
+
+  # Research reads a lot and distils -- same family, more effort headroom.
+  - id: deep-research
+    match: {task_type: [research, web-search, docs-survey]}
+    candidates:
+      - {cli: agy, model: "gemini-3.8-flash-high"}
+      - {cli: opencode, model_select: {provider: opencode, prefer: [free], match: "*gemini*"}}
+      - {cli: native}
+
+  # Review needs real judgment to be adversarial rather than agreeable --
+  # Sonnet, not a Flash tier.
+  - id: review
+    match: {task_type: [review, code-review, adversarial-review]}
+    candidates:
+      - {cli: agy, model: "claude-sonnet-4-6"}
+      - {cli: native}
+
+  # Architecture/refactor planning: mistakes here propagate to every
+  # downstream worker, so this is the one place worth the top tier.
+  - id: complex-code
+    match: {task_type: [architecture, refactor-plan], min_complexity: high}
+    candidates:
+      - {cli: agy, model: "claude-opus-4-6-thinking"}
+      - {cli: agy, model: "claude-sonnet-4-6"}
+      - {cli: codex, model: "gpt-5-codex"}
+      - {cli: native}
+
+defaults: {fallback: native, on_unresolvable: native}

package/mcps/mcsc/packages/core/schema/rulebook.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Rulebook Schema",
+  "type": "object",
+  "properties": {
+    "version": {
+      "type": "integer",
+      "const": 1
+    },
+    "rules": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "match": {
+            "type": "object"
+          },
+          "candidates": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "properties": {
+                "cli": {
+                  "type": "string",
+                  "enum": ["agy", "opencode", "codex", "native"]
+                }
+              },
+              "required": ["cli"]
+            }
+          }
+        },
+        "required": ["id", "match", "candidates"]
+      }
+    },
+    "defaults": {
+      "type": "object",
+      "properties": {
+        "fallback": {
+          "type": "string",
+          "enum": ["native"]
+        },
+        "on_unresolvable": {
+          "type": "string",
+          "enum": ["native"]
+        }
+      },
+      "required": ["fallback", "on_unresolvable"]
+    }
+  },
+  "required": ["version", "rules", "defaults"]
+}

package/mcps/mcsc/packages/core/src/adapters/agy.js

@@ -0,0 +1,107 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { emitTrail } from '../trail.js';
+const execFileAsync = promisify(execFile);
+
+/**
+ * CliAdapter shelling out DIRECTLY to the vendor 'agy' binary.
+ *
+ * @param {import('../types.js').DelegationRequest} req
+ * @returns {Promise<{ exit: number; output: string; attestation: { kind: 'confirmed' | 'unavailable'; modelId?: string; sessionRef?: string } }>}
+ */
+export async function delegate(req) {
+  const trailEvent = {
+    session_id: `mcsc-agy-${process.pid}-${Date.now()}`,
+    cwd: req.cwd || process.cwd(),
+    agent:
+      typeof req.label === 'string' && req.label.length > 0
+        ? `agy:${req.label}`
+        : 'agy',
+  };
+  emitTrail({ ...trailEvent, hook_event_name: 'SessionStart' });
+  try {
+    const args = [];
+    if (req.model) args.push('--model', req.model);
+    args.push(
+      '--print-timeout',
+      '15m',
+      '--output-format',
+      'json',
+      '--project',
+      'mcsc-delegate',
+      '--print',
+      req.prompt
+    );
+    
+    const env = { ...process.env, MCSC_CALLER: 'agy' };
+
+    const run = execFileAsync(
+      'agy',
+      args,
+      {
+        cwd: req.cwd,
+        encoding: 'utf-8',
+        maxBuffer: 1024 * 1024 * 50,
+        env,
+        signal: req.signal
+      }
+    );
+    // An open stdin pipe makes the CLI wait for input forever.
+    run.child.stdin.end();
+    const { stdout, stderr } = await run;
+
+    const raw = stdout || stderr;
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      // If we can't parse JSON, we cannot attest the model.
+      emitTrail({ ...trailEvent, hook_event_name: 'SessionEnd' });
+      return {
+        exit: 0,
+        output: raw.trim(),
+        attestation: { kind: 'unavailable' },
+      };
+    }
+
+    if (parsed && typeof parsed === 'object') {
+      const modelId = parsed.modelId || parsed.model || parsed.cli_model || parsed.id;
+      const sessionRef = parsed.conversation_id || parsed.session || parsed.sessionId || parsed.id;
+
+      if (modelId) {
+        emitTrail({ ...trailEvent, hook_event_name: 'SessionEnd' });
+        return {
+          exit: 0,
+          output: raw.trim(),
+          attestation: {
+            kind: 'confirmed',
+            modelId: String(modelId),
+            sessionRef: String(sessionRef || ''),
+          },
+        };
+      }
+    }
+
+    emitTrail({ ...trailEvent, hook_event_name: 'SessionEnd' });
+    return {
+      exit: 0,
+      output: raw.trim(),
+      attestation: { kind: 'unavailable' },
+    };
+  } catch (e) {
+    if (e.name === 'AbortError') {
+      emitTrail({ ...trailEvent, hook_event_name: 'SessionEnd' });
+      return {
+        exit: 1,
+        output: 'Cancelled by orchestrator',
+        attestation: { kind: 'unavailable' }
+      };
+    }
+    emitTrail({ ...trailEvent, hook_event_name: 'SessionEnd' });
+    return {
+      exit: 1,
+      output: (e.stderr || e.message || '').trim(),
+      attestation: { kind: 'unavailable' },
+    };
+  }
+}

package/mcps/mcsc/packages/core/src/adapters/codex.js

@@ -0,0 +1,56 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { emitTrail } from '../trail.js';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Adapter für die Codex CLI.
+ * Implementiert die DelegationRequest Schnittstelle.
+ * @param {import('./types.js').DelegationRequest} req 
+ * @returns {Promise<{ exit: number; output: string }>}
+ */
+export async function delegate(req) {
+  const trailEvent = {
+    session_id: `mcsc-codex-${process.pid}-${Date.now()}`,
+    cwd: req.cwd || process.cwd(),
+    agent:
+      typeof req.label === 'string' && req.label.length > 0
+        ? `codex:${req.label}`
+        : 'codex',
+  };
+  emitTrail({ ...trailEvent, hook_event_name: 'SessionStart' });
+  try {
+    const args = ['exec'];
+    if (req.model) args.push('-m', req.model);
+    args.push(req.prompt);
+
+    // Recursion Guard
+    const env = { ...process.env, MCSC_CALLER: 'codex' };
+
+    const run = execFileAsync(
+      'codex', args,
+      {
+        cwd: req.cwd,
+        encoding: 'utf-8',
+        maxBuffer: 1024 * 1024 * 50, // 50MB Limit
+        env,
+        signal: req.signal
+      }
+    );
+    // An open stdin pipe makes the CLI wait for input forever.
+    run.child.stdin.end();
+    const { stdout, stderr } = await run;
+    
+    emitTrail({ ...trailEvent, hook_event_name: 'SessionEnd' });
+    return { exit: 0, output: stdout || stderr };
+  } catch (e) {
+    emitTrail({ ...trailEvent, hook_event_name: 'SessionEnd' });
+    if (e.name === 'AbortError') {
+      emitTrail({ ...trailEvent, hook_event_name: 'SessionEnd' });
+      return { exit: 1, output: 'Cancelled by orchestrator' };
+    }
+    emitTrail({ ...trailEvent, hook_event_name: 'SessionEnd' });
+    return { exit: 1, output: (e.stderr || e.message || '').trim() };
+  }
+}

package/mcps/mcsc/packages/core/src/adapters/native.js

@@ -0,0 +1,14 @@
+/**
+ * CliAdapter for 'native'.
+ *
+ * Native delegation happens at the orchestrator level (Agent tool),
+ * not by shelling out. This adapter is a no-op that signals
+ * unattested delegation — the orchestrator should handle the
+ * native Claude Code subagent lifecycle itself.
+ *
+ * @param {import('../adapters/types.js').DelegationRequest} req
+ * @returns {Promise<{ exit: number; output: string; attestation: { kind: 'unavailable'; } }>}
+ */
+export async function delegate(req) {
+  throw new Error("Task requires native handling by the current orchestrator. Do not use delegate tools for this.");
+}

package/mcps/mcsc/packages/core/src/adapters/opencode.js

@@ -0,0 +1,183 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { emitTrail } from '../trail.js';
+
+const MAX_OUTPUT = 1024 * 1024 * 50; // 50MB, mirrors the old execFile maxBuffer
+
+/**
+ * CliAdapter shelling out to `opencode run --auto --format json [--model <model>] <prompt>`.
+ * Optional `req.variant` is passed through as `--variant <variant>` (model reasoning effort).
+ * Reads stdout line by line: assistant text parts are collected and joined as
+ * `output`; tool events are forwarded to the live map as PreToolUse/PostToolUse.
+ *
+ * @param {import('../types.js').DelegationRequest} req
+ * @returns {Promise<{ exit: number; output: string; attestation: { kind: 'unavailable'; } }>}
+ */
+export async function delegate(req) {
+  const cwd = req.cwd || process.cwd();
+  const trailEvent = {
+    session_id: `mcsc-opencode-${process.pid}-${Date.now()}`,
+    cwd,
+    agent:
+      typeof req.label === 'string' && req.label.length > 0
+        ? `opencode:${req.label}`
+        : 'opencode',
+  };
+  emitTrail({ ...trailEvent, hook_event_name: 'SessionStart' });
+
+  const env = { ...process.env, MCSC_CALLER: 'opencode' };
+  const args = ['run', '--auto', '--format', 'json'];
+  if (req.model) args.push('--model', req.model);
+  if (req.variant) args.push('--variant', String(req.variant));
+  args.push(req.prompt);
+
+  const child = spawn('opencode', args, {
+    cwd: req.cwd,
+    env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  return new Promise((resolve) => {
+    const textParts = [];
+    let stdoutBuf = '';
+    let stderrBuf = '';
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let overflowed = false;
+    let aborted = false;
+    let settled = false;
+
+    const onAbort = () => {
+      aborted = true;
+      child.kill('SIGKILL');
+    };
+    if (req.signal) {
+      if (req.signal.aborted) onAbort();
+      else req.signal.addEventListener('abort', onAbort, { once: true });
+    }
+
+    const finalize = (result) => {
+      if (settled) return;
+      settled = true;
+      if (req.signal) req.signal.removeEventListener('abort', onAbort);
+      emitTrail({ ...trailEvent, hook_event_name: 'SessionEnd' });
+      resolve(result);
+    };
+
+    const buildToolInput = (input) => {
+      const toolInput = {};
+      if (!input || typeof input !== 'object') return toolInput;
+      const rawPath = input.filePath || input.file_path || input.path || input.file;
+      if (typeof rawPath === 'string' && rawPath.length > 0) {
+        toolInput.file_path = path.isAbsolute(rawPath)
+          ? rawPath
+          : path.resolve(cwd, rawPath);
+      }
+      const rawCommand = input.command || input.cmd;
+      if (typeof rawCommand === 'string' && rawCommand.length > 0) {
+        toolInput.command = rawCommand;
+      }
+      return toolInput;
+    };
+
+    const handleLine = (line) => {
+      if (!line) return;
+      let evt;
+      try {
+        evt = JSON.parse(line);
+      } catch {
+        return; // Not valid JSON — ignore.
+      }
+      if (!evt || typeof evt !== 'object') return;
+      const part = evt.part;
+      if (!part || typeof part !== 'object') return;
+
+      if (evt.type === 'text') {
+        if (typeof part.text === 'string' && part.text.length > 0) {
+          textParts.push(part.text);
+        }
+        return;
+      }
+
+      if (
+        evt.type === 'tool_use' &&
+        typeof part.tool === 'string' &&
+        part.tool.length > 0
+      ) {
+        const state = part.state || {};
+        const finished = state.status === 'completed' || state.status === 'error';
+        emitTrail({
+          ...trailEvent,
+          hook_event_name: finished ? 'PostToolUse' : 'PreToolUse',
+          tool_name: part.tool.charAt(0).toUpperCase() + part.tool.slice(1),
+          tool_input: buildToolInput(state.input),
+        });
+      }
+    };
+
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+      stdoutBytes += Buffer.byteLength(chunk);
+      if (stdoutBytes > MAX_OUTPUT) {
+        if (!overflowed) {
+          overflowed = true;
+          child.kill('SIGKILL');
+        }
+        return;
+      }
+      stdoutBuf += chunk;
+      let idx;
+      while ((idx = stdoutBuf.indexOf('\n')) !== -1) {
+        const line = stdoutBuf.slice(0, idx).trim();
+        stdoutBuf = stdoutBuf.slice(idx + 1);
+        handleLine(line);
+      }
+    });
+
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk) => {
+      stderrBytes += Buffer.byteLength(chunk);
+      if (stderrBytes > MAX_OUTPUT) return; // cap stderr, never fail on it
+      stderrBuf += chunk;
+    });
+
+    child.on('error', (err) => {
+      finalize({
+        exit: 1,
+        output: (stderrBuf || err.message || '').trim(),
+        attestation: { kind: 'unavailable' },
+      });
+    });
+
+    child.on('close', (code) => {
+      const rest = stdoutBuf.trim();
+      if (rest) handleLine(rest); // flush a trailing line without newline
+      if (aborted) {
+        finalize({
+          exit: 1,
+          output: 'Cancelled by orchestrator',
+          attestation: { kind: 'unavailable' },
+        });
+        return;
+      }
+      if (overflowed) {
+        finalize({
+          exit: 1,
+          output: 'stdout maxBuffer length exceeded',
+          attestation: { kind: 'unavailable' },
+        });
+        return;
+      }
+      if (code === 0) {
+        const output = textParts.length > 0 ? textParts.join('\n') : stderrBuf;
+        finalize({ exit: 0, output, attestation: { kind: 'unavailable' } });
+        return;
+      }
+      finalize({
+        exit: 1,
+        output: (stderrBuf || `opencode exited with code ${code}`).trim(),
+        attestation: { kind: 'unavailable' },
+      });
+    });
+  });
+}

package/mcps/mcsc/packages/core/src/adapters/types.js

@@ -0,0 +1,21 @@
+/**
+ * @typedef {Object} DelegationRequest
+ * @property {string} taskType
+ * @property {string} prompt
+ * @property {string} model
+ * @property {string} cwd
+ * @property {string} [variant] Optional model variant (reasoning effort) passed to `opencode run --variant`.
+ */
+
+/**
+ * @typedef {Object} DelegationResult
+ * @property {number} exit
+ * @property {string} output
+ * @property {{
+ *   kind: 'confirmed' | 'mismatch' | 'unavailable',
+ *   modelId?: string,
+ *   sessionRef?: string,
+ *   requested?: string,
+ *   actual?: string
+ * }} attestation
+ */