@huynle/hub 0.8.0 → 0.8.2

package/src/spoke/locations.ts

@@ -10,6 +10,8 @@ export interface PermissionLocation {
   get(input: { sessionID: string; requestID: string }): Promise<unknown>
   /** `message`: a reject's reason (OpenCode's reply message). */
   reply(input: { sessionID: string; requestID: string; decision: PermissionDecision; message?: string }): Promise<unknown>
+  vcs?: { diff(): Promise<ReadonlyArray<unknown>>; branch(): Promise<string | undefined> }
+  names?(): Promise<LocalNames>
 }
 
 /**
@@ -33,3 +35,121 @@ export async function replyPermission(
   }
   return "gone"
 }
+
+/** A directory's branch and working-copy changes (undefined: nothing could read them). */
+export interface VcsReader {
+  diff(directory: string): Promise<ReadonlyArray<unknown> | undefined>
+  branch(directory: string): Promise<string | undefined>
+}
+
+/**
+ * Reads a directory's VCS state through the plugin instance whose location is that directory, else the own
+ * server's API (which honours the location), else not at all. OpenCode's plugin vcs API answers for the
+ * instance's own location whatever location is passed, so the first instance (the background service's is
+ * its $HOME) would report another directory's branch and changes. A read that takes longer than `timeoutMs` (a hung
+ * server) answers undefined, so the session summary goes on without branch and changes.
+ */
+/** How long a branch or changes read may take before the summary goes on without it (a hung server). */
+export const VCS_READ_TIMEOUT_MS = 5_000
+
+/** The value, or undefined once `ms` passed (the read is left to finish on its own). */
+function within<T>(read: Promise<T | undefined>, ms: number): Promise<T | undefined> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const late = new Promise<undefined>((resolve) => {
+    timer = setTimeout(() => resolve(undefined), ms)
+  })
+  return Promise.race([read.catch(() => undefined), late]).finally(() => clearTimeout(timer))
+}
+
+export function vcsReader(locations: () => readonly PermissionLocation[], server: () => Promise<VcsReader | undefined>, timeoutMs: number = VCS_READ_TIMEOUT_MS): VcsReader {
+  const local = (directory: string) => locations().find((l) => l.directory === directory && l.vcs)?.vcs
+  return {
+    diff: async (directory) => {
+      const vcs = local(directory)
+      return within(vcs ? vcs.diff() : server().then((reader) => reader?.diff(directory)), timeoutMs)
+    },
+    branch: async (directory) => {
+      const vcs = local(directory)
+      return within(vcs ? vcs.branch() : server().then((reader) => reader?.branch(directory)), timeoutMs)
+    },
+  }
+}
+
+
+/** A directory's local skill and command names (a hub profile's of the same name give way to them). */
+export interface LocalNames {
+  readonly skills: readonly string[]
+  readonly commands: readonly string[]
+}
+
+/** A directory's local names; undefined: nothing could read that directory's. */
+export type NamesSource = (directory: string) => Promise<LocalNames | undefined>
+
+/** How long two reads of a directory's names must agree before they count (OpenCode loads them one source at a time). */
+export const NAMES_SETTLE_MS = 500
+
+/**
+ * Reads a directory's local skill and command names like vcsReader reads its VCS state: through the plugin
+ * instance whose location is that directory, else the own server's API (which honours the location), else not
+ * at all (undefined). OpenCode's plugin skill.list / command.list answer for the instance's own location whatever
+ * location is passed, so the first instance would report another directory's names. A location OpenCode is still
+ * loading lists nothing, then its built-ins, then its own commands and skills one source at a time: the names
+ * count once they list a command (OpenCode always has built-in ones) and two reads `settleMs` apart agree. A read
+ * that fails, or does not settle within `timeoutMs`, is unknown.
+ */
+export function namesReader(
+  locations: () => readonly PermissionLocation[],
+  server: () => Promise<NamesSource | undefined>,
+  timeoutMs: number = VCS_READ_TIMEOUT_MS,
+  settleMs: number = NAMES_SETTLE_MS,
+): NamesSource {
+  return (directory) => {
+    const local = locations().find((l) => l.directory === directory && l.names)
+    let done = false
+    const settled = async (read: NamesSource): Promise<LocalNames | undefined> => {
+      let previous = await read(directory)
+      while (!done) {
+        await new Promise((resolve) => setTimeout(resolve, settleMs))
+        const next = await read(directory)
+        if (next === undefined) return undefined
+        if (next.commands.length && previous && sameNames(previous, next)) return next
+        previous = next
+      }
+      return undefined
+    }
+    const reading = local?.names ? settled(() => local.names!()) : server().then((read) => (read ? settled(read) : undefined))
+    return within(reading, timeoutMs).finally(() => (done = true))
+  }
+}
+
+function sameNames(a: LocalNames, b: LocalNames): boolean {
+  const same = (x: readonly string[], y: readonly string[]) => x.length === y.length && x.every((name, i) => name === y[i])
+  return same(a.skills, b.skills) && same(a.commands, b.commands)
+}
+
+/** The `name` of each item of a plugin or HTTP API list (bare, or wrapped as { location, data }). */
+export function listedNames(value: unknown): string[] {
+  const v = value as any
+  const list = Array.isArray(v) ? v : Array.isArray(v?.data) ? v.data : []
+  return list.flatMap((item: any) => (typeof item?.name === "string" ? [item.name] : []))
+}
+
+interface ListApi {
+  list(input: { location: { directory: string } }): Promise<unknown>
+}
+
+/** A directory's names over the own server's API (skill.list / command.list honour the location there); an answer for another directory is unknown. */
+export function serverNames(client: { skill: ListApi; command: ListApi }): NamesSource {
+  return async (directory) => {
+    const location = { directory }
+    const [skills, commands] = await Promise.all([client.skill.list({ location }), client.command.list({ location })])
+    if ([skills, commands].some((answer) => answeredFor(answer) !== undefined && answeredFor(answer) !== directory)) return undefined
+    return { skills: listedNames(skills), commands: listedNames(commands) }
+  }
+}
+
+/** The directory a wrapped { location, data } answer is for (undefined: a bare answer). */
+function answeredFor(answer: unknown): string | undefined {
+  const directory = (answer as any)?.location?.directory
+  return typeof directory === "string" ? directory : undefined
+}

package/src/spoke/profile-apply.ts

@@ -7,9 +7,11 @@
 // - 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).
+//   Same-named local skills/commands win (partial); their names are read in the session's own folder, and when they
+//   cannot be read the profile's skills and commands are not offered (partial with a note; the instructions apply).
+//   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
@@ -41,11 +43,19 @@ export const PROFILE_TOOL_INPUT = {
   additionalProperties: false,
 } as const
 
+/** The note of an apply whose session's local skill and command names could not be read. */
+const UNKNOWN_NAMES_NOTE = "skills and commands not offered: the session's local skills and commands could not be read"
+/** The planner's notes for skills/commands this adapter did not offer (replaced by UNKNOWN_NAMES_NOTE). */
+const ADAPTER_UNSUPPORTED = /^(skills|commands) not supported by this harness adapter$/
+
 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 session's local skill and command names, read in its own folder; absent: skills and commands are not
+   * applied. Undefined or a failure: unknown, so the instructions apply and the skills and commands are not offered.
+   */
+  readonly localNames?: (sessionID: string) => Promise<ProfileLocalNames | undefined>
   /** 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). */
@@ -177,20 +187,20 @@ export class OpenCodeProfiles {
       this.supersede(sessionID, req)
       return { result: current.result }
     }
+    // Local names are read only when there is something they could shadow. Unknown names (unreadable in the
+    // session's own folder) never reject the apply: the skills and commands are just not offered.
+    const tool = this.options.tool()
+    const wantsBindings = tool && (req.content.skills.length > 0 || req.content.commands.length > 0)
     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
+    if (wantsBindings && this.options.localNames) local = await this.options.localNames(sessionID).catch(() => undefined)
+    const unknown = wantsBindings && this.options.localNames !== undefined && local === undefined
+    const bindings = 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)
+    const notes = unknown ? [UNKNOWN_NAMES_NOTE, ...plan.notes.filter((note) => !ADAPTER_UNSUPPORTED.test(note))] : plan.notes
+    const result = profileApplyResult(req, plan.status, 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)

package/src/spoke/session-context.ts

@@ -1,8 +1,11 @@
 // 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.
+// - parts: instructions then notes are appended by the plugin's context hook after the profile parts; the board goes
+//   after the conversation as a system message (V-01: it changes between turns, and OpenCode sends tools, system,
+//   then messages, so a board in the system prompt made every push re-write the cached conversation; see
+//   applySessionContext). The whole set replaces the previous one.
+// - The kept tools are put in name order (the request lists them in the hook's record order).
 // - 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.
@@ -16,17 +19,78 @@
 // 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 { 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"
+import { CONCIERGE_TOOLS, type SessionContextKey, type SessionContextRequest, type SessionContextResult, toolDenied } from "../../packages/protocol/src/concierge.ts"
 
 interface Context {
   readonly revision: number
+  /** The stable parts (instructions, notes): the end of the system prompt. */
   readonly parts: readonly string[]
+  /** The changing parts (board): after the conversation. */
+  readonly tail: readonly string[]
   readonly deny: readonly string[]
   readonly allow?: ReadonlySet<string>
 }
 
+/** Parts at the end of the system prompt (stable between turns), in this order. */
+const SYSTEM_KEYS: readonly SessionContextKey[] = ["instructions", "notes"]
+/** Parts after the conversation (they change between turns). */
+const TAIL_KEYS: readonly SessionContextKey[] = ["board"]
+const EPHEMERAL = { type: "ephemeral" } as const
+
+interface HookPart {
+  type: string
+  text?: string
+  cache?: unknown
+}
+interface HookMessage {
+  role: string
+  content: HookPart[]
+}
+
+/** The tools in name order (OpenCode sends them in the record's order: the request's prefix must not move). */
+export function sortTools(tools: Record<string, unknown>): void {
+  const entries = Object.entries(tools).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+  for (const [name] of entries) delete tools[name]
+  for (const [name, tool] of entries) tools[name] = tool
+}
+
+/** An OpenCode effort message (a system message carrying only the reasoning effort). */
+const isEffort = (m: HookMessage) => m.role === "system" && m.content.length === 1 && m.content[0]?.type === "effort"
+
+/** The index of the last item matching (-1: none). */
+const lastIndex = <T>(items: readonly T[], match: (item: T) => boolean) => {
+  for (let i = items.length - 1; i >= 0; i--) if (match(items[i]!)) return i
+  return -1
+}
+
+/** A cache hint on the message's last text part (else its last part that is not compaction or effort). */
+function hint(message: HookMessage): void {
+  const text = lastIndex(message.content, (p) => p.type === "text")
+  const index = text >= 0 ? text : lastIndex(message.content, (p) => p.type !== "compaction" && p.type !== "effort")
+  const part = message.content[index]
+  if (part && part.cache === undefined) message.content[index] = { ...part, cache: EPHEMERAL }
+}
+
+/**
+ * (V-01) Adds a session context to a context hook's request so the provider's prompt cache survives a board change.
+ * OpenCode sends tools, the system parts, then the messages; it puts cache breakpoints on the last tool, the first and
+ * last system part and the last message (4 at most). The stable parts end the system prompt (the last one carries a
+ * hint); the board follows the conversation as one system message (with a hint), and the conversation's last message
+ * gets a hint, so the next turn reads everything up to it from the cache whatever the board says. Without a board
+ * nothing is added after the conversation; a request without messages gets the board in its system prompt.
+ */
+export function applySessionContext(event: { system: HookPart[]; messages?: HookMessage[] }, system: readonly string[], tail: readonly string[]): void {
+  const messages = Array.isArray(event.messages) ? event.messages : undefined
+  const ending = messages ? system : [...system, ...tail]
+  ending.forEach((text, i) => event.system.push(i === ending.length - 1 ? { type: "text", text, cache: EPHEMERAL } : { type: "text", text }))
+  if (!messages || !tail.length) return
+  const last = messages[lastIndex(messages, (m) => !isEffort(m))]
+  if (last) hint(last)
+  messages.push({ role: "system", content: [{ type: "text", text: tail.join("\n\n"), cache: EPHEMERAL }] })
+}
+
 /** 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)
@@ -43,6 +107,62 @@ 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 {
@@ -60,46 +180,62 @@ export class SessionContexts {
     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 file = this.options.lockFile
-    if (!file) return
-    let stamp: string
-    try {
-      stamp = stampOf(file)
-    } catch {
-      return
-    }
+    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[] {
-    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 []
-    }
+    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
-    // 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
+    if (!file) return this.boundLocks()
     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)
+      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}`)
@@ -119,22 +255,32 @@ export class SessionContexts {
     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 pick = (keys: readonly SessionContextKey[]) => 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.contexts.set(req.sessionID, { revision: req.revision, parts: pick(SYSTEM_KEYS), tail: pick(TAIL_KEYS), 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). */
+  /** The session's stable parts for the end of its system prompt: instructions, notes (none without a context). */
   systemParts(sessionID: string): string[] {
     return [...(this.contexts.get(sessionID)?.parts ?? [])]
   }
 
+  /** The session's changing parts, sent after its conversation: the board (none without a context). */
+  tailParts(sessionID: string): string[] {
+    return [...(this.contexts.get(sessionID)?.tail ?? [])]
+  }
+
   /** 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()
@@ -157,6 +303,7 @@ export class SessionContexts {
   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]
+    sortTools(tools)
   }
 
   /** Records the agent a locked session runs on; true when it changed (a new report is due). */
@@ -166,11 +313,14 @@ export class SessionContexts {
     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 } {
+  /**
+   * 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 { ...(agent ? { agent } : {}), ...(revision !== undefined ? { contextRevision: revision } : {}) }
+    return { locked: true, ...(agent ? { agent } : {}), ...(revision !== undefined ? { contextRevision: revision } : {}) }
   }
 }