typeclaw 0.20.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"

package/src/agent/restart/index.ts

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

package/src/agent/tools/restart.ts

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

package/src/channels/adapters/discord-bot-classify.ts

@@ -141,7 +141,13 @@ function splitInbound(event: DiscordGatewayMessageCreateEvent): SplitInbound {
   return { text, attachments }
 }
 
-function describeDiscordMedia(event: DiscordGatewayMessageCreateEvent): InboundAttachment[] {
+export type DiscordMediaCarrier = {
+  attachments?: DiscordFile[]
+  embeds?: DiscordGatewayEmbed[]
+  sticker_items?: DiscordGatewayStickerItem[]
+}
+
+export function describeDiscordMedia(event: DiscordMediaCarrier): InboundAttachment[] {
   return [
     ...(event.attachments ?? []).map(describeAttachment),
     ...(event.embeds ?? []).map(describeEmbed),
@@ -167,7 +173,7 @@ function describeSticker(sticker: DiscordGatewayStickerItem): Omit<InboundAttach
   return { kind: 'sticker', ref: '', filename: sticker.name }
 }
 
-function renderPlaceholder(attachment: InboundAttachment): string {
+export function renderPlaceholder(attachment: InboundAttachment): string {
   const parts: string[] = [`Discord attachment #${attachment.id}: ${attachment.kind}`]
   if (attachment.mimetype !== undefined) parts.push(attachment.mimetype)
   if (attachment.filename !== undefined) parts.push(`name=${attachment.filename}`)

package/src/channels/adapters/discord-bot.ts

@@ -1,8 +1,11 @@
 import { DiscordBotClient, DiscordBotListener } from 'agent-messenger/discordbot'
 import {
   DiscordIntent,
+  type DiscordFile,
+  type DiscordGatewayEmbed,
   type DiscordGatewayInteractionEvent,
   type DiscordGatewayMessageCreateEvent,
+  type DiscordGatewayStickerItem,
 } from 'agent-messenger/discordbot'
 
 import {
@@ -29,7 +32,12 @@ import type {
 } from '@/channels/types'
 
 import { createDiscordChannelResolver } from './discord-bot-channel-resolver'
-import { classifyInbound, type InboundDropReason } from './discord-bot-classify'
+import {
+  classifyInbound,
+  describeDiscordMedia,
+  type InboundDropReason,
+  renderPlaceholder,
+} from './discord-bot-classify'
 import {
   ackInteraction,
   parseInteractionAsCommand,
@@ -487,6 +495,9 @@ type DiscordRawHistoryMessage = {
   content: string
   timestamp: string
   message_reference?: { message_id?: string }
+  attachments?: DiscordFile[]
+  embeds?: DiscordGatewayEmbed[]
+  sticker_items?: DiscordGatewayStickerItem[]
 }
 
 // Discord treats threads as separate channels with their own snowflake ids,
@@ -551,14 +562,28 @@ export function createDiscordHistoryCallback(deps: {
 function mapDiscordMessage(msg: DiscordRawHistoryMessage, botUserId: string | null): ChannelHistoryMessage {
   const isBot = msg.author.bot === true || (botUserId !== null && msg.author.id === botUserId)
   const ts = Date.parse(msg.timestamp)
+  // The REST history fetch bypasses the inbound classifier, so attachments,
+  // embeds, and stickers on already-posted messages (e.g. an image on a thread
+  // root the agent is later @-mentioned under) must be mapped here too —
+  // otherwise they are silently dropped and look_at_channel_attachment can
+  // never resolve them. Mirror the classifier's splitInbound: bake placeholders
+  // into text and carry the structured attachments so the router can resolve ids.
+  const attachments = describeDiscordMedia(msg)
+  const text =
+    attachments.length === 0
+      ? msg.content
+      : msg.content === ''
+        ? attachments.map(renderPlaceholder).join('\n')
+        : `${msg.content}\n${attachments.map(renderPlaceholder).join('\n')}`
   return {
     externalMessageId: msg.id,
     authorId: msg.author.id,
     authorName: msg.author.global_name ?? msg.author.username ?? msg.author.id,
-    text: msg.content,
+    text,
     ts: Number.isFinite(ts) ? ts : 0,
     isBot,
     replyToBotMessageId: msg.message_reference?.message_id ?? null,
+    ...(attachments.length > 0 ? { attachments } : {}),
   }
 }
 

package/src/channels/adapters/github/decoy-reviewer.ts

@@ -0,0 +1,43 @@
+import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
+
+// `absent` separates "GitHub says the reviewer is already not requested"
+// (404/422 — never on the list, already removed, or invalid for the repo) from
+// `failed` ("couldn't reach GitHub"), so callers warn only on the latter.
+export type RemoveRequestedReviewerResult =
+  | { kind: 'removed'; status: number }
+  | { kind: 'absent'; status: number; message: string }
+  | { kind: 'failed'; status?: number; reason: string }
+
+export async function removeRequestedReviewer(params: {
+  fetchImpl: typeof fetch
+  token: string
+  owner: string
+  repo: string
+  pullNumber: number
+  reviewerLogin: string
+}): Promise<RemoveRequestedReviewerResult> {
+  const url = `${GITHUB_API_BASE}/repos/${params.owner}/${params.repo}/pulls/${params.pullNumber}/requested_reviewers`
+  try {
+    const response = await params.fetchImpl(url, {
+      method: 'DELETE',
+      headers: githubJsonHeaders(params.token),
+      body: JSON.stringify({ reviewers: [params.reviewerLogin] }),
+    })
+    if (response.ok) return { kind: 'removed', status: response.status }
+    const message = await response.text().catch(() => '')
+    // 404 (PR/reviewer not found) and 422 (reviewer not currently requested,
+    // or not a valid reviewer for this repo) mean there is nothing to remove —
+    // the desired end state already holds. Everything else (401/403 auth,
+    // 429 rate, 5xx) is a real failure worth surfacing.
+    if (response.status === 404 || response.status === 422) {
+      return { kind: 'absent', status: response.status, message }
+    }
+    return {
+      kind: 'failed',
+      status: response.status,
+      reason: `GitHub API ${response.status}${message !== '' ? `: ${message}` : ''}`,
+    }
+  } catch (err) {
+    return { kind: 'failed', reason: err instanceof Error ? err.message : String(err) }
+  }
+}

package/src/channels/adapters/github/inbound.ts

@@ -2,6 +2,8 @@ import { createHmac, timingSafeEqual } from 'node:crypto'
 
 import type { InboundMessage } from '@/channels/types'
 
+import type { GithubAuthContext } from './auth'
+import { removeRequestedReviewer } from './decoy-reviewer'
 import type { DeliveryDedup } from './dedup'
 import { isGithubEventAllowed } from './event-allowlist'
 import { encodeGithubReactionRef, type GithubReactionTarget } from './reactions'
@@ -23,6 +25,13 @@ export type GithubWebhookHandlerOptions = {
   // omitted, team-reviewer requests are silently dropped (the v1 fallback
   // behavior). The adapter wires this in production; tests inject a fake.
   isBotInTeam?: (input: { org: string; slug: string; login: string }) => Promise<boolean>
+  // App-auth only: mints a repo-scoped token used to drop the decoy reviewer
+  // once the bot's own review lands. Omitted under PAT auth (no decoy exists).
+  authToken?: (context?: GithubAuthContext) => Promise<string>
+  // Schedules the decoy-drop off the webhook ACK path so the 200 stays fast.
+  // Defaults to fire-and-forget; tests inject a recorder to await the task.
+  scheduleBackgroundTask?: (task: () => Promise<void>) => void
+  fetchImpl?: typeof fetch
 }
 
 export function createGithubWebhookHandler(options: GithubWebhookHandlerOptions): (req: Request) => Promise<Response> {
@@ -51,6 +60,7 @@ export function createGithubWebhookHandler(options: GithubWebhookHandlerOptions)
     const selfLogin = options.selfLogin()
     const author = readAuthor(event, payload)
     if (author !== null && isSelfAuthor(author, selfId, selfLogin)) {
+      maybeScheduleDecoyReviewerDrop({ event, action, payload, selfLogin, options })
       options.logger.info(
         `[github] dropped self-authored ${event}${action !== null ? `.${action}` : ''} from @${author.login}`,
       )
@@ -70,6 +80,65 @@ export function createGithubWebhookHandler(options: GithubWebhookHandlerOptions)
   }
 }
 
+// GitHub auto-records the App as a reviewer the moment its review posts, but
+// leaves the decoy user pinned as a perpetual "review requested". When the bot
+// drops its own review (the self-authored event we're about to discard), fire a
+// background DELETE to remove the decoy. The DELETE is authenticated as the App,
+// so the resulting review_request_removed webhook has the bot actor as sender
+// and is dropped by classifyReviewRequest's self-loop guard — no fresh session.
+function maybeScheduleDecoyReviewerDrop(input: {
+  event: string
+  action: string | null
+  payload: Record<string, unknown>
+  selfLogin: string | null
+  options: GithubWebhookHandlerOptions
+}): void {
+  const { event, action, payload, selfLogin, options } = input
+  if (event !== 'pull_request_review' || action !== 'submitted') return
+  if (selfLogin === null) return
+  const authToken = options.authToken
+  if (authToken === undefined) return
+  if ((options.authType?.() ?? 'pat') !== 'app') return
+  const decoyLogin = resolveDecoyReviewerLogin(selfLogin, 'app')
+  if (decoyLogin === null) return
+
+  const repository = readRepository(payload)
+  const pr = readRecord(payload.pull_request)
+  const pullNumber = readNumber(pr, 'number')
+  if (repository === null || pullNumber === null) return
+
+  const fetchImpl = options.fetchImpl ?? fetch
+  const schedule = options.scheduleBackgroundTask ?? defaultScheduleBackgroundTask
+  const target = `${repository.owner}/${repository.name}#${pullNumber}`
+  schedule(async () => {
+    // authToken can throw (installation lookup / token mint), and a thrown
+    // failure must still warn — the default scheduler swallows rejections, so
+    // catching here is the only place the failure is observable.
+    try {
+      const token = await authToken({ repoSlug: `${repository.owner}/${repository.name}` })
+      const result = await removeRequestedReviewer({
+        fetchImpl,
+        token,
+        owner: repository.owner,
+        repo: repository.name,
+        pullNumber,
+        reviewerLogin: decoyLogin,
+      })
+      if (result.kind === 'failed') {
+        options.logger.warn(`[github] failed to drop decoy reviewer @${decoyLogin} from ${target}: ${result.reason}`)
+      }
+    } catch (err) {
+      options.logger.warn(
+        `[github] failed to drop decoy reviewer @${decoyLogin} from ${target}: ${err instanceof Error ? err.message : String(err)}`,
+      )
+    }
+  })
+}
+
+function defaultScheduleBackgroundTask(task: () => Promise<void>): void {
+  void task().catch(() => {})
+}
+
 export async function verifySignature(body: string, secret: string, sigHeader: string): Promise<boolean> {
   const expected = `sha256=${createHmac('sha256', secret).update(body).digest('hex')}`
   const a = Buffer.from(expected)

package/src/channels/adapters/github/index.ts

@@ -19,7 +19,7 @@ import {
   buildPermissionGuidance,
   parseListHooksPermissionStatus,
 } from './permission-guidance'
-import { createGithubReactionCallback } from './reactions'
+import { createGithubReactionCallback, createGithubRemoveReactionCallback } from './reactions'
 import { createTeamMembershipChecker } from './team-membership'
 import { deregisterGithubWebhooks, registerGithubWebhooks, type WebhookRegistrationResult } from './webhook-register'
 
@@ -125,6 +125,11 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
     authType: options.secrets.auth.type,
     fetchImpl,
   })
+  const removeReaction = createGithubRemoveReactionCallback({
+    token: authToken,
+    authType: options.secrets.auth.type,
+    fetchImpl,
+  })
   const history = createGithubHistoryCallback({
     token: authToken,
     fetchImpl,
@@ -145,6 +150,8 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
     selfLogin: () => selfLogin,
     authType: () => options.secrets.auth.type,
     isBotInTeam,
+    authToken,
+    fetchImpl,
     logger,
     route: (message) => {
       rememberWorkspace(message.workspace, message.chat)
@@ -168,6 +175,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
       // is fully wired before any webhook can arrive.
       options.router.registerOutbound('github', outbound)
       options.router.registerReaction('github', reaction)
+      options.router.registerRemoveReaction('github', removeReaction)
       options.router.registerTyping('github', typing)
       options.router.registerHistory('github', history)
       options.router.registerMembership('github', membership)
@@ -180,6 +188,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
         // and the manager can report the failure cleanly.
         options.router.unregisterOutbound('github', outbound)
         options.router.unregisterReaction('github', reaction)
+        options.router.unregisterRemoveReaction('github', removeReaction)
         options.router.unregisterTyping('github', typing)
         options.router.unregisterHistory('github', history)
         options.router.unregisterMembership('github', membership)
@@ -301,6 +310,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
       started = false
       options.router.unregisterOutbound('github', outbound)
       options.router.unregisterReaction('github', reaction)
+      options.router.unregisterRemoveReaction('github', removeReaction)
       options.router.unregisterTyping('github', typing)
       options.router.unregisterHistory('github', history)
       options.router.unregisterMembership('github', membership)