troxy-cli 1.10.0 → 1.11.1

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,7 +1,11 @@
 {
   "name": "troxy-cli",
-  "version": "1.10.0",
-  "description": "AI payment control — protect your agent's payments with policies",
+  "version": "1.11.1",
+  "description": "Control layer for AI agents: check payments, emails, logins and destructive actions against your policies",
+  "homepage": "https://troxy.io",
+  "bugs": {
+    "email": "support@troxy.io"
+  },
   "type": "module",
   "bin": {
     "troxy": "bin/troxy.js"

package/src/api.js

@@ -84,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,77 @@ 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('  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/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);
+  });
+});