Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
feat(wallpaper): serve macOS stills and imported images from a core cache
iceclatterWT7b7664dd404a
diff --git a/src/core/wallpaper.test.ts b/src/core/wallpaper.test.tsnew file mode 100644index 000000000..fc8f5118a--- /dev/null+++ b/src/core/wallpaper.test.ts@@ -0,0 +1,63 @@+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'+import { tmpdir } from 'node:os'+import path from 'node:path'+import { afterEach, describe, expect, it } from 'vitest'+import { cachedImagePath, importWallpaper, scanStills } from './wallpaper'++const HASH = 'a'.repeat(40)+let root: string | null = null+afterEach(() => {+ if (root) rmSync(root, { recursive: true, force: true })+ root = null+})++function put(rel: string, bytes: number): void {+ const p = path.join(root!, rel)+ mkdirSync(path.dirname(p), { recursive: true })+ writeFileSync(p, Buffer.alloc(bytes))+}++describe('scanStills', () => {+ it('finds >1MB stills incl. .wallpapers/*, skips thumbnails/placeholders, scenic first', async () => {+ root = mkdtempSync(path.join(tmpdir(), 'wp-'))+ put('Mac Blue.heic', 2_000_000)+ put('Sonoma.heic', 2_000_000)+ put('.wallpapers/Sonoma Horizon/Sonoma Horizon.heic', 2_000_000)+ put('.wallpapers/Sonoma Horizon/Sonoma Horizon.madesktop', 2_000_000)+ put('.thumbnails/Big.heic', 2_000_000)+ put('Tiny.heic', 1000)+ put('notes.txt', 2_000_000)+ const list = await scanStills(root)+ expect(list.map((s) => s.label)).toEqual(['Sonoma Horizon', 'Sonoma', 'Mac Blue'])+ expect(list[0].id).toBe('mac:.wallpapers/Sonoma Horizon/Sonoma Horizon.heic')+ })++ it('a missing root is an empty list', async () => {+ expect(await scanStills(path.join(tmpdir(), 'no-such-wallpaper-dir-xyz'))).toEqual([])+ })+})++describe('cachedImagePath (the read jail)', () => {+ const cache = path.resolve('/data/wallpapers')+ it('accepts only a hash-named direct child of the cache dir', () => {+ expect(cachedImagePath(path.join(cache, `${HASH}.jpg`), cache)).toBe(path.join(cache, `${HASH}.jpg`))+ expect(cachedImagePath(path.join(cache, `${HASH}-t.jpg`), cache)).not.toBeNull()+ })+ it.each([+ ['traversal', path.join(cache, '..', `${HASH}.jpg`)],+ ['nested', path.join(cache, 'x', `${HASH}.jpg`)],+ ['non-hash name', path.join(cache, 'id_rsa.jpg')],+ ['wrong extension', path.join(cache, `${HASH}.txt`)],+ ['windows-shaped', `C:\\Users\\me\\${HASH}.jpg`],+ ['empty', '']+ ])('refuses %s', (_label, p) => {+ expect(cachedImagePath(p, cache)).toBeNull()+ })+})++describe('importWallpaper', () => {+ it('refuses a file that is not a supported image', async () => {+ await expect(importWallpaper('/etc/passwd')).rejects.toThrow(/JPEG, PNG, WebP or HEIC/)+ await expect(importWallpaper(42)).rejects.toThrow()+ })+})diff --git a/src/core/wallpaper.ts b/src/core/wallpaper.tsnew file mode 100644index 000000000..53f94efd1--- /dev/null+++ b/src/core/wallpaper.ts@@ -0,0 +1,224 @@+import { execFile } from 'node:child_process'+import { createHash } from 'node:crypto'+import { copyFile, mkdir, readdir, readFile, stat, unlink } from 'node:fs/promises'+import path from 'node:path'+import { promisify } from 'node:util'+import { IPC } from '../shared/ipc'+import {+ normalizeWallpaper,+ type DesktopWallpaper,+ type WallpaperStill+} from '../shared/wallpaper'+import { renameAtomic, tempNameFor } from './fs-atomic'+import { platform } from './platform'++/**+ * Wallpaper files for the canvas background (Liquid Glass appearance). Core, so both shells serve+ * it: on the Server Edition (Linux) the stills list is simply empty and gradients need no files.+ *+ * Every file the renderer can get bytes for lives in ONE directory, `<userData>/wallpapers/`, under+ * a hash name this module minted. The renderer never names a path to read: a still is named by its+ * `mac:` id and re-resolved against a fresh scan, and an imported image's path must be a direct+ * child of the cache dir with a hash-shaped name (`cachedImagePath`). So a hand-edited+ * settings.json cannot aim `load` at anything else, and there is no traversal to reject because+ * no caller-supplied segment is ever joined.+ */++const run = promisify(execFile)++export const SYSTEM_WALLPAPER_DIR = '/System/Library/Desktop Pictures'+const SIPS = '/usr/bin/sips'+/** Real stills are several MB; the 356px `.madesktop` placeholders and thumbnails are not. */+const MIN_STILL_BYTES = 1_000_000+const STILL_EXT = /\.(heic|jpe?g|png)$/i+const IMPORT_EXT = /\.(heic|jpe?g|png|webp)$/i+/** Shown first, in this order: the scenic ones. */+const SCENIC_FIRST = ['Sonoma Horizon', 'Sonoma']+const FULL_PX = 3840+const THUMB_PX = 320+/** Refuse to ship anything bigger over IPC as a data: URL. */+const MAX_LOAD_BYTES = 25 * 1024 * 1024+const CACHED_NAME = /^[0-9a-f]{40}(-t)?\.(jpg|jpeg|png|webp)$/++export interface ScannedStill {+ id: string+ label: string+ path: string+}++export function wallpaperCacheDir(): string {+ return path.join(platform().userDataDir, 'wallpapers')+}++/**+ * The stock macOS stills under `root`, scenic first. Recurses into `.wallpapers/<name>/`, skips+ * `.thumbnails` and anything under 1 MB (which is what drops the `.madesktop` placeholders' tiny+ * siblings). A missing root is an empty list, which is the answer everywhere but macOS.+ */+export async function scanStills(root = SYSTEM_WALLPAPER_DIR, depth = 3): Promise<ScannedStill[]> {+ const found: ScannedStill[] = []+ const walk = async (dir: string, left: number): Promise<void> => {+ let entries+ try {+ entries = await readdir(dir, { withFileTypes: true })+ } catch {+ return+ }+ for (const e of entries) {+ const p = path.join(dir, e.name)+ if (e.isDirectory()) {+ if (e.name !== '.thumbnails' && left > 0) await walk(p, left - 1)+ } else if (e.isFile() && STILL_EXT.test(e.name)) {+ try {+ if ((await stat(p)).size < MIN_STILL_BYTES) continue+ } catch {+ continue+ }+ const rel = path.relative(root, p).split(path.sep).join('/')+ found.push({ id: `mac:${rel}`, label: e.name.replace(STILL_EXT, ''), path: p })+ }+ }+ }+ await walk(root, depth)+ const seen = new Set<string>()+ const rank = (label: string): number => {+ const i = SCENIC_FIRST.indexOf(label)+ return i === -1 ? SCENIC_FIRST.length : i+ }+ return found+ .sort((a, b) => rank(a.label) - rank(b.label) || a.label.localeCompare(b.label))+ .filter((s) => (seen.has(s.label) ? false : (seen.add(s.label), true)))+}++/** A cached file's name: stable per source file version and output size. */+async function cacheKey(src: string, variant: string): Promise<string> {+ const st = await stat(src)+ return createHash('sha1').update(`${src}\x00${st.mtimeMs}\x00${st.size}\x00${variant}`).digest('hex')+}++/** In-flight conversions, so two callers asking for the same file share one `sips`. */+const inflight = new Map<string, Promise<string>>()++/** Publish `produce(tmp)` at `target` through a unique temp, unless it is already there. */+function publishOnce(target: string, produce: (tmp: string) => Promise<void>): Promise<string> {+ const pending = inflight.get(target)+ if (pending) return pending+ const job = (async () => {+ try {+ await stat(target)+ return target+ } catch {+ // not cached yet+ }+ await mkdir(path.dirname(target), { recursive: true })+ const tmp = tempNameFor(target)+ try {+ await produce(tmp)+ await renameAtomic(tmp, target)+ } catch (err) {+ await unlink(tmp).catch(() => {})+ throw err+ }+ return target+ })().finally(() => inflight.delete(target))+ inflight.set(target, job)+ return job+}++/** HEIC/JPEG/PNG → JPEG no larger than `px` on its long edge, via macOS's built-in `sips`. */+async function convertWithSips(src: string, px: number, suffix: string): Promise<string> {+ const target = path.join(wallpaperCacheDir(), `${await cacheKey(src, `sips${px}`)}${suffix}.jpg`)+ return publishOnce(target, async (tmp) => {+ await run(SIPS, ['-s', 'format', 'jpeg', '-Z', String(px), src, '--out', tmp], {+ timeout: 60_000+ })+ })+}++let stillScan: Promise<ScannedStill[]> | null = null+function stills(): Promise<ScannedStill[]> {+ if (process.platform !== 'darwin') return Promise.resolve([])+ // One scan per app run: the system stills only change with an OS update.+ stillScan ??= scanStills().catch(() => [])+ return stillScan+}++async function toDataUrl(file: string): Promise<string | null> {+ try {+ const st = await stat(file)+ if (st.size > MAX_LOAD_BYTES) return null+ const ext = path.extname(file).slice(1).toLowerCase()+ const mime = ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : 'image/jpeg'+ return `data:${mime};base64,${(await readFile(file)).toString('base64')}`+ } catch {+ return null+ }+}++/**+ * The cache file an `image` wallpaper names, or null when the value names anything else. Only a+ * DIRECT child of the cache dir with a hash-shaped name qualifies — that is the whole jail.+ */+export function cachedImagePath(p: string, cacheDir = wallpaperCacheDir()): string | null {+ if (typeof p !== 'string' || p.length === 0) return null+ const resolved = path.resolve(p)+ if (path.dirname(resolved) !== path.resolve(cacheDir)) return null+ if (!CACHED_NAME.test(path.basename(resolved))) return null+ return resolved+}++export async function listStills(): Promise<WallpaperStill[]> {+ const list = await stills()+ const out: WallpaperStill[] = []+ // Sequential on purpose: a fresh cache runs one `sips` per still, and a dozen at once is a burst+ // of CPU for a grid of 320px thumbnails. Cached, each is a stat plus a small read.+ for (const s of list) {+ const thumb = await convertWithSips(s.path, THUMB_PX, '-t')+ .then(toDataUrl)+ .catch(() => null)+ out.push({ id: s.id, label: s.label, thumb })+ }+ return out+}++export async function loadWallpaper(value: unknown): Promise<string | null> {+ const w = normalizeWallpaper(value)+ if (w.kind === 'image') {+ const file = cachedImagePath(w.path)+ return file ? toDataUrl(file) : null+ }+ if (w.kind === 'preset' && w.id.startsWith('mac:')) {+ const still = (await stills()).find((s) => s.id === w.id)+ if (!still) return null+ return convertWithSips(still.path, FULL_PX, '')+ .then(toDataUrl)+ .catch(() => null)+ }+ return null+}++/**+ * Copy a picked image into the cache (HEIC is converted, since Chromium cannot decode it) and+ * return the value to store. The copy is what keeps the wallpaper when the original moves.+ */+export async function importWallpaper(sourcePath: unknown): Promise<DesktopWallpaper> {+ if (typeof sourcePath !== 'string' || !IMPORT_EXT.test(sourcePath)) {+ throw new Error('Choose a JPEG, PNG, WebP or HEIC image.')+ }+ const src = path.resolve(sourcePath)+ if (/\.heic$/i.test(src)) {+ if (process.platform !== 'darwin') throw new Error('HEIC images can only be converted on macOS.')+ return { kind: 'image', path: await convertWithSips(src, FULL_PX, '') }+ }+ const ext = path.extname(src).toLowerCase().replace('.jpeg', '.jpg')+ const target = path.join(wallpaperCacheDir(), `${await cacheKey(src, 'copy')}${ext}`)+ await publishOnce(target, (tmp) => copyFile(src, tmp))+ return { kind: 'image', path: target }+}++/** Wire onto the platform's RPC surface (Electron ipcMain / server WS-RPC alike). */+export function registerWallpaperIpc(): void {+ platform().handle(IPC.wallpaperListStills, () => listStills())+ platform().handle(IPC.wallpaperLoad, (value: unknown) => loadWallpaper(value))+ platform().handle(IPC.wallpaperImport, (sourcePath: unknown) => importWallpaper(sourcePath))+}diff --git a/src/main/index.ts b/src/main/index.tsindex 346328472..347401922 100644--- a/src/main/index.ts+++ b/src/main/index.ts@@ -268,6 +268,7 @@ import type { CodexCliCaps } from '../shared/types'import { registerGrokCliIpc } from '../core/grok-cli'import { refreshCodexIdentityCaps, registerCodexIdentityIpc } from '../core/codex-identity-caps'import { codexCliCaps, registerCodexCliIpc } from '../core/codex-cli'+import { registerWallpaperIpc } from '../core/wallpaper'import {bindCodexThreadIdentity,setCodexThreadIdentityAuthSecret,@@ -1400,6 +1401,7 @@ app.whenReady().then(async () => {// What THIS machine's codex accepts for `--ask-for-approval`. Lazy + memoized inside the probe,// so registering it costs nothing until the first Codex launch line asks.registerCodexCliIpc()+ registerWallpaperIpc()// Warm the `claude --version` probe now (it spawns a login shell + node, ~sub-second) so the// renderer's first `claude.cliCaps()` — awaited on the launch path of a cold-restored agent// node — resolves from cache instead of racing the probe into a conservative "no auto".diff --git a/src/preload/index.ts b/src/preload/index.tsindex 1008e8cdd..cd48f2837 100644--- a/src/preload/index.ts+++ b/src/preload/index.ts@@ -491,6 +491,11 @@ const api: NodeTerminalApi = {read: (q?: SessionMemoryQuery) => ipcRenderer.invoke(IPC.sessionMemory, q),host: (q?: SessionMemoryQuery) => ipcRenderer.invoke(IPC.sessionMemoryHost, q)},+ wallpaper: {+ listStills: () => ipcRenderer.invoke(IPC.wallpaperListStills),+ load: (w) => ipcRenderer.invoke(IPC.wallpaperLoad, w),+ importImage: (p) => ipcRenderer.invoke(IPC.wallpaperImport, p)+ },triggers: {arm: (projectId, nodeId, spec) => ipcRenderer.invoke(IPC.triggersArm, { projectId, nodeId, spec }),disarm: (projectId, nodeId) => ipcRenderer.invoke(IPC.triggersDisarm, { projectId, nodeId }),diff --git a/src/renderer/bridge/stubs.ts b/src/renderer/bridge/stubs.tsindex 2b4858a5a..bab26986d 100644--- a/src/renderer/bridge/stubs.ts+++ b/src/renderer/bridge/stubs.ts@@ -283,6 +283,15 @@ export function buildStubApi(): Omit<read: () => Promise.resolve({ ok: false, rows: [], mem: null }),host: () => Promise.resolve(null)},+ wallpaper: {+ // Superseded by the real WS-backed namespace in ws-bridge (registerWallpaperIpc runs in the+ // server shell). A RELAY tab keeps this: the wallpaper is this window's own appearance, and+ // the peer's disk has nothing to say about it. No stills, nothing to load (gradient presets+ // are pure CSS and need no bridge), and import refuses.+ listStills: () => Promise.resolve([]),+ load: () => Promise.resolve(null),+ importImage: U('wallpaper.importImage')+ },triggers: {// Superseded by the real WS-backed namespace in ws-bridge (startTriggerService registers the// handlers in the server shell). On the RELAY tab this stub stays in force and REFUSES: thediff --git a/src/renderer/bridge/ws-bridge.ts b/src/renderer/bridge/ws-bridge.tsindex 004b9f5c3..5f6781cee 100644--- a/src/renderer/bridge/ws-bridge.ts+++ b/src/renderer/bridge/ws-bridge.ts@@ -1,5 +1,6 @@import type { NormalizedAgentEvent } from '../../shared/agents/normalize'import { subscribeAgentReplay } from '../../shared/agent-replay-subscription'+import type { DesktopWallpaper, WallpaperStill } from '../../shared/wallpaper'// WebSocket bridge that reconstructs `window.nodeTerminal` in the browser (Server Edition).//// Under Electron the preload already defines `window.nodeTerminal`; this module only runs when@@ -852,6 +853,16 @@ export function buildSessionMemoryApi(client: RpcClient): Pick<NodeTerminalApi,}}+export function buildWallpaperApi(client: RpcClient): Pick<NodeTerminalApi, 'wallpaper'> {+ return {+ wallpaper: {+ listStills: () => client.request(IPC.wallpaperListStills) as Promise<WallpaperStill[]>,+ load: (w: DesktopWallpaper) => client.request(IPC.wallpaperLoad, w) as Promise<string | null>,+ importImage: (p: string) => client.request(IPC.wallpaperImport, p) as Promise<DesktopWallpaper>+ }+ }+}+/*** Build the `claude` namespace over an RpcClient. `cliCaps` is a REAL handler on the server* (`registerClaudeCliIpc` runs in the server shell too), so the browser resolves the very same@@ -1133,6 +1144,7 @@ export async function installWsBridge(): Promise<boolean> {...buildSpeechApi(client),...buildUsageApi(client),...buildSessionMemoryApi(client),+ ...buildWallpaperApi(client),...buildTriggersApi(client),...buildGitHubApi(client),...buildClaudeAccountsApi(client),diff --git a/src/server/handlers/index.ts b/src/server/handlers/index.tsindex 9235be14c..3e484099c 100644--- a/src/server/handlers/index.ts+++ b/src/server/handlers/index.ts@@ -10,6 +10,7 @@ import { claudeCliCaps, registerClaudeCliIpc } from '../../core/claude-cli'import { registerGrokCliIpc } from '../../core/grok-cli'import { registerCodexIdentityIpc } from '../../core/codex-identity-caps'import { registerCodexCliIpc } from '../../core/codex-cli'+import { registerWallpaperIpc } from '../../core/wallpaper'import { startUsageService } from '../../core/usage/usage-service'import { registerClaudeAccountsIpc } from '../../core/claude-accounts-service'import { codexUsageAccounts } from '../../core/codex-accounts-core'@@ -83,6 +84,7 @@ export function registerCoreHandlers(// hand a later codex a value it removed: exactly the "a stub compiles fine while doing nothing"// failure the three-surfaces rule warns about.registerCodexCliIpc()+ registerWallpaperIpc()void claudeCliCaps()// The answer is populated after server node identity is armed. Early browser callers wait fordiff --git a/src/shared/ipc.ts b/src/shared/ipc.tsindex f422db2b3..2c21a5e07 100644--- a/src/shared/ipc.ts+++ b/src/shared/ipc.ts@@ -287,6 +287,10 @@ export const IPC = {/** The scoped machine's RAM (available/total) — the cheap read behind the system-resource* pill. Safe to poll locally; NOT polled for an SSH scope. */sessionMemoryHost: 'session-memory:host',+ // Canvas wallpaper (core/wallpaper.ts): macOS stills, cached image reads, image import.+ wallpaperListStills: 'wallpaper:list-stills',+ wallpaperLoad: 'wallpaper:load',+ wallpaperImport: 'wallpaper:import',// Trigger nodes (issue #493): machine-local arm/disarm + the card's status/run-now.triggersArm: 'triggers:arm',triggersDisarm: 'triggers:disarm',diff --git a/src/shared/types.ts b/src/shared/types.tsindex a596ab5cd..aa1b7d90b 100644--- a/src/shared/types.ts+++ b/src/shared/types.ts@@ -3548,6 +3548,7 @@ export interface NodeTerminalApi {githubControl: import('./github-issues').GitHubControlApiusage: UsageApisessionMemory: SessionMemoryApi+ wallpaper: import('./wallpaper').WallpaperApitriggers: TriggersApicontext: ContextApicanvas: CanvasApi