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.