@awak-app/simy-cli 0.1.3 → 0.1.5

package/src/orchestrator/budget.js

@@ -0,0 +1,112 @@
+import { clampAttempts } from "./shared.js";
+
+export const DEFAULT_TOKEN_BUDGET = 250_000;
+export const DEFAULT_RETRY_BUDGET = 2;
+const MAX_TOKEN_BUDGET = 10_000_000;
+
+export function resolveRunBudgets(request = {}) {
+  const legacyMaxAttempts = clampAttempts(request.max_attempts);
+  const explicitRetryBudget = integer(request.retry_budget);
+  const retryBudget =
+    explicitRetryBudget === null
+      ? legacyMaxAttempts - 1
+      : Math.min(4, Math.max(0, explicitRetryBudget));
+  return {
+    token_budget: normalizeTokenBudget(request.token_budget),
+    retry_budget: retryBudget,
+    max_attempts: retryBudget + 1,
+  };
+}
+
+export function budgetState(snapshot, pendingAttempt = null) {
+  const attempts = [
+    ...(Array.isArray(snapshot?.attempts) ? snapshot.attempts : []),
+    ...(pendingAttempt ? [pendingAttempt] : []),
+  ];
+  const tokenBudget = normalizeTokenBudget(snapshot?.charter?.token_budget);
+  const retryBudget = normalizeRetryBudget(
+    snapshot?.charter?.retry_budget,
+    snapshot?.charter?.max_attempts,
+  );
+  const tokensUsed = attempts.reduce(
+    (sum, attempt) => sum + tokenUsageTotal(attempt?.token_usage),
+    0,
+  );
+  const attemptsUsed = attempts.length;
+  const retriesUsed = Math.max(attemptsUsed - 1, 0);
+  const tokenExhausted = tokensUsed >= tokenBudget;
+  const retryExhausted = attemptsUsed > 0 && retriesUsed >= retryBudget;
+  return {
+    schema_version: 1,
+    token_budget: tokenBudget,
+    tokens_used: tokensUsed,
+    tokens_remaining: Math.max(tokenBudget - tokensUsed, 0),
+    token_exhausted: tokenExhausted,
+    retry_budget: retryBudget,
+    retries_used: retriesUsed,
+    retries_remaining: Math.max(retryBudget - retriesUsed, 0),
+    retry_exhausted: retryExhausted,
+    exhausted: tokenExhausted || retryExhausted,
+    exhausted_reason: tokenExhausted
+      ? "token_budget_exhausted"
+      : retryExhausted
+        ? "retry_budget_exhausted"
+        : null,
+  };
+}
+
+export function refreshBudgetState(snapshot, pendingAttempt = null) {
+  const state = budgetState(snapshot, pendingAttempt);
+  snapshot.budget = state;
+  return state;
+}
+
+export function canStartProvider(snapshot, { attemptNumber, phase }) {
+  const state = refreshBudgetState(snapshot);
+  if (state.token_exhausted) {
+    return { allowed: false, reason: "token_budget_exhausted", budget: state };
+  }
+  if (phase === "executor" && attemptNumber > state.retry_budget + 1) {
+    return { allowed: false, reason: "retry_budget_exhausted", budget: state };
+  }
+  return { allowed: true, reason: null, budget: state };
+}
+
+export function tokenUsageTotal(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return 0;
+  if (Array.isArray(value.records)) {
+    return value.records.reduce((sum, record) => sum + recordTokenTotal(record), 0);
+  }
+  return recordTokenTotal(value);
+}
+
+function recordTokenTotal(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return 0;
+  const explicit = nonNegativeNumber(value.total_tokens);
+  if (explicit !== null) return explicit;
+  return (
+    (nonNegativeNumber(value.tokens_in ?? value.input_tokens) ?? 0) +
+    (nonNegativeNumber(value.tokens_out ?? value.output_tokens) ?? 0)
+  );
+}
+
+function normalizeTokenBudget(value) {
+  const parsed = integer(value);
+  if (parsed === null || parsed <= 0) return DEFAULT_TOKEN_BUDGET;
+  return Math.min(MAX_TOKEN_BUDGET, parsed);
+}
+
+function normalizeRetryBudget(value, maxAttempts) {
+  const parsed = integer(value);
+  if (parsed !== null) return Math.min(4, Math.max(0, parsed));
+  return clampAttempts(maxAttempts) - 1;
+}
+
+function integer(value) {
+  const parsed = Number.parseInt(String(value ?? ""), 10);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function nonNegativeNumber(value) {
+  return Number.isFinite(value) && value >= 0 ? Math.round(value) : null;
+}

package/src/orchestrator/contract.js

@@ -1,45 +1,105 @@
 import { randomUUID } from "node:crypto";
 
 import {
-  clampAttempts,
   cleanString,
   event,
   looksLikeUiTask,
   stringArray,
+  visualEvidenceSurface,
 } from "./shared.js";
+import { budgetState, resolveRunBudgets } from "./budget.js";
 import { classifyRisk } from "./risk.js";
+import {
+  DESKTOP_EXECUTION_TARGET,
+  normalizeDesktopExecutionTarget,
+} from "../desktop-executor.js";
 
 export function createCodingLoopSnapshot({ runId, request, metadata = {} }) {
   const now = new Date().toISOString();
   const baseBranch = cleanString(request.base_branch) || "dev";
   const expectedEvidence = stringArray(request.expected_evidence);
-  if (looksLikeUiTask(request.requirement) && !expectedEvidence.includes("ui_evidence_path")) {
-    expectedEvidence.push("ui_evidence_path");
-  }
   const acceptanceCriteria = stringArray(request.acceptance_criteria);
   const mustNot = stringArray(request.must_not);
-  const risk = classifyRisk(request);
-  const designSummary = cleanString(request.design_summary);
-  const designApprovedBy = cleanString(request.design_review_approved_by);
-  const designEvidenceUrl = cleanString(request.design_review_url);
+  const charterContext = record(request.charter_context);
+  const risk = inheritRisk(classifyRisk(request), record(charterContext.risk));
+  const inheritedDesignReview = record(charterContext.design_review);
+  const inheritedPromptPolicyReport = record(charterContext.prompt_policy_report);
+  const inheritedEvidencePolicy = record(charterContext.evidence_policy);
+  const classifiedVisualSurface = visualEvidenceSurface(request.requirement);
+  const inheritedVisualSurface = ["web_ui", "browser_extension"].includes(
+    inheritedEvidencePolicy.surface,
+  )
+    ? inheritedEvidencePolicy.surface
+    : null;
+  const visualSurface = classifiedVisualSurface || inheritedVisualSurface;
+  const browserEvidenceRequired =
+    inheritedEvidencePolicy.browser_required === true || visualSurface !== null;
+  if (browserEvidenceRequired && !expectedEvidence.includes("ui_evidence_path")) {
+    expectedEvidence.push("ui_evidence_path");
+  }
+  if (browserEvidenceRequired && !expectedEvidence.includes("browser_screenshot_or_video")) {
+    expectedEvidence.push("browser_screenshot_or_video");
+  }
+  const designSummary = cleanString(
+    inheritedDesignReview.summary || request.design_summary,
+  );
+  const designApprovedBy = cleanString(
+    inheritedDesignReview.approved_by || request.design_review_approved_by,
+  );
+  const designEvidenceUrl = cleanString(
+    inheritedDesignReview.evidence_url || request.design_review_url,
+  );
+  const acceptanceCriteriaSource =
+    acceptanceCriteria.length > 0 &&
+    cleanString(charterContext.acceptance_criteria_source) === "explicit"
+      ? "explicit"
+      : acceptanceCriteria.length > 0 &&
+          cleanString(charterContext.acceptance_criteria_source) === "default"
+        ? "default"
+        : acceptanceCriteria.length > 0
+          ? "explicit"
+          : "default";
+  const inheritedRequiredChecks = stringArray(charterContext.required_checks);
+  const inheritedNonGoals = stringArray(charterContext.non_goals);
+  const inheritedArtifacts = stringArray(charterContext.artifacts_required);
+  const inheritedAssumptions = stringArray(charterContext.assumptions);
+  const designReviewRequired =
+    risk.requires_design_review || inheritedDesignReview.required === true;
+  const designReviewApproved =
+    inheritedDesignReview.status === "approved" &&
+    Boolean(designSummary && designApprovedBy && designEvidenceUrl);
 
-  return {
+  const budgets = resolveRunBudgets(request);
+  const executionTarget = normalizeDesktopExecutionTarget(request.execution_target);
+  const executionDeviceId = cleanString(request.execution_device_id) || null;
+
+  const snapshot = {
     id: runId,
     state: "queued",
-    metadata: { ...metadata, execution_location: "local_cli" },
+    metadata: {
+      ...metadata,
+      execution_location: "local_cli",
+      execution_target: executionTarget,
+      execution_device_id: executionDeviceId,
+    },
     charter: {
       id: `${runId}_charter`,
       requirement: cleanString(request.requirement),
       repository: cleanString(request.repository),
       backend: request.backend === "claude" ? "claude" : "codex",
+      execution_target: executionTarget,
       audit_backend:
-        request.audit_backend === "claude" || request.audit_backend === "codex"
+        charterContext.audit_backend === "claude" || charterContext.audit_backend === "codex"
+          ? charterContext.audit_backend
+          : request.audit_backend === "claude" || request.audit_backend === "codex"
           ? request.audit_backend
           : request.backend === "claude"
             ? "claude"
             : "codex",
       base_branch: baseBranch,
-      max_attempts: clampAttempts(request.max_attempts),
+      max_attempts: budgets.max_attempts,
+      retry_budget: budgets.retry_budget,
+      token_budget: budgets.token_budget,
       ui_evidence_root: cleanString(request.ui_evidence_root),
       acceptance_criteria:
         acceptanceCriteria.length > 0
@@ -49,12 +109,18 @@ export function createCodingLoopSnapshot({ runId, request, metadata = {} }) {
               "Relevant tests pass and are recorded.",
               `A pull request targets ${baseBranch}.`,
             ],
-      acceptance_criteria_source: acceptanceCriteria.length > 0 ? "explicit" : "default",
+      acceptance_criteria_source: acceptanceCriteriaSource,
       expected_tests: stringArray(request.expected_tests),
       expected_evidence: expectedEvidence,
-      required_checks: stringArray(request.required_checks),
+      required_checks:
+        inheritedRequiredChecks.length > 0
+          ? inheritedRequiredChecks
+          : stringArray(request.required_checks),
       require_human_approval:
-        risk.requires_design_review || request.require_human_approval !== false,
+        risk.requires_design_review ||
+        charterContext.require_human_approval === true ||
+        (charterContext.require_human_approval !== false &&
+          request.require_human_approval !== false),
       must_not:
         mustNot.length > 0
           ? mustNot
@@ -67,32 +133,56 @@ export function createCodingLoopSnapshot({ runId, request, metadata = {} }) {
       attachments: Array.isArray(request.attachments) ? request.attachments : [],
       risk,
       design_review: {
-        required: risk.requires_design_review,
+        required: designReviewRequired,
         summary: designSummary || null,
         approved_by: designApprovedBy || null,
         evidence_url: designEvidenceUrl || null,
-        status: risk.requires_design_review
-          ? designSummary && designApprovedBy && designEvidenceUrl
+        status: designReviewRequired
+          ? designReviewApproved || (designSummary && designApprovedBy && designEvidenceUrl)
             ? "approved"
             : "missing"
           : "not_required",
       },
+      evidence_policy: {
+        browser_required: browserEvidenceRequired,
+        surface: visualSurface,
+        accepted_artifact_kinds: browserEvidenceRequired ? ["image", "video"] : [],
+        visual_review_required: browserEvidenceRequired,
+      },
       thread_state: {
-        original_request: cleanString(request.requirement),
-        user_goal: cleanString(request.requirement),
-        non_goals: ["Unrelated refactors", "Server-side execution of repository code"],
-        expected_finish_line: `A verified pull request targeting ${baseBranch}.`,
-        artifacts_required: ["pr_url", "commit_sha", "tests_run", ...expectedEvidence],
+        original_request:
+          cleanString(charterContext.original_request) || cleanString(request.requirement),
+        user_goal: cleanString(charterContext.user_goal) || cleanString(request.requirement),
+        non_goals:
+          inheritedNonGoals.length > 0
+            ? inheritedNonGoals
+            : ["Unrelated refactors", "Server-side execution of repository code"],
+        expected_finish_line:
+          cleanString(charterContext.expected_finish_line) ||
+          `A verified pull request targeting ${baseBranch}.`,
+        artifacts_required:
+          inheritedArtifacts.length > 0
+            ? inheritedArtifacts
+            : ["pr_url", "commit_sha", "tests_run", ...expectedEvidence],
         failure_count: 0,
-        assumptions: [],
+        retry_circuit_breaker: {
+          state: "closed",
+          reason: null,
+          opened_at: null,
+        },
+        assumptions: inheritedAssumptions,
       },
-      prompt_policy_report: buildPromptPolicyReport(request, risk),
+      prompt_policy_report: mergePromptPolicyReport(
+        buildPromptPolicyReport(request, risk),
+        inheritedPromptPolicyReport,
+      ),
       created_at: now,
     },
     attempts: [],
     events: [
-      event("queued", "Coding loop queued for local orchestration.", {
+      event("queued", "Agentic loop queued for local orchestration.", {
         execution_location: "local_cli",
+        execution_target: DESKTOP_EXECUTION_TARGET,
       }),
     ],
     final_audit: null,
@@ -101,10 +191,68 @@ export function createCodingLoopSnapshot({ runId, request, metadata = {} }) {
     created_at: now,
     updated_at: now,
   };
+  snapshot.budget = budgetState(snapshot);
+  return snapshot;
+}
+
+function inheritRisk(classifiedRisk, inheritedRisk) {
+  const weight = { low: 0, medium: 1, high: 2, critical: 3 };
+  const inheritedLevel = Object.hasOwn(weight, inheritedRisk.level)
+    ? inheritedRisk.level
+    : "low";
+  const level =
+    weight[inheritedLevel] > weight[classifiedRisk.level]
+      ? inheritedLevel
+      : classifiedRisk.level;
+  const tags = [...new Set([...classifiedRisk.tags, ...stringArray(inheritedRisk.tags)])];
+  const requiredControls = [
+    ...new Set([
+      ...classifiedRisk.required_controls,
+      ...stringArray(inheritedRisk.required_controls),
+    ]),
+  ];
+  const requiresDesignReview =
+    classifiedRisk.requires_design_review ||
+    inheritedRisk.requires_design_review === true ||
+    level === "high" ||
+    level === "critical";
+  if (requiresDesignReview && !requiredControls.includes("design_review")) {
+    requiredControls.push("design_review");
+  }
+  return {
+    level,
+    tags,
+    requires_design_review: requiresDesignReview,
+    required_controls: requiredControls,
+  };
+}
+
+function record(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function mergePromptPolicyReport(current, inherited) {
+  const registryId = cleanString(inherited.registry_id);
+  if (!registryId) return current;
+  return {
+    registry_id: registryId,
+    matched_policy_ids: uniqueStrings(
+      inherited.matched_policy_ids,
+      current.matched_policy_ids,
+    ),
+    matched_triggers: uniqueStrings(inherited.matched_triggers, current.matched_triggers),
+    risk_level: current.risk_level,
+    risk_tags: uniqueStrings(inherited.risk_tags, current.risk_tags),
+    reasons: uniqueStrings(inherited.reasons, current.reasons),
+  };
+}
+
+function uniqueStrings(...values) {
+  return [...new Set(values.flatMap((value) => stringArray(value)))];
 }
 
 export function newRunId() {
-  return `coding_loop_${randomUUID()}`;
+  return `agentic_loop_${randomUUID()}`;
 }
 
 function buildPromptPolicyReport(request, risk) {

package/src/orchestrator/independent-audit.js

@@ -56,7 +56,8 @@ export function buildIndependentAuditInstruction(charter, attempt) {
       [
         "Finish with exactly one line beginning SIMY_AUDIT_JSON: followed by one JSON object.",
         "Required keys: passed, summary, findings.",
-        "Each finding must contain code, severity, target, explanation, and repairability.",
+        "Each finding candidate must contain passed, code, severity, target, explanation, and repairability.",
+        "Only passed=false entries are findings. Omit passing checks, and never report passed=true evidence as a finding.",
         "Use passed=false when a blocker or major finding remains, or when evidence is unavailable.",
       ].join("\n"),
     ),
@@ -76,6 +77,7 @@ export function buildIndependentAudit(execution) {
       summary: cleanString(execution?.error || result.summary) || "Independent audit did not return valid evidence.",
       findings: [
         {
+          passed: false,
           code: "INDEPENDENT_AUDIT_UNAVAILABLE",
           severity: "blocker",
           target: "independent_audit",
@@ -87,9 +89,10 @@ export function buildIndependentAudit(execution) {
     };
   }
 
-  const findings = result.findings
+  const evaluations = result.findings
     .filter((item) => item && typeof item === "object")
     .map((item, index) => ({
+      passed: item.passed === true ? true : item.passed === false ? false : null,
       code: cleanString(item.code) || `INDEPENDENT_AUDIT_${index + 1}`,
       severity: cleanString(item.severity).toLowerCase() || "major",
       target: cleanString(item.target) || "pull_request",
@@ -97,10 +100,21 @@ export function buildIndependentAudit(execution) {
       repairability: item.repairability === "manual" ? "manual" : "auto",
       auto_fix_hint: cleanString(item.auto_fix_hint) || null,
     }));
-  const blocking = findings.some((item) => ["blocker", "major"].includes(item.severity));
+  const findings = evaluations.filter((item) => item.passed === false);
+  if (result.passed === false && findings.length === 0) {
+    findings.push({
+      passed: false,
+      code: "INDEPENDENT_AUDIT_FAILED_WITHOUT_FINDING",
+      severity: "blocker",
+      target: "independent_audit",
+      explanation: "The independent auditor returned passed=false without an explicit failed finding.",
+      repairability: "manual",
+      auto_fix_hint: null,
+    });
+  }
   const requiresHuman = findings.some((item) => item.repairability === "manual");
   return {
-    passed: result.passed === true && !blocking && !requiresHuman,
+    passed: result.passed === true && findings.length === 0,
     summary: cleanString(result.summary) || "Independent audit completed.",
     findings,
     requires_human: requiresHuman,

package/src/orchestrator/index.js

@@ -3,3 +3,4 @@ export { collectPrEvidence } from "./evidence.js";
 export { buildIndependentAuditInstruction } from "./independent-audit.js";
 export { recheckPrReadiness, runCodingLoop } from "./loop.js";
 export { mergeTokenUsage, parseStructuredMarker, parseStructuredResult } from "./result.js";
+export { buildRetryFingerprint, evaluateRetryCircuit } from "./retry.js";

package/src/orchestrator/instruction.js

@@ -1,21 +1,33 @@
 import { bullets, looksLikeUiTask, section } from "./shared.js";
+import { problemSolvingResultContract } from "./problem-solving.js";
 
 export function buildCodingInstruction(
   charter,
-  { attemptNumber, previousAttempt = null, previousFindings = [], promptInterventions = [] },
+  {
+    attemptNumber,
+    budget = null,
+    previousAttempt = null,
+    previousFindings = [],
+    promptInterventions = [],
+  },
 ) {
   const sections = [
-    section("role", "You are the local coding executor for a SIMY coding loop."),
+    section("role", "You are the local coding executor for a SIMY agentic loop."),
     section(
       "requirement_charter",
       [
         `Requirement: ${charter.requirement}`,
+        `Original request: ${charter.thread_state.original_request}`,
+        `User goal: ${charter.thread_state.user_goal}`,
         `Repository: ${charter.repository}`,
+        `Execution target: Your Desktop (${charter.execution_target || "desktop"})`,
         `Required PR base branch: ${charter.base_branch}`,
         `Risk level: ${charter.risk.level}`,
         `Design summary: ${charter.design_review.summary || "not required"}`,
         `Design approved by: ${charter.design_review.approved_by || "not required"}`,
         `Attempt: ${attemptNumber}/${charter.max_attempts}`,
+        `Retry budget: ${Math.max(attemptNumber - 1, 0)}/${charter.retry_budget}`,
+        `Token budget remaining: ${budget?.tokens_remaining ?? charter.token_budget}/${charter.token_budget}`,
         `Local evidence root: ${charter.ui_evidence_root || "not required"}`,
       ].join("\n"),
     ),
@@ -46,6 +58,9 @@ export function buildCodingInstruction(
         [
           previousAttempt ? `Previous attempt summary: ${previousAttempt.summary || "missing"}` : "",
           previousAttempt ? `Previous PR: ${previousAttempt.pr_url || "missing"}` : "",
+          previousAttempt
+            ? `Previous strategy: ${previousAttempt.problem_solving?.strategy || "not recorded"}`
+            : "",
           "Findings to repair:",
           bullets(
             previousFindings.map(
@@ -70,6 +85,18 @@ export function buildCodingInstruction(
   }
 
   sections.push(
+    section(
+      "problem_solving_protocol",
+      [
+        "Treat implementation as hypothesis testing: state assumptions, list plausible causes or approaches, inspect discriminating evidence, then choose the smallest strategy supported by that evidence.",
+        attemptNumber > 1
+          ? "This is a retry. Before editing, generate at least eight distinct MECE hypotheses, select a different primary hypothesis or approach, and do not repeat the previous strategy."
+          : "For the first attempt, make uncertainty and the selected implementation hypothesis explicit before editing.",
+        attemptNumber > 1
+          ? "Explain exactly what changed from the previous attempt and why the new evidence supports this strategy."
+          : "Record the selected hypothesis, evidence checked, and strategy in the structured result.",
+      ].join("\n"),
+    ),
     section(
       "execution_contract",
       [
@@ -84,7 +111,8 @@ export function buildCodingInstruction(
       "result_contract",
       [
         "Finish with exactly one line beginning SIMY_RESULT_JSON: followed by one JSON object.",
-        "Required keys: outcome_kind, summary, branch_name, commit_sha, commit_message_headline, pr_url, pr_number, pr_title, pr_base_branch, tests_run, tests_passed, ui_evidence_path, unrelated_changes_detected, secret_scan_passed, changed_files, residual_risks.",
+        "Required keys: outcome_kind, summary, branch_name, commit_sha, commit_message_headline, pr_url, pr_number, pr_title, pr_base_branch, tests_run, tests_passed, ui_evidence_path, unrelated_changes_detected, secret_scan_passed, changed_files, residual_risks, problem_solving.",
+        problemSolvingResultContract(),
         "Use null for unavailable scalar values and [] for unavailable arrays. Do not claim evidence that was not observed.",
       ].join("\n"),
     ),
@@ -129,8 +157,16 @@ export function buildPromptInterventions(
     rows.push({
       trigger: "repair_focus",
       title: "Repair focus",
-      prompt: "Fix only the reported gate failures, then rerun the affected verification.",
-      evidence_required: ["fixed_finding_codes", "rerun_report"],
+      prompt:
+        "Diagnose the reported gate failures with at least eight distinct hypotheses, select a new strategy supported by evidence, and do not repeat the previous approach.",
+      evidence_required: [
+        "hypotheses",
+        "selected_hypothesis_id",
+        "evidence_checked",
+        "changed_from_previous",
+        "fixed_finding_codes",
+        "rerun_report",
+      ],
     });
   }
   if (humanGuidance.trim()) {