mirror of
https://github.com/openclaw/openclaw.git
synced 2026-08-12 21:53:00 -06:00
docs: align prompt-overlay, truncation, and pruning docs with shipped behavior (#121324)
* fix(openai): describe personality as the canonical GPT-5 style toggle The shipped config-schema description told operators and models to prefer agents.defaults.promptOverlays.gpt5.personality, a retired key that config validation rejects and doctor deletes. plugins.entries.openai.config.personality is the only live reader (src/agents/gpt5-prompt-overlay.ts). * docs: align prompt-overlay, truncation-notice, and pruning docs with shipped behavior - teach plugins.entries.openai.config.personality as canonical; retired agents.defaults.promptOverlays noted as rejected/migrated - replace nonexistent agents.defaults.bootstrapPromptTruncationWarning with prose describing the built-in always-on notice - reword session-pruning internal constants as built-in behavior, name the real contextPruning config surface - delete stale/orphan pages (path3 harness for a never-committed script, superseded swarms plan, landed path3 artifact-family scoping note) - fix dead paths in reference/test.md and concepts/typebox.md * docs: describe the embedded truncation notice as compact The embedded runtime injects buildBootstrapPromptWarningNotice, which deliberately omits file names and sizes; per-file diagnostics stay in /context, status, and logs. Addresses ClawSweeper P2 on #121324. * docs: doctor migrates the retired personality key instead of removing it Main landed #121346 mid-flight: doctor --fix now moves agents.defaults.promptOverlays.gpt5.personality into plugins.entries.openai.config.personality when unset.
This commit is contained in:
Peter Steinberger
committed by
GitHub
GitHub
parent
c0e5856181
commit
8ab7ac54e2
@@ -1,168 +0,0 @@
|
||||
---
|
||||
summary: "Design for live Gateway proof of the Path 3 SQLite session/transcript flip"
|
||||
read_when:
|
||||
- You are proving the Path 3 SQLite storage flip against a live Gateway
|
||||
- You need to distinguish expected legacy JSONL drift from runtime failures
|
||||
- You are building or reviewing the agent-driven live SQLite E2E harness
|
||||
title: "Path 3 live SQLite E2E harness"
|
||||
---
|
||||
|
||||
The Path 3 live SQLite E2E harness proves the Gateway is using SQLite as the
|
||||
canonical session and transcript store while legacy JSONL files remain
|
||||
migration input or archive material. It is a maintainer proof harness, not a
|
||||
normal user diagnostic.
|
||||
|
||||
After a Gateway has processed post-migration traffic, legacy JSONL parity is no
|
||||
longer a valid runtime health signal. A healthy migrated Gateway can have
|
||||
SQLite transcript rows that differ from legacy JSONL counts because new turns
|
||||
should advance SQLite only. The live harness must therefore measure Gateway
|
||||
behavior, SQLite row movement, legacy-file quiescence, and log health at each
|
||||
step.
|
||||
|
||||
## Command shape
|
||||
|
||||
The intended live command is:
|
||||
|
||||
```bash
|
||||
node scripts/path3-live-sqlite-e2e.mjs \
|
||||
--url http://127.0.0.1:18789 \
|
||||
--agent main \
|
||||
--session-key agent:main:path3-live-e2e:<timestamp> \
|
||||
--json
|
||||
```
|
||||
|
||||
The command connects to an already running Gateway. It does not start, stop,
|
||||
import, or re-run the migration unless an explicit migration mode is added
|
||||
later. A CI or isolated-local variant can use
|
||||
`test/helpers/openclaw-test-instance.ts`, but the live proof path should inspect
|
||||
the actual operator Gateway and its real per-agent SQLite database.
|
||||
|
||||
## Isolated built-CLI proof
|
||||
|
||||
The built-CLI proof runner seeds an isolated legacy session store, starts the
|
||||
rebuilt Gateway, and proves that startup imports hot legacy sessions into
|
||||
SQLite before runtime reads begin. It must not run `openclaw doctor --fix`
|
||||
before the first Gateway start, because that would prove the manual migration
|
||||
path instead of the upgrade path users receive on first boot after the flip.
|
||||
|
||||
After startup import, the isolated proof may run
|
||||
`openclaw doctor --session-sqlite inspect` and
|
||||
`openclaw doctor --session-sqlite validate` as diagnostic evidence. Those
|
||||
doctor commands are not the migration driver for the startup-upgrade proof.
|
||||
Separate doctor-import scenarios should seed legacy transcript files plus
|
||||
trajectory sidecars and verify doctor archives those artifacts while SQLite
|
||||
remains canonical.
|
||||
|
||||
## Preflight
|
||||
|
||||
Preflight collects a baseline and fails before sending a proof turn if the
|
||||
Gateway is not usable:
|
||||
|
||||
- `GET /health` and Gateway deep status must report a running, reachable
|
||||
Gateway.
|
||||
- The CLI and Gateway versions must match the branch being tested.
|
||||
- The harness records a log cursor for the active Gateway file log.
|
||||
- The harness records per-agent SQLite table counts for `sessions`,
|
||||
`session_entries`, `transcript_events`, `transcript_event_identities`, and
|
||||
`session_routes`.
|
||||
- The harness records `mtime`, `size`, and existence for legacy
|
||||
`sessions.json`, referenced JSONL files, and candidate proof-session JSONL
|
||||
paths.
|
||||
- `lsof -p <gateway-pid>` must show SQLite DB/WAL/SHM handles and no hot
|
||||
`.jsonl` or `sessions.json` handles.
|
||||
|
||||
`openclaw doctor --session-sqlite validate` is informational only in live mode.
|
||||
After post-flip traffic it may report expected drift against legacy files. The
|
||||
harness should use doctor output for classification and migration inventory,
|
||||
not as the runtime pass/fail oracle.
|
||||
|
||||
## Agent-driven scenario
|
||||
|
||||
The live scenario uses a dedicated proof session key and drives the Gateway
|
||||
through public RPC paths wherever possible. One agent turn should be enough to
|
||||
exercise ordinary persistence, but the full proof should cover the 3.1b seams
|
||||
that previously required individual live checks:
|
||||
|
||||
- Ordinary chat turn: create or reuse the proof session, send a real agent
|
||||
prompt, wait for the final assistant result, and verify `chat.history` or
|
||||
equivalent Gateway projection.
|
||||
- Transcript identity: verify the same marker appears in Gateway history and in
|
||||
SQLite transcript rows, including stable event identity rows when present.
|
||||
- Session metadata accessors: read the proof session and selected existing live
|
||||
sessions through Gateway/session accessors and compare them to SQLite rows.
|
||||
- Session patch projection: apply a reversible model/session metadata change on
|
||||
the proof session, then verify the projected row and Gateway response agree.
|
||||
- Compaction checkpoint lifecycle: list, branch, and restore a checkpoint only
|
||||
on the proof session or a synthetic fixture session created by the harness.
|
||||
- Restart recovery: run the safe recovery marker path against a controlled proof
|
||||
session or an isolated test instance; live mode may only run this step when
|
||||
the target session set is explicit and reversible.
|
||||
- Cleanup lifecycle: delete or reset the proof session, then verify SQLite
|
||||
lifecycle rows and archived transcript state.
|
||||
|
||||
Transport-specific seams that cannot be exercised safely on the live operator
|
||||
Gateway, such as WhatsApp or voice-call ingress, should use owner-level runtime
|
||||
probes against the same SQLite contract rather than fake external transport.
|
||||
|
||||
## Per-step assertions
|
||||
|
||||
Each step snapshots before and after state and writes a structured assertion
|
||||
record:
|
||||
|
||||
- SQLite row counts advance only where expected.
|
||||
- Trajectory runtime rows advance for marker-backed proof sessions that record
|
||||
runtime events.
|
||||
- The proof session row has the expected `session_id`, status, timestamps,
|
||||
metadata, and route rows.
|
||||
- Gateway history/session projection matches the SQLite transcript tail.
|
||||
- No proof-session JSONL file is created or modified.
|
||||
- No proof-session `.trajectory.jsonl`, `.trajectory-path.json`, or
|
||||
marker-derived `trajectory/<session>.jsonl` sidecar is created.
|
||||
- Existing legacy JSONL files and `sessions.json` remain unchanged unless the
|
||||
step is explicitly an offline migration or archive operation.
|
||||
- The Gateway process does not open `.jsonl` or `sessions.json` handles.
|
||||
- Logs since the previous cursor contain no `ERROR`, `FATAL`, `SQLITE_`,
|
||||
`no such column`, session-store unavailable, restart-recovery failure, or
|
||||
transcript-reconcile warning unless the scenario explicitly allowlists it.
|
||||
|
||||
The log scan is part of the pass/fail contract. A Gateway that answers health
|
||||
checks but emits SQLite schema errors or repeated transcript reconcile failures
|
||||
is not green for Path 3.
|
||||
|
||||
## Evidence artifact
|
||||
|
||||
The harness should write evidence under `.artifacts/path3-live-e2e/<timestamp>/`
|
||||
and keep it out of git:
|
||||
|
||||
- `summary.json`: command args, Gateway version, result, failed assertion, and
|
||||
artifact paths.
|
||||
- `sqlite-before.json` and `sqlite-after.json`: row counts and selected proof
|
||||
rows.
|
||||
- `legacy-files.json`: legacy file existence, `mtime`, size, and whether each
|
||||
file changed.
|
||||
- `gateway-log-scan.json`: cursor range, matched log lines, and allowlist
|
||||
decisions.
|
||||
- `events.jsonl`: ordered per-step observations suitable for PR proof comments.
|
||||
|
||||
The PR proof should summarize these artifacts instead of pasting full
|
||||
transcripts or private message content.
|
||||
|
||||
## Safety rules
|
||||
|
||||
- Live mode must never re-import legacy JSONL while the Gateway is running.
|
||||
- Live mode must not mutate non-proof sessions except for explicitly selected,
|
||||
reversible repair probes.
|
||||
- Any destructive or broad migration step requires a fresh backup of the
|
||||
affected SQLite DB and legacy session directory.
|
||||
- Backups should be scoped to the touched agent DB/session directory and reused
|
||||
during one proof run to avoid unbounded disk growth.
|
||||
- The cleanup step must leave no proof session, proof JSONL, or modified legacy
|
||||
file behind unless the caller passes `--keep-artifacts`.
|
||||
|
||||
## Passing result
|
||||
|
||||
A passing live run means the Gateway accepted a real agent-driven session flow,
|
||||
all observed canonical state was in SQLite, legacy runtime files stayed
|
||||
quiescent, and log health stayed clean for the measured window. It does not mean
|
||||
legacy JSONL parity remains clean after live traffic; live drift is expected
|
||||
once SQLite is the canonical store.
|
||||
@@ -99,7 +99,7 @@ Test wrapper runs end with a short `[test] passed|failed|skipped ... in ...` sum
|
||||
|
||||
## Control UI, TUI, and extension lanes
|
||||
|
||||
- **Control UI mocked E2E:** `pnpm test:ui:e2e` runs the Vitest + Playwright lane that starts the Vite Control UI and drives a real Chromium page against a mocked Gateway WebSocket. Tests live in `ui/src/**/*.e2e.test.ts`; shared mocks/controls live in `ui/src/test-helpers/control-ui-e2e.ts`. `pnpm test:e2e` includes this lane. Agent runs default to Testbox/Crabbox, including targeted proof; use `node scripts/run-vitest.mjs run --config test/vitest/vitest.ui-e2e.config.ts --configLoader runner ui/src/ui/e2e/chat-flow.e2e.test.ts` only for an explicit local fallback.
|
||||
- **Control UI mocked E2E:** `pnpm test:ui:e2e` runs the Vitest + Playwright lane that starts the Vite Control UI and drives a real Chromium page against a mocked Gateway WebSocket. Tests live in `ui/src/**/*.e2e.test.ts`; shared mocks/controls live in `ui/src/test-helpers/control-ui-e2e.ts`. `pnpm test:e2e` includes this lane. Agent runs default to Testbox/Crabbox, including targeted proof; use `node scripts/run-vitest.mjs run --config test/vitest/vitest.ui-e2e.config.ts --configLoader runner ui/src/e2e/chat-flow.messaging.e2e.test.ts` only for an explicit local fallback.
|
||||
- **TUI PTY tests:** `node scripts/run-vitest.mjs run --config test/vitest/vitest.tui-pty.config.ts` runs the fast fake-backend PTY lane. `OPENCLAW_TUI_PTY_INCLUDE_LOCAL=1` or `pnpm tui:pty:test:watch --mode local` runs the slower `tui --local` smoke, which mocks only the external model endpoint. CI also sets `OPENCLAW_TUI_PTY_USE_BUILT_CLI=1` after building `dist/`; use that flag only when exact-head built artifacts already exist. Assert stable visible text or fixture calls, not raw ANSI snapshots.
|
||||
- `pnpm test:extensions` and `pnpm test extensions` run all extension/plugin shards. Heavy channel plugins, the browser plugin, and OpenAI run as dedicated shards; other plugin groups stay batched. `pnpm test extensions/<id>` runs one bundled plugin lane.
|
||||
- Source files with sibling tests map to that sibling before falling back to wider directory globs. Helper edits under `src/channels/plugins/contracts/test-helpers`, `src/plugin-sdk/test-helpers`, and `src/plugins/contracts` use a local import graph to run importing tests instead of broad-running every shard when the dependency path is precise.
|
||||
|
||||
Reference in New Issue
Block a user