@huynle/hub 0.6.0 → 0.7.1

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 } : {}),
+  }
+}

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

@@ -0,0 +1,263 @@
+// HarnessSpoke: the base of a spoke for a harness other than OpenCode (design §1.1, §13.2). It owns the hub
+// connection (SpokeConnection) and does what every such spoke must do the same way:
+//
+// - hello: harness, version, evidence, and exactly the ops it has handlers for (core ops included: a non-OpenCode
+//   hello implies none), so the hub sends only those;
+// - op dispatch: an op (or an op option) it did not announce is refused with a clear error, as is an op for a
+//   session it does not report (a hub that predates announced core ops sends them anyway);
+// - sessions: the sessions frame on every change and after every welcome; with `livenessMs`, a session that
+//   shows no sign of life (upsert, touch, emitted event) for that long is dropped by prune();
+// - emit: only events of the harness subset with valid data (harnessEventProblem), never anything else;
+// - tokens: the session and act tokens the hub sends, in memory, kept apart, for reported sessions only, dropped
+//   when the session ends; no token (nor the machine token) is ever logged, serialised or inspected;
+// - deliver: each hub message admitted once per messageID (DeliveryLedger), whatever the harness does with a retry.
+//
+// Session IDs are hub IDs: map native ones with hubSessionID first.
+import {
+  CORE_OPS,
+  encode,
+  featureForOp,
+  harnessEventProblem,
+  isHubSessionID,
+  parseSpokeMessage,
+  requestFeatures,
+  type HarnessEvent,
+  type ResultFor,
+  type ServerRequest,
+  type SessionInfo,
+  type SessionToken,
+  type SessionTokenSkipReason,
+  type SpokeFeature,
+} from "../../protocol/src/index.ts"
+import { SpokeConnection, type ConnectionOptions, type ConnectionState } from "./connection.ts"
+import { DeliveryLedger, type Admission } from "./delivery.ts"
+import { buildHarnessHello, type HarnessHelloOptions } from "./harness-hello.ts"
+import { SessionTokenStore } from "./session-tokens.ts"
+
+const INSPECT = Symbol.for("nodejs.util.inspect.custom")
+
+type Op = ServerRequest["op"]
+/** Ops the spoke itself serves for every harness (tokens and deliver's idempotency); the rest need a handler. */
+export type HandledOp = Exclude<Op, "sessionTokens" | "actTokens" | "deliver">
+export type OpHandler<O extends HandledOp> = (req: Extract<ServerRequest, { op: O }>) => Promise<ResultFor[O]> | ResultFor[O]
+export type OpHandlers = { readonly [O in HandledOp]?: OpHandler<O> }
+export type DeliverRequest = Extract<ServerRequest, { op: "deliver" }>
+/**
+ * Features that change how an op is served rather than adding one; each needs the op it modifies, except
+ * "turnEvents" (the spoke reports every turn's end as the harness confirms it), which is about events, not an op.
+ */
+export type ModifierFeature = "permissionMessage" | "launch" | "hubPrompt" | "turnEvents"
+
+export interface HarnessSpokeOptions extends Omit<HarnessHelloOptions, "ops" | "features"> {
+  readonly server: string
+  /** The machine token. Sent only as the WebSocket's bearer; never logged or serialised. */
+  readonly token: string
+  readonly handlers?: OpHandlers
+  /** Admits a hub message into a session (feature "deliver"); run once per messageID (DeliveryLedger). */
+  readonly deliver?: (req: DeliverRequest) => Promise<Admission>
+  readonly features?: readonly ModifierFeature[]
+  /** Drop a session after this long without a sign of life (prune); 0 or absent: never. */
+  readonly livenessMs?: number
+  readonly now?: () => number
+  readonly socket?: ConnectionOptions["socket"]
+  readonly backoff?: ConnectionOptions["backoff"]
+  readonly requestTimeoutMs?: number
+  readonly onState?: ConnectionOptions["onState"]
+}
+
+const MODIFIER_NEEDS: Record<ModifierFeature, string | null> = { permissionMessage: "permission", launch: "create", hubPrompt: "deliver", turnEvents: null }
+const ALWAYS: readonly SpokeFeature[] = ["sessionTokens", "actTokens"]
+const CORE: readonly string[] = CORE_OPS
+
+export class HarnessSpoke {
+  /** Every feature the hello announces (core ops first). */
+  readonly features: readonly SpokeFeature[]
+  readonly harness: string
+
+  readonly #handlers: OpHandlers
+  readonly #deliver?: HarnessSpokeOptions["deliver"]
+  readonly #announced: ReadonlySet<string>
+  readonly #connection: SpokeConnection
+  readonly #sessions = new Map<string, { info: SessionInfo; seen: number }>()
+  readonly #livenessMs: number
+  readonly #now: () => number
+  readonly #sessionTokens: SessionTokenStore
+  readonly #actTokens: SessionTokenStore
+  readonly #ledger = new DeliveryLedger()
+
+  constructor(options: HarnessSpokeOptions) {
+    this.harness = options.harness
+    this.#handlers = options.handlers ?? {}
+    this.#deliver = options.deliver
+    this.#livenessMs = options.livenessMs ?? 0
+    this.#now = options.now ?? Date.now
+    this.#sessionTokens = new SessionTokenStore(this.#now)
+    this.#actTokens = new SessionTokenStore(this.#now)
+    const handled = (Object.keys(this.#handlers) as HandledOp[]).filter((op) => typeof this.#handlers[op] === "function")
+    if (handled.includes("modelPrefs") !== handled.includes("setModelPrefs")) throw new Error("The modelPrefs feature needs both a modelPrefs and a setModelPrefs handler")
+    const ops = handled.filter((op) => CORE.includes(op)) as (typeof CORE_OPS)[number][]
+    const served = new Set<string>(handled)
+    if (this.#deliver) served.add("deliver")
+    const modifiers = [...new Set(options.features ?? [])]
+    for (const feature of modifiers) {
+      const needs = MODIFIER_NEEDS[feature]
+      if (needs === undefined || !Object.hasOwn(MODIFIER_NEEDS, feature)) throw new Error(`Unknown modifier feature ${JSON.stringify(feature)}`)
+      if (needs !== null && !served.has(needs)) throw new Error(`The ${feature} feature needs a ${needs} handler`)
+    }
+    const optional = [...new Set(handled.filter((op) => !CORE.includes(op)).map((op) => featureForOp(op)))]
+    const hello = buildHarnessHello({ ...options, ops, features: [...optional, ...(this.#deliver ? ["deliver" as const] : []), ...ALWAYS, ...modifiers] })
+    this.features = hello.features as SpokeFeature[]
+    this.#announced = new Set(this.features)
+    this.#connection = new SpokeConnection({
+      server: options.server,
+      token: options.token,
+      hello: () => hello,
+      handle: (req) => this.dispatch(req),
+      onWelcome: () => this.#sendSessions(),
+      ...(options.onState ? { onState: options.onState } : {}),
+      ...(options.backoff ? { backoff: options.backoff } : {}),
+      ...(options.requestTimeoutMs !== undefined ? { requestTimeoutMs: options.requestTimeoutMs } : {}),
+      ...(options.socket ? { socket: options.socket } : {}),
+    })
+  }
+
+  get state(): ConnectionState {
+    return this.#connection.state
+  }
+
+  start(): void {
+    this.#connection.start()
+  }
+
+  stop(): void {
+    this.#connection.stop()
+  }
+
+  retryNow(): void {
+    this.#connection.retryNow()
+  }
+
+  /** Whether the connected hub announced `feature` in its welcome. */
+  hubSupports(feature: string): boolean {
+    return this.#connection.hubSupports(feature)
+  }
+
+  /** Runs a hub request: refuses unannounced ops and unknown sessions, then calls the op's handler. */
+  async dispatch(req: ServerRequest): Promise<unknown> {
+    for (const feature of requestFeatures(req)) {
+      if (!this.#announced.has(feature)) throw new Error(`The ${this.harness} spoke does not serve "${feature}" (not announced in its hello)`)
+    }
+    if ("sessionID" in req && !this.#sessions.has(req.sessionID)) throw new Error(`Unknown session ${req.sessionID}: this ${this.harness} spoke does not report it`)
+    switch (req.op) {
+      case "sessionTokens":
+        if (req.hubURL !== undefined) this.#sessionTokens.hubURL = req.hubURL
+        return this.#storeTokens(this.#sessionTokens, req.tokens)
+      case "actTokens":
+        return this.#storeTokens(this.#actTokens, req.tokens)
+      case "deliver": {
+        const deliver = this.#deliver!
+        return this.#ledger.run(req.messageID, req.wake, () => deliver(req))
+      }
+    }
+    const handler = this.#handlers[req.op as HandledOp] as ((r: ServerRequest) => unknown) | undefined
+    if (!handler) throw new Error(`The ${this.harness} spoke has no handler for "${req.op}"`)
+    return await handler(req)
+  }
+
+  /** Reports a session (new or changed) and counts as a sign of life. Its IDs must be hub session IDs. */
+  upsertSession(info: SessionInfo): void {
+    if (!isHubSessionID(info?.id)) throw new Error(`Session id must be a hub session ID (ses_ + letters and digits; map native IDs with hubSessionID), got ${JSON.stringify(info?.id)}`)
+    if (info.parentID !== undefined && !isHubSessionID(info.parentID)) throw new Error(`Session parentID must be a hub session ID, got ${JSON.stringify(info.parentID)}`)
+    if (!parseSpokeMessage(encode({ t: "sessions", sessions: [info] }))) throw new Error(`Session ${info.id} is not a valid session for the hub (see the protocol's SessionInfo)`)
+    this.#sessions.set(info.id, { info, seen: this.#now() })
+    this.#sendSessions()
+  }
+
+  /** A sign of life from a session (keeps it from being pruned). */
+  touch(sessionID: string): void {
+    const entry = this.#sessions.get(sessionID)
+    if (entry) entry.seen = this.#now()
+  }
+
+  /** The session ended: it is no longer reported and its tokens are dropped. */
+  endSession(sessionID: string): void {
+    this.#dropTokens(sessionID)
+    if (this.#sessions.delete(sessionID)) this.#sendSessions()
+  }
+
+  /**
+   * The session's current session token (for its shells: `hub` there acts as the session) and the URL they reach
+   * the hub at. Hand it to the harness's process environment only, never to a log.
+   */
+  sessionToken(sessionID: string): { token: string; url?: string } | undefined {
+    const entry = this.#sessionTokens.get(sessionID)
+    if (!entry) return undefined
+    const url = this.#sessionTokens.hubURL ?? this.#connection.publicURL
+    return { token: entry.token, ...(url !== undefined ? { url } : {}) }
+  }
+
+  /** The session's act token (act verbs only; never in any environment) and the hub's URL. */
+  actToken(sessionID: string): { token: string; url: string } | undefined {
+    const entry = this.#actTokens.get(sessionID)
+    const url = this.#sessionTokens.hubURL ?? this.#connection.publicURL
+    return entry && url !== undefined ? { token: entry.token, url } : undefined
+  }
+
+  toJSON(): { harness: string; state: ConnectionState; sessions: number; features: readonly SpokeFeature[] } {
+    return { harness: this.harness, state: this.state, sessions: this.#sessions.size, features: this.features }
+  }
+
+  toString(): string {
+    return `HarnessSpoke(${this.harness}, ${this.state}, ${this.#sessions.size} sessions)`
+  }
+
+  [INSPECT](): string {
+    return this.toString()
+  }
+
+  sessions(): SessionInfo[] {
+    return [...this.#sessions.values()].map((e) => e.info)
+  }
+
+  /** Drops sessions without a sign of life for livenessMs (none when it is 0); returns their IDs. */
+  prune(): string[] {
+    if (this.#livenessMs <= 0) return []
+    const cutoff = this.#now() - this.#livenessMs
+    const dropped = [...this.#sessions].filter(([, e]) => e.seen < cutoff).map(([id]) => id)
+    for (const id of dropped) {
+      this.#sessions.delete(id)
+      this.#dropTokens(id)
+    }
+    if (dropped.length) this.#sendSessions()
+    return dropped
+  }
+
+  /** Sends a harness event (T1 subset, validated); throws on an invalid one. False when it could not be sent. */
+  emit(event: HarnessEvent): boolean {
+    const problem = harnessEventProblem(event)
+    if (problem) throw new Error(`Invalid harness event${typeof (event as { type?: unknown })?.type === "string" ? ` ${(event as { type: string }).type}` : ""}: ${problem}`)
+    const sessionID = (event.data as { sessionID?: unknown }).sessionID
+    if (typeof sessionID === "string") this.touch(sessionID)
+    return this.#connection.send({ t: "event", event })
+  }
+
+  #storeTokens(store: SessionTokenStore, tokens: readonly SessionToken[]): ResultFor["sessionTokens"] {
+    const applied: string[] = []
+    const skipped: { sessionID: string; reason: SessionTokenSkipReason }[] = []
+    for (const { sessionID, token, exp } of tokens) {
+      if (!this.#sessions.has(sessionID)) skipped.push({ sessionID, reason: "unknown" })
+      else if (store.set(sessionID, token, exp)) applied.push(sessionID)
+      else skipped.push({ sessionID, reason: "expired" })
+    }
+    return { applied, skipped }
+  }
+
+  #dropTokens(sessionID: string): void {
+    this.#sessionTokens.delete(sessionID)
+    this.#actTokens.delete(sessionID)
+  }
+
+  #sendSessions(): void {
+    this.#connection.send({ t: "sessions", sessions: this.sessions() })
+  }
+}

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

@@ -0,0 +1,12 @@
+// @huynle/hub-spoke-sdk: the harness-neutral parts of a hub spoke (design §13.3). Imports only the protocol and SDK
+// packages, never the hub (src/central) or the OpenCode spoke (src/spoke).
+export * from "./activity.ts"
+export * from "./connection.ts"
+export * from "./delivery.ts"
+export * from "./enroll.ts"
+export * from "./prompt-refs.ts"
+export * from "./prompt-source.ts"
+export * from "./session-tokens.ts"
+export * from "./session-ids.ts"
+export * from "./harness-hello.ts"
+export * from "./harness-spoke.ts"

package/packages/spoke-sdk/src/prompt-refs.ts

@@ -0,0 +1,154 @@
+// Prompt references (design §2.4): hub addresses typed into a prompt get context, never routing. Finding the
+// addresses, resolving them against what the hub reports, and rendering the context note are harness-neutral;
+// how the note reaches the model (OpenCode: an inline text file on the prompt) is the spoke's.
+import { parseAddress, sanitizeLabel, type AgentMessage, type DirectoryEntry, type Status } from "../../sdk/src/index.ts"
+
+export interface Mention {
+  readonly start: number
+  readonly end: number
+  readonly text: string
+}
+
+export interface PromptLike {
+  readonly text: string
+  readonly files?: readonly { readonly uri?: string; readonly name?: string; readonly mention?: Mention }[]
+  readonly agents?: readonly { readonly name: string; readonly mention?: Mention }[]
+  readonly skills?: readonly { readonly name?: string; readonly mention?: Mention }[]
+}
+
+/**
+ * `@name`, `@name.project`, `@@role`, `@@role.project`: names and roles are 2–40 lowercase letters, digits and
+ * dashes (packages/sdk/src/address.ts); not part of a word, email or path, and not followed by one.
+ */
+const ADDRESS = /(?<![\w@./\\-])(@@?)([a-z0-9-]{2,40})(?:\.([A-Za-z0-9_-]+))?(?![\w@/\\-]|\.[\w/\\-])/g
+
+/** The user's own address (not a session). */
+const SELF = "me"
+
+/** The hub addresses a prompt mentions, once each, in order; those the harness already gave a meaning are skipped. */
+export function findReferences(prompt: PromptLike): string[] {
+  const text = typeof prompt?.text === "string" ? prompt.text : ""
+  if (!text.includes("@")) return []
+  const mentions = [...(prompt.files ?? []), ...(prompt.agents ?? []), ...(prompt.skills ?? [])].map((m) => m?.mention).filter((m): m is Mention => !!m)
+  const agentNames = new Set((prompt.agents ?? []).map((a) => a?.name).filter(Boolean))
+  const found: string[] = []
+  for (const match of text.matchAll(ADDRESS)) {
+    const [token, ats, name] = match as unknown as [string, string, string]
+    const start = match.index ?? 0
+    const end = start + token.length
+    const role = ats === "@@"
+    if (!role && name === SELF) continue
+    if (mentions.some((m) => m.start < end && m.end > start)) continue
+    if (!role && (agentNames.has(name) || mentions.some((m) => m.text === token || m.text === `@${name}`))) continue
+    if (!found.includes(token)) found.push(token)
+  }
+  return found
+}
+
+/** What the hub told this session (who, status, inbox waiting), fetched once per lookup. */
+export interface ReferenceSnapshot {
+  readonly who: readonly DirectoryEntry[]
+  readonly status?: Status
+  /** The session's own open asks (inbox waiting). */
+  readonly waiting?: readonly AgentMessage[]
+}
+
+export interface ReferencedSession {
+  readonly sessionID: string
+  readonly name?: string
+  readonly harness?: string
+  readonly machine?: string
+  readonly project?: string
+  readonly state: string
+  /** Open asks from the prompting session to this one. */
+  readonly openAsks: number
+  /** The prompting session itself. */
+  readonly self: boolean
+}
+
+export interface Reference {
+  readonly address: string
+  readonly sessions: readonly ReferencedSession[]
+}
+
+/** The same scope rule as the hub's directory: a claim's project, else the session's project. */
+const inScope = (claim: string | undefined, session: string | undefined, wanted: string | undefined) =>
+  wanted === undefined || claim === wanted || (claim === undefined && session === wanted)
+
+/** The sessions each address names in the snapshot (the caller's own world); unknown addresses are dropped. */
+export function resolveReferences(addresses: readonly string[], snapshot: ReferenceSnapshot, self: string): Reference[] {
+  const live = new Map<string, { state: string; harness?: string }>()
+  const machines = new Map<string, string>()
+  for (const machine of snapshot.status?.machines ?? []) {
+    if (machine.name) machines.set(machine.id, machine.name)
+    for (const project of machine.projects) for (const s of project.sessions) live.set(s.id, { state: s.state, ...(s.harness ? { harness: s.harness } : {}) })
+  }
+  const asks = new Map<string, number>()
+  for (const m of snapshot.waiting ?? []) {
+    if (m.state !== "open" || m.recipient?.kind !== "session") continue
+    asks.set(m.recipient.sessionID, (asks.get(m.recipient.sessionID) ?? 0) + 1)
+  }
+  const view = (e: DirectoryEntry): ReferencedSession => {
+    const now = live.get(e.sessionID)
+    const machine = e.machineID ? machines.get(e.machineID) : undefined
+    return {
+      sessionID: e.sessionID,
+      ...(e.name ? { name: e.name } : {}),
+      ...(now?.harness ? { harness: now.harness } : {}),
+      ...(machine ? { machine } : {}),
+      ...(e.project ? { project: e.project } : {}),
+      state: now?.state ?? (e.online ? (e.state ?? "online") : "offline"),
+      openAsks: asks.get(e.sessionID) ?? 0,
+      self: e.sessionID === self,
+    }
+  }
+  const out: Reference[] = []
+  for (const address of addresses) {
+    const parsed = parseAddress(address)
+    if (!parsed || parsed.kind === "id") continue
+    const matches = snapshot.who.filter((e) =>
+      parsed.kind === "name"
+        ? (e.name === parsed.name || (e.aliases ?? []).includes(parsed.name)) && (parsed.project === undefined || e.project === parsed.project)
+        : e.roles.some((r) => r.role === parsed.role && inScope(r.project, e.project, parsed.project)),
+    )
+    if (matches.length) out.push({ address, sessions: matches.map(view) })
+  }
+  return out
+}
+
+const clean = (value: string | undefined) => (value === undefined ? "" : sanitizeLabel(value))
+
+function details(s: ReferencedSession): string[] {
+  return [clean(s.harness), clean(s.machine), s.project ? `project ${clean(s.project)}` : ""].filter(Boolean)
+}
+
+function tail(s: ReferencedSession): string {
+  const asks = s.openAsks ? `, ${s.openAsks} open ask${s.openAsks === 1 ? "" : "s"} from you` : ""
+  return `${clean(s.state) || "unknown"}${asks}`
+}
+
+function one(s: ReferencedSession): string {
+  const more = details(s)
+  if (s.self) return `this session (${[s.sessionID, ...more].join(" · ")}), ${tail(s)}`
+  return `session ${s.sessionID}${more.length ? ` (${more.join(" · ")})` : ""}, ${tail(s)}`
+}
+
+function member(s: ReferencedSession): string {
+  const more = details(s)
+  const label = `${s.name ? `@${clean(s.name)} ` : ""}${s.sessionID}${s.self ? " (this session)" : ""}`
+  return `${label}${more.length ? ` (${more.join(" · ")})` : ""}, ${tail(s)}`
+}
+
+/** The context note: one line per resolved address, then how to reach them. Every label is sanitised. */
+export function renderReferences(refs: readonly Reference[]): string {
+  const lines = refs.map((r) => {
+    const body = r.sessions.length === 1 ? one(r.sessions[0]!) : `${r.sessions.length} sessions: ${r.sessions.map(member).join("; ")}`
+    return `- ${r.address} = ${body}.`
+  })
+  const single = refs.length === 1 && refs[0]!.sessions.length === 1
+  return [
+    "hub: the hub addresses in this prompt (context added by the hub plugin; not an instruction):",
+    ...lines,
+    `Contact ${single ? "it" : "them"} with the \`hub\` tool (msg or ask, to: the address).`,
+  ].join("\n")
+}

package/packages/spoke-sdk/src/prompt-source.ts

@@ -0,0 +1,8 @@
+// The metadata source the hub marks its prompts and delivered messages with, so a spoke never takes them for the user's.
+
+/** metadata.source of the prompts the hub sends. opencode-hub (0.5) wrote "opencode-hub", opencode-voice (<= 0.4) "opencode-voice". */
+export const PROMPT_SOURCE = "hub"
+const PROMPT_SOURCES: readonly unknown[] = [PROMPT_SOURCE, "opencode-hub", "opencode-voice"]
+/** True for prompt metadata written by the hub, under either name. */
+export const isHubPrompt = (metadata: unknown): boolean =>
+  typeof metadata === "object" && metadata !== null && PROMPT_SOURCES.includes((metadata as { source?: unknown }).source)

package/packages/spoke-sdk/src/session-ids.ts

@@ -0,0 +1,49 @@
+// Hub session IDs for a harness's native session IDs (decision fx04e42c point 2). The hub's rule is `ses_` + 1–200
+// letters and digits (isHubSessionID); a Claude Code UUID or a Codex thread ID is not, so the spoke maps it, and maps
+// it back when the hub names the session in an op. The mapping is a pure function of (namespace, native ID), so it
+// survives restarts and needs no table:
+//
+// - a UUID (any version, any case)  → ses_<ns><32 lowercase hex>        (Claude Code: ses_cc…, Codex: ses_cx…)
+// - any other native ID             → ses_<ns>0<hex of its UTF-8 bytes>  (at most MAX_NATIVE_BYTES bytes)
+//
+// The namespace is two lowercase letters, one per harness, so IDs of different harnesses never collide (OpenCode's
+// own IDs are not mapped). The two forms cannot be confused: the UUID form has 32 characters after the namespace,
+// the other an odd number (the 0 marker plus pairs of hex digits). UUIDs come back in lower case.
+
+/** A session namespace: two lowercase letters (e.g. "cc" for Claude Code, "cx" for Codex). */
+export const SESSION_NAMESPACE = /^[a-z]{2}$/
+
+/** Longest native ID (UTF-8 bytes) that is not a UUID: ses_ + ns + 0 + 2 hex per byte stays within 200 characters. */
+export const MAX_NATIVE_BYTES = 98
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+const UUID_HEX = /^[0-9a-f]{32}$/
+const OTHER_HEX = /^0((?:[0-9a-f]{2})+)$/
+
+function checkNamespace(ns: string): void {
+  if (typeof ns !== "string" || !SESSION_NAMESPACE.test(ns)) throw new Error(`Session namespace must be two lowercase letters (got ${JSON.stringify(ns)})`)
+}
+
+/** The hub session ID for a native session ID in namespace `ns`. Throws on a bad namespace or an unmappable ID. */
+export function hubSessionID(ns: string, nativeID: string): string {
+  checkNamespace(ns)
+  if (typeof nativeID !== "string" || nativeID === "") throw new Error("Native session ID is empty")
+  if (UUID.test(nativeID)) return `ses_${ns}${nativeID.replace(/-/g, "").toLowerCase()}`
+  const bytes = Buffer.from(nativeID, "utf8")
+  if (bytes.length > MAX_NATIVE_BYTES) throw new Error(`Native session ID is too long (${bytes.length} bytes, at most ${MAX_NATIVE_BYTES})`)
+  return `ses_${ns}0${bytes.toString("hex")}`
+}
+
+/** The native session ID a hub session ID in namespace `ns` stands for; undefined when it is not one of them. */
+export function nativeSessionID(ns: string, hubID: string): string | undefined {
+  if (typeof ns !== "string" || !SESSION_NAMESPACE.test(ns) || typeof hubID !== "string") return undefined
+  const prefix = `ses_${ns}`
+  if (!hubID.startsWith(prefix)) return undefined
+  const rest = hubID.slice(prefix.length)
+  if (UUID_HEX.test(rest)) return `${rest.slice(0, 8)}-${rest.slice(8, 12)}-${rest.slice(12, 16)}-${rest.slice(16, 20)}-${rest.slice(20)}`
+  const other = OTHER_HEX.exec(rest)
+  if (!other || other[1]!.length / 2 > MAX_NATIVE_BYTES) return undefined
+  const native = Buffer.from(other[1]!, "hex").toString("utf8")
+  // Only IDs hubSessionID makes: valid UTF-8 that round-trips, and not a UUID (those use the short form).
+  return native !== "" && !UUID.test(native) && hubSessionID(ns, native) === hubID ? native : undefined
+}

package/packages/spoke-sdk/src/session-tokens.ts

@@ -0,0 +1,78 @@
+// The session tokens the hub sent this spoke (sessionTokens op), one per session, kept in memory only. The spoke
+// hands a session's current token to its shells (P1-T6, plugin hooks), so `hub` there acts as that session.
+// A newer token replaces the older one; expired ones are dropped when read. Tokens never appear in JSON, inspect
+// or string output, so logging the store (or an object holding it) cannot leak them.
+
+export interface StoredSessionToken {
+  readonly token: string
+  /** Expiry, ms since the epoch. */
+  readonly exp: number
+}
+
+const INSPECT = Symbol.for("nodejs.util.inspect.custom")
+
+export class SessionTokenStore {
+  /** The URL the sessions' shells reach the hub at, as the hub last sent it. */
+  hubURL?: string
+  readonly #tokens = new Map<string, StoredSessionToken>()
+  readonly #now: () => number
+
+  constructor(now: () => number = Date.now) {
+    this.#now = now
+  }
+
+  /** Stores the session's token, replacing its older one; false (nothing stored) when `exp` has passed. */
+  set(sessionID: string, token: string, exp: number): boolean {
+    if (exp <= this.#now()) return false
+    this.#tokens.set(sessionID, { token, exp })
+    return true
+  }
+
+  /** The session's current token, or undefined when it has none or it expired (then it is dropped). */
+  get(sessionID: string): StoredSessionToken | undefined {
+    const entry = this.#tokens.get(sessionID)
+    if (!entry) return undefined
+    if (entry.exp > this.#now()) return entry
+    this.#tokens.delete(sessionID)
+    return undefined
+  }
+
+  /** Sessions holding an unexpired token. */
+  sessions(): string[] {
+    this.prune()
+    return [...this.#tokens.keys()]
+  }
+
+  get size(): number {
+    this.prune()
+    return this.#tokens.size
+  }
+
+  /** Drops expired tokens. */
+  prune(): void {
+    const now = this.#now()
+    for (const [sessionID, entry] of this.#tokens) if (entry.exp <= now) this.#tokens.delete(sessionID)
+  }
+
+  delete(sessionID: string): void {
+    this.#tokens.delete(sessionID)
+  }
+
+  /** Forgets every token and the hub URL. */
+  clear(): void {
+    this.#tokens.clear()
+    this.hubURL = undefined
+  }
+
+  toJSON(): { sessions: number; hubURL?: string } {
+    return { sessions: this.size, ...(this.hubURL !== undefined ? { hubURL: this.hubURL } : {}) }
+  }
+
+  toString(): string {
+    return `SessionTokenStore(${this.size} sessions)`
+  }
+
+  [INSPECT](): string {
+    return this.toString()
+  }
+}