Skip to content

feat(tui): cluster context + governance definitions (proposal 003 PR-5) - #58

Merged
flg77 merged 1 commit into
mainfrom
tui/perf-soma-context
May 13, 2026
Merged

feat(tui): cluster context + governance definitions (proposal 003 PR-5)#58
flg77 merged 1 commit into
mainfrom
tui/perf-soma-context

Conversation

@flg77

@flg77 flg77 commented May 13, 2026

Copy link
Copy Markdown
Owner

Summary

PR-5 of proposal 003 (ACC TUI usability hardening). Addresses two operator review surfaces:

Performance needs to provide info about the infused role, its cluster id, the active subagents, a summary of what the intent of this role is, and a summary about the actual task.

Dashboard needs more details that are user-friendly by providing summaries — of role-specific activity — Insights into Governance — Categories → Explanations of CAT A-B-C (Not only counters) Including Token Budgets allocation overview of active agent cluster.

Performance screen

Column Source
Cluster short cluster_id from snap.cluster_topology membership lookup; em-dash when not part of an active cluster
Intent first 80 chars of agent.task_progress_label
Subagents total subagent_count for the agent's cluster
Active task current/total step + parenthetical age since last heartbeat

Also a new CLUSTER OVERVIEW panel reusing acc/tui/widgets/cluster_panel.py:ClusterPanel so cluster_id / target_role / members / skill_in_use info renders identically on Performance and Prompt.

Dashboard / Soma screen

  • Each Cat-A / Cat-B / Cat-C counter now ships with a one-line definition row. Source is a new module-level GOVERNANCE_TAXONOMY constant at acc/tui/screens/dashboard.py — taxonomy text editable in one place, not view-hardcoded.
  • New TOKEN BUDGET BY CLUSTER panel joins cluster_topology membership with per-agent token_budget_utilization → one row per active cluster (cluster_id · target_role · N agents · avg X% / worst Y%, colour-coded by worst-single-agent: green < 75%, yellow ≥ 75%, red ≥ 90%).

Tests

tests/test_perf_soma_context_pilot.py (new, 8 cases): column presence, cluster lookup, Intent truncation, step rendering, taxonomy constant shape, definition rendering, cluster-budget rollup math (avg 57% / worst 75% from token utils 0.40 / 0.75 / 0.55), empty state.

79/79 tests green across the full TUI test surface.

CHANGELOG

[Unreleased] § Changed gains four entries — Performance table extensions, CLUSTER OVERVIEW, governance definitions, per-cluster token-budget panel.

Manual verification

acc-tui                          # press 5 → Performance
# Per-agent table now has Cluster / Intent / Subagents / Active task columns.
# CLUSTER OVERVIEW panel renders active clusters.

# Press 1 → Soma
# Each Cat-A/B/C counter has a definition row.
# TOKEN BUDGET BY CLUSTER panel rolls up token utils per cluster.

Reference

Proposal 003 — …\ACC Implementation\003 - ACC TUI usability hardening.md (operator vault).

🤖 Generated with Claude Code

@flg77 @claude
feat(tui): cluster context + governance definitions (proposal 003 PR-5)
ad1edfc 
Implements PR-5 of proposal 003 (ACC TUI usability hardening).
Addresses operator review items on Performance + Soma:

> Performance needs to provide info about the infused role its
> cluster id.  The active subagents.  We also need a summary of
> what the intent of this role is.  A summary about the actual
> task (details).
>
> Dashboard needs more details that are user friendly by
> providing summaries — of role specific activity — Insights into
> Governance — Categories → Explanations of CAT A-B-C (Not only
> counters) Including Token Budgets allocation overview of active
> agent cluster.

## Performance screen

* `acc/tui/screens/performance.py` per-agent table extended with
  four operator-requested columns:
  - **Cluster** — short cluster_id from `snap.cluster_topology`
    membership lookup; em-dash when the agent isn't part of any
    active cluster.
  - **Intent** — first 80 chars of `agent.task_progress_label`
    (sourced from TASK_PROGRESS.step_label).
  - **Subagents** — total `subagent_count` for the agent's
    cluster (or em-dash).
  - **Active task** — `current_task_step/total_task_steps` plus
    a parenthetical age in seconds since last heartbeat.
* New CLUSTER OVERVIEW panel reuses the existing
  `acc/tui/widgets/cluster_panel.py:ClusterPanel` widget — same
  rendering operators already see on the Prompt screen, so the
  cluster_id / target_role / member / skill_in_use info is
  consistent across screens.
* New helper `_agent_to_cluster(snap)` builds a flat
  `dict[agent_id, (cluster_id, count)]` so each row's cluster
  column is one lookup, not a walk.

## Dashboard / Soma screen

* `acc/tui/screens/dashboard.py` — governance panel restructured
  to render each Cat-A / Cat-B / Cat-C counter row alongside a
  one-line definition.  Source is a new module-level
  `GOVERNANCE_TAXONOMY: dict[str, str]` constant at file
  bottom — taxonomy text editable in one place, NOT view-
  hardcoded, per the proposal.
* New TOKEN BUDGET BY CLUSTER panel joins `cluster_topology`
  membership with per-agent `token_budget_utilization` and
  renders one row per active cluster:
  `cluster_id · target_role · N agents · avg X% / worst Y%`
  Colour-coded by worst-single-agent: green < 75%, yellow
  ≥ 75%, red ≥ 90%.  Empty state shows a calm placeholder.
* `_render_cluster_budgets()` added to the snapshot watcher
  fan-out.

## Tests

`tests/test_perf_soma_context_pilot.py` (NEW, 8 cases):

* `test_perf_table_includes_new_columns` — table columns include
  Cluster / Intent / Subagents / Active task.
* `test_perf_table_populates_cluster_column_from_topology` —
  cluster members carry the short cluster_id; non-members get
  the em-dash placeholder.
* `test_perf_table_populates_intent_from_progress_label` —
  Intent column truncates at 80 chars.
* `test_perf_table_active_task_column_shows_step_counts` —
  rendered cell carries `current/total` step counts.
* `test_governance_taxonomy_constant_shape` — central taxonomy
  carries all three Cat-* keys with non-empty values.
* `test_dashboard_governance_renders_definitions` — Cat-A
  "constitutional", Cat-B "operational", Cat-C "learned"
  substrings render on the governance panel.
* `test_dashboard_cluster_budget_renders_per_cluster_row` —
  cluster_id + 3-agent count + avg 57% + worst 75% all render
  from a synthetic snapshot with token utils 0.40 / 0.75 / 0.55.
* `test_dashboard_cluster_budget_empty_state` — no clusters →
  "No active agent clusters" placeholder.

**79/79 tests green** across the full TUI test surface (no
regressions in any previously-green test).

## CHANGELOG

`[Unreleased]` § Changed gains four entries documenting the
Performance table extensions, the CLUSTER OVERVIEW panel,
governance definitions, and the per-cluster token-budget panel.

## Manual verification

```bash
acc-tui    # press 5 → Performance
# Per-agent table shows Cluster / Intent / Subagents / Active task
# columns alongside the existing Queue + Backpressure.
# CLUSTER OVERVIEW panel below the table renders active clusters.

# Press 1 → Soma
# Governance panel: each Cat-A/B/C counter has a definition row.
# TOKEN BUDGET BY CLUSTER panel: per-cluster rollup of token utils.
```

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@flg77
flg77 merged commit 7bbb58e into main May 13, 2026
@flg77
flg77 deleted the tui/perf-soma-context branch May 13, 2026 22:22
This was referenced May 13, 2026
Merged
Merged
flg77 added a commit that referenced this pull request May 13, 2026
@flg77 @claude
chore(release): promote 0.2.0-dev → 0.2.0 (proposal 003 closes) (#60)
5787a1a 
All six PRs of proposal 003 (ACC TUI usability hardening) are on
main:

* #54 (PR-1) — Prompt cancel-on-timeout + CHANGELOG/version bump
* #55 (PR-2) — Ecosystem role.md detail + searchable filter
* #56 (PR-3) — Ecosystem roles/ watcher + selection lock
* #57 (PR-4) — Configuration pane (pane 8)
* #58 (PR-5) — Performance + Soma cluster/governance context
* #59 (PR-6) — CLI/TUI infuse parity + subrole sibling listing

pyproject.toml: 0.2.0-dev → 0.2.0
CHANGELOG.md:   [Unreleased] section closed off as [0.2.0]
                (dated 2026-05-14) with a fresh [Unreleased]
                header ready for the next cycle.

Tag v0.2.0 follows this merge.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
flg77 added a commit that referenced this pull request May 31, 2026
@flg77 @claude
fix(assistant): bump token_budget 2048→4096 to fit v0.3.43 perception…
2d4e9f9 
… block (v0.3.44) (#10)

Closes followup #58.

v0.3.43 added the `## Currently available` perception block to the
Assistant's system prompt (capability + roster + sub-collectives,
~1KB context).  This roughly doubled per-task input-token count
(~1000 → ~2000 tokens on lighthouse).  At the legacy 2048-token
Cat-B budget the Assistant hit utilization 1.10 ≥ 1.0 after 3
back-to-back tasks and started ALERT_ESCALATE blocking — a
legitimate Cat-B rail firing on a now-larger prompt, but the
operator-facing symptom was "the Assistant stopped answering."

Bumps role.yaml v2.2.0 → v2.2.1.  Inline comment block explains the
v0.3.43 prompt-size shift + leaves headroom for the future Phase-2
JSON action block.  No code change.

Tests: pytest -k "assistant or token_budget or role_def or cat_b"
       96 passed, 3 skipped.

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
flg77 added a commit that referenced this pull request Jun 10, 2026
@flg77 @claude
fix(operator): valid acc-config render, vLLM model wiring, offline em…
c3b7f7c 
…bedding, prometheusRules toggle, stop pod churn (#58)

Five fixes found bringing up an acc-e2e collective on RHOAI (vllm backend,
deploy=false). (The missing stage-1.6 CRDs and the PrometheusRules nil-scheme
panic from the same bring-up were already addressed on main by #55.)

1. acc-config.yaml template (templates/acc_config.go) used right-trim
   `{{ if X -}}`, which consumes the *next* line's leading indentation — so
   vllm_inference_url / model / embedding_model rendered at column 0 → invalid
   YAML → agents crash on startup (yaml ScannerError). Switch every
   conditional block to canonical left-trim `{{- if X }}` / `{{- end }}`.

2. The vLLM backend reads config.llm.model, but the template emitted
   `vllm_model` (no such field) → fell back to the ollama default
   `llama3.2:3b` → vLLM returns 404. Emit `model:` (the universal field).

3. acc/config.py build_llm_backend vllm branch dropped embedding_model_path,
   so episode-persist embedding tried to fetch from huggingface.co and failed
   offline. Pass it through like the other backends.

4. AgentCorpusSpec.PrometheusRules had `json:",omitempty"` + default=true, so
   an explicit `false` was dropped by the defaulting webhook's re-marshal and
   the default re-applied — impossible to disable. Drop omitempty.

5. buildManifestDelivery built the acc-roles/skills/mcps ConfigMap volume
   items[] by iterating cm.Data directly — Go randomizes map order, so the
   rendered pod template differed every reconcile. Since the agent Deployment
   reconcile replaces Spec.Template wholesale, this produced a fresh
   ReplicaSet/rollout every ~15s → perpetual pod churn. Sort the keys.

Verified end-to-end on RHOAI: operator generates valid config with the
correct model, agents reach a stable one-per-role steady state (no churn),
offline embedding (no HF calls), and a golden prompt round-trips
(TASK_COMPLETE output "pong").

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@flg77