typeclaw 0.11.0 → 0.11.1

package/README.md

@@ -1,5 +1,9 @@
 # TypeClaw
 
+<p align="center">
+  <img src="./docs/public/typeey.png" alt="Typeey, the TypeClaw mascot — a plush bird with navy wings sitting in grass" width="240" />
+</p>
+
 > A TypeScript-native, Bun-powered, Docker-friendly general-purpose agent runtime.
 
 ## Why?
@@ -89,7 +93,7 @@ bun run lint
 bun run format
 ```
 
-See [AGENTS.md](./AGENTS.md) for the long-form architecture notes — stages, hostd internals, message stream, plugin contracts, and the testing philosophy. The docs site at [typeclaw.dev](https://typeclaw.dev) lives in [`docs/`](./docs/).
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the recommended local dev loop (`bun link` → `typeclaw init`), commit and PR conventions, and where to ask questions. See [AGENTS.md](./AGENTS.md) for the long-form architecture notes — stages, hostd internals, message stream, plugin contracts, and the testing philosophy. The docs site at [typeclaw.dev](https://typeclaw.dev) lives in [`docs/`](./docs/).
 
 ## Acknowledgments
 

package/package.json

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

package/src/agent/multimodal/look-at.ts

@@ -80,6 +80,14 @@ export const lookAtTool = defineTool({
         parentSessionId: '<look-at-tool>',
       }
 
+      // TODO(usage-accounting): this falls through to SessionManager.inMemory()
+      // because no sessionManager is passed, so the look_at subagent's
+      // message.usage never reaches the sessions/ JSONLs that `typeclaw usage`
+      // and the bundled `backup` plugin scan. Same root-cause class as the
+      // plugin-command/cron-handler path fixed in `runPromptForCommand`
+      // (src/server/command-runner.ts). Fixing this requires threading a
+      // SessionFactory into pi-coding-agent's tool execute() signature, which
+      // is a separate change.
       const { session, dispose } = await createSessionWithDispose({
         systemPromptOverride: systemPrompt,
         origin,

package/src/agent/system-prompt.ts

@@ -70,6 +70,8 @@ The bundled \`scout\` subagent is its external counterpart — web research only
 
 When the user hands you a task that will take minutes (a multi-step browser session, a long build, a complex external operation), acknowledge in plain language ("Alright, running that in the background — I'll let you know when it's done"), spawn one subagent with \`run_in_background: true\`, then KEEP TALKING. Stay available for follow-ups, related questions, parallel small tasks. When the completion reminder lands, weave the result into your next reply naturally. If the conversation has gone idle, proactively message the user with the result rather than waiting.
 
+**Concrete threshold: ~30 seconds.** If you expect a tool call to take longer than that, delegate. While your own \`bash\` is blocked, you cannot reply, the channel typing indicator cannot heartbeat past silent stretches (it caps after a couple of minutes of no tool activity by design — see \`MAX_TYPING_HEARTBEAT_MS\`), and the user sees a frozen-looking conversation. Specifically: do NOT run \`npm install\`, \`bun install\`, \`docker build\`, \`docker compose up\`, multi-target \`curl\` probes, headed-browser scrapes, WebSocket/CDP captures, long \`pytest\`/\`npm test\` suites, or any "do N requests across hosts" loop in your own session — delegate every one of those to \`operator\`. Single fast \`bash\` calls (a \`git status\`, a \`ls\`, a one-shot \`curl\` against a known endpoint) stay in your session; that's not what this rule is targeting.
+
 In a channel session, the completion \`<system-reminder>\` is NOT a user message — the channel origin's "you MUST call \`channel_reply\` for every user message" rule does not literally apply, but the underlying constraint does: plain-text output is invisible in a channel. Surface the result via \`channel_reply\` (or \`channel_send\`) so the user actually sees it. Failures need surfacing too: when a delegated task didn't complete, the user needs the outcome and whatever partial progress you got. Skipping the reply is legal only when the user has already seen the substantive answer — typically because you posted it via \`channel_reply\` in the same turn that spawned the subagent, and the reminder is purely confirming completion of a step the user is already tracking. In that case, prefer \`skip_response({ reason: "result confirms prior reply" })\` over the \`NO_REPLY\` text sentinel — the structured tool records why, so the operator can audit silent post-completion turns. Otherwise, post the result.
 
 Before you run a tool chain that returns bulky intermediate output you won't need again — multiple \`webfetch\` calls, a \`websearch\` round you'll iterate on, a \`bash\` command that scrapes a site or dumps a large response, an \`agent-browser\` session, a \`claude\` (Claude Code) or \`codex\` (OpenAI Codex CLI) delegation driven through tmux, any "fetch N things and synthesize" loop — delegate it to a subagent. \`scout\` (for research) or \`operator\` (for actions with side effects) runs the noisy work in its own context window and returns a distilled summary; your session carries the *answer*, not the raw material you derived it from. This is about context economy, not latency: even a fast operation belongs in a subagent when the byproducts are large and disposable (three quick news searches across different outlets still dumps three SERPs and three article bodies into your context forever). The exception is exactly one call whose result you'll cite directly — one \`webfetch\` of a known URL, one \`websearch\` query whose top result is the answer. Two of either, or any "across multiple sources" framing, is delegation territory.

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

@@ -0,0 +1,89 @@
+// Discord bot tokens are a JWT-shaped triple `<base64(user_id)>.<base64(ts)>.<hmac>`.
+// For bot users the user id is also the application id, which is the same
+// value Discord's OAuth2 authorize URL takes as `client_id`. Deriving it from
+// the token the operator just pasted lets us print a ready-to-click invite
+// URL without prompting separately for an application id.
+//
+// We intentionally keep this dependency-free and side-effect-free so it can be
+// called from the host-stage CLI (`channel add`, `init`) without touching the
+// agent-messenger SDK or making any network requests.
+
+// Discord permission bits the discord-bot adapter actually exercises at
+// runtime. Keep this in sync with the REST calls in discord-bot.ts —
+// anything the adapter does (send, react, fetch history, register slash
+// commands, attach files) needs the matching bit here, or the invite URL
+// will under-grant and the bot will silently 403 in production.
+//
+// References:
+//   https://discord.com/developers/docs/topics/permissions#permissions-bitwise-permission-flags
+const DISCORD_PERMISSIONS = {
+  ADD_REACTIONS: 1n << 6n,
+  VIEW_CHANNEL: 1n << 10n,
+  SEND_MESSAGES: 1n << 11n,
+  EMBED_LINKS: 1n << 14n,
+  ATTACH_FILES: 1n << 15n,
+  READ_MESSAGE_HISTORY: 1n << 16n,
+  USE_APPLICATION_COMMANDS: 1n << 31n,
+  SEND_MESSAGES_IN_THREADS: 1n << 38n,
+} as const
+
+// Sum of every bit the adapter uses. BigInt because SEND_MESSAGES_IN_THREADS
+// alone exceeds 2^32, so a plain `number` would silently lose precision once
+// Discord adds another high bit we want.
+export const DISCORD_BOT_INVITE_PERMISSIONS = Object.values(DISCORD_PERMISSIONS).reduce((acc, bit) => acc | bit, 0n)
+
+const DISCORD_OAUTH_AUTHORIZE = 'https://discord.com/oauth2/authorize'
+const DISCORD_BOT_SCOPES = ['bot', 'applications.commands'] as const
+
+/**
+ * Derive the application id (== bot user id) from a Discord bot token without
+ * calling the API. Returns `null` for any token whose first segment doesn't
+ * base64-decode into a snowflake — callers should treat that as "we couldn't
+ * parse it, skip the invite URL hint" rather than as an invalid token, because
+ * Discord reserves the right to change the token format and we'd rather
+ * silently fall back than block onboarding.
+ */
+export function deriveAppIdFromBotToken(token: string): string | null {
+  const segments = token.split('.')
+  if (segments.length !== 3) return null
+  const head = segments[0]
+  if (head === undefined || head.length === 0) return null
+  let decoded: string
+  try {
+    decoded = Buffer.from(padBase64(head), 'base64').toString('utf-8')
+  } catch {
+    return null
+  }
+  // Discord snowflakes are 17-20 digit decimal strings. Reject anything that
+  // doesn't look like one so we don't surface garbage as a "client_id".
+  if (!/^\d{17,20}$/.test(decoded)) return null
+  return decoded
+}
+
+/**
+ * Build the OAuth2 invite URL Discord renders the "Add to Server" picker for.
+ * Defaults to the `bot`+`applications.commands` scope pair and the permission
+ * bitfield the discord-bot adapter actually needs.
+ */
+export function buildDiscordInviteUrl(
+  appId: string,
+  opts: { permissions?: bigint; scopes?: readonly string[] } = {},
+): string {
+  const permissions = opts.permissions ?? DISCORD_BOT_INVITE_PERMISSIONS
+  const scopes = opts.scopes ?? DISCORD_BOT_SCOPES
+  const params = new URLSearchParams({
+    client_id: appId,
+    scope: scopes.join(' '),
+    permissions: permissions.toString(),
+  })
+  return `${DISCORD_OAUTH_AUTHORIZE}?${params.toString()}`
+}
+
+// Base64 segments inside JWT-shaped tokens omit `=` padding. Node's Buffer
+// tolerates missing padding for the standard alphabet but not for url-safe,
+// and we want defensive behavior either way.
+function padBase64(input: string): string {
+  const remainder = input.length % 4
+  if (remainder === 0) return input
+  return input + '='.repeat(4 - remainder)
+}

package/src/channels/adapters/kakaotalk-classify.ts

@@ -4,7 +4,16 @@ import { matchesAnyAlias } from '@/channels/engagement'
 import type { ChannelAdapterConfig } from '@/channels/schema'
 import type { InboundMessage } from '@/channels/types'
 
-export type InboundDropReason = 'self_author' | 'empty_text' | 'unknown_chat' | 'pre_connect'
+export type InboundDropReason = 'self_author' | 'empty_text' | 'unknown_chat' | 'pre_connect' | 'bot_message'
+
+// LOCO message_type 71 is KakaoTalk's notification/feed channel — official
+// accounts like "카카오 고객센터" and "카카오계정" (login alerts, security
+// notices, system messages). These arrive in @kakao-group buckets because
+// they aren't normal user chats, but they are not human conversation and
+// the agent should never reply to them. Not enumerated in
+// agent-messenger's `KAKAO_MESSAGE_TYPE` because that const only covers
+// user-composable types (TEXT/PHOTO/VIDEO/AUDIO/FILE/MULTIPHOTO).
+const KAKAO_NOTIFICATION_MESSAGE_TYPE = 71
 
 export type InboundClassification =
   | { kind: 'drop'; reason: InboundDropReason }
@@ -32,6 +41,9 @@ export function classifyInbound(
   if (String(event.author_id) === context.selfUserId) {
     return { kind: 'drop', reason: 'self_author' }
   }
+  if (event.message_type === KAKAO_NOTIFICATION_MESSAGE_TYPE) {
+    return { kind: 'drop', reason: 'bot_message' }
+  }
 
   const text = event.message ?? ''
   if (text === '') return { kind: 'drop', reason: 'empty_text' }

package/src/channels/adapters/kakaotalk.ts

@@ -671,6 +671,8 @@ function dropHint(reason: InboundDropReason): string {
   switch (reason) {
     case 'unknown_chat':
       return ' (chat not in cache after refresh and provisional registration; check earlier resolver-refresh-failed warnings)'
+    case 'bot_message':
+      return ' (LOCO message_type=71 is KakaoTalk notification/feed; official accounts like 카카오 고객센터 / 카카오계정 / login alerts)'
     case 'empty_text':
     case 'pre_connect':
     case 'self_author':

package/src/channels/router.ts

@@ -62,6 +62,15 @@ export const TYPING_HEARTBEAT_MS = 8000
 // platform-side typing forever. Slack Assistant status in particular has a
 // documented 2-minute timeout, so repeatedly refreshing it after that point
 // turns a temporary status into a permanent-looking artifact.
+//
+// The cap is measured from `live.typingStartedAt`, which is refreshed by
+// two signals of life (see `bumpTypingActivity`):
+//   1. Each new `drain()` iteration (a new turn is starting).
+//   2. Each `tool_execution_end` from the agent session (a tool just
+//      completed — the prompt is progressing, not stuck).
+// A 2-minute bash command that emits no intermediate events still trips
+// the cap, but a chatty agent running long tools stays under it
+// indefinitely. The cap exists to catch *silence*, not duration.
 export const MAX_TYPING_HEARTBEAT_MS = 2 * 60 * 1000
 
 // Idle GC: a LiveSession whose `lastInboundAt` is older than
@@ -361,6 +370,7 @@ type LiveSession = {
   membershipFetch: Promise<MembershipCount | null> | null
   destroyed: boolean
   unsubProviderErrors: (() => void) | null
+  unsubTypingActivity: (() => void) | null
 }
 
 // `event` is null for command invocations that originated outside the inbound
@@ -1000,10 +1010,12 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         membershipFetch,
         destroyed: false,
         unsubProviderErrors: null,
+        unsubTypingActivity: null,
       }
       live.unsubProviderErrors = subscribeProviderErrors(created.session, (err) => {
         logger.error(`[channels] ${live.keyId}: LLM call failed: ${err.message}`)
       })
+      live.unsubTypingActivity = subscribeTypingActivity(created.session, live)
       liveSessions.set(keyId, live)
 
       if (isColdStart) {
@@ -1149,9 +1161,25 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     )
   }
 
+  const bumpTypingActivity = (live: LiveSession): void => {
+    if (live.typingTimer === null) return
+    live.typingStartedAt = now()
+  }
+
+  const subscribeTypingActivity = (session: AgentSession, live: LiveSession): (() => void) => {
+    return session.subscribe((event) => {
+      if (event.type !== 'tool_execution_end') return
+      bumpTypingActivity(live)
+    })
+  }
+
   const startTypingHeartbeat = (live: LiveSession): void => {
     if (live.typingTimedOut || live.typingStopPromise) return
-    if (live.typingTimer || live.destroyed) return
+    if (live.destroyed) return
+    if (live.typingTimer) {
+      bumpTypingActivity(live)
+      return
+    }
     live.typingStartedAt = now()
     // Fire immediately so the indicator appears on the very first inbound,
     // not 8 seconds later.
@@ -1163,7 +1191,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       }
       if (now() - live.typingStartedAt >= MAX_TYPING_HEARTBEAT_MS) {
         logger.warn(
-          `[channels] ${live.keyId}: typing indicator paused after ${MAX_TYPING_HEARTBEAT_MS}ms; prompt still in flight`,
+          `[channels] ${live.keyId}: typing indicator paused after ${MAX_TYPING_HEARTBEAT_MS}ms with no activity; prompt still in flight`,
         )
         live.typingTimedOut = true
         void stopTypingHeartbeat(live)
@@ -2029,6 +2057,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     live.debounceTimer = null
     live.unsubProviderErrors?.()
     live.unsubProviderErrors = null
+    live.unsubTypingActivity?.()
+    live.unsubTypingActivity = null
     await stopTypingHeartbeat(live)
     try {
       await live.session.abort()
@@ -2235,7 +2265,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         }
         if (now() - live.typingStartedAt >= MAX_TYPING_HEARTBEAT_MS) {
           logger.warn(
-            `[channels] ${live.keyId}: typing indicator paused after ${MAX_TYPING_HEARTBEAT_MS}ms; prompt still in flight`,
+            `[channels] ${live.keyId}: typing indicator paused after ${MAX_TYPING_HEARTBEAT_MS}ms with no activity; prompt still in flight`,
           )
           live.typingTimedOut = true
           await stopTypingHeartbeat(live)
@@ -2473,10 +2503,32 @@ export type QuoteAnchorCandidate = {
   hadInterveningObserved: boolean
 }
 
+// Strips `[<Adapter> message with ...]` placeholders that adapter
+// classifiers synthesize for non-text inbounds (KakaoTalk stickers,
+// Slack/Discord/Telegram attachments). The quote anchor is a UX
+// affordance pointing the human at *their words* — quoting a sticker as
+// `> Alice: [KakaoTalk message with sticker (sticker_ani) pack=... path=...]`
+// is noise, and for mixed inbounds like `사진 [KakaoTalk message with
+// photo 1254x1254 ...]` the human only wrote `사진`, so the placeholder
+// is the wrong thing to surface. The callsite (captureQuoteCandidate)
+// treats an empty residue as "no quote anchor"; mixed inbounds keep the
+// human-written portion. renderQuoteAnchor later collapses whitespace
+// so residual double-spaces from mid-string strips are harmless.
+const CHANNEL_MEDIA_PLACEHOLDER_RE = /\[(?:KakaoTalk|Slack|Discord|Telegram) message with [^\]]*\]/g
+
+export function stripChannelMediaPlaceholders(text: string): string {
+  return text
+    .replace(CHANNEL_MEDIA_PLACEHOLDER_RE, '')
+    .replace(/[ \t]+\n/g, '\n')
+    .trim()
+}
+
 // Snapshot the primary inbound + observed-buffer state at drain time so
 // the send-side decision has the data it needs without holding a
 // reference to the batch arrays. Returns null when there's nothing
-// anchorable (empty batch, primary is a bot).
+// anchorable (empty batch, primary is a bot, or primary is a non-text
+// inbound with no residual human-written text after stripping the
+// adapter's media placeholder).
 //
 // `hadInterveningObserved` counts ONLY live observations (`source ===
 // 'observed'`), not prefetched scrollback. Prefetch stamps `receivedAt =
@@ -2495,8 +2547,10 @@ export function captureQuoteCandidate(
   if (batch.length === 0) return null
   const primary = batch[batch.length - 1]!
   if (primary.authorIsBot) return null
+  const cleaned = stripChannelMediaPlaceholders(primary.text)
+  if (cleaned === '') return null
   return {
-    source: { adapter, authorId: primary.authorId, authorName: primary.authorName, text: primary.text },
+    source: { adapter, authorId: primary.authorId, authorName: primary.authorName, text: cleaned },
     primaryReceivedAt: primary.receivedAt,
     hadInterveningObserved: hasInterveningObserved(primary.receivedAt, observed),
   }

package/src/cli/channel.ts

@@ -1,5 +1,4 @@
 import { randomBytes } from 'node:crypto'
-import { readFile } from 'node:fs/promises'
 
 import { cancel, confirm, intro, isCancel, log, note, password, select, spinner, text } from '@clack/prompts'
 import { defineCommand } from 'citty'
@@ -27,7 +26,8 @@ import {
 import { runKakaotalkBootstrap } from '@/init/kakaotalk-auth'
 import { SecretsKakaoCredentialStore } from '@/secrets/kakao-store'
 
-import { c, done, errorLine, printSlackAppManifestSetup } from './ui'
+import { CANCEL_SYMBOL, promptPrivateKeyPem } from './prompt-pem'
+import { c, done, errorLine, printDiscordInviteHint, printSlackAppManifestSetup } from './ui'
 
 const CHANNEL_LABELS: Record<ChannelKind, string> = {
   'slack-bot': 'Slack',
@@ -805,15 +805,12 @@ async function promptGithubAuthUpdate(currentType: 'pat' | 'app'): Promise<Githu
       ].join('\n'),
       'Rotate the GitHub App private key',
     )
-    const privateKeyInput = await text({
-      message: 'New GitHub App private key PEM, escaped PEM, or path to .pem file',
-      validate: (value) => (value && value.length > 0 ? undefined : 'Private key is required'),
-    })
-    if (isCancel(privateKeyInput)) {
+    const privateKey = await promptPrivateKeyPem('New GitHub App private key PEM, escaped PEM, or path to .pem file')
+    if (privateKey === CANCEL_SYMBOL) {
       cancel('Aborted.')
       process.exit(0)
     }
-    return { type: 'app', privateKey: await resolvePrivateKeyInput(privateKeyInput) }
+    return { type: 'app', privateKey }
   }
 
   note(
@@ -855,11 +852,8 @@ async function promptGithubAppAuth(): Promise<{
     cancel('Aborted.')
     process.exit(0)
   }
-  const privateKeyInput = await text({
-    message: 'GitHub App private key PEM, escaped PEM, or path to .pem file',
-    validate: (value) => (value && value.length > 0 ? undefined : 'Private key is required'),
-  })
-  if (isCancel(privateKeyInput)) {
+  const privateKey = await promptPrivateKeyPem('GitHub App private key PEM, escaped PEM, or path to .pem file')
+  if (privateKey === CANCEL_SYMBOL) {
     cancel('Aborted.')
     process.exit(0)
   }
@@ -876,17 +870,11 @@ async function promptGithubAppAuth(): Promise<{
   return {
     type: 'app',
     appId: Number(appId),
-    privateKey: await resolvePrivateKeyInput(privateKeyInput),
+    privateKey,
     ...(parsedInstallationId !== undefined ? { installationId: parsedInstallationId } : {}),
   }
 }
 
-async function resolvePrivateKeyInput(input: string): Promise<string> {
-  const normalized = input.replace(/\\n/g, '\n')
-  if (normalized.includes('-----BEGIN') && normalized.includes('PRIVATE KEY-----')) return normalized
-  return await readFile(input, 'utf8')
-}
-
 function parseRepos(input: string): string[] {
   return input
     .split(',')
@@ -927,6 +915,7 @@ async function promptDiscordToken(): Promise<string> {
     cancel('Aborted.')
     process.exit(0)
   }
+  printDiscordInviteHint(token)
   return token
 }
 

package/src/cli/init.ts

@@ -1,5 +1,4 @@
 import { randomBytes } from 'node:crypto'
-import { readFile } from 'node:fs/promises'
 
 import { cancel, confirm, intro, isCancel, log, note, password, select, spinner, text } from '@clack/prompts'
 import { defineCommand } from 'citty'
@@ -36,7 +35,8 @@ import { makeOAuthLoginRunner, type OAuthLoginResult } from '@/init/oauth-login'
 import { API_KEY_DASHBOARD_URL, validateApiKey, type KeyValidationResult } from '@/init/validate-api-key'
 
 import { buildOAuthCallbacks } from './oauth-callbacks'
-import { c, done, errorLine, printSlackAppManifestSetup } from './ui'
+import { CANCEL_SYMBOL, promptPrivateKeyPem } from './prompt-pem'
+import { c, done, errorLine, printDiscordInviteHint, printSlackAppManifestSetup } from './ui'
 
 // ESC and Ctrl+C both produce clack's cancel symbol (the keypress layer
 // aliases both to the same "cancel" action — there's no way to tell them
@@ -1066,6 +1066,7 @@ async function runDiscordFlow(): Promise<StepResult<CollectedInputs['channelSecr
     validate: (v) => (v && v.length > 0 ? undefined : 'Token is required'),
   })
   if (isCancel(token)) return back()
+  printDiscordInviteHint(token)
   return value({ discordBotToken: token })
 }
 
@@ -1299,11 +1300,8 @@ async function promptGithubAppAuth(): Promise<{
     validate: (v) => validatePositiveInteger(v ?? '', 'App ID is required'),
   })
   if (isCancel(appId)) return null
-  const privateKeyInput = await text({
-    message: 'GitHub App private key PEM, escaped PEM, or path to .pem file',
-    validate: (v) => (v && v.length > 0 ? undefined : 'Private key is required'),
-  })
-  if (isCancel(privateKeyInput)) return null
+  const privateKey = await promptPrivateKeyPem('GitHub App private key PEM, escaped PEM, or path to .pem file')
+  if (privateKey === CANCEL_SYMBOL) return null
   const installationId = await text({
     message: 'Installation ID (optional; leave blank to auto-discover)',
     validate: (v) =>
@@ -1314,17 +1312,11 @@ async function promptGithubAppAuth(): Promise<{
   return {
     type: 'app',
     appId: Number(appId),
-    privateKey: await resolveGithubPrivateKey(privateKeyInput),
+    privateKey,
     ...(parsedInstallationId !== undefined ? { installationId: parsedInstallationId } : {}),
   }
 }
 
-async function resolveGithubPrivateKey(input: string): Promise<string> {
-  const normalized = input.replace(/\\n/g, '\n')
-  if (normalized.includes('-----BEGIN') && normalized.includes('PRIVATE KEY-----')) return normalized
-  return await readFile(input, 'utf8')
-}
-
 function parseGithubRepos(input: string): string[] {
   return input
     .split(',')

package/src/cli/prompt-pem.ts

@@ -0,0 +1,113 @@
+import { readFile } from 'node:fs/promises'
+import { createInterface, type Interface } from 'node:readline'
+
+import { log } from '@clack/prompts'
+
+const BEGIN_MARKER = '-----BEGIN'
+const END_MARKER_RE = /^-----END [A-Z0-9 ]*PRIVATE KEY-----\s*$/
+const END_MARKER_INLINE_RE = /-----END [A-Z0-9 ]*PRIVATE KEY-----/
+
+export const CANCEL_SYMBOL = Symbol('cancel')
+
+export type ReadLineFn = () => Promise<string | typeof CANCEL_SYMBOL>
+
+export async function promptPrivateKeyPem(message: string): Promise<string | typeof CANCEL_SYMBOL> {
+  log.step(message)
+  log.message('Paste the PEM (including BEGIN/END lines), a path to a .pem file, or an escaped PEM.')
+
+  const reader = createStdinLineReader()
+  try {
+    const raw = await readPrivateKeyFromLines(reader.next)
+    if (raw === CANCEL_SYMBOL) return CANCEL_SYMBOL
+    return await resolvePrivateKeyInput(raw)
+  } finally {
+    reader.close()
+  }
+}
+
+/**
+ * Read a PEM block (or single-line value) using `readLine`.
+ *
+ * A line starting with `-----BEGIN` switches into block mode, accumulating
+ * until a line matches `-----END ... PRIVATE KEY-----`. Otherwise the first
+ * non-empty line is returned verbatim (path or escaped PEM). Leading blank
+ * lines are skipped so a stray Enter does not abort the prompt.
+ */
+export async function readPrivateKeyFromLines(readLine: ReadLineFn): Promise<string | typeof CANCEL_SYMBOL> {
+  let first: string
+  while (true) {
+    const line = await readLine()
+    if (line === CANCEL_SYMBOL) return CANCEL_SYMBOL
+    if (line.trim().length > 0) {
+      first = line
+      break
+    }
+  }
+
+  if (!first.trimStart().startsWith(BEGIN_MARKER)) return first.trim()
+
+  // Escaped-PEM pasted as one line (contains both BEGIN and END markers and
+  // no real newlines) bypasses block mode entirely.
+  if (END_MARKER_INLINE_RE.test(first)) return first.trim()
+
+  const lines: string[] = [first.trimEnd()]
+  while (true) {
+    const line = await readLine()
+    if (line === CANCEL_SYMBOL) return CANCEL_SYMBOL
+    const trimmed = line.trimEnd()
+    lines.push(trimmed)
+    if (END_MARKER_RE.test(trimmed)) break
+  }
+  return `${lines.join('\n')}\n`
+}
+
+export async function resolvePrivateKeyInput(input: string): Promise<string> {
+  const unescaped = input.includes('\\n') && !input.includes('\n') ? input.replace(/\\n/g, '\n') : input
+  if (unescaped.includes('-----BEGIN') && unescaped.includes('PRIVATE KEY-----')) return unescaped
+  return await readFile(input, 'utf8')
+}
+
+type StdinLineReader = {
+  next: ReadLineFn
+  close: () => void
+}
+
+function createStdinLineReader(): StdinLineReader {
+  return createReadlineLineReader(process.stdin)
+}
+
+export function createReadlineLineReader(input: NodeJS.ReadableStream): StdinLineReader {
+  const rl: Interface = createInterface({ input, terminal: false })
+  const queue: string[] = []
+  const waiters: ((value: string | typeof CANCEL_SYMBOL) => void)[] = []
+  let closed = false
+
+  rl.on('line', (line) => {
+    const waiter = waiters.shift()
+    if (waiter) waiter(line)
+    else queue.push(line)
+  })
+  rl.on('close', () => {
+    closed = true
+    for (const w of waiters.splice(0)) w(CANCEL_SYMBOL)
+  })
+
+  const next: ReadLineFn = () =>
+    new Promise((resolve) => {
+      const queued = queue.shift()
+      if (queued !== undefined) {
+        resolve(queued)
+        return
+      }
+      if (closed) {
+        resolve(CANCEL_SYMBOL)
+        return
+      }
+      waiters.push(resolve)
+    })
+
+  return {
+    next,
+    close: () => rl.close(),
+  }
+}

package/src/cli/ui.ts

@@ -2,6 +2,7 @@ import { styleText } from 'node:util'
 
 import { cancel, intro, isCancel, log, note, outro, spinner as clackSpinner } from '@clack/prompts'
 
+import { buildDiscordInviteUrl, deriveAppIdFromBotToken } from '@/channels/adapters/discord-bot-invite'
 import { type AutoUpgradeOutcome, describeAutoUpgrade } from '@/init/auto-upgrade'
 
 export { cancel, intro, isCancel, log, note, outro }
@@ -243,3 +244,24 @@ export function printSlackAppManifestSetup(output: NodeJS.WritableStream = proce
     'Finish Slack setup',
   )
 }
+
+// Discord's portal hands out a bot token but no invite URL — operators have to
+// hunt down Application ID → OAuth2 Generator → tick scopes → tick permissions
+// → copy. We short-circuit all of that: the application id is encoded in the
+// token's first base64 segment, so we can hand back a click-ready URL with
+// the exact permission bitfield the adapter uses. No-ops when the token isn't
+// parseable as a Discord bot token so we never block onboarding on best-effort
+// guidance.
+export function printDiscordInviteHint(token: string): void {
+  const appId = deriveAppIdFromBotToken(token)
+  if (appId === null) return
+  note(
+    [
+      buildDiscordInviteUrl(appId),
+      '',
+      'Open it, pick a server, click Authorize.',
+      "The bot won't receive messages until it's in at least one server.",
+    ].join('\n'),
+    'Invite the bot to a server',
+  )
+}

package/src/compose/discover.ts

@@ -15,6 +15,10 @@ export type AgentEntry = {
 // node_modules-style hidden dirs are not skipped because they don't match the
 // dot-prefix rule, but they also won't pass the typeclaw.json filter).
 //
+// Underscore-prefixed names are also skipped so operators can park a disabled
+// or in-progress agent next to live ones (e.g. `_archived-coder/`) without
+// compose touching it.
+//
 // Returns an empty array when rootCwd doesn't exist or is empty — discovery is
 // not the place to fail; the caller decides what to do with zero agents.
 //
@@ -33,6 +37,7 @@ export function discoverAgents(rootCwd: string): AgentEntry[] {
   for (const entry of entries) {
     if (!entry.isDir) continue
     if (entry.name.startsWith('.')) continue
+    if (entry.name.startsWith('_')) continue
     const cwd = join(root, entry.name)
     if (!isInitialized(cwd)) continue
     agents.push({ name: entry.name, cwd, containerName: containerNameFromCwd(cwd) })

package/src/run/index.ts

@@ -338,6 +338,7 @@ export async function startAgent({
             signal: abortController.signal,
             runtimeVersion: runtimeVersionOpt.runtimeVersion,
             containerName: containerNameOpt.containerName,
+            sessionFactory,
           }),
         subagent: (subName: string, payload?: unknown) =>
           dispatchSpawnSubagent(subName, payload, {
@@ -551,6 +552,7 @@ export async function startAgent({
       runtimeVersion: CLI_VERSION,
       containerName,
       outbound,
+      sessionFactory,
     })
 
   const server = createServer({

package/src/server/command-runner.ts

@@ -1,4 +1,9 @@
-import { createSessionWithDispose, type SessionOrigin } from '@/agent'
+import {
+  createSessionWithDispose,
+  type CreateSessionOptions,
+  type CreateSessionResult,
+  type SessionOrigin,
+} from '@/agent'
 import type { PermissionService } from '@/permissions'
 import type {
   CommandExecResult,
@@ -11,6 +16,7 @@ import type {
   SpawnSubagentOptions,
 } from '@/plugin'
 import type { PluginRuntime } from '@/run/plugin-runtime'
+import type { SessionFactory } from '@/sessions'
 
 export type CommandSpawnSubagent = (name: string, payload?: unknown, options?: SpawnSubagentOptions) => Promise<void>
 
@@ -29,6 +35,14 @@ export type CommandRunnerOptions = {
   runtimeVersion: string | undefined
   containerName: string | undefined
   outbound: CommandOutbound
+  // Hands a persisted SessionManager to every prompt session spawned from a
+  // plugin command's `ctx.prompt`. Required so the session writes its JSONL
+  // (and therefore its `message.usage`) under sessions/, which is what
+  // `typeclaw usage` and the `bundled-plugins/backup` plugin scan. Without
+  // this every plugin-command LLM call would fall through to
+  // `SessionManager.inMemory()` and never persist usage — see
+  // `runPromptForCommand` below.
+  sessionFactory: SessionFactory
 }
 
 type CommandHandle = {
@@ -166,6 +180,7 @@ export function createCommandRunner(opts: CommandRunnerOptions): CommandRunner {
               containerName: opts.containerName,
               permissions: opts.permissions,
               signal: abortController.signal,
+              sessionFactory: opts.sessionFactory,
             }),
           subagent: (subName, payload) =>
             opts.spawnSubagent(subName, payload, {
@@ -331,6 +346,8 @@ function writeLine(stream: WritableStream<Uint8Array>, line: string): void {
   void writer.write(new TextEncoder().encode(`${line}\n`)).then(() => writer.releaseLock())
 }
 
+export type CreateSessionForCommand = (options: CreateSessionOptions) => Promise<CreateSessionResult>
+
 export async function runPromptForCommand(args: {
   text: string
   origin: SessionOrigin
@@ -340,6 +357,16 @@ export async function runPromptForCommand(args: {
   containerName: string | undefined
   permissions: PermissionService
   signal: AbortSignal
+  // Persisted-session source. Each call gets a fresh SessionManager so the
+  // resulting JSONL is its own file under sessions/ — the same shape the
+  // cron `prompt` path uses in src/run/index.ts. Passing in-memory here
+  // regresses `typeclaw usage` (see CommandRunnerOptions.sessionFactory).
+  sessionFactory: SessionFactory
+  // Test seam for the agent-session boundary. Production passes the real
+  // `createSessionWithDispose`; tests inject a fake to verify wiring
+  // (specifically: the sessionManager handed off must be persisted, not
+  // in-memory) without booting the full session stack.
+  _createSession?: CreateSessionForCommand
 }): Promise<string> {
   // Mirrors src/agent/multimodal/look-at.ts: spawn a session, prompt, capture
   // the final assistant text, dispose. Unlike look-at we want the FULL agent
@@ -349,9 +376,11 @@ export async function runPromptForCommand(args: {
   // loader (no `systemPromptOverride`).
   const snapshot = args.runtime.get()
   const sessionId = resolveSessionIdForOrigin(args.origin)
-  const { session, dispose } = await createSessionWithDispose({
+  const create = args._createSession ?? createSessionWithDispose
+  const { session, dispose } = await create({
     origin: args.origin,
     permissions: args.permissions,
+    sessionManager: args.sessionFactory.createPersisted(),
     plugins: {
       registry: snapshot.registry,
       hooks: snapshot.hooks,

package/src/skills/typeclaw-channel-github/SKILL.md

@@ -36,27 +36,29 @@ When an incoming message says **"requested your review on PR #N"** (or "requeste
    gh pr view <N> --repo owner/repo --json title,body,baseRefName,headRefOid,files
    ```
 
-2. **Submit a multi-comment review** in one API call. `comments[]` accepts line-level entries; each one lands on the diff exactly like a human reviewer's inline comment:
+2. **Submit a multi-comment review** in one API call by piping a JSON payload to `gh api --input -`. `comments[]` accepts line-level entries; each one lands on the diff exactly like a human reviewer's inline comment:
 
    ```sh
-   gh api -X POST /repos/owner/repo/pulls/<N>/reviews \
-     -F event=COMMENT \
-     -f body="Overall: looks good with a few nits." \
-     -F 'comments[][path]=src/foo.ts' \
-     -F 'comments[][line]=42' \
-     -F 'comments[][side]=RIGHT' \
-     -F 'comments[][body]=nit: prefer `const` here.' \
-     -F 'comments[][path]=src/bar.ts' \
-     -F 'comments[][line]=10' \
-     -F 'comments[][side]=RIGHT' \
-     -F 'comments[][body]=Consider extracting this branch into a helper.'
+   cat <<'JSON' | gh api -X POST /repos/owner/repo/pulls/<N>/reviews --input -
+   {
+     "event": "COMMENT",
+     "body": "Overall: looks good with a few nits.",
+     "comments": [
+       { "path": "src/foo.ts", "line": 42, "side": "RIGHT", "body": "nit: prefer `const` here." },
+       { "path": "src/bar.ts", "line": 10, "side": "RIGHT", "body": "Consider extracting this branch into a helper." }
+     ]
+   }
+   JSON
    ```
 
+   **Always use `--input -` with a quoted heredoc (`<<'JSON'`) for review bodies.** Do **not** use `-f body=...` or `-F 'comments[][body]=...'`: those go through shell argument parsing, so backticks (\`) trigger command substitution and have to be backslash-escaped, which leaks the literal `\` into the rendered comment. The quoted heredoc passes the JSON through untouched — backticks, newlines, and `${...}` all survive verbatim. The same applies to any other `gh api` POST whose body contains backticks, embedded newlines, or shell metacharacters.
+
 3. **Then** post a one-line summary with `channel_reply` so the conversation has a human-readable trace pointing at the review.
 
 ### Rules
 
 - Use `event=COMMENT` by default. Use `APPROVE` only when you have high confidence the PR is ready to merge. Use `REQUEST_CHANGES` only when the PR has clear blockers — not for nits.
+- **Only post comments that the author needs to act on.** Do not post praise ("looks good", "nice refactor", "great work"), affirmations of correct code, or restatements of what a line does. If every comment in your review is positive, post a top-level summary via `channel_reply` instead of a review — or skip commenting and just `APPROVE`. Inline comments are for changes, questions, and blockers, not validation.
 - `line` is a line number **in the file**, not a position in the diff. `side: RIGHT` is the new revision (default for additions); `side: LEFT` is the old revision (use for comments on removed lines).
 - For multi-line comments, also set `start_line` and `start_side` (same semantics).
 - If you need to read whole files at the PR's head SHA, use `gh api /repos/owner/repo/contents/<path>?ref=<headRefOid>`.