@miller-tech/uap 1.100.0 → 1.101.1

package/dist/delivery/task-orchestrator.js

@@ -0,0 +1,185 @@
+/**
+ * Blackboard Task Orchestrator (P1) + Minimal Context Assembler (P2)
+ *
+ * The mechanism that lets a small-context model multi-step through a large
+ * build: instead of one convergence loop holding the WHOLE design in context,
+ * the orchestrator executes a task DAG where each leaf task runs in a FRESH,
+ * MINIMAL context assembled from externalized state — its own goal, its
+ * acceptance criteria, and ONLY the recorded outputs of its direct
+ * dependencies (not the full mission, not every prior summary).
+ *
+ * State lives on a "blackboard" (completed task outcomes), not in the prompt.
+ * A task that finishes writes a compact summary (P1) — and later its verified
+ * interface contract (P4) — back to the blackboard, so a dependent task loads
+ * a few hundred tokens of "what already exists" rather than re-reading source.
+ *
+ * This module is executor-agnostic: it takes a `runTask` callback that turns
+ * an assembled prompt into a pass/fail outcome (production wires the
+ * ConvergenceLoop; tests inject a deterministic stub). That keeps the graph
+ * logic unit-testable without a model.
+ */
+import { topoOrder } from './decompose.js';
+const DEFAULT_DEP_SUMMARY_CHARS = 240;
+/** A short mission line — orientation, not the full spec. */
+const MISSION_SNIPPET_CHARS = 300;
+const DEFAULT_CONTEXT_BUDGET_CHARS = 6000;
+const DEFAULT_MAX_TASKS = 40;
+/**
+ * P6 — enforce the context budget: if the assembled prompt exceeds `budget`,
+ * drop whole dependency lines from the END (furthest/least-recent deps) until
+ * it fits, appending a note about what was elided. Pure + unit-tested; the
+ * governor turns "minimal context" into a hard invariant.
+ */
+export function governContext(prompt, depLineCount, budget) {
+    if (prompt.length <= budget)
+        return { prompt, droppedDeps: 0 };
+    const lines = prompt.split('\n');
+    // dependency lines are the "- <id>: ..." entries under ALREADY BUILT.
+    let dropped = 0;
+    for (let i = lines.length - 1; i >= 0 && lines.join('\n').length > budget && dropped < depLineCount; i--) {
+        if (/^- [^:]+: /.test(lines[i])) {
+            lines.splice(i, 1);
+            dropped++;
+        }
+    }
+    let out = lines.join('\n');
+    if (dropped > 0)
+        out += `\n(context governor: elided ${dropped} lower-priority dependency summary(ies) to fit the ${budget}-char budget)`;
+    // Last resort: hard truncate if still over (e.g. a single huge goal).
+    if (out.length > budget)
+        out = out.slice(0, budget) + '\n…(truncated to context budget)…';
+    return { prompt: out, droppedDeps: dropped };
+}
+/**
+ * P2 — assemble one task's MINIMAL context: a short mission line, the task's
+ * own goal + criteria + declared files, and ONLY the summaries/contracts of
+ * its DIRECT dependencies (pulled from the blackboard). Pure and unit-tested;
+ * this is the function that keeps a small model's window optimal.
+ */
+export function assembleTaskContext(task, mission, blackboard, maxDepSummaryChars = DEFAULT_DEP_SUMMARY_CHARS, opts = {}) {
+    const sections = [];
+    // Orientation only — a snippet, never the whole mission.
+    sections.push(`OBJECTIVE (context, one line): ${mission.slice(0, MISSION_SNIPPET_CHARS)}`);
+    sections.push('');
+    sections.push(`YOUR TASK — ${task.title}:`);
+    sections.push(task.goal);
+    if (task.files && task.files.length > 0) {
+        sections.push('');
+        sections.push(`Files for THIS task: ${task.files.join(', ')} (edit only these).`);
+    }
+    if (task.criteria && task.criteria.length > 0) {
+        sections.push('');
+        sections.push('This task is done when:');
+        task.criteria.forEach((c, i) => sections.push(`  ${i + 1}. ${c}`));
+    }
+    // P3 — relevant persisted design decisions (objective/architecture): a
+    // small retrieval, not the full spec dump.
+    if (opts.designLines && opts.designLines.length > 0) {
+        sections.push('');
+        sections.push('DESIGN CONTEXT (established decisions — honor them):');
+        opts.designLines.slice(0, 6).forEach((d) => sections.push(`- ${d}`));
+    }
+    // ONLY direct dependencies' outputs — the crux of minimal context. A task
+    // that depends on 'store' loads store's contract/summary, not store's source
+    // and not the other 12 tasks. Dependents read the interface, not the tree.
+    const includedDeps = [];
+    const deps = (task.deps ?? []).filter((d) => blackboard.has(d));
+    if (deps.length > 0) {
+        sections.push('');
+        sections.push('ALREADY BUILT — build ON these, do not reimplement them:');
+        for (const depId of deps) {
+            const out = blackboard.get(depId);
+            includedDeps.push(depId);
+            const body = (out.contract ?? out.summary).slice(0, maxDepSummaryChars);
+            sections.push(`- ${depId}: ${body}`);
+        }
+    }
+    const raw = sections.join('\n');
+    const governed = governContext(raw, includedDeps.length, opts.budgetChars ?? DEFAULT_CONTEXT_BUDGET_CHARS);
+    return { taskId: task.id, prompt: governed.prompt, includedDeps };
+}
+/**
+ * P1 — execute the task DAG on a blackboard. Topologically ordered; a task
+ * runs only after every dependency has SUCCEEDED. A failed task blocks its
+ * dependents (their deps aren't all green) and they are reported as skipped/
+ * failed rather than run against incomplete state. Fail-soft on publish.
+ */
+export async function orchestrate(config) {
+    const maxTasks = config.maxTasks ?? DEFAULT_MAX_TASKS;
+    const budget = config.contextBudgetChars;
+    // Mutable queue so P5 re-planning can append discovered subtasks; re-sorted
+    // topologically each time the set grows.
+    let queue = topoOrder(config.tasks);
+    const known = new Set(queue.map((t) => t.id));
+    const blackboard = new Map();
+    const done = new Set();
+    const failed = new Set();
+    const outcomes = [];
+    let turns = 0;
+    for (let qi = 0; qi < queue.length; qi++) {
+        const task = queue[qi];
+        const deps = task.deps ?? [];
+        // Skip a task whose dependency failed — never build against a broken base.
+        const blockedBy = deps.filter((d) => failed.has(d) || !done.has(d));
+        if (blockedBy.length > 0) {
+            const outcome = {
+                taskId: task.id,
+                success: false,
+                summary: `skipped — unmet dependency: ${blockedBy.join(', ')}`,
+                turns: 0,
+            };
+            failed.add(task.id);
+            outcomes.push(outcome);
+            config.onTask?.(task, outcome);
+            continue;
+        }
+        let designLines = [];
+        if (config.retrieveDesign) {
+            try {
+                designLines = await config.retrieveDesign(task);
+            }
+            catch {
+                designLines = [];
+            }
+        }
+        const ctx = assembleTaskContext(task, config.mission, blackboard, config.maxDepSummaryChars, {
+            designLines,
+            budgetChars: budget,
+        });
+        const outcome = await config.runTask(ctx, task);
+        turns += outcome.turns;
+        outcomes.push(outcome);
+        if (outcome.success) {
+            done.add(task.id);
+            blackboard.set(task.id, outcome);
+            try {
+                await config.publish?.(outcome, task);
+            }
+            catch {
+                // publishing to durable memory is best-effort
+            }
+            // P5 — adaptive re-planning: fold discovered subtasks into the queue.
+            const fresh = (outcome.newTasks ?? []).filter((t) => !known.has(t.id));
+            if (fresh.length > 0 && queue.length + fresh.length <= maxTasks) {
+                for (const t of fresh)
+                    known.add(t.id);
+                // Re-topo-sort the not-yet-run remainder plus the new tasks so deps hold.
+                const remainder = queue.slice(qi + 1).concat(fresh);
+                const resorted = topoOrder(remainder);
+                queue = queue.slice(0, qi + 1).concat(resorted);
+            }
+        }
+        else {
+            failed.add(task.id);
+        }
+        config.onTask?.(task, outcome);
+    }
+    return {
+        success: failed.size === 0,
+        completed: [...done],
+        failed: [...failed],
+        turns,
+        outcomes,
+    };
+}
+//# sourceMappingURL=task-orchestrator.js.map

package/dist/delivery/task-orchestrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-orchestrator.js","sourceRoot":"","sources":["../../src/delivery/task-orchestrator.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miller-tech/uap",
-  "version": "1.100.0",
+  "version": "1.101.1",
   "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
   "type": "module",
   "main": "dist/index.js",

package/tools/agents/scripts/anthropic_proxy.py

@@ -205,6 +205,32 @@ PROXY_FORCED_HARD_RELEASE = int(os.environ.get("PROXY_FORCED_HARD_RELEASE", "30"
 PROXY_CONTEXT_RELEASE_THRESHOLD = float(
     os.environ.get("PROXY_CONTEXT_RELEASE_THRESHOLD", "0.90")
 )
+# ---------------------------------------------------------------------------
+# STUCK-BREAK guardrail: a small model can recognize it is looping ("I've been
+# stuck in a loop, let me break out") yet keep repeating the SAME failing tool
+# call -- meta-cognition without an exit. Two signals, both observed live on a
+# qwen3.6 session that looped ~18min fetching a rate-limited GitHub API:
+#   (a) repeated self-reported "stuck" assistant text, and
+#   (b) repeated tool calls hitting a known rate-limited API host.
+# When either streak crosses its threshold the proxy forces a TERMINAL turn:
+# tool_choice back to auto + a firm directive to stop retrying and either
+# proceed without the unreachable resource or ask the operator. Default on;
+# PROXY_STUCK_BREAK=off to disable.
+PROXY_STUCK_BREAK = os.environ.get("PROXY_STUCK_BREAK", "on").lower() not in {
+    "0", "false", "off", "no",
+}
+# Self-reported-stuck phrases (lowercased match). Deliberately narrow.
+_STUCK_PHRASE_RE = re.compile(
+    r"stuck in a loop|been stuck|break out of (?:this|the) loop|going in circles|"
+    r"repeating myself|same (?:thing|error) (?:again|repeatedly)",
+    re.IGNORECASE,
+)
+# Tool args reaching into a rate-limited REST API host (the wrong channel; the
+# hint steers to the browser tool / git clone, which are not rate-limited).
+_RATE_LIMITED_API_RE = re.compile(r"api\.github\.com", re.IGNORECASE)
+PROXY_STUCK_TEXT_THRESHOLD = int(os.environ.get("PROXY_STUCK_TEXT_THRESHOLD", "2"))
+PROXY_STUCK_API_THRESHOLD = int(os.environ.get("PROXY_STUCK_API_THRESHOLD", "3"))
+
 PROXY_TOOL_STATE_MACHINE = os.environ.get(
     "PROXY_TOOL_STATE_MACHINE", "on"
 ).lower() not in {
@@ -1128,6 +1154,9 @@ class SessionMonitor:
     recon_hard_fires: int = 0  # Fix E: monotonic count of recon hard-tier firings
     catastrophic_ctx_streak: int = 0  # Fix F: consecutive turns raw ctx >= finalize ratio
     unexpected_end_turn_count: int = 0  # end_turn without tool_use in active loop
+    self_stuck_streak: int = 0  # consecutive assistant texts self-reporting a loop
+    rate_limited_api_streak: int = 0  # consecutive tool calls hitting a rate-limited API host
+    stuck_break_fires: int = 0  # monotonic count of forced stuck-breaks
     tool_starvation_streak: int = 0  # Consecutive forced turns with no tool_calls produced
     malformed_tool_streak: int = 0  # consecutive malformed pseudo tool payloads
     invalid_tool_call_streak: int = 0  # consecutive invalid tool arg payloads
@@ -1363,6 +1392,40 @@ class SessionMonitor:
                     by_tool = self.tool_target_history.setdefault(name, {})
                     by_tool[target] = by_tool.get(target, 0) + 1
 
+    def note_assistant_text(self, text: str) -> None:
+        """Track the model self-reporting that it is stuck (STUCK-BREAK signal
+        (a)). A matching turn increments the streak; a non-matching turn resets
+        it, so only SUSTAINED self-reported looping trips the break."""
+        if not PROXY_STUCK_BREAK or not text:
+            self.self_stuck_streak = 0
+            return
+        if _STUCK_PHRASE_RE.search(text):
+            self.self_stuck_streak += 1
+        else:
+            self.self_stuck_streak = 0
+
+    def note_tool_arg_hosts(self, arg_blobs: list) -> None:
+        """Track repeated tool calls into a rate-limited API host (STUCK-BREAK
+        signal (b)). Reset when a turn uses none, so only a sustained wrong-
+        channel loop trips the hint."""
+        if not PROXY_STUCK_BREAK:
+            return
+        blob = " ".join(a for a in arg_blobs if isinstance(a, str))
+        if _RATE_LIMITED_API_RE.search(blob):
+            self.rate_limited_api_streak += 1
+        else:
+            self.rate_limited_api_streak = 0
+
+    def should_force_stuck_break(self) -> tuple[bool, str]:
+        """True + reason when a terminal break should be forced this turn."""
+        if not PROXY_STUCK_BREAK:
+            return False, ""
+        if self.self_stuck_streak >= PROXY_STUCK_TEXT_THRESHOLD:
+            return True, f"self-reported stuck x{self.self_stuck_streak}"
+        if self.rate_limited_api_streak >= PROXY_STUCK_API_THRESHOLD:
+            return True, f"rate-limited-API retries x{self.rate_limited_api_streak}"
+        return False, ""
+
     def has_duplicate_read_target(self, threshold: int = 2) -> tuple[bool, str]:
         """Check if any read-only tool has re-read the same target >= threshold times.
 
@@ -4067,6 +4130,36 @@ def _writes_are_gated(openai_body: dict) -> bool:
     return False
 
 
+def _maybe_inject_stuck_break(openai_body: dict, monitor: "SessionMonitor") -> None:
+    """Force a terminal turn when the model is looping self-awarely or hammering
+    a rate-limited API. Unlike the cycle-breaker (which narrows tools), this
+    STOPS tool coercion and tells the model to synthesize / ask / route around
+    the unreachable resource -- converting the model's own "I'm stuck" into an
+    actual exit. Fires at most escalating; monotonic counter for telemetry."""
+    should, reason = monitor.should_force_stuck_break()
+    if not should:
+        return
+    monitor.stuck_break_fires += 1
+    # Release the tool-choice coercion so a plain text turn is allowed.
+    if openai_body.get("tool_choice") == "required":
+        openai_body["tool_choice"] = "auto"
+    directive = (
+        "\n\nSTOP — you are repeating a failing action (" + reason + "). Do NOT "
+        "retry the same tool or fetch again. If a resource is unreachable (e.g. a "
+        "rate-limited GitHub REST API), switch channel: use the browser tool or "
+        "`git clone` (git protocol), NOT api.github.com. If it is still "
+        "unavailable, proceed WITHOUT it using what you already have, or ask the "
+        "operator the single blocking question in one sentence. Take a DIFFERENT "
+        "action now."
+    )
+    msgs = openai_body.get("messages") or []
+    if msgs and msgs[0].get("role") == "system":
+        msgs[0]["content"] = (msgs[0].get("content") or "") + directive
+    else:
+        msgs.insert(0, {"role": "system", "content": directive.strip()})
+    logger.warning("STUCK-BREAK: forced terminal turn (%s, fires=%d)", reason, monitor.stuck_break_fires)
+
+
 def _maybe_inject_recon_convergence(
     openai_body: dict,
     monitor: "SessionMonitor",
@@ -4846,6 +4939,8 @@ def build_openai_request(
     # pre-narrowing toolset so it can restore a dropped write tool.
     _maybe_inject_recon_convergence(openai_body, monitor, full_openai_tools)
 
+    _maybe_inject_stuck_break(openai_body, monitor)
+
     _apply_thinking_grammar(openai_body)
 
     _apply_json_response_grammar(openai_body, anthropic_body)
@@ -8612,6 +8707,12 @@ async def stream_anthropic_response(
         tc_names,
         [a[:200] for a in tc_args],
     )
+    # STUCK-BREAK signals: feed the assistant text + tool args to the monitor.
+    try:
+        monitor.note_assistant_text(accumulated_text)
+        monitor.note_tool_arg_hosts(list(tc_args))
+    except Exception:
+        pass
 
     # -------------------------------------------------------------------
     # Post-stream: recover <tool_call> XML from accumulated text