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.

test(mcp): cover the credential, session, and input gates that decide whether a call leaves the process

nirholas225b1265d917
diff --git a/packages/audio-mcp/test/input-contract.test.mjs b/packages/audio-mcp/test/input-contract.test.mjs
new file mode 100644
index 000000000..e05c7b627
--- /dev/null
+++ b/packages/audio-mcp/test/input-contract.test.mjs
@@ -0,0 +1,57 @@
+// Caller-facing input rules this server enforces itself, before spending a
+// request on the upstream model lanes.
+//
+// `audio_to_face` is the only tool with a rule its JSON schema cannot express:
+// exactly one of two optional fields must be present. A caller who passes
+// neither should be told that in the same turn, not after a round trip that
+// fails somewhere in the pipeline.
+//
+// No network: every case here is decided before a request is made.
+//
+// Run: node --test packages/audio-mcp/test/input-contract.test.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { TOOLS } from '../src/index.js';
+import { HTTP_TIMEOUT_MS, THREE_WS_BASE } from '../src/config.js';
+
+const byName = Object.fromEntries(TOOLS.map((t) => [t.name, t]));
+
+test('audio_to_face declares text and audio as the two ways in', () => {
+ const schema = byName.audio_to_face.inputSchema;
+ assert.ok('text' in schema, 'the text path must be declared');
+ assert.ok('audio' in schema, 'the audio path must be declared');
+ // Both optional at the schema layer, because the rule is "exactly one".
+ assert.equal(schema.text.isOptional(), true);
+ assert.equal(schema.audio.isOptional(), true);
+});
+
+test('audio_to_face refuses locally when neither text nor audio is given', async () => {
+ const started = Date.now();
+ for (const args of [{}, { text: '' }, { text: ' ' }, { audio: '' }]) {
+ await assert.rejects(
+ () => byName.audio_to_face.handler(args),
+ (err) => {
+ assert.equal(err.code, 'bad_request', `expected bad_request for ${JSON.stringify(args)}`);
+ assert.match(err.message, /text/, 'the message must name the text path');
+ assert.match(err.message, /audio/, 'the message must name the audio path');
+ return true;
+ },
+ );
+ }
+ // A local refusal, not a round trip that happened to fail.
+ assert.ok(Date.now() - started < 1000, 'an empty request must not reach a model lane');
+});
+
+test('the request budget is generous enough for a real model call', () => {
+ // TTS, ASR, and Audio2Face are live gRPC calls to hosted models, not cache
+ // reads. A short default would time out on a clip that synthesizes fine.
+ assert.equal(HTTP_TIMEOUT_MS, 60000);
+ assert.ok(HTTP_TIMEOUT_MS >= 30000, 'a model call needs real headroom');
+});
+
+test('the base URL is normalized so path joins cannot double a slash', () => {
+ assert.equal(THREE_WS_BASE, 'https://three.ws');
+ assert.doesNotMatch(THREE_WS_BASE, /\/$/, 'a trailing slash would produce //api/... paths');
+});
diff --git a/packages/autopilot-mcp/test/credential-gate.test.mjs b/packages/autopilot-mcp/test/credential-gate.test.mjs
new file mode 100644
index 000000000..444b30dc5
--- /dev/null
+++ b/packages/autopilot-mcp/test/credential-gate.test.mjs
@@ -0,0 +1,78 @@
+// The credential gate: every autopilot endpoint is owner-scoped, so a server
+// with no THREE_WS_API_KEY must refuse locally rather than fire an
+// unauthenticated request and hand the caller a bare upstream 401.
+//
+// This matters most for the write tools. `execute_proposal` can move real SOL,
+// and the failure a misconfigured server produces should name the missing
+// variable, not look like a rejected transaction.
+//
+// No network: every case here is decided before a request is made. The suite is
+// only meaningful with THREE_WS_API_KEY unset, which is the default for a
+// freshly installed server.
+//
+// Run: node --test packages/autopilot-mcp/test/credential-gate.test.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { TOOLS } from '../src/index.js';
+import { THREE_WS_API_KEY } from '../src/config.js';
+import { MissingCredentialError } from '../src/lib/api.js';
+
+const byName = Object.fromEntries(TOOLS.map((t) => [t.name, t]));
+const AGENT_ID = '845e4464-1d17-4cac-8990-be3f72bbc38d';
+const PROPOSAL_ID = 'p_00000000';
+
+// One representative call per tool, shaped so it would be a valid request if a
+// credential were present.
+const CALLS = {
+ get_autopilot_config: { agentId: AGENT_ID },
+ set_autopilot_config: { agentId: AGENT_ID, enabled: true },
+ generate_proposals: { agentId: AGENT_ID },
+ list_proposals: { agentId: AGENT_ID },
+ dryrun_proposal: { agentId: AGENT_ID, proposalId: PROPOSAL_ID },
+ adjust_proposal: { agentId: AGENT_ID, proposalId: PROPOSAL_ID, params: {} },
+ execute_proposal: { agentId: AGENT_ID, proposalId: PROPOSAL_ID, confirm: true },
+ dismiss_proposal: { agentId: AGENT_ID, proposalId: PROPOSAL_ID },
+ undo_action: { agentId: AGENT_ID, proposalId: PROPOSAL_ID },
+ list_autopilot_activity: {},
+ compute_trust: { agentId: AGENT_ID },
+};
+
+test('THREE_WS_API_KEY defaults to empty, so the gate under test is armed', () => {
+ assert.equal(THREE_WS_API_KEY, '', 'unset THREE_WS_API_KEY before running this suite');
+});
+
+test('every registered tool has a case in this suite', () => {
+ assert.deepEqual(TOOLS.map((t) => t.name).sort(), Object.keys(CALLS).sort());
+});
+
+for (const [name, args] of Object.entries(CALLS)) {
+ test(`${name} refuses locally with missing_credential`, async () => {
+ const started = Date.now();
+ await assert.rejects(
+ () => byName[name].handler(args),
+ (err) => {
+ assert.ok(err instanceof MissingCredentialError, `${name} must throw MissingCredentialError`);
+ assert.equal(err.code, 'missing_credential');
+ assert.equal(err.status, 401);
+ assert.match(err.message, /THREE_WS_API_KEY/, 'the message must name the variable to set');
+ return true;
+ },
+ );
+ // A local refusal, not a round trip that happened to fail.
+ assert.ok(Date.now() - started < 1000, `${name} must refuse before any request`);
+ });
+}
+
+test('the funds-moving tool refuses on the credential, not silently on confirm', async () => {
+ // `execute_proposal` has two independent guards: this server's credential and
+ // the backend's confirmation gate. With no credential the call must never
+ // reach the network, whether or not confirm was passed.
+ for (const confirm of [true, false, undefined]) {
+ await assert.rejects(
+ () => byName.execute_proposal.handler({ agentId: AGENT_ID, proposalId: PROPOSAL_ID, confirm }),
+ (err) => err.code === 'missing_credential',
+ );
+ }
+});
diff --git a/packages/billing-mcp/test/session-gate.test.mjs b/packages/billing-mcp/test/session-gate.test.mjs
new file mode 100644
index 000000000..a5f381d8f
--- /dev/null
+++ b/packages/billing-mcp/test/session-gate.test.mjs
@@ -0,0 +1,73 @@
+// The session gate: which reads are account-scoped, and what a caller gets back
+// when THREE_WS_SESSION is not set.
+//
+// This is the boundary that decides whether a call ever leaves the process. It
+// must refuse locally with an actionable message rather than firing an
+// unauthenticated request and surfacing a bare 401 from the API, and the one
+// public read (`get_fee_info`) must stay outside it.
+//
+// No network: every case here is decided before a request is made. The suite is
+// only meaningful with THREE_WS_SESSION unset, which is the default for a
+// freshly installed server.
+//
+// Run: node --test packages/billing-mcp/test/session-gate.test.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { TOOLS } from '../src/index.js';
+import { THREE_WS_SESSION } from '../src/config.js';
+
+const byName = Object.fromEntries(TOOLS.map((t) => [t.name, t]));
+const SESSION_SCOPED = ['get_billing_summary', 'query_usage', 'export_billing_history', 'get_receipt', 'get_revenue'];
+const PUBLIC = ['get_fee_info'];
+
+test('the tool list is exactly the session-scoped reads plus the public one', () => {
+ assert.deepEqual(TOOLS.map((t) => t.name).sort(), [...SESSION_SCOPED, ...PUBLIC].sort());
+});
+
+test('THREE_WS_SESSION defaults to empty, so the gate under test is armed', () => {
+ assert.equal(THREE_WS_SESSION, '', 'unset THREE_WS_SESSION before running this suite');
+});
+
+for (const name of SESSION_SCOPED) {
+ test(`${name} refuses locally with no_session instead of calling unauthenticated`, async () => {
+ const started = Date.now();
+ const args = name === 'get_receipt' ? { event_id: 1 } : {};
+ await assert.rejects(
+ () => byName[name].handler(args),
+ (err) => {
+ assert.equal(err.code, 'no_session', `${name} must fail with no_session`);
+ assert.equal(err.status, 401);
+ assert.match(err.message, /THREE_WS_SESSION/, 'the message must name the variable to set');
+ assert.match(err.message, /__Host-sid/, 'the message must say where to find the value');
+ return true;
+ },
+ );
+ // A local refusal, not a round trip that happened to fail.
+ assert.ok(Date.now() - started < 1000, `${name} must refuse before any request`);
+ });
+}
+
+test('get_receipt rejects an ambiguous request before it can reach the gate', async () => {
+ // Exactly one of event_id / purchase_id. Neither and both are caller errors,
+ // and both are caught locally rather than sent upstream to be sorted out.
+ for (const args of [{}, { event_id: 1, purchase_id: '00000000-0000-4000-8000-000000000000' }]) {
+ await assert.rejects(
+ () => byName.get_receipt.handler(args),
+ (err) => {
+ assert.notEqual(err.code, 'no_session', 'the shape error must be reported before the session gate');
+ assert.match(err.message, /exactly one of/i);
+ return true;
+ },
+ );
+ }
+});
+
+test('the public fee read is not behind the session gate', () => {
+ // Asserted on the declared surface rather than by calling out to the network:
+ // get_fee_info takes no arguments and is the only tool the README documents
+ // as reachable without a session.
+ assert.deepEqual(Object.keys(byName.get_fee_info.inputSchema ?? {}), []);
+ assert.equal(byName.get_fee_info.annotations.readOnlyHint, true);
+});
diff --git a/prompts/swarm-100/packages-batch-03.md b/prompts/swarm-100/packages-batch-03.md
deleted file mode 100644
index 1de967bb7..000000000
--- a/prompts/swarm-100/packages-batch-03.md
+++ /dev/null
@@ -1,95 +0,0 @@
-# Package audit batch 03: audio-mcp, autopilot-mcp, avatar-agent-mcp, avatar-cli, avatar-schema, billing-mcp
-
-How to run: paste this file's repo path into a fresh Claude Code chat in this
-repository and say "run this work order". This file is fully self-contained:
-it depends on no other prompt file anywhere. If neighboring files in
-prompts/swarm-100/ are gone, that work is done; if present, ignore them.
-Every claim below rots; step 0 re-measures, and what you measure wins.
-
-## Operating clause (binding)
-
-- Read CLAUDE.md first. Its rules override everything, including this file.
-- Finish 100% in this session. Never end the turn with a question, an option
- list, or an unexecuted plan. A judgment call goes in one line of the final
- report; it never becomes a question that halts work.
-- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real
- funds or any irreversible on-chain write, git push or a production deploy,
- committing content that references a crypto project other than $THREE, and
- destroying unrecoverable data.
-- No mocks, no fake data, no placeholder stubs, no unfinished-work markers, no
- commented-out code. Real APIs and real integrations only.
-- The em-dash and en-dash characters are banned in everything you write.
-- Concurrent agents share this worktree: stage explicit paths only (never a
- bare add-everything), and commit finished work promptly.
-- Before committing, run: npm run check:rules -- --paths <files you touched>.
- It must exit 0.
-
-## Step 0: re-derive the current state
-
-For each package below: read its package.json and README.md, then find its
-tests (its own directory and tests/ at the repo root).
-
-## Task: audit and fix these packages
-
-Packages in this batch:
-
-- packages/audio-mcp
-- packages/autopilot-mcp
-- packages/avatar-agent-mcp
-- packages/avatar-cli
-- packages/avatar-schema
-- packages/billing-mcp
-
-For each one:
-
-1. README: present (repo standard is 100% coverage under packages/) and
- accurate: what it does, install and use, public exports, one runnable
- example. Run the example for real.
-2. Exports resolve: import the package's declared entry points with node and
- confirm they load without error.
-3. Tests: run the tests that cover it; if its core path has none, add a real
- one.
-4. Hard-rule scan across its source: no stubs, no mock fallbacks, no
- unfinished markers, no commented-out code. Fix at root.
-5. package.json sanity: name, version, license, exports and files fields
- consistent with what is actually shipped.
-
-## Definition of done
-
-- [ ] Every package in the batch: README verified accurate, example executed,
- entry points imported cleanly, tests green with core-path coverage.
-- [ ] Zero hard-rule violations remain in these packages.
-- [ ] npm run check:rules -- --paths <touched files> exits 0.
-
-## Never blocked
-
-| Blocker | Resolution (act, do not ask) |
-|---|---|
-| Missing env var or credential | Check .env and .env.local, then the Cloud Run service env, then Secret Manager (the CLAUDE.md self-unblock playbook has the exact commands). If it truly exists nowhere, wire the code fully behind the env var, prove the wiring with a dry run, and name the single missing var in the report. |
-| gcloud not on PATH | Run: export PATH="$HOME/google-cloud-sdk/bin:$PATH" |
-| Dev server port 3000 busy | Another agent may be serving this repo; probe it and reuse if so. Otherwise start your own on a free port: npx vite --port 3101 |
-| Playwright browser missing | npx playwright install chromium |
-| A surface needs a signed-in user | Register a fresh account through the real /register flow against the real API and use it. Never mock the session. |
-| A defect sits in code you did not touch | Fix it if it blocks a Definition of done line (root cause it, never mask it). Otherwise note it in the report and continue. |
-| An unrelated test is red | Same rule. Never pipe npm test through tail; it masks exit codes. |
-
-## Close out (required)
-
-1. Verify every Definition of done line with the actual command output in
- front of you. Never claim a line you did not verify.
-2. Commit with explicit paths and a subject that describes the diff (house
- style: type(scope): what changed and why a reader cares).
-3. Delete this prompt file in that same commit:
-
- git rm prompts/swarm-100/packages-batch-03.md
-
- The shrinking directory is this campaign's only progress ledger; there is
- no progress log to update.
-4. Final report: what step 0 measured, what changed (file list), evidence per
- Definition of done line, and any one-line judgment calls. No trailing
- questions, no unexecuted plans.
-
-If a line genuinely cannot pass inside this session (an external party must
-respond, or an owner-gated action is the final step), finish everything else,
-leave this file in place, and state exactly which line remains and who owns
-it. Never delete this file on a partial.