opencode-wait-a-minute 0.0.0-stage → 1.1.0-rc.10

package/src/context/context-rate-distortion.js

@@ -0,0 +1,261 @@
+/**
+ * Context Rate-Distortion (C05 — context-rate-distortion).
+ *
+ * Combines Context Reduction Rate (CRR = tokensSaved / tokensFull) with
+ * Oracle Sufficiency verification (verifySufficiency) to compute the true
+ * rate-distortion curve:
+ *
+ *   rate(b)        = 1 - tokens(b) / tokensFull       (compression ratio)
+ *   distortion(b)  = 1 - sufficient(b)                (sufficiency loss)
+ *
+ * Where:
+ *   tokensFull   = sum of token counts of all candidates
+ *   tokens(b)    = sum of token counts of the selected set at budget b
+ *   sufficient(b) = verifySufficiency(task, selected(b))
+ *
+ * The curve answers: "how aggressively can we compress while still being
+ * oracle-sufficient?"
+ *
+ *   - RDReport.curve          - [{rate, distortion, sufficient, budget, selected}]
+ *   - RDReport.operatingPoint - first budget where sufficient===true (or null)
+ *   - RDReport.maxRate        - largest rate at which distortion===0
+ *   - RDReport.crr            - rate at the operating point (or max rate)
+ *
+ * Independence: uses oracle ground truth; does not consult scoring weights.
+ */
+
+import {
+  computeRequiredClosure,
+  verifySufficiency,
+} from "./context-sufficiency-oracle.js";
+
+/**
+ * @typedef {Object} ContextItem
+ * @property {string} id
+ * @property {number} tokens
+ * @property {number} [priority] - higher = kept earlier under budget; ties broken by id
+ */
+
+/**
+ * @typedef {Object} RDPoint
+ * @property {number} budget
+ * @property {number} rate             - in [0, 1]
+ * @property {number} distortion       - in [0, 1] (0 = sufficient)
+ * @property {boolean} sufficient
+ * @property {string[]} selected
+ * @property {number} tokensUsed
+ */
+
+/**
+ * @typedef {Object} RDReport
+ * @property {string} taskId
+ * @property {number} fullTokens
+ * @property {RDPoint[]} curve
+ * @property {RDPoint|null} operatingPoint - first point with sufficient===true
+ * @property {number} crr                 - rate at operating point (or maxRate)
+ * @property {number} maxRate             - largest rate where distortion===0
+ * @property {Object} stats
+ */
+
+/**
+ * Greedy fill: pick items in priority-descending order until budget exhausted.
+ *
+ * @param {ContextItem[]} candidates
+ * @param {number} budget
+ * @returns {string[]} selected ids
+ */
+function selectByBudget(candidates, budget) {
+  if (!Array.isArray(candidates) || budget <= 0) return [];
+  const sorted = candidates
+    .filter((c) => c && typeof c.id === "string" && typeof c.tokens === "number")
+    .slice()
+    .sort((a, b) => {
+      const pa = typeof a.priority === "number" ? a.priority : 0;
+      const pb = typeof b.priority === "number" ? b.priority : 0;
+      if (pb !== pa) return pb - pa;
+      return a.id.localeCompare(b.id);
+    });
+  const out = [];
+  let used = 0;
+  for (const c of sorted) {
+    if (used + c.tokens <= budget) {
+      out.push(c.id);
+      used += c.tokens;
+    }
+  }
+  return out;
+}
+
+/**
+ * Compute the rate-distortion curve.
+ *
+ * @param {Object} input
+ * @param {string} input.taskId
+ * @param {ContextItem[]} input.candidates
+ * @param {Object} input.oracleGraph
+ * @param {number[]} [input.budgets] - explicit budgets to sweep. If omitted,
+ *   sweep is derived from candidates (each unique prefix budget).
+ * @returns {RDReport}
+ */
+export function computeRateDistortion(input) {
+  if (!input || typeof input !== "object") {
+    throw new TypeError("computeRateDistortion: input required");
+  }
+  const { taskId, candidates, oracleGraph } = input;
+  if (typeof taskId !== "string" || taskId.length === 0) {
+    throw new TypeError("computeRateDistortion: taskId required");
+  }
+  if (!Array.isArray(candidates)) {
+    throw new TypeError("computeRateDistortion: candidates must be an array");
+  }
+  if (!oracleGraph || typeof oracleGraph.getNode !== "function") {
+    throw new TypeError("computeRateDistortion: oracleGraph required");
+  }
+
+  const requiredClosure = computeRequiredClosure(taskId, oracleGraph);
+  const requiredSet = new Set(requiredClosure);
+
+  const fullTokens = candidates.reduce(
+    (acc, c) => acc + (typeof c.tokens === "number" ? c.tokens : 0),
+    0,
+  );
+
+  let budgets = input.budgets;
+  if (!Array.isArray(budgets) || budgets.length === 0) {
+    // derive: 0, plus cumulative token sums in priority order
+    const sorted = candidates
+      .filter((c) => c && typeof c.tokens === "number")
+      .slice()
+      .sort((a, b) => {
+        const pa = typeof a.priority === "number" ? a.priority : 0;
+        const pb = typeof b.priority === "number" ? b.priority : 0;
+        if (pb !== pa) return pb - pa;
+        return a.id.localeCompare(b.id);
+      });
+    const derived = [0];
+    let acc = 0;
+    for (const c of sorted) {
+      acc += c.tokens;
+      if (acc !== derived[derived.length - 1]) derived.push(acc);
+    }
+    if (derived[derived.length - 1] !== fullTokens) derived.push(fullTokens);
+    budgets = derived;
+  }
+  budgets = [...new Set(budgets.filter((b) => typeof b === "number" && b >= 0))].sort((a, b) => a - b);
+
+  /** @type {RDPoint[]} */
+  const curve = [];
+  let operatingPoint = null;
+  let maxRate = 0;
+
+  for (const budget of budgets) {
+    const selected = selectByBudget(candidates, budget);
+    const verdict = verifySufficiency(taskId, oracleGraph, selected);
+    const tokensUsed = selected.reduce((acc, id) => {
+      const c = candidates.find((x) => x.id === id);
+      return acc + (c && typeof c.tokens === "number" ? c.tokens : 0);
+    }, 0);
+    const rate = fullTokens === 0 ? 1 : 1 - tokensUsed / fullTokens;
+    const distortion = verdict.sufficient ? 0 : 1;
+    const point = {
+      budget,
+      rate: clamp01(rate),
+      distortion: clamp01(distortion),
+      sufficient: verdict.sufficient,
+      selected,
+      tokensUsed,
+    };
+    curve.push(point);
+    if (operatingPoint === null && verdict.sufficient) {
+      operatingPoint = point;
+    }
+    if (verdict.sufficient && point.rate > maxRate) {
+      maxRate = point.rate;
+    }
+  }
+
+  // Track which required nodes were ever included across any point
+  const everIncludedRequired = new Set();
+  for (const p of curve) {
+    for (const id of p.selected) if (requiredSet.has(id)) everIncludedRequired.add(id);
+  }
+  const unreachableRequired = requiredClosure.filter((id) => !everIncludedRequired.has(id));
+
+  const crr = operatingPoint ? operatingPoint.rate : (curve.length ? curve[curve.length - 1].rate : 0);
+
+  return {
+    taskId,
+    fullTokens,
+    curve,
+    operatingPoint,
+    crr: clamp01(crr),
+    maxRate: clamp01(maxRate),
+    stats: {
+      pointCount: curve.length,
+      requiredCount: requiredClosure.length,
+      unreachableRequiredCount: unreachableRequired.length,
+      unreachableRequired,
+      sufficientPoints: curve.filter((p) => p.sufficient).length,
+    },
+  };
+}
+
+/**
+ * Convenience: Context Reduction Rate at a specific budget.
+ *
+ * @param {RDReport} report
+ * @param {number} budget
+ * @returns {number} CRR in [0, 1]; 0 if budget not in curve.
+ */
+export function crrAt(report, budget) {
+  if (!report || !Array.isArray(report.curve)) return 0;
+  const point = report.curve.find((p) => p.budget === budget);
+  if (!point) return 0;
+  return point.rate;
+}
+
+/**
+ * Convenience: distortion at a specific budget.
+ *
+ * @param {RDReport} report
+ * @param {number} budget
+ * @returns {number} distortion in [0, 1]; 1 if budget not in curve.
+ */
+export function distortionAt(report, budget) {
+  if (!report || !Array.isArray(report.curve)) return 1;
+  const point = report.curve.find((p) => p.budget === budget);
+  if (!point) return 1;
+  return point.distortion;
+}
+
+/**
+ * Aggregate rate-distortion across multiple tasks into a mean curve.
+ *
+ * @param {RDReport[]} reports
+ * @returns {{meanCrr: number, meanMaxRate: number, pointCount: number}}
+ */
+export function aggregateRateDistortion(reports) {
+  if (!Array.isArray(reports) || reports.length === 0) {
+    return { meanCrr: 0, meanMaxRate: 0, pointCount: 0 };
+  }
+  let crrSum = 0;
+  let maxSum = 0;
+  let pts = 0;
+  for (const r of reports) {
+    if (typeof r.crr === "number" && !Number.isNaN(r.crr)) crrSum += r.crr;
+    if (typeof r.maxRate === "number" && !Number.isNaN(r.maxRate)) maxSum += r.maxRate;
+    pts += r && Array.isArray(r.curve) ? r.curve.length : 0;
+  }
+  return {
+    meanCrr: crrSum / reports.length,
+    meanMaxRate: maxSum / reports.length,
+    pointCount: pts,
+  };
+}
+
+function clamp01(n) {
+  if (typeof n !== "number" || Number.isNaN(n)) return 0;
+  if (n < 0) return 0;
+  if (n > 1) return 1;
+  return n;
+}

package/src/context/context-recovery.js

@@ -0,0 +1,209 @@
+/**
+ * Context Recovery — Reconstruct minimum corrective context when agent drifts.
+ *
+ * Change 78: reconstructMinimumCorrectiveContext()
+ *
+ * When an agent action has drifted from the goal, this module
+ * rebuilds the minimal context needed to get back on track.
+ *
+ * The recovery context includes:
+ *   - The original goal/objective
+ *   - What has already been accomplished (verified items)
+ *   - The most recent relevant observations
+ *   - Constraints that must be respected
+ *   - Open questions that need resolution
+ */
+
+/**
+ * @typedef {Object} RecoveryContext
+ * @property {string} goal - The original goal
+ * @property {Object[]} accomplished - Verified/accomplished items
+ * @property {Object[]} recentObservations - Most recent relevant observations
+ * @property {Object[]} constraints - Active constraints
+ * @property {Object[]} openQuestions - Questions needing resolution
+ * @property {string} driftReason - Why recovery was needed
+ * @property {number} timestamp - When recovery context was built
+ */
+
+/**
+ * @typedef {Object} DriftReport
+ * @property {boolean} drifted - Whether drift was detected
+ * @property {string} reason - Description of the drift
+ * @property {number} confidence - 0-1 confidence of drift detection
+ */
+
+/**
+ * Simple keyword check: does the content relate to the goal?
+ * @param {string} content
+ * @param {string} goal
+ * @returns {boolean}
+ */
+function relatesToGoal(content, goal) {
+  if (!content || !goal) return false;
+  if (content === goal) return true;
+  const contentLower = String(content).toLowerCase();
+  const goalWords = String(goal).toLowerCase().split(/\s+/).filter((w) => w.length > 2);
+  if (goalWords.length === 0) return true;
+  const matches = goalWords.filter((w) => contentLower.includes(w));
+  return matches.length >= Math.ceil(goalWords.length / 2);
+}
+
+/**
+ * Change 78 — reconstructMinimumCorrectiveContext
+ *
+ * Builds a minimal context from available data when agent has drifted.
+ *
+ * @param {Object} params
+ * @param {string} params.goal - The original goal/objective
+ * @param {Object[]} [params.accomplished=[]] - Already completed/verified items
+ * @param {Object[]} [params.observations=[]] - Recent observations
+ * @param {Object[]} [params.constraints=[]] - Active constraints
+ * @param {Object[]} [params.openQuestions=[]] - Unresolved questions
+ * @param {Object[]} [params.recentActions=[]] - Recent actions taken
+ * @param {string} params.driftReason - Why recovery is needed
+ * @param {number} [params.maxObservations=5] - Max observations to include
+ * @param {number} [params.maxAccomplished=10] - Max accomplished items
+ * @returns {RecoveryContext}
+ */
+export function reconstructMinimumCorrectiveContext({
+  goal,
+  accomplished = [],
+  observations = [],
+  constraints = [],
+  openQuestions = [],
+  recentActions = [],
+  driftReason,
+  maxObservations = 5,
+  maxAccomplished = 10,
+}) {
+  if (!goal || typeof goal !== "string") {
+    throw new TypeError("goal must be a non-empty string");
+  }
+  if (!driftReason || typeof driftReason !== "string") {
+    throw new TypeError("driftReason must be a non-empty string");
+  }
+
+  // Accomplished: verified items, most recent first
+  const sortedAccomplished = [...accomplished]
+    .sort((a, b) => (b.timestamp || 0) - (a.timestamp || 0))
+    .slice(0, maxAccomplished);
+
+  // Observations: filter for goal relevance, most recent first
+  const relevantObservations = observations
+    .filter((obs) => relatesToGoal(obs.content || "", goal))
+    .sort((a, b) => (b.timestamp || 0) - (a.timestamp || 0))
+    .slice(0, maxObservations);
+
+  // If not enough goal-relevant observations, include recent actions as context
+  if (relevantObservations.length < 2 && recentActions.length > 0) {
+    const actionContext = recentActions
+      .sort((a, b) => (b.timestamp || 0) - (a.timestamp || 0))
+      .slice(0, Math.max(1, maxObservations - relevantObservations.length));
+    // Blend: alternate between observations and actions
+    const blended = [];
+    const maxLen = Math.max(relevantObservations.length, actionContext.length);
+    for (let i = 0; i < maxLen; i++) {
+      if (relevantObservations[i]) blended.push(relevantObservations[i]);
+      if (actionContext[i]) blended.push(actionContext[i]);
+    }
+    return buildRecovery({
+      goal,
+      accomplished: sortedAccomplished,
+      observations: blended.slice(0, maxObservations),
+      constraints,
+      openQuestions,
+      driftReason,
+    });
+  }
+
+  return buildRecovery({
+    goal,
+    accomplished: sortedAccomplished,
+    observations: relevantObservations,
+    constraints,
+    openQuestions,
+    driftReason,
+  });
+}
+
+/**
+ * @param {Object} parts
+ * @returns {RecoveryContext}
+ */
+function buildRecovery({ goal, accomplished, observations, constraints, openQuestions, driftReason }) {
+  return {
+    goal,
+    accomplished: accomplished || [],
+    recentObservations: observations || [],
+    constraints: constraints || [],
+    openQuestions: openQuestions || [],
+    driftReason,
+    timestamp: Date.now(),
+  };
+}
+
+/**
+ * Quick check: does the agent action represent a drift from the goal?
+ *
+ * @param {Object} agentAction - The action taken by the agent
+ * @param {string} goal - The original goal
+ * @returns {DriftReport}
+ */
+export function detectActionDrift(agentAction, goal) {
+  if (!agentAction || typeof agentAction !== "object") {
+    return { drifted: false, reason: "No action provided", confidence: 0 };
+  }
+  if (!goal || typeof goal !== "string") {
+    return { drifted: false, reason: "No goal provided", confidence: 0 };
+  }
+
+  const actionContent = String(agentAction.content || agentAction.description || "").toLowerCase();
+  const actionType = String(agentAction.type || "").toLowerCase();
+
+  // Direct match: action type or content explicitly references goal
+  const directMatch = actionContent.includes(goal.toLowerCase()) ||
+                      goal.toLowerCase().includes(actionContent) ||
+                      actionContent === goal.toLowerCase();
+
+  if (directMatch) {
+    return { drifted: false, reason: "Action directly related to goal", confidence: 0.95 };
+  }
+
+  // Check for verb/topic overlap
+  const goalWords = goal.toLowerCase().split(/\s+/).filter((w) => w.length > 2);
+  const contentWords = actionContent.split(/\s+/).filter((w) => w.length > 2);
+  const overlap = goalWords.filter((w) => contentWords.includes(w)).length;
+  const overlapRatio = goalWords.length > 0 ? overlap / goalWords.length : 0;
+
+  if (overlapRatio >= 0.3) {
+    return { drifted: false, reason: "Action has topic overlap with goal", confidence: 0.7 };
+  }
+
+  // Known drift indicators
+  const driftIndicators = [
+    "exploring", "wandering", "asking clarification", "need more info",
+    "unclear", "confused", "redundant", "waiting", "idle",
+  ];
+  const isDrift = driftIndicators.some((ind) => actionContent.includes(ind));
+
+  if (isDrift) {
+    return {
+      drifted: true,
+      reason: `Action contains drift indicator: "${actionContent.substring(0, 60)}"`,
+      confidence: 0.75,
+      signals: [actionContent],
+    };
+  }
+
+  // Low overlap, no drift indicators = likely drift but low confidence
+  if (overlapRatio < 0.1 && actionContent.length > 0) {
+    return {
+      drifted: true,
+      reason: `Low topic overlap (${Math.round(overlapRatio * 100)}%) between action and goal`,
+      confidence: 0.5,
+      signals: [`low_overlap:${Math.round(overlapRatio * 100)}%`],
+    };
+  }
+
+  return { drifted: false, reason: "Action appears goal-aligned", confidence: 0.8 };
+}

package/src/context/context-retrieval-integration.js

@@ -0,0 +1,60 @@
+import { retrieveContext } from "./context-retrieval.js";
+import { retrieveActiveContext, isContextSufficient } from "./active-context-boundary.js";
+import { buildContextQuery, matchesQuery, scoreRelevance, retrieveRelevantContext, CONTEXT_PURPOSE } from "./context-query-contract.js";
+import { LIFECYCLE_STATES } from "./context-lifecycle.js";
+
+/**
+ * High-level retrieval that integrates ContextManager with query contract and active boundary.
+ * @param {Object} manager - ContextManager instance (must have registry.list())
+ * @param {Object} query - Output from buildContextQuery() or compatible object
+ * @param {Object} options
+ * @param {number} [options.maxResults=50]
+ * @param {boolean} [options.includeHistory=false] - include INVALIDATED/ARCHIVED
+ * @returns {{relevantItems: ManagedItem[], sufficiencyCheck: Object, metadata: Object}}
+ */
+export function integrateRetrieval(manager, query, options = {}) {
+  const { maxResults = 50, includeHistory = false } = options;
+  const startTime = Date.now();
+
+  if (!manager || typeof manager.registry?.list !== "function") {
+    throw new TypeError("integrateRetrieval requires a manager with registry.list()");
+  }
+
+  const allItems = manager.registry.list();
+
+  let relevantItems = retrieveRelevantContext(allItems, query);
+
+  if (!includeHistory) {
+    relevantItems = retrieveActiveContext(relevantItems, query.purpose);
+  }
+
+  if (maxResults > 0 && relevantItems.length > maxResults) {
+    relevantItems = relevantItems.slice(0, maxResults);
+  }
+
+  const sufficiencyCheck = isContextSufficient(relevantItems, query.purpose);
+
+  return {
+    relevantItems,
+    sufficiencyCheck,
+    metadata: {
+      totalItems: allItems.length,
+      retrievedCount: relevantItems.length,
+      purpose: query.purpose,
+      elapsedMs: Date.now() - startTime,
+    },
+  };
+}
+
+/**
+ * Convenience: build query and retrieve in one call.
+ * @param {Object} manager - ContextManager instance
+ * @param {Object} params - buildContextQuery parameters
+ * @param {Object} options - integrateRetrieval options
+ */
+export function retrieveForContext(manager, params, options = {}) {
+  const query = buildContextQuery(params);
+  return integrateRetrieval(manager, query, options);
+}
+
+export { CONTEXT_PURPOSE, buildContextQuery, matchesQuery, scoreRelevance, retrieveRelevantContext, retrieveActiveContext, isContextSufficient };

package/src/context/context-retrieval.js

@@ -0,0 +1,93 @@
+/**
+ * Context Retrieval — retrieveContext(query, constraints).
+ *
+ * Change 69: Retrieves context items from a ContextManager/registry
+ * based on requirement relevance. Uses ranking from context-ranking.js
+ * and respects constraint filters (layer, lifecycle, admission).
+ *
+ * Invariant: Returns results ordered by relevance score (descending).
+ * Items that don't satisfy mandatory constraints are excluded.
+ */
+
+import { rankContextItems } from "./context-ranking.js";
+
+/**
+ * @typedef {Object} RetrievalConstraints
+ * @property {string[]} [layers] - Filter by memory layers (N0..N3, ARCHIVE).
+ * @property {string[]} [lifecycle] - Filter by lifecycle states.
+ * @property {string[]} [admission] - Filter by admission class.
+ * @property {number} [maxResults] - Max items to return.
+ * @property {number} [minScore] - Minimum relevance score threshold.
+ * @property {string[]} [requiredTerms] - Terms that must appear.
+ * @property {string[]} [excludedIds] - Item IDs to exclude.
+ */
+
+/**
+ * @typedef {Object} RetrievalResult
+ * @property {Array} items - Ranked context items.
+ * @property {number} total - Total items before limiting.
+ * @property {number} returned - Number of items returned.
+ * @property {number} elapsedMs - Query execution time.
+ */
+
+/**
+ * Retrieves and ranks context items based on query relevance and constraints.
+ *
+ * @param {string} query - Search query / requirement text.
+ * @param {RetrievalConstraints} [constraints={}] - Filter and limit options.
+ * @returns {RetrievalResult}
+ */
+export function retrieveContext(query, constraints = {}) {
+  const startTime = Date.now();
+  const {
+    layers,
+    lifecycle,
+    admission,
+    maxResults = 50,
+    minScore = 0,
+    requiredTerms = [],
+    excludedIds = [],
+  } = constraints;
+
+  // Admission class filter (MANDATORY/CONDITIONAL/OPTIONAL)
+  const admissionFilter = (item) => {
+    if (!admission || !admission.length) return true;
+    const itemAdmission = item.admission || item.admissionClass || "OPTIONAL";
+    return admission.includes(itemAdmission);
+  };
+
+  // Retrieve from ContextManager if provided, or use registry directly.
+  // Note: `manager` is used for API compatibility (not a standard property).
+  const registry = constraints.registry || constraints.manager;
+  let items = [];
+
+  if (registry) {
+    const allItems = registry.list ? registry.list() : Object.values(registry);
+    items = allItems.filter((item) => {
+      if (layers && !layers.includes(item.memoryLayer)) return false;
+      if (lifecycle && !lifecycle.includes(item.lifecycle)) return false;
+      if (excludedIds.includes(item.id)) return false;
+      if (!admissionFilter(item)) return false;
+      return true;
+    });
+  }
+
+  // Rank by relevance to query
+  const ranked = rankContextItems(items, query, { requiredTerms });
+
+  // Apply min score filter
+  const filtered = ranked.filter((item) => {
+    const score = item.relevanceScore ?? 0;
+    return score >= minScore;
+  });
+
+  const total = filtered.length;
+  const result = filtered.slice(0, maxResults);
+
+  return {
+    items: result,
+    total,
+    returned: result.length,
+    elapsedMs: Date.now() - startTime,
+  };
+}