AI Agent v1: "Terminal Doctor" (read-heavy MVP)

[kipavy]

AI Agent v1 — "Terminal Doctor" (read-heavy MVP)

First vertical slice — proves the whole stack with a small blast radius.

Part of the BYOK AI Agent epic: #55

⛔ Depends on #59 (UI/UX design & anti-clutter pass) for the panel / palette / terminal surfaces.

Scope

In the chat panel and via the terminal shortcut, the agent can:

1. Open a connection (prompts — network/auth).
2. Run read-only commands.
3. Read terminal output (the key new gated verb).
4. Explain / diagnose errors, suggest fixes.
5. Any write / risky command still prompts (Approve / Edit / Reject).

Proves

Provider loop · tool registry · terminal-output read (gated tier) · approval UX ·
chat panel + terminal surface.

Requires

• Gated capability tier: terminal-read + session-open (see capability-layer issue).
• Provider/BYOK layer (Vercel AI SDK, key in keychain).
• Agent loop + a small tool registry.
• Approval/permission state machine.
• Chat panel + terminal-context surface.
• Agent settings (provider, key, model).

Acceptance criteria

• User configures a provider + key; agent connects.
• From a terminal, "why did this fail?" reads recent output and explains.
• Agent can open a saved connection and run a read-only command after approval.
• Any mutating command is blocked behind an approval prompt.
• Actions recorded in the audit trail.

[kipavy]

v1 slice complete on dev (663cca58, pushed)

All five acceptance criteria are met and live-verified against a real provider (gpt-4o-mini) and a real host in the headless container — not just unit-tested. Shipped across phases 57a, P1, P2, 3a, 3b, 3c, P4, 3d and 3e:

• Provider / BYOK — profiles, keys in the Rust keychain, requests over Tauri HTTP.
• Tool registry — list_connections, open_session, run_command, read_terminal, close_session, propose_plan.
• Approval gate — Approve / Approve-always / Edit / Reject, with grants that are exact-command only and scoped to a connection id (never a host name).
• Plan mode — propose_plan renders a checklist card with per-step editing, pre-authorization badges on steps that cannot be pre-authorized, and "Approve & run" (one token, one execution; drift or off-plan calls fall back to a card).
• Audit trail — seven agent.* actions, always local and additionally to the team when applicable. Command text never goes on the wire; metadata.approval records how an action was authorized.
• Surfaces — drawer + title-bar button, terminal "Ask AI" touchpoint (selection or buffer snapshot), settings page with profiles/permissions/allowlist.

Suite at merge: 218 files / 1512 tests green, tsc clean.

Deferred follow-ups filed separately: #75 (persistence bounds) and #76 (plan checklist UX + test debt). Docs remain open at VoltiusApp/docs#9.

One security-boundary change to note: hasShellMetacharacter was widened to reject C0/C1, DEL, bidi and zero-width characters in addition to CR/LF, because such a command can render differently from what executes. It is shared with the stored allowlist, so a stored grant containing one of those characters is dropped on hydrate. Noted in the changelog; only pre-release builds are affected.