@huynle/hub 0.6.1 → 0.7.2

package/packages/spoke-sdk/src/connection.ts

@@ -0,0 +1,295 @@
+// The spoke's single outbound WebSocket to the central server: hello/welcome handshake, request/
+// response correlation in both directions, and reconnect with jittered exponential backoff. A bye carrying
+// retryAfterMs (a hub pod draining, design §10) is followed by one short jittered reconnect (0–retryAfterMs) instead.
+import {
+  encode,
+  MAX_FRAME,
+  parseServerMessage,
+  PROTOCOL_VERSION,
+  type Hello,
+  type ResultFor,
+  type ServerRequest,
+  type SpokeMessage,
+  type SpokeRequest,
+  type Welcome,
+} from "../../protocol/src/index.ts"
+
+export type ConnectionState = "off" | "connecting" | "connected" | "revoked" | "error"
+
+export interface Backoff {
+  readonly minMs: number
+  readonly maxMs: number
+  readonly random?: () => number
+}
+
+/** Minimal WebSocket surface used here (Bun's WebSocket accepts `{ headers }` as a 2nd argument). */
+export interface SocketLike {
+  readonly readyState: number
+  onopen: ((ev: unknown) => void) | null
+  onmessage: ((ev: { data: unknown }) => void) | null
+  onclose: ((ev: { code?: number; reason?: string }) => void) | null
+  onerror: ((ev: unknown) => void) | null
+  send(data: string): void
+  close(code?: number, reason?: string): void
+}
+
+export interface ConnectionOptions {
+  readonly server: string
+  readonly token: string
+  /** Hello fields, computed per attempt so mode/directory are current. */
+  readonly hello: () => Omit<Hello, "t" | "v">
+  /** Executes a server request; a thrown error becomes `{ ok: false, error }`. */
+  readonly handle: (req: ServerRequest) => Promise<unknown>
+  readonly onWelcome?: (welcome: Welcome) => void
+  readonly onState?: (state: ConnectionState, error?: string) => void
+  readonly backoff?: Backoff
+  readonly requestTimeoutMs?: number
+  readonly socket?: (url: string, headers: Record<string, string>) => SocketLike
+}
+
+export function backoffDelay(attempt: number, backoff: Backoff): number {
+  const base = Math.min(backoff.maxMs, backoff.minMs * 2 ** Math.min(attempt, 30))
+  const random = (backoff.random ?? Math.random)()
+  return Math.round(base * (0.5 + 0.5 * random))
+}
+
+/** The reconnect delay a bye's retryAfterMs asks for: uniformly jittered over 0–retryAfterMs, so peers spread out. */
+export function retryAfterDelay(retryAfterMs: number, random: () => number = Math.random): number {
+  return Math.round(retryAfterMs * random())
+}
+
+export function wsURL(server: string): string {
+  return `${server.replace(/\/+$/, "").replace(/^http/, "ws")}/spoke/ws`
+}
+
+const defaultSocket = (url: string, headers: Record<string, string>): SocketLike =>
+  new (WebSocket as unknown as new (url: string, options: { headers: Record<string, string> }) => SocketLike)(url, { headers })
+
+const message = (cause: unknown) => (cause instanceof Error ? cause.message : String(cause))
+
+interface Pending {
+  resolve: (value: unknown) => void
+  reject: (error: Error) => void
+  timer: ReturnType<typeof setTimeout>
+}
+
+export class SpokeConnection {
+  state: ConnectionState = "off"
+  lastError?: string
+  publicURL?: string
+  machineID?: string
+
+  private socket?: SocketLike
+  private welcomed = false
+  /** Features the hub listed in its welcome on the current socket (none before a welcome or from an old hub). */
+  private hubFeatures: ReadonlySet<string> = new Set()
+  private stopped = true
+  private attempt = 0
+  private retry?: ReturnType<typeof setTimeout>
+  /** The last bye's retryAfterMs (a draining hub): the next reconnect waits about this instead of the backoff. */
+  private retryAfterMs?: number
+  private nextID = 0
+  private readonly pending = new Map<string, Pending>()
+  private readonly backoff: Backoff
+
+  constructor(private readonly options: ConnectionOptions) {
+    this.backoff = options.backoff ?? { minMs: 1000, maxMs: 60_000 }
+  }
+
+  start(): void {
+    if (!this.stopped) return
+    this.stopped = false
+    this.open()
+  }
+
+  stop(): void {
+    this.stopped = true
+    clearTimeout(this.retry)
+    this.drop(1000, "stop")
+    this.failPending("disconnected")
+    this.setState("off")
+  }
+
+  /** Whether the connected hub announced `feature`; send a request a newer hub added only when it did. */
+  hubSupports(feature: string): boolean {
+    return this.hubFeatures.has(feature)
+  }
+
+  /** Reconnects at once (e.g. after a local hub was started) instead of waiting out the backoff. */
+  retryNow(): void {
+    if (this.stopped || this.state === "connected" || this.state === "revoked" || this.socket) return
+    clearTimeout(this.retry)
+    this.attempt = 0
+    this.open()
+  }
+
+  /** Sends a frame once the server has welcomed us. Returns false when it could not be sent. */
+  send(frame: SpokeMessage): boolean {
+    if (!this.socket || !this.welcomed || this.socket.readyState !== 1) return false
+    try {
+      let text = encode(frame)
+      if (text.length > MAX_FRAME) {
+        // The hub drops the connection on an oversize frame; answer a request with an error instead.
+        if (frame.t !== "res") return false
+        text = encode({ t: "res", id: frame.id, ok: false, error: `Result too large to send (${text.length} characters, limit ${MAX_FRAME})` })
+      }
+      this.socket.send(text)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  request<R extends SpokeRequest>(req: R): Promise<ResultFor[R["op"]]> {
+    const id = `s${++this.nextID}`
+    return new Promise((resolve, reject) => {
+      if (this.state !== "connected") return reject(new Error("Not connected to the hub"))
+      const timer = setTimeout(() => {
+        this.pending.delete(id)
+        reject(new Error("The hub timed out"))
+      }, this.options.requestTimeoutMs ?? 15_000)
+      this.pending.set(id, { resolve: resolve as (v: unknown) => void, reject, timer })
+      if (!this.send({ t: "req", id, req })) {
+        clearTimeout(timer)
+        this.pending.delete(id)
+        reject(new Error("Not connected to the hub"))
+      }
+    })
+  }
+
+  private open(): void {
+    if (this.stopped) return
+    this.setState(this.state === "error" ? "error" : "connecting")
+    let socket: SocketLike
+    try {
+      socket = (this.options.socket ?? defaultSocket)(wsURL(this.options.server), {
+        Authorization: `Bearer ${this.options.token}`,
+      })
+    } catch (cause) {
+      this.fail(message(cause))
+      return
+    }
+    this.socket = socket
+    this.welcomed = false
+    socket.onopen = () => {
+      try {
+        socket.send(encode({ t: "hello", v: PROTOCOL_VERSION, ...this.options.hello() }))
+      } catch (cause) {
+        this.lastError = message(cause)
+      }
+    }
+    socket.onmessage = (ev) => this.receive(ev.data)
+    socket.onerror = () => {
+      this.lastError = this.welcomed ? "Connection error" : "Could not connect to the hub"
+    }
+    socket.onclose = (ev) => {
+      if (this.socket !== socket) return
+      this.socket = undefined
+      const wasWelcomed = this.welcomed
+      this.welcomed = false
+      this.hubFeatures = new Set()
+      this.failPending("disconnected")
+      if (this.stopped || this.state === "revoked") return
+      this.fail(wasWelcomed ? `Connection closed${ev.reason ? `: ${ev.reason}` : ""}` : (this.lastError ?? "Could not connect"))
+    }
+  }
+
+  private receive(data: unknown): void {
+    const text = typeof data === "string" ? data : data instanceof ArrayBuffer ? Buffer.from(data).toString("utf8") : String(data)
+    const frame = parseServerMessage(text)
+    if (!frame) return
+    switch (frame.t) {
+      case "welcome":
+        this.welcomed = true
+        this.hubFeatures = new Set(frame.features ?? [])
+        this.attempt = 0
+        this.publicURL = frame.publicURL
+        this.machineID = frame.machineID
+        this.lastError = undefined
+        this.setState("connected")
+        try {
+          this.options.onWelcome?.(frame)
+        } catch (cause) {
+          console.error("[hub] welcome handler failed", cause)
+        }
+        return
+      case "bye":
+        if (frame.reason === "revoked") {
+          this.stopped = true
+          clearTimeout(this.retry)
+          this.lastError = "This machine was revoked on the hub"
+          this.setState("revoked")
+          this.drop(1000, "revoked")
+          this.failPending("revoked")
+        } else if (frame.retryAfterMs !== undefined) {
+          this.retryAfterMs = frame.retryAfterMs
+        }
+        return
+      case "res": {
+        const pending = this.pending.get(frame.id)
+        if (!pending) return
+        this.pending.delete(frame.id)
+        clearTimeout(pending.timer)
+        if (frame.ok) pending.resolve(frame.result)
+        else pending.reject(new Error(frame.error ?? "Request failed"))
+        return
+      }
+      case "req":
+        void this.answer(frame.id, frame.req)
+        return
+    }
+  }
+
+  private async answer(id: string, req: ServerRequest): Promise<void> {
+    let reply: SpokeMessage
+    try {
+      reply = { t: "res", id, ok: true, result: await this.options.handle(req) }
+    } catch (cause) {
+      reply = { t: "res", id, ok: false, error: message(cause) }
+    }
+    this.send(reply)
+  }
+
+  private fail(error: string): void {
+    this.lastError = error
+    this.setState("error")
+    if (this.stopped) return
+    clearTimeout(this.retry)
+    const retryAfterMs = this.retryAfterMs
+    this.retryAfterMs = undefined
+    const delay = retryAfterMs !== undefined ? retryAfterDelay(retryAfterMs, this.backoff.random) : backoffDelay(this.attempt++, this.backoff)
+    this.retry = setTimeout(() => this.open(), delay)
+  }
+
+  private drop(code: number, reason: string): void {
+    const socket = this.socket
+    this.socket = undefined
+    this.welcomed = false
+    this.hubFeatures = new Set()
+    if (!socket) return
+    socket.onopen = socket.onmessage = socket.onerror = socket.onclose = null
+    try {
+      socket.close(code, reason)
+    } catch {
+      // already closed
+    }
+  }
+
+  private failPending(reason: string): void {
+    for (const [id, pending] of this.pending) {
+      clearTimeout(pending.timer)
+      pending.reject(new Error(`Hub ${reason}`))
+      this.pending.delete(id)
+    }
+  }
+
+  private setState(state: ConnectionState): void {
+    if (state === this.state) return
+    this.state = state
+    try {
+      this.options.onState?.(state, this.lastError)
+    } catch {
+      // observers must not break the connection
+    }
+  }
+}

package/packages/spoke-sdk/src/delivery.ts

@@ -0,0 +1,119 @@
+// Harness-neutral delivery helpers (the deliver op): the provenance envelope an agent's prompt (kind "prompt") is
+// rendered in, who put each inbox item into a session, and applying each hub message once (DeliveryLedger: the hub
+// retries a deliver with the same messageID; a harness may not deduplicate it, so the spoke must).
+import { sanitizeLabel, sanitizeText } from "../../sdk/src/envelope.ts"
+import type { DeliverMeta, DeliverResult, InboxOrigin } from "../../protocol/src/index.ts"
+import { PROMPT_SOURCE } from "./prompt-source.ts"
+
+/** Body lines that could pass for a header or boundary (or an escaped one): escaped with a leading backslash. */
+const FORGEABLE = /^\s*\\*(?:\[hub\]|-{3,}|↩)/i
+
+/**
+ * The text a session sees for an agent's prompt (kind "prompt"): a provenance header naming the sender and the
+ * grant, then the sanitised body between two boundaries (the same shape as the hub's message envelope, so
+ * timelines read the body back). The header comes from the hub's meta, never from the body.
+ */
+export function renderPromptEnvelope(input: { readonly messageID: string; readonly from: string; readonly grant: string; readonly text: string }): string {
+  const id = sanitizeLabel(input.messageID)
+  const boundary = `----- ${id} -----`
+  const body = sanitizeText(input.text)
+    .split("\n")
+    .map((line) => (FORGEABLE.test(line) ? `\\${line}` : line))
+    .join("\n")
+  return [`[hub] prompt from ${sanitizeLabel(input.from)} · grant ${sanitizeLabel(input.grant)} · ${id}`, boundary, body, boundary].join("\n")
+}
+
+/** What OpenCode gets for a deliver: a prompt wrapped in its provenance envelope, other kinds as the hub rendered them. */
+export function deliverText(req: { readonly messageID: string; readonly text: string; readonly meta: DeliverMeta }): string {
+  if (req.meta.kind !== "prompt") return req.text
+  return renderPromptEnvelope({ messageID: req.messageID, from: req.meta.from, grant: req.meta.grant ?? "", text: req.text })
+}
+
+const record = (v: unknown): Record<string, any> => (typeof v === "object" && v !== null ? (v as Record<string, any>) : {})
+
+/** A bounded insertion-ordered map: the oldest entry goes when it is full. */
+class Bounded<V> {
+  private readonly map = new Map<string, V>()
+  constructor(private readonly max: number) {}
+  get(key: string): V | undefined {
+    return this.map.get(key)
+  }
+  set(key: string, value: V): void {
+    this.map.delete(key)
+    this.map.set(key, value)
+    if (this.map.size > this.max) this.map.delete(this.map.keys().next().value!)
+  }
+  delete(key: string): void {
+    this.map.delete(key)
+  }
+}
+
+/**
+ * Who put each inbox item into a session, from OpenCode's session.inbox.enqueued events and the spoke's own
+ * deliveries: a user item is the user's (typed, or sent from the phone), a synthetic item with hub metadata is
+ * the hub's; anything else (OpenCode's own notes, compaction) has no origin.
+ */
+export class InboxOrigins {
+  private readonly origins: Bounded<InboxOrigin>
+  constructor(max = 1000) {
+    this.origins = new Bounded(max)
+  }
+
+  observe(event: { readonly type: string; readonly data?: unknown }): void {
+    if (event.type !== "session.inbox.enqueued") return
+    const data = record(event.data)
+    if (typeof data.inboxID !== "string" || this.origins.get(data.inboxID) === "hub") return
+    const item = record(data.item)
+    const metadata = record(record(item.payload).metadata)
+    // A hub message (hub metadata with its messageID) is never the user's, whatever item type OpenCode gives it.
+    if (metadata.source === PROMPT_SOURCE && typeof metadata.messageID === "string" && (item.type === "synthetic" || item.type === "user")) this.origins.set(data.inboxID, "hub")
+    else if (item.type === "user") this.origins.set(data.inboxID, "user")
+  }
+
+  /** Marks an inbox item the spoke delivered for the hub. */
+  hub(inboxID: string): void {
+    this.origins.set(inboxID, "hub")
+  }
+
+  /** The item's origin, when known; forgets it (an item is delivered once). */
+  take(inboxID: string): InboxOrigin | undefined {
+    const origin = this.origins.get(inboxID)
+    this.origins.delete(inboxID)
+    return origin
+  }
+}
+
+export interface Admission {
+  readonly result: DeliverResult
+  /** Whether it was sent with resume (could start a turn). */
+  readonly resumed: boolean
+}
+
+/**
+ * Applies each hub message once: a duplicate messageID (the hub's retry, in flight or done) gets the first
+ * result without another admission. Only a retry that asks to wake a message first admitted without waking is
+ * sent again (OpenCode keeps one message for the id and wakes the session). Failures are not remembered.
+ */
+export class DeliveryLedger {
+  private readonly entries: Bounded<Promise<Admission>>
+  constructor(max = 1000) {
+    this.entries = new Bounded(max)
+  }
+
+  async run(messageID: string, wake: boolean, send: () => Promise<Admission>): Promise<DeliverResult> {
+    const known = this.entries.get(messageID)
+    if (known) {
+      const admission = await known.catch(() => undefined)
+      if (admission && (!wake || admission.resumed)) return admission.result
+      if (this.entries.get(messageID) !== known) return this.run(messageID, wake, send)
+    }
+    const attempt = send()
+    this.entries.set(messageID, attempt)
+    try {
+      return (await attempt).result
+    } catch (cause) {
+      if (this.entries.get(messageID) === attempt) this.entries.delete(messageID)
+      throw cause
+    }
+  }
+}

package/packages/spoke-sdk/src/enroll.ts

@@ -0,0 +1,101 @@
+// Device-code enrollment of this machine with the central server (before it has a token).
+// POST /spoke/enroll → EnrollStart; then POST /spoke/enroll/poll until the user approves it.
+import type { EnrollPoll, EnrollStart } from "../../protocol/src/index.ts"
+
+export type EnrollOutcome =
+  | { readonly status: "approved"; readonly machineID: string; readonly machineToken: string }
+  | { readonly status: "denied" | "expired" | "cancelled" }
+
+export interface EnrollOptions {
+  readonly signal?: AbortSignal
+  readonly fetch?: typeof fetch
+  readonly now?: () => number
+  /**
+   * "follow" (default) follows HTTP redirects. "error" refuses them: a redirect could send the device code to
+   * another origin or downgrade to plain http. A refused redirect throws EnrollmentRefused, which polling does not
+   * retry.
+   */
+  readonly redirect?: "follow" | "error"
+  /**
+   * The hub hands out an approved credential exactly once. With keepRedeemed, `signal` never aborts a poll request
+   * in flight (its reply may carry that credential); it still stops polling before the next request.
+   */
+  readonly keepRedeemed?: boolean
+}
+
+/** The hub answered in a way the caller's policy refuses (a redirect under redirect: "error"); not retried. */
+export class EnrollmentRefused extends Error {
+  override readonly name = "EnrollmentRefused"
+}
+
+const REQUEST_TIMEOUT_MS = 15_000
+
+async function post(server: string, path: string, body: unknown, options: EnrollOptions, abortable = true): Promise<unknown> {
+  const doFetch = options.fetch ?? fetch
+  const signals = [AbortSignal.timeout(REQUEST_TIMEOUT_MS), ...(options.signal && abortable ? [options.signal] : [])]
+  const strict = options.redirect === "error"
+  const response = await doFetch(`${server.replace(/\/+$/, "")}${path}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+    signal: AbortSignal.any(signals),
+    ...(strict ? { redirect: "manual" as const } : {}),
+  })
+  if (strict && (response.type === "opaqueredirect" || (response.status >= 300 && response.status < 400))) {
+    throw new EnrollmentRefused(`${path} was redirected; enrollment does not follow redirects`)
+  }
+  if (!response.ok) throw new Error(`${path} failed: HTTP ${response.status}`)
+  return response.json()
+}
+
+function isStart(v: any): v is EnrollStart {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    typeof v.userCode === "string" &&
+    typeof v.deviceCode === "string" &&
+    typeof v.approveURL === "string" &&
+    typeof v.intervalMs === "number" &&
+    typeof v.expiresAt === "number"
+  )
+}
+
+export async function startEnrollment(server: string, machineName: string, options: EnrollOptions = {}): Promise<EnrollStart> {
+  const body = await post(server, "/spoke/enroll", { machineName }, options)
+  if (!isStart(body)) throw new Error("Invalid enrollment reply from the hub")
+  return body
+}
+
+const sleep = (ms: number, signal?: AbortSignal) =>
+  new Promise<void>((resolve) => {
+    const timer = setTimeout(done, ms)
+    function done() {
+      clearTimeout(timer)
+      signal?.removeEventListener("abort", done)
+      resolve()
+    }
+    signal?.addEventListener("abort", done, { once: true })
+  })
+
+/** Polls until approved, denied, expired, or aborted. Transient errors are retried until expiry. */
+export async function pollEnrollment(server: string, start: EnrollStart, options: EnrollOptions = {}): Promise<EnrollOutcome> {
+  const now = options.now ?? Date.now
+  const interval = Math.max(1, start.intervalMs)
+  for (;;) {
+    if (options.signal?.aborted) return { status: "cancelled" }
+    if (now() > start.expiresAt) return { status: "expired" }
+    await sleep(interval, options.signal)
+    if (options.signal?.aborted) return { status: "cancelled" }
+    let reply: Partial<EnrollPoll> & Record<string, unknown>
+    try {
+      reply = (await post(server, "/spoke/enroll/poll", { deviceCode: start.deviceCode }, options, !options.keepRedeemed)) as typeof reply
+    } catch (cause) {
+      if (cause instanceof EnrollmentRefused) throw cause
+      continue
+    }
+    if (reply?.status === "approved" && typeof reply.machineID === "string" && typeof reply.machineToken === "string") {
+      return { status: "approved", machineID: reply.machineID, machineToken: reply.machineToken }
+    }
+    if (reply?.status === "denied" || reply?.status === "expired") return { status: reply.status }
+  }
+}

package/packages/spoke-sdk/src/harness-hello.ts

@@ -0,0 +1,79 @@
+// The hello of a spoke for a harness other than OpenCode (design §1.1, P7-T1): its harness id, version and evidence
+// level, and every feature it serves. Unlike an OpenCode hello it implies nothing: each core op (CORE_OPS) the spoke
+// serves is announced, and the hub sends only announced ops. Refuses what would mislead the hub instead of sending it.
+import { randomBytes } from "node:crypto"
+import {
+  CORE_OPS,
+  EVIDENCE_LEVELS,
+  HARNESS_OPENCODE,
+  KNOWN_SPOKE_FEATURES,
+  type CoreOp,
+  type EvidenceLevel,
+  type Hello,
+  type ProcessKind,
+  type SpokeFeature,
+  type SpokeMode,
+} from "../../protocol/src/index.ts"
+
+export interface HarnessHelloOptions {
+  /** The harness id: a lowercase token (letters, digits, `.`, `_`, `-`), not "opencode". */
+  readonly harness: string
+  readonly harnessVersion: string
+  /** How the spoke observes activity; the hub never treats a session as idle on weaker evidence than it claims. */
+  readonly evidence: EvidenceLevel
+  /** The spoke's own version. */
+  readonly pluginVersion: string
+  readonly directory: string
+  /** The core ops the spoke serves (a hooks spoke may serve "permission" but not "turn"). */
+  readonly ops: readonly CoreOp[]
+  /** The optional features it serves (e.g. "deliver", "sessionTokens"); never a core op. */
+  readonly features?: readonly SpokeFeature[]
+  readonly processID?: string
+  readonly kind?: ProcessKind
+  readonly mode?: SpokeMode
+  readonly pid?: number
+  readonly launchID?: string
+}
+
+/** The hello's harness id rule (as the hub parses it). */
+const HARNESS = /^[a-z0-9][a-z0-9._-]*$/
+const HARNESS_MAX = 64
+const VERSION_MAX = 100
+const CORE: readonly string[] = CORE_OPS
+const KNOWN: readonly string[] = KNOWN_SPOKE_FEATURES
+
+const unique = <T>(values: readonly T[]): T[] => [...new Set(values)]
+
+/** The hello fields (without `t` and `v`, which the connection adds) for a non-OpenCode spoke. Throws on bad options. */
+export function buildHarnessHello(options: HarnessHelloOptions): Omit<Hello, "t" | "v"> {
+  const { harness, harnessVersion, evidence } = options
+  if (harness === HARNESS_OPENCODE) throw new Error("A harness spoke cannot be harness \"opencode\": OpenCode hellos imply every core op; use the OpenCode spoke")
+  if (typeof harness !== "string" || harness.length > HARNESS_MAX || !HARNESS.test(harness)) {
+    throw new Error(`The harness id must be 1–${HARNESS_MAX} lowercase letters, digits, ".", "_" or "-" (got ${JSON.stringify(harness)})`)
+  }
+  if (typeof harnessVersion !== "string" || harnessVersion.length > VERSION_MAX) throw new Error(`The harness version must be text of at most ${VERSION_MAX} characters`)
+  if (!(EVIDENCE_LEVELS as readonly string[]).includes(evidence)) throw new Error(`The evidence level must be one of ${EVIDENCE_LEVELS.join(", ")} (got ${JSON.stringify(evidence)})`)
+  for (const op of options.ops) if (!CORE.includes(op)) throw new Error(`Unknown core op ${JSON.stringify(op)} (core ops: ${CORE_OPS.join(", ")})`)
+  const features = unique(options.features ?? [])
+  for (const feature of features) {
+    if (CORE.includes(feature)) throw new Error(`"${feature}" is a core op: list it in ops, not features`)
+    if (!KNOWN.includes(feature)) throw new Error(`Unknown spoke feature ${JSON.stringify(feature)}`)
+  }
+  if (features.includes("hubPrompt") && !features.includes("deliver")) throw new Error("The hubPrompt feature needs the deliver feature")
+  const ops = CORE_OPS.filter((op) => options.ops.includes(op))
+  return {
+    processID: options.processID ?? `${harness.replace(/[^A-Za-z0-9_-]/g, "_")}_${randomBytes(8).toString("hex")}`,
+    kind: options.kind ?? "service",
+    directory: options.directory,
+    pid: options.pid ?? process.pid,
+    mode: options.mode ?? "always",
+    // Hubs that predate `harness` require opencodeVersion from every spoke (protocol Hello).
+    opencodeVersion: "",
+    pluginVersion: options.pluginVersion,
+    features: [...ops, ...features],
+    harness,
+    harnessVersion,
+    evidence,
+    ...(options.launchID !== undefined ? { launchID: options.launchID } : {}),
+  }
+}