typeclaw 0.7.0 → 0.9.0

package/src/channels/router.ts

@@ -6,6 +6,7 @@ import { SessionManager } from '@mariozechner/pi-coding-agent'
 import { createSession, type AgentSession } from '@/agent'
 import { subscribeProviderErrors } from '@/agent/provider-error'
 import type { ChannelParticipant, SessionOrigin } from '@/agent/session-origin'
+import { renderSubagentCompletionReminder } from '@/agent/subagent-completion-reminder'
 import { createCommandRegistry } from '@/commands'
 import { CORE_PERMISSIONS, type PermissionService } from '@/permissions'
 import type { HookBus } from '@/plugin'
@@ -254,6 +255,14 @@ type LiveSession = {
   currentTurnAuthorId: string | null
   currentTurnAuthorIds: Set<string>
   lastTurnAuthorIds: Set<string>
+  // Mirror of currentTurnAuthorId at end-of-turn (the LAST speaker of the
+  // prior batch), preserved across the drain finally-block which resets
+  // currentTurnAuthorId to null. Read by the reminder-only branch in
+  // drain() so a system-reminder wakeup carries the same author the prior
+  // turn's tool.before saw — matching "last speaker" semantics (not "first
+  // inserted into Set"), so a multi-author prior turn like alice→bob
+  // restores `bob`, the same identity normal turns would have used.
+  lastTurnAuthorId: string | null
   consecutiveAborts: number
   // Per-(chat:thread) count of bot messages sent without intervening user
   // input being rendered into the model's context. Reset at the top of each
@@ -261,6 +270,15 @@ type LiveSession = {
   // about to be shown to the model). channel_send reads this BEFORE calling
   // router.send so the hint reflects the position of the about-to-happen send
   // (n-th in a row), nudging the model to yield without forcing it to.
+  // Queue of `<system-reminder>...</system-reminder>` strings to prepend
+  // into the next turn's user-message body. Populated by
+  // `injectSubagentCompletionReminder` (and any future system-injected
+  // wakeups) so a backgrounded subagent's completion can wake a channel
+  // session that has no pending user inbounds. Drained at the top of
+  // every `drain()` iteration alongside the regular promptQueue batch;
+  // the drain loop's run condition checks BOTH queues so a system
+  // reminder alone is enough to trigger a turn.
+  pendingSystemReminders: string[]
   consecutiveSends: Map<string, number>
   // Per-(chat:thread) text of the last reserved bot send. Set
   // SYNCHRONOUSLY inside router.send before the outbound callback awaits,
@@ -297,9 +315,30 @@ type LiveSession = {
   unsubProviderErrors: (() => void) | null
 }
 
+// `event` is null for command invocations that originated outside the inbound
+// pipeline (e.g. Discord native slash commands fired from listener.on
+// ('interaction_create')). Handlers that need a real inbound — for some
+// future hypothetical command like `/quote` — must guard on event !== null
+// instead of assuming it.
 type ChannelCommandContext = {
   live: LiveSession
-  event: InboundMessage
+  event: InboundMessage | null
+}
+
+export type ExecuteCommandResult =
+  | { kind: 'handled'; name: string }
+  | { kind: 'unknown-command'; name: string }
+  | { kind: 'no-live-session' }
+  | { kind: 'permission-denied' }
+  | { kind: 'ambiguous'; matchCount: number }
+
+// Identifies who invoked an adapter-driven command. Required so the router
+// can run the same channel.respond permission gate the text-prefix command
+// path runs (isChannelRespondDenied in route()). Without it, a guest user
+// in a public Slack channel could /stop an owner-created session that
+// happened to be live, bypassing role gating entirely.
+export type ExecuteCommandOptions = {
+  invokerId: string
 }
 
 export type SendSource = 'tool' | 'system'
@@ -345,11 +384,42 @@ export type ChannelRouter = {
   registerFetchAttachment: (adapter: ChannelKey['adapter'], cb: FetchAttachmentCallback) => void
   unregisterFetchAttachment: (adapter: ChannelKey['adapter'], cb: FetchAttachmentCallback) => void
   fetchAttachment: (adapter: ChannelKey['adapter'], args: FetchAttachmentArgs) => Promise<FetchAttachmentResult>
+  // Execute a command by name against an existing live session, bypassing
+  // the inbound classifier, engagement gate, debounce, and prompt queue.
+  // Used by adapters that receive commands through a native surface
+  // (Discord application-command interactions) rather than text. Gates
+  // the invoker on channel.respond — same permission gate the text-prefix
+  // command path runs — so a guest user cannot abort an owner's session
+  // by clicking the slash-command picker. Adapters MUST forward the
+  // invoker's platform-specific user id; without it the gate cannot
+  // identify the actor and resolves to 'guest' which denies. Returns:
+  //   - handled: command ran
+  //   - permission-denied: invoker lacks channel.respond
+  //   - no-live-session: channel has no active session
+  //   - ambiguous: multiple thread-keyed sessions in same chat (Slack);
+  //     caller should refuse to act rather than abort an arbitrary one
+  //   - unknown-command: name is not registered
+  executeCommand: (key: ChannelKey, name: string, options: ExecuteCommandOptions) => Promise<ExecuteCommandResult>
   // Lowered self-aliases (configured + implicit dir-name). Adapters use
   // this to anchor outbound threading on alias-only inbounds — see
   // slack-bot-classify.ts. Read live so a reload of `alias` propagates
   // to adapters without a restart.
   getSelfAliases: () => readonly string[]
+  // Inject a `<system-reminder>` block addressed to a live channel session
+  // identified by `parentSessionId`. The reminder is rendered into the
+  // next turn's user-message body and triggers a drain even if the
+  // promptQueue is empty. Returns `delivered` when a matching live
+  // session was found and the reminder was queued, `no-live-session`
+  // otherwise. Used by the subagent-completion bridge in
+  // src/run/index.ts; safe for tests to call directly via a fake router.
+  injectSubagentCompletionReminder: (args: {
+    parentSessionId: string
+    subagent: string
+    taskId: string
+    ok: boolean
+    durationMs: number
+    error?: string
+  }) => { kind: 'delivered'; keyId: string } | { kind: 'no-live-session' }
   stop: () => Promise<void>
   liveCount: () => number
   __testing?: {
@@ -359,6 +429,34 @@ export type ChannelRouter = {
     isTypingActive: (key: ChannelKey) => boolean
     stopTyping: (key: ChannelKey) => Promise<void>
     runIdleGc: () => Promise<void>
+    // Returns the seeded author state on the live session matching
+    // `key`, or undefined when no live session exists. Tests use this
+    // to pin the symmetric-seeding invariant between `lastTurnAuthorId`
+    // (string) and `lastTurnAuthorIds` (Set) at session creation —
+    // observable directly here rather than via a downstream sticky-
+    // credit grant test that would need to coordinate with multiple
+    // subsystems.
+    getLiveAuthorState: (key: ChannelKey) =>
+      | {
+          currentTurnAuthorId: string | null
+          currentTurnAuthorIds: readonly string[]
+          lastTurnAuthorId: string | null
+          lastTurnAuthorIds: readonly string[]
+        }
+      | undefined
+    // Returns a shallow copy of `live.originRef.current` for the live
+    // session matching `key`, or undefined when no live session exists.
+    // Exists so tests can assert on the per-turn origin that tool.before
+    // consumers would see — the origin is normally only observable
+    // indirectly via in-flight tool calls, which the fake session doesn't
+    // execute. The shallow copy detaches the top-level fields from
+    // `originRef` so a later turn replacing `originRef.current` doesn't
+    // change a captured assertion. Nested fields (`participants`,
+    // `membership`) are still shared by reference; in practice
+    // `updateParticipants` returns a fresh array rather than mutating in
+    // place, so observed snapshots are stable for the assertions tests
+    // make today. NOT a public router method.
+    getLiveOriginSnapshot: (key: ChannelKey) => SessionOrigin | undefined
   }
 }
 
@@ -763,6 +861,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         resolvedNames,
         originRef,
         promptQueue: [],
+        pendingSystemReminders: [],
         contextBuffer: [],
         draining: false,
         debounceTimer: null,
@@ -774,7 +873,18 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         firstUnprocessedAt: 0,
         currentTurnAuthorId: null,
         currentTurnAuthorIds: new Set(),
-        lastTurnAuthorIds: new Set(),
+        // `lastTurnAuthorId` (string, used for `lastInboundAuthorId` in
+        // origin) and `lastTurnAuthorIds` (Set, used by
+        // `grantStickyForReplyTargets` as the fallback when
+        // `currentTurnAuthorIds` is empty) are seeded TOGETHER from
+        // `triggeringAuthorId`. Seeding only the string would leave the
+        // Set empty for the cold-start reminder-only path, which is
+        // observable when the agent replies during that turn — `send()`
+        // would compute an empty `targetIds` and silently drop the
+        // sticky-credit grant for the seeded author. The two fields must
+        // stay in sync, so they are written in the same statement.
+        lastTurnAuthorIds: triggeringAuthorId !== undefined ? new Set([triggeringAuthorId]) : new Set(),
+        lastTurnAuthorId: triggeringAuthorId ?? null,
         consecutiveAborts: 0,
         consecutiveSends: new Map(),
         lastSentText: new Map(),
@@ -989,12 +1099,13 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     }
   }
 
-  const fireSessionTurnStart = async (live: LiveSession): Promise<void> => {
+  const fireSessionTurnStart = async (live: LiveSession, userPrompt: string): Promise<void> => {
     if (!live.hooks) return
     try {
       await live.hooks.runSessionTurnStart({
         sessionId: live.sessionId,
         agentDir: options.agentDir,
+        userPrompt,
         origin: buildLiveOrigin(live),
       })
     } catch (err) {
@@ -1045,6 +1156,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     live.debounceTimer = null
     live.firstUnprocessedAt = 0
     live.promptQueue.length = 0
+    live.pendingSystemReminders.length = 0
     await stopTypingHeartbeat(live)
     try {
       await live.session.abort()
@@ -1058,7 +1170,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     if (live.draining || live.destroyed) return
     live.draining = true
     try {
-      while (live.promptQueue.length > 0 && !live.destroyed) {
+      while ((live.promptQueue.length > 0 || live.pendingSystemReminders.length > 0) && !live.destroyed) {
         live.typingTimedOut = false
         // Heartbeat must run during generation as well as during debounce.
         // Because new inbounds during a turn just push into promptQueue
@@ -1067,13 +1179,32 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         startTypingHeartbeat(live)
         const batch = live.promptQueue.splice(0, live.promptQueue.length)
         const observed = live.contextBuffer.splice(0, live.contextBuffer.length)
-        const text = composeTurnPrompt(observed, batch, { loopGuardActive: live.loopGuardActive })
+        const reminders = live.pendingSystemReminders.splice(0, live.pendingSystemReminders.length)
+        const text = composeTurnPrompt(observed, batch, {
+          loopGuardActive: live.loopGuardActive,
+          systemReminders: reminders,
+        })
 
-        live.currentTurnAuthorId = batch.length > 0 ? batch[batch.length - 1]!.authorId : null
-        live.currentTurnAuthorIds = new Set(batch.map((m) => m.authorId))
         if (batch.length > 0) {
+          live.currentTurnAuthorId = batch[batch.length - 1]!.authorId
+          live.currentTurnAuthorIds = new Set(batch.map((m) => m.authorId))
           live.consecutiveSends.clear()
           live.lastSentText.clear()
+        } else if (live.lastTurnAuthorId !== null) {
+          // Reminder-only turn (batch.length === 0, reminders.length > 0):
+          // restore the author identity from the prior turn so author-
+          // scoped role resolution still works on this turn. The drain
+          // finally-block clears `currentTurnAuthorId` between turns, so a
+          // reminder arriving while the session is idle would otherwise
+          // strip `lastInboundAuthorId` from the tool.before origin and
+          // demote roles like `slack:T0/C0 author:U_OWNER` to whichever
+          // non-author rule matches — silently breaking the channel_reply
+          // that the reminder is asking the agent to send. `lastTurnAuthorId`
+          // tracks the LAST speaker of the prior batch (matching normal-
+          // turn `batch[batch.length - 1]!.authorId` semantics) so a multi-
+          // author prior turn like alice→bob restores `bob`, not alice.
+          live.currentTurnAuthorId = live.lastTurnAuthorId
+          live.currentTurnAuthorIds = new Set(live.lastTurnAuthorIds)
         }
 
         // Update the live origin holder so this turn's tool.before events
@@ -1090,7 +1221,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         logger.info(`[channels] ${live.keyId} prompting batch=${batch.length} text_len=${text.length}`)
         const promptStart = now()
         const successfulSendsBeforePrompt = live.successfulChannelSends
-        await fireSessionTurnStart(live)
+        await fireSessionTurnStart(live, text)
         try {
           await live.session.prompt(text)
           await validateChannelTurn(live, successfulSendsBeforePrompt)
@@ -1105,6 +1236,9 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         }
         await fireSessionIdle(live)
         live.lastTurnAuthorIds = new Set(live.currentTurnAuthorIds)
+        if (live.currentTurnAuthorId !== null) {
+          live.lastTurnAuthorId = live.currentTurnAuthorId
+        }
       }
     } finally {
       live.draining = false
@@ -1706,6 +1840,14 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       if (live.destroyed) continue
       if (live.draining) continue
       if (live.promptQueue.length > 0) continue
+      // pendingSystemReminders is checked alongside promptQueue because both
+      // represent pending work that drain() will process. Today's only
+      // populator (injectSubagentCompletionReminder) also fires drain()
+      // synchronously, which sets draining=true and shadows this guard via
+      // the line above — but the guard exists to keep the invariant honest
+      // for any future caller that queues a reminder without immediately
+      // waking the drain loop.
+      if (live.pendingSystemReminders.length > 0) continue
       if (t - live.lastInboundAt <= SESSION_IDLE_MS) continue
       victims.push(live)
     }
@@ -1733,6 +1875,87 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     }
   }
 
+  const executeCommand = async (
+    key: ChannelKey,
+    name: string,
+    options: ExecuteCommandOptions,
+  ): Promise<ExecuteCommandResult> => {
+    const lowered = name.toLowerCase()
+    if (!commands.has(lowered)) {
+      return { kind: 'unknown-command', name: lowered }
+    }
+    // Permission gate runs BEFORE the live-session lookup so a guest user
+    // invoking /stop on a non-existent session gets 'permission-denied'
+    // (consistent answer regardless of session state) rather than leaking
+    // session presence via the 'no-live-session' vs 'permission-denied'
+    // distinction.
+    const partial: SessionOrigin = {
+      kind: 'channel',
+      adapter: key.adapter,
+      workspace: key.workspace,
+      chat: key.chat,
+      thread: key.thread,
+      lastInboundAuthorId: options.invokerId,
+    }
+    if (!permissions.has(partial, CORE_PERMISSIONS.channelRespond)) {
+      return { kind: 'permission-denied' }
+    }
+    const resolved = resolveLiveSessionForCommand(liveSessions, key)
+    if (resolved.kind === 'none') {
+      return { kind: 'no-live-session' }
+    }
+    if (resolved.kind === 'ambiguous') {
+      return { kind: 'ambiguous', matchCount: resolved.count }
+    }
+    const result = await commands.execute(`/${lowered}`, { live: resolved.session, event: null })
+    if (result.kind === 'handled') {
+      return { kind: 'handled', name: result.name }
+    }
+    // commands.execute can only return not-command (impossible — we pass a
+    // leading slash), unknown-command (impossible — we just checked has()),
+    // or handled. Any other outcome is a bug.
+    return { kind: 'unknown-command', name: lowered }
+  }
+
+  const injectSubagentCompletionReminder = (args: {
+    parentSessionId: string
+    subagent: string
+    taskId: string
+    ok: boolean
+    durationMs: number
+    error?: string
+  }): { kind: 'delivered'; keyId: string } | { kind: 'no-live-session' } => {
+    for (const live of liveSessions.values()) {
+      if (live.destroyed) continue
+      if (live.sessionId !== args.parentSessionId) continue
+      const text = renderSubagentCompletionReminder({
+        subagent: args.subagent,
+        taskId: args.taskId,
+        ok: args.ok,
+        durationMs: args.durationMs,
+        ...(args.error !== undefined ? { error: args.error } : {}),
+        channel: true,
+      })
+      live.pendingSystemReminders.push(text)
+      logger.info(`[channels] ${live.keyId}: subagent-completion reminder queued task=${args.taskId} ok=${args.ok}`)
+      // Wake the drain loop. If a turn is already in flight, the wakeup is
+      // a no-op because drain() will pick up the reminder on its next
+      // iteration (it now gates on promptQueue OR pendingSystemReminders).
+      // If the session is idle, fire drain() immediately rather than going
+      // through the debounce path — the reminder is not a user inbound,
+      // so the "coalesce nearby inbounds" rationale for debouncing does
+      // not apply. Mirrors the TUI path's `idle ? 'interrupt' : 'queue'`
+      // semantics: the channel router doesn't have a `delivery: interrupt`
+      // mechanism (no in-flight abort during a turn), but firing drain()
+      // immediately is the equivalent for an idle session.
+      if (!live.draining) {
+        void drain(live)
+      }
+      return { kind: 'delivered', keyId: live.keyId }
+    }
+    return { kind: 'no-live-session' }
+  }
+
   return {
     route,
     send,
@@ -1752,7 +1975,9 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     registerFetchAttachment,
     unregisterFetchAttachment,
     fetchAttachment,
+    executeCommand,
     getSelfAliases: computeSelfAliases,
+    injectSubagentCompletionReminder,
     stop,
     liveCount: () => liveSessions.size,
     __testing: {
@@ -1796,6 +2021,22 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         await stopTypingHeartbeat(live)
       },
       runIdleGc,
+      getLiveOriginSnapshot: (key: ChannelKey) => {
+        const live = liveSessions.get(channelKeyId(key))
+        const origin = live?.originRef.current
+        if (origin === undefined) return undefined
+        return { ...origin }
+      },
+      getLiveAuthorState: (key: ChannelKey) => {
+        const live = liveSessions.get(channelKeyId(key))
+        if (live === undefined) return undefined
+        return {
+          currentTurnAuthorId: live.currentTurnAuthorId,
+          currentTurnAuthorIds: Array.from(live.currentTurnAuthorIds),
+          lastTurnAuthorId: live.lastTurnAuthorId,
+          lastTurnAuthorIds: Array.from(live.lastTurnAuthorIds),
+        }
+      },
     },
   }
 }
@@ -1803,27 +2044,50 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
 function composeTurnPrompt(
   observed: readonly ObservedInbound[],
   batch: readonly QueuedInbound[],
-  state: { loopGuardActive: boolean } = { loopGuardActive: false },
+  state: { loopGuardActive: boolean; systemReminders?: readonly string[] } = { loopGuardActive: false },
 ): string {
   const parts: string[] = []
+  // System reminders (subagent-completion wakeups today) lead the turn body
+  // because they are typically what triggered the drain — when the prompt
+  // queue is empty and the only thing in this iteration is a reminder, the
+  // model needs to see the reminder before any optional context. The
+  // reminder block is self-fenced by its <system-reminder> tags, so no
+  // extra framing is needed and the model already learns this shape from
+  // the TUI path; channel sessions see the same tags.
+  if (state.systemReminders && state.systemReminders.length > 0) {
+    for (const reminder of state.systemReminders) {
+      parts.push(reminder)
+    }
+    parts.push('')
+  }
   // Loop-guard notice lives in the user-turn text (recomposed every drain)
   // rather than in the system prompt so it does not invalidate the
   // prompt-prefix cache. The cached prefix covers system + tools + earlier
   // turns; the current user-turn suffix is non-cacheable by design, so
   // adding a section here is cache-neutral.
   //
-  // SYSTEM MESSAGE convention: any runtime-injected block in the user turn
-  // that is NOT from a chat participant must use the
-  // `**[SYSTEM MESSAGE — not from a human]**` framing fenced by horizontal
-  // rules (`---`). This is structurally distinct from the H2 sections used
-  // for actual conversation content (`## Recent context`,
+  // SYSTEM MESSAGE convention: any runtime-injected block in the user
+  // turn that is NOT from a chat participant MUST use the
+  // `**[SYSTEM MESSAGE — not from a human]**` framing fenced by
+  // horizontal rules (`---`) — the loop-guard block below is the
+  // canonical example. This is structurally distinct from the H2
+  // sections used for actual conversation content (`## Recent context`,
   // `## Current message`). Without the fencing, models — especially
   // persona-rich ones like Kimi — read the heading as a human-authored
   // instruction and reply to it ("알겠습니다, 대화 여기까지 할게요"). The
-  // bracketed marker plus the explicit "Do not acknowledge or reply to this
-  // notice" line is the trust boundary that prevents this. New runtime
-  // notices (rate-limit, schema-mismatch, abort signals, etc.) MUST follow
-  // this same convention so models learn the pattern.
+  // bracketed marker plus the explicit "Do not acknowledge or reply to
+  // this notice" line is the trust boundary that prevents this. New
+  // runtime notices (rate-limit, schema-mismatch, abort signals, etc.)
+  // MUST follow this convention.
+  //
+  // ONE narrow exception exists: subagent-completion reminders use
+  // `<system-reminder>...</system-reminder>` tags (prepended above) for
+  // parity with the TUI path's identical tagging (see
+  // `renderSubagentCompletionReminder` in
+  // `src/agent/subagent-completion-reminder.ts`) so the model sees the
+  // same shape across origins. The exception is scoped to that single
+  // case: do NOT extend it to new notice types. Anything that is not
+  // a true subagent-style completion ping uses framing 1.
   if (state.loopGuardActive) {
     parts.push(
       '---',
@@ -1912,6 +2176,52 @@ function consecutiveSendKey(chat: string, thread: string | null | undefined): st
   return `${chat}:${thread ?? ''}`
 }
 
+export type ResolveLiveSessionResult =
+  | { kind: 'found'; session: LiveSession }
+  | { kind: 'none' }
+  | { kind: 'ambiguous'; count: number }
+
+// Lookup policy for adapter-driven commands. Exact-key match always wins.
+// On miss, fall back to (adapter, workspace, chat) without thread — but
+// only when EXACTLY ONE non-destroyed candidate exists. Ambiguous matches
+// return 'ambiguous' so the caller can refuse to act rather than abort an
+// arbitrary session.
+//
+// Why the fallback: Slack slash commands carry channel_id but no thread_ts,
+// so a slash invocation from a thread-keyed live session would otherwise
+// report no-live-session. Discord doesn't hit this — Discord treats threads
+// as channels, so the exact-key path already resolves.
+//
+// Why ambiguity-rejection: "first match wins" map-iteration semantics would
+// abort an arbitrary thread when multiple thread-keyed sessions coexist in
+// one channel (plausible on Slack: bot mentioned in multiple threads). The
+// user's slash command picker doesn't know about threads; we don't know
+// which they meant; refusing is safer than guessing.
+export function resolveLiveSessionForCommand(
+  liveSessions: ReadonlyMap<string, LiveSession>,
+  key: ChannelKey,
+): ResolveLiveSessionResult {
+  const exact = liveSessions.get(channelKeyId(key))
+  if (exact && !exact.destroyed) return { kind: 'found', session: exact }
+
+  const matches: LiveSession[] = []
+  for (const candidate of liveSessions.values()) {
+    if (candidate.destroyed) continue
+    if (
+      candidate.key.adapter === key.adapter &&
+      candidate.key.workspace === key.workspace &&
+      candidate.key.chat === key.chat
+    ) {
+      matches.push(candidate)
+      if (matches.length > 1) {
+        return { kind: 'ambiguous', count: matches.length }
+      }
+    }
+  }
+  if (matches.length === 1) return { kind: 'found', session: matches[0]! }
+  return { kind: 'none' }
+}
+
 function normalizeSendText(text: string | undefined): string | undefined {
   if (text === undefined) return undefined
   if (text === '') return undefined

package/src/channels/subagent-completion-bridge.ts

@@ -0,0 +1,84 @@
+import { parseSubagentCompletedPayload } from '@/agent/subagent-completion-reminder'
+import type { Stream } from '@/stream'
+
+import type { ChannelRouter } from './router'
+
+export type SubagentCompletionBridgeLogger = {
+  info: (msg: string) => void
+  warn: (msg: string) => void
+}
+
+export type SubagentCompletionBridgeOptions = {
+  stream: Stream
+  router: Pick<ChannelRouter, 'injectSubagentCompletionReminder'>
+  logger?: SubagentCompletionBridgeLogger
+}
+
+export type SubagentCompletionBridge = {
+  stop: () => void
+}
+
+const consoleLogger: SubagentCompletionBridgeLogger = {
+  info: (msg) => console.log(msg),
+  warn: (msg) => console.warn(msg),
+}
+
+// Bridges `subagent.completed` broadcasts on the in-process Stream into a
+// channel router call so the channel session that spawned the subagent
+// gets woken up with a `<system-reminder>` when the subagent finishes.
+//
+// Two-bridges-for-two-surfaces design (matches the TUI side at
+// src/server/index.ts `routeSubagentCompletionReminder`):
+//
+//   - TUI sessions: the WS server subscribes to broadcasts on the same
+//     stream and re-publishes the reminder as `target: { kind: 'session' }`
+//     so the per-session drain loop in the server picks it up. Lookup is
+//     by sessionId (which is `state.sessionFileId`).
+//
+//   - Channel sessions: this bridge subscribes and calls
+//     `router.injectSubagentCompletionReminder` because the channel router
+//     owns its own per-key drain loop and doesn't use the stream's
+//     session-keyed target.
+//
+// `parentSessionId` matching is the same on both sides: when a channel
+// session spawns a subagent via `spawn_subagent`, the tool captures
+// `sessionManager.getSessionId()` and publishes it as the broadcast's
+// `parentSessionId`. That id is exactly what the router stores on each
+// `LiveSession`, so the lookup is O(N) over live sessions with N small
+// (one per active conversation).
+//
+// On `no-live-session`, we silently drop. Three observable paths reach
+// this branch in production:
+//
+//   - The parent session was GC'd by the idle-eviction tick
+//     (SESSION_IDLE_MS) while the subagent was running.
+//   - The parent session rolled over (SESSION_FRESHNESS_TTL_MS) when a
+//     new inbound arrived during a long-running subagent — the channel
+//     conversation continues on the new sessionId, but the broadcast
+//     still carries the old one.
+//   - The parent was a TUI session (the TUI bridge in
+//     src/server/index.ts handles it).
+//
+// The right fix for the first two paths is for the broadcast to carry
+// the channel-key coordinate `{ adapter, workspace, chat, thread }` so
+// the bridge can fall back to "any live session for the same channel
+// key" when the exact sessionId no longer matches. That requires
+// extending the broadcast payload (consumed by TUI and channel paths)
+// and gating spawn_subagent to capture the origin coordinates — both
+// non-trivial. Deferred until we see this drop pattern in production
+// logs; the info log line below makes the case diagnosable from logs
+// alone.
+export function createSubagentCompletionBridge(options: SubagentCompletionBridgeOptions): SubagentCompletionBridge {
+  const logger = options.logger ?? consoleLogger
+  const unsubscribe = options.stream.subscribe({ target: { kind: 'broadcast' } }, (msg) => {
+    const parsed = parseSubagentCompletedPayload(msg.payload)
+    if (parsed === null) return
+    const result = options.router.injectSubagentCompletionReminder(parsed)
+    if (result.kind === 'no-live-session') {
+      logger.info(
+        `[channels] subagent-completion reminder dropped: no live session for parentSessionId=${parsed.parentSessionId} task=${parsed.taskId}`,
+      )
+    }
+  })
+  return { stop: unsubscribe }
+}

package/src/cli/builtins.ts

@@ -12,6 +12,7 @@ export const BUILTIN_COMMAND_NAMES = [
   'status',
   'reload',
   'logs',
+  'inspect',
   'shell',
   'compose',
   'channel',

package/src/cli/index.ts

@@ -22,6 +22,7 @@ const main = defineCommand({
     status: () => import('./status').then((m) => m.statusCommand),
     reload: () => import('./reload').then((m) => m.reload),
     logs: () => import('./logs').then((m) => m.logsCommand),
+    inspect: () => import('./inspect').then((m) => m.inspectCommand),
     shell: () => import('./shell').then((m) => m.shellCommand),
     compose: () => import('./compose').then((m) => m.composeCommand),
     channel: () => import('./channel').then((m) => m.channelCommand),