pstack-dsh 0.2.3

package/src/settings-api.ts

@@ -0,0 +1,48 @@
+import type { CatalogHost } from './catalog.ts'
+import { buildCatalog } from './catalog.ts'
+import type { CatalogResult } from './catalog-types.ts'
+import {
+  parseOverlay,
+  readOverlay,
+  validateOverlayAgainstCatalog,
+  writeOverlay,
+  type Overlay,
+} from './overlay.ts'
+import { resolveDshHome } from './home.ts'
+import { dropUnselectableRoles } from './settings-draft.ts'
+
+export interface SettingsSnapshot {
+  catalog: CatalogResult
+  overlay: Overlay
+  path: string
+  missing: boolean
+  droppedRoles: string[]
+}
+
+export async function loadSettingsSnapshot(host: CatalogHost): Promise<SettingsSnapshot> {
+  const dshHome = host.dshHome ?? resolveDshHome(host.env)
+  const catalog = await buildCatalog({ ...host, dshHome })
+  const current = await readOverlay(dshHome)
+  const { overlay, droppedRoles } = dropUnselectableRoles(current.overlay, catalog.routes)
+  return {
+    catalog,
+    overlay,
+    path: current.path,
+    missing: current.missing,
+    droppedRoles,
+  }
+}
+
+export async function saveSettingsOverlay(host: CatalogHost, raw: unknown): Promise<{ path: string; overlay: Overlay }> {
+  const dshHome = host.dshHome ?? resolveDshHome(host.env)
+  const overlay = typeof raw === 'string' ? parseOverlay(raw) : parseOverlay(JSON.stringify(raw))
+  const catalog = await buildCatalog({ ...host, dshHome })
+  const errors = validateOverlayAgainstCatalog(overlay, catalog.routes)
+  if (errors.length > 0) {
+    const error = new Error(`overlay rejected against live catalog:\n${errors.join('\n')}`)
+    ;(error as Error & { errors: string[] }).errors = errors
+    throw error
+  }
+  const path = await writeOverlay(overlay, dshHome)
+  return { path, overlay }
+}

package/src/settings-draft.ts

@@ -0,0 +1,144 @@
+import { ALL_ROLES, isPanelRole, type PstackRole } from './roles.ts'
+import type { LiveRoute } from './catalog-types.ts'
+import {
+  emptyOverlay,
+  routeKey,
+  type Overlay,
+  type OverlayRoute,
+} from './overlay-model.ts'
+
+export type InheritChoice = 'inherit-parent' | 'auto'
+
+export interface RoleDraft {
+  readonly role: PstackRole
+  readonly panel: boolean
+  inherit: boolean
+  inheritChoice: InheritChoice
+  routes: OverlayRoute[]
+}
+
+export function selectableRoutes(routes: readonly LiveRoute[]): LiveRoute[] {
+  return routes.filter(route => route.selectable)
+}
+
+export function overlayToDraft(overlay: Overlay): RoleDraft[] {
+  return ALL_ROLES.map(role => {
+    const assignment = overlay.roles[role] ?? { inherit: true, routes: [] }
+    const inherit = assignment.inherit || assignment.routes.length === 0
+    return {
+      role,
+      panel: isPanelRole(role),
+      inherit,
+      inheritChoice: 'inherit-parent' as InheritChoice,
+      routes: inherit ? [] : assignment.routes.map(route => ({ ...route })),
+    }
+  })
+}
+
+export function draftToOverlay(drafts: readonly RoleDraft[]): Overlay {
+  const overlay = emptyOverlay()
+  for (const draft of drafts) {
+    if (draft.inherit || draft.routes.length === 0) {
+      overlay.roles[draft.role] = { inherit: true, routes: [] }
+      continue
+    }
+    overlay.roles[draft.role] = {
+      inherit: false,
+      routes: draft.panel ? draft.routes.map(route => ({ ...route })) : [draft.routes[0]!],
+    }
+  }
+  return overlay
+}
+
+export function liveFor(routes: readonly LiveRoute[], provider: string, model: string): LiveRoute | undefined {
+  return routes.find(route => route.selectable && route.provider === provider && route.model === model)
+}
+
+export function stripIllegalEffort(route: OverlayRoute, live: readonly LiveRoute[]): OverlayRoute {
+  const found = liveFor(live, route.provider, route.model)
+  if (found === undefined) return { provider: route.provider, model: route.model }
+  if (route.reasoningEffort === undefined) return { provider: route.provider, model: route.model }
+  if (found.efforts.length === 0) return { provider: route.provider, model: route.model }
+  if (!found.efforts.some(effort => effort.id === route.reasoningEffort)) {
+    return { provider: route.provider, model: route.model }
+  }
+  return { provider: route.provider, model: route.model, reasoningEffort: route.reasoningEffort }
+}
+
+/** Stale overlay entries become inherit in the returned overlay; original file is not written. */
+export function dropUnselectableRoles(overlay: Overlay, live: readonly LiveRoute[]): {
+  overlay: Overlay
+  droppedRoles: string[]
+} {
+  const next = emptyOverlay()
+  const droppedRoles: string[] = []
+  const selectable = new Set(live.filter(route => route.selectable).map(route => routeKey(route.provider, route.model)))
+  for (const role of ALL_ROLES) {
+    const assignment = overlay.roles[role] ?? { inherit: true, routes: [] }
+    if (role === 'how-critics') {
+      next.roles[role] = { inherit: assignment.inherit, routes: assignment.routes.map(route => ({ ...route })) }
+      continue
+    }
+    if (assignment.inherit || assignment.routes.length === 0) {
+      next.roles[role] = { inherit: true, routes: [] }
+      continue
+    }
+    const kept = assignment.routes
+      .filter(route => selectable.has(routeKey(route.provider, route.model)))
+      .map(route => stripIllegalEffort(route, live))
+    if (kept.length === 0) {
+      droppedRoles.push(role)
+      next.roles[role] = { inherit: true, routes: [] }
+      continue
+    }
+    if (kept.length !== assignment.routes.length) droppedRoles.push(role)
+    next.roles[role] = {
+      inherit: false,
+      routes: isPanelRole(role) ? kept : [kept[0]!],
+    }
+  }
+  return { overlay: next, droppedRoles }
+}
+
+export function applyInheritAll(drafts: RoleDraft[], choice: InheritChoice = 'inherit-parent'): RoleDraft[] {
+  return drafts.map(draft => draft.role === 'how-critics' ? draft : ({
+    ...draft,
+    inherit: true,
+    inheritChoice: choice,
+    routes: [],
+  }))
+}
+
+export function applyRouteToAll(drafts: RoleDraft[], route: OverlayRoute, live: readonly LiveRoute[]): RoleDraft[] {
+  const cleaned = stripIllegalEffort(route, live)
+  if (liveFor(live, cleaned.provider, cleaned.model) === undefined) return drafts
+  return drafts.map(draft => draft.role === 'how-critics' ? draft : ({
+    ...draft,
+    inherit: false,
+    inheritChoice: 'inherit-parent',
+    routes: draft.panel ? [{ ...cleaned }] : [{ ...cleaned }],
+  }))
+}
+
+export function routeSelectValue(draft: RoleDraft, index = 0): string {
+  if (draft.inherit || draft.routes.length === 0) return draft.inheritChoice
+  const route = draft.routes[index]
+  if (route === undefined) return draft.inheritChoice
+  return routeKey(route.provider, route.model)
+}
+
+export function parseRouteSelectValue(
+  value: string,
+  live: readonly LiveRoute[],
+): { inherit: true; inheritChoice: InheritChoice } | { inherit: false; route: OverlayRoute } {
+  if (value === 'inherit-parent' || value === 'auto') {
+    return { inherit: true, inheritChoice: value }
+  }
+  const separator = value.indexOf('::')
+  if (separator <= 0) return { inherit: true, inheritChoice: 'inherit-parent' }
+  const provider = value.slice(0, separator)
+  const model = value.slice(separator + 2)
+  const found = liveFor(live, provider, model)
+  if (found === undefined) return { inherit: true, inheritChoice: 'inherit-parent' }
+  return { inherit: false, route: { provider: found.provider, model: found.model } }
+}

package/src/settings-routes.ts

@@ -0,0 +1,77 @@
+/** Same-origin Settings snapshot/save. Overlay file is `$DSH_HOME/pstack-dsh.json`. */
+
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-client-connection'
+import type { CatalogHost } from './catalog.ts'
+import { SETTINGS_SAVE_PATH, SETTINGS_SNAPSHOT_PATH } from './ids.ts'
+import { json, readJson, trustedRequest } from './http-trust.ts'
+import { loadSettingsSnapshot, saveSettingsOverlay } from './settings-api.ts'
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+async function handleSnapshot(host: CatalogHost, req: IncomingMessage, res: ServerResponse): Promise<void> {
+  if (req.method !== 'GET') {
+    json(res, 405, { error: 'method not allowed' })
+    return
+  }
+  json(res, 200, await loadSettingsSnapshot(host))
+}
+
+async function handleSave(host: CatalogHost, req: IncomingMessage, res: ServerResponse): Promise<void> {
+  if (req.method !== 'PUT' && req.method !== 'POST') {
+    json(res, 405, { error: 'method not allowed' })
+    return
+  }
+  try {
+    const body = await readJson(req)
+    const overlay = isRecord(body) && 'overlay' in body ? body.overlay : body
+    const saved = await saveSettingsOverlay(host, overlay)
+    json(res, 200, saved)
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : 'save failed'
+    const errors = error instanceof Error && 'errors' in error && Array.isArray(error.errors)
+      ? error.errors as string[]
+      : undefined
+    json(res, 400, { error: message, ...errors === undefined ? {} : { errors } })
+  }
+}
+
+export function registerPstackSettingsRoutes(ctx: Context, host: CatalogHost): void {
+  const webServer = ctx.webServer
+  if (webServer === undefined) return
+  ctx.effect(() => {
+    const routes = [
+      webServer.register({
+        kind: 'exact',
+        path: SETTINGS_SNAPSHOT_PATH,
+        handler: async (req, res) => {
+          const rejection = ctx.connection.requestRejection(req)
+          if (rejection !== undefined) {
+            json(res, rejection, { error: rejection === 401 ? 'unauthorized' : 'forbidden' })
+            return
+          }
+          if (!trustedRequest(req)) {
+            json(res, 403, { error: 'forbidden' })
+            return
+          }
+          if (req.method === 'GET') {
+            await handleSnapshot(host, req, res)
+            return
+          }
+          await handleSave(host, req, res)
+        },
+      }),
+    ]
+    return () => {
+      for (const dispose of routes) dispose()
+    }
+  }, 'pstack-dsh: Settings overlay routes')
+}
+
+export const SETTINGS_HTTP = {
+  snapshot: SETTINGS_SNAPSHOT_PATH,
+  save: SETTINGS_SAVE_PATH,
+} as const

package/src/skills-provider.ts

@@ -0,0 +1,96 @@
+import { readdir, readFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseSkillMarkdown } from './frontmatter.ts'
+import { SKILL_PROVIDER_NAME } from './ids.ts'
+
+const BUNDLED_SKILL_RANK = 600
+
+export function defaultSkillsRoot(): string {
+  return join(dirname(fileURLToPath(import.meta.url)), '..', 'skills')
+}
+
+interface SkillRecord {
+  name: string
+  description: string
+  whenToUse?: string
+  modelInvocable: boolean
+  userInvocable: boolean
+  content: string
+  dir: string
+}
+
+async function loadSkills(root: string): Promise<SkillRecord[]> {
+  let entries: string[] = []
+  try {
+    entries = await readdir(root)
+  } catch {
+    return []
+  }
+  const records: SkillRecord[] = []
+  for (const name of entries) {
+    const dir = join(root, name)
+    const path = join(dir, 'SKILL.md')
+    let text: string
+    try {
+      text = await readFile(path, 'utf8')
+    } catch {
+      continue
+    }
+    const parsed = parseSkillMarkdown(text, name)
+    if (parsed === undefined) continue
+    records.push({
+      name: parsed.frontmatter.name,
+      description: parsed.frontmatter.description,
+      ...parsed.frontmatter.whenToUse === undefined ? {} : { whenToUse: parsed.frontmatter.whenToUse },
+      modelInvocable: parsed.frontmatter.modelInvocable,
+      userInvocable: parsed.frontmatter.userInvocable,
+      content: parsed.content,
+      dir,
+    })
+  }
+  return records.sort((a, b) => a.name.localeCompare(b.name))
+}
+
+export function createSkillProvider(skillsRoot = defaultSkillsRoot()) {
+  return {
+    name: SKILL_PROVIDER_NAME,
+    async list() {
+      const skills = await loadSkills(skillsRoot)
+      return skills.map(skill => ({
+        name: skill.name,
+        description: skill.description,
+        ...skill.whenToUse === undefined ? {} : { whenToUse: skill.whenToUse },
+        invocation: {
+          modelInvocable: skill.modelInvocable,
+          userInvocable: skill.userInvocable,
+        },
+        provider: SKILL_PROVIDER_NAME,
+        source: 'bundled' as const,
+        resourceBase: { kind: 'directory' as const, path: skill.dir },
+        rank: BUNDLED_SKILL_RANK,
+        locator: skill.dir,
+        path: join(skill.dir, 'SKILL.md'),
+      }))
+    },
+    async get(candidate: { name: string; locator?: unknown }) {
+      const skills = await loadSkills(skillsRoot)
+      const skill = skills.find(entry => entry.name === candidate.name)
+      if (skill === undefined) return undefined
+      return {
+        name: skill.name,
+        description: skill.description,
+        ...skill.whenToUse === undefined ? {} : { whenToUse: skill.whenToUse },
+        invocation: {
+          modelInvocable: skill.modelInvocable,
+          userInvocable: skill.userInvocable,
+        },
+        provider: SKILL_PROVIDER_NAME,
+        source: 'bundled' as const,
+        resourceBase: { kind: 'directory' as const, path: skill.dir },
+        content: skill.content,
+        path: join(skill.dir, 'SKILL.md'),
+      }
+    },
+  }
+}

package/src/spawn.ts

@@ -0,0 +1,52 @@
+import type { Overlay, OverlayRoute } from './overlay.ts'
+import { resolveRole } from './overlay.ts'
+import { normalizeRole } from './roles.ts'
+
+export interface SpawnRequest {
+  readonly role: string
+  readonly description: string
+  readonly prompt: string
+  readonly runInBackground: boolean
+  readonly routeIndex?: number
+}
+
+export interface AgentOptions {
+  provider?: string
+  model?: string
+}
+
+export interface ResolvedSpawn {
+  readonly role: string
+  readonly description: string
+  readonly prompt: string
+  readonly runInBackground: boolean
+  readonly inherit: boolean
+  readonly agentOptions?: AgentOptions
+  readonly reasoningEffort?: string
+  readonly route?: OverlayRoute
+}
+
+export function resolveSpawn(overlay: Overlay, request: SpawnRequest): ResolvedSpawn {
+  const role = normalizeRole(request.role)
+  const assignment = resolveRole(overlay, role)
+  const inherit = assignment.inherit || assignment.routes.length === 0
+  const index = request.routeIndex ?? 0
+  const route = inherit ? undefined : assignment.routes[index] ?? assignment.routes[0]
+  return {
+    role,
+    description: request.description,
+    prompt: request.prompt,
+    runInBackground: request.runInBackground,
+    inherit,
+    ...route === undefined
+      ? {}
+      : {
+        agentOptions: { provider: route.provider, model: route.model },
+        route,
+        ...route.reasoningEffort === undefined ? {} : { reasoningEffort: route.reasoningEffort },
+      },
+  }
+}
+
+/** Fields a skill may send on pstack_spawn. Official `subagent` has no model/effort. */
+export const SPAWN_MODEL_FIELDS = ['description', 'prompt', 'role', 'run_in_background', 'route_index'] as const

package/src/tools.ts

@@ -0,0 +1,226 @@
+import type { ParameterSchemaSpec } from '@deepseek-ai/dsh-tools'
+import type { CatalogHost } from './catalog.ts'
+import { buildCatalog } from './catalog.ts'
+import {
+  parseOverlay,
+  readOverlay,
+  validateOverlayAgainstCatalog,
+  writeOverlay,
+  type Overlay,
+} from './overlay.ts'
+import { resolveDshHome } from './home.ts'
+import { loadPersona } from './persona.ts'
+import { applyRoleConfig, RoleEffortMap } from './request-overlay.ts'
+import { resolveSpawn } from './spawn.ts'
+import { isPstackRole, normalizeRole } from './roles.ts'
+import {
+  SPAWN_PROVIDER,
+  TOOL_CATALOG,
+  TOOL_OVERLAY_READ,
+  TOOL_OVERLAY_WRITE,
+  TOOL_SPAWN,
+} from './ids.ts'
+
+export interface ToolDefinition {
+  name: string
+  description: string
+  parameters: ParameterSchemaSpec
+  execute(args: Record<string, unknown>, exec: { signal?: AbortSignal; agent?: { id: string } }): Promise<unknown>
+}
+
+export interface SubagentHandle {
+  start(provider: string, request: Record<string, unknown>): Promise<{ id: string; result: Promise<{ output?: unknown; stopReason?: string }>; dispose?: () => Promise<void> | void }>
+  startContinuable?(args: { provider: string; label?: string; request: Record<string, unknown>; signal?: AbortSignal }): Promise<{ childId: string }>
+  getProvider?(name: string): { prepareContinuable?: unknown; capabilities?: { persona?: boolean } } | undefined
+}
+
+export interface ToolHost {
+  llm?: CatalogHost['llm']
+  credentials?: CatalogHost['credentials']
+  settings?: CatalogHost['settings']
+  subagents?: SubagentHandle
+  dshHome?: string
+  env?: NodeJS.ProcessEnv
+  spawnProvider?: string
+  roles: RoleEffortMap
+}
+
+function textPrompt(prompt: string): unknown[] {
+  return [{ type: 'text', text: prompt }]
+}
+
+export function catalogTool(host: ToolHost): ToolDefinition {
+  return {
+    name: TOOL_CATALOG,
+    description:
+      'List live DSH LLM routes pstack may use: registered adapters with a logged-in API key, plus OAuth store routes (dsh-oauth-login, dsh-antigravity-oauth) that are already signed in. Never a vendor catalog. Secrets are omitted.',
+    parameters: {},
+    async execute(_args, exec) {
+      return buildCatalog({
+        llm: host.llm,
+        credentials: host.credentials,
+        settings: host.settings,
+        dshHome: host.dshHome,
+        env: host.env,
+      }, exec.signal)
+    },
+  }
+}
+
+export function overlayReadTool(host: ToolHost): ToolDefinition {
+  return {
+    name: TOOL_OVERLAY_READ,
+    description: 'Read $DSH_HOME/pstack-dsh.json. Missing file means inherit the parent conversation for every role.',
+    parameters: {},
+    async execute() {
+      const current = await readOverlay(host.dshHome ?? resolveDshHome(host.env))
+      return {
+        path: current.path,
+        missing: current.missing,
+        overlay: current.overlay,
+      }
+    },
+  }
+}
+
+export function overlayWriteTool(host: ToolHost): ToolDefinition {
+  return {
+    name: TOOL_OVERLAY_WRITE,
+    description:
+      'Write $DSH_HOME/pstack-dsh.json after validating every provider/model/effort against pstack_catalog. inherit-parent is stored as inherit: true with empty routes.',
+    parameters: {
+      overlay: {
+        type: 'json',
+        required: true,
+        description: 'Full overlay object { version: 1, roles: { <role>: { inherit, routes } } }',
+      },
+    },
+    async execute(args) {
+      const overlay = typeof args.overlay === 'string'
+        ? parseOverlay(args.overlay)
+        : parseOverlay(JSON.stringify(args.overlay))
+      const catalog = await buildCatalog({
+        llm: host.llm,
+        credentials: host.credentials,
+        settings: host.settings,
+        dshHome: host.dshHome,
+        env: host.env,
+      })
+      const errors = validateOverlayAgainstCatalog(overlay, catalog.routes)
+      if (errors.length > 0) {
+        throw new Error(`overlay rejected against live catalog:\n${errors.join('\n')}`)
+      }
+      const path = await writeOverlay(overlay, host.dshHome ?? resolveDshHome(host.env))
+      return { path, overlay }
+    },
+  }
+}
+
+export function spawnTool(host: ToolHost): ToolDefinition {
+  return {
+    name: TOOL_SPAWN,
+    description:
+      'Delegate a pstack role to a DSH subagent via ctx.subagents (spawn provider). Send description, prompt, role, and optional run_in_background. Do not send model, provider, reasoning_effort, thinking, isolation, or subagent_type. Route and effort come from $DSH_HOME/pstack-dsh.json when that role is mapped to a live logged-in route; otherwise the child inherits this conversation.',
+    parameters: {
+      description: {
+        type: 'string',
+        required: true,
+        description: 'A short (3-5 word) description of the delegated task, for display.',
+      },
+      prompt: {
+        type: 'string',
+        required: true,
+        description: 'The complete, self-contained task. The child does not see this conversation.',
+      },
+      role: {
+        type: 'string',
+        required: true,
+        description: 'pstack role key (feature, how-explainer, poteto-agent, comment-sicko, …).',
+      },
+      run_in_background: {
+        type: 'boolean',
+        description: 'Default true. Continuable children return a subagent id; one-shot background returns a job-like start without waiting.',
+      },
+      route_index: {
+        type: 'number',
+        description: 'Which overlay route to use for a panel role. Default 0.',
+      },
+    },
+    async execute(args, exec) {
+      const parent = exec.agent
+      if (parent === undefined) throw new Error('pstack_spawn requires a calling agent')
+      const subagents = host.subagents
+      if (subagents === undefined) throw new Error('pstack_spawn requires ctx.subagents')
+      const role = normalizeRole(String(args.role ?? ''))
+      if (role === 'how-critics') {
+        return { kind: 'disabled', role, reason: 'how-critics was retired in pstack 0.15; no agent was started.' }
+      }
+      if (!isPstackRole(role) && role.length === 0) throw new Error('pstack_spawn role is required')
+      const overlay: Overlay = (await readOverlay(host.dshHome ?? resolveDshHome(host.env))).overlay
+      const resolved = resolveSpawn(overlay, {
+        role,
+        description: String(args.description ?? ''),
+        prompt: String(args.prompt ?? ''),
+        runInBackground: args.run_in_background !== false,
+        routeIndex: typeof args.route_index === 'number' ? args.route_index : undefined,
+      })
+      if (resolved.description.trim().length === 0) throw new Error('description is required')
+      if (resolved.prompt.trim().length === 0) throw new Error('prompt is required')
+
+      const persona = await loadPersona(resolved.role)
+      const providerName = host.spawnProvider ?? SPAWN_PROVIDER
+      const provider = subagents.getProvider?.(providerName)
+      const request: Record<string, unknown> = {
+        label: resolved.description,
+        prompt: textPrompt(resolved.prompt),
+        parent,
+        signal: exec.signal,
+        ...resolved.agentOptions ? { agentOptions: resolved.agentOptions } : {},
+        ...persona && provider?.capabilities?.persona !== false ? { persona } : {},
+      }
+
+      const remember = (sessionId: string) => {
+        host.roles.remember(sessionId, {
+          role: resolved.role,
+          ...resolved.reasoningEffort ? { reasoningEffort: resolved.reasoningEffort } : {},
+          ...resolved.agentOptions?.provider ? { provider: resolved.agentOptions.provider } : {},
+          ...resolved.agentOptions?.model ? { model: resolved.agentOptions.model } : {},
+        })
+      }
+
+      if (resolved.runInBackground && typeof subagents.startContinuable === 'function' && provider?.prepareContinuable !== undefined) {
+        const started = await subagents.startContinuable({
+          provider: providerName,
+          label: resolved.description,
+          request,
+          signal: exec.signal,
+        })
+        remember(started.childId)
+        return { kind: 'continuable', subagentId: started.childId, role: resolved.role, inherit: resolved.inherit }
+      }
+
+      const run = await subagents.start(providerName, request)
+      remember(run.id)
+      if (resolved.runInBackground) {
+        return { kind: 'foreground-detached', runId: run.id, role: resolved.role, inherit: resolved.inherit }
+      }
+      const result = await run.result
+      await Promise.resolve(run.dispose?.())
+      return {
+        kind: 'foreground',
+        runId: run.id,
+        role: resolved.role,
+        inherit: resolved.inherit,
+        output: result.output ?? null,
+        stopReason: result.stopReason ?? 'completed',
+      }
+    },
+  }
+}
+
+export function bindRequestOverlay(roles: RoleEffortMap) {
+  return (sessionId: string, config: Parameters<typeof applyRoleConfig>[0]) =>
+    applyRoleConfig(config, roles.lookup(sessionId))
+}
+
+export const ALL_TOOLS = [catalogTool, overlayReadTool, overlayWriteTool, spawnTool] as const