Skip to content

feat(briefing): the briefing page shows how the run went — MCP server status, every tool call, hooks, command and prompt; new "extra allowed tools" setting - #87

Merged
LiminCode merged 1 commit into
mainfrom
briefing-run-trace
Nov 20, 2026
Merged

LiminCode merged 1 commit into
mainfrom
briefing-run-trace

Conversation

@LiminCode

Copy link
Copy Markdown
Owner

Summary

The work briefing was a black box: after a run only the text remained, so tonight's "Jira unreadable" took an hour to diagnose although the headless run had printed every MCP server's status. Now every attempt leaves a run record and the briefing page shows it under the text as collapsible sections ("How this run went"): the chain (fish → WSL → Claude Code version · model · permission mode · turns), a table of the MCP servers that matter (allowed by the briefing's tool list or actually called) with status and call count — a server that needs login gets the exact claude mcp login "<name>" line —, how many allow-list entries actually exist in that session, every tool call with a short argument line and ✓/✗, the account's own hooks that ran, the full command and the prompt exactly as sent (with a link to the panorama settings group to edit the template). A failed attempt keeps its record too. One new setting, Extra allowed tools (one name or mcp__server__* prefix per line), lets the user allow a renamed or additional connector without a code change. Design memo: .scratch/config-panorama/briefing-trace-design.md (local).

What changed and why

  • pet/work_briefing.py: claude_command now uses --output-format stream-json --verbose (the init event carries the MCP server list and tool names; each tool call is an event; the last line is still the result, so _result_record and the notes feature that shares this command are unchanged). New parse_trace(stdout, allowed, denied) folds the stream into {version, model, permission_mode, servers[{name, status, source, calls, allowed}], others, tools, calls[{n, tool, args, ok}], hooks, denied, denied_rules}; server_slug reproduces Claude Code's mcp__<server>__ naming; _args_summary caps each value at 80 and the line at 200 chars. generate() adds command, gh_command, prompt, allowed. Briefing.trace is a new field; record() stores it once under the state file's trace key on every attempt (failed ones included, with at/ok/turns/seconds) and strips it from the stored briefing; last_trace() reads it back. normalize_tools + extra_allowed_tools in normalize; allowed_tools(sources, extra).
  • pet/work_briefing_service.py: passes extra_tools to generate; last_trace().
  • pet/panorama/reports.py: trace_sections(trace) renders the sections server-side (everything escaped; only p / table / ol / code / pre / a); the provider adds details and settings_focus; SETTINGS_URL placeholder for the "edit template" link.
  • pet/panorama/page/report.html|js|css: <section id="details">; the page draws <details> blocks (first one open) and swaps the placeholder for /#<token>&settings=<group> on the same server; Metro styling with the shared tokens.
  • pet/settings_table.py: work_briefing.extra_allowed_tools (lines, advanced). Gate: a preference, low-frequency, default empty, unique home, the product cannot infer what the account has installed; bad lines are dropped by normalize_tools, so the write path reports rejected instead of silently storing less.
  • pet/locale/zh.json, en.json: briefing.settings.extra_tools*, briefing.trace.*.
  • Docs: docs/work-assistant.md (command line, "运行记录" section, extra tools), docs/config-panorama.md (report payload fields), CHANGELOG.md.
  • Tests: tests/test_work_briefing_trace.py (new, 9: stream → trace, call outcomes, prefix/whole-server rules, old single-line output, generate fills, record/last_trace, normalize_tools, allow-list order, service hand-off); test_panorama_reports.py (+2: sections and escaping, failed run / no record); test_panorama_report_page.py (+1: sections and the settings link under QJSEngine); test_settings_write_path.py (+1); updated expectations in test_work_briefing.py, test_settings_table.py, test_panorama_settings_routes.py.

Performance

PYTHONPATH on the worktree, venv Python, this machine (Windows 11):

Path Result
parse_trace on tonight's real headless init stream (31,272 chars, 32 servers, 145 tools), 200 runs median 0.46 ms, max 1.09 ms
parse_trace on init + 300 synthetic tool calls with 4 KB results (1,285 KB), 50 runs median 2.98 ms, max 4.10 ms
trace_sections for the real run (14 calls), 200 runs median 0.04 ms
trace_sections for 300 calls, 200 runs median 0.19 ms, max 0.64 ms
Real run's record in the state file 23,453 B of JSON (state file 39,925 B total); page payload with the sections 20,458 B
Assets report.js 4,927 B (was 4,132), report.css 4,553 B (was 3,132)
  • Steady state: zero. Parsing happens once per generation on the worker thread that already waited ~90 s for claude -p; the sections are built only when a page asks for the report (same trigger as before).
  • New cost on the existing path: the headless run now streams every event through the same pipe; the stdout for the real run was about 0.4 MB instead of one line. No new threads, no new processes, no network beyond what the briefing already does; one extra JSON key written in the same atomic state-file write.
  • Memory: the trace lives in the state file and in the Feed's latest payload (~20 KB).

Real-machine run

  1. Real generation with the worktree code (gen_trace.py: wb.generate() with the real WSL login shell, the company account's connectors, model sonnet, effort medium, output to a scratch directory, not the pet's data dir): ok=True, 91.9 s, 15 turns, $0.49. Record: Claude Code 2.1.329 · claude-sonnet-5-5 · permission mode auto; servers claude.ai Slack connected (2 calls), claude.ai Google Calendar connected (1), claude.ai Atlassian connected (11 — the user had logged the connector in earlier tonight); 29 other servers counted; 15 of the 38 allow-list entries actually existed; 14 tool calls, all ✓; hooks SessionStart:startup; prompt 4,607 chars, command 5,715 chars; the stored briefing has no trace key.
  2. Page: served that directory with a standalone read-only PanoramaServer and opened /report/work_briefing#<token> in the built-in browser. Read from the DOM: theme light, hash cleared, five sections with the expected titles, first one open, the chain line, three server rows with st connected / 已连接 / 这次调了 N 次, the two notes (29 unrelated servers; 38 allowed / 15 present), 14 <li> with 14 ✓ and 0 ✗, hooks line, the settings link http://127.0.0.1:<port>/#<token>&settings=work_briefing, <pre> lengths 5,969 (commands) and 4,610 (prompt). Screenshots were taken for inspection only; the content is company material and is not attached.
  3. The pet will be restarted from main after the merge; the live page shows the record from the next generation on (older briefings have none and the page shows nothing extra).

Tests

Red first: tests/test_work_briefing_trace.py failed on AttributeError: parse_trace / normalize_tools / last_trace and the --output-format assertion before the product change. Affected families (work briefing, work notes, Slack, prompt editing, memory distill, panorama, settings, i18n, architecture, docs discipline, briefing metro, personal): 1186 passed + the two failures fixed afterwards (an i18n key with a hyphen, the settings-route count 14 → 15); after the fixes the touched files pass (168 + 48). ruff check pet tests and git diff --check clean. Full suite not run: no config migration, no lifecycle or threading change (one more kwarg on the existing worker call and one extra key in the same state-file write), no packaging/platform dispatch change.

Docs

  • CHANGELOG.md: one line (user-visible change)
  • Topic doc under docs/ updated (work-assistant.md, config-panorama.md)
  • ADR: not needed (no new feature domain or boundary; the report page and its one-edit-place rule are ADR 0014 / 0018)

🤖 Generated with Claude Code

…额外放行的工具」

- work_briefing:claude -p 改用 --output-format stream-json --verbose;parse_trace 从事件流整理运行记录(init 的服务器
  清单 / 工具清单、tool_use + tool_result、hook_started、permission_denials),generate 再填命令 / gh 命令 / 提示词 / 放行名单;
  record 把记录单独存在状态文件的 trace 键下(每次尝试都换,失败的也留),last_trace 读回;结果行解析不变(笔记共用那行命令)
- normalize 新增 extra_allowed_tools(normalize_tools:只认 mcp__ 开头、* 只在末尾),allowed_tools / claude_command 接 extra;
  service 把它传给 generate,并有 last_trace()
- reports.trace_sections:几段 {title, html}(链路、服务器表、调用时间线、hooks、命令、提示词 + 到设置里改的占位链接);
  provider 多给 details / settings_focus;report.html/js/css:折叠块,第一段默认展开,占位换成带令牌的配置全景地址
- settings_table:work_briefing 组多一行 lines 控件;字表 zh / en;docs/work-assistant「运行记录」一节、config-panorama 报告页字段、
  CHANGELOG

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@LiminCode
LiminCode merged commit 2ab2b1b into main Nov 20, 2026
0 of 3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant