feat(agent): observable agent execution + durable runs

[1012839419a-alt]

Summary

• observable agent execution: chat API now streams structured agent-run progress events; the global agent dock renders live run state, and the Operations/Agents page surfaces run activity
• durable agent runs: interactive agent runs are persisted (new AgentRun / AgentRunEvent / AgentSession models + alembic migration), so runs survive API restarts and can be replayed/queried
• documented in openspec/changes/agent-execution-experience/ (brief / design / motion / qa / tasks)

Origin

This is T2 split out of draft PR #61 (7 commits → 4 independent themes). T2 = cde5ff8 (observable agent execution) + 80fb22d (persist interactive agent runs), cherry-picked onto current main (7838811, #60) with zero conflicts; T1 (local admin onboarding) was already split into #68 and is NOT included here.

Verification

• pytest: 50 passed (code-intel pipeline-selected candidates: chat API, identity models, and related suites)
• ruff: no net-new lint debt vs main baseline (27 remaining = all pre-existing; the only T2-introduced E501 was fixed)
• code-intel change risk (T2 scope): level=medium, 67th percentile, 11 files +674/-16 — testAsymmetry 0 (no dedicated tests for the new run-persistence code; covered indirectly via chat API tests). Additional unit coverage for AgentRun persistence is a follow-up.

Notes

• alembic migration a8b9c0d1e2f3 down_revision was rewired from T1's local-admin migration (z7a8b9c0d1e2) to the actual predecessor on main (k8l9m0n1o2p3), so the migration chain is self-contained without T1.
• T3 (dev toolchain) and T4 (fixed API image) remain in Add first-run local administrator onboarding #61.

[coderabbitai]

Warning

Review limit reached

@1012839419a-alt, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 35 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 608c7d0e-15c9-4f1c-99b6-3476599076ac

📥 Commits

Reviewing files that changed from the base of the PR and between 94ab53d and 5b20d32.

📒 Files selected for processing (11)

• backend/api/v1/chat.py
• backend/migrations/versions/a8b9c0d1e2f3_add_durable_agent_runs.py
• backend/models/__init__.py
• backend/models/agent_run.py
• frontend/app/(app)/operations-agents/page.tsx
• frontend/components/shell/global-agent-dock.tsx
• openspec/changes/agent-execution-experience/brief.md
• openspec/changes/agent-execution-experience/design.md
• openspec/changes/agent-execution-experience/motion.md
• openspec/changes/agent-execution-experience/qa.md
• openspec/changes/agent-execution-experience/tasks.md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[repowise-bot]

⚠️ Health of changed files: 6.4 → 5.7 (-0.6)
_{🚨 Change risk: high, riskier than 78% of this repo's commits.}

📋 At a glance
2 files changed health · 4 hotspots touched · 6 new findings introduced · 1 co-change pair left out · 1 file with recent fix history · 1 dead-code finding · no tests touched.

Files & modules (2)

• backend (2 files)
  • .../v1/chat.py
  • backend/models/__init__.py
• frontend (2 files)
  • .../shell/global-agent-dock.tsx
  • .../operations-agents/page.tsx

✅ Health gate: passed

📌 Before you merge

• Run tests/integration/test_chat_api.py, tests/skills/test_loop.py, .../llm/test_pr_e_consumers.py, tests/integration/test_image_studio_api.py (+1 more): they import the changed files
• .../v1/__init__.py changed together with backend/models/__init__.py in 14 past commits and isn't in this PR

🔎 More signals (4)

🗺️ Change map

flowchart LR
  subgraph PR ["Changed in this PR (3 with dependents)"]
    f_backend_api_v1_chat_py[".../v1/chat.py 🔥"]:::changed
    f_backend_models___init___py["backend/models/__init__.py 🔥"]:::changed
    f_frontend_components_shell_global_agent_dock_tsx[".../shell/global-agent-dock.tsx 🔥"]:::changed
  end
  f_backend_api_v1___init___py[".../v1/__init__.py"]
  f_backend_api_v1_chat_py --> f_backend_api_v1___init___py
  f_backend_models___init___py --> f_backend_api_v1___init___py
  f_backend_api_v1_workflows_py[".../v1/workflows.py"]
  f_backend_models___init___py --> f_backend_api_v1_workflows_py
  f_backend_channels_opencli_channel_py["backend/channels/opencli_channel.py"]
  f_backend_models___init___py --> f_backend_channels_opencli_channel_py
  f_backend_config_py["backend/config.py"]
  f_backend_models___init___py --> f_backend_config_py
  f_frontend_components_shell_app_shell_tsx[".../shell/app-shell.tsx"]
  f_frontend_components_shell_global_agent_dock_tsx --> f_frontend_components_shell_app_shell_tsx
  more(["+1 more dependent"])
  PR --> more
  w_backend_api_v1___init___py(["⚠️ .../v1/__init__.py changed together 14×, not in PR"]):::warn
  f_backend_models___init___py -.- w_backend_api_v1___init___py
  t_tests_integration_test_chat_api_py(["✅ tests/integration/test_chat_api.py"]):::guard
  t_tests_integration_test_chat_api_py -.-> f_backend_api_v1_chat_py
  t_tests_integration_test_image_studio_api_py(["✅ tests/integration/test_image_studio_api.py"]):::guard
  t_tests_integration_test_image_studio_api_py -.-> f_backend_models___init___py
  classDef changed fill:#dbeafe,stroke:#1d4ed8,color:#1e3a5f
  classDef warn fill:#fef3c7,stroke:#b45309,color:#78350f
  classDef guard fill:#dcfce7,stroke:#15803d,color:#14532d

Loading

_{Solid arrows: code that imports the changed files (6 direct dependents, from the last indexed snapshot). Dashed: history/tests.}

🔥 Hotspots touched (4)

• .../operations-agents/page.tsx: 2 commits/90d, 0 dependents · primary owner: 2233admin (100%)
• backend/models/__init__.py: 23 commits/90d, 8 dependents · primary owner: 2233admin (53%)
• .../shell/global-agent-dock.tsx: 2 commits/90d, 1 dependents · primary owner: 2233admin (100%)

1 more

• .../v1/chat.py: 7 commits/90d, 4 dependents · primary owner: Curry (98%)

🔗 Hidden coupling (1 file)

• backend/models/__init__.py co-changes with .../v1/__init__.py (14×, 🟡 notable), not in this PR.

💀 Dead code (1 finding)

• 💀 .../v1/chat.py _optional_request_identity (confidence 0.65)

👀 Suggested reviewers @2233admin

---

📊 See the full report for this PR
_{Your repo map with this PR's blast radius lit up, every caller of the contracts it changes, and health before and after. No sign-in. · ⭐ Star Repowise · 📥 Install bot · Silence on a single PR with [skip repowise] in the title · Per-repo toggle on repowise.dev/settings?tab=bot · Updated 2026-08-07 17:18 UTC}

[1012839419a-alt]

CI: Next Frontend failure — 上游 CI 配置缺陷（next start vs output: standalone）

现象：Next Frontend job 失败，page.goto: net::ERR_CONNECTION_REFUSED at http://127.0.0.1:3000/login（e2e/login.spec.mjs:4）

根因：job 的 WebServer 步骤用 next start --hostname 127.0.0.1 --port 3000，但项目 next.config 是 output: standalone。日志明确：

⚠ "next start" does not work with "output: standalone" configuration. Use "node .next/standalone/server.js" instead.

next start 在 standalone 模式下不监听端口（或直接退出）→ e2e 连 3000 被拒。

为什么历史 PR 是绿的（#65 等）：同一警告也出现在 #65 的日志里，但那次 next start 恰好起来了（1 passed）。该失败是 standalone 生效与否的 runner 环境差异——间歇性 flake，不是 #68/#70 的前端代码问题：

• next build 完全成功：✓ Compiled successfully + ✓ Generating static pages (35/35)
• 本 PR 前端改动（global-agent-dock.tsx 等）已通过编译 + 全页 prerender，无 SSR 错误

建议：上游把 CI WebServer 步骤改为 standalone 模式正确启动方式（node .next/standalone/server.js，参考 Next.js 官方 standalone 部署文档），或 rerun 该 job 等 runner 恢复正常。本 PR 代码无需改动。