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(okx): tell a charged buyer that a failed generation already settled instead of promising a free retry

nirholas5fa2cc4254b7
diff --git a/api/_mcp-studio/studio-shape.js b/api/_mcp-studio/studio-shape.js
index 60007256e..e3e3b37e5 100644
--- a/api/_mcp-studio/studio-shape.js
+++ b/api/_mcp-studio/studio-shape.js
@@ -71,7 +71,12 @@ export function shapeSubmit(job, base, prompt, { pollPath = STUDIO_POLL_PATH } =
}
// Shape a forge poll response into { status:'pending'|'done'|'error', ... }.
-export function shapePoll(data, base, jobId, title, { pollPath = STUDIO_POLL_PATH } = {}) {
+// `paid` says whether the surface asking is a metered one. It only changes what
+// a FAILED job is told, and it has to: the free lanes really are free to retry,
+// while a metered row settles the moment the lane accepts a job, so the free
+// wording would tell a charged buyer something false about their money. See the
+// failed branch below.
+export function shapePoll(data, base, jobId, title, { pollPath = STUDIO_POLL_PATH, paid = false } = {}) {
const glbUrl = typeof data?.glb_url === 'string' ? data.glb_url : '';
const preview = previewOf(data);
const tier = tierOf(data);
@@ -88,12 +93,26 @@ export function shapePoll(data, base, jobId, title, { pollPath = STUDIO_POLL_PAT
};
}
if (data?.status === 'failed') {
+ // The message is already sanitized by /api/gpt-forge, and the lane only
+ // reports a failure once its own backend failover chain is exhausted, so
+ // this is terminal for THIS job. What a retry costs depends on the
+ // surface, and the difference is not cosmetic: on a metered row payment
+ // settles when the lane accepts the job, so the free lanes' "it costs
+ // nothing to try again" would tell a buyer who was already charged
+ // something false. Neither note claims anything about one particular job
+ // (a status row polls any job id it is handed); each states its own
+ // surface's payment model, which is what the caller has to act on. The
+ // exact per-call answer is the PAYMENT-RESPONSE receipt from the submit.
+ const upstream = String(data?.error || '3D generation hit a snag upstream').trim().replace(/[.!]+$/, '');
+ const lanes = Array.isArray(data?.retry_backends) ? data.retry_backends.filter((b) => typeof b === 'string') : [];
+ const note = paid
+ ? 'Jobs here settle when the lane accepts them, so a retry is a new paid call.'
+ : 'It costs nothing to try again.';
return {
status: 'error',
job: jobId,
- // The message is already sanitized by /api/gpt-forge; generation is free
- // to retry, so a failed job costs the caller nothing.
- error: data?.error || '3D generation hit a snag upstream, it costs nothing to try again.',
+ error: `${upstream}. ${note}`,
+ ...(lanes.length ? { retryBackends: lanes } : {}),
};
}
// queued / running / anything transient stays pending; keep the title on the
diff --git a/api/_okx3d/forge.js b/api/_okx3d/forge.js
index 86bd21173..53a6cb4ef 100644
--- a/api/_okx3d/forge.js
+++ b/api/_okx3d/forge.js
@@ -106,7 +106,10 @@ function laneError(err) {
// A pending job is polled at the free forge-status endpoint, so `poll` is a
// real URL an agent can hit, and `poll_tool` names the JSON-RPC tool to call
// there. Both, because buyers in this marketplace read either.
-const POLL_OPTS = { pollPath: STATUS_ENDPOINT };
+// `paid: true` is what makes a failed-job message honest on this surface: these
+// rows settle when the lane accepts the job, so the free lanes' "it costs
+// nothing to try again" would be a lie told to a buyer who was already charged.
+const POLL_OPTS = { pollPath: STATUS_ENDPOINT, paid: true };
// Every finished creation has a public page at /m/<creation id>: the model
// spinning in a viewer, AR and fullscreen, download, embed and share, comments
diff --git a/docs/okx-marketplace.md b/docs/okx-marketplace.md
index b722f4ef7..3e51d69b8 100644
--- a/docs/okx-marketplace.md
+++ b/docs/okx-marketplace.md
@@ -26,12 +26,36 @@ documented at the bottom of this page.
> [x402 payments](./x402.md) · seller-side protocol spec:
> [`specs/okx-agent-payments.md`](../specs/okx-agent-payments.md)
-The **single source of truth** for every service (names, 2-part OKX descriptions, prices,
+The **single source of truth** for every service (names, OKX listing copy, prices,
endpoints, input schemas, and which rows are listed) is
[`api/_lib/okx-catalog.js`](../api/_lib/okx-catalog.js). The free catalog endpoint below
serves it verbatim and the listing submission is generated from it, so the docs, the
endpoints, and the OKX listing cannot drift apart.
+### The A2MCP listing description format
+
+OKX listing QA requires **four** newline-separated parts on an A2MCP service and rejects a
+listing missing any of them (the contract is stated in `onchainos agent update --help`).
+Submitting two parts is what earned the standing review remark on agent #2632: "The service
+you submitted is missing a complete description, parameter details, and usage examples."
+
+| Part | Content | Where it comes from |
+| --- | --- | --- |
+| 1 | What the service does | `describes.capability` |
+| 2 | Every parameter on ONE line, `;`-separated, each `<name> (<type>, required/optional): <meaning>` | generated from `inputSchema` + `describes.params` |
+| 3 | Request method (`POST`/`GET`, plus the MCP tool name where there is one) | generated from `kind` + `tool` |
+| 4 | A working `curl` against the real endpoint | generated from `endpoint` + `describes.example` |
+
+Parts 2 and 4 are **derived, never hand-written**: `parameterSpec()` reads the row's own
+JSON Schema, so a renamed argument renames itself in the listing, and `requestExample()`
+builds the call from example arguments that the test suite validates against that same
+schema. A published example the endpoint would reject cannot ship. `validateCatalog()`
+fails any listed row whose schema and documented parameters disagree, whose description is
+not four non-empty parts, or which exceeds OKX's 2000 half-width cap.
+
+Back-burner rows (`listed: false`) are held to the catalog rules only; they pick up the
+four-part rules when they return to the listing.
+
---
## Free discovery lane
@@ -166,8 +190,13 @@ the viewer, the AR launch and the page.
- `previewImageUrl` is the painted concept view the forge produces before the mesh, so you
can show something the moment it exists.
-A failed job answers `status: "error"` with an actionable message. Generation failures are
-free to retry.
+A failed job answers `status: "error"` with an actionable message and, when the generator can
+name them, `retryBackends`: the alternate engines that can still serve this request. The lane
+exhausts its own backend failover chain before it ever reports a failure, so an `error` frame
+is terminal for that job. **A retry is a new paid call**: these rows settle when the lane
+accepts a job (see Payment semantics below), so a job that fails during generation has been
+charged. Over the 30 days to 2026-09-02, 255 of 10,278 forge jobs (2.5%) ended `failed` after
+acceptance.
### Payment semantics
@@ -177,7 +206,9 @@ unit tests in [`tests/api/okx-forge.test.js`](../tests/api/okx-forge.test.js).
- **You pay only when the job is accepted.** Input validation and the age-13+ content gate
run before settlement; a rejected prompt or a malformed argument fails the call and
- **no payment settles**.
+ **no payment settles**. Acceptance is the line: once the lane takes the job the payment
+ settles, so a failure that happens later, during generation, has been charged and a retry
+ is a new paid call. Nothing here refunds after settlement.
- **HD means HD.** If the high-detail lane will not take a job, `forge-hd` answers
`tier_unavailable` (with `charged: false` and a `retry_after`) instead of quietly serving
a standard mesh at the HD price. That refusal is also before settlement.
diff --git a/tests/okx-chat-bot.test.js b/tests/okx-chat-bot.test.js
index ef3a3bca4..3ddf9f23a 100644
--- a/tests/okx-chat-bot.test.js
+++ b/tests/okx-chat-bot.test.js
@@ -9,7 +9,7 @@
// Pure logic only: no daemon, no wallet, no network, no DB.
import http from 'node:http';
-import { existsSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
@@ -97,14 +97,18 @@ describe('okx-chat-bot session classifier', () => {
});
describe('okx-chat-bot provider selection', () => {
+ // A host with no interactive CLI login, so these assertions read the env and
+ // nothing else. mkdtemp gives a home that provably holds no credential file.
+ const bare = mkdtempSync(join(tmpdir(), 'okx-bot-nohome-'));
+
it('prefers Claude when an Anthropic credential is present', () => {
- const r = resolveProvider({ ANTHROPIC_API_KEY: 'sk-ant-x', OPENAI_API_KEY: 'sk-y' });
+ const r = resolveProvider({ ANTHROPIC_API_KEY: 'sk-ant-x', OPENAI_API_KEY: 'sk-y' }, bare);
expect(r.provider).toBe('claude');
expect(r.credentialed).toBe(true);
});
it('falls back to the codex CLI when only an OpenAI key exists', () => {
- const r = resolveProvider({ OPENAI_API_KEY: 'sk-y' });
+ const r = resolveProvider({ OPENAI_API_KEY: 'sk-y' }, bare);
expect(r.provider).toBe('codex');
expect(r.credentialed).toBe(true);
});
@@ -112,17 +116,30 @@ describe('okx-chat-bot provider selection', () => {
// A provider CLI with no key spawns, fails to authenticate, and the buyer
// just sees silence. That must surface as uncredentialed, never as ready.
it('reports uncredentialed rather than pretending a keyless CLI will answer', () => {
- const r = resolveProvider({});
+ const r = resolveProvider({}, bare);
expect(r.credentialed).toBe(false);
expect(classify({ ...ONLINE, providerCredentialed: r.credentialed }).ready).toBe(false);
});
+ // The stopgap host has no key at all: its claude CLI was logged in by a human
+ // and the adapter authors replies from that grant. Calling it uncredentialed
+ // is a false red on a host that demonstrably answers buyers.
+ it('counts an interactive claude CLI login as a credential', () => {
+ const home = mkdtempSync(join(tmpdir(), 'okx-bot-home-'));
+ mkdirSync(join(home, '.claude'), { recursive: true });
+ writeFileSync(join(home, '.claude', '.credentials.json'), '{}');
+ const r = resolveProvider({}, home);
+ expect(r).toMatchObject({ provider: 'claude', credentialed: true });
+ expect(r.reason).toMatch(/interactive login/);
+ rmSync(home, { recursive: true, force: true });
+ });
+
it('honours an explicit pin and still tells the truth about its credential', () => {
- expect(resolveProvider({ OKX_BOT_AI_PROVIDER: 'codex', OPENAI_API_KEY: 'k' })).toMatchObject({
+ expect(resolveProvider({ OKX_BOT_AI_PROVIDER: 'codex', OPENAI_API_KEY: 'k' }, bare)).toMatchObject({
provider: 'codex',
credentialed: true,
});
- expect(resolveProvider({ OKX_BOT_AI_PROVIDER: 'claude', OPENAI_API_KEY: 'k' })).toMatchObject({
+ expect(resolveProvider({ OKX_BOT_AI_PROVIDER: 'claude', OPENAI_API_KEY: 'k' }, bare)).toMatchObject({
provider: 'claude',
credentialed: false,
});