@huynle/hub 0.7.4 → 0.8.1

package/src/spoke/session-context.ts

@@ -0,0 +1,256 @@
+// 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 { closeSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, 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
+  /** (FX-07) How long a write waits for the other processes' exclusive lock before it writes anyway. */
+  readonly lockWaitMs?: number
+  /**
+   * Other lock files read (never written): the other default state dir places (FX-08: a lock written before an
+   * upgrade moved the state dir still locks the session; fail closed).
+   */
+  readonly readLockFiles?: readonly string[]
+}
+
+/** (FX-07) A `<lockFile>.lock` older than this belongs to a process that died while writing: it is broken. */
+const WRITE_LOCK_STALE_MS = 10_000
+const WRITE_LOCK_WAIT_MS = 2_000
+const pause = (ms: number) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+
+/**
+ * (FX-07) Runs `write` holding `<file>.lock` (created exclusively), so the read-merge-write of every OpenCode process
+ * on the machine is serialized and none drops another's locks. A stale lock (its holder died) is broken; after
+ * `waitMs` the write runs anyway (the lock still holds in this process, and the write merges what it reads).
+ */
+function underWriteLock(file: string, waitMs: number, write: () => void): void {
+  const lock = `${file}.lock`
+  const deadline = Date.now() + waitMs
+  let held = false
+  for (;;) {
+    try {
+      closeSync(openSync(lock, "wx", 0o600))
+      held = true
+      break
+    } catch (cause) {
+      if ((cause as NodeJS.ErrnoException).code !== "EEXIST") break
+    }
+    try {
+      if (Date.now() - statSync(lock).mtimeMs > WRITE_LOCK_STALE_MS) {
+        unlinkSync(lock)
+        continue
+      }
+    } catch {
+      continue // released meanwhile
+    }
+    if (Date.now() >= deadline) {
+      console.error("[hub] the Concierge session lock file stayed busy: writing without it")
+      break
+    }
+    pause(2 + Math.floor(Math.random() * 5))
+  }
+  try {
+    write()
+  } finally {
+    if (held) {
+      try {
+        unlinkSync(lock)
+      } catch {
+        // already gone
+      }
+    }
+  }
+}
+
+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())
+  }
+
+  /** Every lock file read: the written one first, then the read-only ones. */
+  private files(): string[] {
+    return [...(this.options.lockFile ? [this.options.lockFile] : []), ...(this.options.readLockFiles ?? [])]
+  }
+
+  /** Adds the locks another process wrote since the last read (locks are never removed). */
+  private refresh(): void {
+    const files = this.files()
+    if (!files.length) return
+    const stamp = files
+      .map((file) => {
+        try {
+          return stampOf(file)
+        } catch {
+          return "-"
+        }
+      })
+      .join("|")
+    if (stamp === this.lockStamp) return
+    this.lockStamp = stamp
+    for (const id of this.load()) this.locks.add(id)
+  }
+
+  /** The union of the lock files' sessions (a missing or corrupt file adds none). */
+  private load(): string[] {
+    return this.files().flatMap((file) => {
+      try {
+        const raw = JSON.parse(readFileSync(file, "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
+    this.locks.add(sessionID)
+    const file = this.options.lockFile
+    if (!file) return this.boundLocks()
+    try {
+      mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 })
+      underWriteLock(file, this.options.lockWaitMs ?? WRITE_LOCK_WAIT_MS, () => {
+        // Merge with what other processes wrote (read under the write lock): never drop their locks.
+        for (const id of this.load()) this.locks.add(id)
+        // The newest lock last, so the bound never drops it.
+        this.locks.delete(sessionID)
+        this.locks.add(sessionID)
+        this.boundLocks()
+        const tmp = `${file}.${process.pid}.tmp`
+        writeFileSync(tmp, `${JSON.stringify({ v: 1, sessions: [...this.locks] })}\n`, { mode: 0o600 })
+        renameSync(tmp, file)
+      })
+      this.lockStamp = ""
+      this.refresh()
+    } 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 }
+  }
+
+  /** At most LOCKS_MAX locks (the oldest dropped). */
+  private boundLocks(): void {
+    while (this.locks.size > LOCKS_MAX) this.locks.delete(this.locks.values().next().value as string)
+  }
+
+  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): locked (FX-07: from the very first frame, even
+   * after a restart, before its agent is read or the hub re-sends a context), its agent and context revision.
+   */
+  report(sessionID: string): { locked?: true; agent?: string; contextRevision?: number } {
+    if (!this.locks.has(sessionID)) return {}
+    const agent = this.agents.get(sessionID)
+    const revision = this.contexts.get(sessionID)?.revision
+    return { locked: true, ...(agent ? { agent } : {}), ...(revision !== undefined ? { contextRevision: revision } : {}) }
+  }
+}