ocuclaw 1.2.4 → 1.3.0

package/dist/domain/activity-status-arbiter.js

@@ -0,0 +1,109 @@
+// Pure ladder-ranking logic for the activity-status arbiter (Plan 2 core).
+//
+// LEAF MODULE: it may import small shared leaf helpers, but nothing it imports
+// may import it back. The CJS build (scripts/build.mjs#emitCjsFile) appends
+// `module.exports = {...}` at EOF and converts imports to eager in-place
+// requires, so a bidirectional import would resolve to `{}` mid-cycle and
+// crash at call time. Keep this module a strict leaf.
+
+const RANK_INTERVENTION = "intervention";
+const RANK_GENERATED_SUMMARY = "generated_summary";
+const RANK_TOOL = "tool";
+const RANK_GENERIC_THINKING = "generic_thinking";
+const RANK_QUIET = "quiet";
+
+// Ladder order, highest first. Matches spec §5.
+const RANKS = [
+  RANK_INTERVENTION,
+  RANK_GENERATED_SUMMARY,
+  RANK_TOOL,
+  RANK_GENERIC_THINKING,
+  RANK_QUIET,
+];
+
+function isInterventionSignal(s) {
+  return (
+    s.isError === true ||
+    s.phaseIsError === true ||
+    s.hasRateLimitInfo === true ||
+    s.failoverPending === true
+  );
+}
+
+// Classify an already-resolved activity into its ladder rank.
+// The branch order IS the ladder order. `intervention` and `tool` are
+// rankable regardless of includeThinking; the two thinking-derived ranks
+// (`generated_summary` and `generic_thinking`) are both gated by
+// `includeThinking === true` (spec §7.4: `includeThinking = false` →
+// no `generated_summary` override and no `generic_thinking` fallback).
+//
+// NOTE: the guard here enforces spec §7.4 directly — callers may pass
+// any value for `thinkingSummarySource` regardless of `includeThinking`
+// and will always get the correct answer.
+function classifyRank(signals) {
+  const s = signals || {};
+  if (isInterventionSignal(s)) return RANK_INTERVENTION;
+  if (
+    s.isThinking === true &&
+    s.includeThinking === true &&
+    evaluateSummaryEligibility(s.thinkingSummarySource, s.label)
+  ) {
+    return RANK_GENERATED_SUMMARY;
+  }
+  if (s.hasTool === true) return RANK_TOOL;
+  if (s.isThinking === true && s.includeThinking === true) {
+    return RANK_GENERIC_THINKING;
+  }
+  return RANK_QUIET;
+}
+
+// Exact generic stems that must never outrank a tool, even from a
+// summary/bold source. Compared against the normalized whole label.
+const GENERIC_SUMMARY_DENYLIST = new Set([
+  "thinking",
+  "working",
+  "planning",
+  "analyzing",
+  "considering",
+  "checking",
+  "reasoning",
+  "looking into it",
+  "let me check",
+  "let me think",
+  "hmm",
+]);
+
+function normalizeSummaryLabel(label) {
+  if (typeof label !== "string") return "";
+  return label
+    .replace(/\*\*/g, "")
+    .replace(/[.…]+$/g, "") // trailing dots / ellipsis
+    .trim() // leading/trailing whitespace
+    .toLowerCase();
+}
+
+// A summary may outrank a tool only if it is an authored, concise, specific
+// signal: source ∈ {summary, bold}, non-empty, not a generic stem, and not a
+// bare verb with no object.
+function evaluateSummaryEligibility(thinkingSummarySource, label) {
+  if (thinkingSummarySource !== "summary" && thinkingSummarySource !== "bold") {
+    return false;
+  }
+  const normalized = normalizeSummaryLabel(label);
+  if (!normalized) return false;
+  if (GENERIC_SUMMARY_DENYLIST.has(normalized)) return false;
+  // bare verb / single token = no object
+  if (!/\s/.test(normalized)) return false;
+  return true;
+}
+
+export {
+  RANKS,
+  RANK_INTERVENTION,
+  RANK_GENERATED_SUMMARY,
+  RANK_TOOL,
+  RANK_GENERIC_THINKING,
+  RANK_QUIET,
+  evaluateSummaryEligibility,
+  classifyRank,
+};