Skip to content

feat(wire): AgentEvent::Asked — a pending human-answerable question on the wire#143

Merged
phall1 merged 1 commit into
mainfrom
feat/agent-asked-event
Jun 18, 2026
Merged

feat(wire): AgentEvent::Asked — a pending human-answerable question on the wire#143
phall1 merged 1 commit into
mainfrom
feat/agent-asked-event

Conversation

@phall1

@phall1 phall1 commented Jun 18, 2026

Copy link
Copy Markdown
Owner

Adds an additive AgentEvent::Asked so a projection consumer (phux-mobile, phux-web) can tell "an agent is waiting on a human" — render the question and raise a notification — without re-deriving it from its local grid. Sibling of ADR-0033's TerminalControl; a structured agent-surface signal, not a new wire tier.

What

  • AgentEvent::Asked at event tag 0x09 (after terminal_control's 0x08) on the EVENT (0xB3) stream: { id, question, suggestions: [str], elapsed_seconds: opt<u64> }. Body is field-tagged TLV (id=1, question=2, suggestion=3 repeated, elapsed_seconds=4), so the suggestion list and counter are additive; an older decoder skips it by length to AgentEvent::Unknown.
  • v1 trigger — phux-ask title sentinel. The server decides a pane is asking from its terminal title (phux-ask[<id>]:<question>?s=a|b|c), coalesced so a re-asserted marker doesn't re-fire. libghostty-vt surfaces no OSC 9/777, so the title is the closest signal an agent can drive and the server can observe without disturbing the snapshot synthesizer.
  • ADR-0035 records the mechanism decision (additive AgentEvent variant vs the spec-only TERMINAL_EVENT/RUN_HOOK).
  • Additive: no tag renumbered, no existing bytes change. PROTOCOL_VERSION stays 0.5.0 (CHANGELOG 0.5.0-draft.8).

Why a draft, not 0.6.0

Matches the established convention — every recent additive wire change (ADR-0032/0033, QUIC, per-spawn TERM) landed as a 0.5.0-draft.N with PROTOCOL_VERSION held at 0.5.0 until the release is cut.

Tests / validation (local)

  • cargo test -p phux-protocol green (incl. the asked roundtrip, the proptest strategy covering both TerminalControl and Asked, and the forward-compat skip test now using tag 0x0a).
  • cargo check -p phux-server --tests green (the title-sentinel emission + agent_asked.rs integration test compile).
  • just docs-check green (84 files; CHANGELOG top ↔ PROTOCOL_VERSION sync).

Follow-up

  • Full agent-state detection (per-agent manifests and/or opt-in agent hooks; surfacing OSC 9 if libghostty grows the accessor) — phux-2sl6.
  • Consumer: phux-mobile already consumes this rev (PHUX_REV) and ships the foreground notification; it will re-pin to this branch's merge commit.

🤖 Generated with Claude Code

@phall1 phall1 force-pushed the feat/agent-asked-event branch from 9b3497b to 294c961 Compare June 18, 2026 02:10
A projection consumer (ADR-0035) needs to know "an agent is waiting on a
human" without re-deriving it from its local grid. Add an additive
AgentEvent::Asked on the EVENT (0xB3) stream at tag 0x09 (after ADR-0033's
terminal_control 0x08), carrying { id, question, suggestions, elapsed_seconds }
as a field-tagged TLV body so the suggestion list and elapsed counter are
additive. An older decoder skips it by length to AgentEvent::Unknown.

The v1 ask-trigger is the `phux-ask` terminal-title sentinel: libghostty-vt
surfaces no OSC 9/777, so the title is the closest signal an agent can drive
and the server can observe without disturbing the snapshot synthesizer.
Coalesced so a re-asserted marker doesn't re-fire; retitling clears the ask.
Full agent-state detection (manifests / hooks) is follow-up (phux-2sl6).

Additive: no tag renumbered, PROTOCOL_VERSION stays 0.5.0
(CHANGELOG 0.5.0-draft.8). ADR-0035 records the mechanism decision.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@phall1 phall1 force-pushed the feat/agent-asked-event branch from 294c961 to e250e74 Compare June 18, 2026 02:10
@phall1 phall1 merged commit 2b44dd7 into main Jun 18, 2026
3 checks passed
@phall1 phall1 deleted the feat/agent-asked-event branch June 18, 2026 02:56
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