clawdie/bherdr
Watch
1
0
Fork
You've already forked bherdr
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Agent state: colibri's error has no bherdr reportable equivalent #34

New issue
Closed
opened 2026-10-04 00:09:51 +02:00 by clawdie · 1 comment
clawdie commented 2026-10-04 00:09:51 +02:00
Owner
Copy link

Agent state: colibri's error has no bherdr reportable equivalent

Summary

Colibri models a failed agent turn as a first-class state (error). bherdr's
reportable agent-state set is idle | working | blocked | unknown — there is
no error, so a failed turn can only surface as unknown. When the Go Colibri
consumes bherdr pane/agent state, this gap silently loses the failure signal.

Evidence

Colibri internal/zotrpc/events.go (and crates/colibri-glasspane,
AgentState) — 5 states:

idle, working, blocked, done, error

turn_end/agent_end folds to done, but error is sticky: once set it
survives a later terminal frame (Apply():

case "turn_end", "agent_end":
    if state == StateError {
        return StateError
    }
    return StateDone
case "error":
    return StateError

bherdr internal/server/server.go — reportable states are validated to:

idle, working, blocked, unknown

and rollup precedence is blocked > working > idle > unknown
(rollupTabStatus, rollupWorkspaceStatus). "error" appears nowhere as an
agent state in internal/wire or internal/server.

bherdr docs/wiki/protocol-contract.md:

pane.report_agent requires pane_id, source, agent, state … state is
idle|working|blocked|unknown (PaneAgentState). Detected AgentStatus
additionally has done, so done is derivable, never reportable.

Finding (Jev probe, advisory)

A grounded probe over the two real vocabularies (jev_probe):

question answer
do shared states idle/working/blocked agree? 0.65
does bherdr have a state for a failed turn? 0.22 (no)
where does colibri error map in bherdr? split — idle 0.43 / unknown 0.34 / error 0.23
where does colibri done map? done 0.42 (matches "derivable")

Jev is a prior, not an authority; the underlying gap is confirmed by reading
the two sources above.

Options

  1. bherdr adds a reportable error state (protocol 22 extension). Cleanest
    fidelity; changes the pinned subset and needs the protocol-contract bump.
  2. Colibri adapter maps error → unknown and carries the failure in a
    side channel (task ledger already records failed). No bherdr change; loses
    the distinction on the pane surface.
  3. bherdr keeps 4 states; done/error stay derivable and Colibri derives
    both from turn_end stop reason — which it already does for zot RPC. This
    is the smallest change: bherdr is the pane surface, colibri owns turn
    outcome.

Recommendation

Option 3 unless the pane surface must show failures distinctly. If it must,
Option 1 with an explicit protocol-contract update. The decision belongs to the
bherdr protocol owner; this issue records the gap and evidence.

Refs: colibri internal/zotrpc/events.go, crates/colibri-glasspane/src/lib.rs;
bherdr internal/server/server.go, docs/wiki/protocol-contract.md.

# Agent state: colibri's `error` has no bherdr reportable equivalent ## Summary Colibri models a failed agent turn as a first-class state (`error`). bherdr's reportable agent-state set is `idle | working | blocked | unknown` — there is no `error`, so a failed turn can only surface as `unknown`. When the Go Colibri consumes bherdr pane/agent state, this gap silently loses the failure signal. ## Evidence Colibri `internal/zotrpc/events.go` (and `crates/colibri-glasspane`, `AgentState`) — 5 states: ``` idle, working, blocked, done, error ``` `turn_end`/`agent_end` folds to `done`, but `error` is **sticky**: once set it survives a later terminal frame (`Apply()`: ```go case "turn_end", "agent_end": if state == StateError { return StateError } return StateDone case "error": return StateError ``` bherdr `internal/server/server.go` — reportable states are validated to: ``` idle, working, blocked, unknown ``` and rollup precedence is `blocked > working > idle > unknown` (`rollupTabStatus`, `rollupWorkspaceStatus`). `"error"` appears nowhere as an agent state in `internal/wire` or `internal/server`. bherdr `docs/wiki/protocol-contract.md`: > `pane.report_agent` requires `pane_id, source, agent, state` … `state` is > `idle|working|blocked|unknown` (`PaneAgentState`). Detected `AgentStatus` > additionally has `done`, so `done` is derivable, never reportable. ## Finding (Jev probe, advisory) A grounded probe over the two real vocabularies (`jev_probe`): | question | answer | | --- | --- | | do shared states `idle/working/blocked` agree? | 0.65 | | **does bherdr have a state for a failed turn?** | **0.22 (no)** | | where does colibri `error` map in bherdr? | split — `idle` 0.43 / `unknown` 0.34 / `error` 0.23 | | where does colibri `done` map? | `done` 0.42 (matches "derivable") | Jev is a prior, not an authority; the underlying gap is confirmed by reading the two sources above. ## Options 1. **bherdr adds a reportable `error` state** (protocol 22 extension). Cleanest fidelity; changes the pinned subset and needs the protocol-contract bump. 2. **Colibri adapter maps `error` → `unknown`** and carries the failure in a side channel (task ledger already records `failed`). No bherdr change; loses the distinction on the pane surface. 3. **bherdr keeps 4 states; `done`/`error` stay derivable** and Colibri derives both from `turn_end` stop reason — which it already does for zot RPC. This is the smallest change: bherdr is the *pane* surface, colibri owns turn outcome. ## Recommendation Option 3 unless the pane surface must show failures distinctly. If it must, Option 1 with an explicit protocol-contract update. The decision belongs to the bherdr protocol owner; this issue records the gap and evidence. Refs: colibri `internal/zotrpc/events.go`, `crates/colibri-glasspane/src/lib.rs`; bherdr `internal/server/server.go`, `docs/wiki/protocol-contract.md`.
clawdie commented 2026-10-07 09:26:58 +02:00
Author
Owner
Copy link

Resolved by Option 3, ratified in this repo's docs/wiki/protocol-contract.md via PR #40 (merge 1377b04):

  • bherdr keeps the 4-state reportable set (idle | working | blocked | unknown) — no wire-protocol change;
  • Colibri derives the ledger task outcome (done / error) from Zot turn_end stop reasons;
  • the pane surface continues to report unknown for a failed turn.

This matches the projection codified in colibri testdata/contracts/agent-state/v1/states.json (done → idle, error → unknown, rollup blocked > working > idle > unknown).

If the pane surface must later surface failures distinctly, reopen under Option 1 (a reportable error state, with a protocol-contract bump). Closing as resolved.

Resolved by **Option 3**, ratified in this repo's `docs/wiki/protocol-contract.md` via PR #40 (merge `1377b04`): - bherdr keeps the 4-state reportable set (`idle | working | blocked | unknown`) — no wire-protocol change; - Colibri derives the ledger task outcome (`done` / `error`) from Zot `turn_end` stop reasons; - the pane surface continues to report `unknown` for a failed turn. This matches the projection codified in colibri `testdata/contracts/agent-state/v1/states.json` (`done → idle`, `error → unknown`, rollup `blocked > working > idle > unknown`). If the pane surface must later surface failures distinctly, reopen under **Option 1** (a reportable `error` state, with a protocol-contract bump). Closing as resolved.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
docs/reconcile-freebsd-runner-topology
fix/deprecate-forge-host
docs/upgrade-0.9.5
fix/freebsd-canary-probe
ci/freebsd-canary
snapshot/0.15.0-dev/8809544
v0.15.0-dev
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
clawdie/bherdr#34
No description provided.