Skip to content

Commit 2b0baf3

Browse files
authored
fix(agent): write a session file with its first message (plan decision 17) (#25)
* feat(agent): write a session file with its first message (plan decision 17) A new session was a file from session/new on: a header and nothing else. A user who started the TUI and left, left such a file behind. session/list showed it as "(no messages)", and zypi --continue could take it for the latest session. session/new now makes a deferred session (DeferredJsonlSessionStorage, in the harness). It keeps its entries in memory until the first message entry. That entry writes the header, the entries held before it (a model choice, a name, a leaf move) and itself in one go. After that each entry is appended as before. The write comes before the entry is recorded, so a failed write leaves no trace of the message and the next message tries again. A session in which nobody typed has no file: nothing to list, load or continue. Sessions that older versions left with no message keep the title "(no messages)". An id the client chose (--session-id) must stay taken while its session has no file, so the agent keeps the ids of its open sessions in a set. The set leaves an id when the session is closed or deleted, or when the session could not be opened. Another process cannot see that set. So the first prompt of a session with a chosen id looks for the id in the files once more, and refuses it with the same error as session/new if a session has saved under it since. session/load and session/resume answer "not found" for a session that has no file: there is nothing to load. * test(tui): check the late session file at the TUI level (plan decision 17) The agent now writes a session file with the first user message. Three checks that drive the real pieces had to change with it: - scripts/tui_pty/resume_matrix.py (zypi under a pseudo-terminal): the TUI makes a session at once, with no message, for `--session-id` and for `/new`. (A start with no flag makes none until the first message.) Two new cases leave such a session with no message and require that no session file exists. The first one comes first on purpose: under an agent that writes at once, its empty session is the newest one, so `--continue` and `--resume` with no argument take it and fail too. Two cases type a message and look for the file after it: `--session-id <fresh uuid>`, and `/new` and then a message. A case can have steps (`Step`). wait_for_run types the first one when the TUI is up (the model name on the border of the input box), and each next one when the screen shows that the one before took effect. The `/new` cases start with `--resume <id>`, so they do not depend on which session is the newest. scripts/tests/test_tui_pty.py tests the cases and wait_for_run with a fake terminal. Mutation check: with either of the two `repo.create` calls in agent.py made to write at once, the case for that call fails (and for the call that serves `--session-id`, the two cases that take the newest session fail too). - scripts/tui_pty/smoke.py: after a restart, the /resume picker used to list the new empty session first and the script pressed Down to skip it. That session has no file now and is not listed, so the earlier session is the first row and the script no longer presses Down. - python_agent_e2e.rs (the Rust ACP client against the real Python agent): the sessions that must be listed (51 for the paging test, the `existing` one for the id check) now get a first message. The id check also asserts what the agent does for a session that has no file yet: it refuses a second `session/new` with the same id (InvalidParams), and once the first message is sent the pager's own check finds the id through session/list. No test is added or removed on the Rust side (the count of python_agent_e2e stays 14). * test(agent): close two gaps that a mutation run found (plan decision 17) A run of 15 one-line changes to the production code of this PR, each against the tests that watch it, found two that no test noticed: - The header of a deferred session took its time from a second look at the clock and not from the time in the file name. The test compared the two, but both looks fell in the same millisecond, so it passed by chance. It now gives every look at the clock a new time. - The second look at a chosen id (before the first message) also refused a session whose own file was there. No test sent a second message in a session with a chosen id. A new test sends three. After the change, both are caught. The other 13 were caught before. * docs: record plan decision 17 (the session file is written at the first message) and r14 - CHANGELOG.md, [Unreleased]: the agent writes the file of a session with its first message. It lists the behaviour changes (no flag: no session until the first message; `--session-id` and `/new`: a session at once, with no file; a chosen id stays reserved while its session is open), what library users get (`JsonlSessionRepo.create({"deferred": True})`), and the tests. The entry for the cost of paging says it is left as it is. - The embedded user guide (17-sessions.md), packages/pi-agent-cli/AGENTS.md and docs/DESIGN.md section 6.1: a session in which nobody typed has no file, so it is not listed and cannot be loaded. - scripts/tui_pty/README.md (16 cases) and docs/baselines/tui.md. - The plan (r14): the status, the answers to the four questions (#23 and #24 merged, decision 18 not done, decision 17 done, decision 10 to do), and the index of section 10. - The execution log: section 10.17 (the merges, the design of decision 17, what each ACP method does for a session without a file, the facts about the TUI, the tests, two mutation runs and the two gaps they found, the numbers, what is not verified), B.9 (how to repeat it) and the revision record. One old line (about the empty first row of the /resume picker) points to section 10.17.
1 parent 0476ea4 commit 2b0baf3

24 files changed

Lines changed: 1100 additions & 94 deletions

‎CHANGELOG.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
99

1010
### Changed
1111

12-
- **`zypi --continue`, `--resume` and `--session-id` ask the agent which session is meant (TUI)**: `zypi` used to look for the session in the session files of the old Rust agent. The Python agent writes another layout, so `--resume <title>` found no session, an unknown id failed only after the UI had started, a used `--session-id` left the UI open with `Session creation failed: Invalid params`, and `--continue` took the session that was created last (the first of the **Known issues** of 0.5.0). Now `zypi` starts the agent first and then asks it over ACP, with `session/list` (page after page) and `session/load`. It reads no session file for this. A session that does not exist ends the run before the event loop starts: the terminal is restored, the agent is stopped, the message is printed, and the exit status is 1. **Behaviour changes**: `--continue` and `--resume` without a value take the session of this directory with the latest activity (the time of its last write), not the one that was created last. `--resume <id>` finds the id in every directory and loads the session in the directory it belongs to. `--resume <title>` matches the title, which is the first message of the session, among the sessions of this directory, without regard to letter case and to spaces at the ends; two sessions with the same title are an error that lists their ids and last activity. `--session-id <id>` reads every page of the session list and refuses an id that any session has (`Session ID <id> is already in use.`, exit status 1); that costs one pass through the list (`scripts/session_list_bench.py` prints it as `walk all`), and an agent that offers no `session/list` skips the check and refuses a used id itself. The lookup stops after 30 s, the limit of the connect (`GROK_CONNECT_UI_TIMEOUT_SECS`). **Not solved**: the agent writes the file of a session when the session is created, so a run in which nobody typed a message leaves a session with the title `(no messages)`, and `--continue` takes it when it is the latest. The fix is in the Python agent (write the file at the first message). **Also not solved**: the agent lists its session directory again for each page, so reading all pages costs pages × directory size, which grows faster than the number of sessions. `scripts/session_list_bench.py` (median of 3, Linux / Windows): `--session-id` takes 1.3 s / 1.8 s at 1,000 sessions and 28 s / 34 s at 5,000, which is over the 30 s limit on Windows; `--continue` takes 0.6 s / 0.8 s at 1,000 and 10 s / 12 s at 5,000. The fix is in the Python agent too (plan decision 18). Tests: 25 unit tests of the lookup against a scripted agent, 4 of the time limit and of a cancel, 3 end-to-end tests against the real agent, and `scripts/tui_pty/resume_matrix.py --strict` (13 of 13 pass; cases 5 and 11 were known gaps, and case 8 now needs exit status 1).
12+
- **`zypi --continue`, `--resume` and `--session-id` ask the agent which session is meant (TUI)**: `zypi` used to look for the session in the session files of the old Rust agent. The Python agent writes another layout, so `--resume <title>` found no session, an unknown id failed only after the UI had started, a used `--session-id` left the UI open with `Session creation failed: Invalid params`, and `--continue` took the session that was created last (the first of the **Known issues** of 0.5.0). Now `zypi` starts the agent first and then asks it over ACP, with `session/list` (page after page) and `session/load`. It reads no session file for this. A session that does not exist ends the run before the event loop starts: the terminal is restored, the agent is stopped, the message is printed, and the exit status is 1. **Behaviour changes**: `--continue` and `--resume` without a value take the session of this directory with the latest activity (the time of its last write), not the one that was created last. `--resume <id>` finds the id in every directory and loads the session in the directory it belongs to. `--resume <title>` matches the title, which is the first message of the session, among the sessions of this directory, without regard to letter case and to spaces at the ends; two sessions with the same title are an error that lists their ids and last activity. `--session-id <id>` reads every page of the session list and refuses an id that any session has (`Session ID <id> is already in use.`, exit status 1); that costs one pass through the list (`scripts/session_list_bench.py` prints it as `walk all`), and an agent that offers no `session/list` skips the check and refuses a used id itself. The lookup stops after 30 s, the limit of the connect (`GROK_CONNECT_UI_TIMEOUT_SECS`). A session in which nobody typed has no file now, so `--continue` cannot take it (see the next entry). **Not solved, and left as it is**: the agent lists its session directory again for each page, so reading all pages costs pages × directory size, which grows faster than the number of sessions. `scripts/session_list_bench.py` (median of 3, Linux / Windows): `--session-id` takes 1.3 s / 1.8 s at 1,000 sessions and 28 s / 34 s at 5,000, which is over the 30 s limit on Windows; `--continue` takes 0.6 s / 0.8 s at 1,000 and 10 s / 12 s at 5,000. The owner decided that this is fine below 1,000 sessions (plan decision 18). Tests: 25 unit tests of the lookup against a scripted agent, 4 of the time limit and of a cancel, 3 end-to-end tests against the real agent, and `scripts/tui_pty/resume_matrix.py --strict` (13 of 13 pass; cases 5 and 11 were known gaps, and case 8 now needs exit status 1).
13+
- **The agent writes the file of a session with its first message (`pi-agent-cli`, `pi-agent-harness`)**: the agent used to write the file of a session when it answered `session/new`. A run in which nobody typed a message left a file with the title `(no messages)`. That file stayed in the `/resume` list, and `zypi --continue` took it when it was the latest session of the directory. Now `session/new` makes the session in memory only. The file is written with the first message of the user, in one write: the header, the entries that were made before the message (for example a model change), and the message. A session in which nobody typed has no file. `session/list` does not show it, and `session/load` and `session/resume` answer `resource_not_found` for it. A client that has the session open can keep using it. **Behaviour changes**: `zypi` with no flag starts no session until the first message; `zypi --session-id <id>` and `/new` start one at once, with no file. An id that a client chose (`_meta.sessionId`) stays reserved while its session is open in the agent, so a second `session/new` with that id is refused (`invalid_params`) although no file has it. If another agent process saves a session with that id first, the first prompt of the session is refused (`a session with this id already exists`). This narrows the gap between two agent processes. It does not close it. Files that earlier versions wrote keep the title `(no messages)`. **For library users**: `JsonlSessionRepo.create({"deferred": True})` returns a `DeferredJsonlSessionStorage`, and its `written` property says whether the file exists. `create` without `deferred`, and `fork`, write at once as before. Tests: 10 for the storage (what is written and in which order, a failed write and its retry, two first messages at once), 6 new ones for the agent (the ACP contract and the chosen ids), and the older tests that expect a session in the list now send a message first. `scripts/tui_pty/resume_matrix.py --strict` has 16 cases (13 before). Two of the three new ones fail against an agent that writes at once: `--session-id` and `/new`, each left with no message. The third types a message after `/new`.
1314
- **A resumed session no longer takes the sandbox profile it was created with (TUI)**: the old Rust agent saved the sandbox profile in the files of a session. `zypi --continue` and `--resume` read it back before the sandbox was applied, so a resumed session kept its sandbox, and `--sandbox X` on a session that was saved with `Y` was refused (`cannot resume this session under sandbox profile ...`). The Python agent never saved a profile, so for its sessions nothing changes. The profile now comes from `--sandbox`, from `GROK_SANDBOX` and from the configuration, as it does for a new session. The code that read it is gone (decision 2 of the plan).
1415

1516
### Removed

‎docs/DESIGN.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -195,6 +195,7 @@ Anthropic 原生 image blocks;其他 provider 回退为 user-message 注入;
195195
- **11 种 SessionTreeEntry**(pydantic discriminated union):message、thinkingLevelChange、modelChange、activeToolsChange、compaction、branchSummary、custom、customMessage、label、sessionInfo、leaf
196196
- **树结构**:`parentId` 构成树;分支 = 从任意历史 entry 续写;leaf entry 实现叶子指针移动
197197
- **两种存储**:`JsonlSessionStorage`(文件 I/O + 内存索引)、`MemorySessionStorage`(纯内存,测试用)
198+
- **延迟写(Python 一侧的扩展,默认不开)**:`JsonlSessionRepo.create({"deferred": True})` 返回 `DeferredJsonlSessionStorage`(`JsonlSessionStorage` 的子类)。第一条 `message` entry 到来之前,entry 只记在内存里;那时才一次写下 header、攒下的 entry 与这条消息。没发过消息的会话不留文件,`list`、`find`、`has_session` 也看不到它。`pi-agent-cli` 的 `session/new` 用它(计划决策 17)。
198199
- **Repo**:create/open/list/delete/fork;fork 语义忠实对齐 pi `getEntriesToFork`
199200

200201
### 6.2 AgentHarness 主类

0 commit comments

Comments
 (0)