typeclaw 0.21.0 → 0.22.0

package/src/mcp/catalog.ts

@@ -0,0 +1,29 @@
+export type McpCatalogServer = {
+  name: string
+  description?: string
+  connected: boolean
+  toolCount?: number
+}
+
+export function renderMcpCatalog(servers: McpCatalogServer[]): string {
+  const connected = servers.filter((server) => server.connected)
+  if (connected.length === 0) return ''
+
+  const lines = connected.map((server) => {
+    const toolCount = server.toolCount ?? 0
+    const description = server.description?.trim() ? server.description.trim() : 'no description'
+    return `- ${server.name} (${toolCount} tools): ${description}`
+  })
+
+  // WHY: this catalog is boot-stable for prompt-cache locality; MCP
+  // tools/list_changed notifications are intentionally not reflected here until
+  // the manager refresh path is invoked or the session restarts.
+  return [
+    '## MCP servers',
+    '',
+    'The following MCP servers are connected. Each exposes tools you can discover and call:',
+    ...lines,
+    '',
+    "Use `mcp_list_tools(server)` to see a server's tools, `mcp_describe(server, tool)` for a tool's input schema, and `mcp_call(server, tool, args)` to invoke it.",
+  ].join('\n')
+}

package/src/mcp/client.ts

@@ -0,0 +1,236 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
+import type { RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js'
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js'
+import { CallToolResultSchema, type CallToolResult, type ListToolsRequest } from '@modelcontextprotocol/sdk/types.js'
+
+import type { McpServer } from '@/config/config'
+import { resolveSecret } from '@/secrets/resolve'
+
+export type McpToolInfo = {
+  name: string
+  description: string
+  inputSchema: unknown
+}
+
+// The SDK defaults each request to 60s; typeclaw boot should fail fast enough
+// that one dead MCP server does not make the agent feel hung at startup.
+export const DEFAULT_MCP_REQUEST_TIMEOUT_MS = 30_000
+export const DEFAULT_MCP_CONNECT_TIMEOUT_MS = 15_000
+
+export type McpConnection = {
+  name: string
+  listTools(): Promise<McpToolInfo[]>
+  refresh(): Promise<McpToolInfo[]>
+  callTool(toolName: string, args?: Record<string, unknown>): Promise<CallToolResult>
+  close(): Promise<void>
+}
+
+export type McpSdkClient = {
+  listTools(
+    params?: ListToolsRequest['params'],
+    options?: RequestOptions,
+  ): Promise<{
+    tools: { name: string; description?: string; inputSchema: unknown }[]
+    nextCursor?: string
+  }>
+  callTool(
+    params: { name: string; arguments?: Record<string, unknown> },
+    resultSchema?: typeof CallToolResultSchema,
+    options?: RequestOptions,
+  ): Promise<CallToolResult>
+  close(): Promise<void>
+}
+
+type McpConnectClient = McpSdkClient & {
+  connect(transport: Transport, options?: RequestOptions): Promise<void>
+}
+
+export async function connectMcpServer(
+  server: McpServer,
+  opts: {
+    env: NodeJS.ProcessEnv
+    signal?: AbortSignal
+    connectTimeoutMs?: number
+    client?: McpConnectClient
+    transport?: Transport
+  },
+): Promise<McpConnection> {
+  const requestTimeout = server.timeoutMs ?? DEFAULT_MCP_REQUEST_TIMEOUT_MS
+  const connectTimeout = opts.connectTimeoutMs ?? DEFAULT_MCP_CONNECT_TIMEOUT_MS
+  const client = opts.client ?? new Client({ name: 'typeclaw', version: '0.17.0' }, { capabilities: {} })
+  const transport = opts.transport ?? createTransport(server, opts.env)
+
+  try {
+    await withConnectDeadline(connectTimeout, opts.signal, (signal) =>
+      client.connect(transport, { signal, timeout: requestTimeout }),
+    )
+  } catch (cause) {
+    try {
+      await client.close()
+    } catch (closeCause) {
+      attachCloseCause(cause, closeCause)
+    }
+    throw cause
+  }
+
+  return createMcpConnection(
+    server.name,
+    {
+      listTools: (params, options) => client.listTools(params, options),
+      async callTool(params, _resultSchema, options) {
+        const result = await client.callTool(params, CallToolResultSchema, options)
+        return CallToolResultSchema.parse(result)
+      },
+      close: () => client.close(),
+    },
+    { timeoutMs: requestTimeout },
+  )
+}
+
+export function createMcpConnection(
+  name: string,
+  client: McpSdkClient,
+  opts: { timeoutMs?: number; signal?: AbortSignal } = {},
+): McpConnection {
+  let cachedTools: McpToolInfo[] | undefined
+  const timeout = opts.timeoutMs ?? DEFAULT_MCP_REQUEST_TIMEOUT_MS
+
+  async function fetchTools(): Promise<McpToolInfo[]> {
+    const tools: McpToolInfo[] = []
+    let cursor: string | undefined
+    do {
+      const result = await client.listTools(cursor === undefined ? undefined : { cursor }, {
+        timeout,
+        signal: opts.signal,
+      })
+      tools.push(
+        ...result.tools.map((tool) => ({
+          name: tool.name,
+          description: tool.description ?? '',
+          inputSchema: tool.inputSchema,
+        })),
+      )
+      cursor = result.nextCursor
+    } while (cursor !== undefined)
+
+    cachedTools = tools
+    return cachedTools
+  }
+
+  return {
+    name,
+    async listTools(): Promise<McpToolInfo[]> {
+      if (cachedTools !== undefined) return cachedTools
+      return fetchTools()
+    },
+    refresh(): Promise<McpToolInfo[]> {
+      cachedTools = undefined
+      return fetchTools()
+    },
+    callTool(toolName: string, args?: Record<string, unknown>): Promise<CallToolResult> {
+      return client.callTool({ name: toolName, arguments: args }, CallToolResultSchema, {
+        timeout,
+        signal: opts.signal,
+      })
+    },
+    close(): Promise<void> {
+      return client.close()
+    },
+  }
+}
+
+function createTransport(server: McpServer, env: NodeJS.ProcessEnv): Transport {
+  return server.command
+    ? new StdioClientTransport({ command: server.command, args: server.args, env: resolveServerEnv(server, env) })
+    : new StreamableHTTPClientTransport(new URL(requiredUrl(server)))
+}
+
+async function withConnectDeadline<T>(
+  timeoutMs: number,
+  parentSignal: AbortSignal | undefined,
+  fn: (signal: AbortSignal) => Promise<T>,
+): Promise<T> {
+  const deadline = new AbortController()
+  const timer = setTimeout(() => deadline.abort(new Error('MCP connect timeout')), timeoutMs)
+  const merged = mergeSignals(parentSignal, deadline.signal)
+  const operation = fn(merged.signal)
+  let removeAbortListener = (): void => {}
+  const abort = new Promise<never>((_resolve, reject) => {
+    const onAbort = (): void => reject(merged.signal.reason)
+    removeAbortListener = (): void => merged.signal.removeEventListener('abort', onAbort)
+    if (merged.signal.aborted) onAbort()
+    else merged.signal.addEventListener('abort', onAbort, { once: true })
+  })
+  try {
+    return await Promise.race([operation, abort])
+  } finally {
+    clearTimeout(timer)
+    removeAbortListener()
+    if (merged.signal.aborted) void operation.catch(() => undefined)
+    merged.dispose()
+  }
+}
+
+function mergeSignals(...signals: (AbortSignal | undefined)[]): { signal: AbortSignal; dispose(): void } {
+  const activeSignals = signals.filter((signal): signal is AbortSignal => signal !== undefined)
+  if (activeSignals.length === 0) return { signal: new AbortController().signal, dispose() {} }
+  if (activeSignals.length === 1) return { signal: activeSignals[0]!, dispose() {} }
+
+  const controller = new AbortController()
+  const listeners: (() => void)[] = []
+  for (const signal of activeSignals) {
+    const abort = (): void => controller.abort(signal.reason)
+    if (signal.aborted) {
+      abort()
+      break
+    }
+    signal.addEventListener('abort', abort, { once: true })
+    listeners.push(() => signal.removeEventListener('abort', abort))
+  }
+
+  return {
+    signal: controller.signal,
+    dispose() {
+      for (const remove of listeners) remove()
+    },
+  }
+}
+
+function attachCloseCause(cause: unknown, closeCause: unknown): void {
+  if (!(cause instanceof Error)) return
+  const error = cause as Error & { cause?: unknown }
+  error.cause = { original: error.cause, close: closeCause }
+}
+
+// A stdio MCP server is a child process the agent spawns, so it must NOT
+// inherit the full parent environment: that env holds unrelated credentials
+// (FIREWORKS_API_KEY, GH_TOKEN, channel tokens) and inheriting them leaks every
+// secret to every server. We start from a minimal allowlist needed to spawn and
+// run a process (PATH/HOME to launch npx/bunx, locale + temp for correctness),
+// then overlay only the secrets the server explicitly declares. This mirrors
+// the bwrap sandbox's `--clearenv` + DEFAULT_SANDBOX_ENV leak guard.
+const BASE_ENV_ALLOWLIST = ['PATH', 'HOME', 'LANG', 'LC_ALL', 'TMPDIR', 'TZ'] as const
+
+export function resolveServerEnv(server: Pick<McpServer, 'env'>, env: NodeJS.ProcessEnv): Record<string, string> {
+  const childEnv: Record<string, string> = {}
+  for (const key of BASE_ENV_ALLOWLIST) {
+    const value = env[key]
+    if (value !== undefined) childEnv[key] = value
+  }
+
+  for (const [key, secret] of Object.entries(server.env)) {
+    const explicitKeyValue = env[key]
+    const resolved =
+      explicitKeyValue !== undefined && explicitKeyValue !== '' ? explicitKeyValue : resolveSecret(secret, key, env)
+    if (resolved !== undefined) childEnv[key] = resolved
+  }
+
+  return childEnv
+}
+
+function requiredUrl(server: McpServer): string {
+  if (server.url !== undefined) return server.url
+  throw new Error(`MCP server "${server.name}" is missing url`)
+}

package/src/mcp/index.ts

@@ -0,0 +1,25 @@
+export {
+  connectMcpServer,
+  createMcpConnection,
+  resolveServerEnv,
+  type McpConnection,
+  type McpSdkClient,
+  type McpToolInfo,
+} from './client'
+export {
+  createMcpManager,
+  namespaceToolName,
+  parseNamespacedTool,
+  type ConnectMcpServerFn,
+  type McpConnectResult,
+  type McpManager,
+} from './manager'
+export { renderMcpCatalog, type McpCatalogServer } from './catalog'
+export {
+  createMcpDispatcherTools,
+  MCP_DISPATCHER_TOOL_NAMES,
+  type McpCallArgs,
+  type McpDescribeArgs,
+  type McpDispatcherTool,
+  type McpListToolsArgs,
+} from './tools'

package/src/mcp/manager.ts

@@ -0,0 +1,156 @@
+import type { McpServer } from '@/config/config'
+
+import { connectMcpServer, type McpConnection } from './client'
+
+const TOOL_NAMESPACE_SEPARATOR = '__'
+
+export type McpConnectResult =
+  | { ok: true; name: string; connection: McpConnection; toolCount: number }
+  | { ok: false; name: string; error: Error }
+
+export type McpRefreshResult = { ok: true; name: string; toolCount: number } | { ok: false; name: string; error: Error }
+
+export type McpManager = {
+  connectAll(opts?: { signal?: AbortSignal }): Promise<McpConnectResult[]>
+  getConnection(name: string): McpConnection | undefined
+  listServers(): { name: string; description?: string; connected: boolean; toolCount?: number }[]
+  refresh(): Promise<McpRefreshResult[]>
+  closeAll(): Promise<void>
+}
+
+export type ConnectMcpServerFn = (
+  server: McpServer,
+  opts: { env: NodeJS.ProcessEnv; signal?: AbortSignal },
+) => Promise<McpConnection>
+
+export function createMcpManager(
+  servers: McpServer[],
+  opts: { env: NodeJS.ProcessEnv; connect?: ConnectMcpServerFn },
+): McpManager {
+  const activeServers = servers.filter((server) => server.enabled)
+  const connect = opts.connect ?? connectMcpServer
+  const connections = new Map<string, McpConnection>()
+  const toolCounts = new Map<string, number>()
+
+  return {
+    async connectAll(connectOpts: { signal?: AbortSignal } = {}): Promise<McpConnectResult[]> {
+      const firstIndexByName = new Map<string, number>()
+      const results = await Promise.all(
+        activeServers.map((server, index): Promise<McpConnectResult> => {
+          // The name is the tool namespace and the connections key, so a second
+          // server sharing a name would silently shadow the first. Fail the
+          // duplicate fast instead of connecting it, keeping routing unambiguous.
+          const firstIndex = firstIndexByName.get(server.name)
+          if (firstIndex !== undefined) {
+            return Promise.resolve({
+              ok: false,
+              name: server.name,
+              error: new Error(
+                `mcpServers[${index}].name duplicates mcpServers[${firstIndex}].name ('${server.name}')`,
+              ),
+            })
+          }
+          firstIndexByName.set(server.name, index)
+          return connectOne(server, opts.env, connect, connectOpts.signal)
+        }),
+      )
+      for (const result of results) {
+        if (!result.ok) continue
+        connections.set(result.name, result.connection)
+        toolCounts.set(result.name, result.toolCount)
+      }
+      return results
+    },
+    getConnection(name: string): McpConnection | undefined {
+      return connections.get(name)
+    },
+    listServers(): { name: string; description?: string; connected: boolean; toolCount?: number }[] {
+      return activeServers.map((server) => {
+        const toolCount = toolCounts.get(server.name)
+        return {
+          name: server.name,
+          connected: connections.has(server.name),
+          ...(server.description === undefined ? {} : { description: server.description }),
+          ...(toolCount === undefined ? {} : { toolCount }),
+        }
+      })
+    },
+    async refresh(): Promise<McpRefreshResult[]> {
+      // One unhealthy connection must not discard healthy servers' tool-count
+      // updates, so each refresh is isolated and reported per-server instead of
+      // letting a single rejection fail the whole batch.
+      return Promise.all(
+        [...connections.entries()].map(async ([name, connection]): Promise<McpRefreshResult> => {
+          try {
+            const tools = await connection.refresh()
+            toolCounts.set(name, tools.length)
+            return { ok: true, name, toolCount: tools.length }
+          } catch (cause) {
+            return { ok: false, name, error: normalizeError(cause) }
+          }
+        }),
+      )
+    },
+    async closeAll(): Promise<void> {
+      await Promise.allSettled([...connections.values()].map((connection) => connection.close()))
+      connections.clear()
+      toolCounts.clear()
+    },
+  }
+}
+
+export function namespaceToolName(server: string, tool: string): string {
+  return `${server}${TOOL_NAMESPACE_SEPARATOR}${tool}`
+}
+
+export function parseNamespacedTool(namespaced: string): { server: string; tool: string } | undefined {
+  // Config validation reserves `__` out of server names; splitting on the first
+  // separator is therefore unambiguous even when MCP tool names contain it.
+  const separatorIndex = namespaced.indexOf(TOOL_NAMESPACE_SEPARATOR)
+  if (separatorIndex <= 0) return undefined
+
+  const toolStart = separatorIndex + TOOL_NAMESPACE_SEPARATOR.length
+  if (toolStart >= namespaced.length) return undefined
+
+  return { server: namespaced.slice(0, separatorIndex), tool: namespaced.slice(toolStart) }
+}
+
+async function connectOne(
+  server: McpServer,
+  env: NodeJS.ProcessEnv,
+  connect: ConnectMcpServerFn,
+  signal: AbortSignal | undefined,
+): Promise<McpConnectResult> {
+  let connection: McpConnection | undefined
+  try {
+    connection = await connect(server, { env, signal })
+    const tools = await connection.listTools()
+    return { ok: true, name: server.name, connection, toolCount: tools.length }
+  } catch (cause) {
+    const closeError = connection === undefined ? undefined : await closeAfterFailedCatalog(connection)
+    if (closeError !== undefined) {
+      return {
+        ok: false,
+        name: server.name,
+        error: new Error(`MCP server "${server.name}" failed to connect and then failed to close`, {
+          cause: { original: cause, close: closeError },
+        }),
+      }
+    }
+    return { ok: false, name: server.name, error: normalizeError(cause) }
+  }
+}
+
+async function closeAfterFailedCatalog(connection: McpConnection): Promise<Error | undefined> {
+  try {
+    await connection.close()
+    return undefined
+  } catch (cause) {
+    return normalizeError(cause)
+  }
+}
+
+function normalizeError(cause: unknown): Error {
+  if (cause instanceof Error) return cause
+  return new Error(String(cause))
+}

package/src/mcp/tools.ts

@@ -0,0 +1,190 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
+import { z } from 'zod'
+
+import { defineTool } from '@/plugin/define'
+import type { ContentPart, Tool, ToolResult } from '@/plugin/types'
+
+import type { McpConnection, McpToolInfo } from './client'
+import type { McpManager } from './manager'
+import { namespaceToolName, parseNamespacedTool } from './manager'
+
+export const MCP_DISPATCHER_TOOL_NAMES = ['mcp_list_tools', 'mcp_describe', 'mcp_call'] as const
+
+export type McpListToolsArgs = { server: string }
+export type McpDescribeArgs = { server: string; tool: string }
+export type McpCallArgs = { server: string; tool: string; args?: Record<string, unknown> }
+export type McpDispatcherTool = Tool<McpListToolsArgs> | Tool<McpDescribeArgs> | Tool<McpCallArgs>
+export type McpDispatcherTools = [Tool<McpListToolsArgs>, Tool<McpDescribeArgs>, Tool<McpCallArgs>]
+
+export function createMcpDispatcherTools(manager: McpManager): McpDispatcherTools {
+  return [createListToolsTool(manager), createDescribeTool(manager), createCallTool(manager)]
+}
+
+function createListToolsTool(manager: McpManager): Tool<McpListToolsArgs> {
+  return defineTool<McpListToolsArgs>({
+    description: 'List the tools exposed by one connected MCP server. Returns namespaced tool ids and descriptions.',
+    parameters: z.object({
+      server: z.string().describe('The MCP server name from the system prompt catalog.'),
+    }),
+    async execute(args) {
+      const connection = manager.getConnection(args.server)
+      if (connection === undefined) return textResult(unknownServerMessage(manager, args.server))
+
+      const tools = await safeListTools(connection)
+      if (tools.length === 0) return textResult(`MCP server ${JSON.stringify(args.server)} exposes no tools.`)
+
+      const lines = tools.map((tool) => {
+        const description = tool.description.trim() === '' ? 'no description' : tool.description.trim()
+        return `- ${namespaceToolName(args.server, tool.name)} — ${description}`
+      })
+      return textResult(`Tools for MCP server ${JSON.stringify(args.server)}:\n${lines.join('\n')}`)
+    },
+  })
+}
+
+function createDescribeTool(manager: McpManager): Tool<McpDescribeArgs> {
+  return defineTool<McpDescribeArgs>({
+    description: 'Describe one MCP tool. Returns its description and full input JSON Schema.',
+    parameters: z.object({
+      server: z.string().describe('The MCP server name from the system prompt catalog.'),
+      tool: z.string().describe('The bare tool name or namespaced server__tool id.'),
+    }),
+    async execute(args) {
+      const resolved = resolveToolArgs(args.server, args.tool)
+      const connection = manager.getConnection(resolved.server)
+      if (connection === undefined) return textResult(unknownServerMessage(manager, resolved.server))
+
+      const tools = await safeListTools(connection)
+      const tool = tools.find((item) => item.name === resolved.tool)
+      if (tool === undefined) {
+        const available = tools.map((item) => namespaceToolName(resolved.server, item.name)).join(', ')
+        return textResult(
+          `Unknown MCP tool ${JSON.stringify(resolved.tool)} on server ${JSON.stringify(resolved.server)}. Available tools: ${available || 'none'}.`,
+        )
+      }
+
+      const description = tool.description.trim() === '' ? 'no description' : tool.description.trim()
+      return textResult(
+        [
+          `MCP tool ${namespaceToolName(resolved.server, tool.name)}`,
+          `Description: ${description}`,
+          '',
+          'Input schema:',
+          '```json',
+          JSON.stringify(tool.inputSchema, null, 2),
+          '```',
+        ].join('\n'),
+      )
+    },
+  })
+}
+
+function createCallTool(manager: McpManager): Tool<McpCallArgs> {
+  return defineTool<McpCallArgs>({
+    description: 'Call an MCP tool on a connected server. Use mcp_describe first to learn the input schema.',
+    parameters: z.object({
+      server: z.string().describe('The MCP server name from the system prompt catalog.'),
+      tool: z.string().describe('The bare tool name or namespaced server__tool id.'),
+      args: z.record(z.string(), z.unknown()).optional().describe('Arguments matching the tool input schema.'),
+    }),
+    async execute(args) {
+      const resolved = resolveToolArgs(args.server, args.tool)
+      const connection = manager.getConnection(resolved.server)
+      if (connection === undefined) return textResult(unknownServerMessage(manager, resolved.server))
+
+      const result = await safeCallTool(connection, resolved.tool, args.args ?? {})
+      return mapCallToolResult(resolved.server, resolved.tool, result)
+    },
+  })
+}
+
+function resolveToolArgs(server: string, tool: string): { server: string; tool: string } {
+  const parsed = parseNamespacedTool(tool)
+  return parsed ?? { server, tool }
+}
+
+function unknownServerMessage(manager: McpManager, server: string): string {
+  const available = manager
+    .listServers()
+    .filter((entry) => entry.connected)
+    .map((entry) => entry.name)
+    .join(', ')
+  return `Unknown MCP server ${JSON.stringify(server)}. Available servers: ${available || 'none'}.`
+}
+
+async function safeListTools(connection: McpConnection): Promise<McpToolInfo[]> {
+  try {
+    return await connection.listTools()
+  } catch (cause) {
+    throw new Error(`MCP list tools failed: ${sanitizeMcpError(errorMessage(cause))}`)
+  }
+}
+
+async function safeCallTool(
+  connection: McpConnection,
+  tool: string,
+  args: Record<string, unknown>,
+): Promise<CallToolResult> {
+  try {
+    return await connection.callTool(tool, args)
+  } catch (cause) {
+    throw new Error(`MCP call failed: ${sanitizeMcpError(errorMessage(cause))}`)
+  }
+}
+
+function mapCallToolResult(server: string, tool: string, result: CallToolResult): ToolResult {
+  const content = result.content.map(mapMcpContentPart)
+  if (result.isError === true) {
+    return {
+      content: content.map((part) =>
+        part.type === 'text' ? { type: 'text' as const, text: `MCP tool error: ${sanitizeMcpError(part.text)}` } : part,
+      ),
+      details: { server, tool, isError: true },
+    }
+  }
+  return { content, details: { server, tool, isError: false } }
+}
+
+function mapMcpContentPart(part: CallToolResult['content'][number]): ContentPart {
+  if (part.type === 'text' && typeof part.text === 'string') return { type: 'text', text: part.text }
+  if (part.type === 'image' && typeof part.data === 'string' && typeof part.mimeType === 'string') {
+    return { type: 'image', mimeType: part.mimeType, data: part.data }
+  }
+  return { type: 'text', text: summarizeUnsupportedPart(part) }
+}
+
+function summarizeUnsupportedPart(part: CallToolResult['content'][number]): string {
+  const type = typeof part.type === 'string' ? part.type : 'unknown'
+  const uri = readNestedString(part, 'resource', 'uri') ?? readString(part, 'uri')
+  if (uri !== undefined) return `[mcp:${type} ${uri}]`
+  const mimeType = readNestedString(part, 'resource', 'mimeType') ?? readString(part, 'mimeType')
+  if (mimeType !== undefined) return `[mcp:${type} ${mimeType}]`
+  return `[mcp:${type} omitted]`
+}
+
+export function sanitizeMcpError(raw: string): string {
+  const scrubbed = raw
+    .replace(/\b([A-Z_][A-Z0-9_]*)=\S+/g, '$1=<redacted>')
+    .replace(/(?:\/[\w.-]+)+/g, '<path>')
+    .replace(/\b[A-Za-z]:\\[^\s]+/g, '<path>')
+  return scrubbed.length <= 500 ? scrubbed : `${scrubbed.slice(0, 497)}...`
+}
+
+function errorMessage(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause)
+}
+
+function readString(value: unknown, key: string): string | undefined {
+  if (typeof value !== 'object' || value === null) return undefined
+  const found = (value as Record<string, unknown>)[key]
+  return typeof found === 'string' ? found : undefined
+}
+
+function readNestedString(value: unknown, key: string, nestedKey: string): string | undefined {
+  if (typeof value !== 'object' || value === null) return undefined
+  return readString((value as Record<string, unknown>)[key], nestedKey)
+}
+
+function textResult(text: string): ToolResult {
+  return { content: [{ type: 'text', text }] }
+}

package/src/permissions/builtins.ts

@@ -16,6 +16,13 @@ export const CORE_PERMISSIONS = {
   // an operator may grant guest channelRespond to let strangers drive masked
   // turns, but session lifecycle control stays member-and-up.
   sessionControl: 'session.control',
+  // Operate-the-agent tier: gates the /reload and /restart channel commands
+  // (both the text-prefix and native-slash paths in the router). Strictly
+  // above sessionControl — reloading config or restarting the container
+  // mutates global agent state and drops every in-flight session, so it is
+  // owner+trusted only (NOT member). A member who can /stop a turn must not
+  // be able to bounce the whole container.
+  sessionAdmin: 'session.admin',
   cronSchedule: 'cron.schedule',
   cronModify: 'cron.modify',
   subagentSpawn: 'subagent.spawn',
@@ -70,6 +77,7 @@ export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> =
     permissions: [
       CORE_PERMISSIONS.channelRespond,
       CORE_PERMISSIONS.sessionControl,
+      CORE_PERMISSIONS.sessionAdmin,
       CORE_PERMISSIONS.cronSchedule,
       CORE_PERMISSIONS.cronModify,
       CORE_PERMISSIONS.subagentSpawn,
@@ -89,6 +97,7 @@ export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> =
     permissions: [
       CORE_PERMISSIONS.channelRespond,
       CORE_PERMISSIONS.sessionControl,
+      CORE_PERMISSIONS.sessionAdmin,
       CORE_PERMISSIONS.cronSchedule,
       CORE_PERMISSIONS.subagentSpawn,
       CORE_PERMISSIONS.subagentCancel,

package/src/reload/format.ts

@@ -0,0 +1,14 @@
+import type { ReloadResult } from './types'
+
+// Human-facing /reload reply for Slack/Discord. Separate from reload-tool.ts's
+// model-facing formatter on purpose — different audience, different shape.
+export function formatChannelReloadSummary(results: readonly ReloadResult[]): string {
+  if (results.length === 0) return 'Nothing to reload.'
+  const failed = results.filter((r) => !r.ok).length
+  const header =
+    failed === 0
+      ? `Reloaded ${results.length} subsystem(s).`
+      : `Reloaded ${results.length} subsystem(s); ${failed} failed.`
+  const lines = results.map((r) => (r.ok ? `• ${r.scope}: ${r.summary}` : `• ${r.scope}: failed — ${r.reason}`))
+  return [header, ...lines].join('\n')
+}

package/src/reload/index.ts

@@ -1,3 +1,4 @@
 export { requestReload, type RequestReloadOptions } from './client'
+export { formatChannelReloadSummary } from './format'
 export { ReloadRegistry } from './registry'
 export type { Reloadable, ReloadAllResult, ReloadResult } from './types'