@awak-app/simy-cli 0.1.3 → 0.1.5

package/src/agent.js

@@ -36,7 +36,19 @@ import {
   referenceLocalAttachmentPaths,
 } from "./local-attachments.js";
 import { discoverWorkspace } from "./workspace-context.js";
-import { resolveBackendExecutable } from "./backend-executable.js";
+import { BACKEND_VERSION_POLICIES } from "./backend-executable.js";
+import {
+  DESKTOP_EXECUTION_LABEL,
+  DESKTOP_EXECUTION_TARGET,
+  desktopExecutorCapability,
+  inspectDesktopExecutor,
+  normalizeDesktopExecutionTarget,
+} from "./desktop-executor.js";
+import { recoveryContractForPreflight } from "./orchestrator/recovery.js";
+import {
+  DEFAULT_RETRY_BUDGET,
+  DEFAULT_TOKEN_BUDGET,
+} from "./orchestrator/budget.js";
 import {
   resolveWebApiBaseUrl,
   sessionRequiresWebAuthorization,
@@ -60,6 +72,7 @@ export async function startAgent({
   daemon = false,
   webOrigin = null,
   sessionRoot,
+  updateManager = null,
   dependencies = {},
   quiet = false,
 } = {}) {
@@ -207,6 +220,7 @@ export async function startAgent({
   };
 
   const selectRepository = async (run, repository) => {
+    if (run) ensureAcceptingNewWork(updateManager);
     const selected = repository?.local_path
       ? repositoryInventory.find(
           (item) =>
@@ -219,10 +233,14 @@ export async function startAgent({
       throw new Error(`This run requires ${run.request.repository}; select that local repository.`);
     }
     if (!run) return selected;
-    return continueLocalCodingRunAfterRepositoryApproval(
-      run,
-      { repository: selected.repository, localPath: selected.local_path },
-      runOptions,
+    return withUpdateWork(
+      updateManager,
+      () =>
+        continueLocalCodingRunAfterRepositoryApproval(
+          run,
+          { repository: selected.repository, localPath: selected.local_path },
+          runOptions,
+        ),
     );
   };
 
@@ -239,6 +257,20 @@ export async function startAgent({
       }
 
       const url = new URL(req.url || "/", `http://${req.headers.host || "127.0.0.1"}`);
+      const agenticLoopPath = canonicalAgenticLoopPath(url.pathname);
+      if (
+        req.method === "POST" &&
+        agenticLoopPath.startsWith("/v1/agentic-loop") &&
+        agenticLoopPath !== "/v1/agentic-loop/preflight"
+      ) {
+        const releaseUpdateWork = acquireUpdateWork(updateManager);
+        if (!releaseUpdateWork) {
+          json(res, 503, updateInProgressResponse(updateManager));
+          return;
+        }
+        res.once("finish", releaseUpdateWork);
+        res.once("close", releaseUpdateWork);
+      }
       if (req.method === "GET" && url.pathname === "/v1/health") {
         json(res, 200, {
           ok: true,
@@ -246,6 +278,7 @@ export async function startAgent({
           web_origin: apiOrigin,
           session_valid: isSessionValid(session, Date.now(), apiOrigin),
           session_expires_at: session?.expires_at ?? null,
+          cli_update: updateManager?.snapshot?.() ?? null,
         });
         return;
       }
@@ -253,7 +286,7 @@ export async function startAgent({
         json(res, 200, await readCapabilities(dependencies));
         return;
       }
-      if (req.method === "POST" && url.pathname === "/v1/coding-loop/preflight") {
+      if (req.method === "POST" && agenticLoopPath === "/v1/agentic-loop/preflight") {
         if (!isSessionValid(session, Date.now(), apiOrigin)) {
           json(res, 401, { error: "simy session expired; run simy again" });
           return;
@@ -268,11 +301,22 @@ export async function startAgent({
           json(res, 400, { error: "backend must be codex or claude" });
           return;
         }
+        let executionTarget;
+        try {
+          executionTarget = normalizeDesktopExecutionTarget(body.execution_target);
+        } catch (error) {
+          json(res, 400, {
+            error: error instanceof Error ? error.message : "execution_target must be desktop",
+            code: "unsupported_execution_target",
+          });
+          return;
+        }
         const backend = body.backend;
         const indexedRepository = await ensureRepositoryIndexed(repository);
         const environment = await inspectCodingLoopEnvironment({
           repository,
           backend,
+          executionTarget,
           localPath:
             typeof body.local_path === "string"
               ? body.local_path
@@ -316,7 +360,11 @@ export async function startAgent({
         void synchronizeAuthorizedSession();
         return;
       }
-      if (req.method === "POST" && url.pathname === "/v1/coding-loop/start") {
+      if (req.method === "POST" && agenticLoopPath === "/v1/agentic-loop/start") {
+        if (!acceptsNewWork(updateManager)) {
+          json(res, 503, updateInProgressResponse(updateManager));
+          return;
+        }
         if (!isSessionValid(session, Date.now(), apiOrigin)) {
           json(res, 401, { error: "simy session expired; run simy again" });
           return;
@@ -339,9 +387,40 @@ export async function startAgent({
           return;
         }
         if (registry.has(runId)) {
-          json(res, 409, { error: "coding loop run already exists" });
+          json(res, 409, { error: "agentic loop run already exists" });
+          return;
+        }
+        let executionTarget;
+        try {
+          executionTarget = normalizeDesktopExecutionTarget(body.execution_target);
+        } catch (error) {
+          json(res, 400, {
+            error: error instanceof Error ? error.message : "execution_target must be desktop",
+            code: "unsupported_execution_target",
+          });
+          return;
+        }
+        if (body.backend !== "codex" && body.backend !== "claude") {
+          json(res, 400, { error: "backend must be codex or claude" });
           return;
         }
+        if (body.execution_target != null) {
+          const inspection = normalizeBackendInspection(body.backend, availableCapabilities);
+          if (!inspection.compatible) {
+            const summary = backendPreflightSummary(body.backend, inspection);
+            json(res, 409, {
+              error: summary,
+              code: `desktop_executor_${inspection.status}`,
+              execution_target: executionTarget,
+              recovery: recoveryContractForPreflight({
+                key: "backend",
+                summary,
+                details: inspection,
+              }),
+            });
+            return;
+          }
+        }
         let stagedAttachments = [];
         try {
           stagedAttachments = await stageRunAttachments({
@@ -358,6 +437,8 @@ export async function startAgent({
           runId,
           request: {
             backend: body.backend === "claude" ? "claude" : "codex",
+            execution_target: executionTarget,
+            execution_device_id: session?.device_id || null,
             audit_backend:
               body.audit_backend === "claude" || body.audit_backend === "codex"
                 ? body.audit_backend
@@ -370,6 +451,8 @@ export async function startAgent({
                 : indexedRepository?.local_path || null,
             base_branch: typeof body.base_branch === "string" ? body.base_branch : "dev",
             max_attempts: body.max_attempts,
+            retry_budget: body.retry_budget,
+            token_budget: body.token_budget,
             ui_evidence_root:
               typeof body.ui_evidence_root === "string" ? body.ui_evidence_root : "",
             acceptance_criteria: Array.isArray(body.acceptance_criteria)
@@ -391,6 +474,12 @@ export async function startAgent({
               typeof body.design_review_url === "string" ? body.design_review_url : "",
             must_not: Array.isArray(body.must_not) ? body.must_not : [],
             proposal_id: typeof body.proposal_id === "string" ? body.proposal_id : null,
+            charter_context:
+              body.charter_context &&
+              typeof body.charter_context === "object" &&
+              !Array.isArray(body.charter_context)
+                ? body.charter_context
+                : null,
             attachments: stagedAttachments,
           },
           session,
@@ -407,7 +496,7 @@ export async function startAgent({
         return;
       }
 
-      const controlMatch = url.pathname.match(/^\/v1\/coding-loop\/([^/]+)\/control$/);
+      const controlMatch = agenticLoopPath.match(/^\/v1\/agentic-loop\/([^/]+)\/control$/);
       if (req.method === "POST" && controlMatch) {
         if (!isSessionValid(session, Date.now(), apiOrigin)) {
           json(res, 401, { error: "simy session expired; run simy again" });
@@ -428,6 +517,10 @@ export async function startAgent({
         } else if (body.action === "pause") {
           pauseLocalCodingRun(run);
         } else if (body.action === "resume") {
+          if (!acceptsNewWork(updateManager)) {
+            json(res, 503, updateInProgressResponse(updateManager));
+            return;
+          }
           resumeLocalCodingRun(run);
         } else {
           json(res, 400, { error: "action must be pause, resume, or stop" });
@@ -444,7 +537,7 @@ export async function startAgent({
         return;
       }
 
-      const guidanceMatch = url.pathname.match(/^\/v1\/coding-loop\/([^/]+)\/guidance$/);
+      const guidanceMatch = agenticLoopPath.match(/^\/v1\/agentic-loop\/([^/]+)\/guidance$/);
       if (req.method === "POST" && guidanceMatch) {
         if (!isSessionValid(session, Date.now(), apiOrigin)) {
           json(res, 401, { error: "simy session expired; run simy again" });
@@ -474,7 +567,7 @@ export async function startAgent({
         return;
       }
 
-      const hilMatch = url.pathname.match(/^\/v1\/coding-loop\/([^/]+)\/hil$/);
+      const hilMatch = agenticLoopPath.match(/^\/v1\/agentic-loop\/([^/]+)\/hil$/);
       if (hilMatch) {
         if (!isSessionValid(session, Date.now(), apiOrigin)) {
           json(res, 401, { error: "simy session expired; run simy again" });
@@ -502,6 +595,10 @@ export async function startAgent({
         }
 
         if (req.method === "POST") {
+          if (!acceptsNewWork(updateManager)) {
+            json(res, 503, updateInProgressResponse(updateManager));
+            return;
+          }
           const body = await readJson(req);
           const requestId = localRepositoryHilRequestId(run);
           if (body.request_id !== requestId) {
@@ -556,8 +653,12 @@ export async function startAgent({
         }
       }
 
-      const recheckMatch = url.pathname.match(/^\/v1\/coding-loop\/([^/]+)\/recheck$/);
+      const recheckMatch = agenticLoopPath.match(/^\/v1\/agentic-loop\/([^/]+)\/recheck$/);
       if (req.method === "POST" && recheckMatch) {
+        if (!acceptsNewWork(updateManager)) {
+          json(res, 503, updateInProgressResponse(updateManager));
+          return;
+        }
         const run = registry.get(decodeURIComponent(recheckMatch[1]));
         if (!run) {
           json(res, 404, { error: "run not found" });
@@ -572,7 +673,7 @@ export async function startAgent({
         return;
       }
 
-      const streamMatch = url.pathname.match(/^\/v1\/coding-loop\/([^/]+)\/stream$/);
+      const streamMatch = agenticLoopPath.match(/^\/v1\/agentic-loop\/([^/]+)\/stream$/);
       if (req.method === "GET" && streamMatch) {
         streamRun(res, registry.get(decodeURIComponent(streamMatch[1])));
         return;
@@ -616,6 +717,7 @@ export async function startAgent({
 
   server.on("close", () => {
     if (heartbeatTimer) clearInterval(heartbeatTimer);
+    updateManager?.stop?.();
     registry.close();
   });
   return {
@@ -629,17 +731,19 @@ export async function startAgent({
     workspace,
     repositoryScanRoot,
     capabilities: availableCapabilities,
+    updates: updateManager,
     controls: {
       repositoryInventory: () => [...repositoryInventory],
       scanRepositories,
       selectRepository,
-      create: async (input) => {
+      create: (input) => withUpdateWork(updateManager, async () => {
         if (!isSessionValid(session, Date.now(), apiOrigin)) {
           throw new Error("Sign in to SIMY before starting a coding task.");
         }
         const requirement = String(input.requirement || "").trim();
         const repository = String(input.repository || "").trim();
         const backend = input.backend === "claude" ? "claude" : "codex";
+        const executionTarget = normalizeDesktopExecutionTarget(input.executionTarget);
         if (!requirement) throw new Error("Describe the coding task first.");
         if (!repository) throw new Error("Set a repository with /repo owner/name.");
         if (availableCapabilities?.backends?.[backend] !== true) {
@@ -652,7 +756,11 @@ export async function startAgent({
           local_path: indexedRepository?.local_path || input.localPath || workspace.localPath,
           base_branch: String(input.baseBranch || "dev"),
           backend,
-          max_attempts: 3,
+          execution_target: executionTarget,
+          execution_device_id: session?.device_id || null,
+          max_attempts: DEFAULT_RETRY_BUDGET + 1,
+          retry_budget: DEFAULT_RETRY_BUDGET,
+          token_budget: DEFAULT_TOKEN_BUDGET,
           acceptance_criteria: [],
           expected_tests: [],
           expected_evidence: [],
@@ -671,20 +779,74 @@ export async function startAgent({
               request,
             });
         const runId = String(remoteRun?.id || "");
-        if (!runId) throw new Error("SIMY Web did not return a coding run id.");
+        if (!runId) throw new Error("SIMY Web did not return an Agentic Loop run id.");
         const run = createRun({ runId, request, session, apiOrigin });
         registry.create(run);
         void startLocalCodingRun(run, runOptions);
         return run;
-      },
-      continue: (run, guidance) => continueLocalCodingRun(run, guidance, runOptions),
-      applyDecision: (run, decision) => applyLocalHumanDecision(run, decision, runOptions),
+      }),
+      continue: (run, guidance) =>
+        withUpdateWork(updateManager, () => continueLocalCodingRun(run, guidance, runOptions)),
+      applyDecision: (run, decision) =>
+        withUpdateWork(updateManager, () => applyLocalHumanDecision(run, decision, runOptions)),
       queueGuidance: queueLocalCodingGuidance,
       pause: pauseLocalCodingRun,
-      resume: resumeLocalCodingRun,
+      resume: (run) => withUpdateWorkSync(updateManager, () => resumeLocalCodingRun(run)),
       stop: stopLocalCodingRun,
       recheck: (run) =>
-        recheckLocalCodingRun(run, { collectEvidence: runOptions.collectEvidence }),
+        withUpdateWork(updateManager, () =>
+          recheckLocalCodingRun(run, { collectEvidence: runOptions.collectEvidence }),
+        ),
+    },
+  };
+}
+
+function acceptsNewWork(updateManager) {
+  return updateManager?.acceptsNewWork?.() !== false;
+}
+
+function acquireUpdateWork(updateManager) {
+  if (!acceptsNewWork(updateManager)) return null;
+  return updateManager?.beginWork?.() ?? (() => {});
+}
+
+function ensureAcceptingNewWork(updateManager) {
+  if (acceptsNewWork(updateManager)) return;
+  throw new Error(
+    updateManager?.snapshot?.().message ||
+      "SIMY is installing an update. Wait for the daemon to restart, then try again.",
+  );
+}
+
+async function withUpdateWork(updateManager, action) {
+  const release = acquireUpdateWork(updateManager);
+  if (!release) ensureAcceptingNewWork(updateManager);
+  try {
+    return await action();
+  } finally {
+    release?.();
+  }
+}
+
+function withUpdateWorkSync(updateManager, action) {
+  const release = acquireUpdateWork(updateManager);
+  if (!release) ensureAcceptingNewWork(updateManager);
+  try {
+    return action();
+  } finally {
+    release?.();
+  }
+}
+
+function updateInProgressResponse(updateManager) {
+  return {
+    error:
+      updateManager?.snapshot?.().message ||
+      "SIMY is installing an update. Wait for the daemon to restart, then try again.",
+    code: "cli_update_in_progress",
+    recovery: {
+      title: "Wait for SIMY to restart",
+      description: "The CLI will reconnect automatically after the update finishes.",
     },
   };
 }
@@ -702,6 +864,8 @@ async function createRemoteRun({ apiOrigin, apiBaseUrl, token, request }) {
       backend: request.backend,
       base_branch: request.base_branch,
       max_attempts: request.max_attempts,
+      retry_budget: request.retry_budget,
+      token_budget: request.token_budget,
       acceptance_criteria: request.acceptance_criteria,
       expected_tests: request.expected_tests,
       expected_evidence: request.expected_evidence,
@@ -812,12 +976,31 @@ function localRepositoryHilRequest(run, root, authorizedRoots) {
 
 async function capabilities() {
   const [codex, claude] = await Promise.all([
-    resolveBackendExecutable("codex"),
-    resolveBackendExecutable("claude"),
+    inspectDesktopExecutor("codex"),
+    inspectDesktopExecutor("claude"),
   ]);
   return {
-    backends: { codex: Boolean(codex), claude: Boolean(claude) },
-    features: { repository_scan_approval: true },
+    backends: { codex: codex.compatible, claude: claude.compatible },
+    backend_versions: {
+      codex: publicBackendInspection(codex),
+      claude: publicBackendInspection(claude),
+    },
+    execution_targets: {
+      desktop: {
+        execution_target: DESKTOP_EXECUTION_TARGET,
+        label: DESKTOP_EXECUTION_LABEL,
+        available: codex.compatible || claude.compatible,
+        backends: {
+          codex: desktopExecutorCapability(codex),
+          claude: desktopExecutorCapability(claude),
+        },
+      },
+    },
+    features: {
+      repository_scan_approval: true,
+      executor_version_preflight: true,
+      desktop_executor: true,
+    },
     session_ttl_hours: 48,
   };
 }
@@ -826,13 +1009,24 @@ async function readCapabilities(dependencies) {
   return dependencies.capabilities ? dependencies.capabilities() : capabilities();
 }
 
-async function inspectCodingLoopEnvironment({ repository, backend, localPath, dependencies }) {
+async function inspectCodingLoopEnvironment({
+  repository,
+  backend,
+  executionTarget,
+  localPath,
+  dependencies,
+}) {
   const checks = [
     {
       key: "session",
       status: "passed",
       summary: "Local CLI session is connected to this SIMY Web origin.",
     },
+    {
+      key: "execution_target",
+      status: "passed",
+      summary: `This run will execute on ${DESKTOP_EXECUTION_LABEL} through SIMY CLI.`,
+    },
   ];
   let repositoryPath = null;
   try {
@@ -843,32 +1037,107 @@ async function inspectCodingLoopEnvironment({ repository, backend, localPath, de
       summary: `Verified ${repository} against the local Git origin.`,
     });
   } catch (error) {
+    const summary =
+      error instanceof Error ? error.message : "Local repository could not be resolved.";
     checks.push({
       key: "repository",
       status: "failed",
-      summary: error instanceof Error ? error.message : "Local repository could not be resolved.",
+      summary,
+      recovery: recoveryContractForPreflight({ key: "repository", summary }),
     });
   }
 
   const available = await readCapabilities(dependencies);
-  const backendAvailable = available?.backends?.[backend] === true;
+  const inspection = normalizeBackendInspection(backend, available);
+  const backendSummary = backendPreflightSummary(backend, inspection);
   checks.push({
     key: "backend",
-    status: backendAvailable ? "passed" : "failed",
-    summary: backendAvailable
-      ? `${backend === "claude" ? "Claude Code" : "Codex"} is available locally.`
-      : `${backend === "claude" ? "Claude Code" : "Codex"} is not available on PATH.`,
+    status: inspection.compatible ? "passed" : "failed",
+    summary: backendSummary,
+    details: {
+      status: inspection.status,
+      installed_version: inspection.installed_version,
+      minimum_version: inspection.minimum_version,
+      update_command: inspection.update_command,
+    },
+    ...(inspection.compatible
+      ? {}
+      : {
+          recovery: recoveryContractForPreflight({
+            key: "backend",
+            summary: backendSummary,
+            details: inspection,
+          }),
+        }),
   });
 
   return {
-    ready: Boolean(repositoryPath && backendAvailable),
+    ready: Boolean(repositoryPath && inspection.compatible),
     repository,
     backend,
+    execution_target: executionTarget,
     local_path: repositoryPath,
     checks,
   };
 }
 
+function publicBackendInspection(inspection) {
+  return {
+    status: inspection.status,
+    available: inspection.available,
+    compatible: inspection.compatible,
+    installed_version: inspection.installed_version,
+    minimum_version: inspection.minimum_version,
+    update_command: inspection.update_command,
+  };
+}
+
+function normalizeBackendInspection(backend, capabilitiesValue) {
+  const policy = BACKEND_VERSION_POLICIES[backend];
+  const detail = capabilitiesValue?.backend_versions?.[backend];
+  if (detail && typeof detail === "object") {
+    return {
+      status: String(detail.status || (detail.compatible ? "compatible" : "missing")),
+      available: detail.available === true,
+      compatible: detail.compatible === true,
+      installed_version:
+        typeof detail.installed_version === "string" ? detail.installed_version : null,
+      minimum_version:
+        typeof detail.minimum_version === "string"
+          ? detail.minimum_version
+          : policy.minimumVersion,
+      update_command:
+        typeof detail.update_command === "string" ? detail.update_command : policy.updateCommand,
+    };
+  }
+  const compatible = capabilitiesValue?.backends?.[backend] === true;
+  return {
+    status: compatible ? "compatible" : "missing",
+    available: compatible,
+    compatible,
+    installed_version: null,
+    minimum_version: policy.minimumVersion,
+    update_command: policy.updateCommand,
+  };
+}
+
+function backendPreflightSummary(backend, inspection) {
+  const label = BACKEND_VERSION_POLICIES[backend].label;
+  if (inspection.status === "compatible" && inspection.installed_version) {
+    return `${label} ${inspection.installed_version} is compatible (requires ${inspection.minimum_version} or newer).`;
+  }
+  if (inspection.status === "outdated") {
+    return `${label} ${inspection.installed_version} is too old. Update to ${inspection.minimum_version} or newer: ${inspection.update_command}`;
+  }
+  if (inspection.status === "unknown_version") {
+    return `${label} is installed, but its version could not be verified. Reinstall or update it: ${inspection.update_command}`;
+  }
+  if (inspection.status === "compatible") {
+    return `${label} is available locally.`;
+  }
+  return `${label} is not available. Install or update it: ${inspection.update_command}`;
+}
+
 async function verifyLaunchChallenge({ apiOrigin, apiBaseUrl, token, runId, challenge }) {
   try {
     const response = await fetch(
@@ -890,6 +1159,10 @@ async function verifyLaunchChallenge({ apiOrigin, apiBaseUrl, token, runId, chal
   }
 }
 
+function canonicalAgenticLoopPath(pathname) {
+  return pathname.replace(/^\/v1\/coding-loop(?=\/|$)/, "/v1/agentic-loop");
+}
+
 function streamRun(res, run) {
   if (!run) {
     json(res, 404, { error: "run not found" });