@ikon85/agent-workflow-kit 0.44.1 → 0.45.0

package/src/lib/routingSources/deepswe.mjs

@@ -1,7 +1,15 @@
+import {
+  assertPublishedEffort,
+  evidenceFreshness,
+  evidenceIdentity,
+  evidenceSourceClaim,
+} from '../routingCatalog.mjs';
+
 const SOURCE_ID = 'deepswe';
 const OWNER = 'DataCurve';
 const ARTIFACT_URL =
   'https://deepswe.datacurve.ai/artifacts/v1.1/leaderboard-live.json';
+const WORKLOAD = evidenceIdentity({ workload: 'repository-repair', axis: 'functional' });
 
 function object(value, field) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
@@ -34,7 +42,9 @@ function context({ snapshotHash, observedAt, expiresAt }) {
 }
 
 function ingest({ payload, ...inputContext }) {
-  const { snapshotHash, observedAt, expiresAt } = context(inputContext);
+  // The caller's window bounds the refresh; the observation is dated by the
+  // Kit-side freshness policy for this source, never by the owner artifact.
+  const { snapshotHash, observedAt } = context(inputContext);
   object(payload, 'DeepSWE payload');
   const artifact = object(payload.artifact, 'DeepSWE artifact');
   if (artifact.owner !== OWNER || artifact.url !== ARTIFACT_URL) {
@@ -54,7 +64,10 @@ function ingest({ payload, ...inputContext }) {
     object(row, `DeepSWE rows[${index}]`);
     const providerId = string(row.provider, `DeepSWE rows[${index}].provider`);
     const modelId = string(row.model, `DeepSWE rows[${index}].model`);
-    const effort = string(row.effort, `DeepSWE rows[${index}].effort`);
+    const effort = assertPublishedEffort({
+      sourceId: SOURCE_ID,
+      effort: string(row.effort, `DeepSWE rows[${index}].effort`),
+    });
     const id = `${SOURCE_ID}:${benchmarkVersion}:${providerId}:${modelId}:${effort}`;
     if (observationIds.has(id)) throw new TypeError(`duplicate DeepSWE observation: ${id}`);
     observationIds.add(id);
@@ -64,7 +77,7 @@ function ingest({ payload, ...inputContext }) {
       providerId,
       modelId,
       effort,
-      workload: 'development',
+      workload: WORKLOAD,
       harness: { id: harnessId, version: harnessVersion },
       score: number(row.score, `DeepSWE rows[${index}].score`),
       source: {
@@ -82,11 +95,11 @@ function ingest({ payload, ...inputContext }) {
           `DeepSWE rows[${index}].confidence95HalfWidth`,
         ),
       },
-      freshness: { observedAt, expiresAt },
+      freshness: evidenceFreshness({ sourceId: SOURCE_ID, observedAt }),
       cost: {
         amount: number(row.averageCostUsd, `DeepSWE rows[${index}].averageCostUsd`),
         currency: 'USD',
-        unit: 'task',
+        unit: 'attempt',
       },
     });
   });
@@ -102,5 +115,6 @@ export const deepSweSource = Object.freeze({
   sourceId: SOURCE_ID,
   owner: OWNER,
   artifactUrl: ARTIFACT_URL,
+  claim: evidenceSourceClaim(SOURCE_ID),
   ingest,
 });

package/src/lib/routingSources/openhands.mjs

@@ -1,6 +1,15 @@
+import {
+  assertCostUnit,
+  assertPublishedEffort,
+  evidenceFreshness,
+  evidenceIdentity,
+  evidenceSourceClaim,
+} from '../routingCatalog.mjs';
+
 const SOURCE_ID = 'openhands-evaluation';
 const OWNER = 'All Hands AI';
 const ARTIFACT_URL = 'https://github.com/All-Hands-AI/OpenHands/tree/main/evaluation';
+const WORKLOAD = evidenceIdentity({ workload: 'repository-repair', axis: 'functional' });
 
 function object(value, field) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
@@ -50,7 +59,10 @@ function ingest({ payload, snapshotHash, observedAt, expiresAt }) {
     object(row, `OpenHands results[${index}]`);
     const providerId = string(row.provider, `OpenHands results[${index}].provider`);
     const modelId = string(row.model, `OpenHands results[${index}].model`);
-    const effort = string(row.effort, `OpenHands results[${index}].effort`);
+    const effort = assertPublishedEffort({
+      sourceId: SOURCE_ID,
+      effort: string(row.effort, `OpenHands results[${index}].effort`),
+    });
     const id = `${SOURCE_ID}:${benchmarkVersion}:${providerId}:${modelId}:${effort}`;
     if (observationIds.has(id)) throw new TypeError(`duplicate OpenHands observation: ${id}`);
     observationIds.add(id);
@@ -61,7 +73,7 @@ function ingest({ payload, snapshotHash, observedAt, expiresAt }) {
       providerId,
       modelId,
       effort,
-      workload: 'development',
+      workload: WORKLOAD,
       harness: { id: harnessId, version: harnessVersion },
       score: number(row.resolvedRate, `OpenHands results[${index}].resolvedRate`),
       source: {
@@ -76,14 +88,14 @@ function ingest({ payload, snapshotHash, observedAt, expiresAt }) {
         kind: 'standard-error',
         value: number(row.standardError, `OpenHands results[${index}].standardError`),
       },
-      freshness: { observedAt, expiresAt },
+      freshness: evidenceFreshness({ sourceId: SOURCE_ID, observedAt }),
       cost: {
         amount: number(meanCost.amount, `OpenHands results[${index}].meanCost.amount`),
         currency: string(
           meanCost.currency,
           `OpenHands results[${index}].meanCost.currency`,
         ),
-        unit: string(meanCost.unit, `OpenHands results[${index}].meanCost.unit`),
+        unit: assertCostUnit(meanCost.unit, `OpenHands results[${index}].meanCost.unit`),
       },
     });
   });
@@ -98,5 +110,6 @@ export const openHandsSource = Object.freeze({
   sourceId: SOURCE_ID,
   owner: OWNER,
   artifactUrl: ARTIFACT_URL,
+  claim: evidenceSourceClaim(SOURCE_ID),
   ingest,
 });

package/src/lib/routingSources/openhandsFrontend.mjs

@@ -1,4 +1,10 @@
 import { frontendEvidenceWorkload } from '../frontendWorkloads.mjs';
+import {
+  assertCostUnit,
+  assertPublishedEffort,
+  evidenceFreshness,
+  evidenceSourceClaim,
+} from '../routingCatalog.mjs';
 
 const OWNER_URL = 'https://www.openhands.dev/blog/openhands-index';
 const SOURCE_ID = 'openhands-frontend';
@@ -70,7 +76,10 @@ function ingest({ payload, snapshotHash, observedAt, expiresAt }) {
     object(row, `OpenHands rows[${index}]`);
     const providerId = string(row.providerId, `OpenHands rows[${index}].providerId`);
     const modelId = string(row.modelId, `OpenHands rows[${index}].modelId`);
-    const effort = string(row.effort, `OpenHands rows[${index}].effort`);
+    const effort = assertPublishedEffort({
+      sourceId: SOURCE_ID,
+      effort: string(row.effort, `OpenHands rows[${index}].effort`),
+    });
     const modelIdentity = `${providerId}:${modelId}`;
     if (!modelIds.has(modelIdentity)) {
       models.push({ providerId, modelId });
@@ -116,11 +125,11 @@ function ingest({ payload, snapshotHash, observedAt, expiresAt }) {
         status: row.status,
         sampleSize: finite(row.sampleSize, `OpenHands rows[${index}].sampleSize`),
       },
-      freshness: { observedAt, expiresAt },
+      freshness: evidenceFreshness({ sourceId: SOURCE_ID, observedAt }),
       cost: {
         amount: finite(row.cost.amount, `OpenHands rows[${index}].cost.amount`),
         currency: string(row.cost.currency, `OpenHands rows[${index}].cost.currency`),
-        unit: string(row.cost.unit, `OpenHands rows[${index}].cost.unit`),
+        unit: assertCostUnit(row.cost.unit, `OpenHands rows[${index}].cost.unit`),
       },
     });
   }
@@ -131,5 +140,6 @@ export const openHandsFrontendSource = Object.freeze({
   sourceId: SOURCE_ID,
   owner: 'OpenHands',
   artifactUrl: OWNER_URL,
+  claim: evidenceSourceClaim(SOURCE_ID),
   ingest,
 });

package/src/lib/safeText.mjs

@@ -0,0 +1,26 @@
+/**
+ * Text that reaches a terminal verbatim.
+ *
+ * Two shipped surfaces need the same guarantee and must not each grow their own
+ * copy: the update plan renders Kit-authored manifest prose, and `routing status`
+ * renders diagnostics that can carry an external error message. Either would
+ * repaint the terminal if a control sequence rode through, so both strip C0/C1
+ * control characters here.
+ *
+ * This module is a leaf on purpose: it imports nothing, so an installed consumer
+ * receives it whole without dragging the installer-side update machinery along.
+ */
+
+/**
+ * Validate that a value is a string and strip C0/C1 control characters plus
+ * redundant whitespace from it. Returns null for a non-string or an input that
+ * sanitizes to nothing, so a caller can distinguish "absent" from "empty".
+ */
+export function sanitizeReadinessText(value) {
+  if (typeof value !== 'string') return null;
+  const cleaned = value
+    .replace(/[\u0000-\u001f\u007f-\u009f]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return cleaned || null;
+}

package/src/lib/updateCandidate.mjs

@@ -11,6 +11,7 @@ import { validateConsumerFile } from './consumerPath.mjs';
 import { sha256File } from './hash.mjs';
 import { stubSentinel } from './sentinel.mjs';
 import { STUB_TARGETS } from './bundle.mjs';
+import { sanitizeReadinessText } from './safeText.mjs';
 import {
   CONSUMER_MANIFEST_NAME, CONSUMER_ORIGIN, READINESS_MANIFEST_PATH,
   filesForInstallRole, indexByPath, readManifest, validateManifest, writeManifest,
@@ -415,7 +416,7 @@ export async function adoptReadinessCandidate({
     migrations,
     migrated: migrations.map(({ path }) => path),
     migrationConflicts,
-    availability: readinessDiff(before, after),
+    availability: readinessDiff(before, after, nextManifest?.readiness?.capabilities),
     incompatible,
   };
 }
@@ -568,11 +569,38 @@ async function readinessSnapshot(root, manifest) {
   return { skills, capabilities };
 }
 
-function readinessDiff(before, after) {
+/**
+ * Manifest prose is Kit-authored but reaches a terminal verbatim, so every
+ * catalog string is validated (must be a string) and stripped of C0/C1 control
+ * characters — an escape sequence would otherwise repaint the update plan.
+ *
+ * The implementation moved to `./safeText.mjs` when `routing status` needed the
+ * same guarantee: that command ships to consumers, this module does not, so
+ * importing it from here would have escaped the installed consumer. Imported
+ * and re-exported rather than relocated, so this module keeps using it and
+ * every existing caller keeps its import path.
+ */
+export { sanitizeReadinessText };
+
+/** One unresolved capability in plain terms: what it is and what closes it. */
+function unresolvedEntry(capability, state, catalogEntry) {
+  return {
+    capability,
+    state,
+    title: sanitizeReadinessText(catalogEntry?.title),
+    remedy: sanitizeReadinessText(catalogEntry?.remedy),
+    evidencePaths: (catalogEntry?.evidence?.paths ?? [])
+      .map(sanitizeReadinessText)
+      .filter((path) => path !== null),
+  };
+}
+
+function readinessDiff(before, after, catalog = {}) {
   const newlyAvailable = [];
   const newlyDegraded = [];
   const newlyBlocked = [];
   const unresolved = new Set();
+  const unresolvedEntries = [];
   for (const [skill, current] of Object.entries(after.skills)) {
     const prior = before.skills[skill];
     if (current.verdict === 'blocked' && prior?.verdict !== 'blocked') newlyBlocked.push(skill);
@@ -582,11 +610,16 @@ function readinessDiff(before, after) {
     }
   }
   for (const [capability, result] of Object.entries(after.capabilities)) {
-    if (result.state !== 'ready') unresolved.add(`${capability}:${result.state}`);
+    if (result.state === 'ready') continue;
+    unresolved.add(`${capability}:${result.state}`);
+    unresolvedEntries.push(unresolvedEntry(capability, result.state, catalog?.[capability]));
   }
   return {
     newlyAvailable: newlyAvailable.sort(), newlyDegraded: newlyDegraded.sort(),
     newlyBlocked: newlyBlocked.sort(), stillUnresolved: [...unresolved].sort(),
+    unresolved: unresolvedEntries.sort(
+      (a, b) => (a.capability < b.capability ? -1 : 1),
+    ),
   };
 }