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(api): stop /wk hanging on inherited keys and repair grounded web search

nirholas173b6d693af8
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b6c6df49f..2404be0e8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -23,6 +23,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
- **Mistyped filters on the revenue, checkout and ring endpoints answer plainly instead of failing**: The public revenue feed, the checkout SKU API and the ring report all took values straight from the URL into the database. A timestamp that was not a timestamp, a checkout id that was not an id, and the query fell over: the caller got an opaque "something went wrong" with a support reference, and our own alerting logged a fault that was only ever a typo. All three now say what was wrong, in words, with the right status code. The ring report also stops treating an unrecognised period as "show me everything", which quietly answered the wrong question and ran the most expensive query it has. The revenue feed now echoes back the endpoint filter it actually applied rather than the raw text it was sent, and the paid-call lookup only accepts something shaped like a real transaction signature. (`/x402-revenue`) `[fix]`
- **Robinhood Chain worlds survive a hiccup in the live feed instead of going dark**: The in-world trading terminal inside a Robinhood Chain world polls the chain feed every five seconds, and the Worlds lobby lists those coins from the same feed. A single event that arrived without its payload, or with a timestamp the chain wrote in an unexpected format, took both requests down with a server error: the terminal showed a dead tape, and the lobby's Robinhood Chain tab quietly emptied with nothing on screen to say why. Bad events are now skipped and the rest of the tape still renders, a price that is genuinely missing stays blank rather than printing as a real $0 trade, and a launch with no readable contract address no longer produces a card that leads nowhere. Asking for trades with an address that is not a contract address now gets a clear error back instead of an empty list that read as "this coin has never traded". (`/worlds`) `[fix]`
- **Scrolling the activity feed past a bad cursor no longer breaks the whole feed**: An audit of the account endpoints found one real break and two smaller ones. The activity feed on /community and your personal feed ask for the next page of results by passing the last item’s timestamp back; if that value arrived malformed, from a hand-edited link or a stale bookmark, the database rejected it and the entire feed came back as a server error with nothing to act on. It now answers with a plain "that is not a timestamp" so the page can recover and reload from the top. The referral code editor stated its length rule with a typographic dash that read as a minus sign on some devices, and now spells it out. The purchase history endpoint also documented the wrong default view: it always merges your purchases and your sales, which is what the dashboard shows. (`/community`) `[fix]`
+- **Seeding an agent from your X account no longer asks for permission to post as you**: Teaching an agent your voice from your public X posts required connecting X first, and that connect asked X for everything the platform can do with an account, including posting and uploading media on your behalf. Reading your posts once and writing as you are two different things to agree to, and only the first one is what seeding needs. The Connect button on the X card in Settings now asks X for read access to your profile and posts and nothing else, and it says so before you click. Posting is its own connect, offered right beside it and labelled as such, and Reconnect keeps whichever of the two you already chose rather than quietly widening it. If a connection cannot read your posts at all, the card now says which permission is missing and offers a reconnect instead of showing you a consent screen for a seed that could not run, and an agent trying to post through a read-only connection is told exactly that instead of failing against X with nothing to act on. Everything else about the lane is unchanged: nothing is read until you consent on a screen that lists what is read and stored, and revoking still deletes every memory the seeding produced. (`/settings`) `[improvement, security]`
- **Shared agent links keep their preview card through a chain hiccup**: The preview card for an on-chain agent is rendered on demand from the chain and the agent's manifest. When either read was slow or briefly unavailable, the card answered as if the agent did not exist, and social sites cached that answer for up to an hour, so a link to a real agent unfurled with no image at all. The card is now served either way and only kept for a minute when a read fell short, so the next crawl picks up the real thing. Alongside it, ten agent endpoints (the preview card and page, the oEmbed provider, memory sync, the action log, ask, delegate and team tasks) now answer a mistyped agent id with a clear, specific error instead of a generic server failure. `[fix, improvement]`
- **Sharing an agent link posts the agent's picture again**: Pasting a link to an agent into a chat app, a social post or a group thread is supposed to unfurl into a card with the agent's name, its description and a picture of it. For every agent that actually has an avatar picture, which is nearly all of them, the page that builds that card was crashing instead, so the link unfurled as a bare URL with nothing attached. The card now renders with the agent's own thumbnail, falls back to a freshly rendered portrait when an agent has no thumbnail yet, and an unknown or malformed agent link sends the visitor to the app instead of erroring. `[fix]`
- **Skill marketplace: installs are locked to your own clicks, and edits keep their star rating**: Three fixes to the skills marketplace. Installing or removing a skill now carries the same one-time security token every other account action does, so a page you happen to have open elsewhere can no longer quietly add skills to your account behind your back. Editing one of your published skills used to answer back with its rating blanked out, which made the detail panel show 'No ratings yet' on a skill people had actually rated until you reloaded; it now reports the real average and count. And when a skill you were paging past gets deleted or made private mid-scroll, 'Load more' stops cleanly instead of looping the first page of results back into the grid over and over. (`/marketplace`) `[fix, security]`
@@ -49,6 +50,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
- **Trending stops going blank on a bad limit, and shared cards stop trusting the image host**: Asking the trending board for a non-numeric number of rows (limit=abc) answered with an empty leaderboard and a 200, as though nothing on the platform were trending at all. The bad value was reaching the database verbatim, failing both the agent and the coin ranking, and a catch-all turned that failure into an empty list with nothing logged anywhere. An unreadable limit now falls back to the default ten, the same way an unrecognised window falls back to 24 hours, and if either ranking ever does fail it now says so in the logs instead of quietly serving an empty board. Separately, the trade, trader and walk preview cards inline a portrait fetched from whatever URL the profile points at, and they read that response whole with no limit; a card now refuses anything that is not an image or that runs past 1.5 MB, and falls back to the monogram it already drew for a dead host. The profile card at /u/<name> also used to answer an image request with a JSON error if the database hiccuped, which is exactly the kind of broken preview a social crawler caches; it now returns a real, uncached card instead. (`/trending`) `[fix, improvement]`
- **Trending: muted text on the board is readable, and the Tip button that only navigated is gone**: Ten pieces of text on the Trending board sat below the WCAG AA contrast floor: the subtitle, the two unselected tabs, the 7d and all-time buttons, the column headers, agent descriptions and the unit labels next to each number. They are all legible now, and the Oracle link in the footnote is underlined instead of being told apart by colour alone. The wallet chip on each row carried a Tip button and a hover card, but the whole row is a link, so the browser followed the row instead of running either one: pressing Tip took you to the agent's wallet page rather than opening a tip. Both controls are gone from the board and tipping stays where it works, on the agent page the row opens, while the chip keeps showing the wallet address and its live balance. An automated accessibility scan now reports zero violations on all three boards and on their loading, empty and error states. (`/trending`) `[fix, improvement]`
- **Wallet reputation stops losing coins it never got around to judging**: The rollup that turns launch history into wallet reputation was judging 80 coins every five minutes while the intel firehose was recording about 32,000 new mints a day, so it fell roughly 8,000 coins a day behind. That backlog does not wait its turn: the rollup works oldest-first and only reaches back 14 days, which is exactly when retention prunes the record, so the tail of the queue aged out and those buyers never counted toward anyone’s reputation at all. 309,000 coins were sitting unjudged with the oldest already 8.4 days from the cliff. The per-run budget is now 400, which outruns the firehose several times over, drains the backlog within days and then idles. Scores across the smart-money surfaces get their full evidence base back. The operations health board also tracks the retention and reconstruct sweeps, so a stall in either is visible instead of showing up later as a symptom. `[fix, infra]`
+- **Web search answers again, and a stray address can no longer tie up the server**: Three repairs on the public API. Web search had been answering nothing but an error: the question went to Google's grounded search as designed, but the model was given a single budget to both think and reply, spent all of it thinking, and came back empty, which we correctly reported as a failure and wrongly did so on every single query. Thinking now has its own allowance on top of the answer, and when a search does come back empty the log says why instead of leaving the next person to guess. Second, the machine-readable directory at the root of the site, the file other agents read to learn what three.ws sells, would hang forever on a handful of odd names rather than saying no such thing, and a request that never ends holds a server slot until it is cut off. Every unknown name now gets a plain not-found. Third, at checkout, a wallet that hands back a payment the network could never accept is now told so at the moment it happens, instead of the modal saying sending and the error arriving later from the payment processor. `[fix, security]`
## 2026-08-15
diff --git a/api/_lib/web-search.js b/api/_lib/web-search.js
index e4449511e..d4f0c484c 100644
--- a/api/_lib/web-search.js
+++ b/api/_lib/web-search.js
@@ -25,9 +25,12 @@
// VERTEX_GEMINI_MODEL : model id (default: google/gemini-2.5-flash)
import { getGcpAccessToken } from './gcp-auth.js';
-import { vertexGeminiAvailable, vertexGeminiModel } from './vertex-gemini.js';
+import { vertexGeminiAvailable, vertexGeminiModel, vertexGeminiThinkingBudget } from './vertex-gemini.js';
const FETCH_TIMEOUT_MS = 20_000;
+// Visible answer tokens. The reasoning cap is funded separately on top (see the
+// generationConfig below), so this is what the caller actually gets back.
+const ANSWER_TOKENS = 1024;
export function webSearchAvailable() {
return vertexGeminiAvailable();
@@ -76,6 +79,7 @@ export async function groundedSearch(query, { maxSources = 8, signal } = {}) {
if (!q) throw new Error('web search: empty query');
const token = await getGcpAccessToken();
+ const think = vertexGeminiThinkingBudget();
const res = await fetch(groundedUrl(), {
method: 'POST',
headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
@@ -83,7 +87,19 @@ export async function groundedSearch(query, { maxSources = 8, signal } = {}) {
body: JSON.stringify({
contents: [{ role: 'user', parts: [{ text: q }] }],
tools: [{ googleSearch: {} }],
- generationConfig: { temperature: 0.2, maxOutputTokens: 1024 },
+ generationConfig: {
+ temperature: 0.2,
+ // Visible-answer budget PLUS the reasoning cap, exactly like the
+ // OpenAI-compat anchor's vertexGeminiBudget(). Gemini 2.5 reasons by
+ // default and bills those tokens against maxOutputTokens without ever
+ // returning them, so a flat 1024 here was spent thinking: the reply
+ // carried no text and no groundingChunks, which this function then
+ // (correctly) reported as an empty grounded response and /api/web-search
+ // surfaced as a 502 on every query. Capping the reasoning and funding
+ // it on top is what makes ANSWER_TOKENS mean tokens the caller receives.
+ maxOutputTokens: ANSWER_TOKENS + think,
+ thinkingConfig: { thinkingBudget: think },
+ },
}),
});
if (!res.ok) {
@@ -103,7 +119,19 @@ export async function groundedSearch(query, { maxSources = 8, signal } = {}) {
// A response with neither text nor sources is an upstream failure in
// disguise (safety block, empty candidate) — surface it as an error so
- // chains fall through instead of caching an empty "success".
- if (!answer && !sources.length) throw new Error('web search: empty grounded response');
+ // chains fall through instead of caching an empty "success". Name the cause:
+ // finishReason separates "MAX_TOKENS" (budget spent on reasoning) from
+ // "SAFETY"/"RECITATION" (blocked) from a prompt-level block, and without it
+ // every one of these looked identical from the outside: a bare 502 with
+ // nothing in the log to act on.
+ if (!answer && !sources.length) {
+ const finish = candidate?.finishReason || 'none';
+ const blocked = body?.promptFeedback?.blockReason || 'none';
+ throw new Error(
+ `web search: empty grounded response (finishReason=${finish}, promptBlockReason=${blocked}, candidates=${
+ body?.candidates?.length ?? 0
+ })`,
+ );
+ }
return { answer, sources, queries };
}
diff --git a/api/web-search.js b/api/web-search.js
index ebfaa0420..f89ebbdc9 100644
--- a/api/web-search.js
+++ b/api/web-search.js
@@ -53,9 +53,11 @@ export default wrap(async (req, res) => {
} catch (err) {
// Upstream failure is a real error state, not an empty result — tell the
// caller it can retry, and keep the message generic (the raw upstream
- // detail goes to logs, not to the public).
+ // detail goes to logs, not to the public). Uses the shared error() shape
+ // so a client parsing {error, error_description} does not have to special
+ // case this one handler.
console.error('[web-search]', err?.message || err);
- return json(res, 502, { error: 'search upstream failed, retry shortly' });
+ return error(res, 502, 'upstream_error', 'search upstream failed, retry shortly');
}
return json(
diff --git a/api/wk.js b/api/wk.js
index f2df4e5e4..9eb779c15 100644
--- a/api/wk.js
+++ b/api/wk.js
@@ -1908,7 +1908,7 @@ async function handleThreeVanity(req, res) {
protocol: 'three-vanity/v1',
protocols: ['three-vanity/v1', 'three-pog/v1'],
description:
- 'Provably-fair Solana vanity grinding. Keys are ground under a commit–reveal ' +
+ 'Provably-fair Solana vanity grinding. Keys are ground under a commit-reveal ' +
'seed-mixing protocol (three-vanity/v1) and/or attested with a proof-of-grind ' +
'certificate (three-pog/v1). Both are signed by the attestation key below and ' +
'verified entirely client-side — nothing here is trusted, everything is recomputed.',
@@ -1983,7 +1983,10 @@ export default wrap(async (req, res) => {
: { methods: 'GET,OPTIONS' };
if (cors(req, res, corsOpts)) return;
if (!method(req, res, ['GET'])) return;
- const fn = DISPATCH[name];
- if (!fn) return error(res, 404, 'not_found', `unknown well-known resource: ${name}`);
+ const fn = Object.hasOwn(DISPATCH, name) ? DISPATCH[name] : null;
+ // Echo at most a label's worth of the caller's input. Unbounded reflection let
+ // a 5 KB ?name= come straight back in the 404 body (and into the access log),
+ // which is free amplification for anyone pointing a scraper at /.well-known.
+ if (!fn) return error(res, 404, 'not_found', `unknown well-known resource: ${String(name ?? 'null').slice(0, 64)}`);
return fn(req, res);
});
diff --git a/api/x402-checkout-record.js b/api/x402-checkout-record.js
index 33b40c9d3..bdcb3060f 100644
--- a/api/x402-checkout-record.js
+++ b/api/x402-checkout-record.js
@@ -1,13 +1,17 @@
// Records a successful paid checkout call against a SKU.
//
// The hosted checkout page (/pay/c/<slug>) calls this after the drop-in
-// modal returns a settled payment. The endpoint is public — anyone can record
-// a call against any SKU — so we authenticate the entry by verifying the
-// X-PAYMENT-RESPONSE blob from the facilitator's /settle response.
+// modal returns a settled payment.
//
-// In v1 we trust the client-reported payment header (the facilitator already
-// gated settlement; spoofing means lying to yourself about analytics). Future
-// hardening: verify the tx on-chain before recording.
+// Trust model, stated plainly because the numbers this table feeds are a
+// merchant's revenue dashboard: the endpoint is public and the row is NOT
+// authenticated. Anyone can POST a record against any active SKU. What bounds
+// the damage is that the row is analytics-only (it moves no funds, unlocks no
+// resource), the per-IP limiter caps the write rate, and the (sku_id,
+// tx_signature) unique index means one on-chain signature can be counted once.
+// Forging a row therefore means lying to yourself about your own conversion
+// numbers. Verifying the tx on-chain before recording would close the gap; it
+// costs an RPC round-trip on the checkout hot path and is not done today.
import { z } from 'zod';
import { sql } from './_lib/db.js';
diff --git a/api/x402-checkout.js b/api/x402-checkout.js
index 3a27629d3..2cafc19f6 100644
--- a/api/x402-checkout.js
+++ b/api/x402-checkout.js
@@ -406,6 +406,16 @@ async function handleEncode(req, res) {
if (check.confirmed === false) {
return error(res, 400, 'invalid_payment', check.reason || 'transaction does not meet payment requirements');
}
+ // confirmSolanaPayment is deliberately conservative: anything it cannot
+ // decode comes back `inconclusive` so a parsing quirk never rejects a real
+ // payment. One inconclusive reason is not a quirk though: a blob that does
+ // not deserialize into a transaction at all can never settle anywhere, and
+ // wrapping it into an X-PAYMENT header only moves the failure to the
+ // facilitator, where the buyer sees an opaque error after "Sending…"
+ // instead of a clear one at the step that produced the bad signature.
+ if (check.reason === 'undeserializable_transaction') {
+ return error(res, 400, 'invalid_payment', 'signed_tx_base64 is not a decodable Solana transaction');
+ }
}
const payload = {
diff --git a/api/x402-merchant.js b/api/x402-merchant.js
index ccfa73d91..0b1c2c4a1 100644
--- a/api/x402-merchant.js
+++ b/api/x402-merchant.js
@@ -218,16 +218,21 @@ async function handleGet(req, res) {
// Public storefront read — no auth. Returns the published layout + its
// products so /store/<handle> can render without exposing owner-only fields.
if (store) {
+ // Handles are at most 40 chars (storeHandle above). Reject anything longer
+ // before it reaches Postgres and before it is echoed back: a 3 KB ?store=
+ // used to make one round-trip AND come straight back in the 404 body.
+ const handle = String(store).toLowerCase();
+ if (handle.length > 40) return error(res, 404, 'store_not_found', 'no published store with that handle');
const [m] = await sql`
select owner_user_id, business_name, logo_url, accent_color,
store_handle, store_layout, store_theme,
charity_enabled, charity_name, charity_chain, charity_address, charity_bps,
roundup_enabled, roundup_to_atomics
from x402_merchant_settings
- where store_handle = ${String(store).toLowerCase()} and store_published = true
+ where store_handle = ${handle} and store_published = true
limit 1
`;
- if (!m) return error(res, 404, 'store_not_found', `no published store "${store}"`);
+ if (!m) return error(res, 404, 'store_not_found', `no published store "${handle}"`);
const products = await sql`
select id, slug, merchant_name, action_name, description, logo_url, image_url,
accent_color, price_atomics, price_network, target_method, position
diff --git a/data/changelog.json b/data/changelog.json
index 6cddf0c60..f087d5483 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,25 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security. `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-08-16",
+ "title": "Web search answers again, and a stray address can no longer tie up the server",
+ "summary": "Three repairs on the public API. Web search had been answering nothing but an error: the question went to Google's grounded search as designed, but the model was given a single budget to both think and reply, spent all of it thinking, and came back empty, which we correctly reported as a failure and wrongly did so on every single query. Thinking now has its own allowance on top of the answer, and when a search does come back empty the log says why instead of leaving the next person to guess. Second, the machine-readable directory at the root of the site, the file other agents read to learn what three.ws sells, would hang forever on a handful of odd names rather than saying no such thing, and a request that never ends holds a server slot until it is cut off. Every unknown name now gets a plain not-found. Third, at checkout, a wallet that hands back a payment the network could never accept is now told so at the moment it happens, instead of the modal saying sending and the error arriving later from the payment processor.",
+ "tags": [
+ "fix",
+ "security"
+ ]
+ },
+ {
+ "date": "2026-08-16",
+ "title": "Seeding an agent from your X account no longer asks for permission to post as you",
+ "summary": "Teaching an agent your voice from your public X posts required connecting X first, and that connect asked X for everything the platform can do with an account, including posting and uploading media on your behalf. Reading your posts once and writing as you are two different things to agree to, and only the first one is what seeding needs. The Connect button on the X card in Settings now asks X for read access to your profile and posts and nothing else, and it says so before you click. Posting is its own connect, offered right beside it and labelled as such, and Reconnect keeps whichever of the two you already chose rather than quietly widening it. If a connection cannot read your posts at all, the card now says which permission is missing and offers a reconnect instead of showing you a consent screen for a seed that could not run, and an agent trying to post through a read-only connection is told exactly that instead of failing against X with nothing to act on. Everything else about the lane is unchanged: nothing is read until you consent on a screen that lists what is read and stored, and revoking still deletes every memory the seeding produced.",
+ "tags": [
+ "improvement",
+ "security"
+ ],
+ "link": "/settings"
+ },
{
"date": "2026-08-16",
"title": "The Forge community board remembers what you liked",
diff --git a/docs/api-reference.md b/docs/api-reference.md
index caba3e5fb..bf4018815 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -5180,8 +5180,9 @@ returns `vertexaisearch.cloud.google.com` for every result.
GCP project configured (local dev without credentials). A designed "not
available here" state, not an error.
- `400 missing_query` — `q` was absent or empty.
-- `502` — the upstream grounded call failed (auth, quota, safety block, or
- timeout). Retryable.
+- `502 upstream_error`: the upstream grounded call failed (auth, quota, safety
+ block, or timeout). Retryable. Body is the standard error shape,
+ `{ "error": "upstream_error", "error_description": "search upstream failed, retry shortly" }`.
Results are edge-cached for 60 seconds (`stale-while-revalidate` 300).
diff --git a/prompts/swarm-100/api-top-16.md b/prompts/swarm-100/api-top-16.md
deleted file mode 100644
index 5904db7d2..000000000
--- a/prompts/swarm-100/api-top-16.md
+++ /dev/null
@@ -1,110 +0,0 @@
-# API audit: api/*.js batch 16 (10 files)
-
-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
-
-1. Confirm each file below still exists; deleted ones are done, skip them.
-2. For each, decide routability: grep its path in vercel.json and read how
- server/index.mjs maps filesystem handlers. Routed files get an endpoint
- audit; internal modules get a code and test audit.
-3. Start a local server for endpoint checks: node server/index.mjs with .env
- loaded, on a free PORT if 3000 is busy.
-
-## Task: audit these api files, then fix everything found
-
-Files in this batch:
-
-- api/version.js
-- api/vision.js
-- api/walk-og.js
-- api/wars.js
-- api/web-search.js
-- api/wk-x402.js
-- api/wk.js
-- api/x402-checkout-record.js
-- api/x402-checkout.js
-- api/x402-merchant.js
-
-For every routed handler:
-
-1. Exercise it with curl against the local server: the success path returns
- real data with the correct status; malformed input returns a 4xx JSON
- error, never a stack trace or an HTML error page; auth is enforced where
- the code intends it; CORS matches neighboring handlers.
-2. Hard-rule scan: no mock fallbacks, no fake-data arrays, no stubbed
- responses, no unfinished markers. Errors are handled at the boundary and
- internal code trusts itself.
-3. Do not spend funds or sign anything on-chain while probing. Payment and
- trading handlers get their validation and error paths exercised, never a
- live settlement.
-
-For every internal (non-routed) module:
-
-4. Something must import it; if nothing does, delete it as dead code (verify
- with a repo-wide grep first).
-5. Its main path and one failure path must be covered in tests/; add the
- missing test if not.
-
-## Definition of done
-
-- [ ] Every listed file has recorded evidence: a curl transcript for routed
- handlers, a passing test or a deletion for internal modules.
-- [ ] Zero hard-rule violations remain in these files.
-- [ ] vitest run passes; 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/api-top-16.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.
diff --git a/public/changelog.json b/public/changelog.json
index 27860afd9..518c31574 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-08-16T16:45:09.325Z",
+ "generated_at": "2026-08-16T17:00:52.612Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
@@ -186,6 +186,17 @@
"fix"
]
},
+ {
+ "date": "2026-08-16",
+ "type": "update",
+ "title": "Seeding an agent from your X account no longer asks for permission to post as you",
+ "summary": "Teaching an agent your voice from your public X posts required connecting X first, and that connect asked X for everything the platform can do with an account, including posting and uploading media on your behalf. Reading your posts once and writing as you are two different things to agree to, and only the first one is what seeding needs. The Connect button on the X card in Settings now asks X for read access to your profile and posts and nothing else, and it says so before you click. Posting is its own connect, offered right beside it and labelled as such, and Reconnect keeps whichever of the two you already chose rather than quietly widening it. If a connection cannot read your posts at all, the card now says which permission is missing and offers a reconnect instead of showing you a consent screen for a seed that could not run, and an agent trying to post through a read-only connection is told exactly that instead of failing against X with nothing to act on. Everything else about the lane is unchanged: nothing is read until you consent on a screen that lists what is read and stored, and revoking still deletes every memory the seeding produced.",
+ "link": "/settings",
+ "tags": [
+ "improvement",
+ "security"
+ ]
+ },
{
"date": "2026-08-16",
"type": "update",
@@ -464,6 +475,17 @@
"infra"
]
},
+ {
+ "date": "2026-08-16",
+ "type": "update",
+ "title": "Web search answers again, and a stray address can no longer tie up the server",
+ "summary": "Three repairs on the public API. Web search had been answering nothing but an error: the question went to Google's grounded search as designed, but the model was given a single budget to both think and reply, spent all of it thinking, and came back empty, which we correctly reported as a failure and wrongly did so on every single query. Thinking now has its own allowance on top of the answer, and when a search does come back empty the log says why instead of leaving the next person to guess. Second, the machine-readable directory at the root of the site, the file other agents read to learn what three.ws sells, would hang forever on a handful of odd names rather than saying no such thing, and a request that never ends holds a server slot until it is cut off. Every unknown name now gets a plain not-found. Third, at checkout, a wallet that hands back a payment the network could never accept is now told so at the moment it happens, instead of the modal saying sending and the error arriving later from the payment processor.",
+ "link": null,
+ "tags": [
+ "fix",
+ "security"
+ ]
+ },
{
"date": "2026-08-15",
"type": "update",
diff --git a/public/changelog.xml b/public/changelog.xml
index a240a755c..b7f38ef09 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -142,6 +142,14 @@
<category>fix</category>
<description>An audit of the account endpoints found one real break and two smaller ones. The activity feed on /community and your personal feed ask for the next page of results by passing the last item’s timestamp back; if that value arrived malformed, from a hand-edited link or a stale bookmark, the database rejected it and the entire feed came back as a server error with nothing to act on. It now answers with a plain &quot;that is not a timestamp&quot; so the page can recover and reload from the top. The referral code editor stated its length rule with a typographic dash that read as a minus sign on some devices, and now spells it out. The purchase history endpoint also documented the wrong default view: it always merges your purchases and your sales, which is what the dashboard shows.</description>
</item>
+ <item>
+ <title>Seeding an agent from your X account no longer asks for permission to post as you</title>
+ <link>https://three.ws/settings</link>
+ <guid isPermaLink="false">2026-08-16:Seeding an agent from your X account no longer asks for permission to post as you</guid>
+ <pubDate>Sun, 16 Aug 2026 12:00:00 GMT</pubDate>
+ <category>improvement</category>
+ <description>Teaching an agent your voice from your public X posts required connecting X first, and that connect asked X for everything the platform can do with an account, including posting and uploading media on your behalf. Reading your posts once and writing as you are two different things to agree to, and only the first one is what seeding needs. The Connect button on the X card in Settings now asks X for read access to your profile and posts and nothing else, and it says so before you click. Posting is its own connect, offered right beside it and labelled as such, and Reconnect keeps whichever of the two you already chose rather than quietly widening it. If a connection cannot read your posts at all, the card now says which permission is missing and offers a reconnect instead of showing you a consent screen for a seed that could not run, and an agent trying to post through a read-only connection is told exactly that instead of failing against X with nothing to act on. Everything else about the lane is unchanged: nothing is read until you consent on a screen that lists what is read and stored, and revoking still deletes every memory the seeding produced.</description>
+ </item>
<item>
<title>Shared agent links keep their preview card through a chain hiccup</title>
<link>https://three.ws/changelog</link>
@@ -350,6 +358,14 @@
<category>fix</category>
<description>The rollup that turns launch history into wallet reputation was judging 80 coins every five minutes while the intel firehose was recording about 32,000 new mints a day, so it fell roughly 8,000 coins a day behind. That backlog does not wait its turn: the rollup works oldest-first and only reaches back 14 days, which is exactly when retention prunes the record, so the tail of the queue aged out and those buyers never counted toward anyone’s reputation at all. 309,000 coins were sitting unjudged with the oldest already 8.4 days from the cliff. The per-run budget is now 400, which outruns the firehose several times over, drains the backlog within days and then idles. Scores across the smart-money surfaces get their full evidence base back. The operations health board also tracks the retention and reconstruct sweeps, so a stall in either is visible instead of showing up later as a symptom.</description>
</item>
+ <item>
+ <title>Web search answers again, and a stray address can no longer tie up the server</title>
+ <link>https://three.ws/changelog</link>
+ <guid isPermaLink="false">2026-08-16:Web search answers again, and a stray address can no longer tie up the server</guid>
+ <pubDate>Sun, 16 Aug 2026 12:00:00 GMT</pubDate>
+ <category>fix</category>
+ <description>Three repairs on the public API. Web search had been answering nothing but an error: the question went to Google's grounded search as designed, but the model was given a single budget to both think and reply, spent all of it thinking, and came back empty, which we correctly reported as a failure and wrongly did so on every single query. Thinking now has its own allowance on top of the answer, and when a search does come back empty the log says why instead of leaving the next person to guess. Second, the machine-readable directory at the root of the site, the file other agents read to learn what three.ws sells, would hang forever on a handful of odd names rather than saying no such thing, and a request that never ends holds a server slot until it is cut off. Every unknown name now gets a plain not-found. Third, at checkout, a wallet that hands back a payment the network could never accept is now told so at the moment it happens, instead of the modal saying sending and the error arriving later from the payment processor.</description>
+ </item>
<item>
<title>3D viewer: shared model links keep their name, and every button on the page does something</title>
<link>https://three.ws/viewer</link>
diff --git a/tests/api/web-search-grounded.test.js b/tests/api/web-search-grounded.test.js
new file mode 100644
index 000000000..9b9c56ba2
--- /dev/null
+++ b/tests/api/web-search-grounded.test.js
@@ -0,0 +1,126 @@
+/**
+ * Grounded web search (api/_lib/web-search.js): request budget + failure detail.
+ *
+ * /api/web-search answered 502 on every production query on 2026-08-16. The
+ * request asked Vertex Gemini 2.5 Flash for a grounded answer with a flat
+ * maxOutputTokens of 1024 and no thinking cap. Gemini 2.5 reasons by default and
+ * bills those tokens against maxOutputTokens WITHOUT returning them (the exact
+ * behaviour api/_lib/vertex-gemini.js already documents and funds around on the
+ * OpenAI-compat path), so the reply came back with no text and no grounding
+ * chunks, groundedSearch threw "empty grounded response", and the handler turned
+ * that into a 502.
+ *
+ * These tests pin the two halves of the repair: the reasoning cap is declared AND
+ * funded on top of the visible budget, and an empty response now names its own
+ * cause so the next 502 is diagnosable from one log line.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+
+// The module mints a real GCP OAuth token at call time; the tests are about the
+// request body and the failure reporting, so stub the token out.
+vi.mock('../../api/_lib/gcp-auth.js', () => ({ getGcpAccessToken: async () => 'test-token' }));
+
+const { groundedSearch, webSearchAvailable } = await import('../../api/_lib/web-search.js');
+
+const OLD_ENV = { ...process.env };
+
+function jsonResponse(body, ok = true, status = 200) {
+ return {
+ ok,
+ status,
+ json: async () => body,
+ text: async () => JSON.stringify(body),
+ };
+}
+
+beforeEach(() => {
+ process.env.GOOGLE_CLOUD_PROJECT = 'test-project';
+ process.env.VERTEX_GEMINI_THINKING_BUDGET = '512';
+});
+
+afterEach(() => {
+ process.env = { ...OLD_ENV };
+ vi.restoreAllMocks();
+ vi.unstubAllGlobals();
+});
+
+describe('groundedSearch request shape', () => {
+ it('is gated by GOOGLE_CLOUD_PROJECT', () => {
+ expect(webSearchAvailable()).toBe(true);
+ delete process.env.GOOGLE_CLOUD_PROJECT;
+ expect(webSearchAvailable()).toBe(false);
+ });
+
+ it('caps reasoning and funds it ON TOP of the visible answer budget', async () => {
+ let sent;
+ vi.stubGlobal('fetch', async (_url, init) => {
+ sent = JSON.parse(init.body);
+ return jsonResponse({
+ candidates: [
+ {
+ content: { parts: [{ text: 'Solana is a high-throughput L1.' }] },
+ groundingMetadata: {
+ groundingChunks: [{ web: { uri: 'https://solana.com', title: 'Solana', domain: 'solana.com' } }],
+ webSearchQueries: ['what is solana'],
+ },
+ },
+ ],
+ });
+ });
+
+ const out = await groundedSearch('what is solana');
+ expect(out.answer).toContain('Solana');
+ expect(out.sources).toHaveLength(1);
+
+ const cfg = sent.generationConfig;
+ expect(cfg.thinkingConfig.thinkingBudget).toBe(512);
+ // The reasoning cap must be additional, never carved out of the caller's
+ // answer budget: that subtraction is what emptied the response.
+ expect(cfg.maxOutputTokens).toBeGreaterThan(512);
+ expect(cfg.maxOutputTokens).toBe(1024 + 512);
+ expect(sent.tools).toEqual([{ googleSearch: {} }]);
+ });
+
+ it('honours a VERTEX_GEMINI_THINKING_BUDGET override', async () => {
+ process.env.VERTEX_GEMINI_THINKING_BUDGET = '0';
+ let sent;
+ vi.stubGlobal('fetch', async (_url, init) => {
+ sent = JSON.parse(init.body);
+ return jsonResponse({ candidates: [{ content: { parts: [{ text: 'answer' }] } }] });
+ });
+
+ await groundedSearch('q');
+ expect(sent.generationConfig.thinkingConfig.thinkingBudget).toBe(0);
+ expect(sent.generationConfig.maxOutputTokens).toBe(1024);
+ });
+});
+
+describe('groundedSearch failure reporting', () => {
+ it('names the finish reason when the model returns neither text nor sources', async () => {
+ vi.stubGlobal('fetch', async () =>
+ jsonResponse({ candidates: [{ finishReason: 'MAX_TOKENS', content: { parts: [] } }] }),
+ );
+
+ await expect(groundedSearch('q')).rejects.toThrow(/finishReason=MAX_TOKENS/);
+ });
+
+ it('names a prompt-level block reason', async () => {
+ vi.stubGlobal('fetch', async () => jsonResponse({ candidates: [], promptFeedback: { blockReason: 'SAFETY' } }));
+
+ await expect(groundedSearch('q')).rejects.toThrow(/promptBlockReason=SAFETY/);
+ });
+
+ it('surfaces an upstream non-2xx with its status', async () => {
+ vi.stubGlobal('fetch', async () => jsonResponse({ error: 'nope' }, false, 403));
+
+ await expect(groundedSearch('q')).rejects.toThrow(/upstream 403/);
+ });
+
+ it('refuses an empty query before spending a token', async () => {
+ const fetchSpy = vi.fn();
+ vi.stubGlobal('fetch', fetchSpy);
+ await expect(groundedSearch(' ')).rejects.toThrow(/empty query/);
+ expect(fetchSpy).not.toHaveBeenCalled();
+ });
+});
diff --git a/tests/api/wk-dispatch.test.js b/tests/api/wk-dispatch.test.js
new file mode 100644
index 000000000..c456c1777
--- /dev/null
+++ b/tests/api/wk-dispatch.test.js
@@ -0,0 +1,84 @@
+/**
+ * /api/wk dispatcher: name lookup must never touch Object.prototype.
+ *
+ * The well-known dispatcher resolved handlers with a bare `DISPATCH[name]` on an
+ * object literal, so every inherited key was a "route". Measured against
+ * production on 2026-08-16, before the fix:
+ *
+ * GET /api/wk?name=constructor → no response at all; the request held a
+ * request slot until the gateway gave up
+ * (Object was called as the handler and
+ * returned a value instead of replying)
+ * GET /api/wk?name=hasOwnProperty → 500 internal_error
+ *
+ * Both are reachable anonymously, and `/wk/<name>` + `/.well-known/*` route into
+ * the same dispatcher. The hang is the serious half: it is a free way to pin
+ * server capacity. These tests pin the own-property lookup and the reflection
+ * cap that goes with it.
+ */
+
+import { describe, it, expect } from 'vitest';
+import handler from '../../api/wk.js';
+
+function fakeReq(name) {
+ const qs = name === undefined ? '' : `?name=${encodeURIComponent(name)}`;
+ return { method: 'GET', headers: {}, url: `/api/wk${qs}`, query: name === undefined ? {} : { name } };
+}
+
+function fakeRes() {
+ const headers = {};
+ return {
+ statusCode: 0,
+ body: undefined,
+ ended: false,
+ setHeader(k, v) {
+ headers[String(k).toLowerCase()] = v;
+ },
+ getHeader(k) {
+ return headers[String(k).toLowerCase()];
+ },
+ end(b) {
+ this.body = b;
+ this.ended = true;
+ },
+ _headers: headers,
+ };
+}
+
+async function call(name) {
+ const res = fakeRes();
+ await handler(fakeReq(name), res);
+ return { res, json: res.body ? JSON.parse(res.body) : undefined };
+}
+
+describe('/api/wk name dispatch', () => {
+ for (const inherited of ['constructor', 'hasOwnProperty', 'toString', 'valueOf', '__proto__', 'isPrototypeOf']) {
+ it(`answers 404 for the inherited key "${inherited}" instead of hanging or 500ing`, async () => {
+ const { res, json } = await call(inherited);
+ expect(res.ended).toBe(true);
+ expect(res.statusCode).toBe(404);
+ expect(json.error).toBe('not_found');
+ });
+ }
+
+ it('still serves a real well-known resource', async () => {
+ const { res, json } = await call('x402');
+ expect(res.statusCode).toBe(200);
+ expect(Array.isArray(json.schemes)).toBe(true);
+ });
+
+ it('answers 404 with no name', async () => {
+ const { res, json } = await call(undefined);
+ expect(res.statusCode).toBe(404);
+ expect(json.error).toBe('not_found');
+ });
+
+ it('caps how much of the caller input it echoes back', async () => {
+ const { res, json } = await call('A'.repeat(5000));
+ expect(res.statusCode).toBe(404);
+ // Prefix + at most 64 echoed characters, not the whole 5 KB.
+ expect(json.error_description.length).toBeLessThan(120);
+ expect(json.error_description).toContain('A'.repeat(64));
+ expect(json.error_description).not.toContain('A'.repeat(65));
+ });
+});
diff --git a/tests/api/x402-checkout-encode.test.js b/tests/api/x402-checkout-encode.test.js
new file mode 100644
index 000000000..b19ddef00
--- /dev/null
+++ b/tests/api/x402-checkout-encode.test.js
@@ -0,0 +1,74 @@
+/**
+ * POST /api/x402-checkout?action=encode rejects a transaction that can never
+ * settle, keep passing everything else through.
+ *
+ * encode wraps the buyer's signed transaction into the base64 X-PAYMENT envelope.
+ * Its pre-flight check (confirmSolanaPayment) is deliberately conservative:
+ * anything it cannot decode returns `inconclusive` so a parsing quirk never
+ * rejects a real payment. That left one gap worth closing: a blob that does not
+ * deserialize into a Solana transaction AT ALL used to come back 200 with a fully
+ * formed X-PAYMENT header, so the buyer saw "Sending…" and then an opaque
+ * facilitator error instead of a clear one at the step that produced the bad
+ * signature. Verified against a live handler before the fix: garbage bytes in,
+ * 200 + x_payment out.
+ *
+ * The narrow rejection is safe by construction. An undeserializable blob has no
+ * valid interpretation, so it cannot be a false reject.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { confirmSolanaPayment } from '../../api/_lib/x402-solana-confirm.js';
+
+const USDC = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
+const PAY_TO = '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM';
+
+const requirement = { asset: USDC, payTo: PAY_TO, amount: '10000' };
+
+describe('encode pre-flight: undeserializable transactions are distinguishable', () => {
+ it('reports undeserializable_transaction for random bytes', () => {
+ const garbage = Buffer.alloc(300, 7).toString('base64');
+ const check = confirmSolanaPayment({
+ paymentPayload: { payload: { transaction: garbage } },
+ requirement,
+ });
+ // Not a hard `confirmed: false`, which is why the handler needs the reason.
+ expect(check.confirmed).toBeUndefined();
+ expect(check.inconclusive).toBe(true);
+ expect(check.reason).toBe('undeserializable_transaction');
+ });
+
+ it('reports a different reason for a missing transaction, so the 400 stays narrow', () => {
+ const check = confirmSolanaPayment({ paymentPayload: { payload: {} }, requirement });
+ expect(check.inconclusive).toBe(true);
+ expect(check.reason).toBe('no_serialized_transaction');
+ });
+
+ it('does not flag a real prepared transaction as undeserializable', async () => {
+ // Build the same v0 message shape handlePrepare emits, then round-trip it.
+ const { PublicKey, TransactionMessage, VersionedTransaction } = await import('@solana/web3.js');
+ const {
+ TOKEN_PROGRAM_ID,
+ ASSOCIATED_TOKEN_PROGRAM_ID,
+ getAssociatedTokenAddressSync,
+ createTransferCheckedInstruction,
+ } = await import('@solana/spl-token');
+
+ const mint = new PublicKey(USDC);
+ const payTo = new PublicKey(PAY_TO);
+ const buyer = new PublicKey(PAY_TO);
+ const senderAta = getAssociatedTokenAddressSync(mint, buyer, false, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID);
+ const receiverAta = getAssociatedTokenAddressSync(mint, payTo, false, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID);
+ const message = new TransactionMessage({
+ payerKey: payTo,
+ recentBlockhash: '11111111111111111111111111111111',
+ instructions: [
+ createTransferCheckedInstruction(senderAta, mint, receiverAta, buyer, 10000n, 6, [], TOKEN_PROGRAM_ID),
+ ],
+ }).compileToV0Message();
+ const tx = Buffer.from(new VersionedTransaction(message).serialize()).toString('base64');
+
+ const check = confirmSolanaPayment({ paymentPayload: { payload: { transaction: tx } }, requirement });
+ expect(check.reason).not.toBe('undeserializable_transaction');
+ expect(check.confirmed).toBe(true);
+ });
+});