typeclaw 0.34.1 → 0.35.1

package/src/channels/router.ts

@@ -24,6 +24,7 @@ import { extractClaimCode } from '@/role-claim'
 import type { Stream } from '@/stream'
 
 import { formatChannelCommandHelp } from './commands'
+import { detectContinuationWillingness } from './continuation-willingness'
 import {
   countEffectiveHumans,
   decideEngagement,
@@ -239,6 +240,30 @@ export const EMPTY_TURN_RETRY_NUDGE = [
 // drop so the human is never left staring at dead air after a degenerate turn.
 export const EMPTY_TURN_FALLBACK_TEXT =
   "⚠️ I got stuck putting together a reply and couldn't finish. Could you rephrase or try again?"
+// At most one continuation nudge per logical turn. Stricter than the empty-turn
+// retry budget (2) because the turn ALREADY delivered a user-facing reply — this
+// is a one-shot correction offer, not recovery from no output.
+export const MAX_WILLINGNESS_NUDGES = 1
+// Injected when a reply that ended the turn (terminal-reply abort) promised to
+// keep working but omitted `continue: true`. Reminder-only, SYSTEM MESSAGE
+// framing so persona-rich models do not reply to the notice itself.
+export const WILLINGNESS_NUDGE = [
+  '---',
+  '**[SYSTEM MESSAGE — not from a human]**',
+  '',
+  'Your last reply said you would keep working this turn, but it ended right',
+  'after sending — a successful channel reply ends the turn unless you set',
+  '`continue: true` on it. This is an automated signal from the channel router,',
+  'not a message from anyone in the chat. **Do not acknowledge or reply to this',
+  'notice itself.**',
+  '',
+  'If you still have work to do (fetch data, run a tool, spawn a subagent, then',
+  'reply with the result), do it now — and on the status reply that precedes more',
+  'work this turn, set `continue: true`. If there is nothing left to do, reply',
+  'with `NO_REPLY`.',
+  '',
+  '---',
+].join('\n')
 // Rolling window for outbound send-rate telemetry. 5s matches Discord's
 // rate-limit shape (5 msg / 5 s / channel) and comfortably covers Slack's
 // 1 msg/s sustained. The window is observational; exceeding the burst
@@ -565,6 +590,18 @@ type LiveSession = {
   // increments it before injecting EMPTY_TURN_RETRY_NUDGE and reads it to decide
   // retry-vs-fallback. See the candidate===null branch.
   emptyTurnRetries: number
+  // Count of continuation nudges spent on the CURRENT logical turn, bounded by
+  // MAX_WILLINGNESS_NUDGES. Reset alongside `emptyTurnRetries` only when a real
+  // user batch starts (batch.length > 0), NOT on the reminder-only iteration the
+  // nudge itself queues — same anti-reloop discipline as the empty-turn budget.
+  willingnessNudges: number
+  // Stashed by `installChannelReplyTerminalHook` just before it aborts the turn
+  // after a successful `channel_reply` that omitted `continue: true`. Read once
+  // by `validateChannelTurn` to decide the continuation nudge. `turnSeq`-stamped
+  // (like `skippedTurn`/`skipLockedSendTurn`) so a stale record from an earlier
+  // turn can never trigger a nudge on a later one. `null` when no such reply
+  // ended this turn.
+  lastTerminalReplyAbort: { turnSeq: number; text: string } | null
   // One-shot output-token budget for the NEXT `session.prompt()` only.
   // `installChannelOutputCap` reads and clears it per stream call, so it
   // overrides the default backstop for exactly one re-prompt. Set by the
@@ -1491,6 +1528,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         inFlightToolSends: new Map(),
         policyDeniedToolSendsThisTurn: new Map(),
         emptyTurnRetries: 0,
+        willingnessNudges: 0,
+        lastTerminalReplyAbort: null,
         nextPromptMaxTokens: undefined,
         skippedTurn: null,
         skipLockedSendTurn: null,
@@ -1746,6 +1785,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       const keepTurnAlive = details?.continue === true
       if (succeeded && !keepTurnAlive && agent.signal?.aborted !== true) {
         logger.info(`[channels] ${live.keyId} terminal_after_channel_reply`)
+        const replyText = (context.toolCall.arguments as { text?: unknown } | undefined)?.text
+        live.lastTerminalReplyAbort = typeof replyText === 'string' ? { turnSeq: live.turnSeq, text: replyText } : null
         agent.abort()
       }
       return result
@@ -2029,6 +2070,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           // iterations the retry itself queues do not refill the budget and loop
           // forever (and the raised cap stays scoped to the turn that set it).
           live.emptyTurnRetries = 0
+          live.willingnessNudges = 0
           live.nextPromptMaxTokens = undefined
         } else if (live.lastTurnAuthorId !== null) {
           live.currentTurnEngageReactions = []
@@ -3134,6 +3176,26 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     return { ok: true }
   }
 
+  // The turn ended via the terminal-reply abort. If that reply promised to keep
+  // working but omitted `continue: true`, queue ONE reminder-only re-prompt so
+  // the model gets a second chance to actually do it. The abort already fired
+  // (safe default preserved); this only adds an optional nudge. Bounded by
+  // MAX_WILLINGNESS_NUDGES and gated on `promptQueue` being empty so a real
+  // inbound that coalesced into this turn is never answered with a stale nudge.
+  const maybeNudgeContinuationWillingness = (live: LiveSession): void => {
+    const record = live.lastTerminalReplyAbort
+    live.lastTerminalReplyAbort = null
+    if (record === null || record.turnSeq !== live.turnSeq) return
+    if (live.willingnessNudges >= MAX_WILLINGNESS_NUDGES) return
+    if (live.promptQueue.length > 0) return
+    if (!detectContinuationWillingness(record.text)) return
+    live.willingnessNudges++
+    logger.info(
+      `[channels] ${live.keyId} willingness_nudge attempt=${live.willingnessNudges}/${MAX_WILLINGNESS_NUDGES}`,
+    )
+    live.pendingSystemReminders.push(WILLINGNESS_NUDGE)
+  }
+
   const validateChannelTurn = async (live: LiveSession, successfulSendsBeforePrompt: number): Promise<void> => {
     // `skip_response` short-circuit. Honoring it bypasses recovery entirely.
     // Stale-flag protection: only honor when stamped on the just-completed
@@ -3159,7 +3221,10 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       live.skippedTurn = null
       logger.info(`[channels] ${live.keyId} skip_contested_by_send recovering reply`)
     }
-    if (live.successfulChannelSends > successfulSendsBeforePrompt) return
+    if (live.successfulChannelSends > successfulSendsBeforePrompt) {
+      maybeNudgeContinuationWillingness(live)
+      return
+    }
 
     const postEmptyTurnFallback = async (cause: string): Promise<void> => {
       logger.warn(`[channels] ${live.keyId} empty_turn_fallback cause=${cause}`)
@@ -3204,6 +3269,23 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       // The legitimate empty-state case (a TUI-only check before any user
       // prompt, no inbound this turn) is excluded: no batch means no real turn
       // to retry or apologize for — keep the historical silent bail there.
+      const leafStopReason = assistantLeafStopReason(live.session)
+
+      // A `stopReason: 'error'` leaf is an upstream provider failure (401, billing,
+      // malformed response, etc.), NOT a reasoning-loop or budget exhaustion. It is
+      // already captured by subscribeProviderErrors into `pendingProviderError`
+      // (fired synchronously on `message_end` before `prompt()` resolves), and
+      // `maybePostDeferredProviderError` in drain()'s finally posts the REDACTED
+      // `safeMessage`. Retrying with EMPTY_TURN_RETRY_NUDGE would waste the budget
+      // nudging the model about output length when the real fault is the provider;
+      // posting EMPTY_TURN_FALLBACK_TEXT would mask the actual failure behind a
+      // misleading "I got stuck" notice. Return early so the provider-error path
+      // owns this turn's surface.
+      if (leafStopReason === 'error') {
+        logger.warn(`[channels] ${live.keyId} provider_error_turn deferring to provider-error notice`)
+        return
+      }
+
       const skipLockedThisTurn = live.skipLockedSendTurn === live.turnSeq
       const attemptedSendThisTurn = skipLockedThisTurn || live.policyDeniedToolSendsThisTurn.size > 0
 
@@ -3224,11 +3306,13 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         return
       }
 
-      // Only a TRUNCATED assistant leaf (length/error/aborted) from a real
-      // conversational turn is a degeneration worth retrying. A cold/empty turn
-      // (no inbound author, or no assistant message at all) keeps the historical
-      // silent bail — re-prompting it would manufacture replies to nothing.
-      if (live.currentTurnAuthorId === null || !assistantLeafTruncated(live.session)) {
+      // Only a TRUNCATED assistant leaf — `length` (budget exhaustion) or
+      // `aborted` (terminal-reply abort) — from a real conversational turn is a
+      // degeneration worth retrying. `error` was already diverted above to the
+      // provider-error path. A cold/empty turn (no inbound author, or no
+      // assistant message at all) keeps the historical silent bail —
+      // re-prompting it would manufacture replies to nothing.
+      if (live.currentTurnAuthorId === null || leafStopReason === undefined) {
         logger.info(`[channels] ${live.keyId}: no recoverable assistant text in branch`)
         return
       }
@@ -3236,11 +3320,11 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         live.emptyTurnRetries++
         // Raise the re-prompt's budget ONLY for a `length` truncation: that is
         // the budget-exhaustion case (reasoning ate the whole pool before any
-        // prose), so the retry needs room to finish thinking AND reply. `error`
-        // and `aborted` are not budget exhaustion — an upstream failure or the
-        // terminal-reply abort — so they retry under the default backstop.
-        // Consumed one-shot by installChannelOutputCap on the next prompt().
-        if (assistantLeafStopReason(live.session) === 'length') {
+        // prose), so the retry needs room to finish thinking AND reply. `aborted`
+        // is the terminal-reply abort, not budget exhaustion, so it retries under
+        // the default backstop. Consumed one-shot by installChannelOutputCap on
+        // the next prompt().
+        if (leafStopReason === 'length') {
           live.nextPromptMaxTokens = CHANNEL_EMPTY_TURN_RETRY_MAX_OUTPUT_TOKENS
         }
         logger.warn(
@@ -4615,15 +4699,14 @@ function recoverableAssistantText(
   return null
 }
 
-// The truncation stop reason when the leaf is an assistant message that was CUT
-// OFF mid-output — `length` (hit the token cap, the canonical kimi reasoning-
-// loop), `error`, or `aborted` — else undefined. This is the precise signature
-// of "the model was producing but got truncated", as distinct from a turn that
-// produced no assistant message at all (leaf undefined / a non-assistant
-// entry), which is a benign empty/cold turn. Callers that only need the boolean
-// use `assistantLeafTruncated`; the retry guard reads the reason itself because
-// the raised reasoning budget is justified ONLY for `length` (budget
-// exhaustion), not for `error`/`aborted`.
+// The non-terminal stop reason when the leaf is an assistant message that did
+// NOT cleanly finish — `length` (hit the token cap, the canonical kimi
+// reasoning-loop), `error` (an upstream provider failure), or `aborted` (the
+// terminal-reply abort) — else undefined. `undefined` is the signature of a
+// benign empty/cold turn (leaf undefined / a non-assistant entry). The
+// validateChannelTurn recovery path branches on the specific reason: `error`
+// diverts to the provider-error notice, `length` gets a raised retry budget,
+// `aborted` retries under the default backstop.
 function assistantLeafStopReason(session: AgentSession): 'length' | 'error' | 'aborted' | undefined {
   const leaf = session.sessionManager.getLeafEntry()
   if (!leaf || leaf.type !== 'message' || leaf.message.role !== 'assistant') return undefined
@@ -4632,10 +4715,6 @@ function assistantLeafStopReason(session: AgentSession): 'length' | 'error' | 'a
   return undefined
 }
 
-function assistantLeafTruncated(session: AgentSession): boolean {
-  return assistantLeafStopReason(session) !== undefined
-}
-
 function visibleAssistantText(message: AssistantMessage): string {
   return message.content
     .filter((block) => block.type === 'text')

package/src/cli/channel.ts

@@ -29,6 +29,7 @@ import { runLineBootstrap } from '@/init/line-auth'
 import { SecretsKakaoCredentialStore } from '@/secrets/kakao-store'
 
 import { CANCEL_SYMBOL, promptPrivateKeyPem } from './prompt-pem'
+import { displayQR } from './qr'
 import { c, done, errorLine, printDiscordInviteHint, printSlackAppManifestSetup } from './ui'
 
 const CHANNEL_LABELS: Record<ChannelKind, string> = {
@@ -66,14 +67,15 @@ const addSub = defineCommand({
 
     intro(`Adding channel: ${CHANNEL_LABELS[channel]}`)
 
-    const credentials = await collectCredentials(channel, cwd)
+    const lineSpinnerHolder: LineAuthSpinnerHolder = { current: null }
+    const credentials = await collectCredentials(channel, cwd, lineSpinnerHolder)
 
     const events: AddChannelStepEvent[] = []
     try {
       await runAddChannel({
         cwd,
         ...credentials,
-        onProgress: reportProgress(events),
+        onProgress: reportProgress(events, lineSpinnerHolder),
       })
       if (credentials.channel === 'github' && credentials.tunnelProvider === 'none') {
         log.warn(
@@ -256,10 +258,13 @@ async function runReauth(cwd: string, adapter: ReauthableAdapter): Promise<void>
 }
 
 async function runLineReauth(cwd: string): Promise<void> {
-  const login = await promptLineLogin()
+  const holder: LineAuthSpinnerHolder = { current: null }
+  const login = await promptLineLogin(holderSpinnerControl(holder))
   const s = spinner()
   s.start('Logging in to LINE...')
+  holder.current = s
   const result = await runLineBootstrap({ ...login, agentDir: cwd })
+  holder.current = null
   if (!result.ok) {
     s.stop(`LINE login failed: ${result.reason}`)
     process.exit(1)
@@ -607,7 +612,11 @@ type CollectedCredentials =
       auth: { type: 'pat'; pat: string } | { type: 'app'; appId: number; privateKey: string; installationId?: number }
     }
 
-async function collectCredentials(channel: ChannelKind, cwd: string): Promise<CollectedCredentials> {
+async function collectCredentials(
+  channel: ChannelKind,
+  cwd: string,
+  lineSpinnerHolder?: LineAuthSpinnerHolder,
+): Promise<CollectedCredentials> {
   switch (channel) {
     case 'discord-bot':
       return { channel, discordBotToken: await promptDiscordToken() }
@@ -618,7 +627,7 @@ async function collectCredentials(channel: ChannelKind, cwd: string): Promise<Co
     case 'telegram-bot':
       return { channel, telegramBotToken: await promptTelegramToken() }
     case 'line': {
-      const login = await promptLineLogin()
+      const login = await promptLineLogin(lineSpinnerHolder ? holderSpinnerControl(lineSpinnerHolder) : undefined)
       return {
         channel,
         runLineAuth: ({ cwd: agentDir }) => runLineBootstrap({ ...login, agentDir }),
@@ -1061,7 +1070,7 @@ async function promptKakaotalkCredentials(
 }
 
 type LinePromptResult =
-  | { method: 'qr'; callbacks: { onQRUrl: (url: string) => void; onPincode: (pin: string) => void } }
+  | { method: 'qr'; callbacks: { onQRUrl: (url: string) => Promise<void>; onPincode: (pin: string) => void } }
   | {
       method: 'email'
       email: string
@@ -1069,7 +1078,18 @@ type LinePromptResult =
       callbacks: { onPincode: (pin: string) => void }
     }
 
-async function promptLineLogin(): Promise<LinePromptResult> {
+// LINE's interactive logins block while the SDK waits on the phone: QR
+// long-polls for a scan, email/password waits for the user to enter a PIN. The
+// add-flow spinner ('Logging in to LINE...') keeps animating during that wait
+// and would otherwise repaint over the multi-line QR or the PIN, garbling both.
+// This control lets the QR/PIN callbacks pause the live spinner, print legibly,
+// then resume it with a "waiting for you" message so output stays readable.
+export type LineAuthSpinnerControl = {
+  pause: () => void
+  resume: (message: string) => void
+}
+
+async function promptLineLogin(spinnerControl?: LineAuthSpinnerControl): Promise<LinePromptResult> {
   note(
     [
       'LINE authentication uses a personal account registered as a sub-device.',
@@ -1094,13 +1114,17 @@ async function promptLineLogin(): Promise<LinePromptResult> {
     process.exit(0)
   }
 
-  const onPincode = (pin: string): void => log.info(`Enter this PIN in the LINE app to confirm: ${pin}`)
+  const onPincode = (pin: string): void => {
+    spinnerControl?.pause()
+    printLinePincode(pin)
+    spinnerControl?.resume('Waiting for you to confirm the PIN in the LINE app...')
+  }
 
   if (method === 'qr') {
     return {
       method: 'qr',
       callbacks: {
-        onQRUrl: (url) => note(url, 'Open this URL on your phone (or scan the QR it renders)'),
+        onQRUrl: (url) => presentLineQr(url, spinnerControl),
         onPincode,
       },
     }
@@ -1125,8 +1149,73 @@ async function promptLineLogin(): Promise<LinePromptResult> {
   return { method: 'email', email, password: pwd, callbacks: { onPincode } }
 }
 
-function reportProgress(events: AddChannelStepEvent[]): (event: AddChannelStepEvent) => void {
-  const spinners: Partial<Record<AddChannelStepEvent['step'], ReturnType<typeof spinner>>> = {}
+async function presentLineQr(url: string, spinnerControl?: LineAuthSpinnerControl): Promise<void> {
+  spinnerControl?.pause()
+  const presentation = await displayQR(url, {
+    title: 'LINE login',
+    scanInstruction: 'Scan with the LINE app on your phone',
+  })
+
+  const lines: string[] = []
+  if (presentation.terminal !== null) {
+    lines.push(presentation.terminal)
+    lines.push('Scan the QR code above with the LINE app on your phone.')
+    lines.push('If it is too small to scan, enlarge the terminal (or zoom out) and re-run.')
+    if (presentation.opened) {
+      lines.push('A browser window with a larger QR code was also opened.')
+    }
+  } else if (presentation.opened) {
+    lines.push('A browser window with the QR code was opened. Scan it with the LINE app on your phone.')
+  } else if (presentation.htmlPath !== null) {
+    lines.push(`Open this file in a browser and scan it with the LINE app: ${presentation.htmlPath}`)
+  }
+  if (lines.length > 0) note(lines.join('\n'), 'Scan to log in to LINE')
+
+  if (presentation.terminal === null && !presentation.opened && presentation.htmlPath === null) {
+    printLineQrUrl(url)
+  }
+
+  spinnerControl?.resume('Waiting for you to scan the QR code with the LINE app...')
+}
+
+// Last-resort fallback when no QR could be rendered. The raw URL stays OUT of
+// note(): clack wraps long lines with a `│` gutter that corrupts the login URL
+// (it carries `?secret=...&e2eeVersion=...`). Same constraint as
+// src/cli/oauth-callbacks.ts.
+export function printLineQrUrl(url: string, output: NodeJS.WritableStream = process.stdout): void {
+  note('Open this URL on a device that can render it as a QR code:', 'Log in to LINE')
+  output.write(`${url}\n\n`)
+}
+
+// PIN stays OUT of the note() gutter (same `│`-splitting reason as
+// printLineQrUrl) and must stand out: the SDK blocks on phone confirmation and
+// throws if its window lapses, so a PIN scrolled past unnoticed leaves nothing
+// in secrets.json — the root cause of the runtime "No account found" error. The
+// "waiting" line is emitted by the resumed spinner, not here.
+export function printLinePincode(pin: string, output: NodeJS.WritableStream = process.stdout): void {
+  note('Open the LINE app on your phone and enter this PIN to authorize this device:', 'Confirm LINE login')
+  output.write(`\n  PIN: ${pin}\n\n`)
+}
+
+type Spinner = ReturnType<typeof spinner>
+
+// `current` is the live `line-auth` spinner, shared between `reportProgress`
+// (which owns its lifecycle) and the QR/PIN callbacks (which must pause it to
+// print legibly). It is null whenever no LINE login spinner is active.
+export type LineAuthSpinnerHolder = { current: Spinner | null }
+
+export function holderSpinnerControl(holder: LineAuthSpinnerHolder): LineAuthSpinnerControl {
+  return {
+    pause: () => holder.current?.stop(),
+    resume: (message) => holder.current?.start(message),
+  }
+}
+
+function reportProgress(
+  events: AddChannelStepEvent[],
+  lineSpinnerHolder?: LineAuthSpinnerHolder,
+): (event: AddChannelStepEvent) => void {
+  const spinners: Partial<Record<AddChannelStepEvent['step'], Spinner>> = {}
 
   return (event) => {
     events.push(event)
@@ -1134,6 +1223,7 @@ function reportProgress(events: AddChannelStepEvent[]): (event: AddChannelStepEv
       const s = spinner()
       s.start(START_MESSAGES[event.step])
       spinners[event.step] = s
+      if (event.step === 'line-auth' && lineSpinnerHolder) lineSpinnerHolder.current = s
       return
     }
 
@@ -1142,6 +1232,7 @@ function reportProgress(events: AddChannelStepEvent[]): (event: AddChannelStepEv
 
     switch (event.step) {
       case 'line-auth':
+        if (lineSpinnerHolder) lineSpinnerHolder.current = null
         s.stop(reportLineAuth(event.result))
         break
       case 'kakaotalk-auth':

package/src/cli/qr.ts

@@ -0,0 +1,130 @@
+import { execFile } from 'node:child_process'
+import { writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { promisify } from 'node:util'
+
+import QRCode from 'qrcode'
+
+const execFileAsync = promisify(execFile)
+
+// The upstream LINE SDK's QR login hands back a raw auth URL
+// (https://line.me/R/au/q/...), which is not scannable on its own — the LINE
+// mobile app needs an actual QR image. This module renders that URL the way the
+// upstream `agent-line` CLI does: an HTML page opened in the browser plus, on a
+// TTY, an inline ASCII QR. Every external effect is best-effort so a non-TTY or
+// browserless host degrades to a machine-readable scan payload rather than
+// blocking login.
+
+export type QRPresentation = {
+  qrUrl: string
+  htmlPath: string | null
+  terminal: string | null
+  opened: boolean
+}
+
+export type DisplayQROptions = {
+  title: string
+  scanInstruction: string
+  brandColor?: string
+  isTty?: boolean
+  opener?: (filePath: string) => Promise<void>
+  tmpDir?: string
+  now?: () => number
+}
+
+export async function buildQRHtml(
+  url: string,
+  options: { title: string; scanInstruction: string; brandColor: string },
+): Promise<string> {
+  const svg = await QRCode.toString(url, { type: 'svg', margin: 2 })
+  const title = escapeHtml(options.title)
+  const instruction = escapeHtml(options.scanInstruction)
+  return `<!DOCTYPE html>
+<html><head><meta charset="utf-8"><title>${title}</title>
+<style>body{display:flex;flex-direction:column;align-items:center;justify-content:center;min-height:100vh;margin:0;font-family:-apple-system,system-ui,sans-serif;background:${options.brandColor}}
+.card{background:#fff;border-radius:16px;padding:40px;text-align:center;box-shadow:0 4px 24px rgba(0,0,0,.15)}
+h1{margin:0 0 8px;font-size:22px;color:#111}p{margin:0 0 24px;color:#666;font-size:14px}
+svg{width:280px;height:280px}</style></head>
+<body><div class="card"><h1>${title}</h1><p>${instruction}</p>${svg}</div></body></html>`
+}
+
+export async function renderTerminalQR(url: string): Promise<string> {
+  // 'L' error correction yields the fewest modules, so the QR stays small
+  // enough to scan from a terminal over SSH where screen real estate is the
+  // binding constraint. A short-lived auth URL doesn't need higher ECC.
+  return QRCode.toString(url, { type: 'terminal', small: true, errorCorrectionLevel: 'L' })
+}
+
+// Writes the QR HTML to a temp file and tries to open it in the default
+// browser, and (when on a TTY) renders an inline ASCII QR. Every external
+// effect is best-effort: a failure to write, open, or render degrades the
+// result rather than throwing, so login is never blocked by presentation.
+export async function displayQR(url: string, options: DisplayQROptions): Promise<QRPresentation> {
+  const brandColor = options.brandColor ?? '#06C755'
+  const isTty = options.isTty ?? process.stderr.isTTY === true
+  const now = options.now ?? Date.now
+  const dir = options.tmpDir ?? tmpdir()
+
+  const htmlPath = await writeQRHtmlFile(url, {
+    title: options.title,
+    scanInstruction: options.scanInstruction,
+    brandColor,
+    dir,
+    stamp: now(),
+  })
+
+  let opened = false
+  if (htmlPath !== null) {
+    const open = options.opener ?? openInBrowser
+    opened = await open(htmlPath).then(
+      () => true,
+      () => false,
+    )
+  }
+
+  const terminal = isTty ? await renderTerminalQR(url).catch(() => null) : null
+
+  return { qrUrl: url, htmlPath, terminal, opened }
+}
+
+async function writeQRHtmlFile(
+  url: string,
+  options: { title: string; scanInstruction: string; brandColor: string; dir: string; stamp: number },
+): Promise<string | null> {
+  try {
+    const html = await buildQRHtml(url, options)
+    const slug =
+      options.title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'qr'
+    const htmlPath = join(options.dir, `typeclaw-${slug}-${options.stamp}.html`)
+    await writeFile(htmlPath, html, { mode: 0o600 })
+    return htmlPath
+  } catch {
+    return null
+  }
+}
+
+async function openInBrowser(filePath: string): Promise<void> {
+  const platform = process.platform
+  if (platform === 'darwin') {
+    await execFileAsync('open', [filePath])
+    return
+  }
+  if (platform === 'win32') {
+    await execFileAsync('cmd', ['/c', 'start', '', filePath])
+    return
+  }
+  await execFileAsync('xdg-open', [filePath])
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}