Skip to content

Commit 21e9d44

Browse files
authored
feat: session occupancy lock, default workspace, and shared session rating rules (#390)
## Requirement or Bug Lock a session to one writer, add a default workspace, share the session rating rules, and fix three session bugs. ## Bug Reproduction Steps 1. Archived session events: archive a session, restore it, then send a prompt from a web client. No more session events arrive for that session. 2. Wedged turn: interrupt a turn so it never ends (kill the process mid-turn), then restart and open the session. The conversation view stops at an old point, and the interrupted turn shows as completed. 3. Two writers: open one session in two clients (TUI and web, or two TUIs) and send from both. Both write to the same session journal, and each client works from a stale copy of the other's turns. ## Root Cause 1. The gateway kept per-session event state after close and archive. A restored session reused the stale state, so new events were not sent. 2. When the transcript is rebuilt, turn ordinals were renumbered locally instead of taken from the wire ids, so later turns landed at the wrong position. A turn that never ended was rebuilt as completed. 3. Nothing stopped a second process from writing to a session another process was writing to. All three are fixes at the root, not workarounds. ## Code Changes **Session lock.** A session can have one writing process at a time. Before a turn, a manual compaction, or a print-mode run, the session run gate takes the lock and checks the session files for changes made by another process. ```diff begin turn / manual compaction / print run + sessionRunGate.begin() + hold lock -> another process holds it: "session occupied" + wire changed on disk -> release, "session stale" run + idle 3 s -> release lock ``` - TUI: "Session in use" dialog with retry and cancel. A stale session is reloaded, then the message is sent again. - Print mode: reloads a stale session once; an occupied session ends with exit code 4 (and an `error` line in `stream-json`). - SDK, ACP, web: get the same two errors from the engine. - `PYTHINKER_CODE_SESSION_LOCK=0` (also `false` / `off`) turns the lock and the stale checks off. Documented in `docs/configuration/env-vars.md`. **Default workspace.** The gateway now accepts a new session without a workspace or `cwd`. It creates and uses `~/PythinkerCode/Default`; `[default_workspace] path` in `config.toml` chooses another folder. ```diff packages/agent-core-v2/src/app/ + defaultWorkspace/ config section, path rules, ensure() packages/agent-gateway/src/routes/sessions.ts + workDir ??= defaultWorkspace.ensure() ``` **Shared session rating rules.** The survey rules move from the CLI into a new private workspace package, so the TUI and the server use the same rules. ```diff + packages/product/ @pymodel/pythinker-code-product (private) + src/client-configs/ config fetch + disk cache + src/session-rating/ eligibility rules, server host apps/pythinker-code/src/utils/ - survey-popup-config.ts moved into packages/product packages/agent-gateway/src/routes/ + sessionRating.ts POST /api/v1/sessions/{session_id}/rating ``` - Client configs are fetched only when `CUSTOM_API_BASE_URL` is set. Without it, no request and no cache read. - The opt-out moves from `tui.toml` to `disable_feedback_survey` in `config.toml`. An existing `tui.toml` value is moved over on the next start. - `packages/product` is in both `flake.nix` workspace lists. **Session events.** The broadcaster drops a session's event state on close and archive. **Transcript.** Rebuilt turns take their ordinals from the wire ids, and a turn without an end record is marked failed. **Other fixes found on the way.** - klient `config.changed` / `config.sectionChanged` dropped every event whose `value` or `previousValue` was undefined; both are now optional. - The engine test harness `flushLog()` did nothing; it now flushes persistence. - Remote Control HTTP tunnel limits can be injected, so tests cover chunking and request limits without large payloads. Defaults do not change. - `AGENTS.md`: review scope rules. - Two gateway errors shared code `40420`; "Expert Talk run not found" moves to `40422`. The new codes are `40939` (default workspace unavailable), `40940` (session occupied) and `40941` (session stale). ## Behavior Changes and Affected Users | Behavior | Before | After | Who relies on the old behavior | Escape hatch | |---|---|---|---|---| | Two processes write to one session (TUI, print mode, web, desktop, SDK, ACP, VS Code) | Both write | Second writer gets "session occupied"; TUI shows retry/cancel, print mode exits 4 | Users who keep one session open in two clients and send from both | `PYTHINKER_CODE_SESSION_LOCK=0` | | Send after another process changed the session | Sent on a stale copy | TUI and print mode reload and resend; other clients get "session stale" | Same as above | `PYTHINKER_CODE_SESSION_LOCK=0` | | New session with no workspace and no `cwd` (gateway REST) | Refused | Created in `~/PythinkerCode/Default` (folder created on first use) | Scripts that expect the request to fail | `[default_workspace] path` sets the folder | | Session rating opt-out | `disable_feedback_survey` in `tui.toml` | `disable_feedback_survey` in `config.toml`; old value moved on next start | Users who edit `tui.toml` by hand | The old key is still read once and migrated | | Session rating config fetch | Fetched from the configured region host | Fetched only when `CUSTOM_API_BASE_URL` is set | Nobody (no hosted endpoint) | n/a | | Events after archive + restore | Stop | Continue | Nobody | n/a | | Interrupted turn after restart | Shown as completed; view stops at an old point | Shown as failed; view current | Nobody | n/a | | `POST /api/v1/sessions/{session_id}/rating` | 404 | Rating action | n/a (additive) | n/a | | klient config-change events with an undefined value | Dropped | Delivered | Nobody | n/a | | Gateway error code for "Expert Talk run not found" | `40420` (shared with `RUNTIME_NOT_FOUND`) | `40422` (gateway and `packages/protocol`) | External scripts or clients that match `40420` to detect a missing Expert Talk run; no consumer in this repository | Match the error `code` string, or `40422` | **Contract files touched** (consumers: desktop and web apps, the inspector, the VS Code extension, ACP clients, SDK users, headless-output parsers): - `packages/agent-core-v2/docs/config-manifest.toml`: new `[default_workspace]` section. Additive. - `apiSurface.snapshot.test.ts.snap`: new rating route. Additive. - `packages/node-sdk/src/index.ts`: exports `ConfigSectionChange`. Additive. - `packages/acp-server/src/session.ts`: maps "session occupied" and "session stale" to `invalidRequest` with a client-action message. - `apps/pythinker-code/src/cli/v2/run-v2-print.ts`: new exit code 4 for an occupied session; the reload notice goes to stderr. **Test coverage** | Row | Tests | |---|---| | Session lock, off switch | `sessionLockService.test.ts`, `sessionRunGate.test.ts` (off switch tests fail without the source change), TUI and print-mode tests | | Default workspace | `defaultWorkspace.test.ts`, gateway `sessions.test.ts`, `workspaces.test.ts` | | Session rating, opt-out move, no fetch without custom base | `packages/product` (275), gateway rating tests, `pythinker-tui-startup.test.ts` | | Archived session events | `sessionEventBroadcaster.test.ts` (fails without the fix) | | Wedged turns | `packages/transcript` (128), gateway transcript tests | | klient events | SDK `onConfigSectionChanged` test | | Tunnel limits | `remote-control.test.ts` (29) | Local gates: build, typecheck, lint (0 errors), sherif, VS Code typecheck, flake workspace check, and `nix build .#pythinker-code` pass. `pnpm test` (two full runs): 18619 passed, 1 timed out under full-suite load each time (`fullCompaction.test.ts` "names truncated compaction responses when retries are exhausted"); that file passes 96/96 alone and the full engine suite passes 6902/6902. ## Checklist - [x] I have read the [CONTRIBUTING](https://github.com/PyModel/pythinker-code/blob/main/CONTRIBUTING.md) document. - [ ] I have linked a related issue (external PRs: issue must have a maintainer's `/approve`). - [x] I have added tests that prove my feature works. - [x] The behavior-change table above is complete, and every removed behavior or flipped default is named in the changeset and either has an escape hatch or was explicitly approved by a maintainer in this PR. - [x] Ran `gen-changesets` skill, or this PR needs no changeset. - [x] Ran `gen-docs` skill, or this PR needs no doc update.
1 parent e291918 commit 21e9d44

231 files changed

Lines changed: 12875 additions & 5327 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@pymodel/pythinker-code": patch
3+
---
4+
5+
Fix session events stopping after a session is archived and restored.

‎.changeset/default-workspace.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@pymodel/pythinker-code": minor
3+
---
4+
5+
New chats started without a project folder now open in `~/PythinkerCode/Default`, which is created on first use; set `path` under `[default_workspace]` in config.toml to use a different folder.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@pymodel/pythinker-code": minor
3+
---
4+
5+
When the same session is open in more than one client, only one can write at a time: sending from a second client now shows a retry/cancel prompt, or reloads changes made elsewhere first and resends your message, and two clients can no longer write to one session at once. Set PYTHINKER_CODE_SESSION_LOCK=0 to allow concurrent writers again.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@pymodel/pythinker-code": patch
3+
---
4+
5+
Move the session rating opt-out from tui.toml to `disable_feedback_survey` in config.toml; an existing tui.toml setting is moved over on the next start.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@pymodel/pythinker-code": patch
3+
---
4+
5+
Fix the conversation view freezing at an old point after restarting when a turn had been interrupted; interrupted turns are now marked as failed instead of shown as completed.

‎AGENTS.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -131,6 +131,14 @@ Gate behind flags. Env: `PYTHINKER_CODE_EXPERIMENTAL_<NAME>` toggles one; `PYTHI
131131

132132
These rules apply to every pull request review, automated or human. The user populations and contract files they refer to are listed in `.agents/skills/review-pr/surfaces.md`.
133133

134+
### Review scope: the PR's diff, not the repo
135+
136+
- Review only the PR's diff against its base. A problem in code the PR does not touch (pre-existing on base) is reported as a non-blocking note, never as a blocking finding — the sole exception is pre-existing code that the PR's behavior directly triggers or amplifies.
137+
- Report a class of issues in one pass: when a finding generalizes to several locations in the diff, list all of them at once instead of raising them across successive rounds.
138+
- No pure style or personal-preference findings. Every finding carries a severity: P0 blocking / P1 should-fix / P2 suggestion.
139+
- Re-reviews are incremental: review only what changed since the previous review; do not restate findings on unchanged code or re-raise resolved threads. Before treating a resolved thread as settled, verify the current code: suppress a finding only when the problem is actually fixed or the finding no longer holds.
140+
- Domain-specific rules keep their own canonical homes — changesets (`.agents/skills/gen-changesets/SKILL.md`), comment-free zones (Coding Rules), PR text (`.agents/skills/write-pr/SKILL.md`); review against those, not ad-hoc taste.
141+
134142
### Enumerate changed behavior, not just bugs
135143

136144
Any input that worked before the change — a config key, env var, CLI flag, provider response shape, session written by an older version, client request, or hook payload — must behave the same after it unless the PR declares the change. For every deleted or narrowed branch, condition, default, or prompt sentence, ask who reached it before and where they go now; for every new condition, ask which existing inputs now match it first. Flag a PR that calls a path "unchanged" when its branch condition moved.
Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
{
2-
"sourceHash": "c074163e25a1c9b444ed60d046af3dfa42a98b029431851d02169c817a5a01f7",
2+
"sourceHash": "734a2fc9eab1704b61003e995895121ab7a081b5f50089ea689528bbc65c9cbb",
33
"sourceFileCount": 501
44
}

apps/pythinker-code/dist-web/assets/CodeBlockNode-Gx3QMVLZ.js renamed to apps/pythinker-code/dist-web/assets/CodeBlockNode-D0W6r4O4.js

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

apps/pythinker-code/dist-web/assets/DesignSystemView-BAgPEsSe.js renamed to apps/pythinker-code/dist-web/assets/DesignSystemView-DWx8o64m.js

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

apps/pythinker-code/dist-web/assets/Tooltip-Bzdkbh8U.js renamed to apps/pythinker-code/dist-web/assets/Tooltip-Bj1LyJqp.js

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)