Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

.system/specs/PX-SPEC-JCJZVDBZ-ask-question-events/index.md

Raw
Rendered preview

id: PX-SPEC-JCJZVDBZ type: spec title: Ask Question Events

Intent

Let arbitrary Pi event-bus clients request Ask's human-question experience without depending on its model tool or runtime implementation. Ask question events are a general communication capability, not a Hornets-specific integration.

Scope

In: documented event-bus question service, request correlation, provider claiming, answer validation, origin attribution, cancellation, expiry, unavailable/failure outcomes. Out: harness management, review policy, automatic agent continuation, new dashboard or UI redesign, sibling imports, arbitrary SDK invocation. Preserve the existing Ask tool, question presentation, free-text answers/notes, cancellation behavior, and existing external question-provider interoperability.

Service contract

Clients submit question content and supported answer shape with a unique request identity and originating session/task identity. The service exposes discovery or bounded claim negotiation so an absent provider cannot leave callers waiting indefinitely. Exactly one provider owns presentation and completion of each request; competing or duplicate claims cannot create duplicate dialogs. Question identifiers, answer values, notes, and origin stay correlated throughout the request. Validate incoming requests and responses; malformed, mismatched, duplicate, stale, or non-owning answers cannot complete another request. Return distinct answered, dismissed/cancelled, unavailable, expired, and failed outcomes without inventing a human response. Unavailable or unclaimed service permits caller-owned fallback; failure after presentation must not silently redisplay the question. Clients can cancel their own pending request; cancellation affects that request, not unrelated tasks or the entire parent session. The model tool retains its existing agent-turn cancellation semantics. Session invalidation, shutdown, and provider loss settle affected requests and remove pending ownership; late answers are ignored. Concurrent clients remain independently attributable and cannot race visible presentation or receive one another's answers. A human answer conveys only that question's response, not blanket execution, login, spending, or tool authorization.

Interaction model

Only a claimed request may reach presentation and receive an authoritative answer.

stateDiagram-v2
  [*] --> Requested
  Requested --> Unavailable: no provider or unsupported request
  Requested --> Claimed: exactly one provider accepts
  Claimed --> Presented: ready for human input
  Presented --> Answered: valid correlated answer
  Requested --> Cancelled: client cancels
  Claimed --> Cancelled: client cancels
  Presented --> Cancelled: dismissal or cancellation
  Claimed --> Failed: provider lost
  Presented --> Failed: provider lost
  Requested --> Expired: deadline reached
  Claimed --> Expired: deadline reached
  Presented --> Expired: deadline reached
  Answered --> [*]
  Unavailable --> [*]
  Cancelled --> [*]
  Failed --> [*]
  Expired --> [*]

Independence and visibility

The public protocol defines concepts and outcomes without requiring clients to import Ask or another sibling's runtime/types. Existing Ask callers and external question providers remain compatible; distinguish inbound service requests from existing outbound provider routing to avoid recursive handling. Any client, including a synthetic independent client, can use the service without Hornets, PiPi, Dilemma, Relop, or the peer-review skill. Ask remains useful with no event-bus clients. Hornets may consume the capability, but owns its own fallback when Ask is absent. Reuse current Pi/Ask interaction conventions; expose enough source attribution for the human to know which task awaits a decision. No new layout or visual identity is specified.

Acceptance criteria

  • A standalone event-bus client can discover/request Ask questioning, receive a human answer and notes, and cancel without invoking the model-only Ask tool.
  • Existing Ask tool behavior, external question-provider routing, and current question interactions remain usable without any new clients.
  • No provider, unsupported requests, or unavailable interactive delivery produce a timely explicit outcome, never an indefinite wait or synthetic answer.
  • Competing providers, concurrent clients, duplicate requests, malformed answers, and late/wrong-origin responses cannot cause duplicate presentation or cross-request completion.
  • Request cancellation, expiry, provider loss, session invalidation, and shutdown settle only affected requests and reject stale replies.
  • Human-visible origin identifies the requesting task; dismissal does not become approval or cancel unrelated work.
  • A synthetic client demonstrates the full request/claim/answer lifecycle without Hornets or other sibling dependencies.
  • Consumers depend only on the documented optional protocol, with no sibling runtime imports or required shared storage.
---
id: PX-SPEC-JCJZVDBZ
type: spec
title: Ask Question Events
---

## Intent

Let arbitrary Pi event-bus clients request Ask's human-question experience without depending on its model tool or runtime implementation.
Ask question events are a general communication capability, not a Hornets-specific integration.

## Scope

In: documented event-bus question service, request correlation, provider claiming, answer validation, origin attribution, cancellation, expiry, unavailable/failure outcomes.
Out: harness management, review policy, automatic agent continuation, new dashboard or UI redesign, sibling imports, arbitrary SDK invocation.
Preserve the existing Ask tool, question presentation, free-text answers/notes, cancellation behavior, and existing external question-provider interoperability.

## Service contract

Clients submit question content and supported answer shape with a unique request identity and originating session/task identity.
The service exposes discovery or bounded claim negotiation so an absent provider cannot leave callers waiting indefinitely.
Exactly one provider owns presentation and completion of each request; competing or duplicate claims cannot create duplicate dialogs.
Question identifiers, answer values, notes, and origin stay correlated throughout the request.
Validate incoming requests and responses; malformed, mismatched, duplicate, stale, or non-owning answers cannot complete another request.
Return distinct answered, dismissed/cancelled, unavailable, expired, and failed outcomes without inventing a human response.
Unavailable or unclaimed service permits caller-owned fallback; failure after presentation must not silently redisplay the question.
Clients can cancel their own pending request; cancellation affects that request, not unrelated tasks or the entire parent session.
The model tool retains its existing agent-turn cancellation semantics.
Session invalidation, shutdown, and provider loss settle affected requests and remove pending ownership; late answers are ignored.
Concurrent clients remain independently attributable and cannot race visible presentation or receive one another's answers.
A human answer conveys only that question's response, not blanket execution, login, spending, or tool authorization.

## Interaction model

Only a claimed request may reach presentation and receive an authoritative answer.

```mermaid
stateDiagram-v2
  [*] --> Requested
  Requested --> Unavailable: no provider or unsupported request
  Requested --> Claimed: exactly one provider accepts
  Claimed --> Presented: ready for human input
  Presented --> Answered: valid correlated answer
  Requested --> Cancelled: client cancels
  Claimed --> Cancelled: client cancels
  Presented --> Cancelled: dismissal or cancellation
  Claimed --> Failed: provider lost
  Presented --> Failed: provider lost
  Requested --> Expired: deadline reached
  Claimed --> Expired: deadline reached
  Presented --> Expired: deadline reached
  Answered --> [*]
  Unavailable --> [*]
  Cancelled --> [*]
  Failed --> [*]
  Expired --> [*]
```

## Independence and visibility

The public protocol defines concepts and outcomes without requiring clients to import Ask or another sibling's runtime/types.
Existing Ask callers and external question providers remain compatible; distinguish inbound service requests from existing outbound provider routing to avoid recursive handling.
Any client, including a synthetic independent client, can use the service without Hornets, PiPi, Dilemma, Relop, or the peer-review skill.
Ask remains useful with no event-bus clients.
[Hornets](../PX-SPEC-WQR3XWPQ-hornets-cross-harness-delegation/index.md) may consume the capability, but owns its own fallback when Ask is absent.
Reuse current Pi/Ask interaction conventions; expose enough source attribution for the human to know which task awaits a decision.
No new layout or visual identity is specified.

## Acceptance criteria

- [ ] A standalone event-bus client can discover/request Ask questioning, receive a human answer and notes, and cancel without invoking the model-only Ask tool.
- [ ] Existing Ask tool behavior, external question-provider routing, and current question interactions remain usable without any new clients.
- [ ] No provider, unsupported requests, or unavailable interactive delivery produce a timely explicit outcome, never an indefinite wait or synthetic answer.
- [ ] Competing providers, concurrent clients, duplicate requests, malformed answers, and late/wrong-origin responses cannot cause duplicate presentation or cross-request completion.
- [ ] Request cancellation, expiry, provider loss, session invalidation, and shutdown settle only affected requests and reject stale replies.
- [ ] Human-visible origin identifies the requesting task; dismissal does not become approval or cancel unrelated work.
- [ ] A synthetic client demonstrates the full request/claim/answer lifecycle without Hornets or other sibling dependencies.
- [ ] Consumers depend only on the documented optional protocol, with no sibling runtime imports or required shared storage.