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
// Polls the backend /v1/check feed from the main process (so the renderer CSP stays 'self').
// Successor to the static announcements.json: returns targeted messages for the announcement
// banner, one-time popups (`popups`), AND the mandatory-update policy for the Update Card. It also carries the anonymous
// install id (deviceId + os/arch/version), which the backend upserts into `devices` as a
// passive active-install counter — so the version distribution reflects EVERY install, not only
// the (few) that also opt into the telemetry ping. It also states the plan (`pro` | `free`) so a
// message can be aimed at paid or free users; the backend matches on it and does not store it.
// While the Settings → Privacy telemetry toggle is on it also carries the open-project count
// (`openProjects`, a bare number — never names, paths or hosts); the backend keeps the per-install
// maximum, the data the project-limit allowance is computed from. See `configureCheck`.
// In the other direction, the reply says whether the open-project limit is on (`limits`, present
// only while it is); that answer reaches core through `onCheckAnswer`, not through CheckResult.
// Nothing personal is sent and the client IP is never stored server-side; a hard opt-out is still
// DO_NOT_TRACK / NODETERM_TELEMETRY_DISABLED.
import { createHash } from 'node:crypto'
import { platform } from './platform'
import { getDeviceId } from './device-id'
import { isPremium } from './license'
import type { Announcement, PopupAnnouncement, UpdatePolicy } from '../shared/types'
const API_BASE = process.env.NODETERM_API_BASE || 'https://api.nodeterm.dev'
const CACHE_MS = 5 * 60 * 1000
export interface CheckResult {
messages: Announcement[]
/** One-time popups. The server sends them under their own key so that a build reading only
* `messages` (every one before this, and mobile) never receives one as a recurring banner. */
popups: PopupAnnouncement[]
update: UpdatePolicy
}
const EMPTY: CheckResult = { messages: [], popups: [], update: { minSupported: null, mandatory: false } }
// Same build + DO_NOT_TRACK gate as telemetry: dev never hits the prod API unless a local
// server is targeted explicitly. Deliberately NOT gated on the in-app telemetry toggle: this
// call always runs (content delivery + the anonymous install count), so an install still counts
// even if the user never opts into the detailed telemetry ping. The env kill-switches above are
// the hard off. The one field that IS gated on the toggle is `openProjects` (`openProjectsQuery`).
function allowed(): boolean {
if (process.env.DO_NOT_TRACK || process.env.NODETERM_TELEMETRY_DISABLED) return false
if (!platform().isPackaged && !process.env.NODETERM_API_BASE) return false
return true
}
function sanitize(data: unknown): CheckResult {
if (!data || typeof data !== 'object') return EMPTY
const d = data as Record<string, unknown>
const items = (raw: unknown): Record<string, unknown>[] =>
(Array.isArray(raw) ? raw : [])
.filter((m): m is Record<string, unknown> => !!m && typeof m === 'object')
.filter((m) => typeof m.id === 'string' && typeof m.title === 'string')
const toMessage = (m: Record<string, unknown>): Announcement => ({
id: m.id as string,
title: m.title as string,
body: typeof m.body === 'string' ? m.body : undefined,
url: typeof m.url === 'string' && /^https?:\/\//.test(m.url) ? m.url : undefined,
level: m.level === 'success' || m.level === 'warning' ? m.level : 'info'
})
const messages = items(d.messages).map(toMessage)
const popups = items(d.popups).map((m): PopupAnnouncement => {
const p: PopupAnnouncement = toMessage(m)
const label = typeof m.ctaLabel === 'string' ? m.ctaLabel.trim() : ''
if (label) p.ctaLabel = label.slice(0, CTA_LABEL_MAX)
// A closed set: an action this build does not know is no action, never a guess at one.
if (m.action === 'upgrade') p.action = 'upgrade'
if (typeof m.image === 'string' && IMAGE_HASH.test(m.image)) p.image = m.image
return p
})
const u = (d.update ?? {}) as Record<string, unknown>
const update: UpdatePolicy = {
minSupported: typeof u.minSupported === 'string' ? u.minSupported : null,
mandatory: u.mandatory === true
}
// Optional release highlights for the update card. Both or neither: notes without the version
// they describe could be pinned to the wrong card.
if (typeof u.notes === 'string' && u.notes.trim() && typeof u.latestVersion === 'string' && u.latestVersion) {
update.notes = u.notes.slice(0, NOTES_MAX)
update.latestVersion = u.latestVersion.slice(0, 64)
}
return { messages, popups, update }
}
const NOTES_MAX = 16 * 1024
const CTA_LABEL_MAX = 40
const IMAGE_HASH = /^[0-9a-f]{64}$/
/** The largest popup picture this build takes; the admin console refuses more on upload. */
const IMAGE_MAX_BYTES = 2 * 1024 * 1024
const IMAGE_TIMEOUT_MS = 20_000
/** Test seam: the sanitizer is the whole contract with the feed's shape. */
export const sanitizeCheckForTest = sanitize
/** What one successful read of the feed said about the open-project limit. The server adds
* `limits: { projects: { free, epoch } }` exactly while the limit is on and leaves the key absent
* otherwise, so `off` is the ABSENCE of the key — but only in a reply shaped like a check reply
* (`messages` array + `update` object, which every 2xx from the route carries). `unknown` = anything
* else: a malformed `limits`, or JSON that is not a check reply at all (`{}`, `{"status":"ok"}`, a
* proxy's JSON page behind a followed redirect). It must change nothing: the latch reads `off` as
* "clear", and a reply that did not come from the route must never be able to clear it. */
export type LimitsAnswer = { kind: 'on'; free: number; epoch: number } | { kind: 'off' } | { kind: 'unknown' }
const FREE_MIN = 1
const FREE_MAX = 1000
const isRecord = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v)
// Kept apart from `sanitize`, whose CheckResult its existing callers (banner, update card) depend on
// exactly — and stricter than it: `sanitize` reads any JSON as an empty feed, which is harmless for a
// banner, while here only a check-shaped reply says anything (see LimitsAnswer). A fresh object every
// call, so no answer aliases a module constant a listener could mutate.
function sanitizeLimits(data: unknown): LimitsAnswer {
if (!isRecord(data) || !Array.isArray(data.messages) || !isRecord(data.update)) return { kind: 'unknown' }
if (!Object.hasOwn(data, 'limits')) return { kind: 'off' }
const projects = isRecord(data.limits) ? data.limits.projects : undefined
if (!isRecord(projects)) return { kind: 'unknown' }
const { free, epoch } = projects
if (typeof free !== 'number' || !Number.isInteger(free) || free < FREE_MIN || free > FREE_MAX) {
return { kind: 'unknown' }
}
// Safe integers only: the epoch is compared for equality against a stored token's.
if (typeof epoch !== 'number' || !Number.isSafeInteger(epoch) || epoch < 1) return { kind: 'unknown' }
return { kind: 'on', free, epoch }
}
/** Test seam: the limits half of the feed's shape. */
export const sanitizeLimitsForTest = sanitizeLimits
type AnswerListener = (a: LimitsAnswer) => void
const answerListeners = new Set<AnswerListener>()
/** Subscribe to the server's limit answer. Fired only after a 2xx response whose body parsed as
* JSON, once per network read — never for a cache hit, a failed read or its fallback, because the
* project-limit latch reads `off` as "clear" and a blocked network must not be able to say it.
* Returns the unsubscribe. */
export function onCheckAnswer(listener: AnswerListener): () => void {
answerListeners.add(listener)
return () => {
answerListeners.delete(listener)
}
}
function emitAnswer(answer: LimitsAnswer): void {
// A copy, so a listener that unsubscribes (or subscribes) mid-emit does not skew this round.
for (const listener of [...answerListeners]) {
try {
listener(answer)
} catch (err) {
// A listener's bug is its own: fetchCheck's callers still get the answer they asked for.
console.warn('[check] answer listener failed', err)
}
}
}
export interface CheckDeps {
/** Open projects in the workspace index (`WorkspaceStore.openProjectCount`); undefined = unknown
* (index not loaded yet, or never saved in v3 form), and an unknown count is never sent. */
openProjects: () => number | undefined
/** `settings.telemetryEnabled` — the count is sent only while it is exactly true. */
telemetryEnabled: () => boolean
}
// Set once by the shell at boot; read per call, so a toggle flip or a project open/close takes
// effect on the next uncached fetch. Never configured = the count is never sent.
let deps: CheckDeps | null = null
export function configureCheck(next: CheckDeps): void {
deps = next
}
/** The open-project count for one read: `param` is `openProjects=<n>` only when configured, the
* telemetry toggle is on and `n` is a non-negative integer (nothing else is added); `owed` = the
* count was wanted (toggle on) but is not known yet — the index still loading at boot. Never
* throws: a toggle that cannot be read is off, a count that cannot be read is unknown. */
function openProjectsQuery(): { param: Record<string, string>; owed: boolean } {
let wanted = false
try {
wanted = !!deps && deps.telemetryEnabled() === true
} catch {
wanted = false
}
if (!deps || !wanted) return { param: {}, owed: false }
let n: number | undefined
try {
n = deps.openProjects()
} catch {
n = undefined
}
return typeof n === 'number' && Number.isInteger(n) && n >= 0
? { param: { openProjects: String(n) }, owed: false }
: { param: {}, owed: true }
}
type Plan = 'pro' | 'free'
// The plan the response was fetched for. The backend aims messages at paid or free users by the
// plan WE state (the feed is anonymous — it cannot look a device up), so an answer belongs to the
// plan it was asked with: a purchase or a lapse must not be served the other plan's messages.
// `countOwed`: the read went out while the count was wanted but unknown (see openProjectsQuery).
let cache: { at: number; plan: Plan; data: CheckResult; countOwed: boolean } | null = null
export async function fetchCheck(): Promise<CheckResult> {
if (!allowed()) return EMPTY
const now = Date.now()
// Offline token verify, so it is cheap to read per call and already right at boot.
const plan: Plan = isPremium() ? 'pro' : 'free'
const count = openProjectsQuery()
// A reply fetched while the count was owed does not stand in for a read that can carry it: at boot
// the first reads (this module's own, the banner's, the update card's) can all run before the
// workspace index is loaded, and served from the cache that count-less reply would keep the count
// off the wire until the 6 h tick — for a session shorter than that, for good. So once the count
// is known this read refetches, and its reply replaces the cache. A reply that carried the count,
// or was fetched with the toggle off, is reused exactly as before.
const countNowKnown = cache?.countOwed === true && Object.hasOwn(count.param, 'openProjects')
if (cache && cache.plan === plan && now - cache.at < CACHE_MS && !countNowKnown) return cache.data
// A failed read keeps the last good answer, except the messages and popups it fetched for another
// plan. The update policy does not depend on the plan, so it survives.
const fallback = (): CheckResult =>
!cache ? EMPTY : cache.plan === plan ? cache.data : { messages: [], popups: [], update: cache.data.update }
try {
const q = new URLSearchParams({
deviceId: getDeviceId(),
version: platform().appVersion,
os: process.platform,
arch: process.arch,
channel: 'stable',
plan,
...count.param
})
const ctrl = new AbortController()
const t = setTimeout(() => ctrl.abort(), 8000)
const res = await fetch(`${API_BASE}/v1/check?${q.toString()}`, {
signal: ctrl.signal,
cache: 'no-cache'
}).finally(() => clearTimeout(t))
if (!res.ok) return fallback()
// A body that does not parse (a captive portal's HTML page) throws into the fallback below.
const body: unknown = await res.json()
const data = sanitize(body)
cache = { at: now, plan, data, countOwed: count.owed }
// The one place an answer is given: a 2xx whose body parsed as JSON. Cached first, so a
// listener that reads the feed again is served from the cache rather than re-fetching.
emitAnswer(sanitizeLimits(body))
return data
} catch {
return fallback()
}
}
/** The type the bytes say. A closed set, so nothing else can reach a `data:` URL. */
function imageMime(b: Uint8Array): string | null {
const starts = (at: number, sig: number[]): boolean => sig.every((x, i) => b[at + i] === x)
if (starts(0, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) return 'image/png'
if (starts(0, [0xff, 0xd8, 0xff])) return 'image/jpeg'
if (starts(0, [0x52, 0x49, 0x46, 0x46]) && starts(8, [0x57, 0x45, 0x42, 0x50])) return 'image/webp'
return null
}
/** The body up to `max` bytes, or null past it. Read in chunks: `content-length` is only a claim. */
async function readCapped(body: ReadableStream<Uint8Array>, max: number): Promise<Buffer | null> {
const reader = body.getReader()
const chunks: Uint8Array[] = []
let size = 0
for (;;) {
const { done, value } = await reader.read()
if (done) return Buffer.concat(chunks)
size += value.length
if (size > max) {
await reader.cancel()
return null
}
chunks.push(value)
}
}
let lastImage: { sha256: string; url: string } | null = null
/**
* A popup's picture as a `data:` URL (the renderer CSP's `img-src` takes no network source), or null
* when it cannot be had. The feed only ever names a hash, never a URL, so it cannot point this at
* another host; the bytes must match that hash and be an image. No install id goes with it.
* The latest is kept: a popup waiting its turn asks again every few minutes.
*/
export async function fetchPopupImage(sha256: string): Promise<string | null> {
if (!IMAGE_HASH.test(sha256) || !allowed()) return null
if (lastImage?.sha256 === sha256) return lastImage.url
const ctrl = new AbortController()
const t = setTimeout(() => ctrl.abort(), IMAGE_TIMEOUT_MS)
try {
const res = await fetch(`${API_BASE}/v1/message-image/${sha256}`, { signal: ctrl.signal, redirect: 'error' })
if (!res.ok || !res.body) return null
const bytes = await readCapped(res.body, IMAGE_MAX_BYTES)
if (!bytes || createHash('sha256').update(bytes).digest('hex') !== sha256) return null
const mime = imageMime(bytes)
if (!mime) return null
lastImage = { sha256, url: `data:${mime};base64,${bytes.toString('base64')}` }
return lastImage.url
} catch {
return null
} finally {
clearTimeout(t)
}
}