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): add reviewed @trythreews announcement queue with quality checks and dry-run publishing
nirholasfdbaaf3cdb90
diff --git a/.env.example b/.env.exampleindex 2517e7999..7697bb26c 100644--- a/.env.example+++ b/.env.example@@ -1490,6 +1490,12 @@ X_API_SECRET=X_ACCESS_TOKEN=X_ACCESS_SECRET=+# Autonomous @trythreews announcement queue. Keep the switch false until the+# review queue, X media upload, and R2 state have passed a production dry run.+X_ANNOUNCEMENT_AUTO_PUBLISH=false+X_ANNOUNCEMENT_STATE_BUCKET=+X_ANNOUNCEMENT_STATE_KEY=state/x-announcements.json+# Telegram bot — used by /api/pump/deliver-telegram to push pump.fun signals# to subscriber chats. Without it the endpoint 500s.# Create a bot via https://t.me/BotFather → /newbot.diff --git a/.github/workflows/x-announcements.yml b/.github/workflows/x-announcements.ymlnew file mode 100644index 000000000..795e8079a--- /dev/null+++ b/.github/workflows/x-announcements.yml@@ -0,0 +1,65 @@+name: X announcements++on:+ workflow_dispatch:+ inputs:+ dry_run:+ description: Preview the next approved item without posting+ required: true+ default: true+ type: boolean+ schedule:+ - cron: '7 14 * * *'+ - cron: '13 19 * * *'+ - cron: '19 0 * * *'++concurrency:+ group: x-announcements-trythreews+ cancel-in-progress: false++permissions:+ contents: read++jobs:+ validate:+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v4+ - uses: actions/setup-node@v4+ with:+ node-version-file: .nvmrc+ cache: npm+ - run: npm ci --ignore-scripts+ - run: npm run x:announce:check++ publish:+ needs: validate+ if: >-+ (github.event_name == 'workflow_dispatch' && inputs.dry_run) ||+ (github.event_name == 'schedule' && vars.X_ANNOUNCEMENT_AUTO_PUBLISH == 'true') ||+ (github.event_name == 'workflow_dispatch' && !inputs.dry_run && vars.X_ANNOUNCEMENT_AUTO_PUBLISH == 'true')+ runs-on: ubuntu-latest+ environment: x-production+ steps:+ - uses: actions/checkout@v4+ - uses: actions/setup-node@v4+ with:+ node-version-file: .nvmrc+ cache: npm+ - run: npm ci --ignore-scripts+ - name: Preview next approved announcement+ if: github.event_name == 'workflow_dispatch' && inputs.dry_run+ run: npm run x:announce:run -- --dry-run+ - name: Publish one due announcement+ if: github.event_name == 'schedule' || (github.event_name == 'workflow_dispatch' && !inputs.dry_run)+ run: npm run x:announce:run+ env:+ X_API_KEY: ${{ secrets.X_API_KEY }}+ X_API_SECRET: ${{ secrets.X_API_SECRET }}+ X_ACCESS_TOKEN: ${{ secrets.X_ACCESS_TOKEN }}+ X_ACCESS_SECRET: ${{ secrets.X_ACCESS_SECRET }}+ R2_ACCOUNT_ID: ${{ secrets.R2_ACCOUNT_ID }}+ R2_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}+ R2_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }}+ X_ANNOUNCEMENT_STATE_BUCKET: ${{ secrets.X_ANNOUNCEMENT_STATE_BUCKET }}+ X_ANNOUNCEMENT_STATE_KEY: state/x-announcements.jsondiff --git a/.gitignore b/.gitignoreindex 424d0b9c8..1063dd281 100644--- a/.gitignore+++ b/.gitignore@@ -644,3 +644,5 @@ docs/ops/npm-publish-status.md# Packaged VS Code extensions belong on GitHub Releases, not in Git history.*.vsixHSO6cvibUAATRw9.jpg+# Local X announcement publish ledger (production uses R2).+.x-announcement-state.jsondiff --git a/data/x-announcement-pipeline.json b/data/x-announcement-pipeline.jsonnew file mode 100644index 000000000..0b9b76a67--- /dev/null+++ b/data/x-announcement-pipeline.json@@ -0,0 +1,63 @@+{+ "version": 1,+ "account": "trythreews",+ "mode": "approval",+ "cadence": {+ "timezone": "UTC",+ "slots": ["14:07", "19:13", "00:19"],+ "minimumMinutesApart": 240+ },+ "quality": {+ "archiveSimilarityLimit": 0.42,+ "queueSimilarityLimit": 0.34,+ "maximumSameLaneInARow": 2,+ "maximumSamePatternInARow": 1+ },+ "items": [+ {+ "id": "genesis",+ "status": "review",+ "notBefore": "2026-09-17T14:07:00Z",+ "lane": "community",+ "pattern": "mechanism",+ "source": "docs/announcements/genesis.md",+ "parts": ["docs/announcements/genesis.post.txt"],+ "media": [+ {+ "path": "public/announce/img/genesis-hero.webp",+ "alt": "The three.ws Genesis page signed in: describe an agent, upload a selfie, or remix a public avatar, and it becomes a rigged 3D agent with its own wallet and on-chain identity"+ }+ ]+ },+ {+ "id": "rig-doctor",+ "status": "review",+ "notBefore": "2026-09-17T19:13:00Z",+ "lane": "developer",+ "pattern": "correction",+ "source": "docs/announcements/open-source-friday.md",+ "parts": ["docs/announcements/open-source-friday.post.txt"],+ "media": [+ {+ "path": "public/announce/img/rig-doctor-hero.webp",+ "alt": "three.ws Rig Doctor: drop in any humanoid GLB and it names the skeleton convention, then lists joint by joint which bones will animate and which will not move"+ }+ ]+ },+ {+ "id": "aws-authorization-spine",+ "status": "review",+ "notBefore": "2026-09-18T00:19:00Z",+ "lane": "article",+ "pattern": "number",+ "source": "docs/announcements/aws-builder-center-authorization-spine.md",+ "parts": ["docs/announcements/aws-builder-center-authorization-spine.post.txt"],+ "media": [+ {+ "path": "public/announce/img/aws-builder-center-authorization-spine.webp",+ "alt": "The article live on the AWS Builder Center under the three.ws byline, headlined Budgets, entitlements, and the $THREE token layer: how we authorize autonomous agent spending, published 11 September 2026"+ }+ ]+ }+ ]+}diff --git a/package.json b/package.jsonindex c3095dca8..a92504460 100644--- a/package.json+++ b/package.json@@ -196,6 +196,9 @@"announce:rank": "node scripts/announce-rank.mjs","announce:media": "node scripts/capture-doc-media.mjs --spec data/announce-media.json --out public/announce/img --manifest public/announce/media-manifest.json","check:announce": "node scripts/check-announce.mjs",+ "x:announce:check": "node scripts/x-announcement-pipeline.mjs check",+ "x:announce:plan": "node scripts/x-announcement-pipeline.mjs plan",+ "x:announce:run": "node scripts/x-announcement-pipeline.mjs run","changelog:push": "node scripts/changelog-telegram.mjs","changelog:push:x": "node scripts/changelog-x.mjs","tweet": "node scripts/post-tweet.mjs",diff --git a/scripts/lib/x-announcement-quality.mjs b/scripts/lib/x-announcement-quality.mjsnew file mode 100644index 000000000..5768b38f8--- /dev/null+++ b/scripts/lib/x-announcement-quality.mjs@@ -0,0 +1,80 @@+const URL_RE = /(?:https?:\/\/|\b(?:www\.)?three\.ws\/)[^\s]+/gi;++export const weightedLength = (value) =>+ [...String(value || '').replace(URL_RE, 'x'.repeat(23))].reduce(+ (total, char) => total + (char.codePointAt(0) > 0xffff ? 2 : 1),+ 0,+ );++export function normalizeCopy(value) {+ return String(value || '')+ .toLowerCase()+ .replace(URL_RE, ' url ')+ .replace(/\$([a-z0-9]+)/g, '$1')+ .replace(/[^a-z0-9@]+/g, ' ')+ .trim();+}++export function tokenNgrams(value, size = 3) {+ const tokens = normalizeCopy(value).split(/\s+/).filter(Boolean);+ if (tokens.length < size) return new Set(tokens.length ? [tokens.join(' ')] : []);+ const grams = new Set();+ for (let index = 0; index <= tokens.length - size; index++) {+ grams.add(tokens.slice(index, index + size).join(' '));+ }+ return grams;+}++export function jaccard(left, right) {+ if (!left.size && !right.size) return 1;+ let intersection = 0;+ for (const item of left) if (right.has(item)) intersection++;+ return intersection / (left.size + right.size - intersection);+}++export function copySimilarity(left, right) {+ return jaccard(tokenNgrams(left), tokenNgrams(right));+}++export const BANNED_OPENINGS = [+ /^introducing\b/i,+ /^we(?:'re| are) (?:excited|thrilled|proud|happy)/i,+ /^say hello to\b/i,+ /^meet the new\b/i,+ /^big news\b/i,+ /^today we(?:'re| are) launching\b/i,+ /^ever wondered\b/i,+ /^what if you could\b/i,+ /^imagine a world\b/i,+];++export const BANNED_PHRASES = [+ /\bgame[- ]chang(?:er|ing)\b/i,+ /\brevolutionary\b/i,+ /\bseamless(?:ly)?\b/i,+ /\bunlock the power\b/i,+ /\bnext level\b/i,+ /\bthe future of \w+ is here\b/i,+ /\band the best part\b/i,+ /\blet that sink in\b/i,+ /\bhere'?s the kicker\b/i,+ /\bsupercharge\b/i,+];++export function copyProblems(text, { minimum = 100, maximum = 280 } = {}) {+ const problems = [];+ const copy = String(text || '').trim();+ const weight = weightedLength(copy);+ if (!copy) problems.push('copy is empty');+ if (weight < minimum) problems.push(`copy is ${weight} weighted characters; minimum is ${minimum}`);+ if (weight > maximum) problems.push(`copy is ${weight} weighted characters; maximum is ${maximum}`);+ if (/#\w/.test(copy)) problems.push('hashtags are outside the @trythreews voice');+ if (/[\u{1F300}-\u{1FAFF}\u{2600}-\u{27BF}]/u.test(copy)) problems.push('emoji are outside the @trythreews voice');+ if (/[\u2013\u2014]/.test(copy)) problems.push('en-dashes and em-dashes are banned');+ if (!URL_RE.test(copy)) problems.push('copy must link to its evidence or product surface');+ URL_RE.lastIndex = 0;+ for (const pattern of BANNED_OPENINGS) if (pattern.test(copy)) problems.push(`banned opening: ${pattern.source}`);+ for (const pattern of BANNED_PHRASES) if (pattern.test(copy)) problems.push(`banned phrase: ${pattern.source}`);+ return problems;+}+diff --git a/scripts/x-announcement-pipeline.mjs b/scripts/x-announcement-pipeline.mjsnew file mode 100644index 000000000..82dc3a8f6--- /dev/null+++ b/scripts/x-announcement-pipeline.mjs@@ -0,0 +1,240 @@+#!/usr/bin/env node++import { GetObjectCommand, PutObjectCommand, S3Client } from '@aws-sdk/client-s3';+import { existsSync, readFileSync, writeFileSync } from 'node:fs';+import { extname, resolve } from 'node:path';+import { spawnSync } from 'node:child_process';+import { fileURLToPath } from 'node:url';+import { copyProblems, copySimilarity, weightedLength } from './lib/x-announcement-quality.mjs';++const root = resolve(fileURLToPath(new URL('..', import.meta.url)));+const args = process.argv.slice(2);+const command = args.find((arg) => !arg.startsWith('--')) || 'check';+const has = (flag) => args.includes(`--${flag}`);+const value = (name, fallback = null) => {+ const inline = args.find((arg) => arg.startsWith(`--${name}=`));+ if (inline) return inline.slice(name.length + 3);+ const index = args.indexOf(`--${name}`);+ return index >= 0 && args[index + 1] && !args[index + 1].startsWith('--') ? args[index + 1] : fallback;+};++const configPath = resolve(root, value('config', 'data/x-announcement-pipeline.json'));+const localStatePath = resolve(root, value('state', '.x-announcement-state.json'));+const config = JSON.parse(readFileSync(configPath, 'utf8'));++function textAt(path) {+ return readFileSync(resolve(root, path), 'utf8').trim();+}++function loadArchivePosts() {+ const paths = [+ 'data/archives/trythreews_tweets_2026-06-03.json',+ 'data/archives/trythreews_tweets_2026-05-16.json',+ ];+ const posts = [];+ for (const path of paths) {+ if (!existsSync(resolve(root, path))) continue;+ const payload = JSON.parse(readFileSync(resolve(root, path), 'utf8'));+ const rows = Array.isArray(payload) ? payload : payload.tweets || payload.data || [];+ for (const row of rows) {+ const text = row.text || row.full_text || row.tweet?.full_text || row.tweet?.text;+ if (text) posts.push(String(text));+ }+ }+ return posts;+}++function validate() {+ const errors = [];+ const notes = [];+ const heads = [];+ const ids = new Set();+ const allowedStatuses = new Set(['draft', 'review', 'approved', 'paused', 'posted']);++ for (const item of config.items || []) {+ const prefix = item.id || '<missing id>';+ if (!item.id || ids.has(item.id)) errors.push(`${prefix}: id is missing or duplicated`);+ ids.add(item.id);+ if (!allowedStatuses.has(item.status)) errors.push(`${prefix}: invalid status ${item.status}`);+ if (!item.lane || !item.pattern) errors.push(`${prefix}: lane and pattern are required`);+ if (!item.notBefore || !Number.isFinite(Date.parse(item.notBefore))) errors.push(`${prefix}: notBefore must be ISO-8601`);+ if (!Array.isArray(item.parts) || !item.parts.length) errors.push(`${prefix}: at least one post part is required`);+ if (!Array.isArray(item.media) || !item.media.length) errors.push(`${prefix}: every announcement requires media`);+ if ((item.media || []).length > 4) errors.push(`${prefix}: X accepts at most four images`);++ const mediaKinds = new Set();+ for (const media of item.media || []) {+ const path = resolve(root, media.path || '');+ if (!media.path || !existsSync(path)) errors.push(`${prefix}: missing media ${media.path || '<path>'}`);+ const extension = extname(media.path || '').toLowerCase();+ const kind = ['.mp4', '.mov'].includes(extension) ? 'video' : extension === '.gif' ? 'gif' : 'image';+ mediaKinds.add(kind);+ if (kind === 'image' && !String(media.alt || '').trim()) errors.push(`${prefix}: image ${media.path} needs alt text`);+ }+ if (mediaKinds.has('video') && (item.media.length !== 1 || mediaKinds.size !== 1)) errors.push(`${prefix}: video must be the only attachment`);+ if (mediaKinds.has('gif') && (item.media.length !== 1 || mediaKinds.size !== 1)) errors.push(`${prefix}: GIF must be the only attachment`);++ const parts = [];+ for (const partPath of item.parts || []) {+ if (!existsSync(resolve(root, partPath))) {+ errors.push(`${prefix}: missing post part ${partPath}`);+ continue;+ }+ parts.push(textAt(partPath));+ }+ for (let index = 0; index < parts.length; index++) {+ for (const problem of copyProblems(parts[index], { minimum: index === 0 ? 100 : 1 })) {+ errors.push(`${prefix} part ${index + 1}: ${problem}`);+ }+ }+ if (parts[0]) heads.push({ id: prefix, text: parts[0] });+ }++ const queueLimit = Number(config.quality?.queueSimilarityLimit ?? 0.34);+ for (let left = 0; left < heads.length; left++) {+ for (let right = left + 1; right < heads.length; right++) {+ const score = copySimilarity(heads[left].text, heads[right].text);+ if (score >= queueLimit) errors.push(`${heads[left].id} and ${heads[right].id}: queue similarity ${score.toFixed(2)} exceeds ${queueLimit}`);+ }+ }++ const archive = loadArchivePosts();+ const archiveLimit = Number(config.quality?.archiveSimilarityLimit ?? 0.42);+ for (const head of heads) {+ let closest = { score: 0, text: '' };+ for (const prior of archive) {+ const score = copySimilarity(head.text, prior);+ if (score > closest.score) closest = { score, text: prior };+ }+ if (closest.score >= archiveLimit) errors.push(`${head.id}: archive similarity ${closest.score.toFixed(2)} exceeds ${archiveLimit}`);+ else notes.push(`${head.id}: ${weightedLength(head.text)} chars, closest archive similarity ${closest.score.toFixed(2)}`);+ }++ return { errors, notes };+}++function printValidation(result) {+ for (const note of result.notes) console.log(`note ${note}`);+ if (result.errors.length) {+ for (const error of result.errors) console.error(`error ${error}`);+ return false;+ }+ console.log(`x-announcement-pipeline: ${config.items.length} item(s) passed`);+ return true;+}++function r2Settings() {+ const accountId = process.env.R2_ACCOUNT_ID;+ const accessKeyId = process.env.R2_ACCESS_KEY_ID;+ const secretAccessKey = process.env.R2_SECRET_ACCESS_KEY;+ const bucket = process.env.X_ANNOUNCEMENT_STATE_BUCKET;+ if (!(accountId && accessKeyId && secretAccessKey && bucket)) return null;+ return {+ bucket,+ key: process.env.X_ANNOUNCEMENT_STATE_KEY || 'state/x-announcements.json',+ client: new S3Client({+ region: 'auto',+ endpoint: `https://${accountId}.r2.cloudflarestorage.com`,+ credentials: { accessKeyId, secretAccessKey },+ }),+ };+}++async function bodyText(body) {+ if (!body) return '';+ if (typeof body.transformToString === 'function') return body.transformToString();+ const chunks = [];+ for await (const chunk of body) chunks.push(chunk);+ return Buffer.concat(chunks).toString('utf8');+}++async function loadState() {+ const remote = r2Settings();+ if (remote) {+ try {+ const object = await remote.client.send(new GetObjectCommand({ Bucket: remote.bucket, Key: remote.key }));+ return JSON.parse(await bodyText(object.Body));+ } catch (error) {+ if (error?.name !== 'NoSuchKey' && error?.$metadata?.httpStatusCode !== 404) throw error;+ return { version: 1, published: [] };+ }+ }+ if (!existsSync(localStatePath)) return { version: 1, published: [] };+ return JSON.parse(readFileSync(localStatePath, 'utf8'));+}++async function saveState(state) {+ const serialized = `${JSON.stringify(state, null, '\t')}\n`;+ const remote = r2Settings();+ if (remote) {+ await remote.client.send(new PutObjectCommand({+ Bucket: remote.bucket,+ Key: remote.key,+ Body: serialized,+ ContentType: 'application/json',+ }));+ return;+ }+ writeFileSync(localStatePath, serialized);+}++function publisherArgs(item, dryRun) {+ const publishArgs = ['scripts/post-tweet.mjs'];+ if (item.parts.length === 1) publishArgs.push('--file', item.parts[0]);+ else publishArgs.push('--thread', JSON.stringify(item.parts));+ for (const media of item.media) {+ publishArgs.push('--media', media.path);+ if (media.alt) publishArgs.push('--alt', media.alt);+ }+ if (dryRun) publishArgs.push('--dry-run');+ return publishArgs;+}++function showPlan() {+ for (const item of [...config.items].sort((a, b) => a.notBefore.localeCompare(b.notBefore))) {+ console.log(`${item.notBefore} ${item.status.padEnd(8)} ${item.lane.padEnd(10)} ${item.pattern.padEnd(10)} ${item.id}`);+ }+}++async function run() {+ const check = validate();+ if (!printValidation(check)) process.exit(1);+ const state = await loadState();+ const published = new Set((state.published || []).map((row) => row.id));+ const requested = value('id');+ const now = Date.parse(value('now', new Date().toISOString()));+ const item = [...config.items]+ .filter((row) => row.status === 'approved')+ .filter((row) => !published.has(row.id))+ .filter((row) => !requested || row.id === requested)+ .filter((row) => requested || Date.parse(row.notBefore) <= now)+ .sort((a, b) => a.notBefore.localeCompare(b.notBefore))[0];+ if (!item) {+ console.log(requested ? `No approved unpublished item named ${requested}.` : 'No approved announcement is due.');+ return;+ }++ const dryRun = has('dry-run');+ console.log(`${dryRun ? 'Previewing' : 'Publishing'} ${item.id} (${item.lane}/${item.pattern})`);+ const result = spawnSync(process.execPath, publisherArgs(item, dryRun), { cwd: root, encoding: 'utf8', stdio: 'inherit' });+ if (result.status !== 0) process.exit(result.status || 1);+ if (dryRun) return;+ state.published = [+ ...(state.published || []),+ { id: item.id, publishedAt: new Date().toISOString(), lane: item.lane, pattern: item.pattern },+ ];+ await saveState(state);+ console.log(`Recorded ${item.id} in ${r2Settings() ? 'R2' : localStatePath}`);+}++if (command === 'check') {+ if (!printValidation(validate())) process.exit(1);+} else if (command === 'plan') {+ showPlan();+} else if (command === 'run') {+ await run();+} else {+ console.error('Usage: node scripts/x-announcement-pipeline.mjs <check|plan|run> [--dry-run] [--id slug]');+ process.exit(1);+}+