@huynle/hub 0.7.3 → 0.8.0

package/src/spoke/profile-apply.ts

@@ -0,0 +1,298 @@
+// The OpenCode profile application adapter (HWA-16; contract packages/protocol/src/profiles.ts, SDK rules in
+// packages/spoke-sdk/src/profile-apply.ts). A hub profile becomes a session-scoped layer held in this process's
+// memory only; nothing is written to disk and no OpenCode configuration (global or project) is touched:
+//
+// - Instructions: the plugin's `context` hook appends them to the session's system prompt after OpenCode's own
+//   parts (which carry AGENTS.md and the user's config), framed by profileInstructionsBlock: local instructions win.
+// - Skills and commands: listed in that system part and served by the `hub_profile` tool (registered once per
+//   process like the `hub` tool; the context hook hides it from sessions without a profile, and it answers only
+//   the calling session's layer). OpenCode's skill/command registries are location-wide, so they are not used.
+//   Same-named local skills/commands win (partial). Commands that reference `{{secret:NAME}}` are skipped: a
+//   rendered command becomes a persisted prompt or tool result in OpenCode, and resolved secrets must never be
+//   written (renderAtInvocation false). The model preference is ignored (the user's model is never switched).
+// - Next-turn boundary: an idle session's layer is replaced at once (its next turn reads it). For a busy session
+//   the new layer is staged, the running turn keeps the previous one, and the answer waits for the turn to end
+//   (Spoke.observe calls settle; a poll backs it up). The answer echoes exactly the version that became
+//   effective. A wait past boundaryWaitMs fails: the hub, which times out first, keeps the pin pending and sends it
+//   again on the spoke's next sessions frame, which is answered from the then-effective layer. A newer version
+//   staged before the boundary supersedes the older one, which is answered `rejected`.
+// - Rollback: a failed or unsupported apply leaves the effective layer as it was; re-pinning an older version
+//   replaces the layer with it. There is no remove op in v1 (an empty version clears the layer).
+// - Bounded: at most maxSessions layers (oldest dropped; the hub re-sends after a reconnect), notes bounded by the
+//   SDK. Lost on process restart: the new connection's sessions frame makes the hub send the pin again.
+import { isObj } from "../../packages/protocol/src/wire.ts"
+import { type ProfileApplyRequest, type ProfileApplyResult, type ProfileCommand, type ProfileSkill, profileTemplateParts } from "../../packages/protocol/src/index.ts"
+import { boundedNotes, planProfileApplication, profileApplyResult, profileDigest, type ProfileLocalNames, renderProfileCommand } from "../../packages/spoke-sdk/src/profile-apply.ts"
+
+export const PROFILE_TOOL = "hub_profile"
+
+export const PROFILE_TOOL_DESCRIPTION =
+  "Use this session's hub agent profile: {skill: name} returns a profile skill's instructions; " +
+  "{command: name, params: {name: value}} returns a profile command's text with its parameters filled in, to follow as the user's request. " +
+  "Only the skills and commands listed in the hub profile section of your instructions exist."
+
+export const PROFILE_TOOL_INPUT = {
+  type: "object",
+  properties: {
+    skill: { type: "string", description: "A profile skill's name." },
+    command: { type: "string", description: "A profile command's name." },
+    params: { type: "object", additionalProperties: { type: "string" }, description: "The command's parameters (each {{name}} in it; `arguments` for free text)." },
+  },
+  additionalProperties: false,
+} as const
+
+export interface OpenCodeProfilesOptions {
+  /** The session has a turn running (OpenCode busy, or a hub turn in progress). */
+  readonly isBusy: (sessionID: string) => boolean
+  /** The session's local skill and command names; absent: skills and commands are not applied. */
+  readonly localNames?: (sessionID: string) => Promise<ProfileLocalNames>
+  /** The hub_profile tool is available in this OpenCode. */
+  readonly tool: () => boolean
+  /** How long a busy session's answer waits for the boundary (default 120 s). */
+  readonly boundaryWaitMs?: number
+  /** How often a waiting answer checks the session (default 1 s). */
+  readonly pollMs?: number
+  /** Sessions with a layer kept (default 1000). */
+  readonly maxSessions?: number
+}
+
+export interface ProfileEffectiveLayer {
+  readonly profileID: string
+  readonly version: number
+  readonly digest: string
+  readonly status: ProfileApplyResult["status"]
+}
+
+interface Layer {
+  readonly result: ProfileApplyResult
+  readonly instructions?: string
+  readonly skills: readonly ProfileSkill[]
+  readonly commands: readonly ProfileCommand[]
+}
+
+interface Waiter {
+  readonly resolve: (result: ProfileApplyResult) => void
+  readonly reject: (cause: Error) => void
+}
+
+interface Staged {
+  readonly layer: Layer
+  readonly waiters: Set<Waiter>
+  poll?: ReturnType<typeof setInterval>
+}
+
+/** A final answer, or one waiting for the boundary (its waiter is registered before staging returns). */
+type Step = { readonly result: ProfileApplyResult } | { readonly pending: Promise<ProfileApplyResult> }
+
+const sameVersion = (a: ProfileApplyResult, req: ProfileApplyRequest) => a.profileID === req.profileID && a.version === req.version && a.digest === req.digest
+
+export class OpenCodeProfiles {
+  private readonly layers = new Map<string, Layer>()
+  private readonly staged = new Map<string, Staged>()
+  private readonly locks = new Map<string, Promise<void>>()
+
+  constructor(private readonly options: OpenCodeProfilesOptions) {}
+
+  /** The profileApply op: answers once the version is effective in the session (see the header). */
+  async handle(req: ProfileApplyRequest): Promise<ProfileApplyResult> {
+    if (profileDigest(req.content) !== req.digest) return profileApplyResult(req, "rejected", ["digest does not match the content; nothing applied"])
+    const step = await this.serialize(req.sessionID, () => this.stage(req))
+    return "pending" in step ? step.pending : step.result
+  }
+
+  /** A turn boundary may have passed: makes a staged layer effective when the session is not busy. */
+  settle(sessionID: string): void {
+    const staged = this.staged.get(sessionID)
+    if (!staged || this.options.isBusy(sessionID)) return
+    this.dropStaged(sessionID, staged)
+    this.setLayer(sessionID, staged.layer)
+    for (const waiter of staged.waiters) waiter.resolve(staged.layer.result)
+  }
+
+  /** The version the session runs now, if any. */
+  effective(sessionID: string): ProfileEffectiveLayer | undefined {
+    const layer = this.layers.get(sessionID)
+    if (!layer) return undefined
+    const { profileID, version, digest, status } = layer.result
+    return { profileID, version, digest, status }
+  }
+
+  /** System prompt parts for the session's next model request (after local instructions). */
+  systemParts(sessionID: string): string[] {
+    const layer = this.layers.get(sessionID)
+    if (!layer) return []
+    const parts: string[] = []
+    if (layer.instructions !== undefined) parts.push(layer.instructions)
+    if (layer.skills.length || layer.commands.length) parts.push(bindingsText(layer))
+    return parts
+  }
+
+  /** Whether the session's model sees the hub_profile tool. */
+  toolVisible(sessionID: string): boolean {
+    const layer = this.layers.get(sessionID)
+    return layer !== undefined && (layer.skills.length > 0 || layer.commands.length > 0)
+  }
+
+  /** The hub_profile tool for the calling session: a skill's body or a command's rendered text, or why not. */
+  runTool(sessionID: string, input: unknown): string {
+    const value = isObj(input) ? input : {}
+    const skill = typeof value.skill === "string" ? value.skill : undefined
+    const command = typeof value.command === "string" ? value.command : undefined
+    if (skill === undefined && command === undefined) return "Give a skill or command name of this session's hub profile."
+    const layer = this.layers.get(sessionID)
+    if (!layer) return "This session has no hub profile."
+    if (skill !== undefined) {
+      const found = layer.skills.find((s) => s.name === skill)
+      return found ? `Skill ${found.name} (hub profile ${layer.result.profileID} v${layer.result.version}):\n\n${found.body}` : `This session has no hub profile skill named ${skill}.`
+    }
+    const found = layer.commands.find((c) => c.name === command)
+    if (!found) return `This session has no hub profile command named ${command}.`
+    const params = isObj(value.params) ? value.params : {}
+    if (!Object.values(params).every((v) => typeof v === "string")) return `Command ${found.name}: every parameter must be text.`
+    try {
+      // Commands with secret references are never in a layer, so no secret is ever resolved here.
+      return renderProfileCommand(found.template, params as Record<string, string>, () => undefined)
+    } catch (cause) {
+      return `Command ${found.name} could not be run: ${cause instanceof Error ? cause.message : String(cause)}`
+    }
+  }
+
+  /** The session ended: drops its layer and fails an answer still waiting for its boundary. */
+  forget(sessionID: string): void {
+    this.layers.delete(sessionID)
+    const staged = this.staged.get(sessionID)
+    if (!staged) return
+    this.dropStaged(sessionID, staged)
+    for (const waiter of staged.waiters) waiter.reject(new Error("the session ended before the profile took effect"))
+  }
+
+  // ---------- internals ----------
+
+  private async stage(req: ProfileApplyRequest): Promise<Step> {
+    const { sessionID } = req
+    const staged = this.staged.get(sessionID)
+    if (staged && sameVersion(staged.layer.result, req)) return { pending: this.wait(sessionID, staged) }
+    const current = this.layers.get(sessionID)
+    if (current && sameVersion(current.result, req)) {
+      this.supersede(sessionID, req)
+      return { result: current.result }
+    }
+    let local: ProfileLocalNames | undefined
+    if (this.options.localNames) {
+      try {
+        local = await this.options.localNames(sessionID)
+      } catch {
+        return { result: profileApplyResult(req, "rejected", ["could not read the session's local skills and commands (they take precedence); nothing applied"]) }
+      }
+    }
+    const bindings = this.options.tool() && local !== undefined
+    const plan = planProfileApplication(req, {
+      capabilities: { instructions: true, skills: bindings, commands: bindings, model: false, live: true, renderAtInvocation: false },
+      ...(local ? { local } : {}),
+    })
+    const result = profileApplyResult(req, plan.status, plan.notes)
+    if (plan.status === "unsupported") return { result }
+    const layer: Layer = { result, ...(plan.instructions !== undefined ? { instructions: plan.instructions } : {}), skills: plan.skills, commands: plan.commands }
+    this.supersede(sessionID, req)
+    if (!this.options.isBusy(sessionID)) {
+      this.setLayer(sessionID, layer)
+      return { result }
+    }
+    const next: Staged = { layer, waiters: new Set() }
+    this.staged.set(sessionID, next)
+    return { pending: this.wait(sessionID, next) }
+  }
+
+  /** Waits for the staged layer's boundary, at most boundaryWaitMs. */
+  private wait(sessionID: string, staged: Staged): Promise<ProfileApplyResult> {
+    const pending = new Promise<ProfileApplyResult>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        staged.waiters.delete(waiter)
+        if (!staged.waiters.size) this.stopPoll(staged)
+        const { profileID, version } = staged.layer.result
+        reject(new Error(`the session is still busy; profile ${profileID} v${version} is staged and takes effect at its next turn boundary`))
+      }, this.options.boundaryWaitMs ?? 120_000)
+      unref(timer)
+      const waiter: Waiter = {
+        resolve: (result) => (clearTimeout(timer), resolve(result)),
+        reject: (cause) => (clearTimeout(timer), reject(cause)),
+      }
+      staged.waiters.add(waiter)
+      if (!staged.poll) {
+        staged.poll = setInterval(() => this.settle(sessionID), this.options.pollMs ?? 1000)
+        unref(staged.poll)
+      }
+    })
+    pending.catch(() => {}) // handled by handle(); the waiter may fail before it is awaited
+    return pending
+  }
+
+  /** A staged layer for another version is answered rejected: `req` replaces it before it took effect. */
+  private supersede(sessionID: string, req: ProfileApplyRequest): void {
+    const staged = this.staged.get(sessionID)
+    if (!staged) return
+    this.dropStaged(sessionID, staged)
+    const { profileID, version, digest } = staged.layer.result
+    const note = `superseded by profile ${req.profileID} v${req.version} before it took effect at the next turn boundary`
+    const result: ProfileApplyResult = { sessionID, profileID, version, digest, status: "rejected", notes: boundedNotes([note]) }
+    for (const waiter of staged.waiters) waiter.resolve(result)
+  }
+
+  private dropStaged(sessionID: string, staged: Staged): void {
+    if (this.staged.get(sessionID) === staged) this.staged.delete(sessionID)
+    this.stopPoll(staged)
+  }
+
+  private stopPoll(staged: Staged): void {
+    if (staged.poll) clearInterval(staged.poll)
+    staged.poll = undefined
+  }
+
+  private setLayer(sessionID: string, layer: Layer): void {
+    this.layers.delete(sessionID)
+    this.layers.set(sessionID, layer)
+    while (this.layers.size > (this.options.maxSessions ?? 1000)) this.layers.delete(this.layers.keys().next().value!)
+  }
+
+  /** Runs one session's staging steps one at a time (waiting for a boundary is outside). */
+  private serialize<T>(sessionID: string, run: () => Promise<T>): Promise<T> {
+    const previous = this.locks.get(sessionID) ?? Promise.resolve()
+    const next = previous.then(run)
+    const tail = next.then(
+      () => undefined,
+      () => undefined,
+    )
+    this.locks.set(sessionID, tail)
+    void tail.then(() => {
+      if (this.locks.get(sessionID) === tail) this.locks.delete(sessionID)
+    })
+    return next
+  }
+}
+
+/** The system part that lists the session's profile skills and commands (names, descriptions, parameters). */
+function bindingsText(layer: Layer): string {
+  const { profileID, version } = layer.result
+  const lines = [
+    `Hub profile ${profileID} v${version} adds skills and commands to this session only, through the ${PROFILE_TOOL} tool. Local skills and commands of the same name take precedence and are not listed.`,
+  ]
+  if (layer.skills.length) {
+    lines.push("", `Profile skills (load one with ${PROFILE_TOOL} {"skill": name} before following it):`)
+    for (const skill of layer.skills) lines.push(`- ${skill.name}: ${oneLine(skill.description)}`)
+  }
+  if (layer.commands.length) {
+    lines.push("", `Profile commands (when the user asks for /name or the command by name, call ${PROFILE_TOOL} {"command": name, "params": {...}} and follow the text it returns):`)
+    for (const command of layer.commands) {
+      const parts = profileTemplateParts(command.template)
+      const params = typeof parts === "string" ? [] : [...new Set(parts.flatMap((p) => ("param" in p ? [p.param] : [])))]
+      lines.push(`- ${command.name}${params.length ? ` (params: ${params.join(", ")})` : ""}: ${oneLine(command.description)}`)
+    }
+  }
+  return lines.join("\n")
+}
+
+const oneLine = (text: string) => text.replace(/\s+/g, " ").trim()
+
+function unref(timer: ReturnType<typeof setTimeout>): void {
+  ;(timer as { unref?: () => void }).unref?.()
+}

package/src/spoke/session-context.ts

@@ -0,0 +1,176 @@
+// CON-04 session contexts (spoke feature "sessionContext"; contract packages/protocol/src/concierge.ts). The hub pushes
+// a session's per-turn context; the spoke keeps it in this process's memory (like profile layers, profile-apply.ts):
+//
+// - parts: appended by the plugin's context hook after the profile parts, in key order (instructions, board,
+//   notes). The whole set replaces the previous one.
+// - tools.allow: the exact tool names the session keeps; the hook deletes every other tool on every turn (unknown
+//   future tools included: fail closed). tools.deny: globs of tool names deleted as well.
+// - Revisions: an older revision than the effective one is refused ("stale"); the same one is answered again.
+//   `clear` drops the parts. At most maxSessions contexts are kept (the least recently set dropped); lost on a
+//   process restart, after which the hub sends them again (the session reports no contextRevision).
+//
+// LOCKED sessions (the Concierge's, R1 of the CON-04 verify): a context with lockAgent locks its session for good.
+// A locked session, WHATEVER agent it runs on and with or without a context (cleared, or not re-sent yet after a
+// restart), keeps only CONCIERGE_TOOLS (intersected with its context's allow-list), never gets conversation mode,
+// voice style or orchestrator parts. Locks survive `clear`, the context bound and a restart: they are persisted in
+// the plugin's state dir (lockFile), so a restarted OpenCode locks the session before the hub reconnects. The agent
+// a locked session was last seen on is reported to the hub (SessionInfo.agent), which suspends a Concierge found on
+// another agent.
+import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs"
+import path from "node:path"
+import { CONCIERGE_TOOLS, SESSION_CONTEXT_KEYS, type SessionContextRequest, type SessionContextResult, toolDenied } from "../../packages/protocol/src/concierge.ts"
+
+interface Context {
+  readonly revision: number
+  readonly parts: readonly string[]
+  readonly deny: readonly string[]
+  readonly allow?: ReadonlySet<string>
+}
+
+/** Locked sessions kept at most (oldest dropped; the hub keeps 20 Concierge sessions per user). */
+const LOCKS_MAX = 1000
+const LOCKED_TOOLS: ReadonlySet<string> = new Set(CONCIERGE_TOOLS)
+/** OpenCode's internal agents (title generation, compaction, summaries): never the session's own agent. */
+/** A file version: atomic writes rename a new inode in, so inode + mtime + size changes with every write. */
+const stampOf = (file: string) => {
+  const st = statSync(file)
+  return `${st.ino}:${st.mtimeMs}:${st.size}`
+}
+
+export const INTERNAL_AGENTS: ReadonlySet<string> = new Set(["title", "compaction", "summary"])
+
+export interface SessionContextsOptions {
+  readonly maxSessions?: number
+  /** Where locked session IDs persist (the plugin's state dir); in memory only without it. */
+  readonly lockFile?: string
+}
+
+export class SessionContexts {
+  private readonly contexts = new Map<string, Context>()
+  /** The last cleared revision per session, so a stale set cannot resurrect a cleared context. */
+  private readonly cleared = new Map<string, number>()
+  private readonly locks: Set<string>
+  /** The lock file's mtime when last read (another process may add locks: re-read on change). */
+  private lockStamp = ""
+  private readonly agents = new Map<string, string>()
+  private readonly maxSessions: number
+
+  constructor(private readonly options: SessionContextsOptions = {}) {
+    this.maxSessions = options.maxSessions ?? 200
+    this.locks = new Set(this.load())
+  }
+
+  /** Adds the locks another process wrote since the last read (locks are never removed). */
+  private refresh(): void {
+    const file = this.options.lockFile
+    if (!file) return
+    let stamp: string
+    try {
+      stamp = stampOf(file)
+    } catch {
+      return
+    }
+    if (stamp === this.lockStamp) return
+    this.lockStamp = stamp
+    for (const id of this.load()) this.locks.add(id)
+  }
+
+  private load(): string[] {
+    if (!this.options.lockFile) return []
+    try {
+      const raw = JSON.parse(readFileSync(this.options.lockFile, "utf8")) as { v?: unknown; sessions?: unknown }
+      return raw.v === 1 && Array.isArray(raw.sessions) ? raw.sessions.filter((id): id is string => typeof id === "string" && id.length > 0 && id.length <= 200) : []
+    } catch {
+      return []
+    }
+  }
+
+  private lock(sessionID: string): void {
+    this.refresh()
+    if (this.locks.has(sessionID)) return
+    // Merge with what other processes wrote: never drop their locks.
+    for (const id of this.load()) this.locks.add(id)
+    this.locks.add(sessionID)
+    while (this.locks.size > LOCKS_MAX) this.locks.delete(this.locks.values().next().value as string)
+    const file = this.options.lockFile
+    if (!file) return
+    try {
+      mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 })
+      const tmp = `${file}.${process.pid}.tmp`
+      writeFileSync(tmp, `${JSON.stringify({ v: 1, sessions: [...this.locks] })}\n`, { mode: 0o600 })
+      renameSync(tmp, file)
+      this.lockStamp = stampOf(file)
+    } catch (cause) {
+      // The lock still holds in this process; the hub re-sends the context after a restart.
+      console.error(`[hub] could not persist the Concierge session lock: ${(cause as Error).message}`)
+    }
+  }
+
+  /** Applies a hub request (validated by the protocol parser); throws "stale: …" for an older revision. */
+  handle(req: SessionContextRequest): SessionContextResult {
+    const effective = this.contexts.get(req.sessionID)?.revision ?? this.cleared.get(req.sessionID)
+    if (effective !== undefined && req.revision < effective) throw new Error(`stale: revision ${req.revision} is older than the effective ${effective}`)
+    this.contexts.delete(req.sessionID)
+    if (req.clear) {
+      this.cleared.set(req.sessionID, req.revision)
+      this.bound(this.cleared)
+      return { revision: req.revision }
+    }
+    this.cleared.delete(req.sessionID)
+    if (req.lockAgent) this.lock(req.sessionID)
+    const byKey = new Map(req.parts.map((p) => [p.key, p.text]))
+    const parts = SESSION_CONTEXT_KEYS.flatMap((key) => (byKey.has(key) ? [byKey.get(key)!] : []))
+    const allow = req.tools?.allow
+    this.contexts.set(req.sessionID, { revision: req.revision, parts, deny: [...(req.tools?.deny ?? [])], ...(allow ? { allow: new Set(allow) } : {}) })
+    this.bound(this.contexts)
+    return { revision: req.revision }
+  }
+
+  private bound(map: Map<string, unknown>): void {
+    while (map.size > this.maxSessions) map.delete(map.keys().next().value as string)
+  }
+
+  /** The session's parts for its system prompt (none without a context). */
+  systemParts(sessionID: string): string[] {
+    return [...(this.contexts.get(sessionID)?.parts ?? [])]
+  }
+
+  /** A Concierge session: only CONCIERGE_TOOLS, its agent and model kept, no conversation mode. */
+  locked(sessionID: string): boolean {
+    if (!this.locks.has(sessionID)) this.refresh()
+    return this.locks.has(sessionID)
+  }
+
+  lockedSessions(): string[] {
+    return [...this.locks]
+  }
+
+  /** Whether the hub took this tool from the session (a locked session's non-Concierge tool, off its allow-list, or denied). */
+  denied(sessionID: string, tool: string): boolean {
+    if (this.locks.has(sessionID) && !LOCKED_TOOLS.has(tool)) return true
+    const context = this.contexts.get(sessionID)
+    if (!context) return false
+    return (context.allow !== undefined && !context.allow.has(tool)) || toolDenied(tool, context.deny)
+  }
+
+  /** Deletes the tools the hub took from the session from a context event's tools. */
+  filterTools(sessionID: string, tools: Record<string, unknown>): void {
+    if (!this.contexts.has(sessionID) && !this.locked(sessionID)) return
+    for (const name of Object.keys(tools)) if (this.denied(sessionID, name)) delete tools[name]
+  }
+
+  /** Records the agent a locked session runs on; true when it changed (a new report is due). */
+  seenAgent(sessionID: string, agent: string | undefined): boolean {
+    if (!this.locks.has(sessionID) || !agent || INTERNAL_AGENTS.has(agent) || this.agents.get(sessionID) === agent) return false
+    this.agents.set(sessionID, agent)
+    return true
+  }
+
+  /** What the sessions frame says about the session (locked ones only): its agent and context revision. */
+  report(sessionID: string): { agent?: string; contextRevision?: number } {
+    if (!this.locks.has(sessionID)) return {}
+    const agent = this.agents.get(sessionID)
+    const revision = this.contexts.get(sessionID)?.revision
+    return { ...(agent ? { agent } : {}), ...(revision !== undefined ? { contextRevision: revision } : {}) }
+  }
+}