Skip to content

REPORT.md

Latest commit

 

History

History
188 lines (151 loc) · 12.2 KB

REPORT.md

File metadata and controls

188 lines (151 loc) · 12.2 KB
Raw

W4 Drafts UX implementation report

Outcome

Implemented the complete drafts UX on top of the landed ownership, visibility, membership, and person-filter machinery.

  • New-session creation can start atomically as visibility: "draft"; the initial durable session entry carries draft visibility before the create response or any session-change broadcast.
  • The create affordance is exposed only when the hello policy allows drafts and the Gateway reports at least two canonical, non-merged sharing identities. Older gateways and solo mode fail closed by hiding the control.
  • Own drafts keep normal row emphasis with a subtle ghost marker. Admin-visible drafts owned by someone else use the same draft class family with a faded, light/dark-safe treatment.
  • A dedicated Publish draft header menu item calls the existing visibility callback with "shared", which continues through the landed session.visibility.set RPC, audit-line, rollback, and live-event path.
  • Multi-user and sharing configuration docs now explain create-as-draft behavior, admin visibility, and the non-security-boundary constraint.
  • No suggestion queue, invite link, config key, SQLite schema/table/version, membership enforcement, new Gateway event, or changelog change was added.

Files changed

Protocol and Gateway

  • packages/gateway-protocol/src/schema/sessions-create.ts
  • packages/gateway-protocol/src/schema/sessions-create.test.ts
  • packages/gateway-protocol/src/schema/frames.ts
  • src/gateway/session-create-service.ts
  • src/gateway/server-methods/sessions-create.ts
  • src/gateway/server/ws-connection/connect-hello.ts
  • src/gateway/server.sessions.create.test.ts
  • src/gateway/server.auth.default-token.suite.ts
  • apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift

The Kotlin generators ran successfully; their tracked outputs were byte-identical. dist/protocol.schema.json is generated locally by protocol checks but remains ignored and untracked, matching origin/main.

Control UI

  • ui/src/pages/new-session/new-session-page.ts
  • ui/src/pages/new-session/create-params.ts
  • ui/src/pages/new-session/create-params.test.ts
  • ui/src/pages/new-session/catalog-target.ts
  • ui/src/pages/new-session/target-controls.ts
  • ui/src/pages/new-session/target-controls.test.ts
  • ui/src/pages/chat/components/chat-session-sharing.ts
  • ui/src/pages/chat/components/chat-session-sharing.test.ts
  • ui/src/components/app-sidebar-session-navigation-logic.ts
  • ui/src/components/app-sidebar-session-navigation-logic.test.ts
  • ui/src/components/app-sidebar-session-row-render.ts
  • ui/src/components/app-sidebar-session-types.ts
  • ui/src/styles/components.css
  • ui/src/styles/new-session.css
  • ui/src/i18n/locales/en.ts
  • ui/src/e2e/session-ownership.e2e.test.ts
  • ui/src/test-helpers/control-ui-e2e.ts

Docs

  • docs/concepts/multi-user.md
  • docs/gateway/config-agents.md

Local proof artifacts, not committed

  • .artifacts/control-ui-e2e/drafts-ux/behavior-contract.md
  • .artifacts/control-ui-e2e/drafts-ux/01-sidebar-draft-treatment.png
  • .artifacts/control-ui-e2e/drafts-ux/01-sidebar-draft-treatment-dark.png
  • .artifacts/control-ui-e2e/drafts-ux/02-create-draft-available.png
  • .artifacts/control-ui-e2e/drafts-ux/03-create-draft-selected.png
  • .artifacts/control-ui-e2e/drafts-ux/04-publish-draft-action.png
  • .artifacts/control-ui-e2e/drafts-ux/*.webm

Key decisions and ambiguity resolution

  1. visibility is optional and additive in SessionsCreateParamsSchema. Omission preserves the prior storage shape and projects as shared. New rows reject a disallowed visibility with SESSION_VISIBILITY_DISABLED; keyed adoption is allowed only when the requested visibility exactly matches the existing effective visibility, including after policy changes. Mismatches and in-place resets remain rejected.
  2. The hello policy object now exposes optional allowedSessionVisibilities and hasMultipleSessionSharingIdentities. Current Gateways always populate both. Optional schema fields preserve compatibility with older Gateway/client pairs.
  3. The multi-user boolean comes from canonical non-merged user profiles, not loaded session creators. It reveals only whether the draft UI's two-identity threshold is met, not the exact profile count.
  4. The new-session UI rechecks the hello policy at submit time and clears a checked draft selection as soon as policy/identity availability disappears. A hidden prior choice cannot silently reactivate.
  5. Admin ownership styling compares the session creator id with the current authenticated user id because sharingRole: "admin" intentionally wins over "owner" for administrators.
  6. Promotion remains one existing session.visibility.set call with visibility: "shared"; no parallel publish method, event, audit path, or invite workflow was introduced.
  7. The sidebar's pending unsent-composer showDraft/renderDraftSessionRow machinery was not touched.

Verification

All final code commands below ran against implementation HEAD 0c755a401b47a9c12f61d8a01b49017f3f938e2d, rebased onto 977db1c83261b13e92e7ad74c5f544e61acf1b90. origin/main advanced by six commits during the final proof; no further moving-base rebase was attempted after the successful gate.

Install and formatting

  • pnpm install
    • Initial fresh install: exit 0, 1,272 packages, pnpm 11.2.2.
    • Final post-rebase refresh: exit 0 using pnpm 11.15.1; lockfile supply-chain policies passed and 285 packages were refreshed.
  • ./node_modules/.bin/oxfmt --write --threads=1 <changed files>
    • Exit 0. The final changed gate reported All matched files use the correct format.
  • git diff --check origin/main...HEAD
    • Exit 0, no output.

Focused Vitest and browser behavior

  • node scripts/run-vitest.mjs packages/gateway-protocol/src/schema/sessions-create.test.ts ui/src/pages/new-session/create-params.test.ts ui/src/pages/new-session/target-controls.test.ts ui/src/pages/chat/components/chat-session-sharing.test.ts ui/src/components/app-sidebar-session-navigation-logic.test.ts
    • Exit 0.
    • Gateway-client shard: 1 file, 2 tests passed.
    • UI shard: 4 files, 21 tests passed.
    • Final wrapper: passed 2 Vitest shards in 7.32s.
  • node scripts/run-vitest.mjs src/gateway/server.sessions.create.test.ts
    • Exit 0: 1 file, 67 tests passed; final wrapper passed 1 Vitest shard in 22.51s.
    • Covers omitted visibility -> shared projection, draft visibility on the first list, disabled new drafts, matching keyed adoption, mismatched adoption rejection, and exact retry after policy disable.
  • node scripts/run-vitest.mjs src/gateway/server.auth.default-token.test.ts
    • Exit 0: 1 file, 23 tests passed; final wrapper passed 1 Vitest shard in 6.49s.
  • node scripts/run-vitest.mjs run --config test/vitest/vitest.ui-e2e.config.ts --configLoader runner ui/src/e2e/session-ownership.e2e.test.ts
    • Exit 0: 1 file, 7 tests passed in 5.75s.
    • Proves multi-person availability, solo dormancy, atomic sessions.create traffic, own/foreign sidebar treatment, light/dark rendering, one-call publish, and clearing a selected draft mode after policy becomes unavailable.

Required typechecks

  • OPENCLAW_HEAVY_CHECK_LOCK_SCOPE=worktree node scripts/run-tsgo.mjs -p tsconfig.core.json
    • Exit 0, no diagnostics.
  • OPENCLAW_HEAVY_CHECK_LOCK_SCOPE=worktree node scripts/run-tsgo.mjs -p tsconfig.ui.json
    • Exit 0, no diagnostics.
  • OPENCLAW_HEAVY_CHECK_LOCK_SCOPE=worktree node scripts/run-tsgo.mjs -p tsconfig.extensions.json
    • Exit 0, no diagnostics.
  • OPENCLAW_HEAVY_CHECK_LOCK_SCOPE=worktree node scripts/run-tsgo.mjs -b tsconfig.projects.json
    • Exit 0, no diagnostics.

Protocol and localization

  • pnpm protocol:gen
    • Exit 0; wrote the local ignored dist/protocol.schema.json without adding it to Git.
  • pnpm protocol:gen:swift
    • Exit 0; wrote GatewayModels.swift.
  • pnpm protocol:gen:kotlin
    • Exit 0; wrote both Kotlin generator targets, with no tracked diff.
  • pnpm protocol:check
    • Exit 0; regenerated JSON/Swift/Kotlin and printed protocol since guard passed: 0 new core methods use train 2026.7.
  • node --import tsx scripts/control-ui-i18n-verify.ts baseline
    • Exit 0: raw-copy: baseline entries=105, source: keys=3968.
  • node --import tsx scripts/native-app-i18n.ts baseline --write
    • Exit 0: entries=5232 changed=true; the diff contained only unrelated current-main iOS source-line shifts and was discarded rather than added to W4.

Docs and changed gate

  • pnpm docs:check-mdx
    • Exit 0: Docs MDX check passed (751 files, 3308ms).
  • pnpm check:changed
    • Delegated to Testbox tbx_01ky81kpwnmn9y6xdzg7jmf99k, Actions run 30031143438.
    • Final wrapper: exitCode: 0, runStatus: succeeded, command 25m24.264s, total 25m26.417s; the one-shot Testbox stopped successfully.
    • Ran the actual 30-file W4 lanes: ratchets, formatting, API/plugin boundaries, UI i18n, core/core-test/UI typechecks, all core/UI/packages lint shards, macOS CI test shards, native state schema guard, database-first guards, and import cycles.
    • Final import-cycle result: 0 runtime value cycle(s).

Autoreview

  • Branch command: .agents/skills/autoreview/scripts/autoreview --mode branch --base 977db1c83261b13e92e7ad74c5f544e61acf1b90 --stream-engine-output.
  • Accepted and fixed:
    • replaced the exact global profile count with privacy-preserving hasMultipleSessionSharingIdentities;
    • cleared stale checked draft state when policy/identity availability disappears;
    • preserved matching keyed-create adoption retries;
    • preserved those exact retries after the drafts policy is disabled while still rejecting every genuinely new disabled draft.
  • Rejected after direct verification:
    • native binding drift: pnpm protocol:check regenerated all outputs cleanly; HelloOk.policy is intentionally an untyped map in Swift/Kotlin, so policy keys do not produce native field diffs;
    • unkeyed policy bypass: createSessionEntryWithTranscript owns generated and explicit keys, and the 67-test suite proves unkeyed disabled drafts remain rejected.
  • Final branch result: autoreview clean: no accepted/actionable findings reported, overall confidence 0.94.

LOC summary

Implementation diff before adding this report, grouped by role and excluding generated/docs from production:

Group Added Deleted
Production 192 18
Tests and test support 562 1
Generated Swift 4 0
Docs 5 1

The generated total contains only the tracked Swift protocol model. The JSON schema is deliberately excluded because it is ignored and untracked on origin/main.

Commits

  • ce0ac10f6af feat(protocol): support draft session creation
  • c73b1076dae feat(ui): add draft session workflows
  • 4b3215e3818 docs: explain multi-user drafts
  • afcb60ba214 test(ui): tighten draft ownership fixture
  • d415bd43305 test(ui): satisfy draft E2E lint
  • 9403a9fa1f9 test(ui): keep draft fixtures strictly typed
  • 7eb3abb54da test: strengthen draft compatibility coverage
  • d91a15034c2 fix: harden draft availability policy
  • 4705acfd2e3 test(ui): type draft policy mock control
  • 0e0e96f339d fix: preserve keyed draft creation retries
  • 0c755a401b4 fix: keep disabled draft retries idempotent

Skipped or deferred

  • No push, pull request, scripts/pr, release, publish, CHANGELOG.md, or GitHub mutation was performed.
  • No SQLite change was needed; therefore there was no schema-version bump or lazy table ensure.
  • No new Gateway event was added; existing sessions.changed and session.sharing paths retain their current scope guards and draft filtering.
  • Foreign-language UI bundles were not edited; the requested en.ts plus baseline workflow was used.
  • dist/protocol.schema.json is absent from branch history and git ls-files, while final status reports it only as !! dist/protocol.schema.json after generation. Swift and both Kotlin targets were verified with git cat-file -e origin/main:<path>; no state-generated files changed.
  • Final branch status after proof: feature work is committed and the tracked worktree is clean. origin/main advanced by six commits after the successful gate; no push or further moving-base chase was performed.