@hybridlabor-api/aos 4.6.6 → 4.7.0

package/mcps/mcsc/packages/core/src/capabilities/buildOfferTable.js

@@ -0,0 +1,34 @@
+import { resolveOffer } from './registry.js';
+
+/**
+ * @param {Array<any>} rules
+ * @param {Map<import('./types.js').CliId, any>} inventorySnapshot
+ * @param {number} now
+ * @returns {Promise<Object>} offerTable
+ */
+export async function buildOfferTable(rules, inventorySnapshot, now) {
+  const offerTable = {};
+
+  for (const rule of rules) {
+    if (!rule.candidates) continue;
+    const tier = rule.id;
+
+    for (const candidate of rule.candidates) {
+      const cliId = candidate.cli;
+      if (cliId === 'native') continue;
+
+      const health = inventorySnapshot.get(cliId);
+      if (!health || (health.status !== 'ready' && health.status !== 'degraded')) continue;
+
+      const offer = await resolveOffer(cliId, tier, now);
+      if (offer) {
+        if (!offerTable[cliId]) {
+          offerTable[cliId] = {};
+        }
+        offerTable[cliId][rule.id] = offer;
+      }
+    }
+  }
+
+  return offerTable;
+}

package/mcps/mcsc/packages/core/src/capabilities/registry.js

@@ -0,0 +1,99 @@
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * @param {import('./types.js').CliId} cliId
+ * @param {import('./types.js').Tier} tier
+ * @param {number} now
+ * @returns {Promise<import('./types.js').ModelOffer | null>}
+ */
+export async function resolveOffer(cliId, tier, now) {
+  if (cliId === 'agy') {
+    try {
+      const { stdout } = await execFileAsync('agy', ['models']);
+      // Expected output format: 
+      // Fetching available models...
+      // gemini-3.8-flash-high   Gemini 3.8 Flash (High)
+      const lines = stdout.split('\n').map(l => l.trim()).filter(l => l.length > 0 && !l.startsWith('Fetching'));
+      const models = lines.map(l => l.split(/\s+/)[0]);
+      
+      let selectedModel = null;
+      if (tier === 'complex-code') {
+        const claudes = models.filter(m => m.includes('claude'));
+        if (claudes.length > 0) {
+          selectedModel = claudes[0];
+        } else {
+          const proModels = models.filter(m => m.includes('pro'));
+          if (proModels.length > 0) {
+            selectedModel = proModels[0];
+          }
+        }
+      } else if (['deep-research', 'quick-review', 'media-generation'].includes(tier)) {
+        const flashes = models.filter(m => m.includes('flash'));
+        if (flashes.length > 0) {
+          selectedModel = flashes[0];
+        }
+      }
+
+      if (!selectedModel && models.length > 0) {
+        selectedModel = models[0];
+      }
+
+      if (selectedModel) {
+        return {
+          cliId,
+          modelId: selectedModel,
+          tier,
+          resolvedAt: now,
+          source: 'live-list'
+        };
+      }
+      return null;
+    } catch (e) {
+      return null;
+    }
+  }
+
+  if (cliId === 'opencode') {
+    try {
+      const { stdout } = await execFileAsync('opencode', ['models']);
+      const lines = stdout.split('\n').map(l => l.trim());
+      const opencodeFreeModels = lines.filter(l => l.startsWith('opencode/') && l.toLowerCase().includes('free'));
+      
+      let selectedModel = null;
+      if (tier === 'complex-code') {
+        selectedModel = opencodeFreeModels.find(m => m.includes('ultra') || m.includes('pro'));
+      } else if (['deep-research', 'quick-review', 'media-generation'].includes(tier)) {
+        selectedModel = opencodeFreeModels.find(m => m.includes('lightning') || m.includes('flash'));
+      }
+
+      let source = 'live-list';
+      if (!selectedModel && opencodeFreeModels.length > 0) {
+        // v1 heuristic fallback
+        selectedModel = opencodeFreeModels[0];
+        source = 'pinned'; 
+      }
+
+      if (selectedModel) {
+        return {
+          cliId,
+          modelId: selectedModel,
+          tier,
+          resolvedAt: now,
+          source
+        };
+      }
+      return null;
+    } catch (e) {
+      return null;
+    }
+  }
+
+  if (cliId === 'native' || cliId === 'codex') {
+    return null;
+  }
+
+  return null;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * @typedef {'agy' | 'opencode' | 'codex' | 'native'} CliId
+ */
+
+/**
+ * @typedef {'deep-research' | 'complex-code' | 'quick-review' | 'media-generation'} Tier
+ */
+
+/**
+ * @typedef {Object} ModelOffer
+ * @property {CliId} cliId
+ * @property {string} modelId
+ * @property {Tier} tier
+ * @property {number} resolvedAt
+ * @property {'live-list' | 'pinned' | 'stale-cache'} source
+ */
+
+/**
+ * @typedef {Object} CapabilityRegistryPort
+ * @property {(cliId: CliId, tier: Tier, now: number) => Promise<ModelOffer | null>} resolveOffer
+ * @property {(cliId: CliId) => Promise<void>} refresh
+ */
+
+export {};

package/mcps/mcsc/packages/core/src/detect/cache.js

@@ -0,0 +1,47 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const CACHE_DIR = join(homedir(), '.config', 'mcsc');
+const CACHE_FILE = join(CACHE_DIR, 'capabilities.json');
+
+/**
+ * @param {string} cliId
+ * @returns {Promise<import('./types.js').CliHealth | null>}
+ */
+export const getCached = async (cliId) => {
+  try {
+    const data = JSON.parse(await readFile(CACHE_FILE, 'utf8'));
+    if (!data[cliId]) return null;
+    const entry = data[cliId];
+    const now = Date.now(); // must match setCached's Date.now() — performance.now() is a different clock (process-uptime-relative)
+    if (now - entry.timestamp > entry.ttl) {
+      delete data[cliId];
+      await writeFile(CACHE_FILE, JSON.stringify(data, null, 2));
+      return null;
+    }
+    return entry.health;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * @param {string} cliId
+ * @param {import('./types.js').CliHealth} health
+ * @param {number} ttlMs
+ */
+export const setCached = async (cliId, health, ttlMs) => {
+  try {
+    const data = {};
+    try {
+      const existing = JSON.parse(await readFile(CACHE_FILE, 'utf8'));
+      Object.assign(data, existing);
+    } catch {}
+    data[cliId] = { health, timestamp: Date.now(), ttl: ttlMs };
+    await mkdir(CACHE_DIR, { recursive: true });
+    await writeFile(CACHE_FILE, JSON.stringify(data, null, 2));
+  } catch {
+    // cache write failure is non-fatal
+  }
+};

package/mcps/mcsc/packages/core/src/detect/inventory.js

@@ -0,0 +1,73 @@
+import { probes } from './probes.js';
+// CliHealth is a JSDoc-only typedef in ./types.js — reference it via
+// `@typedef {import('./types.js').CliHealth} CliHealth` in comments, never
+// as a real import (there is nothing to import at runtime).
+import { execFile as execFileCb } from 'node:child_process';
+import { stat, readFile } from 'node:fs/promises';
+
+/** @param {{cliIds: string[], maxAgeMs: number}} opts */
+export const runInventory = async ({ cliIds, maxAgeMs }) => {
+  const cliHealthMap = new Map();
+
+  const sh = {
+    cliId: '',
+    execFile: (cmd, args, options) =>
+      new Promise((resolve, reject) => {
+        execFileCb(cmd, args, options, (error, stdout, stderr) => {
+          if (error) reject(error);
+          else resolve({ stdout, stderr });
+        });
+      }),
+    stat: (p) => stat(p).then((s) => ({ mtime: s.mtimeMs })),
+    readFile: (p) => readFile(p, 'utf8'),
+  };
+
+  for (const cliId of cliIds) {
+    sh.cliId = cliId;
+    const cliProbes = probes.filter((p) => p.cliId === cliId);
+    const probesResults = [];
+
+    for (const probe of cliProbes) {
+      try {
+        const result = await probe.run(sh);
+        probesResults.push(result.pass ? { pass: true } : { pass: false, evidence: result.evidence, reason: result.reason });
+      } catch (e) {
+        probesResults.push({ pass: false, evidence: e.message, reason: 'probe-error' });
+      }
+    }
+
+    const allPass = probesResults.every((r) => r.pass);
+    const hasUnusable = probesResults.some(
+      (r) => r.reason === 'not-on-path' || r.reason === 'unauthenticated' || r.reason === 'permissions' || r.reason === 'hangs' || r.reason === 'version-unsupported'
+    );
+
+    let status, binary, version, reason;
+
+    if (allPass) {
+      status = 'ready';
+      binary = 'resolved';
+      version = 'detected';
+    } else if (hasUnusable) {
+      status = 'unusable';
+      const unusableReason = probesResults.find(
+        (r) => r.reason && ['not-on-path', 'unauthenticated', 'permissions', 'hangs', 'version-unsupported'].includes(r.reason)
+      )?.reason || 'unknown';
+      reason = unusableReason;
+      // 'missing' only when the binary itself couldn't be resolved — every
+      // other reason (unauthenticated, permissions, hangs, version-unsupported)
+      // means the binary IS on PATH, just unusable for some other cause.
+      // Collapsing all of these to 'missing' told operators a real, installed
+      // CLI "wasn't there" when the actual fix was e.g. `codex login`.
+      binary = unusableReason === 'not-on-path' ? 'missing' : 'resolved';
+      version = binary === 'missing' ? 'n/a' : 'detected';
+    } else {
+      status = 'degraded';
+      binary = 'resolved';
+      version = 'detected';
+    }
+
+    cliHealthMap.set(cliId, { status, binary, version, probes: probesResults, ...(status === 'unusable' ? { reason } : {}) });
+  }
+
+  return cliHealthMap;
+};

package/mcps/mcsc/packages/core/src/detect/probes.js

@@ -0,0 +1,158 @@
+import { execFile } from 'node:child_process';
+import { stat, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {object} options
+ * @returns {Promise<{stdout: string, stderr: string, error: any}>}
+ */
+const runExecFile = (cmd, args, options) => {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, options, (error, stdout, stderr) => {
+      if (error) reject(error);
+      else resolve({ stdout, stderr, error });
+    });
+  });
+};
+
+/** @param {string} path */
+const statPath = (path) => stat(path).then((s) => ({ mtime: s.mtimeMs }));
+
+/** @param {string} path */
+const readFilePath = (path) => readFile(path, 'utf8');
+
+/**
+ * @param {{execFile: (cmd: string, args: string[], options?: object) => Promise<any>,
+ *           stat: (path: string) => Promise<{mtime: number}>,
+ *           readFile: (path: string) => Promise<string>}} sh
+ * @returns {Promise<{pass: boolean, evidence?: string, reason?: string}>}
+ */
+const binaryResolvable = async (sh) => {
+  const binaryMap = { agy: 'agy', opencode: 'opencode', codex: 'codex' };
+  const name = binaryMap[sh.cliId];
+  if (!name) return { pass: false, reason: 'unknown-cli' };
+  try {
+    const which = await runExecFile('which', [name], {});
+    const resolvedPath = which.stdout.trim();
+    // realpath does no PATH lookup of its own — it needs the actual path
+    // `which` just resolved, not the bare command name.
+    await runExecFile('realpath', [resolvedPath], {});
+    return { pass: true };
+  } catch {
+    return { pass: false, evidence: `binary '${name}' not resolvable`, reason: 'not-on-path' };
+  }
+};
+
+/**
+ * @param {{execFile: (cmd: string, args: string[], options?: object) => Promise<any>,
+ *           readFile: (path: string) => Promise<string>}} sh
+ * @returns {Promise<{pass: boolean, evidence?: string, reason?: string}>}
+ */
+const authLive = async (sh) => {
+  try {
+    if (sh.cliId === 'agy') {
+      await runExecFile('agy', ['models'], { timeout: 15000 });
+      return { pass: true };
+    }
+    if (sh.cliId === 'opencode') {
+      await runExecFile('opencode', ['models'], { timeout: 15000 });
+      return { pass: true };
+    }
+    if (sh.cliId === 'codex') {
+      await runExecFile('codex', ['models'], { timeout: 15000 });
+      return { pass: true };
+    }
+    return { pass: false, evidence: 'no auth command for this CLI', reason: 'unauthenticated' };
+  } catch (e) {
+    return { pass: false, evidence: e.message, reason: 'unauthenticated' };
+  }
+};
+
+/**
+ * @param {{execFile: (cmd: string, args: string[], options?: object) => Promise<any>,
+ *           stat: (path: string) => Promise<{mtime: number}>,
+ *           readFile: (path: string) => Promise<string>}} sh
+ * @returns {Promise<{pass: boolean, evidence?: string, reason?: string}>}
+ */
+const opencodeFsOwnership = async (sh) => {
+  const configDirs = [
+    join(homedir(), '.config', 'opencode'),
+    join(homedir(), '.cache', 'opencode'),
+    join(homedir(), '.local', 'state', 'opencode'),
+    join(homedir(), '.local', 'share', 'opencode'),
+  ];
+  for (const dir of configDirs) {
+    try {
+      await statPath(dir);
+    } catch {
+      return { pass: false, evidence: `config dir '${dir}' not accessible`, reason: 'permissions' };
+    }
+  }
+  return { pass: true };
+};
+
+/**
+ * @param {{execFile: (cmd: string, args: string[], options?: object) => Promise<any>,
+ *           readFile: (path: string) => Promise<string>}} sh
+ * @returns {Promise<{pass: boolean, evidence?: string, reason?: string}>}
+ */
+const agyMcpHeadlessLatency = async (sh) => {
+  const start = Date.now();
+  try {
+    await runExecFile('agy', ['--print-timeout', '20s', '-p', 'OK'], {});
+    const duration = Date.now() - start;
+    if (duration > 20000) {
+      return { pass: false, evidence: `latency ${duration}ms exceeds 20s budget`, reason: 'degrade' };
+    }
+    return { pass: true };
+  } catch (e) {
+    return { pass: false, evidence: e.message, reason: 'degrade' };
+  }
+};
+
+/**
+ * @param {{execFile: (cmd: string, args: string[], options?: object) => Promise<any>,
+ *           readFile: (path: string) => Promise<string>}} sh
+ * @returns {Promise<{pass: boolean, evidence?: string, reason?: string}>}
+ */
+const tierFreshness = async (sh) => {
+  try {
+    if (sh.cliId === 'opencode') {
+      await runExecFile('opencode', ['models'], { timeout: 15000 });
+      return { pass: true };
+    }
+    if (sh.cliId === 'agy') {
+      await runExecFile('agy', ['models'], { timeout: 15000 });
+      return { pass: true };
+    }
+    if (sh.cliId === 'codex') {
+      await runExecFile('codex', ['models'], { timeout: 15000 });
+      return { pass: true };
+    }
+    return { pass: true };
+  } catch (e) {
+    return { pass: false, evidence: e.message, reason: 'stale-tier' };
+  }
+};
+
+/**
+ * @type {Probe[]}
+ */
+export const probes = [
+  { id: 'agy.binary.resolvable', cliId: 'agy', severity: 'fatal', timeoutMs: 10000, run: binaryResolvable, remedy: { human: 'Install agy via npm/brew', command: 'which agy', autoFixable: true } },
+  { id: 'opencode.binary.resolvable', cliId: 'opencode', severity: 'fatal', timeoutMs: 10000, run: binaryResolvable, remedy: { human: 'Install opencode via npm', command: 'which opencode', autoFixable: true } },
+  { id: 'codex.binary.resolvable', cliId: 'codex', severity: 'fatal', timeoutMs: 10000, run: binaryResolvable, remedy: { human: 'Install codex CLI', command: 'which codex', autoFixable: true } },
+  { id: 'agy.auth.live', cliId: 'agy', severity: 'fatal', timeoutMs: 15000, run: authLive, remedy: { human: 'Re-authenticate agy', command: 'agy login', autoFixable: false } },
+  { id: 'opencode.auth.live', cliId: 'opencode', severity: 'fatal', timeoutMs: 15000, run: authLive, remedy: { human: 'Re-authenticate opencode', command: 'opencode login', autoFixable: false } },
+  { id: 'codex.auth.live', cliId: 'codex', severity: 'fatal', timeoutMs: 15000, run: authLive, remedy: { human: 'Authenticate codex', command: 'codex login', autoFixable: false } },
+  { id: 'opencode.fs.ownership', cliId: 'opencode', severity: 'fatal', timeoutMs: 10000, run: opencodeFsOwnership, remedy: { human: 'Fix opencode config dir ownership', command: 'chown -R $(whoami):staff ~/.config/opencode', autoFixable: true } },
+  { id: 'agy.mcp.headless-latency', cliId: 'agy', severity: 'degrade', timeoutMs: 20000, run: agyMcpHeadlessLatency, remedy: { human: 'Investigate MCP server connectivity', command: 'agy mcp list', autoFixable: false } },
+  { id: 'opencode.tier.freshness', cliId: 'opencode', severity: 'degrade', timeoutMs: 15000, run: tierFreshness, remedy: { human: 'Refresh opencode model list', command: 'opencode models', autoFixable: false } },
+  { id: 'agy.tier.freshness', cliId: 'agy', severity: 'degrade', timeoutMs: 15000, run: tierFreshness, remedy: { human: 'Refresh agy model list', command: 'agy models', autoFixable: false } },
+  { id: 'codex.tier.freshness', cliId: 'codex', severity: 'degrade', timeoutMs: 15000, run: tierFreshness, remedy: { human: 'Refresh codex model list', command: 'codex models', autoFixable: false } },
+];
+
+export default probes;

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

@@ -0,0 +1,26 @@
+/**
+ * @typedef {'agy'|'opencode'|'codex'|'native'} CliId
+ */
+
+/**
+ * @typedef {{pass: boolean, evidence?: string, reason?: string}} ProbeResult
+ */
+
+/**
+ * @typedef {{id: string, cliId: CliId, severity: 'fatal'|'degrade'|'info', timeoutMs: number,
+ *   run: (sh: {execFile: (cmd: string, args: string[], options?: object) => Promise<any>,
+ *            fs: {stat: (path: string) => Promise<{mtime: number}>,
+ *                   readFile: (path: string) => Promise<string>}), ProbeResult,
+ *   remedy: {human: string, command?: string, autoFixable: boolean}}} Probe
+ */
+
+/**
+ * @typedef {{status: 'ready'|'degraded'|'unusable'|'absent', binary: string, version: string, probes: ProbeResult[]}} CliHealth.ready
+ * @typedef {{status: 'unusable', reason: 'not-on-path'|'unauthenticated'|'permissions'|'hangs'|'version-unsupported', probes: ProbeResult[]}} CliHealth.unusable
+ * @typedef {{status: 'absent'}} CliHealth.absent
+ * @typedef {CliHealth.ready | CliHealth.unusable | CliHealth.absent} CliHealth
+ */
+
+// These are JSDoc-only typedefs — nothing to export at runtime. Other files
+// reference them via `@typedef {import('./types.js').CliHealth} CliHealth`.
+export {};

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()];
+}