# QianjiangClaw Progress Summary

Updated: 2026-03-24

## 1. Project Goal

Current practical goal:

- Keep the desktop app as the main Windows client while moving from technical PoC to real deliverable integration.
- Use Electron plus React plus TypeScript plus pnpm workspace.
- Keep `Renderer -> preload -> Electron Main -> GatewayClient / RuntimeManager / cloud clients` as the stable boundary.
- Ship a bundled OpenClaw runtime inside the installer so the desktop app becomes the single user-facing entry point.

The practical end goal is:

- user installs one Windows app
- user binds an OpenClaw employee `api_key`
- app fetches runtime configuration from cloud
- app generates local managed runtime config automatically
- app starts bundled OpenClaw runtime locally
- app reports runtime liveness and events back to cloud
- user can use the installer without manually filling provider, model, base_url, or vendor model api_key

## 2. Current Stage

Current stage should now be treated as:

- Stage A: complete
- Stage B: complete
- Stage C technical PoC: complete
- Stage D formal delivery: started, but not complete

Practical interpretation:

- installer generation works
- installer bundled-runtime smoke works
- desktop app can carry and launch bundled runtime on this machine
- real runtime cloud config integration for `openclaw-employee-config` is implemented
- runtime cloud supervisor is implemented for heartbeat, config sync, and event flush
- bundled runtime now includes a preinstalled Python layer for core table/document/web/config tasks
- diagnostics and smoke now expose runtime cloud telemetry
- installer can now be treated as trial-usable, but not yet as a final stable delivery

## 3. What Has Been Completed

### 3.1 Desktop architecture and local runtime path

Completed:

- Electron plus React plus TypeScript desktop app is working
- preload and IPC boundary is in place
- real local Gateway integration works
- sessions, history, chat.send, diagnostics export, and keytar-backed secrets are implemented
- bundled runtime detect, start, stop, restart, health, and tail logs are implemented

### 3.2 Installer and bundled runtime PoC

Completed:

- NSIS installer is generated at `dist/installer/QianjiangClaw-Setup-0.1.0.exe`
- installer smoke passes
- installer bundled-runtime smoke passes
- installer includes `vendor/openclaw-runtime` as extraResources
- generated installer can launch bundled runtime and connect bundled Gateway in the current verification environment

### 3.3 Bundled Python runtime payload

Completed in code and packaging:

- bundled runtime now materializes a Python runtime under `vendor/openclaw-runtime/python`
- the payload includes the first locked dependency set for built-in Skills:
  - `openpyxl`
  - `pandas`
  - `requests`
  - `beautifulsoup4`
  - `lxml`
  - `pypdf`
  - `python-docx`
  - `charset-normalizer`
  - `pyyaml`
- runtime readiness now requires Node/OpenClaw files plus Python payload plus import self-check
- bundled runtime smoke now asserts `pythonReady = true`
- installer smoke now validates the packaged Python payload and imports the locked package set directly from `resources/vendor/openclaw-runtime/python`

### 3.4 Product UI baseline

Completed:

- desktop product UI is in place
- workspace page prioritizes account summary, current skill, execution policy, chat, and session flow
- diagnostics page includes Gateway, bundled runtime, logs, installed paths, runtime cloud, and export snapshot
- settings page hosts runtime credential binding for OpenClaw employee `api_key`
- runtime cloud telemetry status is visible in diagnostics

### 3.5 Runtime cloud configuration integration

Completed in code:

- `OpenClawConfigClient` is implemented around `POST /openclaw-employee-config`
- the desktop app stores employee `api_key` in `SecretManager/keytar`
- the settings flow can save the runtime cloud base URL and employee `api_key`
- bundled runtime startup is now driven by cloud-fetched config instead of only the old local PoC path
- the returned payload is normalized into managed runtime config before runtime startup
- diagnostics now include runtime cloud config status

Implemented runtime-cloud behavior:

- if employee `api_key` is missing, runtime stays unconfigured and should not auto-start as usable
- if `POST /openclaw-employee-config` succeeds, the app extracts runtime-critical fields such as:
  - `llm.provider.base_url`
  - `llm.provider.api_key`
  - `llm.model_id`
  - `config_version`
  - runtime heartbeat/events endpoints
- those values are merged into the local managed runtime config used by bundled OpenClaw
- runtime config sync is now implemented with a periodic `action: "sync"` flow
- sync results update runtime cloud status and runtime telemetry state

### 3.6 Runtime cloud heartbeat, events, and telemetry

Completed in code:

- `RuntimeCloudSupervisor` is implemented in Electron Main as the runtime cloud orchestrator
- `POST /openclaw-heartbeat` is implemented and scheduled through the supervisor
- `POST /openclaw-employee-events` is implemented with in-memory queueing and batch flush
- runtime cloud event production is wired into desktop lifecycle and chat flow
- runtime telemetry is exposed through preload/IPC as `runtimeTelemetry.getStatus()`
- diagnostics export includes `runtimeTelemetry`
- smoke validates runtime telemetry instead of only runtime startup

Implemented event/telemetry behavior:

- heartbeat loop runs independently of local runtime health and does not stop bundled runtime on cloud failure
- config sync loop runs independently and records changed/unchanged state into telemetry
- event queue batches and flushes runtime cloud events without blocking desktop chat flow
- the current core event set includes:
  - `startup`
  - `message_received`
  - `message_sent`
  - `error`
  - `config_updated`
  - `shutdown`
- runtime telemetry currently records:
  - heartbeat success/error and last billing summary
  - config sync success/error
  - queued and accepted event counts
  - message/error counters
  - current config version

### 3.7 Real cloud endpoint verification

Verified:

- the real endpoint `https://xuphfkscoptnjoaecbvn.supabase.co/functions/v1/openclaw-employee-config` responds successfully with a real employee `api_key`
- the response contains runtime-critical fields including:
  - `config_version`
  - `llm.provider.base_url`
  - `llm.provider.api_key`
  - `llm.model_id`
  - `endpoints.heartbeat`
  - `endpoints.events`

This means the project is no longer only using mock contract data for runtime configuration.

### 3.8 Current verification result

Verified in the latest local acceptance pass:

- `corepack pnpm typecheck` passes
- `corepack pnpm build` passes
- `build/scripts/electron-smoke.ps1` passes
- smoke confirms bundled runtime is running in `bundled-runtime` mode
- smoke confirms the packaged Python payload contains the 9 locked dependencies
- smoke confirms runtime telemetry records heartbeat, config sync, and accepted runtime cloud events

### 3.9 Frontend refactor progress

Completed in the current frontend refactor pass:

- sidebar composition is extracted from `App.tsx` into `apps/ui/src/features/shell/AppSidebar.tsx`
- `AppSidebar` now composes `Sidebar`, `ExpertTree`, and `SessionList`
- expert category config and matching logic now live in `ExpertTree`
- `App.tsx` no longer inlines sidebar nav, expert tree, or session list JSX
- confirmed-unused legacy sidebar/expert CSS rules were removed
- current `App.tsx` size is about 4178 lines, so the sidebar split is complete but further reduction is still needed

Verified:

- `corepack pnpm --filter @qjclaw/ui typecheck`
- `corepack pnpm build`
- `corepack pnpm smoke:settings`
- `corepack pnpm smoke:default-chat`
- `corepack pnpm smoke:desktop-session-switch-stream`
- `corepack pnpm smoke:desktop-expert-bootstrap-ui`

## 4. Current Product Decision

The current Stage D product decision is:

- the installer becomes practically usable only after bundled OpenClaw starts from real cloud-fetched config
- the user must first bind an OpenClaw employee `api_key`
- this `api_key` is the employee identity key used by the runtime cloud API
- this is not the upstream LLM vendor api key
- the desktop app stores this key in `SecretManager/keytar`
- the desktop app calls `POST /openclaw-employee-config` with `{ api_key, action: "init" }`
- the returned payload is turned into local managed runtime config before bundled runtime start
- the bundled Python payload is part of the formal runtime contract, not a first-run dynamic install path
- Electron Main owns runtime cloud orchestration for config sync, heartbeat, and events

Current runtime endpoints from the cloud document are:

- `POST /openclaw-employee-config`
- `POST /openclaw-heartbeat`
- `POST /openclaw-employee-events`

At this moment:

- `POST /openclaw-employee-config` is implemented and verified
- `POST /openclaw-heartbeat` is implemented
- `POST /openclaw-employee-events` is implemented
- runtime cloud config sync is implemented
- runtime telemetry is implemented and exported through diagnostics/smoke

## 5. What Is Still Missing

### 5.1 Final stable installer usability is still not complete

Not complete yet:

- installer usability has moved beyond pure PoC, but still needs more real-world validation
- long-running real task execution stability still needs verification
- final product-side account, credits, and Skills production integration is still incomplete

### 5.2 Runtime-side cloud follow-up is still pending

Not complete yet:

- broader runtime event coverage beyond the current core set
- stronger runtime error recovery and offline replay strategy
- production-grade hot-update behavior after config sync changes
- more real-world acceptance for long-running heartbeat/events stability

### 5.3 Product-side cloud integration is still pending

Later work still pending:

- real login/session production integration
- real profile production integration
- real credits production integration
- real Skills production integration
- final model-policy production integration

## 6. Most Important Current Conclusion

The project is no longer primarily blocked on installer packaging or local runtime control-plane work.

The current state is:

- installer exists
- bundled runtime exists inside the installer
- user-bound employee `api_key` can now drive real runtime cloud configuration
- `openclaw-employee-config` can return the real `base_url`, provider `api_key`, and `model_id` needed by OpenClaw
- the desktop app can use those values to generate managed runtime config automatically
- the installer now carries a preinstalled Python layer for the first batch of built-in Skills
- runtime cloud supervisor now keeps heartbeat, config sync, and event flush running in Electron Main
- diagnostics and smoke now verify runtime telemetry, not only runtime startup

So the installer is no longer an empty shell.

However, the project is still not a fully finished formal delivery because:

- runtime cloud core APIs are finished, but broader runtime recovery and event coverage are not
- full business-side cloud APIs are not finished
- broader real-world acceptance is still pending

## 7. Immediate Next Work

The next work should happen in this order:

1. keep the bundled Python payload contract stable in future installer builds
2. expand runtime event coverage and improve failure recovery/offline replay
3. run a broader acceptance pass with installer + real employee `api_key` + real task execution
4. continue product-side production API integration for account, credits, Skills, and model policy
5. evaluate whether config sync should trigger stronger runtime refresh behavior
6. only after that treat Stage D as entering broader product delivery work

## 8. Next-Start Checklist

When work resumes next time, start here:

1. read the runtime cloud API source document under `docs/` (the runtime cloud API integration document)
2. read `docs/progress-summary.md`
3. verify `openclaw-employee-config`, `openclaw-heartbeat`, and `openclaw-employee-events` still respond correctly in the target environment
4. verify the bundled Python payload is still present in `vendor/openclaw-runtime/python`
5. verify the packaged Python payload is still present in `dist/installer/win-unpacked/resources/vendor/openclaw-runtime/python`
6. run smoke and confirm runtime telemetry still shows heartbeat/config sync/event acceptance
7. run installer acceptance with a real employee `api_key`
8. expand runtime-side recovery/event coverage where needed
9. then continue the remaining product-side cloud APIs

## 9. Current One-Line Status

Current status: installer, bundled runtime, preinstalled Python payload, runtime cloud config, heartbeat, events, config sync, and runtime telemetry are all working; the app can now auto-fetch OpenClaw runtime config from user-bound employee `api_key`, start bundled runtime, report cloud heartbeat/events, and export diagnostics, but Stage D is still incomplete until broader runtime hardening, product-side cloud APIs, and wider real-world acceptance are finished.

## 10. 2026-05-07 Frontend Refactor Follow-Up

Completed:

- removed `resolveExpertVisualKey` and `buildShortcutPrompt` from `AppSidebar` / `ExpertTree` props; `ExpertTree` now imports the pure helpers directly
- added `ConversationWorkspaceView` to own the chat/expert workspace display composition while keeping stream, composer, session, and smoke logic in `App.tsx`
- moved workspace status chip derivation into `features/shell/startupStatus.ts`
- reduced `App.tsx` to 2672 lines without changing smoke action shapes

Skipped intentionally:

- did not wire `useChatSessionsController`; current local session flow has subtle active-session reset behavior that should be reconciled separately
- did not delete CSS; duplicate selector areas are in the frozen conversation/final theme layers and were not safe to trim in this pass

Verified:

- App encoding check: first bytes `105,109,112`, no UTF-8 BOM
- `rg -n "�" apps/ui/src/App.tsx apps/ui/src/features apps/ui/src/lib`
- `corepack pnpm --filter @qjclaw/ui typecheck`
- `corepack pnpm build`
- `corepack pnpm smoke:default-chat`
- `corepack pnpm smoke:settings`
- `corepack pnpm smoke:desktop-session-switch-stream`
- `corepack pnpm smoke:desktop-expert-bootstrap-ui`
