## Summary
This branch folds four merge requests and one unpushed commit into one, so that `main`
takes one review, one approval and one merge instead of four, and so the eight-file
overlap between them is resolved once. It carries, in this order:
- **!602** `feat/ppt_deliver_to_named_path` -- `ppt_build` takes `deliver_to`; every
publish writes the deck under `out/` and copies the same measured bytes to the path
the user named, recording it with `role: "delivery"`. The PDF preview rides along only
where its own `.pdf` name is free: a file already at that stem is the user's and is
left alone, and the reply says the preview stayed under `out/`.
- **!628** `feat/ppt_copy_route_and_page_isolation` -- `adapt` is removed, so cloning a
template page and writing into it with `replace_text` is the only route; a page whose
block raises loses only itself and the pages after it still build; a draft counts
against the tier's build cap and one is released at it.
- **!632** `feat/ship_templates_and_soffice_dep` -- the ten bundled deck templates are
tracked in git with per-file sha256 pins, so a fresh clone can build a deck; the
LibreOffice dependency is declared and resolved through one resolver.
- **!642** `fix/ppt_copy_route_and_clone_typography` -- a copy-route lookup that finds
nothing names the near miss before the inventory; a text frame with no paragraph at
all can be written into; a cloned page's title size is said; `row_type_drift` compares
the same structural slot across a run's units.
- **D57's other-page clause, rewired.** D57 gave five refusals a "did you mean" hint,
and one of them also answered "the string you named is on page N of this template".
That clause needs the file a page was cloned out of, and the only refusal holding it
was `adapt`'s, which !628 removed. It is restored by reading `PPT_TEMPLATE_SOURCE`,
which the runner already sets in the author's own process and which this module
already reads for `bundled()`; the two helpers behind the clause are unchanged.
- **D60** `read the ground under each word, not across the whole box` -- the `unreadable`
contrast gate also measures the render's own word boxes, as extra regions through the
same guards, so a two-line block crossed by a narrow bright ridge can no longer elect
the dark ground and read as legible.
Decisions the union forced, none of which drops a behaviour:
- The publish record is built !602's way, with its delivery `role`, and written the way
D49 requires -- read back off the file, atomic, and refused rather than silent when
the record cannot be written.
- `clear_region`, `shapes_in`, `page_box` and the refusal of a bare four-number region
survive `adapt`'s removal; so do `_heading_rows` and its helpers, which the row
reading loads even though the call they were written for is gone.
- The author-facing guidance names !628's single route and keeps D59's rule that a
region must declare which reading it is.
**The decision log carries a numbering collision, on purpose.** It is a set union with
no wording changed, and the numbers are left exactly as each branch wrote them, so a
reviewer meets this rather than discovers it:
- !602 and !628 each wrote a **D37** and a **D38**, about different decisions.
- !628's **D45** is not `main`'s D45; they are unrelated entries under one number.
- !628's **D42** is `main`'s **D45** word for word, so the merged log carries one
decision under two numbers.
Renumbering touches every cross-reference in the log, and doing that inside a
seventy-commit fold immediately before a merge is how a silent break gets in. The
numbering is being fixed on a separate branch, which carries a script and a test that
fails when a citation points at nothing.
## Type
- [x] Feature
- [x] Fix
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
Run on an interpreter carrying `python-pptx`, with `PYTHONPATH` at this worktree and its
`plugins-dist/ppt-engine`, confirmed from a neutral working directory that `raven` and
`raven_ppt` resolve out of the worktree and not the host repo.
- `make test-python` (the whole suite, as CI runs it) -- 20826 passed, 49 skipped, and
26 failures this machine produces on any branch: it has no `/usr/share/zoneinfo`, so
every cron timezone case raises `ValueError: unknown timezone 'Asia/Shanghai'`. Checked
out plain `origin/main` in a clean worktree and ran the same two files: the same 6
failed and 20 errors, the ids identical character for character. Nothing on this branch
touches cron or timezones. The stale `test_trunks_executor_would_have_dropped_that_output`
that failed on the previous revision is retired on the new base and its replacement,
`test_trunks_executor_preserves_output_on_timeout`, was run on its own and passes.
The 6 failures and 20 errors are all cron timezone tests failing identically on plain
`main` in a clean worktree, on a host with no `/usr/share/zoneinfo`.
- `make check-commits` -- exit 0.
- `make check-source-language` -- exit 0.
- `make check-large-files` -- exit 0.
- `make lint-imports` -- exit 0, 9 contracts kept, 0 broken.
- `ruff check` and `ruff format --check` over the 80 changed Python files -- exit 0.
- `pytest tests/test_ppt_engine_templates.py tests/test_utils_office.py
tests/test_cli_doctor_commands.py` -- 97 passed; the ten templates are tracked and
satisfy their pins, and the soffice resolver finds the local binary.
- The delivery contract, the record read-back, the page isolation and the near miss were
each run as a measurement rather than asserted; the `unreadable` gate was run through
the real LibreOffice render chain on a delivered 12-page deck and reports BLOCKING on
page 12 under one word at 1.6:1.
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
User-visible changes: `ppt_build` gains `deliver_to` and delivers outside `out/`;
`adapt` is gone from the author-facing template module, so a program calling it fails to
import -- `title=` and `subtitle=` have no replacement and the heading is named by the
words the template put there; a draft now counts against the tier's build cap; three
gates that nothing measured against being wrong no longer refuse; and the ten templates
are now bytes in the repository rather than a private registry fetch.
Two pieces here are about not destroying something the user has. The delivery
refuses to write its `.pdf` where a file the user already owns sits at the same
stem, rather than replacing it; and the large-file roster moved out of the manifest
inside the tree being checked and into the gate's own source, so a change can no
longer grant itself the exception the gate exists to withhold.
Rollback is per piece: each of the five sources is a contiguous run of commits on this
branch, in the order listed above, so any one of them can be reverted as a range without
touching the others.
- [x] Backward compatibility considered
- [x] Security impact considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
## Summary
Reported as "deliver_files is broken". It is not: **the tool never ran.**
Every `deliver_files` call on one install was refused before dispatch -- five in a row in a single session -- and nothing was ever delivered:
```
Error: Invalid parameters for tool 'deliver_files': files should be array
```
What the model sent was the array, spelled as a string:
```json
{"files": "[{\"path\": \"...poster.png\", \"title\": \"...\"}]", "message": "..."}
```
`cast_params` already forgives that spelling for every scalar type -- `"3"` for an integer, `"true"` for a boolean -- and did not for arrays or objects, which are exactly the types a model is most likely to stringify.
## Type
- [x] Fix
- [ ] Feature
## The edge of the forgiving is the design
When the value is a string, try `json.loads`, and take the result **only if it is the type the schema asked for**. A string that is not JSON, or is JSON of the wrong shape, is returned unchanged so the validator still names the real problem -- the point is to widen what is accepted, not to swallow a type error.
**Nothing here can raise.** Turning "your argument has the wrong type" into a traceback would be worse than the refusal it replaces, so the parse is wrapped and failure falls through.
**A `type: "string"` field is never parsed.** JSON is ordinary text in a message body or a file's content, and replacing it would hand the tool something it never asked for. Two independent things prevent it today (the string branch returns before the parse is reached, and the parse only wins on a type match), which is why the case pinning it is a tripwire rather than a load-bearing assertion -- said so in its own docstring rather than left to look like coverage.
## Not just deliver_files
Six built-in tools declare an array or object parameter and were all exposed:
| tool | parameter |
|---|---|
| `deliver_files` | `files` |
| `ask_user` | `questions` |
| `image_generate` | `images` |
| `message` | `media` |
| `create_playbook` | `skills` |
| `video_generate` | `params` |
The same failure was already seen from the other side: `acp_client/acp_agent.py` records `update_task_state` and `operations should be array` from a real dispatch.
## Verification
```
make lint-python ruff check + ruff format --check, 1850 files
make lint-imports 9 contracts kept, 0 broken
pytest tests/ 19,699 passed, 7 failed (all pre-existing, see below)
```
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [ ] User-facing docs or screenshots -- no user-facing string
**End to end, through the real tool**, with the exact payload that failed five times in production:
```
files sent as: str -> [{"path": ".../poster.png", "title": "..."}]
returned: Delivered 1 file(s): poster.png (72 B).
still "should be array": False
registered in the store: True
```
Twelve cases, five mutations, each killing at least one:
| mutation | red |
|---|---|
| drop the whole branch (the old behaviour) | 3 |
| raise instead of falling through on a parse failure | 5 |
| accept the parse whatever type it yielded | 1 |
| do not re-cast the parsed value, so items are not cast | 1 |
| widen the tuple to include `string` | **survived -- unreachable** |
The last is worth stating rather than hiding: that mutation cannot change behaviour, because the `type == "string"` branch returns earlier and the type check would refuse the result anyway. I also tried moving the new block above that branch, alone and combined with widening the tuple, and neither reddens anything either. The invariant holds by construction; the case that documents it says so.
**Pre-existing failures, checked against the base.** 7 failed in the full run, all in `tests/test_security_network.py` (`test_a_redirect_to_a_dangerous_address_is_refused` and siblings). Running that file alone on this same tree gives 4 -- the count is order-dependent -- and the change touches only `raven/agent/tools/params.py` plus a new test file, neither of which `raven/security/network.py` imports. The failures are the box's resolver: it returns poisoned answers roughly half the time, which I measured separately (`en.wikipedia.org` came back as `2001::1` on 3 of 6 lookups). Not introduced here, and worth someone's attention on its own.
## Risk
- [x] Security impact considered -- widens what reaches a tool's own validation, not what bypasses it. A parsed value is still validated against the same schema, and a parse that yields the wrong type is refused exactly as before
- [x] Backward compatibility considered -- a call that worked before takes the identical path; the new branch is reached only by a `str` where an array or object is declared, which previously always failed
- [x] Rollback path is clear -- single-commit revert
## Related Issues
N/A
## Swept
`mr-review-patterns` pre-submit sweep, over `git diff origin/main...HEAD`.
- **1 (a write location moved)** -- nothing moved; a branch was added to an existing dispatch on `target_type`. Grepped every caller of `cast_params`: the registry is the only one, and it runs `validate_params` right after, which is the reader this affects.
- **2 (a value with several entry points)** -- the cast is the single funnel every tool argument passes through, which is why the fix belongs here and not in `deliver_files`.
- **3 (a guard)** -- checked both directions: what it wrongly lets through (JSON of the wrong type, non-JSON text -- both refused, with cases) and what it wrongly refuses (a real list, unaffected, with a case).
- **4 (tests)** -- five mutations above, one honestly reported as unreachable. Failing-ID sets diffed against the base rather than counts.
- **6 (stale text)** -- the module docstring enumerated what is coerced ("a string that should be an integer"); it now names arrays and objects too. Grepped the tracked tree for other statements of the rule: none.
- **9 (error handling)** -- the new path adds one way to end and it is caught: `json.loads` raises `ValueError` on bad text and `TypeError` on a non-string, and both fall through to the untouched value.
- **11** -- `git ls-files | grep -c node_modules` is 0; the commit-message gate was run, not eyeballed.
Not applicable, with reasons: **3b, 3c, 3d, 3e** (no tool schema produced, no state moved, one lane, no assertion lost its symbol); **4b, 4c, 4d** (no platform branch, no shell, no rendered number); **5, 5b** (no dependency; `json` is stdlib and already imported across this package); **6b, 6c** (no backup, no generated artifact); **7, 7b** (nothing on disk); **8** (no asset, no secret); **10** (no prompt text).
## Deliberately not fixed
The error text still ends with `[Analyze the error above and try a different approach.]`, and the model plainly did not -- it sent the same shape five times. A message naming the expected spelling (`files must be a JSON array, not a string containing one`) would give it something to act on. That is a change to the registry's error surface, affects every tool, and deserves its own argument.
## Moved from !594
Opened on a compliant source branch. AGENTS.md 2.1 asks for a 3-5 word snake_case description and the previous branch had seven; GitLab cannot change an existing merge request's source branch, so the change moves rather than the name.
Same commits, rebased onto `c2a9768f`. Both code findings from the review on !594 are already in them -- `RecursionError` caught with its regression case, and the implementation comment reduced to the two non-obvious reasons. Nothing else changed, so that review carries.
## Summary
Overhaul the interactive `raven trajectory` browser end to end, fixing
every
issue from real-terminal testing:
- Navigation: every screen opens with a help area under its title (page
purpose plus "[Key] function" hotkey hints, rendered in a new readable
help color). Esc walks one level up (action -> attempt -> session); on
the
top-level session screen Esc stays put and quitting is Ctrl+C only,
which
prints a single exit notice. Esc inside a running action cancels just
that
action through a dedicated exception at the action boundary, so the back
sentinel can never reach a conversion or the data layer; a cancelled
report keeps its pre-confirm bundle-and-pin side effects (the existing
declined-report contract). Back/Exit menu entries are gone; answered
prompts erase themselves and navigation is echoed as breadcrumb lines
with markup-escaped untrusted text.
- Tables: the session list is TITLE | ATTEMPTS | LAST ACTIVITY and the
attempt list is # | STARTED | TURNS | SPANS | VERDICT | PIN | MERGED |
PREVIEW with green check cells. Time cells keep the year. The layout is
budgeted per screen build from the live terminal width (row indent, a
safety margin, and inter-column gaps are all part of the math); PREVIEW
drops as a whole column when it no longer fits, and below the dynamic
minimum width the tightest layout is kept while the renderer clips
overlong lines at the terminal edge. Every dynamic cell passes a
single-line sanitization gate before width math (verdict sidecars only
guarantee a non-empty string), cells are measured and truncated by
terminal display width (CJK is 2 cells), and fixed column widths always
fit their headers.
- Space preview: Space on an attempt row prints that attempt's per-turn
input/output previews, collected in the same snapshot scan and sorted by
a fully-stringified key so ordering never follows log source order (the
table PREVIEW cell derives from the same sorted collection). Any key,
arrow keys included, returns with the cursor kept on the row; the waiter
passes the terminal's CPR reply through to the renderer instead of
treating it as a keypress, and Ctrl+C keeps the browser-wide cancel.
- Merge hotkey: with two or more attempts, m/M opens the multi-select
merge
(advertised in the help line; the old "Merge attempts" menu entry is
gone). The checkbox screen carries its own help line for toggle,
confirm,
and cancel. A single attempt neither binds nor advertises the key.
- Theme and feel: new success (green check) and help (readable hint
text)
colors in both palettes, all WCAG AA on their backgrounds; a lone ESC is
flushed after 50ms instead of prompt_toolkit's 0.5s default, removing
the
laggy Esc feel.
The data layer is untouched: changes are confined to
raven/cli/trajectory_browse.py, raven/cli/_theme.py, and their tests.
The
id-taking subcommands (raven trajectory save/list/...) behave as before.
## Type
- [x] Fix
- [ ] Feature
- [ ] Docs
- [ ] CI / tooling
- [ ] Refactor
- [ ] Other
## Verification
- `COLORTERM=truecolor uv run pytest tests/test_cli_theme.py
tests/test_cli_trajectory_browse.py
tests/test_cli_trajectory_commands.py -q` -> 220 passed
- `COLORTERM=truecolor uv run pytest tests/ --ignore=tests/integration
-q` -> 6917 passed; the 10 failed + 20 errors are the pre-existing
environment-dependent set, identical file-by-file on a clean main
checkout (cron, everos server, config loader, tracing viewer)
- `uv run ruff check` and `uv run ruff format --check` on the four
touched files -> clean
- PTY smoke on a CPR-answering pseudo terminal at 100 and 58 columns:
full flow (preview, merge cancel, action screen, staged Esc backout,
Ctrl+C quit) and the narrow-width degradation contract
- New coverage includes real pipe-input key-binding tests (Esc on all
four prompt kinds, Space/m/M hits, waiter key paths with CPR
pass-through), table budget/clipping boundaries at the computed minimum
width, and corrupt verdict/timestamp corpora
- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally
- [x] User-facing docs or screenshots are updated when needed
## Risk
- The interactive browser's look and key protocol change wholesale (that
is
the point of this PR): Esc no longer quits from the top level (Ctrl+C
does), Back/Exit entries are gone, and lists render as tables. The
machine-facing subcommands and the trajectory data layer are untouched.
- Rollback: revert the squash commit; the browser returns to the
previous
interaction wholesale, no data migration involved.
- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes
## Related Issues
N/A
---------
Co-authored-by: 江国庆 <guoqingjiang@deepglint.com>
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
## What
Adds a `RAVEN_WHEEL_SLIM=1` build switch to `hatch_build.py`: when set, the wheel build skips the vendored sub-agent tree and the prebuilt TUI/web bundle inclusion. Default builds are byte-identical to before.
## Why
The release wheel is ~106 MiB compressed; ~94% is the `subagents/` snapshots (raven-ppt alone carries 74 MiB of `.pptx` templates and fonts) plus UI bundles. A cloud provisioner that only ever runs `raven acp` inside a sandbox uploads all of that per instance for assets nothing there opens. The slim wheel is ~3.0 MiB with the full python package intact, cutting sandbox provisioning upload from 15-23s to under a second.
## Behavior on slim installs
- Sub-agents: absent by design; onboarding step 5 reports no tree (headless installs never reach it). Their own distribution channel is future work.
- `raven tui` / `raven serve`: fall back to the source-checkout resolvers exactly as a dev build without prebuilt bundles does today; headless installs never call them.
## Verified
- `RAVEN_WHEEL_SLIM=1 uv build --wheel` -> 3.0 MiB wheel, 734 files, `raven/acp` complete, no `raven/subagents` or UI dist entries.
- The slim wheel provisioned a real E2B-compatible sandbox and served a full `raven acp` session end to end (delegated task with shell execution, ask_user elicitation round trip, multi-turn session continuity).
- Default build without the variable is unchanged.
## What
Adds a `RAVEN_WHEEL_SLIM=1` build switch to `hatch_build.py`: when set, the wheel build skips the vendored sub-agent tree and the prebuilt TUI/web bundle inclusion. Default builds are byte-identical to before.
## Why
The release wheel is ~106 MiB compressed; ~94% is the `subagents/` snapshots (raven-ppt alone carries 74 MiB of `.pptx` templates and fonts) plus UI bundles. A cloud provisioner that only ever runs `raven acp` inside a sandbox uploads all of that per instance for assets nothing there opens. The slim wheel is ~3.0 MiB with the full python package intact, cutting sandbox provisioning upload from 15-23s to under a second.
## Behavior on slim installs
- Sub-agents: absent by design; onboarding step 5 reports no tree (headless installs never reach it). Their own distribution channel is future work.
- `raven tui` / `raven serve`: fall back to the source-checkout resolvers exactly as a dev build without prebuilt bundles does today; headless installs never call them.
## Verified
- `RAVEN_WHEEL_SLIM=1 uv build --wheel` -> 3.0 MiB wheel, 734 files, `raven/acp` complete, no `raven/subagents` or UI dist entries.
- The slim wheel provisioned a real E2B-compatible sandbox and served a full `raven acp` session end to end (delegated task with shell execution, ask_user elicitation round trip, multi-turn session continuity).
- Default build without the variable is unchanged.
The fork's deck engine lands as plugins-dist/ppt-engine: 137 sources
ride a pinned copy manifest (42 byte-copies, 95 respelled to
raven_ppt, every file sha256-verified after transform, 34 carriers of
functional CJK flagged per row), and its 858-line ACP layer is
rewritten as six plugin modules on the landed seams -- eleven deck
tools seated per workdir, a two-phase material-staging/deck-announce
turn hook, and a config slice that fails closed: a malformed or
wrong-typed knob casts a sentinel hook naming the fix instead of
booting a silent zero-tool face, because the stack logs and skips a
raising factory. The kernel validator learns JSON-Schema type lists
(["integer","null"]) in two additive branches so ppt_outline admits
its schema, fixing the same latent crash for MCP tools. The fork's
1310-test scope lands as 1295 across 71 ported files and a 77-row
conservation ledger. The Chinese these files carry is capability data
for a Chinese-deck product -- caption markers, agenda words, worked
deck examples, test briefs -- and lands under an owner-signed
exemption pinned to exactly two prefixes, the engine wheel and its
test family; the rest of the tree keeps the zero-CJK rule. deliver() retires because the trunk workdir
already is the client's cwd. Plates stay out of git through the w106
manifest machinery; the lock file changes only through uv itself.
Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>