agentquad 0.3.0

package/src/ask-user-buttons.js

@@ -0,0 +1,142 @@
+/**
+ * ask_user 推送的 inline keyboard 拼装 + callback 路由解析。
+ *
+ * Telegram 的 callback_data 上限是 64 字节（含），所以编码必须紧凑：
+ *   qt:ans:<ticket>:<idx>   ← 用户点选项
+ *   qt:ext:<ticket>:<idx>   ← 用户点 ✏️ 补充
+ *
+ * ticket 是 3 字符 base32（pending-questions.js 生成），idx 是 0-7 单字符 → 总长 ≤ 16 字节，安全。
+ *
+ * 布局策略：
+ *   - 选项数 ≤ 4 且每条选项文本长度（含 emoji 计 1）≤ 8 → 2 列
+ *   - 否则 1 列
+ *   - 每个选项下面单独一行 ✏️ 补充按钮（行内空间留给主选项）
+ */
+
+export const CB_PREFIX = 'qt'
+export const CB_KIND_ANSWER = 'ans'
+export const CB_KIND_EXTEND = 'ext'
+
+const SHORT_TEXT_THRESHOLD = 8     // 用 ≤8 字符判断"短"
+const TWO_COL_MAX_OPTIONS = 4      // 超过 4 个选项强制单列（视觉太挤）
+
+/**
+ * 截断按钮文字。Telegram 按钮文本最大 64 字节，超过会发不出去。
+ * 我们更激进地砍到 24，保持可读 + 不撑屏。
+ */
+function truncateLabel(s, max = 24) {
+  const t = String(s || '').replace(/\s+/g, ' ').trim()
+  if (t.length <= max) return t
+  return t.slice(0, max - 1) + '…'
+}
+
+/**
+ * 用 [...str] 算"显示宽度"（Unicode code points），保证中文字符也按 1 计。
+ * 不区分东亚宽度，只为粗略判断"按钮文字短/长"。
+ */
+function displayWidth(s) {
+  return [...String(s || '')].length
+}
+
+/**
+ * 构造 ask_user 的 inline keyboard。
+ *
+ * 入参：
+ *   - ticket: 3 字符 ticket
+ *   - options: 选项字符串数组（≥ 2，建议 ≤ 8）
+ *
+ * 返回：{ inline_keyboard: Button[][] }，可直接作为 reply_markup 传 sendMessage。
+ *
+ * 行布局：
+ *   - 选项行：每行 1 个按钮（长选项）或 2 个按钮（短选项 + 选项数 ≤ 4）
+ *   - 紧跟在选项行后面会跟一个"✏️" 按钮行（独占）
+ *   注意：每个选项独立配一个 ✏️，让用户可以在选完之后单独补充。
+ *   为了不让按钮翻倍变成"主+辅"竖排太长，✏️ 跟主按钮放同一行最右（如果主按钮也独占行）。
+ *
+ * 实际版本：选用 "选项 + ✏️ 共占一行" 布局，让总行数等于选项数 —— 视觉最紧凑。
+ */
+export function buildAskUserReplyMarkup(ticket, options) {
+  if (!ticket || typeof ticket !== 'string') {
+    throw new Error('ticket required')
+  }
+  if (!Array.isArray(options) || options.length === 0) {
+    throw new Error('options required')
+  }
+
+  const allShort = options.every((o) => displayWidth(o) <= SHORT_TEXT_THRESHOLD)
+  const useTwoCol = allShort && options.length <= TWO_COL_MAX_OPTIONS && options.length > 1
+
+  const rows = []
+  if (useTwoCol) {
+    // 2 列：每行 [opt_i, ✏️_i, opt_{i+1}, ✏️_{i+1}] —— 4 列太挤，所以
+    // 折中：选项一行（2 个），✏️ 一行（2 个），用前缀 ✏️ 1./2. 标识对应关系
+    for (let i = 0; i < options.length; i += 2) {
+      const optRow = [
+        { text: truncateLabel(`${i + 1}. ${options[i]}`), callback_data: `${CB_PREFIX}:${CB_KIND_ANSWER}:${ticket}:${i}` },
+      ]
+      if (i + 1 < options.length) {
+        optRow.push({ text: truncateLabel(`${i + 2}. ${options[i + 1]}`), callback_data: `${CB_PREFIX}:${CB_KIND_ANSWER}:${ticket}:${i + 1}` })
+      }
+      rows.push(optRow)
+      const extRow = [
+        { text: `✏️ 补充${i + 1}`, callback_data: `${CB_PREFIX}:${CB_KIND_EXTEND}:${ticket}:${i}` },
+      ]
+      if (i + 1 < options.length) {
+        extRow.push({ text: `✏️ 补充${i + 2}`, callback_data: `${CB_PREFIX}:${CB_KIND_EXTEND}:${ticket}:${i + 1}` })
+      }
+      rows.push(extRow)
+    }
+  } else {
+    // 1 列：每行 [opt_i, ✏️] —— 主按钮独占主体，✏️ 缩成右侧小按钮
+    for (let i = 0; i < options.length; i++) {
+      rows.push([
+        { text: truncateLabel(`${i + 1}. ${options[i]}`), callback_data: `${CB_PREFIX}:${CB_KIND_ANSWER}:${ticket}:${i}` },
+        { text: '✏️', callback_data: `${CB_PREFIX}:${CB_KIND_EXTEND}:${ticket}:${i}` },
+      ])
+    }
+  }
+
+  return { inline_keyboard: rows }
+}
+
+/**
+ * 解析 callback_data。
+ * 返回 { kind, ticket, idx } 或 null（不是 AgentQuad 的 callback）。
+ *
+ * 对未知 prefix（包括老的 qt:wd / qt:q / qt:t wizard prefix）返回 null —— caller 决定 fallback。
+ */
+export function parseCallbackData(data) {
+  const s = String(data || '')
+  if (!s.startsWith(`${CB_PREFIX}:`)) return null
+  const parts = s.split(':')
+  if (parts.length !== 4) return null
+  const [, kind, ticket, idxStr] = parts
+  if (kind !== CB_KIND_ANSWER && kind !== CB_KIND_EXTEND) return null
+  if (!ticket || ticket.length < 1) return null
+  const idx = parseInt(idxStr, 10)
+  if (!Number.isInteger(idx) || idx < 0 || idx > 99) return null
+  return { kind, ticket, idx }
+}
+
+/**
+ * 选项数字回填给 pending.submitReply 的纯文本（"1" / "2"…）
+ * 老路径完全兼容（pending-questions.parseReply 的"1..N"分支）。
+ */
+export function buildAnswerReplyText(idx) {
+  return String(idx + 1)
+}
+
+/**
+ * 拼"选项 + 用户补充"的最终 answerText（透传给 AI）。
+ * 例：选项是 "北京时间"，用户补 "用 +0800 不要 +08:00" → "北京时间 · 用 +0800 不要 +08:00"
+ *
+ * 用 ` · ` 分隔（中圆点）—— 视觉清晰，AI 上下文也能看出主+附结构。
+ */
+export function buildExtendedReplyText(optionLabel, extra) {
+  const opt = String(optionLabel || '').trim()
+  const ex = String(extra || '').trim()
+  if (!opt && !ex) return ''
+  if (!ex) return opt
+  if (!opt) return ex
+  return `${opt} · ${ex}`
+}

package/src/claude-transcript.js

@@ -0,0 +1,203 @@
+/**
+ * Claude Code 会话日志解析器：把 ~/.claude/projects/<encoded>/<uuid>.jsonl 解析成
+ * 干净的可读文本。
+ *
+ * 用途：
+ *   - readLatestAssistantTurn(jsonlPath) → AI 最近一轮的完整文本（用于 Stop hook 推送）
+ *   - buildFullTranscript(jsonlPath) → 整段对话 markdown（用于 SessionEnd 附件）
+ *
+ * jsonl 格式（v2.1.x）：
+ *   每行一个 JSON 对象，type ∈ {user, assistant, queue-operation, ...}
+ *   message.role: user / assistant
+ *   message.content:
+ *     - string（user 偶尔）
+ *     - array of:
+ *         {type: 'text', text: '...'}
+ *         {type: 'tool_use', name: 'Bash', input: {...}, id: '...'}
+ *         {type: 'tool_result', tool_use_id: '...', content: '...' or array}
+ *
+ * 设计：
+ *   - 读全文件（v1 假设 < 5MB；后续超大可改成 readline 流式）
+ *   - 跳过 meta / queue / system 行
+ *   - 工具调用用简短摘要（"🔧 Bash: ls /tmp"）替代完整 input
+ *   - 工具结果默认折叠（前 200 字 + "(N more chars)"）
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { normalizeContent, blockToText } from './transcripts/blocks.js'
+
+const MAX_FILE_BYTES = 10 * 1024 * 1024  // 10MB 上限保护
+
+export function readJsonlLines(path) {
+  if (!existsSync(path)) return []
+  const stat = existsSync(path) ? readFileSync(path) : null
+  if (!stat) return []
+  if (stat.length > MAX_FILE_BYTES) {
+    // 超大文件只读末尾 5MB
+    const buf = stat.subarray(stat.length - 5 * 1024 * 1024)
+    return buf.toString('utf8').split('\n')
+  }
+  return stat.toString('utf8').split('\n')
+}
+
+function parseJsonlLine(line) {
+  if (!line) return null
+  const trimmed = line.trim()
+  if (!trimmed || !trimmed.startsWith('{')) return null
+  try { return JSON.parse(trimmed) } catch { return null }
+}
+
+/**
+ * 取最后一条 assistant 消息的完整文本。
+ * 返回 { text, hasToolUse, timestamp, raw } 或 null。
+ */
+export function readLatestAssistantTurn(jsonlPath) {
+  const lines = readJsonlLines(jsonlPath)
+  if (lines.length === 0) return null
+
+  // 反向找最近的 assistant
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const obj = parseJsonlLine(lines[i])
+    if (!obj) continue
+    if (obj.type !== 'assistant') continue
+    const content = normalizeContent(obj.message?.content)
+    if (content.length === 0) continue
+
+    const parts = []
+    let hasToolUse = false
+    for (const block of content) {
+      if (block?.type === 'tool_use') hasToolUse = true
+      const piece = blockToText(block)
+      if (piece) parts.push(piece)
+    }
+    const text = parts.join('\n\n').trim()
+    if (!text) continue
+    return {
+      text,
+      hasToolUse,
+      timestamp: obj.timestamp || null,
+      raw: obj,
+    }
+  }
+  return null
+}
+
+/**
+ * 取最后一条 assistant 消息的 stop_reason（'end_turn' / 'tool_use' / 'max_tokens' / null）。
+ *
+ * 用途：Stop hook 校验门。Claude 自家的 Stop hook 在中间停顿、子代理、内部 transition 等场景下
+ * 也会 fire，但只有 stop_reason === 'end_turn' 才是"真的本轮结束"。openclaw-hook.js 用这个
+ * 函数判断要不要把会话状态翻成 idle。
+ *
+ * 读不到文件或解析失败时返回 null，调用方应把 null 视作"不可判定"（一般兜底为 true 不阻塞）。
+ */
+export function readLatestAssistantStopReason(jsonlPath) {
+  const lines = readJsonlLines(jsonlPath)
+  if (lines.length === 0) return null
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const obj = parseJsonlLine(lines[i])
+    if (!obj) continue
+    if (obj.type !== 'assistant') continue
+    if (obj.isMeta || obj.isSidechain) continue
+    const sr = obj.message?.stop_reason
+    return typeof sr === 'string' ? sr : null
+  }
+  return null
+}
+
+/**
+ * 取最后一条 user 消息的时间戳（不含 isMeta / sidechain）。
+ * 用于 Stop hook 识别 "AI 是否已经回应到最新 user 输入"。
+ */
+export function readLatestUserTimestamp(jsonlPath) {
+  const lines = readJsonlLines(jsonlPath)
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const obj = parseJsonlLine(lines[i])
+    if (!obj) continue
+    if (obj.type !== 'user') continue
+    if (obj.isMeta || obj.isSidechain) continue
+    if (obj.timestamp) return obj.timestamp
+  }
+  return null
+}
+
+/**
+ * 拿"针对最新 user 输入的 assistant 回应"。
+ *
+ * 解决的问题：Stop hook 触发瞬间，Claude Code 可能还没写完 jsonl，导致
+ * readLatestAssistantTurn 拿到上一轮的内容（用户感觉"每条回复都是上一次的"）。
+ *
+ * 策略：retry 等待，直到 latest assistant.timestamp > latest user.timestamp。
+ * 默认 retry 5 次 × 250ms = 1.25s 上限。
+ */
+export async function readLatestAssistantTurnFresh(jsonlPath, opts = {}) {
+  const maxRetries = opts.maxRetries ?? 5
+  const delayMs = opts.delayMs ?? 250
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const userTs = readLatestUserTimestamp(jsonlPath)
+    const turn = readLatestAssistantTurn(jsonlPath)
+    if (!turn) {
+      // 没 assistant 消息 → 只能等
+      if (attempt === maxRetries) return null
+    } else if (!userTs || !turn.timestamp || turn.timestamp > userTs) {
+      // assistant 在 user 之后（已回应 latest input）—— 干净，返回
+      return { ...turn, fresh: true, attempts: attempt }
+    } else {
+      // assistant 在 user 之前 —— stale，等等再读
+      if (attempt === maxRetries) {
+        // 仍然 stale → 返回 stale 数据让上游决定
+        return { ...turn, fresh: false, attempts: attempt }
+      }
+    }
+    await new Promise((r) => setTimeout(r, delayMs))
+  }
+  return null
+}
+
+/**
+ * 整段对话渲染成 markdown。供 SessionEnd 附件用。
+ * 返回 { markdown, turnCount }。
+ */
+export function buildFullTranscript(jsonlPath, opts = {}) {
+  const lines = readJsonlLines(jsonlPath)
+  if (lines.length === 0) return { markdown: '', turnCount: 0 }
+
+  const out = []
+  let turnCount = 0
+
+  for (const line of lines) {
+    const obj = parseJsonlLine(line)
+    if (!obj) continue
+    if (obj.type !== 'user' && obj.type !== 'assistant') continue
+    if (obj.isMeta) continue   // 跳过 meta（local-command-caveat 等）
+    if (obj.isSidechain) continue
+
+    const role = obj.message?.role || obj.type
+    const content = normalizeContent(obj.message?.content)
+    if (content.length === 0) continue
+
+    const parts = []
+    for (const block of content) {
+      const piece = blockToText(block, { includeToolResult: true, toolResultMaxChars: opts.toolResultMaxChars || 1000 })
+      if (piece) parts.push(piece)
+    }
+    const text = parts.join('\n\n').trim()
+    if (!text) continue
+
+    const ts = obj.timestamp ? new Date(obj.timestamp).toISOString().slice(0, 19).replace('T', ' ') : ''
+    if (role === 'user') {
+      out.push(`### 👤 User${ts ? ` _${ts}_` : ''}\n\n${text}\n`)
+    } else {
+      out.push(`### 🤖 Assistant${ts ? ` _${ts}_` : ''}\n\n${text}\n`)
+    }
+    turnCount++
+  }
+
+  if (turnCount === 0) return { markdown: '', turnCount: 0 }
+  const header = `# Claude Code Session Transcript\n\n_Generated: ${new Date().toISOString()}_\n_Source: ${jsonlPath}_\n_Turns: ${turnCount}_\n\n---\n\n`
+  return {
+    markdown: header + out.join('\n'),
+    turnCount,
+  }
+}
+
+export const __test__ = { normalizeContent, blockToText, parseJsonlLine }