@huynle/hub 0.7.3 → 0.8.0

package/packages/node/src/opencode-warm.ts

@@ -0,0 +1,325 @@
+// Warms OpenCode servers so their hub plugin loads (RP-10, feedback qe6lpzxz #4; RF-04). OpenCode 2.x loads plugins
+// per location, on the first request that names one, and its plugin API has no server-start hook: a freshly started
+// server (`opencode service restart`, a login item, a foreground `opencode serve`) has no hub spoke, so its machine
+// shows offline and host launches cannot be placed until a client opens a project; and OpenCode unloads a location
+// after an hour without session activity (its experimental.location_idle_timeout), which takes the plugin with it.
+// The node daemon asks each server for cheap location reads on every tick: GET /api/agent without a location (the
+// server's default location), then GET /api/agent?location[directory]=<dir> for each project directory to keep
+// loaded: node.json's list, else the projects of the server's recent root sessions under the node's workspace roots
+// (at most WARM_DIRECTORIES_MAX), so a foreground server's spoke reports those projects' idle sessions.
+// The background service is found through its registration file (readServiceRegistration: no request; not
+// @opencode/client's Service.discover, which probes whatever URL the file names with the password and follows
+// redirects); a foreground server through node.json `opencode.servers` (serverEndpoint: its URL and a password file).
+// Security: only a literal loopback URL (127.0.0.1, [::1]; localhost is asked as 127.0.0.1, no resolver) without
+// user info is ever asked, never across a redirect, so a password never leaves this machine; a password file must be
+// a private regular file (no group/other access, not a link) and its content is never logged; logs carry the URL's
+// origin only. Logs on changes only.
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync, statSync, type Stats } from "node:fs"
+import path from "node:path"
+import { readFile } from "node:fs/promises"
+import { listServiceSessions, type ListingClient, type RawProject, type RawSession } from "../../../src/spoke/listing.ts"
+
+/** How often the daemon asks (a restarted server is warmed within this). */
+export const WARM_INTERVAL_MS = 30_000
+const WARM_TIMEOUT_MS = 10_000
+/** Project locations warmed per server and tick, besides its default location. */
+export const WARM_DIRECTORIES_MAX = 8
+/** Automatic project locations: sessions updated within this many days, from one page of this many. */
+const SESSION_DAYS = 7
+const SESSION_PAGE = 100
+/** Loopback hosts asked as they are (after URL normalization); localhost is rewritten to 127.0.0.1. */
+const LOOPBACK = new Set(["127.0.0.1", "[::1]"])
+const PASSWORD_FILE_MAX = 4096
+
+/** A local OpenCode server (the service's registration, or a node.json server with its password). */
+export interface WarmEndpoint {
+  readonly url: string
+  readonly auth?: { readonly type: "basic"; readonly username: string; readonly password: string } | undefined
+  /** Why the endpoint cannot be used (e.g. its password file); the tick fails with it and sends nothing. */
+  readonly problem?: string
+}
+
+export interface OpenCodeWarmerOptions {
+  /** The running server, or undefined when there is none (the service's registration file, or a node.json server). */
+  readonly discover: () => Promise<WarmEndpoint | undefined>
+  readonly log: (line: string) => void
+  readonly intervalMs?: number
+  readonly timeoutMs?: number
+  readonly fetch?: typeof fetch
+  /** What is warmed, in log lines (default "the OpenCode service"). */
+  readonly name?: string
+  /** Project directories to keep loaded besides the default location; replaces the automatic ones ([]: none). */
+  readonly directories?: readonly string[]
+  /** Automatic project directories (when `directories` is absent): recent sessions' projects under these roots. */
+  readonly roots?: () => readonly string[]
+  /** Whether a directory exists (default: stat); missing ones are not asked for. */
+  readonly isDirectory?: (directory: string) => boolean
+}
+
+export type WarmOutcome = "warmed" | "none" | "failed"
+
+const isDirectory = (directory: string) => {
+  try {
+    return statSync(directory).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+const trimSlash = (dir: string) => dir.replace(/\/+$/, "") || "/"
+const within = (dir: string, root: string) => {
+  const r = trimSlash(root)
+  return dir === r || dir.startsWith(r === "/" ? "/" : `${r}/`)
+}
+
+/**
+ * A directory the server reported, normalized: absolute, without `.` or `..` segments (refused, not resolved: a
+ * server's `/roots/../etc` must not pass a prefix check), trailing slashes dropped; undefined otherwise.
+ */
+function normalDirectory(dir: string): string | undefined {
+  if (typeof dir !== "string" || !path.isAbsolute(dir) || dir.split("/").some((part) => part === "." || part === "..")) return undefined
+  return path.resolve(dir)
+}
+
+export class OpenCodeWarmer {
+  /** What was last logged per topic, so only changes are logged. */
+  private readonly last = new Map<string, string>()
+  private timer?: ReturnType<typeof setTimeout>
+  private warmed: string[] = []
+
+  constructor(private readonly options: OpenCodeWarmerOptions) {}
+
+  /** The project directories the last tick loaded (besides the default location). */
+  warmedDirectories(): readonly string[] {
+    return this.warmed
+  }
+
+  /** One discovery and, when a server runs, its location reads. */
+  async tick(): Promise<WarmOutcome> {
+    this.warmed = []
+    let endpoint: WarmEndpoint | undefined
+    try {
+      endpoint = await this.options.discover()
+    } catch {
+      endpoint = undefined
+    }
+    if (!endpoint) return "none"
+    let registered: URL
+    try {
+      registered = new URL(endpoint.url)
+    } catch {
+      return this.report("the registered URL", "an invalid URL")
+    }
+    const label = registered.origin
+    if (registered.username || registered.password) return this.report(label, "a URL with user info")
+    if (registered.protocol !== "http:" && registered.protocol !== "https:") return this.report(label, "not an http URL")
+    const host = registered.hostname === "localhost" ? "127.0.0.1" : registered.hostname
+    if (!LOOPBACK.has(host)) return this.report(label, "not a loopback URL")
+    if (endpoint.problem) return this.report(label, endpoint.problem)
+    const base = `${registered.protocol}//${host}${registered.port ? `:${registered.port}` : ""}`
+    const headers: Record<string, string> = endpoint.auth ? { authorization: `Basic ${btoa(`${endpoint.auth.username}:${endpoint.auth.password}`)}` } : {}
+    const problem = await this.get(`${base}/api/agent`, headers).then(() => undefined, (cause: Error) => cause.message)
+    if (problem) return this.report(label, problem)
+    this.report(label)
+    await this.warmDirectories(base, headers, label)
+    return "warmed"
+  }
+
+  /** Ticks now and every intervalMs until `signal` aborts. */
+  start(signal: AbortSignal): void {
+    const loop = async () => {
+      if (signal.aborted) return
+      await this.tick()
+      if (!signal.aborted) this.timer = setTimeout(loop, this.options.intervalMs ?? WARM_INTERVAL_MS)
+    }
+    signal.addEventListener("abort", () => clearTimeout(this.timer), { once: true })
+    void loop()
+  }
+
+  /** Loads each project location (listed, else automatic); problems are logged on change, never fatal. */
+  private async warmDirectories(base: string, headers: Record<string, string>, label: string): Promise<void> {
+    let directories: readonly string[]
+    if (this.options.directories) directories = this.options.directories
+    else if (this.options.roots) {
+      try {
+        directories = await this.sessionProjects(base, headers, this.options.roots())
+        this.note("list", label)
+      } catch (cause) {
+        this.note("list", label, `could not list the sessions of ${this.name()} at ${label} (${(cause as Error).message}); warming its default location only`)
+        directories = []
+      }
+    } else directories = []
+    const exists = this.options.isDirectory ?? isDirectory
+    const failed: string[] = []
+    for (const directory of directories.slice(0, WARM_DIRECTORIES_MAX)) {
+      if (!exists(directory)) continue
+      try {
+        await this.get(`${base}/api/agent?${new URLSearchParams({ "location[directory]": directory })}`, headers)
+        this.warmed.push(directory)
+      } catch (cause) {
+        failed.push(`${directory} (${(cause as Error).message})`)
+      }
+    }
+    this.note("directories", label, failed.length ? `could not load ${failed.length} project location(s) of ${this.name()} at ${label}: ${failed.join(", ")}` : undefined)
+  }
+
+  /** The projects of the server's recent root sessions under `roots`, newest first. */
+  private async sessionProjects(base: string, headers: Record<string, string>, roots: readonly string[]): Promise<string[]> {
+    if (roots.length === 0) return []
+    const client: ListingClient = {
+      session: {
+        list: async (input) => {
+          const query = new URLSearchParams({ limit: String(input.limit ?? SESSION_PAGE), ...(input.cursor ? { cursor: input.cursor } : {}) })
+          const page = (await this.json(`${base}/api/session?${query}`, headers)) as { data?: RawSession[]; cursor?: { next?: string | null } }
+          if (!page || !Array.isArray(page.data)) throw new Error("not a session list")
+          return { data: page.data, cursor: { next: null } }
+        },
+      },
+      project: { list: async () => (await this.json(`${base}/api/project`, headers)) as RawProject[] },
+    }
+    const sessions = await listServiceSessions(client, { days: SESSION_DAYS, max: SESSION_PAGE, pageSize: SESSION_PAGE, maxPages: 1 })
+    const out: string[] = []
+    for (const s of sessions) {
+      const project = normalDirectory(s.project)
+      if (!project || project === "/" || !roots.some((root) => within(project, path.resolve(root))) || out.includes(project)) continue
+      out.push(project)
+      if (out.length >= WARM_DIRECTORIES_MAX) break
+    }
+    return out
+  }
+
+  private async json(url: string, headers: Record<string, string>): Promise<unknown> {
+    const response = await this.request(url, headers)
+    return response.json()
+  }
+
+  private async get(url: string, headers: Record<string, string>): Promise<void> {
+    const response = await this.request(url, headers)
+    void response.body?.cancel().catch(() => {})
+  }
+
+  /** One request: no redirect followed (a 3xx is a failure), bounded in time. Errors carry no URL or credentials. */
+  private async request(url: string, headers: Record<string, string>): Promise<Response> {
+    let response: Response
+    try {
+      response = await (this.options.fetch ?? fetch)(url, { headers, redirect: "manual", signal: AbortSignal.timeout(this.options.timeoutMs ?? WARM_TIMEOUT_MS) })
+    } catch (cause) {
+      throw new Error((cause as Error).name === "TimeoutError" ? "timed out" : "unreachable")
+    }
+    if (response.type === "opaqueredirect" || (response.status >= 300 && response.status < 400)) {
+      void response.body?.cancel().catch(() => {})
+      throw new Error(`a redirect (HTTP ${response.status}), not followed`)
+    }
+    if (!response.ok) {
+      void response.body?.cancel().catch(() => {})
+      throw new Error(`HTTP ${response.status}`)
+    }
+    return response
+  }
+
+  private name(): string {
+    return this.options.name ?? "the OpenCode service"
+  }
+
+  /** Logs `line` when a topic's state changed (undefined: fine now, logged only as a change back to fine). */
+  private note(topic: string, label: string, line?: string): void {
+    const state = line ?? `ok ${label}`
+    if (this.last.get(topic) === state) return
+    const before = this.last.get(topic)
+    this.last.set(topic, state)
+    if (line) this.options.log(line)
+    else if (before !== undefined && !before.startsWith("ok ")) this.options.log(`${topic === "list" ? "listing the sessions" : "loading the project locations"} of ${this.name()} at ${label} works again`)
+  }
+
+  private report(url: string, problem?: string): WarmOutcome {
+    const line = problem ? `failed ${url}: ${problem}` : `ok ${url}`
+    if (line !== this.last.get("warm")) {
+      this.last.set("warm", line)
+      this.options.log(problem ? `could not warm ${this.name()} at ${url} (${problem}); retrying` : `warmed ${this.name()} at ${url}: its hub plugin loads, so its spoke connects`)
+    }
+    return problem ? "failed" : "warmed"
+  }
+}
+
+/**
+ * OpenCode's background service from its registration file (service.json: {url, pid, password?, id?, version?}),
+ * without any request: undefined when the file is missing or malformed or its process is gone. The URL is passed on
+ * as it is; OpenCodeWarmer.tick decides whether it may be asked.
+ */
+export async function readServiceRegistration(file: string): Promise<WarmEndpoint | undefined> {
+  let info: unknown
+  try {
+    info = JSON.parse(await readFile(file, "utf8"))
+  } catch {
+    return undefined
+  }
+  if (!info || typeof info !== "object") return undefined
+  const { url, pid, password } = info as Record<string, unknown>
+  if (typeof url !== "string" || url.length > 2048 || typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) return undefined
+  try {
+    process.kill(pid, 0)
+  } catch (cause) {
+    if ((cause as NodeJS.ErrnoException).code !== "EPERM") return undefined
+  }
+  return typeof password === "string" ? { url, auth: { type: "basic", username: "opencode", password } } : { url }
+}
+
+/** Pseudo-file systems: their files report size 0 yet read data (/proc/self/environ), or are devices. */
+const PSEUDO_ROOTS = ["/proc", "/sys", "/dev"]
+
+/**
+ * A server password from a file (its first line): only a private regular file (not a link, FIFO, device or socket,
+ * nothing under /proc, /sys or /dev, no symbolic link in its directory path, no group or other access, owned by this
+ * user) of 1 byte to 4 KiB. Never blocks: the file is checked with lstat before it is opened, and opened with
+ * O_NONBLOCK and O_NOFOLLOW (then checked again on the descriptor). Problems never include the content.
+ */
+export function readPasswordFile(file: string): { password: string } | { problem: string } {
+  if (!path.isAbsolute(file)) return { problem: `password file ${file} is not an absolute path` }
+  const resolved = path.resolve(file)
+  if (PSEUDO_ROOTS.some((root) => resolved === root || resolved.startsWith(`${root}/`))) return { problem: `password file ${file} is not a regular file` }
+  try {
+    const dir = path.dirname(resolved)
+    if (realpathSync(dir) !== dir) return { problem: `password file ${file} is reached through a symbolic link (use its real path)` }
+  } catch {
+    return { problem: `password file ${file} does not exist` }
+  }
+  let before: Stats
+  try {
+    before = lstatSync(resolved)
+  } catch (cause) {
+    return { problem: `password file ${file} ${(cause as NodeJS.ErrnoException).code === "ENOENT" ? "does not exist" : "cannot be read"}` }
+  }
+  if (before.isSymbolicLink()) return { problem: `password file ${file} is a symbolic link` }
+  if (!before.isFile()) return { problem: `password file ${file} is not a regular file` }
+  let fd: number
+  try {
+    fd = openSync(resolved, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0))
+  } catch (cause) {
+    const code = (cause as NodeJS.ErrnoException).code
+    return { problem: `password file ${file} ${code === "ELOOP" ? "is a symbolic link" : code === "ENOENT" ? "does not exist" : "cannot be read"}` }
+  }
+  try {
+    const stat = fstatSync(fd)
+    if (!stat.isFile() || stat.dev !== before.dev || stat.ino !== before.ino) return { problem: `password file ${file} is not a regular file` }
+    if ((stat.mode & 0o077) !== 0) return { problem: `password file ${file} is readable by others (chmod 600 it)` }
+    if (typeof process.getuid === "function" && stat.uid !== process.getuid()) return { problem: `password file ${file} is not owned by this user` }
+    if (stat.size === 0) return { problem: `password file ${file} is empty` }
+    if (stat.size > PASSWORD_FILE_MAX) return { problem: `password file ${file} is too large` }
+    const buffer = Buffer.alloc(PASSWORD_FILE_MAX + 1)
+    const length = readSync(fd, buffer, 0, buffer.length, 0)
+    if (length > stat.size || length > PASSWORD_FILE_MAX) return { problem: `password file ${file} is too large` }
+    const password = buffer.subarray(0, length).toString("utf8").split(/\r?\n/)[0]!.trim()
+    if (!password) return { problem: `password file ${file} is empty` }
+    return { password }
+  } finally {
+    closeSync(fd)
+  }
+}
+
+/** A node.json server's endpoint: its URL with the password read from its file on every discovery (rotation). */
+export function serverEndpoint(server: { readonly url: string; readonly passwordFile: string }): () => Promise<WarmEndpoint> {
+  return async () => {
+    const read = readPasswordFile(server.passwordFile)
+    return "password" in read ? { url: server.url, auth: { type: "basic", username: "opencode", password: read.password } } : { url: server.url, problem: read.problem }
+  }
+}

package/packages/node/src/run.ts

@@ -3,10 +3,13 @@
 // also offers the openshell runtime (sandboxes through the openshell CLI): it checks the CLI, asks the gateway for
 // its backends and sweeps this machine's sandboxes from an earlier run into the hello; an unusable CLI is logged and
 // the node runs with the host runtime only. The host runtime offers the harnesses found on this machine
-// (harnesses.ts: opencode, claude-code with its CLI, node.json `harnesses` overriding). Exit codes: 0 after a clean stop, 1 when
+// (harnesses.ts: opencode, claude-code with its CLI, node.json `harnesses` overriding). While it offers opencode, the
+// node keeps OpenCode's background service and node.json's foreground servers warm (opencode-warm.ts) so their hub
+// plugin loads without a client opening a project. Exit codes: 0 after a clean stop, 1 when
 // the machine is not enrolled, EXIT_CONFIG (78, EX_CONFIG) when node.json gives the node nothing to do; the
 // service units do not restart on 78.
 import { homedir } from "node:os"
+import path from "node:path"
 import type { NodeLaunchReport } from "../../protocol/src/index.ts"
 import { OpenShellCli } from "../../runtime-openshell/src/cli.ts"
 import type { Runtime } from "../../runtime-sdk/src/index.ts"
@@ -14,6 +17,7 @@ import { nodeConfigPath, readNodeConfig, readSpokeCredentials, type NodeConfig,
 import { NodeDaemon, NODE_VERSION } from "./daemon.ts"
 import { detectHarnesses } from "./harnesses.ts"
 import { HostRuntime } from "./host.ts"
+import { OpenCodeWarmer, readServiceRegistration, serverEndpoint, type WarmEndpoint } from "./opencode-warm.ts"
 import { createOpenShellRuntime, openshellBackends, PROBE_TIMEOUT_MS, sweepSandboxes } from "./openshell.ts"
 
 export const EXIT_CONFIG = 78
@@ -29,6 +33,27 @@ export interface RunNodeOptions {
   readonly signal: AbortSignal
   /** The openshell executable (default "openshell" on PATH). */
   readonly openshellBinary?: string
+  /** Finds OpenCode's background service (default: readServiceRegistration on this env's registration file). */
+  readonly openCodeService?: () => Promise<WarmEndpoint | undefined>
+}
+
+/** OpenCode's service registration file for `env` and `home` (@opencode/client's default location). */
+export const openCodeServiceFile = (env: Env, home: string): string =>
+  path.join(env.XDG_STATE_HOME || path.join(home, ".local", "state"), "opencode", "service.json")
+
+
+/**
+ * Keeps OpenCode's hub plugin loaded (opencode-warm.ts): the background service and each node.json
+ * `opencode.servers` entry (a foreground `opencode serve`), at their default location and project directories
+ * (listed, else the projects of their recent sessions under the workspace roots).
+ */
+function startOpenCodeWarmers(config: NodeConfig, service: () => Promise<WarmEndpoint | undefined>, log: (line: string) => void, signal: AbortSignal): void {
+  const roots = () => config.workspaceRoots
+  const directories = config.opencode?.directories
+  new OpenCodeWarmer({ discover: service, log, roots, ...(directories ? { directories } : {}) }).start(signal)
+  for (const server of config.opencode?.servers ?? []) {
+    new OpenCodeWarmer({ discover: serverEndpoint(server), log, name: "the OpenCode server", roots, ...(server.directories ? { directories: server.directories } : {}) }).start(signal)
+  }
 }
 
 interface OpenShellSetup {
@@ -96,6 +121,7 @@ export async function runNode(options: RunNodeOptions): Promise<number> {
   })
   log(`hub node ${NODE_VERSION}: ${config.slots} slots, roots ${config.workspaceRoots.join(", ")}; host harnesses ${harnesses.join(", ") || "none"}`)
   daemon.start()
+  if (harnesses.includes("opencode")) startOpenCodeWarmers(config, options.openCodeService ?? (() => readServiceRegistration(openCodeServiceFile(env, home))), log, options.signal)
   await new Promise<void>((resolve) => {
     if (options.signal.aborted) return resolve()
     options.signal.addEventListener("abort", () => resolve(), { once: true })

package/packages/preset/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-preset",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "private": true,
   "description": "The preset spoke: drives a harness without a spoke of its own through a terminal pane (tmux), described by a data-only preset; official presets in presets/ (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/preset/src/profile.ts

@@ -0,0 +1,34 @@
+// Profile application on preset sessions (HWA-18; protocol packages/protocol/src/profiles.ts). A preset session is a
+// terminal the spoke pastes into (evidence "screen"): there is no session-scoped place for instructions, skills or
+// commands, the model is fixed by the harness, and the spoke could not confirm any change took effect. Typing a
+// profile into the conversation would be a prompt, not a profile, so nothing is ever pasted.
+//
+// The spoke still announces profileApply so the answer is explicit: every known session's request is answered
+// "unsupported" with one note per part and PRESET_PROFILE_NOTE; a mismatched digest or an unknown session is
+// "rejected". Command-only support (rendering a command and pasting it at invocation) is not offered: on screen
+// evidence it cannot be verified.
+import type { ProfileApplyRequest, ProfileApplyResult } from "../../protocol/src/index.ts"
+import { planProfileApplication, profileApplyResult, profileDigest, type ProfileCapabilities } from "../../spoke-sdk/src/index.ts"
+
+/** What the preset spoke can apply of a profile to a running harness: nothing. */
+export const PRESET_PROFILE_CAPABILITIES: ProfileCapabilities = Object.freeze({
+  instructions: false,
+  skills: false,
+  commands: false,
+  model: false,
+  live: false,
+  renderAtInvocation: false,
+})
+
+export const PRESET_PROFILE_NOTE =
+  "preset sessions are terminals the spoke pastes into: a running harness's instructions, skills, commands or model cannot be changed without typing into the conversation, and no change could be confirmed (screen evidence)"
+
+/** The `profileApply` op handler for a preset spoke whose sessions are `has`. */
+export function presetProfileApply(has: (sessionID: string) => boolean): (req: ProfileApplyRequest) => Promise<ProfileApplyResult> {
+  return async (req) => {
+    if (profileDigest(req.content) !== req.digest) return profileApplyResult(req, "rejected", ["digest does not match the content; nothing applied"])
+    if (!has(req.sessionID)) return profileApplyResult(req, "rejected", [`unknown session ${req.sessionID}`])
+    const plan = planProfileApplication(req, { capabilities: PRESET_PROFILE_CAPABILITIES })
+    return profileApplyResult(req, "unsupported", [...plan.notes, PRESET_PROFILE_NOTE])
+  }
+}

package/packages/preset/src/spoke.ts

@@ -8,6 +8,7 @@
 //   is "retained" (nothing is typed into the user's input line) and pasted ahead of the session's next turn or
 //   message; a prompt (hubPrompt) goes in its provenance envelope;
 // - interrupt and stop: Ctrl-C, only when the backend can send keys;
+// - profileApply: answered "unsupported" with notes (or "rejected"), never pasted (profile.ts);
 // - never permission, form or steer (a terminal paste can answer neither a dialog nor a running turn reliably);
 // - never an event: no activity, and above all no idle, is inferred from the screen (the hub never treats screen
 //   evidence as idle anyway). The screen is only sampled for the harness's native session ID (source screen) and the
@@ -21,6 +22,7 @@ import path from "node:path"
 import type { HarnessPreset, SessionInfo } from "../../protocol/src/index.ts"
 import { deliverText, HarnessSpoke, hubSessionID, type Admission, type DeliverRequest, type HarnessSpokeOptions, type OpHandlers } from "../../spoke-sdk/src/index.ts"
 import { launchArgv, nativeIDFromScreen } from "./presets.ts"
+import { presetProfileApply } from "./profile.ts"
 import type { TerminalBackend, TerminalPane } from "./tmux.ts"
 
 /** The hub session ID namespace of preset sessions (ses_pr…). */
@@ -111,6 +113,8 @@ export class PresetSpoke {
         await this.#submit(this.#session(req.sessionID), req.text)
         return { outcome: "timeout", reply: "" }
       },
+      // Answered explicitly, never applied (profile.ts): unsupported with notes, or rejected.
+      profileApply: presetProfileApply((id) => this.#sessions.has(id)),
       ...(this.#backend.canSendKeys
         ? {
             interrupt: async (req: { sessionID: string }) => (await this.#interrupt(req.sessionID), {}),

package/packages/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-protocol",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "private": true,
   "description": "Hub ↔ spoke wire protocol (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/protocol/src/artifacts.ts

@@ -0,0 +1,142 @@
+// Persistent artifacts (HWA-02 contract; metadata/revisions + BlobStore interface HWA-20, standalone blobs and
+// transfer API HWA-21, cluster blobs HWA-22, viewers HWA-23, AI jobs HWA-24/25, isolated app host HWA-26/27).
+//
+// Invariants frozen here:
+// - Blobs are content-addressed (sha256) and immutable; revisions reference blobs; metadata lives in the state
+//   store. Standalone keeps blobs as files under the hub data directory; a cluster keeps them in a chunked
+//   Postgres table (decision tctkrik8). Nothing lives in ephemeral session or launch paths.
+// - Access: private to the owner by default. Visibility widens only explicitly; every read checks it. AI actions
+//   run with the viewer's own authority (no privilege laundering through the artifact or its job session).
+// - Interactive artifacts ("app" kind) run only in the isolated artifact host (separate origin, sandboxed frame,
+//   CSP, capability bridge); never inside the console bundle, never as a console plugin, never in central.
+// - Concurrent revisions: a new revision names `baseRevisionID`; a stale base is 409 `conflict` (no silent merge).
+import { DESCRIPTION_MAX, isContractID, isLabel, isText, metadataProblem, tagsProblem, type RecordState, type Revisioned } from "./contracts.ts"
+import { isObj } from "./wire.ts"
+
+export const ARTIFACT_LIMITS = {
+  artifactsPerUser: 5_000,
+  revisionsPerArtifact: 500,
+  /** Bytes of one blob and of all of one user's blobs. */
+  blobBytes: 25 * 1024 * 1024,
+  userBlobBytes: 2 * 1024 * 1024 * 1024,
+  /** Files in a multi-file ("bundle") revision, e.g. an app. */
+  bundleFiles: 200,
+  /** Chunk size of the cluster Postgres blob table. */
+  chunkBytes: 1024 * 1024,
+  /** Concurrent AI jobs per user and per artifact. */
+  aiJobsPerUser: 8,
+  aiJobsPerArtifact: 2,
+  /** Characters of an AI job instruction. */
+  aiInstructionChars: 8_000,
+} as const
+
+export const ARTIFACT_SCOPES = ["artifacts:read", "artifacts:write", "artifacts:ai"] as const
+
+/** What renders an artifact. Declarative kinds render in the console; "app" only in the isolated host. */
+export const ARTIFACT_KINDS = ["markdown", "code", "image", "table", "chart", "dashboard", "html", "app", "file"] as const
+export type ArtifactKind = (typeof ARTIFACT_KINDS)[number]
+export const ISOLATED_KINDS: readonly ArtifactKind[] = ["html", "app"]
+
+export type ArtifactVisibility = "private" | "workspace"
+
+export interface Artifact extends Revisioned {
+  readonly v: 1
+  readonly id: string
+  readonly title: string
+  readonly description?: string
+  readonly kind: ArtifactKind
+  readonly state: RecordState
+  /** "private": owner only; "workspace": the owner plus sessions that are current members of workspaceID. */
+  readonly visibility: ArtifactVisibility
+  readonly workspaceID?: string
+  /** Session that created it (provenance only; grants nothing). */
+  readonly createdBySessionID?: string
+  readonly latestRevisionID: string
+  readonly tags?: readonly string[]
+  readonly metadata?: Readonly<Record<string, string>>
+  readonly createdAt: number
+  readonly updatedAt: number
+}
+
+export interface BlobRef {
+  /** `sha256:<64 hex>`. */
+  readonly hash: string
+  readonly bytes: number
+  /** A media type from a fixed allowlist (the transfer API rejects others). */
+  readonly mediaType: string
+  /** Path inside a bundle revision; absent for a single-file revision. */
+  readonly path?: string
+}
+
+export interface ArtifactRevision {
+  readonly v: 1
+  readonly id: string
+  readonly artifactID: string
+  readonly number: number
+  readonly baseRevisionID?: string
+  readonly blobs: readonly BlobRef[]
+  /** Entry file of a bundle (apps, html). */
+  readonly entry?: string
+  readonly author: { readonly kind: "user" } | { readonly kind: "session"; readonly sessionID: string } | { readonly kind: "ai_job"; readonly jobID: string }
+  readonly createdAt: number
+}
+
+export type AiJobState = "queued" | "running" | "succeeded" | "failed" | "cancelled"
+
+/** An agent-backed AI action on an artifact, durable across hub restarts; runs as the requesting viewer. */
+export interface ArtifactAiJob extends Revisioned {
+  readonly v: 1
+  readonly id: string
+  readonly artifactID: string
+  readonly baseRevisionID: string
+  readonly requestedBy: { readonly kind: "user" } | { readonly kind: "session"; readonly sessionID: string }
+  readonly state: AiJobState
+  /** Launch or session doing the work (when started). */
+  readonly launchID?: string
+  readonly sessionID?: string
+  readonly resultRevisionID?: string
+  readonly error?: string
+  readonly createdAt: number
+  readonly updatedAt: number
+}
+
+export const ARTIFACT_EVENT_TYPES = ["artifact.created", "artifact.revised", "artifact.archived", "artifact.visibility", "artifact.job"] as const
+
+/** Media types the transfer API accepts. Anything else is rejected, never sniffed. */
+export const ARTIFACT_MEDIA_TYPES = [
+  "text/markdown",
+  "text/plain",
+  "text/csv",
+  "text/html",
+  "text/css",
+  "text/javascript",
+  "application/json",
+  "application/pdf",
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp",
+  "image/svg+xml",
+] as const
+
+export const isBlobHash = (v: unknown): v is string => typeof v === "string" && /^sha256:[0-9a-f]{64}$/.test(v)
+
+export function artifactInputProblem(v: unknown): string | undefined {
+  if (!isObj(v)) return "body must be an object"
+  if (!isLabel(v.title)) return "title must be 1–120 characters of text"
+  if (v.description !== undefined && !isText(v.description, DESCRIPTION_MAX)) return `description must be at most ${DESCRIPTION_MAX} characters`
+  if (!ARTIFACT_KINDS.includes(v.kind as ArtifactKind)) return `kind must be one of ${ARTIFACT_KINDS.join(", ")}`
+  if (v.visibility !== undefined && v.visibility !== "private" && v.visibility !== "workspace") return "visibility must be private or workspace"
+  if (v.visibility === "workspace" && !isContractID("workspace", v.workspaceID)) return "workspace visibility needs a workspaceID"
+  if (v.workspaceID !== undefined && !isContractID("workspace", v.workspaceID)) return "workspaceID must be a workspace ID"
+  return tagsProblem(v.tags) ?? metadataProblem(v.metadata)
+}
+
+export function blobRefProblem(v: unknown): string | undefined {
+  if (!isObj(v)) return "blob must be an object"
+  if (!isBlobHash(v.hash)) return "hash must be sha256:<64 hex>"
+  if (typeof v.bytes !== "number" || !Number.isSafeInteger(v.bytes) || v.bytes < 0 || v.bytes > ARTIFACT_LIMITS.blobBytes) return `bytes must be 0–${ARTIFACT_LIMITS.blobBytes}`
+  if (!ARTIFACT_MEDIA_TYPES.includes(v.mediaType as (typeof ARTIFACT_MEDIA_TYPES)[number])) return "mediaType is not allowed"
+  if (v.path !== undefined && (typeof v.path !== "string" || !/^(?!\/)(?!.*(?:^|\/)\.\.?(?:\/|$))[A-Za-z0-9._/-]{1,200}$/.test(v.path))) return "path must be a relative path without . or .. segments"
+  return undefined
+}