@ikon85/agent-workflow-kit 0.32.1 → 0.34.0

package/src/cli.mjs

@@ -8,6 +8,7 @@ import { diff } from './commands/diff.mjs';
 import { uninstall } from './commands/uninstall.mjs';
 import { setOwnership } from './commands/own.mjs';
 import { CONSUMER_ORIGIN, KIT_ORIGIN } from './lib/manifest.mjs';
+import { currentAgentSurface } from './lib/agentSurfaceRegistry.mjs';
 import { createCommandAdapter } from '../scripts/release-state.mjs';
 import { installedIdentityFromDir } from '../scripts/release-parity.mjs';
 
@@ -29,12 +30,18 @@ p.intro('agent-workflow-kit');
 
 try {
   if (cmd === 'init') {
-    const r = await init({ kitRoot: KIT_ROOT, consumerRoot, force });
+    const r = await init({
+      kitRoot: KIT_ROOT,
+      consumerRoot,
+      force,
+      routingProfile: routingProfileOptions(),
+    });
     p.note(
       `copied ${r.copied.length} · seeded ${r.seeded.length} stub(s)` +
         (r.skipped.length ? `\nskipped (pre-existing, use --force): ${r.skipped.join(', ')}` : ''),
       'init'
     );
+    printRoutingProfile(r.routingProfile);
     p.outro('Next: run /setup-workflow to fill the project layer + board profile. ' +
       'To enable the drift-guard hook, add .claude/hooks/drift-guard.py to your settings.json hooks.');
   } else if (cmd === 'diff') {
@@ -45,9 +52,15 @@ try {
     const decide = (action, path) => decideUpdate(action, path, yes);
     const releaseIdentities = await readUpdateRelease();
     const r = await update({
-      kitRoot: KIT_ROOT, consumerRoot, now: stamp(), decide, releaseIdentities,
+      kitRoot: KIT_ROOT,
+      consumerRoot,
+      now: stamp(),
+      decide,
+      releaseIdentities,
+      routingProfile: routingProfileOptions(),
     });
     printPlan(r);
+    printRoutingProfile(r.routingProfile);
     for (const c of r.conflicts) p.note(c.diff || '(binary/!text)', `conflict (not applied): ${c.path}`);
     if (r.state === 'failed') throw new Error(renderUpdateFailure(r));
     if (r.state === 'conflicted') {
@@ -126,6 +139,100 @@ async function decideUpdate(action, path, yes) {
   throw new Error(`unknown update decision action: ${action}`);
 }
 
+function routingProfileOptions() {
+  return {
+    currentSurface: currentAgentSurface(),
+    prompt: yes ? undefined : promptRoutingProfile,
+  };
+}
+
+function printRoutingProfile(result) {
+  if (!result) return;
+  const suffix = result.reasons?.length ? ` · ${result.reasons.join(', ')}` : '';
+  p.note(`${result.status}${suffix}`, 'routing profile');
+}
+
+async function promptRoutingProfile(question) {
+  if (question.kind === 'surfaces') {
+    return ensurePrompt(await p.multiselect({
+      message: question.message,
+      options: question.options.map(({ id, label }) => ({ value: id, label })),
+      initialValues: question.preselected,
+      required: true,
+    }), 'surface selection');
+  }
+  if (question.kind === 'autonomy') {
+    return ensurePrompt(await p.select({
+      message: question.message,
+      options: question.options,
+    }), 'switching choice');
+  }
+  if (question.kind === 'activation') {
+    const draft = question.advancedDraft ? ' · advanced draft ready' : '';
+    return ensurePrompt(await p.select({
+      message: `${question.message}${draft}`,
+      options: [
+        { value: 'approve', label: 'Approve' },
+        { value: 'safe-current-surface', label: 'Safe current surface' },
+        { value: 'back', label: 'Back' },
+        { value: 'advanced', label: 'Advanced' },
+        { value: 'decline', label: 'Decline' },
+      ],
+    }), 'activation choice');
+  }
+  if (question.kind === 'advanced') {
+    const optimization = ensurePrompt(await p.select({
+      message: question.message,
+      options: [
+        { value: 'balanced', label: 'Balanced' },
+        { value: 'quality', label: 'Quality' },
+        { value: 'cost', label: 'Cost' },
+      ],
+      initialValue: question.draft?.optimization ?? 'balanced',
+    }), 'advanced choice');
+    return { ...question.draft, optimization };
+  }
+  if (question.kind === 'reconcile') {
+    if (question.delta.type === 'missing-profile' || question.delta.type === 'invalid-profile') {
+      return ensurePrompt(await p.select({
+        message: question.message,
+        options: [
+          { value: 'review', label: 'Review routing choices now' },
+          { value: 'decline', label: 'Not now' },
+        ],
+      }), 'routing migration choice');
+    }
+    const additions = question.delta.newSurfaces;
+    if (additions.length) {
+      const removed = question.delta.removedSurfaces.map(({ label }) => label);
+      const change = [
+        `new: ${additions.map(({ label }) => label).join(', ')}`,
+        ...(removed.length ? [`unavailable: ${removed.join(', ')}`] : []),
+      ].join(' · ');
+      const addSurfaceIds = ensurePrompt(await p.multiselect({
+        message: `Routing choices changed — ${change}`,
+        options: additions.map(({ id, label }) => ({ value: id, label })),
+        initialValues: [],
+        required: false,
+      }), 'routing reconcile choice');
+      return { action: 'apply', addSurfaceIds };
+    }
+    const removed = question.delta.removedSurfaces.map(({ label }) => label).join(', ');
+    const message = removed
+      ? `Remove unavailable agent app from routing: ${removed}?`
+      : 'Refresh the routing profile registry revision?';
+    return ensurePrompt(await p.confirm({ message }), 'routing reconcile choice')
+      ? { action: 'apply', addSurfaceIds: [] }
+      : { action: 'decline' };
+  }
+  throw new Error(`unknown routing profile question: ${question.kind}`);
+}
+
+function ensurePrompt(value, label) {
+  if (p.isCancel(value)) throw new Error(`${label} cancelled`);
+  return value;
+}
+
 async function readUpdateRelease() {
   const adapter = await createCommandAdapter({
     repoRoot: KIT_ROOT,

package/src/commands/init.mjs

@@ -12,6 +12,9 @@ import {
   CONSUMER_ORIGIN,
   PACKAGE_MANIFEST_NAME, CONSUMER_MANIFEST_NAME,
 } from '../lib/manifest.mjs';
+import {
+  inspectRoutingProfile, reconcileRoutingProfile, setupRoutingProfile,
+} from '../lib/routingProfile.mjs';
 
 const exists = (p) => access(p).then(() => true, () => false);
 
@@ -24,7 +27,7 @@ const exists = (p) => access(p).then(() => true, () => false);
  *    already exist — idempotent),
  *  - never touches board-sync.md / CLAUDE.md / AGENTS.md.
  */
-export async function init({ kitRoot, consumerRoot, force = false }) {
+export async function init({ kitRoot, consumerRoot, force = false, routingProfile }) {
   const pkg = await readManifest(join(kitRoot, PACKAGE_MANIFEST_NAME));
   if (!pkg) throw new Error('kit package manifest not found');
   const prior = await readManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME));
@@ -80,5 +83,18 @@ export async function init({ kitRoot, consumerRoot, force = false }) {
     result.seeded.push(stub);
   }
 
+  if (routingProfile) {
+    const options = { consumerRoot, ...routingProfile };
+    const inspection = await inspectRoutingProfile(options);
+    result.routingProfile = prior
+      ? await reconcileRoutingProfile(options, inspection)
+      : (inspection.status === 'still valid'
+        ? { status: 'still valid' }
+        : await setupRoutingProfile({
+          ...options,
+          expectedFingerprint: inspection.fingerprint,
+        }));
+  }
+
   return result;
 }

package/src/commands/routing-policy-update.mjs

@@ -0,0 +1,204 @@
+import {
+  buildEvidenceCatalogFromSources,
+  commitRoutingEvidenceCache,
+  routingEvidenceSourcesFromCache,
+  validateRoutingEvidenceSourceSnapshot,
+} from '../lib/routingEvidenceCache.mjs';
+
+function message(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function observationDiff(previous, next) {
+  const before = new Map(previous.map((entry) => [entry.id, entry]));
+  const after = new Map(next.map((entry) => [entry.id, entry]));
+  const added = [...after.keys()].filter((id) => !before.has(id)).sort();
+  const removed = [...before.keys()].filter((id) => !after.has(id)).sort();
+  const changed = [...after.keys()].filter(
+    (id) => before.has(id)
+      && JSON.stringify(before.get(id)) !== JSON.stringify(after.get(id)),
+  ).sort();
+  return { added, changed, removed };
+}
+
+function validateSource(source, index) {
+  if (!source || typeof source !== 'object') {
+    throw new TypeError(`sources[${index}] must be an object`);
+  }
+  const { adapter, load } = source;
+  if (!adapter || typeof adapter !== 'object') {
+    throw new TypeError(`sources[${index}].adapter must be an object`);
+  }
+  for (const field of ['sourceId', 'owner', 'artifactUrl']) {
+    if (typeof adapter[field] !== 'string' || adapter[field].trim() === '') {
+      throw new TypeError(`sources[${index}].adapter.${field} must be a non-empty string`);
+    }
+  }
+  if (typeof adapter.ingest !== 'function') {
+    throw new TypeError(`sources[${index}].adapter.ingest must be a function`);
+  }
+  if (typeof load !== 'function') {
+    throw new TypeError(`sources[${index}].load must be a function`);
+  }
+}
+
+function modelsFor(observations, catalog) {
+  const identities = new Set(
+    observations.map(({ providerId, modelId }) => `${providerId}:${modelId}`),
+  );
+  return catalog.models.filter(
+    ({ providerId, modelId }) => identities.has(`${providerId}:${modelId}`),
+  );
+}
+
+function legacySourceSnapshots(cache) {
+  const groups = new Map();
+  for (const observation of cache.catalog.observations) {
+    const { source, freshness } = observation;
+    if (!source?.id || !source?.snapshotHash) continue;
+    const existing = groups.get(source.id);
+    if (existing && existing.snapshotHash !== source.snapshotHash) {
+      throw new TypeError(
+        `legacy source ${source.id} contains several snapshot hashes`,
+      );
+    }
+    const observations = existing?.observations ?? [];
+    observations.push(observation);
+    groups.set(source.id, {
+      sourceId: source.id,
+      owner: source.owner,
+      artifactUrl: source.url,
+      snapshotHash: source.snapshotHash,
+      observedAt: freshness.observedAt,
+      expiresAt: freshness.expiresAt,
+      models: [],
+      observations,
+      signals: [],
+    });
+  }
+  return [...groups.values()].map((source, index) =>
+    validateRoutingEvidenceSourceSnapshot({
+      ...source,
+      models: modelsFor(source.observations, cache.catalog),
+    }, index));
+}
+
+function cachedSources(cache) {
+  const explicit = routingEvidenceSourcesFromCache(cache);
+  return explicit.length > 0 ? explicit : legacySourceSnapshots(cache);
+}
+
+function cachedStatus(adapter, prior, reason) {
+  return {
+    sourceId: adapter.sourceId,
+    status: prior ? 'cached' : 'quarantined',
+    reason,
+    cachedAt: prior?.observedAt,
+  };
+}
+
+export async function refreshRoutingEvidence({
+  sources,
+  currentCache,
+  expectedRevision,
+  refreshedAt,
+  expiresAt,
+  onProgress = () => {},
+}) {
+  if (!Array.isArray(sources)) throw new TypeError('sources must be an array');
+  sources.forEach(validateSource);
+  const requestedIds = new Set();
+  for (const { adapter } of sources) {
+    if (requestedIds.has(adapter.sourceId)) {
+      throw new TypeError(`duplicate routing evidence source: ${adapter.sourceId}`);
+    }
+    requestedIds.add(adapter.sourceId);
+  }
+
+  const sourceState = new Map(
+    cachedSources(currentCache).map((source) => [source.sourceId, source]),
+  );
+  const statuses = [];
+  const quarantines = [];
+
+  for (const { adapter, load } of sources) {
+    const prior = sourceState.get(adapter.sourceId);
+    onProgress({ sourceId: adapter.sourceId, status: 'loading' });
+    let loaded;
+    try {
+      loaded = await load();
+    } catch (error) {
+      const reason = `load failed: ${message(error)}`;
+      const status = cachedStatus(adapter, prior, reason);
+      if (!prior) quarantines.push({ sourceId: adapter.sourceId, reason });
+      statuses.push(status);
+      onProgress(status);
+      continue;
+    }
+
+    try {
+      const ingested = adapter.ingest({
+        payload: loaded.payload,
+        snapshotHash: loaded.snapshotHash,
+        observedAt: refreshedAt,
+        expiresAt,
+      });
+      if (ingested.sourceId !== adapter.sourceId) {
+        throw new TypeError(
+          `source identity changed from ${adapter.sourceId} to ${ingested.sourceId}`,
+        );
+      }
+      const candidate = validateRoutingEvidenceSourceSnapshot({
+        sourceId: adapter.sourceId,
+        owner: adapter.owner,
+        artifactUrl: adapter.artifactUrl,
+        snapshotHash: loaded.snapshotHash,
+        observedAt: refreshedAt,
+        expiresAt,
+        models: ingested.models,
+        observations: ingested.observations,
+        signals: ingested.signals ?? [],
+      });
+      const prospective = new Map(sourceState);
+      prospective.set(adapter.sourceId, candidate);
+      buildEvidenceCatalogFromSources(
+        [...prospective.values()],
+        `catalog-r${expectedRevision + 1}`,
+      );
+      sourceState.set(adapter.sourceId, candidate);
+      const status = { sourceId: adapter.sourceId, status: 'live' };
+      statuses.push(status);
+      onProgress(status);
+    } catch (error) {
+      const reason = message(error);
+      const status = cachedStatus(adapter, prior, reason);
+      quarantines.push({ sourceId: adapter.sourceId, reason });
+      onProgress({ sourceId: adapter.sourceId, status: 'quarantined', reason });
+      statuses.push(status);
+      if (prior) onProgress(status);
+    }
+  }
+
+  const nextSources = [...sourceState.values()];
+  const nextCatalog = buildEvidenceCatalogFromSources(
+    nextSources,
+    `catalog-r${expectedRevision + 1}`,
+  );
+  const cache = commitRoutingEvidenceCache({
+    current: currentCache,
+    expectedRevision,
+    nextCatalog,
+    nextSources,
+    refreshedAt,
+    expiresAt,
+  });
+  return {
+    cache,
+    sources: statuses,
+    quarantines,
+    diff: observationDiff(
+      currentCache.catalog.observations,
+      nextCatalog.observations,
+    ),
+  };
+}

package/src/commands/update.mjs

@@ -8,6 +8,9 @@ import { reconcile } from '../lib/updateReconcile.mjs';
 import {
   CONSUMER_MANIFEST_NAME, PACKAGE_MANIFEST_NAME, readManifest,
 } from '../lib/manifest.mjs';
+import {
+  inspectRoutingProfile, reconcileRoutingProfile,
+} from '../lib/routingProfile.mjs';
 
 const RELEASE_NAME = '@ikon85/agent-workflow-kit';
 
@@ -22,6 +25,25 @@ export function renderUpdateFailure(result) {
  * checking -> preview/awaiting_decision -> staging -> verifying -> terminal state.
  */
 export async function update(options) {
+  const preflight = options.routingProfile
+    ? await inspectRoutingProfile({ consumerRoot: options.consumerRoot, ...options.routingProfile })
+    : null;
+  const result = await updatePackage(options);
+  if (!preflight || options.dryRun || result.state !== 'applied') return result;
+  const inspection = await inspectRoutingProfile({
+    consumerRoot: options.consumerRoot,
+    ...options.routingProfile,
+  });
+  return {
+    ...result,
+    routingProfile: await reconcileRoutingProfile(
+      { consumerRoot: options.consumerRoot, ...options.routingProfile },
+      inspection,
+    ),
+  };
+}
+
+async function updatePackage(options) {
   const {
     kitRoot, consumerRoot, decide = () => false, dryRun = false,
     releaseIdentities, verify = verifyCandidate, activate = activateCandidate,

package/src/lib/agentSurfaceRegistry.mjs

@@ -0,0 +1,60 @@
+import { access } from 'node:fs/promises';
+import { delimiter, join } from 'node:path';
+
+export const AGENT_SURFACE_REGISTRY_REVISION = 1;
+
+export const AGENT_SURFACE_REGISTRY = Object.freeze([
+  Object.freeze({
+    id: 'claude-code',
+    label: 'Claude Code',
+    command: 'claude',
+    activeEnvironment: Object.freeze(['CLAUDE_CODE_ENTRYPOINT']),
+    adapter: Object.freeze({
+      providers: Object.freeze(['anthropic']),
+      transports: Object.freeze(['native', 'codex-cli']),
+      enforcement: Object.freeze({ model: 'named-agent', effort: 'named-agent' }),
+    }),
+  }),
+  Object.freeze({
+    id: 'codex',
+    label: 'Codex',
+    command: 'codex',
+    activeEnvironment: Object.freeze(['CODEX_THREAD_ID']),
+    adapter: Object.freeze({
+      providers: Object.freeze(['openai']),
+      transports: Object.freeze(['native', 'claude-cli']),
+      enforcement: Object.freeze({ model: 'per-spawn', effort: 'per-spawn' }),
+    }),
+  }),
+]);
+
+async function commandOnPath(command, env = process.env) {
+  for (const directory of (env.PATH ?? '').split(delimiter).filter(Boolean)) {
+    if (await access(join(directory, command)).then(() => true, () => false)) return true;
+  }
+  return false;
+}
+
+export async function detectAgentSurfaces({
+  registry = AGENT_SURFACE_REGISTRY,
+  commandAvailable = commandOnPath,
+} = {}) {
+  return Promise.all(registry.map(async (surface) => Object.freeze({
+    id: surface.id,
+    label: surface.label,
+    detected: await commandAvailable(surface.command),
+    adapter: surface.adapter,
+  })));
+}
+
+export function surfaceById(id, registry = AGENT_SURFACE_REGISTRY) {
+  return registry.find((surface) => surface.id === id);
+}
+
+export function currentAgentSurface({
+  registry = AGENT_SURFACE_REGISTRY,
+  env = process.env,
+} = {}) {
+  return registry.find((surface) =>
+    surface.activeEnvironment.some((name) => typeof env[name] === 'string' && env[name] !== ''))?.id;
+}

package/src/lib/bundle.mjs

@@ -72,6 +72,40 @@ export const HELPER_FILES = [
   { path: 'src/lib/release-preview.mjs', kind: 'script', mode: 0o644 },
   { path: 'src/lib/release-apply.mjs', kind: 'script', mode: 0o644 },
   { path: 'scripts/project-release.mjs', kind: 'script', mode: 0o755 },
+  // Canonical schema and semantic validator shared across orchestration paths.
+  // Library → 0o644; later helper-owning slices append their paths once present.
+  { path: 'src/lib/reportValidator.mjs', kind: 'script', mode: 0o644 },
+  // Fail-closed orchestration selector and its host-inventory adapters.
+  { path: 'src/lib/capabilityMatrix.mjs', kind: 'script', mode: 0o644 },
+  // Provider-neutral routing runtime: one Evidence catalog, Access graph,
+  // Routing policy, resolver, spawn guard, receipt v2, and surface attestations.
+  // These modules form one consumer unit; omitting one leaves shipped dispatch
+  // prose pointing at a resolver or adapter that cannot execute.
+  { path: 'src/commands/routing-policy-update.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/agentSurfaceRegistry.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/dispatchReceipt.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/frontendWorkloads.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/routeDispatcher.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/routingAccessGraph.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/routingAdapters/claude.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/routingAdapters/codex.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/routingCatalog.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/routingEvidenceCache.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/routingIntent.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/routingPolicy.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/routingProfile.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/routingResolver.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/routingSources/artificialAnalysis.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/routingSources/benchlm.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/routingSources/codeArena.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/routingSources/deepswe.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/routingSources/openhands.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/routingSources/openhandsFrontend.mjs', kind: 'script', mode: 0o644 },
+  // Main-thread recon boundary shared by every orchestration path.
+  { path: 'src/lib/reconcileReconReports.mjs', kind: 'script', mode: 0o644 },
+  // Atomic compare-and-set wave claim: two sessions cannot orchestrate the same
+  // wave. Library (imported by the Phase-0 claim protocol) → 0o644.
+  { path: 'src/lib/waveClaim.mjs', kind: 'script', mode: 0o644 },
   // GitHub-consumer automation: invokes the existing update command, then owns
   // only the stable tested branch/pull-request upsert.
   { path: 'scripts/kit-update-pr.mjs', kind: 'script', mode: 0o755 },