pi-ui-extend 1.0.39 → 1.0.41

package/external/pi-tools-suite/docs/context-gateway-p01r-rb-evidence.md

@@ -0,0 +1,100 @@
+# Context Gateway P01-R / R-B evidence
+
+<!-- markdownlint-disable MD013 -->
+
+> Date: 7 September 2026.
+> Repository HEAD during deterministic gate: `daa1b06` with an explicitly dirty tested source tree.
+> Installed Pi SDK: `@earendil-works/pi-coding-agent` `0.85.1`.
+> Scope: storeless result-pipeline ordering and optional truncation-metadata cleanup. No durable store, Gateway enforce mode, DCP redesign or live model run was introduced here.
+
+## Result
+
+R-B is complete for the currently claimed storeless combinations. The optional
+`truncation-metadata-normalizer` remains disabled by default and returns only a
+`details` patch. Context Gateway `off`/`observe` semantics remain unchanged.
+
+The verified result order is:
+
+1. LSP/comment result enrichment;
+2. passive Context Gateway observe;
+3. optional truncation metadata normalization;
+4. downstream result observers/modifiers;
+5. opt-in credential-firewall session-hygiene redaction.
+
+For provider hooks the credential firewall runs before the final
+`codex-reasoning-fix` sanitizer, which remains last in `MODULES`.
+
+No suite-local result coordinator was added. The ADR now treats a coordinator as
+conditional future enforce/store work only if an actual enabled-handler conflict
+cannot be expressed safely through the tested event-specific order.
+
+## Normalizer scope and invariants
+
+The normalizer is restricted to the measured `Read`/shell/`ast_grep` names and a
+complete SDK truncation shape. It removes only `details.truncation.content` when
+that string is a prefix of the actually delivered text. It preserves the rest of
+the truncation fields and any native `fullOutputPath`.
+
+Deterministic contracts cover:
+
+- actual installed SDK `Read` and `Bash` truncation results;
+- the real suite `ast_grep` truncation result and its native full-output handle;
+- `bash` / `shell` / `shell_command` aliases;
+- Unicode duplicate text and multipart text + image content;
+- idempotence and no mutation of the original content/details objects;
+- no-op for unknown tool names, malformed shapes and non-matching metadata;
+- collapsed/expanded rendering equivalence for installed Bash, installed Read and suite `ast_grep` renderers;
+- persisted JSONL removal of the duplicate metadata copy while structural fields remain;
+- an exactly equal checked OpenAI-completions provider payload before/after metadata normalization.
+
+The generic `tool_result` event cannot prove that a separately loaded replacement
+using the same measured tool name and exact SDK-looking shape is the original SDK
+definition. The ADR therefore marks same-name replacement provenance as limited;
+name+shape is not promoted to a strict-enforce trust primitive.
+
+## Result/security composition
+
+An executable installed `ExtensionRunner` contract uses an enrichment stage,
+Context Gateway observe, the normalizer, a DCP-free fake downstream observer and
+the real credential firewall. It proves that:
+
+- tool call ID observed downstream is unchanged;
+- `content`, image parts, `isError`, usage and structural completeness metadata survive normalization;
+- enrichment diagnostics survive until the later firewall;
+- the downstream observer sees normalized metadata before firewall redaction;
+- with session hygiene enabled, synthetic secrets are removed from final result content/details without restoring the deleted duplicate;
+- with session hygiene disabled, visible content is not redacted while metadata-only normalization still occurs;
+- the input result object itself is not mutated.
+
+A headless AgentSession contract separately proves that the normalized/redacted
+result, rather than the earlier secret-bearing result, is what reaches JSONL and
+the next model context. The provider-hook contract proves that credential
+redaction followed by the final Codex sanitizer neither restores the secret nor
+restores rejected reasoning/prompt-cache fields.
+
+Tool-result `details` bytes are therefore reported as JSONL/metadata overhead,
+not as provider-token savings. The checked OpenAI-completions serializer already
+omits tool-result details.
+
+## Deterministic gate
+
+```text
+bun test test/context-gateway \
+  test/evals/recovery-corpus.test.ts \
+  test/evals/recovery-run-identity.test.ts \
+  test/evals/recovery-report.test.ts \
+  test/evals/recovery-validation.test.ts \
+  test/evals/harness.test.ts \
+  test/config.test.ts \
+  test/evals/extension-contracts.test.ts
+```
+
+Result: **88 pass, 0 fail, 667 assertions**.
+
+Additional checks:
+
+- `npm run typecheck` — pass.
+- `git diff --check` — pass.
+
+No manual suite sync was run; the user-owned watcher remains the synchronization
+mechanism and is not evidence of which bytes a future live run loads.

package/external/pi-tools-suite/docs/context-gateway-p01r-rc-evidence.md

@@ -0,0 +1,69 @@
+# Context Gateway P01-R / R-C evidence
+
+<!-- markdownlint-disable MD013 -->
+
+> Date: 7 September 2026.
+> Repository HEAD during deterministic gate: `daa1b06` with a dirty tested tree.
+> Installed Pi SDK: `@earendil-works/pi-coding-agent` `0.85.1`.
+> Scope: native paging/current-view semantics and temporary full-output lifetime. No durable snapshot, artifact reader, shell rewrite or live model call was added.
+
+## Read is a current decoded text view, not a snapshot reader
+
+Installed SDK `Read` uses 1-based line `offset`/`limit` over `Buffer.toString("utf-8").split("\n")`.
+R-C contracts verify:
+
+- CRLF and Unicode survive relative to that decoded SDK text view;
+- explicit `limit` produces an actionable next line offset;
+- empty files and EOF/out-of-range offsets are distinguishable;
+- a very large limit does not create a separate byte pagination protocol;
+- a single line larger than the SDK byte limit is an honest **limited** case: the result points at a shell fallback and does not fabricate `Use offset=` recovery;
+- the Read schema exposes no `byteOffset` or generic cursor;
+- re-executing the same path after the source changes returns the new file view. Same path/offset is therefore not an immutable historical snapshot.
+
+This project does not claim byte-for-byte source-file coordinates beyond the SDK's decoded text semantics.
+
+## Repo Native Compact cursors are current-index cursors
+
+The checked native cursor surface exists only on `repo_structure` and `repo_ast`.
+`repo_search` has no cursor flag in the current wrapper policy and is not described as if it did.
+
+R-C tightens integer native flags to `Number.isSafeInteger`: negative or unsafe integer cursors are refused before `idx`. Re-running the same `repo_structure --cursor 20` executes `idx` again; a deterministic fake backend returning version 1 and then version 2 produces two different results for the same cursor. The cursor is therefore a continuation token for current backend/index state, not a snapshot identifier.
+
+No command execution is suppressed because args/cursor match an earlier call.
+
+## Successful temp output versus error paths
+
+For a successful large built-in Bash result, the installed SDK returns a structured `details.fullOutputPath`. The file contains the complete emitted output and a normal Read can recover an omitted head fact.
+
+The same path has no durability guarantee. The test replaces its contents and a later Read sees the replacement; after deletion a later Read fails. A native temp path is thus an ephemeral current file handle, not historical snapshot identity.
+
+Bash timeout, abort and non-zero exit preserve their visible status and captured visible output but reject the tool execution. The current exception bridge does not expose a structured `fullOutputPath` result. SDK-formatted error text may itself mention its generated temp path when the partial output was truncated; R-C does **not** parse such text into a trusted capability, because look-alike paths in arbitrary text are not authorization/provenance.
+
+The suite `ast_grep` path behaves similarly but is suite-owned: successful truncated output returns a structured full-output handle containing the complete combined output. Cancelled/killed output returns an explicit cancelled result without a full-output handle, and a real tool error throws instead of publishing a successful artifact capability.
+
+## Broad-output decision
+
+R-C does not introduce another generic cap for built-in Read or rewrite user shell commands. Current evidence already shows successful native recovery for ordinary line-based Read and successful Bash/ast-grep temp-output cases, while long single-line Read and error-path handles remain explicitly limited.
+
+For repo tools the existing opt-in Native Compact profile remains the only new scope/budget enforcement: narrow native defaults, explicit same-call bounded `outputMode=full`, and current-index cursors where the backend exposes them. Search without a native cursor is not given a synthetic one.
+
+A stricter broad-read/search delivery policy requires a demonstrated task where its required facts remain recoverable under the claimed mechanism. Until then small/exact/instruction reads and shell execution stay unchanged.
+
+## Deterministic gate
+
+```text
+bun test \
+  test/context-gateway/native-recovery-contracts.test.ts \
+  test/repo-native-compact.test.ts \
+  test/context-gateway/capture-contracts.test.ts \
+  test/context-gateway/sdk-pipeline.test.ts
+```
+
+Result: **46 pass, 0 fail, 352 assertions**.
+
+Additional checks:
+
+- `npm run typecheck` — pass.
+- `git diff --check` — pass.
+
+Session-history recovery remains plan 32 work. R-C creates neither `artifact_read` nor a catalog and makes no resume/export guarantee for native temp files or current-index cursors.

package/external/pi-tools-suite/docs/context-gateway-p01r-rd-evidence.md

@@ -0,0 +1,100 @@
+# Context Gateway P01-R / R-D evidence
+
+<!-- markdownlint-disable MD013 -->
+
+> Date: 7 September 2026.
+> Repository HEAD during deterministic gate: `daa1b06` with a dirty tested tree.
+> Scope: pure test/build parsing plus passive observe classification. Production tool-result delivery remains passthrough; no archive, reference, fetch, execution or LLM summary is introduced.
+
+## Supported parser scope
+
+R-D adds `src/context-gateway/test-output-parser.ts` as a pure in-memory parser for a deliberately small format set:
+
+- Bun test terminal summaries (`pass`, `fail`, `Ran ... tests across ... files`) and exact failure/warning lines;
+- TAP v13-style terminal plan/count summaries and exact `not ok` / diagnostic lines;
+- bounded TypeScript compiler diagnostics plus an explicit terminal `Found N error(s)` summary.
+
+The parser returns `recognised`, `partial`, or `unrecognised`. Host execution outcome remains authoritative; text does not turn an errored shell call into success. A failed test summary without an exact parsed diagnostic is not considered complete.
+
+The parser's ANSI and bare-CR processing creates only an internal parsing view. It does not mutate the original tool result or claim source byte coordinates.
+
+## Conservative failure rules
+
+The parser/delivery planner intentionally falls back to passthrough when any of these conditions holds:
+
+- SDK/upstream truncation is already reported;
+- timeout/abort is visible;
+- terminal summary conflicts with the host outcome (for example PASS summary followed by command exit 1);
+- multiple recognised formats appear in one output;
+- TypeScript pretty/source/caret lines remain unparsed;
+- a failed summary has no captured exact failure diagnostic;
+- the terminal summary is followed by significant unrecognised output;
+- parser input exceeds the bounded scan budget (default 1 Mi-character); head/tail resemblance is not promoted to completeness;
+- the originating shell command is compound or its scope is unknown;
+- a prospective complete compact representation would exceed the configured byte budget.
+
+Compound-command detection is transient and conservative. Observe stores only `simple / compound / unknown`, never the shell command text. False positives merely preserve passthrough; they never rewrite or block execution.
+
+## Prospective compact delivery is all-or-passthrough
+
+`planProspectiveTestOutputDelivery` is a decision helper, not a production shaper. For a complete recognised **simple** command it can build a candidate containing:
+
+1. exact host outcome;
+2. recognised format;
+3. terminal summary counts;
+4. every parsed mandatory error/warning line.
+
+The candidate is accepted only when the entire representation fits the budget. Diagnostics are never sliced merely to hit a target. `partial` and `unrecognised` inputs have no generic head/tail summary path.
+
+No runtime adapter consumes this candidate in R-D. The current Context Gateway `tool_result` handler still returns `undefined`, so delivered content stays byte-equivalent. Connecting a compact delivery requires a later explicit adapter decision with a recovery/lifetime mechanism appropriate to the omitted data. Native truncation alone is not that permission.
+
+## Observe telemetry
+
+Shell output is parsed transiently only while Context Gateway is in `observe` mode. The telemetry snapshot stores:
+
+- parser version;
+- classification and format counts;
+- scan-limited count;
+- terminal-summary / diagnostic / warning counts for the last observation;
+- safe command-scope enum;
+- prospective `compact-candidate / passthrough` decision and allowlisted reason.
+
+It does **not** store command args, diagnostic strings, filenames from diagnostics, raw body, snippets, or hidden-fact fingerprints. Tests compare the input event before/after telemetry and prove it is not mutated.
+
+## Corpus cases
+
+The deterministic corpus covers:
+
+- complete Bun success;
+- a Bun error in the middle of output plus a warning and later passing test;
+- PASS summary followed by host exit 1;
+- timeout;
+- upstream-truncated output;
+- ANSI and bare-CR overwrite;
+- TAP failure with exact diagnostics;
+- compact TypeScript diagnostics and a pretty/unparsed partial case;
+- mixed/nested recognised formats;
+- unknown custom build output;
+- compound and unknown command scope;
+- an intentionally huge output exceeding the parser scan bound;
+- prospective output that fits the byte budget and the same mandatory diagnostics under a too-small budget.
+
+These are format contracts, not claims that every Bun/TAP/TypeScript version is supported. Unknown variants remain passthrough.
+
+## Deterministic gate
+
+```text
+bun test \
+  test/context-gateway/test-output-parser.test.ts \
+  test/context-gateway/observe.test.ts \
+  test/evals/harness.test.ts
+```
+
+Result: **28 pass, 0 fail, 152 assertions**.
+
+Additional checks:
+
+- `npm run typecheck` — pass.
+- `git diff --check` — pass.
+
+No live model call, manual sync, user config change, result replacement or new full-output archive was performed for R-D.

package/external/pi-tools-suite/docs/context-gateway-p01r-re-evidence.md

@@ -0,0 +1,74 @@
+# Context Gateway P01-R / R-E evidence
+
+<!-- markdownlint-disable MD013 -->
+
+> Date: 7 September 2026.
+> Repository HEAD during deterministic gate: `daa1b06` with a dirty tested tree.
+> Scope: mutation/LSP outcome integrity and storeless capability inventory for web/docs, structured JSON, subagents and visual results. No archival adapter, fetcher, grant or lifetime extension was added.
+
+## Mutation and LSP
+
+R-E keeps mutations as native passthrough. An actual `applyPatch` run in a temporary fixture proves that its returned `changedFiles`/summary contain only the file changed by that invocation while an unrelated dirty file remains untouched and absent from the result. `getEventPaths` prefers `details.changedFiles` over broader input/patch-shaped paths, so downstream LSP refresh does not derive a whole-workspace diff.
+
+The pre-approved patch string is not rewritten by Context Gateway. Errored/cancelled mutation results are no-ops for LSP enrichment and storeless metadata cleanup, preserving their original result object/outcome. Existing LSP integration tests continue to cover successful post-edit diagnostics, changed-file deduplication, deleted-file behavior and aliases. R-B SDK-chain tests separately prove that enrichment/protocol fields survive later storeless cleanup/security stages.
+
+No new “partial mutation” inference is introduced. If a producer reports partial/error/cancelled state, Gateway preserves that producer outcome rather than constructing a synthetic success or retry.
+
+## Capability matrix
+
+`src/context-gateway/storeless-capabilities.ts` records the current non-archival decisions. It is metadata only; importing it registers no tools/readers/adapters.
+
+| Surface | Status | Storeless strategy | Lifetime claim |
+| --- | --- | --- | --- |
+| test/build | limited | pure-parser candidate in observe only | current result |
+| mutation/LSP | supported | native passthrough | current result |
+| web/document | limited | native passthrough | current result |
+| structured JSON | limited | native passthrough | current result |
+| subagent result | limited | native passthrough | producer-managed |
+| visual/image | supported | native passthrough | visual message |
+| direct browser | unsupported | none | none |
+| direct MCP | unsupported | none | none |
+
+The matrix is a claim boundary, not feature discovery by name. Unsupported paths do not become supported merely because an output resembles JSON/HTML or contains a filesystem path.
+
+## Web/document path
+
+Existing web tool tests cover actual producer-owned HTTP behavior: request metadata, content/link metadata, Ollama→Tavily fallback, auth/API errors, invalid JSON, cancellation and timeout. Storeless Gateway adds no fetch callback and does not reinterpret headings/code or producer pagination/truncation metadata. A bounded R-E fixture confirms that `web_fetch` content remains byte-equivalent through observation.
+
+There is no storeless historical page reader. Producer truncation/pagination remains producer-owned, which is why web/document is `limited` rather than an archive-capable adapter.
+
+## Structured JSON
+
+No generic JSON parser/field selector is registered. A fixture containing the exact literal `9007199254740993123456789` remains opaque text and is not parsed into a JavaScript number, rounded, ranked or field-selected. Upstream pagination metadata is left on the producer result. A dedicated typed adapter requires a future concrete use case and precision contract.
+
+## Subagents
+
+The existing async-subagent result tool already emits a bounded summary plus paths to producer artifacts and explicitly avoids inlining raw logs. Its tests cover missing/running/completed states, structured result generation, artifact paths, cleanup and session lifecycle.
+
+P01-R does not read internal subagent history, does not turn an artifact path into an authorization grant and does not extend artifact lifetime. A completed path therefore remains `producer-managed`; it is not promised to survive producer cleanup/resume/export.
+
+## Visual and unsupported direct paths
+
+Image parts remain image parts and are accounted separately from text. No textual placeholder replaces them as a context optimization.
+
+P00 did not prove a direct parent Context Gateway boundary for browser DOM/network/console or a current direct MCP execution adapter. Both remain explicitly `unsupported`; R-E does not add placeholder adapters to make the matrix look complete.
+
+## Deterministic gate
+
+```text
+bun test \
+  test/context-gateway/storeless-format-contracts.test.ts \
+  test/lsp.test.ts \
+  test/web-search.test.ts \
+  test/async-subagents/tools.test.ts \
+  test/context-gateway/sdk-pipeline.test.ts
+```
+
+Result: **107 pass, 0 fail, 689 assertions**.
+
+Additional checks:
+
+- `npm run typecheck` — pass.
+- `git diff --check` — pass.
+
+No live model call, manual sync, user-config change or result-shaping adapter was added for R-E.

package/external/pi-tools-suite/docs/context-gateway-p01r-rf-evidence.md

@@ -0,0 +1,153 @@
+# Context Gateway P01-R / R-F evidence
+
+<!-- markdownlint-disable MD013 -->
+
+> Date: 7 September 2026.
+> Repository HEAD during deterministic gate: `daa1b06` with a dirty tested tree.
+> Scope: storeless lifecycle and current-result UI/replay only. No new persistent artifact service, native-temp reader endpoint, fork grant, export bundle, DCP lifecycle implementation or manual sync was added.
+
+## Runtime / transient lifecycle
+
+Context Gateway observe state is runtime-local. The current implementation tracks
+in-flight tool call IDs separately from aggregate telemetry and refuses an
+`off ↔ observe` mode change while any tool call is still in flight. At a safe
+boundary the mode change clears transient call bindings. `session_start`,
+`session_tree` and `session_shutdown` reset transient and aggregate observation
+state.
+
+Deterministic contracts additionally prove:
+
+- a mode change requested during an observed call is rejected until that result
+  completes; the result is attributed to the old effective observe epoch once;
+- lifecycle reset removes pending bindings and counters rather than carrying them
+  into a resumed/switched branch;
+- two Read/shell calls may complete in reverse order without crossing tool class,
+  parser command-scope or call identity;
+- an unbound result increments the explicit `unboundResults` counter but its
+  bytes/class/parser facts are not aggregated as current-session evidence;
+- extension reload during an in-flight SDK tool remains a separate P00 limitation
+  and is not hidden by telemetry; root tab/session generation guards keep a late
+  result owned by its origin tab.
+
+No suppression ledger is introduced, and no persisted JSONL message is rewritten
+when mode or session lifecycle changes.
+
+## TUI / current result rendering
+
+R-B already proves collapsed/expanded renderer equivalence for the exact
+Read/Bash/ast_grep metadata-normalization surfaces, including image preservation.
+The root renderer/session gate additionally covers:
+
+- shell running/nonzero/signal rendering;
+- LSP diagnostic severity rendering and mutation tool blocks;
+- truncated collapsed previews and expanded full current-result bodies;
+- persisted history tail/replay, unresolved/completed historical tool calls and
+  cancellation while older history is being prepended;
+- stale runtime/session event rejection and late tool-result binding to the
+  original inactive tab.
+
+These are current/persisted tool-result views; they are not a new route to the
+producer's full native temp output.
+
+## ACP / Desktop lazy current-result hydration
+
+Pix already has `pix/session/history`, `pix/session/tool_result` and deferred image
+hydration for Desktop. The lazy tool-result route is explicitly scoped by the ACP
+`sessionId` and the deferred result map created for that session. For a persisted
+result, the backend stores a trusted `sessionPath + byte offset + byte length`
+reference and materializes exactly that persisted JSONL message line on demand.
+
+The ACP contract now proves that requesting a deferred result:
+
+- does not replay or append a `session/update`;
+- returns the persisted current tool-result content/details only on explicit
+  hydration;
+- cannot be performed with another session's ID even when the tool call ID is
+  known;
+- frees the duplicate backend deferred copy after successful hydration.
+
+Desktop transcript logic keeps deferred results lightweight until expansion,
+hydrates them into the local transcript, and separately hydrates deferred image
+bodies. This is a human/UI operation; it does not create a new model tool result
+or provider input.
+
+## Native temp output: deliberate limitation
+
+There is **no existing authenticated host route that reads the contents of a
+`Read`/Bash/ast_grep native temp/full-output handle for TUI/ACP/Desktop**.
+`pix/session/tool_result` is not such a route: it reads a persisted JSONL result,
+not the producer's `fullOutputPath` contents.
+
+Therefore R-F adds no “open full native source” button or ACP endpoint. The UI may
+show the current result/status/diagnostics already available through the normal
+message path, but P01-R does not widen filesystem access merely because a result
+contains a temp path. R-C's lifetime limitations remain in force: temp paths can
+be absent, mutable, expired, or unavailable on error/timeout/abort and have no
+resume/fork/export guarantee.
+
+## Deterministic gates
+
+Context Gateway lifecycle/result gate:
+
+```text
+bun test \
+  test/context-gateway/observe.test.ts \
+  test/context-gateway/sdk-pipeline.test.ts \
+  test/context-gateway/metadata-normalization.test.ts
+```
+
+Result: **49 pass, 0 fail, 337 assertions**. Suite typecheck and `git diff --check`
+also pass for this gate.
+
+Root TUI/session gate:
+
+```text
+node --import tsx --test \
+  tests/conversation-tool-renderer.test.ts \
+  tests/tool-block-renderer.test.ts \
+  tests/conversation-shell-renderer.test.ts \
+  tests/session-history.test.ts \
+  tests/session-lifecycle-controller.test.ts \
+  tests/tabs-controller.test.ts
+```
+
+Result: **98 pass, 0 fail**.
+
+ACP lazy current-result gate:
+
+```text
+node --import tsx --test \
+  --test-name-pattern='desktop lazy session/load omits tool bodies and retrieves them on demand|desktop lazy session/load reuses an already-live tab runtime|deferred' \
+  test/agent.test.ts test/session-replay.test.ts
+npm run typecheck
+```
+
+Result: **4 pass, 0 fail**; ACP typecheck passes. The targeted lazy-result test
+also asserts no hydration `session/update` and denial for another session ID.
+
+An additional ACP boundary suite covers persisted lazy materialization and replay:
+
+```text
+node --import tsx --test \
+  test/session-replay.test.ts \
+  test/session-history-file.test.ts \
+  test/desktop-commands.test.ts
+```
+
+Result: **6 pass, 0 fail**. It additionally proves that the Desktop tool-result
+request surface is `sessionId + toolCallId` scoped, ignores arbitrary path-like
+extras, legacy persisted metadata is not retroactively normalized during replay,
+and deferred image/tool bodies are hydrated only from their existing persisted
+session references.
+
+Desktop gate:
+
+```text
+npm run check
+npm test -- src/lib/transcript.test.ts src/lib/acp-client.test.ts
+```
+
+Result: Desktop check has **0 errors** and two pre-existing Svelte accessibility
+warnings in `WorkspaceSidebar.svelte`; targeted tests are **28 pass, 0 fail**.
+
+No live model call or manual suite sync was used for R-F.