Repository navigation
Commit 21e9d44
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
- .changeset
- apps
- pythinker-code
- dist-web
- assets
- src
- cli/v2
- constant
- tui
- banner
- commands
- components/panes
- constant
- controllers
- utils
- utils
- test
- cli
- tui
- commands
- controllers
- utils
- utils
- vscode
- test
- docs
- configuration
- reference
- packages
- acp-server/src
- agent-core-v2
- docs
- src
- agent
- fullCompaction
- loop
- task
- undo
- app
- defaultWorkspace
- sessionManager
- telemetry
- workspace
- features/btw
- os/backends/node-local
- persistence
- backends
- memory
- node-fs
- interface
- session
- agentLifecycle
- sessionActivity
- sessionMetadata
- state
- wire
- workspace
- sessionLifecycle
- workspaceInstance
- test
- agent
- contextMemory
- mcp
- media/tools
- prompt
- task
- app
- defaultWorkspace
- sessionManager
- telemetry
- workspaceAliases
- workspace
- features
- btw
- plan/tools
- harness
- os/backends/node-local
- tools
- persistence/backends/node-fs
- session
- agentLifecycle
- sessionActivity
- sessionMetadata
- subagent
- state
- wire
- workspace
- sessionLifecycle
- workspaceFs
- workspaceInstance
- workspaceMcp
- agent-gateway
- src
- protocol
- routes
- services
- transcript
- transport
- ws/v1
- test
- __snapshots__
- services
- klient/src
- contract/global
- transports/memory
- node-sdk
- src
- config
- v2
- test
- product
- src
- client-configs/node
- session-rating
- common
- node
- test
- protocol/src
- remote-control
- src
- test
- transcript
- src
- contract
- history
- model
- ops
- test
Some content is hidden
Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
131 | 131 | | |
132 | 132 | | |
133 | 133 | | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
| 139 | + | |
| 140 | + | |
| 141 | + | |
134 | 142 | | |
135 | 143 | | |
136 | 144 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | | - | |
| 2 | + | |
3 | 3 | | |
4 | 4 | | |
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.
0 commit comments