@orion-agents/orion-code 0.2.2 → 0.3.1

package/docs/plan/v0.3.0-web-workbench-plan.md

@@ -0,0 +1,376 @@
+# Orion Code v0.3.0 Web Workbench Development Plan
+
+> Status: implementation complete; local release candidate gates passed
+>
+> Target version: `v0.3.0`
+>
+> Implementation branch: `v0.3.0`
+>
+> Baseline: `v0.2.2@40d02f6`
+>
+> API contract: [v0.3.0 Web API](../architecture/v0.3.0-web-api.yaml)
+>
+> Settings lifecycle and release gates:
+> [v0.3.0 Settings integration plan](v0.3.0-settings-integration-plan.md)
+>
+> DSH source reference: `deepseek-ai/deepseek-harness@b150a551b8d465e31e418e1b2eaf5e79bbb7d28e`
+
+## 1. Product outcome
+
+v0.3.0 turns Orion Code into a local-first coding-agent product with a complete browser surface.
+The browser can select a workspace, create and resume sessions, run AI coding tasks, inspect
+streaming messages and tool activity, answer approvals, control Goal and Plan mode, select models,
+inspect Skills/MCP and runtime diagnostics, and recover after a refresh or disconnect.
+
+The Web surface is an adapter over the same product runtime used by the terminal UIs. It does not
+own a second agent loop, permission implementation, session database, or completion model.
+
+### Completion requirements
+
+| Requirement                                                 | Authoritative proof                                         |
+| ----------------------------------------------------------- | ----------------------------------------------------------- |
+| `orion web` starts the workbench                            | Packaged CLI smoke test and HTTP health response            |
+| Workspace and session management                            | Web API contract tests plus browser workflow test           |
+| Streaming conversation, reasoning, tools, edits and results | Ordered event-stream integration test                       |
+| Approval, Goal, Plan, Skills, MCP, model and diagnostics    | Endpoint/command tests and UI workflow coverage             |
+| Refresh/disconnect recovery                                 | Cursor replay test with no duplicate command execution      |
+| Shared Web/TUI/CLI runtime and persistence                  | Runtime parity test over one fixed scenario                 |
+| Loopback and browser security                               | bind, Origin, nonce, CSP, redaction and path-boundary tests |
+| npm distribution includes the Web UI                        | tarball inspection and installed-artifact smoke test        |
+
+## 2. Reference decisions
+
+The official DeepSeek Harness source is cloned separately under
+`~/ai-project/deepseek-harness` and pinned to the commit above. Orion adopts the useful product
+separation demonstrated there: a browser-only HTTP carrier, a runtime bridge owned by another
+layer, workspace selection before composing tasks, and settings that affect later requests without
+restarting the server.
+
+The pinned DSH browser implementation is **not an SSE design**. Its unary calls travel as HTTP
+`POST` requests, while `packages/client/connection/src/client/web-api-client.ts` opens two
+server-to-browser, downlink-only WebSockets at `/api/events.mux` and `/api/events.host`. The generic
+API-proxy fetch carrier also supports SSE, but the browser subclass overrides those event streams
+with WebSockets. Orion deliberately chooses a smaller transport for v0.3.0: JSON `POST`/mutation
+requests plus one replayable SSE downlink. This is a product decision, not a claim that DSH uses the
+same carrier.
+
+Orion does not copy DSH source or branding and does not adopt its public plugin composition model.
+The existing Orion boundaries remain authoritative: Model, Skills, MCP, Tools, TaskContext,
+Goal/Evidence and the single `ThreadRuntimeV1` execution path.
+
+## 3. Architecture
+
+```text
+Browser (React/Vite)
+  -> same-origin JSON command/query API
+  -> SSE event stream with durable cursor
+Loopback Web Host (node:http)
+  -> WebWorkbenchController
+  -> AgentRuntimeController / OrionSessionRunnerV1
+  -> OrionRuntimeV1 / ThreadRuntimeV1
+  -> existing Session, Goal, config, Skill and MCP stores
+```
+
+### Host and transport
+
+- `orion web [--port <0-65535>] [--no-open] [--cwd <directory>]` binds only `127.0.0.1`;
+  port `0` selects an OS port.
+- Static assets and `/api/v1/*` use one origin. There is no CORS response and no network bind
+  option in v0.3.0.
+- Queries and commands use JSON HTTP. Live renderer-neutral events use SSE so reconnects can carry
+  an acknowledged cursor without adding a second socket command protocol.
+- Every mutation, including workspace/session transitions, settings changes and runtime commands,
+  has a client-generated `requestId`. A bounded result cache keyed by both `requestId` and request
+  digest makes exact retries idempotent for the lifetime of the server process; reuse with a
+  different body returns `409 Conflict`. Accepted IDs are never evicted: after 4,096 distinct
+  mutations the Host fails new IDs closed with `503 mutation_capacity_exhausted` until restart,
+  instead of risking duplicate side effects.
+- Every runtime command also carries `expectedSessionId`. The Host compares it with the active
+  Session in the same synchronous admission step as dispatch; a concurrent Session transition or
+  mismatch returns `409 active_session_changed`/`runtime_busy` without executing or replaying the
+  command.
+- Settings are a compare-and-swap resource. Reads return `revision`; writes carry both `requestId`
+  and `expectedRevision`, and a stale revision returns `409 Conflict` without applying any field.
+- Durable events have increasing cursors and are replayed after reconnect. Ephemeral deltas may be
+  coalesced; the next durable transcript state repairs any missed delta.
+- Every event envelope includes `sessionId` and `threadId`. Runtime events require both keys but
+  allow either value to be `null` before a session/Thread exists; committed Thread events require
+  both identities to be non-null.
+- Collection reads use bounded, revision-bound keyset pagination. The opaque cursor binds route
+  scope, the complete ordered collection digest and the last stable item key. If the collection
+  changes, the Host returns `409 collection_cursor_stale`; the browser reloads page one instead of
+  risking duplicate or skipped items. These cursors are distinct from the monotonically increasing
+  numeric SSE cursor.
+
+### HTTP read and mutation surface
+
+| Surface      | Contract                                                                     | Notes                                                                   |
+| ------------ | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| Workspaces   | `GET /workspaces`, `POST /workspaces/activate`                               | Cursor-paged read; activation has `requestId`                           |
+| Sessions     | `GET/POST /sessions`, `POST /sessions/{id}/activate`, `PATCH /sessions/{id}` | Every write has `requestId`                                             |
+| Recovery     | `GET /sessions/{id}/snapshot`                                                | Cursor-paged TranscriptPage plus Thread and SSE recovery state          |
+| Skills       | `GET /skills`                                                                | Cursor-paged safe `SkillDescriptorV1` metadata only                     |
+| MCP          | `GET /mcp`                                                                   | Cursor-paged runtime summaries; no command, URL, headers or credentials |
+| Tool details | `GET /tool-details`, `GET /tool-details/{callId}`                            | Active-workspace summaries and byte-paged redacted output               |
+| Settings     | `GET/PATCH /settings`                                                        | Revisioned snapshot and `expectedRevision` CAS                          |
+| Runtime      | `POST /commands`, `GET /events`                                              | Idempotent mutations plus one replayable SSE stream                     |
+
+The session snapshot follows `WebSessionSnapshotV1` exactly: nullable `threadId`, independent
+`threadCursor` and `eventCursor`, optional `projectionDigest`/`activeTurnId`, `threadStatus`, a
+cursor-paged `TranscriptPage`, the runtime view, pending approvals, nullable TurnCommit Goal and
+three-field Plan projections, and `recoveryDiagnostics`. A legacy snapshot has `threadId: null` and
+`threadStatus: legacy`; the Web client must not synthesize a Thread identity. A v2 transcript cursor
+binds the Thread identity and immutable transcript-manifest revision. A newer Thread makes an older
+cursor fail with `409 transcript_cursor_stale`, requiring a fresh tail snapshot.
+
+Tool details are workspace/project-scoped because the current artifact metadata records artifact
+identity, tool name and byte size but no `sessionId`. The API resolves only against the active
+workspace and never exposes the artifact path. Byte ranges address a pre-sanitized derivative,
+never the raw artifact, so an arbitrary offset cannot skip a sensitive-field label. The API still
+cannot claim or prove that an artifact belongs to a particular session. Session-scoped routes
+require a future provenance-bearing artifact format and are not part of the v0.3.0 contract.
+
+### 2026-08-29 — long-session paging closure
+
+- Added a persisted, digest-bound Thread head and immutable transcript page manifest. A healthy
+  fresh-process v2 snapshot reads the requested page directly and does not reopen the full
+  projection or replay the JSONL log; missing, stale or corrupt derived state falls back to one
+  authoritative rebuild.
+- The browser now loads one bounded page for Workspaces, Sessions, Skills, MCP and tool-detail
+  summaries. Additional pages require an explicit user action; it no longer drains every page into
+  memory during bootstrap.
+- Collection continuations and transcript continuations now have separate stale-cursor contracts,
+  both fail closed with 409, and both have Host/client/reducer regression coverage.
+- The verification figures below predate this storage evolution. A fresh exact-tarball browser and
+  Node 22/24/26 release matrix must be generated before this newer candidate can be called complete.
+
+### Runtime ownership
+
+- The Web host constructs the same `OrionCodeUiRuntime`, `AgentRuntimeController`,
+  `OrionSessionRunnerV1` and `OrionRuntimeV1` composition used by interactive CLI surfaces.
+- The host projects typed `AgentRuntimeEvent` values into a versioned Web envelope. Presentation
+  code never parses terminal text to recover tool, approval, Goal or diagnostic state.
+- The latest valid `TurnCommitV1` is the sole authority for committed Goal state and its digest.
+  A legacy Goal sidecar may be read once only as a migration seed when no committed Goal state
+  exists; after the seed is committed, it is never merged with, preferred over, or presented as a
+  second authority. v0.3.0 requires no destructive migration of the old file.
+- Plan projection comes only from the `PlanReceiptV1` bound into `TurnCommitV1`. The Web read model
+  exposes exactly `body`, `returnMode` (`build` or `auto`) and `digest`; it does not invent review,
+  approval, status or step state. A valid Plan turn commits without implementing, then Orion
+  restores `returnMode` and automatically starts a separate execution request after the current
+  turn finishes. No second user message or Web-only approval phase exists.
+- Thread event logs, TurnCommit journals, compact checkpoints and permission grants remain shared
+  durable sources. Browser projections never become an independent write authority.
+- Only one active product runtime owns a selected session. Switching workspace/session drains the
+  old owner before starting or replaying the next one.
+
+### Approval lifetime
+
+- The runtime, not a browser connection, owns each pending approval and its stable request ID.
+  Approval scopes are exactly `once`, `project` and `global`; there is no Web-only `session` scope.
+- Network loss, SSE reconnect, refresh and closing a tab leave the approval pending. A session
+  snapshot and subsequent events re-project it after reconnect; a disconnected browser never
+  implies consent or denial.
+- Explicit user denial resolves the request normally. Runtime abort, process shutdown, forced
+  session/workspace teardown and an unrecoverable approval-owner failure resolve every affected
+  request as denied and fail the waiting tool call closed.
+
+### Security boundary
+
+- A random per-process nonce is returned by the same-origin `/api/v1/bootstrap` handshake. Mutating
+  requests require it in `X-Orion-Web-Nonce`; the value is never written to disk or logs.
+- Mutations require an exact loopback Origin. Requests with missing/foreign Origin, invalid content
+  type or oversized bodies fail closed.
+- Responses set CSP, `frame-ancestors 'none'`, `X-Content-Type-Options: nosniff`, no-store API
+  caching and conservative referrer policy.
+- Browser payloads expose configured provider/model metadata but never API keys, authorization
+  headers, environment values or raw secret-bearing config.
+- Workspace paths are canonical real directories. Session selection is permitted only when its
+  canonical project matches the active workspace; file activity remains constrained by the
+  existing ToolGateway and workspace-containment policies.
+
+## 4. Workbench experience
+
+The desktop layout uses a workspace/session rail, a central transcript and composer, and a details
+inspector. On narrow screens the rails become accessible dialogs/drawers without removing features.
+
+- **Workspace/session rail:** current canonical workspace, recent sessions, search, new session,
+  resume and rename; active/running/Goal badges.
+- **Transcript:** Markdown messages, streamed reasoning, structured tool cards, commands, MCP,
+  subagents, research, edits, errors and compact lifecycle. Long output is collapsed with a safe
+  plain-text expansion.
+- **Composer:** BUILD/PLAN/AUTO selector backed by `set_agent_mode` with explicit `agentMode`
+  (`interactive`, `plan` or `auto`), multiline prompt, submit, steer/follow-up while running,
+  interrupt, queue display and keyboard shortcuts.
+- **Approval sheet:** tool identity, reason, sanitized arguments and allow/deny for once/project/
+  global. Refresh, disconnect or closing the tab preserves pending requests; runtime abort or
+  shutdown denies them fail-closed.
+- **Inspector:** committed Goal state and evidence; the Plan receipt's body, return mode and digest;
+  context pressure, token/cost statistics, current model/effort, Skills/MCP catalog state,
+  verification and Harness diagnostics. It has no synthetic Plan review, status or steps.
+- **Settings:** model and effort selection plus tool-confirmation policy. Secret entry is excluded
+  from v0.3.0; credentials stay in Orion configuration/environment and only configured status is
+  shown.
+- **Recovery states:** reconnecting, replaying, unavailable model, damaged session, command
+  rejected/busy, approval expired and server shutdown are explicit states with safe recovery
+  actions.
+
+Accessibility is part of the release gate: semantic landmarks, labelled controls, visible focus,
+keyboard-complete composer/dialogs, reduced motion, status live regions and WCAG AA contrast.
+
+## 5. Delivery phases
+
+1. **Reference and contract:** pin/audit DSH source, commit this plan and the OpenAPI contract, and
+   add shared Web wire types with validators.
+2. **Runtime bridge:** extract the product bootstrap into a reusable composition root; implement
+   workspace/session lifecycle, Goal/Plan TurnCommit projections, idempotent mutations, settings
+   CAS, approval recovery, paginated read models and event replay.
+3. **Loopback host:** implement routing, static serving, SSE, nonce/Origin/body limits, health and
+   graceful shutdown.
+4. **Workbench client:** build the responsive React application and all required runtime panels,
+   using only contract-derived API types.
+5. **Distribution:** add `orion web`, Web build/copy scripts, npm file manifest, version reporting,
+   README/CHANGELOG/migration notes and release receipt coverage.
+6. **Verification:** run protocol, security, runtime parity, browser workflow, build, full Jest,
+   lint, coverage, tarball and clean-install smoke gates. Record failures and repairs in this file.
+
+## 6. Release gates
+
+v0.3.0 is `GO` only when every completion requirement has direct evidence; no Web path can bypass
+ToolGateway approval/sandbox policy; every mutation proves `requestId` replay behavior; settings
+prove stale-revision rejection; refresh/reconnect neither duplicates a mutation nor resolves a
+pending approval; abort/shutdown deny pending approvals; Goal and Plan projections match the latest
+valid TurnCommit; API secrets are absent from captured browser traffic; and one packed tarball
+passes `orion web` on every supported Node major version. A successful local frontend build alone
+is not a release result.
+
+## 7. Delivery record
+
+This section is append-only during implementation. Record the final DSH paths inspected, contract
+changes, implementation milestones, failed gates and repairs, exact verification commands, tarball
+identity and the final release decision.
+
+### 2026-08-27 — reference audit and contract closure
+
+- Confirmed the pinned DSH browser carrier in
+  `packages/client/connection/src/client/web-api-client.ts`,
+  `packages/client/connection/src/websocket-downlink.ts` and
+  `packages/client/connection/src/api-path.ts`: HTTP POST upstream plus two downlink-only
+  WebSockets. The generic API-proxy SSE carrier is not the browser-selected implementation.
+- Cross-checked Orion ownership and safe read fields against `src/runtime/turn-commit.ts`,
+  `src/runtime/thread-ui-adapter.ts`, `src/runtime/tool-detail-repository.ts`,
+  `src/runtime/skills/types.ts` and `src/runtime/mcp/types.ts`.
+- Closed the API contract around paginated read models, request idempotency, settings CAS,
+  TurnCommit-owned Goal/Plan projections, reconnect-safe approvals and a discriminated SSE event
+  union. YAML parsing, all internal `$ref` targets, unique operation IDs, mutation `requestId`
+  requirements, exact Plan fields and event branch scope/UUID fields were checked locally; both
+  documents also pass whitespace-error checks.
+
+### 2026-08-27 — implemented wire-contract reconciliation
+
+- Reconciled the docs with `src/web/protocol.ts`, `src/web/server.ts`,
+  `src/web/workbench-controller.ts` and `src/web/event-hub.ts`: the recovery snapshot now names the
+  exact required and optional fields, runtime-event identities are nullable, and explicit agent-mode
+  selection uses `set_agent_mode` plus `agentMode`.
+- Moved tool-detail reads to active-workspace `/tool-details` routes. The existing project artifact
+  metadata cannot prove session ownership, so neither the plan nor API promises session
+  attribution.
+- Removed the invented Goal state schema; only the TurnCommit authority/digest wrapper is typed and
+  its `state` remains the source-defined opaque JSON value. `ToolDetailPage.nextOffsetBytes` now
+  permits omission or null at end of output.
+
+### 2026-08-27 — implementation and release-candidate closure
+
+- Extracted `createProductUiRuntime` into the shared product bootstrap and connected the Web host
+  to the same `AgentRuntimeController`, `OrionSessionRunnerV1`, `OrionRuntimeV1`, Session/Thread,
+  Goal, ToolDetail, Skill and MCP owners used by the terminal products. Root and child runtimes now
+  rebind from the selected model profile rather than retaining a stale bootstrap model.
+- Added the loopback-only `node:http` host, validated Web wire protocol, process-lifetime mutation
+  idempotency, settings CAS, bounded query/output paging, redacted projections, recovery snapshots,
+  replayable SSE with reset/slow-client behavior, exact Origin/Host/nonce checks and graceful
+  fail-closed shutdown.
+- Added the responsive React/Vite Workbench with workspace/session navigation, transcript and
+  composer, BUILD/PLAN/AUTO, follow-up/interrupt, approval dialogs, Goal/Plan projections, paged
+  tool output, settings, Skill/MCP catalog and diagnostics. The client obtains a snapshot before
+  opening SSE and reconnects from `eventCursor`, preventing snapshot/event startup races.
+- Added `orion web`, npm Web asset packaging, v0.2.2 migration guidance, English/Chinese usage,
+  changelog entries, CI browser coverage and packaged-runtime Web probes. React stays a build-only
+  dependency because the published browser bundle is self-contained.
+- Applied the accessibility audit to the actual rendered application. Semantic landmarks,
+  dialog/drawer labels, focus and Escape behavior, live status, `aria-expanded`/`aria-controls`,
+  reduced motion and contrast tokens were repaired; the real Chrome + axe WCAG 2.2 AA journey
+  reports zero blocking and zero non-blocking violations.
+
+### Failed gates and repairs
+
+- The first full Jest run used the then-unsupported Node 26 against native modules built for
+  Node 24. The rerun proved this was an ABI/environment mismatch. The current compatibility
+  contract supersedes that historical matrix and runs release gates on Node 22.12+/24/26 with an
+  isolated install for each ABI.
+- A later long-lived Node 24 Jest process terminated with a process-level `SIGSEGV` after its early
+  suites passed, while direct native probes remained healthy. To avoid rewriting the shared
+  dependency tree used by long-running Orion processes, the authoritative full regression ran in
+  an isolated Node 22 clean install.
+- Two non-executable benchmark TypeScript modules retained shebangs that `ts-jest` preserved when
+  importing them. Removing those ineffective shebangs restored deterministic importability.
+- Existing architecture/package tests still expected CLI-private bootstrap and a server-only build.
+  They were updated to assert the shared bootstrap and the clean server + client build pipeline.
+- Dependency governance initially treated every React occurrence as the retired Ink renderer.
+  The gate now continues to forbid Ink and runtime React while requiring React 18 and its types only
+  as Web build dependencies.
+- Browser review found a snapshot/SSE startup race, insufficient contrast and incomplete mobile
+  drawer state semantics. Baseline-before-stream ordering, dedicated contrast tokens and explicit
+  drawer ARIA state repaired those failures before the browser gate was accepted.
+
+### Verification result
+
+- `npm run lint`, `npm run build`, `git diff --check`, `npm audit --audit-level=high` and
+  `npm audit --omit=dev --audit-level=high`: pass; production build emits 37 client modules, about
+  230.33 kB JavaScript and 41.03 kB CSS before gzip.
+- Isolated Node 22 `npm ci` full Jest: 281 of 282 suites passed, 3,498 tests passed and 5 skipped;
+  its only failure was the copied test directory intentionally lacking `.git`, which prevented the
+  immutable Phase 0 `git archive` fixture from opening. Re-running that exact remaining suite with
+  the source Git directory bound passed all 12 tests. Together the clean-install regression covers
+  all 282 suites and 3,504 test cases with no product-code failure.
+- `npm run test:web-browser`: loopback health, real session mutation, responsive drawer and Chrome
+  axe journey pass with zero WCAG A/AA/2.1 AA/2.2 AA violations.
+- `npm run release:check -- --allow-dirty --skip-tests`: version/CHANGELOG, ESLint, TypeScript,
+  exact npm pack, clean install, CLI identity/help, native SQLite and packaged Web health/static
+  probes pass. The dirty warning is expected for this uncommitted candidate and includes one
+  pre-existing user-owned plan edit that this implementation did not modify.
+- The exact package name/version is `@orion-agents/orion-code@0.3.0`. Tarball SHA-256 and the
+  Node-major matrix receipts are generated outside the package payload to avoid a self-referential
+  embedded hash; the final release-gate output is authoritative.
+
+### Release decision
+
+The local v0.3.0 source candidate has passed the final PATH-bound Jest and exact-tarball
+Node 22/24/26 matrix. Historical 20/22/24 receipts do not satisfy the current contract. The local
+artifact still records a dirty source tree, so a source-clean commit must generate a new tarball and
+obtain digest-bound remote receipts before publication. This plan does not itself claim a commit,
+push, tag, GitHub Release or npm publication.
+
+### 2026-08-29 — composer dock, recovery and paging quality closure
+
+- The center column is now an explicit header/transcript/composer grid. Transcript history scrolls
+  independently while pending approvals, the follow-up queue and the composer remain in a bounded
+  bottom dock; the mobile Steer action remains reachable. Drafts are keyed by Session, and streaming
+  growth is observed without forcing users who scrolled upward back to the tail.
+- Snapshot recovery now rejects inactive or mismatched Session state, treats `replay_reset` as a
+  terminal barrier, and binds every Session command to the expected active Session. Collection
+  continuations and transcript continuations use separate revision-bound cursors; the browser loads
+  only the first page until the user explicitly asks for more.
+- Large tool output is served only from a pre-sanitized browser derivative. The derivative byte
+  offset is the paging authority, so arbitrary offsets cannot bypass label-based redaction in the
+  raw artifact.
+- The exact local candidate tgz, bound to the receipt stored outside the package payload, passed the
+  complete system Chrome 152 journey, 22/22 scenarios, on Node 22.22.3. The run records
+  `layout.composer_docked=true`, zero console errors/warnings, zero page errors, zero HTTP 5xx, zero
+  secret findings and zero dropped events.
+- The same source passed 289/289 Jest suites and 3,620 tests, with 5 existing platform-conditioned
+  skips. The generated client contains 44 modules (277.19 kB JavaScript and 54.45 kB CSS before
+  gzip).
+
+This remains a dirty local development candidate. A source-clean commit must produce a new SHA and
+obtain the required Node 22/24/26 receipts before push, release tagging or npm publication can be
+described as complete.