@remits/remits-cli 0.1.80 → 0.1.81

package/index.js

@@ -413,6 +413,18 @@ function writeToolResponseFile(cwd, callId, responsePayload) {
   return file;
 }
 
+function readToolResponseFile(cwd, callId) {
+  if (!callId) return null;
+  const paths = ensureLocalState(cwd);
+  const file = path.join(paths.toolResponsesDir, callId + '.json');
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (_) {
+    return null;
+  }
+}
+
 function normalizeName(name) {
   return name.replace(/([a-z])([A-Z])/g, '$1 $2').replace(/\s+/g, ' ').trim();
 }
@@ -1191,9 +1203,14 @@ function collectComponents(cwd) {
   return components;
 }
 
-function buildAxios(baseUrl, token) {
+function parsePositiveInt(value, fallback) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
+
+function buildAxios(baseUrl, token, timeoutMs = 60000) {
   const headers = token ? { Authorization: 'Bearer ' + token } : {};
-  return axios.create({ baseURL: baseUrl, timeout: 60000, headers });
+  return axios.create({ baseURL: baseUrl, timeout: parsePositiveInt(timeoutMs, 60000), headers });
 }
 
 function describeError(err) {
@@ -1934,6 +1951,37 @@ async function waitForStatus(api, cwd, accountId, branchName, taskId, token, dat
   }
 }
 
+async function waitForToolStatus(api, cwd, options) {
+  const started = Date.now();
+  let pollDelayMs = parsePositiveInt(options.pollIntervalMs, 1000);
+  const maxPollDelayMs = parsePositiveInt(options.maxPollIntervalMs, 5000);
+  const deadline = options.waitTimeoutMs ? (started + parsePositiveInt(options.waitTimeoutMs, 0)) : null;
+
+  while (true) {
+    const statusResponse = await loggedPost(api, cwd, '/cli/tool', {
+      token: options.token,
+      command: 'status',
+      accountId: options.accountId,
+      accountIdExplicit: options.accountIdExplicit,
+      branchName: options.branchName,
+      dataMode: options.dataMode,
+      callId: options.callId
+    }, { toolResponseFile: true, toolCallId: options.callId });
+
+    const status = statusResponse.data;
+    if (status.status === 'completed' || status.status === 'failed') {
+      return { data: status, responseFile: statusResponse.responseFile };
+    }
+
+    if (deadline && Date.now() >= deadline) {
+      throw new Error('Timed out waiting for async tool call ' + options.callId + ' after ' + (Date.now() - started) + 'ms');
+    }
+
+    await new Promise((r) => setTimeout(r, pollDelayMs));
+    pollDelayMs = Math.min(maxPollDelayMs, pollDelayMs + 500);
+  }
+}
+
 function watchWebsocket(baseUrl, topicId, taskId) {
   const client = new Client({
     brokerURL: webSocketUrl(baseUrl),
@@ -2130,8 +2178,10 @@ async function toolCommand(flags) {
   const sessionContext = resolveSessionContext(cwd, flags);
   const { session, accountId } = sessionContext;
 
+  const subcommand = flags._ && flags._[1];
+  const statusMode = subcommand === 'status' || flagEnabled(flags.status);
   const toolName = flags.name || flags.tool;
-  if (!toolName) {
+  if (!toolName && !statusMode) {
     throw new Error('Missing --name <toolName>');
   }
 
@@ -2144,8 +2194,48 @@ async function toolCommand(flags) {
   const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
   const branchName = flags.branch || currentBranch(cwd);
   const dataMode = resolveDataMode(flags, session);
-  const callId = crypto.randomUUID();
-  const api = buildAxios(baseUrl, session.token);
+  const timeoutMs = parsePositiveInt(flags['timeout-ms'] || flags.timeoutMs, 60000);
+  const callId = String(flags['call-id'] || flags.callId || crypto.randomUUID());
+  const asyncMode = flagEnabled(flags.async) || flagEnabled(input.async);
+  const waitForAsync = flagEnabled(flags.wait);
+  const pollIntervalMs = parsePositiveInt(flags['poll-interval-ms'] || flags.pollIntervalMs, 1000);
+  const waitTimeoutMs = flags['wait-timeout-ms'] || flags.waitTimeoutMs;
+  const api = buildAxios(baseUrl, session.token, timeoutMs);
+
+  if (statusMode) {
+    const requestedCallId = String(flags['call-id'] || flags.callId || '');
+    if (!requestedCallId) {
+      throw new Error('Missing --call-id <callId>');
+    }
+
+    const stored = readToolResponseFile(cwd, requestedCallId);
+    const statusAccountId = flags['account-id'] || (stored && stored.accountId) || accountId;
+    const statusResponse = await loggedPost(api, cwd, '/cli/tool', {
+      token: session.token,
+      command: 'status',
+      accountId: statusAccountId,
+      accountIdExplicit: accountIdExplicit || Boolean(stored && stored.accountId),
+      branchName: flags.branch || (stored && stored.branchName) || branchName,
+      dataMode: flags['data-mode'] || (stored && stored.dataMode) || dataMode,
+      callId: requestedCallId
+    }, { toolResponseFile: true, toolCallId: requestedCallId });
+
+    const data = statusResponse.data;
+    if (!data.success) {
+      throw new Error(data.message || 'Tool status lookup failed');
+    }
+
+    printSessionResolutionWarning(sessionContext);
+    printResolvedBaseUrl(baseUrl);
+    console.log('Tool call status:', data.status);
+    console.log('Call ID:', requestedCallId);
+    console.log('Data mode:', data.dataMode || dataMode);
+    if (data.threadGroupingId) console.log('Thread grouping ID:', data.threadGroupingId);
+    console.log('Session log:', sessionJsonlFile(cwd));
+    console.log('Tool response file:', statusResponse.responseFile);
+    if (data.status === 'failed') process.exitCode = 1;
+    return;
+  }
 
   const response = await loggedPost(api, cwd, '/cli/tool', {
     token: session.token,
@@ -2155,7 +2245,8 @@ async function toolCommand(flags) {
     dataMode,
     name: String(toolName),
     input,
-    callId
+    callId,
+    async: asyncMode
   }, { toolResponseFile: true, toolCallId: callId });
 
   const data = response.data;
@@ -2165,9 +2256,11 @@ async function toolCommand(flags) {
 
   printSessionResolutionWarning(sessionContext);
   printResolvedBaseUrl(baseUrl);
-  console.log('Tool call succeeded.');
+  console.log(asyncMode ? 'Tool call started.' : 'Tool call succeeded.');
   console.log('Call ID:', callId);
-  console.log('Data mode:', dataMode);
+  console.log('Data mode:', data.dataMode || dataMode);
+  if (data.status) console.log('Status:', data.status);
+  if (data.threadGroupingId) console.log('Thread grouping ID:', data.threadGroupingId);
   // Make the resolved component version explicit so callers never assume staged vs DB.
   if (data.componentSource) {
     const sig = data.componentSignature ? ` (${data.componentSignature})` : '';
@@ -2175,6 +2268,25 @@ async function toolCommand(flags) {
   }
   console.log('Session log:', sessionJsonlFile(cwd));
   console.log('Tool response file:', response.responseFile);
+
+  if (asyncMode && waitForAsync) {
+    const finalStatus = await waitForToolStatus(api, cwd, {
+      token: session.token,
+      accountId: data.accountId || accountId,
+      accountIdExplicit: true,
+      branchName: data.branchName || branchName,
+      dataMode: data.dataMode || dataMode,
+      callId,
+      pollIntervalMs,
+      waitTimeoutMs
+    });
+
+    console.log('Final status:', finalStatus.data.status);
+    console.log('Tool response file:', finalStatus.responseFile);
+    if (finalStatus.data.status !== 'completed') {
+      process.exitCode = 1;
+    }
+  }
 }
 
 async function dataModeCommand(flags, subcommand) {
@@ -4550,7 +4662,8 @@ async function main() {
     console.log('  remits-cli data-mode [set test|prod]');
     console.log('  remits-cli install --skills [--target codex|claude|gemini|all] [--overwrite true]');
     console.log('  remits-cli tools [--base-url URL] [--account-id ID] [--data-mode test|prod]');
-    console.log('  remits-cli tool --name <toolName> [--base-url URL] [--input \"{...}\"|--input-file file.json] [--data-mode test|prod]');
+    console.log('  remits-cli tool --name <toolName> [--base-url URL] [--input \"{...}\"|--input-file file.json] [--data-mode test|prod] [--timeout-ms 60000] [--async true --wait true]');
+    console.log('  remits-cli tool status --call-id <callId> [--base-url URL] [--account-id ID] [--data-mode test|prod]');
     console.log('  remits-cli components stage [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--json|--verbose]');
     console.log('  remits-cli components status [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE --component-id ID] [--json|--verbose]');
     console.log('  remits-cli components clear [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE] [--component-id ID] [--all] [--json|--verbose]');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remits/remits-cli",
-  "version": "0.1.80",
+  "version": "0.1.81",
   "description": "Local CLI for auth, component sync, and live test execution against Remits",
   "license": "MIT",
   "private": false,

package/skills/remits-cli/SKILL.md

@@ -5,6 +5,85 @@ description: Use remits-cli for fast branch-scoped component staging, test execu
 
 # remits-cli
 
+## Table of Contents
+
+- Line 89: Account Targeting Model
+- Line 112: Component Integrity Rules: Repo ↔ Database Reconciliation (read before any sync/commit)
+- Line 118: How the platform reconciles the repo into the database (the mechanism you must understand)
+- Line 144: The surfaces and their intended behavior
+- Line 166: Intended workflows
+- Line 185: Pre-sync safety check (confirm ALL before `components sync` or `components commit`)
+- Line 195: If something looks wrong — stop, don't paper over
+- Line 219: Required Local Index Reads
+- Line 253: Big Picture: How remits-cli State Is Organized
+- Line 283: Support Ticket Mental Model
+- Line 319: Efficiency Rules
+- Line 331: Account Repository Index
+- Line 356: Two Workflows
+- Line 363: Test Mode vs Prod Mode
+- Line 395: Platform Mental Model: Front Stage vs Back Stage
+- Line 402: Documents vs Records
+- Line 412: HTTP Audits
+- Line 466: Record `content` / Context Mental Model
+- Line 486: Provenance Fields
+- Line 504: Why Persisted Context Looks Different From Runtime Context
+- Line 525: Investigation Rule for Record Context
+- Line 540: AI Request Response Records
+- Line 547: AI Session Groupings
+- Line 562: Correlation Keys
+- Line 568: Node Reference Table
+- Line 578: Repository vs External Context
+- Line 585: Getting Started
+- Line 587: Authentication
+- Line 600: Host vs Data Mode
+- Line 619: Tool Execution Lifecycle
+- Line 660: Data Mode
+- Line 670: Development Workflow
+- Line 672: The Golden Rule: Writing Code Is Not Finishing the Job
+- Line 684: The Development Fast Loop
+- Line 843: User Confirmation Preferences
+- Line 853: Component Resolution: Staging Cache vs DB (which "version" actually runs)
+- Line 859: The two source layers + the compile cache
+- Line 870: Staging cache key format
+- Line 883: How the platform picks staged vs DB (the compile signature)
+- Line 900: When staged overrides apply
+- Line 924: Diagnosing which version is in play
+- Line 945: Stage / commit / clear with the MCP tools
+- Line 969: Stale after sync / commit (the in-memory compile cache)
+- Line 979: Production Support Workflow
+- Line 987: Investigation Strategy
+- Line 1017: Presenting Findings
+- Line 1025: Verifying a Production Issue Fix
+- Line 1038: Tool Reference
+- Line 1040: Execute a Tool
+- Line 1067: `mcp_account_view`
+- Line 1074: `mcp_firestore_search`
+- Line 1112: `mcp_object_activity`
+- Line 1121: `mcp_record_listing`
+- Line 1146: `mcp_record_view`
+- Line 1159: `mcp_ai_session_search`
+- Line 1191: `mcp_run_action`
+- Line 1229: `mcp_run_agent`
+- Line 1267: `mcp_system_logs`
+- Line 1290: `mcp_component_view`
+- Line 1308: `mcp_component_grep`
+- Line 1321: `mcp_support_ticket`
+- Line 1370: `mcp_run_test`
+- Line 1379: `mcp_component_edit`
+- Line 1394: `mcp_component_create`
+- Line 1408: `mcp_component_commit`
+- Line 1416: `mcp_cache`
+- Line 1428: Multi-Session Support
+- Line 1448: Persistent Service, Control Center, and Agent Dispatch
+- Line 1457: Starting the Service
+- Line 1483: Control Center
+- Line 1498: Agent Dispatch
+- Line 1519: Configuring the Preferred Agent
+- Line 1530: Local State Files
+- Line 1578: Command Reference
+- Line 1605: Troubleshooting
+- Line 1632: When Something Doesn't Work as Expected
+
 `remits-cli` is the brainstem for both **development** and **production support**. You might run it inside an account repository (where `account-info.json` and `/components` already exist) or from outside any repo when a user needs help on another account. Your users are business professionals — they think in terms of what they can see in a browser.
 
 ## Account Targeting Model
@@ -537,6 +616,47 @@ remits-cli tool --base-url http://localhost:8080 --name mcp_account_view --data-
 
 Do not assume `--data-mode prod` implies the deployed prod host, or that `--data-mode test` implies localhost. If host matters, read `~/.remits-cli/sessions.json` first and pass `--base-url` explicitly.
 
+### Tool Execution Lifecycle
+
+`remits-cli tool` supports both synchronous and asynchronous execution.
+
+Use normal synchronous execution for quick investigation tools:
+
+```bash
+remits-cli tool --name "mcp_account_view" --input '{"accountId": 37}' --data-mode prod
+```
+
+Use asynchronous execution for long-running tools, especially Action or Agent runners that can perform OCR,
+AI calls, document writes, or multi-step workflows:
+
+```bash
+remits-cli tool --name "mcp_run_action" --async true --input '{"accountId":49,"actionId":200,"executionMode":"async","actionInput":{"sourceDocumentId":"..."}}' --data-mode prod
+```
+
+Async starts return immediately with a stable `callId`, `status:"running"`, `threadGroupingId`,
+`accountId`, `branchName`, `dataMode`, and component provenance when available. The full response is saved to:
+
+```text
+./.remits-cli/tool-responses/<callId>.json
+```
+
+Poll or resume an async CLI tool call by call id:
+
+```bash
+remits-cli tool status --call-id <callId> --data-mode prod
+```
+
+If you want the CLI process to wait locally while using short polling requests instead of one long HTTP
+request, pass `--wait true`:
+
+```bash
+remits-cli tool --name "mcp_run_agent" --async true --wait true --input '{"accountId":49,"agentName":"InvoiceAuditor","message":"...","executionMode":"async"}' --data-mode prod
+```
+
+`--timeout-ms <ms>` controls the HTTP timeout for each individual CLI request. It is useful for slower
+synchronous tools, but for multi-minute Actions/Agents prefer `--async true` so the server-side work is not
+tied to one HTTP connection.
+
 ### Data Mode
 
 Controls whether you work with test data or production data. **Default is `test`.**
@@ -640,6 +760,13 @@ For changes to Readers, Actions, or Rules that process data rather than display
 remits-cli tool --name "mcp_firestore_search" --input '{"accountId": <ID>, "collection": "<collection>", "limit": 5, "sort": [{"field": "_lastModifiedAt", "direction": "DESC"}]}'
 ```
 
+For long-running backend verification, prefer async tool execution and poll by `callId` rather than relying on
+a single request to stay open:
+
+```bash
+remits-cli tool --name "mcp_run_action" --async true --wait true --input '{"accountId": <ID>, "actionId": <ACTION_ID>, "executionMode": "async", "actionInput": {...}}' --data-mode test
+```
+
 #### Step 5: Iterate If Needed
 
 If verification reveals issues, repeat the loop: **edit → stage → run**. Every iteration must include a fresh `remits-cli components stage` after your edits and before the next test run. Never run a test immediately after editing without staging first — the platform will execute the previous version, not your latest changes.
@@ -918,6 +1045,17 @@ remits-cli tool --name "mcp_firestore_search" --input '{"accountId": 37, "collec
 
 Response saved to `./.remits-cli/tool-responses/<callId>.json`. Read the file to see results.
 
+For long-running tools, use async mode:
+
+```bash
+remits-cli tool --name "mcp_run_action" --async true --input '{"accountId":37,"actionName":"Rebuild Invoice","executionMode":"async","actionInput":{"invoiceId":"abc"}}' --data-mode prod
+remits-cli tool status --call-id <callId> --data-mode prod
+```
+
+Use `--wait true` when you want the CLI to poll until completion and still avoid a single long HTTP request.
+Use `--timeout-ms <ms>` only to adjust the per-request client timeout; it is not a replacement for async mode
+on multi-minute workflows.
+
 **Account-id precedence for tool calls.** When the CLI and the tool input both carry an account id, the server resolves them in this order:
 
 1. Explicit `--account-id <ID>` flag — always wins. Use this when you want to be certain the tool runs against a specific account (and the user's session covers it).
@@ -1050,6 +1188,82 @@ Front-stage references:
 
 Use `action: "search"` first, then `action: "detail"` with the returned `groupingKey` when you want the human-readable export for investigation or tuning.
 
+### `mcp_run_action`
+Run an Action on a target account, with explicit prod/test data mode, optional staged branch resolution, and
+staged-vs-DB provenance in the result.
+
+Use direct mode only for quick Actions:
+
+```bash
+remits-cli tool --name mcp_run_action --input '{"accountId":49,"actionId":200,"executionMode":"direct","actionInput":{"sourceDocumentId":"..."}}' --data-mode prod
+```
+
+Use async mode for long-running direct Action execution:
+
+```bash
+remits-cli tool --name mcp_run_action --async true --input '{"accountId":49,"actionId":200,"executionMode":"async","actionRunId":"optional-stable-id","actionInput":{"sourceDocumentId":"..."}}' --data-mode prod
+```
+
+Then poll the CLI call:
+
+```bash
+remits-cli tool status --call-id <callId> --data-mode prod
+```
+
+Or poll the tool-level run from another tool/agent context:
+
+```json
+{"command":"status","accountId":49,"actionRunId":"<actionRunId>"}
+```
+
+For job-style Actions (`Action.job == true`), prefer `executionMode:"event"` when you want the durable Event
+lifecycle, Event status, and platform recovery behavior:
+
+```json
+{"accountId":49,"actionId":200,"executionMode":"event","actionInput":{...}}
+```
+
+Key returned fields: `actionRunId`, `status`, `executionMode`, `threadGroupingId`, `eventId`/`eventStatus`
+for Event mode, `componentSource`, `componentSignature`, `result`, `message`, and `error`.
+
+### `mcp_run_agent`
+Run one real Agent turn on a target account. The Agent hooks and tools execute for real against the requested
+`dataMode`; pass `dataMode:"test"` for safer tuning.
+
+Use direct mode only for short turns:
+
+```bash
+remits-cli tool --name mcp_run_agent --input '{"accountId":49,"agentName":"InvoiceAuditor","message":"Summarize this invoice context","executionMode":"direct"}' --data-mode prod
+```
+
+Use async mode for autonomous or long Agent turns. Async mode returns both an `agentRunId` and a concrete
+`sessionId` immediately:
+
+```bash
+remits-cli tool --name mcp_run_agent --async true --input '{"accountId":49,"agentName":"InvoiceAuditor","message":"Audit this invoice","executionMode":"async","context":{"invoiceId":"..."}}' --data-mode prod
+```
+
+Poll the CLI call:
+
+```bash
+remits-cli tool status --call-id <callId> --data-mode prod
+```
+
+Or poll the tool-level agent run:
+
+```json
+{"command":"status","accountId":49,"agentRunId":"<agentRunId>"}
+```
+
+Inspect the AI session while it is running or after it completes:
+
+```bash
+remits-cli tool --name mcp_ai_session_search --input '{"action":"detail","sessionId":"<sessionId>","summaryOnly":true}' --data-mode prod
+```
+
+Key returned fields: `agentRunId`, `sessionId`, `status`, `threadGroupingId`, runtime pause/interruption
+hints, `lastAssistantMessage`, `toolCallCount`, `result`, `message`, and `error`.
+
 ### `mcp_system_logs`
 Query Cloud Run service logs.
 
@@ -1380,7 +1594,8 @@ remits-cli components commit [--message "msg"] [--data-mode test|prod]
 remits-cli test run --test <id|name> [--names "a,b"] [--watch true|false] [--data-mode test|prod]
 remits-cli token [--path <embeddablePathOrId>] [--data-mode test|prod]
 remits-cli tools [--branch <name>] [--data-mode test|prod]
-remits-cli tool --name <toolName> [--branch <name>] [--input "{...}"] [--data-mode test|prod]
+remits-cli tool --name <toolName> [--branch <name>] [--input "{...}"] [--data-mode test|prod] [--timeout-ms 60000] [--async true --wait true]
+remits-cli tool status --call-id <callId> [--data-mode test|prod]
 ```
 
 For tests specifically:
@@ -1402,6 +1617,8 @@ For tests specifically:
 | 500 / `Internal Server Error` from Remits | Stop normal task work. Capture the exact command, error, and response artifact, then escalate to a Remits system admin. Do not invent a workaround. |
 | Tool parameters rejected | Tool schemas may be cached. Run `remits-cli tools` to refresh `.remits-cli/tools/tools.json` with latest schemas. |
 | Tool response missing | Check `./.remits-cli/tool-responses/` |
+| Long-running tool times out | Prefer `remits-cli tool --async true` and poll with `remits-cli tool status --call-id <callId>`. Use `--timeout-ms` only for the per-request HTTP timeout. |
+| Need to continue tracking a long Action or Agent after terminal disconnect | Read `./.remits-cli/tool-responses/<callId>.json` for the returned `threadGroupingId`, `actionRunId`, `agentRunId`, or `sessionId`, then poll status or inspect with `mcp_ai_session_search`. |
 | Staged change has no effect in a live (non-CLI) run | Staged overrides resolve only under a CLI TestMode (`branchName`+`cliUserId`). Live webhooks and other non-CLI runtime paths still use the DB. `commit` to make it durable. See "Component Resolution". |
 | New source shown by `mcp_component_view` but old behavior persists after sync/commit | The compile cache (`CLOSURE_CACHE`) is keyed by `version:<N>:<sourceHash12>`, so a source change on the same version now invalidates it automatically — a run right after sync/commit picks up the new source. If old behavior still persists, confirm the run actually hit the synced instance and that no staged override is still shadowing DB (`remits-cli components status`). |
 | Staged Reader test run throws `No enum constant ObjectType.<family>` | The staged entry has the component family in `type` (should be `kind`). Clear + re-stage; if it persists, the `mcp_component_edit` tool on that instance is on an old/cached version. Inspect with `mcp_cache`. |