Native orchestration API for plugins

[namastex888]

Problem or use case

We are building a Genie integration for Orca and want Orca to remain the sole authority for Runs, Tasks, Dispatches, workers, questions, gates, and lifecycle settlement.

Today a plugin worker cannot call the existing orchestration engine through Orca's typed plugin host facade. The available workaround is a narrowly allowlisted, shell-free adapter over orca orchestration ... --json, but that cannot provide first-class capability consent, stable host schemas, or host-enforced lifecycle authority.

We would like maintainer feedback before writing code. No PR has been opened.

Proposed solution

Expose a small additive orchestration surface through pluginApi: 1, with separate orchestration:read, orchestration:write, and orchestration:subscribe capabilities.

The API would delegate to the existing orchestration services rather than create new state. The first version would be limited to plugin-created Runs, use installation principal and controller-generation fencing rather than trusting manifest identity alone, authorize every child object atomically through its Run, use durable request receipts for remote retries, and treat lifecycle events as advisory with authoritative read-back.

The complete architecture proposal—including scope, authority model, retry semantics, mixed-version behavior, security limitations, and the cross-platform/SSH/federated test plan—is here:

https://gist.github.com/namastex888/76e22d09df7eb4387c1465949ae3f687

If the maintainers agree with this architectural direction and point us at the preferred principal/controller integration seams, I am happy to implement the focused PR and full test matrix. I will not open a speculative PR before that approval.

Alternatives or additional context

The immediate no-upstream workaround is a Genie-owned plugin that invokes only allowlisted Orca orchestration CLI commands using structured argv, mandatory --json, no shell, strict output parsing, capability/version probes, timeouts, and mutation read-back. It would not use terminal injection, internal RPC, a second lifecycle store, or local fallback for unavailable remote execution.

A native host facade would still be preferable because it provides honest install consent, typed compatibility negotiation, durable authority boundaries, and a provider-neutral integration point for plugins beyond Genie.

This proposal follows the repository's contribution requirements: the eventual change would be narrowly scoped, provider-neutral, compatible with macOS/Linux/Windows, and tested across local, folder, SSH, and federated execution. Release changes would remain maintainer-owned.

[soul-sol]

On "lifecycle settlement" specifically — if Orca is to be the sole authority for it,
the part worth pinning in the host schema is that settlement has three outcomes, not
two.

From running a worker pool daily and getting this wrong four separate times:

• COMPLETED — the work is durably confirmed.
• FAILED — it provably did not happen. Safe to retry.
• UNVERIFIED — it may have happened; the host could not judge. Never auto-retried
  or auto-settled.

Collapsing UNVERIFIED into FAILED is what fires side effects twice. Collapsing it into
COMPLETED is what reports success on work that never landed. A plugin that only receives
a boolean has no way to express the third, so it will be forced to pick one of the wrong
answers — which is an argument for putting this in the typed facade rather than leaving
it to the --json adapter.

Two host-side facts that make settlement decidable, both learned the hard way:

• The terminal status has to be recorded when the run ends, not reconstructed later. A
  background process's status disappears the moment the parent stops waiting for it, so a
  worker that exited quietly and one still working are indistinguishable after the fact.
• A missing completion marker must never mean "stalled". Markers are per-tool: one CLI
  prints a token-usage line on normal exit, others print nothing. I required that marker
  from every worker once and scored four healthy runs as stuck. And the inverse also
  holds: an exit of 0 is a candidate, not a verdict — a worker can exit cleanly having
  only asked a question, which is exactly what "questions" and "gates" in your list are
  for.

If the facade exposes settlement, exposing why it settled (recorded exit status vs.
timeout vs. explicit terminal event) is what lets a plugin distinguish a real failure from
a detector false positive. Without it the two look identical downstream.

Reference for the process half, MIT: https://github.com/soul-sol/agent-watch

[pNaOH]

Hi — this is very close to the integration boundary I’m currently investigating in Orca 1.4.217.
Our intended architecture is:

Hermes / sandboxed agent
→ small authenticated host-side adapter
→ Orca native orchestration
→ Codex / Claude workers

We want Orca to remain the lifecycle owner for Runs, Tasks, Dispatches, workers, messaging, stop/cancel, and settlement.
The adapter should only provide:

• authentication
• authorization
• approval
• target validation
• replay protection
• audit boundaries
  From read-only inspection of the installed Orca 1.4.217 backend/schema/skills, CLI help, structured output, and public docs, we confirmed that Orca has:
• authenticated local/remote transports
• paired-device grants / shared-control mechanisms
• headless runtime hosting
• orchestration federation
• session/coordinator authority
• native request/lifecycle ledger concepts
  What we have not been able to establish is the supported contract for a non-interactive service caller.
  In particular:

1. Does Orca 1.4.217 have a supported service principal or non-interactive caller identity for orchestration mutations?
2. Can such a service acquire or attach to coordinator authority and create Tasks / Dispatches / workers without depending on an interactive terminal or live-agent session?
3. Is one of the following the intended supported path for this use case?
   • paired client / shared-control
   • headless runtime
   • orchestration federation
   • local Unix-socket RPC
   • another API that is not currently documented
4. If paired/shared-control is the intended path:
   • what authority does the paired client receive?
   • is that authority scoped?
   • can it acquire coordinator authority?
   • what fencing/revocation guarantees exist?
5. Is there a supported immutable-target / compare-and-lock contract for:

repository
project
worktree
branch
HEAD
coordinator revision

We specifically want to avoid relying on implicit selectors such as current, active, or cwd-derived authority.
6. Are native request IDs and mutation receipts intended to be durable service-facing contracts for:

• deduplication
• exact retry
• ambiguous-failure recovery
• post-crash result lookup
  If so, are acceptance, activation, worker-start, and settlement represented as distinct authoritative states or receipts?

7. If there is currently no supported service-oriented mutation API, should direct use of internal Unix-socket / WebSocket / federation RPC be considered unsupported for third-party integrations?
   We are deliberately not invoking mutation APIs until we understand this support boundary.
   Environment:

Orca CLI/runtime: 1.4.217
Platform: macOS arm64

The key question for us is:
Can a host-side service be a formally supported orchestration caller in Orca today, or is orchestration authority intentionally limited to terminal/live-session/paired-client contexts?
Even a high-level clarification of the intended boundary would be very helpful.

[makerfaireczech]

We have a small Hermes-to-Orca integration working across two macOS hosts for terminal discovery, inspection, and carefully checked direct messaging. We would like to contribute a reusable, sanitized adapter recipe and tests rather than build a parallel orchestration system.

This is closely related to this discussion and #15828. In particular, the earlier Hermes/host-side-adapter comment describes the boundary we want too: Orca remains the authority for Runs, Tasks, Dispatches, delivery, worker lifecycle and settlement; Hermes is a client and human-facing interface.

We recognize that Orca already provides Hermes lifecycle hooks.

It also provides durable Run inboxes with replay/ACK, pending questions and federated worker placement. We are not requesting a second mailbox, a new scheduler, or basic Hermes support.

One important attribution: our current SSH forced-command transport intentionally exposes only an allowlisted subset of commands, with ownership restrictions. Missing orchestration routes through that wrapper are our integration limitation—not an Orca bug and not a request to relax Orca's authority checks.

Would you welcome a reference integration built on supported CLI/host contracts, covering:

1. Caller identity and supported scope. Discover capabilities, bind only to explicitly authorized ownership, and refuse lifecycle/ACK operations when the caller lacks authority. If external coordinator identity is not yet supported, document that boundary and track [Feature]: Add authenticated external coordinator identity #15828 rather than borrow a terminal handle.
2. Durable delivery without duplicate effects. Preserve request IDs and authoritative Run/Dispatch/message/Delivery correlation across adapter restarts; replay and process the whole Delivery before its owner ACKs. Reuse original question identity after timeout. Treat accepted enqueue, acknowledged delivery, observed turn start, reported completion and verified result as separate evidence.
3. Safe interaction with live terminals. Prefer durable orchestration mail for coordination. Never append and submit over a human draft, blindly clear the composer, or infer success from echoed text. On unsupported/uncertain submission evidence, refuse or require inspection. Link the existing draft-safety and confirmed-send work instead of duplicating it: #16289, #16290, #10662.
4. Multi-host and lifecycle correctness. Preserve execution-host identity; use stable Dispatch routing rather than stale pane aliases; distinguish authentication/setup wait from ready/idle and completed work. An unavailable remote host remains unverifiable, with no local fallback or blind retry.

Proposed acceptance tests:

• Two hosts with the same workspace/display names cannot cross-route a request or ACK.
• Restart after enqueue but before ACK replays the same Delivery; repeated processing cannot duplicate the downstream action.
• Another owner cannot ACK that Delivery or emit an authoritative worker completion.
• An existing human draft is untouched; unsupported detection does not silently authorize injection.
• A provider login/approval screen is not classified as an idle prompt or completed task.
• A disconnected host does not trigger a local substitute action; reconnect preserves the original question/request correlation.
• Unsupported or mixed-version capabilities yield an explicit refusal or documented bounded fallback, never a broadened target.

We can prepare a clean-room sample with placeholder hosts, structured argv, strict JSON parsing, capability checks, mutation read-back and focused tests. No production scripts, logs or credentials would be included. Telegram-specific buttons and persistent human-inbox UI would remain in a separate Hermes gateway plugin; they are not an Orca responsibility.

Maintainer question: which supported caller/ownership seam should a non-interactive Hermes adapter target today, and would docs plus a reusable adapter/test fixture be preferable to a small host API addition? We would prefer to contribute to the existing discussion and identity work before proposing a new public API.

References for the existing contracts: orchestration guide, messaging and gates, remote placement, and Hermes lifecycle plugin.