@ikon85/agent-workflow-kit 0.32.1 → 0.34.0

package/src/lib/capabilityMatrix.mjs

@@ -0,0 +1,179 @@
+const UNKNOWN = 'unknown';
+
+const PATH_A_CAPABILITIES = [
+  'namedPhases',
+  'runIdentity',
+  'runtimeOutputValidation',
+  'journal',
+  'resume',
+];
+
+const PATH_B_TOOLS = [
+  ['spawn_agent', 'spawn'],
+  ['wait_agent', 'wait'],
+  ['list_agents', 'aggregate'],
+];
+
+const TARGETS = Object.freeze({
+  A: Object.freeze({ path: 'A', kind: 'reference', value: 'references/dispatch-workflow.md' }),
+  B: Object.freeze({ path: 'B', kind: 'reference', value: 'references/dispatch-subagents.md' }),
+  C: Object.freeze({ path: 'C', kind: 'inline', value: 'path-c' }),
+});
+
+function triState(value) {
+  return typeof value === 'boolean' ? value : UNKNOWN;
+}
+
+function capacity(value) {
+  return Number.isInteger(value) && value >= 0 ? value : UNKNOWN;
+}
+
+function normalizeTool(tool) {
+  if (!tool || typeof tool !== 'object' || Array.isArray(tool)) return null;
+  return {
+    name: typeof tool.name === 'string' ? tool.name : UNKNOWN,
+    schema: tool.schema && typeof tool.schema === 'object' && !Array.isArray(tool.schema)
+      ? tool.schema
+      : UNKNOWN,
+    callable: triState(tool.callable),
+    permitted: triState(tool.permitted),
+    capabilities: Array.isArray(tool.capabilities)
+      && tool.capabilities.every((item) => typeof item === 'string')
+      ? [...new Set(tool.capabilities)]
+      : UNKNOWN,
+  };
+}
+
+function adaptInventory(inventory) {
+  const source = inventory && typeof inventory === 'object' ? inventory : {};
+  const validContract = source.contractVersion === 1;
+  return {
+    contractVersion: 1,
+    tools: validContract && Array.isArray(source.tools)
+      ? source.tools.map(normalizeTool).filter(Boolean)
+      : [],
+    effectiveConcurrency: validContract ? capacity(source.effectiveConcurrency) : UNKNOWN,
+    threadCapacity: validContract ? capacity(source.threadCapacity) : UNKNOWN,
+  };
+}
+
+export const capabilityAdapter = Object.freeze({
+  claude: adaptInventory,
+  codex: adaptInventory,
+});
+
+const ROUTE_IDENTITY_FIELDS = [
+  'id',
+  'surfaceId',
+  'providerId',
+  'modelId',
+  'transportId',
+];
+
+const ROUTE_ENFORCEMENT_METHODS = [
+  'per-spawn',
+  'named-agent',
+  'session-default',
+  'none',
+];
+
+const ROUTE_PRECEDENCE = [
+  'explicit-argument',
+  'agent-definition-over-environment',
+  'environment-over-agent-definition',
+  'session-default',
+];
+
+function routingControl(control) {
+  const source = control && typeof control === 'object' && !Array.isArray(control)
+    ? control
+    : {};
+  return {
+    method: ROUTE_ENFORCEMENT_METHODS.includes(source.method) ? source.method : UNKNOWN,
+    enforced: triState(source.enforced),
+    precedence: ROUTE_PRECEDENCE.includes(source.precedence)
+      ? source.precedence
+      : UNKNOWN,
+    applied: typeof source.applied === 'string' && source.applied !== ''
+      ? source.applied
+      : UNKNOWN,
+  };
+}
+
+function routingPath(path) {
+  const source = path && typeof path === 'object' && !Array.isArray(path) ? path : {};
+  const normalized = Object.fromEntries(ROUTE_IDENTITY_FIELDS.map((field) => [
+    field,
+    typeof source[field] === 'string' && source[field] !== '' ? source[field] : UNKNOWN,
+  ]));
+  normalized.detected = triState(source.detected);
+  normalized.callable = triState(source.callable);
+  normalized.permitted = triState(source.permitted);
+  normalized.model = routingControl(source.model);
+  normalized.effort = routingControl(source.effort);
+  const failures = [];
+  if (ROUTE_IDENTITY_FIELDS.some((field) => normalized[field] === UNKNOWN)) {
+    failures.push('route identity is incomplete');
+  }
+  if (normalized.detected !== true) failures.push('transport is not detected');
+  if (normalized.callable !== true) failures.push('transport is not callable');
+  if (normalized.permitted !== true) failures.push('transport is not permitted');
+  for (const field of ['model', 'effort']) {
+    if (normalized[field].enforced !== true || normalized[field].method === 'none'
+        || normalized[field].method === UNKNOWN) {
+      failures.push(`${field} control is not enforced`);
+    }
+    if (normalized[field].precedence === UNKNOWN) {
+      failures.push(`${field} environment precedence is unverified`);
+    }
+    if (normalized[field].applied === UNKNOWN) {
+      failures.push(`${field} applied value is unverified`);
+    }
+  }
+  normalized.verified = failures.length === 0;
+  normalized.verificationFailures = failures;
+  return Object.freeze(normalized);
+}
+
+export function adaptClaudeRoutingInventory(inventory) {
+  const source = inventory && typeof inventory === 'object' && !Array.isArray(inventory)
+    ? inventory
+    : {};
+  return Object.freeze({
+    contractVersion: 1,
+    paths: source.contractVersion === 1 && Array.isArray(source.paths)
+      ? Object.freeze(source.paths.map(routingPath))
+      : Object.freeze([]),
+  });
+}
+
+function proves(tool, capability) {
+  return tool?.callable === true
+    && tool.permitted === true
+    && tool.schema !== UNKNOWN
+    && Array.isArray(tool.capabilities)
+    && tool.capabilities.includes(capability);
+}
+
+function supportsPathA(inventory) {
+  const workflow = inventory.tools.find(({ name }) => name === 'Workflow');
+  return PATH_A_CAPABILITIES.every((capability) => proves(workflow, capability));
+}
+
+function supportsPathB(inventory) {
+  if (inventory.effectiveConcurrency === UNKNOWN || inventory.effectiveConcurrency < 2) return false;
+  if (inventory.threadCapacity === UNKNOWN || inventory.threadCapacity < 2) return false;
+  return PATH_B_TOOLS.every(([name, capability]) =>
+    inventory.tools.some((tool) => tool.name === name && proves(tool, capability)));
+}
+
+export function classifyCapabilities(inventory) {
+  const normalized = adaptInventory(inventory);
+  if (supportsPathA(normalized)) return 'A';
+  if (supportsPathB(normalized)) return 'B';
+  return 'C';
+}
+
+export function selectOrchestrationReference(inventory) {
+  return TARGETS[classifyCapabilities(inventory)];
+}

package/src/lib/dispatchReceipt.mjs

@@ -0,0 +1,162 @@
+export const DISPATCH_RECEIPT_VERSION = 2;
+
+const ROUTE_FIELDS = [
+  'providerId',
+  'modelId',
+  'effort',
+  'surfaceId',
+  'transportId',
+];
+
+const ENFORCEMENT_METHODS = [
+  'per-spawn',
+  'named-agent',
+  'session-default',
+  'none',
+];
+
+export const DISPATCH_PRECEDENCE = Object.freeze([
+  'explicit-argument',
+  'agent-definition-over-environment',
+  'environment-over-agent-definition',
+  'session-default',
+  'uncontrolled',
+  'unreported',
+]);
+
+function object(value, field) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError(`${field} must be an object`);
+  }
+  return value;
+}
+
+function string(value, field) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new TypeError(`${field} must be a non-empty string`);
+  }
+  return value;
+}
+
+function timestamp(value, field) {
+  string(value, field);
+  if (!Number.isFinite(Date.parse(value))) throw new TypeError(`${field} must be an ISO timestamp`);
+  return value;
+}
+
+function route(input, field) {
+  object(input, field);
+  for (const key of Object.keys(input)) {
+    if (!ROUTE_FIELDS.includes(key)) throw new TypeError(`unknown ${field} field: ${key}`);
+  }
+  return Object.freeze(Object.fromEntries(
+    ROUTE_FIELDS.map((key) => [key, string(input[key], `${field}.${key}`)]),
+  ));
+}
+
+function enforcement(input) {
+  object(input, 'enforcement');
+  const result = {};
+  for (const field of ['model', 'effort']) {
+    if (!ENFORCEMENT_METHODS.includes(input[field])) {
+      throw new TypeError(`${field} enforcement must be one of: ${ENFORCEMENT_METHODS.join(', ')}`);
+    }
+    result[field] = input[field];
+  }
+  return Object.freeze(result);
+}
+
+function precedence(input) {
+  if (input == null) {
+    return Object.freeze({ model: 'unreported', effort: 'unreported' });
+  }
+  object(input, 'precedence');
+  const result = {};
+  for (const field of ['model', 'effort']) {
+    if (!DISPATCH_PRECEDENCE.includes(input[field])) {
+      throw new TypeError(
+        `${field} precedence must be one of: ${DISPATCH_PRECEDENCE.join(', ')}`,
+      );
+    }
+    result[field] = input[field];
+  }
+  return Object.freeze(result);
+}
+
+function revisions(input) {
+  object(input, 'revisions');
+  return Object.freeze({
+    catalog: string(input.catalog, 'revisions.catalog'),
+    accessGraph: string(input.accessGraph, 'revisions.accessGraph'),
+    policy: string(input.policy, 'revisions.policy'),
+  });
+}
+
+function blockedReceipt(input) {
+  const requestedRoute = input.requestedRoute == null
+    ? null
+    : route(input.requestedRoute, 'requestedRoute');
+  const appliedRoute = input.appliedRoute == null
+    ? null
+    : route(input.appliedRoute, 'appliedRoute');
+  if (appliedRoute !== null && requestedRoute === null) {
+    throw new TypeError('blocked applied route requires a requested route');
+  }
+  const appliedEnforcement = input.enforcement == null ? null : enforcement(input.enforcement);
+  const appliedPrecedence = input.precedence == null ? null : precedence(input.precedence);
+  if (appliedRoute !== null && (appliedEnforcement === null || appliedPrecedence === null)) {
+    throw new TypeError('blocked applied route requires enforcement and precedence');
+  }
+  return Object.freeze({
+    schemaVersion: DISPATCH_RECEIPT_VERSION,
+    executionId: string(input.executionId, 'executionId'),
+    status: 'blocked',
+    afk: input.afk === true,
+    requestedRoute,
+    appliedRoute,
+    enforcement: appliedEnforcement,
+    precedence: appliedPrecedence,
+    revisions: revisions(input.revisions),
+    dispatchedAt: timestamp(input.dispatchedAt, 'dispatchedAt'),
+    reason: string(input.reason, 'reason'),
+  });
+}
+
+export function createDispatchReceipt(input) {
+  object(input, 'dispatch receipt');
+  if (input.status === 'blocked') return blockedReceipt(input);
+  if (input.status !== 'dispatched') {
+    throw new TypeError('dispatch receipt status must be dispatched or blocked');
+  }
+  const requestedRoute = route(input.requestedRoute, 'requestedRoute');
+  const appliedRoute = route(input.appliedRoute, 'appliedRoute');
+  for (const field of ROUTE_FIELDS) {
+    if (requestedRoute[field] !== appliedRoute[field]) {
+      throw new Error(`applied route differs from requested route: ${field}`);
+    }
+  }
+  const appliedEnforcement = enforcement(input.enforcement);
+  const appliedPrecedence = precedence(input.precedence);
+  if (input.afk === true
+      && (appliedEnforcement.model === 'none' || appliedEnforcement.effort === 'none')) {
+    throw new Error('AFK dispatch requires enforced model and effort selection');
+  }
+  if (input.afk === true
+      && Object.values(appliedPrecedence).some((value) =>
+        value === 'uncontrolled' || value === 'unreported')) {
+    throw new Error('AFK dispatch requires verified environment precedence');
+  }
+  return Object.freeze({
+    schemaVersion: DISPATCH_RECEIPT_VERSION,
+    executionId: string(input.executionId, 'executionId'),
+    status: 'dispatched',
+    afk: input.afk === true,
+    requestedRoute,
+    appliedRoute,
+    enforcement: appliedEnforcement,
+    precedence: appliedPrecedence,
+    revisions: revisions(input.revisions),
+    dispatchedAt: timestamp(input.dispatchedAt, 'dispatchedAt'),
+    reason: null,
+  });
+}

package/src/lib/frontendWorkloads.mjs

@@ -0,0 +1,170 @@
+import {
+  evidenceWorkloadIdentity,
+  validateEvidenceSelection,
+} from './routingIntent.mjs';
+
+const FRONTEND_DOMAINS = new Set([
+  'general',
+  'reference-design',
+  'marketing',
+  'analytics',
+  'product',
+  'game',
+  'simulation',
+  'editor',
+]);
+
+const QUALITY_AXES = new Set([
+  'visual-preference',
+  'visual-fidelity',
+  'functional',
+  'accessibility',
+  'responsive',
+]);
+
+export const FRONTEND_SOURCE_CLAIMS = Object.freeze({
+  'code-arena-webdev': Object.freeze({
+    workloads: Object.freeze(['frontend-greenfield']),
+    axes: Object.freeze(['visual-preference']),
+    decisive: true,
+  }),
+  'openhands-frontend': Object.freeze({
+    workloads: Object.freeze(['frontend-repository-repair']),
+    axes: Object.freeze(['functional']),
+    decisive: true,
+  }),
+  vision2web: Object.freeze({
+    workloads: Object.freeze(['frontend-greenfield']),
+    axes: Object.freeze(['visual-fidelity', 'functional', 'responsive']),
+    decisive: false,
+  }),
+  design2code: Object.freeze({
+    workloads: Object.freeze(['frontend-greenfield']),
+    axes: Object.freeze(['visual-fidelity']),
+    decisive: false,
+  }),
+});
+
+function nonEmptyString(value, field) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new TypeError(`${field} must be a non-empty string`);
+  }
+  return value;
+}
+
+function plainObject(value, field) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError(`${field} must be an object`);
+  }
+  return value;
+}
+
+export function classifyFrontendWorkload(input) {
+  plainObject(input, 'frontend workload');
+  const lifecycle = nonEmptyString(input.lifecycle, 'frontend workload lifecycle');
+  const repositoryContext = nonEmptyString(
+    input.repositoryContext,
+    'frontend workload repositoryContext',
+  );
+  if (!Array.isArray(input.qualityAxes) || input.qualityAxes.length === 0) {
+    throw new TypeError('frontend workload qualityAxes must be a non-empty array');
+  }
+  if (new Set(input.qualityAxes).size !== input.qualityAxes.length) {
+    throw new TypeError('frontend workload qualityAxes must be unique');
+  }
+  for (const axis of input.qualityAxes) {
+    if (!QUALITY_AXES.has(axis)) throw new TypeError(`unknown frontend quality axis: ${axis}`);
+  }
+
+  let workload;
+  let supportedAxes;
+  if (lifecycle === 'greenfield' && repositoryContext === 'isolated') {
+    workload = 'frontend-greenfield';
+    supportedAxes = FRONTEND_SOURCE_CLAIMS['code-arena-webdev'].axes;
+  } else if (
+    ['edit', 'repair'].includes(lifecycle)
+    && repositoryContext === 'existing-repository'
+  ) {
+    workload = 'frontend-repository-repair';
+    supportedAxes = FRONTEND_SOURCE_CLAIMS['openhands-frontend'].axes;
+  } else {
+    throw new TypeError(
+      `unsupported frontend workload mapping: ${lifecycle}/${repositoryContext}`,
+    );
+  }
+
+  const frontendDomain = input.frontendDomain ?? 'general';
+  if (!FRONTEND_DOMAINS.has(frontendDomain)) {
+    throw new TypeError(`unknown frontend domain: ${frontendDomain}`);
+  }
+  const evidenceAxes = input.qualityAxes.filter((axis) => supportedAxes.includes(axis));
+  const unsupportedAxes = input.qualityAxes.filter((axis) => !supportedAxes.includes(axis));
+  return Object.freeze({
+    evidenceSelection: validateEvidenceSelection({
+      workload,
+      domain: frontendDomain,
+      axes: evidenceAxes,
+    }),
+    repositoryContext,
+    unsupportedAxes: Object.freeze(unsupportedAxes),
+  });
+}
+
+export function frontendEvidenceWorkload({ workload, frontendDomain = 'general', axis }) {
+  if (!['frontend-greenfield', 'frontend-repository-repair'].includes(workload)) {
+    throw new TypeError(`unknown frontend evidence workload: ${workload}`);
+  }
+  if (!FRONTEND_DOMAINS.has(frontendDomain)) {
+    throw new TypeError(`unknown frontend domain: ${frontendDomain}`);
+  }
+  if (!QUALITY_AXES.has(axis)) throw new TypeError(`unknown frontend quality axis: ${axis}`);
+  return evidenceWorkloadIdentity({
+    workload,
+    domain: frontendDomain,
+    axes: [axis],
+  });
+}
+
+export function createFrontendRouteReason(observation) {
+  plainObject(observation, 'frontend observation');
+  const [workload, frontendDomain, axis, ...rest] =
+    nonEmptyString(observation.workload, 'frontend observation workload').split(':');
+  if (rest.length > 0 || !workload || !frontendDomain || !axis) {
+    throw new TypeError('frontend observation workload must name workload, domain, and axis');
+  }
+  const sourceId = nonEmptyString(
+    observation.source?.benchmark,
+    'frontend observation source benchmark',
+  );
+  return `${workload} (${frontendDomain}) is supported on ${axis} by ${sourceId}`;
+}
+
+export function evaluateVision2WebReadiness(input) {
+  plainObject(input, 'Vision2Web leaderboard');
+  const season = nonEmptyString(input.season, 'Vision2Web season');
+  const benchmarkVersion = nonEmptyString(
+    input.benchmarkVersion,
+    'Vision2Web benchmarkVersion',
+  );
+  if (!Array.isArray(input.results)) {
+    throw new TypeError('Vision2Web results must be an array');
+  }
+  if (input.results.length === 0) {
+    return Object.freeze({
+      sourceId: 'vision2web',
+      status: 'candidate',
+      season,
+      benchmarkVersion,
+      observations: Object.freeze([]),
+      reason: 'current-season-leaderboard-empty',
+    });
+  }
+  return Object.freeze({
+    sourceId: 'vision2web',
+    status: 'awaiting-owner-adapter-validation',
+    season,
+    benchmarkVersion,
+    observations: Object.freeze([]),
+    reason: 'results-require-owner-adapter',
+  });
+}

package/src/lib/reconcileReconReports.mjs

@@ -0,0 +1,111 @@
+import { validateReconReport } from './reportValidator.mjs';
+
+const byPath = (left, right) => left.path.localeCompare(right.path);
+const bySlice = (left, right) => left.localeCompare(right, 'en', { numeric: true });
+const edgeKey = ({ from, to }) => `${from}:${to}`;
+
+function validateReports(reports) {
+  if (!Array.isArray(reports)) throw new TypeError('recon reports must be an array');
+  const sliceIds = new Set();
+  for (const report of reports) {
+    const validation = validateReconReport(report);
+    if (!validation.ok) throw new Error(`invalid recon report: ${validation.errors.join('; ')}`);
+    if (sliceIds.has(report.sliceId)) throw new Error(`duplicate recon report for slice ${report.sliceId}`);
+    sliceIds.add(report.sliceId);
+  }
+  return sliceIds;
+}
+
+function buildGraph(reports, sliceIds) {
+  const edges = new Map();
+  const successors = new Map([...sliceIds].map((id) => [id, new Set()]));
+  const indegree = new Map([...sliceIds].map((id) => [id, 0]));
+  for (const { dependencyEdges } of reports) {
+    for (const edge of dependencyEdges) {
+      if (!sliceIds.has(edge.from) || !sliceIds.has(edge.to)) {
+        const unknown = !sliceIds.has(edge.from) ? edge.from : edge.to;
+        throw new Error(`dependency edge references unknown slice ${unknown}`);
+      }
+      if (edge.from === edge.to) throw new Error(`self dependency is not allowed for slice ${edge.from}`);
+      if (edges.has(edgeKey(edge))) continue;
+      edges.set(edgeKey(edge), edge);
+      successors.get(edge.from).add(edge.to);
+      indegree.set(edge.to, indegree.get(edge.to) + 1);
+    }
+  }
+  const ready = [...sliceIds].filter((id) => indegree.get(id) === 0).sort(bySlice);
+  const order = [];
+  while (ready.length > 0) {
+    const current = ready.shift();
+    order.push(current);
+    for (const next of [...successors.get(current)].sort(bySlice)) {
+      indegree.set(next, indegree.get(next) - 1);
+      if (indegree.get(next) === 0) ready.push(next);
+    }
+    ready.sort(bySlice);
+  }
+  if (order.length !== sliceIds.size) throw new Error('dependency graph contains a cycle');
+  return { edges: [...edges.values()].sort((a, b) => edgeKey(a).localeCompare(edgeKey(b))), successors, order };
+}
+
+function collectFiles(reports) {
+  const files = new Map();
+  for (const { sliceId, plannedFiles } of reports) {
+    for (const { path, role } of plannedFiles) {
+      const file = files.get(path) ?? { editors: new Set(), shared: false };
+      if (role === 'edit') file.editors.add(sliceId);
+      if (role === 'sharedMutable') file.shared = true;
+      files.set(path, file);
+    }
+  }
+  return files;
+}
+
+function canReach(from, to, successors) {
+  const pending = [...successors.get(from)];
+  const seen = new Set();
+  while (pending.length > 0) {
+    const current = pending.pop();
+    if (current === to) return true;
+    if (seen.has(current)) continue;
+    seen.add(current);
+    pending.push(...successors.get(current));
+  }
+  return false;
+}
+
+function orderedEditors(path, file, graph) {
+  const editors = [...file.editors];
+  if (file.shared && editors.length !== 1) {
+    const found = editors.sort(bySlice);
+    throw new Error(`${path} must have exactly one edit owner; found ${found.length ? found.join(', ') : '0'}`);
+  }
+  const position = new Map(graph.order.map((id, index) => [id, index]));
+  editors.sort((left, right) => position.get(left) - position.get(right));
+  for (let left = 0; left < editors.length; left += 1) {
+    for (let right = left + 1; right < editors.length; right += 1) {
+      if (!canReach(editors[left], editors[right], graph.successors)) {
+        throw new Error(`${path} edit owners are not totally ordered by dependencies`);
+      }
+    }
+  }
+  return editors;
+}
+
+/** Reconcile schema-valid per-slice recon reports before any builder dispatch. */
+export function reconcileReconReports(reports) {
+  const sliceIds = validateReports(reports);
+  const graph = buildGraph(reports, sliceIds);
+  const editOwners = [];
+  const overlaps = [];
+  for (const [path, file] of collectFiles(reports)) {
+    const sliceIdsForPath = orderedEditors(path, file, graph);
+    if (sliceIdsForPath.length > 0) editOwners.push({ path, sliceIds: sliceIdsForPath });
+    if (sliceIdsForPath.length > 1) overlaps.push({ path, editors: sliceIdsForPath });
+  }
+  return {
+    editOwners: editOwners.sort(byPath),
+    overlaps: overlaps.sort(byPath),
+    dependencyEdges: graph.edges,
+  };
+}