Skip to content

Commit 78fd037

Browse files
authored
feat: tower wake steering, prompt hook folding, WaitFor cap, sticky fullscreen messages (#339)
## Requirement or Bug Land a batch of agent-experience behavior changes: tower wake steering and safer tower operations, prompt hook-output folding, a shorter WaitFor cap, and sticky fullscreen user messages. ## Bug Reproduction Steps N/A ## Root Cause N/A ## Code Changes - **Engine** (`packages/agent-core-v2`): `WaitFor` caps at 90 seconds and a newly sent message ends the wait early; `UserPromptSubmit` hook output folds into the prompt message as meta-marked content parts (annotate-then-filter keeps legacy wires readable); tower wake turns abort on user input; tower teardown gains keep-live worktrees, `exclude`, and `dry_run`; the tower store serializes across processes and writes atomically; tower workers must check their inbox before completing a mission. - **Transcript / gateway**: transcript grouping and cold-load mode state follow the folded parts; prompts API exposes the folded shape. - **TUI** (`apps/pythinker-code`): sticky user message pinned above the transcript in fullscreen (`TranscriptView` + gutter pill + layout effects in the vendored TUI); wait renderer gains an "interrupted" state; user message bullet is now `❯` with wrap-aware line heights. - **VS Code**: replay adapter and hook-part helpers understand the folded parts. ## Behavior Changes and Affected Users | Behavior | Before | After | Who relies on the old behavior | Escape hatch | |---|---|---|---|---| | `WaitFor` timeout cap | up to 600s | capped at 90s | agents (or scripts prompting agents) that issued multi-minute waits | none — the changeset names the cap | | Ending a `WaitFor` wait early | `Ctrl-S` only | sending a message with `Enter` also steers it in and ends the wait; queued shell commands or skills keep the queue until the turn ends | users who queued commands expecting the agent to stay waiting | none; queued non-message work still waits | | Tower wake turns | a message sent during a wake turn queued behind it | the message aborts the wake turn and runs as its own turn | tower users relying on undisturbed wake turns | tower mode is experimental (`[experimental] tower = true`) | | Tower teardown | forced teardown could remove worktrees of live agents | keeps worktrees of live agents even when forced; supports `exclude` and `dry_run` | tower users scripting teardown | the new options control the behavior | | User message bullet | `✨` | `❯` | users matching the old glyph in scripts or themes | themes and keybindings unaffected; the glyph only changes rendered output | | Hook output in the transcript | standalone `hook_result` user message | folded into the prompt message as marked content parts (one prompt = one user message) | transcript consumers: SDK callers, desktop/web replay, VS Code adapter — updated in the same change; external raw-wire parsers see meta-marked parts | none | Affected modules and coverage per row: engine wait/hook/tower changes carry unit and contract tests (`test/agent/loop`, `test/agent/task`, `test/features/tower`, `test/features/externalHooks`); transcript folding is covered by the `packages/transcript` and gateway transcript/prompt suites; TUI behavior by component and message-flow tests; VS Code by replay-adapter tests. ## 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: the 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 7fe5adf commit 78fd037

107 files changed

Lines changed: 5615 additions & 1289 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.

‎.agents/skills/gen-changesets/SKILL.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ Fix occasional loss of tool call results in long conversations.
3232

3333
Wording:
3434
- One short, user-facing English sentence that states only what changed. Drop trailing clauses that explain the cause, the benefit, or the mechanism.
35+
- When a default flips or an existing behavior is removed, name the behavior users lose, not only the new default. State the escape hatch if one exists, e.g. `Stop hot-reloading config, skills, and AGENTS.md by default; set [watch] enabled = true or PYTHINKER_CODE_WATCH=1 to turn it back on.`; if there is none, say plainly that the old behavior is no longer available.
3536
- New features: say plainly what it is plus one line on how to use it, e.g. `Add the /foo slash command to list active sessions. Run /foo to see them.`
3637
- Experimental features: also state how to enable them (the flag, config key, or env var).
3738
- No file, class, or function names, and no PR numbers. No vague words like refactor, optimize, or improve. No real internal identifiers — use neutral placeholders such as `example.com` or `YOUR_API_KEY`.

‎.agents/skills/review-pr/SKILL.md‎

Lines changed: 160 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,73 +1,199 @@
11
---
22
name: review-pr
3-
description: Use when reviewing a pull request in the pythinker-code repository — evaluate the change against the template structure.
3+
description: Use when reviewing a pull request in this repository — check the description against the PR template section by section, then run a separate regression and user-impact pass that produces impact levels and a review summary.
44
disable-model-invocation: true
55
---
66

77
# Review PR
88

9-
Review a pull request by evaluating the description against the template and the actual diff, then write a structured review summary in English.
9+
Most regressions in this repository were not logic errors. They were changes that were correct
10+
relative to their own intent but silently altered a behavior an existing population depended on:
11+
a provider-dialect branch narrowed, a default flipped, a system-prompt sentence deleted, an old
12+
path's feature dropped in a refactor, a fix that changed startup timing. General review excludes
13+
intentional behavior changes from bugs, so this skill runs that check as its own pass.
14+
15+
The review criterion is one sentence: **any input that worked before the change — a config key,
16+
an environment variable, a command-line flag, a provider response shape, session data written by
17+
an older version, a client request, or a hook payload — must behave the same after it, unless the
18+
PR explicitly declares the change and provides a way back.**
1019

1120
## Workflow
1221

13-
1. Fetch the PR description and metadata:
22+
1. Fetch the PR metadata and description:
1423

1524
```bash
1625
gh pr view <number> --json title,body,url,files,additions,deletions,baseRefName,headRefName
1726
```
1827

19-
2. Read the full diff:
28+
2. Read the full diff (large PRs file by file):
2029

2130
```bash
2231
gh pr diff <number>
2332
```
2433

25-
3. Read enough surrounding code to verify the claims in the PR description.
34+
3. Read enough surrounding code to verify every claim in the description. The diff alone cannot
35+
show who reached a branch before the change.
36+
37+
4. **Pass 1: classify.** Decide the depth of pass 3; see "Pass 1: classify".
38+
39+
5. **Pass 2: template section check.** See "Pass 2: template section check".
40+
41+
6. **Pass 3: regression and user impact.** Run it in a fresh context when a subagent is
42+
available: give it only the PR number, base and head, a two-to-three-sentence summary of the
43+
change, and the path to `surfaces.md`. Do not give it the author's impact conclusions; have it
44+
build the inventory from the diff and code first, then compare it against the author's table
45+
when it returns. Without subagent capability, do it yourself in the same order: build the list
46+
first, read the author's table second. See "Pass 3: regression and user impact".
47+
48+
7. Write the review summary in English; format under "Output".
49+
50+
## Pass 1: classify
51+
52+
| Change class | Pass 3 depth |
53+
|---|---|
54+
| Pure internal refactor, tests, docs, test-only CI | Only evidence that nothing observable changed: which branches, defaults, and contract files are untouched |
55+
| Release and packaging: release, native build, VS Code publishing workflows, packaging scripts, web bundle sync | Full pass; populations split by install channel and platform: npm package, per-platform native binaries, VS Code marketplace, bundled web assets |
56+
| New feature that touches no existing path | Only check whether the new branch captures existing inputs first: does the new condition precede the old one |
57+
| Behavior change, default flip, validation or permission tightened or loosened | Full pass |
58+
| Prompt text: system prompt, tool descriptions, reminders, overlays, built-in skills | Full pass, and every edited sentence gets its own row |
59+
| Replacement of an old path, large refactor, protocol swap | Full pass, and require the author to provide the old path's feature inventory |
60+
| Protocol, disk format, SDK export, hook payload, or CLI contract change | Full pass, and name the consumers outside the repository |
61+
| Fix that changes startup order, lifecycle, or async timing | Full pass, focused on who depended on the old order |
62+
63+
A PR can belong to several classes at once; treat it as the heaviest one.
64+
65+
## Pass 3: regression and user impact
66+
67+
### 1. Behavior-change inventory
68+
69+
List every observable behavior the diff changes, including behavior the author calls "unchanged"
70+
and behavior the author considers "internal". Internal packages ship in the CLI release;
71+
"internal" does not mean invisible to users.
2672

27-
4. Evaluate each section against the criteria below.
73+
Each row records: behavior, before, after, change type (added / modified / removed / default
74+
flip / tightened / loosened), and evidence (a `file:line` on each side; when one side does not
75+
exist, give a reachable path on the other).
2876

29-
5. Write the review summary in English.
77+
How to read the diff:
3078

31-
## Review Criteria
79+
- For every deleted or narrowed branch, condition, default, or sentence, ask who reached it
80+
before the change and where they go now.
81+
- For every new branch or condition, ask which existing inputs now match it first. The classic
82+
failure: a parser stops reading the string form of a field when the array form exists, and
83+
gateways shaped like OpenRouter send both.
84+
- Test changes that rewrite an old assertion to the new behavior are direct evidence of a
85+
behavior change; map each one to an inventory row.
86+
- Scan the diff file list against the "trigger clues" in `surfaces.md` first. Every matched
87+
surface must have a corresponding row in the inventory, otherwise it is a miss.
3288

33-
### Requirement or Bug
89+
### 2. Affected populations
3490

35-
- Is the linked issue valid and relevant?
36-
- If no issue, is the requirement clearly stated in one or two sentences?
91+
Map each row to a concrete population in `surfaces.md` and write the population's name together
92+
with evidence that it exists: a doc page, an issue, a config example, a provider payload shape.
93+
A row with no findable population does not become a finding; it goes to "author to confirm".
3794

38-
### Bug Reproduction Steps
95+
### 3. Impact level
3996

40-
- For bug PRs: are the steps clear and reproducible?
41-
- Can you follow the steps to confirm the bug exists on the base branch?
97+
The level is decided only by the facts of the change, never by remediation state (changeset,
98+
docs, tests). Three steps:
4299

43-
### Root Cause
100+
1. Data loss, a widened security boundary, old data becoming unreadable, or a population's
101+
feature unusable in full: L3 outright.
102+
2. Otherwise: observable with a one-step way back (config, env, flag): L1. Observable with no
103+
way back and the old behavior unrecoverable: L2. No observable change: L0.
104+
3. Silent upgrade: a user-supplied input (config, env var, data, request field) is ignored or
105+
dropped with no error signal, so users cannot discover it themselves: raise one level, at
106+
most L3. Behavior that changed openly and is visible in the output is not silent.
44107

45-
- For bug PRs: is the root cause convincingly explained?
46-
- Does the stated root cause match what you see in the diff?
47-
- Is it clear whether this is a fundamental fix or a workaround?
108+
Breadth has three tiers and must name the population: all users / one config or platform
109+
population / edge environments.
48110

49-
### Code Changes
111+
Level each row separately; the PR takes the highest. The reason the silent-upgrade rule exists:
112+
with no signal there is no report, so the regression survives until someone stumbles on it.
50113

51-
- Does the description match the actual diff?
52-
- Are visual outlines (diff blocks, call trees, file trees) accurate and helpful?
53-
- Is the approach sound? Are there simpler alternatives?
54-
- Are there edge cases the author missed?
114+
### 4. Remediation check
55115

56-
### Impact Scope
116+
Four fixed questions, each answered yes / no / not applicable, with evidence:
57117

58-
- Are all affected modules identified? Cross-check with the diff file list.
59-
- Does test coverage match the claimed scope?
60-
- Are there untested paths that carry risk?
118+
- Escape hatch: is there a config, env, or flag that restores the old behavior.
119+
- Changeset: does it name what users **lose**, not only the new default; when there is no way
120+
back, does it say plainly that the old behavior is gone.
121+
- Old data and old clients: sessions written by the previous version, migrated data, and clients
122+
shipped in the previous release (desktop, web, VS Code, ACP) still work; rolling back to the
123+
previous release is safe.
124+
- Guard test: one test that pins the old behavior **for the population that keeps it**.
61125

62-
### Checklist
126+
Plus one: are the documentation promises about this surface updated together with the change.
63127

64-
- Are all applicable items checked?
65-
- For items marked as "not needed", do you agree?
128+
### Handling per level
129+
130+
- L3: recommend blocking. Requires a guard test plus an escape hatch, a flag gate, or a
131+
migration; without all of them it must not merge.
132+
- L2: a maintainer must decide explicitly in the PR; the changeset must name the lost behavior;
133+
docs in sync.
134+
- L1: verify the changeset and docs.
135+
- L0: one sentence on why it is L0, with evidence.
136+
137+
### Findings vs author confirmations
138+
139+
- A finding needs both: `file:line` evidence on each side of the change, and a named population
140+
with evidence it exists. Missing either one, demote to "author to confirm". When a whole file
141+
is added or a whole implementation deleted, one side is naturally empty; give the existing side
142+
the reachable affected `file:line`.
143+
- At most 5 author confirmations, sorted by possible impact; report only the count beyond that.
144+
- Do not report: problems that existed before the PR (a serious one gets a single "incidental
145+
finding" line), problems lint and typecheck catch, style.
146+
- None of these are evidence of "no impact": the author says "unchanged", no test references the
147+
deleted sentence, the change is only in internal packages.
148+
149+
## Pass 2: template section check
150+
151+
- Related Issue: is the linked issue valid and relevant; when there is no issue, is the
152+
requirement stated in one or two sentences?
153+
- Problem: does it state the user need or limitation; is it consistent with the linked issue?
154+
- What changed: does the description match the actual diff; are visual outlines (diff blocks,
155+
call trees, file trees) accurate and helpful; is the approach sound with simpler alternatives
156+
considered; which edge cases did the author miss?
157+
- Behavior Changes and Affected Users: compare the author's table row by row with the
158+
independent inventory from pass 3. A behavior the author missed is a finding; a row you cannot
159+
reproduce goes to "author to confirm". Are populations named, or just "some users"? When the
160+
table says `None`, does the evidence hold? Do affected modules and test coverage match the diff
161+
file list; which risky paths are untested?
162+
- Checklist: are all applicable boxes checked; do you agree with the "not needed" ones?
66163

67164
## Output
68165

69-
Write the review summary in English. For each section:
166+
English, in this order:
167+
168+
```markdown
169+
## Verdict
170+
One line: merge / changes needed / recommend blocking, plus the PR impact level and change class.
171+
172+
## Regression and user impact
173+
- Change class: ...
174+
- Impact level: Lx (breadth: ...; silent: yes/no)
175+
176+
| Behavior | Before | After | Affected population | Evidence | Level | Escape hatch |
177+
|---|---|---|---|---|---|---|
178+
179+
Remediation check:
180+
- Escape hatch: ...
181+
- Changeset names the lost behavior: ...
182+
- Old data and old clients: ...
183+
- Guard test: ...
184+
- Docs: ...
185+
186+
Author to confirm (max 5):
187+
1. ...
188+
189+
## Template section check
190+
Section by section: adequately filled in, missing, inaccurate, or inconsistent with the diff.
191+
192+
## Changes needed
193+
Actionable list; write "none" if empty.
194+
```
195+
196+
## Retrospective backfill
70197

71-
- State whether it is adequately filled in.
72-
- Flag anything missing, inaccurate, or inconsistent with the diff.
73-
- If the PR is ready, say so. If changes are needed, list them as actionable items.
198+
After every regression post-mortem, add the newly discovered population or trigger clue to
199+
`surfaces.md` and a line to its history table. An inventory that is not updated goes stale.

0 commit comments

Comments
 (0)