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.

feat(extension): give the checkout companion a popup and the knock SDK a CLI

nirholas8e1fe4dc65ba
diff --git a/extensions/checkout-companion/popup.css b/extensions/checkout-companion/popup.css
new file mode 100644
index 000000000..2741656d3
--- /dev/null
+++ b/extensions/checkout-companion/popup.css
@@ -0,0 +1,49 @@
+:root {
+ color-scheme: light dark;
+ --bg: #ffffff;
+ --fg: #14161a;
+ --muted: #5b616e;
+ --line: rgba(16, 18, 22, 0.1);
+ --accent: #6d5cff;
+ --ok: #12a58c;
+ --warn: #c23a2f;
+}
+@media (prefers-color-scheme: dark) {
+ :root {
+ --bg: #16181d;
+ --fg: #edeff3;
+ --muted: #9aa1ae;
+ --line: rgba(255, 255, 255, 0.12);
+ }
+}
+* { box-sizing: border-box; }
+body {
+ width: 320px;
+ margin: 0;
+ padding: 16px;
+ font: 14px/1.45 -apple-system, BlinkMacSystemFont, "Segoe UI", Inter, system-ui, sans-serif;
+ background: var(--bg);
+ color: var(--fg);
+}
+header { display: flex; gap: 12px; align-items: center; margin-bottom: 16px; }
+h1 { font-size: 15px; margin: 0; }
+.muted { color: var(--muted); margin: 2px 0 0; font-size: 12.5px; }
+.muted.ok { color: var(--ok); }
+.muted.warn { color: var(--warn); }
+.controls { display: grid; gap: 2px; }
+.row {
+ display: flex; align-items: center; justify-content: space-between; gap: 12px;
+ padding: 10px; border-radius: 10px; cursor: pointer;
+ transition: background 120ms ease;
+}
+.row:hover { background: color-mix(in srgb, var(--fg) 6%, transparent); }
+.row:focus-within { outline: 2px solid var(--accent); outline-offset: 1px; }
+.row small { display: block; color: var(--muted); font-size: 12px; margin-top: 2px; }
+input[type="checkbox"] { accent-color: var(--accent); width: 18px; height: 18px; flex: none; cursor: pointer; }
+footer {
+ display: flex; justify-content: space-between; gap: 8px;
+ margin-top: 16px; padding-top: 12px; border-top: 1px solid var(--line);
+}
+a { color: var(--accent); text-decoration: none; font-size: 12.5px; }
+a:hover { text-decoration: underline; }
+a:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; border-radius: 4px; }
diff --git a/extensions/checkout-companion/popup.html b/extensions/checkout-companion/popup.html
new file mode 100644
index 000000000..30a90a185
--- /dev/null
+++ b/extensions/checkout-companion/popup.html
@@ -0,0 +1,48 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="utf-8">
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>Checkout Companion</title>
+ <link rel="stylesheet" href="popup.css">
+ </head>
+ <body>
+ <header>
+ <img src="icons/icon-48.png" width="32" height="32" alt="">
+ <div>
+ <h1>Checkout Companion</h1>
+ <p id="connection" class="muted">Checking your account…</p>
+ </div>
+ </header>
+
+ <section class="controls">
+ <label class="row">
+ <span>
+ <strong>Read checkout pages</strong>
+ <small>Only pages that look like a payment step.</small>
+ </span>
+ <input type="checkbox" id="enabled">
+ </label>
+ <label class="row">
+ <span>
+ <strong>Say it out loud</strong>
+ <small>Speaks only when something is worth checking.</small>
+ </span>
+ <input type="checkbox" id="speak">
+ </label>
+ <label class="row">
+ <span>
+ <strong>Remember prices</strong>
+ <small>Compares the total against the price you were shown.</small>
+ </span>
+ <input type="checkbox" id="rememberPrices">
+ </label>
+ </section>
+
+ <footer>
+ <a href="options.html" target="_blank" rel="noopener">Account and privacy</a>
+ <a href="https://three.ws/checkout-companion" target="_blank" rel="noopener">How it works</a>
+ </footer>
+ <script src="popup.js" type="module"></script>
+ </body>
+</html>
diff --git a/extensions/checkout-companion/popup.js b/extensions/checkout-companion/popup.js
new file mode 100644
index 000000000..f6abb545f
--- /dev/null
+++ b/extensions/checkout-companion/popup.js
@@ -0,0 +1,32 @@
+// The popup: three switches and an honest line about whether it can work.
+//
+// The connection line is a live check rather than "you saved a token", because
+// a saved token that no longer resolves looks identical to a working one until
+// the moment someone is standing on a checkout page needing an answer.
+
+const DEFAULTS = { enabled: true, speak: true, rememberPrices: true };
+const FIELDS = Object.keys(DEFAULTS);
+
+const stored = await chrome.storage.local.get(DEFAULTS);
+for (const field of FIELDS) {
+ const input = document.getElementById(field);
+ input.checked = stored[field] ?? DEFAULTS[field];
+ input.addEventListener('change', () => {
+ chrome.storage.local.set({ [field]: input.checked });
+ });
+}
+
+const connection = document.getElementById('connection');
+try {
+ const state = await chrome.runtime.sendMessage({ type: 'checkout:ping' });
+ if (state?.connected) {
+ connection.textContent = state.via === 'token' ? 'Connected with a bridge token.' : 'Connected as your signed-in account.';
+ connection.className = 'muted ok';
+ } else {
+ connection.textContent = 'Not connected. Open account settings to fix this.';
+ connection.className = 'muted warn';
+ }
+} catch {
+ connection.textContent = 'Could not reach three.ws.';
+ connection.className = 'muted warn';
+}
diff --git a/packages/knock-sdk/src/cli.js b/packages/knock-sdk/src/cli.js
new file mode 100755
index 000000000..db10db474
--- /dev/null
+++ b/packages/knock-sdk/src/cli.js
@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+// knock: reach a real person from your terminal.
+//
+// npx @three-ws/knock quote nirholas
+// npx @three-ws/knock directory
+// npx @three-ws/knock send nirholas "Two questions about the facilitator." \
+// --from "Ada" --subject "Your x402 settle path"
+// npx @three-ws/knock receipt "https://three.ws/api/knock/reply?id=…&token=…"
+//
+// A free door sends immediately. A priced door prints exactly who is being
+// paid, how much, in what token, on what chain, and then STOPS for a yes. That
+// confirmation is not a convenience: it is the rule this CLI is built around,
+// because an unattended process should never be able to spend on your behalf
+// by accident. Pass --yes only when a human already approved the amount.
+//
+// Paying needs an x402 client, which you supply with --payer <module>. The
+// module is imported and must export `fetchWithPayment` (or a default that is
+// a function). That keeps your keys in the wallet you already trust and lets
+// you pay on whichever chain that client speaks.
+
+import { createInterface } from 'node:readline/promises';
+import { pathToFileURL } from 'node:url';
+import { confirmationFor, directory, knock, quote, receipt, KnockError } from './index.js';
+
+const HELP = `knock: reach a real person, and pay their price to do it.
+
+Usage
+ knock quote <handle> what a door costs
+ knock directory [--limit 60] every open door, cheapest first
+ knock send <handle> <message> [options] knock on a door
+ knock receipt <receipt-url> what became of a knock you sent
+
+Options for send
+ --from <name> who is knocking (required)
+ --subject <line> one line their companion says out loud
+ --url <link> an http(s) link about you
+ --request-id <id> idempotency key; a retry never knocks twice
+ --max-price <usdc> refuse if the door costs more than this
+ --payer <module> an x402 client exporting fetchWithPayment
+ --yes skip the payment confirmation (a human already approved)
+
+Global
+ --origin <url> default https://three.ws
+ --json machine-readable output
+`;
+
+const args = process.argv.slice(2);
+const flags = {};
+const positional = [];
+for (let i = 0; i < args.length; i += 1) {
+ const arg = args[i];
+ if (arg.startsWith('--')) {
+ const key = arg.slice(2);
+ const next = args[i + 1];
+ if (next === undefined || next.startsWith('--')) flags[key] = true;
+ else {
+ flags[key] = next;
+ i += 1;
+ }
+ } else positional.push(arg);
+}
+
+const json = Boolean(flags.json);
+const origin = typeof flags.origin === 'string' ? flags.origin : undefined;
+const out = (value) => console.log(json ? JSON.stringify(value, null, 2) : value);
+
+try {
+ await main();
+} catch (err) {
+ if (json) console.error(JSON.stringify({ error: err.code || 'error', message: err.message }, null, 2));
+ else console.error(`knock: ${err.message}`);
+ process.exitCode = err instanceof KnockError && err.status === 402 ? 2 : 1;
+}
+
+async function main() {
+ const command = positional[0];
+ if (!command || flags.help || command === 'help') return out(HELP);
+
+ if (command === 'quote') {
+ const door = await quote(need(positional[1], 'a handle'), { origin });
+ return out(json ? door : renderQuote(door));
+ }
+
+ if (command === 'directory') {
+ const doors = await directory({ origin, limit: Number(flags.limit) || 60 });
+ if (json) return out(doors);
+ if (!doors.length) return out('No open doors yet.');
+ return out(
+ doors
+ .map((d) => `${d.price.padStart(9)} @${d.handle}${d.headline ? ` ${d.headline}` : ''}`)
+ .join('\n'),
+ );
+ }
+
+ if (command === 'receipt') {
+ const state = await receipt(need(positional[1], 'a receipt URL'));
+ if (json) return out(state);
+ if (state.status === 'replied') return out(`Replied: ${state.reply}`);
+ if (state.status === 'dismissed') return out('Read and dismissed. No reply.');
+ return out(state.seen ? 'Read. No reply written yet.' : 'Not opened yet.');
+ }
+
+ if (command === 'send') {
+ const handle = need(positional[1], 'a handle');
+ const message = need(positional[2], 'a message');
+ const from = need(typeof flags.from === 'string' ? flags.from : null, '--from <name>');
+
+ const door = await quote(handle, { origin });
+ if (!door.free && !flags.yes) await confirmSpend(door);
+
+ const fetchWithPayment = door.free ? undefined : await loadPayer(door);
+ const result = await knock({
+ to: handle,
+ from,
+ message,
+ subject: typeof flags.subject === 'string' ? flags.subject : undefined,
+ url: typeof flags.url === 'string' ? flags.url : undefined,
+ requestId: typeof flags['request-id'] === 'string' ? flags['request-id'] : undefined,
+ maxPriceAtomics: flags['max-price'] ? usdcToAtomics(flags['max-price']) : undefined,
+ senderKind: 'agent',
+ fetchWithPayment,
+ origin,
+ });
+ if (json) return out(result);
+ return out(
+ [
+ result.duplicate ? 'Already delivered (same request id).' : `Delivered to ${result.delivered_to}.`,
+ `Paid: ${result.paid}`,
+ `Receipt: ${result.receipt_url}`,
+ ].join('\n'),
+ );
+ }
+
+ throw new KnockError(`unknown command "${command}". Run knock --help.`, { code: 'bad_command' });
+}
+
+function need(value, what) {
+ if (!value) throw new KnockError(`missing ${what}`, { code: 'missing_argument' });
+ return value;
+}
+
+function usdcToAtomics(input) {
+ const raw = String(input).replace(/^\$/, '');
+ if (!/^\d+(\.\d{1,6})?$/.test(raw)) throw new KnockError('--max-price must be a USDC amount like 0.05', { code: 'bad_price' });
+ const [whole, frac = ''] = raw.split('.');
+ return (BigInt(whole) * 1000000n + BigInt(frac.padEnd(6, '0'))).toString();
+}
+
+function renderQuote(door) {
+ return [
+ `${door.display_name} (@${door.handle})`,
+ door.headline ? door.headline : null,
+ door.greeting ? `\n${door.greeting}\n` : null,
+ `Price: ${door.free ? 'free' : `${door.price} ${door.currency}`}`,
+ door.free ? null : `Chains: ${door.networks.join(', ')}`,
+ `Limit: ${door.max_chars} characters`,
+ `Endpoint: ${door.endpoint}`,
+ ]
+ .filter(Boolean)
+ .join('\n');
+}
+
+// The spend gate. Prints the recipient, the amount, the token and the chain,
+// then waits for an explicit yes on a TTY. With no TTY there is nobody to ask,
+// so it refuses rather than assuming consent.
+async function confirmSpend(door) {
+ const c = confirmationFor(door);
+ console.error(
+ [
+ '',
+ ' You are about to pay to reach a person.',
+ '',
+ ` Recipient ${c.recipient}`,
+ ` Amount ${c.amount} ${c.token}`,
+ ` Chain ${c.chains.join(' or ')}`,
+ ` Endpoint ${c.endpoint}`,
+ '',
+ ` ${c.note}`,
+ '',
+ ].join('\n'),
+ );
+ if (!process.stdin.isTTY) {
+ throw new KnockError('refusing to pay without a confirmation. Re-run with --yes if a human approved this amount.', {
+ code: 'confirmation_required',
+ });
+ }
+ const rl = createInterface({ input: process.stdin, output: process.stderr });
+ const answer = (await rl.question(' Pay and knock? [y/N] ')).trim().toLowerCase();
+ rl.close();
+ if (answer !== 'y' && answer !== 'yes') {
+ throw new KnockError('cancelled, nothing was paid', { code: 'cancelled' });
+ }
+}
+
+async function loadPayer(door) {
+ const spec = flags.payer;
+ if (typeof spec !== 'string') {
+ throw new KnockError(
+ `${door.display_name} charges ${door.price}. Pass --payer <module>, where the module exports ` +
+ '`fetchWithPayment` from the x402 client and wallet you already use.',
+ { code: 'payment_required', status: 402 },
+ );
+ }
+ const specifier = spec.startsWith('.') || spec.startsWith('/') ? pathToFileURL(spec).href : spec;
+ const mod = await import(specifier);
+ const payer = mod.fetchWithPayment ?? (typeof mod.default === 'function' ? mod.default : null);
+ if (typeof payer !== 'function') {
+ throw new KnockError(`${spec} does not export a fetchWithPayment function`, { code: 'bad_payer' });
+ }
+ return payer;
+}