[Tracking]: Pi-style Local Agent adaptation for LangBot runner

[huanghuoguoguo]

Goal

Implement the useful parts of Pi Agent in langbot-local-agent while preserving LangBot's architecture:

• LangBot Host owns authorization, resources, transcript/history, artifacts, state/storage, and platform delivery.
• Local Agent Runner owns model-facing behavior: message/context assembly, tool loop policy, context budgeting, and recovery strategy.
• The runner must use AgentRunAPIProxy and ctx.resources; it must not reach into host-private managers or assume Pi's local filesystem/security model.
• Pipeline remains a compatibility adapter, not the design center.

Source References

• Pi core loop: pi/packages/agent/src/agent-loop.ts
• Pi agent options/hooks: pi/packages/agent/src/agent.ts, pi/packages/agent/src/types.ts
• Pi session compaction: pi/packages/coding-agent/src/core/agent-session.ts
• Pi compaction utilities: pi/packages/coding-agent/src/core/compaction/*
• Existing related issues: [Feature]: LocalAgentRunner Agent Loop 应增加上下文保护与截断机制 #1, [Feature]: LocalAgentRunner 应支持并行执行 Tool Calls #2, [Feature]: LocalAgentRunner 增加 context-window 感知的上下文管理与按需压缩 #3, [Feature]: Tool 结果超限时应持久化到本地文件而非直接注入上下文 #4, [Roadmap]: LocalAgentRunner 与业界标准的差距分析与改进方向 #5

Non-goals

• Do not copy Pi CLI/TUI product behavior wholesale.
• Do not add per-conversation mutable state to the plugin instance.
• Do not bypass Host authorization to access local files, tools, models, knowledge bases, or storage.
• Do not commit dependency files (pyproject.toml, uv.lock) unless a dependency change is explicitly intended.

Implementation Checklist

Phase 0: Guardrails and Baseline

• Preserve current prompt_get / effective prompt direction if present in the active branch.
• Preserve skill_authoring / skill_injection capabilities if present in the active branch.
• Keep all runner resource access behind AgentRunAPIProxy.
• Add or update tests before claiming any checklist item complete.

Phase 1: Pi-style Tool Loop

• Add same-batch parallel tool execution for independent tool calls, borrowing Pi's semantics:
  • preflight/prepare tool calls in assistant source order;
  • execute allowed tool calls concurrently;
  • emit tool.call.completed as each tool finishes;
  • append model-facing tool result messages in original assistant source order.
• Keep a sequential fallback mode/config for tools or deployments that must avoid concurrency.
• Preserve existing max-tool-iterations loop guard.
• Add tests proving parallel execution and source-order tool result messages.

Phase 2: Tool Result Bounding

• Add max-tool-result-chars / equivalent runner config.
• Truncate or summarize oversized tool results before injecting them into the next model request.
• Prefer Host artifact/storage references for large results when the Host API is available.
• Provide a safe fallback marker when artifact/storage APIs are unavailable.
• Add tests for string, JSON, error, and oversized structured tool results.

Phase 3: Per-turn Context Budgeting

• Move context budgeting from one-time run assembly to before every LLM turn in the tool loop.
• Re-budget after assistant tool calls and tool result messages are appended.
• Keep prompt/current input/recent context priority clear and documented.
• Add tests where a large tool result would exceed budget unless compacted/bounded.

Phase 4: Context Overflow Recovery

• Detect provider context overflow errors in both streaming and non-streaming paths.
• Compact more aggressively and retry once, similar to Pi's overflow compact-and-retry path.
• Avoid infinite retry loops; expose a clear runner.context_overflow failure code after the one retry.
• Add tests for retry-on-overflow and fail-after-second-overflow.

Phase 5: LLM Summary / Checkpoint Path

• Replace deterministic summary-only compaction with an optional Host-authorized summarization path.
• Persist compaction checkpoints through Host state/storage when available.
• Keep deterministic fallback for environments without summary model/storage access.
• Add tests for checkpoint reload through Host history/state API.

Phase 6: LangBot QA Gates

• Unit tests in langbot-local-agent pass.
• Browser E2E local-agent-basic-debug-chat passes.
• Browser E2E local-agent-plugin-tool-call-debug-chat passes.
• Add a dedicated multi-tool-call E2E case in langbot-skills when the fixture supports it.

Current Sprint Slice

• Implement Phase 1 parallel tool execution first.
• Implement Phase 2 tool result bounding next.
• Reassess Phase 3 design after Phase 1/2 tests are passing, because per-turn budgeting touches both the loop and context pipeline.

Acceptance Notes

A feature is not done merely because the issue body says it is covered. Mark items complete only when source code, focused tests, and at least the relevant LangBot browser smoke path agree.

[huanghuoguoguo]

Implementation sprint started.

Current worker split:

• Worker A: Phase 1 same-batch parallel tool execution.

  • Write scope: pkg/agent_core/loop.py, tests/test_agent_core.py.
  • Acceptance: concurrent execution for same assistant batch, completion events may finish-order, tool result messages remain assistant source order, uv run pytest tests/test_agent_core.py -q.

• Worker B: Phase 2 bounded tool result fallback.

  • Write scope: pkg/config.py, pkg/model_calling.py, pkg/agent_core/langbot.py, runner config/docs/tests as needed.
  • Acceptance: max-tool-result-chars, bounded string/JSON/error tool results before model injection, no claim of Host artifact persistence yet, uv run pytest tests/test_runner.py -q.

Coordinator guardrails:

• Preserve existing local prompt API / skill capability changes in the branch.
• Do not modify pyproject.toml or uv.lock in this sprint.
• Keep LangBot Host authorization boundary: no direct Host-private manager access from the runner.

[huanghuoguoguo]

Implementation progress update for current sprint slice:

• Phase 1 slice: Pi-style same-batch parallel tool execution in the LangBot-local agent loop.
  • tool_execution_start remains source ordered.
  • tool execution now runs concurrently for one assistant tool-call batch.
  • tool_execution_end is emitted as tools finish.
  • model-facing role="tool" messages and turn_end.tool_results remain source ordered for provider compatibility.
• Phase 2 slice: runner-level model-facing tool-result bounding fallback.
  • Added max-tool-result-chars, default 20000.
  • String, JSON, and error results are bounded before being appended as role="tool" messages for the next model call.
  • tool.call.completed events keep the raw result/error so LangBot UI/Host events are not degraded.
  • This intentionally does not claim Host artifact persistence; full-output references remain a later Host storage/artifact phase.

Validation:

• uv run --frozen pytest -q -> 70 passed, SDK pydantic deprecation warnings only.
• uv run --frozen ruff check pkg/agent_core/loop.py pkg/model_calling.py pkg/agent_core/langbot.py pkg/config.py components/agent_runner/default.py tests/test_agent_core.py tests/test_runner.py -> passed.
• git diff --check -> passed.

Notes:

• uv.lock was restored after uv run auto-relocked it; no dependency lock or pyproject change is included in this slice.
• Existing local prompt API / skill capability changes were preserved and covered by the current test suite.

[huanghuoguoguo]

Implementation progress update for the second agent-loop alignment slice:

• Added Pi-style internal loop hooks for model-turn preparation, tool-call before/after hooks, next-turn preparation, and optional stop checks. These are internal runner extension points, not a public Host protocol expansion.
• Added per-turn context transform. The loop now re-runs context compaction before every model call, including follow-up model turns after tool results.
• Added context-overflow recovery. If a streaming provider fails before the first visible token with a context-overflow-style error, the runner compacts the current loop context with a more aggressive retry budget and retries that model turn once.
• Preserved LangBot boundaries: all model/tool/history access still goes through Host-authorized AgentRunAPIProxy; no Pi local-tool/security assumptions were imported.

Validation:

• uv run --frozen pytest -q -> 75 passed, SDK pydantic deprecation warnings only.
• uv run --frozen ruff check pkg components tests -> passed.
• git diff --check -> passed.

Remaining:

• Phase 5 LLM summary / checkpoint path is still not implemented. That should wait for a clearer Host state/storage and model usage/token metadata surface rather than faking persistence in the runner plugin.

[huanghuoguoguo]

Checklist status update after local implementation and user-accepted browser E2E:

Completed:

• Phase 0 guardrails: Host authorization boundary preserved; no Host-private manager access; prompt API / skill capability changes preserved in branch; dependency files not intentionally changed.
• Phase 1 core: same-batch parallel tool execution implemented and tested.
• Phase 2 partial: max-tool-result-chars model-facing bounding implemented and tested.
• Phase 3 core: per-turn context budgeting / transform now runs before every model call, including tool follow-up turns.
• Phase 4 core: context-overflow-style provider errors before first visible streamed output trigger one aggressive compaction retry.
• Phase 6 current gates: local unit tests pass; user reports browser E2E accepted in another window.

Still open:

• Phase 1 sequential fallback mode/config is not implemented. Keep this only if a real deployment needs opt-out from concurrency.
• Phase 2 Host artifact/storage references for full tool output are not implemented; this remains [Feature]: Tool 结果超限时应持久化到本地文件而非直接注入上下文 #4.
• Phase 4 should add an explicit runner.context_overflow failure code after second overflow if/when the host wants that granularity.
• Phase 5 LLM summary / checkpoint path is not implemented and should wait for Host state/storage plus model usage/token metadata.

Next alignment slice should not add more loop mechanics first. It should define the Host-side artifact/state contract needed for Pi-style durable compaction and large tool result references.