troxy-cli 1.14.0 → 1.16.0

package/README.md

@@ -78,7 +78,7 @@ Checkpoints an agent can call:
 | `evaluate_login` | logging into or signing up for a site |
 | `evaluate_model` | running a task on a model, and on any model or effort switch |
 | `report_model_usage` | (after) reporting the real token total |
-| `wait_for_payment_approval` | (after ESCALATE) waiting on the owner's decision |
+| `wait_for_approval` | (after ESCALATE) waiting on the owner's decision |
 
 The model checkpoint is the only one that is a required pair. `evaluate_model`
 records what a run is expected to cost; `report_model_usage` records what it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "troxy-cli",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "description": "Control layer for AI agents: check payments, emails, logins and destructive actions against your policies",
   "homepage": "https://troxy.io",
   "bugs": {

package/src/api.js

@@ -1,7 +1,23 @@
+import { createRequire } from 'node:module';
+
 export const BASE_URL =
   process.env.TROXY_API_URL ||
   'https://api.troxy.io';
 
+// Reported on every heartbeat so the dashboard can explain an empty page.
+//
+// Checkpoints an old CLI does not expose simply never fire, and the affected
+// page just looks blank: before 1.14.0 there was no evaluate_model tool at all,
+// so Token Optimization stayed empty forever with nothing saying why. Knowing
+// the version turns that into a sentence the user can act on.
+export const CLI_VERSION = (() => {
+  try {
+    return createRequire(import.meta.url)('../package.json').version;
+  } catch {
+    return null;
+  }
+})();
+
 async function request(method, path, { apiKey, jwt, body } = {}) {
   const headers = { 'Content-Type': 'application/json' };
   if (apiKey) headers['X-Troxy-Key'] = apiKey;
@@ -85,7 +101,15 @@ export const api = {
   waitApprovalStatus: (token) => request('GET', `/approvals/${encodeURIComponent(token)}/wait`),
 
   // MCP heartbeat (agent API key)
-  mcpHeartbeat: (apiKey, agentName, force) => request('POST', '/mcp/heartbeat', { apiKey, body: agentName ? { agent_name: agentName, force_name: !!force } : undefined }),
+  // cli_version goes on every heartbeat, including the ones that carry no
+  // agent name, so a long-running agent that never re-inits still reports it.
+  mcpHeartbeat: (apiKey, agentName, force) => request('POST', '/mcp/heartbeat', {
+    apiKey,
+    body: {
+      cli_version: CLI_VERSION,
+      ...(agentName ? { agent_name: agentName, force_name: !!force } : {}),
+    },
+  }),
 
   // MCP status (agent API key — no login needed)
   mcpStatus:  (apiKey) => request('GET', '/mcp/status', { apiKey }),

package/src/mcp-server.js

@@ -36,17 +36,17 @@ export async function runMcp() {
       name: 'troxy',
       version: '0.1.0',
       instructions:
-        'You are connected to Troxy, a payment control system. ' +
+        'You are connected to Troxy, a control layer for agent actions: payments, emails, logins, destructive actions, and model spend. ' +
         'You MUST call the evaluate_payment tool before completing any purchase, payment, or financial transaction. ' +
         'Never submit a payment form, confirm a checkout, or transfer funds without first receiving an ALLOW decision from evaluate_payment. ' +
         'If the decision is BLOCK, abort the transaction and inform the user. ' +
-        'If the decision is ESCALATE, the response includes an approval_token. Immediately call wait_for_payment_approval with that token; it polls automatically until the payment is approved or declined (up to 10 minutes). Once it returns approved, call evaluate_payment again with the same payment details PLUS the approval_token field. The second call will return ALLOW without re-escalating. ' +
+        'If the decision is ESCALATE, the response includes an approval_token. Immediately call wait_for_approval with that token; it polls automatically until the request is approved or declined (up to 10 minutes). Once it returns approved, call evaluate_payment again with the same payment details PLUS the approval_token field. The second call will return ALLOW without re-escalating. ' +
         'If the decision is NOTIFY, proceed but the user will be notified. ' +
         'When calling evaluate_payment, use the merchant\'s domain name as merchant_name when available (e.g. "amazon.com", "indigobloom.co.il"); this ensures consistent matching against policies. ' +
         'After every ALLOW or NOTIFY decision, attempt the payment, then call confirm_payment with the audit_id and the outcome (success/failed/cancelled). Always include a reason when the charge fails. ' +
-        'You MUST also call the evaluate_email tool before sending any email on the user\'s behalf. Always include the full plaintext "body" argument, exactly as you intend to send it — Troxy policies inspect the body for secrets and confidential content, and cannot do so if it is omitted, summarized, or truncated. When the email goes to more than one person (a reply-all, a group, a bulk send), also pass every To/Cc/Bcc address in "recipients" so mass-email policies can apply. Never send an email without first receiving an ALLOW or NOTIFY decision. If BLOCK, do not send it. If ESCALATE, call wait_for_payment_approval with the returned approval_token (same wait mechanism payments use), then call evaluate_email again with the approval_token once approved. ' +
+        'You MUST also call the evaluate_email tool before sending any email on the user\'s behalf. Always include the full plaintext "body" argument, exactly as you intend to send it — Troxy policies inspect the body for secrets and confidential content, and cannot do so if it is omitted, summarized, or truncated. When the email goes to more than one person (a reply-all, a group, a bulk send), also pass every To/Cc/Bcc address in "recipients" so mass-email policies can apply. Never send an email without first receiving an ALLOW or NOTIFY decision. If BLOCK, do not send it. If ESCALATE, call wait_for_approval with the returned approval_token, then call evaluate_email again with the approval_token once approved. ' +
         'You MUST also call the evaluate_action tool before any destructive or hard-to-undo action on the user\'s behalf: deleting files or records, dropping or truncating a table, force-pushing or deleting a branch, destroying infrastructure, revoking access, or overwriting data. Give the verb, what it affects, how many items, and whether it can be undone. Never carry the action out without first receiving an ALLOW or NOTIFY decision. ' +
-        'You MUST also call the evaluate_login tool before logging into or signing up for any website on the user\'s behalf, giving the site\'s domain and whether it is a login or a signup. Never submit login credentials or a signup form without first receiving an ALLOW or NOTIFY decision. If BLOCK, do not proceed. If ESCALATE, call wait_for_payment_approval with the returned approval_token, then call evaluate_login again with the approval_token once approved. ' +
+        'You MUST also call the evaluate_login tool before logging into or signing up for any website on the user\'s behalf, giving the site\'s domain and whether it is a login or a signup. Never submit login credentials or a signup form without first receiving an ALLOW or NOTIFY decision. If BLOCK, do not proceed. If ESCALATE, call wait_for_approval with the returned approval_token, then call evaluate_login again with the approval_token once approved. ' +
         // The model checkpoint is the only one that is a pair. The estimate on
         // its own is the agent's own prediction, and the dashboard labels every
         // agent that never reports back as unverified, so the instruction has
@@ -94,9 +94,10 @@ export async function runMcp() {
         },
       },
       {
-        name: 'wait_for_payment_approval',
+        name: 'wait_for_approval',
         description:
-          'Poll Troxy every 10 seconds until a pending payment approval is resolved. ' +
+          'Poll Troxy every 10 seconds until a pending approval is resolved. ' +
+          'Applies to every ESCALATE decision from any evaluate_* tool (payment, email, login, action, or model), not just payments. ' +
           'Call this immediately after receiving an ESCALATE decision. ' +
           'It will block until the account owner approves or declines (up to 10 minutes), then return the result automatically.',
         inputSchema: {
@@ -339,7 +340,7 @@ export async function runMcp() {
     const toolName = request.params.name;
     const args = request.params.arguments ?? {};
 
-    if (toolName === 'wait_for_payment_approval') {
+    if (toolName === 'wait_for_approval') {
       const { approval_token } = args;
       const MAX_MS   = 60 * 60_000; // overall cap: 1 hour
       const deadline = Date.now() + MAX_MS;
@@ -359,19 +360,19 @@ export async function runMcp() {
 
         if (status.status === 'APPROVED') {
           return {
-            content: [{ type: 'text', text: `✅ Payment approved! Call evaluate_payment again with the same payment details and approval_token: "${approval_token}" to proceed.` }],
+            content: [{ type: 'text', text: `✅ Approved! Call the same evaluate_* tool again with the original arguments and approval_token: "${approval_token}" to proceed.` }],
             isError: false,
           };
         }
         if (status.status === 'DECLINED') {
           return {
-            content: [{ type: 'text', text: `❌ Payment declined by the account owner. Do not proceed with this payment.` }],
+            content: [{ type: 'text', text: `❌ Declined by the account owner. Do not proceed with this action.` }],
             isError: true,
           };
         }
         if (status.status === 'EXPIRED') {
           return {
-            content: [{ type: 'text', text: `⏱ Approval request has expired. The payment cannot be approved.` }],
+            content: [{ type: 'text', text: `⏱ Approval request has expired. It cannot be approved; re-run the evaluate_* call to start over if still needed.` }],
             isError: true,
           };
         }
@@ -430,7 +431,7 @@ export async function runMcp() {
           emailText = `✗ Email blocked.${reason ? ` ${reason}` : ''} Do not send it. (audit: ${audit_id})`;
           break;
         case 'ESCALATE':
-          emailText = `⏳ Email requires human approval; a request has been sent to the account owner.\n\nApproval token: ${approval_token}\n\nNow call wait_for_payment_approval(approval_token="${approval_token}") to automatically detect approval, then call evaluate_email again with the same recipient/recipients/subject/body PLUS this approval_token. Do not send until it returns approved.`;
+          emailText = `⏳ Email requires human approval; a request has been sent to the account owner.\n\nApproval token: ${approval_token}\n\nNow call wait_for_approval(approval_token="${approval_token}") to automatically detect approval, then call evaluate_email again with the same recipient/recipients/subject/body PLUS this approval_token. Do not send until it returns approved.`;
           break;
         default:
           emailText = JSON.stringify(result);
@@ -464,7 +465,7 @@ export async function runMcp() {
           actionText = `✗ Blocked: ${what}.${reason ? ` ${reason}` : ''} Do not proceed. (audit: ${audit_id})`;
           break;
         case 'ESCALATE':
-          actionText = `⏳ ${what} requires human approval; a request has been sent to the account owner.\n\nApproval token: ${approval_token}\n\nNow call wait_for_payment_approval(approval_token="${approval_token}") to automatically detect approval, then call evaluate_action again with the same arguments PLUS this approval_token. Do not proceed until it returns approved.`;
+          actionText = `⏳ ${what} requires human approval; a request has been sent to the account owner.\n\nApproval token: ${approval_token}\n\nNow call wait_for_approval(approval_token="${approval_token}") to automatically detect approval, then call evaluate_action again with the same arguments PLUS this approval_token. Do not proceed until it returns approved.`;
           break;
         default:
           actionText = JSON.stringify(result);
@@ -499,7 +500,7 @@ export async function runMcp() {
           modelText = `✗ Blocked: ${what}.${reason ? ` ${reason}` : ''} Do not use this model for this task. Choose a cheaper or smaller model and call evaluate_model again with the new model id. (audit: ${audit_id})`;
           break;
         case 'ESCALATE':
-          modelText = `⏳ ${what} requires human approval; a request has been sent to the account owner.\n\nApproval token: ${approval_token}\n\nNow call wait_for_payment_approval(approval_token="${approval_token}") to automatically detect approval, then call evaluate_model again with the same arguments PLUS this approval_token. Do not run the task until it returns approved.`;
+          modelText = `⏳ ${what} requires human approval; a request has been sent to the account owner.\n\nApproval token: ${approval_token}\n\nNow call wait_for_approval(approval_token="${approval_token}") to automatically detect approval, then call evaluate_model again with the same arguments PLUS this approval_token. Do not run the task until it returns approved.`;
           break;
         default:
           modelText = JSON.stringify(result);
@@ -555,7 +556,7 @@ export async function runMcp() {
           loginText = `✗ ${verb} blocked.${reason ? ` ${reason}` : ''} Do not proceed. (audit: ${audit_id})`;
           break;
         case 'ESCALATE':
-          loginText = `⏳ ${verb} requires human approval; a request has been sent to the account owner.\n\nApproval token: ${approval_token}\n\nNow call wait_for_payment_approval(approval_token="${approval_token}") to automatically detect approval, then call evaluate_login again with the same site/login_action PLUS this approval_token. Do not proceed until it returns approved.`;
+          loginText = `⏳ ${verb} requires human approval; a request has been sent to the account owner.\n\nApproval token: ${approval_token}\n\nNow call wait_for_approval(approval_token="${approval_token}") to automatically detect approval, then call evaluate_login again with the same site/login_action PLUS this approval_token. Do not proceed until it returns approved.`;
           break;
         default:
           loginText = JSON.stringify(result);
@@ -592,7 +593,7 @@ export async function runMcp() {
         text = `✗ Payment blocked by policy "${policy}". Do not proceed with this payment. (audit: ${audit_id})`;
         break;
       case 'ESCALATE':
-        text = `⏳ Payment requires human approval; a request has been sent to the account owner.\n\nApproval token: ${approval_token}\n\nNow call wait_for_payment_approval(approval_token="${approval_token}") to automatically detect approval. Do not proceed until it returns approved. (audit: ${audit_id})`;
+        text = `⏳ Payment requires human approval; a request has been sent to the account owner.\n\nApproval token: ${approval_token}\n\nNow call wait_for_approval(approval_token="${approval_token}") to automatically detect approval. Do not proceed until it returns approved. (audit: ${audit_id})`;
         break;
       case 'NOTIFY':
         text = `✓ Payment approved with notification. Policy matched: "${policy}". (audit: ${audit_id})\n\nAfter the charge attempt completes, call confirm_payment with audit_id "${audit_id}" and status "success", "failed", or "cancelled".`;

package/src/tests/model-checkpoint.test.js

@@ -98,3 +98,37 @@ test('the model id is asked for exactly, not as a friendly name', () => {
     'send family names and be priced as the wrong generation',
   );
 });
+
+test('the heartbeat reports which CLI version is running', () => {
+  // An old CLI does not fail, it simply never calls a checkpoint it has never
+  // heard of, so the affected page looks broken rather than out of date.
+  // Before 1.14.0 Token Optimization was empty for every MCP agent and nothing
+  // anywhere said why. The dashboard can only explain that if it knows what is
+  // running.
+  assert.ok(
+    /CLI_VERSION/.test(apiSrc),
+    'api.js does not read its own version',
+  );
+  const hb = apiSrc.slice(apiSrc.indexOf('mcpHeartbeat:'));
+  assert.ok(
+    /cli_version: CLI_VERSION/.test(hb.slice(0, 400)),
+    'the heartbeat does not send the CLI version',
+  );
+  // Every heartbeat, not only the ones carrying a name: a long-running agent
+  // that never re-inits would otherwise never report its version at all.
+  assert.ok(
+    !/agentName \? \{[^}]*cli_version/.test(hb.slice(0, 400)),
+    'cli_version is only sent when an agent name is present, so a steady-state '
+    + 'agent never reports its version',
+  );
+});
+
+test('the version is read from package.json, not hardcoded', () => {
+  // A hardcoded string drifts from the published version the moment someone
+  // bumps one and not the other, and then the dashboard advises upgrading a
+  // CLI that is already current.
+  assert.ok(
+    /createRequire/.test(apiSrc) && /package\.json/.test(apiSrc),
+    'CLI_VERSION is not derived from package.json',
+  );
+});