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(rate-limit): give single-use windows a refund path so a failed call does not burn the caller's window

nirholas2ad7bd4d1e4d
diff --git a/api/_lib/rate-limit.js b/api/_lib/rate-limit.js
index ff429ca9a..990d33b1d 100644
--- a/api/_lib/rate-limit.js
+++ b/api/_lib/rate-limit.js
@@ -140,6 +140,21 @@ function failClosedLimiter({ limit, window }) {
* commands are what keep the Upstash quota alive (June 2026 outage). Never
* combine with `critical`.
*/
+/**
+ * Hand a consumed hit back to its bucket, for the one case that justifies it:
+ * the request was charged, then produced nothing at all because a dependency we
+ * own was unavailable. The caller keeps its window instead of paying for our
+ * outage. Only single-use windows may do this (see the Redis note in
+ * resilientLimiter), and the refund must be unconditional at that point in the
+ * handler: a refund on a path that DID something turns the limiter off.
+ */
+export function refundLimit(name, opts, id) {
+ if (opts.limit !== 1) {
+ throw new Error(`refundLimit: ${name} is not a single-use window (limit ${opts.limit})`);
+ }
+ return getLimiter(name, opts).refund(id);
+}
+
function getLimiter(name, opts) {
const key = `${name}:${opts.limit}:${opts.window}`;
if (limiters.has(key)) return limiters.get(key);
@@ -324,6 +339,29 @@ function resilientLimiter(rl, name, opts) {
};
}
},
+ // Upstash has no "give one token back": resetUsedTokens clears the whole
+ // identifier. That equals a refund only on a single-use window, which is
+ // why getLimiter refuses to expose refund on any other bucket. A refund
+ // that cannot reach Redis is dropped rather than retried: the cost of
+ // losing it is one caller waiting out a window they should not have
+ // spent, and failing the request they are already being apologised to
+ // for would be worse.
+ async refund(id) {
+ try {
+ if (!circuitAllows()) throw new RlCircuitOpenError();
+ await rl.resetUsedTokens(id);
+ circuitRecordSuccess();
+ return true;
+ } catch (err) {
+ if (!err?.circuitOpen) {
+ circuitRecordFailure();
+ if (isRedisQuotaError(err)) warnQuotaOnce();
+ else warnDegradedOnce(name, err);
+ }
+ if (durable) return durable.refund(id);
+ return false;
+ }
+ },
};
}
@@ -510,6 +548,14 @@ function fallbackLimiter(name, opts) {
return lastResort.limit(id);
}
},
+ async refund(id) {
+ try {
+ return await pg.refund(id);
+ } catch (err) {
+ warnDegradedOnce(`${name}:pg`, err);
+ return lastResort.refund(id);
+ }
+ },
};
}
@@ -1684,6 +1730,11 @@ export const limits = {
// per run. 1 seed per agent per 6 hours, matching the X lane.
githubSeed: (agentId) =>
getLimiter('memory:seed:github', { limit: 1, window: '6 h' }).limit(agentId),
+ // Give the window back when a seed run wrote nothing because every model
+ // provider was busy at once. Without this a platform-side outage costs the
+ // owner six hours on a run that never touched their agent's memories.
+ githubSeedRefund: (agentId) =>
+ refundLimit('memory:seed:github', { limit: 1, window: '6 h' }, agentId),
// Consent-first Farcaster memory seeding: reads a hub (or Neynar) and runs one
// LLM pass per seed. 1 seed per agent per 6 hours, matching the X and GitHub
// lanes. Issuing a signing challenge is deliberately outside this budget so a
diff --git a/api/agents/[id]/memory-seed-github.js b/api/agents/[id]/memory-seed-github.js
index 71afe1abf..fe697a38c 100644
--- a/api/agents/[id]/memory-seed-github.js
+++ b/api/agents/[id]/memory-seed-github.js
@@ -177,9 +177,10 @@ async function handlePost(req, res, agentId) {
// here means every lane was busy or down at once, not a bug in this route.
// Left uncaught it reached the client as a bare "internal error, quote ref …"
// and paged ops as an unhandled 5xx on what is a routine upstream throttle.
- // The budget above is already spent by this point and this abstraction has no
- // refund, so the reply says plainly when the next attempt is allowed instead
- // of inviting a retry that would only earn a 429.
+ // The budget above is already spent by this point, and the outage is ours,
+ // not the owner's mistake: hand the window back so they can retry as soon as
+ // a provider frees up instead of waiting out six hours for a run that read
+ // nothing and wrote nothing.
let raw;
try {
({ text: raw } = await llmComplete({
@@ -188,28 +189,42 @@ async function handlePost(req, res, agentId) {
user: `Extract up to ${MAX_FACTS} memory facts from this GitHub material:\n\n${document}`,
}));
} catch (err) {
- const retryAt = rl.reset ? new Date(rl.reset).toISOString() : null;
- const minutes = rl.reset ? Math.max(1, Math.ceil((rl.reset - Date.now()) / 60_000)) : null;
+ const refunded = await limits.githubSeedRefund(agentId).catch(() => false);
+ const retryAt = refunded || !rl.reset ? null : new Date(rl.reset).toISOString();
+ const minutes = retryAt ? Math.max(1, Math.ceil((rl.reset - Date.now()) / 60_000)) : null;
return error(
res,
503,
'distill_unavailable',
`every model provider is busy right now, so nothing was seeded and your memories are unchanged${
- minutes ? `. This agent can be seeded again in about ${minutes} minute${minutes === 1 ? '' : 's'}` : '. Try this agent again later'
+ refunded
+ ? '. This attempt did not use up your six-hour window, so you can try again in a few minutes'
+ : minutes
+ ? `. This agent can be seeded again in about ${minutes} minute${minutes === 1 ? '' : 's'}`
+ : '. Try this agent again later'
}`,
- { retry_at: retryAt, providers_tried: err?.attempts?.map((a) => a.provider) ?? [] },
+ {
+ retry_at: retryAt,
+ window_refunded: refunded,
+ providers_tried: err?.attempts?.map((a) => a.provider) ?? [],
+ },
);
}
const facts = parseFacts(raw);
const seededAt = new Date().toISOString();
const manifest = selectionManifest(resolved);
+ // Same reasoning as the provider outage above: the agent's memories are
+ // untouched, and the advice to pick more material is worthless if acting on
+ // it means waiting out a six-hour window.
if (facts.length === 0) {
+ const refunded = await limits.githubSeedRefund(agentId).catch(() => false);
return error(
res,
502,
'distill_error',
- 'the selected material did not yield any usable facts — try adding a README or another repository',
+ 'the selected material did not yield any usable facts, so nothing was stored. Add a README or another repository and seed again',
+ { window_refunded: refunded },
);
}
diff --git a/api/mcp-studio.js b/api/mcp-studio.js
index 28e3dc694..5ccda6b7c 100644
--- a/api/mcp-studio.js
+++ b/api/mcp-studio.js
@@ -4,8 +4,10 @@
// GET /api/mcp-studio — not offered (no server-initiated stream) → 405
// OPTIONS — CORS preflight
//
-// A free, NON-CRYPTO, payment-free MCP endpoint exposing ONLY five 3D-generation
-// tools. There is no OAuth, no x402, no wallet, no token, and no PaymentRequired
+// A free, NON-CRYPTO, payment-free MCP endpoint exposing ONLY 3D-generation
+// tools (_mcp-studio/tools.js) and the embodiment/persona tools built on top of
+// them (_mcp-studio/persona-tools.js, which carry their own write rate limit).
+// There is no OAuth, no x402, no wallet, no token, and no PaymentRequired
// anywhere in this server — generation runs operator-funded over /api/forge (the
// platform's server-side keys cover provider cost). Built for the ChatGPT App
// Directory, whose policy disqualifies tokens/credits and embedded payments.