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(resilience): record upstream baselines and brownout state, and push commit and changelog feeds through degraded providers

nirholasb452f0423e03
diff --git a/api/_lib/changelog-push.js b/api/_lib/changelog-push.js
index c22d9527d..b4d70db93 100644
--- a/api/_lib/changelog-push.js
+++ b/api/_lib/changelog-push.js
@@ -26,6 +26,7 @@
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import { sql } from './db.js';
+import { provenanceByEntry } from './ship-provenance.js';
import { fetchUpstream } from './upstream-fetch.js';
const CUTOFF_DAYS = 3;
@@ -133,14 +134,29 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
const escapeHtml = (s) =>
String(s).replace(/[<>&]/g, (c) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;' })[c]);
-export function formatTelegramMessage(e) {
+/**
+ * @param {object} e changelog entry
+ * @param {{count: number, compareUrl: string}} [provenance] the commits behind
+ * this entry, from api/_lib/ship-provenance.js. Optional on purpose: an
+ * announcement must still go out when GitHub cannot be read, so the footer
+ * line simply does not appear rather than the message failing to send.
+ */
+export function formatTelegramMessage(e, provenance = null) {
const detailUrl = `https://three.ws/changelog/${slugify(e.title, e.date)}`;
const label = e.type === 'launch' ? 'New on three.ws' : 'Update';
const hashtags = (e.type === 'launch' ? ['launch'] : e.tags).map((t) => `#${t}`).join(' ');
+ const shipped =
+ provenance && provenance.count > 0
+ ? [
+ '',
+ `shipped in <a href="${provenance.compareUrl}">${provenance.count} commit${provenance.count === 1 ? '' : 's'}</a>`,
+ ]
+ : [];
return [
`<b>${escapeHtml(label)} — ${escapeHtml(e.title)}</b>`,
'',
escapeHtml(e.summary),
+ ...shipped,
'',
`<a href="${detailUrl}">${escapeHtml(detailUrl.replace('https://', ''))}</a> · ${escapeHtml(e.date)} · ${escapeHtml(hashtags)}`,
].join('\n');
@@ -180,10 +196,14 @@ export async function pushTelegramLane(feed) {
const { pending, backlog } = pendingEntries(feed, posted, TELEGRAM_LIMIT, { newestWin: true });
if (pending.length === 0) return { posted: 0, backlog };
+ // One GitHub read covers the whole batch, and an unreachable GitHub simply
+ // means no footer: the announcement itself never waits on it.
+ const provenance = await provenanceByEntry(pending).catch(() => new Map());
+
let sent = 0;
try {
for (const e of pending) {
- await sendTelegram(botToken, chatId, formatTelegramMessage(e));
+ await sendTelegram(botToken, chatId, formatTelegramMessage(e, provenance.get(entryKey(e))));
posted.add(entryKey(e));
sent++;
await setState('changelog_push_telegram', { posted: [...posted] });
diff --git a/api/_lib/commit-feed-push.js b/api/_lib/commit-feed-push.js
index 3da5b4420..a71f3551f 100644
--- a/api/_lib/commit-feed-push.js
+++ b/api/_lib/commit-feed-push.js
@@ -35,6 +35,7 @@
import { sql } from './db.js';
import { fetchUpstream } from './upstream-fetch.js';
+import { classify, headline, parseCommit, summaryLine } from '../../packages/shipfeed/src/index.js';
const REPO = 'nirholas/three.ws';
const BASE = 'https://three.ws';
const TELEGRAM_LIMIT = 15; // per run; Bot API allows ~20 msg/min per chat
@@ -51,6 +52,32 @@ const TELEGRAM_PACE_MS = 3500;
const LOCK_KEY = 'commit_feed_push_lock';
const LOCK_TTL_S = 240;
const STATE_KEY = 'commit_feed_push_telegram';
+// Parts of the product a reader has actually seen. Naming them lifts a commit
+// in one of them above the machinery around it when the lane scores what is
+// worth posting; everything unnamed is still scored on its own merits.
+const PRODUCT_SCOPES = [
+ 'agent',
+ 'agents',
+ 'avatar',
+ 'avatars',
+ 'chat',
+ 'companion',
+ 'crews',
+ 'discover',
+ 'embed',
+ 'embeds',
+ 'forge',
+ 'launch',
+ 'marketplace',
+ 'oracle',
+ 'payments',
+ 'pump',
+ 'seeker',
+ 'studio',
+ 'viewer',
+ 'wallet',
+ 'x402',
+];
// Every outbound call is bounded, and deliberately well under LOCK_TTL_S. The
// lock is what stops two ticks posting the same commit twice, but it only holds
// for its TTL: a request that hangs longer than that outlives its own lock, and
@@ -183,56 +210,27 @@ export function newCommitsSince(commits, { lastSha, lastDate } = {}, now = Date.
const escapeHtml = (s) =>
String(s).replace(/[<>&]/g, (c) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;' })[c]);
-// Most commit subjects in this repo follow a loose "scope: description"
-// convention ("agent-sniper: stop LLM judge calls…", "docs: cover ASL
-// fingerspelling…"). Split on the first colon when it looks like that
-// convention so the scope becomes the bold headline and the description the
-// body. Subjects without that convention get a generic "New commit" headline.
-// Only the subject line is ever posted: full commit bodies are hard-wrapped
-// by git and written for engineers, not holders, so they stay on GitHub.
-export function splitSubject(subjectLine) {
- const idx = subjectLine.indexOf(': ');
- if (idx > 0 && idx < 60) {
- return { headline: subjectLine.slice(0, idx), body: subjectLine.slice(idx + 2) };
- }
- return { headline: 'New commit', body: subjectLine };
+// Headline and description come from @three-ws/shipfeed's conventional-commit
+// parser, so `feat(resilience): ...` reads as "Feature · resilience" instead of
+// the raw `feat(resilience)` this lane used to print, and a subject with no
+// convention at all still falls back to the repo's older "Scope: text" habit.
+// Only the subject line is ever posted: full commit bodies are hard-wrapped by
+// git and written for engineers, not holders, so they stay on GitHub.
+export function commitHeadline(commit) {
+ return headline(parseCommit(commit));
}
-// Conventional-commit type prefixes are written for engineers ("feat", "fix",
-// "perf"). Holders following the feed read plain words, so map the known types
-// to friendly labels. Anything not in the map — a real scope like "Avatar
-// Studio" or "/cookbook" — is already readable and passes through untouched.
-const TYPE_LABELS = {
- feat: 'Feature',
- fix: 'Fix',
- perf: 'Performance',
- refactor: 'Refactor',
- docs: 'Docs',
- test: 'Tests',
- tests: 'Tests',
- build: 'Build',
- ci: 'CI',
- chore: 'Chore',
- style: 'Style',
- revert: 'Revert',
-};
-
-export function prettyHeadline(headline) {
- return TYPE_LABELS[String(headline).toLowerCase()] || headline;
+export function commitSummary(commit) {
+ return summaryLine(parseCommit(commit));
}
-// three.ws-branded social-share landing for one commit. Telegram scrapes its
-// OG tags to render the poster card, then redirects a human click to GitHub.
-// The GitHub link still lives in the message text, so both paths work.
export function commitPreviewUrl(commit) {
- const subjectLine = (commit.commit?.message || '').split('\n')[0];
- const { headline, body } = splitSubject(subjectLine);
const author = commit.author?.login || commit.commit?.author?.name || 'unknown';
const date = (commit.commit?.author?.date || '').slice(0, 10);
const params = new URLSearchParams({
sha: commit.sha,
- t: prettyHeadline(headline),
- d: body,
+ t: commitHeadline(commit),
+ d: commitSummary(commit),
date,
author,
});
@@ -241,16 +239,14 @@ export function commitPreviewUrl(commit) {
export function formatTelegramMessage(commit) {
const shortSha = commit.sha.slice(0, 7);
- const subjectLine = (commit.commit?.message || '').split('\n')[0];
- const { headline, body } = splitSubject(subjectLine);
const author = commit.author?.login || commit.commit?.author?.name || 'unknown';
const date = (commit.commit?.author?.date || '').slice(0, 10);
const url = commit.html_url || `https://github.com/${REPO}/commit/${commit.sha}`;
const linkText = `github.com/${REPO}/commit/${shortSha}`;
return [
- `<b>${escapeHtml(prettyHeadline(headline))}</b>`,
+ `<b>${escapeHtml(commitHeadline(commit))}</b>`,
'',
- escapeHtml(body),
+ escapeHtml(commitSummary(commit)),
'',
`<a href="${url}">${escapeHtml(linkText)}</a> · ${escapeHtml(date)} · ${escapeHtml(author)}`,
].join('\n');
@@ -316,9 +312,22 @@ export async function pushTelegramLane() {
}
let sent = 0;
+ let skipped = 0;
let { lastSha, lastDate } = state;
try {
for (const commit of batch) {
+ // A merge commit, a lockfile bump or a `chore(deps):` bump carries no
+ // content a reader can act on: the merged commits already said what
+ // changed, and nobody follows this channel to learn that `ws` moved a
+ // patch version. Skipping them still advances state, so the lane never
+ // re-reads a commit it decided not to post.
+ if (classify(commit, { productScopes: PRODUCT_SCOPES }).noise) {
+ lastSha = commit.sha;
+ lastDate = commitDate(commit);
+ skipped++;
+ await setState(STATE_KEY, { lastSha, lastDate });
+ continue;
+ }
await sendTelegram(botToken, chatId, formatTelegramMessage(commit), commitPreviewUrl(commit));
lastSha = commit.sha;
lastDate = commitDate(commit);
@@ -330,7 +339,7 @@ export async function pushTelegramLane() {
await sleep(TELEGRAM_PACE_MS);
}
} catch (err) {
- return { posted: sent, backlog, error: String(err?.message || err) };
+ return { posted: sent, skipped, backlog, error: String(err?.message || err) };
}
- return { posted: sent, backlog, resynced: Boolean(resynced) };
+ return { posted: sent, skipped, backlog, resynced: Boolean(resynced) };
}
diff --git a/tests/commit-feed-push.test.js b/tests/commit-feed-push.test.js
index bed04a3e4..ddd867ec8 100644
--- a/tests/commit-feed-push.test.js
+++ b/tests/commit-feed-push.test.js
@@ -1,7 +1,7 @@
import { describe, it, expect } from 'vitest';
import {
- splitSubject,
- prettyHeadline,
+ commitHeadline,
+ commitSummary,
commitPreviewUrl,
formatTelegramMessage,
commitDate,
@@ -21,36 +21,42 @@ const commit = (over = {}) => ({
...over,
});
-describe('splitSubject', () => {
- it('splits scope: description on an early colon', () => {
- expect(splitSubject('feat: add a thing')).toEqual({ headline: 'feat', body: 'add a thing' });
- expect(splitSubject('Avatar Studio: 122 sliders')).toEqual({
- headline: 'Avatar Studio',
- body: '122 sliders',
- });
+describe('commitHeadline', () => {
+ it('reads a conventional type as a friendly label', () => {
+ expect(commitHeadline(commit())).toBe('Feature');
});
- it('falls back to New commit when there is no early colon', () => {
- expect(splitSubject('Escape a raw NUL byte in the test')).toEqual({
- headline: 'New commit',
- body: 'Escape a raw NUL byte in the test',
- });
+
+ it('keeps the scope, which the raw type prefix used to swallow', () => {
+ expect(
+ commitHeadline(commit({ commit: { message: 'feat(resilience): add a breaker', author: {} } })),
+ ).toBe('Feature · resilience');
+ });
+
+ it('marks a breaking change', () => {
+ expect(commitHeadline(commit({ commit: { message: 'feat(api)!: drop v1', author: {} } }))).toBe(
+ 'Feature · api (breaking)',
+ );
});
- it('does not split on a late colon', () => {
- const s = 'this is a very long subject line that carries its only colon well past sixty: nope';
- expect(splitSubject(s).headline).toBe('New commit');
+
+ it('falls back to the older "Scope: text" habit', () => {
+ expect(
+ commitHeadline(commit({ commit: { message: 'Avatar Studio: 122 sliders', author: {} } })),
+ ).toBe('Avatar Studio');
});
-});
-describe('prettyHeadline', () => {
- it('maps conventional-commit types to friendly labels', () => {
- expect(prettyHeadline('feat')).toBe('Feature');
- expect(prettyHeadline('fix')).toBe('Fix');
- expect(prettyHeadline('PERF')).toBe('Performance');
+ it('says "New commit" when a subject carries no convention at all', () => {
+ expect(
+ commitHeadline(commit({ commit: { message: 'Escape a raw NUL byte in the test', author: {} } })),
+ ).toBe('New commit');
});
- it('passes real scopes through untouched', () => {
- expect(prettyHeadline('Avatar Studio')).toBe('Avatar Studio');
- expect(prettyHeadline('/cookbook')).toBe('/cookbook');
- expect(prettyHeadline('New commit')).toBe('New commit');
+});
+
+describe('commitSummary', () => {
+ it('drops the type prefix and keeps the description', () => {
+ expect(commitSummary(commit())).toBe('add a thing');
+ expect(
+ commitSummary(commit({ commit: { message: 'Avatar Studio: 122 sliders', author: {} } })),
+ ).toBe('122 sliders');
});
});