@awak-app/simy-cli 0.1.1 → 0.1.3

package/src/orchestrator/loop.js

@@ -4,7 +4,7 @@ import {
   buildIndependentAuditInstruction,
 } from "./independent-audit.js";
 import { buildCodingInstruction, buildPromptInterventions } from "./instruction.js";
-import { buildAttempt } from "./result.js";
+import { buildAttempt, mergeTokenUsage } from "./result.js";
 import { appendEvent, publish } from "./shared.js";
 
 export async function runCodingLoop({
@@ -13,41 +13,53 @@ export async function runCodingLoop({
   executeIndependentAudit,
   collectEvidence,
   onUpdate,
+  humanGuidance = "",
+  resume = false,
+  shouldStop = () => false,
+  consumeHumanGuidance = () => "",
 }) {
-  appendEvent(snapshot, "risk_classifying", "PR risk classification completed.", {
-    risk: snapshot.charter.risk,
-  });
-  await publish(snapshot, "risk_classifying", onUpdate);
+  if (!resume || snapshot.attempts.length === 0) {
+    appendEvent(snapshot, "risk_classifying", "PR risk classification completed.", {
+      risk: snapshot.charter.risk,
+    });
+    await publish(snapshot, "risk_classifying", onUpdate);
 
-  const charterFindings = validateCharter(snapshot.charter);
-  if (charterFindings.length > 0) {
-    snapshot.final_audit = humanGate(
-      "Requirements or design review must be completed before implementation.",
-      charterFindings,
-    );
-    appendEvent(snapshot, "waiting_human", "Requirements require human clarification.", {
-      finding_codes: charterFindings.map((finding) => finding.code),
+    const charterFindings = validateCharter(snapshot.charter);
+    if (charterFindings.length > 0) {
+      snapshot.final_audit = humanGate(
+        "Requirements or design review must be completed before implementation.",
+        charterFindings,
+      );
+      appendEvent(snapshot, "waiting_human", "Requirements require human clarification.", {
+        finding_codes: charterFindings.map((finding) => finding.code),
+      });
+      await publish(snapshot, "waiting_human", onUpdate);
+      return snapshot;
+    }
+
+    appendEvent(snapshot, "chartering", "Requirement charter created locally.", {
+      charter_id: snapshot.charter.id,
+      base_branch: snapshot.charter.base_branch,
+      risk_level: snapshot.charter.risk.level,
     });
-    await publish(snapshot, "waiting_human", onUpdate);
-    return snapshot;
+    await publish(snapshot, "chartering", onUpdate);
   }
 
-  appendEvent(snapshot, "chartering", "Requirement charter created locally.", {
-    charter_id: snapshot.charter.id,
-    base_branch: snapshot.charter.base_branch,
-    risk_level: snapshot.charter.risk.level,
-  });
-  await publish(snapshot, "chartering", onUpdate);
-
-  let previousFindings = [];
+  let previousFindings = resume ? snapshot.final_audit?.findings || [] : [];
+  const firstAttempt = resume ? snapshot.attempts.length + 1 : 1;
+  const lastAttempt = resume ? firstAttempt : snapshot.charter.max_attempts;
   for (
-    let attemptNumber = 1;
-    attemptNumber <= snapshot.charter.max_attempts;
+    let attemptNumber = firstAttempt;
+    attemptNumber <= lastAttempt;
     attemptNumber += 1
   ) {
+    if (shouldStop()) return stopCodingLoop(snapshot, onUpdate);
+    const queuedGuidance = consumeHumanGuidance();
+    const attemptGuidance = [humanGuidance, queuedGuidance].filter(Boolean).join("\n\n");
     const promptInterventions = buildPromptInterventions(snapshot.charter, {
       attemptNumber,
       previousFindings,
+      humanGuidance: attemptGuidance,
     });
     const instruction = buildCodingInstruction(snapshot.charter, {
       attemptNumber,
@@ -78,6 +90,7 @@ export async function runCodingLoop({
         charter: snapshot.charter,
       }),
     );
+    if (shouldStop()) return stopCodingLoop(snapshot, onUpdate);
     const attempt = buildAttempt({
       attemptNumber,
       charter: snapshot.charter,
@@ -88,16 +101,29 @@ export async function runCodingLoop({
 
     appendEvent(snapshot, "collecting_evidence", `Collecting attempt ${attemptNumber} evidence.`, {
       attempt_number: attemptNumber,
+      outcome_kind: attempt.outcome_kind,
+      branch_name: attempt.branch_name,
+      commit_sha: attempt.commit_sha,
+      pr_url: attempt.pr_url,
+      tests_run: attempt.tests_run,
     });
     await publish(snapshot, "collecting_evidence", onUpdate);
     attempt.observed_evidence = await safeEvidence(collectEvidence, attempt);
+    if (shouldStop()) return stopCodingLoop(snapshot, onUpdate);
 
     appendEvent(snapshot, "auditing", `Verifying local evidence for attempt ${attemptNumber}.`, {
       attempt_number: attemptNumber,
       outcome_kind: attempt.outcome_kind,
+      tests_run: attempt.tests_run,
+      tests_passed: attempt.tests_passed,
+      changed_files: attempt.raw_output?.changed_files,
+      evidence_available:
+        attempt.observed_evidence?.local?.available === true ||
+        attempt.observed_evidence?.github?.available === true,
     });
     await publish(snapshot, "auditing", onUpdate);
     attempt.audit = await auditAttempt(snapshot.charter, attempt);
+    if (shouldStop()) return stopCodingLoop(snapshot, onUpdate);
     attempt.implementation_gate = attempt.audit.implementation_gate;
     snapshot.attempts.push(attempt);
 
@@ -121,6 +147,7 @@ export async function runCodingLoop({
       backend: snapshot.charter.audit_backend,
     });
     await publish(snapshot, "independent_auditing", onUpdate);
+    if (shouldStop()) return stopCodingLoop(snapshot, onUpdate);
     const auditInstruction = buildIndependentAuditInstruction(snapshot.charter, attempt);
     const auditExecution = await safeExecution(() =>
       executeIndependentAudit({
@@ -131,11 +158,15 @@ export async function runCodingLoop({
         attempt,
       }),
     );
+    if (shouldStop()) return stopCodingLoop(snapshot, onUpdate);
     attempt.independent_audit = buildIndependentAudit(auditExecution);
+    attempt.token_usage = mergeTokenUsage(attempt.token_usage, auditExecution.tokenUsage);
 
     // 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);
+    if (shouldStop()) return stopCodingLoop(snapshot, onUpdate);
     attempt.implementation_gate = attempt.audit.implementation_gate;
 
     const independentFindings = attempt.independent_audit.findings || [];
@@ -177,6 +208,15 @@ export async function runCodingLoop({
   return snapshot;
 }
 
+async function stopCodingLoop(snapshot, onUpdate) {
+  if (snapshot.state === "stopped") return snapshot;
+  appendEvent(snapshot, "stopped", "Coding loop stopped by the local human operator.", {
+    source: "local_cli",
+  });
+  await publish(snapshot, "stopped", onUpdate);
+  return snapshot;
+}
+
 export async function recheckPrReadiness({ snapshot, collectEvidence, onUpdate }) {
   const attempt = snapshot.attempts.at(-1);
   if (!attempt || !attempt.audit?.passed || !attempt.independent_audit?.passed) return snapshot;

package/src/orchestrator/presentation.js

@@ -0,0 +1,189 @@
+import { cleanString } from "./shared.js";
+
+export function summarizeCodingLoopEvent(snapshot, event) {
+  const detail = objectValue(event?.detail);
+  const state = cleanString(detail.pr_lifecycle_state) || cleanString(event?.state);
+  const explicit = {
+    summary: cleanString(detail.step_summary),
+    result: cleanString(detail.step_result),
+    next: cleanString(detail.next_action),
+  };
+  if (explicit.summary) return explicit;
+
+  const charter = objectValue(snapshot?.charter);
+  const attemptNumber = numberValue(detail.attempt_number) || latestAttemptNumber(snapshot);
+  const maxAttempts = numberValue(charter.max_attempts) || 1;
+  const executor = executorLabel(detail.backend || charter.backend);
+  const repository = cleanString(charter.repository) || "the selected repository";
+  const branch = cleanString(detail.branch_name || charter.base_branch) || "the selected branch";
+  const requirement = sentencePreview(charter.requirement, 120) || "the requested change";
+  const findings = stringArray(detail.finding_codes);
+  const pendingReasons = stringArray(detail.pending_reasons);
+
+  switch (state) {
+    case "queued":
+      return {
+        summary: `Task recorded for local execution in ${repository} on ${branch}.`,
+        result: `Goal: ${requirement}`,
+        next: "SIMY will classify risk and turn the request into an execution charter.",
+      };
+    case "risk_classifying": {
+      const risk = objectValue(detail.risk || charter.risk);
+      const level = cleanString(risk.level) || "unknown";
+      return {
+        summary: `Risk classified as ${level}; the required review gates are now known.`,
+        result: risk.requires_design_review
+          ? "A design review is required before implementation."
+          : "No pre-implementation design review is required.",
+        next: "SIMY will finalize scope, acceptance criteria, tests, and evidence requirements.",
+      };
+    }
+    case "chartering":
+      return {
+        summary: `Execution scope set for: ${requirement}`,
+        result: `${countLabel(charter.acceptance_criteria, "acceptance criterion")}, ${countLabel(charter.expected_tests, "expected test")}, and ${countLabel(charter.expected_evidence, "evidence requirement")}.`,
+        next: `Attempt 1 of ${maxAttempts} will be handed to ${executor}.`,
+      };
+    case "dispatching":
+      return {
+        summary: `Preparing ${executor} attempt ${attemptNumber}/${maxAttempts} for ${branch}.`,
+        result: "The executor instruction now includes the task, constraints, checks, and prior findings.",
+        next: `${executor} will start the local coding process.`,
+      };
+    case "coding":
+      return {
+        summary: `${executor} is implementing attempt ${attemptNumber}/${maxAttempts} on ${branch}.`,
+        result: "Live provider output is shown below as the local process works.",
+        next: "When execution finishes, SIMY will collect code, test, PR, and UI evidence.",
+      };
+    case "collecting_evidence":
+      return {
+        summary: `Attempt ${attemptNumber} finished; SIMY is collecting verifiable implementation evidence.`,
+        result: listResult(detail.tests_run, "Checks to verify", "Checks will be read from the executor result and repository."),
+        next: "The evidence will be checked against the original requirement and acceptance criteria.",
+      };
+    case "auditing":
+      return {
+        summary: `SIMY is verifying attempt ${attemptNumber} against the requirement and recorded evidence.`,
+        result: evidenceResult(detail),
+        next: "A passing implementation proceeds to an independent AI review; findings trigger repair or human input.",
+      };
+    case "independent_auditing":
+      return {
+        summary: `${executorLabel(detail.backend || charter.audit_backend)} is independently reviewing attempt ${attemptNumber}.`,
+        result: "The reviewer uses the frozen instruction, diff, checks, and evidence rather than the implementer's conclusion.",
+        next: "SIMY will combine both audits and decide whether the PR is ready for human review.",
+      };
+    case "checking_pr":
+      return {
+        summary: "SIMY is refreshing the latest GitHub review and CI evidence.",
+        result: "The existing PR, commit, approvals, mergeability, and required checks are being re-read.",
+        next: "The run will move to merge-ready when every required gate passes.",
+      };
+    case "re_instructing":
+      return {
+        summary: `Attempt ${attemptNumber} needs another coding pass before review.`,
+        result: findingResult(findings),
+        next: `SIMY will give the findings to ${executor} for attempt ${Math.min(attemptNumber + 1, maxAttempts)}/${maxAttempts}.`,
+      };
+    case "pr_ready_for_review":
+      return {
+        summary: "Implementation is complete, but the PR still needs human review or external evidence.",
+        result: pendingReasons.length ? `Pending: ${pendingReasons.join("; ")}` : cleanString(event?.message),
+        next: "Review or approve the PR, then refresh its evidence from Web or CLI.",
+      };
+    case "merge_ready":
+      return {
+        summary: "Implementation, checks, evidence, and required review gates have passed.",
+        result: cleanString(detail.pr_url) ? `Merge-ready PR: ${detail.pr_url}` : "The recorded PR is ready to merge.",
+        next: "A human can merge the PR when the release timing is appropriate.",
+      };
+    case "waiting_human":
+      return {
+        summary: "The automated loop is paused because a human decision or missing input is required.",
+        result: findings.length ? findingResult(findings) : cleanString(snapshot?.final_audit?.summary || event?.message),
+        next: "Provide guidance or approval in Web or CLI to continue the same run.",
+      };
+    case "blocked":
+      return {
+        summary: "The run cannot continue automatically with its current attempt budget or evidence.",
+        result: findings.length ? findingResult(findings) : cleanString(event?.message),
+        next: "Review the findings, adjust the request or evidence, and resume the run.",
+      };
+    case "failed":
+      return {
+        summary: "Local orchestration stopped before the requested outcome was verified.",
+        result: cleanString(detail.error || event?.message),
+        next: "Fix the reported problem, then retry or continue the run.",
+      };
+    case "stopped":
+      return {
+        summary: "The local human operator stopped this coding run.",
+        result: "No further executor handoff will occur for this run.",
+        next: "Start a new run or explicitly continue this one when ready.",
+      };
+    default:
+      return {
+        summary: cleanString(event?.message) || "SIMY recorded a coding lifecycle update.",
+        result: "Open details for the complete structured record.",
+        next: "SIMY will continue from the latest recorded state.",
+      };
+  }
+}
+
+function evidenceResult(detail) {
+  const testsPassed = detail.tests_passed;
+  const changedFiles = stringArray(detail.changed_files);
+  const parts = [];
+  if (testsPassed === true) parts.push("reported checks passed");
+  if (testsPassed === false) parts.push("one or more reported checks failed");
+  if (changedFiles.length) parts.push(`${changedFiles.length} changed ${changedFiles.length === 1 ? "file" : "files"} recorded`);
+  return parts.length ? `${capitalize(parts.join("; "))}.` : "SIMY is checking the code result, tests, PR facts, and any required UI evidence.";
+}
+
+function findingResult(findings) {
+  return findings.length ? `Findings: ${findings.join(", ")}.` : "The audit recorded findings that require attention.";
+}
+
+function listResult(values, label, fallback) {
+  const items = stringArray(values);
+  return items.length ? `${label}: ${items.join(", ")}.` : fallback;
+}
+
+function countLabel(values, singular) {
+  const count = Array.isArray(values) ? values.length : 0;
+  const plural = singular === "acceptance criterion" ? "acceptance criteria" : `${singular}s`;
+  return `${count} ${count === 1 ? singular : plural}`;
+}
+
+function latestAttemptNumber(snapshot) {
+  const attempts = Array.isArray(snapshot?.attempts) ? snapshot.attempts : [];
+  return numberValue(attempts.at(-1)?.attempt_number) || 1;
+}
+
+function executorLabel(value) {
+  return cleanString(value) === "claude" ? "Claude Code" : "Codex";
+}
+
+function sentencePreview(value, maxLength) {
+  const text = cleanString(value).replace(/\s+/g, " ");
+  if (text.length <= maxLength) return text;
+  return `${text.slice(0, maxLength - 3).trimEnd()}...`;
+}
+
+function stringArray(value) {
+  return Array.isArray(value) ? value.map(cleanString).filter(Boolean) : [];
+}
+
+function numberValue(value) {
+  const number = Number.parseInt(String(value ?? ""), 10);
+  return Number.isFinite(number) && number > 0 ? number : 0;
+}
+
+function objectValue(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function capitalize(value) {
+  return value ? `${value[0].toUpperCase()}${value.slice(1)}` : value;
+}

package/src/orchestrator/result.js

@@ -44,6 +44,13 @@ export function buildAttempt({ attemptNumber, charter, instruction, promptInterv
   };
 }
 
+export function mergeTokenUsage(...values) {
+  const records = values.flatMap((value) =>
+    Array.isArray(value?.records) ? value.records.filter(isUsageRecord) : [],
+  );
+  return records.length > 0 ? { records } : {};
+}
+
 export function parseStructuredResult(text) {
   return parseStructuredMarker(text, "SIMY_RESULT_JSON:");
 }
@@ -89,3 +96,7 @@ function buildArtifactPreviews(result) {
       : null,
   ].filter(Boolean);
 }
+
+function isUsageRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}