@awak-app/simy-cli 0.1.3 → 0.1.5

package/src/orchestrator/loop.js

@@ -4,7 +4,9 @@ import {
   buildIndependentAuditInstruction,
 } from "./independent-audit.js";
 import { buildCodingInstruction, buildPromptInterventions } from "./instruction.js";
+import { canStartProvider, refreshBudgetState } from "./budget.js";
 import { buildAttempt, mergeTokenUsage } from "./result.js";
+import { evaluateRetryCircuit } from "./retry.js";
 import { appendEvent, publish } from "./shared.js";
 
 export async function runCodingLoop({
@@ -54,8 +56,22 @@ export async function runCodingLoop({
     attemptNumber += 1
   ) {
     if (shouldStop()) return stopCodingLoop(snapshot, onUpdate);
+    const executorBudget = canStartProvider(snapshot, {
+      attemptNumber,
+      phase: "executor",
+    });
+    if (!executorBudget.allowed) {
+      await stopForBudget({
+        snapshot,
+        attempt: snapshot.attempts.at(-1) ?? null,
+        reason: executorBudget.reason,
+        onUpdate,
+      });
+      return snapshot;
+    }
     const queuedGuidance = consumeHumanGuidance();
     const attemptGuidance = [humanGuidance, queuedGuidance].filter(Boolean).join("\n\n");
+    const previousAttempt = snapshot.attempts.at(-1) ?? null;
     const promptInterventions = buildPromptInterventions(snapshot.charter, {
       attemptNumber,
       previousFindings,
@@ -63,7 +79,8 @@ export async function runCodingLoop({
     });
     const instruction = buildCodingInstruction(snapshot.charter, {
       attemptNumber,
-      previousAttempt: snapshot.attempts.at(-1) ?? null,
+      budget: executorBudget.budget,
+      previousAttempt,
       previousFindings,
       promptInterventions,
     });
@@ -98,6 +115,7 @@ export async function runCodingLoop({
       promptInterventions,
       execution,
     });
+    attempt.budget = refreshBudgetState(snapshot, attempt);
 
     appendEvent(snapshot, "collecting_evidence", `Collecting attempt ${attemptNumber} evidence.`, {
       attempt_number: attemptNumber,
@@ -122,10 +140,21 @@ export async function runCodingLoop({
         attempt.observed_evidence?.github?.available === true,
     });
     await publish(snapshot, "auditing", onUpdate);
-    attempt.audit = await auditAttempt(snapshot.charter, attempt);
+    attempt.audit = await auditAttempt(snapshot.charter, attempt, { previousAttempt });
     if (shouldStop()) return stopCodingLoop(snapshot, onUpdate);
     attempt.implementation_gate = attempt.audit.implementation_gate;
     snapshot.attempts.push(attempt);
+    attempt.budget = refreshBudgetState(snapshot);
+
+    if (snapshot.budget.token_exhausted) {
+      await stopForBudget({
+        snapshot,
+        attempt,
+        reason: "token_budget_exhausted",
+        onUpdate,
+      });
+      return snapshot;
+    }
 
     if (!attempt.audit.passed) {
       snapshot.final_audit = attempt.audit;
@@ -142,9 +171,23 @@ export async function runCodingLoop({
       continue;
     }
 
+    const reviewerBudget = canStartProvider(snapshot, {
+      attemptNumber,
+      phase: "reviewer",
+    });
+    if (!reviewerBudget.allowed) {
+      await stopForBudget({
+        snapshot,
+        attempt,
+        reason: reviewerBudget.reason,
+        onUpdate,
+      });
+      return snapshot;
+    }
     appendEvent(snapshot, "independent_auditing", "Starting an independent AI audit.", {
       attempt_number: attemptNumber,
       backend: snapshot.charter.audit_backend,
+      budget: reviewerBudget.budget,
     });
     await publish(snapshot, "independent_auditing", onUpdate);
     if (shouldStop()) return stopCodingLoop(snapshot, onUpdate);
@@ -161,11 +204,12 @@ export async function runCodingLoop({
     if (shouldStop()) return stopCodingLoop(snapshot, onUpdate);
     attempt.independent_audit = buildIndependentAudit(auditExecution);
     attempt.token_usage = mergeTokenUsage(attempt.token_usage, auditExecution.tokenUsage);
+    attempt.budget = refreshBudgetState(snapshot);
 
     // Re-collect after the read-only auditor to catch any mutated HEAD or working tree.
     attempt.observed_evidence = await safeEvidence(collectEvidence, attempt);
     if (shouldStop()) return stopCodingLoop(snapshot, onUpdate);
-    attempt.audit = await auditAttempt(snapshot.charter, attempt);
+    attempt.audit = await auditAttempt(snapshot.charter, attempt, { previousAttempt });
     if (shouldStop()) return stopCodingLoop(snapshot, onUpdate);
     attempt.implementation_gate = attempt.audit.implementation_gate;
 
@@ -196,10 +240,12 @@ export async function runCodingLoop({
       attempt.independent_audit.findings || [],
     );
     snapshot.done_gate_passed = attempt.pr_readiness.ready;
+    attempt.budget = refreshBudgetState(snapshot);
     appendEvent(snapshot, attempt.pr_readiness.state, attempt.pr_readiness.summary, {
       attempt_number: attemptNumber,
       pr_url: attempt.pr_url,
       pending_reasons: attempt.pr_readiness.pending_reasons,
+      budget: snapshot.budget,
     });
     await publish(snapshot, attempt.pr_readiness.state, onUpdate);
     return snapshot;
@@ -210,7 +256,7 @@ export async function runCodingLoop({
 
 async function stopCodingLoop(snapshot, onUpdate) {
   if (snapshot.state === "stopped") return snapshot;
-  appendEvent(snapshot, "stopped", "Coding loop stopped by the local human operator.", {
+  appendEvent(snapshot, "stopped", "Agentic loop stopped by the local human operator.", {
     source: "local_cli",
   });
   await publish(snapshot, "stopped", onUpdate);
@@ -225,7 +271,9 @@ export async function recheckPrReadiness({ snapshot, collectEvidence, onUpdate }
   });
   await publish(snapshot, "checking_pr", onUpdate);
   attempt.observed_evidence = await safeEvidence(collectEvidence, attempt);
-  attempt.audit = await auditAttempt(snapshot.charter, attempt);
+  attempt.audit = await auditAttempt(snapshot.charter, attempt, {
+    previousAttempt: snapshot.attempts.at(-2) ?? null,
+  });
   snapshot.implementation_gate_passed = attempt.audit.passed;
   attempt.pr_readiness = evaluatePrReadiness(snapshot.charter, attempt);
   attempt.pr_gate = attempt.pr_readiness;
@@ -330,6 +378,60 @@ async function handleFailedAudit({
   onUpdate,
 }) {
   snapshot.charter.thread_state.failure_count += 1;
+  const budget = refreshBudgetState(snapshot);
+  if (budget.token_exhausted) {
+    return stopForBudget({
+      snapshot,
+      attempt,
+      reason: "token_budget_exhausted",
+      onUpdate,
+    });
+  }
+  const retryCircuit = evaluateRetryCircuit({
+    attempt,
+    previousAttempt: snapshot.attempts.at(-2) ?? null,
+    findings,
+  });
+  if (retryCircuit.open) {
+    const avoidedAttempts = Math.max(snapshot.charter.max_attempts - attemptNumber, 0);
+    const circuitState = {
+      state: "open",
+      reason: "identical_commit_and_findings",
+      opened_at: new Date().toISOString(),
+      attempt_number: attemptNumber,
+      previous_attempt_number: retryCircuit.previous_attempt_number,
+      avoided_attempts: avoidedAttempts,
+      ...retryCircuit.fingerprint,
+    };
+    snapshot.charter.thread_state.retry_circuit_breaker = circuitState;
+    snapshot.final_audit = retryCircuitAudit(snapshot.final_audit, circuitState);
+    appendEvent(
+      snapshot,
+      "blocked",
+      "Retry stopped because the commit and findings did not change.",
+      {
+        code: "retry_circuit_open",
+        reason: circuitState.reason,
+        attempt_number: attemptNumber,
+        previous_attempt_number: retryCircuit.previous_attempt_number,
+        commit_sha: circuitState.commit_sha,
+        finding_codes: circuitState.finding_codes,
+        retry_fingerprint: circuitState.digest,
+        avoided_attempts: avoidedAttempts,
+      },
+    );
+    await publish(snapshot, "blocked", onUpdate);
+    return true;
+  }
+  if (attemptNumber >= snapshot.charter.max_attempts) {
+    await stopForBudget({
+      snapshot,
+      attempt,
+      reason: "retry_budget_exhausted",
+      onUpdate,
+    });
+    return true;
+  }
   if (requiresHuman) {
     appendEvent(snapshot, "waiting_human", "PR audit requires human input.", {
       finding_codes: findings.map((finding) => finding.code),
@@ -345,13 +447,85 @@ async function handleFailedAudit({
     await publish(snapshot, "re_instructing", onUpdate);
     return false;
   }
-  appendEvent(snapshot, "blocked", "Coding loop exhausted its attempt budget.", {
-    finding_codes: findings.map((finding) => finding.code),
+  return false;
+}
+
+async function stopForBudget({ snapshot, attempt, reason, onUpdate }) {
+  const budget = refreshBudgetState(snapshot);
+  const finding = budgetFinding(reason, budget);
+  const existingAudit = snapshot.final_audit || attempt?.audit || {};
+  const findings = Array.isArray(existingAudit.findings) ? existingAudit.findings : [];
+  snapshot.final_audit = {
+    ...existingAudit,
+    passed: false,
+    summary: finding.explanation,
+    findings: findings.some((item) => item.code === finding.code)
+      ? findings
+      : [...findings, finding],
+    auto_repairable: false,
+    requires_human: true,
+    budget,
+  };
+  if (attempt) attempt.budget = budget;
+  const message =
+    reason === "token_budget_exhausted"
+      ? "Agentic loop exhausted its token budget."
+      : "Agentic loop exhausted its retry budget.";
+  appendEvent(snapshot, "blocked", message, {
+    code: reason,
+    attempt_number: attempt?.attempt_number ?? null,
+    finding_codes: [finding.code],
+    budget,
   });
   await publish(snapshot, "blocked", onUpdate);
   return true;
 }
 
+function budgetFinding(reason, budget) {
+  if (reason === "token_budget_exhausted") {
+    return {
+      passed: false,
+      code: "TOKEN_BUDGET_EXHAUSTED",
+      severity: "blocker",
+      target: "token_budget",
+      explanation: `The run used ${budget.tokens_used} of ${budget.token_budget} provider tokens, so no additional executor or reviewer call can start.`,
+      repairability: "manual",
+      auto_fix_hint: null,
+    };
+  }
+  return {
+    passed: false,
+    code: "RETRY_BUDGET_EXHAUSTED",
+    severity: "blocker",
+    target: "retry_budget",
+    explanation: `The run used ${budget.retries_used} of ${budget.retry_budget} automatic retries.`,
+    repairability: "manual",
+    auto_fix_hint: null,
+  };
+}
+
+function retryCircuitAudit(audit, circuitState) {
+  const circuitFinding = {
+    passed: false,
+    code: "RETRY_CIRCUIT_OPEN",
+    severity: "blocker",
+    target: "retry_loop",
+    explanation:
+      "The last two attempts produced the same commit and findings, so another automatic retry would repeat the same work.",
+    repairability: "manual",
+    auto_fix_hint: null,
+  };
+  return {
+    ...(audit || {}),
+    passed: false,
+    summary: "Automatic retries stopped because the last two failure results were identical.",
+    findings: [...(Array.isArray(audit?.findings) ? audit.findings : []), circuitFinding],
+    auto_repairable: false,
+    requires_human: true,
+    retry_circuit_breaker: circuitState,
+  };
+}
+
 function aggregateAudit(attempt, passed, findings) {
   return {
     passed,

package/src/orchestrator/presentation.js

@@ -106,7 +106,7 @@ export function summarizeCodingLoopEvent(snapshot, event) {
       };
     case "blocked":
       return {
-        summary: "The run cannot continue automatically with its current attempt budget or evidence.",
+        summary: "The run cannot continue automatically with its current token, retry, or evidence budget.",
         result: findings.length ? findingResult(findings) : cleanString(event?.message),
         next: "Review the findings, adjust the request or evidence, and resume the run.",
       };
@@ -118,7 +118,7 @@ export function summarizeCodingLoopEvent(snapshot, event) {
       };
     case "stopped":
       return {
-        summary: "The local human operator stopped this coding run.",
+        summary: "The local human operator stopped this Agentic Loop run.",
         result: "No further executor handoff will occur for this run.",
         next: "Start a new run or explicitly continue this one when ready.",
       };

package/src/orchestrator/problem-solving.js

@@ -0,0 +1,129 @@
+import { cleanString, stringArray } from "./shared.js";
+
+const MIN_RETRY_HYPOTHESES = 8;
+
+export function normalizeProblemSolving(value) {
+  const record = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  const hypotheses = Array.isArray(record.hypotheses)
+    ? record.hypotheses.map(normalizeHypothesis).filter(Boolean)
+    : [];
+  return {
+    hypotheses,
+    selected_hypothesis:
+      cleanString(record.selected_hypothesis_id) ||
+      cleanString(record.selected_hypothesis) ||
+      null,
+    evidence_checked: uniqueStrings(record.evidence_checked),
+    strategy: cleanString(record.strategy) || null,
+    changed_from_previous: cleanString(record.changed_from_previous) || null,
+  };
+}
+
+export function evaluateRetryProblemSolving(attempt, previousAttempt) {
+  const current = normalizeProblemSolving(
+    attempt?.problem_solving || attempt?.raw_output?.problem_solving,
+  );
+  const previous = normalizeProblemSolving(
+    previousAttempt?.problem_solving || previousAttempt?.raw_output?.problem_solving,
+  );
+  if (!Number.isInteger(attempt?.attempt_number) || attempt.attempt_number <= 1) {
+    return { required: false, passed: true, checks: [], current, previous };
+  }
+
+  const distinctHypotheses = new Set(
+    current.hypotheses.map((hypothesis) => canonical(hypothesis.statement)),
+  ).size;
+  const selectedMatches = current.hypotheses.some(
+    (hypothesis) =>
+      canonical(hypothesis.id) === canonical(current.selected_hypothesis) ||
+      canonical(hypothesis.statement) === canonical(current.selected_hypothesis),
+  );
+  const changeDescriptionIsMeaningful = Boolean(
+    current.changed_from_previous &&
+      !/^(?:same|unchanged|none|n\/?a|no change)$/i.test(current.changed_from_previous),
+  );
+  const strategyDiffers = Boolean(
+    current.strategy &&
+      (!previous.strategy || canonical(current.strategy) !== canonical(previous.strategy)),
+  );
+  const checks = [
+    {
+      id: "retry_hypotheses_expanded",
+      label: "Retry considers at least eight distinct hypotheses",
+      passed: distinctHypotheses >= MIN_RETRY_HYPOTHESES,
+      detail: `Expected at least ${MIN_RETRY_HYPOTHESES} distinct hypotheses; recorded ${distinctHypotheses}.`,
+    },
+    {
+      id: "retry_hypothesis_selected",
+      label: "Retry selects one recorded hypothesis",
+      passed: Boolean(current.selected_hypothesis && selectedMatches),
+      detail: current.selected_hypothesis
+        ? `Selected hypothesis ${current.selected_hypothesis} must match a recorded hypothesis.`
+        : "No selected hypothesis was recorded.",
+    },
+    {
+      id: "retry_evidence_checked",
+      label: "Retry records discriminating evidence",
+      passed: current.evidence_checked.length > 0,
+      detail:
+        current.evidence_checked.length > 0
+          ? `${current.evidence_checked.length} evidence item(s) recorded.`
+          : "No evidence checked against the hypotheses was recorded.",
+    },
+    {
+      id: "retry_strategy_changed",
+      label: "Retry uses a changed strategy",
+      passed: Boolean(current.strategy && changeDescriptionIsMeaningful && strategyDiffers),
+      detail: retryStrategyDetail({ current, previous, strategyDiffers }),
+    },
+  ];
+  return {
+    required: true,
+    passed: checks.every((check) => check.passed),
+    checks,
+    current,
+    previous,
+  };
+}
+
+export function problemSolvingResultContract() {
+  return [
+    "problem_solving must be an object with hypotheses, selected_hypothesis_id, evidence_checked, strategy, and changed_from_previous.",
+    "Each hypothesis must use {id, statement}; evidence_checked must list concrete observations or commands.",
+    "On attempt 1, record the assumptions, hypotheses considered, selected hypothesis, and implementation strategy; changed_from_previous may be null.",
+    `On every retry, record at least ${MIN_RETRY_HYPOTHESES} distinct MECE hypotheses, select one of them, check discriminating evidence, use a strategy different from the previous attempt, and explain the change in changed_from_previous.`,
+  ].join("\n");
+}
+
+function normalizeHypothesis(value, index) {
+  if (typeof value === "string") {
+    const statement = cleanString(value);
+    return statement ? { id: `H${index + 1}`, statement } : null;
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const statement = cleanString(value.statement) || cleanString(value.hypothesis);
+  if (!statement) return null;
+  return {
+    id: cleanString(value.id) || `H${index + 1}`,
+    statement,
+  };
+}
+
+function uniqueStrings(value) {
+  return [...new Set(stringArray(value))];
+}
+
+function canonical(value) {
+  return cleanString(value).toLowerCase().replace(/\s+/g, " ");
+}
+
+function retryStrategyDetail({ current, previous, strategyDiffers }) {
+  if (!current.strategy) return "No retry strategy was recorded.";
+  if (!current.changed_from_previous) {
+    return "The retry did not explain what changed from the previous attempt.";
+  }
+  if (!strategyDiffers) {
+    return `The retry repeated the previous strategy: ${current.strategy}`;
+  }
+  return `Changed from ${previous.strategy || "the prior unstructured approach"} to ${current.strategy}: ${current.changed_from_previous}`;
+}