@awak-app/simy-cli 0.1.3 → 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/repository-inventory.js

@@ -112,6 +112,7 @@ export async function writeRepositoryInventory(
           branch: item.branch,
           default_branch: item.default_branch,
           local_path: item.local_path,
+          ...(item.capabilities?.length ? { capabilities: item.capabilities } : {}),
         })),
       },
       null,
@@ -127,12 +128,14 @@ export function mergeRepositoryInventory(...inventories) {
     const repository = normalizeGitHubRemote(item?.repository);
     const localPath = String(item?.local_path || item?.localPath || "").trim();
     if (!repository || !localPath) continue;
+    const capabilities = uniqueCapabilities(item?.capabilities);
     byPath.set(resolve(localPath), {
       repository,
       branch: String(item?.branch || "").trim() || "dev",
       default_branch:
         String(item?.default_branch || item?.defaultBranch || "").trim() || "dev",
       local_path: resolve(localPath),
+      ...(capabilities.length ? { capabilities } : {}),
     });
   }
   return [...byPath.values()].sort((left, right) =>
@@ -158,17 +161,88 @@ async function inspectGitRepository(directory) {
     ]);
     const repository = normalizeGitHubRemote(remote);
     if (!repository) return null;
+    const capabilities = await inspectRepositoryCapabilities(directory);
     return {
       repository,
       branch: String(branch || "").trim() || "dev",
       default_branch: await detectDefaultBranch(directory),
       local_path: String(root || "").trim(),
+      ...(capabilities.length ? { capabilities } : {}),
     };
   } catch {
     return null;
   }
 }
 
+async function inspectRepositoryCapabilities(directory) {
+  const capabilities = [];
+  const rootEntries = await safeDirectoryNames(directory);
+  const packageJson = await readJsonFile(join(directory, "package.json"));
+  const packageNames = Object.keys({
+    ...(packageJson?.dependencies || {}),
+    ...(packageJson?.devDependencies || {}),
+  });
+  const pythonConfig = await readTextFile(join(directory, "pyproject.toml"));
+  const extensionManifest =
+    (await readJsonFile(join(directory, "extension", "manifest.json"))) ||
+    (await readJsonFile(join(directory, "manifest.json")));
+
+  if (
+    packageNames.some((name) => ["next", "react-dom", "vue", "svelte"].includes(name)) ||
+    [...rootEntries].some((name) => /^next\.config\./.test(name))
+  ) {
+    capabilities.push("web_ui");
+  }
+  if ([2, 3].includes(extensionManifest?.manifest_version)) {
+    capabilities.push("browser_extension");
+  }
+  if (rootEntries.has("pubspec.yaml")) capabilities.push("mobile_ui");
+  if (rootEntries.has("supabase") || rootEntries.has("migrations")) {
+    capabilities.push("database_backend");
+  }
+  if (
+    packageJson?.bin ||
+    packageNames.some((name) => ["commander", "ink", "yargs", "oclif"].includes(name))
+  ) {
+    capabilities.push("cli");
+  }
+  if (/\b(langgraph|langchain|crewai|autogen|openai-agents)\b/i.test(pythonConfig)) {
+    capabilities.push("agent_runtime");
+  }
+  if (
+    /\b(fastapi|django|flask)\b/i.test(pythonConfig) ||
+    packageNames.some((name) => ["express", "fastify", "hono", "koa"].includes(name))
+  ) {
+    capabilities.push("backend_api");
+  }
+  return uniqueCapabilities(capabilities);
+}
+
+async function safeDirectoryNames(directory) {
+  try {
+    return new Set((await readdir(directory, { withFileTypes: true })).map((entry) => entry.name));
+  } catch {
+    return new Set();
+  }
+}
+
+async function readJsonFile(filePath) {
+  try {
+    const parsed = JSON.parse(await readFile(filePath, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+async function readTextFile(filePath) {
+  try {
+    return await readFile(filePath, "utf8");
+  } catch {
+    return "";
+  }
+}
+
 async function detectDefaultBranch(directory) {
   try {
     const { stdout } = await execFileAsync(
@@ -207,6 +281,19 @@ function uniqueStrings(values) {
   return [...new Set((Array.isArray(values) ? values : []).map(String).filter(Boolean))];
 }
 
+function uniqueCapabilities(values) {
+  const allowed = new Set([
+    "web_ui",
+    "browser_extension",
+    "mobile_ui",
+    "database_backend",
+    "backend_api",
+    "agent_runtime",
+    "cli",
+  ]);
+  return [...new Set((Array.isArray(values) ? values : []).filter((value) => allowed.has(value)))].sort();
+}
+
 function emptyInventory() {
   return { version: INVENTORY_VERSION, authorizedRoots: [], repositories: [], scannedAt: null };
 }