@awak-app/simy-cli 0.1.2 → 0.1.4

package/src/orchestrator/recovery.js

@@ -0,0 +1,271 @@
+const RECOVERABLE_STATES = new Set(["waiting_human", "blocked", "failed"]);
+
+export function recoveryContractForEvent({ snapshot, state, message, detail = {} }) {
+  if (!RECOVERABLE_STATES.has(state)) return null;
+  if (isRecoveryContract(detail.recovery)) return detail.recovery;
+
+  const reasonCode = recoveryReasonCode(state, message, detail);
+  const attemptNumber = positiveInteger(detail.attempt_number);
+  const actions = recoveryActions(reasonCode);
+  return {
+    schema_version: 1,
+    state,
+    reason_code: reasonCode,
+    user_message: recoveryMessage(reasonCode),
+    primary_action_id: actions[0].id,
+    actions,
+    technical_details: {
+      event_code: clean(detail.code) || null,
+      attempt_number: attemptNumber,
+      max_attempts: positiveInteger(snapshot?.charter?.max_attempts),
+      token_budget: positiveInteger(snapshot?.charter?.token_budget),
+      retry_budget: nonNegativeInteger(snapshot?.charter?.retry_budget),
+      tokens_used: nonNegativeInteger(detail?.budget?.tokens_used),
+      retries_used: nonNegativeInteger(detail?.budget?.retries_used),
+      finding_codes: strings(detail.finding_codes),
+    },
+  };
+}
+
+export function recoveryContractForPreflight({ key, summary, details = {} }) {
+  const updateCommand = clean(details.update_command);
+  if (key === "backend") {
+    const reasonCode =
+      details.status === "outdated"
+        ? "executor_outdated"
+        : details.status === "unknown_version"
+          ? "executor_version_unknown"
+          : "executor_missing";
+    const actions = [
+      {
+        id: "update_executor",
+        type: "run_command",
+        label: "Update the executor",
+        description: "Run this command in Terminal, then check again.",
+        command: updateCommand || null,
+        payload: {},
+      },
+      checkAgainAction(),
+    ];
+    return preflightContract(reasonCode, summary, actions, {
+      installed_version: clean(details.installed_version) || null,
+      minimum_version: clean(details.minimum_version) || null,
+    });
+  }
+  if (key === "repository") {
+    const actions = [
+      {
+        id: "choose_repository",
+        type: "select_repository",
+        label: "Choose the local repository",
+        description: "Select the checkout that should receive this task, then check again.",
+        command: null,
+        payload: {},
+      },
+      checkAgainAction(),
+    ];
+    return preflightContract("repository_unavailable", summary, actions);
+  }
+  const actions = [
+    {
+      id: "reconnect_cli",
+      type: "reconnect_cli",
+      label: "Reconnect SIMY CLI",
+      description: "Open SIMY CLI and sign in again, then check the environment.",
+      command: "simy",
+      payload: {},
+    },
+    checkAgainAction(),
+  ];
+  return preflightContract("cli_session_unavailable", summary, actions);
+}
+
+export function isRecoveryContract(value) {
+  return Boolean(
+    value &&
+      typeof value === "object" &&
+      !Array.isArray(value) &&
+      value.schema_version === 1 &&
+      typeof value.reason_code === "string" &&
+      typeof value.user_message === "string" &&
+      typeof value.primary_action_id === "string" &&
+      Array.isArray(value.actions) &&
+      value.actions.length > 0,
+  );
+}
+
+function recoveryReasonCode(state, message, detail) {
+  const code = clean(detail.code);
+  if (code === "local_repository_not_authorized") return "repository_authorization_required";
+  if (code === "local_execution_interrupted") return "local_execution_interrupted";
+  if (code === "retry_circuit_open" || detail.reason === "identical_commit_and_findings") {
+    return "retry_strategy_unchanged";
+  }
+  if (code === "token_budget_exhausted") return "token_budget_exhausted";
+  if (code === "retry_budget_exhausted") return "retry_budget_exhausted";
+  const findings = strings(detail.finding_codes);
+  if (
+    findings.some((finding) =>
+      [
+        "EXPLICIT_ACCEPTANCE_CRITERIA_REQUIRED",
+        "DESIGN_REVIEW_REQUIRED",
+        "REQUIRED_CI_CHECKS_MISSING",
+      ].includes(finding),
+    )
+  ) {
+    return "requirements_incomplete";
+  }
+  if (state === "waiting_human") return "human_input_required";
+  if (state === "blocked" && /(?:attempt|retry) budget/i.test(clean(message))) {
+    return "retry_budget_exhausted";
+  }
+  if (state === "blocked") return "automatic_progress_blocked";
+  if (/attachment cleanup/i.test(clean(message))) return "attachment_cleanup_failed";
+  return "local_orchestration_failed";
+}
+
+function recoveryMessage(reasonCode) {
+  const messages = {
+    repository_authorization_required:
+      "SIMY needs permission to find the selected repository before it can continue.",
+    local_execution_interrupted:
+      "The local executor stopped during a previous CLI session and is ready for your direction.",
+    retry_strategy_unchanged:
+      "SIMY stopped repeating the same unsuccessful result. Tell it what to try differently.",
+    requirements_incomplete:
+      "SIMY needs the missing requirement or approval before implementation can start.",
+    human_input_required: "SIMY needs your decision or clarification before it can continue.",
+    token_budget_exhausted:
+      "This run used its token budget. Start a new run if you want SIMY to continue with a fresh limit.",
+    retry_budget_exhausted:
+      "This run used its automatic retry budget. Start a new run to continue with a fresh limit.",
+    automatic_progress_blocked:
+      "SIMY cannot continue automatically. Review the issue and tell it how to proceed.",
+    attachment_cleanup_failed:
+      "SIMY could not finish cleaning up a local attachment. Review the details before retrying.",
+    local_orchestration_failed:
+      "The local executor stopped unexpectedly. Give SIMY guidance to retry or start a new run.",
+  };
+  return messages[reasonCode] || messages.automatic_progress_blocked;
+}
+
+function recoveryActions(reasonCode) {
+  if (reasonCode === "repository_authorization_required") {
+    return [
+      {
+        id: "approve_repository_scan",
+        type: "resolve_hil",
+        label: "Allow repository scan",
+        description: "Review the folders SIMY will scan, then allow it to find the checkout.",
+        command: null,
+        payload: { request_kind: "local_repository_scan" },
+      },
+    ];
+  }
+  if (reasonCode === "requirements_incomplete") {
+    return [
+      guidanceAction(
+        "provide_missing_requirements",
+        "Add the missing information",
+        "Send the required acceptance criteria, review approval, or check names to SIMY.",
+      ),
+      newRunAction(),
+    ];
+  }
+  if (reasonCode === "retry_strategy_unchanged") {
+    return [
+      guidanceAction(
+        "change_strategy",
+        "Tell SIMY what to try differently",
+        "Describe a new hypothesis, implementation approach, or evidence source before continuing.",
+      ),
+      newRunAction(),
+    ];
+  }
+  if (reasonCode === "token_budget_exhausted" || reasonCode === "retry_budget_exhausted") {
+    return [newRunAction()];
+  }
+  if (reasonCode === "local_execution_interrupted") {
+    return [
+      guidanceAction(
+        "continue_interrupted_run",
+        "Continue this run",
+        "Confirm what SIMY should do next in the restored run.",
+      ),
+      newRunAction(),
+    ];
+  }
+  if (reasonCode === "human_input_required") {
+    return [
+      guidanceAction(
+        "provide_guidance",
+        "Give SIMY guidance",
+        "Answer the open question or explain what must change before continuing.",
+      ),
+      newRunAction(),
+    ];
+  }
+  return [
+    guidanceAction(
+      "retry_with_guidance",
+      "Retry with guidance",
+      "Explain what SIMY should change before retrying this run.",
+    ),
+    newRunAction(),
+  ];
+}
+
+function guidanceAction(id, label, description) {
+  return { id, type: "send_guidance", label, description, command: null, payload: {} };
+}
+
+function newRunAction() {
+  return {
+    id: "start_new_run",
+    type: "start_new_run",
+    label: "Start a new run",
+    description: "Keep this record and begin again with a revised task.",
+    command: null,
+    payload: {},
+  };
+}
+
+function checkAgainAction() {
+  return {
+    id: "check_again",
+    type: "retry_preflight",
+    label: "Check again",
+    description: "Run the local environment check again after completing the recovery step.",
+    command: null,
+    payload: {},
+  };
+}
+
+function preflightContract(reasonCode, summary, actions, technicalDetails = {}) {
+  return {
+    schema_version: 1,
+    state: "blocked",
+    reason_code: reasonCode,
+    user_message: clean(summary) || "The local environment is not ready.",
+    primary_action_id: actions[0].id,
+    actions,
+    technical_details: technicalDetails,
+  };
+}
+
+function clean(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function strings(value) {
+  return Array.isArray(value) ? value.map(clean).filter(Boolean) : [];
+}
+
+function positiveInteger(value) {
+  const number = Number.parseInt(String(value ?? ""), 10);
+  return Number.isInteger(number) && number > 0 ? number : null;
+}
+
+function nonNegativeInteger(value) {
+  return Number.isInteger(value) && value >= 0 ? value : null;
+}

package/src/orchestrator/result.js

@@ -1,4 +1,5 @@
 import { cleanString, stringArray } from "./shared.js";
+import { normalizeProblemSolving } from "./problem-solving.js";
 
 export function buildAttempt({ attemptNumber, charter, instruction, promptInterventions, execution }) {
   const result = execution.result && typeof execution.result === "object" ? execution.result : {};
@@ -26,6 +27,7 @@ export function buildAttempt({ attemptNumber, charter, instruction, promptInterv
     tests_passed: typeof result.tests_passed === "boolean" ? result.tests_passed : null,
     ui_evidence_path: cleanString(result.ui_evidence_path) || null,
     summary,
+    problem_solving: normalizeProblemSolving(result.problem_solving),
     prompt_interventions: promptInterventions,
     work_log_signals: [],
     work_log_interventions: [],

package/src/orchestrator/retry.js

@@ -0,0 +1,140 @@
+import { createHash } from "node:crypto";
+
+import { cleanString, stringArray } from "./shared.js";
+
+const RETRY_FINGERPRINT_VERSION = 1;
+
+export function evaluateRetryCircuit({ attempt, previousAttempt, findings }) {
+  const fingerprint = buildRetryFingerprint(attempt, findings);
+  attempt.retry_fingerprint = fingerprint;
+  const previousFingerprint = previousAttempt
+    ? previousAttempt.retry_fingerprint ||
+      buildRetryFingerprint(previousAttempt, findingsForAttempt(previousAttempt))
+    : null;
+  return {
+    open: Boolean(previousFingerprint?.digest && previousFingerprint.digest === fingerprint.digest),
+    fingerprint,
+    previous_fingerprint: previousFingerprint,
+    previous_attempt_number: previousAttempt?.attempt_number ?? null,
+  };
+}
+
+export function buildRetryFingerprint(attempt, findings) {
+  const commitSha =
+    cleanString(attempt?.observed_evidence?.local?.head_sha) ||
+    cleanString(attempt?.commit_sha) ||
+    null;
+  const normalizedFindings = normalizeFindings(findings);
+  const normalizedEvidence = normalizeEvidence(attempt);
+  const findingPayload = stableJson(normalizedFindings);
+  const evidencePayload = stableJson(normalizedEvidence);
+  const payload = stableJson({
+    version: RETRY_FINGERPRINT_VERSION,
+    commit_sha: commitSha,
+    findings: normalizedFindings,
+  });
+  return {
+    version: RETRY_FINGERPRINT_VERSION,
+    digest: sha256(payload),
+    commit_sha: commitSha,
+    finding_codes: normalizedFindings.map((finding) => finding.code),
+    findings_sha256: sha256(findingPayload),
+    evidence_sha256: sha256(evidencePayload),
+  };
+}
+
+function findingsForAttempt(attempt) {
+  return [
+    ...(Array.isArray(attempt?.audit?.findings) ? attempt.audit.findings : []),
+    ...(Array.isArray(attempt?.independent_audit?.findings)
+      ? attempt.independent_audit.findings
+      : []),
+  ];
+}
+
+function normalizeFindings(findings) {
+  return (Array.isArray(findings) ? findings : [])
+    .filter((finding) => finding && typeof finding === "object")
+    .map((finding) => ({
+      passed:
+        finding.passed === true ? true : finding.passed === false ? false : null,
+      code: cleanString(finding.code) || null,
+      severity: cleanString(finding.severity).toLowerCase() || null,
+      target: cleanString(finding.target) || null,
+      repairability: cleanString(finding.repairability).toLowerCase() || null,
+    }))
+    .sort(compareStableValues);
+}
+
+function normalizeEvidence(attempt) {
+  const local = attempt?.observed_evidence?.local || {};
+  const github = attempt?.observed_evidence?.github || {};
+  return {
+    reported: {
+      branch_name: cleanString(attempt?.branch_name) || null,
+      commit_sha: cleanString(attempt?.commit_sha) || null,
+      pr_url: cleanString(attempt?.pr_url) || null,
+      pr_number: Number.isInteger(attempt?.pr_number) ? attempt.pr_number : null,
+      tests_run: sortedStrings(attempt?.tests_run),
+      tests_passed:
+        typeof attempt?.tests_passed === "boolean" ? attempt.tests_passed : null,
+      ui_evidence_path: cleanString(attempt?.ui_evidence_path) || null,
+      changed_files: sortedStrings(attempt?.raw_output?.changed_files),
+    },
+    local: {
+      available: local.available === true,
+      head_sha: cleanString(local.head_sha) || null,
+      branch_name: cleanString(local.branch_name) || null,
+      commit_headline: cleanString(local.commit_headline) || null,
+      working_tree_clean: local.working_tree_clean === true,
+      changed_files: sortedStrings(local.changed_files),
+      status_lines: sortedStrings(local.status_lines),
+      errors: sortedStrings(local.errors),
+    },
+    github: {
+      available: github.available === true,
+      url: cleanString(github.url) || null,
+      number: Number.isInteger(github.number) ? github.number : null,
+      title: cleanString(github.title) || null,
+      is_draft: github.is_draft === true,
+      mergeable: cleanString(github.mergeable) || null,
+      merge_state_status: cleanString(github.merge_state_status) || null,
+      review_decision: cleanString(github.review_decision) || null,
+      approvals: sortedStrings(github.approvals),
+      head_branch: cleanString(github.head_branch) || null,
+      head_sha: cleanString(github.head_sha) || null,
+      repository: cleanString(github.repository) || null,
+      base_branch: cleanString(github.base_branch) || null,
+      checks: normalizeChecks(github.checks),
+      error: cleanString(github.error) || null,
+    },
+  };
+}
+
+function normalizeChecks(checks) {
+  return (Array.isArray(checks) ? checks : [])
+    .filter((check) => check && typeof check === "object")
+    .map((check) => ({
+      name: cleanString(check.name) || null,
+      state: cleanString(check.state) || null,
+      status: cleanString(check.status) || null,
+      conclusion: cleanString(check.conclusion) || null,
+    }))
+    .sort(compareStableValues);
+}
+
+function sortedStrings(values) {
+  return [...new Set(stringArray(values))].sort();
+}
+
+function compareStableValues(left, right) {
+  return stableJson(left).localeCompare(stableJson(right));
+}
+
+function stableJson(value) {
+  return JSON.stringify(value);
+}
+
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}

package/src/orchestrator/shared.js

@@ -1,10 +1,47 @@
 import path from "node:path";
 
+import { recoveryContractForEvent } from "./recovery.js";
+
 const ALLOWED_PREFIXES = ["feat:", "chore:", "fix:", "refactor:", "infra:"];
 const MAX_ATTEMPTS = 5;
+const PROCESS_MESSAGE_KEY_BY_STATE = Object.freeze({
+  queued: "agenticLoop.process.queued",
+  risk_classifying: "agenticLoop.process.riskClassifying",
+  chartering: "agenticLoop.process.chartering",
+  dispatching: "agenticLoop.process.dispatching",
+  coding: "agenticLoop.process.coding",
+  collecting_evidence: "agenticLoop.process.collectingEvidence",
+  auditing: "agenticLoop.process.auditing",
+  independent_auditing: "agenticLoop.process.independentAuditing",
+  checking_pr: "agenticLoop.process.checkingPr",
+  re_instructing: "agenticLoop.process.reInstructing",
+  pr_ready_for_review: "agenticLoop.process.readyForReview",
+  merge_ready: "agenticLoop.process.mergeReady",
+  waiting_human: "agenticLoop.process.waitingHuman",
+  blocked: "agenticLoop.process.blocked",
+  failed: "agenticLoop.process.failed",
+  stopped: "agenticLoop.process.stopped",
+  done: "agenticLoop.process.done",
+});
+const PROCESS_MESSAGE_PARAM_KEYS = Object.freeze([
+  "attempt_number",
+  "backend",
+  "previous_backend",
+  "next_backend",
+  "interrupted_state",
+]);
+const PROCESS_MESSAGE_KEY_BY_CODE = Object.freeze({
+  local_execution_interrupted: "agenticLoop.process.executionInterrupted",
+  local_repository_not_authorized: "agenticLoop.process.repositoryRequired",
+  local_repository_not_found: "agenticLoop.process.repositoryRequired",
+  retry_circuit_open: "agenticLoop.process.retryStrategyNeeded",
+});
 
 export function appendEvent(snapshot, state, message, detail = {}) {
-  snapshot.events.push(event(state, message, detail));
+  const recovery = recoveryContractForEvent({ snapshot, state, message, detail });
+  snapshot.events.push(
+    event(state, message, recovery ? { ...detail, recovery } : detail),
+  );
 }
 
 export function bullets(items) {
@@ -22,7 +59,35 @@ export function cleanString(value) {
 }
 
 export function event(state, message, detail = {}) {
-  return { state, message, detail, occurred_at: new Date().toISOString() };
+  return {
+    state,
+    message,
+    detail: processMessageDetail(state, detail),
+    occurred_at: new Date().toISOString(),
+  };
+}
+
+export function processMessageDetail(state, detail = {}) {
+  const normalized = detail && typeof detail === "object" && !Array.isArray(detail) ? detail : {};
+  if (typeof normalized.message_key === "string" && normalized.message_key.trim()) {
+    return { ...normalized };
+  }
+  const messageKey =
+    PROCESS_MESSAGE_KEY_BY_CODE[normalized.code] ?? PROCESS_MESSAGE_KEY_BY_STATE[state];
+  if (!messageKey) return { ...normalized };
+  const messageParams = Object.fromEntries(
+    PROCESS_MESSAGE_PARAM_KEYS.flatMap((key) => {
+      const value = normalized[key];
+      return typeof value === "string" || typeof value === "number" || typeof value === "boolean"
+        ? [[key, value]]
+        : [];
+    }),
+  );
+  return {
+    ...normalized,
+    message_key: messageKey,
+    message_params: messageParams,
+  };
 }
 
 export function evidenceKind(value) {
@@ -40,9 +105,26 @@ export function hasAllowedPrefix(value) {
 }
 
 export function looksLikeUiTask(value) {
-  return /\b(ui|ux|page|screen|component|frontend|browser|css|tailwind|react|next)\b|画面|页面|界面|按钮|表示/i.test(
-    cleanString(value),
-  );
+  return visualEvidenceSurface(value) !== null;
+}
+
+export function visualEvidenceSurface(value) {
+  const text = cleanString(value);
+  if (
+    /\b(browser|chrome|firefox|edge)\s+extension\b|\bextension\s+(popup|manifest|service worker)\b|拡張機能|浏览器扩展|瀏覽器擴充/i.test(
+      text,
+    )
+  ) {
+    return "browser_extension";
+  }
+  if (
+    /\b(ui|ux|page|screen|component|frontend|browser|css|tailwind|react|next)\b|画面|ページ|页面|界面|按钮|表示/i.test(
+      text,
+    )
+  ) {
+    return "web_ui";
+  }
+  return null;
 }
 
 export async function publish(snapshot, state, onUpdate) {

package/src/provider-stream.js

@@ -2,6 +2,8 @@ import { stripVTControlCharacters } from "node:util";
 
 const MAX_LINE_CHARS = 2_000;
 const STRUCTURED_MARKERS = ["SIMY_RESULT_JSON:", "SIMY_AUDIT_JSON:"];
+const CODEX_MCP_AUTH_WARNING =
+  "[Codex] MCP warning: optional connector authorization expired; coding continues.";
 
 export function createProviderStreamDecoder({ backend, stream = "stdout", onLine, onUsage }) {
   let pending = "";
@@ -63,6 +65,10 @@ export function formatProviderEvent(backend, event) {
   return backend === "claude" ? formatClaudeEvent(event) : formatCodexEvent(event);
 }
 
+export function isNonFatalProviderDiagnostic(line) {
+  return line === CODEX_MCP_AUTH_WARNING;
+}
+
 function formatCodexEvent(event) {
   const prefix = "[Codex]";
   if (event.type === "thread.started") {
@@ -189,6 +195,9 @@ function contentLines(prefix, label, value) {
 
 function formatPlainLine(backend, stream, value) {
   const prefix = backend === "claude" ? "[Claude Code]" : "[Codex]";
+  if (backend === "codex" && isCodexMcpAuthorizationDiagnostic(value)) {
+    return CODEX_MCP_AUTH_WARNING;
+  }
   const diagnostic = String(value).match(
     /^\S+\s+(WARN|ERROR|INFO)\s+([\w.-]+(?:::[\w.-]+)*):\s*(.*)$/,
   );
@@ -199,6 +208,14 @@ function formatPlainLine(backend, stream, value) {
   return stream === "stderr" ? `${prefix} stderr: ${value}` : `${prefix} ${value}`;
 }
 
+function isCodexMcpAuthorizationDiagnostic(value) {
+  const text = String(value || "");
+  return (
+    /(?:rmcp::|codex_mcp::)/.test(text) &&
+    /(?:invalid_grant|AuthorizationRequired|OAuth authorization required)/i.test(text)
+  );
+}
+
 function toolResultText(value) {
   if (typeof value === "string") return value;
   if (!Array.isArray(value)) return "";