#posoco-ext-herdr

Targets: native + js (bun); compiles inert elsewhere

#Ports contributed

#Usage

moon add posoco/ext-herdr

// moon.pkg: "posoco/ext-herdr" @herdr

// copied from cetas-js/lib/cetas_js.mbt — both detections are env-gated:
match @herdr.HerdrReporter::detect() {
  Some(reporter) => exts.push(reporter as &@posoco.Extension)
  None => ()
}
match @herdr.HerdrDelegate::detect(cwd=runtime.config.cwd) {
  Some(delegate) => exts.push(delegate as &@posoco.Extension)
  None => ()
}

#Presence (HerdrReporter)

TurnStarted            →  herdr pane report-agent <pane> --source cetas --agent cetas --state working
UserRequestStarted     →  … --state blocked --message <bounded prompt>
UserRequestFinished    →  … --state working
TurnCompleted          →  … --state idle
TurnFailed             →  … --state idle
registration (once)    →  … --state idle
Agent shutdown         →  herdr pane release-agent <pane> --source cetas --agent cetas

• Not a tool provider — the manifest contributes the observer and the lifecycle only. Presence reporting is read-only telemetry that must never fail a turn; failures are swallowed by design (verify manually by running the CLI command above when debugging).

#Delegation (HerdrDelegate)

herdr pane split       --pane <this pane> --direction <right|down> --cwd <host cwd> --no-focus
herdr pane run         <new pane> "cetas-headless --permission readonly -- '<task>' ; echo '[cetas-headless] pane-id'le"
herdr pane wait-output --regex "\[cetas-headless\] (turn [0-9]+ done|turn failed:|pane-idle)" --source recent-unwrapped --timeout <ms> <new pane>
herdr pane read        <new pane> --source recent-unwrapped
                                     (re-run once, best-effort, after a timeout to capture child_session)
herdr pane close       <new pane>   (only after a successful read; skipped when close_pane=false)

#Tool arguments

#Result contract

• Success: the headless answer, then a footer — peer_pane: <new pane id> and, when the pane showed a session: <id> line, child_session: <id>. Pass the child session back via session to continue that child. On this success path the child pane is then closed (default close_pane=true); when pane close itself fails the result still succeeds, with a final note: pane auto-close failed (pane still open) footer line.
• The child's own failure (a [cetas-headless] turn failed: <reason> line on the pane) surfaces as a tool error carrying the reason, peer_pane, and — when the pane showed a session line — child_session. A startup failure (the headless launcher exiting with code 2 before any turn) prints the same shape first — [cetas-headless] turn failed: startup: … — so the wait catches it and the delegate reports it like any child failure. A child that exits without printing any protocol line at all is still terminated promptly by the idle sentinel; the delegate then reports child exited before printing a completion marker with a bounded excerpt of the pane screen (the real death cause — a usage error, a missing binary, an env failure). A marker timeout is likewise a tool error, noting that the pane is left open and the child may still be running; the delegate then reads the pane once, best-effort, to capture child_session (a failed read is silently omitted). child_session is returned on success, failure, and (best-effort) timeout; related work should resume the same session via the session argument. Every CLI step failure (split / run / wait / read) is a model-visible tool error; only spawn/transport breakage raises. The pane is never auto-closed on any of these paths.
  read) is a model-visible tool error; only spawn/transport breakage raises. The pane is never auto-closed on any of these paths.

#Background delegations

background herdr_delegate accepted
delegation_id: agent_task_…
a fresh pane and child session will start; the result arrives as a follow-up turn

#Guardrails and limits

• Depth 1 — hosts never wire delegation tools into cetas-headless, so a delegated child cannot split further panes.
• Concurrency cap 4 — a fifth in-flight delegate is refused until an earlier one finishes; background delegations hold their slot from accept until the channel flow exits (or the task is cancelled).
• The pane read is screen text (--source recent-unwrapped): what returns is what the pane shows, and a long answer can be truncated by the pane buffer — this is not a captured pipe.
• Exit fidelity comes from the pane text — the wait regex's three terminal shapes (marker / failure line / idle sentinel) — not from the child's exit code; the child runs inside the pane's shell and its status is not captured.
• Known risk (pre-existing class): a task whose text itself contains marker or sentinel literals can fake or premature-match a terminal shape. The single-line check plus shell quoting prevents command injection; they do not prevent marker-string injection.
• Envelope v1: the task is sent as a plain (shell-quoted) line, without the [cetas-peer from=… session=…] attribution envelope.

#Environment gates

#Behavior per target