typeclaw 0.20.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"
@@ -45,6 +45,7 @@
     "@clack/prompts": "^1.2.0",
     "@mariozechner/pi-coding-agent": "^0.67.3",
     "@mariozechner/pi-tui": "^0.67.3",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@mozilla/readability": "^0.6.0",
     "agent-messenger": "2.19.1",
     "cheerio": "^1.2.0",

package/src/agent/index.ts

@@ -2,13 +2,21 @@ import { existsSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-import { createAgentSession, DefaultResourceLoader, SessionManager } from '@mariozechner/pi-coding-agent'
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  defineTool as definePiTool,
+  SessionManager,
+} from '@mariozechner/pi-coding-agent'
 import type { AgentSession, ToolDefinition } from '@mariozechner/pi-coding-agent'
 
 import { loadMemory } from '@/bundled-plugins/memory/load-memory'
 import type { ChannelRouter } from '@/channels/router'
 import { getConfig, resolveModel, resolveProfile } from '@/config'
 import { defaultThinkingLevelForRef, providerForModelRef, type KnownModelRef } from '@/config/providers'
+import { renderMcpCatalog } from '@/mcp/catalog'
+import type { McpManager } from '@/mcp/manager'
+import { createMcpDispatcherTools, MCP_DISPATCHER_TOOL_NAMES } from '@/mcp/tools'
 import type { PermissionService, RolesConfig } from '@/permissions'
 import type {
   BuiltinToolRef,
@@ -34,6 +42,7 @@ import {
   wrapPluginTool,
   wrapSystemAgentTool,
   wrapSystemTool,
+  zodToToolParameters,
 } from './plugin-tools'
 import { createReloadTool } from './reload-tool'
 import { loadSelf } from './self'
@@ -98,6 +107,7 @@ export type CreateSessionOptions = {
   sessionManager?: SessionManager
   stream?: Stream
   channelRouter?: ChannelRouter
+  mcpManager?: McpManager
   // Bypass the file-based resource loader (IDENTITY.md, SOUL.md, MEMORY.md,
   // memory/, bundled skills) and use this string verbatim as the system prompt.
   systemPromptOverride?: string
@@ -232,6 +242,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
           ...(options.origin ? { origin: options.origin } : {}),
           ...(options.permissions ? { permissions: options.permissions } : {}),
           ...(options.runtimeVersion !== undefined ? { runtimeVersion: options.runtimeVersion } : {}),
+          ...(options.mcpManager !== undefined ? { mcpManager: options.mcpManager } : {}),
         })
 
   const getOrigin: () => SessionOrigin | undefined =
@@ -307,6 +318,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
             websearchTool,
             webfetchTool,
             lookAtTool,
+            ...(options.mcpManager ? buildMcpDispatcherToolDefinitions(options.mcpManager) : []),
             ...(options.reloadRegistry ? [createReloadTool({ registry: options.reloadRegistry })] : []),
             ...(options.stream ? [createStreamSnapshotTool({ stream: options.stream })] : []),
             ...buildChannelTools(options.channelRouter, options.origin, sessionManager.getSessionId()),
@@ -555,6 +567,40 @@ export function buildChannelTools(
   return tools
 }
 
+export function buildMcpDispatcherToolDefinitions(manager: McpManager): ToolDefinition[] {
+  const tools = createMcpDispatcherTools(manager)
+  return [
+    defineMcpDispatcherTool(MCP_DISPATCHER_TOOL_NAMES[0], tools[0]),
+    defineMcpDispatcherTool(MCP_DISPATCHER_TOOL_NAMES[1], tools[1]),
+    defineMcpDispatcherTool(MCP_DISPATCHER_TOOL_NAMES[2], tools[2]),
+  ]
+}
+
+function defineMcpDispatcherTool<P>(name: string, tool: PluginTool<P>): ToolDefinition {
+  return definePiTool({
+    name,
+    label: name,
+    description: tool.description,
+    parameters: zodToToolParameters(tool.parameters),
+    async execute(_toolCallId, params, signal) {
+      const validated = tool.parameters.safeParse(params)
+      if (!validated.success) {
+        return {
+          content: [{ type: 'text' as const, text: `invalid arguments: ${validated.error.message}` }],
+          details: null,
+        }
+      }
+      const result = await tool.execute(validated.data, {
+        signal,
+        sessionId: 'mcp-dispatcher',
+        agentDir: process.cwd(),
+        logger: { info() {}, warn() {}, error() {} },
+      })
+      return { content: result.content, details: result.details ?? null }
+    },
+  })
+}
+
 export function buildSubagentOrchestrationTools(opts: {
   liveRegistry: LiveSubagentRegistry | undefined
   registry: SubagentRegistry | undefined
@@ -722,6 +768,7 @@ export type CreateResourceLoaderOptions = {
   plugins?: PluginSessionWiring
   materializedSkills?: MaterializedSkills | null
   origin?: SessionOrigin
+  mcpManager?: McpManager
   permissions?: PermissionService
   runtimeVersion?: string
   // Explicit override for the prompt mode. When omitted, the mode is derived
@@ -785,6 +832,7 @@ export type SystemPromptComposition = {
   runtimeVersion?: string
   origin?: SessionOrigin
   roleContext?: SessionRoleContext
+  mcpCatalog?: string
   gitNudge: string
   memorySection: string
 }
@@ -822,6 +870,9 @@ export function composeSystemPrompt(parts: SystemPromptComposition): string {
   if (parts.origin !== undefined) {
     prompt = `${prompt}\n\n${renderSessionOrigin(parts.origin, Date.now(), parts.roleContext)}`
   }
+  if (parts.mcpCatalog !== undefined && parts.mcpCatalog !== '') {
+    prompt = `${prompt}\n\n${parts.mcpCatalog}`
+  }
   if (parts.gitNudge !== '') {
     prompt = `${prompt}\n\n${parts.gitNudge}`
   }
@@ -901,6 +952,9 @@ export async function createResourceLoader(options: CreateResourceLoaderOptions
     ...(options.runtimeVersion !== undefined ? { runtimeVersion: options.runtimeVersion } : {}),
     ...(options.origin !== undefined ? { origin: options.origin } : {}),
     ...(roleContext !== undefined ? { roleContext } : {}),
+    ...(mode === 'full' && options.mcpManager !== undefined
+      ? { mcpCatalog: renderMcpCatalog(options.mcpManager.listServers()) }
+      : {}),
     gitNudge,
     memorySection,
   })

package/src/agent/loop-guard.ts

@@ -1,39 +1,63 @@
-// Detects when the model calls the same tool with byte-identical arguments in
-// a tight streak — the classic "stuck in a thought-loop" failure where the
-// agent repeats `bash("ls")` or `read("foo.ts")` indefinitely waiting for a
-// different answer. Two-tier escalation:
+// Detects when the model is stuck looping on tool calls. Two independent
+// detectors run per call; the more severe decision wins.
 //
-//   - At LOOP_SOFT_WARN consecutive identical calls (default 3), the next call
-//     completes normally but the wrapped tool's output is suffixed with a nudge
-//     telling the model it's looping. Soft warning fires ONCE per streak so
-//     the model isn't drowning in identical reminders.
-//   - At LOOP_HARD_BLOCK consecutive identical calls (default 5), the call is
-//     refused outright. The wrapping in plugin-tools.ts maps the refusal to
-//     `errorResult` for plugin tools (the model sees a tool error and must
-//     change strategy) and to a thrown Error for system / pi-builtin tools
-//     (matches the existing `tool.before { block: true }` plumbing).
+// 1. Consecutive-identical (reason: 'consecutive') — catches the tight loop
+//    where the agent repeats `bash("ls")` byte-for-byte waiting for a different
+//    answer. Soft-warn at LOOP_SOFT_WARN (3), hard-block at LOOP_HARD_BLOCK (5).
 //
-// State is per-session and bounded: the guard keeps at most MAX_SESSIONS
-// session entries with LRU eviction, and each session holds at most one
-// signature + counter (we only care about the current tail streak). When a
-// different tool/args combination arrives, the streak resets to 1.
+// 2. Windowed-frequency (reason: 'windowed') — catches interleaved cycles the
+//    consecutive detector cannot see, e.g. read(a)→edit(b)→read(a)→edit(b)…, or
+//    re-reading one file with drifting offsets. Over a sliding window of the
+//    last WINDOW_SIZE calls, if one signature recurs WINDOW_SOFT_WARN times it
+//    warns and WINDOW_HARD_BLOCK times it blocks. Path-bearing tools coarsen
+//    their signature to the path alone (offsets/limits/line ranges dropped) so
+//    that paging the same file in a cycle collapses to one signature.
 //
-// The detector is intentionally placed INSIDE the tool wrappers (not as a
+// Both warn/block decisions carry the byte-identical or coarsened nudge text.
+// The wrapping in plugin-tools.ts maps a block to `errorResult` for plugin tools
+// and to a thrown Error for system / pi-builtin tools (matching the existing
+// `tool.before { block: true }` plumbing).
+//
+// State is per-session and bounded by MAX_SESSIONS with LRU eviction. The
+// detector is intentionally placed INSIDE the tool wrappers (not as a
 // `tool.before` plugin) so it covers every tool category — plugin tools,
 // TypeClaw system tools, and pi-coding-agent builtins — through one chokepoint.
 
 export const LOOP_SOFT_WARN = 3
 export const LOOP_HARD_BLOCK = 5
 
-// Caps in-process memory across many sessions. Each entry is small
-// (signature string + small counters), so this bound is generous; we just
-// don't want unbounded growth if sessionIds churn.
+export const WINDOW_SIZE = 16
+export const WINDOW_SOFT_WARN = 4
+export const WINDOW_HARD_BLOCK = 6
+
+// Tools whose first path-like argument identifies the target. Their windowed
+// signature keys on that path alone so paging one file with drifting
+// offset/limit collapses to a single signature. Two classes, because the
+// builtins differ in whether the path is required:
+//
+//   - REQUIRED-path tools (read/write/edit): path is mandatory. Coarsen only
+//     when a path key is present; an absent path is malformed input, not a
+//     default, so we must NOT collapse such calls to a shared target.
+//   - DEFAULT-path tools (grep/find/ls): path is OPTIONAL and defaults to the
+//     cwd ("."). Omitting the path and varying only non-target args (pattern,
+//     limit) still hits the same directory, so an omitted/empty path coarsens
+//     to `${tool}#path:.` — otherwise those calls would evade the detector.
+//
+// `glob` is intentionally absent: pi-coding-agent has no `glob` builtin (the
+// glob-pattern arg lives inside grep/find), so listing it here matched nothing.
+const REQUIRED_PATH_TOOLS = new Set(['read', 'write', 'edit'])
+const DEFAULT_PATH_TOOLS = new Set(['grep', 'find', 'ls'])
+const PATH_ARG_KEYS = ['path', 'file', 'filePath', 'filename']
+const DEFAULT_PATH_TARGET = '.'
+
 const MAX_SESSIONS = 256
 
+export type LoopReason = 'consecutive' | 'windowed'
+
 export type LoopGuardDecision =
   | { kind: 'ok' }
-  | { kind: 'warn'; count: number; message: string }
-  | { kind: 'block'; count: number; message: string }
+  | { kind: 'warn'; count: number; reason: LoopReason; message: string }
+  | { kind: 'block'; count: number; reason: LoopReason; message: string }
 
 export type LoopGuard = {
   check: (sessionId: string, tool: string, args: unknown) => LoopGuardDecision
@@ -42,28 +66,53 @@ export type LoopGuard = {
 }
 
 type SessionState = {
+  // Consecutive-identical streak: the current tail signature, its run length,
+  // and whether this streak already emitted its one soft warning.
   signature: string
   count: number
-  // Fires the soft warning exactly once per streak instead of every call
-  // from the 3rd onwards. Re-arms when the streak breaks.
   warned: boolean
+  // Windowed history: the last WINDOW_SIZE coarsened signatures, plus the set
+  // of signatures that already emitted their one windowed soft warning while
+  // still present in the window.
+  window: string[]
+  windowWarned: Set<string>
 }
 
 export type CreateLoopGuardOptions = {
   softWarn?: number
   hardBlock?: number
   maxSessions?: number
+  windowSize?: number
+  windowSoftWarn?: number
+  windowHardBlock?: number
 }
 
 export function createLoopGuard(options: CreateLoopGuardOptions = {}): LoopGuard {
   const softWarn = options.softWarn ?? LOOP_SOFT_WARN
   const hardBlock = options.hardBlock ?? LOOP_HARD_BLOCK
   const maxSessions = options.maxSessions ?? MAX_SESSIONS
+  const windowSize = options.windowSize ?? WINDOW_SIZE
+  const windowSoftWarn = options.windowSoftWarn ?? WINDOW_SOFT_WARN
+  const windowHardBlock = options.windowHardBlock ?? WINDOW_HARD_BLOCK
 
   if (softWarn < 2) throw new Error(`loop-guard: softWarn must be >= 2 (got ${softWarn})`)
   if (hardBlock <= softWarn) {
     throw new Error(`loop-guard: hardBlock (${hardBlock}) must be greater than softWarn (${softWarn})`)
   }
+  if (windowSoftWarn < 2) {
+    throw new Error(`loop-guard: windowSoftWarn must be >= 2 (got ${windowSoftWarn})`)
+  }
+  if (windowHardBlock <= windowSoftWarn) {
+    throw new Error(
+      `loop-guard: windowHardBlock (${windowHardBlock}) must be greater than windowSoftWarn (${windowSoftWarn})`,
+    )
+  }
+  if (windowSize < 2) throw new Error(`loop-guard: windowSize must be >= 2 (got ${windowSize})`)
+  if (windowSize < windowHardBlock) {
+    throw new Error(
+      `loop-guard: windowSize (${windowSize}) must be >= windowHardBlock (${windowHardBlock}) for the block to be reachable`,
+    )
+  }
 
   // Map preserves insertion order; we rely on that for LRU eviction.
   const sessions = new Map<string, SessionState>()
@@ -77,50 +126,90 @@ export function createLoopGuard(options: CreateLoopGuardOptions = {}): LoopGuard
     }
   }
 
+  function evaluateConsecutive(state: SessionState, tool: string): LoopGuardDecision {
+    if (state.count >= hardBlock) {
+      return {
+        kind: 'block',
+        count: state.count,
+        reason: 'consecutive',
+        message: formatBlockMessage(tool, state.count),
+      }
+    }
+    if (state.count >= softWarn && !state.warned) {
+      state.warned = true
+      return { kind: 'warn', count: state.count, reason: 'consecutive', message: formatWarnMessage(tool, state.count) }
+    }
+    return { kind: 'ok' }
+  }
+
+  function evaluateWindowed(state: SessionState, tool: string, windowSig: string): LoopGuardDecision {
+    const count = state.window.reduce((n, sig) => (sig === windowSig ? n + 1 : n), 0)
+    if (count >= windowHardBlock) {
+      return {
+        kind: 'block',
+        count,
+        reason: 'windowed',
+        message: formatWindowedBlockMessage(tool, count),
+      }
+    }
+    if (count >= windowSoftWarn && !state.windowWarned.has(windowSig)) {
+      state.windowWarned.add(windowSig)
+      return {
+        kind: 'warn',
+        count,
+        reason: 'windowed',
+        message: formatWindowedWarnMessage(tool, count),
+      }
+    }
+    return { kind: 'ok' }
+  }
+
   return {
     check(sessionId, tool, args) {
       const signature = makeCallSignature(tool, args)
+      const windowSig = makeWindowSignature(tool, args)
       const existing = sessions.get(sessionId)
 
-      if (!existing || existing.signature !== signature) {
-        touch(sessionId, { signature, count: 1, warned: false })
-        return { kind: 'ok' }
-      }
-
-      const nextCount = existing.count + 1
-      const nextState: SessionState = {
+      const state: SessionState = existing ?? {
         signature,
-        count: nextCount,
-        warned: existing.warned,
+        count: 0,
+        warned: false,
+        window: [],
+        windowWarned: new Set(),
       }
 
-      if (nextCount >= hardBlock) {
-        touch(sessionId, nextState)
-        return {
-          kind: 'block',
-          count: nextCount,
-          message: formatBlockMessage(tool, nextCount),
-        }
+      if (state.signature !== signature) {
+        state.signature = signature
+        state.count = 1
+        state.warned = false
+      } else {
+        state.count += 1
       }
 
-      if (nextCount >= softWarn && !nextState.warned) {
-        nextState.warned = true
-        touch(sessionId, nextState)
-        return {
-          kind: 'warn',
-          count: nextCount,
-          message: formatWarnMessage(tool, nextCount),
+      state.window.push(windowSig)
+      if (state.window.length > windowSize) {
+        const evicted = state.window.shift()
+        if (evicted !== undefined && !state.window.includes(evicted)) {
+          state.windowWarned.delete(evicted)
         }
       }
 
-      touch(sessionId, nextState)
+      touch(sessionId, state)
+
+      const consecutive = evaluateConsecutive(state, tool)
+      if (consecutive.kind === 'block') return consecutive
+
+      // Back-to-back identical calls are the consecutive detector's domain; let
+      // it own them so a tight streak doesn't also trip the windowed detector.
+      // The windowed detector exists for INTERLEAVED cycles, so it only acts
+      // when this call breaks the immediate streak (count === 1).
+      const windowed = state.count === 1 ? evaluateWindowed(state, tool, windowSig) : { kind: 'ok' as const }
+      if (windowed.kind === 'block') return windowed
+      if (consecutive.kind === 'warn') return consecutive
+      if (windowed.kind === 'warn') return windowed
       return { kind: 'ok' }
     },
     reset(sessionId) {
-      const existing = sessions.get(sessionId)
-      if (!existing) return
-      // Resetting is what `tool.after` does on a non-identical call too;
-      // exposed for callers that observe a strategy change externally.
       sessions.delete(sessionId)
     },
     forget(sessionId) {
@@ -146,6 +235,24 @@ function formatBlockMessage(tool: string, count: number): string {
   )
 }
 
+function formatWindowedWarnMessage(tool: string, count: number): string {
+  return (
+    `\n\n[loop-guard] You have called \`${tool}\` on the same target ${count} times in a short span. ` +
+    `This looks like a cycle — revisiting the same work without making progress. ` +
+    `If you have enough information, produce the final answer now. ` +
+    `Otherwise change approach instead of repeating this call.`
+  )
+}
+
+function formatWindowedBlockMessage(tool: string, count: number): string {
+  return (
+    `loop-guard: refused \`${tool}\` — called on the same target ${count} times in a short span. ` +
+    `You are cycling on the same work. Stop. Either (1) produce the final answer with the data you already have, ` +
+    `(2) ask the user a clarifying question, or (3) try a meaningfully different approach. ` +
+    `Do not keep re-running this on the same target.`
+  )
+}
+
 function makeCallSignature(tool: string, args: unknown): string {
   try {
     return `${tool}:${stableStringify(args)}`
@@ -154,6 +261,26 @@ function makeCallSignature(tool: string, args: unknown): string {
   }
 }
 
+// Coarsened signature for windowed detection: path-bearing tools key on their
+// target path alone so re-reading one target with drifting non-path args
+// collapses to a single signature. All other tools fall back to the exact
+// signature.
+function makeWindowSignature(tool: string, args: unknown): string {
+  const isRequiredPath = REQUIRED_PATH_TOOLS.has(tool)
+  const isDefaultPath = DEFAULT_PATH_TOOLS.has(tool)
+  if ((isRequiredPath || isDefaultPath) && args !== null && typeof args === 'object') {
+    const record = args as Record<string, unknown>
+    for (const key of PATH_ARG_KEYS) {
+      const value = record[key]
+      if (typeof value === 'string' && value.length > 0) return `${tool}#path:${value}`
+    }
+    // No explicit path. For default-path tools the effective target is the cwd,
+    // so coarsen to it; for required-path tools we leave the call uncoarsened.
+    if (isDefaultPath) return `${tool}#path:${DEFAULT_PATH_TARGET}`
+  }
+  return makeCallSignature(tool, args)
+}
+
 // Order-independent JSON serialization so semantically-identical objects
 // produce identical signatures regardless of key insertion order.
 function stableStringify(value: unknown): string {

package/src/agent/restart/index.ts

@@ -0,0 +1,101 @@
+import { basename } from 'node:path'
+
+import { writeRestartHandoff } from '@/agent/restart-handoff'
+import { send, sendHttp } from '@/hostd/client'
+import { containerSocketPath } from '@/hostd/paths'
+import type { Stream } from '@/stream'
+
+const ACK_TIMEOUT_MS = 5_000
+
+export type ContainerRestartingBroadcast = {
+  kind: 'container-restarting'
+  restartedAt: string
+  originatingSessionId: string
+}
+
+export type RequestContainerRestartOptions = {
+  containerName: string
+  build?: boolean
+  socketPath?: string
+  hostdUrl?: string
+  hostdToken?: string
+  ackTimeoutMs?: number
+  // When present together with originatingSessionId, the post-ACK
+  // container-restarting broadcast is published here so every live session's
+  // subscribeRestartNotice fans out the restart notice (originator gets
+  // typeclaw.restart-self, siblings get typeclaw.restart). Both the tool and
+  // the server /restart path route through this so the broadcast->handoff
+  // ordering lives in one place.
+  stream?: Stream
+  agentDir?: string
+  originatingSessionId?: string
+  originatingSessionFile?: string
+  restartedAt?: string
+}
+
+export type RequestContainerRestartResult =
+  | { ok: true; containerName: string; restartedAt: string }
+  | { ok: false; containerName: string; reason: string }
+
+export async function requestContainerRestart({
+  containerName,
+  build,
+  socketPath,
+  hostdUrl,
+  hostdToken,
+  ackTimeoutMs,
+  stream,
+  agentDir,
+  originatingSessionId,
+  originatingSessionFile,
+  restartedAt,
+}: RequestContainerRestartOptions): Promise<RequestContainerRestartResult> {
+  const request = { kind: 'restart' as const, containerName, build: build === true }
+  const httpUrl = hostdUrl ?? process.env.TYPECLAW_HOSTD_URL
+  const httpToken = hostdToken ?? process.env.TYPECLAW_HOSTD_TOKEN
+  const ackBudget = ackTimeoutMs ?? ACK_TIMEOUT_MS
+  const reply =
+    httpUrl && httpToken
+      ? await sendHttp(request, { timeoutMs: ackBudget, url: httpUrl, token: httpToken })
+      : await send(request, { timeoutMs: ackBudget, socket: socketPath ?? containerSocketPath() })
+
+  if (!reply.ok) return { ok: false, containerName, reason: reply.reason }
+
+  const restartTimestamp = restartedAt ?? new Date().toISOString()
+
+  // Fan out the restart notice to every live session BEFORE writing the handoff.
+  // The originating session's subscribeRestartNotice appends the
+  // typeclaw.restart-self entry synchronously (broker delivery + the JSONL
+  // append are both synchronous), so the handoff below points at a JSONL that
+  // already carries the "I'm back" instruction the rebooted container hydrates.
+  // Only after an accepted ACK, never on a failed/timed-out restart.
+  if (stream !== undefined && originatingSessionId !== undefined) {
+    const broadcast: ContainerRestartingBroadcast = {
+      kind: 'container-restarting',
+      restartedAt: restartTimestamp,
+      originatingSessionId,
+    }
+    stream.publish({ target: { kind: 'broadcast' }, payload: broadcast })
+  }
+
+  // Post-ACK: hostd has committed the restart, so a handoff-write failure must
+  // never demote it to a failure — that would render a false error in the TUI
+  // and swallow the accepted response. The handoff is a best-effort resume hint
+  // only; a missing one just cold-starts the rebooted container without the
+  // "I'm back" greeting. writeRestartHandoff swallows its own errors today, but
+  // guard here too so this contract survives the writer being changed later.
+  if (agentDir !== undefined && originatingSessionId !== undefined && originatingSessionFile !== undefined) {
+    try {
+      await writeRestartHandoff(agentDir, {
+        schemaVersion: 1,
+        restartedAt: restartTimestamp,
+        originatingSessionId,
+        originatingSessionFile: basename(originatingSessionFile),
+      })
+    } catch {
+      // intentional swallow — see the post-ACK rationale above
+    }
+  }
+
+  return { ok: true, containerName, restartedAt: restartTimestamp }
+}

package/src/agent/tools/restart.ts

@@ -1,14 +1,9 @@
-import { basename } from 'node:path'
-
 import { Type } from '@mariozechner/pi-ai'
 import { defineTool } from '@mariozechner/pi-coding-agent'
 
-import { writeRestartHandoff } from '@/agent/restart-handoff'
-import { send, sendHttp } from '@/hostd/client'
-import { containerSocketPath } from '@/hostd/paths'
+import { requestContainerRestart } from '@/agent/restart'
 import type { Stream } from '@/stream'
 
-const ACK_TIMEOUT_MS = 5_000
 const EXIT_DELAY_MS = 500
 
 export type CreateRestartToolOptions = {
@@ -61,11 +56,7 @@ export type CreateRestartToolOptions = {
 
 export type RestartToolDetails = { ok: boolean; containerName: string; reason?: string }
 
-export type ContainerRestartingBroadcast = {
-  kind: 'container-restarting'
-  restartedAt: string
-  originatingSessionId: string
-}
+export type { ContainerRestartingBroadcast } from '@/agent/restart'
 
 export function createRestartTool({
   containerName,
@@ -80,9 +71,6 @@ export function createRestartTool({
   originatingSessionFile,
 }: CreateRestartToolOptions) {
   const doExit = exit ?? ((code: number) => process.exit(code))
-  const httpUrl = hostdUrl ?? process.env.TYPECLAW_HOSTD_URL
-  const ackBudget = ackTimeoutMs ?? ACK_TIMEOUT_MS
-  const httpToken = hostdToken ?? process.env.TYPECLAW_HOSTD_TOKEN
 
   return defineTool({
     name: 'restart',
@@ -109,49 +97,32 @@ export function createRestartTool({
     }),
     async execute(_toolCallId, params) {
       const build = params.build === true
-      const request = { kind: 'restart' as const, containerName, build }
-      const reply =
-        httpUrl && httpToken
-          ? await sendHttp(request, { timeoutMs: ackBudget, url: httpUrl, token: httpToken })
-          : await send(request, { timeoutMs: ackBudget, socket: socketPath ?? containerSocketPath() })
-      if (!reply.ok) {
-        const details: RestartToolDetails = { ok: false, containerName, reason: reply.reason }
+      // requestContainerRestart owns the post-ACK broadcast->handoff ordering:
+      // on a successful ACK it publishes the container-restarting notice (which
+      // every live session's subscribeRestartNotice turns into a transcript
+      // entry) and then writes the handoff. Handoff fields are gated to TUI
+      // origins by the caller passing originatingSessionFile only for those —
+      // see issue #291's scoping concerns.
+      const result = await requestContainerRestart({
+        containerName,
+        build,
+        originatingSessionId,
+        ...(socketPath !== undefined ? { socketPath } : {}),
+        ...(hostdUrl !== undefined ? { hostdUrl } : {}),
+        ...(hostdToken !== undefined ? { hostdToken } : {}),
+        ...(ackTimeoutMs !== undefined ? { ackTimeoutMs } : {}),
+        ...(stream !== undefined ? { stream } : {}),
+        ...(agentDir !== undefined ? { agentDir } : {}),
+        ...(originatingSessionFile !== undefined ? { originatingSessionFile } : {}),
+      })
+      if (!result.ok) {
+        const details: RestartToolDetails = { ok: false, containerName, reason: result.reason }
         return {
-          content: [{ type: 'text' as const, text: `restart denied: ${reply.reason}` }],
+          content: [{ type: 'text' as const, text: `restart denied: ${result.reason}` }],
           details,
         }
       }
 
-      // Hostd ACK == restart is committed. Fan out the notice to every live
-      // session BEFORE arming the exit timer. Stream broker delivery is
-      // synchronous (broker.ts deliver()) and SessionManager.appendCustomMessageEntry
-      // does a synchronous JSONL write, so the fan-out completes inside this
-      // tick — well before the EXIT_DELAY_MS timer fires.
-      const restartedAt = new Date().toISOString()
-      const broadcast: ContainerRestartingBroadcast = {
-        kind: 'container-restarting',
-        restartedAt,
-        originatingSessionId,
-      }
-      stream?.publish({ target: { kind: 'broadcast' }, payload: broadcast })
-
-      // Write the cross-restart handoff AFTER the broadcast has run so the
-      // originating session's JSONL already contains the `typeclaw.restart-self`
-      // custom message entry that the next container will hydrate on
-      // `SessionManager.open`. Without that ordering, the new container could
-      // theoretically open the JSONL before the entry was flushed and miss
-      // the model-instruction the entry carries. Gated on agentDir +
-      // originatingSessionFile so non-TUI origins (channel/cron/subagent)
-      // skip the file write — see issue #291's scoping concerns.
-      if (agentDir !== undefined && originatingSessionFile !== undefined) {
-        await writeRestartHandoff(agentDir, {
-          schemaVersion: 1,
-          restartedAt,
-          originatingSessionId,
-          originatingSessionFile: basename(originatingSessionFile),
-        })
-      }
-
       // Schedule the exit on the next tick so the tool result is delivered to
       // the model before the process dies. The host daemon polls for the
       // container's removal before re-running `start`, so a small delay here