106 lines
5.2 KiB
Markdown
106 lines
5.2 KiB
Markdown
---
|
|
status: resolved
|
|
claimed-by: "019fbff0-e725-79bd-861c-f1928d963392"
|
|
claimed-at: "2026-08-01T22:00:33-04:00"
|
|
resolved-at: "2026-08-01T22:00:33-04:00"
|
|
parent: "[[089-pi-subagent-result-delivery-design-approval-grill|Pi subagent result delivery design approval]]"
|
|
blocked-by:
|
|
- "[[089-pi-subagent-result-delivery-design-approval-grill|Pi subagent result delivery design approval]]"
|
|
tags:
|
|
- ticket/task/afk
|
|
---
|
|
|
|
# Pi subagent result delivery specification
|
|
|
|
## Question
|
|
|
|
Write the approved non-blocking subagent result-delivery and UI behavior as a specification, without implementation slicing.
|
|
|
|
## Result
|
|
|
|
The approved behavior design is captured below as a specification.
|
|
This artifact intentionally does not divide the work into implementation slices.
|
|
|
|
# Specification: Pi subagent result delivery
|
|
|
|
## Purpose
|
|
|
|
Improve Pi subagents so background work remains visible and retrievable while the parent session continues another workflow.
|
|
The motivating case is Wayfinder dispatching AFK research workers while the parent continues a HITL grill.
|
|
The human should not need to poll, block on `subagent_wait`, or remember that workers might have finished.
|
|
|
|
## Scope
|
|
|
|
This specification covers current-session subagent result delivery, completion awareness, work labels, and improved Pi-native subagent UI.
|
|
It also covers the boundary between the generic subagent layer and workflow-specific skills such as Wayfinder.
|
|
It does not cover cross-restart durability, Herdr integration, remote sandboxing, or redesigning Wayfinder mechanics.
|
|
|
|
## Generic subagent responsibilities
|
|
|
|
The generic subagent layer must expose reliable current-session completion state.
|
|
It must expose reliable current-session terminal result retrieval.
|
|
It must expose completion awareness without requiring blocking waits.
|
|
It must expose useful work labels for running and terminal children.
|
|
It must not prescribe workflow-specific reconciliation rules.
|
|
|
|
A completed result remains visible and retrievable for the parent session until it is explicitly cleared.
|
|
Terminal result persistence across parent session restart, Pi restart, or extension reload is not required.
|
|
|
|
## Work labels
|
|
|
|
Each child should have a human-readable label that explains what it is working on.
|
|
The spawn caller may provide an explicit label.
|
|
Structured callers may provide or imply a label from their own context, such as a Wayfinder ticket title.
|
|
Ad hoc children should fall back to a generated or truncated prompt summary.
|
|
|
|
## Completion awareness
|
|
|
|
Completion during HITL work should be visible but non-disruptive.
|
|
The UI should announce completion once and keep persistent compact state visible afterward.
|
|
Completion notices should identify what finished and whether it completed, failed, timed out, or was cancelled.
|
|
Several completions may be batched into one notice.
|
|
|
|
The generic layer should not inject ordinary messages into the active parent conversation by default.
|
|
Result bodies should remain retrievable out of band until a workflow or explicit user action chooses to inspect them.
|
|
|
|
## Compact UI
|
|
|
|
The compact UI should show aggregate counts by status rather than one row per child.
|
|
The compact view is for ambient awareness while the parent workflow remains primary.
|
|
It should be enough to tell that work is running, queued, completed, failed, timed out, cancelled, or otherwise awaiting attention.
|
|
|
|
## Expanded UI
|
|
|
|
The expanded UI should show one row per subagent.
|
|
Each row should include the child label, lifecycle state, elapsed time, and last activity or result marker.
|
|
Rows should truncate cleanly when space is limited.
|
|
The expanded view is for quickly understanding what children exist and which ones need attention.
|
|
|
|
## Attached child view
|
|
|
|
Selecting a child for inspection should open a read-only attached child view.
|
|
The view should look like a normal Pi session view, but without the text prompt.
|
|
The view should be an overlay or temporary replacement rather than a split pane.
|
|
The view only needs detach and normal scroll up and down controls.
|
|
It must not provide a text-input channel to the child.
|
|
|
|
Pi can support this shape through a custom Pi-native viewer component fed by child RPC or session events.
|
|
The design must not assume an embeddable promptless `InteractiveMode` exists.
|
|
|
|
## Wayfinder boundary
|
|
|
|
Wayfinder treats the generic subagent layer as a reliable current-session source for child completion, result, and label state.
|
|
Wayfinder owns active-map reconciliation.
|
|
When AFK workers complete during a HITL ticket, Wayfinder may surface completion awareness but should not read result bodies or reconcile artifacts unless the human explicitly pauses for reconciliation.
|
|
After HITL completion or explicit pause, Wayfinder reconciles active-map workers through its normal artifact and Frontier mechanics.
|
|
|
|
## Acceptance criteria
|
|
|
|
A parent session can continue a HITL workflow while background subagents run.
|
|
The human can see that subagents completed or failed without invoking a blocking wait.
|
|
The parent can retrieve terminal results later in the same session.
|
|
The compact UI shows aggregate status counts.
|
|
The expanded UI shows useful per-child work rows.
|
|
A selected child can be inspected through a read-only Pi-like attached view without a prompt.
|
|
The generic subagent layer remains workflow-neutral.
|