thinkpool-pair 0.7.245 → 0.7.247

package/event-id.mjs

@@ -210,6 +210,237 @@ export function inlineImageBlocks(evt) {
   return out
 }
 
+// One ordered emission boundary for structured-session events while agent screenshots
+// are lifted out of inline base64. This stays import-safe: bridge.mjs owns room/auth
+// state; these definitions own deadlines, bounded reservations, ordering, and teardown.
+export const SCREENSHOT_OMITTED = '[screenshot omitted — upload failed]'
+export const DEFAULT_IMAGE_UPLOAD_TIMEOUT_MS = 15_000
+export const DEFAULT_IMAGE_QUEUE_MAX_PENDING = 4
+export const DEFAULT_IMAGE_QUEUE_MAX_BYTES = 16_000_000
+
+const sanePositiveInt = (value, fallback) => {
+  const n = Number(value)
+  return Number.isSafeInteger(n) && n > 0 ? n : fallback
+}
+
+export function imageQueueConfig(env = process.env) {
+  return {
+    uploadTimeoutMs: sanePositiveInt(env.TP_CODE_IMAGE_UPLOAD_TIMEOUT_MS, DEFAULT_IMAGE_UPLOAD_TIMEOUT_MS),
+    maxPending: sanePositiveInt(env.TP_CODE_IMAGE_QUEUE_MAX_PENDING, DEFAULT_IMAGE_QUEUE_MAX_PENDING),
+    maxBytes: sanePositiveInt(env.TP_CODE_IMAGE_QUEUE_MAX_BYTES, DEFAULT_IMAGE_QUEUE_MAX_BYTES),
+  }
+}
+
+// Deadline covers fetch AND response parsing. Promise.race is deliberate: AbortSignal is
+// still passed to real fetch, but an injected/broken fetch that ignores it cannot pin the
+// ordered queue forever. activeUploads lets session teardown cancel the deadline now.
+export async function uploadCodeImage({
+  webBase,
+  room,
+  authToken,
+  term,
+  cid,
+  image,
+  fetchImpl = globalThis.fetch,
+  timeoutMs = DEFAULT_IMAGE_UPLOAD_TIMEOUT_MS,
+  activeUploads = new Set(),
+}) {
+  const controller = new AbortController()
+  let timer = null
+  let rejectCancel = null
+  let settled = false
+
+  const cancelled = new Promise((_, reject) => { rejectCancel = reject })
+  const handle = {
+    cancel(reason = new Error('code-image upload cancelled')) {
+      if (settled) return
+      if (timer) { clearTimeout(timer); timer = null }
+      try { controller.abort(reason) } catch { /* AbortController is best-effort */ }
+      rejectCancel(reason instanceof Error ? reason : new Error(String(reason)))
+    },
+  }
+  activeUploads.add(handle)
+  timer = setTimeout(() => handle.cancel(new Error(`code-image upload timed out after ${timeoutMs}ms`)), timeoutMs)
+  timer.unref?.()
+
+  const headers = { 'Content-Type': 'application/json' }
+  if (authToken) headers.Authorization = `Bearer ${authToken}`
+  const request = (async () => {
+    const res = await fetchImpl(`${webBase}/api/code-image`, {
+      method: 'POST',
+      headers,
+      signal: controller.signal,
+      body: JSON.stringify({ code: room, term, cid, idx: image.idx, mediaType: image.mediaType, b64: image.b64 }),
+    })
+    if (!res.ok) throw new Error(`code-image ${res.status}`)
+    const { path } = await res.json()
+    if (!path) throw new Error('code-image: no path')
+    return path
+  })()
+
+  try {
+    return await Promise.race([request, cancelled])
+  } finally {
+    settled = true
+    if (timer) clearTimeout(timer)
+    activeUploads.delete(handle)
+  }
+}
+
+const encodedImageBytes = (image) => Buffer.byteLength(String(image?.b64 || ''), 'ascii')
+
+function stripRawImages(evt, images, placeholder) {
+  for (const image of images) {
+    const block = Array.isArray(evt?.content) ? evt.content[image.idx] : null
+    if (block?.source?.type === 'base64' || image.b64) {
+      evt.content[image.idx] = { type: 'text', text: placeholder }
+    }
+    image.b64 = ''
+  }
+}
+
+export class ImageEventQueue {
+  constructor({
+    upload,
+    maxPending = DEFAULT_IMAGE_QUEUE_MAX_PENDING,
+    maxBytes = DEFAULT_IMAGE_QUEUE_MAX_BYTES,
+    placeholder = SCREENSHOT_OMITTED,
+    onUploadError = () => {},
+    onOverload = () => {},
+  }) {
+    if (typeof upload !== 'function') throw new TypeError('ImageEventQueue requires upload')
+    this.upload = upload
+    this.maxPending = sanePositiveInt(maxPending, DEFAULT_IMAGE_QUEUE_MAX_PENDING)
+    this.maxBytes = sanePositiveInt(maxBytes, DEFAULT_IMAGE_QUEUE_MAX_BYTES)
+    this.placeholder = placeholder
+    this.onUploadError = onUploadError
+    this.onOverload = onOverload
+    this.pendingCount = 0
+    this.pendingBytes = 0
+    this.peakPendingCount = 0
+    this.peakPendingBytes = 0
+    this.activeUploads = new Set()
+    this.tasks = new Set()
+    this.tail = Promise.resolve()
+    this.closed = false
+    this.overloadNotified = false
+  }
+
+  stats() {
+    return {
+      pendingCount: this.pendingCount,
+      pendingBytes: this.pendingBytes,
+      peakPendingCount: this.peakPendingCount,
+      peakPendingBytes: this.peakPendingBytes,
+      activeUploads: this.activeUploads.size,
+      queuedEvents: this.tasks.size,
+    }
+  }
+
+  enqueue(evt, images, emitTail) {
+    if (this.closed || typeof emitTail !== 'function') return false
+    const imgs = Array.isArray(images) ? images : []
+    const count = imgs.length
+    const bytes = imgs.reduce((sum, image) => sum + encodedImageBytes(image), 0)
+    const accepted = count > 0 &&
+      this.pendingCount + count <= this.maxPending &&
+      this.pendingBytes + bytes <= this.maxBytes
+
+    if (count && accepted) {
+      for (const image of imgs) {
+        image._queueBytes = encodedImageBytes(image)
+        image._queueReserved = true
+      }
+      this.pendingCount += count
+      this.pendingBytes += bytes
+      this.peakPendingCount = Math.max(this.peakPendingCount, this.pendingCount)
+      this.peakPendingBytes = Math.max(this.peakPendingBytes, this.pendingBytes)
+    } else if (count) {
+      // Critical memory boundary: discard raw base64 BEFORE this event can join a
+      // chain blocked behind an earlier upload.
+      stripRawImages(evt, imgs, this.placeholder)
+      if (!this.overloadNotified) {
+        this.overloadNotified = true
+        this.onOverload({ count, bytes, maxPending: this.maxPending, maxBytes: this.maxBytes })
+      }
+    }
+
+    // Preserve the old synchronous fast path when no image upload is ahead of us.
+    if (!accepted && this.tasks.size === 0) {
+      emitTail(evt)
+      return true
+    }
+
+    const task = { evt, images: imgs, emitTail, accepted, emitted: false, done: false }
+    this.tasks.add(task)
+    this.tail = this.tail.catch(() => {}).then(() => this._run(task))
+    return true
+  }
+
+  async _run(task) {
+    if (task.done || this.closed) return
+    try {
+      if (task.accepted) {
+        for (const image of task.images) {
+          if (!image._queueReserved || this.closed) continue
+          try {
+            const path = await this.upload(task.evt, image, this.activeUploads)
+            task.evt.content[image.idx] = { type: 'image', path, mediaType: image.mediaType }
+          } catch (error) {
+            task.evt.content[image.idx] = { type: 'text', text: this.placeholder }
+            if (!this.closed) this.onUploadError(error)
+          } finally {
+            image.b64 = ''
+            this._release(image)
+          }
+        }
+      }
+      if (!this.closed && !task.emitted) {
+        task.emitTail(task.evt)
+        task.emitted = true
+      }
+    } finally {
+      task.done = true
+      this.tasks.delete(task)
+    }
+  }
+
+  _release(image) {
+    if (!image?._queueReserved) return
+    image._queueReserved = false
+    this.pendingCount = Math.max(0, this.pendingCount - 1)
+    this.pendingBytes = Math.max(0, this.pendingBytes - (image._queueBytes || 0))
+    image._queueBytes = 0
+  }
+
+  async idle() {
+    await this.tail.catch(() => {})
+  }
+
+  // Session close/provider switch/shutdown is synchronous. Cancel active deadlines,
+  // replace any still-raw image, and flush queued tails in insertion order before the
+  // owner persists/deletes the entry. Later promise continuations see done/closed.
+  close({ flush = true } = {}) {
+    if (this.closed) return
+    this.closed = true
+    const reason = new Error('code-image queue closed')
+    for (const upload of this.activeUploads) upload.cancel(reason)
+    this.activeUploads.clear()
+    for (const task of this.tasks) {
+      stripRawImages(task.evt, task.images, this.placeholder)
+      for (const image of task.images) this._release(image)
+      if (flush && !task.emitted) {
+        try { task.emitTail(task.evt) } catch { /* teardown must continue */ }
+        task.emitted = true
+      }
+      task.done = true
+    }
+    this.tasks.clear()
+    this.pendingCount = 0
+    this.pendingBytes = 0
+  }
+}
+
 // Pure aggregation for the /usage report — replay a session's retained log events and
 // fold every completed turn (kind:'result' with usage) into per-model + total token/cost
 // sums. No side effects, import-safe (bridge/test-usage-summary.mjs exercises it), so the

package/flow-models.mjs

@@ -11,10 +11,11 @@ const CLAUDE_TIERS = {
 
 const CODEX_SCAFFOLD = ['gpt-5.6-luna', 'gpt-5.4-mini', 'gpt-5.3-codex-spark']
 const CODEX_BALANCED = ['gpt-5.6-terra', 'gpt-5.4']
+const HERMES_REVIEW = ['nous:anthropic/claude-sonnet-4.6', 'nous:anthropic/claude-sonnet-4.5', 'nous:anthropic/claude-sonnet-4']
 
 export function normalizeFlowRuntime(runtime, fallback = null) {
-  if (runtime === 'claude' || runtime === 'codex') return runtime
-  return fallback === 'claude' || fallback === 'codex' ? fallback : null
+  if (runtime === 'claude' || runtime === 'codex' || runtime === 'hermes') return runtime
+  return fallback === 'claude' || fallback === 'codex' || fallback === 'hermes' ? fallback : null
 }
 
 export function modelCatalogValues(catalog = []) {
@@ -32,6 +33,12 @@ function firstVisible(candidates, catalog) {
   return undefined
 }
 
+function firstVisibleMatching(catalog, patterns) {
+  const visible = modelCatalogValues(catalog)
+  for (const pattern of patterns) for (const model of visible) if (pattern.test(model)) return model
+  return undefined
+}
+
 export function flowLaneModelFor({ sliceType, runtime = 'claude', catalog = [], env = process.env } = {}) {
   if (normalizeFlowRuntime(runtime, 'claude') === 'codex') {
     const override = env.TP_FLOW_CODEX_LANE_MODEL
@@ -39,6 +46,16 @@ export function flowLaneModelFor({ sliceType, runtime = 'claude', catalog = [],
     if (override) return modelCatalogValues(catalog).has(override) ? override : undefined
     return firstVisible(sliceType === 'scaffold' ? CODEX_SCAFFOLD : CODEX_BALANCED, catalog)
   }
+  if (normalizeFlowRuntime(runtime, 'claude') === 'hermes') {
+    const override = env.TP_FLOW_HERMES_LANE_MODEL
+    const visible = modelCatalogValues(catalog)
+    if (override === 'inherit') return undefined
+    if (override) return visible.has(override) ? override : undefined
+    if (sliceType === 'review') return firstVisible(HERMES_REVIEW, catalog)
+      || firstVisibleMatching(catalog, [/terra/i, /sonnet/i, /balanced/i])
+    if (sliceType === 'scaffold') return firstVisibleMatching(catalog, [/(?:luna|mini)/i])
+    return firstVisibleMatching(catalog, [/terra/i, /(?:luna|mini)/i])
+  }
   const override = env.TP_FLOW_CLAUDE_LANE_MODEL || env.TP_FLOW_LANE_MODEL
   if (override === 'inherit') return undefined
   if (override) return override
@@ -53,6 +70,13 @@ export function flowConductorModelFor({ runtime = 'claude', originModel, catalog
     if (override) return visible.has(override) ? override : undefined
     return originModel && visible.has(originModel) ? originModel : undefined
   }
+  if (normalizeFlowRuntime(runtime, 'claude') === 'hermes') {
+    const override = env.TP_FLOW_HERMES_CONDUCTOR_MODEL
+    const visible = modelCatalogValues(catalog)
+    if (override === 'inherit') return undefined
+    if (override) return visible.has(override) ? override : undefined
+    return originModel && visible.has(originModel) ? originModel : undefined
+  }
   const override = env.TP_FLOW_CLAUDE_CONDUCTOR_MODEL || env.TP_FLOW_CONDUCTOR_MODEL
   if (override === 'inherit') return undefined
   // Claude non-regression: the conductor historically inherited the host default,

package/flow-task-graph.mjs

@@ -176,10 +176,10 @@ export function normalizePlanOutput (raw) {
 // Codex review protocol deliberately maps one reviewer lane to one builder target.
 // Claude's legacy Flow plans may review several deps and remain unchanged.
 export function validatePlanForRuntime (plan, runtime = 'claude') {
-  if (runtime !== 'codex') return plan
+  if (runtime !== 'codex' && runtime !== 'hermes') return plan
   for (const task of plan?.tasks || []) {
     if (task.sliceType === SLICE_TYPE.review && task.deps.length !== 1) {
-      throw new Error(`Codex review task "${task.key}" must depend on exactly one builder task`)
+      throw new Error(`${runtime === 'hermes' ? 'Hermes' : 'Codex'} review task "${task.key}" must depend on exactly one builder task`)
     }
   }
   return plan
@@ -187,7 +187,7 @@ export function validatePlanForRuntime (plan, runtime = 'claude') {
 
 export function validReviewTargetShape (task, runtime = 'claude') {
   if (!task || task.slice_type !== SLICE_TYPE.review) return true
-  return runtime !== 'codex' || (Array.isArray(task.deps) && task.deps.length === 1)
+  return (runtime !== 'codex' && runtime !== 'hermes') || (Array.isArray(task.deps) && task.deps.length === 1)
 }
 
 export function legacyBuilderCompletionAllowed ({ runtime, flowRole, eventKind, eventSubtype, interrupted = false } = {}) {

package/hermes-acp-bootstrap.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""Process-local ThinkPool Hermes ACP tool policy.
+
+Never import this through the user profile. The bridge starts this file with
+Hermes' installed venv interpreter and passes a validated role policy in env.
+"""
+import json
+import os
+import sys
+
+POLICY_ENV = "THINKPOOL_HERMES_ACP_POLICY"
+
+CODING_TOOLS = frozenset({
+    "web_search", "web_extract", "terminal", "process", "read_file", "write_file",
+    "patch", "search_files", "vision_analyze", "skills_list", "skill_view",
+    "skill_manage", "browser_navigate", "browser_snapshot", "browser_click",
+    "browser_type", "browser_scroll", "browser_back", "browser_press",
+    "browser_get_images", "browser_vision", "browser_console", "browser_cdp",
+    "browser_dialog", "todo", "memory", "execute_code",
+})
+READ_ONLY_TOOLS = frozenset({"read_file", "search_files"})
+ESSENTIAL_CODING_TOOLS = frozenset({
+    "terminal", "process", "read_file", "write_file", "patch", "search_files",
+})
+
+def die(message):
+    print("ThinkPool Hermes ACP policy error: " + message, file=sys.stderr)
+    raise SystemExit(78)
+
+def policy():
+    raw = os.environ.get(POLICY_ENV)
+    try:
+        value = json.loads(raw)
+    except Exception:
+        die("missing or malformed policy")
+    if not isinstance(value, dict) or value.get("version") != 1:
+        die("unsupported policy")
+    role = value.get("role")
+    builtin = value.get("builtinTools")
+    required_builtin = value.get("requiredBuiltinTools")
+    tools = value.get("mcpTools")
+    if role not in {"ordinary", "builder", "conductor", "reviewer", "manual-review"}:
+        die("unknown role")
+    if value.get("mcpServer") != "thinkpool" or not isinstance(builtin, list) or not isinstance(required_builtin, list) or not isinstance(tools, list):
+        die("invalid tool policy")
+    if not all(isinstance(x, str) and x and x.replace("_", "").isalnum() for x in builtin + required_builtin + tools):
+        die("invalid tool name")
+    forbidden = {"delegate_task", "session_search"}
+    if forbidden.intersection(builtin) or forbidden.intersection(required_builtin) or forbidden.intersection(tools):
+        die("delegation and session search are forbidden")
+    required_mcp = {
+        "ordinary": {"read_terminal"}, "builder": {"mark_flow_done"},
+        "conductor": {"submit_flow_plan"},
+        "reviewer": {"submit_flow_review", "run_review_check", "read_review_file"},
+        "manual-review": {"run_review_check", "read_review_file"},
+    }
+    if not required_mcp[role].issubset(tools):
+        die("incomplete role MCP policy")
+    restricted = role in {"conductor", "reviewer", "manual-review"}
+    allowed_builtin = READ_ONLY_TOOLS if restricted else CODING_TOOLS
+    required = READ_ONLY_TOOLS if restricted else ESSENTIAL_CODING_TOOLS
+    if set(builtin) != allowed_builtin:
+        die("restricted role requires exact read-only builtins" if restricted else "coding role requires the full approved builtin allowlist")
+    if set(required_builtin) != required:
+        die("invalid required builtin policy")
+    return role, tuple(dict.fromkeys(builtin)), tuple(dict.fromkeys(required_builtin)), tuple(dict.fromkeys(tools))
+
+ROLE, BUILTIN, REQUIRED_BUILTIN, MCP_TOOLS = policy()
+ALLOWED = frozenset(BUILTIN) | frozenset("mcp__thinkpool__" + x for x in MCP_TOOLS) | frozenset("mcp_thinkpool_" + x for x in MCP_TOOLS)
+
+def name_of(schema):
+    if not isinstance(schema, dict): return ""
+    fn = schema.get("function")
+    return fn.get("name", "") if isinstance(fn, dict) else schema.get("name", "")
+
+def filter_schemas(items):
+    return [item for item in (items or []) if name_of(item) in ALLOWED]
+
+def assert_exact_inventory(agent):
+    """Reject an ACP lifecycle that lost the bridge-owned MCP surface.
+
+    Hermes treats registration errors as non-fatal.  That is acceptable for a
+    standalone CLI, but never for a ThinkPool role: the bridge must not let a
+    reconstructed agent accept a prompt with a partial policy.
+    """
+    tools = list(getattr(agent, "tools", []) or [])
+    names = {name_of(item) for item in tools}
+    # Allowed is deliberately broader than required for ordinary/builder:
+    # browser/provider/vision integrations are availability-gated upstream.
+    missing_builtin = set(REQUIRED_BUILTIN) - names
+    missing_mcp = [name for name in MCP_TOOLS if not ({"mcp__thinkpool__" + name, "mcp_thinkpool_" + name} & names)]
+    extras = names - ALLOWED
+    if missing_builtin or missing_mcp or extras:
+        details = []
+        if missing_builtin: details.append("missing builtins " + ", ".join(sorted(missing_builtin)))
+        if missing_mcp: details.append("missing MCP " + ", ".join(sorted(missing_mcp)))
+        if extras: details.append("forbidden extras " + ", ".join(sorted(extras)))
+        raise RuntimeError("ThinkPool exact inventory is incomplete: " + "; ".join(details))
+    agent.tools = tools
+    agent.valid_tool_names = names
+
+# Patch before importing ACP server. Each new/resumed/reset ACP process reloads
+# this exact policy; no mutable shell alias or profile config participates.
+import toolsets
+toolsets.TOOLSETS["hermes-acp"] = {
+    "description": "ThinkPool process-local ACP policy",
+    "tools": list(BUILTIN), "includes": []
+}
+
+# entry.main() normally discovers profile-configured MCP servers before it
+# creates the ACP server. ThinkPool ACP never inherits those profile servers;
+# the only permitted registration is the bridge's per-session `thinkpool` one.
+import tools.mcp_tool
+tools.mcp_tool.discover_mcp_tools = lambda *args, **kwargs: []
+
+import model_tools
+_get_definitions = model_tools.get_tool_definitions
+def constrained_definitions(*args, **kwargs):
+    return filter_schemas(_get_definitions(*args, **kwargs))
+model_tools.get_tool_definitions = constrained_definitions
+
+import agent.memory_manager
+_inject_memory = agent.memory_manager.inject_memory_provider_tools
+def constrained_memory(agent):
+    result = _inject_memory(agent)
+    if hasattr(agent, "tools"):
+        agent.tools = filter_schemas(agent.tools)
+        agent.valid_tool_names = {name_of(x) for x in agent.tools}
+    return result
+agent.memory_manager.inject_memory_provider_tools = constrained_memory
+
+import acp_adapter.session
+_expand = acp_adapter.session._expand_acp_enabled_toolsets
+def constrained_expand(toolsets_arg=None, mcp_server_names=None):
+    requested = list(toolsets_arg or ["hermes-acp"])
+    if any(name not in {"hermes-acp", "mcp-thinkpool"} for name in requested):
+        raise RuntimeError("ThinkPool ACP only permits hermes-acp and mcp-thinkpool toolsets")
+    names = list(mcp_server_names or [])
+    if any(name != "thinkpool" for name in names):
+        raise RuntimeError("ThinkPool ACP only permits dynamic MCP server thinkpool")
+    # Hermes 0.18.2 calls this from /tools with an already-expanded
+    # ["hermes-acp", "mcp-thinkpool"] list and no mcp_server_names.  Preserve
+    # that exact legal expansion; otherwise /tools silently omits ThinkPool.
+    return ["hermes-acp"] + (["mcp-thinkpool"] if names or "mcp-thinkpool" in requested else [])
+acp_adapter.session._expand_acp_enabled_toolsets = constrained_expand
+
+import acp_adapter.server
+_register = acp_adapter.server.HermesACPAgent._register_session_mcp_servers
+async def constrained_register(self, state, mcp_servers):
+    if any(getattr(server, "name", None) != "thinkpool" for server in (mcp_servers or [])):
+        raise RuntimeError("ThinkPool ACP only permits dynamic MCP server thinkpool")
+    if mcp_servers:
+        # SessionState is process-local.  Keep only the validated descriptors so
+        # a subsequent set_model reconstruction can re-register the same MCP.
+        state._thinkpool_mcp_servers = tuple(mcp_servers)
+    await _register(self, state, mcp_servers)
+    assert_exact_inventory(state.agent)
+acp_adapter.server.HermesACPAgent._register_session_mcp_servers = constrained_register
+
+# Hermes 0.18.2's session/set_model creates a fresh state.agent.  Upstream
+# does not re-run ACP MCP registration, so the new agent can expose only its
+# built-ins while the request still returns success.  Keep the old state until
+# the replacement has re-registered and passed the same exact policy check.
+_set_model = acp_adapter.server.HermesACPAgent.set_session_model
+async def constrained_set_model(self, model_id, session_id, **kwargs):
+    state = self.session_manager.get_session(session_id)
+    if state is None:
+        return await _set_model(self, model_id, session_id, **kwargs)
+    old_agent, old_model = state.agent, getattr(state, "model", None)
+    try:
+        result = await _set_model(self, model_id, session_id, **kwargs)
+        if result is None:
+            raise RuntimeError("Hermes did not acknowledge model switch")
+        servers = getattr(state, "_thinkpool_mcp_servers", ())
+        if MCP_TOOLS and not servers:
+            raise RuntimeError("ThinkPool MCP registration is unavailable after model switch")
+        await constrained_register(self, state, list(servers))
+        assert_exact_inventory(state.agent)
+        self.session_manager.save_session(session_id)
+        return result
+    except Exception:
+        # Fail closed and restore the prior usable agent/model.  A later bridge
+        # /tools probe is the external acknowledgement before UI persistence.
+        state.agent, state.model = old_agent, old_model
+        try:
+            servers = getattr(state, "_thinkpool_mcp_servers", ())
+            if servers:
+                await constrained_register(self, state, list(servers))
+            self.session_manager.save_session(session_id)
+        except Exception:
+            pass
+        raise
+acp_adapter.server.HermesACPAgent.set_session_model = constrained_set_model
+
+from acp_adapter.entry import main
+main()

package/hermes-policy.mjs

@@ -0,0 +1,85 @@
+// Bridge-owned Hermes ACP schema policy. This is intentionally a small, pure
+// contract: Python receives only this JSON and fails closed for anything else.
+export const HERMES_POLICY_VERSION = 1
+
+export const CODING_TOOLS = Object.freeze([
+  'web_search', 'web_extract', 'terminal', 'process', 'read_file', 'write_file',
+  'patch', 'search_files', 'vision_analyze', 'skills_list', 'skill_view',
+  'skill_manage', 'browser_navigate', 'browser_snapshot', 'browser_click',
+  'browser_type', 'browser_scroll', 'browser_back', 'browser_press',
+  'browser_get_images', 'browser_vision', 'browser_console', 'browser_cdp',
+  'browser_dialog', 'todo', 'memory', 'execute_code',
+])
+
+const READ_ONLY_TOOLS = Object.freeze(['read_file', 'search_files'])
+// Hermes providers advertise capabilities conditionally (for example browser
+// CDP/dialog support depends on the installed browser integration).  These are
+// the only builtins an ordinary or builder lane must have to do useful coding
+// work; the complete coding allowlist above remains permitted when available.
+export const ESSENTIAL_CODING_TOOLS = Object.freeze([
+  'terminal', 'process', 'read_file', 'write_file', 'patch', 'search_files',
+])
+const ROLE_REQUIRED = Object.freeze({
+  ordinary: ['read_terminal', 'spawn_terminal', 'close_terminal'],
+  conductor: ['submit_flow_plan'],
+  builder: ['mark_flow_done'],
+  reviewer: ['submit_flow_review', 'run_review_check', 'read_review_file'],
+  'manual-review': ['run_review_check', 'read_review_file'],
+})
+
+export function hermesRoleFor({ flowRole, sliceType } = {}) {
+  if (flowRole === 'conductor') return 'conductor'
+  if (flowRole === 'reviewer') return 'reviewer'
+  if (sliceType === 'review') return 'manual-review'
+  if (flowRole === 'builder') return 'builder'
+  return 'ordinary'
+}
+
+export function hermesPolicyForRole(role, { mcpTools } = {}) {
+  if (!Object.hasOwn(ROLE_REQUIRED, role)) throw new Error(`Unknown Hermes role policy: ${role}`)
+  const supplied = Array.isArray(mcpTools) ? mcpTools.map(String).filter(Boolean) : ROLE_REQUIRED[role]
+  const required = ROLE_REQUIRED[role]
+  // Ordinary worker leaves deliberately lack spawn/close. Main-lane proof is
+  // enforced by requiredMcpTools at dispatch; keep this schema usable for a
+  // non-delegating ordinary child without widening it.
+  const minimum = role === 'ordinary' ? ['read_terminal'] : required
+  for (const tool of minimum) if (!supplied.includes(tool)) throw new Error(`Hermes ${role} policy is missing required ThinkPool tool ${tool}`)
+  const restricted = role === 'conductor' || role === 'reviewer' || role === 'manual-review'
+  const builtinTools = restricted ? READ_ONLY_TOOLS : CODING_TOOLS
+  const requiredBuiltinTools = restricted ? READ_ONLY_TOOLS : ESSENTIAL_CODING_TOOLS
+  return Object.freeze({
+    version: HERMES_POLICY_VERSION,
+    role,
+    // `builtinTools` is the role's complete approved surface, not a promise
+    // that an availability-gated upstream provider implements every tool.
+    builtinTools,
+    requiredBuiltinTools,
+    mcpServer: 'thinkpool',
+    mcpTools: [...new Set(supplied)].sort(),
+  })
+}
+
+export function hermesRequiredMcpTools(role, { canSpawnWorkers = false } = {}) {
+  if (role === 'ordinary') return ['read_terminal', ...(canSpawnWorkers ? ['spawn_terminal', 'close_terminal'] : [])]
+  return [...ROLE_REQUIRED[role]]
+}
+
+// Keep the bridge's local /tools proof on the same canonical inventory as the
+// process-local Python bootstrap.  `allBuiltinTools` lets that proof reject a
+// known built-in which is not part of this role, rather than merely looking
+// for a couple of required MCP names.
+export function hermesExactInventory(role, options = {}) {
+  const policy = hermesPolicyForRole(role, options)
+  return Object.freeze({
+    builtinTools: [...policy.builtinTools].sort(),
+    requiredBuiltinTools: [...policy.requiredBuiltinTools].sort(),
+    mcpTools: [...policy.mcpTools].sort(),
+    // The two excluded upstream capabilities must be checked as forbidden too;
+    // they are intentionally absent from CODING_TOOLS, not unknown to policy.
+    allBuiltinTools: [...CODING_TOOLS, 'delegate_task', 'session_search'].sort(),
+  })
+}
+
+export function hermesPolicyEnv(role, options = {}) {
+  return JSON.stringify(hermesPolicyForRole(role, options))
+}

package/hermes-probe.mjs

@@ -1,8 +1,36 @@
 import { execFileSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
 
 const clean = (value) => String(value || '').replace(/[\r\n]+/g, ' ').trim()
 
-export function probeHermesRuntime({ command = 'thinkpool', prefixArgs = [], execFile = execFileSync, env = process.env } = {}) {
+const INSTALL = /Install directory:\s*(.+?)(?:\r?\n|$)/i
+const PROFILE = /Config:\s*(.+?)(?:\r?\n|$)/i
+
+// Resolve the installed venv and isolated profile once, then launch ACP through
+// bridge-owned code. `thinkpool` is only queried for inventory; it is never the
+// executable that serves an ACP lane.
+export function resolveHermesAcpRuntime({ command = 'thinkpool', execFile = execFileSync, exists = fs.existsSync, bootstrap = new URL('./hermes-acp-bootstrap.py', import.meta.url) } = {}) {
+  try {
+    const versionOutput = execFile(command, ['--version'], { encoding: 'utf8', timeout: 10_000, stdio: ['ignore', 'pipe', 'pipe'] })
+    const install = clean(String(versionOutput).match(INSTALL)?.[1])
+    if (!install || !path.isAbsolute(install)) throw new Error('Hermes did not report an absolute install directory')
+    const python = path.join(install, 'venv', 'bin', 'python')
+    const bootstrapPath = bootstrap instanceof URL ? bootstrap.pathname : String(bootstrap)
+    if (!exists(python) || !exists(bootstrapPath)) throw new Error('Hermes venv Python or ThinkPool ACP bootstrap is missing')
+    // `thinkpool` is the dedicated profile wrapper on supported installs. Its
+    // config output is evidence, not the ACP launch path.
+    const configOutput = execFile(command, ['config', 'show'], { encoding: 'utf8', timeout: 10_000, stdio: ['ignore', 'pipe', 'pipe'] })
+    const config = clean(String(configOutput).match(PROFILE)?.[1])
+    const profile = config ? path.dirname(config) : ''
+    if (!profile || !path.isAbsolute(profile) || path.basename(profile) !== 'thinkpool') throw new Error('Hermes did not report the isolated thinkpool profile')
+    return { python, bootstrap: bootstrapPath, profile, install }
+  } catch (error) {
+    return { error: clean(error?.stderr || error?.message || error) || 'could not resolve Hermes ACP runtime' }
+  }
+}
+
+export function probeHermesRuntime({ command = 'thinkpool', prefixArgs = [], execFile = execFileSync, env = process.env, strictBootstrap = false, exists = fs.existsSync } = {}) {
   try {
     const versionOutput = execFile(command, [...prefixArgs, '--version'], { encoding: 'utf8', env, timeout: 10_000, stdio: ['ignore', 'pipe', 'pipe'] })
     const version = clean(versionOutput).match(/Hermes Agent v([^\s]+)/i)?.[1] || null
@@ -16,7 +44,9 @@ export function probeHermesRuntime({ command = 'thinkpool', prefixArgs = [], exe
       && /ThinkPool blocks hidden Hermes delegation/i.test(guardOutput)
       && /pre_tool_call[\s\S]*delegate_task[\s\S]*(?:✓ allowed|allowed)/i.test(hooksOutput)
     if (!doctorHealthy || !delegationBlocked) return { available: false, version, reason: 'delegate_task guard is not healthy, unchanged, allowlisted, and structurally blocking in the dedicated Hermes profile' }
-    return { available: true, version, acpProtocol: 1, delegationBlocked: true }
+    const runtime = strictBootstrap ? resolveHermesAcpRuntime({ command, execFile, exists }) : null
+    if (runtime?.error) return { available: false, version, reason: `Hermes ACP bootstrap unavailable: ${runtime.error}` }
+    return { available: true, version, acpProtocol: 1, delegationBlocked: true, ...(runtime || {}) }
   } catch (error) {
     return { available: false, version: null, reason: clean(error?.stderr || error?.message || error) }
   }