dsh-plugin-subagent-bridge 0.16.0 → 0.17.0

package/src/http.js

@@ -0,0 +1,358 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { createServer } from 'node:http'
+import { randomBytes, timingSafeEqual } from 'node:crypto'
+import { dirname } from 'node:path'
+import { MAX_BODY_BYTES, PACKAGE_VERSION, PROTOCOL_VERSIONS } from './constants.js'
+import { requireTaskName } from './registry.js'
+import { TOOLS } from './tools.js'
+import { errorResponse, ok, requireString, text } from './utils.js'
+
+export function createBridgeServer({ api, token, host = '127.0.0.1', port }) {
+  const handler = createHandler(api, token)
+  const server = createServer((request, response) => {
+    void handler(request, response)
+  })
+  const bound = () => server.address()?.port ?? port
+  return {
+    get port() {
+      return bound()
+    },
+    get url() {
+      return `http://${host}:${bound()}/mcp/${token}`
+    },
+    listen() {
+      return new Promise((resolve, reject) => {
+        const onError = (error) => reject(error)
+        server.once('error', onError)
+        server.listen(port, host, () => {
+          server.off('error', onError)
+          resolve()
+        })
+      })
+    },
+    close() {
+      return new Promise((resolve) => server.close(() => resolve()))
+    },
+  }
+}
+
+/**
+ * Build the node request handler.
+ * @param api - bridge operations.
+ * @param token - capability token; every request must carry it.
+ * @returns a node request handler.
+ */
+
+export function createHandler(api, token) {
+  return async function handle(request, response) {
+    const url = new URL(request.url ?? '/', 'http://127.0.0.1')
+    if (!authorized(request, url, token)) {
+      response.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' })
+      response.end('not found')
+      return
+    }
+
+    if (request.method === 'GET') {
+      /* No server-initiated stream in this version. */
+      response.writeHead(405, { allow: 'POST', 'content-type': 'text/plain; charset=utf-8' })
+      response.end('method not allowed')
+      return
+    }
+    if (request.method === 'DELETE') {
+      response.writeHead(204).end()
+      return
+    }
+    if (request.method !== 'POST') {
+      response.writeHead(405, { allow: 'POST' })
+      response.end()
+      return
+    }
+
+    let body
+    try {
+      body = await readBody(request)
+    } catch (error) {
+      response.writeHead(413, { 'content-type': 'text/plain; charset=utf-8' })
+      response.end(error instanceof Error ? error.message : 'body too large')
+      return
+    }
+
+    let message
+    try {
+      message = JSON.parse(body)
+    } catch {
+      response.writeHead(200, { 'content-type': 'application/json; charset=utf-8' })
+      response.end(JSON.stringify(errorResponse(null, -32700, 'parse error')))
+      return
+    }
+
+    /* A long-poll read must stop waiting when the client hangs up. */
+    const controller = new AbortController()
+    request.on('close', () => controller.abort())
+
+    const reply = await handleJsonRpc(message, api, { signal: controller.signal })
+    if (reply === null) {
+      response.writeHead(202).end()
+      return
+    }
+    response.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+    response.end(JSON.stringify(reply))
+  }
+}
+
+/**
+ * Handle one JSON-RPC message.
+ * @param message - parsed request or notification.
+ * @param api - bridge operations.
+ * @param options - caller cancellation.
+ * @returns the response, or null for a notification.
+ */
+
+export async function handleJsonRpc(message, api, options = {}) {
+  if (message === null || typeof message !== 'object' || Array.isArray(message)) {
+    return errorResponse(null, -32600, 'invalid request')
+  }
+  const { id, method, params } = message
+  if (typeof method !== 'string') return errorResponse(id ?? null, -32600, 'invalid request')
+  if (id === undefined || id === null) return null
+
+  switch (method) {
+    case 'initialize': {
+      const requested = params?.protocolVersion
+      const version = PROTOCOL_VERSIONS.includes(requested) ? requested : PROTOCOL_VERSIONS[0]
+      return ok(id, {
+        protocolVersion: version,
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: 'dsh-subagent-bridge', version: PACKAGE_VERSION },
+      })
+    }
+    case 'ping':
+      return ok(id, {})
+    case 'tools/list':
+      return ok(id, { tools: TOOLS })
+    case 'tools/call':
+      return callTool(id, params, api, options.signal)
+    default:
+      return errorResponse(id, -32601, `unknown method ${JSON.stringify(method)}`)
+  }
+}
+
+/**
+ * Run one MCP tool call.
+ * @param id - JSON-RPC id.
+ * @param params - `{ name, arguments }`.
+ * @param api - bridge operations.
+ * @param signal - caller cancellation.
+ * @returns the JSON-RPC response; tool failures travel inside `isError`.
+ */
+
+export async function callTool(id, params, api, signal) {
+  const toolName = params?.name
+  const args = params?.arguments ?? {}
+  try {
+    switch (toolName) {
+      case 'dsh_list_sessions':
+        return ok(id, text(await api.listSessions()))
+      case 'dsh_spawn': {
+        const taskName = requireTaskName(args.task_name)
+        const message = requireString(args.message, 'message')
+        const forkTurns = args.fork_turns === 'all' ? 'all' : 'none'
+        if (forkTurns === 'all' && (typeof args.from !== 'string' || args.from === '')) {
+          throw new Error('from is required when fork_turns is "all"')
+        }
+        return ok(
+          id,
+          text(
+            await api.spawn({
+              taskName,
+              message,
+              forkTurns,
+              from: args.from,
+              cwd: args.cwd,
+              workspace: args.workspace === true || (typeof args.workspace === 'string' && args.workspace !== '') ? args.workspace : undefined,
+              mode: args.mode === 'steer' ? 'steer' : undefined,
+              model: typeof args.model === 'string' && args.model !== '' ? args.model : undefined,
+              reasoningEffort:
+                typeof args.reasoningEffort === 'string' && args.reasoningEffort !== '' ? args.reasoningEffort : undefined,
+            }),
+          ),
+        )
+      }
+      case 'dsh_followup': {
+        const worker = requireString(args.worker, 'worker')
+        const message = requireString(args.message, 'message')
+        return ok(
+          id,
+          text(
+            await api.followup({
+              worker,
+              message,
+              mode: args.mode === 'steer' ? 'steer' : undefined,
+              model: typeof args.model === 'string' && args.model !== '' ? args.model : undefined,
+              reasoningEffort:
+                typeof args.reasoningEffort === 'string' && args.reasoningEffort !== '' ? args.reasoningEffort : undefined,
+            }),
+          ),
+        )
+      }
+      case 'dsh_close': {
+        const worker = requireString(args.worker, 'worker')
+        return ok(id, text(await api.close({ worker })))
+      }
+      case 'dsh_answer': {
+        const worker = requireString(args.worker, 'worker')
+        if (!Array.isArray(args.answers) || args.answers.length === 0) throw new Error('answers must be a non-empty array')
+        const answers = args.answers.map((entry, index) => {
+          const questionId = requireString(entry?.id, `answers[${index}].id`)
+          if (!Array.isArray(entry?.selected)) throw new Error(`answers[${index}].selected must be an array`)
+          return {
+            id: questionId,
+            selected: entry.selected.map((label, at) => requireString(label, `answers[${index}].selected[${at}]`)),
+            ...(typeof entry.custom === 'string' && entry.custom !== '' ? { custom: entry.custom } : {}),
+          }
+        })
+        return ok(id, text(await api.answer({ worker, answers })))
+      }
+      case 'dsh_list_workers':
+        return ok(id, text(await api.listWorkers()))
+      case 'dsh_wait': {
+        if (!Array.isArray(args.targets) || args.targets.length === 0) throw new Error('targets must be a non-empty array')
+        const targets = args.targets.map((target, index) => requireString(target, `targets[${index}]`))
+        const timeoutMs = args.timeoutMs === undefined ? undefined : Number(args.timeoutMs)
+        if (timeoutMs !== undefined && (!Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
+          throw new Error('timeoutMs must be a positive number')
+        }
+        return ok(id, text(await api.wait({ targets, timeoutMs })))
+      }
+      case 'dsh_task': {
+        const prompt = requireString(args.prompt, 'prompt')
+        const sessionId = args.sessionId === undefined ? undefined : requireString(args.sessionId, 'sessionId')
+        const timeoutSeconds = args.timeoutSeconds === undefined ? undefined : Number(args.timeoutSeconds)
+        if (timeoutSeconds !== undefined && (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0)) {
+          throw new Error('timeoutSeconds must be a positive number')
+        }
+        return ok(
+          id,
+          text(
+            await api.task({
+              prompt,
+              cwd: typeof args.cwd === 'string' && args.cwd !== '' ? args.cwd : undefined,
+              sessionId,
+              agentPreset: typeof args.agentPreset === 'string' && args.agentPreset !== '' ? args.agentPreset : undefined,
+              workspace: args.workspace === true || (typeof args.workspace === 'string' && args.workspace !== '') ? args.workspace : undefined,
+              mode: args.mode === 'steer' ? 'steer' : undefined,
+              model: typeof args.model === 'string' && args.model !== '' ? args.model : undefined,
+              reasoningEffort:
+                typeof args.reasoningEffort === 'string' && args.reasoningEffort !== '' ? args.reasoningEffort : undefined,
+              timeoutSeconds,
+            }),
+          ),
+        )
+      }
+      case 'dsh_dispatch': {
+        const sessionId = requireString(args.sessionId, 'sessionId')
+        const message = requireString(args.text, 'text')
+        const mode = args.mode === 'steer' ? 'steer' : 'queue'
+        return ok(id, text(await api.dispatch({ sessionId, text: message, mode })))
+      }
+      case 'dsh_read_result': {
+        const sessionId = requireString(args.sessionId, 'sessionId')
+        const sinceSeq = Number(args.sinceSeq)
+        if (!Number.isFinite(sinceSeq) || sinceSeq < 0) throw new Error('sinceSeq must be a non-negative number')
+        const waitSeconds = args.waitSeconds === undefined ? undefined : Number(args.waitSeconds)
+        if (waitSeconds !== undefined && (!Number.isFinite(waitSeconds) || waitSeconds < 0)) {
+          throw new Error('waitSeconds must be a non-negative number')
+        }
+        return ok(id, text(await api.readResult({ sessionId, sinceSeq, waitSeconds, signal })))
+      }
+      default:
+        return errorResponse(id, -32602, `unknown tool ${JSON.stringify(toolName)}`)
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return ok(id, { content: [{ type: 'text', text: message }], isError: true })
+  }
+}
+
+/**
+ * Build the bridge operations over live Host services.
+ * @param ctx - Host context.
+ * @param state - dispatch bookkeeping and running children.
+ * @param settings - resolved settings.
+ * @returns the api used by tool calls.
+ */
+
+export function authorized(request, url, token) {
+  const expected = Buffer.from(token)
+  const fromPath = url.pathname.startsWith('/mcp/') ? url.pathname.slice('/mcp/'.length) : ''
+  if (fromPath !== '' && safeEqual(fromPath, expected)) return true
+  const header = request.headers.authorization
+  if (typeof header === 'string' && header.toLowerCase().startsWith('bearer ')) {
+    return safeEqual(header.slice(7).trim(), expected)
+  }
+  return false
+}
+
+/**
+ * Compare two secrets without early exit.
+ * @param candidate - presented value.
+ * @param expected - expected value.
+ * @returns whether they match.
+ */
+
+export function safeEqual(candidate, expected) {
+  const left = Buffer.from(String(candidate))
+  if (left.length !== expected.length) return false
+  return timingSafeEqual(left, expected)
+}
+
+/**
+ * Read a request body with a size cap.
+ * @param request - node request.
+ * @returns the body text.
+ */
+
+export async function readBody(request) {
+  const chunks = []
+  let size = 0
+  for await (const chunk of request) {
+    size += chunk.length
+    if (size > MAX_BODY_BYTES) throw new Error('request body too large')
+    chunks.push(chunk)
+  }
+  return Buffer.concat(chunks).toString('utf8')
+}
+
+/**
+ * Read the persisted token, minting one on first use.
+ * @param endpointFile - endpoint file path.
+ * @returns the token.
+ */
+
+export async function loadOrCreateToken(endpointFile) {
+  try {
+    const parsed = JSON.parse(await readFile(endpointFile, 'utf8'))
+    if (typeof parsed?.token === 'string' && /^[A-Za-z0-9_-]{32,}$/.test(parsed.token)) return parsed.token
+  } catch {
+    /* First run, or an unreadable file: mint a new token. */
+  }
+  return randomBytes(24).toString('base64url')
+}
+
+/**
+ * Persist the endpoint description for humans and client setup.
+ * @param endpointFile - endpoint file path.
+ * @param value - endpoint description.
+ */
+
+export async function writeEndpointFile(endpointFile, value) {
+  await mkdir(dirname(endpointFile), { recursive: true, mode: 0o700 })
+  await writeFile(endpointFile, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 })
+}
+
+/**
+ * Validate one string argument.
+ * @param value - candidate.
+ * @param label - argument name used in the error.
+ * @returns the string.
+ */

package/src/policy.js

@@ -0,0 +1,19 @@
+import { ASSUMPTION_POLICY } from './constants.js'
+
+export function withAssumptionPolicy(settings, message) {
+  if (settings.assumeDefaults !== true) return message
+  if (message.includes('ask_user_question')) return message
+  const custom = typeof settings.assumptionPolicy === 'string' ? settings.assumptionPolicy.trim() : ''
+  const policy = custom === '' ? ASSUMPTION_POLICY : custom
+  return `${message}\n\n（${policy}）`
+}
+
+/**
+ * Take over the questions a worker asks, so the calling agent can answer them.
+ *
+ * `ask_user_question` pauses the tool call until something answers on the
+ * `user-questions/request` waterfall. The Web UI answers from the browser; for a worker
+ * nobody is watching, the bridge answers instead and forwards the question to its caller.
+ * @param state - bridge state.
+ * @param agent - live agent of the worker session.
+ */

package/src/questions.js

@@ -0,0 +1,130 @@
+import { resolveWorker } from './registry.js'
+import { text } from './utils.js'
+
+export function attachQuestionAnswerer(state, agent) {
+  if (agent?.ctx === undefined || typeof agent.ctx.on !== 'function') return
+  state.openQuestions ??= new Map()
+  state.questionAnswerers ??= new Map()
+  const sessionId = String(agent.id)
+  if (state.questionAnswerers.has(sessionId)) return
+  const handler = (request, next) => {
+    const questions = Array.isArray(request?.questions) ? request.questions : []
+    if (questions.length === 0) return next()
+    return new Promise((resolve, reject) => {
+      const waiter = {
+        questions,
+        settle(answer) {
+          state.openQuestions.delete(sessionId)
+          waiter.cleanup()
+          resolve(answer)
+        },
+        fail(error) {
+          state.openQuestions.delete(sessionId)
+          waiter.cleanup()
+          reject(error)
+        },
+      }
+      const signal = request?.signal
+      const onAbort = () => waiter.fail(new Error('the question was withdrawn'))
+      waiter.cleanup = () => signal?.removeEventListener?.('abort', onAbort)
+      if (signal?.aborted === true) {
+        waiter.fail(new Error('the question was withdrawn'))
+        return
+      }
+      signal?.addEventListener?.('abort', onAbort)
+      state.openQuestions.set(sessionId, waiter)
+    })
+  }
+  try {
+    const off = agent.ctx.on('user-questions/request', handler)
+    state.questionAnswerers.set(sessionId, typeof off === 'function' ? off : () => {})
+  } catch {
+    /* An older Host without the waterfall: the continued-state path still works. */
+  }
+}
+
+/**
+ * The question a worker is currently blocked on, if any.
+ * `ask_user_question` records a tool call and waits for an answer; while it waits the call
+ * has no result yet, which is exactly the signal used here.
+ * @param ctx - Host context.
+ * @param sessionId - session to inspect.
+ * @returns the pending call and its questions, or undefined.
+ */
+
+export function askable(state, ctx, targets) {
+  for (const target of targets) {
+    const resolved = resolveWorker(state, target)
+    const sessionId = resolved === undefined ? target : resolved.sessionId
+    const asked = pendingQuestion(ctx, sessionId, state)
+    if (asked !== undefined) return { worker: target, ...asked }
+  }
+  return undefined
+}
+
+export function pendingQuestion(ctx, sessionId, state) {
+  const open = state?.openQuestions?.get(sessionId)
+  if (open !== undefined) {
+    return {
+      callId: `open:${sessionId}`,
+      questions: open.questions.map((question) => ({
+        id: String(question?.id ?? ''),
+        question: String(question?.question ?? ''),
+        ...(typeof question?.header === 'string' ? { header: question.header } : {}),
+        ...(question?.multiSelect === true ? { multiSelect: true } : {}),
+        ...(Array.isArray(question?.options)
+          ? {
+              options: question.options.map((option) => ({
+                label: String(option?.label ?? ''),
+                ...(typeof option?.description === 'string' ? { description: option.description } : {}),
+              })),
+            }
+          : {}),
+      })),
+    }
+  }
+  const session = ctx.get('sessions')?.get?.(sessionId)
+  if (session === undefined || session === null) return undefined
+  const settled = new Set()
+  let waiting
+  for (const event of session.snapshotEvents()) {
+    if (event.type === 'tool/result' && typeof event.data?.callId === 'string') settled.add(event.data.callId)
+    if (event.type === 'tool/call' && event.data?.name === 'ask_user_question') waiting = event.data
+  }
+  if (waiting === undefined || settled.has(waiting.callId)) return undefined
+  let parsed
+  try {
+    parsed = JSON.parse(typeof waiting.arguments === 'string' ? waiting.arguments : '{}')
+  } catch {
+    return undefined
+  }
+  const questions = Array.isArray(parsed?.questions) ? parsed.questions : []
+  if (questions.length === 0) return undefined
+  return {
+    callId: String(waiting.callId),
+    questions: questions.map((question) => ({
+      id: String(question?.id ?? ''),
+      question: String(question?.question ?? ''),
+      ...(typeof question?.header === 'string' ? { header: question.header } : {}),
+      ...(question?.multi_select === true ? { multiSelect: true } : {}),
+      ...(Array.isArray(question?.options)
+        ? {
+            options: question.options.map((option) => ({
+              label: String(option?.label ?? ''),
+              ...(typeof option?.description === 'string' ? { description: option.description } : {}),
+            })),
+          }
+        : {}),
+    })),
+  }
+}
+
+/**
+ * Sequence number of the first message the caller itself delivered after `sinceSeq`.
+ * With steer the reply shares the running turn, so "the last assistant text of the turn"
+ * can be a step of the original task; anchoring on our own message keeps it exact.
+ * @param ctx - Host context.
+ * @param sessionId - session to read.
+ * @param sinceSeq - sequence captured before the prompt was delivered.
+ * @returns the sequence, or the original value when nothing matches.
+ */

package/src/registry.js

@@ -0,0 +1,155 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import { MAX_PERSISTED_WORKERS } from './constants.js'
+import { text } from './utils.js'
+
+export function saveWorkers(settings, state) {
+  const records = [...state.workers.values()]
+  if (records.length > MAX_PERSISTED_WORKERS) {
+    const closed = records.filter((record) => record.status === 'closed').sort((left, right) => left.createdAt - right.createdAt)
+    const open = records.filter((record) => record.status !== 'closed')
+    const keep = Math.max(0, MAX_PERSISTED_WORKERS - open.length)
+    for (const record of closed.slice(0, Math.max(0, closed.length - keep))) state.workers.delete(record.taskName)
+  }
+  const payload = {
+    version: 1,
+    workers: [...state.workers.values()],
+    baselines: Object.fromEntries(state.baseline),
+  }
+  const write = async () => {
+    try {
+      await mkdir(dirname(settings.workersFile), { recursive: true, mode: 0o700 })
+      await writeFile(settings.workersFile, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600 })
+    } catch {
+      /* Persistence is best effort: a failed write must not break a dispatch. */
+    }
+  }
+  state.saving = (state.saving ?? Promise.resolve()).then(write, write)
+  return state.saving
+}
+
+/**
+ * Cache a terminal outcome so it survives a restart, and persist the change.
+ * @param settings - resolved settings.
+ * @param state - worker bookkeeping.
+ * @param sessionId - worker session.
+ * @param value - computed status; strings are transient and are not cached.
+ */
+
+export async function loadWorkers(settings, state) {
+  let parsed
+  try {
+    parsed = JSON.parse(await readFile(settings.workersFile, 'utf8'))
+  } catch {
+    return
+  }
+  for (const entry of Array.isArray(parsed?.workers) ? parsed.workers : []) {
+    if (typeof entry?.taskName !== 'string' || typeof entry?.sessionId !== 'string') continue
+    state.workers.set(entry.taskName, {
+      taskName: entry.taskName,
+      sessionId: entry.sessionId,
+      status: entry.status === 'closed' ? 'closed' : 'open',
+      /* Blocking tasks resume as non-counting records, exactly as they were written. */
+      countsTowardLimit: entry.countsTowardLimit !== false,
+      ...(typeof entry.root === 'string' ? { root: entry.root } : {}),
+      createdAt: Number(entry.createdAt ?? Date.now()),
+      updatedAt: Number(entry.updatedAt ?? Date.now()),
+      ...(entry.outcome === undefined ? {} : { outcome: entry.outcome }),
+    })
+    state.dispatched.add(entry.sessionId)
+  }
+  for (const [sessionId, seq] of Object.entries(parsed?.baselines ?? {})) {
+    const value = Number(seq)
+    if (typeof sessionId === 'string' && Number.isFinite(value)) state.baseline.set(sessionId, value)
+  }
+}
+
+/**
+ * Persist the worker registry, serializing writes so two saves cannot interleave.
+ * @param settings - resolved settings.
+ * @param state - worker bookkeeping.
+ * @returns a promise settling after the write attempt.
+ */
+
+export async function rememberOutcome(settings, state, sessionId, value) {
+  if (typeof value === 'string') return
+  for (const record of state.workers.values()) {
+    if (record.sessionId !== sessionId || record.outcome !== undefined) continue
+    record.outcome = value
+    record.updatedAt = Date.now()
+    await saveWorkers(settings, state)
+    return
+  }
+}
+
+
+/**
+ * Resolve a worker reference (task name or session id) to its session.
+ * @param state - worker bookkeeping.
+ * @param reference - task name or session id.
+ * @returns `{ sessionId, taskName?, record? }`, or undefined when unknown.
+ */
+
+export function resolveWorker(state, reference) {
+  const record = state.workers.get(reference)
+  if (record !== undefined) return { sessionId: record.sessionId, taskName: record.taskName, record }
+  if (state.dispatched.has(reference)) return { sessionId: reference }
+  for (const candidate of state.workers.values()) {
+    if (candidate.sessionId === reference) return { sessionId: reference, taskName: candidate.taskName, record: candidate }
+  }
+  return undefined
+}
+
+/**
+ * Refuse a new worker when the open ones already fill the limit.
+ * @param state - worker bookkeeping.
+ * @param settings - resolved settings.
+ */
+
+export function assertCapacity(state, settings, root) {
+  const now = Date.now()
+  let total = 0
+  let inRoot = 0
+  for (const record of state.workers.values()) {
+    if (record.status === 'closed') continue
+    if (record.countsTowardLimit === false) continue
+    /* A record nobody has touched for a whole TTL stops holding a slot. */
+    if (now - Number(record.updatedAt ?? record.createdAt ?? 0) > settings.workerTtlMs) continue
+    total += 1
+    if (record.root === root) inRoot += 1
+  }
+  if (inRoot >= settings.maxWorkersPerRoot) {
+    throw new Error(
+      `worker limit reached for ${root} (${settings.maxWorkersPerRoot}); close one with dsh_close before spawning another`,
+    )
+  }
+  if (total >= settings.maxWorkers) {
+    throw new Error(
+      `global worker limit reached (${settings.maxWorkers}); close one with dsh_close before spawning another`,
+    )
+  }
+}
+
+/**
+ * Validate a task name the way the tool description promises.
+ * @param value - candidate name.
+ * @returns the normalized name.
+ */
+
+export function requireTaskName(value) {
+  if (typeof value !== 'string' || value.trim() === '') throw new Error('task_name must be a non-empty string')
+  const normalized = value.trim().toLowerCase().replace(/[^a-z0-9_]+/g, '_')
+  if (normalized === '') throw new Error('task_name must contain letters, digits, or underscores')
+  return normalized
+}
+
+/**
+ * The worker's final answer: the last assistant text produced after a sequence.
+ * Progress prose from earlier steps stays out of the parent's context, matching how
+ * a subagent's final message is the only thing delivered back.
+ * @param ctx - Host context.
+ * @param sessionId - session to read.
+ * @param sinceSeq - only count messages after this sequence.
+ * @param settings - resolved settings.
+ * @returns the final text plus whether it had to be truncated.
+ */