@hybridlabor-api/aos 4.6.6 → 4.7.1

package/mcps/mcsc/packages/core/src/rulebook/load.js

@@ -0,0 +1,53 @@
+/**
+ * @typedef {import('js-yaml').YamlMap} YamlMap
+ *
+ * NOTE: This module depends on the npm package `js-yaml`.
+ * Add it to package.json: `npm i js-yaml`
+ * The package.json currently has no YAML dependency.
+ */
+import { load as parseYaml } from 'js-yaml';
+import { readFile } from 'node:fs/promises';
+
+/**
+ * Load and merge the rulebook YAML files.
+ *
+ * @param {{ defaultsPath: string; overridePath?: string }} opts
+ * @param {string} opts.defaultsPath - Path to the default rulebook YAML (e.g. packages/core/rulebook.default.yaml)
+ * @param {string} [opts.overridePath] - Path to the user override rulebook YAML (e.g. ~/.config/mcsc/rulebook.yaml)
+ * @returns {import('./rulebook.types.js').Rule[]} Merged rule list, with overrides applied by id,
+ *   disabled ids removed, and unknown ids appended.
+ */
+export async function loadRulebook({ defaultsPath, overridePath }) {
+  const defaultsContent = await readFile(defaultsPath, 'utf8');
+  const defaultsYaml = parseYaml(defaultsContent);
+
+  // Build a Map keyed by rule id for O(1) lookups and whole-rule replace
+  const merged = new Map();
+  for (const rule of defaultsYaml.rules || []) {
+    merged.set(rule.id, rule);
+  }
+
+  // Apply override layer
+  if (overridePath) {
+    try {
+      const overrideContent = await readFile(overridePath, 'utf8');
+      const overrideYaml = parseYaml(overrideContent);
+
+      // Per architecture.md §2: a top-level `disabled: [id]` list removes
+      // shipped rules — this is NOT a per-rule field.
+      for (const id of overrideYaml.disabled || []) {
+        merged.delete(id);
+      }
+
+      // Whole-rule replace by id (Map#set both replaces a known id and
+      // appends an unknown one — no deep-merging of candidate arrays).
+      for (const rule of overrideYaml.rules || []) {
+        merged.set(rule.id, rule);
+      }
+    } catch (_) {
+      // If override file doesn't exist or can't be parsed, keep defaults as-is
+    }
+  }
+
+  return [...merged.values()];
+}

package/mcps/mcsc/packages/core/src/rulebook/resolve.js

@@ -0,0 +1,227 @@
+/**
+ * PURE function: routing decision implementing the Rulebook §3 Decision logic
+ * and the §6 fallback/degradation contract.
+ *
+ * Synchronous, side-effect free, no Date.now() inside — the `attemptTrace`
+ * records resolutions but never calls `Date.now()` at the top level; the TTL
+ * check inside uses the offered `resolvedAt` timestamps only.
+ *
+ * @param {Object} taskDescriptor - { task_type: string, complexity?: string }
+ * @param {import('./rulebook.types.js').Rule[]} rules - Merged rule list from loadRulebook()
+ * @param {import('./rulebook.types.js').InventorySnapshot} inventorySnapshot - CLI health snapshot
+ * @param {import('./rulebook.types.js').OfferTable} offerTable - Model offer registry per CLI per rule
+ * @returns {import('./rulebook.types.js').Decision} Route or refuse decision
+ */
+export function decide(taskDescriptor, rules, inventorySnapshot, offerTable, now) {
+  // Step 0: Find the first rule whose match criteria the taskDescriptor satisfies
+  const matchingRule = rules.find(rule => matchesMatch(rule.match, taskDescriptor));
+
+  if (!matchingRule) {
+    return {
+      kind: 'refuse',
+      reason: 'no matching rule for task descriptor',
+      attempted: []
+    };
+  }
+
+  const candidates = matchingRule.candidates;
+  const attemptTrace = [];
+  const taskTier = inferTier(taskDescriptor, matchingRule);
+
+  // --- Helper: find offer for a CLI within this rule ---
+  function findOffer(cliId) {
+    const ruleOffers = offerTable[cliId]?.[matchingRule.id];
+    if (!ruleOffers) return null;
+    return ruleOffers;
+  }
+
+  // --- Step 1: Preferred CLI, live registry offer ---
+  // The "preferred CLI" is the first candidate in the rule's chain that is not 'native'
+  const preferredCandidate = candidates.find(c => c.cli !== 'native');
+  const preferredCliId = preferredCandidate ? preferredCandidate.cli : null;
+
+  if (preferredCliId) {
+    const cliHealth = inventorySnapshot.cliHealth?.[preferredCliId];
+    if (cliHealth && (cliHealth.status === 'ready' || cliHealth.status === 'degraded')) {
+      const offer = findOffer(preferredCliId);
+
+      // Step 1: Preferred CLI has a live registry offer
+      if (offer && offer.source === 'live-list') {
+        return {
+          kind: 'route',
+          cliId: preferredCliId,
+          offer: {
+            cliId: preferredCliId,
+            modelId: offer.modelId,
+            tier: offer.tier,
+            resolvedAt: offer.resolvedAt,
+            source: offer.source
+          },
+          degraded: cliHealth.status === 'degraded' ? ['cli-degraded'] : []
+        };
+      }
+
+      // Step 2: Preferred CLI, cached offer ≤ TTL
+      if (offer && offer.source !== 'live-list') {
+        const ttlMs = preferredCliId === 'opencode' ? 3_600_000 : 86_400_000; // 1h vs 24h
+        if (offer.resolvedAt != null && (now - offer.resolvedAt) <= ttlMs) {
+          return {
+            kind: 'route',
+            cliId: preferredCliId,
+            offer: {
+              cliId: preferredCliId,
+              modelId: offer.modelId,
+              tier: offer.tier,
+              resolvedAt: offer.resolvedAt,
+              source: offer.source
+            },
+            degraded: ['stale-offer']
+          };
+        }
+      }
+    }
+  }
+
+  // --- Steps 3 & 4: Fallback to other CLIs ---
+  // Identify non-native candidates in their declared order
+  const nonNativeCandidates = candidates.filter(c => c.cli !== 'native');
+
+  const checkedNonNative = new Set();
+  if (preferredCliId) checkedNonNative.add(preferredCliId);
+
+  // Step 3: Next CLI in the rule's candidates order, same tier
+  // Try each subsequent non-native candidate after the preferred one
+  // Skip index 0 (the preferred CLI already checked in steps 1-2)
+  for (let i = 1; i < nonNativeCandidates.length; i += 1) {
+    const cliId = nonNativeCandidates[i].cli;
+    const cliHealth = inventorySnapshot.cliHealth?.[cliId];
+
+    if (!cliHealth || cliHealth.status !== 'ready') {
+      attemptTrace.push({
+        step: `step3-${i}`,
+        cli: cliId,
+        reason: cliHealth?.status === 'unusable' ? 'cli-unusable' : 'cli-absent',
+        offered: false
+      });
+      checkedNonNative.add(cliId);
+      continue;
+    }
+
+    const offer = findOffer(cliId);
+    if (offer && offer.tier === taskTier) {
+      // Step 3: Next CLI in the rule's candidates order, same tier
+      return {
+        kind: 'route',
+        cliId,
+        offer: {
+          cliId,
+          modelId: offer.modelId,
+          tier: offer.tier,
+          resolvedAt: offer.resolvedAt,
+          source: offer.source
+        },
+        degraded: ['cli-substituted']
+      };
+    }
+
+    attemptTrace.push({
+      step: `step3-${i}`,
+      cli: cliId,
+      reason: 'tier-mismatch',
+      offered: false
+    });
+    checkedNonNative.add(cliId);
+  }
+
+  // Step 4: Any healthy CLI at the same tier (outside preference chain)
+  // Check all CLIs in the inventory, including those not in the candidate chain
+  for (const [cliId, health] of Object.entries(inventorySnapshot.cliHealth || {})) {
+    if (health.status !== 'ready' || cliId === 'native' || checkedNonNative.has(cliId)) continue;
+    checkedNonNative.add(cliId);
+
+    const offer = findOffer(cliId);
+    if (offer && offer.tier === taskTier) {
+      // Step 4: Any healthy CLI at the same tier, outside preference
+      return {
+        kind: 'route',
+        cliId,
+        offer: {
+          cliId,
+          modelId: offer.modelId,
+          tier: offer.tier,
+          resolvedAt: offer.resolvedAt,
+          source: offer.source
+        },
+        degraded: ['cli-substituted', 'outside-preference']
+      };
+    }
+
+    attemptTrace.push({
+      step: `step4-${cliId}`,
+      cli: cliId,
+      reason: 'tier-mismatch',
+      offered: false
+    });
+  }
+
+  // --- Step 5: Tier downgrade (if fail-open policy) ---
+  const rulePolicy = matchingRule.policy || (matchingRule.id === 'media-generation' ? 'fail-open' : 'fail-closed');
+  if (rulePolicy === 'fail-open') {
+    // Deterministic downgrade target: use 'quick-review' as the fallback tier
+    const downgradeTier = taskTier === 'complex-code' ? 'quick-review' : taskTier;
+    return {
+      kind: 'route',
+      cliId: 'native',
+      offer: {
+        cliId: 'native',
+        modelId: 'native',
+        tier: downgradeTier,
+        resolvedAt: now,
+        source: 'pinned'
+      },
+      degraded: ['tier-downgraded']
+    };
+  }
+
+  // --- Step 6: Otherwise refuse ---
+  return {
+    kind: 'refuse',
+    reason: 'no suitable CLI available after full fallback chain',
+    attempted: attemptTrace
+  };
+}
+
+/**
+ * Infer the task tier from the taskDescriptor and rule match criteria.
+ */
+function inferTier(taskDescriptor, rule) {
+  const { task_type, complexity } = taskDescriptor;
+  const { task_type: ruleTaskTypes, min_complexity } = rule.match;
+
+  if (ruleTaskTypes && Array.isArray(ruleTaskTypes) && ruleTaskTypes.includes(task_type)) {
+    return task_type;
+  }
+
+  if (min_complexity && complexity) {
+    return complexity;
+  }
+
+  // Default: media-generation falls to quick-review; others default quick-review too
+  return 'quick-review';
+}
+
+/**
+ * Check whether a taskDescriptor satisfies a rule's match criteria.
+ */
+function matchesMatch(matchCriteria, taskDescriptor) {
+  if (!matchCriteria.task_type) return true;
+
+  const descriptorTaskTypes = taskDescriptor.task_type;
+  const ruleTaskTypes = matchCriteria.task_type;
+
+  if (!Array.isArray(ruleTaskTypes)) {
+    return ruleTaskTypes === descriptorTaskTypes;
+  }
+
+  return ruleTaskTypes.some(rt => descriptorTaskTypes.includes(rt));
+}

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

@@ -0,0 +1,89 @@
+/**
+ * @typedef {Object} CliId
+ * @type {string}
+ * @readonly */
+export const CliId = {
+  AGY: 'agy',
+  OPENCODE: 'opencode',
+  CODEX: 'codex',
+  NATIVE: 'native'
+};
+
+/** @readonly */ export const Tier = {
+  DEEP_RESEARCH: 'deep-research',
+  COMPLEX_CODE: 'complex-code',
+  QUICK_REVIEW: 'quick-review',
+  MEDIA_GENERATION: 'media-generation'
+};
+
+/**
+ * @typedef {Object} ProbeResult
+ * @property {boolean} pass
+ * @property {string} evidence
+ * @property {string} reason
+ */
+
+/**
+ * @typedef {Object} CliHealth
+ * @property {('ready'|'degraded'|'unusable'|'absent')} status
+ * @property {string} binary
+ * @property {string} version
+ * @property {ProbeResult[]} probes
+ */
+
+/**
+ * @typedef {Object} ModelOffer
+ * @property {string} cliId
+ * @property {string} modelId
+ * @property {string} tier
+ * @property {string} resolvedAt
+ * @property {'live-list'|'pinned'|'stale-cache'} source
+ */
+
+/** @typedef {('stale-offer'|'cli-substituted'|'outside-preference'|'tier-downgraded')} DegradationNote */
+
+/**
+ * @typedef {Object} AttemptTrace
+ * @property {number} step
+ * @property {string} cli
+ * @property {string} reason
+ * @property {boolean} offered
+ */
+
+/**
+ * @typedef {Object} Rule
+ * @property {string} id
+ * @property {Object} match - { task_type: string[], min_complexity?: string }
+ * @property {Array<{cli: string, model?: string, model_select?: Object}>} candidates
+ * @property {('fail-open'|'fail-closed')} policy
+ */
+
+/**
+ * @typedef {Object} InventorySnapshot
+ * @property {{[cliId: string]: CliHealth}} cliHealth
+ */
+
+/**
+ * @typedef {Object} OfferTableEntry
+ * @property {string} modelId
+ * @property {string} tier
+ * @property {string} resolvedAt
+ * @property {'live-list'|'pinned'|'stale-cache'} source
+ */
+
+/**
+ * @typedef {Object} OfferTable
+ * @property {{[ruleId: string]: OfferTableEntry}} [ruleId]
+ * @property {{[cliId: string]: OfferTableEntry}} [cliId]
+ */
+
+/**
+ * @typedef {Object} Decision
+ * @property {('route'|'refuse')} kind
+ * @property {string} kind
+ * @property {string} cliId
+ * @property {ModelOffer} offer
+ * @property {DegradationNote[]} degraded
+ * @property {string} reason
+ * @property {AttemptTrace[]} attempted
+ */

package/mcps/mcsc/packages/core/src/trail.js

@@ -0,0 +1,17 @@
+// Best-effort fire-and-forget telemetry for the AOS live map (agenttrail daemon).
+export async function emitTrail(event) {
+  const body = JSON.stringify(event);
+  const ports = process.env.AGENTTRAIL_PORT
+    ? [Number(process.env.AGENTTRAIL_PORT)]
+    : Array.from({ length: 15 }, (_, i) => 5330 + i);
+  await Promise.allSettled(
+    ports.map((port) =>
+      fetch(`http://127.0.0.1:${port}/hook`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body,
+        signal: AbortSignal.timeout(300),
+      }).catch(() => {})
+    )
+  );
+}

package/mcps/mcsc/packages/mcp/server.js

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { runInventory } from "../core/src/detect/inventory.js";
+import { getCached, setCached } from "../core/src/detect/cache.js";
+import { delegate as agyDelegate } from "../core/src/adapters/agy.js";
+import { delegate as opencodeDelegate } from "../core/src/adapters/opencode.js";
+import { delegate as codexDelegate } from "../core/src/adapters/codex.js";
+import { decide } from "../core/src/rulebook/resolve.js";
+import { loadRulebook } from "../core/src/rulebook/load.js";
+import { buildOfferTable } from "../core/src/capabilities/buildOfferTable.js";
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// --- Global State ---
+let inventory = new Map();
+let rules = [];
+let offerTable = {};
+
+const caller = process.env.MCSC_CALLER || 'none';
+const CLI_IDS = ['agy', 'opencode', 'codex'];
+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) {
+    try {
+      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);
+      }
+    } catch (e) {
+      console.error(`[mcsc-mcp] Warning: inventory run failed: ${e.message}`);
+    }
+  }
+
+  return cliHealthMap;
+}
+
+// --- Initialization ---
+async function init() {
+  inventory = await getInventory();
+
+  const customRulebook = path.resolve(process.cwd(), 'rulebook.yaml');
+  const defaultRulebook = path.resolve(__dirname, '../core/rulebook.default.yaml');
+  const rulebookPath = fs.existsSync(customRulebook) ? customRulebook : defaultRulebook;
+
+  try {
+    if (fs.existsSync(rulebookPath)) {
+      rules = loadRulebook(rulebookPath);
+      const now = Date.now();
+      offerTable = await buildOfferTable(rules, inventory, now);
+    }
+  } catch (e) {
+    console.error(`[mcsc-mcp] Warning: could not load rulebook from ${rulebookPath}: ${e.message}`);
+  }
+}
+
+// --- MCP Server Definition ---
+const server = new Server(
+  {
+    name: "mcsc-mcp",
+    version: "0.1.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// --- Tool Registration ---
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  const tools = [];
+
+  // delegate_agy
+  const agyHealth = inventory.get('agy');
+  if (agyHealth && agyHealth.status === 'ready' && caller !== 'agy') {
+    tools.push({
+      name: "delegate_agy",
+      description: "Delegate a task to Antigravity CLI (Gemini 3.8 Flash or Claude 3.7 Sonnet). Provides full coding capabilities.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          prompt: {
+            type: "string",
+            description: "The complete task description or objective for the subagent to accomplish."
+          },
+          model: {
+            type: "string",
+            description: "Optional model hint for the subagent (e.g., 'flash', 'pro'). Default varies by tool.",
+            default: "flash"
+          }
+        },
+        required: ["prompt"]
+      }
+    });
+  }
+
+  // delegate_opencode
+  const opencodeHealth = inventory.get('opencode');
+  if (opencodeHealth && opencodeHealth.status === 'ready' && caller !== 'opencode') {
+    tools.push({
+      name: "delegate_opencode",
+      description: "Delegate a task to OpenCode CLI.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          prompt: {
+            type: "string",
+            description: "The complete task description."
+          },
+          model: {
+            type: "string",
+            description: "Optional model override."
+          },
+          variant: {
+            type: "string",
+            description: "Optional model variant (reasoning effort, e.g. high/max/minimal)."
+          }
+        },
+        required: ["prompt"]
+      }
+    });
+  }
+
+  // delegate_codex
+  const codexHealth = inventory.get('codex');
+  if (codexHealth && codexHealth.status === 'ready' && caller !== 'codex') {
+    tools.push({
+      name: "delegate_codex",
+      description: "Delegate a task to Codex CLI.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          prompt: {
+            type: "string",
+            description: "The complete task description."
+          },
+          model: {
+            type: "string",
+            description: "Optional model override."
+          }
+        },
+        required: ["prompt"]
+      }
+    });
+  }
+
+  // delegate_smart (Routing Engine)
+  if (rules && rules.length > 0) {
+    tools.push({
+      name: "delegate_smart",
+      description: "Smart task delegation. Reads the rulebook to find the best CLI for the task type and delegates automatically.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          task_type: {
+            type: "string",
+            description: "The type of task (e.g. 'review', 'architecture', 'media')."
+          },
+          prompt: {
+            type: "string",
+            description: "The exact prompt for the delegated CLI."
+          }
+        },
+        required: ["task_type", "prompt"]
+      }
+    });
+  }
+
+  return { tools };
+});
+
+// --- Tool Execution ---
+server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+  const { name, arguments: args } = request.params;
+  const signal = extra.signal;
+
+  const req = {
+    cwd: process.cwd(),
+    prompt: args.prompt,
+    model: args.model,
+    variant: args.variant,
+    signal
+  };
+
+  try {
+    let result;
+
+    switch (name) {
+      case "delegate_agy":
+        result = await agyDelegate(req);
+        break;
+
+      case "delegate_opencode":
+        result = await opencodeDelegate(req);
+        break;
+
+      case "delegate_codex":
+        result = await codexDelegate(req);
+        break;
+
+      case "delegate_smart": {
+        const taskDescriptor = { task_type: args.task_type };
+        const snapshot = { cliHealth: Object.fromEntries(inventory) };
+        const decision = decide(taskDescriptor, rules, snapshot, offerTable, Date.now());
+
+        if (decision.kind === 'refuse') {
+          return {
+            content: [{ type: "text", text: `Smart Delegation refused: ${decision.reason}` }],
+            isError: true,
+          };
+        }
+
+        if (decision.offer && decision.offer.modelId) {
+          req.model = decision.offer.modelId;
+        }
+
+        switch (decision.cliId) {
+          case 'agy':
+            result = await agyDelegate(req);
+            break;
+          case 'opencode':
+            result = await opencodeDelegate(req);
+            break;
+          case 'codex':
+            result = await codexDelegate(req);
+            break;
+          case 'native':
+            throw new Error("Task requires native handling by the current orchestrator. Do not use delegate tools for this.");
+          default:
+            throw new Error(`Unknown CLI: ${decision.cliId}`);
+        }
+        break;
+      }
+
+      default:
+        return {
+          content: [{ type: "text", text: `Unknown tool: ${name}` }],
+          isError: true,
+        };
+    }
+
+    if (result.exit !== 0) {
+      return {
+        content: [{ type: "text", text: `Delegation failed (Exit ${result.exit}):\n${result.output}` }],
+        isError: true,
+      };
+    }
+
+    return {
+      content: [{ type: "text", text: result.output }],
+    };
+
+  } catch (error) {
+    if (error.name === 'AbortError') {
+      return {
+        content: [{ type: "text", text: "Tool execution was cancelled by the orchestrator." }],
+        isError: true,
+      };
+    }
+    return {
+      content: [{ type: "text", text: `Error executing ${name}: ${error.message}` }],
+      isError: true,
+    };
+  }
+});
+
+// --- Startup ---
+async function main() {
+  await init();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("MCSC MCP Server running on stdio");
+}
+
+main().catch((error) => {
+  console.error("Server error:", error);
+  process.exit(1);
+});

package/mcps/mcsc/server.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import './packages/mcp/server.js';