--- id: PX-PLAN-NY2PMQWM type: plan title: Ask Question Service spec: PX-SPEC-JCJZVDBZ status: draft --- ## Outcome Any independent Pi event-bus client can request Ask's existing human-question experience without calling its model-only tool. Implements [Ask Question Events](../../specs/PX-SPEC-JCJZVDBZ-ask-question-events/index.md). Plan prerequisites: none; Hornets is an optional client. ## Structure and behavior dependencies New inbound service ownership stays distinct from existing outbound question-provider negotiation. ```mermaid flowchart TB C["Independent event-bus client"] --> I["Ask inbound question service"] T["Existing Ask model tool"] --> F["Existing question flow"] I --> F F --> U["Native Ask interaction"] F --> O["Existing outbound provider routing"] U --> R["Correlated answer or terminal outcome"] O --> R R --> C R --> T ``` ## Ordered behaviors 1. **Request and answer a question without the model tool.** Add the inbound service in `extensions/ask/src/service.ts` and its public event contract document under `extensions/ask/`. Register service lifecycle from `index.ts`; reuse `ask-tool.ts` normalization and `runAskFlow` rather than duplicating question presentation. Define stable version, request/session/task identity, supported question shape, claim ownership, replies, and terminal outcomes in the documented protocol. Keep inbound service channels distinct from `src/interaction.ts` outbound `pi-ext:ask:request/claim/answer` channels to prevent self-claim and recursion. A synthetic client sends a valid request through the real Pi event bus, receives one claimed presentation, and gets actual selected/free-text answers and notes. 2. **Return honest unavailable and failed outcomes.** Exercise discovery/claim with no provider, unsupported question shape, headless mode, and existing external question-provider delivery. Reuse existing outbound negotiation when applicable without making a new inbound request recursively re-enter itself. No claimant permits caller fallback; once presentation occurred, provider release/loss returns a terminal outcome rather than silently showing the question again. Preserve existing outbound protocol compatibility; any change needed to distinguish pre-presentation fallback from post-presentation failure receives explicit regressions. Existing Ask tool cancellation continues to terminate its agent turn; inbound client dismissal/cancellation settles only its own request. 3. **Handle simultaneous clients and disappearing owners.** Service ownership correlates one provider and one active request; serialize native presentation without cross-answering concurrent requesters. Add bounded pending lifetime and queues with explicit expiry/overflow behavior, cancellation, provider release/loss, and session/reload/shutdown cleanup. Ignore duplicate/stale/wrong-owner replies; reject malformed requests and answers without stranding the client. Queued cancellation never opens a dialog later; active cancellation closes only the owned interaction. Origin attribution reaches current Ask UI without a new layout or redesign. 4. **Use the service independently after relocation.** Extend `__tests__/contract.test.ts` and `interaction.test.ts`; add focused service tests where concurrency/state rules require them. A test-only client imports no Ask runtime or sibling types and exercises documented messages only. Preserve the model tool and external provider tests with no service client installed. Document optional service use in `README.md` with a link to the canonical protocol, not a duplicated schema. Build/relocate Ask and run native question delivery, cancellation, and unavailable paths through the loaded extension. ## Interfaces and ownership `index.ts` owns listeners and session invalidation; `src/service.ts` owns inbound request lifecycle. `ask-tool.ts` retains model-tool behavior and question flow; `src/interaction.ts` retains outbound provider negotiation. Consumers implement the documented optional protocol locally; no sibling runtime import, shared storage, or required client helper package. Do not add a dependency on Hornets, voice, PiPi, Dilemma, Relop, or peer-review policy. [Hornets integration](../PX-PLAN-2W7CNSCD-hornets-codex-parity-and-optional-bridges/index.md) may consume the protocol after this plan, but cannot define its semantics. ## Verification - Real fixture-loaded Ask plus synthetic client proves request/claim/presentation/answer and origin attribution. - Deterministic races cover competing claims, concurrent clients, wrong versions/origins/answers, duplicate completion, late replies, and cancellation before/after presentation. - Provider loss, headless/no-provider, expiry, queue overflow, session replacement, reload, and shutdown all settle visibly without duplicate fallback. - Existing model-tool and outbound-provider tests remain regression evidence; event-client cancellation must not cancel unrelated parent work. - Use affected Ask Mise `test`, `lint`, `check`, and `verify-package`; finish with root checks at integration, not implicit broader CI. - Inspect representative native rendering for any changed attribution; metadata assertions alone do not prove visible origin. ## Exit criteria - [ ] Standalone synthetic client can ask/answer/cancel through the loaded Ask extension without model-tool access. - [ ] Existing tool and external question-provider behavior remain compatible. - [ ] Request ownership, concurrency, malformed traffic, cancellation, expiry, provider loss, and session invalidation cannot cross-complete or strand requests. - [ ] Unavailable-before-presentation permits caller fallback; failure after presentation never silently redisplays the question. - [ ] Service ships and verifies without Hornets or other optional clients.