dsh-mesh-node 0.0.0-stage → 0.0.2

package/src/server.js

@@ -0,0 +1,317 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { createServer as createHttpServer } from 'node:http'
+import { createServer as createHttpsServer } from 'node:https'
+import { McpServer, createMcpHandler } from '@modelcontextprotocol/server'
+import { toNodeHandler } from '@modelcontextprotocol/node'
+import { MESH_VERSION, verifyBearer, createConfigLoader, createSecretsLoader, meshHome, addInboundToken, peerAclForToken } from './core/config.js'
+import { makeAudit, auditPath } from './core/audit.js'
+import { JobRunner } from './core/jobs.js'
+import { loadTlsMaterial, describeCert } from './core/tls.js'
+import { claimPairingCode, readPairingState } from './core/pairing.js'
+import { dispatch, isAllowed, applyPeerAcl, registerTools, toolNames } from './tools/index.js'
+import { createTunnelCache } from './core/tunnels.js'
+
+const NODE_STARTED_AT = new Date().toISOString()
+
+const INSTRUCTIONS = `This endpoint is a dsh-mesh node: another developer machine exposed over the Model Context Protocol.
+Call mesh_self first to learn what the peer can do and which tools your token may use.
+All paths are paths on the PEER machine, not on yours.
+Long operations: use task_submit (with an idem key) then poll task_status, instead of risking a call timeout.
+shell_run is opt-in and normally refused.`
+
+/** Carries the authenticated token id down into the per-request MCP server factory. */
+const requestScope = new AsyncLocalStorage()
+
+export function buildMcpServer({ ctx, log = console }) {
+  const config = ctx.getConfig()
+  const server = new McpServer(
+    { name: `dsh-mesh/${config.node?.name || 'local'}`, version: MESH_VERSION },
+    { instructions: INSTRUCTIONS }
+  )
+  registerTools(server, ctx)
+  return server
+}
+
+function sendJson(res, status, body, extraHeaders = {}) {
+  const text = JSON.stringify(body)
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', ...extraHeaders })
+  res.end(text)
+}
+
+/** Read a small JSON body (pairing requests are tiny; anything huge is a mistake). */
+function readJsonBody(req, limitBytes = 8192) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    let size = 0
+    const chunks = []
+    req.on('data', (chunk) => {
+      size += chunk.length
+      if (size > limitBytes) {
+        rejectPromise(new Error('body too large'))
+        req.destroy()
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => {
+      const text = Buffer.concat(chunks).toString('utf8').replace(/^\uFEFF/, '').trim()
+      if (text === '') return resolvePromise({})
+      try {
+        resolvePromise(JSON.parse(text))
+      } catch {
+        rejectPromise(new Error('body is not valid JSON'))
+      }
+    })
+    req.on('error', rejectPromise)
+  })
+}
+
+/** Peer ids double as token ids; keep them filename/log friendly. */
+function sanitizePeerId(raw) {
+  const id = String(raw || '')
+    .trim()
+    .replace(/[^A-Za-z0-9._-]/g, '-')
+    .replace(/-+/g, '-')
+    .slice(0, 48)
+  return id === '' ? null : id
+}
+
+/**
+ * Start the mesh HTTP endpoint.
+ * @param {object} opts
+ * @param {object} [opts.config] Fixed config (tests). Omit to load and hot-reload from disk.
+ * @param {object} opts.secrets Inbound tokens.
+ * @param {string} [opts.home] Mesh home directory (defaults to ~/.dsh-mesh).
+ */
+export async function startMeshServer({ config, secrets, log = console, port, bind, tls, home } = {}) {
+  const meshHomeDir = home || meshHome()
+  const getConfig = config ? () => config : createConfigLoader({ home: meshHomeDir, log })
+  // Secrets hot-reload too: rotating a token takes effect without a restart.
+  const getSecrets = secrets ? () => secrets : createSecretsLoader({ home: meshHomeDir, log })
+  const audit = makeAudit({ home: meshHomeDir, log })
+
+  const initial = getConfig()
+  // 2026-11-09：隧道状态缓存（自建 frps + Sakura）。/health 携带，60s 后台刷新，不阻塞请求。
+  const tunnelCache = createTunnelCache({ repo: initial.repo || process.cwd(), home: meshHomeDir, refreshMs: Math.max(3000, Number(process.env.TUNNEL_CACHE_MS || 10_000)), log }).start()
+  const jobs = new JobRunner({
+    home: meshHomeDir,
+    audit,
+    log,
+    limits: initial.limits || {},
+    exec: (tool, args, opts) => dispatch(ctx, tool, args, opts)
+  })
+
+  // Shared context. `peerId` is filled per request from the verified bearer token.
+  const ctx = {
+    home: meshHomeDir,
+    secrets,
+    getSecrets,
+    log,
+    audit,
+    jobs,
+    getConfig,
+    isAllowed,
+    toolNames: () => toolNames(ctx),
+    dispatch: (name, args, opts) => dispatch(ctx, name, args, opts)
+  }
+
+  const nodeCfg = initial.node || {}
+  const listenPort = port ?? nodeCfg.port ?? 8124
+  const listenBind = bind ?? nodeCfg.bind ?? '127.0.0.1'
+  const mcpPath = nodeCfg.path || '/mcp'
+  const tlsCfg = tls ?? nodeCfg.tls ?? { enabled: false }
+
+  let calls = 0
+  const mcpHandler = createMcpHandler(
+    () => {
+      const scope = requestScope.getStore()
+      const peerAcl = scope?.peerAcl || null
+      return buildMcpServer({
+        ctx: {
+          ...ctx,
+          peerId: scope?.tokenId,
+          peerAcl,
+          getConfig: () => applyPeerAcl(getConfig(), peerAcl)
+        },
+        log
+      })
+    },
+    { onerror: (error) => log?.error?.(`[dsh-mesh] handler error: ${error?.message || error}`) }
+  )
+  const nodeHandler = toNodeHandler(mcpHandler)
+
+  const requestListener = async (req, res) => {
+    let pathname = '/'
+    try {
+      pathname = new URL(req.url, 'http://mesh.local').pathname
+    } catch {
+      /* malformed URL falls through to 404 */
+    }
+
+    if (pathname === '/health') {
+      const liveConfig = getConfig()
+      const pairingState = readPairingState(meshHomeDir)
+      sendJson(res, 200, {
+        ok: true,
+        service: 'dsh-mesh',
+        version: MESH_VERSION,
+        node: liveConfig.node?.name || 'local',
+        /** Local DSH instances this node can bridge to (cluster addressing: <node>:<instance>). */
+        hosts: (liveConfig.hosts || []).map((entry) => ({
+          id: entry.id,
+          url: entry.url,
+          enabled: entry.enabled !== false
+        })),
+        uptimeSec: Math.round((Date.now() - Date.parse(NODE_STARTED_AT)) / 1000),
+        pid: process.pid,
+        startedAt: NODE_STARTED_AT,
+        tools: toolNames(ctx).length,
+        jobs: jobs.stats(),
+        tls: tlsCfg?.enabled === true,
+        tunnels: tunnelCache.get(),
+        pairing: {
+          enabled: liveConfig.pairing?.enabled === true,
+          codeActive: Boolean(pairingState && !pairingState.used && !pairingState.expired),
+          expiresAt: pairingState?.expiresAt ?? null
+        },
+        now: new Date().toISOString()
+      })
+      return
+    }
+
+    // Unauthenticated by design: a peer has no token yet, it redeems a one-time code instead.
+    if (pathname === '/pair') {
+      if (req.method !== 'POST') {
+        sendJson(res, 405, { code: 'E_INVALID_ARG', message: 'use POST /pair' }, { allow: 'POST' })
+        return
+      }
+      const liveConfig = getConfig()
+      if (liveConfig.pairing?.enabled !== true) {
+        sendJson(res, 403, { code: 'E_DENIED', message: 'pairing is disabled on this node' })
+        return
+      }
+      let body
+      try {
+        body = await readJsonBody(req)
+      } catch (error) {
+        sendJson(res, 400, { code: 'E_INVALID_ARG', message: error?.message || 'bad body' })
+        return
+      }
+      const claim = claimPairingCode({
+        home: meshHomeDir,
+        code: body?.code,
+        maxAttempts: Number(liveConfig.pairing?.maxAttempts) || 5
+      })
+      if (!claim.ok) {
+        // Small constant delay so the answer time does not reveal much; never say why.
+        await new Promise((r) => setTimeout(r, 200))
+        await audit({ peer: 'pair', tool: 'pair', ok: false, code: claim.reason, args: ['code'] })
+        sendJson(
+          res,
+          401,
+          {
+            code: claim.reason === 'E_MAX_ATTEMPTS' ? 'E_MAX_ATTEMPTS' : 'E_AUTH',
+            message: 'pairing code rejected',
+            retryable: claim.reason !== 'E_MAX_ATTEMPTS' && claim.reason !== 'E_CODE_USED'
+          },
+          { 'www-authenticate': 'Bearer realm="dsh-mesh"' }
+        )
+        return
+      }
+      const baseId = sanitizePeerId(body?.peerName) || `peer-${Date.now().toString(36)}`
+      let created
+      try {
+        created = addInboundToken({
+          home: meshHomeDir,
+          id: baseId,
+          note: `paired ${new Date().toISOString()}`,
+          acl: body?.acl
+        })
+      } catch {
+        created = addInboundToken({
+          home: meshHomeDir,
+          id: `${baseId}-${Math.random().toString(36).slice(2, 6)}`,
+          note: `paired ${new Date().toISOString()}`,
+          acl: body?.acl
+        })
+      }
+      await audit({ peer: created.id, tool: 'pair', ok: true, args: ['code', 'peerName'] })
+      const scheme = tlsCfg?.enabled === true ? 'https' : 'http'
+      const address = httpServer.address()
+      const actualPort = typeof address === 'object' && address ? address.port : listenPort
+      sendJson(res, 200, {
+        ok: true,
+        token: created.token,
+        tokenId: created.id,
+        node: liveConfig.node?.name || 'local',
+        version: MESH_VERSION,
+        url: `${scheme}://${listenBind}:${actualPort}${mcpPath}`,
+        certFingerprint: tlsCfg?.enabled === true ? describeCert(meshHomeDir)?.fingerprint256 ?? null : null,
+        tools: toolNames(ctx).length
+      })
+      return
+    }
+
+    if (pathname !== mcpPath) {
+      sendJson(res, 404, { code: 'E_NOT_FOUND', message: `no route for ${pathname}`, mcpEndpoint: mcpPath })
+      return
+    }
+
+    const secretsNow = getSecrets()
+    const tokenId = verifyBearer(req, secretsNow)
+    if (!tokenId) {
+      sendJson(
+        res,
+        401,
+        { code: 'E_AUTH', message: 'missing or invalid bearer token' },
+        { 'www-authenticate': 'Bearer realm="dsh-mesh"' }
+      )
+      return
+    }
+    const peerAcl = peerAclForToken(secretsNow, tokenId)
+
+    calls += 1
+    const started = Date.now()
+    res.on('close', () => {
+      log?.debug?.(`[dsh-mesh] ${req.method} ${pathname} token=${tokenId} ${res.statusCode} ${Date.now() - started}ms`)
+    })
+
+    try {
+      await requestScope.run({ tokenId, peerAcl }, () => nodeHandler(req, res))
+    } catch (error) {
+      log?.error?.(`[dsh-mesh] transport failure: ${error?.message || error}`)
+      if (!res.headersSent) sendJson(res, 500, { code: 'E_INTERNAL', message: 'transport failure' })
+    }
+  }
+
+  const httpServer =
+    tlsCfg?.enabled === true
+      ? createHttpsServer(loadTlsMaterial({ home: meshHomeDir, cert: tlsCfg.cert, key: tlsCfg.key }), requestListener)
+      : createHttpServer(requestListener)
+
+  await new Promise((resolvePromise, rejectPromise) => {
+    httpServer.once('error', rejectPromise)
+    httpServer.listen(listenPort, listenBind, () => {
+      httpServer.off('error', rejectPromise)
+      resolvePromise()
+    })
+  })
+
+  const address = httpServer.address()
+  const actualPort = typeof address === 'object' && address ? address.port : listenPort
+  const scheme = tlsCfg?.enabled === true ? 'https' : 'http'
+  const url = `${scheme}://${listenBind}:${actualPort}${mcpPath}`
+
+  return {
+    port: actualPort,
+    url,
+    httpServer,
+    ctx,
+    auditPath: auditPath(meshHomeDir),
+    get requestCount() {
+      return calls
+    },
+    close() {
+      return new Promise((resolvePromise) => httpServer.close(() => resolvePromise()))
+    }
+  }
+}

package/src/tools/alerts.js

@@ -0,0 +1,80 @@
+// @generated 2026-10-27 P2：mesh_alert（查看/清除本机「当前告警」指针）
+// [why] 告警写进 <mesh home>/ALERT.json 后，只能本机跑 `mesh-health --clear-alert` 清；
+//       加一个 mesh 工具就能远程清（例如家里/peer-x 上残留的旧告警），历史 alerts.jsonl 默认保留。
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { z } from 'zod'
+import { fail, ok } from '../core/result.js'
+
+function alertPaths(home) {
+  return { state: join(home, 'ALERT.json'), history: join(home, 'alerts.jsonl') }
+}
+
+function readLatest(state) {
+  try {
+    const parsed = JSON.parse(readFileSync(state, 'utf8'))
+    return parsed && parsed.at ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+export function buildAlerts(ctx) {
+  return [
+    {
+      name: 'mesh_alert',
+      title: 'Inspect or clear this node active alert',
+      description:
+        'Read the latest alert (ALERT.json) plus the last 10 entries of alerts.jsonl, or clear the "active alert" pointer so mesh-health stops showing it (history is kept unless keepHistory:false). status is read-only; clear requires confirm:true. Use it after verifying a recovered incident.',
+      inputSchema: z.object({
+        op: z.enum(['status', 'clear']).describe('status = read; clear = reset the active-alert pointer'),
+        confirm: z.boolean().optional().describe('clear requires true'),
+        keepHistory: z.boolean().optional().describe('clear: keep alerts.jsonl history (default true; false truncates it)')
+      }),
+      handler: async ({ op, confirm, keepHistory }) => {
+        const { state, history } = alertPaths(ctx.home)
+        if (op === 'status') {
+          let recent = []
+          try {
+            recent = readFileSync(history, 'utf8')
+              .trim()
+              .split('\n')
+              .filter(Boolean)
+              .slice(-10)
+              .map((line) => {
+                try {
+                  return JSON.parse(line)
+                } catch {
+                  return { raw: line.slice(0, 200) }
+                }
+              })
+          } catch {
+            /* no history yet */
+          }
+          return ok({ latest: readLatest(state), recentCount: recent.length, recent, paths: { state, history } })
+        }
+        if (op === 'clear') {
+          if (confirm !== true) return fail('E_INVALID_ARG', 'clear requires confirm:true')
+          const previous = readLatest(state)
+          try {
+            mkdirSync(ctx.home, { recursive: true })
+            writeFileSync(state, '{}\n', 'utf8')
+          } catch (error) {
+            return fail('E_WRITE', `cannot clear active alert: ${error?.message || error}`)
+          }
+          let historyTruncated = false
+          if (keepHistory === false) {
+            try {
+              writeFileSync(history, '', 'utf8')
+              historyTruncated = true
+            } catch {
+              /* keep history on failure */
+            }
+          }
+          return ok({ cleared: Boolean(previous), previous, keptHistory: !historyTruncated, historyTruncated })
+        }
+        return fail('E_INVALID_ARG', 'op must be status|clear')
+      }
+    }
+  ]
+}

package/src/tools/channel.js

@@ -0,0 +1,253 @@
+import { z } from 'zod'
+import { DshWebClient, DshError, assistantText, summarizeRecord } from '../core/ds-web.js'
+import { saveSecrets } from '../core/config.js'
+import { fail, invalidArg, notFound, ok } from '../core/result.js'
+
+/**
+ * M3 channel (route A): talk to a *local* DSH web instance's Remote API so a peer AI
+ * can put a message into a running session and read the reply back.
+ *
+ * Route B (a DSH plugin calling `inbox.append`) needs an installed plugin and is not
+ * implemented yet; when it lands these tools keep the same surface.
+ */
+
+function meshHome(ctx) {
+  return ctx.home
+}
+
+function targets(ctx) {
+  const config = ctx.getConfig()
+  const configured = (config.dsh?.targets || []).filter((t) => t && t.id && t.baseUrl)
+  return configured.map((t) => ({ id: t.id, baseUrl: t.baseUrl, note: t.note }))
+}
+
+function secretsOf(ctx) {
+  try {
+    return ctx.getSecrets() || {}
+  } catch {
+    return {}
+  }
+}
+
+/** Persist the cookie so a restart of the mesh node does not need a new launch URL. */
+function rememberCookie(ctx, { targetId, baseUrl, cookie }) {
+  const secrets = secretsOf(ctx)
+  secrets.dshWeb = { ...(secrets.dshWeb || {}) }
+  secrets.dshWeb[targetId] = { baseUrl, cookie, savedAt: new Date().toISOString() }
+  saveSecrets(secrets, meshHome(ctx))
+}
+
+function targetInfo(ctx) {
+  const secrets = secretsOf(ctx)
+  const stored = secrets.dshWeb || {}
+  return targets(ctx).map((t) => {
+    const saved = stored[t.id]
+    return {
+      id: t.id,
+      baseUrl: t.baseUrl,
+      note: t.note,
+      hasCookie: Boolean(saved?.cookie),
+      savedAt: saved?.savedAt
+    }
+  })
+}
+
+/** Build a client for one configured target, reusing the persisted cookie. */
+function clientFor(ctx, targetId) {
+  const secrets = secretsOf(ctx)
+  const saved = (secrets.dshWeb || {})[targetId]
+  const configured = targets(ctx).find((t) => t.id === targetId)
+  if (!configured && !saved) {
+    return {
+      error: notFound(`unknown channel target: ${targetId}`, {
+        targets: targetInfo(ctx).map((t) => t.id),
+        hint: 'add dsh.targets[] to config.json or call channel_login with a launch URL'
+      })
+    }
+  }
+  const baseUrl = configured?.baseUrl || saved?.baseUrl
+  const client = new DshWebClient({ baseUrl, cookie: saved?.cookie, log: ctx.log })
+  return { client, baseUrl, targetId }
+}
+
+function describeError(error) {
+  if (error instanceof DshError) {
+    return fail(error.code, error.message.replace(/^[A-Z_]+: /, ''), {
+      retryable: error.code === 'E_DSH_UNREACHABLE' || error.code === 'E_TIMEOUT',
+      ...error.extra
+    })
+  }
+  return fail('E_DSH_UNEXPECTED', String(error?.message || error))
+}
+
+function autoTargetId(baseUrl) {
+  try {
+    const url = new URL(baseUrl)
+    const port = url.port || (url.protocol === 'https:' ? '443' : '80')
+    return `dsh-${port}`
+  } catch {
+    return 'dsh-local'
+  }
+}
+
+export function buildChannel(ctx) {
+  const limits = ctx.getConfig().limits || {}
+  const defaultWaitMs = limits.channelWaitMs ?? 180000
+  const defaultPollMs = limits.channelPollMs ?? 800
+  const defaultMessages = limits.channelMaxMessages ?? 60
+
+  return [
+    {
+      name: 'channel_targets',
+      title: 'List DSH channel targets',
+      description:
+        'List the local DSH instances this mesh node can talk to (config.dsh.targets plus targets saved by channel_login), and whether a session cookie is already stored. Read-only.',
+      inputSchema: z.object({}),
+      handler: async () => ok({ targets: targetInfo(ctx), hint: 'channel_login <launchUrl> to (re)authenticate' })
+    },
+    {
+      name: 'channel_login',
+      title: 'Log in to a local DSH instance',
+      description:
+        'Exchange a `dsh web` launch URL (the one printed on startup, containing ?token=) for a session cookie, then persist it in secrets.json. The launch token is single-use; the cookie survives DSH restarts. Returns the target id and how many sessions exist.',
+      inputSchema: z.object({
+        launchUrl: z.string().describe('Full launch URL, e.g. http://127.0.0.1:3080/?token=...'),
+        target: z.string().optional().describe('Target id to store under (defaults to dsh-<port>)')
+      }),
+      handler: async (args) => {
+        try {
+          const client = new DshWebClient({ log: ctx.log })
+          const { baseUrl } = await client.login(args.launchUrl)
+          const targetId = args.target || autoTargetId(baseUrl)
+          const list = await client.listSessions()
+          rememberCookie(ctx, { targetId, baseUrl, cookie: client.cookie })
+          return ok({
+            target: targetId,
+            baseUrl,
+            sessions: (list?.items || []).length,
+            stored: '~/.dsh-mesh/secrets.json (0600, never in git)',
+            next: `channel_send({ target: "${targetId}", text: "..." })`
+          })
+        } catch (error) {
+          return describeError(error)
+        }
+      }
+    },
+    {
+      name: 'channel_sessions',
+      title: 'List sessions on a DSH target',
+      description:
+        'List sessions of one local DSH instance: sessionId, title, state (working|idle|ended), running, agentAvailable, cwd (workspace) and updatedAt. Requires a channel_login cookie for that target; host_sessions is the cookie-free alternative. Use this before channel_send to find the session you want to talk to, or omit sessionId there to open a new one.',
+      inputSchema: z.object({
+        target: z.string().describe('Target id from channel_targets'),
+        limit: z.number().int().min(1).max(200).optional()
+      }),
+      handler: async (args) => {
+        const built = clientFor(ctx, args.target)
+        if (built.error) return built.error
+        try {
+          const value = await built.client.listSessions()
+          const items = (value?.items || []).slice(0, args.limit ?? 50).map((item) => ({
+            sessionId: item.sessionId || item.id,
+            title: item.title || item.projections?.values?.title || '',
+            state: item.running ? 'working' : item.agentAvailable ? 'idle' : 'ended',
+            status: item.status,
+            running: item.running === true,
+            agentAvailable: item.agentAvailable === true,
+            cwd: item.cwd || '',
+            updatedAt: item.updatedAt || item.modifiedAt || item.createdAt
+          }))
+          return ok({ target: args.target, baseUrl: built.baseUrl, count: items.length, sessions: items })
+        } catch (error) {
+          return describeError(error)
+        }
+      }
+    },
+    {
+      name: 'channel_page',
+      title: 'Read recent events of a DSH session',
+      description:
+        'Read the last N events of one session (user messages, assistant messages, turn boundaries) as a compact list. Useful to catch up on a conversation without waiting for a turn.',
+      inputSchema: z.object({
+        target: z.string().describe('Target id from channel_targets'),
+        sessionId: z.string(),
+        maxMessages: z.number().int().min(1).max(200).optional()
+      }),
+      handler: async (args) => {
+        const built = clientFor(ctx, args.target)
+        if (built.error) return built.error
+        try {
+          const page = await built.client.page({
+            sessionId: args.sessionId,
+            maxMessages: args.maxMessages ?? defaultMessages
+          })
+          return ok({
+            target: args.target,
+            sessionId: args.sessionId,
+            hasMore: page.hasMore,
+            events: page.records.map(summarizeRecord),
+            assistantText: assistantText(page.records).slice(-4000)
+          })
+        } catch (error) {
+          return describeError(error)
+        }
+      }
+    },
+    {
+      name: 'channel_send',
+      title: 'Send a message to a DSH session and wait for the reply',
+      description:
+        'Put a text message into a local DSH session (creating a fresh session when sessionId is omitted) and wait until that turn ends, then return the assistant reply. This is how a peer AI wakes the other side up instead of only reading files. Opt-in tool: enable it in acl.allow.',
+      inputSchema: z.object({
+        target: z.string().describe('Target id from channel_targets'),
+        text: z.string().min(1).describe('Message to send, as if typed by the user'),
+        sessionId: z.string().optional().describe('Existing session; omit to open a new one'),
+        mode: z.enum(['queue', 'steer']).optional().describe('queue = after current turn, steer = interrupt'),
+        waitMs: z.number().int().min(1000).max(1800000).optional()
+      }),
+      handler: async (args, { signal } = {}) => {
+        const built = clientFor(ctx, args.target)
+        if (built.error) return built.error
+        try {
+          const sessionId = args.sessionId || (await built.client.createSession())
+          if (signal?.aborted) throw new DshError('E_ABORTED', 'caller aborted before prompt')
+          const result = await built.client.sendAndWait({
+            sessionId,
+            text: args.text,
+            mode: args.mode || 'queue',
+            waitMs: args.waitMs ?? defaultWaitMs,
+            pollMs: defaultPollMs
+          })
+          return ok({
+            target: args.target,
+            created: !args.sessionId,
+            sessionId: result.sessionId,
+            requestId: result.requestId,
+            turnEnd: result.turnEnd,
+            reply: result.reply,
+            events: result.events,
+            ms: result.ms
+          })
+        } catch (error) {
+          return describeError(error)
+        }
+      }
+    },
+    {
+      name: 'channel_cancel',
+      title: 'Cancel the running turn of a DSH session',
+      description: 'Ask one session to abort its current turn. Opt-in tool: enable it in acl.allow.',
+      inputSchema: z.object({ target: z.string(), sessionId: z.string() }),
+      handler: async (args) => {
+        const built = clientFor(ctx, args.target)
+        if (built.error) return built.error
+        try {
+          await built.client.cancel({ sessionId: args.sessionId })
+          return ok({ target: args.target, sessionId: args.sessionId, cancelled: true })
+        } catch (error) {
+          return describeError(error)
+        }
+      }
+    }
+  ]
+}