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

package/src/context/context-budget-manager.js

@@ -0,0 +1,232 @@
+/**
+ * Context Budget Manager — N0-N3/Archive Budget Tracking & Enforcement.
+ *
+ * Change 72: Tracks token budgets per memory layer, enforces limits,
+ * reports violations, and suggests eviction priorities.
+ *
+ * Budget model:
+ *   - Each layer (N0, N1, N2, N3, ARCHIVE) has a max token budget.
+ *   - Items are tracked with their estimated token cost.
+ *   - Budget violations are reported with remediation suggestions.
+ *   - N0 is always protected (minimum guaranteed budget).
+ *
+ * Invariant: Total budget across layers >= reserved + flex from assembly.
+ */
+
+/** Default tier budgets in tokens (approximate). */
+const DEFAULT_BUDGETS = Object.freeze({
+  N0: 200,      // Identity/goal — tiny but mandatory
+  N1: 800,      // Domain/project context
+  N2: 500,      // Current task state/evidence
+  N3: 1500,     // Session/capsule retrieval layer
+  ARCHIVE: 4000, // Historical/compressed
+});
+
+/** Minimum guaranteed budgets (cannot be reduced). */
+const MINIMUM_BUDGETS = Object.freeze({
+  N0: 100,
+  N1: 100,
+  N2: 100,
+  N3: 200,
+  ARCHIVE: 500,
+});
+
+const LAYER_ORDER = ["N0", "N1", "N2", "N3", "ARCHIVE"];
+
+/**
+ * ContextBudgetManager tracks and enforces token budgets per memory layer.
+ */
+export class ContextBudgetManager {
+  /**
+   * @param {Object} [options]
+   * @param {Object} [options.budgets] - Custom max budgets per layer.
+   * @param {Object} [options.minimums] - Custom minimum budgets per layer.
+   */
+  constructor(options = {}) {
+    this._budgets = { ...DEFAULT_BUDGETS, ...(options.budgets || {}) };
+    this._minimums = { ...MINIMUM_BUDGETS, ...(options.minimums || {}) };
+    /** @type {Map<string, {tokens: number, itemId: string, admission: string}>} */
+    this._items = new Map();
+    /** @type {Array<{layer: string, action: string, detail: string, timestamp: number}>} */
+    this._auditLog = [];
+  }
+
+  // ---------------------------------------------------------------
+  // Budget configuration
+  // ---------------------------------------------------------------
+
+  /** Get max budget for a layer. */
+  getBudget(layer) {
+    return this._budgets[layer] ?? 0;
+  }
+
+  /** Get minimum guaranteed budget for a layer. */
+  getMinimum(layer) {
+    return this._minimums[layer] ?? 0;
+  }
+
+  /** Get all budgets. */
+  getAllBudgets() {
+    return { ...this._budgets };
+  }
+
+  /** Set budget for a layer. */
+  setBudget(layer, tokens) {
+    if (tokens < this.getMinimum(layer)) {
+      throw new Error(
+        `Budget for ${layer} (${tokens}) below minimum (${this.getMinimum(layer)})`
+      );
+    }
+    this._budgets[layer] = tokens;
+    this._log(layer, "budget_updated", `Budget set to ${tokens}`);
+  }
+
+  // ---------------------------------------------------------------
+  // Item tracking
+  // ---------------------------------------------------------------
+
+  /** Register an item with its token cost in a layer. */
+  addItem(layer, itemId, tokens, admission = "OPTIONAL") {
+    if (!LAYER_ORDER.includes(layer)) {
+      throw new Error(`Unknown layer: ${layer}`);
+    }
+    this._items.set(itemId, { layer, tokens, itemId, admission });
+    this._log(layer, "item_added", `${itemId}: ${tokens} tok (${admission})`);
+    return this.getLayerUsage(layer);
+  }
+
+  /** Remove an item from tracking. */
+  removeItem(itemId) {
+    const item = this._items.get(itemId);
+    if (item) {
+      this._items.delete(itemId);
+      this._log(item.layer, "item_removed", itemId);
+    }
+    return item;
+  }
+
+  /** Get all tracked items for a layer. */
+  getItems(layer) {
+    return Array.from(this._items.values()).filter((i) => i.layer === layer);
+  }
+
+  /** Get all tracked items. */
+  getAllItems() {
+    return Array.from(this._items.values());
+  }
+
+  // ---------------------------------------------------------------
+  // Usage & enforcement
+  // ---------------------------------------------------------------
+
+  /** Get current token usage for a layer. */
+  getLayerUsage(layer) {
+    let used = 0;
+    for (const item of this._items.values()) {
+      if (item.layer === layer) used += item.tokens;
+    }
+    const budget = this.getBudget(layer);
+    return {
+      layer,
+      used,
+      budget,
+      remaining: Math.max(0, budget - used),
+      utilization: budget > 0 ? used / budget : 0,
+      overBudget: used > budget,
+    };
+  }
+
+  /** Get usage for all layers. */
+  getAllUsage() {
+    return LAYER_ORDER.map((layer) => this.getLayerUsage(layer));
+  }
+
+  /** Get total tokens across all layers. */
+  getTotalUsage() {
+    let total = 0;
+    for (const item of this._items.values()) total += item.tokens;
+    return total;
+  }
+
+  /** Check for budget violations and return report. */
+  checkViolations() {
+    const violations = [];
+    for (const layer of LAYER_ORDER) {
+      const usage = this.getLayerUsage(layer);
+      if (usage.overBudget) {
+        const excess = usage.used - usage.budget;
+        const minimumProtected = usage.used > this.getMinimum(layer)
+          ? this.getMinimum(layer)
+          : usage.used;
+        violations.push({
+          layer,
+          severity: this.getMinimum(layer) > 0 && usage.used <= this.getMinimum(layer)
+            ? "SOFT"
+            : "HARD",
+          overBy: excess,
+          used: usage.used,
+          budget: usage.budget,
+          minimum: this.getMinimum(layer),
+          suggestion: this._suggestEviction(layer, excess),
+        });
+      }
+    }
+    return {
+      violations,
+      clean: violations.length === 0,
+      totalOverBudget: violations.reduce((sum, v) => sum + v.overBy, 0),
+    };
+  }
+
+  /** Suggest items to evict from a layer to meet budget. */
+  _suggestEviction(layer, excessTokens) {
+    const items = this.getItems(layer).sort((a, b) => a.tokens - b.tokens);
+    const suggestions = [];
+    let freed = 0;
+    for (const item of items) {
+      if (freed >= excessTokens) break;
+      suggestions.push({ itemId: item.itemId, tokens: item.tokens, admission: item.admission });
+      freed += item.tokens;
+    }
+    return suggestions;
+  }
+
+  // ---------------------------------------------------------------
+  // Audit & reporting
+  // ---------------------------------------------------------------
+
+  /** Get audit log entries. */
+  getAuditLog() {
+    return [...this._auditLog];
+  }
+
+  /** Generate a budget report summary. */
+  report() {
+    const allUsage = this.getAllUsage();
+    const check = this.checkViolations();
+    return {
+      layer: allUsage,
+      layers: allUsage,
+      totalUsed: this.getTotalUsage(),
+      totalBudget: Object.values(this._budgets).reduce((a, b) => a + b, 0),
+      violations: check.violations,
+      violationReport: check,
+      timestamp: Date.now(),
+    };
+  }
+
+  _log(layer, action, detail) {
+    this._auditLog.push({
+      layer,
+      action,
+      detail,
+      timestamp: Date.now(),
+    });
+    // Keep audit log manageable
+    if (this._auditLog.length > 10000) {
+      this._auditLog = this._auditLog.slice(-5000);
+    }
+  }
+}
+
+export { DEFAULT_BUDGETS, MINIMUM_BUDGETS, LAYER_ORDER };

package/src/context/context-builder.js

@@ -0,0 +1,49 @@
+/**
+ * Context Builder.
+ * Assembles a context artifact from various sources with freshness, promotion, and budget rules.
+ */
+
+import { isStale, updateLastAccess } from "./context-freshness.js";
+
+export function build({ context = [], memory = [], decision = [], query = {}, options = {} }) {
+  const { maxItems = 10, ttl = 60000 } = options;
+  const now = Date.now();
+
+  // Combine and deduplicate
+  const allItems = [...context, ...memory, ...decision];
+  const uniqueItems = Array.from(new Map(allItems.map(item => [item.id, item])).values());
+
+  // Apply freshness / staleness / ttl
+  const freshItems = uniqueItems
+    .filter(item => !isStale(item, ttl, now))
+    .map(item => updateLastAccess(item, now));
+
+  // Promotion rules (e.g., items mentioned in query get promoted)
+  const promotedItems = freshItems.map(item => ({
+    ...item,
+    isPromoted: query.keywords?.some(kw => item.content?.includes(kw)) || false,
+  }));
+
+  // Budget enforcement
+  // Sort by promoted first, then lastAccess
+  const sortedItems = promotedItems.sort((a, b) => {
+    if (a.isPromoted !== b.isPromoted) return a.isPromoted ? -1 : 1;
+    return b.lastAccess - a.lastAccess;
+  });
+
+  const finalItems = sortedItems.slice(0, maxItems);
+
+  return {
+    structure: "artifact",
+    items: finalItems,
+    provenance: {
+      source: "context-builder",
+      timestamp: now,
+      method: "build",
+    },
+    metadata: {
+      totalInput: allItems.length,
+      finalCount: finalItems.length,
+    }
+  };
+}

package/src/context/context-cache.js

@@ -0,0 +1,55 @@
+export function createContextCache({ ttlMs = 60_000, maxEntries = 100 } = {}) {
+  const store = new Map(); // key -> { value, expiresAt }
+
+  function get(key) {
+    const entry = store.get(key);
+    if (!entry) return undefined;
+    if (Date.now() > entry.expiresAt) {
+      store.delete(key);
+      return undefined;
+    }
+    return entry.value;
+  }
+
+  function set(key, value, customTtlMs) {
+    const ttl = customTtlMs ?? ttlMs;
+    if (store.size >= maxEntries && !store.has(key)) {
+      // Evict oldest insertion (Map preserves insertion order).
+      const oldestKey = store.keys().next().value;
+      if (oldestKey !== undefined) store.delete(oldestKey);
+    }
+    store.set(key, { value, expiresAt: Date.now() + ttl });
+  }
+
+  function has(key) {
+    return get(key) !== undefined;
+  }
+
+  function deleteKey(key) {
+    return store.delete(key);
+  }
+
+  function clear() {
+    store.clear();
+  }
+
+  function size() {
+    // Lazy prune expired entries before counting.
+    const now = Date.now();
+    for (const [k, v] of store) {
+      if (now > v.expiresAt) store.delete(k);
+    }
+    return store.size;
+  }
+
+  function keys() {
+    const now = Date.now();
+    const out = [];
+    for (const [k, v] of store) {
+      if (now <= v.expiresAt) out.push(k);
+    }
+    return out;
+  }
+
+  return { get, set, has, delete: deleteKey, clear, size, keys };
+}

package/src/context/context-capture.js

@@ -0,0 +1,243 @@
+/**
+ * Context Capture — mechanisms for capturing context from diverse sources.
+ *
+ * Captures: tool calls, agent messages, file modifications, git changes,
+ * requirement changes, and verification results.
+ *
+ * Each capture produces a raw record with: id, type, content, source,
+ * timestamp, scope, metadata.
+ */
+
+import crypto from "node:crypto";
+import { classifyContextItem } from "./context-classification.js";
+import { scopeContextItem } from "./context-scope.js";
+
+let _idCounter = 0;
+
+function genId(prefix) {
+  _idCounter += 1;
+  return `${prefix}_${Date.now().toString(36)}${_idCounter.toString(36).padStart(4, "0")}`;
+}
+
+function now() {
+  return Date.now();
+}
+
+/**
+ * Attach classification and scope metadata to a capture record.
+ * @param {Object} record
+ */
+function attachContextMeta(record) {
+  if (!record) return;
+  record.classification = classifyContextItem(record);
+  record.scopeAssignment = scopeContextItem(record);
+}
+
+function buildRecord(type, content, source, scope, metadata = {}) {
+  return {
+    id: genId(`${type}_ctx`),
+    type,
+    content,
+    source,
+    timestamp: now(),
+    scope: scope || "session",
+    metadata,
+  };
+}
+
+// -- 1. Tool calls ---------------------------------------------------------
+
+/**
+ * Capture a tool call invocation.
+ * @param {string} toolName - Name of the tool called
+ * @param {Object} params - Arguments passed to the tool
+ * @param {Object} [opts] - Optional scope/metadata
+ * @returns {Object} Capture record
+ */
+export function captureToolCall(toolName, params, opts = {}) {
+  const record = buildRecord(
+    "tool_call",
+    { toolName, params },
+    "tool",
+    opts.scope || "session",
+    { toolName, paramsSummary: JSON.stringify(params).slice(0, 500), ...opts.metadata },
+  );
+  attachContextMeta(record);
+  return record;
+}
+
+/**
+ * Capture a tool call result.
+ * @param {string} toolName
+ * @param {*} result - The result returned
+ * @param {Object} [opts]
+ * @returns {Object} Capture record
+ */
+export function captureToolResult(toolName, result, opts = {}) {
+  const record = buildRecord(
+    "tool_result",
+    { toolName, result },
+    "tool",
+    opts.scope || "session",
+    { toolName, resultSize: typeof result === "string" ? result.length : 0, ...opts.metadata },
+  );
+  attachContextMeta(record);
+  return record;
+}
+
+// -- 2. Agent messages -----------------------------------------------------
+
+/**
+ * Capture an agent message (user or assistant).
+ * @param {"user"|"assistant"} role
+ * @param {string} content - Message text
+ * @param {Object} [opts]
+ * @returns {Object} Capture record
+ */
+export function captureAgentMessage(role, content, opts = {}) {
+  if (!["user", "assistant"].includes(role)) {
+    throw new TypeError(`Invalid role: ${role}. Must be "user" or "assistant"`);
+  }
+  const record = buildRecord(
+    "agent_message",
+    { role, content },
+    "agent",
+    opts.scope || "session",
+    { role, contentLength: content.length, ...opts.metadata },
+  );
+  attachContextMeta(record);
+  return record;
+}
+
+/**
+ * Capture a system prompt fragment.
+ * @param {string} content
+ * @param {Object} [opts]
+ * @returns {Object} Capture record
+ */
+export function captureSystemMessage(content, opts = {}) {
+  const record = buildRecord(
+    "agent_message",
+    { role: "system", content },
+    "agent",
+    opts.scope || "session",
+    { role: "system", contentLength: content.length, ...opts.metadata },
+  );
+  attachContextMeta(record);
+  return record;
+}
+
+// -- 3. File modifications -------------------------------------------------
+
+/**
+ * Capture a file modification event.
+ * @param {string} filePath - Path to the file
+ * @param {"create"|"modify"|"delete"} action
+ * @param {Object} [details] - Optional diff/summary
+ * @param {Object} [opts]
+ * @returns {Object} Capture record
+ */
+export function captureFileModification(filePath, action, details = {}, opts = {}) {
+  if (!["create", "modify", "delete"].includes(action)) {
+    throw new TypeError(`Invalid action: ${action}. Must be create/modify/delete`);
+  }
+  const record = buildRecord(
+    "file_modification",
+    { filePath, action, details },
+    "filesystem",
+    opts.scope || "session",
+    { filePath, action, ...opts.metadata },
+  );
+  attachContextMeta(record);
+  return record;
+}
+
+// -- 4. Git changes --------------------------------------------------------
+
+/**
+ * Capture a git change (commit, branch, merge, etc.).
+ * @param {"commit"|"branch"|"merge"|"rebase"|"reset"} action
+ * @param {Object} details - { hash, message, branch, filesChanged, ... }
+ * @param {Object} [opts]
+ * @returns {Object} Capture record
+ */
+export function captureGitChange(action, details, opts = {}) {
+  if (!["commit", "branch", "merge", "rebase", "reset"].includes(action)) {
+    throw new TypeError(`Invalid git action: ${action}`);
+  }
+  return buildRecord(
+    "git_change",
+    { action, details },
+    "git",
+    opts.scope || "session",
+    { action, commitHash: details.hash || null, ...opts.metadata },
+  );
+}
+
+// -- 5. Requirement changes ------------------------------------------------
+
+/**
+ * Capture a requirement change (created, updated, closed).
+ * @param {"created"|"updated"|"closed"|"reopened"} action
+ * @param {Object} requirement - { id, title, description, ... }
+ * @param {Object} [opts]
+ * @returns {Object} Capture record
+ */
+export function captureRequirementChange(action, requirement, opts = {}) {
+  if (!["created", "updated", "closed", "reopened"].includes(action)) {
+    throw new TypeError(`Invalid requirement action: ${action}`);
+  }
+  const record = buildRecord(
+    "requirement_change",
+    { action, requirement },
+    "requirement",
+    opts.scope || "session",
+    {
+      action,
+      requirementId: requirement.id || null,
+      requirementTitle: requirement.title || null,
+      ...opts.metadata,
+    },
+  );
+  attachContextMeta(record);
+  return record;
+}
+
+// -- 6. Verification results -----------------------------------------------
+
+/**
+ * Capture a verification result.
+ * @param {"passed"|"failed"|"skipped"|"blocked"} status
+ * @param {Object} details - { testName, assertion, output, ... }
+ * @param {Object} [opts]
+ * @returns {Object} Capture record
+ */
+export function captureVerificationResult(status, details, opts = {}) {
+  if (!["passed", "failed", "skipped", "blocked"].includes(status)) {
+    throw new TypeError(`Invalid verification status: ${status}`);
+  }
+  const record = buildRecord(
+    "verification_result",
+    { status, details },
+    "verification",
+    opts.scope || "session",
+    { status, testName: details.testName || null, ...opts.metadata },
+  );
+  attachContextMeta(record);
+  return record;
+}
+
+// -- Batch -----------------------------------------------------------------
+
+/**
+ * Capture multiple records at once.
+ * @param {Object[]} records - Array of partial records to capture
+ * @returns {Object[]}
+ */
+export function captureBatch(records) {
+  return records.map((r) => {
+    const record = buildRecord(r.type, r.content, r.source, r.scope, r.metadata || {});
+    attachContextMeta(record);
+    return record;
+  });
+}