troxy-cli 1.9.0 → 1.11.0

package/bin/troxy.js

@@ -457,8 +457,21 @@ switch (command) {
       process.exit(1);
     }
 
+    // Refresh the hosted-agent instructions regardless of whether the package
+    // moved. For a cloud agent the package is beside the point: what goes stale
+    // is its picture of which checkpoints exist, and that lives on the server.
+    // This is a no-op on a machine with an MCP client, which gets a fresh tool
+    // list from the MCP handshake every session anyway.
+    const { refreshHostedInstructions } = await import('../src/init.js');
+    const refresh = async () => {
+      try {
+        return await refreshHostedInstructions((loadConfig() || {}).apiKey);
+      } catch { return false; }
+    };
+
     if (current === latest) {
-      console.log(`already up to date (${current})\n`);
+      console.log(`already up to date (${current})`);
+      if (!await refresh()) console.log('');
       break;
     }
 
@@ -480,7 +493,8 @@ switch (command) {
       }
       // Also refresh the npx cache so MCP servers (e.g. OpenClaw) pick up the new version
       try { execSync(`npx --yes troxy-cli@${latest} --version`, { stdio: 'pipe' }); } catch { /* non-fatal */ }
-      console.log(`✓\n\n  Updated to ${latest}. Restart your terminal and any MCP clients to use the new version.\n`);
+      console.log(`✓\n\n  Updated to ${latest}. Restart your terminal and any MCP clients to use the new version.`);
+      if (!await refresh()) console.log('');
     } catch (err) {
       const stderr = err.stderr?.toString() || err.message || '';
       if (stderr.includes('EACCES') || stderr.includes('permission')) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "troxy-cli",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "description": "AI payment control — protect your agent's payments with policies",
   "type": "module",
   "bin": {

package/src/api.js

@@ -73,6 +73,7 @@ export const api = {
   evaluate: (body, apiKey) => request('POST', '/evaluate', { apiKey, body }),
   evaluateEmail: (body, apiKey) => request('POST', '/evaluate/email', { apiKey, body }),
   evaluateLogin: (body, apiKey) => request('POST', '/evaluate/login', { apiKey, body }),
+  evaluateAction: (body, apiKey) => request('POST', '/evaluate/action', { apiKey, body }),
   selfRevoke: (apiKey) => request('POST', '/mcp/self-revoke', { apiKey }),
   confirmPayment: (auditId, body, apiKey) => request('POST', `/payments/${auditId}/confirm`, { apiKey, body }),
   waitApprovalStatus: (token) => request('GET', `/approvals/${encodeURIComponent(token)}/wait`),
@@ -83,6 +84,11 @@ export const api = {
   // MCP status (agent API key — no login needed)
   mcpStatus:  (apiKey) => request('GET', '/mcp/status', { apiKey }),
 
+  // Setup instructions for an agent with no MCP client to configure. Fetched
+  // rather than hardcoded so a new checkpoint reaches agents without an npm
+  // release — a cloud agent runs init once and never upgrades the package.
+  agentInstructions: (apiKey) => request('GET', '/agent/instructions', { apiKey }),
+
   // MCP pause / resume / rename via JWT (requires troxy login)
   pauseToken:  (jwt, id)       => request('POST',  `/tokens/${id}/pause`,  { jwt }),
   resumeToken: (jwt, id)       => request('POST',  `/tokens/${id}/resume`, { jwt }),

package/src/init.js

@@ -12,7 +12,10 @@ import { evaluatePayment, api } from './api.js';
 // one immediately, so every real consumer — which holds the key via ENV, not config.json —
 // kept presenting the now-revoked key until the user manually re-ran init. Non-interactive
 // (no prompts), so it's safe to call from rotate-key with the existing agent name.
-export async function reprovisionKeyConsumers(key, agentName) {
+// True when this machine has something that can host an MCP server. When it
+// does not, we are almost certainly inside a hosted agent's own sandbox, and
+// the setup it needs is instructions rather than config files.
+export function detectMcpClients() {
   const platform = process.platform;
   const detected = MCP_CLIENTS.filter(c => {
     const p = c.path[platform] ?? c.path.linux;
@@ -25,11 +28,36 @@ export async function reprovisionKeyConsumers(key, agentName) {
     hasOpenClaw = true;
   } catch {}
 
-  if (detected.length === 0 && !hasOpenClaw) {
-    console.log('\n  No MCP clients detected (Claude Desktop, Cursor, Windsurf, OpenClaw).');
-    console.log('  Troxy MCP server config:\n');
-    console.log(JSON.stringify(mcpEntry(key), null, 4));
-    console.log('\n  Add the above to your MCP client\'s config under "mcpServers".\n');
+  return { detected, hasOpenClaw, none: detected.length === 0 && !hasOpenClaw };
+}
+
+// `troxy update` on a hosted agent. The npm package is beside the point there:
+// what goes stale is the agent's picture of which checkpoints exist, and that
+// lives on the server. So this re-fetches and reprints even when the package
+// itself is already current, which is the common case for an agent that runs
+// npx and never installs anything.
+export async function refreshHostedInstructions(key) {
+  if (!key || !detectMcpClients().none) return false;
+  await printHostedAgentSetup(key);
+  return true;
+}
+
+export async function reprovisionKeyConsumers(key, agentName) {
+  const platform = process.platform;
+  const { detected, hasOpenClaw, none } = detectMcpClients();
+
+  if (none) {
+    // No MCP client on this machine almost always means a hosted agent running
+    // init inside its own sandbox. This branch used to print the mcpServers
+    // JSON and say "add this to your MCP client's config" — advice such an
+    // agent cannot act on: it has no config file, and it cannot reconfigure the
+    // runtime it lives inside. A real Base44 agent hit exactly this, ended up
+    // registered and named in the dashboard but with zero tools, and fell back
+    // to hand-written curl against whichever endpoints it found in the docs.
+    //
+    // What it CAN do is read this output, because it just ran the command. So
+    // print the instructions instead. One command, no copy-paste, no docs.
+    await printHostedAgentSetup(key);
   } else {
     console.log('\n  MCP clients found:');
     for (const client of detected) {
@@ -67,6 +95,78 @@ export async function reprovisionKeyConsumers(key, agentName) {
   }
 }
 
+const AGENTS_START = '<!-- troxy:start -->';
+const AGENTS_END   = '<!-- troxy:end -->';
+
+// The endpoint deliberately does not echo the caller's key back, so the live
+// key is substituted here, on the machine that already has it. Split/join
+// rather than a regex because a key is user-controlled input and would other-
+// wise need escaping to avoid being read as a pattern.
+export function buildHostedInstructions(data, key) {
+  const text = String((data && data.instructions) || '');
+  if (!text.trim()) throw new Error('empty instructions');
+  const placeholder = (data && data.key_placeholder) || 'YOUR_TROXY_KEY';
+  return text.split(placeholder).join(key);
+}
+
+// Print the setup an agent with no MCP client needs, and persist it where
+// agent runtimes look. Two delivery paths on purpose, because neither is
+// reliable alone: stdout reaches the agent right now but dies with the session,
+// AGENTS.md survives but only matters on platforms that read it.
+async function printHostedAgentSetup(key) {
+  console.log('\n  No MCP client on this machine, so this looks like a hosted agent.');
+  console.log('  Nothing to install. The instructions below are the whole setup.\n');
+
+  let text;
+  try {
+    text = buildHostedInstructions(await api.agentInstructions(key), key);
+  } catch {
+    console.log('  Could not reach the Troxy API to fetch them.');
+    console.log('  Get the block from dash.troxy.io → API Keys → Cloud agents,');
+    console.log('  or re-run this command once you are back online.\n');
+    return;
+  }
+
+  const rule = '  ' + '─'.repeat(66);
+  console.log(rule);
+  console.log(text.split('\n').map(l => '  ' + l).join('\n'));
+  console.log(rule);
+
+  try {
+    const written = writeAgentsFile(process.cwd(), text);
+    console.log(`\n  Saved to ${written}`);
+  } catch (err) {
+    console.log(`\n  Could not write AGENTS.md (${err.message})`);
+  }
+
+  console.log('\n  If you are an AI agent reading this: save the block above to your');
+  console.log('  own persistent instructions or memory, so it survives a new session.');
+  console.log('  Then follow it before you pay, email, log in, or delete anything.\n');
+}
+
+// Idempotent, and never clobbers instructions the user wrote themselves: the
+// Troxy section lives between markers, so re-running init (or rotate-key, which
+// changes the key inside the block) replaces only that span.
+export function writeAgentsFile(dir, text) {
+  const file = path.join(dir, 'AGENTS.md');
+  const block = `${AGENTS_START}\n${text}\n${AGENTS_END}`;
+  let existing = '';
+  try { existing = fs.readFileSync(file, 'utf8'); } catch {}
+
+  let next;
+  if (existing.includes(AGENTS_START) && existing.includes(AGENTS_END)) {
+    const head = existing.slice(0, existing.indexOf(AGENTS_START));
+    const tail = existing.slice(existing.indexOf(AGENTS_END) + AGENTS_END.length);
+    next = head + block + tail;
+  } else if (existing.trim()) {
+    next = existing.replace(/\s*$/, '') + '\n\n' + block + '\n';
+  } else {
+    next = block + '\n';
+  }
+  fs.writeFileSync(file, next);
+  return file;
+}
+
 function prompt(question) {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   return new Promise(resolve => rl.question(question, ans => { rl.close(); resolve(ans.trim()); }));

package/src/mcp-server.js

@@ -9,6 +9,7 @@ import { evaluatePayment, api } from './api.js';
 const confirmPayment = (auditId, body, apiKey) => api.confirmPayment(auditId, body, apiKey);
 const evaluateEmail   = (body, apiKey) => api.evaluateEmail(body, apiKey);
 const evaluateLogin   = (body, apiKey) => api.evaluateLogin(body, apiKey);
+const evaluateAction  = (body, apiKey) => api.evaluateAction(body, apiKey);
 
 export async function runMcp() {
   const config    = loadConfig();
@@ -42,6 +43,7 @@ export async function runMcp() {
         '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_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.',
     },
     { capabilities: { tools: {} } },
@@ -181,6 +183,49 @@ export async function runMcp() {
           },
         },
       },
+      {
+        name: 'evaluate_action',
+        description:
+          'Evaluate whether a destructive or hard-to-undo action should be allowed, blocked, or ' +
+          'escalated based on your Troxy policies. Call this BEFORE deleting, overwriting, dropping, ' +
+          'truncating, force-pushing, destroying, or revoking anything on the user\'s behalf.',
+        inputSchema: {
+          type: 'object',
+          required: ['action_verb'],
+          properties: {
+            action_verb: {
+              type: 'string',
+              description:
+                'What you are about to do, one lowercase word: delete, overwrite, drop, truncate, ' +
+                'force_push, destroy, revoke, deploy, share, upload, or export.',
+            },
+            resource: {
+              type: 'string',
+              description:
+                'What it affects — a path, table, bucket, repo or branch, e.g. "/var/data", ' +
+                '"users", "refs/heads/main". Policies can narrow a rule to a specific target.',
+            },
+            item_count: {
+              type: 'number',
+              description:
+                'How many things the action affects (files, rows, records). Send the real number ' +
+                'whenever you know it — bulk-action policies depend on it. Defaults to 1.',
+            },
+            reversible: {
+              type: 'boolean',
+              description:
+                'True only if this can be straightforwardly undone (e.g. a soft delete, a revert). ' +
+                'If you are unsure, omit it or send false: an undeclared action is treated as ' +
+                'irreversible so it is not waved through by mistake.',
+            },
+            agent: { type: 'string', description: 'Name of the agent (optional)' },
+            approval_token: {
+              type: 'string',
+              description: 'Approval token from a previous ESCALATE response. Include this to proceed after the user has approved.',
+            },
+          },
+        },
+      },
       {
         name: 'evaluate_login',
         description:
@@ -319,6 +364,37 @@ export async function runMcp() {
       };
     }
 
+    if (toolName === 'evaluate_action') {
+      if (agentName && !args.agent) args.agent = agentName;
+      let result;
+      try {
+        result = await evaluateAction(args, apiKey);
+      } catch (err) {
+        return { content: [{ type: 'text', text: `Troxy error: ${err.message}` }], isError: true };
+      }
+      if (result.error) {
+        return { content: [{ type: 'text', text: `Troxy error: ${result.error}` }], isError: true };
+      }
+      const { decision, reason, audit_id, approval_token } = result;
+      const what = `${args.action_verb}${args.resource ? ` on ${args.resource}` : ''}`;
+      let actionText;
+      switch (decision) {
+        case 'ALLOW':
+        case 'NOTIFY':
+          actionText = `✓ Approved: ${what}.${reason ? ` ${reason}` : ''} You may proceed. (audit: ${audit_id})`;
+          break;
+        case 'BLOCK':
+          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.`;
+          break;
+        default:
+          actionText = JSON.stringify(result);
+      }
+      return { content: [{ type: 'text', text: actionText }], isError: decision === 'BLOCK' };
+    }
+
     if (toolName === 'evaluate_login') {
       if (agentName && !args.agent) args.agent = agentName;
       let result;

package/src/tests/agents-file.test.js

@@ -0,0 +1,133 @@
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { writeAgentsFile, buildHostedInstructions, refreshHostedInstructions, detectMcpClients } from '../init.js';
+
+// `troxy init` on a hosted agent writes the Troxy setup into AGENTS.md, which
+// on most agent platforms is a file the user also writes their own rules into.
+// So the write has to be surgical: re-running init (or rotate-key, which
+// changes the key inside the block) must replace only Troxy's section and leave
+// everything else byte-for-byte intact.
+
+let dir;
+beforeEach(() => { dir = fs.mkdtempSync(path.join(os.tmpdir(), 'troxy-agents-')); });
+afterEach(() => { fs.rmSync(dir, { recursive: true, force: true }); });
+
+const read = () => fs.readFileSync(path.join(dir, 'AGENTS.md'), 'utf8');
+
+describe('writeAgentsFile', () => {
+  it('creates the file when there is none', () => {
+    writeAgentsFile(dir, '## Troxy\nkey ONE');
+    assert.match(read(), /## Troxy\nkey ONE/);
+  });
+
+  it('wraps the block in markers so it can be found again', () => {
+    writeAgentsFile(dir, 'BLOCK');
+    const out = read();
+    assert.ok(out.includes('<!-- troxy:start -->'));
+    assert.ok(out.includes('<!-- troxy:end -->'));
+  });
+
+  it('appends to a file the user already wrote, without touching their content', () => {
+    const theirs = '# My agent rules\n\nAlways answer in English.\n';
+    fs.writeFileSync(path.join(dir, 'AGENTS.md'), theirs);
+    writeAgentsFile(dir, 'BLOCK');
+    const out = read();
+    assert.ok(out.startsWith('# My agent rules'));
+    assert.ok(out.includes('Always answer in English.'));
+    assert.ok(out.includes('BLOCK'));
+  });
+
+  it('replaces its own block on a re-run instead of stacking duplicates', () => {
+    writeAgentsFile(dir, 'key ONE');
+    writeAgentsFile(dir, 'key TWO');
+    const out = read();
+    assert.equal(out.split('<!-- troxy:start -->').length - 1, 1);
+    assert.ok(out.includes('key TWO'));
+    assert.ok(!out.includes('key ONE'));
+  });
+
+  it('keeps the user content around the block when replacing', () => {
+    // The rotate-key case: a stale key must be swapped out without collateral.
+    fs.writeFileSync(path.join(dir, 'AGENTS.md'), 'BEFORE\n');
+    writeAgentsFile(dir, 'key ONE');
+    fs.appendFileSync(path.join(dir, 'AGENTS.md'), '\nAFTER\n');
+    writeAgentsFile(dir, 'key TWO');
+    const out = read();
+    assert.ok(out.includes('BEFORE'));
+    assert.ok(out.includes('AFTER'));
+    assert.ok(out.includes('key TWO'));
+    assert.ok(!out.includes('key ONE'));
+  });
+
+  it('does not add a second block to a file that only has whitespace', () => {
+    fs.writeFileSync(path.join(dir, 'AGENTS.md'), '   \n\n');
+    writeAgentsFile(dir, 'BLOCK');
+    assert.equal(read().split('<!-- troxy:start -->').length - 1, 1);
+  });
+
+  it('returns the path it wrote, so init can report it', () => {
+    const written = writeAgentsFile(dir, 'BLOCK');
+    assert.equal(written, path.join(dir, 'AGENTS.md'));
+  });
+});
+
+describe('buildHostedInstructions', () => {
+  const KEY = 'txy-live-key-123';
+
+  it('substitutes the live key for the placeholder', () => {
+    const out = buildHostedInstructions(
+      { instructions: 'Authorization: Bearer YOUR_TROXY_KEY', key_placeholder: 'YOUR_TROXY_KEY' }, KEY);
+    assert.equal(out, `Authorization: Bearer ${KEY}`);
+    assert.ok(!out.includes('YOUR_TROXY_KEY'));
+  });
+
+  it('substitutes every occurrence, not just the first', () => {
+    const out = buildHostedInstructions(
+      { instructions: 'X YOUR_TROXY_KEY Y YOUR_TROXY_KEY', key_placeholder: 'YOUR_TROXY_KEY' }, KEY);
+    assert.equal(out.split(KEY).length - 1, 2);
+  });
+
+  it('falls back to the known placeholder if the server omits it', () => {
+    const out = buildHostedInstructions({ instructions: 'Bearer YOUR_TROXY_KEY' }, KEY);
+    assert.ok(out.includes(KEY));
+  });
+
+  it('treats a key containing regex characters literally', () => {
+    // Keys are opaque server-generated strings, but a replace built on a regex
+    // would corrupt the output the day that stops being true.
+    const weird = 'txy-a$&b.*c';
+    const out = buildHostedInstructions(
+      { instructions: 'Bearer YOUR_TROXY_KEY', key_placeholder: 'YOUR_TROXY_KEY' }, weird);
+    assert.equal(out, `Bearer ${weird}`);
+  });
+
+  it('rejects an empty payload rather than printing a blank setup', () => {
+    // Better to fall through to the "could not reach the API" path than to hand
+    // an agent an empty block it will treat as complete.
+    assert.throws(() => buildHostedInstructions({ instructions: '   ' }, KEY));
+    assert.throws(() => buildHostedInstructions({}, KEY));
+    assert.throws(() => buildHostedInstructions(null, KEY));
+  });
+});
+
+describe('refreshHostedInstructions', () => {
+  it('does nothing without a saved key', async () => {
+    // `troxy update` runs on machines that never ran init. It must not reach
+    // for the network, or print a setup block, with no key to authenticate.
+    assert.equal(await refreshHostedInstructions(undefined), false);
+    assert.equal(await refreshHostedInstructions(''), false);
+  });
+
+  it('reports whether this machine can host an MCP server', () => {
+    // The signal that decides between "patch config files" and "print
+    // instructions". Shape only — the answer is environment-dependent.
+    const r = detectMcpClients();
+    assert.ok(Array.isArray(r.detected));
+    assert.equal(typeof r.hasOpenClaw, 'boolean');
+    assert.equal(r.none, r.detected.length === 0 && !r.hasOpenClaw);
+  });
+});