@huynle/hub 0.6.0 → 0.7.1

package/src/central/cluster/view.ts

@@ -0,0 +1,232 @@
+// The cluster view (design §9, decision vkxkqiuf §5): how every pod sees the connections other pods hold.
+// Each pod's Registry and NodeRegistry are the single writers of its own connections and export a slice per tenant
+// (registry: connections and what they report, status boards, pending permissions and forms, presence, running
+// turns; nodes: the tenant's nodes). This pod publishes its slices
+//   - to the Catalog: hash of the user, session VIEW_SESSION, one report per pod (connID = podID) with a TTL;
+//   - as deltas on the Bus (VIEW_TOPIC: {pod, user, slice | null}), shortly after a change and again every
+//     heartbeat (which also refreshes the Catalog TTL);
+// and mirrors the other pods' slices into its Registry and NodeRegistry (setRemote), so their synchronous reads
+// cover the whole cluster. The mirror is rebuilt from the Catalog at start and on resync() (e.g. after a Bus
+// reconnect lost deltas). A pod that stops removes its slices; a pod that dies stops refreshing them: the other pods
+// drop a slice not refreshed within the TTL, and the Catalog filters it out on read.
+import { realTimers } from "../backend/memory-bus"
+import type { Bus, Catalog, Clock, Timers, Unsubscribe } from "../backend/types"
+import type { NodeRegistry, NodeSlice } from "../nodes"
+import type { Registry, RegistrySlice } from "../registry"
+
+export const VIEW_TOPIC = "cluster.view"
+/** The Catalog session id the slices are reported under (never a real session id: those start with ses). */
+export const VIEW_SESSION = "_view"
+export const VIEW_HEARTBEAT_MS = 15_000
+export const VIEW_TTL_MS = 45_000
+/** Changes within this window go out together. */
+export const VIEW_PUBLISH_DELAY_MS = 50
+
+/** One pod's state of one tenant. */
+export interface ViewSlice {
+  readonly registry?: RegistrySlice
+  readonly nodes?: NodeSlice
+}
+
+interface ViewMessage {
+  readonly pod: string
+  readonly user: string
+  readonly slice: ViewSlice | null
+}
+
+type Mirrored<T extends Registry | NodeRegistry> = Pick<T, "onLocalChange" | "clusterTenants" | "clusterSlice" | "setRemote">
+
+export interface ClusterViewOptions {
+  readonly catalog: Catalog
+  readonly bus: Bus
+  /** This pod (HUB_POD_ID). */
+  readonly podID: string
+  readonly registry: Mirrored<Registry>
+  readonly nodes: Mirrored<NodeRegistry>
+  /** The users whose Catalog entries a rebuild reads. */
+  readonly users: () => readonly string[] | Promise<readonly string[]>
+  readonly now?: Clock
+  readonly timers?: Timers
+  readonly heartbeatMs?: number
+  readonly ttlMs?: number
+  readonly publishDelayMs?: number
+  readonly onError?: (error: unknown) => void
+}
+
+/** Tenants that are not users (a machine without an owner) are never published. */
+const publishable = (tenant: string | undefined): tenant is string => tenant !== undefined && tenant !== "" && !tenant.startsWith("?")
+
+export class ClusterView {
+  readonly podID: string
+  private readonly options: ClusterViewOptions
+  private readonly now: Clock
+  private readonly timers: Timers
+  private readonly heartbeatMs: number
+  private readonly ttlMs: number
+  private readonly publishDelayMs: number
+  private readonly onError: (error: unknown) => void
+  /** Tenants whose slice changed since the last flush; `all`: every tenant. */
+  private dirty = new Set<string>()
+  private dirtyAll = false
+  private flushTimer: unknown
+  private heartbeatTimer: unknown
+  /** What this pod published last per user (JSON), to skip unchanged slices between heartbeats. */
+  private readonly sent = new Map<string, string>()
+  /** Other pods' slices applied here: pod → user → when last received (this pod's clock). */
+  private readonly received = new Map<string, Map<string, number>>()
+  /** Serialises flushes, rebuilds and stop. */
+  private queue: Promise<void> = Promise.resolve()
+  private readonly offs: Array<() => void> = []
+  private unsubscribe?: Unsubscribe
+  private running = false
+
+  constructor(options: ClusterViewOptions) {
+    this.options = options
+    this.podID = options.podID
+    this.now = options.now ?? Date.now
+    this.timers = options.timers ?? realTimers
+    this.heartbeatMs = options.heartbeatMs ?? VIEW_HEARTBEAT_MS
+    this.ttlMs = options.ttlMs ?? VIEW_TTL_MS
+    this.publishDelayMs = options.publishDelayMs ?? VIEW_PUBLISH_DELAY_MS
+    this.onError = options.onError ?? ((error) => console.error(`[hub] cluster view: ${error instanceof Error ? error.message : String(error)}`))
+  }
+
+  /** Listens for deltas, rebuilds the mirror from the Catalog, publishes this pod's slices and starts the heartbeat. */
+  async start(): Promise<void> {
+    if (this.running) return
+    this.running = true
+    const mark = (tenant: string | undefined) => this.mark(tenant)
+    this.offs.push(this.options.registry.onLocalChange(mark), this.options.nodes.onLocalChange(mark))
+    this.unsubscribe = await this.options.bus.subscribe(VIEW_TOPIC, (message) => this.receive(message as ViewMessage))
+    await this.resync()
+    this.dirtyAll = true
+    await this.flush()
+    this.arm()
+  }
+
+  /** Stops publishing and listening, and removes this pod's slices from the Catalog and the other pods. */
+  async stop(): Promise<void> {
+    if (!this.running) return
+    this.running = false
+    for (const off of this.offs.splice(0)) off()
+    for (const timer of [this.flushTimer, this.heartbeatTimer]) if (timer !== undefined) this.timers.clear(timer)
+    this.flushTimer = this.heartbeatTimer = undefined
+    const unsubscribe = this.unsubscribe
+    this.unsubscribe = undefined
+    await this.enqueue(async () => {
+      await unsubscribe?.()
+      const users = [...this.sent.keys()]
+      this.sent.clear()
+      await Promise.allSettled(users.map((user) => this.withdraw(user)))
+    })
+  }
+
+  /** How many users this pod currently publishes slices for. */
+  published(): number {
+    return this.sent.size
+  }
+
+  /** Reads every other pod's slices from the Catalog and replaces the mirror with them. */
+  resync(): Promise<void> {
+    return this.enqueue(async () => {
+      const users = await this.options.users()
+      const seen = new Set<string>()
+      for (const user of users) {
+        for (const entry of await this.options.catalog.entries(user)) {
+          if (entry.sessionID !== VIEW_SESSION || entry.connID === this.podID) continue
+          seen.add(`${entry.connID}\u0000${user}`)
+          this.apply(entry.connID, user, entry.value as ViewSlice)
+        }
+      }
+      for (const [pod, slices] of this.received) for (const user of slices.keys()) if (!seen.has(`${pod}\u0000${user}`)) this.apply(pod, user, null)
+    })
+  }
+
+  /** A local change of `tenant` (undefined: any): published after the publish delay. */
+  private mark(tenant: string | undefined): void {
+    if (!this.running) return
+    if (tenant === undefined) this.dirtyAll = true
+    else if (publishable(tenant)) this.dirty.add(tenant)
+    else return
+    if (this.flushTimer !== undefined) return
+    this.flushTimer = this.timers.set(() => {
+      this.flushTimer = undefined
+      void this.flush()
+    }, this.publishDelayMs)
+  }
+
+  /** Publishes the slices of the dirty tenants (all, after a heartbeat); `force` republishes unchanged ones too. */
+  private flush(force = false): Promise<void> {
+    return this.enqueue(async () => {
+      if (!this.running) return
+      const { registry, nodes } = this.options
+      const tenants = this.dirtyAll
+        ? new Set([...registry.clusterTenants(), ...nodes.clusterTenants(), ...this.sent.keys()])
+        : new Set(this.dirty)
+      this.dirty = new Set()
+      this.dirtyAll = false
+      for (const user of tenants) {
+        if (!publishable(user)) continue
+        const r = registry.clusterSlice(user)
+        const n = nodes.clusterSlice(user)
+        try {
+          if (!r && !n) {
+            if (this.sent.delete(user)) await this.withdraw(user)
+            continue
+          }
+          const slice: ViewSlice = { ...(r ? { registry: r } : {}), ...(n ? { nodes: n } : {}) }
+          const json = JSON.stringify(slice)
+          if (!force && this.sent.get(user) === json) continue
+          this.sent.set(user, json)
+          await this.options.catalog.set(user, VIEW_SESSION, this.podID, slice as Record<string, unknown>, { ttlMs: this.ttlMs })
+          await this.options.bus.publish(VIEW_TOPIC, { pod: this.podID, user, slice } satisfies ViewMessage)
+        } catch (error) {
+          // The next heartbeat publishes it again.
+          this.sent.delete(user)
+          this.onError(error)
+        }
+      }
+    })
+  }
+
+  private async withdraw(user: string): Promise<void> {
+    await this.options.catalog.delete(user, VIEW_SESSION, this.podID)
+    await this.options.bus.publish(VIEW_TOPIC, { pod: this.podID, user, slice: null } satisfies ViewMessage)
+  }
+
+  private receive(message: ViewMessage): void {
+    if (!this.running || typeof message?.pod !== "string" || typeof message.user !== "string" || message.pod === this.podID) return
+    this.apply(message.pod, message.user, message.slice ?? null)
+  }
+
+  /** Applies (or, null, removes) another pod's slice of a user. */
+  private apply(pod: string, user: string, slice: ViewSlice | null): void {
+    let users = this.received.get(pod)
+    if (slice) {
+      if (!users) this.received.set(pod, (users = new Map()))
+      users.set(user, this.now())
+    } else if (users?.delete(user) && !users.size) this.received.delete(pod)
+    this.options.nodes.setRemote(pod, user, slice?.nodes)
+    this.options.registry.setRemote(pod, user, slice?.registry)
+  }
+
+  /** Every heartbeat: republish this pod's slices (refreshing their TTL) and drop the ones other pods stopped refreshing. */
+  private arm(): void {
+    this.heartbeatTimer = this.timers.set(() => {
+      this.heartbeatTimer = undefined
+      if (!this.running) return
+      const t = this.now()
+      for (const [pod, users] of [...this.received]) for (const [user, at] of [...users]) if (t - at > this.ttlMs) this.apply(pod, user, null)
+      this.dirtyAll = true
+      void this.flush(true).finally(() => {
+        if (this.running) this.arm()
+      })
+    }, this.heartbeatMs)
+  }
+
+  private enqueue(task: () => Promise<void>): Promise<void> {
+    const run = this.queue.then(task, task)
+    this.queue = run.catch((error) => this.onError(error))
+    return run
+  }
+}

package/src/central/config.ts

@@ -2,10 +2,11 @@
 // optional hub config file (~/.config/hub/hub.json or $HUB_CONFIG) over built-in defaults. The file's speech
 // settings sit between the phone's saved settings and the env (see speech/settings.ts).
 import { existsSync, readFileSync, statSync } from "node:fs"
-import { homedir } from "node:os"
+import { homedir, hostname } from "node:os"
 import path from "node:path"
 import { hubEnv } from "../env"
 import { isLoopbackHost } from "../loopback"
+import { formatPattern, parsePattern } from "./agent/policy"
 import { APP_DIR, configBase, legacyPaths, migrateFirst, stateBase } from "../migrate"
 import { updateSpeech, type StoredSpeech } from "./speech/settings"
 
@@ -59,6 +60,57 @@ export interface CentralConfig {
   /** Speech settings from hub.json (below the phone's saved settings, above the env). */
   readonly speech?: StoredSpeech
   readonly auth: AuthConfig
+  /** hub.json `agents.never`: permission patterns no agent may ever approve, for every user (design §5, §7). */
+  readonly agentsNever: readonly string[]
+  /** hub.json `agents.launches`: per-user launch caps, only those set (placement fills in its defaults). */
+  readonly launchCaps?: HubLaunches
+  /** hub.json `agents.webhooks.allowPrivate`: webhooks may target http, loopback, private and local hosts (admin opt-in). */
+  readonly webhooksAllowPrivate?: true
+  /** Cluster mode (design §9): set only when HUB_DATABASE_URL and HUB_VALKEY_URL (or hub.json cluster) are. */
+  readonly cluster?: ClusterConfig
+}
+
+/**
+ * Cluster mode: shared state in Postgres, cross-pod messages and short-lived data in Valkey. The URLs hold
+ * credentials: they are non-enumerable (never serialized or printed with the config) and never put in messages.
+ */
+export interface ClusterConfig {
+  /** This pod's id (HUB_POD_ID, default the hostname): RPC topics and leases name it. */
+  readonly podID: string
+  /** postgres:// or postgresql:// (non-enumerable). */
+  readonly databaseURL: string
+  /** redis://, rediss://, valkey:// or valkeys:// (non-enumerable). */
+  readonly valkeyURL: string
+}
+
+/** hub.json `cluster` (env HUB_DATABASE_URL / HUB_VALKEY_URL win). */
+export interface HubCluster {
+  readonly database?: string
+  readonly valkey?: string
+}
+
+/** hub.json `agents.launches`: per-user launch caps (design §6.2, §7). */
+export interface HubLaunches {
+  /** Launches waiting to be placed. */
+  readonly maxQueued?: number
+  /** Launches placed and not ended (placing, provisioning, running). */
+  readonly maxActive?: number
+  /** New launches per clock hour. */
+  readonly perHour?: number
+}
+
+/** hub.json `agents`, validated. */
+export interface HubAgents {
+  /** Normalised `action[:glob]` patterns (see agent/policy.ts), duplicates dropped. */
+  readonly never?: readonly string[]
+  readonly launches?: HubLaunches
+  readonly webhooks?: HubWebhooks
+}
+
+/** hub.json `agents.webhooks` (decision znbg8xa5 #8). */
+export interface HubWebhooks {
+  /** Lets webhook URLs use http and private or local targets (self-hosted receivers); off by default (SSRF). */
+  readonly allowPrivate?: boolean
 }
 
 /** hub.json, validated. */
@@ -69,11 +121,18 @@ export interface HubFile {
   readonly stateDir?: string
   readonly speech?: StoredSpeech
   readonly auth?: HubAuth
+  readonly agents?: HubAgents
+  readonly cluster?: HubCluster
 }
 
 type Env = Readonly<Record<string, string | undefined>>
 
-const HUB_KEYS = new Set(["host", "port", "publicURL", "stateDir", "speech", "auth"])
+const HUB_KEYS = new Set(["host", "port", "publicURL", "stateDir", "speech", "auth", "agents", "cluster"])
+const CLUSTER_KEYS = ["database", "valkey"] as const
+const AGENTS_KEYS = new Set(["never", "launches", "webhooks"])
+const WEBHOOK_KEYS = new Set(["allowPrivate"])
+const LAUNCH_CAP_KEYS = ["maxQueued", "maxActive", "perHour"] as const
+const LAUNCH_CAP_MAX = 100_000
 const AUTH_KEYS = new Set(["mode", "issuer", "clientId", "clientSecret", "allowed", "admins"])
 const EMAIL = /^[^\s@,]+@[^\s@,]+\.[^\s@,]+$/
 const DOMAIN = /^@[^\s@,]+\.[^\s@,]+$/
@@ -161,6 +220,8 @@ export function readHubFile(file: string, home: string = homedir()): { file?: Hu
     hub.stateDir = expandHome((raw.stateDir as string).trim(), home)
   }
   if (raw.auth !== undefined) hub.auth = readHubAuth(raw.auth, file, warnings, fail)
+  if (raw.agents !== undefined) hub.agents = readHubAgents(raw.agents, file, warnings, fail)
+  if (raw.cluster !== undefined) hub.cluster = readHubCluster(raw.cluster, file, warnings, fail)
   if (raw.speech !== undefined) {
     if (!isObj(raw.speech)) fail("speech must be an object with stt and/or tts")
     const speech = { ...(raw.speech as Record<string, unknown>) }
@@ -206,6 +267,86 @@ function readHubAuth(raw: unknown, file: string, warnings: string[], fail: (mess
   return auth
 }
 
+/** hub.json `cluster`. Values are never echoed; URLs with a password are dropped from a file others can read. */
+function readHubCluster(raw: unknown, file: string, warnings: string[], fail: (message: string) => never): HubCluster {
+  if (!isObj(raw)) fail("cluster must be an object with database and valkey URLs")
+  const input = raw as Record<string, unknown>
+  for (const key of Object.keys(input)) {
+    if (!(CLUSTER_KEYS as readonly string[]).includes(key)) warnings.push(`${file}: unknown key "cluster.${key}" ignored`)
+  }
+  const shared = (statSync(file).mode & 0o044) !== 0
+  const cluster: { -readonly [K in keyof HubCluster]: HubCluster[K] } = {}
+  for (const key of CLUSTER_KEYS) {
+    const value = input[key]
+    if (value === undefined) continue
+    if (typeof value !== "string" || !value.trim()) fail(`cluster.${key} must be a non-empty URL string`)
+    const url = (value as string).trim()
+    if (shared && hasPassword(url)) {
+      warnings.push(`${file} is readable by other users, so its cluster.${key} is ignored (it holds a password). Fix it with: chmod 600 ${file}`)
+      continue
+    }
+    cluster[key] = url
+  }
+  return cluster
+}
+
+function hasPassword(url: string): boolean {
+  try {
+    return new URL(url).password !== ""
+  } catch {
+    // Unparseable: assume the worst; centralConfig rejects it anyway.
+    return true
+  }
+}
+
+function readHubAgents(raw: unknown, file: string, warnings: string[], fail: (message: string) => never): HubAgents {
+  if (!isObj(raw)) fail("agents must be an object")
+  const input = raw as Record<string, unknown>
+  for (const key of Object.keys(input)) if (!AGENTS_KEYS.has(key)) warnings.push(`${file}: unknown key "agents.${key}" ignored`)
+  const launches = input.launches === undefined ? undefined : readHubLaunches(input.launches, file, warnings, fail)
+  const never = input.never === undefined ? undefined : readNever(input.never, fail)
+  const webhooks = input.webhooks === undefined ? undefined : readHubWebhooks(input.webhooks, file, warnings, fail)
+  return { ...(never ? { never } : {}), ...(launches ? { launches } : {}), ...(webhooks ? { webhooks } : {}) }
+}
+
+function readHubWebhooks(raw: unknown, file: string, warnings: string[], fail: (message: string) => never): HubWebhooks {
+  if (!isObj(raw)) fail("agents.webhooks must be an object")
+  const input = raw as Record<string, unknown>
+  for (const key of Object.keys(input)) if (!WEBHOOK_KEYS.has(key)) warnings.push(`${file}: unknown key "agents.webhooks.${key}" ignored`)
+  if (input.allowPrivate !== undefined && typeof input.allowPrivate !== "boolean") fail("agents.webhooks.allowPrivate must be true or false")
+  return input.allowPrivate === undefined ? {} : { allowPrivate: input.allowPrivate as boolean }
+}
+
+function readHubLaunches(raw: unknown, file: string, warnings: string[], fail: (message: string) => never): HubLaunches {
+  if (!isObj(raw)) fail("agents.launches must be an object")
+  const input = raw as Record<string, unknown>
+  const caps: Record<string, number> = {}
+  for (const key of Object.keys(input)) {
+    if (!(LAUNCH_CAP_KEYS as readonly string[]).includes(key)) {
+      warnings.push(`${file}: unknown key "agents.launches.${key}" ignored`)
+      continue
+    }
+    const value = input[key]
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > LAUNCH_CAP_MAX) {
+      fail(`agents.launches.${key} must be a whole number from 1 to ${LAUNCH_CAP_MAX}`)
+    }
+    caps[key] = value as number
+  }
+  return caps
+}
+
+function readNever(raw: unknown, fail: (message: string) => never): string[] {
+  if (!Array.isArray(raw)) fail('agents.never must be a list of patterns ("action" or "action:glob")')
+  const never: string[] = []
+  for (const item of raw as unknown[]) {
+    const pattern = typeof item === "string" ? parsePattern(item) : undefined
+    if (!pattern) fail(`agents.never: ${JSON.stringify(item)} is not a pattern ("action" or "action:glob")`)
+    const text = formatPattern(pattern!)
+    if (!never.includes(text)) never.push(text)
+  }
+  return never
+}
+
 /** Validates the OIDC issuer: https, or plain http on loopback when the dev flag is set. No trailing slash. */
 function issuerURL(raw: string, insecure: boolean): string {
   let url: URL
@@ -252,6 +393,53 @@ function authConfig(env: Env, file: HubAuth = {}): AuthConfig {
   return auth as unknown as OidcConfig
 }
 
+const POD_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
+const DATABASE_KEY = "HUB_DATABASE_URL (cluster.database)"
+const VALKEY_KEY = "HUB_VALKEY_URL (cluster.valkey)"
+
+/** The URL when its scheme is one of `protocols`; errors name the key, never the value (it holds credentials). */
+function serviceURL(raw: string, name: string, protocols: readonly string[]): string {
+  let protocol: string
+  try {
+    protocol = new URL(raw).protocol
+  } catch {
+    throw new Error(`${name} is not a valid URL`)
+  }
+  if (!protocols.includes(protocol)) throw new Error(`${name} must be a ${protocols.map((p) => `${p}//`).join(" or ")} URL`)
+  return raw
+}
+
+/**
+ * Cluster settings from env over hub.json, or undefined (single process). Both URLs or neither; cluster mode
+ * requires HUB_TOKEN_KEYS (keys every pod shares) and OIDC sign-in (pairing codes and the local owner are
+ * single-process). Throws without echoing the URLs.
+ */
+function clusterConfig(env: Env, auth: AuthConfig, file: HubCluster = {}): ClusterConfig | undefined {
+  const database = env.HUB_DATABASE_URL?.trim() || file.database
+  const valkey = env.HUB_VALKEY_URL?.trim() || file.valkey
+  if (!database && !valkey) return undefined
+  if (!database || !valkey) {
+    throw new Error(`${DATABASE_KEY} and ${VALKEY_KEY} must be set together for cluster mode; only ${database ? DATABASE_KEY : VALKEY_KEY} is set`)
+  }
+  const databaseURL = serviceURL(database, DATABASE_KEY, ["postgres:", "postgresql:"])
+  const valkeyURL = serviceURL(valkey, VALKEY_KEY, ["redis:", "rediss:", "valkey:", "valkeys:"])
+  if (!env.HUB_TOKEN_KEYS?.trim()) {
+    throw new Error("Cluster mode requires HUB_TOKEN_KEYS: token signing keys every pod shares (the token-keys.json shape)")
+  }
+  if (auth.mode !== "oidc") {
+    throw new Error("Cluster mode requires HUB_AUTH=oidc: pairing mode (pairing codes, the local owner) works in a single process only")
+  }
+  const podID = env.HUB_POD_ID?.trim() || hostname()
+  if (!POD_ID.test(podID)) {
+    throw new Error(`HUB_POD_ID must be 1-128 letters, digits, '.', '_' or '-' (starting with a letter or digit), got ${JSON.stringify(podID)}`)
+  }
+  const cluster = { podID }
+  // Getters: printed as nothing, skipped by JSON.stringify.
+  Object.defineProperty(cluster, "databaseURL", { get: () => databaseURL, enumerable: false })
+  Object.defineProperty(cluster, "valkeyURL", { get: () => valkeyURL, enumerable: false })
+  return cluster as ClusterConfig
+}
+
 export function centralConfig(rawEnv: Env = process.env, home: string = homedir(), file: HubFile = {}): CentralConfig {
   const env = hubEnv(rawEnv)
   const host = env.HUB_HOST || file.host || "127.0.0.1"
@@ -262,6 +450,8 @@ export function centralConfig(rawEnv: Env = process.env, home: string = homedir(
   if (!/^https?:\/\/[^\s/]+$/.test(publicURL)) {
     throw new Error(`HUB_PUBLIC_URL must be an http(s) origin without a path, got ${JSON.stringify(publicURL)}`)
   }
+  const auth = authConfig(env, file.auth)
+  const cluster = clusterConfig(env, auth, file.cluster)
   return {
     host,
     port,
@@ -277,7 +467,11 @@ export function centralConfig(rawEnv: Env = process.env, home: string = homedir(
     // Push services want a contact: an https URL or mailto. The public URL works for hosted hubs.
     vapidSubject: env.HUB_VAPID_SUBJECT || (publicURL.startsWith("https://") ? publicURL : "mailto:hub@localhost"),
     ...(file.speech ? { speech: file.speech } : {}),
-    auth: authConfig(env, file.auth),
+    auth,
+    agentsNever: [...(file.agents?.never ?? [])],
+    ...(file.agents?.launches ? { launchCaps: { ...file.agents.launches } } : {}),
+    ...(file.agents?.webhooks?.allowPrivate === true ? { webhooksAllowPrivate: true as const } : {}),
+    ...(cluster ? { cluster } : {}),
   }
 }
 

package/src/central/done.ts

@@ -0,0 +1,96 @@
+// "All done": one notification when a root session and its whole tree settle, instead of one per root turn.
+//
+// In OpenCode v2 a root session runs many short turns: each background subagent that completes injects a synthetic
+// message into its parent, which starts a new turn, and Voice mode and steering do the same. A notification per
+// `session.execution.succeeded` of the root therefore fired while other subagents and jobs were still running.
+// A run is armed when anything in the tree starts; once the root's last turn succeeded and the tree is settled
+// (StatusBoard.settled: nothing runs, waits for an answer or has a running shell; no hub turn) for DONE_SETTLE_MS
+// without anything starting again, it fires once and disarms.
+import type { Timers } from "./registry"
+
+/** How long a tree must stay settled before "all done" (a continuation turn starts well within it). */
+export const DONE_SETTLE_MS = 15_000
+
+/** Root runs tracked at once (oldest idle ones are forgotten first). */
+const RUNS_LIMIT = 1000
+
+type Outcome = "succeeded" | "failed" | "interrupted"
+
+interface Run {
+  /** Something ran since the last "all done". */
+  armed: boolean
+  /** How the root's last turn ended (undefined while it runs). */
+  outcome?: Outcome
+  timer?: unknown
+}
+
+export class DoneWatch {
+  private readonly runs = new Map<string, Run>()
+
+  constructor(
+    private readonly timers: Timers,
+    /** The tree of `rootID` is settled now. */
+    private readonly settled: (rootID: string) => boolean,
+    private readonly fire: (rootID: string) => void,
+    private readonly delay = DONE_SETTLE_MS,
+  ) {}
+
+  /** A session of the tree started a run (`root`: the root itself). */
+  started(rootID: string, root: boolean): void {
+    const run = this.run(rootID)
+    run.armed = true
+    if (root) run.outcome = undefined
+    this.cancel(run)
+  }
+
+  /** The root's turn ended; `wasRunning`: it was known to run (a duplicate or stray end does not arm). */
+  rootEnded(rootID: string, outcome: Outcome, wasRunning: boolean): void {
+    const run = this.runs.get(rootID) ?? (wasRunning ? this.run(rootID) : undefined)
+    if (!run) return
+    if (wasRunning) run.armed = true
+    run.outcome = outcome
+    this.schedule(rootID, run)
+  }
+
+  /** Something else changed in the tree (a subagent or job ended, an answer, a hub turn released). */
+  poke(rootID: string): void {
+    const run = this.runs.get(rootID)
+    if (run?.armed) this.schedule(rootID, run)
+  }
+
+  forget(rootID: string): void {
+    const run = this.runs.get(rootID)
+    if (run) this.cancel(run)
+    this.runs.delete(rootID)
+  }
+
+  private run(rootID: string): Run {
+    let run = this.runs.get(rootID)
+    if (run) return run
+    this.runs.set(rootID, (run = { armed: false }))
+    if (this.runs.size > RUNS_LIMIT) {
+      for (const [id, old] of this.runs) {
+        if (old.timer !== undefined) continue
+        this.runs.delete(id)
+        break
+      }
+    }
+    return run
+  }
+
+  private schedule(rootID: string, run: Run): void {
+    if (!run.armed) return
+    this.cancel(run)
+    run.timer = this.timers.set(() => {
+      run.timer = undefined
+      if (!run.armed || run.outcome !== "succeeded" || !this.settled(rootID)) return
+      run.armed = false
+      this.fire(rootID)
+    }, this.delay)
+  }
+
+  private cancel(run: Run): void {
+    if (run.timer !== undefined) this.timers.clear(run.timer)
+    run.timer = undefined
+  }
+}