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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mddeleted file mode 100644index 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.