birdclaw 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # CHANGELOG
 
+## 0.6.0 - 2026-05-22
+
+### Added
+
+- Add `birdclaw dms sync/list --mode xurl|auto` for recent OAuth2 DM event imports through `xurl`, with bird fallback in auto mode.
+- Add an explicit Messages sort toggle for newest conversations or sender follower count.
+- Add web DM inbox controls for switching between all, accepted, and message-request conversations.
+- Render the `What happened` AI digest as a structured day overview with summary cards, signal topics, highlight tweets, links, people, and hover previews for cited tweet ids and `@handle` mentions.
+- Add a streaming `What happened` AI digest in the web UI and CLI (`birdclaw today`, `birdclaw digest`) backed by OpenAI Responses API, GPT-5.5 by default, medium reasoning, priority service tier, local context hashing, and cached final structured results.
+- Add a global web account switcher plus `jobs sync-account`/`install-account-launchd` so multi-account Birdclaw installs can refresh home, mentions, likes, bookmarks, and DMs from launchd.
+
+### Changed
+
+- Stream the Today report as one longer Markdown brief with inline hoverable tweet citations instead of adding separate overview and action cards after the model finishes.
+- Increase the default Today digest tweet context and accept larger web digest requests so 24-hour reports can see deeper into the local archive.
+- Start the Effect rewrite by making `effect` a first-class runtime dependency and moving web API fetches, web sync orchestration, live command helpers, action transport, `bird`/`xurl` JSON/action transports and public adapters, backup export/import/validation and Git orchestration, moderation target resolution, blocks/mutes write helpers, remote block sync, batch blocklist imports, x-web mutations, authored/mentions/mention-thread sync including xurl recent-search and parent-walk fallback internals, conversation loading, home timeline, saved collection, DM live sync, profile hydration/resolution/affiliation/reply inspection, shared tweet lookup, research and whois report generation, follow graph live sync, link preview/index fetches, archive discovery/import subprocesses, avatar/URL caches, OpenAI/inbox scoring, scheduled bookmark sync locking/audit/launchd install, and media-fetch archive reuse/download concurrency onto Effect programs with Promise-compatible public wrappers.
+
+### Fixed
+
+- Deduplicate unscoped timeline rows across accounts so Home does not show the same tweet twice when multiple accounts saw it.
+- Render model-emitted Markdown links even when the model inserts a space or line break between the link label and URL.
+- Close Today tweet hover previews when opening their source links so command-clicked citations cannot leave stale preview cards stacked on later hovers.
+- Keep the Messages shell aligned with the rest of the app while collapsing the sidebar labels, and label optional follower/score DM filters instead of showing default `0` fields.
+- Link grouped AI digest tweet citations to nearby readable text instead of showing raw `tweet_...` IDs.
+- Expand the Messages web layout into an icon-rail workspace so the DM list and thread panes no longer squeeze into the standard feed width.
+- Show DM message requests across accounts instead of filtering them by the active sidebar account.
+- Verify the live `bird` account before DM sync, preserve stable account IDs for sparse DM payloads, and pace request-page imports.
+- Align DM profile stat labels and values consistently in the web detail panel.
+- Keep outbound DM bubble text readable by separating inbound and outbound bubble color classes in the web UI.
+- Link AI digest tweet citations on readable text instead of leaking raw `tweet_...` ids when the model cites a local tweet by prefixed id.
+- Hydrate profile metadata for Today highlight tweets so real avatar images replace fallback initials after cached digest results render.
+- Allow trusted private-proxy web deployments to stream the AI digest remotely without a token, while keeping app-level token enforcement when configured and surfacing API error details in the Today view.
+- Harden web write/quota endpoints, URL/avatar fetching, backup imports, archive replacement imports, block sync pruning, and GitHub workflows based on a deepsec security pass.
+- Validate compose, tweet-reply, and DM-reply writes before live transport, reject failed xurl sends without leaving local ghost entries, and keep failed web reply drafts visible with the transport error.
+- Keep account-scoped manual sync buttons disabled until account metadata loads so saved timelines do not submit accountless collection syncs.
+- Cancel failed link preview response bodies promptly so repeated broken preview fetches do not leave sockets open until timeout.
+- Harden link preview metadata fetching against private-network redirects, DNS rebinding, oversized or compressed responses, and slow/broken multi-address hosts.
+- Link raw `@handle` mentions in archived timeline text and render retweets as embedded original tweets with compact repost attribution.
+- Remove the duplicate inline sync account picker now that the global web account switcher controls manual sync account state, and move the theme toggle out of the sidebar footer so the account switcher stays anchored at the bottom.
+- Move the one-button theme toggle above the sidebar account picker so the bottom controls align with the active-account avatar.
+- Hide unresolved `t.co` placeholders and duplicate preview cards on media tweets, and let single-image media render in a natural image-sized frame.
+- Render reposts as native timeline rows with the original author avatar and a single compact repost attribution.
+- Hide empty bookmark, media, and account metadata from timeline action rows so the footer only shows useful state.
+- Move the theme toggle into the sidebar account footer row so it sits with the active-account controls.
+
+## 0.5.1 - 2026-05-15
+
+### Fixed
+
+- Harden the published CLI wrapper and release checks so the packaged `birdclaw` binary avoids `tsx` CLI IPC startup and stays covered by lint, format, and smoke tests.
+- Forward shutdown signals through the published CLI and bundled web server, and include referenced script helpers in npm packages.
+- Keep the selected DM conversation visible while its thread refreshes so the reply composer no longer flashes away mid-action.
+- Send the selected web account through manual sync controls so multi-account timelines sync the intended profile.
+- Run web sync requests as background jobs with status polling so the UI no longer holds one blocking sync request open.
+- Add typed web API fetch handling and explicit DMs loading/error/empty states so failed local reads surface cleanly.
+- Add explicit web app sync controls for home timeline, mentions, likes, bookmarks, and DMs so fresh live data can be pulled without leaving the UI.
+- Refine the web app sidebar tagline and theme selector so the brand chrome reads more clearly in compact layouts.
+- Add shared web feed loading/error/empty states with timeline-shaped skeleton rows and move conversation expansion into a cached single-thread surface with hover prefetch.
+- Use the Birdclaw crab-bird mark in the web app chrome, loading states, and empty states; soften dark-mode contrast and replace text-only reply warnings with conversation/replied indicators.
+- Allow the local web app to respond when Tailscale Serve forwards requests through the `clawmac.sheep-coho.ts.net` hostname.
+- Speed up the default home timeline load on large local databases and keep malformed archived media URL entities from crashing the web timeline.
+- Preserve tweet media aspect ratios, open timeline media in an inline viewer, and suppress duplicate media URL cards.
+
 ## 0.5.0 - 2026-05-15
 
 ### Added

package/README.md

@@ -78,6 +78,12 @@ Status: WIP. Real and usable. Not done. Expect schema churn, transport gaps, and
 - CI disables live writes
 - app has no auth layer because it is a local-only tool
 
+### Runtime Architecture
+
+Birdclaw uses [Effect](https://effect.website/) for new and migrated I/O-heavy internals. The current Effect boundary covers browser API fetches, web sync orchestration, sync-job polling, `bird`/`xurl` subprocess helpers and public adapters, backup export/import/validation and Git orchestration, moderation action transport and target resolution, `bird` action/profile adapters, blocks/mutes write helpers, remote block sync, batch blocklist imports, x-web mutations, authored/mentions/mention-thread sync including xurl recent-search and parent-walk fallback internals, conversation loading, home timeline, saved collection, DM live sync, profile hydration/resolution/affiliation/reply inspection, shared tweet lookup, research and whois report generation, follow graph live sync, link preview/index fetches, archive discovery/import subprocesses, avatar/URL caches, OpenAI/inbox scoring, scheduled bookmark sync locking/audit/launchd install, and the paced/concurrent `media fetch` archive-reuse and HTTP download pipeline.
+
+Public CLI and React call sites still expose plain `Promise` wrappers where that keeps the surrounding framework code simple. New core code should prefer `Effect` programs with typed error values, then add a Promise wrapper only at the outer CLI, route, or component boundary.
+
 ## Still In Progress
 
 - broader resumable live sync beyond the targeted paths already wired
@@ -91,6 +97,7 @@ If you need polished product-grade sync parity today, this is not there yet.
 ## Screens
 
 - `Home`: read and reply without fighting the main Twitter timeline
+- `What happened`: stream an AI digest for today, 24h, yesterday, or week
 - `Mentions`: work the reply queue with clean filters
 - `Likes` / `Bookmarks`: revisit saved posts from archive or live sync
 - `DMs`: triage by sender context, follower count, and influence
@@ -256,6 +263,16 @@ Start the app:
 birdclaw serve
 ```
 
+`birdclaw serve` binds the dev server to `127.0.0.1` and enables local
+loopback web APIs without a token. Remote access through a trusted private proxy
+requires `BIRDCLAW_ALLOW_REMOTE_WEB=1`. To require an app-level token too, set
+`BIRDCLAW_WEB_TOKEN` and send it as `x-birdclaw-token` or a `birdclaw_token`
+cookie.
+
+Use the Sync button in Home, Mentions, Likes, Bookmarks, or DMs to run the matching live sync from the web UI and then reload the local view. These controls are explicit because live reads can be slow, auth-dependent, or rate-limited.
+
+When running behind a trusted reverse proxy such as Tailscale Serve, add any extra proxy hostnames to `BIRDCLAW_ALLOWED_HOSTS`. The clawmac Tailscale hostname is allowed by default.
+
 First moderation pass:
 
 ```bash
@@ -359,6 +376,7 @@ Notes:
 - `bird` mode uses your local `bird` CLI and caches its mentions output into birdclaw's canonical store
 - filters still work in `xurl` mode; filtered payloads are rebuilt from the local canonical store after sync
 - `sync authored`, `sync mentions`, `sync mention-threads`, `sync likes`, `sync bookmarks`, and `sync timeline` store live results in the canonical local store; per-account authored/home/mention/like/bookmark membership is kept as edges so shared tweets do not clobber account ownership
+- the web UI has explicit Sync buttons for home timeline, mentions, likes, bookmarks, and DMs; they call the same sync paths and then reload the local DB-backed view
 
 ### Research bookmarks and threads
 
@@ -369,20 +387,37 @@ birdclaw research "codex" --limit 20 --thread-depth 10 --json
 birdclaw research --account acct_primary --out ~/research/codex.md
 ```
 
+### What happened today
+
+`birdclaw today` streams a local "what happened" digest from the SQLite store. It uses the OpenAI Responses API with `gpt-5.5`, medium reasoning, and priority service tier by default. Set `OPENAI_API_KEY`; override with `BIRDCLAW_AI_MODEL`, `BIRDCLAW_OPENAI_REASONING_EFFORT`, or `BIRDCLAW_OPENAI_SERVICE_TIER` when needed.
+
+```bash
+birdclaw today
+birdclaw digest 24h --refresh
+birdclaw digest week --json
+birdclaw digest --since 2026-05-16T00:00:00Z --until 2026-05-17T00:00:00Z
+birdclaw digest today --include-dms
+```
+
+The web UI exposes the same stream under `What happened`. DMs are excluded unless explicitly enabled. Final structured results are cached by the exact local context hash, model, reasoning effort, and service tier.
+
 ### Search and triage DMs
 
 ```bash
 pnpm cli search dms "prototype" --json
-pnpm cli search dms "layout" --min-followers 1000 --min-influence-score 120 --sort influence --json
+pnpm cli search dms "layout" --min-followers 1000 --min-influence-score 120 --sort followers --json
 pnpm cli search dms "blacksmith" --context 4 --resolve-profiles --expand-urls --no-xurl-fallback --json
 pnpm cli whois "blacksmith guy" --context 4 --no-xurl-fallback --json
 pnpm cli whois "github guy" --current-affiliation github --exclude-domain-only --no-xurl-fallback
 pnpm cli whois "blacksmith" --tweets --context 4 --no-xurl-fallback --json
 pnpm cli dms sync --limit 50 --refresh --json
+pnpm cli dms sync --mode auto --limit 50 --refresh --json
 pnpm cli dms list --refresh --limit 10 --json
-pnpm cli dms list --unreplied --min-followers 500 --min-influence-score 90 --sort influence --json
+pnpm cli dms list --unreplied --min-followers 500 --min-influence-score 90 --sort followers --json
 ```
 
+`dms sync/list --refresh` supports `--mode bird|xurl|auto`. `bird` is the default and required for message-request state; `xurl` imports recent OAuth2 DM events as accepted conversations, and `auto` falls back to bird when xurl cannot read them.
+
 `--resolve-profiles` fills archive-imported numeric DM profiles through the local
 cache first, then `bird`, then `xurl` unless `--no-xurl-fallback` is set.
 Resolved profiles keep bio, location, profile URL, verification type, structured
@@ -425,7 +460,7 @@ pnpm cli unban @amelia --account acct_primary --transport bird --json
 Notes:
 
 - `ban` / `unban` accept `--transport auto|bird|xurl`
-- `auto` tries `bird` first, then falls back to `xurl`, then `x-web` cookie-backed block/unblock when both fail
+- `auto` tries `bird` first, then falls back to `xurl`; unverified x-web writes are not used by moderation actions
 - forced `xurl` writes still verify through `bird status` before sqlite changes
 - Twitter still rejects pure OAuth2 block writes, so `auto` is the safe default for block/unblock
 - `blocks import` accepts newline-delimited blocklists with comments and markdown bullets
@@ -537,7 +572,22 @@ Configure stale-aware backup reads in `~/.birdclaw/config.json`:
 
 Read paths such as CLI search, inbox, API status/query, and web startup pull + merge from Git only when the last backup check is stale. Data-changing commands run a full backup sync afterward when this config is enabled. Set `BIRDCLAW_BACKUP_AUTO_SYNC=0` to disable that behavior for one process.
 
-### Scheduled Bookmark Sync
+### Scheduled Account and Bookmark Sync
+
+`birdclaw jobs sync-account` refreshes home timeline, mentions, mention threads, likes, bookmarks, and DMs for a selected account, then appends a per-step audit entry.
+
+```bash
+birdclaw --json jobs sync-account --account acct_openclaw --limit 100 --max-pages 3 --refresh --allow-bird-account
+tail -n 5 ~/.birdclaw/audit/account-sync.jsonl | jq .
+```
+
+On macOS, install the 30-minute LaunchAgent:
+
+```bash
+birdclaw --json jobs install-account-launchd --account acct_openclaw --program /opt/homebrew/bin/birdclaw --env-path ~/.config/bird/openclaw.env --allow-bird-account
+```
+
+Use `--env-path ~/.config/bird/openclaw.env` when launchd needs account-specific `bird` cookies. Pass `--allow-bird-account` only when those cookies match `--account`; otherwise Bird-backed timeline, mentions, and DM steps refuse non-default account writes to avoid misattribution. Use `--steps timeline,mentions,dms` to narrow the scheduled surfaces.
 
 `birdclaw jobs sync-bookmarks` refreshes live bookmarks and appends one JSONL audit entry per run. Each entry includes host, timestamps, duration, before/after bookmark counts, source transport, fetched count, backup sync result, and any error.
 
@@ -554,7 +604,7 @@ On macOS, install the 3-hour LaunchAgent after choosing the Birdclaw executable
 birdclaw --json jobs install-bookmarks-launchd --program /opt/homebrew/bin/birdclaw
 ```
 
-If the machine uses `bird` with browser cookies that are not available to launchd, write an export-only env file with mode `0600` and install with `--env-file ~/.config/bird/env.sh`. Birdclaw sources that file inside the scheduled process without storing the secrets in the plist.
+If the machine uses `bird` with browser cookies that are not available to launchd, write an export-only env file with mode `0600` and install with `--env-path ~/.config/bird/env.sh`. Birdclaw sources that file inside the scheduled process without storing the secrets in the plist.
 
 The LaunchAgent writes `~/Library/LaunchAgents/com.steipete.birdclaw.bookmarks-sync.plist`, runs at load, then every 10,800 seconds. It writes the audit log to `~/.birdclaw/audit/bookmarks-sync.jsonl` and stdout/stderr to `~/.birdclaw/logs/bookmarks-sync.*.log`. A lock file prevents overlapping runs and records an `already-running` skip when needed. The default job fetches up to 5 pages every 3 hours; pass `--all` if you want every retrievable page each run.
 

package/bin/birdclaw.mjs

@@ -1,30 +1,69 @@
 #!/usr/bin/env node
-import { spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 const require = createRequire(import.meta.url);
-const tsxCli = require.resolve("tsx/cli");
+const tsxLoader = pathToFileURL(require.resolve("tsx")).href;
 const birdclawCli = join(packageRoot, "src", "cli.ts");
 
-const result = spawnSync(
+const child = spawn(
 	process.execPath,
-	[tsxCli, birdclawCli, ...process.argv.slice(2)],
+	["--import", tsxLoader, birdclawCli, ...process.argv.slice(2)],
 	{
 		stdio: "inherit",
 		env: process.env,
+		detached: process.platform !== "win32",
 	},
 );
 
-if (result.error) {
-	console.error(result.error.message);
-	process.exit(1);
+const forwardedSignals = ["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT"];
+
+function removeSignalHandlers() {
+	for (const signal of forwardedSignals) {
+		process.removeListener(signal, forwardSignal);
+	}
+}
+
+function forwardSignal(signal) {
+	if (child.exitCode === null && child.signalCode === null) {
+		signalChild(signal);
+	}
+}
+
+function signalChild(signal) {
+	if (child.pid === undefined) {
+		return;
+	}
+	const targetPid = process.platform === "win32" ? child.pid : -child.pid;
+	try {
+		process.kill(targetPid, signal);
+	} catch (error) {
+		if (error?.code !== "ESRCH") {
+			throw error;
+		}
+	}
 }
 
-if (result.signal) {
-	process.kill(process.pid, result.signal);
+for (const signal of forwardedSignals) {
+	process.on(signal, forwardSignal);
 }
 
-process.exit(result.status ?? 0);
+child.on("error", (error) => {
+	removeSignalHandlers();
+	console.error(error.message);
+	process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+	removeSignalHandlers();
+
+	if (signal) {
+		process.kill(process.pid, signal);
+		return;
+	}
+
+	process.exit(code ?? 0);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "birdclaw",
-	"version": "0.5.0",
+	"version": "0.6.0",
 	"description": "Local Twitter memory in SQLite for archives, DMs, likes, bookmarks, and moderation",
 	"homepage": "https://github.com/steipete/birdclaw#readme",
 	"license": "MIT",
@@ -13,6 +13,7 @@
 	},
 	"files": [
 		"bin/",
+		"scripts/",
 		"src/",
 		"!src/**/*.test.ts",
 		"!src/**/*.test.tsx",
@@ -35,16 +36,16 @@
 		"access": "public"
 	},
 	"scripts": {
-		"dev": "vite dev --port 3000",
+		"dev": "BIRDCLAW_LOCAL_WEB=1 vite dev --host 127.0.0.1 --port 3000",
 		"build": "vite build",
 		"preview": "vite preview",
-		"test": "env -u NODE_OPTIONS node ./scripts/run-vitest.mjs run",
-		"coverage": "env -u NODE_OPTIONS node ./scripts/run-vitest.mjs run --coverage",
+		"test": "node ./scripts/run-vitest.mjs run",
+		"coverage": "node ./scripts/run-vitest.mjs run --coverage",
 		"e2e": "playwright test",
 		"typecheck": "tsgo --noEmit",
-		"format": "oxfmt --write src scripts playwright vite.config.ts vitest.config.ts playwright.config.ts",
-		"format:check": "oxfmt --check src scripts playwright vite.config.ts vitest.config.ts playwright.config.ts",
-		"lint": "oxlint --import-plugin --node-plugin --vitest-plugin --deny-warnings -A require-mock-type-parameters -A no-control-regex src scripts playwright vite.config.ts vitest.config.ts playwright.config.ts",
+		"format": "oxfmt --write bin src scripts playwright vite.config.ts vitest.config.ts playwright.config.ts",
+		"format:check": "oxfmt --check bin src scripts playwright vite.config.ts vitest.config.ts playwright.config.ts",
+		"lint": "oxlint --import-plugin --node-plugin --vitest-plugin --deny-warnings -A require-mock-type-parameters -A no-control-regex bin src scripts playwright vite.config.ts vitest.config.ts playwright.config.ts",
 		"check": "pnpm run format:check && pnpm run lint",
 		"perf:browser": "node ./scripts/browser-perf.mjs",
 		"cli": "tsx src/cli.ts",
@@ -62,6 +63,7 @@
 		"@tanstack/router-plugin": "^1.167.35",
 		"@vitejs/plugin-react": "^6.0.1",
 		"commander": "^14.0.3",
+		"effect": "^3.21.2",
 		"kysely": "^0.29.0",
 		"lucide-react": "^1.16.0",
 		"react": "^19.2.6",