troxy-cli 1.14.0 → 1.17.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.17.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,22 +36,33 @@ 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
         // to make the second call as non-optional as the first.
-        'You MUST also call the evaluate_model tool when you begin a substantial task and whenever you switch model or effort level partway through it, giving the exact model id and how many tokens you expect to use. Do not run the task without first receiving an ALLOW or NOTIFY decision; if BLOCK, pick a cheaper or smaller model and call evaluate_model again with the new id. Then, when the task finishes, you MUST call report_model_usage with the audit_id from that decision and the real token total from your model API. Both halves are required: without the second call Troxy has only your prediction, and the account owner is shown that this agent\'s costs are unverified. Report the true number even when it is far above your estimate.',
+        //
+        // The previous wording gated this on whether the task felt big
+        // enough, which was a judgment call, not a rule. Driven live: the
+        // same agent, same session, called evaluate_model to review two
+        // source files, then minutes later pulled real data from an actual
+        // connected business (orders, customer messages, an artifact) and
+        // called nothing. Both were real work by any reasonable reading. The
+        // old wording meant whatever the model felt like in the moment, and
+        // Token Optimization is supposed to be a precise record, not a mood.
+        // The trigger below is mechanical instead: did this turn use a tool,
+        // yes or no. That is a fact you can check, not a judgment you make.
+        'You MUST also call the evaluate_model tool at the start of ANY turn where you will use one or more tools of any kind — reading or writing a file, running a command, browsing, calling an external API, anything beyond a plain text reply — and whenever you switch model or effort level partway through the turn. This is not a judgment call about how the turn feels: if you are about to use a tool, call evaluate_model first, every time, regardless of how small the turn seems. A turn that is pure conversation with no tool use at all is the only kind that does not need it. Give the exact model id and how many tokens you expect to use. Do not use any tool without first receiving an ALLOW or NOTIFY decision; if BLOCK, pick a cheaper or smaller model and call evaluate_model again with the new id. Then, at the end of that same turn, you MUST call report_model_usage with the audit_id from that decision and the real token total from your model API. Both halves are required: without the second call Troxy has only your prediction, and the account owner is shown that this agent\'s costs are unverified. Report the true number even when it is far above your estimate.',
     },
     { capabilities: { tools: {} } },
   );
@@ -94,9 +105,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: {
@@ -267,8 +279,9 @@ export async function runMcp() {
         description:
           'Evaluate whether running a task on a given AI model should be allowed, blocked, or escalated ' +
           'based on your Troxy policies, and record what it is expected to cost. ' +
-          'Call this when you start a task and whenever you switch model or effort level mid-task. ' +
-          'Returns an audit_id. Keep it: you must pass it to report_model_usage when the task finishes.',
+          'Call this at the start of any turn where you will use a tool of any kind, and whenever you switch model or effort level mid-turn. ' +
+          'This is mechanical, not a judgment call: tool use in this turn means call it, no tool use means you can skip it. ' +
+          'Returns an audit_id. Keep it: you must pass it to report_model_usage at the end of the turn.',
         inputSchema: {
           type: 'object',
           required: ['model'],
@@ -308,8 +321,8 @@ export async function runMcp() {
       {
         name: 'report_model_usage',
         description:
-          'Report how many tokens a task ACTUALLY used, once it has finished. ' +
-          'Call this after every ALLOW or NOTIFY from evaluate_model, using the audit_id it returned. ' +
+          'Report how many tokens the turn ACTUALLY used, once it has finished. ' +
+          'Call this after every ALLOW or NOTIFY from evaluate_model, using the audit_id it returned — no judgment call, every approved evaluate_model gets a matching report. ' +
           'Without it Troxy only has your prediction, and the account owner is told, per agent, that its figures are unverified. ' +
           'Report the real number even when it is far above what you estimated: the gap is the point.',
         inputSchema: {
@@ -339,7 +352,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 +372,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 +443,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 +477,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);
@@ -488,7 +501,7 @@ export async function runMcp() {
       // Every non-blocked branch repeats the audit_id and the instruction to
       // report back. Half the value of this checkpoint is the second call, and
       // an agent that is only told "approved" has no reason to make it.
-      const followUp = ` When the task finishes, call report_model_usage(audit_id="${audit_id}", actual_tokens=<real total>).`;
+      const followUp = ` When this turn finishes, call report_model_usage(audit_id="${audit_id}", actual_tokens=<real total>).`;
       let modelText;
       switch (decision) {
         case 'ALLOW':
@@ -499,7 +512,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 +568,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 +605,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,71 @@ 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',
+  );
+});
+
+test('the checkpoint trigger is mechanical, not a judgment call', () => {
+  // "When you begin a substantial task" was tried first and driven live: the
+  // same agent, same session, called evaluate_model to review two source
+  // files, then minutes later pulled real data from an actual connected
+  // business (orders, customer messages, an artifact) and called nothing.
+  // Both were real work. "Substantial" meant whatever the model felt like in
+  // the moment, which is not what a precise cost record can be built on.
+  // Sliced from the opening quote of the instructions STRING, not the
+  // instructions: field or file start, so the explanatory code comment
+  // above it (which deliberately quotes the retired word for context) does
+  // not trip this check.
+  const instructions = src.slice(src.indexOf("'You are connected to Troxy"), src.indexOf('capabilities'));
+  assert.ok(
+    !/substantial/i.test(instructions),
+    'the instructions still gate the checkpoint on "substantial", a judgment '
+    + 'call proven inconsistent on the same agent in the same session',
+  );
+  assert.ok(
+    /tool/i.test(instructions) && /every time/i.test(instructions),
+    'the instructions do not state a mechanical, checkable trigger (tool use) '
+    + 'to replace the judgment call that was removed',
+  );
+});
+
+test('evaluate_model\'s own tool description matches the mechanical trigger', () => {
+  // The top-level instructions are what an agent reads once; the tool
+  // description is what it sees every time it considers calling this
+  // specific tool. Both have to agree, or whichever one it reads last wins.
+  const schema = src.slice(src.indexOf("name: 'evaluate_model'"));
+  const desc = schema.slice(0, schema.indexOf('inputSchema'));
+  assert.ok(!/substantial/i.test(desc), 'the tool description still says "substantial"');
+  assert.ok(/tool/i.test(desc), 'the tool description does not mention the tool-use trigger');
+});