@awak-app/simy-cli 0.1.5 → 0.2.1

package/README.md

@@ -93,6 +93,19 @@ executor updates, repository selection, and CLI reconnection. Web clients must
 validate the action type before rendering or executing it; raw local error text
 is not copied into the recovery contract.
 
+## Provider token budget
+
+Each run accepts a configurable `token_budget` (or the explicit
+`provider_token_budget` alias) from 1 to 10,000,000 Provider tokens. The default
+is 250,000. Provider tokens are the Codex or Claude Code usage reported for the
+run; they are a safety limit and are not billed as SIMY tokens.
+
+When a run reaches this limit, its recovery contract suggests a higher rounded
+limit. SIMY Web can edit that suggestion and call
+`POST /v1/agentic-loop/:run_id/provider-token-budget` with
+`provider_token_budget`. The CLI persists the higher limit and resumes the same
+run. SIMY token consumption remains a separate platform billing record.
+
 ## Interactive console
 
 Running `simy` in a terminal opens the Agentic Loop chat. It discovers the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awak-app/simy-cli",
-  "version": "0.1.5",
+  "version": "0.2.1",
   "description": "Local SIMY Agentic Loop executor for Codex and Claude Code.",
   "type": "module",
   "bin": {

package/src/agent.js

@@ -7,6 +7,7 @@ import {
   continueLocalCodingRun,
   continueLocalCodingRunAfterRepositoryApproval,
   createRun,
+  increaseLocalCodingRunProviderTokenBudget,
   LocalRunRegistry,
   isLocalRepositoryApprovalPending,
   pauseLocalCodingRun,
@@ -64,6 +65,11 @@ import {
   scanGitRepositories,
   writeRepositoryInventory,
 } from "./repository-inventory.js";
+import {
+  CLI_API_CONTRACT_VERSION,
+  CLI_VERSION,
+  withCliContract,
+} from "./cli-contract.js";
 
 const DEVICE_HEARTBEAT_INTERVAL_MS = 20_000;
 
@@ -99,7 +105,11 @@ export async function startAgent({
         ]
       : [],
   );
-  const availableCapabilities = await readCapabilities(dependencies);
+  const installMode = updateManager?.snapshot?.()?.install_mode ?? null;
+  const availableCapabilities = withCliContract(
+    await readCapabilities(dependencies),
+    installMode,
+  );
   const heartbeatDevice = dependencies.heartbeatDevice || heartbeatLocalDevice;
   const runOptions = dependencies.runOptions || {};
   const repositoryScanRoot = resolve(
@@ -274,6 +284,8 @@ export async function startAgent({
       if (req.method === "GET" && url.pathname === "/v1/health") {
         json(res, 200, {
           ok: true,
+          cli_version: CLI_VERSION,
+          api_contract_version: CLI_API_CONTRACT_VERSION,
           daemon,
           web_origin: apiOrigin,
           session_valid: isSessionValid(session, Date.now(), apiOrigin),
@@ -283,7 +295,7 @@ export async function startAgent({
         return;
       }
       if (req.method === "GET" && url.pathname === "/v1/capabilities") {
-        json(res, 200, await readCapabilities(dependencies));
+        json(res, 200, availableCapabilities);
         return;
       }
       if (req.method === "POST" && agenticLoopPath === "/v1/agentic-loop/preflight") {
@@ -356,7 +368,12 @@ export async function startAgent({
         startHeartbeatTimer();
         loginUrl = null;
         registry.emit("change", registry.list());
-        json(res, 200, { ok: true, expires_at: session.expires_at });
+        json(res, 200, {
+          ok: true,
+          expires_at: session.expires_at,
+          cli_version: CLI_VERSION,
+          api_contract_version: CLI_API_CONTRACT_VERSION,
+        });
         void synchronizeAuthorizedSession();
         return;
       }
@@ -452,7 +469,7 @@ export async function startAgent({
             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,
+            token_budget: body.provider_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)
@@ -537,6 +554,53 @@ export async function startAgent({
         return;
       }
 
+      const providerBudgetMatch = agenticLoopPath.match(
+        /^\/v1\/agentic-loop\/([^/]+)\/provider-token-budget$/,
+      );
+      if (req.method === "POST" && providerBudgetMatch) {
+        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;
+        }
+        const run = registry.get(decodeURIComponent(providerBudgetMatch[1]));
+        if (!run) {
+          json(res, 404, { error: "run not found" });
+          return;
+        }
+        const body = await readJson(req);
+        let budget;
+        try {
+          budget = await increaseLocalCodingRunProviderTokenBudget(
+            run,
+            body.provider_token_budget,
+          );
+        } catch (error) {
+          json(res, 409, {
+            error: error instanceof Error ? error.message : "Provider token budget was rejected",
+            code: "provider_token_budget_rejected",
+          });
+          return;
+        }
+        const continuation = continueLocalCodingRun(
+          run,
+          String(body.message || "Continue after increasing the Provider token budget."),
+          runOptions,
+        );
+        json(res, 202, {
+          ok: true,
+          run_id: run.id,
+          state: "resuming",
+          provider_token_budget: budget.token_budget,
+          provider_tokens_used: budget.tokens_used,
+        });
+        void continuation.catch((error) => reportProviderBudgetResumeError(error, quiet));
+        return;
+      }
+
       const guidanceMatch = agenticLoopPath.match(/^\/v1\/agentic-loop\/([^/]+)\/guidance$/);
       if (req.method === "POST" && guidanceMatch) {
         if (!isSessionValid(session, Date.now(), apiOrigin)) {
@@ -698,6 +762,9 @@ export async function startAgent({
     loginUrl = new URL("/local-cli/connect", apiOrigin);
     loginUrl.searchParams.set("port", String(port));
     loginUrl.searchParams.set("nonce", authNonce);
+    loginUrl.searchParams.set("cli_version", CLI_VERSION);
+    loginUrl.searchParams.set("api_contract_version", String(CLI_API_CONTRACT_VERSION));
+    if (installMode) loginUrl.searchParams.set("install_mode", installMode);
     if (!quiet) {
       console.log(`Sign in to SIMY: ${loginUrl.toString()}`);
       console.log(`Session file: ${sessionPath(apiOrigin, sessionRoot)}`);
@@ -910,6 +977,8 @@ export async function heartbeatLocalDevice({
       ),
       body: JSON.stringify({
         port,
+        cli_version: CLI_VERSION,
+        api_contract_version: CLI_API_CONTRACT_VERSION,
         capabilities,
         repo_inventory: repoInventory,
       }),
@@ -943,6 +1012,14 @@ function reportRepositoryResumeError(error, quiet) {
   );
 }
 
+function reportProviderBudgetResumeError(error, quiet) {
+  if (!quiet) {
+    console.error(
+      `Provider token budget was increased, but the run could not resume: ${error instanceof Error ? error.message : error}`,
+    );
+  }
+}
+
 function localRepositoryHilRequestId(run) {
   return `local-repository-scan:${run.id}`;
 }

package/src/cli-contract.js

@@ -0,0 +1,11 @@
+export const CLI_VERSION = "0.2.1";
+export const CLI_API_CONTRACT_VERSION = 2;
+
+export function withCliContract(capabilities = {}, installMode = null) {
+  return {
+    ...capabilities,
+    cli_version: CLI_VERSION,
+    api_contract_version: CLI_API_CONTRACT_VERSION,
+    ...(installMode ? { install_mode: installMode } : {}),
+  };
+}

package/src/orchestrator/budget.js

@@ -2,7 +2,8 @@ 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 const MAX_PROVIDER_TOKEN_BUDGET = 10_000_000;
+const PROVIDER_TOKEN_BUDGET_STEP = 250_000;
 
 export function resolveRunBudgets(request = {}) {
   const legacyMaxAttempts = clampAttempts(request.max_attempts);
@@ -12,12 +13,47 @@ export function resolveRunBudgets(request = {}) {
       ? legacyMaxAttempts - 1
       : Math.min(4, Math.max(0, explicitRetryBudget));
   return {
-    token_budget: normalizeTokenBudget(request.token_budget),
+    token_budget: normalizeTokenBudget(request.provider_token_budget ?? request.token_budget),
     retry_budget: retryBudget,
     max_attempts: retryBudget + 1,
   };
 }
 
+export function suggestedProviderTokenBudget(value) {
+  const state = value?.schema_version === 1 ? value : budgetState(value);
+  if (state.tokens_used >= MAX_PROVIDER_TOKEN_BUDGET) return null;
+  const required = Math.max(
+    state.token_budget * 2,
+    state.tokens_used * 1.25,
+    state.tokens_used + PROVIDER_TOKEN_BUDGET_STEP,
+  );
+  return Math.min(
+    MAX_PROVIDER_TOKEN_BUDGET,
+    Math.ceil(required / PROVIDER_TOKEN_BUDGET_STEP) * PROVIDER_TOKEN_BUDGET_STEP,
+  );
+}
+
+export function increaseProviderTokenBudget(snapshot, value) {
+  const requested = integer(value);
+  if (requested === null || requested <= 0) {
+    throw new Error("Provider token budget must be a positive integer.");
+  }
+  if (requested > MAX_PROVIDER_TOKEN_BUDGET) {
+    throw new Error(
+      `Provider token budget cannot exceed ${MAX_PROVIDER_TOKEN_BUDGET.toLocaleString("en-US")}.`,
+    );
+  }
+  const current = budgetState(snapshot);
+  if (requested <= current.token_budget) {
+    throw new Error("Provider token budget must be higher than the current limit.");
+  }
+  if (requested <= current.tokens_used) {
+    throw new Error("Provider token budget must be higher than the Provider tokens already used.");
+  }
+  snapshot.charter.token_budget = requested;
+  return refreshBudgetState(snapshot);
+}
+
 export function budgetState(snapshot, pendingAttempt = null) {
   const attempts = [
     ...(Array.isArray(snapshot?.attempts) ? snapshot.attempts : []),
@@ -93,7 +129,7 @@ function recordTokenTotal(value) {
 function normalizeTokenBudget(value) {
   const parsed = integer(value);
   if (parsed === null || parsed <= 0) return DEFAULT_TOKEN_BUDGET;
-  return Math.min(MAX_TOKEN_BUDGET, parsed);
+  return Math.min(MAX_PROVIDER_TOKEN_BUDGET, parsed);
 }
 
 function normalizeRetryBudget(value, maxAttempts) {

package/src/orchestrator/loop.js

@@ -469,7 +469,7 @@ async function stopForBudget({ snapshot, attempt, reason, onUpdate }) {
   if (attempt) attempt.budget = budget;
   const message =
     reason === "token_budget_exhausted"
-      ? "Agentic loop exhausted its token budget."
+      ? "Agentic loop reached its Provider token budget."
       : "Agentic loop exhausted its retry budget.";
   appendEvent(snapshot, "blocked", message, {
     code: reason,
@@ -487,8 +487,8 @@ function budgetFinding(reason, budget) {
       passed: false,
       code: "TOKEN_BUDGET_EXHAUSTED",
       severity: "blocker",
-      target: "token_budget",
-      explanation: `The run used ${budget.tokens_used} of ${budget.token_budget} provider tokens, so no additional executor or reviewer call can start.`,
+      target: "provider_token_budget",
+      explanation: `The run used ${budget.tokens_used} of ${budget.token_budget} Provider tokens, so no additional executor or reviewer call can start until the Provider token budget is increased. Provider tokens are not billed as SIMY tokens.`,
       repairability: "manual",
       auto_fix_hint: null,
     };

package/src/orchestrator/recovery.js

@@ -1,3 +1,5 @@
+import { suggestedProviderTokenBudget } from "./budget.js";
+
 const RECOVERABLE_STATES = new Set(["waiting_human", "blocked", "failed"]);
 
 export function recoveryContractForEvent({ snapshot, state, message, detail = {} }) {
@@ -6,7 +8,7 @@ export function recoveryContractForEvent({ snapshot, state, message, detail = {}
 
   const reasonCode = recoveryReasonCode(state, message, detail);
   const attemptNumber = positiveInteger(detail.attempt_number);
-  const actions = recoveryActions(reasonCode);
+  const actions = recoveryActions(reasonCode, detail.budget);
   return {
     schema_version: 1,
     state,
@@ -18,6 +20,8 @@ export function recoveryContractForEvent({ snapshot, state, message, detail = {}
       event_code: clean(detail.code) || null,
       attempt_number: attemptNumber,
       max_attempts: positiveInteger(snapshot?.charter?.max_attempts),
+      provider_token_budget: positiveInteger(snapshot?.charter?.token_budget),
+      provider_tokens_used: nonNegativeInteger(detail?.budget?.tokens_used),
       token_budget: positiveInteger(snapshot?.charter?.token_budget),
       retry_budget: nonNegativeInteger(snapshot?.charter?.retry_budget),
       tokens_used: nonNegativeInteger(detail?.budget?.tokens_used),
@@ -136,7 +140,7 @@ function recoveryMessage(reasonCode) {
       "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.",
+      "This run reached its Provider token safety limit. Provider tokens are not billed by SIMY. Increase the limit to continue this run.",
     retry_budget_exhausted:
       "This run used its automatic retry budget. Start a new run to continue with a fresh limit.",
     automatic_progress_blocked:
@@ -149,7 +153,7 @@ function recoveryMessage(reasonCode) {
   return messages[reasonCode] || messages.automatic_progress_blocked;
 }
 
-function recoveryActions(reasonCode) {
+function recoveryActions(reasonCode, budget = null) {
   if (reasonCode === "repository_authorization_required") {
     return [
       {
@@ -182,7 +186,25 @@ function recoveryActions(reasonCode) {
       newRunAction(),
     ];
   }
-  if (reasonCode === "token_budget_exhausted" || reasonCode === "retry_budget_exhausted") {
+  if (reasonCode === "token_budget_exhausted") {
+    const suggestedBudget = suggestedProviderTokenBudget(budget);
+    if (!suggestedBudget || budget?.retry_exhausted === true) return [newRunAction()];
+    return [
+      {
+        id: "increase_provider_token_budget",
+        type: "increase_provider_token_budget",
+        label: "Increase Provider token budget",
+        description:
+          "Raise this run's safety limit and continue. Provider tokens are usage diagnostics and are not billed as SIMY tokens.",
+        command: null,
+        payload: {
+          ...(suggestedBudget ? { suggested_provider_token_budget: suggestedBudget } : {}),
+        },
+      },
+      newRunAction(),
+    ];
+  }
+  if (reasonCode === "retry_budget_exhausted") {
     return [newRunAction()];
   }
   if (reasonCode === "local_execution_interrupted") {

package/src/runner.js

@@ -19,7 +19,7 @@ import {
   redactExecutionText,
 } from "./orchestrator/execution-io.js";
 import { summarizeCodingLoopEvent } from "./orchestrator/presentation.js";
-import { refreshBudgetState } from "./orchestrator/budget.js";
+import { increaseProviderTokenBudget, refreshBudgetState } from "./orchestrator/budget.js";
 import { appendEvent } from "./orchestrator/shared.js";
 import {
   createProviderStreamDecoder,
@@ -252,6 +252,35 @@ export async function continueLocalCodingRun(run, guidance, dependencies = {}) {
   return executeLocalCodingRun(run, dependencies, { humanGuidance: message, resume: true });
 }
 
+export async function increaseLocalCodingRunProviderTokenBudget(run, value) {
+  if (run.operation || run.child) {
+    throw new Error("Provider token budget can change only while the run is waiting.");
+  }
+  if (!RESUMABLE_STATES.has(run.status)) {
+    throw new Error("Provider token budget can change only for a blocked or waiting run.");
+  }
+  const currentBudget = refreshBudgetState(run.snapshot);
+  if (currentBudget.retry_exhausted) {
+    throw new Error("The Agentic Loop run also used its retry budget. Start a new run to continue.");
+  }
+  const previousBudget = currentBudget.token_budget;
+  const budget = increaseProviderTokenBudget(run.snapshot, value);
+  run.request.token_budget = budget.token_budget;
+  appendEvent(
+    run.snapshot,
+    "waiting_human",
+    `Provider token budget increased from ${previousBudget} to ${budget.token_budget}.`,
+    {
+      code: "provider_token_budget_increased",
+      previous_provider_token_budget: previousBudget,
+      provider_token_budget: budget.token_budget,
+      budget,
+    },
+  );
+  await updateRun(run, "waiting_human");
+  return budget;
+}
+
 export async function continueLocalCodingRunAfterRepositoryApproval(
   run,
   { repository, localPath } = {},