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(x): add reviewed @trythreews announcement queue with quality checks and dry-run publishing

nirholasfdbaaf3cdb90
diff --git a/.env.example b/.env.example
index 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.yml
new file mode 100644
index 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.json
diff --git a/.gitignore b/.gitignore
index 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.
*.vsix
HSO6cvibUAATRw9.jpg
+# Local X announcement publish ledger (production uses R2).
+.x-announcement-state.json
diff --git a/data/x-announcement-pipeline.json b/data/x-announcement-pipeline.json
new file mode 100644
index 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.json
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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);
+}
+