docs/integration.md

# Integration notes

## Inputs

- Upstream: `https://huggingface.co/spaces/victor/MiniCPM5-2B-WebGPU-Pi`.
- Cloned commit: `8ac95048396e4cb8ae997d6996505f499fa0c67b`.
- Supplied archive SHA-256: `063e89c96bb7afdeb476fc04f4031a8dfdba0fd4d8e175d61490dc49643d949c`.
- `runtime/minicpm5.js` SHA-256: `785c0cdba03a74f1b00be99f6fe6abcfedb22292f92bc89bbf78ea546ab5a4f7`.
- `runtime/agent.js` SHA-256: `1a15c495d2a4f699f2629d023ec17717f115c97c964f0e8c7e67d9d0a583c7b0`.

Both supplied modules are copied unchanged. Model weights use the supplied
runtime's default GGUF repository/file at revision `main`. Its loader validates
format and resource identity; the app does not claim a pinned weight revision or
whole-file SHA-256 verification.

## Replacement boundary

The UI starts `src/agent.worker.js` as a module worker. `WorkspaceController`
loads `MiniCPM5ForCausalLM` directly and constructs the supplied `Agent`. The
agent owns one lazily created session and reuses it for follow-ups and new chats.
Agent and model resources are disposed separately after device loss.

Pi's agent core, Transformers.js model/tokenizer loader, ONNX Runtime, custom
ONNX download/cache layer, XML tool parser, sampling adapter, and WASM binaries
from the original worker are removed. The runtime handles tokenization, GGUF
weights, prompt rendering, KV caching, reasoning/text separation, and validated
tool-call parsing.

The frontend still uses Pi's terminal components. `conversation.js` translates
display events only: it does not implement inference or another agent loop.
Tool arguments are already parsed objects. Tool definitions use plain JSON
Schema and execute against the same just-bash workspace as the editor and shell.
Nonzero bash exits reject so the supplied agent recognizes failures and avoids
repeating identical failed calls.

## History and persistence

Canonical messages come directly from the supplied Agent and are preserved
unchanged. Pi-formatted display messages are stored separately. Saves happen
after each completed reply and tool result, before the agent continues, and
again when the run settles. Storage failures leave the in-memory workspace
usable and report that saving failed.

The database is `minicpm5-gguf-workspace`, distinct from the original Pi database
because the message schemas differ. Existing upstream conversations are not
automatically migrated. Export important old files from the original app and
import text files into this version. A clone on a new origin also naturally has
separate browser storage.

The attached Agent intentionally excludes an interrupted partial assistant
reply from its own history. If no complete assistant reply was produced, its
user turn is omitted too. The UI retains that interrupted exchange for review,
marks it stopped, and explains that it is not used as model history. Completed
tool rounds remain valid and are saved.

## Loading and metrics

Only byte progress is rendered as transferred bytes. Tensor uploads and GPU
preparation are indeterminate. The UI becomes ready only after
`from_pretrained` resolves. The requested context is 8,192 tokens and the UI is
updated to the runtime's actual device-dependent capacity.

Cache probing conservatively returns false because the supplied public API has
no complete-cache check. This preserves an honest download confirmation while
allowing the runtime's range cache to work normally. `cachedOnly` requests fail
with `MODEL_CACHE_MISS`, without starting a network load.

The old sampling configuration is removed. The runtime decodes greedily.
Generation activity is shown while deltas stream. Exact token counts, TTFT,
cached tokens, and decode speed are taken from completed runtime results rather
than estimated from characters.

## Verification

Validation completed: **37 tests passed** with `npm test`, including real
shell/tool execution, supplied-agent lifecycle checks, controller/event checks
with fake model sessions, and the actual worker module/RPC transport using the
real shell. `npm run build` passed. Every shipped JavaScript file passed syntax
checks, local asset/module references resolved, and both supplied runtime
modules matched the archive byte-for-byte. These checks do not validate
numerical inference, shader
compatibility, actual GGUF download/cache recovery, or visual layout in a browser.

No browser-control capability or WebGPU device was available for a browser
inference check. The upstream layout/assets were retained, but the updated app
still needs the following checks on the intended GPU:

1. Start locally, load the GGUF, and verify download progress and actual context.
2. Ask for total sales revenue; verify the agent reads both files, computes
   $144, writes a report, and reads it back.
3. Ask for a script, run it, edit it, and verify the updated output.
4. Stop during reasoning and during a shell task; send a follow-up.
5. Reload and verify workspace restoration and cache reuse.
6. Start a new chat and verify files remain; test Import/Export and narrow layout.

The original project's conversion benchmarks and browser validation claims are
not carried forward: they measured a different model format and runtime.