@ngockhoale/ukit 3.3.2 → 3.4.0

package/src/core/agentRuntime/adapters.js

@@ -46,9 +46,13 @@ import { spawn } from 'node:child_process';
 
 import {
   validateSemanticEvent,
+  validateTaskContract,
+  validateResultEnvelope,
   CONTRACT_VERSION,
   MAX_SAFE_PAYLOAD_BYTES,
 } from './contract.js';
+import { resolveConfigStage } from '../runtimeConfig.js';
+import { resolveRunArtifact } from './eventStore.js';
 import {
   makeSpanContext,
   emitSpanRecord,
@@ -421,9 +425,10 @@ export function detectHost(env = process.env) {
 }
 
 /**
- * Evaluate one host lane against the current environment.
+ * Evaluate the owned-runner primitives for one lane. Shared by the host
+ * lanes (probeHostAdapter) and the owned-vm lane
+ * (probeSubagentCapabilities) so both speak the same status ladder.
  *
- * @param {string} name lane name (HOST_NAMES member or arbitrary string)
  * @param {object} [opts]
  * @param {boolean} [opts.liveHostE2E] declare live host E2E evidence —
  *   the ONLY path to 'supported'. Never derived from primitive presence.
@@ -431,20 +436,9 @@ export function detectHost(env = process.env) {
  * @param {Function} [opts.killImpl] required primitive (default process.kill)
  * @param {Function} [opts.probeImpl] required liveness primitive (default sig-0)
  * @param {string} [opts.platform] default process.platform
- * @returns {{name:string|null, supported:string, reason:string|null,
- *   completionApi:string|null, primitives:object}}
+ * @returns {{supported:string, reason:string|null, primitives:object}}
  */
-export function probeHostAdapter(name, opts = {}) {
-  const descriptor = HOST_ADAPTERS[name];
-  if (!descriptor) {
-    return {
-      name: null,
-      supported: HOST_UNSUPPORTED,
-      reason: 'unknown_host',
-      completionApi: null,
-      primitives: {},
-    };
-  }
+function probeRunnerPrimitives(opts = {}) {
   const platform = typeof opts.platform === 'string' ? opts.platform : process.platform;
   // `undefined` picks the Node defaults; any other non-function value is a
   // caller-supplied (possibly deliberately absent) primitive — probes must
@@ -467,37 +461,54 @@ export function probeHostAdapter(name, opts = {}) {
   };
   if (platform === 'win32') {
     return {
-      name,
       supported: HOST_UNSUPPORTED,
       reason: 'process_group_kill_unavailable',
-      completionApi: descriptor.completionApi,
       primitives,
     };
   }
   if (!primitives.spawn || !primitives.livenessProbe || !primitives.processGroupKill) {
     return {
-      name,
       supported: HOST_UNSUPPORTED,
       reason: 'host_spawn_unavailable',
-      completionApi: descriptor.completionApi,
       primitives,
     };
   }
   if (opts.liveHostE2E === true) {
+    return { supported: HOST_SUPPORTED, reason: null, primitives };
+  }
+  return {
+    supported: HOST_UNSUPPORTED_PROBE,
+    reason: 'live_host_e2e_unproven',
+    primitives,
+  };
+}
+
+/**
+ * Evaluate one host lane against the current environment.
+ *
+ * @param {string} name lane name (HOST_NAMES member or arbitrary string)
+ * @param {object} [opts] same options as probeRunnerPrimitives
+ * @returns {{name:string|null, supported:string, reason:string|null,
+ *   completionApi:string|null, primitives:object}}
+ */
+export function probeHostAdapter(name, opts = {}) {
+  const descriptor = HOST_ADAPTERS[name];
+  if (!descriptor) {
     return {
-      name,
-      supported: HOST_SUPPORTED,
-      reason: null,
-      completionApi: descriptor.completionApi,
-      primitives,
+      name: null,
+      supported: HOST_UNSUPPORTED,
+      reason: 'unknown_host',
+      completionApi: null,
+      primitives: {},
     };
   }
+  const probe = probeRunnerPrimitives(opts);
   return {
     name,
-    supported: HOST_UNSUPPORTED_PROBE,
-    reason: 'live_host_e2e_unproven',
+    supported: probe.supported,
+    reason: probe.reason,
     completionApi: descriptor.completionApi,
-    primitives,
+    primitives: probe.primitives,
   };
 }
 
@@ -510,3 +521,293 @@ export function listHostAdapters(opts = {}) {
   for (const name of HOST_NAMES) out[name] = probeHostAdapter(name, opts);
   return out;
 }
+
+// --- C89-004: subagent-orchestration capability probe (SPEC §8 FR-06, §12) --
+// Truth table the orchestrator reads before promising lazy disclosure, tool
+// filtering, model binding, or a real fork. Statuses:
+//   'supported'   — UKit owns the mechanism (owned-runner completion
+//                   journal) OR the caller declared live evidence
+//                   (opts.liveHostE2E + a per-capability evidenceRef).
+//   'advisory'    — a surface exists but UKit cannot bound how the host
+//                   consumes it (catalog mirrors, modelRoles hints,
+//                   frontmatter tool lists, artifactDir scoping).
+//   'unsupported' — the capability does not exist on this lane: no host
+//                   API. Evidence can never promote these cells.
+//   'unverified'  — reachable in principle but unproven here (fixture-only
+//                   or no declared live evidence). The only promotable class.
+// Published mirror: manifests/hostCapabilities.yaml `subagentOrchestration`
+// + docs/HOST_CAPABILITY_MATRIX.md § Subagent orchestration (SPEC §12).
+
+export const SUBAGENT_CAPABILITIES = Object.freeze([
+  'spawn',
+  'toolFiltering',
+  'skillCatalog',
+  'agentCatalog',
+  'writeScope',
+  'modelBind',
+  'fork',
+  'usageCache',
+  'completionSignal',
+]);
+
+export const SUBAGENT_CAPABILITY_LANES = Object.freeze([
+  ...HOST_NAMES,
+  'owned-vm',
+]);
+
+// Status words for capability cells — distinct namespace from the lane
+// ladder (supported/unsupported-probe/unsupported) on purpose.
+const CAP_SUPPORTED = 'supported';
+const CAP_ADVISORY = 'advisory';
+const CAP_UNSUPPORTED = 'unsupported';
+const CAP_UNVERIFIED = 'unverified';
+
+// Owned completion journal is UKit machinery, identical on every lane and
+// exercised by real-subprocess tests — supported by construction, with an
+// evidenceRef so the cell is never an empty claim.
+const OWNED_COMPLETION_EVIDENCE = 'tests/core/agentRuntime/hostAdapters.test.js';
+
+// Per-lane static baselines. Only 'unverified' cells promote to
+// 'supported' via caller evidence; 'advisory' is a fixed bound (a surface
+// UKit cannot bound is advisory no matter how often it is exercised) and
+// 'unsupported' names a missing API evidence cannot fabricate.
+const SUBAGENT_CAPABILITY_BASELINES = Object.freeze({
+  'omp': Object.freeze({
+    toolFiltering: { status: CAP_ADVISORY, reason: 'advisory_only' },
+    skillCatalog: { status: CAP_ADVISORY, reason: 'advisory_only' },
+    agentCatalog: { status: CAP_ADVISORY, reason: 'advisory_only' },
+    writeScope: { status: CAP_ADVISORY, reason: 'advisory_only' },
+    modelBind: { status: CAP_ADVISORY, reason: 'advisory_only' },
+    fork: { status: CAP_UNSUPPORTED, reason: 'no_host_state_inheritance_api' },
+    usageCache: { status: CAP_ADVISORY, reason: 'advisory_only' },
+  }),
+  'claude-code': Object.freeze({
+    toolFiltering: { status: CAP_ADVISORY, reason: 'advisory_only' },
+    skillCatalog: { status: CAP_ADVISORY, reason: 'advisory_only' },
+    agentCatalog: { status: CAP_ADVISORY, reason: 'advisory_only' },
+    writeScope: { status: CAP_ADVISORY, reason: 'advisory_only' },
+    modelBind: { status: CAP_ADVISORY, reason: 'advisory_only' },
+    fork: { status: CAP_UNSUPPORTED, reason: 'no_host_state_inheritance_api' },
+    usageCache: { status: CAP_ADVISORY, reason: 'advisory_only' },
+  }),
+  'codex': Object.freeze({
+    toolFiltering: { status: CAP_UNSUPPORTED, reason: 'no_host_tool_filtering_api' },
+    skillCatalog: { status: CAP_ADVISORY, reason: 'advisory_only' },
+    agentCatalog: { status: CAP_ADVISORY, reason: 'advisory_only' },
+    writeScope: { status: CAP_UNSUPPORTED, reason: 'no_host_write_scope_api' },
+    modelBind: { status: CAP_UNSUPPORTED, reason: 'no_host_model_binding_api' },
+    fork: { status: CAP_UNSUPPORTED, reason: 'no_host_state_inheritance_api' },
+    usageCache: { status: CAP_UNSUPPORTED, reason: 'no_provider_usage_api' },
+  }),
+  'owned-vm': Object.freeze({
+    toolFiltering: { status: CAP_UNSUPPORTED, reason: 'no_child_tool_surface' },
+    skillCatalog: { status: CAP_UNSUPPORTED, reason: 'no_child_catalog_surface' },
+    agentCatalog: { status: CAP_UNSUPPORTED, reason: 'no_child_catalog_surface' },
+    writeScope: { status: CAP_ADVISORY, reason: 'advisory_only' },
+    modelBind: { status: CAP_UNSUPPORTED, reason: 'no_child_model_binding' },
+    fork: { status: CAP_UNSUPPORTED, reason: 'no_host_state_inheritance_api' },
+    usageCache: { status: CAP_UNSUPPORTED, reason: 'no_provider_usage_api' },
+  }),
+});
+
+function capCell(status, reason, evidenceRef) {
+  const cell = { status, reason: reason ?? null };
+  if (typeof evidenceRef === 'string' && evidenceRef !== '') {
+    cell.evidenceRef = evidenceRef;
+  }
+  return cell;
+}
+
+/**
+ * Probe one lane's subagent-orchestration control surface.
+ *
+ * Never fabricates control: a host API UKit does not have stays
+ * 'unsupported', advisory surfaces stay 'advisory', and 'supported' exists
+ * only where UKit owns the mechanism (completionSignal — the eventStore
+ * journal) or where the caller declared live evidence for a promotable
+ * (default-'unverified') cell.
+ *
+ * @param {string|null|undefined} [host] lane name; undefined → ambient
+ *   detectHost(opts.env) — ambiguous/absent markers resolve a null lane
+ *   and every cell reports unverified/unsupported, never a guessed lane.
+ * @param {object} [opts]
+ * @param {object} [opts.env] env map for ambient detection
+ * @param {boolean} [opts.liveHostE2E] declared live E2E evidence for the
+ *   owned-runner spawn surface (same bar as probeHostAdapter)
+ * @param {Object<string,string>} [opts.evidence] per-capability evidence
+ *   refs; a promotable cell reports 'supported' only with BOTH live
+ *   evidence context (liveHostE2E for spawn) and a non-empty ref.
+ * @param {Function} [opts.spawnImpl] owned-runner primitive override
+ * @param {Function} [opts.killImpl] owned-runner primitive override
+ * @param {Function} [opts.probeImpl] owned-runner primitive override
+ * @param {string} [opts.platform] default process.platform
+ * @returns {{host:string|null, capabilities:
+ *   Record<string,{status:string, reason:string|null, evidenceRef?:string}>}}
+ */
+export function probeSubagentCapabilities(host, opts = {}) {
+  const lane = host === undefined || host === null
+    ? detectHost(opts.env)
+    : host;
+  const resolved = SUBAGENT_CAPABILITY_LANES.includes(lane) ? lane : null;
+  const capabilities = {};
+
+  if (resolved === null) {
+    // Unknown explicit name or unresolved ambient markers → conservative
+    // fallback: runner-bound cells report the lane probe verdict, the rest
+    // stay unverified. Nothing is ever guessed or faked supported.
+    const probe = lane === undefined || lane === null
+      ? { supported: HOST_UNSUPPORTED, reason: 'host_unresolved' }
+      : probeHostAdapter(lane, opts);
+    const unresolved = lane === undefined || lane === null;
+    for (const cap of SUBAGENT_CAPABILITIES) {
+      if (cap === 'spawn') {
+        capabilities[cap] = capCell(
+          unresolved || probe.supported !== HOST_UNSUPPORTED
+            ? CAP_UNVERIFIED
+            : CAP_UNSUPPORTED,
+          unresolved ? 'host_unresolved' : (probe.reason ?? 'host_unresolved'),
+        );
+      } else {
+        // completionSignal and every host-exposed control: unknown or
+        // unresolved lane → unverified. The owned journal exists, but it
+        // is never promised for a lane we cannot name.
+        capabilities[cap] = capCell(
+          CAP_UNVERIFIED,
+          unresolved ? 'host_unresolved' : (probe.reason ?? 'unknown_host'),
+        );
+      }
+    }
+    return { host: resolved, capabilities };
+  }
+
+  const baselines = SUBAGENT_CAPABILITY_BASELINES[resolved];
+  const runner = probeRunnerPrimitives(opts);
+  const evidence = opts.evidence && typeof opts.evidence === 'object'
+    ? opts.evidence
+    : {};
+  const liveSpawn = opts.liveHostE2E === true
+    && typeof evidence.spawn === 'string'
+    && evidence.spawn !== '';
+
+  for (const cap of SUBAGENT_CAPABILITIES) {
+    if (cap === 'spawn') {
+      // Runner primitive status mirrors the lane probe; 'supported' only
+      // with declared live E2E AND a cell-level evidenceRef.
+      if (runner.supported === HOST_UNSUPPORTED) {
+        capabilities.spawn = capCell(CAP_UNSUPPORTED, runner.reason);
+      } else if (runner.supported === HOST_SUPPORTED && liveSpawn) {
+        capabilities.spawn = capCell(CAP_SUPPORTED, null, evidence.spawn);
+      } else {
+        capabilities.spawn = capCell(
+          CAP_UNVERIFIED,
+          runner.supported === HOST_SUPPORTED
+            ? 'evidence_ref_required'
+            : runner.reason,
+        );
+      }
+      continue;
+    }
+    if (cap === 'completionSignal') {
+      capabilities.completionSignal = runner.supported === HOST_UNSUPPORTED
+        ? capCell(CAP_UNSUPPORTED, runner.reason)
+        : capCell(CAP_SUPPORTED, null, OWNED_COMPLETION_EVIDENCE);
+      continue;
+    }
+    const base = baselines[cap];
+    const ref = typeof evidence[cap] === 'string' && evidence[cap] !== ''
+      ? evidence[cap]
+      : null;
+    if (base.status === CAP_UNVERIFIED && ref && runner.supported === HOST_SUPPORTED) {
+      capabilities[cap] = capCell(CAP_SUPPORTED, null, ref);
+    } else {
+      capabilities[cap] = capCell(base.status, base.reason);
+    }
+  }
+  return { host: resolved, capabilities };
+}
+
+// --- C89-003: ResultEnvelope ingestion on the owned runner (SPEC §5, §11) --
+// `subagentOrchestrator.referenceHandoff.stage` gates the whole lane: 'off'
+// (or absent/malformed config) is a typed no-op — no fs access, no schema
+// work, the legacy stdout/stderr surface is byte-identical. When enabled the
+// runner accepts a child's compact ResultEnvelope, verifies every evidence/
+// artifact ref through `resolveRunArtifact` inside the run root, and returns
+// the compact control result. An envelope that claims 'complete' while any
+// of its evidence is missing, corrupt, truncated, or out-of-scope downgrades
+// to 'partial' — false completeness is never served.
+
+const REFERENCE_HANDOFF_FLAG = 'subagentOrchestrator.referenceHandoff.stage';
+/** Cap on refs resolved per envelope — ingestion work stays bounded. */
+const MAX_ENVELOPE_REFS = 64;
+
+/**
+ * Ingest one child ResultEnvelope on the owned runner.
+ *
+ * @param {object} args
+ * @param {object} [args.config] runtime config (stage gate)
+ * @param {string} args.runRoot run directory the refs are scoped to
+ * @param {object} args.caller `{runId, role?}` — resolution authorization
+ * @param {object} [args.contract] TaskContract the child ran under; when
+ *   present it is validated before the envelope is even looked at
+ * @param {object} args.envelope ResultEnvelope v1
+ * @returns {Promise<{ok:false, code:string, errors?:string[]}
+ *          |{ok:true, status:string, summary:string, claims:object[],
+ *            resolvedRefs:object[], unresolvedRefs:object[],
+ *            provenance:object}>}
+ */
+export async function ingestResultEnvelope({
+  config = null,
+  runRoot,
+  caller,
+  contract,
+  envelope,
+} = {}) {
+  if (resolveConfigStage(config, REFERENCE_HANDOFF_FLAG) === 'off') {
+    return { ok: false, code: 'reference_handoff_off' };
+  }
+  if (contract !== undefined) {
+    const v = validateTaskContract(contract);
+    if (!v.valid) return { ok: false, code: 'invalid_contract', errors: v.errors };
+  }
+  const v = validateResultEnvelope(envelope);
+  if (!v.valid) return { ok: false, code: 'invalid_envelope', errors: v.errors };
+
+  // Review fix (C89 R1): claim-level evidenceRefs were schema-validated but
+  // never resolved — a 'complete' envelope with all claim evidence missing
+  // would still report complete. Resolve every declared ref through the same
+  // bounded loop; failures land in unresolvedRefs and downgrade status.
+  const claimRefs = (envelope.claims ?? []).flatMap((claim) => claim.evidenceRefs ?? []);
+  const refs = [...envelope.evidenceRefs, ...envelope.artifactRefs, ...claimRefs];
+  const resolvedRefs = [];
+  const unresolvedRefs = [...envelope.unresolved];
+  for (const ref of refs.slice(0, MAX_ENVELOPE_REFS)) {
+    const resolved = await resolveRunArtifact(ref, { runRoot, caller });
+    if (resolved.status === 'unavailable') {
+      unresolvedRefs.push({ ref, reason: resolved.reason });
+    } else {
+      resolvedRefs.push({ ref, verified: true, sha256: resolved.sha256 });
+      if (resolved.truncated === true) {
+        unresolvedRefs.push({ ref, reason: 'truncated' });
+      }
+    }
+  }
+  for (const ref of refs.slice(MAX_ENVELOPE_REFS)) {
+    unresolvedRefs.push({ ref, reason: 'ref_cap_exceeded' });
+  }
+
+  // Never upgrade a child's own status; 'complete' downgrades to 'partial'
+  // the moment any declared evidence fails to resolve verified.
+  const status = envelope.status === 'complete' && unresolvedRefs.length > 0
+    ? 'partial'
+    : envelope.status;
+
+  return {
+    ok: true,
+    status,
+    summary: envelope.summary,
+    claims: envelope.claims,
+    resolvedRefs,
+    unresolvedRefs,
+    provenance: envelope.provenance,
+  };
+}

package/src/core/agentRuntime/artifacts.js

@@ -190,3 +190,92 @@ export function createArtifactWriter(dir, limits = {}, deps = {}) {
 
   return { open };
 }
+
+// --- C89-003: single-artifact commit (SPEC §5) ------------------------------
+// `createArtifactWriter` streams child stdout/stderr; `writeRunArtifact`
+// commits ONE caller-supplied buffer (e.g. a full child report) as a
+// checksummed original inside the run directory — the file an envelope's
+// evidenceRefs point at. Commit is atomic (temp + fsync + rename) and every
+// failure leaves nothing behind.
+
+const ARTIFACT_NAME_RE = /^[A-Za-z0-9._-]{1,200}$/;
+
+// Real FileHandle exposes .sync(), not .fsync(); tolerate both.
+const defaultSyncImpl = async (handle) => {
+  if (handle && typeof handle.sync === 'function') return handle.sync();
+  if (handle && typeof handle.fsync === 'function') return handle.fsync();
+  return undefined;
+};
+
+/**
+ * Persist `bytes` as `<dir>/<name>` and return a checksummed ref:
+ * `{path, sha256, bytes, truncated:false, stream:null}`. `name` must be a
+ * plain basename — any path component or traversal rejects typed before a
+ * single byte touches disk.
+ *
+ * @param {string} dir run artifact directory
+ * @param {string} name basename-only file name
+ * @param {Buffer|Uint8Array|string} bytes content to persist
+ * @param {object} [opts] `{maxBytes, deps:{mkdirImpl,openImpl,writeImpl,fsyncImpl,closeImpl,renameImpl,unlinkImpl}}`
+ * @returns {Promise<object>} artifact ref (same shape family as stream refs)
+ */
+export async function writeRunArtifact(dir, name, bytes, opts = {}) {
+  if (
+    typeof dir !== 'string' || dir === ''
+    || typeof name !== 'string'
+    || !ARTIFACT_NAME_RE.test(name)
+    || name === '.' || name === '..'
+    || path.basename(name) !== name
+  ) {
+    throw new ArtifactError(
+      'invalid_artifact_name',
+      `artifact name must be a basename: ${String(name)}`,
+    );
+  }
+  const maxBytes = Number.isInteger(opts.maxBytes) && opts.maxBytes >= 0
+    ? opts.maxBytes
+    : DEFAULT_LIMITS.maxOutputBytes;
+  const buf = Buffer.isBuffer(bytes)
+    ? bytes
+    : Buffer.from(bytes === undefined || bytes === null ? '' : bytes);
+  if (buf.length > maxBytes) {
+    throw new ArtifactError(
+      'artifact_too_large',
+      `artifact ${name} is ${buf.length} bytes (cap ${maxBytes})`,
+    );
+  }
+  const d = {
+    mkdirImpl: opts.deps?.mkdirImpl ?? ((p) => fs.mkdir(p, { recursive: true })),
+    openImpl: opts.deps?.openImpl ?? ((p) => fs.open(p, 'w')),
+    writeImpl: opts.deps?.writeImpl ?? ((h, b) => h.write(b)),
+    fsyncImpl: opts.deps?.fsyncImpl ?? defaultSyncImpl,
+    closeImpl: opts.deps?.closeImpl ?? ((h) => h.close()),
+    renameImpl: opts.deps?.renameImpl ?? ((a, b) => fs.rename(a, b)),
+    unlinkImpl: opts.deps?.unlinkImpl ?? ((p) => fs.unlink(p)),
+  };
+
+  const finalPath = path.join(dir, name);
+  const tmpPath = path.join(dir, `.${name}.${crypto.randomUUID()}.tmp`);
+  let handle;
+  try {
+    await d.mkdirImpl(dir);
+    handle = await d.openImpl(tmpPath);
+    if (buf.length > 0) await d.writeImpl(handle, buf);
+    await d.fsyncImpl(handle);
+    await d.closeImpl(handle);
+    handle = undefined;
+    await d.renameImpl(tmpPath, finalPath);
+  } catch (err) {
+    if (handle) {
+      try { await d.closeImpl(handle); } catch { /* error already in flight */ }
+    }
+    try { await d.unlinkImpl(tmpPath); } catch { /* nothing landed */ }
+    throw toArtifactError(err);
+  }
+  return {
+    path: finalPath,
+    sha256: crypto.createHash('sha256').update(buf).digest('hex'),
+    bytes: buf.length,
+    truncated: false,
+  };
+}