typeclaw 0.20.0 → 0.22.0

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'

package/src/run/bundled-plugins.ts

@@ -1,5 +1,6 @@
 import agentBrowserPlugin from '@/bundled-plugins/agent-browser'
 import backupPlugin from '@/bundled-plugins/backup'
+import bunHygienePlugin from '@/bundled-plugins/bun-hygiene'
 import explorerPlugin from '@/bundled-plugins/explorer'
 import githubCliAuthPlugin from '@/bundled-plugins/github-cli-auth'
 import guardPlugin from '@/bundled-plugins/guard'
@@ -29,6 +30,11 @@ import type { ResolvedPlugin } from '@/plugin'
 // Reversing this order would make guard advise on the full oversized payload
 // and then tool-result-cap would clobber the advice text along with the rest.
 //
+// `bun-hygiene` is registered after `guard` and guards a disjoint surface
+// (package-manager bash commands: global installs and non-bun managers), so its
+// position relative to security/guard only matters for precedence — keeping it
+// after the two general guards means a security/guard block always wins first.
+//
 // `github-cli-auth` is registered AFTER `security` so security's `tool.before`
 // runs its exfil/secret scanners on the bash command first. github-cli-auth
 // injects the minted token via an env overlay (TYPECLAW_INTERNAL_BASH_ENV), not
@@ -45,6 +51,7 @@ export const BUNDLED_PLUGINS: ResolvedPlugin[] = [
   { name: 'security', version: undefined, source: '<bundled>', defined: securityPlugin },
   { name: 'tool-result-cap', version: undefined, source: '<bundled>', defined: toolResultCapPlugin },
   { name: 'guard', version: undefined, source: '<bundled>', defined: guardPlugin },
+  { name: 'bun-hygiene', version: undefined, source: '<bundled>', defined: bunHygienePlugin },
   { name: 'github-cli-auth', version: undefined, source: '<bundled>', defined: githubCliAuthPlugin },
   { name: 'memory', version: undefined, source: '<bundled>', defined: memoryPlugin },
   { name: 'backup', version: undefined, source: '<bundled>', defined: backupPlugin },

package/src/run/channel-session-factory.ts

@@ -7,6 +7,7 @@ import type { CreateSessionForSubagent, SubagentRegistry } from '@/agent/subagen
 import { capJsonlFileInPlace } from '@/bundled-plugins/tool-result-cap/cap-jsonl'
 import type { CapOptions } from '@/bundled-plugins/tool-result-cap/cap-result'
 import type { CreateSessionForChannel, ChannelRouter } from '@/channels'
+import type { McpManager } from '@/mcp'
 import type { PermissionService, RolesConfig } from '@/permissions'
 import type { ReloadRegistry } from '@/reload'
 import type { SessionFactory } from '@/sessions'
@@ -35,6 +36,7 @@ export type BuildChannelSessionFactoryDeps = {
   // cycle while still ensuring the factory's sessions get the same router
   // their inbound messages came from.
   getChannelRouter: () => ChannelRouter
+  mcpManager?: McpManager
   containerName?: string
   runtimeVersion?: string
   // When set, rehydrating a session JSONL caps oversized tool results in the
@@ -113,6 +115,7 @@ export function buildChannelSessionFactory(deps: BuildChannelSessionFactoryDeps)
       sessionManager,
       stream: deps.stream,
       channelRouter: deps.getChannelRouter(),
+      ...(deps.mcpManager !== undefined ? { mcpManager: deps.mcpManager } : {}),
       origin,
       originRef,
       ...(snap.hasAnyPluginContent

package/src/run/index.ts

@@ -3,6 +3,7 @@ import { SessionManager } from '@mariozechner/pi-coding-agent'
 import { createSession, createSessionWithDispose } from '@/agent'
 import { LiveSessionRegistry } from '@/agent/live-sessions'
 import { LiveSubagentRegistry } from '@/agent/live-subagents'
+import { requestContainerRestart } from '@/agent/restart'
 import type { SessionOrigin } from '@/agent/session-origin'
 import {
   awaitWithSubagentTimeout,
@@ -38,11 +39,12 @@ import {
   type Scheduler,
 } from '@/cron'
 import { CLI_VERSION } from '@/init/cli-version'
+import { createMcpManager } from '@/mcp'
 import { loadPlugins, type LoadPluginsResult, pluginCronJobs, type PluginRegistry, summarizeLoaded } from '@/plugin'
 import { createPluginLogger } from '@/plugin/context'
 import type { CronHandlerContext } from '@/plugin/types'
 import { createContainerBroker, publishForwardResult } from '@/portbroker'
-import { ReloadRegistry } from '@/reload'
+import { formatChannelReloadSummary, ReloadRegistry } from '@/reload'
 import { createClaimController } from '@/role-claim'
 import {
   exportClaudeCredentialsFileForAgent,
@@ -140,6 +142,15 @@ export async function startAgent({
   const pluginConfigsByName = loadPluginConfigsSync(cwd)
   const cwdConfig = loadConfigSync(cwd)
   const githubTokenBridge = createGithubTokenBridge()
+  const mcpManager =
+    cwdConfig.mcpServers.length > 0 ? createMcpManager(cwdConfig.mcpServers, { env: process.env }) : null
+  if (mcpManager !== null) {
+    const results = await mcpManager.connectAll()
+    for (const result of results) {
+      if (!result.ok) console.warn(`[mcp] ${result.name} failed to connect: ${result.error.message}`)
+    }
+  }
+  const mcpManagerOpt = mcpManager !== null ? { mcpManager } : {}
   const pluginsLoaded = await loadPlugins({
     entries: cwdConfig.plugins,
     agentDir: cwd,
@@ -255,11 +266,32 @@ export async function startAgent({
       getCreateSessionForSubagent: () => createSessionForSubagent,
       ...containerNameOpt,
       ...runtimeVersionOpt,
+      ...mcpManagerOpt,
     }),
     permissions: pluginsLoaded.permissions,
     claimHandler: claimController.claimHandler,
     githubTokenBridge,
     stream,
+    onReload: async () => {
+      const { results } = await reloadRegistry.reloadAll()
+      return formatChannelReloadSummary(results)
+    },
+    // Always registered so /restart's presence in /help, the Slack manifest,
+    // and the Discord declarations is environment-independent. When there is no
+    // container to bounce (TYPECLAW_CONTAINER_NAME unset — tests, ad-hoc
+    // `typeclaw run` outside Docker), the handler reports that instead of the
+    // command resolving as unknown, which would make the advertised contract
+    // depend on the runtime environment.
+    onRestart: async (): Promise<string> => {
+      if (containerName === undefined) {
+        return 'Restart is unavailable: this agent is not running inside a typeclaw container.'
+      }
+      // No originatingSessionId/stream/handoff: a channel-invoked restart must
+      // not write a resume hint or fire the "I'm back" broadcast that a TUI
+      // restart does (issue #291 scoping — only TUI origins resume).
+      const result = await requestContainerRestart({ containerName })
+      return result.ok ? 'Restart scheduled; the container will bounce shortly.' : `Restart denied: ${result.reason}`
+    },
   })
 
   const createSessionForSubagent: import('@/agent/subagents').CreateSessionForSubagent = async (
@@ -376,6 +408,7 @@ export async function startAgent({
             containerName: containerNameOpt.containerName,
             sessionFactory,
             channelRouter: channelManager.router,
+            ...mcpManagerOpt,
           }),
         subagent: (subName: string, payload?: unknown) =>
           dispatchSpawnSubagent(subName, payload, {
@@ -424,6 +457,7 @@ export async function startAgent({
         createSessionForSubagent,
         ...containerNameOpt,
         ...runtimeVersionOpt,
+        ...mcpManagerOpt,
       })
       liveSessionRegistry.register({ sessionId, session })
       return {
@@ -591,6 +625,7 @@ export async function startAgent({
       outbound,
       sessionFactory,
       channelRouter: channelManager.router,
+      ...mcpManagerOpt,
     })
 
   const server = createServer({
@@ -600,6 +635,7 @@ export async function startAgent({
     sessionFactory,
     stream,
     channelRouter: channelManager.router,
+    ...mcpManagerOpt,
     agentDir: cwd,
     pluginRuntime,
     claimController,
@@ -634,6 +670,7 @@ export async function startAgent({
     subagentCompletionBridge.stop()
     await tunnelManager.stop()
     await channelManager.stop()
+    await mcpManager?.closeAll()
     uninstallCodexFetchObserver()
   }
 

package/src/server/command-runner.ts

@@ -6,6 +6,7 @@ import {
   type SessionOrigin,
 } from '@/agent'
 import type { ChannelRouter } from '@/channels/router'
+import type { McpManager } from '@/mcp'
 import type { PermissionService } from '@/permissions'
 import type {
   CommandExecResult,
@@ -53,6 +54,7 @@ export type CommandRunnerOptions = {
   // `channelManager.router` via `createSessionForCron`; this is the matching
   // wire for the handler/command path.
   channelRouter: ChannelRouter | undefined
+  mcpManager?: McpManager
 }
 
 type CommandHandle = {
@@ -192,6 +194,7 @@ export function createCommandRunner(opts: CommandRunnerOptions): CommandRunner {
               signal: abortController.signal,
               sessionFactory: opts.sessionFactory,
               channelRouter: opts.channelRouter,
+              ...(opts.mcpManager !== undefined ? { mcpManager: opts.mcpManager } : {}),
             }),
           subagent: (subName, payload) =>
             opts.spawnSubagent(subName, payload, {
@@ -376,6 +379,7 @@ export async function runPromptForCommand(args: {
   // See CommandRunnerOptions.channelRouter. Threaded to createSessionWithDispose
   // so the spawned session exposes `channel_send`.
   channelRouter?: ChannelRouter
+  mcpManager?: McpManager
   // Test seam for the agent-session boundary. Production passes the real
   // `createSessionWithDispose`; tests inject a fake to verify wiring
   // (specifically: the sessionManager handed off must be persisted, not
@@ -402,6 +406,7 @@ export async function runPromptForCommand(args: {
       agentDir: args.agentDir,
     },
     ...(args.channelRouter !== undefined ? { channelRouter: args.channelRouter } : {}),
+    ...(args.mcpManager !== undefined ? { mcpManager: args.mcpManager } : {}),
     ...(args.runtimeVersion !== undefined ? { runtimeVersion: args.runtimeVersion } : {}),
     ...(args.containerName !== undefined ? { containerName: args.containerName } : {}),
   })

package/src/server/index.ts

@@ -12,12 +12,14 @@ import { runPluginDoctorChecks, runPluginDoctorFix } from '@/agent/doctor'
 import type { LiveSessionRegistry } from '@/agent/live-sessions'
 import type { LiveSubagentRegistry } from '@/agent/live-subagents'
 import { detectProviderError } from '@/agent/provider-error'
+import { requestContainerRestart } from '@/agent/restart'
 import { consumeRestartHandoff, type RestartHandoff } from '@/agent/restart-handoff'
 import type { SessionOrigin } from '@/agent/session-origin'
 import { parseSubagentCompletedPayload, renderSubagentCompletionReminder } from '@/agent/subagent-completion-reminder'
 import type { CreateSessionForSubagent } from '@/agent/subagents'
 import type { ChannelRouter } from '@/channels/router'
 import { aggregateCronList, type CronListEntry, loadCron } from '@/cron'
+import type { McpManager } from '@/mcp'
 import type { HookBus } from '@/plugin'
 import type { BrokerWsData, ContainerBroker } from '@/portbroker'
 import type { ReloadAllResult, ReloadRegistry } from '@/reload'
@@ -60,6 +62,7 @@ export type ServerOptions = {
   sessionFactory?: SessionFactory
   stream?: Stream
   channelRouter?: ChannelRouter
+  mcpManager?: McpManager
   agentDir?: string
   pluginRuntime?: PluginRuntime
   containerName?: string
@@ -220,6 +223,7 @@ export function createServer({
   sessionFactory,
   stream,
   channelRouter,
+  mcpManager,
   agentDir,
   pluginRuntime,
   containerName,
@@ -470,6 +474,7 @@ export function createServer({
               origin,
               ...(stream ? { stream } : {}),
               ...(channelRouter ? { channelRouter } : {}),
+              ...(mcpManager ? { mcpManager } : {}),
               ...(pluginsWiring ? { plugins: pluginsWiring } : {}),
               ...(containerName !== undefined ? { containerName } : {}),
               ...(runtimeVersion !== undefined ? { runtimeVersion } : {}),
@@ -652,6 +657,11 @@ export function createServer({
             return
           }
 
+          if (msg.type === 'restart') {
+            await handleRestart(ws, state, containerName, agentDir, stream)
+            return
+          }
+
           if (msg.type === 'doctor') {
             await handleDoctor(ws, msg.requestId, pluginRuntime, agentDir)
             return
@@ -1437,3 +1447,46 @@ async function handleReload(
     })
   }
 }
+
+async function handleRestart(
+  ws: Ws,
+  state: SessionState | undefined,
+  containerName: string | undefined,
+  agentDir: string | undefined,
+  stream: Stream | undefined,
+): Promise<void> {
+  if (containerName === undefined) {
+    send(ws, {
+      type: 'restart_result',
+      status: 'failed',
+      error: 'restart unavailable: no container name configured',
+    })
+    return
+  }
+
+  // Pass stream so requestContainerRestart fans out the container-restarting
+  // notice — the originating session's subscribeRestartNotice appends the
+  // typeclaw.restart-self entry to its JSONL before the handoff is written, so
+  // the rebooted container resumes with the "I'm back" instruction (same path
+  // the agent restart tool uses).
+  const originatingSessionFile = state?.sessionManager?.getSessionFile()
+  const result = await requestContainerRestart({
+    containerName,
+    ...(agentDir !== undefined ? { agentDir } : {}),
+    ...(state?.sessionFileId !== undefined ? { originatingSessionId: state.sessionFileId } : {}),
+    ...(originatingSessionFile !== undefined ? { originatingSessionFile } : {}),
+    ...(stream !== undefined ? { stream } : {}),
+  })
+  if (!result.ok) {
+    send(ws, { type: 'restart_result', status: 'failed', error: result.reason })
+    return
+  }
+
+  // hostd's supervisor ACKs first, then runs stop+start in the background;
+  // this process should not self-exit or it could race the daemon-owned stop.
+  send(ws, {
+    type: 'restart_result',
+    status: 'accepted',
+    message: 'restart scheduled; reconnecting when the new container is up',
+  })
+}

package/src/shared/protocol.ts

@@ -130,6 +130,7 @@ export type InspectServerMessage =
 export type ClientMessage =
   | { type: 'prompt'; text: string; delivery?: PromptDelivery }
   | { type: 'reload'; scope?: string }
+  | { type: 'restart' }
   | { type: 'abort' }
   | { type: 'queue_cancel'; messageId: string }
   | { type: 'doctor'; requestId: DoctorRequestId }
@@ -213,6 +214,7 @@ export type ServerMessage =
   | { type: 'done' }
   | { type: 'error'; message: string }
   | { type: 'reload_result'; results: ReloadResultPayload[] }
+  | { type: 'restart_result'; status: 'accepted' | 'failed'; message?: string; error?: string }
   | { type: 'notification'; payload: unknown; replyTo?: string; meta?: Record<string, string> }
   | { type: 'queue_state'; pending: QueueStateItem[] }
   | { type: 'prompt_started'; messageId: string; text: string }