tutti/packages/agent/gui/REVIEW.md

AgentGUI Review Contract

This file adds AgentGUI-specific review requirements. It does not replace the repository contribution, testing, security, accessibility, or code-quality rules.

Review only the lanes triggered by the change. For every triggered lane, report one of:

• pass: include concrete evidence
• not applicable: explain why the change cannot affect the lane
• blocked: name the missing evidence or unavailable consumer

Do not use an unsupported statement such as "no impact" as review evidence.

1. Architecture Integrity

Trigger this lane when a change touches:

• Session, Turn, Interaction, Goal, runtime-operation, or prompt lifecycle
• AgentGUIRuntime, AgentHostApi, engine state, selectors, projections, controllers, event handling, reconciliation, or public exports
• composer, Rail, timeline, Message Center, approvals, interactive prompts, Workbench integration, or host adapters

Review against:

• Agent GUI Node
• Agent Activity Packages

Verify:

1. The existing owner still owns each fact and state transition.
2. The command and observation paths still follow the documented direction.
3. Events remain invalidation hints and canonical reads remain authoritative.
4. Session, Turn, Interaction, request, and Workbench identities stay exact.
5. Shared behavior remains provider-neutral and capability-driven.
6. React renders projections and dispatches actions; it does not recreate lifecycle or reconciliation orchestration.
7. New public exports are durable consumer contracts, not convenience exports for one host.

If the change alters ownership, data flow, or a public contract, update the durable architecture document in the same change.

2. Performance

Trigger this lane when a change touches:

• high-frequency engine subscriptions, selectors, snapshots, or stream updates
• Session list, Rail, timeline, transcript, message projection, or reconciliation
• scroll, resize, layout measurement, virtualization, rich-text rendering, or hidden surfaces
• caches, retained per-Session state, timers, observers, or diagnostic logging

Verify:

1. A change in one Session does not rebuild unrelated Session projections.
2. High-frequency render paths do not consume whole-workspace snapshots.
3. Streaming does not add per-token logging, broad reconciliation, repeated parsing, or synchronous full-layout reads.
4. Lists, history reads, caches, and retained UI state remain bounded.
5. Memoized boundaries keep stable references and do not receive aggregate objects when scalar projections are sufficient.
6. Virtualization, scroll following, and prepend restoration keep one geometry and intent owner.
7. pnpm check:agent-gui-degradation budgets do not increase.

Use evidence proportional to risk:

• For a statically isolated change, identify the unchanged hot path and boundary.
• For state or projection changes, provide focused test results and reference stability or fanout evidence.
• For reported jank, long tasks, or render storms, provide a trace or profiler comparison tied to the exact interaction.

Use Agent session lifecycle troubleshooting for known large-history, streaming, reconciliation, and diagnostic-log traps.

3. Consumer Compatibility

Trigger this lane when a change touches an exported symbol, subpath export, runtime or host input, projection shape, event/DTO mapping, command behavior, feature capability, or lifecycle ordering.

Review these known in-repository consumers:

• Desktop workspace AgentGUI and standalone Agent windows
• Desktop Message Center, Workbench, Issue Manager, and App Center integrations
• Mobile conversation, Rail, composer, media, and activity services
• agent-activity-core and the tuttid activity adapter

Also review the published contract for out-of-repository consumers:

• TSH and other AgentGUI hosts
• closed-source cloud hosts
• external workspace applications

Verify:

1. Existing imports and documented subpath exports remain valid.
2. Optional capabilities still fail closed when absent or unknown.
3. Consumers do not need to copy engine, lifecycle, merge, or attention logic.
4. Cancellation, failure, retry, reconnect, stale response, and recovery paths preserve their documented ordering and terminal semantics.
5. Unknown providers, enum values, missing optional data, and unavailable host capabilities remain explicit rather than silently reinterpreted.
6. A contract change has consumer coverage or a named migration plan.

For a closed-source consumer, record only:

• the sanitized consumer role
• the public contract or capability it uses
• validation status and any remaining uncertainty

Do not record private repository URLs, customer names, credentials, deployment topology, proprietary feature names, or unreleased operational details.

4. Review Output

The review summary must include:

Lane	Trigger	Result	Evidence	Affected consumers
Architecture	Why it applies	pass, not applicable, or blocked	Document section, code path, or test	Named surfaces
Performance	Why it applies	pass, not applicable, or blocked	Static boundary, test, budget, or trace	Named surfaces
Consumers	Why it applies	pass, not applicable, or blocked	Import search, contract test, or validation status	Named consumers

List unresolved risks separately. Do not convert unavailable evidence into a pass.

5. Automation Boundary

REVIEW.md defines semantic review requirements; it is not itself an executable gate. Agent instructions route reviewers to this file. Repository checks and hooks may verify objective invariants such as forbidden imports, dependency direction, public-export shape, degradation budgets, and required test fixtures. They must not claim to prove semantic compatibility or performance without the evidence required above.