Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

fix(agents): refuse to arm or fire a spending automation over MCP until the owner has signed the real-funds agreements

nirholas9d90f3d518ff
diff --git a/api/_mcp/tools/agent-lifecycle.js b/api/_mcp/tools/agent-lifecycle.js
index 72eb397ee..8b1597f5a 100644
--- a/api/_mcp/tools/agent-lifecycle.js
+++ b/api/_mcp/tools/agent-lifecycle.js
@@ -53,6 +53,7 @@ import {
listUserAutomations,
} from '../../_lib/agents-v1/automations.js';
import { connectorSpendError } from '../policy.js';
+import { currentSignatureFor, agreementRequirement } from '../../_lib/real-funds-agreement.js';
const SPEND_ACTIONS = new Set(['swap', 'transfer']);
const MAX_GLB_BYTES = 64 * 1024 * 1024;
@@ -130,8 +131,12 @@ function pick(args, map) {
// ── spend gate ───────────────────────────────────────────────────────────────
-/** Refuse a connector key, or a bearer without wallet:write, before any spend config is touched. */
-function assertMaySpend(auth, toolName) {
+/**
+ * Refuse a connector key, a bearer without wallet:write, or an account that has
+ * not signed the real-funds agreements, before any spend config is touched.
+ * A failed agreement lookup refuses too: nothing is armed on an unverified signature.
+ */
+async function assertMaySpend(auth, toolName) {
if (auth?.connector) throw connectorSpendError(toolName);
if (!hasScope(auth?.scope, 'wallet:write')) {
return designedError(
@@ -139,6 +144,19 @@ function assertMaySpend(auth, toolName) {
'This automation spends from the agent wallet, so the connection needs the wallet:write scope. Reconnect with wallet access, or use an agent_prompt or notify action.',
);
}
+ let signature;
+ try {
+ signature = await currentSignatureFor(auth.userId);
+ } catch {
+ return designedError('agreement_check_unavailable', 'Could not verify the signed real-funds agreements, so nothing was armed. Try again in a moment.');
+ }
+ if (!signature) {
+ const requirement = agreementRequirement();
+ return toolResult(
+ { status: 'risk_ack_required', error: 'risk_ack_required', ...requirement },
+ { isError: true, text: `Sign the real-funds agreements before an agent can spend on its own. Nothing was armed. Sign at ${requirement.sign_url}` },
+ );
+ }
return null;
}
@@ -715,7 +733,7 @@ export const toolDefs = [
const norm = await api(async () => normalizeAutomation(body));
if (failed(norm)) return norm.__error;
if (SPEND_ACTIONS.has(norm.action.type)) {
- const refused = assertMaySpend(auth, 'automation_create');
+ const refused = await assertMaySpend(auth, 'automation_create');
if (refused) return refused;
if (args.confirm_spend !== true) {
return spendConfirmation('automation_create', spendTerms(await displayDestination(norm.action), norm.trigger, norm.limits), { title: norm.title });
@@ -766,7 +784,7 @@ export const toolDefs = [
const nextType = current.source === 'automation' ? args.action?.type || current.action?.type : null;
const onlyDisabling = args.enabled === false && Object.keys(body).length === 1;
if (SPEND_ACTIONS.has(nextType) && !onlyDisabling) {
- const refused = assertMaySpend(auth, 'automation_update');
+ const refused = await assertMaySpend(auth, 'automation_update');
if (refused) return refused;
if (args.confirm_spend !== true) {
const action = args.action && args.action.type && args.action.type !== current.action.type ? args.action : { ...current.action, ...(args.action || {}) };
@@ -814,7 +832,7 @@ export const toolDefs = [
const current = await api(() => getAutomation(auth.userId, args.automation_id));
if (failed(current)) return current.__error;
if (current.source === 'automation' && SPEND_ACTIONS.has(current.action?.type)) {
- const refused = assertMaySpend(auth, 'automation_trigger');
+ const refused = await assertMaySpend(auth, 'automation_trigger');
if (refused) return refused;
if (args.confirm_spend !== true) {
return spendConfirmation('automation_trigger', spendTerms(current.action, { type: 'manual', note: 'fires once, now' }, current.limits), { automation_id: args.automation_id });
diff --git a/docs/mcp.md b/docs/mcp.md
index c8a1ae0c4..9a9309990 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -553,7 +553,7 @@ Sixteen tools let an MCP client manage an agent end to end: change it, pause it,
{ "name": "delete_agent", "arguments": { "agent_id": "<agent_id>", "confirm_delete": true, "preview_id": "<preview_id>" } }
```
-**Automations that spend show their terms first.** Creating, updating or triggering a `swap` or `transfer` automation without `confirm_spend: true` returns `confirmation_required` with a `terms` block (recipient, amount, asset, chain and the trigger condition) for the model to show the owner. Only the owner's explicit yes should send `confirm_spend`. Hosted connector sessions cannot arm spend automations at all (`-32003`), and the agent's spend policy and caps apply to every fire.
+**Automations that spend show their terms first.** Creating, updating or triggering a `swap` or `transfer` automation without `confirm_spend: true` returns `confirmation_required` with a `terms` block (recipient, amount, asset, chain and the trigger condition) for the model to show the owner. Only the owner's explicit yes should send `confirm_spend`. Hosted connector sessions cannot arm spend automations at all (`-32003`). An account that has not signed the real-funds agreements gets `risk_ack_required` with the `sign_url` to sign at, and nothing is armed. The agent's spend policy and caps apply to every fire.
**Runs are budgeted and leave a receipt trail.** Runs stop when either budget runs out (status `budget_exhausted`), and every run ends with a plain-language `summary`. Each step's receipt hashes the step together with the one before it, so editing, dropping or reordering a step breaks the chain at that step. The owner can watch and replay any run on the agent page's **Runs** tab, and `create_agent_run` returns its `replay_url`. Details: [docs/agent-runtime.md](./agent-runtime.md#autonomous-runs-budgets-receipts-and-replay).
diff --git a/tests/mcp-agent-lifecycle.test.js b/tests/mcp-agent-lifecycle.test.js
index ce05a2df3..38be8e541 100644
--- a/tests/mcp-agent-lifecycle.test.js
+++ b/tests/mcp-agent-lifecycle.test.js
@@ -155,6 +155,14 @@ vi.mock('../api/_lib/agent-wallet.js', async (importOriginal) => ({
getSolanaAddressBalances: vi.fn(async () => ({ sol: 0.5, usdc: 0 })),
}));
+// The signed real-funds agreements are a database read; each test decides
+// whether the owner has signed (the default) or not.
+const signatureMock = vi.fn();
+vi.mock('../api/_lib/real-funds-agreement.js', async (importOriginal) => ({
+ ...(await importOriginal()),
+ currentSignatureFor: (...a) => signatureMock(...a),
+}));
+
vi.mock('../api/_lib/ssrf-guard.js', async (importOriginal) => ({
...(await importOriginal()),
fetchSafePublicUrl: vi.fn(),
@@ -276,6 +284,7 @@ function glb() {
const PNG = Buffer.from('89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c489', 'hex');
beforeEach(() => {
+ signatureMock.mockReset().mockResolvedValue({ signedAt: '2026-10-01T00:00:00.000Z', signatureName: 'QA Owner', context: 'agent-wallet' });
db.agents.clear();
db.automations.clear();
db.runs.clear();
@@ -536,6 +545,31 @@ describe('automation tools', () => {
expect(db.automations.size).toBe(0);
});
+ it('refuses a spend automation from an owner who has not signed the real-funds agreements', async () => {
+ signatureMock.mockResolvedValue(null);
+ const res = await call('automation_create', {
+ agent_id: AGENT,
+ trigger: { type: 'tip_received' },
+ action: { type: 'transfer', destination: DEST, amountSol: 0.01 },
+ confirm_spend: true,
+ });
+ expect(res.result.isError).toBe(true);
+ expect(out(res)).toMatchObject({ status: 'risk_ack_required', sign_url: expect.stringContaining('http') });
+ expect(db.automations.size).toBe(0);
+ });
+
+ it('refuses to arm a spend automation when the agreement lookup fails', async () => {
+ signatureMock.mockRejectedValue(new Error('db down'));
+ const res = await call('automation_create', {
+ agent_id: AGENT,
+ trigger: { type: 'tip_received' },
+ action: { type: 'transfer', destination: DEST, amountSol: 0.01 },
+ confirm_spend: true,
+ });
+ expect(out(res).status).toBe('agreement_check_unavailable');
+ expect(db.automations.size).toBe(0);
+ });
+
it('creates a transfer automation once confirm_spend is true', async () => {
const res = await call('automation_create', {
agent_id: AGENT,