P1 — render structured tool execution and user approvals in chat #89

New issue

Open

opened 2026-08-12 14:43:19 +00:00 by lost-rob0t · 0 comments

lost-rob0t commented

2026-08-12 14:43:19 +00:00

(Migrated from github.com)

Motivation

Tool calls are core Zara behavior, but a desktop assistant must show useful execution state without dumping implementation logs. Meaningful side effects also need a structured waiting-for-user approval path.

Scope

Consume the generic tool lifecycle events from #82.
Add a durable/tool-run model with states: queued, running, waiting-for-user, completed, failed, cancelled.
Render compact tool cards in Full Chat and Quick Copilot with expandable sanitized details.
Add structured approval/rejection actions routed through RuntimeHost commands.
Display bounded result/error previews, elapsed/status metadata and explicit cancellation.
Redact secrets before rendering or diagnostic export.
Ensure malformed tool events degrade to a visible error state rather than breaking the conversation renderer.

Acceptance criteria

Every visible tool run has a stable run ID and explicit state.
waiting-for-user exposes an actionable approval/rejection UI where requested by runtime policy.
Approval/rejection never calls a tool directly from a widget.
Completed/failed/cancelled tool runs are distinguishable at a glance.
Details are expandable and bounded; normal chat does not dump raw logs.
Secret-bearing arguments/output are redacted by a shared policy before display/export.
Cancellation maps to canonical turn/tool cancellation semantics.

Testing requirements

Unit tests for tool-state transitions, invalid transitions and redaction.
Qt tests for queued/running/waiting/completed/failed/cancelled rendering.
Approval/rejection and cancellation integration tests using fake tools.
Malformed tool-event tests.
Full repository/Nix suite.

Dependencies

#82 runtime event contract.
#83 RuntimeHost command bridge.
#85 conversation rendering.
Design: #81.

Explicit non-goals

No bypass of existing tool security policy.
No direct widget invocation of ToolRegistry tools.
No raw unbounded stdout/stderr in normal chat.
No general-purpose terminal emulator.

## Motivation Tool calls are core Zara behavior, but a desktop assistant must show useful execution state without dumping implementation logs. Meaningful side effects also need a structured `waiting-for-user` approval path. ## Scope - Consume the generic tool lifecycle events from #82. - Add a durable/tool-run model with states: queued, running, waiting-for-user, completed, failed, cancelled. - Render compact tool cards in Full Chat and Quick Copilot with expandable sanitized details. - Add structured approval/rejection actions routed through RuntimeHost commands. - Display bounded result/error previews, elapsed/status metadata and explicit cancellation. - Redact secrets before rendering or diagnostic export. - Ensure malformed tool events degrade to a visible error state rather than breaking the conversation renderer. ## Acceptance criteria - [ ] Every visible tool run has a stable run ID and explicit state. - [ ] `waiting-for-user` exposes an actionable approval/rejection UI where requested by runtime policy. - [ ] Approval/rejection never calls a tool directly from a widget. - [ ] Completed/failed/cancelled tool runs are distinguishable at a glance. - [ ] Details are expandable and bounded; normal chat does not dump raw logs. - [ ] Secret-bearing arguments/output are redacted by a shared policy before display/export. - [ ] Cancellation maps to canonical turn/tool cancellation semantics. ## Testing requirements - Unit tests for tool-state transitions, invalid transitions and redaction. - Qt tests for queued/running/waiting/completed/failed/cancelled rendering. - Approval/rejection and cancellation integration tests using fake tools. - Malformed tool-event tests. - Full repository/Nix suite. ## Dependencies - #82 runtime event contract. - #83 RuntimeHost command bridge. - #85 conversation rendering. - Design: #81. ## Explicit non-goals - No bypass of existing tool security policy. - No direct widget invocation of `ToolRegistry` tools. - No raw unbounded stdout/stderr in normal chat. - No general-purpose terminal emulator.