Skip to content

delivery: unify background completion inbox contract - #382

Open
testikun wants to merge 2 commits into
openpi-dev:mainfrom
testikun:codex/issue-160-completion-inbox
Open

delivery: unify background completion inbox contract#382
testikun wants to merge 2 commits into
openpi-dev:mainfrom
testikun:codex/issue-160-completion-inbox

Conversation

@testikun

@testikun testikun commented Sep 4, 2026

Copy link
Copy Markdown
Contributor

Problem

Closes #160.

Direct Subagent, Background Terminal, and Workflow each maintained a separate pending/consume/retry gate. Their execution states should remain producer-owned, but delivery identity, Session ownership, generation fencing, and atomic consumption had drifted across three implementations.

Value

A single small contract now proves the shared delivery invariants once: completions cannot cross Session owners or generations, explicit consumption races automatic delivery through one gate, failed batches retain exact identity and order, and dead letters remain inspectable. Producer-specific lifecycle and wake behavior remain unchanged.

Approach

  • Add a shared in-process completion inbox with stable delivery ids, Pi SessionManager owner generations, producer identity, terminal references, pending/in-flight claims, acknowledgement/retry, and fail-closed dead letters.
  • Migrate Direct Subagent and Background Terminal adapters off their private pending maps while preserving their existing follow-up and next-turn policies.
  • Migrate Workflow's in-memory gate while retaining its durable per-run receipts, partial acknowledgement, persistence recovery, and at-least-once replay contract.
  • Persist Workflow owner identity and epoch through bounded projections. Same-Session restart is an explicit revival boundary; stale predecessor instances and cross-Session restores cannot append to the revived transcript.
  • Record the four-layer boundary and validation contract in docs/design/COMPLETION_INBOX.md.

Validation

  • bun run check — passed.
  • bun run test — 1,253 passed, 0 failed, 1 skipped; Vitest 30 passed.
  • Node 22 node scripts/run-tests.mjs — 1,253 passed, 0 failed, 1 skipped; Vitest 30 passed.
  • Focused shared inbox, Workflow delivery, and Workflow lifecycle e2e run — 40 passed, 0 failed.

Impact

  • User-visible behavior: stale background completions are no longer eligible to enter a replacement Session; normal completion messages and wake policies are unchanged.
  • Model-visible context/tools: no schema or tool changes.
  • Runtime/lifecycle: all three producers use the shared owner/epoch/consumption gate; each producer still owns execution, cancellation, and terminal facts.
  • Persisted data: Workflow delivery records gain optional ownerSessionId and ownerEpoch; legacy records restore compatibly.
  • UI: no component or visual change; a screenshot is not applicable.
  • Risk: transport acceptance is not presented as distributed exactly-once. Workflow deliberately remains at-least-once when transport succeeds but durable receipt persistence fails.

@github-actions github-actions Bot added documentation Improvements or additions to documentation area:workflows Workflow engine, capability, skills, or tests area:subagents Subagent delegation, skills, or tests area:background-terminals Background terminal runtime, skill, or tests labels Sep 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:background-terminals Background terminal runtime, skill, or tests area:subagents Subagent delegation, skills, or tests area:workflows Workflow engine, capability, skills, or tests documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

delivery: 统一后台完成事件的 owner 路由、epoch 与消费收据合同

1 participant