typeclaw 0.9.1 → 0.9.2

package/src/channels/manager.ts

@@ -5,6 +5,7 @@ import type { PermissionService } from '@/permissions'
 import type { GithubSecretsBlock } from '@/secrets'
 import { SecretsKakaoCredentialStore } from '@/secrets/kakao-store'
 import { SecretsBackend } from '@/secrets/storage'
+import type { Stream } from '@/stream'
 
 import { createDiscordBotAdapter, type DiscordBotAdapter } from './adapters/discord-bot'
 import { createGithubAdapter, type GithubAdapter } from './adapters/github'
@@ -78,6 +79,11 @@ export type ChannelManagerOptions = {
   // a URL" so error logs can be precise. Same shape as
   // `tunnelUrlForChannel` for consistency. Optional for tests.
   tunnelConfiguredForChannel?: (channelName: string) => boolean
+  // Forwarded to the router as `stream`. When set, every inbound the
+  // router sees is published as a tagged broadcast for inspect surfacing.
+  // Production wiring (`src/run/index.ts`) always passes the agent's
+  // Stream; tests typically omit it.
+  stream?: Stream
 }
 
 export type ChannelManager = {
@@ -113,6 +119,7 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
     ...(options.createSessionForChannel ? { createSessionForChannel: options.createSessionForChannel } : {}),
     ...(options.permissions ? { permissions: options.permissions } : {}),
     ...(options.claimHandler ? { claimHandler: options.claimHandler } : {}),
+    ...(options.stream ? { stream: options.stream } : {}),
   })
   const createDiscordAdapter = options.createDiscordAdapter ?? createDiscordBotAdapter
   const createGithub = options.createGithubAdapter ?? createGithubAdapter

package/src/channels/router.ts

@@ -11,6 +11,7 @@ import { createCommandRegistry } from '@/commands'
 import { CORE_PERMISSIONS, type PermissionService } from '@/permissions'
 import type { HookBus } from '@/plugin'
 import { extractClaimCode } from '@/role-claim'
+import type { Stream } from '@/stream'
 
 import { decideEngagement, grantStickyForReplyTargets, StickyLedger, type EngagementDecision } from './engagement'
 import {
@@ -505,6 +506,14 @@ export type CreateChannelRouterOptions = {
   // back over the same chat, or null to fall through to normal routing
   // when no pending claim window matches.
   claimHandler?: ClaimHandler
+  // Optional in-process Stream. When set, every inbound the router sees
+  // is published as a tagged broadcast (`kind: 'channel-inbound'`) so the
+  // `/inspect` WS endpoint can surface it live and `stream.scan()` can
+  // backfill it on subscribe. Decoupled from the routing decision: even
+  // permission-denied and role-claim inbounds publish, so the operator
+  // can diagnose silent drops from `typeclaw inspect` alone. Omitted in
+  // tests that don't care about inspect surfacing.
+  stream?: Stream
 }
 
 export type ClaimHandlerInput = {
@@ -539,6 +548,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   const sessionIdleTimeoutMs = options.sessionIdleTimeoutMs ?? SESSION_IDLE_TIMEOUT_MS
   const permissions = options.permissions ?? GRANT_ALL_PERMISSIONS
   const claimHandler = options.claimHandler
+  const stream = options.stream
   const liveSessions = new Map<string, LiveSession>()
   const creating = new Map<string, Promise<LiveSession>>()
   const outboundCallbacks = new Map<ChannelKey['adapter'], Set<OutboundCallback>>()
@@ -713,7 +723,20 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     const existing = liveSessions.get(keyId)
     if (existing && !existing.destroyed) {
       const idleMs = now() - existing.lastInboundAt
-      if (idleMs > SESSION_FRESHNESS_TTL_MS) {
+      // `lastInboundAt` is only bumped on engaged inbounds (see route()),
+      // so a session whose drain loop has been compiling a slow reply for
+      // 5+ minutes off a single inbound looks "idle" by this clock even
+      // though `session.prompt()` is mid-flight. Aborting that prompt to
+      // re-cold-start on the next user message wipes the in-flight work
+      // (observed against `openai-codex/gpt-5.5` in PR #359's incident:
+      // a 285s + 227s turn pair lost the second turn entirely to
+      // `tearDownLive` → `session.abort()` triggered by the user's
+      // follow-up at 5min idle). The `runIdleGc` path already skips
+      // draining sessions for the same reason; rollover must match.
+      // The skip is bounded: when the in-flight prompt completes or its
+      // own provider/transport timeout fires, `draining` clears and the
+      // next inbound's idle check picks up rollover normally.
+      if (idleMs > SESSION_FRESHNESS_TTL_MS && !existing.draining) {
         logger.info(`[channels] ${keyId}: stale-rollover (live: ${idleMs}ms idle)`)
         await tearDownLive(existing)
         liveSessions.delete(keyId)
@@ -1277,6 +1300,33 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     }, wait)
   }
 
+  const publishInbound = (event: InboundMessage, decision: 'engage' | 'observe' | 'denied' | 'claim'): void => {
+    if (stream === undefined) return
+    try {
+      stream.publish({
+        target: { kind: 'broadcast' },
+        payload: {
+          kind: 'channel-inbound',
+          adapter: event.adapter,
+          workspace: event.workspace,
+          chat: event.chat,
+          thread: event.thread,
+          authorId: event.authorId,
+          authorName: event.authorName,
+          authorIsBot: event.authorIsBot,
+          isDm: event.isDm,
+          isBotMention: event.isBotMention,
+          text: event.text,
+          externalMessageId: event.externalMessageId,
+          ts: event.ts,
+          decision,
+        },
+      })
+    } catch (err) {
+      logger.warn(`[channels] inbound stream publish failed: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+
   const route = async (event: InboundMessage): Promise<void> => {
     const adapterConfig = options.configForAdapter(event.adapter)
     if (!adapterConfig) return
@@ -1303,6 +1353,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         text: event.text,
       })
       if (outcome.kind !== 'fallthrough') {
+        publishInbound(event, 'claim')
         logger.info(
           `[channels] ${channelKeyId(key)}: claim ${outcome.kind} author=${event.authorId} id=${event.externalMessageId}`,
         )
@@ -1321,6 +1372,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     }
 
     if (isChannelRespondDenied(event)) {
+      publishInbound(event, 'denied')
       logger.info(
         `[channels] ${channelKeyId(key)}: denied by permissions (channel.respond) author=${event.authorId} id=${event.externalMessageId}`,
       )
@@ -1388,6 +1440,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     })
 
     if (decision === 'observe') {
+      publishInbound(event, 'observe')
       // Log every observe so an unanswered mention is diagnosable from logs
       // alone instead of "routed but no prompting" silence. The bracketed
       // shape mirrors `prompting batch=` so log scraping can pair them.
@@ -1396,6 +1449,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       return
     }
 
+    publishInbound(event, 'engage')
+
     updateLoopGuard(live, event)
 
     enqueue(live, event)
@@ -1739,8 +1794,19 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   const validateChannelTurn = async (live: LiveSession, successfulSendsBeforePrompt: number): Promise<void> => {
     if (live.successfulChannelSends > successfulSendsBeforePrompt) return
 
-    const assistantText = latestAssistantText(live.session)
-    if (assistantText === null) return
+    const candidate = recoverableAssistantText(live.session)
+    if (candidate === null) {
+      // Observability: previously a silent bail-out. The most common cause is a
+      // turn that ends mid-loop with NO assistant message at all (leaf is a
+      // session header / model_change / similar non-message entry, or a session
+      // that just started). Logged at debug-level info so operators can grep for
+      // unexpected silent turns; not warn-level because legitimate empty-state
+      // sessions hit this on every TUI-only check before the first user prompt.
+      logger.info(`[channels] ${live.keyId}: no recoverable assistant text in branch`)
+      return
+    }
+
+    const { text: assistantText, source } = candidate
 
     if (endsWithNoReplySignal(assistantText)) {
       const leakedReasoning = !isNoReplySignal(assistantText)
@@ -1760,8 +1826,18 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       return
     }
 
+    // `source` distinguishes the two recovery shapes for log triage:
+    //   - 'leaf': the assistant message IS the leaf (existing behavior; model
+    //     ended its turn with text but forgot to call channel_reply).
+    //   - 'pre-tool': the leaf is a toolResult (or other non-assistant entry)
+    //     and the assistant message lives upstream in the branch. This is the
+    //     Kimi-on-Fireworks `kimi-k2p6-turbo` failure mode where the post-tool
+    //     follow-up LLM call never produced a persisted assistant message, so
+    //     the model's pre-tool commentary is the only user-facing text we have.
+    //     Recovering it means the user gets *something* — strictly better than
+    //     the historical silent drop.
     logger.warn(
-      `[channels] ${live.keyId}: recovering assistant_text_without_channel_tool text_len=${assistantText.length}`,
+      `[channels] ${live.keyId}: recovering assistant_text_without_channel_tool source=${source} text_len=${assistantText.length}`,
     )
     const result = await send(
       {
@@ -2306,12 +2382,67 @@ async function raceWithTimeout<T>(work: Promise<T>, ms: number, label: string):
   }
 }
 
-function latestAssistantText(session: AgentSession): string | null {
-  const entry = session.sessionManager.getLeafEntry()
-  if (entry?.type !== 'message') return null
-  if (entry.message.role !== 'assistant') return null
-  if (entry.message.stopReason !== 'stop') return null
-  return visibleAssistantText(entry.message)
+// Walks the session branch backward from the leaf to find a recoverable
+// assistant message — i.e., text the user should see but didn't, because the
+// model failed to call `channel_reply`/`channel_send` before its turn ended.
+//
+// Two recovery shapes:
+//
+//   - source: 'leaf'
+//     The leaf entry IS an assistant message with `stopReason === 'stop'`.
+//     The model finished its turn with visible text but never called a channel
+//     tool. Pre-existing behavior; this is what the historical
+//     `latestAssistantText` covered.
+//
+//   - source: 'pre-tool'
+//     The leaf is a `toolResult` and the immediately-prior assistant message
+//     has `stopReason === 'toolUse'` (it called the tool that produced this
+//     toolResult). The upstream pi-agent-core loop SHOULD have made a
+//     follow-up LLM call after the tool returned, but that call either never
+//     happened or produced no persisted message. Recovers the assistant's
+//     pre-tool commentary so the user gets *something* — observed against
+//     Fireworks' `accounts/fireworks/routers/kimi-k2p6-turbo` on 2026-05-26.
+//
+// Returns null when no recovery is appropriate:
+//   - No leaf, no messages in branch, branch is malformed
+//   - Leaf is an assistant with non-'stop' stopReason (e.g. mid-stream error)
+//     and is NOT preceded by a toolResult pattern — we don't recover partial
+//     errored output because it's typically a truncation, not a deliberate
+//     reply
+//   - Leaf is a user/system message (model hasn't responded yet)
+//
+// `visibleAssistantText` returning '' (empty string) is a valid recovery
+// target — the caller's downstream guards (`endsWithNoReplySignal('')` returns
+// true) handle the no-content case explicitly via the `no_reply` log.
+function recoverableAssistantText(session: AgentSession): { text: string; source: 'leaf' | 'pre-tool' } | null {
+  const leaf = session.sessionManager.getLeafEntry()
+  if (!leaf) return null
+
+  if (leaf.type === 'message' && leaf.message.role === 'assistant') {
+    if (leaf.message.stopReason !== 'stop') return null
+    return { text: visibleAssistantText(leaf.message), source: 'leaf' }
+  }
+
+  // Pre-tool recovery: the leaf must be a toolResult message, and walking
+  // back through parentId chain must land on an assistant message before any
+  // user message (otherwise we'd be recovering text from a turn the user
+  // already saw a reply to). Bounded walk with a depth guard so a malformed
+  // session can't infinite-loop.
+  if (!(leaf.type === 'message' && leaf.message.role === 'toolResult')) return null
+
+  let cursor: { parentId: string | null } | undefined = leaf
+  for (let depth = 0; depth < 32 && cursor?.parentId; depth++) {
+    const parent = session.sessionManager.getEntry(cursor.parentId)
+    if (!parent) return null
+    if (parent.type === 'message') {
+      if (parent.message.role === 'assistant') {
+        return { text: visibleAssistantText(parent.message), source: 'pre-tool' }
+      }
+      if (parent.message.role === 'user') return null
+    }
+    cursor = parent
+  }
+  return null
 }
 
 function visibleAssistantText(message: AssistantMessage): string {

package/src/channels/schema.ts

@@ -19,7 +19,7 @@ const stickinessSchema = z.union([
   }),
 ])
 
-export const STICKY_DEFAULT_WINDOW_MS = 5 * 60 * 1000
+export const STICKY_DEFAULT_WINDOW_MS = 15 * 60 * 1000
 
 const engagementSchema = z
   .object({

package/src/cli/compose.ts

@@ -12,11 +12,12 @@ import {
   type ComposeDoctorReport,
 } from '@/compose'
 import { config } from '@/config'
+import { parseTailValue } from '@/container'
 import { formatJson, formatReport } from '@/doctor'
 
 import { formatComposeStatus } from './compose-status'
 import { formatComposeUsage, formatComposeUsageJson } from './compose-usage'
-import { c, spinner } from './ui'
+import { c, errorLine, spinner } from './ui'
 import { parseSince, parseUntil } from './usage-args'
 
 const startSub = defineCommand({
@@ -144,8 +145,23 @@ const logsSub = defineCommand({
       description: 'stream new log output as it arrives',
       default: false,
     },
+    tail: {
+      type: 'string',
+      alias: 'n',
+      description: 'number of lines to show from the end of each agent\'s logs (non-negative integer or "all")',
+    },
   },
   async run({ args }) {
+    let tail: string | undefined
+    if (args.tail !== undefined) {
+      const parsed = parseTailValue(args.tail)
+      if (!parsed.ok) {
+        console.error(errorLine(parsed.reason))
+        process.exit(2)
+      }
+      tail = parsed.value
+    }
+
     const controller = new AbortController()
     const onSig = (): void => controller.abort()
     process.once('SIGINT', onSig)
@@ -156,7 +172,12 @@ const logsSub = defineCommand({
       } else {
         console.log(c.dim('Showing logs for all agents.'))
       }
-      const result = await composeLogs({ rootCwd: process.cwd(), follow: args.follow, signal: controller.signal })
+      const result = await composeLogs({
+        rootCwd: process.cwd(),
+        follow: args.follow,
+        tail,
+        signal: controller.signal,
+      })
       if (result.agents.length === 0) {
         console.log(c.dim('No typeclaw agents found in immediate subdirectories of cwd.'))
         return

package/src/cli/logs.ts

@@ -1,6 +1,6 @@
 import { defineCommand } from 'citty'
 
-import { logs } from '@/container'
+import { logs, parseTailValue } from '@/container'
 import { findAgentDir } from '@/init'
 
 import { c, errorLine } from './ui'
@@ -17,17 +17,32 @@ export const logsCommand = defineCommand({
       description: 'stream new log output as it arrives',
       default: false,
     },
+    tail: {
+      type: 'string',
+      alias: 'n',
+      description: 'number of lines to show from the end of the logs (non-negative integer or "all")',
+    },
   },
   async run({ args }) {
     const cwd = findAgentDir(process.cwd()) ?? process.cwd()
 
+    let tail: string | undefined
+    if (args.tail !== undefined) {
+      const parsed = parseTailValue(args.tail)
+      if (!parsed.ok) {
+        console.error(errorLine(parsed.reason))
+        process.exit(2)
+      }
+      tail = parsed.value
+    }
+
     if (args.follow) {
       console.log(c.cyan('Streaming container logs...'))
     } else {
       console.log(c.dim('Showing container logs.'))
     }
 
-    const result = await logs({ cwd, follow: args.follow })
+    const result = await logs({ cwd, follow: args.follow, tail })
     if (!result.ok) {
       console.error(errorLine(result.reason))
       process.exit(1)

package/src/compose/logs.ts

@@ -1,4 +1,4 @@
-import { containerExists } from '@/container'
+import { buildDockerLogsCmd, containerExists } from '@/container'
 import { supportsColor } from '@/container/log-colors'
 import { makeLogTimestampReformatter, type TimestampReformatter } from '@/container/log-timestamps'
 import { getBun } from '@/container/shared'
@@ -8,6 +8,7 @@ import { discoverAgents, type AgentEntry } from './discover'
 export type ComposeLogsOptions = {
   rootCwd: string
   follow: boolean
+  tail?: string
   out?: NodeJS.WritableStream
   err?: NodeJS.WritableStream
   signal?: AbortSignal
@@ -66,6 +67,7 @@ export function makeLinePrefixer(
 export async function composeLogs({
   rootCwd,
   follow,
+  tail,
   out = process.stdout,
   err = process.stderr,
   signal,
@@ -93,9 +95,11 @@ export async function composeLogs({
   const useColor = supportsColor(out)
 
   const procs = attached.map((agent) => {
-    const cmd = follow
-      ? ['docker', 'logs', '--timestamps', '-f', agent.containerName]
-      : ['docker', 'logs', '--timestamps', agent.containerName]
+    const cmd = buildDockerLogsCmd({
+      containerName: agent.containerName,
+      follow,
+      ...(tail !== undefined ? { tail } : {}),
+    })
     const proc = bun.spawn({ cmd, stdout: 'pipe', stderr: 'pipe' })
     return { agent, proc }
   })

package/src/config/config.ts

@@ -121,6 +121,14 @@ const dockerfileObjectSchema = z.object({
   // time, not via version pins like apt. Default `false`; the bundled
   // `typeclaw-claude-code` skill prompts the user to opt in.
   claudeCode: z.boolean().default(false),
+  // `codexCli` is boolean-only (not an apt feature toggle): the upstream
+  // installer is the npm package `@openai/codex` which we install globally
+  // via `bun install -g`. Default `false`; the bundled `typeclaw-codex-cli`
+  // skill prompts the user to opt in. Mirrors the `claudeCode` toggle for
+  // OpenAI's Codex CLI (https://github.com/openai/codex) — same shape, same
+  // restart-required semantics, separate hook scripts (Codex uses
+  // hooks.json with a different event matcher than Claude Code).
+  codexCli: z.boolean().default(false),
   append: z.array(dockerfileLineSchema).default([]),
 })
 

package/src/container/index.ts

@@ -1,4 +1,4 @@
-export { logs, planLogs, type LogsPlan, type LogsResult } from './logs'
+export { buildDockerLogsCmd, logs, parseTailValue, planLogs, type LogsPlan, type LogsResult } from './logs'
 export { CONTAINER_PORT, TUI_TOKEN_LABEL, findFreePort, resolveHostPort, resolveTuiToken } from './port'
 export {
   requireContainerRunning,

package/src/container/logs.ts

@@ -5,6 +5,7 @@ import { containerExists, containerNameFromCwd, getBun } from './shared'
 export type LogsPlan = {
   containerName: string
   follow: boolean
+  tail?: string
 }
 
 export type LogsResult = { ok: true; containerName: string; exitCode: number } | { ok: false; reason: string }
@@ -12,6 +13,10 @@ export type LogsResult = { ok: true; containerName: string; exitCode: number } |
 export type LogsOptions = {
   cwd: string
   follow: boolean
+  // Forwarded to `docker logs --tail <value>`. Accepts a non-negative
+  // integer string or the sentinel `"all"`. When undefined, no `--tail`
+  // arg is added and docker's default ("all") applies.
+  tail?: string
   out?: NodeJS.WritableStream
   err?: NodeJS.WritableStream
   signal?: AbortSignal
@@ -23,6 +28,7 @@ export type LogsOptions = {
 export async function logs({
   cwd,
   follow,
+  tail,
   out = process.stdout,
   err = process.stderr,
   signal,
@@ -31,18 +37,14 @@ export async function logs({
   const bun = getBun()
   if (!bun) return { ok: false, reason: 'bun runtime not available' }
 
-  const { containerName } = planLogs(cwd, { follow })
+  const plan = planLogs(cwd, { follow, tail })
 
   try {
-    if (!(await containerExists(containerName))) {
-      return { ok: false, reason: `Container ${containerName} not found. Run \`typeclaw start\` first.` }
+    if (!(await containerExists(plan.containerName))) {
+      return { ok: false, reason: `Container ${plan.containerName} not found. Run \`typeclaw start\` first.` }
     }
 
-    const cmd = ['docker', 'logs', '--timestamps']
-    if (follow) cmd.push('-f')
-    cmd.push(containerName)
-
-    const proc = bun.spawn({ cmd, cwd, stdout: 'pipe', stderr: 'pipe' })
+    const proc = bun.spawn({ cmd: buildDockerLogsCmd(plan), cwd, stdout: 'pipe', stderr: 'pipe' })
 
     const onAbort = (): void => {
       try {
@@ -62,14 +64,39 @@ export async function logs({
     const exitCode = await proc.exited
     signal?.removeEventListener('abort', onAbort)
 
-    return { ok: true, containerName, exitCode }
+    return { ok: true, containerName: plan.containerName, exitCode }
   } catch (error) {
     return { ok: false, reason: error instanceof Error ? error.message : String(error) }
   }
 }
 
-export function planLogs(cwd: string, { follow }: { follow: boolean }): LogsPlan {
-  return { containerName: containerNameFromCwd(cwd), follow }
+export function planLogs(cwd: string, { follow, tail }: { follow: boolean; tail?: string }): LogsPlan {
+  return { containerName: containerNameFromCwd(cwd), follow, ...(tail !== undefined ? { tail } : {}) }
+}
+
+// Validate user-supplied `--tail` value. Mirrors `docker logs --tail`'s
+// accepted shape: either the sentinel `"all"` (case-insensitive) or a
+// non-negative integer.
+export function parseTailValue(raw: string): { ok: true; value: string } | { ok: false; reason: string } {
+  const trimmed = raw.trim()
+  if (trimmed.length === 0) return { ok: false, reason: '--tail requires a value (a non-negative integer or "all")' }
+  if (trimmed.toLowerCase() === 'all') return { ok: true, value: 'all' }
+  // Reject leading +, leading zeros (other than "0"), signs, decimals, and
+  // scientific notation up front so the user gets a clear error instead of
+  // docker's terse "invalid value" later.
+  if (!/^(?:0|[1-9]\d*)$/.test(trimmed)) {
+    return { ok: false, reason: `--tail expects a non-negative integer or "all", got ${JSON.stringify(raw)}` }
+  }
+  return { ok: true, value: trimmed }
+}
+
+// Exported so `compose/logs.ts` builds the exact same `docker logs` argv shape.
+export function buildDockerLogsCmd(plan: LogsPlan): string[] {
+  const cmd = ['docker', 'logs', '--timestamps']
+  if (plan.tail !== undefined) cmd.push('--tail', plan.tail)
+  if (plan.follow) cmd.push('-f')
+  cmd.push(plan.containerName)
+  return cmd
 }
 
 // Exported for `compose/logs.ts` so the multi-agent path reuses the same