@huynle/hub 0.6.0 → 0.7.1

package/src/spoke/env-inject.ts

@@ -0,0 +1,160 @@
+// Session identity for shells (P1-T6, Brain decision 31swaq28): every shell an agent runs through the shell tool
+// gets HUB_URL and HUB_SESSION_TOKEN for its own session, so `hub` there acts as that session; the hub bin dir
+// (where the spoke writes the `hub`/`hubctl` launchers, P1-T10) goes first on PATH for every shell.
+//
+// OpenCode's `shell.create.before` hook has a mutable env but no sessionID; the tool `execute.before` hook has the
+// sessionID and the command. In the shell tool the two run back to back (execute.before, then Shell.create runs
+// create.before, then the tool's own env tweaks and the permission check), so a shell is matched to the most recent
+// pending shell tool call with the same command. Not used: the OPENCODE_SESSION_ID in the create.before env — the
+// shell tool sets it only after our hook, so at that point it is the server process's inherited one (of the
+// session that started this OpenCode, if any), which would hand out the wrong identity.
+//
+// Fail closed: the same command pending from two different sessions gives neither a token; so does a command that
+// another plugin rewrote in a way we cannot see. Known gap: user `!` commands (session.shell) have no tool call, so
+// they get only the stripped env and PATH, no token.
+import { homedir } from "node:os"
+import path from "node:path"
+import { defaultStateDir } from "./localhub"
+
+type Env = Record<string, string | undefined>
+
+/** What the tool `execute.before`/`execute.after` hooks report (the fields used here). */
+export interface ToolCall {
+  readonly tool: string
+  readonly sessionID: string
+  readonly id: string
+  readonly input: unknown
+}
+
+/** The shell `create.before` invocation (the fields used here). */
+export interface ShellInvocation {
+  readonly command: string
+  env: Env
+}
+
+/** A session's identity for its shells. */
+export interface Identity {
+  readonly token: string
+  readonly url?: string
+}
+
+/** The OpenCode tool names that run a command in a shell. */
+const SHELL_TOOLS = new Set(["shell", "bash"])
+const HUB_VARS = ["HUB_URL", "HUB_SESSION_TOKEN"] as const
+const DEFAULT_PATH = ["/usr/bin", "/bin", "/usr/sbin", "/sbin"]
+
+interface Pending {
+  readonly call: ToolCall
+  readonly at: number
+}
+
+const commandOf = (call: ToolCall): string | undefined => {
+  const input = call.input as { command?: unknown } | null | undefined
+  return input && typeof input === "object" && typeof input.command === "string" ? input.command : undefined
+}
+
+/** Pairs shells with the shell tool calls that create them (see the file comment). */
+export class ShellCorrelator {
+  readonly #pending: Pending[] = []
+  readonly #ttlMs: number
+  readonly #max: number
+  readonly #now: () => number
+
+  constructor(options: { ttlMs?: number; max?: number; now?: () => number } = {}) {
+    this.#ttlMs = options.ttlMs ?? 30_000
+    this.#max = options.max ?? 256
+    this.#now = options.now ?? Date.now
+  }
+
+  /** Remembers a shell tool call (other tools are ignored). */
+  record(call: ToolCall): void {
+    if (!SHELL_TOOLS.has(call.tool) || typeof call.sessionID !== "string" || commandOf(call) === undefined) return
+    this.#prune()
+    this.#pending.push({ call, at: this.#now() })
+    if (this.#pending.length > this.#max) this.#pending.splice(0, this.#pending.length - this.#max)
+  }
+
+  /** Forgets a tool call once it finished (its shell, if any, was created long before). */
+  done(callID: string): void {
+    for (let i = this.#pending.length - 1; i >= 0; i--) if (this.#pending[i]!.call.id === callID) this.#pending.splice(i, 1)
+  }
+
+  /**
+   * The session of the pending shell tool call with this command, consuming it; undefined when none or when calls
+   * from different sessions are pending with it (then all of them are dropped). The command is read now, so input
+   * rewrites by hooks that ran after ours count.
+   */
+  match(command: string): string | undefined {
+    this.#prune()
+    const matches = this.#pending.filter((p) => commandOf(p.call) === command)
+    if (matches.length === 0) return undefined
+    const sessions = new Set(matches.map((p) => p.call.sessionID))
+    if (sessions.size > 1) {
+      for (const p of matches) this.#pending.splice(this.#pending.indexOf(p), 1)
+      return undefined
+    }
+    this.#pending.splice(this.#pending.indexOf(matches[0]!), 1)
+    return matches[0]!.call.sessionID
+  }
+
+  get size(): number {
+    this.#prune()
+    return this.#pending.length
+  }
+
+  #prune(): void {
+    const oldest = this.#now() - this.#ttlMs
+    while (this.#pending.length > 0 && this.#pending[0]!.at <= oldest) this.#pending.shift()
+  }
+}
+
+/** Deletes HUB_URL and HUB_SESSION_TOKEN (an identity inherited from an outer session must never leak). */
+export function stripInheritedHubEnv(env: Env): void {
+  for (const name of HUB_VARS) delete env[name]
+}
+
+/** Strips inherited HUB_*, sets the session's identity when it has one, and puts `binDir` first on PATH once. */
+export function applyHubEnv(env: Env, identity: Identity | undefined, binDir: string): void {
+  stripInheritedHubEnv(env)
+  if (identity) {
+    if (identity.url) env.HUB_URL = identity.url
+    env.HUB_SESSION_TOKEN = identity.token
+  }
+  const rest = env.PATH === undefined ? DEFAULT_PATH : env.PATH.split(path.delimiter).filter((dir) => dir !== binDir)
+  env.PATH = [binDir, ...rest].join(path.delimiter)
+}
+
+/** Where the `hub`/`hubctl` launchers live: bin under the hub state dir ($HUB_STATE_DIR or ~/.local/state/hub). */
+export function hubBinDir(env: Env = process.env, home: string = homedir()): string {
+  return path.join(defaultStateDir(env, home), "bin")
+}
+
+/** The hook handlers: tool execute.before/after and shell create.before. They never throw. */
+export function envInjector(options: { correlator: ShellCorrelator; binDir: string; identity: (sessionID: string) => Identity | undefined }) {
+  const { correlator, binDir, identity } = options
+  return {
+    toolBefore(call: ToolCall): void {
+      try {
+        correlator.record(call)
+      } catch (cause) {
+        console.error("[hub] shell env: could not record a tool call", cause)
+      }
+    },
+    toolAfter(call: ToolCall): void {
+      try {
+        correlator.done(call.id)
+      } catch {
+        // nothing to forget
+      }
+    },
+    shellBefore(invocation: ShellInvocation): void {
+      try {
+        if (!invocation.env || typeof invocation.env !== "object") return
+        const sessionID = typeof invocation.command === "string" ? correlator.match(invocation.command) : undefined
+        applyHubEnv(invocation.env, sessionID ? identity(sessionID) : undefined, binDir)
+      } catch (cause) {
+        console.error("[hub] shell env: could not prepare a shell", cause)
+      }
+    },
+  }
+}

package/src/spoke/hub-rpc.ts

@@ -0,0 +1,115 @@
+// The TUI's /who and /msg, server side (RPC hubWho and hubMsg, registered in src/index.ts): the hub's agent API as
+// the TUI's CURRENT session, through the shared SDK with that session's own token (Spoke.shellIdentity), the same
+// identity the hub tool uses (src/spoke/hub-tool.ts). The token is only sent to the hub; it never appears in a
+// result or an error (redacted should the hub echo it). Labels are sanitised here, so the TUI shows them as is.
+import { HubClient, HubError, HubTransportError, sanitizeLabel, type AgentMessage, type DirectoryEntry } from "../../packages/sdk/src/index.ts"
+import type { HubToolSpoke } from "./hub-tool"
+
+/** The RPC error a failure answers with (src/rpc.ts lists them). */
+export type HubRpcErrorCode = "invalid" | "not_connected" | "unsupported" | "unreachable" | "server_error"
+
+export class HubRpcError extends Error {
+  constructor(
+    readonly code: HubRpcErrorCode,
+    message: string,
+  ) {
+    super(message)
+  }
+}
+
+/** One session in /who (labels sanitised; roles by bare name). */
+export interface WhoRow {
+  readonly sessionID: string
+  readonly name?: string
+  readonly project?: string
+  readonly state?: string
+  readonly online: boolean
+  readonly roles: string[]
+}
+
+export interface MsgResult {
+  readonly id: string
+  /** Who it reached: @name, a session ID, or "the user". */
+  readonly to: string
+  readonly delivery?: string
+}
+
+/** An RPC call waits at most this long for the hub. */
+const TIMEOUT_MS = 15_000
+
+type Input = Record<string, unknown>
+
+const inputOf = (value: unknown): Input => (value && typeof value === "object" ? (value as Input) : {})
+const optStr = (input: Input, key: string) => (typeof input[key] === "string" && (input[key] as string).trim() ? (input[key] as string).trim() : undefined)
+
+/** /msg: sends `text` word for word to `to` as session `sessionID`. */
+export async function hubMsg(spoke: HubToolSpoke, value: unknown): Promise<MsgResult> {
+  const input = inputOf(value)
+  const sessionID = optStr(input, "sessionID")
+  if (!sessionID) throw new HubRpcError("invalid", "Open a session first: /msg sends as the current session.")
+  const to = optStr(input, "to")
+  if (!to) throw new HubRpcError("invalid", "Who should get it? Usage: /msg @name text")
+  const text = input.text
+  if (typeof text !== "string" || !text.trim()) throw new HubRpcError("invalid", "What should the message say? Usage: /msg @name text")
+  return withClient(spoke, sessionID, "messaging", async (client, signal) => {
+    const { message, delivery } = await client.msg(to, text, { signal })
+    return { id: message.id, to: recipientText(message), ...(delivery ? { delivery } : {}) }
+  })
+}
+
+/** /who: the named and role-holding sessions (optionally one project or one role), as session `sessionID`. */
+export async function hubWho(spoke: HubToolSpoke, value: unknown): Promise<{ sessions: WhoRow[] }> {
+  const input = inputOf(value)
+  const sessionID = optStr(input, "sessionID")
+  if (!sessionID) throw new HubRpcError("invalid", "Open a session first: /who asks the hub as the current session.")
+  const project = optStr(input, "project")
+  const role = optStr(input, "role")
+  return withClient(spoke, sessionID, undefined, async (client, signal) => {
+    const { sessions } = await client.who({ ...(project ? { project } : {}), ...(role ? { role } : {}), signal })
+    return { sessions: sessions.map(whoRow) }
+  })
+}
+
+/** Runs `action` with a client holding the session's token; every failure becomes a HubRpcError without the token. */
+async function withClient<T>(
+  spoke: HubToolSpoke,
+  sessionID: string,
+  feature: string | undefined,
+  action: (client: HubClient, signal: AbortSignal) => Promise<T>,
+): Promise<T> {
+  const identity = spoke.shellIdentity(sessionID)
+  if (!identity) throw new HubRpcError("not_connected", "This session has no hub token yet: share it with the hub (/hub) and wait until it is connected.")
+  if (!identity.url) throw new HubRpcError("not_connected", "The hub's URL is not known yet; try again shortly.")
+  if (feature && !spoke.hubSupports(feature)) throw new HubRpcError("unsupported", `The hub this machine is connected to does not support ${feature}; it needs a newer hub.`)
+  const scrub = (text: string) => (identity.token ? text.split(identity.token).join("[redacted]") : text)
+  try {
+    return await action(new HubClient({ url: identity.url, token: identity.token }), AbortSignal.timeout(TIMEOUT_MS))
+  } catch (cause) {
+    if (cause instanceof HubError) {
+      throw new HubRpcError("server_error", scrub(`${cause.message} (${cause.code})${cause.hint ? `. Hint: ${cause.hint}` : ""}`))
+    }
+    if (cause instanceof HubTransportError) throw new HubRpcError("unreachable", scrub(cause.message))
+    throw new HubRpcError("server_error", scrub(cause instanceof Error ? cause.message : String(cause)))
+  }
+}
+
+function whoRow(entry: DirectoryEntry): WhoRow {
+  const name = entry.name ? sanitizeLabel(entry.name) : ""
+  const project = entry.project ? sanitizeLabel(entry.project) : ""
+  const state = entry.state ? sanitizeLabel(entry.state) : ""
+  return {
+    sessionID: sanitizeLabel(entry.sessionID),
+    ...(name ? { name } : {}),
+    ...(project ? { project } : {}),
+    ...(state ? { state } : {}),
+    online: entry.online === true,
+    roles: (entry.roles ?? []).map((r) => sanitizeLabel(r.role)).filter(Boolean),
+  }
+}
+
+function recipientText(message: AgentMessage): string {
+  const r = message.recipient
+  if (r?.kind === "session") return r.name ? `@${sanitizeLabel(r.name)}` : sanitizeLabel(r.sessionID)
+  if (r?.kind === "user") return "the user"
+  return sanitizeLabel(message.to)
+}