v0.75.0: plugin helpers (tw), in-place edits that count, per-block streaming

[fylorn]

Summary

Script plugins get a built-in helper object and no longer have to return the object they edited.

tw

A frozen global next to console and reject. It is plain JavaScript (crates/tw-plugin/src/helpers.js), evaluated together with the bridge at build time and baked into the snapshot. No new host imports, hooks or permissions; the host checks whatever it produces exactly like hand-written plugin output.

function	does
appendSystem(req, text)	appends a paragraph to the system prompt once
texts(req, fn)	visits the system prompt, text parts and tool results (inputs views too); a returned string replaces
toolCalls(req, fn)	hands over each tool-call part in the history; editing input takes effect
mapStrings(value, fn)	deep copy with every string value mapped; __proto__ stays an ordinary key
replace(text, rules)	rule-based replacement (below)
streamReplace(rules, options)	{ onReplyText, onReplyTextEnd } for stream-mode plugins, same result as replace on the whole block
lines(text), pairs(text, sep)	parse multi-line settings; pairs throws on a malformed line and names its number

Rules are [find, replacement] pairs (array, Map or any iterable): one left-to-right scan, the first listed rule wins at a position, replaced text is never rescanned, string finds are literal, regular expressions work like String.prototype.replace (no g needed; empty-matching and y patterns are rejected). Secret placeholders such as <<TW_SECRET_1>> are never matched or split, and a match cannot span one.

streamReplace holds back only what a later piece could still change: for string rules, a tail that could start a find string; with a regular expression, the last maxMatch characters (default 256); and a trailing partial placeholder. Text blocks that are open at the same time are buffered separately: the host now passes the block number to the sandbox on every onReplyText / onReplyTextEnd call (guest ABI 2). Plugin code cannot see it. With reply: "block" each call is a whole block and is replaced at once.

In-place edits count

When onRequest or onToolCall returns undefined, the bridge serializes the object it received. If that differs from the input text, it goes to the host exactly as if the hook had returned it; otherwise the result is "unchanged" without involving the host. Returned objects, null, arrays and reject() behave as before. A verdict of "unchanged" can only drop an edit; permission and key checks on the host side are untouched.

Default plugins

reply-language uses tw.appendSystem, wsl-paths uses tw.toolCalls + tw.mapStrings with in-place edits. Manifests are byte-identical, behaviour is unchanged (existing tests pass), manifests.json is regenerated.

Run record: text changes are counted per block

A stream-mode plugin that holds text back hands out pieces that differ from what it was given, so each such call used to count as a text change, and tw.streamReplace with a regular expression made nearly every answer "changed". The gateway now compares, per text block, everything the plugin was given with everything it handed back (placeholder form). Matched parts are dropped as they arrive and only the unmatched stretch is kept, so a block is never stored twice; the block counts as one change if the two differ at its end. A plugin skipped after an error counts only if what it already handed out differs. Block mode keeps its per-block comparison.

Cleanup

A stale comment in the guest's Cargo.toml that described files the repository no longer has is replaced.

Cost

Measured with cargo run -p tw-plugin --example latency (host in debug; the sandbox code is the same optimized build either way), median of n runs:

case	before	after
hook reads a 1 MB view and returns nothing (sandbox CPU)	7.1 ms	13.3 ms
hook edits a 1 MB view and returns it (sandbox CPU)	17.3 ms	16.9 ms
hook reads a 100 KB view and returns nothing	0.76 ms	1.4 ms
reply() (fresh instance + ctx)	103 µs	109 µs
on_request, small view (fresh instance)	121 µs	125 µs

Dense rule-based replacement (1 MB, about 108,000 matches, sandbox CPU, before / after the last commit): string rules 132 / 20 ms, rules with a regular expression 147 / 112 ms, streamReplace in 64-character pieces 477 / 181 ms (strings) and 502 / 210 ms (with a regular expression). String rules whose find strings cannot overlap are applied with native split/join (a private-use character holds a replacement's place when it could otherwise be rescanned); everything else uses the scan, which now calls bound builtins instead of Reflect.apply wrappers.

The extra time for a hook that returns nothing is one JSON.stringify of the view plus a string comparison. The snapshot grows by about 190 KiB (guest.cwasm 3.01 MB to 3.21 MB, compared with the same bridge without tw); stripping function sources and debug info, or zeroing freed memory during initialization, saved under 5 KB, so neither is included.

Tests

• crates/tw-plugin/tests/helpers.rs: every helper in the sandbox, including misuse, missing permissions and tampered builtins; interleaved blocks against block-mode results.
• crates/tw-plugin/tests/corpus/helpers-split.js: randomized property test run inside the sandbox. Whole-text replace equals a naive per-position reference, and any split streamed through streamReplace equals the whole-text result without cutting a placeholder or a surrogate pair (3 seeds x 1500 cases x 4 splits; about a third of the cases use all-string rules on long texts with coarse splits to cover the split/join path; deliberate bugs in the holding logic and in the split/join path were each caught). Dense replacement is tested against the CPU limit without measuring time: 1 MB with string rules, 100 KB with a regular expression.
• crates/tw-plugin/tests/in_place.rs: the return cases for both hooks (no return with and without edits, edited then restored, returned self, returned other object, async, reject, unserializable edits).
• Run record: a stream-mode tw.streamReplace whose rules never match, fed one character per frame, is recorded as unchanged (this failed before the fix); holding a whole block and releasing it unchanged is unchanged, any difference is a change, in both modes; unit tests for the per-block comparison, including the skip-after-error case.
• Gateway: the block number reaches the plugin for interleaved Anthropic blocks in both modes; the sandbox adapter passes it through; end-to-end runs for in-place request edits, a read-only hook leaving the request byte-identical, streamReplace over a one-character-per-frame stream, and secrets that survive replacement rules aimed at placeholder text.

cargo fmt --all -- --check, cargo clippy --workspace --all-targets -- -D warnings and cargo test --workspace pass locally.

Release

This PR also carries v0.75.0: the workspace version and release-notes/0.75.0.md, which cover #339, #340, #342, #343 and this change. Protocol 48 and the request store schema are unchanged.

🤖 Generated with Claude Code