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
feat(x-mentions): route image-to-3D mentions to their handler and settle late image3d replies each tick
nirholasfdd68660d5ab
diff --git a/api/_lib/x-mention-poll.js b/api/_lib/x-mention-poll.jsindex 07509e500..0bde85f59 100644--- a/api/_lib/x-mention-poll.js+++ b/api/_lib/x-mention-poll.js@@ -33,6 +33,7 @@ import { answerOnBehalf } from './x-mention-on-behalf.js';import * as xBudget from './x-budget.js';import { handleAvatar, finishPendingAvatars } from './x-mention-avatar.js';import { finishPendingMakes } from './x-mention-make.js';+import { handleImage3d, finishPendingImage3d } from './x-mention-image3d.js';import { createDeliver } from './x-mention-deliver.js';export const LOCK_KEY = 'x_mentions_lock';@@ -44,7 +45,7 @@ const DAY = 86400;const REFUSED_REPLY = 'I cannot move funds or handle keys, and no one can ask me to. I make 3D models: try "make a red vintage scooter". https://three.ws/grok';/** Intents whose dedicated handler is a later order; they answer with help until it lands. */-const UNBUILT_HANDLERS = Object.freeze(new Set(['make', 'image3d', 'launch']));+const UNBUILT_HANDLERS = Object.freeze(new Set(['make', 'launch']));function intEnv(env, name, fallback) {const n = Number.parseInt(env[name] ?? '', 10);@@ -107,7 +108,7 @@ async function composeAnswer({ mention, parsed, account, compose }) {* Only ever throws for a store failure on the mention row itself, which the* caller treats as "not fully recorded" and stops the batch there.*/-export async function handleMention({ mention, account, limits, env, store = mentionStore, compose = composePublicReply, adapterFactory = createXAdapter, guard = guardMention, paused = isPaused, budget = xBudget, request = null, onBehalf = answerOnBehalf, knownBots = null, avatar = handleAvatar }) {+export async function handleMention({ mention, account, limits, env, store = mentionStore, compose = composePublicReply, adapterFactory = createXAdapter, guard = guardMention, paused = isPaused, budget = xBudget, request = null, onBehalf = answerOnBehalf, knownBots = null, avatar = handleAvatar, image3d = handleImage3d }) {const parsed = parseMentionIntent(mention, account);const dryRun = true;const { inserted } = await store.recordMention({ mention, parsed, dryRun });@@ -160,6 +161,11 @@ export async function handleMention({ mention, account, limits, env, store = menif (result.decision === 'reply') await budget.recordPosts(1);return { tweetId: mention.id, intent: 'avatar', decision: result.decision, reason: result.reason, text: result.text, dry_run: dryRun };}+ if (parsed.intent === 'image3d') {+ const result = await image3d({ tweetId: mention.id, authorId: mention.userId || mention.author?.id, args: parsed.args, dryRun });+ if (result.decision === 'reply') await budget.recordPosts(1);+ return { tweetId: mention.id, intent: 'image3d', decision: result.decision, reason: result.reason, text: result.text, dry_run: dryRun };+ }const answer = await composeAnswer({ mention, parsed, account, compose });const adapter = adapterFactory({ mention, parsed, env, policyDryRun: true });await adapter.sendText(mention.id, answer.text);@@ -227,7 +233,7 @@ export async function pollAccount({ descriptor, env = process.env, maxMentions =let stoppedAt = null;for (const mention of batch) {try {- decisions.push(await handleMention({ mention, account: page.account, limits, env, store, compose: deps.compose, adapterFactory: deps.adapterFactory, guard: deps.guard, paused: deps.paused, budget: deps.budget, request: resolve, onBehalf: deps.onBehalf, knownBots: deps.knownBots, avatar: deps.avatar }));+ decisions.push(await handleMention({ mention, account: page.account, limits, env, store, compose: deps.compose, adapterFactory: deps.adapterFactory, guard: deps.guard, paused: deps.paused, budget: deps.budget, request: resolve, onBehalf: deps.onBehalf, knownBots: deps.knownBots, avatar: deps.avatar, image3d: deps.image3d }));lastRecorded = mention.id;} catch (err) {stoppedAt = mention.id;@@ -264,9 +270,9 @@ export async function listAccounts({ env = process.env, agentAccounts = async ()}/**- * Settle the make and avatar jobs that outlived their mention. Gated like any+ * Settle the make, avatar and image-to-3D jobs that outlived their mention. Gated like any* other reply (kill switch, then the post budget), each finisher isolated so- * one failing never stops the other or the tick. Delivery goes through the X+ * one failing never stops the others or the tick. Delivery goes through the X* adapter: dry rows are recorded, live rows are posted.*/export async function runFollowUps({ env = process.env, deps = {} } = {}) {@@ -284,6 +290,7 @@ export async function runFollowUps({ env = process.env, deps = {} } = {}) {return {makeFollowUp: await run(deps.finishPendingMakes || finishPendingMakes),avatarFollowUp: await run(deps.finishPendingAvatars || finishPendingAvatars),+ image3dFollowUp: await run(deps.finishPendingImage3d || finishPendingImage3d),};}diff --git a/docs/x-mention-bot.md b/docs/x-mention-bot.mdindex 8a9a1d1f4..0eb29e093 100644--- a/docs/x-mention-bot.md+++ b/docs/x-mention-bot.md@@ -74,12 +74,14 @@ npx vitest run tests/x-mention-guard.test.js tests/x-budget.test.js```The kill switch tests assert zero calls to the reply brain and the X adapter.-## Late replies: make and avatar follow-ups+## Late replies: make, avatar and image-to-3D follow-ups-A `make` or `avatar` mention whose 3D job outlives the bounded wait is recorded as `pending`. Every `x-mentions` tick then runs `runFollowUps()` (`api/_lib/x-mention-poll.js`), which calls `finishPendingMakes()` and `finishPendingAvatars()`:+A `make`, `avatar` or `image3d` mention whose 3D job outlives the bounded wait is recorded as `pending`. Every `x-mentions` tick then runs `runFollowUps()` (`api/_lib/x-mention-poll.js`), which calls `finishPendingMakes()`, `finishPendingAvatars()` and `finishPendingImage3d()` (`api/_lib/x-mention-image3d.js`, see [x-mention-image3d.md](x-mention-image3d.md)):-- **Gated like any reply.** The kill switch skips both, and a closed read/post budget gate skips both. The report carries `followUps: { skipped: 'kill_switch' | 'budget' }`.-- **Isolated.** Each finisher runs in its own catch; one throwing reports `{ error }` under `makeFollowUp` or `avatarFollowUp` and the other still runs.+- **Gated like any reply.** The kill switch skips all three, and a closed read/post budget gate skips all three. The report carries `followUps: { skipped: 'kill_switch' | 'budget' }`.+- **Isolated.** Each finisher runs in its own catch; one throwing reports `{ error }` under `makeFollowUp`, `avatarFollowUp` or `image3dFollowUp` and the others still run.- **Delivered through the X adapter.** `api/_lib/x-mention-deliver.js` builds the `deliver` the finishers use on `createXAdapter`. A dry row (`dry_run = true`, the default) is only recorded on the `x_mention_events` row and nothing is posted. A live row is posted by the adapter only when `X_MENTION_BOT_LIVE=1` and a token resolver is supplied (`getAccessToken(row)`); each real post counts against the post budget. With no resolver the adapter stays in dry run, so rows are no longer held as `paused` for lack of a deliver.+The `image3d` intent is routed to `handleImage3d()` in `handleMention` (dry run, same budget and per-author limits as any reply); only `make` and `launch` still answer with help (`handler_not_built`).+Going live stays the separate owner step.diff --git a/prompts/finish/_context/x-grok-PROGRESS.md b/prompts/finish/_context/x-grok-PROGRESS.mdindex 4fd61c2d4..2ff598809 100644--- a/prompts/finish/_context/x-grok-PROGRESS.md+++ b/prompts/finish/_context/x-grok-PROGRESS.md@@ -200,3 +200,10 @@ Added `agent-get-started`, `daily-3d-brief`, `asset-pack`, `avatar-from-photo` t- Evidence: `prompts/x-grok/_generated/image3d-dry-run.json`: 3 own-image reply rows from real public product posts (photo fetch 200, `/m/` link 200). Media: 2 of 3 posters answer 200 image/png; row 2 answers 413 because production `/api/render/glb` caps input at 10 MB and that GLB is 11.5 MB.- Remaining line: three rows with loading media. The 25 MB cap is in `11914b4c8`; after the next deploy rerun `node scripts/x-mention-image3d-dry-run.mjs --posts <ids>` to record row 2 as 200, then delete the order file. Owner: whoever runs the deploy (gated).- Not wired: `x-mention-poll.js` still routes `image3d` to help via `UNBUILT_HANDLERS`, and no cron calls `finishPendingImage3d`. `x-mention-image3d.js` imports the in-flight `x-mention-make.js`.++## 2026-10-09: order 053 image-to-3D wired into the x-mentions poll (dry run)++- `handleMention` now routes the `image3d` intent to `handleImage3d()` (removed from `UNBUILT_HANDLERS`; `make` and `launch` still answer help). `runFollowUps()` also runs `finishPendingImage3d()` behind the same kill switch and budget gate, error-isolated, delivering through the same `createDeliver()`; report key `image3dFollowUp`.+- Git check: `x-mention-make.js`, `x-mention-image3d.js` and their tests were already committed (`git status` clean at start); nothing to commit for them.+- Tests: `tests/x-mention-poll.test.js` extended (image3d routed to its handler against real PGlite with only CDN/vision/store/3D-lane edges replaced; late image3d settle live and dry; failure isolation; kill switch and budget skip all three; tick runs all three). poll + image3d + make + avatar suites: 71 passing. Nothing was posted to X.+- Remaining: unchanged from the 053 entry (rerun the image3d dry-run script after the next deploy; live posting needs the order 928 token resolver).diff --git a/tests/x-mention-poll.test.js b/tests/x-mention-poll.test.jsindex 74da15893..edfe082a4 100644--- a/tests/x-mention-poll.test.js+++ b/tests/x-mention-poll.test.js@@ -24,6 +24,7 @@ const store = await import('../api/_lib/x-mention-store.js');const { XTierUnavailable, XRateLimited } = await import('../api/_lib/x-mentions.js');const make = await import('../api/_lib/x-mention-make.js');const avatar = await import('../api/_lib/x-mention-avatar.js');+const image3d = await import('../api/_lib/x-mention-image3d.js');const { createDeliver } = await import('../api/_lib/x-mention-deliver.js');const { createXAdapter } = await import('../api/_lib/gateway/adapters/x.js');@@ -41,7 +42,21 @@ const ACCT = { kind: 'company', ref: 'trythreews' };const request = async () => ({ status: 200, headers: {}, body: page });const compose = vi.fn(async () => ({ text: 'Hello from three.ws', source: 'model', reason: null }));-const deps = (extra = {}) => ({ request, resolvedAccount: COMPANY, compose, ...extra });+const PNG = Buffer.concat([Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]), Buffer.alloc(2048, 7)]);+const I3D_BASE = 'https://three.test';+const I3D_CREATION = '7a2e4b63-1d3f-4c8f-8b69-2a1b0b5c8d21';+const I3D_DONE = { status: 'done', glb_url: 'https://cdn.three.test/forge/sneaker.glb', creation_id: I3D_CREATION };+/** The real image3d handler with only its network edges (CDN, vision, image store, 3D lane) replaced. */+const image3dEdges = (extra = {}) => ({+ base: I3D_BASE,+ probeMedia: async () => true,+ fetchImpl: async () => new Response(PNG, { status: 200, headers: { 'content-type': 'image/png' } }),+ describe: async () => ({ json: { safe: true, usable: true, subject: 'red sneaker' } }),+ persist: async () => 'https://cdn.three.test/forge/refs/x.png',+ startForge: async () => I3D_DONE,+ ...extra,+});+const deps = (extra = {}) => ({ request, resolvedAccount: COMPANY, compose, image3d: (e) => image3d.handleImage3d(e, image3dEdges()), ...extra });beforeEach(async () => {dbState.pg = new PGlite();@@ -80,13 +95,32 @@ describe('a poll with a cursor', () => {expect(await store.getCursor(ACCT)).toBe(out.cursor);});- it('routes handlers from later orders to help with handler_not_built', async () => {+ it('routes the make and launch intents (later orders) to help with handler_not_built', async () => {await poll.pollAccount({ descriptor: DESCRIPTOR, env: {}, deps: deps() });const rows = await store.recentDecisions(ACCT, { limit: 50 });- const unbuilt = rows.filter((r) => ['make', 'image3d', 'avatar', 'launch'].includes(r.intent) && r.decision === 'reply');+ const unbuilt = rows.filter((r) => ['make', 'launch'].includes(r.intent) && r.decision === 'reply');for (const r of unbuilt) expect(r.reason).toBe('handler_not_built');});+ it('answers an image3d mention with the image3d handler, not help', async () => {+ const id = '1900000000000000100';+ const mention = {+ id, userId: '42', username: 'alice', text: '@trythreews 3D this', createdAt: new Date().toISOString(), conversationId: id, account: ACCT,+ mentions: [{ username: 'trythreews', id: COMPANY.userId }], urls: [],+ media: [{ key: '3_1', type: 'photo', url: 'https://pbs.twimg.com/media/GxQ1aBcWsAAbCdE.jpg', width: 1200, height: 900 }],+ inReplyToUserId: null, repliedTo: null, quoted: null, isRetweet: false, fromSelf: false,+ };+ const budget = { readGate: async () => ({ allow: true }), budgetGate: async () => ({ allow: true }), recordPosts: vi.fn(async () => {}) };+ const out = await poll.handleMention({+ mention, account: COMPANY, limits: poll.replyLimits({}), env: {}, budget, paused: async () => false,+ guard: async () => ({ allow: true }), image3d: (e) => image3d.handleImage3d(e, image3dEdges()),+ });+ expect(out).toMatchObject({ intent: 'image3d', decision: 'reply', reason: 'image3d_done', dry_run: true });+ expect(out.text).toContain(`/m/${I3D_CREATION}`);+ expect(budget.recordPosts).toHaveBeenCalledWith(1);+ expect(await store.getMentionEvent(id)).toMatchObject({ intent: 'image3d', decision: 'reply', reason: 'image3d_done', dry_run: true, reply_tweet_id: null });+ });+it('handles a mention once when the same page is read twice', async () => {await poll.pollAccount({ descriptor: DESCRIPTOR, env: {}, deps: deps() });const first = (await store.recentDecisions(ACCT, { limit: 50 })).length;@@ -151,7 +185,7 @@ describe('the run lock', () => {describe('late-reply follow-ups', () => {const BASE = 'https://three.test';const DONE = { status: 'done', glb_url: 'https://cdn.three.test/m.glb', creation_id: '11111111-1111-4111-8111-111111111111', preview_image_url: 'https://cdn.three.test/m.png' };- const ids = { make: '1900000000000000001', avatar: '1900000000000000002' };+ const ids = { make: '1900000000000000001', avatar: '1900000000000000002', image3d: '1900000000000000003' };const open = { paused: async () => false, budget: { readGate: async () => ({ allow: true }), recordPosts: vi.fn(async () => {}) } };async function pending(intent, id, dryRun) {@@ -165,6 +199,7 @@ describe('late-reply follow-ups', () => {const finishers = (post) => ({finishPendingMakes: (o, d) => make.finishPendingMakes(o, { ...d, base: BASE, pollOnce: async () => DONE }),finishPendingAvatars: (o, d) => avatar.finishPendingAvatars(o, { ...d, base: BASE, pollOnce: async () => DONE, startRig: async () => { throw Object.assign(new Error('no rig'), { code: 'rig_down' }); } }),+ finishPendingImage3d: (o, d) => image3d.finishPendingImage3d(o, { ...d, base: BASE, pollOnce: async () => DONE, probeMedia: async () => true }),getAccessToken: post ? () => async () => 'tok' : undefined,adapterFactory: post ? (o) => createXAdapter({ ...o, post, fetchMedia: async () => ({ buffer: Buffer.from('x'), mimeType: 'image/png' }), uploadMedia: async () => 'media-1', env: { X_MENTION_BOT_LIVE: '1' } }) : undefined,});@@ -204,6 +239,32 @@ describe('late-reply follow-ups', () => {expect(await store.getMentionEvent(ids.make)).toMatchObject({ dry_run: true, reply_text: 'done', reply_tweet_id: null });});+ it('a pending image3d row is settled late and delivered through the same adapter', async () => {+ await pending('image3d', ids.image3d, false);+ const post = vi.fn(async () => ({ id: '2900000000000000009' }));+ const out = await poll.runFollowUps({ env: { X_MENTION_BOT_LIVE: '1' }, deps: { ...open, ...finishers(post) } });+ expect(out.image3dFollowUp).toMatchObject({ checked: 1, replied: 1 });+ expect(post).toHaveBeenCalledTimes(1);+ expect(await store.getMentionEvent(ids.image3d)).toMatchObject({ intent: 'image3d', decision: 'reply', reason: 'image3d_done_late', dry_run: false, reply_tweet_id: '2900000000000000009' });+ expect(open.budget.recordPosts).toHaveBeenCalledTimes(1);+ });++ it('a dry image3d row is recorded and never posted', async () => {+ await pending('image3d', ids.image3d, true);+ const post = vi.fn();+ const out = await poll.runFollowUps({ env: { X_MENTION_BOT_LIVE: '1' }, deps: { ...open, ...finishers(post) } });+ expect(out.image3dFollowUp).toMatchObject({ replied: 1 });+ expect(post).not.toHaveBeenCalled();+ expect(await store.getMentionEvent(ids.image3d)).toMatchObject({ decision: 'reply', dry_run: true, reply_tweet_id: null });+ });++ it('a failing image3d finisher does not stop makes or avatars', async () => {+ const ok = vi.fn(async () => ({ checked: 0 }));+ const out = await poll.runFollowUps({ env: {}, deps: { ...open, finishPendingMakes: ok, finishPendingAvatars: ok, finishPendingImage3d: async () => { throw new Error('i3d boom'); } } });+ expect(out.image3dFollowUp).toEqual({ error: 'i3d boom' });+ expect(ok).toHaveBeenCalledTimes(2);+ });+it('one failing finisher does not stop the other', async () => {const avatarOnly = vi.fn(async () => ({ checked: 0 }));const out = await poll.runFollowUps({ env: {}, deps: { ...open, finishPendingMakes: async () => { throw new Error('boom'); }, finishPendingAvatars: avatarOnly } });@@ -213,19 +274,21 @@ describe('late-reply follow-ups', () => {it('the kill switch and the budget gate skip both finishers', async () => {const spy = vi.fn(async () => ({}));- const killed = await poll.runFollowUps({ env: {}, deps: { ...open, paused: async () => true, finishPendingMakes: spy, finishPendingAvatars: spy } });+ const killed = await poll.runFollowUps({ env: {}, deps: { ...open, paused: async () => true, finishPendingMakes: spy, finishPendingAvatars: spy, finishPendingImage3d: spy } });expect(killed).toEqual({ followUps: { skipped: 'kill_switch' } });- const broke = await poll.runFollowUps({ env: {}, deps: { ...open, budget: { readGate: async () => ({ allow: false, reason: 'daily_cap' }) }, finishPendingMakes: spy, finishPendingAvatars: spy } });+ const broke = await poll.runFollowUps({ env: {}, deps: { ...open, budget: { readGate: async () => ({ allow: false, reason: 'daily_cap' }) }, finishPendingMakes: spy, finishPendingAvatars: spy, finishPendingImage3d: spy } });expect(broke).toMatchObject({ followUps: { skipped: 'budget', reason: 'daily_cap' } });expect(spy).not.toHaveBeenCalled();});- it('a tick runs both finishers', async () => {+ it('a tick runs all three finishers', async () => {const m = vi.fn(async () => ({ checked: 0 }));const a = vi.fn(async () => ({ checked: 0 }));- const report = await poll.runMentionTick({ env: {}, deps: { acquireLock: async () => 'h', releaseLock: async () => {}, listAccounts: async () => [DESCRIPTOR], request, resolvedAccount: COMPANY, ...open, finishPendingMakes: m, finishPendingAvatars: a } });+ const i = vi.fn(async () => ({ checked: 0 }));+ const report = await poll.runMentionTick({ env: {}, deps: { acquireLock: async () => 'h', releaseLock: async () => {}, listAccounts: async () => [DESCRIPTOR], request, resolvedAccount: COMPANY, ...open, finishPendingMakes: m, finishPendingAvatars: a, finishPendingImage3d: i } });expect(m).toHaveBeenCalledTimes(1);expect(a).toHaveBeenCalledTimes(1);- expect(report).toMatchObject({ makeFollowUp: { checked: 0 }, avatarFollowUp: { checked: 0 } });+ expect(i).toHaveBeenCalledTimes(1);+ expect(report).toMatchObject({ makeFollowUp: { checked: 0 }, avatarFollowUp: { checked: 0 }, image3dFollowUp: { checked: 0 } });});});