nsaspy/a0-symbolics

Fork 0

[P0][symbolics-worker] Define canonical Agent Zero tools + clean synthwave themes + Prolog-RLM sync #198

New issue

Open

opened 2026-09-11 04:53:38 +00:00 by nsaspy · 1 comment

nsaspy commented

2026-09-11 04:53:38 +00:00

Owner

Operator directive

This is the first issue for the dedicated a0-symbolics worker in the Machine Spirit fleet.

Related/current contracts: #174, #186, #182, #139, #91. Generic symbolic/runtime behavior remains owned upstream by lost-rob0t/prolog-rlm; do not create a second runtime or second tool authority here.

Goal

Make a0-symbolics / Agent Zero feel like a clean symbolic workstation while tightening the tool surface and keeping the Prolog-RLM integration continuously current.

This issue has three coupled deliverables:

define the canonical Agent Zero / a0 tool surface and metadata contract;
improve the WebUI into a clean synthwave workstation with a real runtime theme selector;
establish a tested, continuous Prolog-RLM sync/pin discipline so a0 does not drift from upstream semantics.

A — Canonical tool surface

First inspect the current code and inventory every source of tools/capabilities:

Agent Zero built-ins;
a0-symbolics/plugin tools;
MCP/imported tools;
Prolog-RLM-projected tools;
runtime/control tools exposed through the Agent Zero bridge.

Then converge on one normalized tool metadata/definition contract. Prefer extending the existing authoritative registry/projection paths from #186 and Prolog-RLM rather than adding another registry.

The contract must make these concepts explicit and separate:

registered tool
!= model-visible tool
!= active/run-local tool
!= capability
!= execution authorization

Requirements:

stable canonical tool IDs/names, description, input schema, effects/risk, capabilities and source/provider metadata;
compact catalog/search metadata for discovery without projecting every full schema into every prompt;
small essential/control surface always available;
bounded task-relevant tool projection for normal work;
bounded discovery/retry when the needed capability is not currently visible;
runtime authorization remains host-owned and cannot be widened by model-visible catalog state;
imported/MCP tools enter through the same normalized contract after host classification;
duplicate/parallel tool registries are removed or made derived/read-only projections;
active tools/capabilities and their source can be inspected from the UI without dumping giant schemas into chat.

Coordinate directly with #186 rather than re-solving its context-debloat problem in parallel.

B — UI direction: clean synthwave, not neon soup

Build on the existing WebUI contract in #174. Do not create a parallel redesign framework.

Target visual language:

crisp, modern symbolic workstation;
deep neutral surfaces;
restrained synthwave accents;
high readability and strong hierarchy;
deliberate spacing/typography;
minimal chrome and visual noise;
dense enough for serious agent/tool inspection without becoming a dashboard wall.

Add a first-class theme selector backed by design tokens / CSS variables. At minimum ship equivalent presets for:

Synthwave — the polished default/operator theme;
Dark — neutral dark;
Light — clean light.

Theme requirements:

persist the selected theme;
support system preference where appropriate;
plugin UI/extension surfaces inherit tokenized theme state instead of hard-coded colors;
accessible keyboard/focus states;
reduced-motion path;
usable contrast and touch targets;
no fake-glass/card-soup everywhere;
no excessive glow, gradients, scanlines or animation that compete with actual work.

The UI must make the important Agent Zero state legible: conversation, current mode/runtime, active tools/capabilities, execution/tool activity, settings, and plugin surfaces. Keep diagnostics available without making the normal chat surface look like an ops console.

Visual acceptance

Code-only acceptance is not enough. Capture/review screenshots for at least:

main shell + chat;
composer/tool activity;
tool/capability inspector;
settings/theme selector;
plugin-rendered surface;
empty/loading/error/long-output states;
desktop and narrow/mobile widths;
Synthwave, Dark and Light themes.

C — Keep a0-symbolics current with Prolog-RLM

Treat lost-rob0t/prolog-rlm as the canonical upstream for generic symbolic/runtime/tool-context semantics.

Before each implementation slice:

inspect the current upstream Prolog-RLM head/release and the current a0 pin/integration state;
inspect active upstream issues/PRs touching the contracts a0 consumes;
adapt a0 to upstream contracts rather than copying/forking generic semantics downstream.

Pin/sync requirements:

do not blindly float production against moving main;
pin an explicit compatible upstream revision/release;
make the pin and upstream comparison visible/inspectable;
gate bumps on live bridge/compiler/runtime/tool-context conformance tests;
record a sync receipt containing at least a0 revision, Prolog-RLM pin, compared upstream head/release, and conformance result;
make drift detectable so stale pins do not silently survive;
when upstream changes generic behavior, fix/adapt a0 rather than preserving a downstream fork;
keep Agent Zero upstream ingestion/update work under #139 and preserve a0 patches through those upstream updates.

Acceptance

Current tool sources are inventoried and normalized behind one canonical/derived contract.
No second independent tool registry/authority is introduced.
Model-visible projection is bounded; runtime execution authorization is unchanged/fail-closed.
Active tools/capabilities can be inspected cleanly in the UI.
Synthwave + Dark + Light theme choices (or clearly documented equivalents) are runtime-selectable and persisted.
UI uses shared design tokens and plugin surfaces inherit theme state.
Synthwave presentation is clean/functional rather than glow-heavy visual noise.
Desktop/narrow layouts, focus/keyboard, reduced motion and contrast receive explicit QA.
#174 plugin/UI extension contract remains compatible.
Prolog-RLM pin/sync procedure is documented and automated enough to detect drift.
Pin changes are conformance-gated, not blind dependency bumps.
Live Agent Zero ↔ Prolog-RLM tool/context integration passes at the pinned revision.
Screenshot evidence is attached/reviewed before acceptance.

Worker law

The dedicated a0-symbolics worker consumes this issue first. After this issue is accepted, it consumes only unclaimed a0-symbolics issues, while continuously keeping the Prolog-RLM integration/pin healthy.

Before claiming any issue, inspect current issue/PR/worktree ownership and skip work already active elsewhere. One worker should not duplicate another worker's issue.

When this P0 is accepted and the remaining a0-symbolics backlog is predominantly maintenance/non-blocking rather than foundational work, the Machine Spirit fleet will replace this worker slot with a task steward + TODO-sync role. That later steward coordinates work; it does not become another feature implementation worker.

## Operator directive This is the **first issue for the dedicated `a0-symbolics` worker** in the Machine Spirit fleet. Related/current contracts: #174, #186, #182, #139, #91. Generic symbolic/runtime behavior remains owned upstream by `lost-rob0t/prolog-rlm`; do not create a second runtime or second tool authority here. ## Goal Make `a0-symbolics` / Agent Zero feel like a clean symbolic workstation while tightening the tool surface and keeping the Prolog-RLM integration continuously current. This issue has three coupled deliverables: 1. define the canonical Agent Zero / a0 tool surface and metadata contract; 2. improve the WebUI into a **clean synthwave** workstation with a real runtime theme selector; 3. establish a tested, continuous Prolog-RLM sync/pin discipline so a0 does not drift from upstream semantics. ## A — Canonical tool surface First inspect the current code and inventory every source of tools/capabilities: - Agent Zero built-ins; - a0-symbolics/plugin tools; - MCP/imported tools; - Prolog-RLM-projected tools; - runtime/control tools exposed through the Agent Zero bridge. Then converge on **one normalized tool metadata/definition contract**. Prefer extending the existing authoritative registry/projection paths from #186 and Prolog-RLM rather than adding another registry. The contract must make these concepts explicit and separate: ```text registered tool != model-visible tool != active/run-local tool != capability != execution authorization ``` Requirements: - stable canonical tool IDs/names, description, input schema, effects/risk, capabilities and source/provider metadata; - compact catalog/search metadata for discovery without projecting every full schema into every prompt; - small essential/control surface always available; - bounded task-relevant tool projection for normal work; - bounded discovery/retry when the needed capability is not currently visible; - runtime authorization remains host-owned and cannot be widened by model-visible catalog state; - imported/MCP tools enter through the same normalized contract after host classification; - duplicate/parallel tool registries are removed or made derived/read-only projections; - active tools/capabilities and their source can be inspected from the UI without dumping giant schemas into chat. Coordinate directly with #186 rather than re-solving its context-debloat problem in parallel. ## B — UI direction: clean synthwave, not neon soup Build on the existing WebUI contract in #174. **Do not create a parallel redesign framework.** Target visual language: - crisp, modern symbolic workstation; - deep neutral surfaces; - restrained synthwave accents; - high readability and strong hierarchy; - deliberate spacing/typography; - minimal chrome and visual noise; - dense enough for serious agent/tool inspection without becoming a dashboard wall. Add a first-class **theme selector** backed by design tokens / CSS variables. At minimum ship equivalent presets for: - `Synthwave` — the polished default/operator theme; - `Dark` — neutral dark; - `Light` — clean light. Theme requirements: - persist the selected theme; - support system preference where appropriate; - plugin UI/extension surfaces inherit tokenized theme state instead of hard-coded colors; - accessible keyboard/focus states; - reduced-motion path; - usable contrast and touch targets; - no fake-glass/card-soup everywhere; - no excessive glow, gradients, scanlines or animation that compete with actual work. The UI must make the important Agent Zero state legible: conversation, current mode/runtime, active tools/capabilities, execution/tool activity, settings, and plugin surfaces. Keep diagnostics available without making the normal chat surface look like an ops console. ### Visual acceptance Code-only acceptance is not enough. Capture/review screenshots for at least: - main shell + chat; - composer/tool activity; - tool/capability inspector; - settings/theme selector; - plugin-rendered surface; - empty/loading/error/long-output states; - desktop and narrow/mobile widths; - Synthwave, Dark and Light themes. ## C — Keep a0-symbolics current with Prolog-RLM Treat `lost-rob0t/prolog-rlm` as the canonical upstream for generic symbolic/runtime/tool-context semantics. Before each implementation slice: 1. inspect the current upstream Prolog-RLM head/release and the current a0 pin/integration state; 2. inspect active upstream issues/PRs touching the contracts a0 consumes; 3. adapt a0 to upstream contracts rather than copying/forking generic semantics downstream. Pin/sync requirements: - do **not** blindly float production against moving `main`; - pin an explicit compatible upstream revision/release; - make the pin and upstream comparison visible/inspectable; - gate bumps on live bridge/compiler/runtime/tool-context conformance tests; - record a sync receipt containing at least a0 revision, Prolog-RLM pin, compared upstream head/release, and conformance result; - make drift detectable so stale pins do not silently survive; - when upstream changes generic behavior, fix/adapt a0 rather than preserving a downstream fork; - keep Agent Zero upstream ingestion/update work under #139 and preserve a0 patches through those upstream updates. ## Acceptance - [ ] Current tool sources are inventoried and normalized behind one canonical/derived contract. - [ ] No second independent tool registry/authority is introduced. - [ ] Model-visible projection is bounded; runtime execution authorization is unchanged/fail-closed. - [ ] Active tools/capabilities can be inspected cleanly in the UI. - [ ] Synthwave + Dark + Light theme choices (or clearly documented equivalents) are runtime-selectable and persisted. - [ ] UI uses shared design tokens and plugin surfaces inherit theme state. - [ ] Synthwave presentation is clean/functional rather than glow-heavy visual noise. - [ ] Desktop/narrow layouts, focus/keyboard, reduced motion and contrast receive explicit QA. - [ ] #174 plugin/UI extension contract remains compatible. - [ ] Prolog-RLM pin/sync procedure is documented and automated enough to detect drift. - [ ] Pin changes are conformance-gated, not blind dependency bumps. - [ ] Live Agent Zero ↔ Prolog-RLM tool/context integration passes at the pinned revision. - [ ] Screenshot evidence is attached/reviewed before acceptance. ## Worker law The dedicated `a0-symbolics` worker consumes **this issue first**. After this issue is accepted, it consumes only **unclaimed** a0-symbolics issues, while continuously keeping the Prolog-RLM integration/pin healthy. Before claiming any issue, inspect current issue/PR/worktree ownership and skip work already active elsewhere. One worker should not duplicate another worker's issue. When this P0 is accepted and the remaining a0-symbolics backlog is predominantly maintenance/non-blocking rather than foundational work, the Machine Spirit fleet will replace this worker slot with a **task steward + TODO-sync** role. That later steward coordinates work; it does not become another feature implementation worker.

nsaspy commented

2026-09-11 05:04:34 +00:00

Author

Owner

Operator testing amendment

This issue is not accepted on unit/component tests alone.

Add these gates to the existing acceptance criteria:

Playwright

Run Playwright against the real built Agent Zero/a0-symbolics WebUI, not a mock standalone page.

Cover at minimum:

Synthwave / Dark / Light theme selection + persistence;
chat/composer rendering;
active tool/capability inspector;
tool enable/visibility interactions exposed by this slice;
plugin-rendered surfaces inheriting theme tokens;
loading/error/long-output states;
keyboard/focus behavior;
narrow/mobile viewport;
reload/reconnect state reconstruction.

Capture trace/screenshots/video on failure and attach/refer to screenshot evidence on the candidate head.

Real E2E

Exercise the actual path:

Agent Zero WebUI
-> a0-symbolics integration/plugin
-> Prolog-RLM tool/context/runtime path
-> provider/tool execution
-> canonical result/event projection
-> Agent Zero WebUI

A DOM-only success while Prolog-RLM/tool execution failed is a failed test.

Live LLM through llm.starintel.actor

For model/tool/context/runtime behavior, run a live validation lane through llm.starintel.actor using the normal configured provider/auth path.

The candidate head must prove at least:

a real user turn completes through the a0-symbolics -> Prolog-RLM path;
selected/active tools exposed by the new contract are truthfully reflected;
context/runtime state remains canonical across the turn;
provider/tool failure is surfaced as failure, never false-green UI success;
safe receipt records endpoint identity, model/provider route, run/session IDs, relevant tool/context state, status and timestamps without credentials/secrets.

Live testing may remain opt-in for ordinary offline contributor runs, but when requested it must hard-fail on missing configuration and must not silently downgrade to mocks.

This is now part of the completion gate for #189.

## Operator testing amendment This issue is not accepted on unit/component tests alone. Add these gates to the existing acceptance criteria: ### Playwright Run Playwright against the **real built Agent Zero/a0-symbolics WebUI**, not a mock standalone page. Cover at minimum: - Synthwave / Dark / Light theme selection + persistence; - chat/composer rendering; - active tool/capability inspector; - tool enable/visibility interactions exposed by this slice; - plugin-rendered surfaces inheriting theme tokens; - loading/error/long-output states; - keyboard/focus behavior; - narrow/mobile viewport; - reload/reconnect state reconstruction. Capture trace/screenshots/video on failure and attach/refer to screenshot evidence on the candidate head. ### Real E2E Exercise the actual path: ```text Agent Zero WebUI -> a0-symbolics integration/plugin -> Prolog-RLM tool/context/runtime path -> provider/tool execution -> canonical result/event projection -> Agent Zero WebUI ``` A DOM-only success while Prolog-RLM/tool execution failed is a failed test. ### Live LLM through llm.starintel.actor For model/tool/context/runtime behavior, run a live validation lane through `llm.starintel.actor` using the normal configured provider/auth path. The candidate head must prove at least: - a real user turn completes through the a0-symbolics -> Prolog-RLM path; - selected/active tools exposed by the new contract are truthfully reflected; - context/runtime state remains canonical across the turn; - provider/tool failure is surfaced as failure, never false-green UI success; - safe receipt records endpoint identity, model/provider route, run/session IDs, relevant tool/context state, status and timestamps without credentials/secrets. Live testing may remain opt-in for ordinary offline contributor runs, but when requested it must hard-fail on missing configuration and must not silently downgrade to mocks. This is now part of the completion gate for #189.