stablyai / stablyai/orca

[Feature]: Consume structured OMP subagent lifecycle hooks

Open
#11,554 0 comments 0 reactions 1 assignee Claimed by @brennanb2025 View on GitHub
Dominant language
TypeScript
Stars
72.1k
Forks
4.7k
Avg merge
14h 54m
Merged PRs (30d)
520

Description

## Problem or use case

OMP `task` workers run as in-process child agent sessions. Orca currently cannot reliably distinguish their lifecycle from the visible root OMP session, which can cause a child completion to mark the parent as finished (#9181) and can allow child prompt/message content to affect the parent preview (#9348). The generic agent-graph work is tracked by #8251, but it needs an OMP-specific, structured ingress contract before Orca can represent OMP children safely.

## Proposed solution

Add a versioned, authenticated OMP hook contract at the existing `/hook/omp` ingress that accepts child lifecycle records alongside normal root status records:

- `subagent_started`: stable child identity plus an optional opaque/display label.
- `subagent_finished`: the same identity plus a bounded terminal outcome (`completed`, `failed`, or `cancelled`).
- Every child record carries the parent/root session identity needed to attach it to the active pane/session.

The payload must be metadata-only: do not accept or persist prompts, tool arguments, assistant text, errors, or full child transcripts. Ingestion must be idempotent for duplicate start/finish events, reject/ignore child events that cannot be authenticated and routed to the current root session, and never let a child terminal event trigger the root-pane completion notification.

Expose these children through the existing agent hierarchy as nested rows under the root OMP session, with aggregate state in the root row. A child should be visible as working after start, terminal after finish, and never replace the root preview or create a second top-level OMP agent row.

## Alternatives or additional context

- This is a focused OMP adapter/ingress milestone for #8251, not a second generic graph API; it should link to the provider-neutral model when that model exists.
- #9181 and #9348 remain the correctness regressions this must not reintroduce.
- OMP currently needs a reliable public main/subagent identity surface. If that upstream contract is unavailable, do not infer children from PID, `yield`, UI presence, prompt text, or terminal output. Track the upstream dependency in can1357/oh-my-pi#5985.
- Acceptance evidence should include an end-to-end OMP `task` run in Orca: one root row, N nested child rows, no false root completion or preview overwrite, deduplicated repeated lifecycle hooks, and reconnect/restart cleanup consistent with #8251.
- The accompanying producer-only prototype is deliberately exploratory: it identifies candidate children from session IDs because OMP does not yet expose `agentKind`, `agentId`, `parentAgentId`, or `taskDepth` to extension lifecycle handlers. Its delivery was unit-tested only; it is not a substitute for the upstream identity contract and must not be shipped as a heuristic-based correctness fix.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.