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(shipfeed): publish a ship feed with provenance, its package, API, MCP server and public surface

nirholas8f062ba9ed45
diff --git a/api/_lib/ship-provenance.js b/api/_lib/ship-provenance.js
new file mode 100644
index 000000000..6faa5e986
--- /dev/null
+++ b/api/_lib/ship-provenance.js
@@ -0,0 +1,99 @@
+// @ts-check
+// Provenance for a changelog entry: which commits actually produced it.
+//
+// The holder channel carries two feeds that describe the same work and have
+// never known about each other (api/_lib/changelog-push.js posts the sentence,
+// api/_lib/commit-feed-push.js posts the code). This module is the join: it
+// reads recent commits once per process window and hands each release note the
+// count and sha range of the work behind it, so the announcement can point at
+// the diff instead of leaving a reader to guess which of that afternoon's
+// thirty commits it meant.
+//
+// Every part of it is best-effort by design. A release announcement must go out
+// even when GitHub is rate-limited, so every failure here resolves to null and
+// the caller posts the message it would have posted anyway.
+
+import { linkCommits, entryKey, fetchGitHubCommits } from '../../packages/shipfeed/src/index.js';
+import { fetchUpstream } from './upstream-fetch.js';
+
+const REPO = 'nirholas/three.ws';
+const COMMIT_LIMIT = 300;
+const CACHE_TTL_MS = 5 * 60_000;
+
+/** Process-local cache: one GitHub read serves every entry in a cron tick. */
+let cache = { at: 0, commits: null };
+
+const boundedFetch = (url, init) =>
+ fetchUpstream(url, init, {
+ name: 'github-commits',
+ timeoutMs: 12_000,
+ attempts: 2,
+ okWhen: () => true,
+ });
+
+/**
+ * Recent commits on main, or null when GitHub cannot be read right now.
+ * @param {{now?: number}} [options]
+ */
+export async function recentCommits(options = {}) {
+ const now = options.now ?? Date.now();
+ if (cache.commits && now - cache.at < CACHE_TTL_MS) return cache.commits;
+ try {
+ const commits = await fetchGitHubCommits({
+ repo: REPO,
+ branch: 'main',
+ limit: COMMIT_LIMIT,
+ token: process.env.GITHUB_TOKEN || process.env.GH_TOKEN || '',
+ fetchImpl: boundedFetch,
+ userAgent: 'three.ws-shipfeed',
+ });
+ cache = { at: now, commits };
+ return commits;
+ } catch (err) {
+ console.warn(`[ship-provenance] commit read failed: ${err?.message || err}`);
+ return null;
+ }
+}
+
+/**
+ * Map each entry key to the work behind it.
+ *
+ * @param {{date: string, title: string, summary?: string, tags?: string[], link?: string}[]} entries
+ * @param {{commits?: object[]|null}} [options] injected commits (tests, callers that already read them)
+ * @returns {Promise<Map<string, {count: number, range: string, compareUrl: string}>>}
+ * empty when commits are unavailable, so callers need no special case
+ */
+export async function provenanceByEntry(entries, options = {}) {
+ const out = new Map();
+ if (!Array.isArray(entries) || entries.length === 0) return out;
+
+ // `commits` present but null means "the caller already tried and failed";
+ // absent means "read them yourself". Coalescing the two would send a test,
+ // or a caller handling its own outage, back out to the network.
+ const commits = 'commits' in options ? options.commits : await recentCommits();
+ if (!commits || commits.length === 0) return out;
+
+ const { byEntry } = linkCommits(entries, commits);
+ for (const entry of entries) {
+ const bucket = byEntry.get(entryKey(entry));
+ if (!bucket || bucket.commits.length === 0) continue;
+ const first = bucket.commits[0];
+ const last = bucket.commits[bucket.commits.length - 1];
+ const range = `${first.shortSha}..${last.shortSha}`;
+ out.set(entryKey(entry), {
+ count: bucket.commits.length,
+ range,
+ // A one-commit range has nothing to compare against, so link the commit.
+ compareUrl:
+ bucket.commits.length === 1
+ ? `https://github.com/${REPO}/commit/${first.sha}`
+ : `https://github.com/${REPO}/compare/${first.sha}...${last.sha}`,
+ });
+ }
+ return out;
+}
+
+/** Reset the process cache. Tests use this; production never needs it. */
+export function resetProvenanceCache() {
+ cache = { at: 0, commits: null };
+}
diff --git a/packages/herald-mcp/LICENSE b/packages/herald-mcp/LICENSE
new file mode 100644
index 000000000..dff21b7f4
--- /dev/null
+++ b/packages/herald-mcp/LICENSE
@@ -0,0 +1,20 @@
+Copyright 2026 nirholas
+
+All rights reserved.
+
+This software is proprietary and may not be used, copied, modified, distributed,
+translated, or made available to any third party without the express written
+permission of the copyright owner.
+
+No rights are granted by implication, estoppel, or otherwise. Use of this
+software is subject to the terms of a separate license agreement with the
+copyright owner.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+IN NO EVENT SHALL THE COPYRIGHT OWNER BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE,
+ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
diff --git a/packages/herald-mcp/README.md b/packages/herald-mcp/README.md
new file mode 100644
index 000000000..191e50236
--- /dev/null
+++ b/packages/herald-mcp/README.md
@@ -0,0 +1,116 @@
+# @three-ws/herald-mcp
+
+**Let your agent tell you something in person.**
+
+An MCP server with one idea behind it: when an agent finishes something that
+mattered, or gets stuck, it should not add a line to a log you will never scroll
+back to. It should walk up to you and say so.
+
+Wire this in, and it does. Your own 3D companion appears in the corner of
+whatever browser tab you have open, gestures, and says the line out loud, with a
+link to click through.
+
+```
+you: run the migration, then the backfill, and tell me when it's done
+agent: [runs for 22 minutes]
+ [calls announce_result: task "the backfill", outcome succeeded, 1320s]
+your browser: your avatar walks on: "the backfill finished in 22m"
+```
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `announce` | Say one line, with importance (0-100), tone, a gesture, and an optional link. |
+| `announce_result` | Report a finished task. The urgency is chosen from the outcome, so a failure cuts through quiet hours and a success does not. |
+| `check_rail` | Prove the key and the rail work, without interrupting anybody (queues at importance 0, which every client drops). |
+
+## Install
+
+```sh
+npx -y @three-ws/herald-mcp
+```
+
+Claude Code:
+
+```sh
+claude mcp add herald -e THREE_WS_API_KEY=sk_live_... -- npx -y @three-ws/herald-mcp
+```
+
+Claude Desktop / Cursor (`mcp.json`):
+
+```json
+{
+ "mcpServers": {
+ "herald": {
+ "command": "npx",
+ "args": ["-y", "@three-ws/herald-mcp"],
+ "env": { "THREE_WS_API_KEY": "sk_live_..." }
+ }
+ }
+}
+```
+
+## The key
+
+Create one at [three.ws/dashboard/developers](https://three.ws/dashboard/developers)
+with the **`herald:announce`** scope, and put it in `THREE_WS_API_KEY`.
+
+An announcement is always delivered to **the key owner's own** live sessions.
+There is no recipient parameter: this server cannot be pointed at anybody else,
+so the worst a leaked key can do is annoy the person who leaked it. Revoke it in
+the same place.
+
+| Variable | Required | Default | Notes |
+| --- | --- | --- | --- |
+| `THREE_WS_API_KEY` | yes | | API key with `herald:announce`, or an OAuth access token. Aliases: `THREE_WS_TOKEN`, `THREE_WS_BEARER`. |
+| `THREE_WS_BASE` | no | `https://three.ws` | Override for self-hosting or a preview deployment. |
+| `THREE_WS_TIMEOUT_MS` | no | `20000` | Per-request timeout. |
+
+## When to use it (and when not to)
+
+Announcements are scarce on purpose. The receiving client applies an importance
+floor, a rate limit, dedupe, quiet hours, and a freshness window, so anything
+that does not clear the bar is dropped rather than queued. That is the feature:
+an interruption only works while it is rare.
+
+Good: a long job finished, a job failed, a decision is needed, something broke,
+money moved.
+
+Bad: progress updates, "starting step 3 of 7", anything the person can read
+later. Those belong in the notification inbox
+([@three-ws/notifications-mcp](https://www.npmjs.com/package/@three-ws/notifications-mcp)).
+
+If nothing is open to hear it, the line expires in about five minutes. The rail
+is a live channel, not an archive.
+
+## Example calls
+
+```jsonc
+// something broke, and it should wake somebody up
+{ "name": "announce", "arguments": {
+ "text": "The payments worker has been failing for 10 minutes",
+ "from": "watchdog", "importance": 95, "tone": "error",
+ "url": "https://three.ws/dashboard", "key": "payments-worker-down" } }
+
+// a long task finished, and it should not
+{ "name": "announce_result", "arguments": {
+ "task": "the nightly backfill", "outcome": "succeeded", "seconds": 1320 } }
+
+// wiring check
+{ "name": "check_rail", "arguments": { "note": "claude-code" } }
+```
+
+## How it reaches a browser
+
+`POST /api/herald/announce` queues the line on the account's rail; the page
+listens over SSE and hands it to [@three-ws/herald](https://www.npmjs.com/package/@three-ws/herald),
+which decides whether it clears the person's own rules and then delivers it
+through the 3D companion (or an accessible card when there is no GPU).
+
+Try the whole loop, including the rules engine, at
+[three.ws/herald](https://three.ws/herald).
+
+## License
+
+Apache-2.0.
diff --git a/packages/herald-mcp/package.json b/packages/herald-mcp/package.json
new file mode 100644
index 000000000..b47f97725
--- /dev/null
+++ b/packages/herald-mcp/package.json
@@ -0,0 +1,56 @@
+{
+ "name": "@three-ws/herald-mcp",
+ "version": "0.1.0",
+ "mcpName": "io.github.nirholas/herald-mcp",
+ "description": "Let an AI agent tell its human something in person: a 3D character walks onto the browser tab they have open and says it out loud. Announce a line, report a finished task with the right urgency, or check the rail. Account-scoped over the live three.ws API via a Bearer API key.",
+ "type": "module",
+ "author": "nirholas <[email protected]>",
+ "license": "Apache-2.0",
+ "homepage": "https://three.ws/herald",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/nirholas/three.ws.git",
+ "directory": "packages/herald-mcp"
+ },
+ "bugs": {
+ "url": "https://github.com/nirholas/three.ws/issues"
+ },
+ "keywords": [
+ "mcp",
+ "three.ws",
+ "herald",
+ "notifications",
+ "avatar",
+ "agent",
+ "tts",
+ "alerts"
+ ],
+ "publishConfig": {
+ "access": "public"
+ },
+ "files": [
+ "src",
+ "server.json",
+ "README.md",
+ "LICENSE"
+ ],
+ "bin": {
+ "herald-mcp": "src/index.js"
+ },
+ "main": "./src/index.js",
+ "exports": {
+ ".": "./src/index.js"
+ },
+ "engines": {
+ "node": ">=20"
+ },
+ "scripts": {
+ "start": "node src/index.js",
+ "test": "node --test \"test/**/*.test.mjs\"",
+ "inspect": "npx -y @modelcontextprotocol/inspector node src/index.js"
+ },
+ "dependencies": {
+ "@modelcontextprotocol/sdk": "^1.29.0",
+ "zod": "^3.23.8"
+ }
+}
diff --git a/packages/herald-mcp/server.json b/packages/herald-mcp/server.json
new file mode 100644
index 000000000..6c21c6e25
--- /dev/null
+++ b/packages/herald-mcp/server.json
@@ -0,0 +1,56 @@
+{
+ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+ "name": "io.github.nirholas/herald-mcp",
+ "title": "three.ws Herald",
+ "description": "Tell your human something in person: a 3D character walks onto the browser tab they have open and says it.",
+ "websiteUrl": "https://three.ws/herald",
+ "icons": [
+ {
+ "src": "https://three.ws/three-ws-mcp-icon.svg",
+ "mimeType": "image/svg+xml",
+ "sizes": [
+ "any"
+ ]
+ }
+ ],
+ "repository": {
+ "url": "https://github.com/nirholas/three.ws",
+ "source": "github",
+ "subfolder": "packages/herald-mcp"
+ },
+ "version": "0.1.0",
+ "packages": [
+ {
+ "registryType": "npm",
+ "identifier": "@three-ws/herald-mcp",
+ "version": "0.1.0",
+ "runtimeHint": "npx",
+ "transport": {
+ "type": "stdio"
+ },
+ "environmentVariables": [
+ {
+ "name": "THREE_WS_API_KEY",
+ "description": "A three.ws API key (sk_live_… / sk_test_…) with the herald:announce scope, or an OAuth access token for the same account, carried as Authorization: Bearer. Required: an announcement is always delivered to the key owner's own sessions. Aliases: THREE_WS_TOKEN, THREE_WS_BEARER. Treat like a password.",
+ "format": "string",
+ "isRequired": true,
+ "isSecret": true
+ },
+ {
+ "name": "THREE_WS_BASE",
+ "description": "Base URL of the three.ws API. Override only when self-hosting or targeting a preview deployment.",
+ "format": "string",
+ "isRequired": false,
+ "default": "https://three.ws"
+ },
+ {
+ "name": "THREE_WS_TIMEOUT_MS",
+ "description": "Per-request timeout in milliseconds for the announce call.",
+ "format": "number",
+ "isRequired": false,
+ "default": "20000"
+ }
+ ]
+ }
+ ]
+}
diff --git a/packages/herald-mcp/smithery.yaml b/packages/herald-mcp/smithery.yaml
new file mode 100644
index 000000000..c067345d5
--- /dev/null
+++ b/packages/herald-mcp/smithery.yaml
@@ -0,0 +1,10 @@
+# Smithery deployment config for @three-ws/herald-mcp
+# https://smithery.ai/docs/config#smitheryyaml
+startCommand:
+ type: stdio
+ configSchema:
+ type: object
+ properties: {}
+ required: []
+ commandFunction: |
+ (config) => ({ command: "npx", args: ["-y", "@three-ws/herald-mcp"], env: {} })
diff --git a/packages/herald-mcp/src/config.js b/packages/herald-mcp/src/config.js
new file mode 100644
index 000000000..887c71513
--- /dev/null
+++ b/packages/herald-mcp/src/config.js
@@ -0,0 +1,43 @@
+// Centralized env + HTTP base for the herald MCP.
+//
+// This server has exactly one job: hand a line to the three.ws delivery rail so
+// the human who owns the key hears it from their own 3D companion. It is
+// authenticated (a Bearer credential on every request), it signs nothing
+// locally, and it holds no other secret.
+//
+// The addressing model is worth understanding before wiring an agent to it: an
+// announcement always goes to the *key owner's own* sessions. There is no
+// recipient parameter, so an agent cannot use this to interrupt anyone else.
+
+export function env(key, fallback) {
+ const v = process.env[key];
+ return v !== undefined && String(v).trim() !== '' ? String(v).trim() : fallback;
+}
+
+// Base URL of the three.ws API. Override only when self-hosting or pointing at
+// a preview deployment.
+export const THREE_WS_BASE = env('THREE_WS_BASE', 'https://three.ws').replace(/\/+$/, '');
+
+// The agent owner's three.ws credential: an API key (sk_live_… / sk_test_…)
+// carrying the `herald:announce` scope, or an OAuth access token for the same
+// account. REQUIRED: the rail is account-scoped and returns 401 without it.
+// THREE_WS_TOKEN / THREE_WS_BEARER are accepted aliases.
+export const THREE_WS_API_KEY =
+ env('THREE_WS_API_KEY') || env('THREE_WS_TOKEN') || env('THREE_WS_BEARER') || '';
+
+// Per-request timeout (ms). One small POST; generous enough to ride out a cold
+// edge without leaving an agent hanging.
+export const HTTP_TIMEOUT_MS = (() => {
+ const raw = env('THREE_WS_TIMEOUT_MS');
+ if (raw === undefined) return 20000;
+ const n = Number(raw);
+ if (!Number.isFinite(n) || n <= 0) {
+ throw Object.assign(new Error(`THREE_WS_TIMEOUT_MS must be a positive number (got "${raw}")`), {
+ code: 'bad_config',
+ });
+ }
+ return n;
+})();
+
+// Identifies this client to the API in request logs.
+export const USER_AGENT = '@three-ws/herald-mcp';
diff --git a/packages/herald-mcp/src/index.js b/packages/herald-mcp/src/index.js
new file mode 100755
index 000000000..57ce8e65a
--- /dev/null
+++ b/packages/herald-mcp/src/index.js
@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+// @three-ws/herald-mcp: MCP server entry point.
+//
+// Gives an AI agent a way to tell its human something in person. Not another
+// line in a log the person will never scroll back to: their own 3D companion
+// walks onto the browser tab they have open, gestures, and says it out loud,
+// with a link to click through.
+//
+// • announce say one line, with importance, tone, gesture and a link
+// • announce_result report a finished task with the urgency chosen for you
+// • check_rail prove the key and the rail work, interrupting nobody
+//
+// AUTHENTICATED, and deliberately unable to reach anyone else: an announcement
+// always goes to the key owner's own live sessions. There is no recipient
+// parameter, so the worst a leaked key can do is annoy the person who leaked
+// it. Keys are minted at https://three.ws/dashboard/developers with the
+// `herald:announce` scope and revoked there.
+//
+// Run standalone:
+// THREE_WS_API_KEY=sk_live_… node packages/herald-mcp/src/index.js
+//
+// Or wire into Claude Code / Cursor: see README.md.
+
+import { realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+import { def as announce } from './tools/announce.js';
+import { def as announceResult } from './tools/announce-result.js';
+import { def as checkRail } from './tools/check-rail.js';
+
+// Single source of truth for the advertised server version: package.json.
+const require = createRequire(import.meta.url);
+const { version: PKG_VERSION } = require('../package.json');
+
+export const TOOLS = [announce, announceResult, checkRail];
+
+/**
+ * Construct a fully-registered McpServer without connecting a transport.
+ * Registration is env-free (no key needed to advertise the tool surface), so
+ * this is safe to import from tests. A credential is required only to run one.
+ * @returns {McpServer}
+ */
+export function buildServer() {
+ const server = new McpServer(
+ { name: 'herald-mcp', title: 'three.ws Herald', version: PKG_VERSION },
+ {
+ capabilities: { tools: {} },
+ instructions:
+ 'three.ws Herald MCP: deliver a message to your human in person. announce says one line ' +
+ "through the owner's own 3D companion on whatever browser tab they have open, with " +
+ 'importance (0-100), tone, a gesture and an optional link. announce_result reports a ' +
+ 'finished task and picks the urgency from the outcome, so a failure cuts through quiet ' +
+ 'hours and a success does not. check_rail verifies the credential without interrupting ' +
+ 'anybody. Reserve these for moments that deserve to interrupt a person: the client applies ' +
+ 'an importance floor, a rate limit, dedupe and quiet hours, so chatter is dropped rather ' +
+ 'than queued. Every announcement is delivered to the key owner and nobody else, and an ' +
+ 'undelivered one expires in about five minutes rather than piling up. Requires ' +
+ 'THREE_WS_API_KEY with the herald:announce scope. $THREE is the only coin.',
+ },
+ );
+
+ for (const tool of TOOLS) {
+ server.registerTool(
+ tool.name,
+ {
+ title: tool.title,
+ description: tool.description,
+ inputSchema: tool.inputSchema,
+ annotations: tool.annotations,
+ },
+ async (args, extra) => {
+ try {
+ const result = await tool.handler(args, extra);
+ const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+ return { content: [{ type: 'text', text }] };
+ } catch (err) {
+ const payload = {
+ ok: false,
+ error: err?.code || 'unhandled',
+ message: err?.message || String(err),
+ ...(err?.status ? { status: err.status } : {}),
+ ...(err?.body ? { detail: err.body } : {}),
+ };
+ return {
+ content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+ isError: true,
+ };
+ }
+ },
+ );
+ }
+
+ return server;
+}
+
+async function main() {
+ const server = buildServer();
+ const transport = new StdioServerTransport();
+ await server.connect(transport);
+ console.error(`[herald-mcp@${PKG_VERSION}] connected over stdio with ${TOOLS.length} tools`);
+}
+
+// Connect stdio ONLY when this file is the process entry point. Importing the
+// module (tests, embedding) must not grab the transport. realpath both sides:
+// npm bin shims are symlinks, so argv[1] may differ from import.meta.url.
+function isProcessEntryPoint() {
+ if (!process.argv[1]) return false;
+ try {
+ return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+ } catch {
+ return false;
+ }
+}
+
+if (isProcessEntryPoint()) {
+ main().catch((err) => {
+ console.error('[herald-mcp] fatal:', err);
+ process.exit(1);
+ });
+}
diff --git a/packages/herald-mcp/src/lib/api.js b/packages/herald-mcp/src/lib/api.js
new file mode 100644
index 000000000..3e76a05d1
--- /dev/null
+++ b/packages/herald-mcp/src/lib/api.js
@@ -0,0 +1,80 @@
+// Real HTTP access to the three.ws herald rail. No mocks, no fixtures: every
+// call is a live, authenticated request to THREE_WS_BASE. The Bearer credential
+// is attached here (single HTTP client, single auth path) and errors are
+// normalized into one shape so tool handlers surface a clean message + status.
+
+import { THREE_WS_BASE, HTTP_TIMEOUT_MS, USER_AGENT, THREE_WS_API_KEY } from '../config.js';
+
+// Thrown before any request when the server has no credential. The rail is
+// account-scoped, so a missing key is a config error, not an upstream 401.
+export class MissingCredentialError extends Error {
+ constructor() {
+ super(
+ 'No three.ws credential configured. Set THREE_WS_API_KEY to a three.ws API key ' +
+ '(sk_live_… / sk_test_…) carrying the herald:announce scope, or an OAuth access token ' +
+ 'for the same account. Create one at https://three.ws/dashboard/developers.',
+ );
+ this.code = 'missing_credential';
+ this.status = 401;
+ }
+}
+
+/**
+ * Call a three.ws endpoint and return its parsed JSON body.
+ *
+ * @param {string} path Endpoint path beginning with `/`.
+ * @param {{ method?: string, body?: unknown }} [opts]
+ * @returns {Promise<any>}
+ * @throws {MissingCredentialError} when no credential is configured.
+ * @throws {Error} with `.code` ('timeout' | 'network_error' | 'upstream_error'),
+ * and on upstream errors `.status` + `.body`.
+ */
+export async function apiRequest(path, { method = 'GET', body } = {}) {
+ if (!THREE_WS_API_KEY) throw new MissingCredentialError();
+
+ const controller = new AbortController();
+ const timer = setTimeout(() => controller.abort(), HTTP_TIMEOUT_MS);
+
+ let res;
+ try {
+ res = await fetch(`${THREE_WS_BASE}${path}`, {
+ method,
+ headers: {
+ accept: 'application/json',
+ 'user-agent': USER_AGENT,
+ // Capital-B "Bearer " — the server's CSRF guard exempts requests on
+ // this exact prefix, so authenticated writes need no CSRF token.
+ authorization: `Bearer ${THREE_WS_API_KEY}`,
+ ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+ },
+ body: body !== undefined ? JSON.stringify(body) : undefined,
+ signal: controller.signal,
+ });
+ } catch (err) {
+ clearTimeout(timer);
+ if (err?.name === 'AbortError') {
+ throw Object.assign(new Error(`three.ws ${path} timed out after ${HTTP_TIMEOUT_MS}ms`), {
+ code: 'timeout',
+ });
+ }
+ throw Object.assign(new Error(`three.ws ${path} request failed: ${err?.message || err}`), {
+ code: 'network_error',
+ });
+ }
+ clearTimeout(timer);
+
+ const text = await res.text();
+ let data;
+ try {
+ data = text ? JSON.parse(text) : {};
+ } catch {
+ data = { raw: text };
+ }
+
+ if (!res.ok) {
+ const message =
+ data?.error_description || data?.message || data?.error || `three.ws ${path} returned HTTP ${res.status}`;
+ throw Object.assign(new Error(message), { code: 'upstream_error', status: res.status, body: data });
+ }
+ return data;
+}
diff --git a/packages/herald-mcp/src/tools/announce-result.js b/packages/herald-mcp/src/tools/announce-result.js
new file mode 100644
index 000000000..9666c59f2
--- /dev/null
+++ b/packages/herald-mcp/src/tools/announce-result.js
@@ -0,0 +1,93 @@
+// `announce_result` — report a finished task with the urgency it deserves.
+//
+// The importance/tone choice is the part an agent gets wrong, so this tool
+// makes it for you from the outcome: a failure is loud enough to cut through
+// quiet hours, a success is not.
+
+import { z } from 'zod';
+
+import { apiRequest } from '../lib/api.js';
+
+const IMPORTANCE = { failed: 95, needs_input: 90, succeeded: 65 };
+const TONE = { failed: 'error', needs_input: 'alert', succeeded: 'celebrate' };
+const EMOTE = { failed: undefined, needs_input: 'wave', succeeded: 'dance' };
+
+function humanDuration(seconds) {
+ if (!Number.isFinite(seconds) || seconds <= 0) return null;
+ if (seconds < 60) return `${Math.round(seconds)}s`;
+ if (seconds < 3600) return `${Math.round(seconds / 60)}m`;
+ return `${(seconds / 3600).toFixed(1)}h`;
+}
+
+export const def = {
+ name: 'announce_result',
+ title: 'Report a finished task in person',
+ annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: true },
+ description:
+ 'Tell the human how a task went, in person, with the urgency chosen for you from the outcome: ' +
+ '`failed` and `needs_input` are loud enough to cut through quiet hours, `succeeded` is not. Pass ' +
+ 'the task name, the outcome, and optionally how long it took and where to look. This is the right ' +
+ 'tool at the end of anything long enough that the person walked away from it. Returns the queued ' +
+ 'announcement.',
+ inputSchema: {
+ task: z
+ .string()
+ .trim()
+ .min(1)
+ .max(120)
+ .describe('What was being done, in human words ("the nightly backfill", "your test suite").'),
+ outcome: z
+ .enum(['succeeded', 'failed', 'needs_input'])
+ .describe('How it ended. Drives importance, tone and gesture.'),
+ detail: z
+ .string()
+ .trim()
+ .max(160)
+ .optional()
+ .describe('One short clause of context ("3 tests failing", "waiting on your approval").'),
+ seconds: z
+ .number()
+ .min(0)
+ .optional()
+ .describe('How long it took, in seconds. Rendered as "in 4m" when given.'),
+ url: z
+ .string()
+ .trim()
+ .max(2048)
+ .optional()
+ .describe('Where to look: the run, the diff, the dashboard.'),
+ key: z
+ .string()
+ .trim()
+ .max(120)
+ .optional()
+ .describe('Dedupe key, so a retry loop reporting the same result says it once.'),
+ },
+ async handler(args) {
+ const took = humanDuration(args.seconds);
+ const verb =
+ args.outcome === 'succeeded' ? 'finished' : args.outcome === 'failed' ? 'failed' : 'needs you';
+ const parts = [`${args.task} ${verb}`];
+ if (took) parts[0] += args.outcome === 'succeeded' ? ` in ${took}` : ` after ${took}`;
+ if (args.detail) parts.push(args.detail);
+
+ const data = await apiRequest('/api/herald/announce', {
+ method: 'POST',
+ body: {
+ text: parts.join(': ').slice(0, 280),
+ importance: IMPORTANCE[args.outcome],
+ tone: TONE[args.outcome],
+ emote: EMOTE[args.outcome],
+ url: args.url,
+ key: args.key,
+ },
+ });
+ return {
+ ok: true,
+ id: data?.id ?? null,
+ queued: data?.queued === true,
+ said: data?.announcement?.text ?? null,
+ importance: IMPORTANCE[args.outcome],
+ };
+ },
+};
diff --git a/packages/herald-mcp/src/tools/announce.js b/packages/herald-mcp/src/tools/announce.js
new file mode 100644
index 000000000..ca13ed1f3
--- /dev/null
+++ b/packages/herald-mcp/src/tools/announce.js
@@ -0,0 +1,90 @@
+// `announce` — say one line, in person, on the owner's own screen.
+
+import { z } from 'zod';
+
+import { apiRequest } from '../lib/api.js';
+
+export const def = {
+ name: 'announce',
+ title: 'Tell your human, in person',
+ annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: true },
+ description:
+ 'Deliver one line to the human who owns this key, in person: their 3D companion walks onto the ' +
+ 'browser tab they have open, gestures, and says it, with an optional link to click through. Use ' +
+ 'this for the handful of moments that deserve to interrupt someone (a long task finished, a ' +
+ 'decision is needed, something broke), not for progress chatter: the client applies an importance ' +
+ 'floor, a rate limit, quiet hours and dedupe, so noise is dropped rather than queued. The message ' +
+ 'is always delivered to the key owner and nobody else. If no browser is open it expires quietly in ' +
+ 'about five minutes; the durable record is the notification inbox, not this. Returns the queued ' +
+ 'announcement and how long it stays deliverable.',
+ inputSchema: {
+ text: z
+ .string()
+ .trim()
+ .min(1)
+ .max(280)
+ .describe('The line to say out loud. One sentence. Write it as speech, not as a log line.'),
+ from: z
+ .string()
+ .trim()
+ .max(60)
+ .optional()
+ .describe('Who it is from, spoken as attribution ("your build", "Stripe", the agent\'s name).'),
+ importance: z
+ .number()
+ .int()
+ .min(0)
+ .max(100)
+ .optional()
+ .describe(
+ '0-100, default 70. The client drops anything under its floor (50 by default) and only ' +
+ 'lets 90+ through quiet hours. Use 90+ for something broken or blocking, 60-80 for a ' +
+ 'finished task, under 50 for something that can wait for the inbox.',
+ ),
+ url: z
+ .string()
+ .trim()
+ .max(2048)
+ .optional()
+ .describe('Where clicking through goes: an absolute https URL or a three.ws path.'),
+ tone: z
+ .enum(['neutral', 'alert', 'celebrate', 'error'])
+ .optional()
+ .describe('Colours the bubble and picks a default gesture. Default alert.'),
+ emote: z
+ .enum(['wave', 'dance', 'punch', 'backflip'])
+ .optional()
+ .describe('Gesture the avatar arrives with. Rigs without it fall back to a wave.'),
+ key: z
+ .string()
+ .trim()
+ .max(120)
+ .optional()
+ .describe(
+ 'Dedupe key. Two announcements sharing a key are said once, so a retrying job can call ' +
+ 'this every attempt without repeating itself.',
+ ),
+ },
+ async handler(args) {
+ const data = await apiRequest('/api/herald/announce', {
+ method: 'POST',
+ body: {
+ text: args.text,
+ from: args.from,
+ importance: args.importance,
+ url: args.url,
+ tone: args.tone,
+ emote: args.emote,
+ key: args.key,
+ },
+ });
+ return {
+ ok: true,
+ id: data?.id ?? null,
+ queued: data?.queued === true,
+ expires_in_seconds: data?.expires_in ?? null,
+ delivered_to: 'the key owner\'s own live sessions',
+ announcement: data?.announcement ?? null,
+ };
+ },
+};
diff --git a/packages/herald-mcp/src/tools/check-rail.js b/packages/herald-mcp/src/tools/check-rail.js
new file mode 100644
index 000000000..636bb8832
--- /dev/null
+++ b/packages/herald-mcp/src/tools/check-rail.js
@@ -0,0 +1,42 @@
+// `check_rail` — prove the credential and the rail work, without interrupting.
+
+import { z } from 'zod';
+
+import { apiRequest } from '../lib/api.js';
+import { THREE_WS_BASE } from '../config.js';
+
+export const def = {
+ name: 'check_rail',
+ title: 'Check the delivery rail',
+ annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+ description:
+ 'Verify that the configured key works and the delivery rail accepts announcements, without ' +
+ 'interrupting anybody: it queues a line at importance 0, which every client drops under its own ' +
+ 'floor. Use this once when wiring an agent up, or when announce fails and you need to tell a bad ' +
+ 'key apart from an unreachable rail. Returns the base URL and whether the credential was accepted.',
+ inputSchema: {
+ note: z
+ .string()
+ .trim()
+ .max(60)
+ .optional()
+ .describe('Optional label recorded on the probe, to tell two agents apart in a log.'),
+ },
+ async handler(args) {
+ await apiRequest('/api/herald/announce', {
+ method: 'POST',
+ body: {
+ text: `herald check${args?.note ? `: ${args.note}` : ''}`,
+ importance: 0,
+ key: 'herald:mcp:check',
+ },
+ });
+ return {
+ ok: true,
+ base: THREE_WS_BASE,
+ credential: 'accepted',
+ interrupted_anyone: false,
+ note: 'Queued at importance 0, which every client drops under its own floor.',
+ };
+ },
+};
diff --git a/packages/herald-mcp/test/registration.test.mjs b/packages/herald-mcp/test/registration.test.mjs
new file mode 100644
index 000000000..e966acbe5
--- /dev/null
+++ b/packages/herald-mcp/test/registration.test.mjs
@@ -0,0 +1,65 @@
+// Tool-surface invariants for @three-ws/herald-mcp.
+//
+// Importing src/index.js is side-effect-free: the stdio transport only connects
+// when the file is the process entry point, and buildServer() needs no
+// credential to advertise the tool surface. These tests run offline: they never
+// touch the network.
+//
+// Run: node --test packages/herald-mcp/test/registration.test.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { TOOLS, buildServer } from '../src/index.js';
+
+const EXPECTED_NAMES = ['announce', 'announce_result', 'check_rail'];
+// Anything that queues a real interruption is a write.
+const WRITE_NAMES = new Set(['announce', 'announce_result']);
+
+test('registers exactly the advertised tools', () => {
+ assert.deepEqual(
+ TOOLS.map((t) => t.name),
+ EXPECTED_NAMES,
+ );
+});
+
+test('every tool carries a title, a description and a schema', () => {
+ for (const tool of TOOLS) {
+ assert.ok(tool.title, `${tool.name} needs a title`);
+ assert.ok(tool.description?.length > 80, `${tool.name} needs a real description`);
+ assert.equal(typeof tool.inputSchema, 'object', `${tool.name} needs an input schema`);
+ assert.equal(typeof tool.handler, 'function', `${tool.name} needs a handler`);
+ }
+});
+
+test('write tools never claim to be read-only, and the probe does', () => {
+ for (const tool of TOOLS) {
+ const readOnly = tool.annotations?.readOnlyHint === true;
+ if (WRITE_NAMES.has(tool.name)) {
+ assert.equal(readOnly, false, `${tool.name} queues a real interruption`);
+ } else {
+ assert.equal(readOnly, true, `${tool.name} should be marked read-only`);
+ }
+ }
+});
+
+test('announce constrains the line the way the API does', () => {
+ const schema = TOOLS.find((t) => t.name === 'announce').inputSchema;
+ assert.equal(schema.text.safeParse('').success, false);
+ assert.equal(schema.text.safeParse('x'.repeat(281)).success, false);
+ assert.equal(schema.text.safeParse('Deploy is green').success, true);
+ assert.equal(schema.importance.safeParse(101).success, false);
+ assert.equal(schema.importance.safeParse(80).success, true);
+});
+
+test('announce_result only accepts the three outcomes it maps', () => {
+ const schema = TOOLS.find((t) => t.name === 'announce_result').inputSchema;
+ for (const outcome of ['succeeded', 'failed', 'needs_input']) {
+ assert.equal(schema.outcome.safeParse(outcome).success, true);
+ }
+ assert.equal(schema.outcome.safeParse('maybe').success, false);
+});
+
+test('buildServer constructs without a credential', () => {
+ assert.ok(buildServer());
+});
diff --git a/packages/shipfeed/tests/feed.test.js b/packages/shipfeed/tests/feed.test.js
new file mode 100644
index 000000000..dbb2c76c2
--- /dev/null
+++ b/packages/shipfeed/tests/feed.test.js
@@ -0,0 +1,161 @@
+import { describe, it, expect } from 'vitest';
+import { buildShipFeed } from '../src/feed.js';
+import { groupIntoShips } from '../src/group.js';
+import { commitsFromGitLog, normalizeChangelog, GIT_LOG_FORMAT } from '../src/sources.js';
+
+const NUL = String.fromCharCode(0);
+const RS = String.fromCharCode(30);
+
+const commit = (sha, message, date, extra = {}) => ({
+ sha: sha.padEnd(40, '0'),
+ html_url: `https://github.com/o/r/commit/${sha}`,
+ parents: [{ sha: 'p' }],
+ commit: {
+ message,
+ author: { name: 'nirholas', date },
+ committer: { date },
+ },
+ author: { login: 'nirholas' },
+ ...extra,
+});
+
+const entries = [
+ {
+ date: '2026-08-27',
+ title: 'Text-to-3D now has five independent image sources behind it',
+ summary:
+ 'Every text-to-3D generation starts by painting a concept image. The painter now tries five independent image providers in order under one shared time budget.',
+ tags: ['fix', 'infra'],
+ link: '/forge',
+ },
+];
+
+const background = [
+ commit('d001', 'docs(seeker): write the dApp Store release runbook', '2026-08-27T07:00:00Z'),
+ commit('d002', 'fix(wallet): tell the owner a wallet is unsignable', '2026-08-27T07:30:00Z'),
+ commit('d003', 'test(agent-index): cover the backlog drain', '2026-08-27T08:00:00Z'),
+];
+
+describe('buildShipFeed', () => {
+ const commits = [
+ commit('aaa1', 'fix(forge): put every concept image provider on one shared time budget', '2026-08-27T09:00:00Z'),
+ commit('bbb2', 'chore(deps): bump ws', '2026-08-27T09:10:00Z'),
+ commit('ccc3', 'feat(companion): let the corner avatar deliver a message', '2026-08-26T18:00:00Z'),
+ ...background,
+ ];
+
+ it('attaches commits to the release note they produced', () => {
+ const feed = buildShipFeed({ commits, entries, repo: 'o/r', siteUrl: 'https://three.ws' });
+ const release = feed.releases[0];
+ expect(release.commits.map((c) => c.shortSha)).toContain('aaa1000');
+ expect(release.stats.commits).toBeGreaterThan(0);
+ expect(release.url).toBe(
+ 'https://three.ws/changelog/2026-08-27-text-to-3d-now-has-five-independent-image-sources-behind-it',
+ );
+ });
+
+ it('carries a confidence and a reason on every linked commit', () => {
+ const feed = buildShipFeed({ commits, entries, repo: 'o/r' });
+ for (const c of feed.releases.flatMap((r) => r.commits)) {
+ expect(c.confidence).toBeGreaterThan(0);
+ expect(Array.isArray(c.why)).toBe(true);
+ expect(c.why.length).toBeGreaterThan(0);
+ }
+ });
+
+ it('groups everything no note claimed into ships', () => {
+ const feed = buildShipFeed({ commits, entries, repo: 'o/r' });
+ const shipShas = feed.ships.flatMap((s) => s.commits.map((c) => c.shortSha));
+ const linkedShas = feed.releases.flatMap((r) => r.commits.map((c) => c.shortSha));
+ expect(shipShas.length + linkedShas.length).toBe(commits.length);
+ expect(shipShas.some((s) => linkedShas.includes(s))).toBe(false);
+ });
+
+ it('reports coverage, audience mix, and velocity', () => {
+ const feed = buildShipFeed({ commits, entries, repo: 'o/r', now: Date.parse('2026-08-28T00:00:00Z') });
+ expect(feed.stats.commits).toBe(commits.length);
+ expect(feed.stats.coverage).toBeGreaterThan(0);
+ expect(feed.stats.coverage).toBeLessThanOrEqual(1);
+ expect(feed.stats.byAudience.holder + feed.stats.byAudience.developer + feed.stats.byAudience.internal).toBe(
+ commits.length,
+ );
+ expect(feed.stats.velocity.map((v) => v.date)).toEqual(['2026-08-26', '2026-08-27']);
+ expect(feed.stats.topAuthors[0]).toEqual({ name: 'nirholas', count: commits.length });
+ });
+
+ it('hides machinery at the holder floor and says how much it hid', () => {
+ const feed = buildShipFeed({ commits, entries, repo: 'o/r', minAudience: 'holder' });
+ const shown = [
+ ...feed.releases.flatMap((r) => r.commits),
+ ...feed.ships.flatMap((s) => s.commits),
+ ];
+ expect(shown.some((c) => c.shortSha === 'bbb2000')).toBe(false);
+ expect(feed.stats.hidden).toBeGreaterThan(0);
+ });
+
+ it('drops release notes from outside the commit window', () => {
+ const old = { date: '2020-01-01', title: 'Ancient history', summary: 'Long gone.', tags: [] };
+ const feed = buildShipFeed({ commits, entries: [...entries, old], repo: 'o/r' });
+ expect(feed.releases.map((r) => r.title)).not.toContain('Ancient history');
+ expect(feed.stats.entriesConsidered).toBe(2);
+ });
+
+ it('returns an empty but well-formed feed for an empty repository', () => {
+ const feed = buildShipFeed({ commits: [], entries: [] });
+ expect(feed.releases).toEqual([]);
+ expect(feed.ships).toEqual([]);
+ expect(feed.stats.commits).toBe(0);
+ expect(feed.stats.coverage).toBe(0);
+ });
+});
+
+describe('groupIntoShips', () => {
+ it('splits bursts on a quiet gap and headlines each by its strongest commit', () => {
+ const ships = groupIntoShips([
+ commit('a1', 'chore: tidy an import', '2026-08-27T09:00:00Z'),
+ commit('a2', 'feat(forge): add a provider rung to the painter', '2026-08-27T09:20:00Z'),
+ commit('b1', 'fix(wallet): stop a double withdrawal prompt', '2026-08-27T16:00:00Z'),
+ ]);
+ expect(ships).toHaveLength(2);
+ expect(ships[0].commits).toHaveLength(1); // newest ship first
+ expect(ships[1].title).toBe('Feature · forge');
+ expect(ships[1].commits).toHaveLength(2);
+ });
+});
+
+describe('commitsFromGitLog', () => {
+ it('parses git log output into the same shape the API returns', () => {
+ const record = [
+ 'f'.repeat(40),
+ '2026-08-27T09:00:00Z',
+ '2026-08-27T08:55:00Z',
+ 'nirholas',
+ 'nirholas',
+ 'parent1 parent2',
+ 'feat(forge): a thing\n\nbody',
+ ].join(NUL);
+ const [parsed] = commitsFromGitLog(record + RS, { repo: 'o/r' });
+ expect(parsed.sha).toBe('f'.repeat(40));
+ expect(parsed.parents).toHaveLength(2);
+ expect(parsed.commit.committer.date).toBe('2026-08-27T09:00:00Z');
+ expect(parsed.html_url).toBe(`https://github.com/o/r/commit/${'f'.repeat(40)}`);
+ });
+
+ it('publishes the exact format string it expects', () => {
+ expect(GIT_LOG_FORMAT).toContain('%x00');
+ expect(GIT_LOG_FORMAT.endsWith('%x1e')).toBe(true);
+ });
+});
+
+describe('normalizeChangelog', () => {
+ it('accepts the three.ws feed shape and a bare array alike', () => {
+ const wrapped = normalizeChangelog({ entries });
+ const bare = normalizeChangelog(entries);
+ expect(wrapped).toEqual(bare);
+ expect(wrapped[0].tags).toEqual(['fix', 'infra']);
+ });
+
+ it('drops entries with no date or title rather than inventing one', () => {
+ expect(normalizeChangelog([{ title: 'no date' }, { date: '2026-08-27' }, null])).toEqual([]);
+ });
+});
diff --git a/public/ship/index.html b/public/ship/index.html
new file mode 100644
index 000000000..d99ec9e5a
--- /dev/null
+++ b/public/ship/index.html
@@ -0,0 +1,289 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width,initial-scale=1" />
+<title>Ship log · three.ws</title>
+<meta name="description" content="Every three.ws release note joined to the commits that produced it, with a confidence score and the reasoning behind every link." />
+<link rel="canonical" href="https://three.ws/ship" />
+<link rel="alternate" type="application/rss+xml" title="three.ws ship log" href="/api/ship/feed?format=rss" />
+<link rel="stylesheet" href="/nav.css" />
+<link rel="stylesheet" href="/footer.css" />
+<script>/* three.ws theme boot — no-flash; runtime in /theme-switcher.js */(function(){try{var m=localStorage.getItem('twx_theme');var l=m==='auto'?(window.matchMedia&&window.matchMedia('(prefers-color-scheme: light)').matches):m==='light';document.documentElement.setAttribute('data-theme',l?'light':'dark');}catch(e){document.documentElement.setAttribute('data-theme','dark');}})();</script>
+<style>
+ body { margin: 0; background: var(--bg-0); color: var(--ink); font-family: var(--font-body); -webkit-font-smoothing: antialiased; }
+ .sl-wrap { max-width: 940px; margin: 0 auto; padding: 96px 24px 72px; }
+
+ .sl-hero h1 { font-size: clamp(34px, 5vw, 52px); margin: 0 0 12px; letter-spacing: -0.02em; color: var(--ink-bright); }
+ .sl-hero p { color: var(--ink-dim); font-size: 17px; margin: 0 0 8px; line-height: 1.55; max-width: 62ch; }
+ .sl-hero a { color: var(--ink); }
+
+ .sl-stats { display: grid; grid-template-columns: repeat(auto-fit, minmax(140px, 1fr)); gap: 10px; margin: 28px 0 0; }
+ .sl-stat { background: var(--surface-1); border: 1px solid var(--stroke); border-radius: var(--radius-lg); padding: 14px 16px; }
+ .sl-stat-value { font-size: 26px; font-weight: var(--weight-bold); color: var(--ink-bright); font-variant-numeric: tabular-nums; letter-spacing: -0.01em; }
+ .sl-stat-label { font-size: 11px; text-transform: uppercase; letter-spacing: 0.06em; color: var(--ink-faint); margin-top: 4px; }
+ .sl-spark { display: flex; align-items: flex-end; gap: 2px; height: 30px; margin-top: 6px; }
+ .sl-spark span { flex: 1 1 0; background: color-mix(in srgb, var(--success) 55%, transparent); border-radius: 2px 2px 0 0; min-height: 2px; transition: background var(--duration-fast) var(--ease-standard); }
+ .sl-spark span:hover { background: var(--success); }
+
+ .sl-controls { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; margin: 26px 0 0; }
+ .sl-filter { background: var(--surface-1); border: 1px solid var(--stroke); color: var(--ink-dim); font-size: 12px; font-weight: var(--weight-semibold); letter-spacing: 0.03em; border-radius: var(--radius-pill); padding: 6px 14px; cursor: pointer; transition: border-color var(--duration-fast) var(--ease-standard), color var(--duration-fast) var(--ease-standard); }
+ .sl-filter:hover { border-color: var(--stroke-strong); color: var(--ink-bright); }
+ .sl-filter:focus-visible { outline: 2px solid var(--focus-ring-color); outline-offset: 2px; }
+ .sl-filter[aria-pressed="true"] { border-color: var(--success); color: var(--success); background: color-mix(in srgb, var(--success) 8%, transparent); }
+ .sl-spacer { flex: 1 1 auto; }
+
+ .sl-section-title { font-size: 12px; text-transform: uppercase; letter-spacing: 0.08em; color: var(--ink-faint); margin: 48px 0 14px; }
+
+ .sl-release { background: var(--surface-1); border: 1px solid var(--stroke); border-radius: var(--radius-lg); padding: 18px 20px; margin-bottom: 12px; transition: border-color var(--duration-fast) var(--ease-standard); }
+ .sl-release:hover { border-color: var(--stroke-strong); }
+ .sl-release-head { display: flex; align-items: baseline; gap: 10px; flex-wrap: wrap; }
+ .sl-date { font-family: var(--font-mono); font-size: 12px; color: var(--ink-faint); letter-spacing: 0.04em; }
+ .sl-title { color: var(--ink-bright); font-weight: var(--weight-semibold); font-size: 17px; line-height: 1.35; margin: 0; }
+ .sl-title a { color: inherit; text-decoration: none; }
+ .sl-title a:hover, .sl-title a:focus-visible { text-decoration: underline; }
+ .sl-summary { color: var(--ink-dim); font-size: 14px; line-height: 1.6; margin: 8px 0 0; }
+ .sl-tags { margin-top: 10px; display: flex; flex-wrap: wrap; gap: 6px; }
+ .sl-tag { font-size: 10px; font-weight: var(--weight-bold); letter-spacing: 0.05em; text-transform: uppercase; border-radius: var(--radius-pill); padding: 2px 8px; border: 1px solid var(--stroke); color: var(--ink-dim); }
+
+ details.sl-commits { margin-top: 14px; border-top: 1px solid var(--stroke); padding-top: 12px; }
+ details.sl-commits > summary { cursor: pointer; list-style: none; font-size: 12px; font-family: var(--font-mono); color: var(--ink-faint); display: flex; align-items: center; gap: 8px; }
+ details.sl-commits > summary::-webkit-details-marker { display: none; }
+ details.sl-commits > summary:focus-visible { outline: 2px solid var(--focus-ring-color); outline-offset: 3px; border-radius: 4px; }
+ details.sl-commits > summary::before { content: '+'; display: inline-block; width: 14px; text-align: center; color: var(--ink-dim); }
+ details.sl-commits[open] > summary::before { content: '-'; }
+ .sl-commit { display: grid; grid-template-columns: 74px 1fr auto; gap: 10px; align-items: baseline; padding: 7px 0; border-bottom: 1px dashed color-mix(in srgb, var(--stroke) 70%, transparent); }
+ .sl-commit:last-child { border-bottom: none; }
+ .sl-sha { font-family: var(--font-mono); font-size: 12px; color: var(--ink-faint); text-decoration: none; }
+ .sl-sha:hover, .sl-sha:focus-visible { color: var(--accent); text-decoration: underline; }
+ .sl-commit-text { font-size: 13px; line-height: 1.5; color: var(--ink-dim); }
+ .sl-commit-headline { color: var(--ink); font-weight: var(--weight-semibold); }
+ .sl-audience { font-size: 10px; text-transform: uppercase; letter-spacing: 0.05em; border-radius: var(--radius-pill); padding: 1px 7px; border: 1px solid var(--stroke); color: var(--ink-faint); white-space: nowrap; }
+ .sl-audience-holder { color: var(--success); border-color: color-mix(in srgb, var(--success) 35%, transparent); }
+ .sl-audience-developer { color: var(--accent); border-color: color-mix(in srgb, var(--accent) 35%, transparent); }
+ .sl-why { background: none; border: none; padding: 0 0 0 6px; font: inherit; font-size: 11px; color: var(--ink-faint); cursor: pointer; font-family: var(--font-mono); }
+ .sl-why:hover { color: var(--ink-bright); }
+ .sl-why:focus-visible { outline: 2px solid var(--focus-ring-color); outline-offset: 2px; border-radius: 3px; }
+ .sl-reasons { grid-column: 1 / -1; margin: 4px 0 6px 84px; font-size: 12px; color: var(--ink-faint); font-family: var(--font-mono); line-height: 1.6; }
+ .sl-reasons li { list-style: none; }
+ .sl-empty-note { color: var(--ink-faint); font-size: 12px; font-style: italic; margin-top: 12px; }
+
+ .sl-skeleton { background: var(--surface-1); border: 1px solid var(--stroke); border-radius: var(--radius-lg); height: 118px; margin-bottom: 12px; overflow: hidden; position: relative; }
+ .sl-skeleton::after { content: ''; position: absolute; inset: 0; transform: translateX(-100%); background: linear-gradient(90deg, transparent, color-mix(in srgb, var(--ink) 6%, transparent), transparent); animation: sl-shimmer 1.4s infinite; }
+ @keyframes sl-shimmer { 100% { transform: translateX(100%); } }
+ @media (prefers-reduced-motion: reduce) { .sl-skeleton::after { animation: none; } }
+
+ .sl-error { color: var(--ink-dim); font-size: 15px; line-height: 1.6; }
+ .sl-error a { color: var(--ink); }
+ @media (max-width: 560px) {
+ .sl-commit { grid-template-columns: 66px 1fr; }
+ .sl-audience { grid-column: 2; justify-self: start; }
+ .sl-reasons { margin-left: 0; }
+ }
+</style>
+ <meta name="robots" content="index, follow, max-image-preview:large, max-snippet:-1">
+ <meta property="og:type" content="website">
+ <meta property="og:site_name" content="three.ws">
+ <meta property="og:locale" content="en_US">
+ <meta property="og:title" content="Ship log · three.ws">
+ <meta property="og:description" content="Every three.ws release note joined to the commits that produced it, with a confidence score and the reasoning behind every link.">
+ <meta property="og:url" content="https://three.ws/ship">
+ <meta property="og:image" content="https://three.ws/api/page-og?s=learn&amp;t=Ship+log&amp;d=Every+release+note%2C+joined+to+the+commits+that+produced+it.&amp;p=%2Fship">
+ <meta property="og:image:width" content="1200">
+ <meta property="og:image:height" content="630">
+ <meta property="og:image:type" content="image/png">
+ <meta property="og:image:alt" content="Ship log — three.ws">
+ <meta name="twitter:card" content="summary_large_image">
+ <meta name="twitter:site" content="@trythreews">
+ <meta name="twitter:title" content="Ship log · three.ws">
+ <meta name="twitter:description" content="Every three.ws release note joined to the commits that produced it, with a confidence score and the reasoning behind every link.">
+ <meta name="twitter:image" content="https://three.ws/api/page-og?s=learn&amp;t=Ship+log&amp;d=Every+release+note%2C+joined+to+the+commits+that+produced+it.&amp;p=%2Fship">
+ <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"WebPage","name":"Ship log","description":"Every three.ws release note joined to the commits that produced it, with a confidence score and the reasoning behind every link.","url":"https://three.ws/ship","isPartOf":{"@type":"WebSite","name":"three.ws","url":"https://three.ws"}}]}</script>
+</head>
+<body>
+ <div id="nav-container"></div>
+ <script src="/nav.js"></script>
+ <main class="sl-wrap">
+ <div class="sl-hero">
+ <h1>Ship log</h1>
+ <p>The changelog says what shipped. The commit log says how. This page is the join: every release note with the code that produced it underneath, matched by <a href="/docs/shipfeed">an open-source scorer</a> that shows its reasoning and its confidence for every link.</p>
+ <p>Feeds: <a href="/api/ship/feed">JSON</a> · <a href="/api/ship/feed?format=rss">RSS</a> · <a href="/api/ship/feed?format=markdown">Markdown</a> · <a href="/changelog">plain changelog</a></p>
+ <div class="sl-stats" id="sl-stats" aria-live="polite"></div>
+ </div>
+
+ <div class="sl-controls" id="sl-controls" role="group" aria-label="Filter the ship log by audience"></div>
+
+ <div id="sl-content">
+ <div class="sl-skeleton" aria-hidden="true"></div>
+ <div class="sl-skeleton" aria-hidden="true"></div>
+ <div class="sl-skeleton" aria-hidden="true"></div>
+ <p class="sr-only" role="status">Loading the ship log.</p>
+ </div>
+ </main>
+
+ <script type="module">
+ const content = document.getElementById('sl-content');
+ const statsElt = document.getElementById('sl-stats');
+ const controls = document.getElementById('sl-controls');
+ const FILTERS = [
+ ['internal', 'Everything'],
+ ['developer', 'Developers'],
+ ['holder', 'Product news'],
+ ];
+ let audience = 'internal';
+ let feed = null;
+ let inFlight = null;
+
+ const esc = (s) => String(s ?? '').replace(/[<>&"]/g, (c) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;' })[c]);
+
+ function fmtDate(iso) {
+ try {
+ return new Date(iso + 'T00:00:00Z').toLocaleDateString(undefined, { month: 'short', day: 'numeric', year: 'numeric', timeZone: 'UTC' });
+ } catch { return iso; }
+ }
+
+ function renderStats(f) {
+ const v = f.stats.velocity;
+ const max = Math.max(1, ...v.map((d) => d.count));
+ const bars = v.map((d) => `<span style="height:${Math.max(6, Math.round((d.count / max) * 100))}%" title="${esc(d.date)}: ${d.count} commits"></span>`).join('');
+ statsElt.innerHTML = [
+ ['Commits read', f.stats.commits],
+ ['Release notes', f.stats.releases],
+ ['Linked to code', `${Math.round(f.stats.coverage * 100)}%`],
+ ['Unannounced', f.stats.orphans],
+ ].map(([label, value]) => `
+ <div class="sl-stat">
+ <div class="sl-stat-value">${esc(value)}</div>
+ <div class="sl-stat-label">${esc(label)}</div>
+ </div>`).join('') + `
+ <div class="sl-stat">
+ <div class="sl-spark" role="img" aria-label="Commits per day over the window">${bars}</div>
+ <div class="sl-stat-label">Daily commits</div>
+ </div>`;
+ }
+
+ function commitRow(c) {
+ const audienceClass = `sl-audience sl-audience-${esc(c.audience)}`;
+ const why = c.why && c.why.length
+ ? `<button class="sl-why" type="button" data-sha="${esc(c.sha)}" aria-expanded="false">why ${Math.round((c.confidence || 0) * 100)}%</button>`
+ : '';
+ return `
+ <div class="sl-commit" id="c-${esc(c.shortSha)}">
+ <a class="sl-sha" href="${esc(c.url)}" rel="noreferrer">${esc(c.shortSha)}</a>
+ <div class="sl-commit-text"><span class="sl-commit-headline">${esc(c.headline)}</span> ${esc(c.summary)}${why}</div>
+ <span class="${audienceClass}">${esc(c.audience)}</span>
+ </div>`;
+ }
+
+ function releaseCard(r) {
+ const tags = r.tags.map((t) => `<span class="sl-tag">${esc(t)}</span>`).join('');
+ const commits = r.commits.map(commitRow).join('');
+ const body = r.commits.length
+ ? `<details class="sl-commits"><summary>${r.commits.length} commit${r.commits.length === 1 ? '' : 's'}${r.stats.range ? ` · ${esc(r.stats.range)}` : ''}</summary>${commits}</details>`
+ : '<p class="sl-empty-note">No commit in this window matched this note with enough confidence to claim it.</p>';
+ return `
+ <article class="sl-release">
+ <div class="sl-release-head">
+ <span class="sl-date">${esc(fmtDate(r.date))}</span>
+ <h2 class="sl-title">${r.url ? `<a href="${esc(r.url)}">${esc(r.title)}</a>` : esc(r.title)}</h2>
+ </div>
+ ${r.summary ? `<p class="sl-summary">${esc(r.summary)}</p>` : ''}
+ ${tags ? `<div class="sl-tags">${tags}</div>` : ''}
+ ${body}
+ </article>`;
+ }
+
+ function shipCard(s) {
+ return `
+ <article class="sl-release">
+ <div class="sl-release-head">
+ <span class="sl-date">${esc(fmtDate(String(s.start).slice(0, 10)))}</span>
+ <h2 class="sl-title">${esc(s.title)}</h2>
+ </div>
+ <p class="sl-summary">${esc(s.summary)}</p>
+ <details class="sl-commits"><summary>${s.commits.length} commit${s.commits.length === 1 ? '' : 's'} · ${esc(s.id)}</summary>${s.commits.map(commitRow).join('')}</details>
+ </article>`;
+ }
+
+ function render() {
+ if (!feed) return;
+ renderStats(feed);
+ const releases = feed.releases.filter((r) => r.commits.length || audience === 'internal');
+ const parts = [];
+ if (releases.length === 0 && feed.ships.length === 0) {
+ parts.push('<p class="sl-error">Nothing in this window yet. Try <a href="/changelog">the changelog</a>.</p>');
+ }
+ if (releases.length) {
+ parts.push('<h2 class="sl-section-title">Announced</h2>', releases.map(releaseCard).join(''));
+ }
+ if (feed.ships.length) {
+ parts.push(
+ '<h2 class="sl-section-title">Unannounced: shipped, never written up</h2>',
+ feed.ships.map(shipCard).join(''),
+ );
+ }
+ content.innerHTML = parts.join('');
+ content.querySelectorAll('.sl-why').forEach((btn) => {
+ btn.addEventListener('click', () => toggleReasons(btn));
+ });
+ }
+
+ function toggleReasons(btn) {
+ const row = btn.closest('.sl-commit');
+ const open = btn.getAttribute('aria-expanded') === 'true';
+ const existing = row.nextElementSibling;
+ if (open && existing && existing.classList.contains('sl-reasons')) existing.remove();
+ if (!open) {
+ const sha = btn.dataset.sha;
+ const commit = [...feed.releases.flatMap((r) => r.commits), ...feed.ships.flatMap((s) => s.commits)].find((c) => c.sha === sha);
+ const list = document.createElement('ul');
+ list.className = 'sl-reasons';
+ list.innerHTML = (commit?.why || []).map((w) => `<li>${esc(w)}</li>`).join('');
+ row.after(list);
+ }
+ btn.setAttribute('aria-expanded', String(!open));
+ }
+
+ function renderControls() {
+ controls.innerHTML = FILTERS.map(([value, label]) =>
+ `<button class="sl-filter" type="button" data-audience="${value}" aria-pressed="${value === audience}">${label}</button>`,
+ ).join('') + '<span class="sl-spacer"></span>';
+ controls.querySelectorAll('.sl-filter').forEach((btn) => {
+ btn.addEventListener('click', () => {
+ if (btn.dataset.audience === audience) return;
+ audience = btn.dataset.audience;
+ renderControls();
+ load();
+ });
+ });
+ }
+
+ async function load() {
+ content.innerHTML = '<div class="sl-skeleton" aria-hidden="true"></div><div class="sl-skeleton" aria-hidden="true"></div><div class="sl-skeleton" aria-hidden="true"></div>';
+ inFlight?.abort();
+ const controller = new AbortController();
+ inFlight = controller;
+ try {
+ const res = await fetch(`/api/ship/feed?limit=200&audience=${audience}`, {
+ headers: { accept: 'application/json' },
+ signal: AbortSignal.any([controller.signal, AbortSignal.timeout(20000)]),
+ });
+ if (!res.ok) throw new Error('feed ' + res.status);
+ feed = await res.json();
+ render();
+ } catch (err) {
+ if (controller.signal.aborted) return;
+ content.innerHTML = '<p class="sl-error">The ship log could not be built right now. The <a href="/changelog">changelog</a> is always available, and the raw feed is at <a href="/api/ship/feed">/api/ship/feed</a>.</p>';
+ console.error('[ship]', err);
+ }
+ }
+
+ renderControls();
+ load();
+ </script>
+ <script src="/brand.js" defer></script>
+ <div id="footer-container"></div>
+ <script src="/footer.js"></script>
+ <script type="module" src="/i18n.js"></script>
+</body>
+</html>