@ikon85/agent-workflow-kit 0.33.0 → 0.34.0

package/src/lib/routingAdapters/codex.mjs

@@ -0,0 +1,136 @@
+import { adaptClaudeRoutingInventory } from '../capabilityMatrix.mjs';
+
+const MODEL_SELECTORS = ['model'];
+const EFFORT_SELECTORS = ['effort', 'reasoning_effort', 'model_reasoning_effort'];
+
+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 schemaProperties(schema) {
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) return {};
+  if (!schema.properties || typeof schema.properties !== 'object'
+      || Array.isArray(schema.properties)) return {};
+  return schema.properties;
+}
+
+function hasSelector(properties, selectors) {
+  return selectors.some((selector) =>
+    Object.prototype.hasOwnProperty.call(properties, selector));
+}
+
+function uncontrolled(control) {
+  return {
+    ...control,
+    method: 'none',
+    enforced: false,
+    precedence: 'uncontrolled',
+    applied: undefined,
+  };
+}
+
+function applySpawnSchemaEvidence(path, properties) {
+  const candidate = { ...path };
+  if (path?.model?.method === 'per-spawn'
+      && !hasSelector(properties, MODEL_SELECTORS)) {
+    candidate.model = uncontrolled(path.model);
+  }
+  if (path?.effort?.method === 'per-spawn'
+      && !hasSelector(properties, EFFORT_SELECTORS)) {
+    candidate.effort = uncontrolled(path.effort);
+  }
+  return candidate;
+}
+
+function matchesRoute(path, route) {
+  return ['surfaceId', 'providerId', 'modelId', 'transportId']
+    .every((field) => path[field] === route[field]);
+}
+
+function appliedRoute(path, requestedRoute) {
+  return Object.freeze({
+    ...requestedRoute,
+    modelId: path.model.applied,
+    effort: path.effort.applied,
+  });
+}
+
+function mismatchReason(path, requested, applied) {
+  for (const field of ['modelId', 'effort']) {
+    if (requested[field] === applied[field]) continue;
+    const control = field === 'modelId' ? path.model : path.effort;
+    if (control.precedence === 'environment-over-agent-definition') {
+      return `environment precedence mismatch: ${field === 'modelId' ? 'model' : field}`;
+    }
+    return `applied route mismatch: ${field}`;
+  }
+  return null;
+}
+
+export function adaptCodexRoutingInventory(inventory) {
+  const source = object(inventory, 'Codex host attestation');
+  timestamp(source.observedAt, 'Codex host attestation observedAt');
+  const host = object(source.host, 'Codex host attestation host');
+  string(host.id, 'Codex host attestation host.id');
+  string(host.version, 'Codex host attestation host.version');
+  const properties = schemaProperties(source.spawnSchema);
+  const paths = Array.isArray(source.paths)
+    ? source.paths
+      .filter((path) => path?.surfaceId === 'codex')
+      .map((path) => applySpawnSchemaEvidence(path, properties))
+    : [];
+  return adaptClaudeRoutingInventory({
+    contractVersion: source.contractVersion,
+    paths,
+  });
+}
+
+export function createCodexRoutingAdapter({ inventory, dispatchers = {} }) {
+  const capabilities = adaptCodexRoutingInventory(inventory);
+  return Object.freeze({
+    async prepare(requestedRoute) {
+      const path = capabilities.paths.find((candidate) =>
+        matchesRoute(candidate, requestedRoute));
+      if (!path) throw new Error('Codex route capability is not attested');
+      if (!path.verified) throw new Error(path.verificationFailures.join('; '));
+      const invoke = dispatchers[path.transportId];
+      if (typeof invoke !== 'function') {
+        throw new Error(`transport has no approved dispatcher: ${path.transportId}`);
+      }
+      const applied = appliedRoute(path, requestedRoute);
+      const mismatch = mismatchReason(path, requestedRoute, applied);
+      const enforcement = Object.freeze({
+        model: path.model.method,
+        effort: path.effort.method,
+      });
+      return Object.freeze({
+        appliedRoute: applied,
+        enforcement,
+        precedence: Object.freeze({
+          model: path.model.precedence,
+          effort: path.effort.precedence,
+        }),
+        mismatchReason: mismatch,
+        dispatch: () => invoke(Object.freeze({ route: applied, enforcement })),
+      });
+    },
+  });
+}

package/src/lib/routingCatalog.mjs

@@ -0,0 +1,123 @@
+export const EVIDENCE_CATALOG_VERSION = 1;
+
+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 number(value, field) {
+  if (!Number.isFinite(value)) throw new TypeError(`${field} must be a finite number`);
+  return value;
+}
+
+function timestamp(value, field) {
+  string(value, field);
+  const parsed = Date.parse(value);
+  if (!Number.isFinite(parsed)) throw new TypeError(`${field} must be an ISO timestamp`);
+  return value;
+}
+
+function clone(value) {
+  return structuredClone(value);
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  for (const child of Object.values(value)) deepFreeze(child);
+  return value;
+}
+
+const identity = ({ providerId, modelId }) => `${providerId}:${modelId}`;
+
+function validateModel(model, index) {
+  object(model, `models[${index}]`);
+  return {
+    providerId: string(model.providerId, `models[${index}].providerId`),
+    modelId: string(model.modelId, `models[${index}].modelId`),
+  };
+}
+
+function validateObservation(entry, index, knownModels) {
+  const field = `observations[${index}]`;
+  object(entry, field);
+  const observation = {
+    id: string(entry.id, `${field}.id`),
+    providerId: string(entry.providerId, `${field}.providerId`),
+    modelId: string(entry.modelId, `${field}.modelId`),
+    effort: string(entry.effort, `${field}.effort`),
+    workload: string(entry.workload, `${field}.workload`),
+    harness: clone(object(entry.harness, `${field}.harness`)),
+    score: number(entry.score, `${field}.score`),
+    source: clone(object(entry.source, `${field}.source`)),
+    uncertainty: clone(object(entry.uncertainty, `${field}.uncertainty`)),
+    freshness: clone(object(entry.freshness, `${field}.freshness`)),
+    cost: clone(object(entry.cost, `${field}.cost`)),
+  };
+  string(observation.harness.id, `${field}.harness.id`);
+  string(observation.harness.version, `${field}.harness.version`);
+  string(observation.source.owner, `${field}.source.owner`);
+  string(observation.source.id, `${field}.source.id`);
+  string(observation.source.url, `${field}.source.url`);
+  string(observation.source.benchmark, `${field}.source.benchmark`);
+  string(observation.source.version, `${field}.source.version`);
+  string(observation.source.snapshotHash, `${field}.source.snapshotHash`);
+  string(observation.uncertainty.kind, `${field}.uncertainty.kind`);
+  number(observation.uncertainty.value, `${field}.uncertainty.value`);
+  const observedAt = timestamp(observation.freshness.observedAt, `${field}.freshness.observedAt`);
+  const expiresAt = timestamp(observation.freshness.expiresAt, `${field}.freshness.expiresAt`);
+  if (Date.parse(expiresAt) <= Date.parse(observedAt)) {
+    throw new TypeError(`${field}.freshness.expiresAt must follow observedAt`);
+  }
+  const amount = number(observation.cost.amount, `${field}.cost.amount`);
+  if (amount < 0) throw new TypeError(`${field}.cost.amount must be non-negative`);
+  string(observation.cost.currency, `${field}.cost.currency`);
+  string(observation.cost.unit, `${field}.cost.unit`);
+  if (!knownModels.has(identity(observation))) {
+    throw new TypeError(`${field} references an unknown model`);
+  }
+  return observation;
+}
+
+export function validateEvidenceCatalog(input) {
+  object(input, 'evidence catalog');
+  if (input.schemaVersion !== EVIDENCE_CATALOG_VERSION) {
+    throw new TypeError(`evidence catalog schemaVersion must be ${EVIDENCE_CATALOG_VERSION}`);
+  }
+  const revision = string(input.revision, 'evidence catalog revision');
+  if (!Array.isArray(input.models)) throw new TypeError('evidence catalog models must be an array');
+  if (!Array.isArray(input.observations)) {
+    throw new TypeError('evidence catalog observations must be an array');
+  }
+  const models = input.models.map(validateModel);
+  const modelIds = new Set();
+  for (const model of models) {
+    const key = identity(model);
+    if (modelIds.has(key)) throw new TypeError(`duplicate evidence model: ${key}`);
+    modelIds.add(key);
+  }
+  const observations = input.observations.map((entry, index) =>
+    validateObservation(entry, index, modelIds));
+  const observationIds = new Set();
+  for (const entry of observations) {
+    if (observationIds.has(entry.id)) {
+      throw new TypeError(`duplicate evidence observation: ${entry.id}`);
+    }
+    observationIds.add(entry.id);
+  }
+  return deepFreeze({
+    schemaVersion: EVIDENCE_CATALOG_VERSION,
+    revision,
+    models,
+    observations,
+  });
+}

package/src/lib/routingEvidenceCache.mjs

@@ -0,0 +1,222 @@
+import { validateEvidenceCatalog } from './routingCatalog.mjs';
+import { validateAccessGraph } from './routingAccessGraph.mjs';
+import { validateRoutingPolicy } from './routingPolicy.mjs';
+
+export const ROUTING_EVIDENCE_CACHE_VERSION = 1;
+
+function object(value, field) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError(`${field} must be an object`);
+  }
+  return value;
+}
+
+function timestamp(value, field) {
+  if (typeof value !== 'string' || !Number.isFinite(Date.parse(value))) {
+    throw new TypeError(`${field} must be an ISO timestamp`);
+  }
+  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 deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  for (const child of Object.values(value)) deepFreeze(child);
+  return value;
+}
+
+export function validateRoutingEvidenceSourceSnapshot(input, index = 0) {
+  const field = `sources[${index}]`;
+  object(input, field);
+  const sourceId = string(input.sourceId, `${field}.sourceId`);
+  const owner = string(input.owner, `${field}.owner`);
+  const artifactUrl = string(input.artifactUrl, `${field}.artifactUrl`);
+  const snapshotHash = string(input.snapshotHash, `${field}.snapshotHash`);
+  const observedAt = timestamp(input.observedAt, `${field}.observedAt`);
+  const expiresAt = timestamp(input.expiresAt, `${field}.expiresAt`);
+  if (Date.parse(expiresAt) <= Date.parse(observedAt)) {
+    throw new TypeError(`${field}.expiresAt must follow observedAt`);
+  }
+  if (!Array.isArray(input.models)) throw new TypeError(`${field}.models must be an array`);
+  if (!Array.isArray(input.observations)) {
+    throw new TypeError(`${field}.observations must be an array`);
+  }
+  const catalog = validateEvidenceCatalog({
+    schemaVersion: 1,
+    revision: `source:${sourceId}`,
+    models: input.models,
+    observations: input.observations,
+  });
+  for (const [observationIndex, observation] of catalog.observations.entries()) {
+    const observationField = `${field}.observations[${observationIndex}].source`;
+    if (observation.source.id !== sourceId) {
+      throw new TypeError(`${observationField}.id must equal ${sourceId}`);
+    }
+    if (observation.source.snapshotHash !== snapshotHash) {
+      throw new TypeError(`${observationField}.snapshotHash must equal loaded snapshotHash`);
+    }
+    if (observation.source.owner !== owner) {
+      throw new TypeError(`${observationField}.owner must equal ${owner}`);
+    }
+    if (observation.source.url !== artifactUrl) {
+      throw new TypeError(`${observationField}.url must equal ${artifactUrl}`);
+    }
+  }
+  const rawSignals = input.signals ?? [];
+  if (!Array.isArray(rawSignals)) throw new TypeError(`${field}.signals must be an array`);
+  const signals = rawSignals.map((signal, signalIndex) => {
+    object(signal, `${field}.signals[${signalIndex}]`);
+    return structuredClone(signal);
+  });
+  return deepFreeze({
+    sourceId,
+    owner,
+    artifactUrl,
+    snapshotHash,
+    observedAt,
+    expiresAt,
+    models: structuredClone(catalog.models),
+    observations: structuredClone(catalog.observations),
+    signals,
+  });
+}
+
+function validateSourceSnapshots(input) {
+  if (input === undefined) return [];
+  if (!Array.isArray(input)) throw new TypeError('routing evidence cache sources must be an array');
+  const sources = input.map(validateRoutingEvidenceSourceSnapshot);
+  const sourceIds = new Set();
+  const observationIds = new Set();
+  for (const source of sources) {
+    if (sourceIds.has(source.sourceId)) {
+      throw new TypeError(`duplicate routing evidence source: ${source.sourceId}`);
+    }
+    sourceIds.add(source.sourceId);
+    for (const observation of source.observations) {
+      if (observationIds.has(observation.id)) {
+        throw new TypeError(`duplicate evidence observation across sources: ${observation.id}`);
+      }
+      observationIds.add(observation.id);
+    }
+  }
+  return sources;
+}
+
+export function buildEvidenceCatalogFromSources(sources, revision) {
+  const validated = validateSourceSnapshots(sources);
+  const modelMap = new Map();
+  const observations = [];
+  const observationIds = new Set();
+  for (const source of validated) {
+    for (const model of source.models) {
+      modelMap.set(`${model.providerId}:${model.modelId}`, model);
+    }
+    for (const observation of source.observations) {
+      if (observationIds.has(observation.id)) {
+        throw new TypeError(`duplicate evidence observation across sources: ${observation.id}`);
+      }
+      observationIds.add(observation.id);
+      observations.push(observation);
+    }
+  }
+  return validateEvidenceCatalog({
+    schemaVersion: 1,
+    revision,
+    models: [...modelMap.values()],
+    observations,
+  });
+}
+
+function validateCacheShape(input) {
+  object(input, 'routing evidence cache');
+  if (input.schemaVersion !== ROUTING_EVIDENCE_CACHE_VERSION) {
+    throw new TypeError(
+      `routing evidence cache schemaVersion must be ${ROUTING_EVIDENCE_CACHE_VERSION}`,
+    );
+  }
+  if (!Number.isInteger(input.revision) || input.revision < 0) {
+    throw new TypeError('routing evidence cache revision must be a non-negative integer');
+  }
+  const refreshedAt = timestamp(input.refreshedAt, 'routing evidence cache refreshedAt');
+  const expiresAt = timestamp(input.expiresAt, 'routing evidence cache expiresAt');
+  if (Date.parse(expiresAt) <= Date.parse(refreshedAt)) {
+    throw new TypeError('routing evidence cache expiresAt must follow refreshedAt');
+  }
+  return deepFreeze({
+    schemaVersion: ROUTING_EVIDENCE_CACHE_VERSION,
+    revision: input.revision,
+    refreshedAt,
+    expiresAt,
+    catalog: validateEvidenceCatalog(input.catalog),
+    sources: validateSourceSnapshots(input.sources),
+  });
+}
+
+export function routingEvidenceSourcesFromCache(input) {
+  return validateCacheShape(input).sources;
+}
+
+export function validateRoutingEvidenceCache(input, { now } = {}) {
+  const cache = validateCacheShape(input);
+  const checkedAt = Date.parse(now);
+  if (!Number.isFinite(checkedAt)) throw new TypeError('now must be an ISO timestamp');
+  if (Date.parse(cache.expiresAt) <= checkedAt) {
+    throw new Error(`stale routing evidence cache: expired at ${cache.expiresAt}`);
+  }
+  return cache;
+}
+
+export function commitRoutingEvidenceCache({
+  current,
+  expectedRevision,
+  nextCatalog,
+  nextSources,
+  refreshedAt,
+  expiresAt,
+}) {
+  const cache = validateCacheShape(current);
+  if (cache.revision !== expectedRevision) {
+    throw new Error(
+      `concurrent evidence cache mutation: expected revision ${expectedRevision}, `
+      + `found ${cache.revision}`,
+    );
+  }
+  return validateRoutingEvidenceCache({
+    schemaVersion: ROUTING_EVIDENCE_CACHE_VERSION,
+    revision: cache.revision + 1,
+    refreshedAt,
+    expiresAt,
+    catalog: nextCatalog,
+    sources: nextSources ?? cache.sources,
+  }, { now: refreshedAt });
+}
+
+export function captureRoutingProfileSnapshot({ accessGraph, policy }) {
+  const access = validateAccessGraph(accessGraph);
+  const routingPolicy = validateRoutingPolicy(policy);
+  return Object.freeze({
+    accessGraph: access.revision,
+    policy: routingPolicy.revision,
+  });
+}
+
+export function assertRoutingProfileUnchanged(snapshot, { accessGraph, policy }) {
+  object(snapshot, 'routing profile snapshot');
+  const current = captureRoutingProfileSnapshot({ accessGraph, policy });
+  for (const field of ['accessGraph', 'policy']) {
+    if (snapshot[field] !== current[field]) {
+      throw new Error(
+        `concurrent routing profile mutation: ${field} changed from `
+        + `${snapshot[field]} to ${current[field]}`,
+      );
+    }
+  }
+  return true;
+}

package/src/lib/routingIntent.mjs

@@ -0,0 +1,93 @@
+export const ROUTING_INTENT_VERSION = 1;
+
+export const ROUTING_WORKLOADS = Object.freeze([
+  'judgment',
+  'development',
+  'mechanical',
+]);
+
+export const ROUTING_REASONING = Object.freeze([
+  'deep',
+  'balanced',
+  'light',
+]);
+
+const FIELDS = new Set(['version', 'workload', 'reasoning', 'evidenceSelection']);
+const EVIDENCE_SELECTION_FIELDS = new Set(['workload', 'domain', 'axes']);
+
+function requireEnum(value, allowed, field) {
+  if (!allowed.includes(value)) {
+    throw new TypeError(`${field} must be one of: ${allowed.join(', ')}`);
+  }
+  return value;
+}
+
+function requireIdentitySegment(value, field) {
+  if (typeof value !== 'string' || value.trim() === '' || value.includes(':')) {
+    throw new TypeError(`${field} must be a non-empty string without colons`);
+  }
+  return value;
+}
+
+export function validateEvidenceSelection(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new TypeError('evidence selection must be an object');
+  }
+  for (const field of Object.keys(input)) {
+    if (!EVIDENCE_SELECTION_FIELDS.has(field)) {
+      throw new TypeError(`unknown evidence selection field: ${field}`);
+    }
+  }
+  if (!Array.isArray(input.axes) || input.axes.length === 0) {
+    throw new TypeError('evidence selection axes must be a non-empty array');
+  }
+  const axes = input.axes.map((axis) =>
+    requireIdentitySegment(axis, 'evidence selection axis'));
+  if (new Set(axes).size !== axes.length) {
+    throw new TypeError('evidence selection axes must be unique');
+  }
+  return Object.freeze({
+    workload: requireIdentitySegment(input.workload, 'evidence selection workload'),
+    domain: requireIdentitySegment(input.domain, 'evidence selection domain'),
+    axes: Object.freeze(axes),
+  });
+}
+
+export function evidenceWorkloadIdentity(input) {
+  const selection = validateEvidenceSelection(input);
+  if (selection.axes.length !== 1) {
+    throw new TypeError('evidence workload identity requires exactly one axis');
+  }
+  return `${selection.workload}:${selection.domain}:${selection.axes[0]}`;
+}
+
+export function evidenceSelectionMatchesObservation(input, observationWorkload) {
+  const selection = validateEvidenceSelection(input);
+  if (typeof observationWorkload !== 'string') return false;
+  const [workload, domain, axis, ...rest] = observationWorkload.split(':');
+  if (rest.length > 0 || !workload || !domain || !axis) return false;
+  return selection.workload === workload
+    && selection.domain === domain
+    && selection.axes.includes(axis);
+}
+
+export function validateRoutingIntent(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new TypeError('routing intent must be an object');
+  }
+  for (const field of Object.keys(input)) {
+    if (!FIELDS.has(field)) throw new TypeError(`unknown routing intent field: ${field}`);
+  }
+  if (input.version !== ROUTING_INTENT_VERSION) {
+    throw new TypeError(`routing intent version must be ${ROUTING_INTENT_VERSION}`);
+  }
+  const intent = {
+    version: ROUTING_INTENT_VERSION,
+    workload: requireEnum(input.workload, ROUTING_WORKLOADS, 'workload'),
+    reasoning: requireEnum(input.reasoning, ROUTING_REASONING, 'reasoning'),
+  };
+  if (input.evidenceSelection !== undefined) {
+    intent.evidenceSelection = validateEvidenceSelection(input.evidenceSelection);
+  }
+  return Object.freeze(intent);
+}

package/src/lib/routingPolicy.mjs

@@ -0,0 +1,67 @@
+export const ROUTING_POLICY_VERSION = 1;
+
+const POLICY_FIELDS = new Set([
+  'schemaVersion',
+  'revision',
+  'allowedSurfaces',
+  'allowedTransports',
+  'switching',
+  'optimization',
+  'unreachable',
+  'missingInfrastructure',
+]);
+
+const SWITCHING = ['automatic', 'ask', 'current-surface-only'];
+const OPTIMIZATION = ['quality', 'balanced', 'cost'];
+const UNREACHABLE = ['handoff', 'inherit', 'block'];
+const MISSING_INFRASTRUCTURE = ['inherit', 'block'];
+
+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 stringList(value, field) {
+  if (!Array.isArray(value) || !value.every((entry) => typeof entry === 'string' && entry !== '')) {
+    throw new TypeError(`${field} must be an array of non-empty strings`);
+  }
+  return [...new Set(value)];
+}
+
+function oneOf(value, values, field) {
+  if (!values.includes(value)) throw new TypeError(`${field} must be one of: ${values.join(', ')}`);
+  return value;
+}
+
+export function validateRoutingPolicy(input) {
+  object(input, 'routing policy');
+  for (const key of Object.keys(input)) {
+    if (!POLICY_FIELDS.has(key)) throw new TypeError(`unknown routing policy field: ${key}`);
+  }
+  if (input.schemaVersion !== ROUTING_POLICY_VERSION) {
+    throw new TypeError(`routing policy schemaVersion must be ${ROUTING_POLICY_VERSION}`);
+  }
+  return Object.freeze({
+    schemaVersion: ROUTING_POLICY_VERSION,
+    revision: string(input.revision, 'routing policy revision'),
+    allowedSurfaces: Object.freeze(stringList(input.allowedSurfaces, 'allowedSurfaces')),
+    allowedTransports: Object.freeze(stringList(input.allowedTransports, 'allowedTransports')),
+    switching: oneOf(input.switching, SWITCHING, 'switching'),
+    optimization: oneOf(input.optimization, OPTIMIZATION, 'optimization'),
+    unreachable: oneOf(input.unreachable, UNREACHABLE, 'unreachable'),
+    missingInfrastructure: oneOf(
+      input.missingInfrastructure,
+      MISSING_INFRASTRUCTURE,
+      'missingInfrastructure',
+    ),
+  });
+}