@stravica-ai/digital-operator-pa 0.1.13 → 0.1.16

package/dist/engineering-pa-cli/src/agent/cli.mjs

@@ -0,0 +1,266 @@
+// cli.mjs — argv router for `pa agent <verb>`.
+//
+// Verbs:
+//   pa agent audit            Read cache, auto-refresh if stale, print
+//                             summary + gap list. Fast path — cached.
+//   pa agent audit refresh    Force rebuild of the audit cache.
+//
+// Global flags:
+//   --format <human|json>     Output format (default: human)
+//   --quiet                   Suppress stdout; the cache write is the payload
+//   --strict                  Return non-zero exit if any capability is 'fail'
+//   --pa-name <name>          Override the PA name (defaults to preferences.paName)
+//
+// Exit codes (tooling standard §6):
+//   0 ok  |  1 usage error  |  2 unresolvable state (missing manifest,
+//   missing repo root, unresolvable paName, cache write failure). Under
+//   --strict, any 'fail' capability also produces exit 2.
+//
+// Cache: <repo-root>/.session/agent-audit.json.
+// Staleness: 60 minutes, override via operator/config/preferences.json:
+//            agentAudit.cacheStalenessMinutes.
+//
+// Performance target: cache-read <2s (session-boot budget), refresh <3s
+// on a real estate. All probes are Node-only synchronous, so the whole
+// audit is a walk of a handful of files — well under budget.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { hostname as osHostname } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import { loadBundledManifestSync } from '../../../engineering-pa-core/src/agent-baseline/manifest.mjs';
+
+import { auditManifest } from './audit.mjs';
+import { getRepoRoot } from '../pa/repo-root.mjs';
+
+const CLI_VERSION = '0.1.0';
+const DEFAULT_STALENESS_MINUTES = 60;
+
+const USAGE = `pa agent — agent baseline audit
+
+Usage:
+  pa agent audit                Read cache; auto-refresh if missing/stale
+  pa agent audit refresh        Force rebuild of the audit cache
+  pa agent -h, --help           Show this help
+
+Global flags:
+  --format <human|json>         Output format (default: human)
+  --quiet                       Suppress stdout summary
+  --strict                      Exit non-zero if any capability is 'fail'
+  --pa-name <name>              Override the PA name (defaults to preferences.paName)
+
+Cache file: <repo-root>/.session/agent-audit.json.
+Staleness threshold: 60 minutes (override via operator/config/preferences.json:
+agentAudit.cacheStalenessMinutes).
+
+Exit codes (tooling standard §6):
+  0 ok | 1 usage | 2 unresolvable state | 2 --strict fail
+`;
+
+/**
+ * Entry point. Returns an exit code.
+ */
+export async function run(argv) {
+  const args = argv ?? [];
+  if (args.length === 0 || args.includes('-h') || args.includes('--help')) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  try {
+    // parseArgs is inside the try so usage errors (unknown flag, bad
+    // --format value) surface as the clean `[pa agent] ...` stderr line
+    // + intentional exit code, not a raw Node stack trace via the
+    // unhandled-rejection path.
+    const { positionals, flags } = parseArgs(args);
+    const verb = positionals[0];
+    const sub = positionals[1] ?? 'default';
+
+    if (verb !== 'audit') {
+      process.stderr.write(`[pa agent] unknown verb: ${verb}\n`);
+      process.stderr.write(USAGE);
+      return 1;
+    }
+
+    if (sub === 'default') return await runAudit({ flags, forceRefresh: false });
+    if (sub === 'refresh') return await runAudit({ flags, forceRefresh: true });
+    process.stderr.write(`[pa agent audit] unknown subverb: ${sub}\n`);
+    process.stderr.write(USAGE);
+    return 1;
+  } catch (err) {
+    process.stderr.write(`[pa agent] ${err.message || err}\n`);
+    return err.exitCode ?? 2;
+  }
+}
+
+function parseArgs(argv) {
+  const flags = { format: 'human', quiet: false, strict: false, paName: null };
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--format') { flags.format = argv[++i]; continue; }
+    if (arg.startsWith('--format=')) { flags.format = arg.slice('--format='.length); continue; }
+    if (arg === '--quiet') { flags.quiet = true; continue; }
+    if (arg === '--strict') { flags.strict = true; continue; }
+    if (arg === '--pa-name') { flags.paName = argv[++i]; continue; }
+    if (arg.startsWith('--pa-name=')) { flags.paName = arg.slice('--pa-name='.length); continue; }
+    if (arg.startsWith('--')) {
+      const err = new Error(`unknown flag ${arg}`);
+      err.exitCode = 1;
+      throw err;
+    }
+    positionals.push(arg);
+  }
+  if (flags.format !== 'human' && flags.format !== 'json') {
+    const err = new Error(`--format must be human|json (got ${JSON.stringify(flags.format)})`);
+    err.exitCode = 1;
+    throw err;
+  }
+  return { positionals, flags };
+}
+
+async function runAudit({ flags, forceRefresh }) {
+  const repoRoot = await getRepoRoot();
+  const cachePath = cacheFilePath(repoRoot);
+  const staleness = readStalenessMinutes(repoRoot);
+  const paName = flags.paName ?? readPaName(repoRoot);
+  if (!paName) {
+    const err = new Error('paName not resolvable — set operator/config/preferences.json:paName or pass --pa-name');
+    err.exitCode = 2;
+    throw err;
+  }
+  const cached = forceRefresh ? null : readCache(cachePath);
+  const stale = cached ? isStale(cached, staleness) : true;
+  let audit;
+  if (!cached || stale) {
+    audit = performAudit({ repoRoot, paName });
+    writeCache(cachePath, audit);
+  } else {
+    audit = cached;
+  }
+  if (!flags.quiet) {
+    if (flags.format === 'json') {
+      process.stdout.write(JSON.stringify(audit, null, 2) + '\n');
+    } else {
+      process.stdout.write(formatHuman(audit) + '\n');
+    }
+  }
+  if (flags.strict && audit.summary.fail > 0) return 2;
+  return 0;
+}
+
+/**
+ * Perform a fresh audit — pure orchestration around the manifest loader
+ * and the audit runner. Exported for the boot-context hook and tests.
+ */
+export function performAudit({ repoRoot, paName, now, hostname }) {
+  const manifest = loadBundledManifestSync();
+  const ctx = {
+    repoRoot,
+    paName,
+    hostname: hostname ?? safeHostname(),
+    now: now ?? Date.now(),
+  };
+  return auditManifest(manifest, ctx);
+}
+
+function safeHostname() {
+  try { return osHostname(); } catch { return null; }
+}
+
+function cacheFilePath(repoRoot) {
+  return join(repoRoot, '.session', 'agent-audit.json');
+}
+
+function readCache(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(path, cache) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(cache, null, 2) + '\n');
+  } catch (err) {
+    const wrapped = new Error(`could not write cache to ${path}: ${err.message}`);
+    wrapped.exitCode = 2;
+    throw wrapped;
+  }
+}
+
+function isStale(cache, stalenessMinutes) {
+  if (!cache?.capturedAt) return true;
+  const capturedMs = Date.parse(cache.capturedAt);
+  if (!Number.isFinite(capturedMs)) return true;
+  const ageMs = Date.now() - capturedMs;
+  return ageMs > stalenessMinutes * 60 * 1000;
+}
+
+function readStalenessMinutes(repoRoot) {
+  try {
+    const prefsPath = join(repoRoot, 'operator', 'config', 'preferences.json');
+    if (existsSync(prefsPath)) {
+      const prefs = JSON.parse(readFileSync(prefsPath, 'utf8'));
+      const value = prefs?.agentAudit?.cacheStalenessMinutes;
+      if (typeof value === 'number' && value > 0) return value;
+    }
+  } catch {
+    // fall through
+  }
+  return DEFAULT_STALENESS_MINUTES;
+}
+
+function readPaName(repoRoot) {
+  try {
+    const prefsPath = join(repoRoot, 'operator', 'config', 'preferences.json');
+    if (existsSync(prefsPath)) {
+      const prefs = JSON.parse(readFileSync(prefsPath, 'utf8'));
+      if (typeof prefs.paName === 'string' && prefs.paName.length > 0) return prefs.paName;
+    }
+  } catch {
+    // fall through
+  }
+  return null;
+}
+
+function formatHuman(audit) {
+  const parts = [];
+  parts.push(`Agent baseline audit @ ${audit.capturedAt}`);
+  parts.push(`  manifest v${audit.manifestVersion} (schema ${audit.schemaVersion})`);
+  parts.push(`  paName: ${audit.context.paName}   hostname: ${audit.context.hostname ?? '-'}`);
+  parts.push('');
+  const s = audit.summary;
+  parts.push(
+    `Summary: ${s.pass}/${s.total} pass, ${s.fail} fail, ${s.warn} warn, ${s.unverifiedHere} unverified-here`,
+  );
+  parts.push('');
+  for (const cap of audit.capabilities) {
+    const marker = statusMarker(cap.status);
+    parts.push(`  ${marker} ${cap.id.padEnd(28)} ${cap.label}`);
+    parts.push(`      ${cap.detail}`);
+  }
+  return parts.join('\n');
+}
+
+function statusMarker(status) {
+  switch (status) {
+    case 'pass':             return '[PASS]';
+    case 'warn':             return '[WARN]';
+    case 'fail':             return '[FAIL]';
+    case 'unverified-here':  return '[UNVERIFIED-HERE]';
+    default:                 return '[?]';
+  }
+}
+
+// Test seam: expose helpers.
+export const _internals = {
+  cacheFilePath,
+  readCache,
+  readStalenessMinutes,
+  readPaName,
+  formatHuman,
+  parseArgs,
+};

package/dist/engineering-pa-cli/src/agent/probes.mjs

@@ -0,0 +1,236 @@
+// probes.mjs — mechanical presence-probes for the agent baseline manifest.
+//
+// Every probe is pure Node stdlib, synchronous, and returns a shape:
+//   { outcome: 'pass' | 'fail' | 'unverified-here', detail: '<string>' }
+//
+// The caller (packages/cli/src/agent/cli.mjs) folds severity and
+// hostDependent flags on top of these mechanical outcomes to arrive at
+// the final rendered status.
+//
+// Cross-platform: no `which`, no shell scripts, no external tools.
+// Filesystem access via node:fs sync; JSON parsed inline. All errors are
+// converted to `unverified-here` with a diagnostic string — a probe must
+// never throw and never crash the audit.
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { expandTemplate } from '../../../engineering-pa-core/src/agent-baseline/manifest.mjs';
+
+const PASS = 'pass';
+const FAIL = 'fail';
+const UNVERIFIED = 'unverified-here';
+
+/**
+ * Dispatch a single probe against a repo root. Never throws.
+ */
+export function runProbe(probe, ctx) {
+  try {
+    switch (probe.type) {
+      case 'file-exists':          return probeFileExists(probe, ctx);
+      case 'directory-exists':     return probeDirectoryExists(probe, ctx);
+      case 'staging-recent-write': return probeStagingRecentWrite(probe, ctx);
+      case 'knowledge-doc-exists': return probeKnowledgeDocExists(probe, ctx);
+      case 'schedule-defined':     return probeScheduleDefined(probe, ctx);
+      case 'json-field-includes':  return probeJsonFieldIncludes(probe, ctx);
+      default:
+        return {
+          outcome: UNVERIFIED,
+          detail: `unknown probe type: ${probe.type}`,
+        };
+    }
+  } catch (err) {
+    // Probes must never abort the audit — degrade to unverified-here with
+    // the diagnostic. A missing repoRoot / permission denied should look
+    // like a diagnostic on the line, not a stack trace.
+    return { outcome: UNVERIFIED, detail: `probe threw: ${err?.message || String(err)}` };
+  }
+}
+
+function probeFileExists(probe, ctx) {
+  const rel = expandTemplate(probe.path, ctx);
+  const abs = join(ctx.repoRoot, rel);
+  if (!existsSync(abs)) {
+    return { outcome: FAIL, detail: `missing: ${rel}` };
+  }
+  // Symmetrical with probeDirectoryExists: exists-but-wrong-shape is a
+  // hard fail, not a pass. A dir sitting where a file should be defeats
+  // the whole intent — `readFileSync` would throw on it.
+  try {
+    if (!statSync(abs).isFile()) {
+      return { outcome: FAIL, detail: `path exists but is not a file: ${rel}` };
+    }
+  } catch (err) {
+    return { outcome: UNVERIFIED, detail: `stat failed for ${rel}: ${err.message}` };
+  }
+  return { outcome: PASS, detail: `present at ${rel}` };
+}
+
+function probeDirectoryExists(probe, ctx) {
+  const rel = expandTemplate(probe.path, ctx);
+  const abs = join(ctx.repoRoot, rel);
+  if (!existsSync(abs)) {
+    return { outcome: FAIL, detail: `directory missing: ${rel}` };
+  }
+  try {
+    if (!statSync(abs).isDirectory()) {
+      return { outcome: FAIL, detail: `path exists but is not a directory: ${rel}` };
+    }
+  } catch (err) {
+    return { outcome: UNVERIFIED, detail: `stat failed for ${rel}: ${err.message}` };
+  }
+  return { outcome: PASS, detail: `directory present at ${rel}` };
+}
+
+function probeKnowledgeDocExists(probe, ctx) {
+  // Currently a thin alias for file-exists — kept as its own probe type so
+  // future extensions (link-in-graph, non-orphan) can enrich the check
+  // without a manifest schema break.
+  return probeFileExists(probe, ctx);
+}
+
+function probeStagingRecentWrite(probe, ctx) {
+  const rel = expandTemplate(probe.path, ctx);
+  const abs = join(ctx.repoRoot, rel);
+  if (!existsSync(abs)) {
+    return { outcome: FAIL, detail: `staging dir missing: ${rel}` };
+  }
+  let entries;
+  try {
+    entries = readdirSync(abs);
+  } catch (err) {
+    return { outcome: UNVERIFIED, detail: `readdir failed for ${rel}: ${err.message}` };
+  }
+  const maxAgeMs = probe.maxAgeDays * 24 * 60 * 60 * 1000;
+  const now = ctx.now ?? Date.now();
+  let latestMs = 0;
+  let latestName = null;
+  for (const name of entries) {
+    if (name.startsWith('.')) continue;
+    try {
+      const st = statSync(join(abs, name));
+      const mtime = st.mtimeMs;
+      if (mtime > latestMs) {
+        latestMs = mtime;
+        latestName = name;
+      }
+    } catch {
+      // ignore per-entry stat failures; keep scanning
+    }
+  }
+  if (latestMs === 0) {
+    return { outcome: FAIL, detail: `staging dir has no non-hidden entries: ${rel}` };
+  }
+  const ageDays = (now - latestMs) / (24 * 60 * 60 * 1000);
+  if (now - latestMs > maxAgeMs) {
+    return {
+      outcome: FAIL,
+      detail: `newest entry ${latestName} is ${ageDays.toFixed(1)}d old (max ${probe.maxAgeDays}d)`,
+    };
+  }
+  return {
+    outcome: PASS,
+    detail: `newest entry ${latestName} is ${ageDays.toFixed(1)}d old`,
+  };
+}
+
+function probeScheduleDefined(probe, ctx) {
+  const rel = expandTemplate(probe.path, ctx);
+  const dir = join(ctx.repoRoot, rel);
+  if (!existsSync(dir)) {
+    return { outcome: FAIL, detail: `schedules dir missing: ${rel}` };
+  }
+  let files;
+  try {
+    files = readdirSync(dir).filter((f) => f.endsWith('.json'));
+  } catch (err) {
+    return { outcome: UNVERIFIED, detail: `readdir failed for ${rel}: ${err.message}` };
+  }
+  const includesAll = (probe.commandIncludes ?? []).map(String);
+  const includesAny = (probe.commandIncludesAny ?? []).map(String);
+  const matches = [];
+  for (const name of files) {
+    let sched;
+    try {
+      sched = JSON.parse(readFileSync(join(dir, name), 'utf8'));
+    } catch {
+      continue;
+    }
+    if (sched?.enabled === false) continue;
+    const cmd = typeof sched?.command === 'string' ? sched.command : '';
+    if (!cmd) continue;
+    const allOk = includesAll.every((s) => cmd.includes(s));
+    const anyOk = includesAny.length === 0 || includesAny.some((s) => cmd.includes(s));
+    if (allOk && anyOk) matches.push({ file: name, host: sched.host ?? null });
+  }
+  if (matches.length === 0) {
+    return {
+      outcome: FAIL,
+      detail: `no enabled schedule matches include=${JSON.stringify(includesAll)} any=${JSON.stringify(includesAny)}`,
+    };
+  }
+  // If the matching schedule is host-pinned to a different host from the
+  // audited host, the estate declares it — just not verifiable HERE. The
+  // caller sees this via the outcome + host context on the audit line.
+  const currentHost = ctx.hostname ?? null;
+  const hostMatched = matches.some((m) => !m.host || matchesHost(m.host, currentHost));
+  if (!hostMatched) {
+    const declared = matches.map((m) => m.host).filter(Boolean).join(', ');
+    return {
+      outcome: UNVERIFIED,
+      detail: `declared on host(s) ${declared} — not this host (${currentHost ?? 'unknown'})`,
+    };
+  }
+  return {
+    outcome: PASS,
+    detail: `${matches.length} matching schedule(s): ${matches.map((m) => m.file).join(', ')}`,
+  };
+}
+
+/**
+ * Match a schedule.host string against the current hostname. Mirrors the
+ * scheduler's convention: exact match, or short-name-before-first-dot.
+ */
+function matchesHost(scheduleHost, currentHost) {
+  if (!currentHost) return false;
+  if (scheduleHost === currentHost) return true;
+  const shortSched = scheduleHost.split('.')[0];
+  const shortCurrent = currentHost.split('.')[0];
+  return shortSched === shortCurrent;
+}
+
+function probeJsonFieldIncludes(probe, ctx) {
+  // Optional gating on a required tool — if the tool's directory is
+  // absent, the whole capability doesn't apply on this estate, and we
+  // report unverified-here rather than fail.
+  if (probe.requiredTool) {
+    const toolDir = join(ctx.repoRoot, 'operator', 'extensions', 'tools', probe.requiredTool);
+    if (!existsSync(toolDir)) {
+      return { outcome: UNVERIFIED, detail: `required tool not installed on this estate: ${probe.requiredTool}` };
+    }
+  }
+  const rel = expandTemplate(probe.path, ctx);
+  const abs = join(ctx.repoRoot, rel);
+  if (!existsSync(abs)) {
+    return { outcome: FAIL, detail: `config file missing: ${rel}` };
+  }
+  let doc;
+  try {
+    doc = JSON.parse(readFileSync(abs, 'utf8'));
+  } catch (err) {
+    return { outcome: UNVERIFIED, detail: `${rel} not valid JSON: ${err.message}` };
+  }
+  const field = probe.field;
+  const value = expandTemplate(probe.expectedValue, ctx);
+  const target = doc?.[field];
+  if (!Array.isArray(target)) {
+    return { outcome: FAIL, detail: `${rel}: field '${field}' is not an array` };
+  }
+  if (!target.includes(value)) {
+    return {
+      outcome: FAIL,
+      detail: `${rel}: field '${field}' does not include ${JSON.stringify(value)}; got ${JSON.stringify(target)}`,
+    };
+  }
+  return { outcome: PASS, detail: `${rel}: '${field}' includes ${JSON.stringify(value)}` };
+}

package/dist/engineering-pa-cli/src/autonomy/cli.mjs

@@ -21,7 +21,7 @@ import {
   validateFrontmatter,
   nowIso,
   emptyEnvelope,
-} from './envelope.mjs';
+} from '../../../engineering-pa-core/src/autonomy/envelope.mjs';
 
 const USAGE = `pa autonomy — per-agent per-task-type approval state