Proto-UI / Proto-UI/Proto-UI

[dogfood][agent-harness] Build the first fixed-layout all-Proto Harness vertical slice

Open
#515 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

advanced contribution area: adapters area: prototypes enhancement
Dominant language
TypeScript
Stars
35
Forks
15
Avg merge
2d 18h
Merged PRs (30d)
103

Description

Parent: #513
Depends on: #514 and the bounded ChatUI/App-local children linked from #513

Goal

Create the first usable apps/agent-harness/** vertical slice whose eligible interface is built entirely through Proto UI.

This Issue defines the bounded M1 integration target and preserves the independent ownership and evidence boundaries for @proto.ui/compositions-chatui, Base semantic candidates, Modules, Host Capabilities, and design-language projections. Ready dependencies, reversible integration work, and executable evidence advance immediately; only the affected slice pauses when current authority leaves a concrete product choice unresolved.

User journey

The slice must let a user:

  1. view a small list of sessions;
  2. select one session;
  3. read a finite transcript;
  4. submit a multiline prompt;
  5. observe an assistant response that streams in bounded chunks;
  6. stop an active response;
  7. inspect one tool invocation;
  8. approve or reject one inline action request;
  9. retry one failed response;
  10. open one code or log artifact in the right-hand workspace.

Fixed layout

Use a bounded three-region layout without resizable panes:

┌──────────────┬────────────────────────────┬──────────────────┐
│ Sessions     │ Transcript                 │ Artifact         │
│              │                            │ Tabs             │
│              │                            │                  │
│              ├────────────────────────────┤                  │
│              │ Composer                   │                  │
└──────────────┴────────────────────────────┴──────────────────┘

Narrow/mobile behavior may use a simple reviewed layout switch or existing Dialog/Tabs path. Do not implement app-private dragging, geometry measurement, or Drawer/Sheet semantics in this slice.

Required Proto UI surfaces

Existing official surfaces

At minimum consume current approved/dogfood-ready entries where applicable:

  • Button;
  • Textarea;
  • Scroll Area;
  • Tabs;
  • Dialog or existing overlay/menu surfaces;
  • Badge, Card, Separator, Skeleton from the chosen design-language path where their current admission permits dogfood;
  • Async Region and Live Region;
  • Tooltip where available.
Independent private compositions
  • Message;
  • Code Block;
  • Composer.

Each remains independently reviewable and must not be reintroduced as a shadow Base family; that independence enables parallel progress and does not impose a blanket human gate.

App-local Proto UI prototypes

The slice may define under apps/agent-harness/src/prototypes/**:

  • HarnessMessageProjection for App-owned message facts and content-part routing;
  • ToolInvocation;
  • ApprovalRequest;
  • ReasoningTrace in an initially always-expanded form;
  • RunStatus;
  • ArtifactCard / static artifact panel.

These must compose Proto UI controls and emit semantic requests to application callbacks. Rendering must not execute tools, approve actions, send prompts, retry requests, or mutate persistence.

Data and service fixture

Use an App-owned deterministic fixture/runtime sufficient to exercise the UI states. It may simulate streaming and failures, but it must remain clearly outside Proto UI semantic ownership.

Required fixture states:

  • idle session;
  • active streaming response;
  • stopped response;
  • failed response with retry;
  • pending tool invocation;
  • pending approval;
  • approved and rejected resolution;
  • code artifact and log artifact.

Primary boundaries

  • Agent message/run/tool/approval persistence remains App Maker-owned.
  • Each semantic action must be emitted once from an explicit Proto UI control event; rerender/remount must not execute it.
  • Streaming updates must update stable component roots rather than rebuild one unbounded monolithic Template tree.
  • The initial transcript may have a fixed upper bound and may defer virtualization.
  • Reasoning may be always expanded until #388 permits the needed Collapsible slice.
  • Transcript follow-tail may use the minimal authorized behavior from its own child; do not add private DOM scroll measurement if that child remains blocked.

Evidence

Functional
  • session selection;
  • send, stop, retry;
  • tool detail inspection;
  • approve/reject exactly once;
  • artifact tab selection;
  • streaming state changes;
  • repeated session switching.
Lifecycle
  • repeated mount/unmount/dispose;
  • session switch during active streaming;
  • stale fixture callbacks do not update the newly selected session;
  • no duplicate listeners or action execution after remount.
Accessibility
  • keyboard-only complete journey;
  • stable focus order and visible focus;
  • focus restoration after Dialog/menu use;
  • accessible names, roles, states, and errors;
  • Async Region busy projection;
  • Live Region updates are coalesced and do not announce every token;
  • Composer IME composition does not submit.
Responsive/design
  • 320px, 390px, and representative desktop widths;
  • light/dark/system;
  • forced colors/high contrast;
  • reduced motion and 200% zoom/reflow.

Acceptance criteria

  • apps/agent-harness/** contains a runnable bounded Harness fixture app.
  • Every eligible visible/interactive surface maps to a row in #514's matrix.
  • No third-party component, headless primitive, chat UI runtime, or Agent UI framework owns an eligible path.
  • No application-private generic focus, keyboard, scrolling, collection, dismissal, text-control, or ARIA state machine is introduced.
  • Message, Code Block, and Composer are consumed only through their independently governed private composition entries.
  • Tool/approval/run/reasoning subjects remain app-local Proto UI prototypes.
  • The full user journey and evidence matrix pass.
  • #513 and #514 are updated with evidence links and row states.

Explicitly deferred

  • resizable panes;
  • virtualized/windowed lists;
  • thread search requiring Base Input if unavailable;
  • Collapsible details if #388 is not ready;
  • attachments, image preview, file drop/paste;
  • file/subagent Tree;
  • branch/checkpoint editing;
  • terminal emulator;
  • production code editor;
  • sandbox/browser preview;
  • workflow/Agent builder.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with parent issue #513 and dependency #514, then inspect apps/agent-harness/** and its src/prototypes/** entry points. Run the deterministic fixture app and review the required user journey, lifecycle, accessibility, and responsive evidence. Done means the bounded Proto UI slice runs, its evidence passes, and #513 and #514 contain updated evidence links and row states.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
accessibility, frontend, testing-qa
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.