haebom commited on
Commit
506a341
·
verified ·
1 Parent(s): 5810e5b

Sync source with GitHub 84fddf0

Browse files
README.md CHANGED
@@ -77,6 +77,36 @@ Chrome Web Store version **0.1.0** passed review and is publicly available as
77
  verified on 2026-09-25. Store availability is not evidence of model quality,
78
  scientific validity or production readiness.
79
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
80
  ## Local use
81
 
82
  ```sh
 
77
  verified on 2026-09-25. Store availability is not evidence of model quality,
78
  scientific validity or production readiness.
79
 
80
+ ## Local MCP stdio server
81
+
82
+ The TypeScript SDK includes a local-only MCP stdio server for Codex and Claude
83
+ Code hosts. It exposes one `vons_decide` tool and a read-only bundle metadata
84
+ resource. The host must provide an explicit path to a user-supplied,
85
+ manifest-verified ONNX bundle. The server validates requests and responses but
86
+ does not execute downstream tools, authorize actions, or start an HTTP listener.
87
+ Its Codex and Claude Code setup examples, input contract and filesystem checks
88
+ are documented in the [TypeScript SDK guide](sdk/typescript/README.md#codex-project-local-stdio-setup-example).
89
+
90
+ The source preview contains the MCP server source, but no model weights,
91
+ tokenizer assets, runtime bundle, or preconfigured local MCP server. A host
92
+ integration still requires a compatible local bundle and explicit local setup.
93
+
94
+ ## Ollama local tool calls
95
+
96
+ The Python integration wraps Ollama's loopback `/api/chat` tool-calling API around one Vons function, `vons_decide`. The host validates the structured request against the Vons contract and runs only a user-supplied, manifest-verified ONNX bundle. Model output cannot dispatch arbitrary tools or authorize actions. Raw Ollama output and the validated Vons response remain separate.
97
+
98
+ This source preview does not include an Ollama model, ONNX bundle, pretrained weights, or tokenizer assets. Install and configure those locally before using the inference path.
99
+
100
+ ```sh
101
+ python -m pip install -e '.[inference]'
102
+ python -m vons.cli ollama-tool-call --help
103
+ python -m vons.cli ollama-tool-call \
104
+ --host http://127.0.0.1:11434 \
105
+ --model <locally-installed-ollama-model> \
106
+ --bundle <verified-local-bundle-directory> \
107
+ --input <messages.json>
108
+ ```
109
+
110
  ## Local use
111
 
112
  ```sh
configs/public-release.json CHANGED
@@ -14,9 +14,9 @@
14
  "LICENSE",
15
  "README.md",
16
  "configs/pilot-diffusion.json",
17
- "configs/pilot.json",
18
  "configs/pilot-v2-diffusion.json",
19
  "configs/pilot-v2-direct.json",
 
20
  "configs/public-release.json",
21
  "docs/COMMUNITY.md",
22
  "docs/HUB_PUBLISHING.md",
@@ -27,11 +27,11 @@
27
  "docs/PUBLIC_RELEASE.md",
28
  "docs/assets/inlevel9-signature-dark.png",
29
  "docs/assets/inlevel9-signature.png",
30
- "docs/assets/vons-logo.png",
31
  "docs/assets/vons-extension-icon-128.png",
32
  "docs/assets/vons-extension-icon-16.png",
33
  "docs/assets/vons-extension-icon-32.png",
34
  "docs/assets/vons-extension-icon-48.png",
 
35
  "docs/publications/ARXIV.md",
36
  "docs/publications/LICENSE.md",
37
  "docs/publications/README.md",
@@ -65,9 +65,12 @@
65
  "sdk/typescript/package-lock.json",
66
  "sdk/typescript/package.json",
67
  "sdk/typescript/src/index.ts",
 
 
68
  "sdk/typescript/src/onnx.ts",
69
  "sdk/typescript/test/extension.test.mjs",
70
  "sdk/typescript/test/index.test.mjs",
 
71
  "sdk/typescript/test/onnx.test.mjs",
72
  "sdk/typescript/test/parity.test.mjs",
73
  "tests/test_browser_benchmark.py",
@@ -88,6 +91,7 @@
88
  "tests/test_mind2web_prediction.py",
89
  "tests/test_mind2web_replay.py",
90
  "tests/test_mind2web_runner.py",
 
91
  "tests/test_onnx_export.py",
92
  "tests/test_public_release.py",
93
  "tests/test_quality_summary.py",
@@ -128,6 +132,7 @@
128
  "vons/mind2web_adapter.py",
129
  "vons/models.py",
130
  "vons/ollama.py",
 
131
  "vons/research.py",
132
  "vons/training.py"
133
  ],
 
14
  "LICENSE",
15
  "README.md",
16
  "configs/pilot-diffusion.json",
 
17
  "configs/pilot-v2-diffusion.json",
18
  "configs/pilot-v2-direct.json",
19
+ "configs/pilot.json",
20
  "configs/public-release.json",
21
  "docs/COMMUNITY.md",
22
  "docs/HUB_PUBLISHING.md",
 
27
  "docs/PUBLIC_RELEASE.md",
28
  "docs/assets/inlevel9-signature-dark.png",
29
  "docs/assets/inlevel9-signature.png",
 
30
  "docs/assets/vons-extension-icon-128.png",
31
  "docs/assets/vons-extension-icon-16.png",
32
  "docs/assets/vons-extension-icon-32.png",
33
  "docs/assets/vons-extension-icon-48.png",
34
+ "docs/assets/vons-logo.png",
35
  "docs/publications/ARXIV.md",
36
  "docs/publications/LICENSE.md",
37
  "docs/publications/README.md",
 
65
  "sdk/typescript/package-lock.json",
66
  "sdk/typescript/package.json",
67
  "sdk/typescript/src/index.ts",
68
+ "sdk/typescript/src/mcp-cli.ts",
69
+ "sdk/typescript/src/mcp.ts",
70
  "sdk/typescript/src/onnx.ts",
71
  "sdk/typescript/test/extension.test.mjs",
72
  "sdk/typescript/test/index.test.mjs",
73
+ "sdk/typescript/test/mcp.test.mjs",
74
  "sdk/typescript/test/onnx.test.mjs",
75
  "sdk/typescript/test/parity.test.mjs",
76
  "tests/test_browser_benchmark.py",
 
91
  "tests/test_mind2web_prediction.py",
92
  "tests/test_mind2web_replay.py",
93
  "tests/test_mind2web_runner.py",
94
+ "tests/test_ollama_tool_call.py",
95
  "tests/test_onnx_export.py",
96
  "tests/test_public_release.py",
97
  "tests/test_quality_summary.py",
 
132
  "vons/mind2web_adapter.py",
133
  "vons/models.py",
134
  "vons/ollama.py",
135
+ "vons/onnx_runtime.py",
136
  "vons/research.py",
137
  "vons/training.py"
138
  ],
docs/COMMUNITY.md CHANGED
@@ -13,8 +13,9 @@ report what works or fails.
13
  | Read the research | [Paper and Tech Report](publications/README.md) | Reviewed PDFs and exact verification scope are included |
14
  | Try without weights | The walkthrough below | Deterministic contract and synthetic data only |
15
  | Run model inference | [TypeScript SDK](../sdk/typescript/README.md) | Requires separately obtained, reviewed model/tokenizer assets |
16
- | Share experience | [Experience report](https://github.com/inlevel9-com/Vons/issues/new?template=experience.yml) | GitHub account required to submit |
17
- | Reproduce a result | [Reproduction report](https://github.com/inlevel9-com/Vons/issues/new?template=reproduction.yml) | Form included; evidence reviewed separately |
 
18
  | Improve Vons | [Contributing](../CONTRIBUTING.md) | Documentation, tests and scoped code changes welcome |
19
 
20
  The destinations are [GitHub: inlevel9-com/Vons](https://github.com/inlevel9-com/Vons)
@@ -27,6 +28,24 @@ The current software terms require a separate agreement for
27
  enterprise/commercial use, including enterprise evaluation. Reading the paper
28
  under its article terms is separate from software use.
29
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
30
  ## A five-minute first exploration
31
 
32
  Five minutes is a usability target, not a measured onboarding result. Start in
 
13
  | Read the research | [Paper and Tech Report](publications/README.md) | Reviewed PDFs and exact verification scope are included |
14
  | Try without weights | The walkthrough below | Deterministic contract and synthetic data only |
15
  | Run model inference | [TypeScript SDK](../sdk/typescript/README.md) | Requires separately obtained, reviewed model/tokenizer assets |
16
+ | Try the Chrome extension | [Chrome Web Store listing](https://chromewebstore.google.com/detail/vons-%E2%80%94-local-decisions/cbmjkokoojinfgafahncmjlfmicinide) and [setup guide](../sdk/typescript/extension/README.md) | Requires a compatible local model bundle; this repository does not include weights or tokenizer assets |
17
+ | Share experience | [Experience report](https://github.com/inlevel9-com/Vons/issues/new?template=experience.yml), or [optional email fallback](mailto:oswarld@inlevel9.com?subject=Vons%20first-use%20feedback) | The issue form may be blocked; email is optional and not posted publicly |
18
+ | Reproduce a result | [Reproduction report](https://github.com/inlevel9-com/Vons/issues/new?template=reproduction.yml), or [email a reproduction report](mailto:oswarld@inlevel9.com?subject=Vons%20reproduction%20report) | Evidence is reviewed separately; do not attach restricted inputs |
19
  | Improve Vons | [Contributing](../CONTRIBUTING.md) | Documentation, tests and scoped code changes welcome |
20
 
21
  The destinations are [GitHub: inlevel9-com/Vons](https://github.com/inlevel9-com/Vons)
 
28
  enterprise/commercial use, including enterprise evaluation. Reading the paper
29
  under its article terms is separate from software use.
30
 
31
+ GitHub may require you to sign in before using the report forms. If you cannot
32
+ submit a report there, you can email a short first-use report to
33
+ [oswarld@inlevel9.com](mailto:oswarld@inlevel9.com?subject=Vons%20first-use%20feedback).
34
+ This is voluntary and goes to the email recipients rather than being posted as
35
+ a public issue; it is not telemetry or an automatic model-training signal.
36
+ Please do not send secrets, private prompts, customer traces, restricted data or
37
+ model weights. A useful short report can answer:
38
+
39
+ 1. What were you trying to accomplish, and which Vons path did you try?
40
+ 2. Did you get a useful first result? If not, where did you get stuck?
41
+ 3. Would you use Vons again for this task? What one change would make it useful?
42
+
43
+ For a reproduction, include the claim/source, environment, steps, expected and
44
+ observed behavior, and permitted hashes. Keep raw or restricted inputs local.
45
+ The source revision, device and runtime are optional for experience reports;
46
+ omit personal or confidential details. Email may reveal your address to its
47
+ recipients.
48
+
49
  ## A five-minute first exploration
50
 
51
  Five minutes is a usability target, not a measured onboarding result. Start in
docs/HUGGING_FACE.md CHANGED
@@ -77,6 +77,36 @@ Chrome Web Store version **0.1.0** passed review and is publicly available as
77
  verified on 2026-09-25. Store availability is not evidence of model quality,
78
  scientific validity or production readiness.
79
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
80
  ## Local use
81
 
82
  ```sh
 
77
  verified on 2026-09-25. Store availability is not evidence of model quality,
78
  scientific validity or production readiness.
79
 
80
+ ## Local MCP stdio server
81
+
82
+ The TypeScript SDK includes a local-only MCP stdio server for Codex and Claude
83
+ Code hosts. It exposes one `vons_decide` tool and a read-only bundle metadata
84
+ resource. The host must provide an explicit path to a user-supplied,
85
+ manifest-verified ONNX bundle. The server validates requests and responses but
86
+ does not execute downstream tools, authorize actions, or start an HTTP listener.
87
+ Its Codex and Claude Code setup examples, input contract and filesystem checks
88
+ are documented in the [TypeScript SDK guide](../sdk/typescript/README.md#codex-project-local-stdio-setup-example).
89
+
90
+ The source preview contains the MCP server source, but no model weights,
91
+ tokenizer assets, runtime bundle, or preconfigured local MCP server. A host
92
+ integration still requires a compatible local bundle and explicit local setup.
93
+
94
+ ## Ollama local tool calls
95
+
96
+ The Python integration wraps Ollama's loopback `/api/chat` tool-calling API around one Vons function, `vons_decide`. The host validates the structured request against the Vons contract and runs only a user-supplied, manifest-verified ONNX bundle. Model output cannot dispatch arbitrary tools or authorize actions. Raw Ollama output and the validated Vons response remain separate.
97
+
98
+ This source preview does not include an Ollama model, ONNX bundle, pretrained weights, or tokenizer assets. Install and configure those locally before using the inference path.
99
+
100
+ ```sh
101
+ python -m pip install -e '.[inference]'
102
+ python -m vons.cli ollama-tool-call --help
103
+ python -m vons.cli ollama-tool-call \
104
+ --host http://127.0.0.1:11434 \
105
+ --model <locally-installed-ollama-model> \
106
+ --bundle <verified-local-bundle-directory> \
107
+ --input <messages.json>
108
+ ```
109
+
110
  ## Local use
111
 
112
  ```sh
pyproject.toml CHANGED
@@ -16,6 +16,7 @@ dependencies = []
16
  [project.optional-dependencies]
17
  train = ["numpy>=1.26", "torch>=2.2", "transformers>=4.40", "safetensors>=0.4"]
18
  export = ["onnx>=1.16", "onnxruntime>=1.18", "onnxscript>=0.5"]
 
19
  ollama = ["ollama>=0.3"]
20
  dev = ["pytest>=8", "ruff>=0.6"]
21
 
 
16
  [project.optional-dependencies]
17
  train = ["numpy>=1.26", "torch>=2.2", "transformers>=4.40", "safetensors>=0.4"]
18
  export = ["onnx>=1.16", "onnxruntime>=1.18", "onnxscript>=0.5"]
19
+ inference = ["numpy>=1.26", "onnxruntime>=1.18", "tokenizers>=0.19"]
20
  ollama = ["ollama>=0.3"]
21
  dev = ["pytest>=8", "ruff>=0.6"]
22
 
sdk/typescript/README.md CHANGED
@@ -41,6 +41,134 @@ For a UI that does not require serving the development workspace, build the
41
  It packages the runtime locally and accepts a user-selected, hash-verified model
42
  folder. The guide explains installation and the separate model requirement.
43
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
44
  This package is private in npm metadata until an npm release is requested.
45
  Its `files` allowlist includes source, this guide and the software license. Models, tokenizers,
46
  datasets, generated demo JavaScript and dependencies are intentionally excluded
 
41
  It packages the runtime locally and accepts a user-selected, hash-verified model
42
  folder. The guide explains installation and the separate model requirement.
43
 
44
+ ## MCP stdio server (local-only, ONNX runtime backend)
45
+
46
+ This SDK ships a small, local-only Model Context Protocol (MCP) stdio server in
47
+ `src/mcp.ts` and `src/mcp-cli.ts`. It is strictly for hosts that already have a
48
+ user-supplied, hash-verified ONNX decision bundle on the local filesystem. The
49
+ server uses these exact, pinned npm dependencies:
50
+
51
+ - `@modelcontextprotocol/server` `2.1.0`
52
+ - `zod` `4.6.5`
53
+
54
+ ### What it exposes
55
+
56
+ Exactly one MCP tool and one read-only MCP resource:
57
+
58
+ - **Tool:** `vons_decide` — takes a strict DecisionRequest JSON object mirroring
59
+ the shared contract (`state`, `questions[]`, optional `backend`, optional
60
+ non-negative integer `seed`), validates it through the shared
61
+ `validateRequest` → `DecisionBackend.decide` → `validateResponse` pipeline,
62
+ and returns a JSON-serialized DecisionResponse as a single MCP `text` content
63
+ item. Malformed inputs raise an explicit MCP application error; no fake
64
+ `choice`, no silent fallback, and no coerced success. Explicit abstentions
65
+ (`status=abstain`, `choice=null`, `abstain_reason`) round-trip exactly as
66
+ returned by the backend.
67
+ - **Resource:** `vons://bundle/manifest/metadata` — non-sensitive metadata only.
68
+ Returns `schema_version`, `backend`, `model_id` (if declared), `option_count`,
69
+ and `sequence_length`. No local filesystem path is emitted. Never includes file
70
+ bytes, file hashes, tokenizer contents, graph data, or runtime asset digests.
71
+
72
+ ### What it explicitly does NOT do
73
+
74
+ Per the Vons pilot scope and AGENTS.md host boundary:
75
+
76
+ - No HTTP listener, no network, no remote MCP service.
77
+ - Writes MCP JSON-RPC messages **only** to stdout.
78
+ - Diagnostic messages, errors, warning banners, and runtime logs go **only** to stderr. The `--help` usage text is intentionally written to stdout (exit code 0) so it may be piped or redirected by shell callers; when usage is printed for invalid/missing flags it is still written to stderr with a non-zero exit status.
79
+ - Never executes downstream tools, never authorizes actions, never runs
80
+ host-side tooling.
81
+ - Never performs silent fallback decisions or substitutes a fake `choice`
82
+ when the input is invalid or the backend fails.
83
+ - No auto-discovery of bundles, no search for manifests, no default paths.
84
+ The user must pass an explicit `--bundle <dir>`.
85
+ - No request contents, response contents, or manifest asset hashes are ever
86
+ written to any file, network, or stderr log line outside the MCP stdout
87
+ JSON-RPC channel.
88
+
89
+ ### CLI usage
90
+
91
+ ```sh
92
+ node --experimental-strip-types sdk/typescript/src/mcp-cli.ts --bundle <dir> \
93
+ [--manifest-sha256 <64-char-hex>] [--provider wasm|webgpu]
94
+ ```
95
+
96
+ `--provider wasm` is the supported value. It is the only supported CLI value, and it is also the default when `--provider` is omitted entirely. `--provider webgpu` is explicitly rejected with exit code 4, because a stdio child process cannot obtain a browser WebGPU adapter. Hosts that want WebGPU must invoke the SDK directly from a browser/extension context that has called `requestAdapter()` explicitly.
97
+
98
+ ### Codex project-local stdio setup example
99
+
100
+ Create or edit `config.toml` in the Codex project's `.codex/` directory (or its
101
+ equivalent config location for your workspace):
102
+
103
+ ```toml
104
+ [mcp_servers.vons]
105
+ command = "node"
106
+ args = [
107
+ "--experimental-strip-types",
108
+ "/absolute/path/to/Vons/sdk/typescript/src/mcp-cli.ts",
109
+ "--bundle",
110
+ "/absolute/path/to/user-supplied-hash-verified-vons-bundle",
111
+ # Optional: remove these two arguments to skip pinning; otherwise replace the placeholder.
112
+ "--manifest-sha256",
113
+ "<64-char-lowercase-manifest-sha256>"
114
+ ]
115
+ ```
116
+
117
+ The host is responsible for consent, validation, and execution around this
118
+ server.
119
+
120
+ ### Claude Code project-local stdio setup example
121
+
122
+ Create or edit `.mcp.json` in the project root. Remove the optional flag/value
123
+ pair to skip pinning; otherwise replace the placeholder with the lowercase
124
+ SHA-256 of `bundle-manifest-v1.json` before use.
125
+
126
+ ```json
127
+ {
128
+ "mcpServers": {
129
+ "vons": {
130
+ "command": "node",
131
+ "args": [
132
+ "--experimental-strip-types",
133
+ "/absolute/path/to/Vons/sdk/typescript/src/mcp-cli.ts",
134
+ "--bundle",
135
+ "/absolute/path/to/user-supplied-hash-verified-vons-bundle",
136
+ "--manifest-sha256",
137
+ "<64-char-lowercase-manifest-sha256>",
138
+ "--provider",
139
+ "wasm"
140
+ ]
141
+ }
142
+ }
143
+ }
144
+ ```
145
+
146
+ Both examples assume Node 22+ is on `PATH` and that the bundle directory was
147
+ previously verified by the host. The CLI starts in stdio protocol mode and
148
+ never forks an HTTP listener.
149
+
150
+ ### Filesystem loader (strict)
151
+
152
+ The CLI `--bundle <dir>` argument accepts local directory paths (including
153
+ shell-resolved relative forms like `../my-bundle`), then realpath-resolves the
154
+ selected root before opening. URL schemes such as `https://`, `http://`, or
155
+ `file://` are rejected for `--bundle` itself. After the bundle root is
156
+ resolved, the manifest loader in `mcp.ts` applies the following strict
157
+ checks to each **manifest-declared relative file path** and to the bundle
158
+ manifest itself:
159
+
160
+ - URLs (`https://`, `http://`, `file://`, `data://`, `ftp://`)
161
+ - Absolute paths and `/`-rooted file paths
162
+ - Any occurrence of `..`, including URL-encoded `%2e%2e` or similar
163
+ - Windows drive letters and backslashes
164
+ - Query strings (`?`) or fragments (`#`)
165
+ - Symlinks or real paths that escape the `realpath()`-resolved bundle root
166
+
167
+ Declared files must also match entries inside a `vons.bundle.manifest/v1`
168
+ manifest named `bundle-manifest-v1.json`. Unknown, duplicate, or
169
+ non-existent declared files abort the server start with a clear error and
170
+ exit code 3.
171
+
172
  This package is private in npm metadata until an npm release is requested.
173
  Its `files` allowlist includes source, this guide and the software license. Models, tokenizers,
174
  datasets, generated demo JavaScript and dependencies are intentionally excluded
sdk/typescript/package-lock.json CHANGED
@@ -10,7 +10,9 @@
10
  "license": "SEE LICENSE IN LICENSE",
11
  "dependencies": {
12
  "@huggingface/tokenizers": "0.2.0",
13
- "onnxruntime-web": "1.30.0"
 
 
14
  },
15
  "devDependencies": {
16
  "esbuild": "0.28.2",
@@ -468,6 +470,31 @@
468
  "integrity": "sha512-LidMHe1FpcSYH4vcSjXooda34pC0M8m1gmDOv7SQi6Iv+ib1zX7J3sHBCC9/3FPCkn2k1b55FneVqMRxrr99pg==",
469
  "license": "Apache-2.0"
470
  },
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
471
  "node_modules/@protobufjs/aspromise": {
472
  "version": "1.1.2",
473
  "resolved": "https://registry.npmjs.org/@protobufjs/aspromise/-/aspromise-1.1.2.tgz",
@@ -662,6 +689,15 @@
662
  "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-8.9.0.tgz",
663
  "integrity": "sha512-KTDyRTYX8sWmKXAikPHHSyc63CRPETMctyjKFupcC6OBLXT3xsN0e9aF7m+mIXutFWpUXuedtowG7iLOzp0kQg==",
664
  "license": "MIT"
 
 
 
 
 
 
 
 
 
665
  }
666
  }
667
  }
 
10
  "license": "SEE LICENSE IN LICENSE",
11
  "dependencies": {
12
  "@huggingface/tokenizers": "0.2.0",
13
+ "@modelcontextprotocol/server": "2.1.0",
14
+ "onnxruntime-web": "1.30.0",
15
+ "zod": "4.6.5"
16
  },
17
  "devDependencies": {
18
  "esbuild": "0.28.2",
 
470
  "integrity": "sha512-LidMHe1FpcSYH4vcSjXooda34pC0M8m1gmDOv7SQi6Iv+ib1zX7J3sHBCC9/3FPCkn2k1b55FneVqMRxrr99pg==",
471
  "license": "Apache-2.0"
472
  },
473
+ "node_modules/@modelcontextprotocol/core": {
474
+ "version": "2.1.0",
475
+ "resolved": "https://registry.npmjs.org/@modelcontextprotocol/core/-/core-2.1.0.tgz",
476
+ "integrity": "sha512-YdFj5gMRHr0gYNAhTbQDgjLHiEJdIAUYxomhKseUNye7ZGlISQmUoLh2sveFFCiQ7j2YMffT1kgSND0FSfIFjQ==",
477
+ "license": "MIT",
478
+ "dependencies": {
479
+ "zod": "^4.2.0"
480
+ },
481
+ "engines": {
482
+ "node": ">=20"
483
+ }
484
+ },
485
+ "node_modules/@modelcontextprotocol/server": {
486
+ "version": "2.1.0",
487
+ "resolved": "https://registry.npmjs.org/@modelcontextprotocol/server/-/server-2.1.0.tgz",
488
+ "integrity": "sha512-FdvwZU5N03O77Suh35JqjAqq5R1ZTEPFtwu6N4BgBq28qrQtrCnpbLL5U2pwYCuE194jAw0xnlOVmIqhfoYuUQ==",
489
+ "license": "MIT",
490
+ "dependencies": {
491
+ "@modelcontextprotocol/core": "2.1.0",
492
+ "zod": "^4.2.0"
493
+ },
494
+ "engines": {
495
+ "node": ">=20"
496
+ }
497
+ },
498
  "node_modules/@protobufjs/aspromise": {
499
  "version": "1.1.2",
500
  "resolved": "https://registry.npmjs.org/@protobufjs/aspromise/-/aspromise-1.1.2.tgz",
 
689
  "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-8.9.0.tgz",
690
  "integrity": "sha512-KTDyRTYX8sWmKXAikPHHSyc63CRPETMctyjKFupcC6OBLXT3xsN0e9aF7m+mIXutFWpUXuedtowG7iLOzp0kQg==",
691
  "license": "MIT"
692
+ },
693
+ "node_modules/zod": {
694
+ "version": "4.6.5",
695
+ "resolved": "https://registry.npmjs.org/zod/-/zod-4.6.5.tgz",
696
+ "integrity": "sha512-v5l/aFXZQeai4awLbOpSoHecE9UiMrnfx75tEXLjNonXVARxQ5mOeipTjROUchszUNCqnE+hqAMujRsRHsut2Q==",
697
+ "license": "MIT",
698
+ "funding": {
699
+ "url": "https://github.com/sponsors/colinhacks"
700
+ }
701
  }
702
  }
703
  }
sdk/typescript/package.json CHANGED
@@ -5,19 +5,25 @@
5
  "type": "module",
6
  "dependencies": {
7
  "@huggingface/tokenizers": "0.2.0",
8
- "onnxruntime-web": "1.30.0"
 
 
9
  },
10
  "exports": {
11
  ".": "./src/index.ts",
12
- "./onnx": "./src/onnx.ts"
 
 
13
  },
14
  "scripts": {
15
- "test": "node --experimental-strip-types --test test/index.test.mjs test/onnx.test.mjs test/parity.test.mjs test/extension.test.mjs",
16
  "build:browser": "esbuild demo/main.ts --bundle --format=esm --platform=browser --target=es2022 --outfile=demo/main.js",
17
  "build:benchmark": "esbuild demo/benchmark.ts --bundle --format=esm --platform=browser --target=es2022 --outfile=demo/benchmark.js",
18
  "build:parity": "esbuild demo/parity.ts --bundle --format=esm --platform=browser --target=es2022 --outfile=demo/parity.js",
19
  "build:extension": "node extension/build.mjs",
20
- "typecheck:extension": "tsc -p extension/tsconfig.json"
 
 
21
  },
22
  "engines": {
23
  "node": ">=22"
 
5
  "type": "module",
6
  "dependencies": {
7
  "@huggingface/tokenizers": "0.2.0",
8
+ "@modelcontextprotocol/server": "2.1.0",
9
+ "onnxruntime-web": "1.30.0",
10
+ "zod": "4.6.5"
11
  },
12
  "exports": {
13
  ".": "./src/index.ts",
14
+ "./onnx": "./src/onnx.ts",
15
+ "./mcp": "./src/mcp.ts",
16
+ "./mcp-cli": "./src/mcp-cli.ts"
17
  },
18
  "scripts": {
19
+ "test": "node --experimental-strip-types --test test/index.test.mjs test/onnx.test.mjs test/parity.test.mjs test/extension.test.mjs test/mcp.test.mjs",
20
  "build:browser": "esbuild demo/main.ts --bundle --format=esm --platform=browser --target=es2022 --outfile=demo/main.js",
21
  "build:benchmark": "esbuild demo/benchmark.ts --bundle --format=esm --platform=browser --target=es2022 --outfile=demo/benchmark.js",
22
  "build:parity": "esbuild demo/parity.ts --bundle --format=esm --platform=browser --target=es2022 --outfile=demo/parity.js",
23
  "build:extension": "node extension/build.mjs",
24
+ "build:mcp": "esbuild src/mcp.ts src/mcp-cli.ts --bundle=false --platform=node --target=es2022 --outdir=dist-mcp-test/ --ignore-annotations",
25
+ "typecheck:extension": "tsc -p extension/tsconfig.json",
26
+ "typecheck:mcp": "tsc --noEmit --allowImportingTsExtensions --noEmitOnError --target ES2022 --moduleResolution bundler --module ESNext --strict --skipLibCheck --esModuleInterop --lib ES2022,DOM src/mcp.ts src/mcp-cli.ts src/index.ts src/onnx.ts"
27
  },
28
  "engines": {
29
  "node": ">=22"
sdk/typescript/src/mcp-cli.ts ADDED
@@ -0,0 +1,277 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import { parseArgs } from "node:util";
2
+ import { readFileSync, realpathSync } from "node:fs";
3
+ import { resolve, join, sep } from "node:path";
4
+ import { pathToFileURL } from "node:url";
5
+
6
+ import { loadBundleManifestStrict, runStdioMcpServer, isForbiddenBundlePath } from "./mcp.ts";
7
+
8
+ import { createOnnxWebBackend } from "./onnx.ts";
9
+ import type { BundleManifest } from "./onnx.ts";
10
+
11
+ interface CliArgs {
12
+ bundle: string | undefined;
13
+ manifestSha256: string | undefined;
14
+ provider: "wasm" | "webgpu" | undefined;
15
+ help: boolean;
16
+ }
17
+
18
+ function printUsage(stream: NodeJS.WritableStream = process.stderr): void {
19
+ stream.write(
20
+ [
21
+ "vons-local-mcp stdio server (uses local ONNX Web backend via --bundle; no KASI adapter; no host tool execution)",
22
+ "",
23
+ "USAGE:",
24
+ " node --experimental-strip-types sdk/typescript/src/mcp-cli.ts --bundle <dir> [options]",
25
+ "",
26
+ "REQUIRED:",
27
+ " --bundle <dir> Path to a user-supplied, hash-verified local ONNX bundle directory.",
28
+ " Must contain bundle-manifest-v1.json declaring vons.bundle.manifest/v1.",
29
+ " No URL, no auto-discovery, no implicit defaults. Shell-resolved relative paths (including ../..) are supported for the local --bundle directory after the scheme-rejection check.",
30
+ "",
31
+ "OPTIONS:",
32
+ " --manifest-sha256 <hex> Optional 64-char lowercase SHA-256 to authenticate the bundle manifest.",
33
+ " If declared and mismatched, the process aborts; no fallback or soft-error.",
34
+ " --provider <wasm|webgpu> Backend provider choice for the ONNX runtime (default: wasm).",
35
+ " In the stdio CLI, --provider wasm is the only supported value.",
36
+ " --provider webgpu is explicitly rejected with exit code 4 because a",
37
+ " stdio process cannot obtain a browser WebGPU adapter. Use a browser",
38
+ " or extension host with requestAdapter() explicitly to use WebGPU.",
39
+ " --help Print this help text and exit 0.",
40
+ "",
41
+ "CONSTRAINTS (explicit non-goals):",
42
+ " - No HTTP listener, no network, no remote connections.",
43
+ " - Writes MCP JSON-RPC messages ONLY to stdout.",
44
+ " - Diagnostic messages (errors, warning banners, runtime logs, and usage printed for invalid/missing flags) go ONLY to stderr.",
45
+ " - The --help usage text is intentionally printed to stdout (exit 0) so it may be piped or redirected by shell callers.",
46
+ " - Never executes downstream tools, never authorizes actions, never stores/persists/upload data.",
47
+ " - Never performs silent fallback decisions, never substitutes a fake choice on errors.",
48
+ " - CLI --bundle accepts local directory paths (including shell-resolved ../..); URL schemes are rejected; the chosen root is realpath-resolved before manifest and declared files are validated.",
49
+ " - Declared files inside bundle-manifest-v1.json must not use URLs, absolute paths, .. traversal, drive letters, query strings, or fragments; any symlink escape or realpath escape is rejected.",
50
+ " - No request or response contents are written to any log except the MCP stdout channel.",
51
+ "",
52
+ ].join("\n"),
53
+ );
54
+ }
55
+
56
+ function parseCliArgs(argv: string[]): CliArgs {
57
+ try {
58
+ const parsed = parseArgs({
59
+ args: argv,
60
+ options: {
61
+ bundle: { type: "string" },
62
+ "manifest-sha256": { type: "string" },
63
+ provider: { type: "string" },
64
+ help: { type: "boolean", short: "h" },
65
+ },
66
+ strict: true,
67
+ allowPositionals: false,
68
+ });
69
+ const providerRaw = parsed.values["provider"];
70
+ let provider: CliArgs["provider"];
71
+ if (providerRaw === undefined) {
72
+ provider = undefined;
73
+ } else if (providerRaw === "wasm" || providerRaw === "webgpu") {
74
+ provider = providerRaw;
75
+ } else {
76
+ throw new Error(
77
+ `--provider must be 'wasm' or 'webgpu', got '${String(providerRaw)}'. No auto-detection.`,
78
+ );
79
+ }
80
+ return {
81
+ bundle: parsed.values["bundle"],
82
+ manifestSha256: parsed.values["manifest-sha256"],
83
+ provider,
84
+ help: Boolean(parsed.values.help),
85
+ };
86
+ } catch (cause) {
87
+ printUsage();
88
+ process.stderr.write(`\nargument error: ${(cause as Error).message}\n`);
89
+ process.exit(2);
90
+ }
91
+ }
92
+
93
+ function diag(level: "debug" | "info" | "warn" | "error", message: string): void {
94
+ process.stderr.write(`[vons-mcp:${level}] ${message}\n`);
95
+ }
96
+
97
+ function makeBundleLocalFsFetch(
98
+ bundleRootRealPath: string,
99
+ manifest: BundleManifest,
100
+ ): typeof fetch {
101
+ const bundlePrefix = "vons-bundle-fs://local/";
102
+ const validRelPaths = new Set(manifest.files.map((f) => f.path));
103
+ const fetchImpl: typeof fetch = async (input, init) => {
104
+ const urlStr = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
105
+ if (typeof urlStr !== "string") {
106
+ throw new TypeError("invalid fetch input in local-fs bundle adapter");
107
+ }
108
+ if (init && "signal" in init && init.signal && init.signal.aborted) {
109
+ throw new DOMException("Aborted", "AbortError");
110
+ }
111
+ if (!urlStr.startsWith(bundlePrefix)) {
112
+ throw new Error(
113
+ `stdios bundle fetch adapter only accepts ${bundlePrefix} URLs; refusing to fetch: ${urlStr.slice(0, 64)}`,
114
+ );
115
+ }
116
+ const relEncoded = urlStr.slice(bundlePrefix.length);
117
+ const rel = decodeURIComponent(relEncoded);
118
+ if (isForbiddenBundlePath(rel) || !validRelPaths.has(rel)) {
119
+ throw new Error(`bundle-local fetch refused: path not declared in manifest: ${rel}`);
120
+ }
121
+ const abs = join(bundleRootRealPath, ...rel.split("/"));
122
+ let absRealPath: string | null = null;
123
+ try {
124
+ absRealPath = realpathSync(abs);
125
+ } catch {
126
+ throw new Error(`bundle-local fetch refused: declared file not found on disk (realpath failed): ${rel}`);
127
+ }
128
+ if (
129
+ absRealPath !== bundleRootRealPath &&
130
+ !absRealPath.startsWith(bundleRootRealPath + sep)
131
+ ) {
132
+ throw new Error(`bundle-local fetch refused: file escapes bundle root via symlink: ${rel}`);
133
+ }
134
+ const bytes = readFileSync(absRealPath);
135
+ const body = new Uint8Array(bytes);
136
+ return new Response(body.buffer as ArrayBuffer, {
137
+ status: 200,
138
+ headers: {
139
+ "content-type": "application/octet-stream",
140
+ "content-length": String(body.byteLength),
141
+ },
142
+ }) as Response;
143
+ };
144
+ return fetchImpl;
145
+ }
146
+
147
+ function bundleLocalBaseHref(bundleRootRealPath: string): string {
148
+ return "vons-bundle-fs://local/";
149
+ }
150
+
151
+ async function main(argv: string[]): Promise<number> {
152
+ const args = parseCliArgs(argv);
153
+ if (args.help) {
154
+ printUsage(process.stdout);
155
+ return 0;
156
+ }
157
+ if (!args.bundle || args.bundle.length === 0) {
158
+ printUsage();
159
+ diag("error", "--bundle <dir> is required. No implicit or auto-discovered bundle path is used.");
160
+ return 2;
161
+ }
162
+ if (args.provider !== undefined && args.provider !== "wasm" && args.provider !== "webgpu") {
163
+ diag("error", `--provider must be 'wasm' or 'webgpu', got '${String(args.provider)}'. No auto-detection.`);
164
+ return 2;
165
+ }
166
+ const provider = args.provider ?? "wasm";
167
+ const URI_SCHEME_RE = /^(https?|file|ftp|data):(\/\/)?/i;
168
+ if (URI_SCHEME_RE.test(args.bundle.trimStart())) {
169
+ const trimmed = args.bundle.trim();
170
+ const m = trimmed.match(URI_SCHEME_RE);
171
+ const scheme = m ? m[1].toLowerCase() : "unknown";
172
+ diag(
173
+ "error",
174
+ `--bundle rejected: URI scheme '${scheme}://' is not supported. ` +
175
+ `The --bundle argument must be a local filesystem directory path (shell-resolved relative paths including ../.. are supported). ` +
176
+ `Passed value: '${trimmed.slice(0, 120)}'${trimmed.length > 120 ? " (truncated)" : ""}. ` +
177
+ `No silent fallback; no request contents were processed.`,
178
+ );
179
+ return 3;
180
+ }
181
+ const bundleDir = resolve(args.bundle);
182
+ let loaded: Awaited<ReturnType<typeof loadBundleManifestStrict>>;
183
+ try {
184
+ loaded = loadBundleManifestStrict(bundleDir, args.manifestSha256);
185
+ } catch (cause) {
186
+ diag(
187
+ "error",
188
+ `bundle load failed: ${cause instanceof Error ? cause.message : String(cause)}. ` +
189
+ `No silent fallback; the user must repair the bundle or path. No request contents were processed.`,
190
+ );
191
+ return 3;
192
+ }
193
+ const manifest: BundleManifest = loaded.manifest;
194
+ if (provider === "webgpu") {
195
+ diag(
196
+ "error",
197
+ "--provider webgpu was selected, but the stdio CLI cannot obtain a browser WebGPU adapter. " +
198
+ "WebGPU is only supported inside browser/extension host contexts with an explicit requestAdapter() call. " +
199
+ "Either re-run with --provider wasm, or invoke the SDK's browser host integration instead.",
200
+ );
201
+ return 4;
202
+ }
203
+ const md = manifest.metadata;
204
+ diag(
205
+ "info",
206
+ `bundle loaded: backend=${md.backend}, option_count=${md.option_count ?? "null"}, ` +
207
+ `sequence_length=${md.sequence_length ?? "null"}, model_id=${md.model_id ?? "(none declared)"}. ` +
208
+ `manifest.sha256=${loaded.manifestSha256.slice(0, 12)}... (full digest omitted from logs). ` +
209
+ `Starting stdio MCP server; MCP JSON-RPC only on stdout, diagnostics only on stderr.`,
210
+ );
211
+ diag(
212
+ "info",
213
+ `provider=${provider}. Wire ONNX Web backend with bundle-local fs fetch adapter; ` +
214
+ `actual ONNX runtime loading only runs for real user bundles (not in synthetic protocol tests).`,
215
+ );
216
+ const bundleFetch = makeBundleLocalFsFetch(loaded.rootRealPath, manifest);
217
+ let backend: Awaited<ReturnType<typeof createOnnxWebBackend>>;
218
+ try {
219
+ backend = await createOnnxWebBackend({
220
+ manifest,
221
+ baseUrl: bundleLocalBaseHref(loaded.rootRealPath),
222
+ provider,
223
+ fetch: bundleFetch,
224
+ });
225
+ } catch (cause) {
226
+ diag(
227
+ "error",
228
+ `failed to create ONNX Web backend for provider=${provider}: ${cause instanceof Error ? cause.message : String(cause)}. ` +
229
+ `No fallback backend or synthetic choice substituted; MCP server startup aborted.`,
230
+ );
231
+ return 5;
232
+ }
233
+ try {
234
+ await runStdioMcpServer({
235
+ backend,
236
+ manifest,
237
+ manifestSha256: loaded.manifestSha256,
238
+ bundleRoot: loaded.rootRealPath,
239
+ logger: (level, message) => diag(level, message),
240
+ });
241
+ } catch (cause) {
242
+ diag("error", `stdio MCP server terminated with error: ${cause instanceof Error ? cause.message : String(cause)}`);
243
+ return 1;
244
+ } finally {
245
+ try {
246
+ await backend.dispose();
247
+ } catch {
248
+ void 0;
249
+ }
250
+ }
251
+ return 0;
252
+ }
253
+
254
+ const _argv1 = typeof process !== "undefined" && process.argv && process.argv[1] ? process.argv[1] : null;
255
+ const _isDirectCliInvoke =
256
+ _argv1 !== null &&
257
+ typeof import.meta !== "undefined" &&
258
+ import.meta.url !== null &&
259
+ typeof import.meta.url === "string" &&
260
+ pathToFileURL(resolve(_argv1)).href === import.meta.url;
261
+
262
+ if (_isDirectCliInvoke) {
263
+ void main(process.argv.slice(2)).then((code) => {
264
+ if (code !== 0) {
265
+ process.exitCode = code;
266
+ }
267
+ });
268
+ }
269
+
270
+ export {
271
+ parseCliArgs,
272
+ printUsage,
273
+ diag,
274
+ main,
275
+ isForbiddenBundlePath,
276
+ loadBundleManifestStrict,
277
+ };
sdk/typescript/src/mcp.ts ADDED
@@ -0,0 +1,452 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import { readFileSync, realpathSync, statSync, existsSync } from "node:fs";
2
+ import { resolve, isAbsolute, sep, join } from "node:path";
3
+ import { createHash } from "node:crypto";
4
+ import type { Readable, Writable } from "node:stream";
5
+
6
+ import { McpServer } from "@modelcontextprotocol/server";
7
+ import type { Transport } from "@modelcontextprotocol/server";
8
+ import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
9
+ import { z } from "zod";
10
+
11
+ import {
12
+ type Backend,
13
+ type DecisionBackend,
14
+ type DecisionRequest,
15
+ type DecisionResponse,
16
+ validateRequest,
17
+ validateResponse,
18
+ } from "./index.ts";
19
+ import type { BundleManifest } from "./onnx.ts";
20
+
21
+ const BUNDLE_MANIFEST_NAME = "bundle-manifest-v1.json";
22
+ const EXPECTED_BUNDLE_SCHEMA = "vons.bundle.manifest/v1";
23
+ const MANIFEST_RESOURCE_URI = "vons://bundle/manifest/metadata";
24
+ const MANIFEST_RESOURCE_NAME = "bundle-manifest-metadata";
25
+
26
+ const QuestionFields = {
27
+ id: z.string().min(1),
28
+ prompt: z.string().min(1),
29
+ };
30
+ const NonScoreRubricZodSchema = z.union([
31
+ z.tuple([]),
32
+ z.array(z.string()).min(2).max(10),
33
+ ]);
34
+ const QuestionZodSchema = z.discriminatedUnion("type", [
35
+ z.strictObject({
36
+ ...QuestionFields,
37
+ type: z.literal("choice"),
38
+ options: z.array(z.string().min(1)).min(2).max(32),
39
+ rubric: NonScoreRubricZodSchema.optional(),
40
+ }),
41
+ z.strictObject({
42
+ ...QuestionFields,
43
+ type: z.literal("boolean"),
44
+ options: z.union([
45
+ z.tuple([]),
46
+ z.tuple([z.literal("true"), z.literal("false")]),
47
+ ]),
48
+ rubric: NonScoreRubricZodSchema.optional(),
49
+ }),
50
+ z.strictObject({
51
+ ...QuestionFields,
52
+ type: z.literal("score"),
53
+ options: z.array(z.string().min(1)).min(2).max(32),
54
+ rubric: z.array(z.string()).min(2).max(10),
55
+ }),
56
+ ]);
57
+
58
+ export const DecisionRequestZodSchema = z.strictObject({
59
+ state: z.union([
60
+ z.string().min(1),
61
+ z.record(z.string(), z.unknown()).refine((value) => !Array.isArray(value), { message: "state must not be an array" }),
62
+ ]),
63
+ questions: z.array(QuestionZodSchema).min(1).max(8),
64
+ backend: z.enum(["direct", "diffusion"]).optional(),
65
+ seed: z.number().int().nonnegative().optional(),
66
+ });
67
+
68
+ export interface BundleMetadataResource {
69
+ schema_version: "vons.bundle.metadata/v1";
70
+ backend: Backend | null;
71
+ model_id: string | null;
72
+ option_count: number | null;
73
+ sequence_length: number | null;
74
+ }
75
+
76
+ export interface McpServerOptions {
77
+ backend: DecisionBackend;
78
+ manifest?: BundleManifest | null;
79
+ manifestSha256?: string | null;
80
+ bundleRoot?: string | null;
81
+ logger?: ((level: "debug" | "info" | "warn" | "error", message: string) => void) | null;
82
+ }
83
+
84
+ export function isForbiddenBundlePath(value: string): boolean {
85
+ if (typeof value !== "string") return true;
86
+ if (value.length === 0) return true;
87
+ if (/^(https?|file|data|ftp):\/\//i.test(value.trim())) return true;
88
+ if (value.startsWith("file://")) return true;
89
+ if (isAbsolute(value)) return true;
90
+ if (/^[A-Za-z]:[\\/]/.test(value)) return true;
91
+ if (value.includes("\\")) return true;
92
+ if (value.includes("..")) return true;
93
+ if (/%(?:2e|2f|5c)/i.test(value)) return true;
94
+ if (/[?#]/.test(value)) return true;
95
+ return false;
96
+ }
97
+
98
+ export interface StrictBundleLoaderResult {
99
+ rootRealPath: string;
100
+ manifest: BundleManifest;
101
+ manifestSha256: string;
102
+ manifestPath: string;
103
+ }
104
+
105
+ export function loadBundleManifestStrict(bundleDir: string, expectedSha256?: string | null): StrictBundleLoaderResult {
106
+ if (typeof bundleDir !== "string" || bundleDir.length === 0) {
107
+ throw new TypeError("--bundle directory path must be a non-empty string");
108
+ }
109
+ if (/^(https?|file):\/\//i.test(bundleDir.trim())) {
110
+ throw new TypeError("--bundle must be a local directory path; URLs are forbidden");
111
+ }
112
+ if (!existsSync(bundleDir)) {
113
+ throw new Error(`bundle directory not found: ${bundleDir}`);
114
+ }
115
+ const dirStat = statSync(bundleDir);
116
+ if (!dirStat.isDirectory()) {
117
+ throw new TypeError(`bundle path is not a directory: ${bundleDir}`);
118
+ }
119
+ const rootRealPath = realpathSync(bundleDir);
120
+ const manifestPath = join(rootRealPath, BUNDLE_MANIFEST_NAME);
121
+ if (!existsSync(manifestPath)) {
122
+ throw new Error(
123
+ `bundle manifest ${BUNDLE_MANIFEST_NAME} not found in bundle directory. ` +
124
+ `The user must supply a hash-verified bundle; no auto-discovery is performed.`,
125
+ );
126
+ }
127
+ let manifestPathReal: string | null = null;
128
+ try {
129
+ manifestPathReal = realpathSync(manifestPath);
130
+ } catch {
131
+ throw new Error(`bundle manifest ${BUNDLE_MANIFEST_NAME} cannot be resolved; check symlink targets and permissions`);
132
+ }
133
+ if (manifestPathReal !== join(rootRealPath, BUNDLE_MANIFEST_NAME)) {
134
+ throw new Error(
135
+ `bundle manifest escapes bundle root via symlink: ${BUNDLE_MANIFEST_NAME}`,
136
+ );
137
+ }
138
+ const manifestRealPath = realpathSync(manifestPath);
139
+ if (manifestRealPath === rootRealPath || !manifestRealPath.startsWith(rootRealPath + sep)) {
140
+ throw new Error("bundle manifest escapes bundle root via symlink");
141
+ }
142
+ const manifestStat = statSync(manifestRealPath);
143
+ if (!manifestStat.isFile()) {
144
+ throw new TypeError(`bundle manifest is not a regular file: ${manifestPath}`);
145
+ }
146
+ const manifestBytes = readFileSync(manifestRealPath);
147
+ const manifestSha256 = createHash("sha256").update(manifestBytes).digest("hex");
148
+ if (expectedSha256 && typeof expectedSha256 === "string" && expectedSha256.length > 0) {
149
+ if (!/^[0-9a-f]{64}$/.test(expectedSha256)) {
150
+ throw new TypeError("--manifest-sha256 must be a 64-character lowercase hex digest");
151
+ }
152
+ if (manifestSha256 !== expectedSha256) {
153
+ throw new Error(
154
+ `bundle manifest SHA-256 mismatch. Expected ${expectedSha256}, got ${manifestSha256}. ` +
155
+ `No silent fallback or auto-discovery is performed; verify the bundle contents.`,
156
+ );
157
+ }
158
+ }
159
+ let manifest: BundleManifest;
160
+ try {
161
+ manifest = JSON.parse(manifestBytes.toString("utf8")) as BundleManifest;
162
+ } catch (cause) {
163
+ throw new Error(`bundle manifest is not valid JSON: ${(cause as Error).message}`);
164
+ }
165
+ if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
166
+ throw new TypeError("bundle manifest must be an object");
167
+ }
168
+ if (manifest.schema_version !== EXPECTED_BUNDLE_SCHEMA) {
169
+ throw new TypeError(
170
+ `bundle manifest schema_version must be ${EXPECTED_BUNDLE_SCHEMA}, got ${String(manifest.schema_version)}`,
171
+ );
172
+ }
173
+ if (!manifest.metadata || typeof manifest.metadata !== "object" || Array.isArray(manifest.metadata)) {
174
+ throw new TypeError("bundle manifest metadata must be an object");
175
+ }
176
+ if (manifest.metadata.backend !== "direct" && manifest.metadata.backend !== "diffusion") {
177
+ throw new TypeError("bundle manifest metadata.backend must be 'direct' or 'diffusion'");
178
+ }
179
+ if (!Array.isArray(manifest.files)) {
180
+ throw new TypeError("bundle manifest files must be an array");
181
+ }
182
+ const paths = new Set<string>();
183
+ for (const record of manifest.files) {
184
+ if (!record || typeof record !== "object" || typeof record.path !== "string" || record.path.length === 0) {
185
+ throw new TypeError("bundle manifest file record must have a non-empty string path");
186
+ }
187
+ if (paths.has(record.path)) {
188
+ throw new TypeError(`bundle manifest contains duplicate file path: ${record.path}`);
189
+ }
190
+ paths.add(record.path);
191
+ if (isForbiddenBundlePath(record.path)) {
192
+ throw new TypeError(`bundle manifest file path is forbidden (must be relative, no traversal): ${record.path}`);
193
+ }
194
+ const recordFullPath = resolve(rootRealPath, record.path);
195
+ let recordFullRealPath: string | null = null;
196
+ try {
197
+ recordFullRealPath = realpathSync(recordFullPath);
198
+ } catch {
199
+ recordFullRealPath = null;
200
+ }
201
+ if (!recordFullRealPath) {
202
+ throw new Error(`bundle declared file not found: ${record.path}`);
203
+ }
204
+ if (recordFullRealPath !== rootRealPath && !recordFullRealPath.startsWith(rootRealPath + sep)) {
205
+ throw new Error(`bundle declared file escapes bundle root via symlink: ${record.path}`);
206
+ }
207
+ }
208
+ return { rootRealPath, manifest, manifestSha256, manifestPath };
209
+ }
210
+
211
+ export function bundleManifestToMetadata(
212
+ manifest: BundleManifest,
213
+ _rootRealPath: string,
214
+ ): BundleMetadataResource {
215
+ const md = manifest.metadata ?? ({} as BundleManifest["metadata"]);
216
+ return {
217
+ schema_version: "vons.bundle.metadata/v1",
218
+ backend: md.backend ?? null,
219
+ model_id: typeof md.model_id === "string" ? md.model_id : null,
220
+ option_count:
221
+ Number.isInteger(md.option_count) && (md.option_count as number) >= 0 ? (md.option_count as number) : null,
222
+ sequence_length:
223
+ Number.isInteger(md.sequence_length) && (md.sequence_length as number) >= 0
224
+ ? (md.sequence_length as number)
225
+ : null,
226
+ };
227
+ }
228
+
229
+ export function createMcpServer(options: McpServerOptions): McpServer {
230
+ if (!options || typeof options !== "object") throw new TypeError("options is required");
231
+ if (!options.backend || typeof options.backend.decide !== "function") {
232
+ throw new TypeError("options.backend must implement DecisionBackend.decide");
233
+ }
234
+ const backend: DecisionBackend = options.backend;
235
+ const manifest: BundleManifest | null = options.manifest ?? null;
236
+ const bundleRoot: string | null = options.bundleRoot ?? null;
237
+ const logger = options.logger ?? null;
238
+
239
+ const log = (level: "debug" | "info" | "warn" | "error", message: string): void => {
240
+ if (logger) {
241
+ try {
242
+ logger(level, message);
243
+ } catch {
244
+ void 0;
245
+ }
246
+ }
247
+ };
248
+
249
+ const server = new McpServer({
250
+ name: "vons-local-mcp",
251
+ version: "0.1.0",
252
+ });
253
+
254
+ const metadataResource: BundleMetadataResource | null = manifest
255
+ ? bundleManifestToMetadata(manifest, bundleRoot ?? "")
256
+ : null;
257
+
258
+ server.registerResource(
259
+ MANIFEST_RESOURCE_NAME,
260
+ MANIFEST_RESOURCE_URI,
261
+ {
262
+ title: "Vons bundle manifest metadata",
263
+ description:
264
+ "Non-sensitive, non-asset metadata for the user-supplied hash-verified ONNX bundle. " +
265
+ "Returns only schema_version, backend, model_id (if declared), option_count, and sequence_length. " +
266
+ "No local filesystem path is emitted. Never includes file bytes, file hashes, tokenizer contents, graph data, or runtime asset digests.",
267
+ mimeType: "application/json",
268
+ },
269
+ async (uri) => {
270
+ if (uri.href !== MANIFEST_RESOURCE_URI) {
271
+ throw new Error("unknown manifest resource URI");
272
+ }
273
+ if (!metadataResource) {
274
+ throw new Error(
275
+ "no manifest loaded. The server requires an explicit --bundle directory pointing to a " +
276
+ "hash-verified ONNX bundle; no auto-discovery or implicit default is performed.",
277
+ );
278
+ }
279
+ return {
280
+ contents: [
281
+ {
282
+ uri: MANIFEST_RESOURCE_URI,
283
+ mimeType: "application/json",
284
+ text: JSON.stringify(metadataResource, null, 2),
285
+ },
286
+ ],
287
+ };
288
+ },
289
+ );
290
+
291
+ server.registerTool(
292
+ "vons_decide",
293
+ {
294
+ description:
295
+ "Call the user-supplied, hash-verified Vons local ONNX decision backend with a structured DecisionRequest. " +
296
+ "Returns a DecisionResponse JSON with per-question probabilities and either a choice (status=ok) or explicit " +
297
+ "abstention (status=abstain, choice=null, abstain_reason). The host remains responsible for validation, " +
298
+ "consent, execution, and any KASI policy. This server never authorizes actions, never runs downstream tools, " +
299
+ "never writes data, never logs request contents to stdout, and never performs silent fallback or auto-discovery.",
300
+ inputSchema: DecisionRequestZodSchema,
301
+ },
302
+ async (args) => {
303
+ const parseResult = DecisionRequestZodSchema.safeParse(args);
304
+ if (!parseResult.success) {
305
+ const firstIssue = parseResult.error.issues[0];
306
+ const message =
307
+ "vons_decide arguments failed strict schema validation: " +
308
+ (firstIssue
309
+ ? `${firstIssue.path.join(".") || "<root>"}: ${firstIssue.message}`
310
+ : parseResult.error.message);
311
+ log("warn", "invalid tool arguments rejected by strict schema validation");
312
+ return {
313
+ content: [
314
+ {
315
+ type: "text" as const,
316
+ text: JSON.stringify({ error: message, schema: "vons.mcp.tool.validation/v1" }),
317
+ },
318
+ ],
319
+ isError: true,
320
+ };
321
+ }
322
+ const zodValidated = parseResult.data as DecisionRequest;
323
+ try {
324
+ validateRequest(zodValidated);
325
+ } catch (cause) {
326
+ const message = `vons_decide request rejected by shared contract validator: ${(cause as Error).message}`;
327
+ log("warn", "request rejected by shared contract validation");
328
+ return {
329
+ content: [{ type: "text" as const, text: JSON.stringify({ error: message }) }],
330
+ isError: true,
331
+ };
332
+ }
333
+ let response: DecisionResponse;
334
+ try {
335
+ response = await backend.decide(zodValidated);
336
+ } catch (cause) {
337
+ void cause;
338
+ const message =
339
+ `vons_decide backend raised a runtime error. No response was produced, and no fallback decision was made. ` +
340
+ `(Backend error details are intentionally not surfaced on stdout or stderr to avoid leaking internal request/asset contents.)`;
341
+ log("error", "backend inference failed; no response or fallback decision was produced");
342
+ return {
343
+ content: [{ type: "text" as const, text: JSON.stringify({ error: message }) }],
344
+ isError: true,
345
+ };
346
+ }
347
+ if (!response || typeof response !== "object") {
348
+ return {
349
+ content: [
350
+ {
351
+ type: "text" as const,
352
+ text: JSON.stringify({
353
+ error: "vons_decide backend returned a non-object response. No fallback decision was substituted.",
354
+ }),
355
+ },
356
+ ],
357
+ isError: true,
358
+ };
359
+ }
360
+ try {
361
+ validateResponse(response);
362
+ } catch (cause) {
363
+ const message = `vons_decide backend response failed contract validation: ${(cause as Error).message}`;
364
+ log("error", "backend response failed shared contract validation");
365
+ return {
366
+ content: [{ type: "text" as const, text: JSON.stringify({ error: message }) }],
367
+ isError: true,
368
+ };
369
+ }
370
+ const requestedQuestionIds = new Set(zodValidated.questions.map((question) => question.id));
371
+ const answeredQuestionIds = new Set(response.answers.map((answer) => answer.question_id));
372
+ if (
373
+ requestedQuestionIds.size !== answeredQuestionIds.size ||
374
+ [...requestedQuestionIds].some((questionId) => !answeredQuestionIds.has(questionId))
375
+ ) {
376
+ const message =
377
+ "vons_decide backend response question IDs must exactly match the request; " +
378
+ "refusing missing or unexpected answers.";
379
+ log("error", "backend response question IDs did not match the request");
380
+ return {
381
+ content: [{ type: "text" as const, text: JSON.stringify({ error: message }) }],
382
+ isError: true,
383
+ };
384
+ }
385
+ const allAbstain =
386
+ response.answers.length > 0 &&
387
+ response.answers.every((a) => a.status === "abstain" && a.choice === null);
388
+ if (allAbstain) {
389
+ log("debug", "backend abstained; no fallback decision was applied");
390
+ }
391
+ const anyWithChoice = response.answers.some(
392
+ (a) => a.status === "ok" && typeof a.choice === "string",
393
+ );
394
+ if (!anyWithChoice && !allAbstain) {
395
+ return {
396
+ content: [
397
+ {
398
+ type: "text" as const,
399
+ text: JSON.stringify({
400
+ error:
401
+ "vons_decide backend produced a response that is neither all-abstain nor all-ok choices; refusing to forward an ambiguous result.",
402
+ }),
403
+ },
404
+ ],
405
+ isError: true,
406
+ };
407
+ }
408
+ return {
409
+ content: [
410
+ {
411
+ type: "text" as const,
412
+ text: JSON.stringify(response),
413
+ },
414
+ ],
415
+ isError: false,
416
+ };
417
+ },
418
+ );
419
+
420
+ return server;
421
+ }
422
+
423
+ export interface RunStdioServerOptions extends McpServerOptions {
424
+ stdin?: Readable | null;
425
+ stdout?: Writable | null;
426
+ signal?: AbortSignal | null;
427
+ }
428
+
429
+ export async function runStdioMcpServer(options: RunStdioServerOptions): Promise<void> {
430
+ const server = createMcpServer(options);
431
+ const stdin = (options.stdin ?? process.stdin) as Readable;
432
+ const stdout = (options.stdout ?? process.stdout) as Writable;
433
+ const transport: Transport = new StdioServerTransport(stdin, stdout);
434
+ const signal = options.signal;
435
+ let onAbort: (() => void) | null = null;
436
+ if (signal) {
437
+ if (signal.aborted) return;
438
+ onAbort = () => {
439
+ void server.close().catch(() => void 0);
440
+ };
441
+ signal.addEventListener("abort", onAbort);
442
+ }
443
+ try {
444
+ await server.connect(transport);
445
+ } finally {
446
+ if (onAbort !== null && signal) {
447
+ signal.removeEventListener("abort", onAbort);
448
+ }
449
+ }
450
+ }
451
+
452
+ export { StdioServerTransport };
sdk/typescript/test/mcp.test.mjs ADDED
@@ -0,0 +1,1240 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import { test, describe, beforeEach, afterEach } from "node:test";
2
+ import assert from "node:assert/strict";
3
+ import { mkdtempSync, writeFileSync, symlinkSync, mkdirSync, rmSync } from "node:fs";
4
+ import { tmpdir } from "node:os";
5
+ import { resolve, join } from "node:path";
6
+ import { createHash } from "node:crypto";
7
+ import { spawnSync } from "node:child_process";
8
+ import { PassThrough } from "node:stream";
9
+
10
+ function syntheticManifest(overrides = {}) {
11
+ const record = (path, role, bytes = 4) => ({
12
+ path, role, bytes, sha256: "1".repeat(64), runtime_loaded: true, model_asset: true,
13
+ });
14
+ const base = {
15
+ schema_version: "vons.bundle.manifest/v1",
16
+ manifest: { path: "bundle-manifest-v1.json", sha256: null, self_hash_excluded: true },
17
+ metadata: { backend: "direct", option_count: 2, sequence_length: 32 },
18
+ files: [
19
+ record("model.onnx", "model_graph"),
20
+ record("tokenizer.json", "tokenizer"),
21
+ record("tokenizer_config.json", "tokenizer"),
22
+ ],
23
+ summary: { model_asset_bytes: 12, complete_download_bytes: 12 },
24
+ };
25
+ return Object.assign({}, base, overrides);
26
+ }
27
+
28
+ function writeSyntheticBundleDir(manifest) {
29
+ const dir = mkdtempSync(join(tmpdir(), "vons-mcp-bundle-"));
30
+ for (const record of manifest.files) {
31
+ const parts = record.path.split("/");
32
+ if (parts.length > 1) {
33
+ mkdirSync(join(dir, ...parts.slice(0, -1)), { recursive: true });
34
+ }
35
+ writeFileSync(join(dir, record.path), Buffer.alloc(record.bytes ?? 4));
36
+ }
37
+ const manifestJson = JSON.stringify(manifest, null, 2);
38
+ const manifestBytes = Buffer.from(manifestJson, "utf8");
39
+ const manifestSha256 = createHash("sha256").update(manifestBytes).digest("hex");
40
+ writeFileSync(join(dir, "bundle-manifest-v1.json"), manifestBytes);
41
+ return { dir, manifestSha256 };
42
+ }
43
+
44
+ class SyntheticOkBackend {
45
+ constructor(choicesPerQuestion) {
46
+ this.backend = "direct";
47
+ this.choices = choicesPerQuestion;
48
+ }
49
+ async decide(request) {
50
+ return {
51
+ answers: this.choices.map((choice, idx) => {
52
+ const options = request.questions[idx].options;
53
+ const choiceIndex = options.indexOf(choice);
54
+ const uniform = 1 / options.length;
55
+ const bump = 0.3;
56
+ const probabilities = options.map((o, i) => {
57
+ if (i === choiceIndex) {
58
+ return { option: o, probability: uniform + bump };
59
+ }
60
+ return { option: o, probability: uniform - (bump / Math.max(1, options.length - 1)) };
61
+ });
62
+ return {
63
+ question_id: request.questions[idx].id,
64
+ status: "ok",
65
+ choice,
66
+ probabilities,
67
+ confidence: 0.72,
68
+ seed: request.seed ?? null,
69
+ };
70
+ }),
71
+ backend: "direct",
72
+ model_id: "synthetic-ok-v0",
73
+ metadata: { runtime: "synthetic", provenance: "mcp-pilot-test-fixture" },
74
+ };
75
+ }
76
+ }
77
+
78
+ class SyntheticAbstainBackend {
79
+ constructor(reasons) { this.backend = "direct"; this.reasons = reasons; }
80
+ async decide(request) {
81
+ return {
82
+ answers: request.questions.map((q, i) => ({
83
+ question_id: q.id,
84
+ status: "abstain",
85
+ choice: null,
86
+ abstain_reason: this.reasons[i] ?? "synthetic abstention",
87
+ probabilities: [],
88
+ confidence: 0,
89
+ })),
90
+ backend: "direct",
91
+ model_id: "synthetic-abstain-v0",
92
+ };
93
+ }
94
+ }
95
+
96
+ class SyntheticThrowingBackend {
97
+ constructor(msg) { this.backend = "direct"; this.msg = msg; }
98
+ async decide(request) { void request; throw new Error(this.msg); }
99
+ }
100
+
101
+ describe("mcp.ts: isForbiddenBundlePath path safety", () => {
102
+ test("allows relative, safe paths", async (t) => {
103
+ void t;
104
+ const { isForbiddenBundlePath } = await import("../src/mcp.ts");
105
+ assert.equal(isForbiddenBundlePath("model.onnx"), false);
106
+ assert.equal(isForbiddenBundlePath("a/b/c.json"), false);
107
+ assert.equal(isForbiddenBundlePath("tokenizer/tokenizer.json"), false);
108
+ });
109
+ test("rejects URLs", async (t) => {
110
+ void t;
111
+ const { isForbiddenBundlePath } = await import("../src/mcp.ts");
112
+ assert.equal(isForbiddenBundlePath("https://example.com/x.onnx"), true);
113
+ assert.equal(isForbiddenBundlePath("http://evil/x"), true);
114
+ assert.equal(isForbiddenBundlePath("file:///etc/passwd"), true);
115
+ });
116
+ test("rejects absolute and traversal forms", async (t) => {
117
+ void t;
118
+ const { isForbiddenBundlePath } = await import("../src/mcp.ts");
119
+ assert.equal(isForbiddenBundlePath("/absolute/path"), true);
120
+ assert.equal(isForbiddenBundlePath("../escape"), true);
121
+ assert.equal(isForbiddenBundlePath("sub/../escape"), true);
122
+ assert.equal(isForbiddenBundlePath("foo%2e%2ebar"), true);
123
+ assert.equal(isForbiddenBundlePath("C:\\win\\path"), true);
124
+ assert.equal(isForbiddenBundlePath("D:/win/path"), true);
125
+ assert.equal(isForbiddenBundlePath("a/b/c?query"), true);
126
+ assert.equal(isForbiddenBundlePath("a/b#frag"), true);
127
+ });
128
+ });
129
+
130
+ describe("mcp-cli.ts createOnnxWebBackend integration: expectedManifestSha256 object-path mismatch regression", () => {
131
+ test("pretty disk manifest bytes hash differs from stableJson() in-memory hash; omitting expectedManifestSha256 lets structural validation proceed", async (t) => {
132
+ void t;
133
+ const { createHash } = await import("node:crypto");
134
+ const sdkMod = await import("../src/mcp.ts");
135
+ const manifest = syntheticManifest();
136
+ const prettyJson = JSON.stringify(manifest, null, 2);
137
+ const diskBytes = Buffer.from(prettyJson, "utf8");
138
+ const diskSha256 = createHash("sha256").update(diskBytes).digest("hex");
139
+ const stableSerialize = (value) => {
140
+ if (value === null || typeof value !== "object") {
141
+ const prim = JSON.stringify(value);
142
+ if (prim === undefined) throw new TypeError("undefined");
143
+ return prim;
144
+ }
145
+ if (Array.isArray(value)) {
146
+ return `[${value.map(stableSerialize).join(",")}]`;
147
+ }
148
+ const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
149
+ return `{${entries.map(([k, item]) => `${JSON.stringify(k)}:${stableSerialize(item)}`).join(",")}}`;
150
+ };
151
+ const stableSha256 = createHash("sha256")
152
+ .update(Buffer.from(stableSerialize(manifest), "utf8"))
153
+ .digest("hex");
154
+ assert.notEqual(
155
+ diskSha256,
156
+ stableSha256,
157
+ "regression requires pretty-disk hash and stable-json hash to actually differ",
158
+ );
159
+ const { loadBundleManifestStrict } = sdkMod;
160
+ const { dir } = writeSyntheticBundleDir(manifest);
161
+ const loaded = loadBundleManifestStrict(dir);
162
+ assert.equal(loaded.manifestSha256, diskSha256);
163
+ assert.equal(loaded.manifest.schema_version, manifest.schema_version);
164
+ const onnxMod = await import("../src/onnx.ts");
165
+ const localFetch = (async (input, init) => {
166
+ void init;
167
+ const u = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
168
+ if (!u.startsWith("vons-bundle-fs://local/")) {
169
+ throw new Error(`refused ${u.slice(0, 64)}`);
170
+ }
171
+ const rel = decodeURIComponent(u.slice("vons-bundle-fs://local/".length));
172
+ const path = await import("node:path");
173
+ const fs2 = await import("node:fs");
174
+ const abs = path.join(dir, ...rel.split("/"));
175
+ const bytes = fs2.readFileSync(abs);
176
+ return new Response(bytes.buffer, {
177
+ status: 200,
178
+ headers: { "content-type": "application/octet-stream", "content-length": String(bytes.byteLength) },
179
+ });
180
+ });
181
+ let thrownMsg = null;
182
+ try {
183
+ await onnxMod.createOnnxWebBackend({
184
+ manifest: loaded.manifest,
185
+ baseUrl: "vons-bundle-fs://local/",
186
+ provider: "wasm",
187
+ fetch: localFetch,
188
+ });
189
+ } catch (e) {
190
+ thrownMsg = e instanceof Error ? e.message : String(e);
191
+ }
192
+ assert.ok(thrownMsg !== null, "expected backend creation to fail for a synthetic bundle with invalid asset bytes");
193
+ assert.equal(
194
+ /SHA-256 mismatch/i.test(thrownMsg),
195
+ false,
196
+ `manifest SHA mismatch error must not appear; structural validation and asset loading must fail instead. Got: ${thrownMsg.slice(0, 180)}`,
197
+ );
198
+ });
199
+ });
200
+
201
+ describe("mcp.ts: loadBundleManifestStrict strict filesystem loader", () => {
202
+ let bundleDir = null;
203
+ let manifest = null;
204
+ beforeEach((t) => {
205
+ void t;
206
+ manifest = syntheticManifest();
207
+ const { dir } = writeSyntheticBundleDir(manifest);
208
+ bundleDir = dir;
209
+ });
210
+ afterEach((t) => {
211
+ void t;
212
+ if (bundleDir) try { rmSync(bundleDir, { recursive: true }); } catch (_) { void 0; }
213
+ bundleDir = null;
214
+ });
215
+ test("accepts a valid synthetic bundle", async (t) => {
216
+ void t;
217
+ const { loadBundleManifestStrict } = await import("../src/mcp.ts");
218
+ const result = loadBundleManifestStrict(bundleDir);
219
+ assert.equal(result.manifest.schema_version, "vons.bundle.manifest/v1");
220
+ assert.equal(result.manifest.metadata.backend, "direct");
221
+ assert.ok(result.manifestPath.endsWith("bundle-manifest-v1.json"), true);
222
+ assert.ok(result.rootRealPath.length > 0);
223
+ });
224
+ test("rejects URL bundle directory", async (t) => {
225
+ void t;
226
+ const { loadBundleManifestStrict } = await import("../src/mcp.ts");
227
+ assert.throws(() => loadBundleManifestStrict("https://evil.invalid/bundle"), /forbid|URL/);
228
+ assert.throws(() => loadBundleManifestStrict("file:///tmp/nope"), /forbid|URL/);
229
+ });
230
+ test("rejects bundle manifest with traversal in declared file paths", async (t) => {
231
+ void t;
232
+ const { loadBundleManifestStrict } = await import("../src/mcp.ts");
233
+ const badManifest = syntheticManifest();
234
+ badManifest.files = [...badManifest.files];
235
+ badManifest.files.push({ path: "../escape.pwn", role: "model_graph", bytes: 4, sha256: "1".repeat(64), model_asset: true, runtime_loaded: true });
236
+ const { dir } = writeSyntheticBundleDir(badManifest);
237
+ writeFileSync(join(dir, "escape.pwn"), Buffer.alloc(4));
238
+ try {
239
+ assert.throws(() => loadBundleManifestStrict(dir), /forbidden|traversal/);
240
+ } finally { rmSync(dir, { recursive: true }); }
241
+ });
242
+ test("rejects manifest SHA-256 mismatch explicitly (no silent fallback)", async (t) => {
243
+ void t;
244
+ const { loadBundleManifestStrict } = await import("../src/mcp.ts");
245
+ const expected = "a".repeat(64);
246
+ assert.throws(() => loadBundleManifestStrict(bundleDir, expected), /mismatch/);
247
+ });
248
+ test("rejects malformed JSON manifest", async (t) => {
249
+ void t;
250
+ const { loadBundleManifestStrict } = await import("../src/mcp.ts");
251
+ writeFileSync(join(bundleDir, "bundle-manifest-v1.json"), "{ not json ");
252
+ assert.throws(() => loadBundleManifestStrict(bundleDir), /valid JSON/);
253
+ });
254
+ test("rejects wrong schema_version", async (t) => {
255
+ void t;
256
+ const { loadBundleManifestStrict } = await import("../src/mcp.ts");
257
+ const badManifest = syntheticManifest();
258
+ badManifest.schema_version = "vons.bundle.manifest/v0";
259
+ const { dir } = writeSyntheticBundleDir(badManifest);
260
+ try {
261
+ assert.throws(() => loadBundleManifestStrict(dir), /schema_version/);
262
+ } finally { rmSync(dir, { recursive: true }); }
263
+ });
264
+ test("rejects symlink escapes from declared files", async (t) => {
265
+ void t;
266
+ const { loadBundleManifestStrict } = await import("../src/mcp.ts");
267
+ const outside = mkdtempSync(join(tmpdir(), "vons-mcp-outside-"));
268
+ try {
269
+ const evil = join(outside, "secret.txt");
270
+ writeFileSync(evil, "should-never-be-read");
271
+ const escape = join(bundleDir, "escape-link.onnx");
272
+ try { symlinkSync(evil, escape); } catch (_) { void 0; }
273
+ const badManifest = syntheticManifest();
274
+ badManifest.files = [{ path: "escape-link.onnx", role: "model_graph", bytes: 42, sha256: "1".repeat(64), runtime_loaded: true, model_asset: true }];
275
+ const manifestJson = JSON.stringify(badManifest, null, 2);
276
+ writeFileSync(join(bundleDir, "bundle-manifest-v1.json"), manifestJson);
277
+ assert.throws(() => loadBundleManifestStrict(bundleDir), /escapes bundle root|forbidden/);
278
+ } finally { rmSync(outside, { recursive: true }); }
279
+ });
280
+ test("rejects a bundle manifest symlink that resolves outside the bundle root", async (t) => {
281
+ void t;
282
+ const { loadBundleManifestStrict } = await import("../src/mcp.ts");
283
+ const outside = mkdtempSync(join(tmpdir(), "vons-mcp-outside-manifest-"));
284
+ const externalManifestPath = join(outside, "bundle-manifest-v1.json");
285
+ writeFileSync(externalManifestPath, JSON.stringify(syntheticManifest({ files: [] })));
286
+ const manifestPath = join(bundleDir, "bundle-manifest-v1.json");
287
+ try {
288
+ rmSync(manifestPath);
289
+ symlinkSync(externalManifestPath, manifestPath);
290
+ assert.throws(() => loadBundleManifestStrict(bundleDir), /bundle manifest escapes bundle root via symlink/);
291
+ } finally {
292
+ rmSync(outside, { recursive: true });
293
+ }
294
+ });
295
+ });
296
+
297
+ describe("mcp.ts: createMcpServer synthetic backend validation", () => {
298
+ test("rejects missing backend option", async (t) => {
299
+ void t;
300
+ const { createMcpServer } = await import("../src/mcp.ts");
301
+ assert.throws(() => createMcpServer({}), /backend.*DecisionBackend/);
302
+ });
303
+ test("DecisionRequestZodSchema strict-rejects empty questions", async (t) => {
304
+ void t;
305
+ const { DecisionRequestZodSchema } = await import("../src/mcp.ts");
306
+ const parsed = DecisionRequestZodSchema.safeParse({ state: "x", questions: [] });
307
+ assert.equal(parsed.success, false);
308
+ });
309
+ test("DecisionRequestZodSchema accepts a boolean question with omitted options", async (t) => {
310
+ void t;
311
+ const { DecisionRequestZodSchema } = await import("../src/mcp.ts");
312
+ const { validateRequest } = await import("../src/index.ts");
313
+ const request = {
314
+ state: "synthetic boolean request",
315
+ questions: [{ id: "q-bool", type: "boolean", prompt: "Is the statement true?", options: [] }],
316
+ };
317
+ const parsed = DecisionRequestZodSchema.safeParse(request);
318
+ assert.equal(parsed.success, true, "MCP schema must accept the shared boolean-options form");
319
+ assert.doesNotThrow(() => validateRequest(request));
320
+ });
321
+ test("DecisionRequestZodSchema strict-rejects unknown extra keys", async (t) => {
322
+ void t;
323
+ const { DecisionRequestZodSchema } = await import("../src/mcp.ts");
324
+ const parsed = DecisionRequestZodSchema.safeParse({
325
+ state: "ok", questions: [{ id: "q", type: "choice", prompt: "x", options: ["A", "B"] }],
326
+ evil_surprise: "should be rejected by strictObject",
327
+ });
328
+ assert.equal(parsed.success, false);
329
+ assert.ok(!parsed.success, "strict schema rejected passthrough; no fake coerce or fallback allowed");
330
+ });
331
+ test("shared validateRequest rejects duplicated question IDs", async (t) => {
332
+ void t;
333
+ const { validateRequest } = await import("../src/index.ts");
334
+ const dup = {
335
+ state: "x",
336
+ questions: [
337
+ { id: "q1", type: "choice", prompt: "a", options: ["A", "B"] },
338
+ { id: "q1", type: "choice", prompt: "b", options: ["A", "B"] },
339
+ ],
340
+ };
341
+ assert.throws(() => validateRequest(dup));
342
+ });
343
+ test("abstention from backend passes validateResponse and preserves abstain_reason", async (t) => {
344
+ void t;
345
+ const { validateResponse } = await import("../src/index.ts");
346
+ const backend = new SyntheticAbstainBackend(["confidence below threshold", "input unverifiable"]);
347
+ const response = await backend.decide({
348
+ state: "ok", questions: [
349
+ { id: "q1", type: "choice", prompt: "a", options: ["A", "B"] },
350
+ { id: "q2", type: "choice", prompt: "b", options: ["A", "B"] },
351
+ ],
352
+ });
353
+ validateResponse(response);
354
+ assert.equal(response.answers[0].status, "abstain");
355
+ assert.equal(response.answers[0].choice, null);
356
+ assert.equal(response.answers[0].abstain_reason, "confidence below threshold");
357
+ assert.equal(response.answers[1].abstain_reason, "input unverifiable");
358
+ });
359
+ test("backend throwing propagates explicit error with no fallback decision", async (t) => {
360
+ void t;
361
+ const backend = new SyntheticThrowingBackend("synthetic backend error: weights not loaded");
362
+ await assert.rejects(async () => backend.decide({
363
+ state: "x", questions: [{ id: "q", type: "choice", prompt: "x", options: ["A", "B"] }],
364
+ }), /synthetic backend error/);
365
+ });
366
+ test("SyntheticOkBackend produces a validatable response", async (t) => {
367
+ void t;
368
+ const { validateResponse } = await import("../src/index.ts");
369
+ const backend = new SyntheticOkBackend(["A", "B"]);
370
+ const response = await backend.decide({
371
+ state: "ok", questions: [
372
+ { id: "q1", type: "choice", prompt: "p1", options: ["A", "B"] },
373
+ { id: "q2", type: "choice", prompt: "p2", options: ["A", "B"] },
374
+ ],
375
+ });
376
+ validateResponse(response);
377
+ assert.equal(response.answers[0].choice, "A");
378
+ assert.equal(response.answers[1].choice, "B");
379
+ assert.equal(response.answers.every((a) => a.status === "ok"), true);
380
+ });
381
+ });
382
+
383
+ describe("mcp.ts: manifest resource exposes metadata only (no assets, no hashes)", () => {
384
+ test("metadata resource omits files, summary, bundle_loaded_from absolute path, and file hashes", async (t) => {
385
+ void t;
386
+ const { bundleManifestToMetadata } = await import("../src/mcp.ts");
387
+ const manifest = syntheticManifest();
388
+ const md = bundleManifestToMetadata(manifest, "/tmp/synthetic-path");
389
+ assert.equal(md.schema_version, "vons.bundle.metadata/v1");
390
+ assert.equal(md.backend, "direct");
391
+ assert.equal(md.option_count, 2);
392
+ assert.equal(md.sequence_length, 32);
393
+ assert.equal("bundle_loaded_from" in md, false);
394
+ assert.equal("files" in md, false);
395
+ assert.equal("summary" in md, false);
396
+ assert.equal("sha256" in md, false);
397
+ });
398
+ test("optional metadata fields default to null when missing", async (t) => {
399
+ void t;
400
+ const { bundleManifestToMetadata } = await import("../src/mcp.ts");
401
+ const manifest = syntheticManifest();
402
+ manifest.metadata = { backend: "diffusion" };
403
+ const md = bundleManifestToMetadata(manifest, "/tmp/x");
404
+ assert.equal(md.option_count, null);
405
+ assert.equal(md.sequence_length, null);
406
+ assert.equal(md.model_id, null);
407
+ assert.equal(md.backend, "diffusion");
408
+ });
409
+ });
410
+
411
+ describe("mcp-cli.ts: CLI argument handling", () => {
412
+ test("parseCliArgs captures --provider webgpu", async (t) => {
413
+ void t;
414
+ const { parseCliArgs } = await import("../src/mcp-cli.ts");
415
+ const args = parseCliArgs(["--bundle", "/x", "--provider", "webgpu"]);
416
+ assert.equal(args.provider, "webgpu");
417
+ assert.equal(args.bundle, "/x");
418
+ });
419
+ test("parseCliArgs rejects unknown options with exit code 2", async (t) => {
420
+ void t;
421
+ const cliPath = resolve(import.meta.dirname, "..", "src", "mcp-cli.ts");
422
+ const result = spawnSync(
423
+ process.execPath,
424
+ ["--experimental-strip-types", cliPath, "--bundle", "/x", "--unknown-flag"],
425
+ { encoding: "utf8", timeout: 15000 },
426
+ );
427
+ assert.ok(result.status !== 0);
428
+ });
429
+ test("missing --bundle prints usage to stderr with 'no auto-discover' notice and non-zero status", async (t) => {
430
+ void t;
431
+ const cliPath = resolve(import.meta.dirname, "..", "src", "mcp-cli.ts");
432
+ const result = spawnSync(
433
+ process.execPath,
434
+ ["--experimental-strip-types", cliPath],
435
+ { encoding: "utf8", timeout: 15000 },
436
+ );
437
+ assert.ok(result.status !== 0, `expected non-zero exit, got ${result.status}`);
438
+ assert.ok(/--bundle.*required/.test(result.stderr || ""), "stderr must mention required --bundle");
439
+ assert.ok(/no auto-discover/.test(result.stderr || ""), "stderr must state that no auto-discovery is performed");
440
+ assert.equal(/initialize|jsonrpc/i.test(result.stdout || ""), false, "no MCP stdout on usage error");
441
+ });
442
+ test("--help prints usage to stdout and exits 0 with constraint disclaimers", async (t) => {
443
+ void t;
444
+ const cliPath = resolve(import.meta.dirname, "..", "src", "mcp-cli.ts");
445
+ const result = spawnSync(
446
+ process.execPath,
447
+ ["--experimental-strip-types", cliPath, "--help"],
448
+ { encoding: "utf8", timeout: 15000 },
449
+ );
450
+ assert.equal(result.status, 0);
451
+ assert.ok(/USAGE:/.test(result.stdout));
452
+ assert.ok(/CONSTRAINTS/.test(result.stdout));
453
+ assert.ok(/no auto-discovery|No HTTP listener|never authorizes|no silent fallback/.test(result.stdout));
454
+ });
455
+ test("--provider webgpu + --bundle (valid) exits with WebGPU rejection code", async (t) => {
456
+ void t;
457
+ const manifest = syntheticManifest();
458
+ const { dir } = writeSyntheticBundleDir(manifest);
459
+ try {
460
+ const cliPath = resolve(import.meta.dirname, "..", "src", "mcp-cli.ts");
461
+ const result = spawnSync(
462
+ process.execPath,
463
+ ["--experimental-strip-types", cliPath, "--bundle", dir, "--provider", "webgpu"],
464
+ { encoding: "utf8", timeout: 15000 },
465
+ );
466
+ assert.equal(result.status, 4);
467
+ assert.ok(/WebGPU adapter|cannot obtain a browser WebGPU/.test(result.stderr || ""));
468
+ } finally { rmSync(dir, { recursive: true }); }
469
+ });
470
+ test("invalid bundle path exits with explicit error, no fallback, no MCP stdout traffic", async (t) => {
471
+ void t;
472
+ const cliPath = resolve(import.meta.dirname, "..", "src", "mcp-cli.ts");
473
+ const notExist = join(tmpdir(), "vons-mcp-missing-bundle-12345");
474
+ const result = spawnSync(
475
+ process.execPath,
476
+ ["--experimental-strip-types", cliPath, "--bundle", notExist],
477
+ { encoding: "utf8", timeout: 15000 },
478
+ );
479
+ assert.equal(result.status, 3);
480
+ assert.ok(/bundle load failed|not found/.test(result.stderr || ""));
481
+ assert.ok(/No silent fallback/.test(result.stderr || ""));
482
+ assert.equal(/jsonrpc|initialize/i.test(result.stdout || ""), false);
483
+ });
484
+ test("URI-scheme rejection truncates long --bundle values at 120 chars with (truncated) marker; sentinel tail beyond index 120 never leaks", async (t) => {
485
+ void t;
486
+ const cliPath = resolve(import.meta.dirname, "..", "src", "mcp-cli.ts");
487
+ const TAIL_SENTINEL_1841 = "TAIL_SENTINEL_1841_zircon_trilobite_tip";
488
+ const BOUNDARY_CHAR_119 = "\u2694";
489
+ const httpsHeader = "https://example.com/prefix";
490
+ const fillBeforeBoundary = "q".repeat(Math.max(0, 119 - httpsHeader.length));
491
+ const tailAfterBoundary = "r".repeat(400);
492
+ const longValue = httpsHeader + fillBeforeBoundary + BOUNDARY_CHAR_119 + tailAfterBoundary + TAIL_SENTINEL_1841;
493
+ assert.equal(
494
+ longValue[119],
495
+ BOUNDARY_CHAR_119,
496
+ `BOUNDARY_CHAR_119 must live at raw index 119 so the test exercises the exact truncation boundary. ` +
497
+ `Actual longValue[119]=${JSON.stringify(longValue[119])}, ` +
498
+ `fillBeforeBoundary.length=${fillBeforeBoundary.length}, ` +
499
+ `httpsHeader.length=${httpsHeader.length}, ` +
500
+ `longValue.length=${longValue.length}.`,
501
+ );
502
+ assert.ok(
503
+ longValue.indexOf(TAIL_SENTINEL_1841) >= 120,
504
+ `tail sentinel must begin at index >= 120 to test truncation; actual start=${longValue.indexOf(TAIL_SENTINEL_1841)} value.length=${longValue.length}`,
505
+ );
506
+ const longResult = spawnSync(
507
+ process.execPath,
508
+ ["--experimental-strip-types", cliPath, "--bundle", longValue],
509
+ { encoding: "utf8", timeout: 15000 },
510
+ );
511
+ assert.equal(longResult.status, 3, `long https:// --bundle must exit=3 actual=${longResult.status} stderr=${JSON.stringify(longResult.stderr?.slice(0, 200))}`);
512
+ assert.ok(
513
+ (longResult.stderr || "").includes("URI scheme 'https://' is not supported"),
514
+ `long https:// --bundle stderr must include the exact diagnostic: URI scheme 'https://' is not supported. stderr=${JSON.stringify(longResult.stderr?.slice(0, 220))}`,
515
+ );
516
+ assert.ok(/'https':\/\/|https:\/\/|scheme.*https/.test(longResult.stderr || ""), "stderr must mention https or scheme=https for long --bundle");
517
+ assert.ok(/\(truncated\)/.test(longResult.stderr || ""), `stderr must contain literal (truncated) marker for long values. stderr=${JSON.stringify(longResult.stderr?.slice(0, 220))}`);
518
+ assert.ok(
519
+ (longResult.stderr || "").includes(BOUNDARY_CHAR_119),
520
+ `stderr must include the distinctive BOUNDARY_CHAR_119 at raw index 119 '${BOUNDARY_CHAR_119}' so truncation is proven to include the boundary byte. stderr=${JSON.stringify(longResult.stderr?.slice(0, 220))}`,
521
+ );
522
+ assert.equal(
523
+ (longResult.stdout || "").includes(TAIL_SENTINEL_1841),
524
+ false,
525
+ `long-value tail sentinel '${TAIL_SENTINEL_1841}' must NOT appear on stdout; got stdout=${JSON.stringify(longResult.stdout?.slice(0, 200))}`,
526
+ );
527
+ assert.equal(
528
+ (longResult.stderr || "").includes(TAIL_SENTINEL_1841),
529
+ false,
530
+ `long-value tail sentinel '${TAIL_SENTINEL_1841}' must NOT appear on stderr even truncated form allowed 120 chars. stderr=${JSON.stringify((longResult.stderr || "").slice(0, 300))}`,
531
+ );
532
+ assert.equal(
533
+ /bundle directory not found/i.test(longResult.stderr || ""),
534
+ false,
535
+ `long https:// --bundle must NOT produce misleading 'bundle directory not found' text`,
536
+ );
537
+ assert.equal(
538
+ longResult.stdout,
539
+ "",
540
+ `stdout must be exactly empty for long-value URI rejection (no MCP no whitespace). actual stdout=${JSON.stringify(longResult.stdout)}`,
541
+ );
542
+ const shortPad = "d".repeat(Math.max(0, 120 - "https://example.com/s=".length));
543
+ const exactly120 = "https://example.com/s=" + shortPad;
544
+ assert.equal(
545
+ exactly120.length,
546
+ 120,
547
+ `this sub-case requires a raw --bundle value whose length is exactly 120 characters to prove (truncated) is omitted; actual length=${exactly120.length}`,
548
+ );
549
+ const exactResult = spawnSync(
550
+ process.execPath,
551
+ ["--experimental-strip-types", cliPath, "--bundle", exactly120],
552
+ { encoding: "utf8", timeout: 15000 },
553
+ );
554
+ assert.equal(exactResult.status, 3, `exactly-120-char https:// --bundle must also exit=3 actual=${exactResult.status}`);
555
+ assert.ok(
556
+ (exactResult.stderr || "").includes("URI scheme 'https://' is not supported"),
557
+ `exactly-120-char https:// --bundle stderr must include the exact diagnostic: URI scheme 'https://' is not supported. stderr=${JSON.stringify(exactResult.stderr?.slice(0, 220))}`,
558
+ );
559
+ assert.equal(
560
+ /\(truncated\)/.test(exactResult.stderr || ""),
561
+ false,
562
+ `exactly-120-char value must NOT print '(truncated)' (only values strictly longer should get the marker). stderr=${JSON.stringify(exactResult.stderr?.slice(0, 220))}`,
563
+ );
564
+ assert.ok(
565
+ /scheme|https|not supported|--bundle rejected/.test(exactResult.stderr || ""),
566
+ `exactly-120-char value must still produce the explicit URI-scheme error. stderr=${JSON.stringify(exactResult.stderr?.slice(0, 220))}`,
567
+ );
568
+ assert.equal(
569
+ exactResult.stdout,
570
+ "",
571
+ `stdout must be exactly empty for exact-120-char URI rejection (no MCP no whitespace). actual stdout=${JSON.stringify(exactResult.stdout)}`,
572
+ );
573
+ });
574
+ test("rejects URI-scheme --bundle values (https://, file://, ftp://, data:) with exit 3, explicit scheme error, NEVER 'bundle directory not found'", async (t) => {
575
+ void t;
576
+ const cliPath = resolve(import.meta.dirname, "..", "src", "mcp-cli.ts");
577
+ const cases = [
578
+ ["https://example.com/bundle", "https"],
579
+ ["file:///tmp/nonexistent-vons-mcp-xyz", "file"],
580
+ ["ftp://files.internal/pub/bundle-v1", "ftp"],
581
+ ["data:text/plain,rawbundlecontents", "data"],
582
+ ];
583
+ for (const [value, scheme] of cases) {
584
+ const result = spawnSync(
585
+ process.execPath,
586
+ ["--experimental-strip-types", cliPath, "--bundle", value],
587
+ { encoding: "utf8", timeout: 15000 },
588
+ );
589
+ assert.equal(result.status, 3, `exit=3 for scheme=${scheme} value=${value}`);
590
+ assert.ok(
591
+ /--bundle rejected|URI scheme|not supported/.test(result.stderr || ""),
592
+ `stderr must contain explicit URI-scheme rejection for ${scheme}: got stderr=${JSON.stringify(result.stderr)}`,
593
+ );
594
+ assert.ok(
595
+ new RegExp(`scheme.*'${scheme}://'|'${scheme}://'`).test(result.stderr || ""),
596
+ `stderr must name the rejected scheme '${scheme}://' for value=${value}`,
597
+ );
598
+ assert.equal(
599
+ /bundle directory not found/i.test(result.stderr || ""),
600
+ false,
601
+ `stderr must NOT contain the misleading 'bundle directory not found' string for scheme input ${value}`,
602
+ );
603
+ assert.equal(/jsonrpc|initialize/i.test(result.stdout || ""), false);
604
+ }
605
+ });
606
+ test("supports shell-resolved ../ relative --bundle: synthetic bundle accessed via ../<basename>/./sibling/../<basename> succeeds: writes bundle-loaded banner to stderr, no scheme-rejection, no not-found error", async (t) => {
607
+ void t;
608
+ const manifest = syntheticManifest();
609
+ const { dir } = writeSyntheticBundleDir(manifest);
610
+ try {
611
+ const cliPath = resolve(import.meta.dirname, "..", "src", "mcp-cli.ts");
612
+ const parent = resolve(dir, "..");
613
+ const basename = dir.slice(parent.length + 1) || "";
614
+ const validDotDotRelative = `${parent}/./sibling/../${basename}`;
615
+ const result = spawnSync(
616
+ process.execPath,
617
+ ["--experimental-strip-types", cliPath, "--bundle", validDotDotRelative, "--provider", "wasm"],
618
+ { encoding: "utf8", timeout: 6000, input: "", maxBuffer: 2 * 1024 * 1024 },
619
+ );
620
+ assert.ok(
621
+ result.status !== 3,
622
+ `valid ../ bundle path must NOT exit with code=3 (scheme or missing-dir error). Got status=${result.status} stderr=${JSON.stringify(result.stderr?.slice(0, 300))}`,
623
+ );
624
+ assert.equal(
625
+ /--bundle rejected|URI scheme|bundle directory not found/.test(result.stderr || ""),
626
+ false,
627
+ `valid ../ bundle must NOT be rejected as URI scheme or 'bundle directory not found'. Got stderr=${JSON.stringify(result.stderr?.slice(0, 300))}`,
628
+ );
629
+ assert.ok(
630
+ /bundle loaded:|manifest\.sha256=|Starting stdio MCP server|provider=wasm/.test(result.stderr || ""),
631
+ `valid ../ bundle must succeed and write the 'bundle loaded:' / manifest.sha256 / provider=wasm / Starting stdio MCP banner to stderr. Got stderr=${JSON.stringify(result.stderr?.slice(0, 400))}`,
632
+ );
633
+ } finally {
634
+ rmSync(dir, { recursive: true });
635
+ }
636
+ });
637
+ });
638
+
639
+ describe("mcp.ts: MCP initialize / tools/list / tools/call stdio round trip (synthetic backend, injected)", () => {
640
+ function createLoopbackStdio() {
641
+ const serverStdin = new PassThrough();
642
+ const serverStdout = new PassThrough();
643
+ let outBuf = "";
644
+ const outLines = [];
645
+ let resolver = null;
646
+ serverStdout.setEncoding("utf8");
647
+ serverStdout.on("data", (chunk) => {
648
+ outBuf += chunk;
649
+ let idx;
650
+ while ((idx = outBuf.indexOf("\n")) !== -1) {
651
+ const line = outBuf.slice(0, idx);
652
+ outBuf = outBuf.slice(idx + 1);
653
+ if (line.length > 0) outLines.push(line);
654
+ if (resolver) {
655
+ const res = resolver;
656
+ resolver = null;
657
+ res(outLines.shift());
658
+ }
659
+ }
660
+ });
661
+ serverStdout.on("end", () => {
662
+ if (resolver) {
663
+ const res = resolver;
664
+ resolver = null;
665
+ res(null);
666
+ }
667
+ });
668
+ const nextLine = (timeoutMs = 8000) => {
669
+ if (outLines.length > 0) return Promise.resolve(outLines.shift());
670
+ return new Promise((resolve, reject) => {
671
+ const timer = setTimeout(() => {
672
+ resolver = null;
673
+ reject(new Error(`timeout waiting for MCP message on stdout (buffer=${JSON.stringify(outBuf)})`));
674
+ }, timeoutMs);
675
+ resolver = (v) => {
676
+ clearTimeout(timer);
677
+ resolve(v);
678
+ };
679
+ });
680
+ };
681
+ const nextMessage = async (timeoutMs) => {
682
+ const line = await nextLine(timeoutMs);
683
+ if (!line) throw new Error("stream ended while waiting for message");
684
+ return JSON.parse(line);
685
+ };
686
+ const writeLine = (line) => {
687
+ serverStdin.write(line + "\n");
688
+ };
689
+ const end = () => {
690
+ serverStdin.end();
691
+ };
692
+ return { serverStdin, serverStdout, writeLine, end, nextMessage, nextLine, serverStdoutLines: outLines };
693
+ }
694
+
695
+ function mcpRequest(method, params, id) {
696
+ return JSON.stringify({ jsonrpc: "2.0", id, method, params });
697
+ }
698
+
699
+ test("initialize returns server capabilities with tool + resource, then list tools, then call vons_decide (SyntheticOkBackend)", async (t) => {
700
+ void t;
701
+ const { runStdioMcpServer } = await import("../src/mcp.ts");
702
+ const manifest = syntheticManifest();
703
+ const backend = new SyntheticOkBackend(["A", "B"]);
704
+ const loop = createLoopbackStdio();
705
+ const ac = new AbortController();
706
+ const serverPromise = runStdioMcpServer({
707
+ backend,
708
+ manifest,
709
+ manifestSha256: "a".repeat(64),
710
+ bundleRoot: "/tmp/roundtrip-bundle",
711
+ stdin: loop.serverStdin,
712
+ stdout: loop.serverStdout,
713
+ signal: ac.signal,
714
+ }).catch((e) => e);
715
+
716
+ loop.writeLine(
717
+ mcpRequest(
718
+ "initialize",
719
+ {
720
+ protocolVersion: "2024-11-05",
721
+ capabilities: {},
722
+ clientInfo: { name: "mcp-pilot-test", version: "0.1.0" },
723
+ },
724
+ 1,
725
+ ),
726
+ );
727
+ const initResp = await loop.nextMessage(8000);
728
+ assert.equal(initResp.jsonrpc, "2.0");
729
+ assert.equal(initResp.id, 1);
730
+ assert.ok(initResp.result, "initialize result missing");
731
+ assert.ok(initResp.result.capabilities?.tools, "initialize capabilities.tools missing");
732
+ assert.equal(initResp.result.serverInfo?.name, "vons-local-mcp");
733
+
734
+ loop.writeLine(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized", params: {} }));
735
+
736
+ loop.writeLine(mcpRequest("tools/list", {}, 2));
737
+ const listResp = await loop.nextMessage(6000);
738
+ assert.equal(listResp.id, 2);
739
+ assert.ok(Array.isArray(listResp.result?.tools));
740
+ const toolNames = listResp.result.tools.map((tool) => tool.name);
741
+ assert.ok(toolNames.includes("vons_decide"), `expected vons_decide in tools list, got ${toolNames.join(",")}`);
742
+
743
+ const req = {
744
+ state: "hello round trip",
745
+ questions: [
746
+ { id: "q1", type: "choice", prompt: "pick", options: ["A", "B"] },
747
+ { id: "q2", type: "choice", prompt: "pick", options: ["A", "B"] },
748
+ ],
749
+ backend: "direct",
750
+ };
751
+ loop.writeLine(mcpRequest("tools/call", { name: "vons_decide", arguments: req }, 3));
752
+ const callResp = await loop.nextMessage(8000);
753
+ assert.equal(callResp.id, 3);
754
+ assert.ok(callResp.result?.content && callResp.result.content.length > 0, "content missing");
755
+ const parsed = JSON.parse(callResp.result.content[0].text);
756
+ assert.equal(!!parsed.error, false, `unexpected MCP error: ${JSON.stringify(parsed)}`);
757
+ assert.equal(parsed.answers.length, 2);
758
+ assert.equal(parsed.answers[0].question_id, "q1");
759
+ assert.equal(parsed.answers[0].choice, "A");
760
+ assert.equal(parsed.answers[1].question_id, "q2");
761
+ assert.equal(parsed.answers[1].choice, "B");
762
+
763
+ ac.abort();
764
+ loop.end();
765
+ const shutdownOrError = await serverPromise;
766
+ if (shutdownOrError instanceof Error && !/abort|close|ended|aborted/i.test(shutdownOrError.message)) {
767
+ throw shutdownOrError;
768
+ }
769
+ });
770
+
771
+ test("rejects backend answers whose question IDs do not exactly match the request", async (t) => {
772
+ void t;
773
+ const { runStdioMcpServer } = await import("../src/mcp.ts");
774
+ const backend = {
775
+ async decide() {
776
+ return {
777
+ answers: [
778
+ { question_id: "q1", status: "ok", choice: "A", probabilities: [{ option: "A", probability: 1 }], confidence: 1 },
779
+ { question_id: "unexpected", status: "ok", choice: "B", probabilities: [{ option: "B", probability: 1 }], confidence: 1 },
780
+ ],
781
+ backend: "direct",
782
+ model_id: "synthetic-mismatched-question-ids",
783
+ };
784
+ },
785
+ };
786
+ const loop = createLoopbackStdio();
787
+ const ac = new AbortController();
788
+ const serverPromise = runStdioMcpServer({
789
+ backend,
790
+ stdin: loop.serverStdin,
791
+ stdout: loop.serverStdout,
792
+ signal: ac.signal,
793
+ }).catch((error) => error);
794
+
795
+ loop.writeLine(
796
+ mcpRequest(
797
+ "initialize",
798
+ { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "mcp-id-mismatch", version: "0.1.0" } },
799
+ 401,
800
+ ),
801
+ );
802
+ assert.equal((await loop.nextMessage(8000)).id, 401);
803
+ loop.writeLine(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized", params: {} }));
804
+ loop.writeLine(
805
+ mcpRequest(
806
+ "tools/call",
807
+ {
808
+ name: "vons_decide",
809
+ arguments: {
810
+ state: "synthetic request with two questions",
811
+ questions: [
812
+ { id: "q1", type: "choice", prompt: "first", options: ["A", "B"] },
813
+ { id: "q2", type: "choice", prompt: "second", options: ["A", "B"] },
814
+ ],
815
+ },
816
+ },
817
+ 402,
818
+ ),
819
+ );
820
+ const callResp = await loop.nextMessage(8000);
821
+ assert.equal(callResp.id, 402);
822
+ assert.equal(callResp.result?.isError, true);
823
+ assert.match(JSON.parse(callResp.result.content[0].text).error, /question IDs must exactly match/);
824
+
825
+ ac.abort();
826
+ loop.end();
827
+ await serverPromise;
828
+ });
829
+
830
+ test("stderr logger messages never include request, response, or backend error content", async (t) => {
831
+ void t;
832
+ const { runStdioMcpServer } = await import("../src/mcp.ts");
833
+ const questionSentinel = "QUESTION_SENTINEL_9242_gnevas";
834
+ const stateSentinel = "STATE_SENTINEL_7161_zibex";
835
+ const promptSentinel = "PROMPT_SENTINEL_8311_ambrom";
836
+ const distinctiveErrorName = "ZeppelinRudderError_48291";
837
+ const distinctiveErrorMessage = "kraken_barnacle_stern_918_wobble_fjord";
838
+ const distinctiveErrorClass = class extends Error {
839
+ constructor() {
840
+ super(distinctiveErrorMessage);
841
+ this.name = distinctiveErrorName;
842
+ }
843
+ };
844
+ const sentinels = [questionSentinel, stateSentinel, promptSentinel, distinctiveErrorName, distinctiveErrorMessage];
845
+ const logMessages = [];
846
+ const backend = {
847
+ async decide(request) {
848
+ if (request.questions.some((q) => String(q.id) === questionSentinel || String(q.prompt) === promptSentinel)) {
849
+ throw new distinctiveErrorClass();
850
+ }
851
+ throw new distinctiveErrorClass();
852
+ },
853
+ };
854
+ const loop = createLoopbackStdio();
855
+ const ac = new AbortController();
856
+ const serverPromise = runStdioMcpServer({
857
+ backend,
858
+ stdin: loop.serverStdin,
859
+ stdout: loop.serverStdout,
860
+ signal: ac.signal,
861
+ logger: (_level, message) => logMessages.push(message),
862
+ }).catch((error) => error);
863
+
864
+ loop.writeLine(
865
+ mcpRequest(
866
+ "initialize",
867
+ { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "mcp-safe-logs", version: "0.1.0" } },
868
+ 501,
869
+ ),
870
+ );
871
+ assert.equal((await loop.nextMessage(8000)).id, 501);
872
+ loop.writeLine(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized", params: {} }));
873
+
874
+ const call = async (arguments_, id) => {
875
+ loop.writeLine(mcpRequest("tools/call", { name: "vons_decide", arguments: arguments_ }, id));
876
+ return loop.nextMessage(8000);
877
+ };
878
+ const schemaValidationFailure = await call({
879
+ state: "schema-fail-state",
880
+ questions: [{ id: "q-schema", type: "choice", prompt: "synthetic", options: ["A", "B"], UNKNOWN_EXTRA_KEY_48291: true }],
881
+ UNKNOWN_ROOT_KEY: true,
882
+ }, 501);
883
+ assert.equal(schemaValidationFailure.result?.isError ?? ("error" in schemaValidationFailure), true);
884
+
885
+ const sharedContractFailure = await call({
886
+ state: "valid synthetic state",
887
+ questions: [
888
+ { id: questionSentinel, type: "choice", prompt: "first", options: ["A", "B"] },
889
+ { id: questionSentinel, type: "choice", prompt: "second", options: ["A", "B"] },
890
+ ],
891
+ }, 502);
892
+ assert.equal(sharedContractFailure.result?.isError, true);
893
+
894
+ const backendFailure = await call({
895
+ state: stateSentinel,
896
+ questions: [{ id: "q-backend", type: "choice", prompt: promptSentinel, options: ["A", "B"] }],
897
+ }, 503);
898
+ assert.equal(backendFailure.result?.isError, true);
899
+ assert.match(
900
+ backendFailure.result.content[0].text,
901
+ /vons_decide backend raised a runtime error/,
902
+ "backend failure → generic sanitized stdout error",
903
+ );
904
+ assert.equal(
905
+ backendFailure.result.content[0].text.includes("synthetic failure echoed request"),
906
+ false,
907
+ "backend error must not include thrown message verbatim",
908
+ );
909
+ const allowedLogsExactly = new Set([
910
+ "invalid tool arguments rejected by strict schema validation",
911
+ "request rejected by shared contract validation",
912
+ "backend inference failed; no response or fallback decision was produced",
913
+ ]);
914
+ for (const msg of logMessages) {
915
+ assert.ok(allowedLogsExactly.has(msg), `log message must be EXACTLY one of the three constant strings; got: ${JSON.stringify(msg)}`);
916
+ }
917
+ const requiredLogsExactly = [
918
+ "request rejected by shared contract validation",
919
+ "backend inference failed; no response or fallback decision was produced",
920
+ ];
921
+ for (const required of requiredLogsExactly) {
922
+ assert.ok(
923
+ logMessages.some((m) => m === required),
924
+ `missing required EXACT log string: ${required}. Actual log messages: ${JSON.stringify(logMessages)}`,
925
+ );
926
+ }
927
+ for (const value of sentinels) {
928
+ assert.equal(
929
+ backendFailure.result.content[0].text.includes(value),
930
+ false,
931
+ `stdout error content must not leak sentinel ${value}`,
932
+ );
933
+ assert.equal(
934
+ logMessages.join("\n").includes(value),
935
+ false,
936
+ `stderr log must not leak sentinel ${value}`,
937
+ );
938
+ assert.equal(
939
+ sharedContractFailure.result.content[0].text.includes(value),
940
+ false,
941
+ `stdout shared-contract-failure content must not leak sentinel ${value}`,
942
+ );
943
+ }
944
+
945
+ ac.abort();
946
+ loop.end();
947
+ await serverPromise;
948
+ });
949
+
950
+ test("malformed vons_decide arguments round trip → explicit MCP error content, no coerced choice", async (t) => {
951
+ void t;
952
+ const { runStdioMcpServer } = await import("../src/mcp.ts");
953
+ const manifest = syntheticManifest();
954
+ const backend = new SyntheticOkBackend(["X"]);
955
+ const loop = createLoopbackStdio();
956
+ const ac = new AbortController();
957
+ const serverPromise = runStdioMcpServer({
958
+ backend,
959
+ manifest,
960
+ manifestSha256: "b".repeat(64),
961
+ bundleRoot: "/tmp/err-bundle",
962
+ stdin: loop.serverStdin,
963
+ stdout: loop.serverStdout,
964
+ signal: ac.signal,
965
+ }).catch((e) => e);
966
+
967
+ loop.writeLine(
968
+ mcpRequest(
969
+ "initialize",
970
+ {
971
+ protocolVersion: "2024-11-05",
972
+ capabilities: {},
973
+ clientInfo: { name: "mcp-pilot-test-err", version: "0.1.0" },
974
+ },
975
+ 1,
976
+ ),
977
+ );
978
+ const initResp = await loop.nextMessage(8000);
979
+ assert.equal(initResp.id, 1);
980
+
981
+ loop.writeLine(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized", params: {} }));
982
+
983
+ const badReq = {
984
+ state: "x",
985
+ questions: [
986
+ { id: "q0", type: "choice", prompt: "p", options: ["A", "B"], EXTRA_KEY_SHOULD_BE_REJECTED: true },
987
+ ],
988
+ };
989
+ loop.writeLine(mcpRequest("tools/call", { name: "vons_decide", arguments: badReq }, 2));
990
+ const callResp = await loop.nextMessage(8000);
991
+ assert.equal(callResp.jsonrpc, "2.0");
992
+ assert.equal(callResp.id, 2);
993
+ const hasErrorContent =
994
+ (callResp.result && callResp.result.content && callResp.result.content.length > 0 && callResp.result.isError) ||
995
+ typeof callResp.error?.message === "string";
996
+ assert.ok(hasErrorContent, `expected an MCP error, got ${JSON.stringify(callResp).slice(0, 200)}`);
997
+
998
+ ac.abort();
999
+ loop.end();
1000
+ await serverPromise;
1001
+ });
1002
+
1003
+ test("tools/list exposes exactly one tool (only vons_decide) and no KASI or extra tools leak via protocol", async (t) => {
1004
+ void t;
1005
+ const { runStdioMcpServer } = await import("../src/mcp.ts");
1006
+ const manifest = syntheticManifest();
1007
+ const backend = new SyntheticOkBackend(["X", "Y"]);
1008
+ const loop = createLoopbackStdio();
1009
+ const ac = new AbortController();
1010
+ const serverPromise = runStdioMcpServer({
1011
+ backend,
1012
+ manifest,
1013
+ manifestSha256: "c".repeat(64),
1014
+ bundleRoot: "/tmp/exact-tools-bundle",
1015
+ stdin: loop.serverStdin,
1016
+ stdout: loop.serverStdout,
1017
+ signal: ac.signal,
1018
+ }).catch((e) => e);
1019
+
1020
+ loop.writeLine(
1021
+ mcpRequest(
1022
+ "initialize",
1023
+ {
1024
+ protocolVersion: "2024-11-05",
1025
+ capabilities: {},
1026
+ clientInfo: { name: "exact-tools-round-trip", version: "0.1.0" },
1027
+ },
1028
+ 101,
1029
+ ),
1030
+ );
1031
+ const initResp = await loop.nextMessage(8000);
1032
+ assert.equal(initResp.id, 101);
1033
+ assert.equal(initResp.result.serverInfo.name, "vons-local-mcp");
1034
+
1035
+ loop.writeLine(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized", params: {} }));
1036
+
1037
+ loop.writeLine(mcpRequest("tools/list", {}, 102));
1038
+ const listResp = await loop.nextMessage(6000);
1039
+ assert.equal(listResp.id, 102);
1040
+ const tools = listResp.result.tools;
1041
+ assert.equal(Array.isArray(tools), true);
1042
+ assert.equal(
1043
+ tools.length,
1044
+ 1,
1045
+ `exactly one tool must be exposed; got tools=[${tools.map((x) => x.name).join(",")}]`,
1046
+ );
1047
+ assert.equal(tools[0].name, "vons_decide");
1048
+ assert.ok(
1049
+ typeof tools[0].inputSchema === "object" && tools[0].inputSchema !== null,
1050
+ "vons_decide tool must advertise an inputSchema",
1051
+ );
1052
+
1053
+ ac.abort();
1054
+ loop.end();
1055
+ await serverPromise;
1056
+ });
1057
+
1058
+ test("resources/read returns manifest metadata without requiring a bundleRoot or leaking local paths", async (t) => {
1059
+ void t;
1060
+ const { runStdioMcpServer } = await import("../src/mcp.ts");
1061
+ const manifest = syntheticManifest();
1062
+ manifest.metadata.backend = "diffusion";
1063
+ manifest.metadata.model_id = "synthetic-regression-model-v0";
1064
+ manifest.metadata.option_count = 4;
1065
+ manifest.metadata.sequence_length = 2048;
1066
+ const backend = new SyntheticOkBackend(["A", "B", "C", "D"]);
1067
+ const loop = createLoopbackStdio();
1068
+ const ac = new AbortController();
1069
+ const serverPromise = runStdioMcpServer({
1070
+ backend,
1071
+ manifest,
1072
+ manifestSha256: "d".repeat(64),
1073
+ stdin: loop.serverStdin,
1074
+ stdout: loop.serverStdout,
1075
+ signal: ac.signal,
1076
+ }).catch((e) => e);
1077
+
1078
+ loop.writeLine(
1079
+ mcpRequest(
1080
+ "initialize",
1081
+ {
1082
+ protocolVersion: "2024-11-05",
1083
+ capabilities: { resources: {} },
1084
+ clientInfo: { name: "resources-read-metadata", version: "0.1.0" },
1085
+ },
1086
+ 201,
1087
+ ),
1088
+ );
1089
+ const initResp = await loop.nextMessage(8000);
1090
+ assert.equal(initResp.id, 201);
1091
+ assert.ok(initResp.result.capabilities?.resources, "server must declare resources capability");
1092
+
1093
+ loop.writeLine(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized", params: {} }));
1094
+
1095
+ loop.writeLine(
1096
+ mcpRequest("resources/read", { uri: "vons://bundle/manifest/metadata" }, 202),
1097
+ );
1098
+ const readResp = await loop.nextMessage(8000);
1099
+ assert.equal(readResp.jsonrpc, "2.0");
1100
+ assert.equal(readResp.id, 202);
1101
+ assert.ok(Array.isArray(readResp.result?.contents), "resources/read must return contents[] array");
1102
+ const entry = readResp.result.contents.find((c) => c.mimeType === "application/json");
1103
+ assert.ok(entry, `application/json entry must exist in metadata resource response`);
1104
+ const md = JSON.parse(entry.text);
1105
+ assert.equal(md.schema_version, "vons.bundle.metadata/v1");
1106
+ assert.equal(md.backend, "diffusion");
1107
+ assert.equal(md.model_id, "synthetic-regression-model-v0");
1108
+ assert.equal(md.option_count, 4);
1109
+ assert.equal(md.sequence_length, 2048);
1110
+ assert.equal("bundle_loaded_from" in md, false, "bundle_loaded_from absolute local path must not appear in metadata");
1111
+ assert.equal("files" in md, false);
1112
+ assert.equal("hashes" in md, false);
1113
+
1114
+ ac.abort();
1115
+ loop.end();
1116
+ await serverPromise;
1117
+ });
1118
+
1119
+ test("tools/call with SyntheticAbstainBackend preserves abstention choice=null + reason exact via round-trip protocol", async (t) => {
1120
+ void t;
1121
+ const { runStdioMcpServer } = await import("../src/mcp.ts");
1122
+ const manifest = syntheticManifest();
1123
+ const reasons = [
1124
+ "prompt does not contain sufficient grounding for an unambiguous pick",
1125
+ "backend abstains by synthetic injection: no options legible in question q2",
1126
+ ];
1127
+ const backend = new SyntheticAbstainBackend(reasons);
1128
+ const loop = createLoopbackStdio();
1129
+ const ac = new AbortController();
1130
+ const serverPromise = runStdioMcpServer({
1131
+ backend,
1132
+ manifest,
1133
+ manifestSha256: "e".repeat(64),
1134
+ bundleRoot: "/tmp/abstain-round-trip-bundle",
1135
+ stdin: loop.serverStdin,
1136
+ stdout: loop.serverStdout,
1137
+ signal: ac.signal,
1138
+ }).catch((e) => e);
1139
+
1140
+ loop.writeLine(
1141
+ mcpRequest(
1142
+ "initialize",
1143
+ {
1144
+ protocolVersion: "2024-11-05",
1145
+ capabilities: {},
1146
+ clientInfo: { name: "abstain-round-trip", version: "0.1.0" },
1147
+ },
1148
+ 301,
1149
+ ),
1150
+ );
1151
+ const initResp = await loop.nextMessage(8000);
1152
+ assert.equal(initResp.id, 301);
1153
+ assert.equal(initResp.result.serverInfo.name, "vons-local-mcp");
1154
+
1155
+ loop.writeLine(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized", params: {} }));
1156
+
1157
+ const req = {
1158
+ state: "abstain driver — synthetic backend must abstain exact",
1159
+ questions: [
1160
+ { id: "q1", type: "choice", prompt: "insufficient context 1", options: ["A", "B", "C"] },
1161
+ { id: "q2", type: "choice", prompt: "insufficient context 2", options: ["A", "B"] },
1162
+ ],
1163
+ backend: "direct",
1164
+ };
1165
+ loop.writeLine(mcpRequest("tools/call", { name: "vons_decide", arguments: req }, 302));
1166
+ const callResp = await loop.nextMessage(8000);
1167
+ assert.equal(callResp.id, 302);
1168
+ assert.ok(callResp.result?.content && callResp.result.content.length > 0, "abstention content missing");
1169
+ assert.notEqual(callResp.result.isError, true, "abstention is a valid decision response, not isError");
1170
+ const parsed = JSON.parse(callResp.result.content[0].text);
1171
+ assert.equal(!!parsed.error, false, `must not return .error for abstention: ${JSON.stringify(parsed)}`);
1172
+ assert.equal(parsed.answers.length, 2);
1173
+ assert.equal(parsed.answers[0].question_id, "q1");
1174
+ assert.equal(parsed.answers[0].status, "abstain");
1175
+ assert.equal(parsed.answers[0].choice, null);
1176
+ assert.equal(parsed.answers[0].abstain_reason, reasons[0]);
1177
+ assert.deepEqual(parsed.answers[0].probabilities, []);
1178
+ assert.equal(parsed.answers[1].question_id, "q2");
1179
+ assert.equal(parsed.answers[1].status, "abstain");
1180
+ assert.equal(parsed.answers[1].choice, null);
1181
+ assert.equal(parsed.answers[1].abstain_reason, reasons[1]);
1182
+ assert.deepEqual(parsed.answers[1].probabilities, []);
1183
+
1184
+ ac.abort();
1185
+ loop.end();
1186
+ await serverPromise;
1187
+ });
1188
+ });
1189
+
1190
+ describe("TUI findings pass: M2 positional IDs, M3 manifest realpath, M4 docs/diag", () => {
1191
+ test("M4 README provider wording says wasm is supported; webgpu explicitly rejected; no stale 'accepted as metadata' wording; client examples do not include --manifest-sha256", async (t) => {
1192
+ void t;
1193
+ const { readFileSync } = await import("node:fs");
1194
+ const { join } = await import("node:path");
1195
+ const readme = readFileSync(join(process.cwd(), "README.md"), "utf-8");
1196
+ assert.equal(
1197
+ /accepted as metadata/.test(readme),
1198
+ false,
1199
+ "README must not contain stale 'accepted as metadata' wording for --provider webgpu",
1200
+ );
1201
+ assert.ok(
1202
+ /wasm[\s\S]{0,60}supported value/.test(readme) || /wasm must be explicit/.test(readme),
1203
+ "README must describe --provider wasm as the supported value",
1204
+ );
1205
+ assert.ok(
1206
+ /webgpu[\s\S]{0,60}explicitly rejected/.test(readme) || /webgpu[\s\S]{0,60}exit code 4/.test(readme),
1207
+ "README must describe --provider webgpu as explicitly rejected with exit code 4",
1208
+ );
1209
+ assert.equal(
1210
+ /--manifest-sha256\s+[0-9a-f]{64}|manifestSha256:\s*["'][0-9a-f]{64}["']/.test(readme),
1211
+ false,
1212
+ "README client examples never include a full 64-char --manifest-sha256 hash literal",
1213
+ );
1214
+ });
1215
+
1216
+ test("M4 source scan: no unrelated sorts in owned MCP sources; no request/response json echoes in stderr log writes; manifest sha256 banner uses short slice only", async (t) => {
1217
+ void t;
1218
+ const { readFileSync } = await import("node:fs");
1219
+ const { join } = await import("node:path");
1220
+ const mcpSource = readFileSync(join(process.cwd(), "src", "mcp.ts"), "utf-8");
1221
+ const cliSource = readFileSync(join(process.cwd(), "src", "mcp-cli.ts"), "utf-8");
1222
+ const allOwned = mcpSource + "\n" + cliSource;
1223
+
1224
+ assert.equal(
1225
+ /\.(sort|toSorted)\s*\(/.test(allOwned),
1226
+ false,
1227
+ "No unrelated .sort() / .toSorted() calls in MCP-owned sources",
1228
+ );
1229
+ assert.equal(
1230
+ /log\s*\([^)]*JSON\s*\.stringify\s*\(\s*(req|request|res|response)\s*\)/.test(allOwned),
1231
+ false,
1232
+ "No log() calls ever JSON.stringify the request or response object (would leak to stderr)",
1233
+ );
1234
+ assert.ok(
1235
+ /manifest_sha256.*slice\s*\(\s*0\s*,\s*12\s*\)|banner.*slice\s*\(\s*0\s*,\s*12\s*\)|sha256.*slice\s*\(\s*0\s*,\s*12\s*\)/.test(cliSource),
1236
+ "mcp-cli banner uses manifest.sha256.slice(0,12) short digest only, never full",
1237
+ );
1238
+ });
1239
+ });
1240
+
tests/test_ollama_tool_call.py ADDED
@@ -0,0 +1,891 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Synthetic tests for the Ollama native tool-call vertical slice.
2
+
3
+ All tests use injected synthetic backends and canned HTTP responses via
4
+ ``unittest.mock``. No real network calls, no real model weights, no restricted
5
+ Mind2Web rows, no real Ollama daemon is contacted.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import json
11
+ import tempfile
12
+ import unittest
13
+ from collections.abc import Mapping
14
+ from pathlib import Path
15
+ from types import SimpleNamespace
16
+ from typing import Any
17
+ from unittest.mock import MagicMock, patch
18
+
19
+ from vons.contract import (
20
+ Backend,
21
+ DecisionRequest,
22
+ DecisionResponse,
23
+ OptionProbability,
24
+ QuestionAnswer,
25
+ ResponseStatus,
26
+ )
27
+ from vons.ollama import (
28
+ OllamaToolCallError,
29
+ OllamaToolCallHost,
30
+ _validate_loopback_host,
31
+ tool_call_result_to_mapping,
32
+ )
33
+ from vons.onnx_runtime import (
34
+ DecisionBackend,
35
+ OnnxRuntimeBackend,
36
+ OnnxRuntimeError,
37
+ OnnxRuntimeUnavailableError,
38
+ SyntheticAbstainBackend,
39
+ SyntheticChoiceBackend,
40
+ VerifiedBundle,
41
+ _LocalTokenizer,
42
+ )
43
+
44
+
45
+ def _canned_chat_payload(message_body: Mapping[str, Any]) -> Mapping[str, Any]:
46
+ return {"message": message_body, "model": "synthetic", "done": True}
47
+
48
+
49
+ def _vons_decide_tool_call(arguments: Mapping[str, Any]) -> dict[str, Any]:
50
+ return {
51
+ "role": "assistant",
52
+ "content": "",
53
+ "tool_calls": [
54
+ {
55
+ "type": "function",
56
+ "function": {
57
+ "name": "vons_decide",
58
+ "arguments": json.dumps(arguments)
59
+ if isinstance(arguments, dict)
60
+ else arguments,
61
+ },
62
+ }
63
+ ],
64
+ }
65
+
66
+
67
+ def _patch_post(host: OllamaToolCallHost, message_body: Mapping[str, Any]) -> None:
68
+ host._post = MagicMock(return_value=_canned_chat_payload(message_body)) # type: ignore[method-assign]
69
+
70
+
71
+ _VALID_REQUEST = {
72
+ "state": "A weather tool is available. Should we call it?",
73
+ "questions": [
74
+ {
75
+ "id": "q-next",
76
+ "type": "choice",
77
+ "prompt": "Next action?",
78
+ "options": ["call", "clarify", "confirm", "refuse"],
79
+ }
80
+ ],
81
+ "backend": "direct",
82
+ "seed": 7,
83
+ }
84
+
85
+
86
+ class _SpyBackend(DecisionBackend):
87
+ """Test backend that records whether it was called and with what."""
88
+
89
+ backend_type = Backend.DIRECT
90
+
91
+ def __init__(
92
+ self, response: DecisionResponse | None = None, *, raise_on_call: Exception | None = None
93
+ ) -> None:
94
+ self.calls: list[DecisionRequest] = []
95
+ self._response = response
96
+ self._raise = raise_on_call
97
+
98
+ def decide(self, request: DecisionRequest) -> DecisionResponse:
99
+ self._validate_request(request)
100
+ self.calls.append(request)
101
+ if self._raise is not None:
102
+ raise self._raise
103
+ if self._response is not None:
104
+ return self._response
105
+ return SyntheticChoiceBackend(choice_index=0).decide(request)
106
+
107
+
108
+ class LoopbackValidationTests(unittest.TestCase):
109
+ def test_accepts_localhost_variants(self) -> None:
110
+ for url in (
111
+ "http://127.0.0.1:11434",
112
+ "http://localhost:11434/api",
113
+ "http://[::1]:11434/chat",
114
+ ):
115
+ _validate_loopback_host(url) # must not raise
116
+
117
+ def test_rejects_non_loopback(self) -> None:
118
+ for url in (
119
+ "http://example.com:11434",
120
+ "https://192.168.1.1/api/chat",
121
+ "http://0.0.0.0:11434",
122
+ "http://[2001:db8::1]:11434",
123
+ "ftp://127.0.0.1:11434",
124
+ ):
125
+ with self.assertRaises(OllamaToolCallError):
126
+ _validate_loopback_host(url)
127
+
128
+ def test_empty_or_invalid_urls(self) -> None:
129
+ for url in ("", "not-a-url", "127.0.0.1"):
130
+ with self.assertRaises(OllamaToolCallError):
131
+ _validate_loopback_host(url) # type: ignore[arg-type]
132
+
133
+
134
+ class HostInitTests(unittest.TestCase):
135
+ def test_requires_loopback_host(self) -> None:
136
+ backend = SyntheticAbstainBackend()
137
+ with self.assertRaises(OllamaToolCallError):
138
+ OllamaToolCallHost("http://example.com:11434", backend)
139
+
140
+ def test_requires_decision_backend_instance(self) -> None:
141
+ with self.assertRaises(OllamaToolCallError):
142
+ OllamaToolCallHost("http://127.0.0.1:11434", "not a backend") # type: ignore[arg-type]
143
+
144
+ def test_valid_init(self) -> None:
145
+ backend = SyntheticAbstainBackend()
146
+ host = OllamaToolCallHost("http://127.0.0.1:11434/", backend)
147
+ self.assertEqual(host.host, "http://127.0.0.1:11434")
148
+ self.assertIs(host.backend, backend)
149
+
150
+
151
+ class ToolCallRoundTripTests(unittest.TestCase):
152
+ def test_successful_tool_call_invokes_backend(self) -> None:
153
+ backend = _SpyBackend()
154
+ host = OllamaToolCallHost("http://127.0.0.1:11434", backend)
155
+ _patch_post(host, _vons_decide_tool_call(_VALID_REQUEST))
156
+ messages = [{"role": "user", "content": "pick one"}]
157
+
158
+ result = host.chat_with_tools("synthetic-model", messages)
159
+
160
+ self.assertIsNone(result.error)
161
+ self.assertIsNone(result.error_id)
162
+ self.assertTrue(result.tool_invoked)
163
+ self.assertIsNotNone(result.backend_result)
164
+ self.assertEqual(len(backend.calls), 1)
165
+ request = backend.calls[0]
166
+ self.assertEqual(len(request.questions), 1)
167
+ self.assertEqual(request.questions[0].id, "q-next")
168
+ self.assertEqual(request.backend, Backend.DIRECT)
169
+ self.assertEqual(request.seed, 7)
170
+ # Reconciliation: backend answer IDs match request IDs exactly, positionally
171
+ self.assertEqual(result.backend_result.answers[0].question_id, "q-next")
172
+
173
+ def test_accepts_observed_ollama_tool_call_shape(self) -> None:
174
+ backend = _SpyBackend()
175
+ host = OllamaToolCallHost("http://127.0.0.1:11434", backend)
176
+ observed_message = {
177
+ "role": "assistant",
178
+ "content": "",
179
+ "thinking": "synthetic reasoning metadata",
180
+ "tool_calls": [
181
+ {
182
+ "id": "call_synthetic",
183
+ "function": {
184
+ "index": 0,
185
+ "name": "vons_decide",
186
+ "arguments": _VALID_REQUEST,
187
+ },
188
+ }
189
+ ],
190
+ }
191
+ _patch_post(host, observed_message)
192
+
193
+ result = host.chat_with_tools("synthetic-model", [{"role": "user", "content": "x"}])
194
+
195
+ self.assertIsNone(result.error)
196
+ self.assertTrue(result.tool_invoked)
197
+ self.assertEqual(len(backend.calls), 1)
198
+
199
+ def test_invalid_ollama_function_index_blocks_backend_call(self) -> None:
200
+ backend = _SpyBackend()
201
+ host = OllamaToolCallHost("http://127.0.0.1:11434", backend)
202
+ observed_message = {
203
+ "role": "assistant",
204
+ "content": "",
205
+ "tool_calls": [
206
+ {
207
+ "id": "call_synthetic",
208
+ "function": {
209
+ "index": -1,
210
+ "name": "vons_decide",
211
+ "arguments": _VALID_REQUEST,
212
+ },
213
+ }
214
+ ],
215
+ }
216
+ _patch_post(host, observed_message)
217
+
218
+ result = host.chat_with_tools("synthetic-model", [{"role": "user", "content": "x"}])
219
+
220
+ self.assertIsNotNone(result.error)
221
+ self.assertEqual(len(backend.calls), 0)
222
+
223
+ def test_raw_and_validated_separate(self) -> None:
224
+ backend = _SpyBackend()
225
+ host = OllamaToolCallHost("http://127.0.0.1:11434", backend)
226
+ _patch_post(host, _vons_decide_tool_call(_VALID_REQUEST))
227
+
228
+ result = host.chat_with_tools("synthetic-model", [{"role": "user", "content": "x"}])
229
+
230
+ # Raw Ollama response is preserved as-is (contains the exact tool_call shape)
231
+ self.assertIsNotNone(result.raw_ollama_response)
232
+ raw_message = (
233
+ result.raw_ollama_response.get("message", {})
234
+ if isinstance(result.raw_ollama_response, dict)
235
+ else {}
236
+ )
237
+ self.assertEqual(len(raw_message.get("tool_calls", [])), 1)
238
+ # Validated backend result is a separate, typed DecisionResponse
239
+ self.assertIsNotNone(result.backend_result)
240
+ self.assertIsInstance(result.backend_result, DecisionResponse)
241
+ self.assertIsNot(result.raw_ollama_response, result.backend_result)
242
+
243
+ def test_model_text_reply_without_tool_call_is_not_an_error(self) -> None:
244
+ backend = _SpyBackend()
245
+ host = OllamaToolCallHost("http://127.0.0.1:11434", backend)
246
+ _patch_post(host, {"role": "assistant", "content": "I think you should call."})
247
+
248
+ result = host.chat_with_tools("synthetic-model", [{"role": "user", "content": "x"}])
249
+
250
+ self.assertFalse(result.tool_invoked)
251
+ self.assertIsNone(result.backend_result)
252
+ self.assertIsNone(result.error)
253
+ self.assertEqual(len(backend.calls), 0)
254
+
255
+ def test_wrong_tool_name_blocks_backend_call(self) -> None:
256
+ backend = _SpyBackend()
257
+ host = OllamaToolCallHost("http://127.0.0.1:11434", backend)
258
+ wrong_tool = {
259
+ "role": "assistant",
260
+ "content": "",
261
+ "tool_calls": [
262
+ {
263
+ "type": "function",
264
+ "function": {
265
+ "name": "delete_everything",
266
+ "arguments": json.dumps({"scope": "all"}),
267
+ },
268
+ }
269
+ ],
270
+ }
271
+ _patch_post(host, wrong_tool)
272
+
273
+ result = host.chat_with_tools("synthetic-model", [{"role": "user", "content": "x"}])
274
+
275
+ self.assertTrue(result.tool_invoked) # model tried to invoke a tool
276
+ self.assertIsNotNone(result.error)
277
+ self.assertIsNone(result.backend_result)
278
+ self.assertEqual(len(backend.calls), 0) # backend never called
279
+
280
+ def test_malformed_arguments_blocks_backend_call(self) -> None:
281
+ backend = _SpyBackend()
282
+ host = OllamaToolCallHost("http://127.0.0.1:11434", backend)
283
+ missing_required = {"state": "", "questions": []} # empty + no questions
284
+ _patch_post(host, _vons_decide_tool_call(missing_required))
285
+
286
+ result = host.chat_with_tools("synthetic-model", [{"role": "user", "content": "x"}])
287
+
288
+ self.assertTrue(result.tool_invoked)
289
+ self.assertIsNotNone(result.error)
290
+ self.assertIsNone(result.backend_result)
291
+ self.assertEqual(len(backend.calls), 0)
292
+
293
+ def test_unknown_root_argument_blocks_backend_call(self) -> None:
294
+ backend = _SpyBackend()
295
+ host = OllamaToolCallHost("http://127.0.0.1:11434", backend)
296
+ arguments = {**_VALID_REQUEST, "_authorization": "approve"}
297
+ _patch_post(host, _vons_decide_tool_call(arguments))
298
+
299
+ result = host.chat_with_tools("synthetic-model", [{"role": "user", "content": "x"}])
300
+
301
+ self.assertIsNotNone(result.error)
302
+ self.assertEqual(len(backend.calls), 0)
303
+
304
+ def test_unknown_question_argument_blocks_backend_call(self) -> None:
305
+ backend = _SpyBackend()
306
+ host = OllamaToolCallHost("http://127.0.0.1:11434", backend)
307
+ question = {**_VALID_REQUEST["questions"][0], "execute": True}
308
+ arguments = {**_VALID_REQUEST, "questions": [question]}
309
+ _patch_post(host, _vons_decide_tool_call(arguments))
310
+
311
+ result = host.chat_with_tools("synthetic-model", [{"role": "user", "content": "x"}])
312
+
313
+ self.assertIsNotNone(result.error)
314
+ self.assertEqual(len(backend.calls), 0)
315
+
316
+ def test_oversized_tool_arguments_block_backend_call(self) -> None:
317
+ backend = _SpyBackend()
318
+ host = OllamaToolCallHost("http://127.0.0.1:11434", backend)
319
+ arguments = {**_VALID_REQUEST, "state": "x" * 70_000}
320
+ _patch_post(host, _vons_decide_tool_call(arguments))
321
+
322
+ result = host.chat_with_tools("synthetic-model", [{"role": "user", "content": "x"}])
323
+
324
+ self.assertIsNotNone(result.error)
325
+ self.assertEqual(len(backend.calls), 0)
326
+
327
+ def test_invalid_message_shape_is_rejected_before_post(self) -> None:
328
+ backend = _SpyBackend()
329
+ host = OllamaToolCallHost("http://127.0.0.1:11434", backend)
330
+ host._post = MagicMock(side_effect=AssertionError("network must not be reached")) # type: ignore[method-assign]
331
+
332
+ result = host.chat_with_tools("synthetic-model", [{"role": ["user"], "content": "x"}])
333
+
334
+ self.assertIsNotNone(result.error)
335
+ host._post.assert_not_called()
336
+
337
+ def test_duplicate_question_ids_block_backend(self) -> None:
338
+ backend = _SpyBackend()
339
+ host = OllamaToolCallHost("http://127.0.0.1:11434", backend)
340
+ dup_request = {
341
+ "state": "state",
342
+ "questions": [
343
+ {"id": "same", "type": "choice", "prompt": "first", "options": ["a", "b"]},
344
+ {"id": "same", "type": "choice", "prompt": "second", "options": ["c", "d"]},
345
+ ],
346
+ }
347
+ _patch_post(host, _vons_decide_tool_call(dup_request))
348
+
349
+ result = host.chat_with_tools("synthetic-model", [{"role": "user", "content": "x"}])
350
+
351
+ self.assertTrue(result.tool_invoked)
352
+ self.assertIsNotNone(result.error)
353
+ self.assertIsNone(result.backend_result)
354
+ self.assertEqual(len(backend.calls), 0)
355
+
356
+ def test_backend_returning_mismatched_ids_is_rejected(self) -> None:
357
+ """The backend must return answers whose IDs match the request order exactly.
358
+
359
+ This guards against a compromised or buggy backend reordering or dropping
360
+ answers so a client cannot silently misattribute choices to questions.
361
+ """
362
+ # Build a response with the WRONG question_id
363
+ bad_answer = QuestionAnswer(
364
+ question_id="q-SURPRISE",
365
+ choice="call",
366
+ probabilities=(OptionProbability(option="call", probability=1.0),),
367
+ confidence=1.0,
368
+ status=ResponseStatus.OK,
369
+ )
370
+ bad_response = DecisionResponse(
371
+ answers=(bad_answer,),
372
+ backend=Backend.DIRECT,
373
+ model_id="buggy-backend",
374
+ )
375
+ backend = _SpyBackend(response=bad_response)
376
+ host = OllamaToolCallHost("http://127.0.0.1:11434", backend)
377
+ _patch_post(host, _vons_decide_tool_call(_VALID_REQUEST))
378
+
379
+ result = host.chat_with_tools("synthetic-model", [{"role": "user", "content": "x"}])
380
+
381
+ self.assertTrue(result.tool_invoked)
382
+ self.assertIsNotNone(result.error)
383
+ self.assertIsNone(result.backend_result)
384
+ self.assertEqual(len(backend.calls), 1) # backend DID run, but its output rejected
385
+
386
+ def test_backend_raising_is_sanitized(self) -> None:
387
+ backend = _SpyBackend(raise_on_call=RuntimeError("weights corrupted, DB password leaked"))
388
+ host = OllamaToolCallHost("http://127.0.0.1:11434", backend)
389
+ _patch_post(host, _vons_decide_tool_call(_VALID_REQUEST))
390
+
391
+ result = host.chat_with_tools("synthetic-model", [{"role": "user", "content": "x"}])
392
+
393
+ self.assertTrue(result.tool_invoked)
394
+ self.assertIsNotNone(result.error)
395
+ self.assertIsNone(result.backend_result)
396
+ # Sanitized error must NOT contain the leaked exception text
397
+ error_str = str(result.error) + " " + json.dumps(result.error.sanitized())
398
+ self.assertNotIn("DB password", error_str)
399
+ self.assertNotIn("weights corrupted", error_str)
400
+
401
+ def test_empty_messages_list_is_error(self) -> None:
402
+ backend = _SpyBackend()
403
+ host = OllamaToolCallHost("http://127.0.0.1:11434", backend)
404
+ host._post = MagicMock(side_effect=AssertionError("network must not be reached")) # type: ignore[method-assign]
405
+
406
+ result = host.chat_with_tools("synthetic-model", [])
407
+
408
+ self.assertIsNotNone(result.error)
409
+ self.assertFalse(result.tool_invoked)
410
+ host._post.assert_not_called()
411
+
412
+ def test_invalid_model_arg(self) -> None:
413
+ backend = _SpyBackend()
414
+ host = OllamaToolCallHost("http://127.0.0.1:11434", backend)
415
+ result = host.chat_with_tools("", [{"role": "user", "content": "x"}])
416
+ self.assertIsNotNone(result.error)
417
+ self.assertEqual(result.model, "")
418
+
419
+ def test_result_mapping_preserves_raw_separate_from_validated(self) -> None:
420
+ backend = SyntheticChoiceBackend(choice_index=0)
421
+ host = OllamaToolCallHost("http://127.0.0.1:11434", backend)
422
+ _patch_post(host, _vons_decide_tool_call(_VALID_REQUEST))
423
+
424
+ result = host.chat_with_tools("synthetic-model", [{"role": "user", "content": "x"}])
425
+ mapped = tool_call_result_to_mapping(result)
426
+
427
+ self.assertEqual(mapped["model"], "synthetic-model")
428
+ self.assertTrue(mapped["tool_invoked"])
429
+ self.assertIsNone(mapped["error"])
430
+ backend_result = mapped["backend_result"]
431
+ self.assertIsInstance(backend_result, dict)
432
+ self.assertEqual(backend_result["answers"][0]["question_id"], "q-next")
433
+ self.assertEqual(mapped["raw_ollama_response"], result.raw_ollama_response)
434
+ self.assertIsNot(mapped["raw_ollama_response"], mapped["backend_result"])
435
+
436
+ def test_response_with_empty_ok_probabilities_is_rejected(self) -> None:
437
+ answer = QuestionAnswer(
438
+ question_id="q-next",
439
+ choice="call",
440
+ probabilities=(),
441
+ confidence=0.8,
442
+ status=ResponseStatus.OK,
443
+ )
444
+ backend = _SpyBackend(
445
+ response=DecisionResponse(
446
+ answers=(answer,), backend=Backend.DIRECT, model_id="synthetic"
447
+ )
448
+ )
449
+ host = OllamaToolCallHost("http://127.0.0.1:11434", backend)
450
+ _patch_post(host, _vons_decide_tool_call(_VALID_REQUEST))
451
+
452
+ result = host.chat_with_tools("synthetic-model", [{"role": "user", "content": "x"}])
453
+
454
+ self.assertIsNotNone(result.error)
455
+ self.assertIsNone(result.backend_result)
456
+
457
+ def test_response_with_non_json_metadata_is_rejected(self) -> None:
458
+ response = SyntheticChoiceBackend().decide(DecisionRequest.from_mapping(_VALID_REQUEST))
459
+ object.__setattr__(response, "metadata", {"unsafe": object()})
460
+ backend = _SpyBackend(response=response)
461
+ host = OllamaToolCallHost("http://127.0.0.1:11434", backend)
462
+ _patch_post(host, _vons_decide_tool_call(_VALID_REQUEST))
463
+
464
+ result = host.chat_with_tools("synthetic-model", [{"role": "user", "content": "x"}])
465
+
466
+ self.assertIsNotNone(result.error)
467
+ self.assertIsNone(result.backend_result)
468
+
469
+ def test_abstain_backend_preserves_reason_through_host(self) -> None:
470
+ EXACT_REASON = "synthetic backend requested abstention"
471
+ backend = SyntheticAbstainBackend(abstain_reason=EXACT_REASON)
472
+ host = OllamaToolCallHost("http://127.0.0.1:11434", backend)
473
+ _patch_post(host, _vons_decide_tool_call(_VALID_REQUEST))
474
+
475
+ result = host.chat_with_tools("synthetic-model", [{"role": "user", "content": "x"}])
476
+
477
+ self.assertIsNone(result.error)
478
+ self.assertIsNotNone(result.backend_result)
479
+ answer = result.backend_result.answers[0]
480
+ self.assertEqual(answer.status, ResponseStatus.ABSTAIN)
481
+ self.assertIsNone(answer.choice)
482
+ self.assertEqual(answer.abstain_reason, EXACT_REASON)
483
+
484
+ def test_multiple_tool_calls_rejected(self) -> None:
485
+ backend = _SpyBackend()
486
+ host = OllamaToolCallHost("http://127.0.0.1:11434", backend)
487
+ double = {
488
+ "role": "assistant",
489
+ "content": "",
490
+ "tool_calls": [
491
+ {
492
+ "type": "function",
493
+ "function": {"name": "vons_decide", "arguments": json.dumps(_VALID_REQUEST)},
494
+ },
495
+ {
496
+ "type": "function",
497
+ "function": {"name": "vons_decide", "arguments": json.dumps(_VALID_REQUEST)},
498
+ },
499
+ ],
500
+ }
501
+ _patch_post(host, double)
502
+
503
+ result = host.chat_with_tools("synthetic-model", [{"role": "user", "content": "x"}])
504
+
505
+ self.assertTrue(result.tool_invoked)
506
+ self.assertIsNotNone(result.error)
507
+ self.assertIsNone(result.backend_result)
508
+ self.assertEqual(len(backend.calls), 0)
509
+
510
+
511
+ class RedirectEscapeTests(unittest.TestCase):
512
+ def test_host_validates_url_before_each_http_call(self) -> None:
513
+ backend = SyntheticAbstainBackend()
514
+ host = OllamaToolCallHost("http://127.0.0.1:11434", backend)
515
+ # Simulate opener.open raising an error - we already know the host
516
+ # validates host on the way in via constructor. Now confirm the
517
+ # per-call _post path also re-validates by replacing host.host with
518
+ # a remote host and calling _post directly.
519
+ original_host = host.host
520
+ try:
521
+ host.host = "http://evil.example.com:11434" # type: ignore[misc]
522
+ with self.assertRaises(OllamaToolCallError):
523
+ host._post("/api/chat", {"model": "x"})
524
+ finally:
525
+ host.host = original_host
526
+
527
+ def test_non_loopback_redirect_is_blocked_by_handler(self) -> None:
528
+ """`_LoopbackRedirectHandler` rejects redirects leaving loopback.
529
+
530
+ We do not actually execute the redirect handler through an HTTP server
531
+ in synthetic fixtures; we confirm the handler class exists and the
532
+ helper `_validate_loopback_host` rejects a redirect-style URL that
533
+ would point away from loopback.
534
+ """
535
+ from vons.ollama import _LoopbackRedirectHandler
536
+
537
+ self.assertTrue(callable(_LoopbackRedirectHandler.redirect_request))
538
+ with self.assertRaises(OllamaToolCallError):
539
+ _validate_loopback_host("http://10.0.0.5:11434/redirected")
540
+ with self.assertRaises(OllamaToolCallError):
541
+ _validate_loopback_host("https://remote.internal:8443/api/chat")
542
+
543
+
544
+ class SyntheticBackendContractTests(unittest.TestCase):
545
+ def test_synthetic_abstain_requires_reason(self) -> None:
546
+ backend = SyntheticAbstainBackend("my reason")
547
+ request = DecisionRequest.from_mapping(_VALID_REQUEST)
548
+ response = backend.decide(request)
549
+ for answer in response.answers:
550
+ self.assertEqual(answer.abstain_reason, "my reason")
551
+ self.assertIsNone(answer.choice)
552
+
553
+ def test_synthetic_choice_preserves_position(self) -> None:
554
+ backend = SyntheticChoiceBackend(choice_index=1)
555
+ request = DecisionRequest.from_mapping(_VALID_REQUEST)
556
+ response = backend.decide(request)
557
+ self.assertEqual(response.answers[0].choice, "clarify") # index 1
558
+ probs = {p.option: p.probability for p in response.answers[0].probabilities}
559
+ self.assertAlmostEqual(sum(probs.values()), 1.0, places=5)
560
+
561
+ def test_synthetic_choice_out_of_range_is_error(self) -> None:
562
+ backend = SyntheticChoiceBackend(choice_index=99)
563
+ request = DecisionRequest.from_mapping(_VALID_REQUEST)
564
+ with self.assertRaises(OnnxRuntimeError):
565
+ backend.decide(request)
566
+
567
+
568
+ class _FakeEncoding:
569
+ def __init__(self, ids: list[int]) -> None:
570
+ self.ids = ids
571
+ self.attention_mask = [1] * len(ids)
572
+ self.token_type_ids = [0] * len(ids)
573
+
574
+
575
+ class _FakeTokenizer:
576
+ pad_token_id = 0
577
+ cls_token_id = 1
578
+
579
+ def encode(self, text: str, **_kwargs: Any) -> _FakeEncoding:
580
+ return _FakeEncoding([1, *range(3, 3 + len(text.split())), 2])
581
+
582
+
583
+ class _FakeOnnxSession:
584
+ def __init__(self, backend: Backend, *, bad_shape: bool = False) -> None:
585
+ self.backend = backend
586
+ self.bad_shape = bad_shape
587
+ self.feeds: list[dict[str, Any]] = []
588
+ self.input_names = ["input_ids", "attention_mask", "token_type_ids", "option_mask"]
589
+ if backend is Backend.DIFFUSION:
590
+ self.input_names.append("initial_noise")
591
+ self.output_names = [
592
+ "logits" if backend is Backend.DIRECT else "scores",
593
+ "answerability",
594
+ ]
595
+
596
+ def get_inputs(self) -> list[SimpleNamespace]:
597
+ return [SimpleNamespace(name=name) for name in self.input_names]
598
+
599
+ def get_outputs(self) -> list[SimpleNamespace]:
600
+ return [SimpleNamespace(name=name) for name in self.output_names]
601
+
602
+ def run(self, output_names: list[str], feed: dict[str, Any]) -> list[Any]:
603
+ import numpy as np
604
+
605
+ self.feeds.append({key: np.array(value, copy=True) for key, value in feed.items()})
606
+ slots = feed["option_mask"].shape[1]
607
+ width = slots + 1 if self.bad_shape else slots
608
+ scores = np.linspace(2.0, -2.0, width, dtype=np.float32)[None, :]
609
+ values = {
610
+ self.output_names[0]: scores,
611
+ "answerability": np.array([8.0], dtype=np.float32),
612
+ }
613
+ return [values[name] for name in output_names]
614
+
615
+
616
+ def _runtime_backend(
617
+ backend_type: Backend, *, bad_shape: bool = False
618
+ ) -> tuple[OnnxRuntimeBackend, _FakeOnnxSession]:
619
+ inputs = ["input_ids", "attention_mask", "token_type_ids", "option_mask"]
620
+ if backend_type is Backend.DIFFUSION:
621
+ inputs.append("initial_noise")
622
+ outputs = ["logits" if backend_type is Backend.DIRECT else "scores", "answerability"]
623
+ manifest = {
624
+ "metadata": {
625
+ "backend": backend_type.value,
626
+ "option_count": 4,
627
+ "sequence_length": 64,
628
+ "input_names": inputs,
629
+ "output_names": outputs,
630
+ "diffusion_conditioning": "token_cross_attention",
631
+ },
632
+ "files": [],
633
+ }
634
+ bundle = VerifiedBundle(
635
+ root=Path("."),
636
+ manifest_path=Path("bundle-manifest-v1.json"),
637
+ manifest=manifest,
638
+ model_id="a" * 64,
639
+ )
640
+ session = _FakeOnnxSession(backend_type, bad_shape=bad_shape)
641
+ return (
642
+ OnnxRuntimeBackend(bundle, tokenizer=_FakeTokenizer(), session=session),
643
+ session,
644
+ )
645
+
646
+
647
+ class OnnxRuntimeExecutionTests(unittest.TestCase):
648
+ def test_local_tokenizer_adapter_exposes_token_ids_for_budget_check(self) -> None:
649
+ class RawTokenizer:
650
+ max_length: int | None = None
651
+
652
+ def enable_truncation(self, *, max_length: int) -> None:
653
+ self.max_length = max_length
654
+
655
+ def no_truncation(self) -> None:
656
+ self.max_length = None
657
+
658
+ def encode(self, text: str, *, add_special_tokens: bool) -> SimpleNamespace:
659
+ ids = [1, *range(2, 2 + len(text.split())), 3]
660
+ return SimpleNamespace(
661
+ ids=ids, attention_mask=[1] * len(ids), type_ids=[0] * len(ids)
662
+ )
663
+
664
+ tokenizer = _LocalTokenizer(RawTokenizer(), pad_token_id=0, cls_token_id=1)
665
+
666
+ encoded = tokenizer.encode("one two three", max_length=32)
667
+
668
+ self.assertGreater(len(encoded.ids), 3)
669
+ self.assertEqual(len(encoded.ids), len(encoded.attention_mask))
670
+ self.assertIsNone(tokenizer._tokenizer.max_length)
671
+
672
+ def test_executes_direct_session_and_returns_validated_choice(self) -> None:
673
+ backend, session = _runtime_backend(Backend.DIRECT)
674
+ request = DecisionRequest.from_mapping(_VALID_REQUEST)
675
+
676
+ result = backend.decide(request)
677
+
678
+ self.assertEqual(result.backend, Backend.DIRECT)
679
+ self.assertEqual(result.answers[0].question_id, "q-next")
680
+ self.assertEqual(result.answers[0].choice, "call")
681
+ self.assertEqual(session.feeds[0]["input_ids"].shape[:2], (1, 4))
682
+ self.assertNotIn("initial_noise", session.feeds[0])
683
+
684
+ def test_executes_diffusion_session_with_seeded_noise(self) -> None:
685
+ backend, session = _runtime_backend(Backend.DIFFUSION)
686
+ request = DecisionRequest.from_mapping({**_VALID_REQUEST, "backend": "diffusion"})
687
+
688
+ first = backend.decide(request)
689
+ second = backend.decide(request)
690
+
691
+ import numpy as np
692
+
693
+ self.assertEqual(first.answers[0].choice, "call")
694
+ self.assertEqual(second.answers[0].choice, "call")
695
+ self.assertEqual(session.feeds[0]["initial_noise"].shape, (1, 4))
696
+ np.testing.assert_array_equal(
697
+ session.feeds[0]["initial_noise"], session.feeds[1]["initial_noise"]
698
+ )
699
+
700
+ def test_injected_session_must_match_bundle_contract(self) -> None:
701
+ backend, session = _runtime_backend(Backend.DIRECT)
702
+ session.input_names.remove("option_mask")
703
+
704
+ with self.assertRaises(OnnxRuntimeError):
705
+ backend.decide(DecisionRequest.from_mapping(_VALID_REQUEST))
706
+
707
+ def test_invalid_onnx_score_shape_fails_closed(self) -> None:
708
+ backend, _session = _runtime_backend(Backend.DIRECT, bad_shape=True)
709
+
710
+ with self.assertRaisesRegex(OnnxRuntimeError, "invalid score dimensions"):
711
+ backend.decide(DecisionRequest.from_mapping(_VALID_REQUEST))
712
+
713
+
714
+ class BundleLoadTests(unittest.TestCase):
715
+ def test_missing_directory_is_error(self) -> None:
716
+ with tempfile.TemporaryDirectory() as td:
717
+ missing = Path(td) / "nope"
718
+ with self.assertRaises(OnnxRuntimeError):
719
+ VerifiedBundle.load(missing)
720
+
721
+ def test_directory_without_manifest_is_error(self) -> None:
722
+ with tempfile.TemporaryDirectory() as td, self.assertRaises(OnnxRuntimeError):
723
+ VerifiedBundle.load(td)
724
+
725
+ def test_directory_with_manifest_missing_graph_fails_verification(self) -> None:
726
+ with tempfile.TemporaryDirectory() as td:
727
+ root = Path(td)
728
+ # A manifest with a bogus file inventory will fail verify_bundle_manifest
729
+ bad_manifest = {
730
+ "schema_version": "vons.bundle.manifest/v1",
731
+ "manifest": {"path": "bundle-manifest.json"},
732
+ "files": [
733
+ {"path": "nope.onnx", "role": "model_graph", "bytes": 1, "sha256": "0" * 64}
734
+ ],
735
+ "summary": {
736
+ "model_asset_bytes": 1,
737
+ "manifest_bytes": 0,
738
+ "complete_download_bytes": 0,
739
+ "within_model_asset_limit": True,
740
+ "runtime_loaded_file_count": 0,
741
+ },
742
+ }
743
+ (root / "bundle-manifest.json").write_text(json.dumps(bad_manifest), encoding="utf-8")
744
+ with self.assertRaises(OnnxRuntimeError):
745
+ VerifiedBundle.load(root)
746
+
747
+
748
+ class SanitizedErrorTests(unittest.TestCase):
749
+ def test_error_id_is_12_hex_chars(self) -> None:
750
+ err = OllamaToolCallError()
751
+ self.assertRegex(err.error_id, r"^[0-9a-f]{12}$")
752
+ self.assertEqual(len(err.error_id), 12)
753
+
754
+ def test_two_errors_have_different_ids(self) -> None:
755
+ a = OllamaToolCallError()
756
+ b = OllamaToolCallError()
757
+ self.assertNotEqual(a.error_id, b.error_id)
758
+
759
+ def test_sanitized_payload_omits_cause_text(self) -> None:
760
+ err = OllamaToolCallError()
761
+ san = err.sanitized()
762
+ self.assertEqual(san["error"], "ollama_tool_call_failed")
763
+ self.assertIn("error_id", san)
764
+ self.assertEqual(len(san), 2)
765
+
766
+
767
+ class CLISmokeTests(unittest.TestCase):
768
+ def test_cli_parser_accepts_ollama_tool_call_command(self) -> None:
769
+ from vons.cli import _parser
770
+
771
+ parser = _parser()
772
+ args = parser.parse_args(
773
+ [
774
+ "ollama-tool-call",
775
+ "--model",
776
+ "qwen3.8:27b-mlx",
777
+ "--synthetic",
778
+ "abstain",
779
+ "--input",
780
+ "ignored.json",
781
+ ]
782
+ )
783
+ self.assertEqual(args.command, "ollama-tool-call")
784
+ self.assertEqual(args.model, "qwen3.8:27b-mlx")
785
+ self.assertEqual(args.synthetic, "abstain")
786
+
787
+ def test_cli_requires_backend_flag(self) -> None:
788
+ from vons.cli import main as cli_main
789
+
790
+ with tempfile.TemporaryDirectory() as td:
791
+ input_path = Path(td) / "in.json"
792
+ input_path.write_text(json.dumps({"messages": []}), encoding="utf-8")
793
+ rc = cli_main(["ollama-tool-call", "--model", "qwen", "--input", str(input_path)])
794
+ # Exit code 2 means neither --bundle nor --synthetic supplied
795
+ self.assertEqual(rc, 2)
796
+
797
+ def test_cli_missing_messages_is_error(self) -> None:
798
+ from vons.cli import main as cli_main
799
+
800
+ with tempfile.TemporaryDirectory() as td:
801
+ input_path = Path(td) / "in.json"
802
+ input_path.write_text("{}", encoding="utf-8")
803
+ rc = cli_main(
804
+ [
805
+ "ollama-tool-call",
806
+ "--model",
807
+ "qwen",
808
+ "--synthetic",
809
+ "abstain",
810
+ "--input",
811
+ str(input_path),
812
+ ]
813
+ )
814
+ self.assertEqual(rc, 3)
815
+
816
+ def test_tool_call_input_reader_enforces_byte_limit(self) -> None:
817
+ from vons.cli import _MAX_TOOL_CALL_INPUT_BYTES, _read_tool_call_input
818
+
819
+ with tempfile.TemporaryDirectory() as td:
820
+ path = Path(td) / "oversized.json"
821
+ path.write_bytes(b" " * (_MAX_TOOL_CALL_INPUT_BYTES + 1))
822
+
823
+ with self.assertRaisesRegex(ValueError, "size limit"):
824
+ _read_tool_call_input(path)
825
+
826
+ def test_tool_call_input_reader_rejects_unknown_root_keys(self) -> None:
827
+ from vons.cli import _read_tool_call_input
828
+
829
+ with tempfile.TemporaryDirectory() as td:
830
+ path = Path(td) / "input.json"
831
+ path.write_text('{"messages": [], "extra": true}', encoding="utf-8")
832
+
833
+ with self.assertRaises(TypeError):
834
+ _read_tool_call_input(path)
835
+
836
+ def test_cli_runtime_dependency_preflight_happens_before_host(self) -> None:
837
+ from vons.cli import main as cli_main
838
+
839
+ with tempfile.TemporaryDirectory() as td:
840
+ input_path = Path(td) / "input.json"
841
+ input_path.write_text(
842
+ json.dumps({"messages": [{"role": "user", "content": "synthetic"}]}),
843
+ encoding="utf-8",
844
+ )
845
+ bundle = VerifiedBundle(
846
+ root=Path(td),
847
+ manifest_path=Path(td) / "bundle-manifest-v1.json",
848
+ manifest={
849
+ "metadata": {
850
+ "backend": "direct",
851
+ "option_count": 4,
852
+ "sequence_length": 64,
853
+ "input_names": [
854
+ "input_ids",
855
+ "attention_mask",
856
+ "token_type_ids",
857
+ "option_mask",
858
+ ],
859
+ "output_names": ["logits", "answerability"],
860
+ },
861
+ "files": [],
862
+ },
863
+ model_id="a" * 64,
864
+ )
865
+ with (
866
+ patch("vons.cli.VerifiedBundle.load", return_value=bundle),
867
+ patch.object(
868
+ OnnxRuntimeBackend,
869
+ "prepare",
870
+ side_effect=OnnxRuntimeUnavailableError("missing synthetic dependency"),
871
+ ),
872
+ patch("vons.cli.OllamaToolCallHost") as host_factory,
873
+ ):
874
+ rc = cli_main(
875
+ [
876
+ "ollama-tool-call",
877
+ "--model",
878
+ "synthetic",
879
+ "--bundle",
880
+ td,
881
+ "--input",
882
+ str(input_path),
883
+ ]
884
+ )
885
+
886
+ self.assertEqual(rc, 16)
887
+ host_factory.assert_not_called()
888
+
889
+
890
+ if __name__ == "__main__":
891
+ unittest.main()
tools/verify_onnx_bundle.py CHANGED
@@ -1,4 +1,4 @@
1
- """Compare an exported Direct bundle with its PyTorch checkpoint on fixed inputs."""
2
 
3
  from __future__ import annotations
4
 
@@ -11,7 +11,25 @@ import onnxruntime as ort
11
  import torch
12
  from transformers import AutoModel, AutoTokenizer
13
 
14
- from vons.models import ModelConfig, build_model
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
15
 
16
 
17
  def verify(checkpoint_path: Path, bundle_path: Path, *, max_length: int = 32) -> dict[str, object]:
@@ -22,14 +40,11 @@ def verify(checkpoint_path: Path, bundle_path: Path, *, max_length: int = 32) ->
22
  tokenizer = AutoTokenizer.from_pretrained(encoder_config["name"], revision=encoder_config.get("revision"))
23
  encoder = AutoModel.from_pretrained(encoder_config["name"], revision=encoder_config.get("revision")).eval()
24
  backend = checkpoint["backend"]
 
25
  head = build_model(
26
  backend,
27
  option_count=checkpoint["option_count"],
28
- config=ModelConfig(
29
- hidden_size=checkpoint["hidden_size"],
30
- diffusion_steps=int(checkpoint["config"].get("diffusion_steps", 32)),
31
- inference_steps=int(checkpoint["config"].get("inference_steps", 4)),
32
- ),
33
  )
34
  head.load_state_dict(checkpoint["state_dict"])
35
  head.eval()
@@ -39,22 +54,76 @@ def verify(checkpoint_path: Path, bundle_path: Path, *, max_length: int = 32) ->
39
  ]
40
  token_length = max_length if backend == "direct" else int(encoder_config.get("max_tokens", 512))
41
  encoded = tokenizer(texts, padding="max_length", truncation=True, max_length=token_length, return_tensors="pt")
 
 
 
 
 
 
 
 
 
 
 
 
42
  with torch.no_grad():
43
- candidate_embeddings = encoder(**encoded).last_hidden_state[:, 0, :].unsqueeze(0)
44
- option_mask = torch.zeros((1, checkpoint["option_count"]), dtype=torch.bool)
45
  if backend == "direct":
46
- candidate_embeddings = candidate_embeddings[:, :2]
47
- option_mask = torch.ones((1, 2), dtype=torch.bool)
48
- pooled = candidate_embeddings.mean(dim=1)
 
 
 
 
 
49
  torch_output = head(candidate_embeddings, pooled, option_mask)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
50
  else:
51
- padding = checkpoint["option_count"] - candidate_embeddings.shape[1]
52
- candidate_embeddings = torch.cat((candidate_embeddings, torch.zeros((1, padding, candidate_embeddings.shape[-1]))), dim=1)
53
- option_mask[:, :2] = True
54
- pooled = candidate_embeddings[:, :2].mean(dim=1)
55
- betas = torch.linspace(1e-4, 0.02, int(checkpoint["config"].get("diffusion_steps", 32)))
 
 
 
 
 
56
  alpha_bars = torch.cumprod(1.0 - betas, dim=0)
57
- timesteps = torch.linspace(len(alpha_bars) - 1, 0, int(checkpoint["config"].get("inference_steps", 4))).round().long()
58
  sample = torch.zeros((1, checkpoint["option_count"]))
59
  for index, timestep in enumerate(timesteps):
60
  predicted_noise = head(sample, pooled, torch.full((1,), int(timestep), dtype=torch.long))["noise"]
@@ -64,15 +133,16 @@ def verify(checkpoint_path: Path, bundle_path: Path, *, max_length: int = 32) ->
64
  sample = torch.sqrt(previous_alpha) * predicted_x0 + torch.sqrt(1 - previous_alpha) * predicted_noise
65
  torch_output = {
66
  "scores": sample.masked_fill(~option_mask, float("-inf")),
67
- "answerability": head(torch.zeros_like(sample), pooled, torch.zeros((1,), dtype=torch.long))["answerability"],
 
 
68
  }
69
  session = ort.InferenceSession(str(bundle_path), providers=["CPUExecutionProvider"])
70
- options = checkpoint["option_count"] if backend == "diffusion" else 2
71
  ort_feed = {
72
- "input_ids": encoded["input_ids"].numpy()[None, :, :] if backend == "direct" else np.pad(encoded["input_ids"].numpy()[None, :, :], ((0, 0), (0, options - 2), (0, 0))),
73
- "attention_mask": encoded["attention_mask"].numpy()[None, :, :] if backend == "direct" else np.pad(encoded["attention_mask"].numpy()[None, :, :], ((0, 0), (0, options - 2), (0, 0))),
74
- "token_type_ids": encoded["token_type_ids"].numpy()[None, :, :] if backend == "direct" else np.pad(encoded["token_type_ids"].numpy()[None, :, :], ((0, 0), (0, options - 2), (0, 0))),
75
- "option_mask": np.asarray([[True, True] + [False] * (options - 2)], dtype=np.bool_),
76
  }
77
  if backend == "diffusion":
78
  ort_feed["initial_noise"] = np.zeros((1, options), dtype=np.float32)
 
1
+ """Compare an exported end-to-end ONNX bundle with its PyTorch checkpoint."""
2
 
3
  from __future__ import annotations
4
 
 
11
  import torch
12
  from transformers import AutoModel, AutoTokenizer
13
 
14
+ from vons.models import ModelConfig, build_model, cosine_beta_schedule
15
+
16
+
17
+ def _model_config_from_checkpoint(checkpoint: dict[str, object]) -> ModelConfig:
18
+ config = checkpoint["config"]
19
+ if not isinstance(config, dict):
20
+ raise TypeError("checkpoint config must be a mapping")
21
+ backend = str(checkpoint["backend"])
22
+ conditioning = str(config.get("diffusion_conditioning", "pooled"))
23
+ token_conditioned = backend == "diffusion" and conditioning == "token_cross_attention"
24
+ return ModelConfig(
25
+ hidden_size=int(checkpoint["hidden_size"]),
26
+ latent_size=int(config.get("latent_size", 64 if token_conditioned else 32)),
27
+ diffusion_steps=int(config.get("diffusion_steps", 64 if token_conditioned else 32)),
28
+ inference_steps=int(config.get("inference_steps", 8 if token_conditioned else 4)),
29
+ abstain_threshold=float(config.get("abstain_threshold", 0.55)),
30
+ diffusion_conditioning=conditioning,
31
+ attention_heads=int(config.get("attention_heads", 4)),
32
+ )
33
 
34
 
35
  def verify(checkpoint_path: Path, bundle_path: Path, *, max_length: int = 32) -> dict[str, object]:
 
40
  tokenizer = AutoTokenizer.from_pretrained(encoder_config["name"], revision=encoder_config.get("revision"))
41
  encoder = AutoModel.from_pretrained(encoder_config["name"], revision=encoder_config.get("revision")).eval()
42
  backend = checkpoint["backend"]
43
+ conditioning = str(checkpoint["config"].get("diffusion_conditioning", "pooled"))
44
  head = build_model(
45
  backend,
46
  option_count=checkpoint["option_count"],
47
+ config=_model_config_from_checkpoint(checkpoint),
 
 
 
 
48
  )
49
  head.load_state_dict(checkpoint["state_dict"])
50
  head.eval()
 
54
  ]
55
  token_length = max_length if backend == "direct" else int(encoder_config.get("max_tokens", 512))
56
  encoded = tokenizer(texts, padding="max_length", truncation=True, max_length=token_length, return_tensors="pt")
57
+ encoded.setdefault("token_type_ids", torch.zeros_like(encoded["input_ids"]))
58
+ options = (
59
+ checkpoint["option_count"]
60
+ if backend == "diffusion" and conditioning == "pooled"
61
+ else len(texts)
62
+ )
63
+ if options > len(texts):
64
+ for name, tensor in encoded.items():
65
+ encoded[name] = torch.nn.functional.pad(tensor, (0, 0, 0, options - len(texts)))
66
+ batched = {name: tensor.unsqueeze(0) for name, tensor in encoded.items()}
67
+ option_mask = torch.zeros((1, options), dtype=torch.bool)
68
+ option_mask[:, : len(texts)] = True
69
  with torch.no_grad():
 
 
70
  if backend == "direct":
71
+ candidate_embeddings = encoder(
72
+ input_ids=batched["input_ids"].reshape(options, token_length),
73
+ attention_mask=batched["attention_mask"].reshape(options, token_length),
74
+ token_type_ids=batched["token_type_ids"].reshape(options, token_length),
75
+ ).last_hidden_state[:, 0, :].reshape(1, options, -1)
76
+ pooled = (candidate_embeddings * option_mask.unsqueeze(-1)).sum(dim=1) / option_mask.sum(
77
+ dim=1, keepdim=True
78
+ ).clamp_min(1)
79
  torch_output = head(candidate_embeddings, pooled, option_mask)
80
+ elif conditioning == "token_cross_attention":
81
+ sequence_hidden = encoder(
82
+ input_ids=batched["input_ids"].reshape(options, token_length),
83
+ attention_mask=batched["attention_mask"].reshape(options, token_length),
84
+ token_type_ids=batched["token_type_ids"].reshape(options, token_length),
85
+ ).last_hidden_state.reshape(1, options, token_length, -1)
86
+ attention_mask = batched["attention_mask"]
87
+ diffusion_steps = int(checkpoint["config"].get("diffusion_steps", 64))
88
+ inference_steps = int(checkpoint["config"].get("inference_steps", 8))
89
+ alpha_bars = torch.cumprod(1.0 - cosine_beta_schedule(diffusion_steps), dim=0)
90
+ timesteps = torch.linspace(diffusion_steps - 1, 0, inference_steps).round().long()
91
+ sample = torch.zeros((1, options))
92
+ torch_output = {}
93
+ for index, timestep in enumerate(timesteps):
94
+ timestep_batch = torch.full((1,), int(timestep), dtype=torch.long)
95
+ result = head(sample, sequence_hidden, attention_mask, timestep_batch, option_mask)
96
+ predicted_x0 = torch.softmax(result["logits"], dim=-1)
97
+ alpha = alpha_bars[timestep]
98
+ predicted_noise = (sample - torch.sqrt(alpha) * predicted_x0) / torch.sqrt(
99
+ 1 - alpha
100
+ ).clamp_min(1e-6)
101
+ previous_alpha = (
102
+ alpha_bars[timesteps[index + 1]]
103
+ if index + 1 < len(timesteps)
104
+ else sample.new_tensor(1.0)
105
+ )
106
+ sample = torch.sqrt(previous_alpha) * predicted_x0 + torch.sqrt(
107
+ 1 - previous_alpha
108
+ ) * predicted_noise
109
+ torch_output = result
110
+ torch_output = {
111
+ "scores": torch_output["logits"],
112
+ "answerability": torch_output["answerability"],
113
+ }
114
  else:
115
+ candidate_embeddings = encoder(
116
+ input_ids=batched["input_ids"].reshape(options, token_length),
117
+ attention_mask=batched["attention_mask"].reshape(options, token_length),
118
+ token_type_ids=batched["token_type_ids"].reshape(options, token_length),
119
+ ).last_hidden_state[:, 0, :].reshape(1, options, -1)
120
+ weights = option_mask.to(candidate_embeddings.dtype).unsqueeze(-1)
121
+ pooled = (candidate_embeddings * weights).sum(dim=1) / weights.sum(dim=1).clamp_min(1)
122
+ diffusion_steps = int(checkpoint["config"].get("diffusion_steps", 32))
123
+ inference_steps = int(checkpoint["config"].get("inference_steps", 4))
124
+ betas = torch.linspace(1e-4, 0.02, diffusion_steps)
125
  alpha_bars = torch.cumprod(1.0 - betas, dim=0)
126
+ timesteps = torch.linspace(len(alpha_bars) - 1, 0, inference_steps).round().long()
127
  sample = torch.zeros((1, checkpoint["option_count"]))
128
  for index, timestep in enumerate(timesteps):
129
  predicted_noise = head(sample, pooled, torch.full((1,), int(timestep), dtype=torch.long))["noise"]
 
133
  sample = torch.sqrt(previous_alpha) * predicted_x0 + torch.sqrt(1 - previous_alpha) * predicted_noise
134
  torch_output = {
135
  "scores": sample.masked_fill(~option_mask, float("-inf")),
136
+ "answerability": head(
137
+ torch.zeros_like(sample), pooled, torch.zeros((1,), dtype=torch.long)
138
+ )["answerability"],
139
  }
140
  session = ort.InferenceSession(str(bundle_path), providers=["CPUExecutionProvider"])
 
141
  ort_feed = {
142
+ "input_ids": batched["input_ids"].numpy(),
143
+ "attention_mask": batched["attention_mask"].numpy(),
144
+ "token_type_ids": batched["token_type_ids"].numpy(),
145
+ "option_mask": option_mask.numpy(),
146
  }
147
  if backend == "diffusion":
148
  ort_feed["initial_noise"] = np.zeros((1, options), dtype=np.float32)
vons/cli.py CHANGED
@@ -5,12 +5,27 @@ from __future__ import annotations
5
  import argparse
6
  import json
7
  import platform
 
8
  from pathlib import Path
9
 
10
  from .bundle import build_bundle_manifest, verify_bundle_manifest
11
  from .calibration import calibrate_report
12
  from .data import dataset_manifest, read_jsonl, smoke_examples, synthetic_examples, write_jsonl
13
- from .ollama import OllamaClient, benchmark_ollama, write_benchmark
 
 
 
 
 
 
 
 
 
 
 
 
 
 
14
  from .research import build_research_packet
15
  from .training import evaluate, export_diffusion_bundle, export_direct_bundle, export_head, train
16
 
@@ -18,60 +33,189 @@ from .training import evaluate, export_diffusion_bundle, export_direct_bundle, e
18
  def _parser() -> argparse.ArgumentParser:
19
  parser = argparse.ArgumentParser(prog="vons")
20
  sub = parser.add_subparsers(dest="command", required=True)
21
- command = sub.add_parser("generate-smoke"); command.add_argument("--output", required=True)
22
- command = sub.add_parser("generate-synthetic"); command.add_argument("--count", type=int, default=2000); command.add_argument("--seed", type=int, default=7); command.add_argument("--output", required=True)
23
- command = sub.add_parser("validate-data"); command.add_argument("--input", required=True); command.add_argument("--manifest")
24
- command = sub.add_parser("split-data"); command.add_argument("--input", required=True); command.add_argument("--split", choices=["train", "development", "calibration", "test", "smoke"], required=True); command.add_argument("--output", required=True)
25
- command = sub.add_parser("ollama-check"); command.add_argument("--models", nargs="+", required=True); command.add_argument("--host", default="http://127.0.0.1:11434"); command.add_argument("--output")
26
- command = sub.add_parser("ollama-benchmark"); command.add_argument("--model", required=True); command.add_argument("--input", required=True); command.add_argument("--role", default="judge"); command.add_argument("--limit", type=int, default=200); command.add_argument("--seed", type=int, default=7); command.add_argument("--host", default="http://127.0.0.1:11434"); command.add_argument("--output", required=True)
27
- command = sub.add_parser("build-research-packet"); command.add_argument("--results", required=True); command.add_argument("--output", required=True)
28
- command = sub.add_parser("build-bundle-manifest"); command.add_argument("--onnx", required=True); command.add_argument("--tokenizer", required=True); command.add_argument("--output", required=True); command.add_argument("--checkpoint"); command.add_argument("--model-manifest"); command.add_argument("--calibration", action="append", default=[]); command.add_argument("--runtime-asset", action="append", default=[]); command.add_argument("--license", action="append", default=[]); command.add_argument("--config", action="append", default=[]); command.add_argument("--source-root"); command.add_argument("--source-file", action="append", default=[])
29
- command = sub.add_parser("verify-bundle-manifest"); command.add_argument("--manifest", required=True)
30
- command = sub.add_parser("calibrate"); command.add_argument("--calibration-input", required=True); command.add_argument("--calibration-report", required=True); command.add_argument("--test-input", required=True); command.add_argument("--test-report", required=True); command.add_argument("--output", required=True); command.add_argument("--target-brier", type=float); command.add_argument("--target-risk", type=float)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
31
  for name in ("train", "evaluate", "export", "export-bundle", "export-diffusion-bundle"):
32
- command = sub.add_parser(name); command.add_argument("--config"); command.add_argument("--model"); command.add_argument("--input"); command.add_argument("--checkpoint"); command.add_argument("--output")
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
33
  return parser
34
 
35
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
36
  def main(argv: list[str] | None = None) -> int:
37
  args = _parser().parse_args(argv)
38
  if args.command == "generate-smoke":
39
- write_jsonl(args.output, smoke_examples()); print(json.dumps({"output": args.output, "rows": 4}, indent=2)); return 0
 
 
40
  if args.command == "generate-synthetic":
41
- rows = synthetic_examples(args.count, seed=args.seed); write_jsonl(args.output, rows); print(json.dumps({"output": args.output, "rows": len(rows), "seed": args.seed}, indent=2)); return 0
 
 
 
42
  if args.command == "validate-data":
43
- rows = read_jsonl(args.input); manifest = dataset_manifest(args.input, rows)
 
44
  if args.manifest:
45
- Path(args.manifest).parent.mkdir(parents=True, exist_ok=True); Path(args.manifest).write_text(json.dumps(manifest, indent=2, sort_keys=True), encoding="utf-8")
46
- print(json.dumps(manifest, indent=2, sort_keys=True)); return 0
 
 
 
 
47
  if args.command == "split-data":
48
  rows = [row for row in read_jsonl(args.input) if row.split == args.split]
49
  if not rows:
50
  raise SystemExit(f"input has no {args.split!r} rows")
51
  write_jsonl(args.output, rows)
52
- print(json.dumps({"output": args.output, "rows": len(rows), "split": args.split}, indent=2)); return 0
 
53
  if args.command == "ollama-check":
54
- client, payload = OllamaClient(args.host), {"host": args.host, "platform": platform.platform(), "models": []}
 
 
 
55
  for model in args.models:
56
  try:
57
- info = client.show(model); payload["models"].append({"tag": info.tag, "digest": info.digest, "details": info.details, "capabilities": info.capabilities, "license_present": info.license_present})
 
 
 
 
 
 
 
 
 
58
  except (OSError, ValueError, KeyError, RuntimeError, TypeError) as exc:
59
  payload["models"].append({"tag": model, "error": f"{type(exc).__name__}: {exc}"})
60
  serialized = json.dumps(payload, indent=2, sort_keys=True, default=list)
61
  if args.output:
62
- Path(args.output).parent.mkdir(parents=True, exist_ok=True); Path(args.output).write_text(serialized + "\n", encoding="utf-8")
63
- print(serialized); return 0
 
 
64
  if args.command == "ollama-benchmark":
65
  rows = read_jsonl(args.input)
66
- result = benchmark_ollama(OllamaClient(args.host), args.model, rows, role=args.role, limit=args.limit, seed=args.seed)
 
 
 
 
 
 
 
67
  write_benchmark(args.output, result)
68
- print(json.dumps({key: result[key] for key in ("model", "role", "rows", "json_valid_rate", "judgment_accuracy", "latency_p50_ms")}, indent=2))
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
69
  return 0
70
  if args.command == "build-research-packet":
71
- output = build_research_packet(results_dir=args.results, output=args.output); print(json.dumps({"output": str(output)}, indent=2)); return 0
 
 
72
  if args.command == "build-bundle-manifest":
73
  output = build_bundle_manifest(
74
- args.onnx, args.tokenizer, args.output,
 
 
75
  checkpoint_path=args.checkpoint,
76
  model_manifest_path=args.model_manifest,
77
  calibration_paths=args.calibration,
@@ -81,9 +225,15 @@ def main(argv: list[str] | None = None) -> int:
81
  source_root=args.source_root,
82
  source_paths=args.source_file,
83
  )
84
- print(json.dumps({"output": str(output), "verification": verify_bundle_manifest(output)}, indent=2)); return 0
 
 
 
 
 
85
  if args.command == "verify-bundle-manifest":
86
- print(json.dumps(verify_bundle_manifest(args.manifest), indent=2)); return 0
 
87
  if args.command == "calibrate":
88
  output = calibrate_report(
89
  calibration_input=args.calibration_input,
@@ -94,27 +244,94 @@ def main(argv: list[str] | None = None) -> int:
94
  target_risk=args.target_risk,
95
  target_brier=args.target_brier,
96
  )
97
- print(json.dumps({"report": str(output)}, indent=2)); return 0
 
98
  if args.command == "train":
99
  if not args.config:
100
  raise SystemExit("train requires --config")
101
- print(json.dumps({"checkpoint": str(train(args.config))}, indent=2)); return 0
 
102
  if args.command == "evaluate":
103
  if not args.checkpoint or not args.input or not args.output:
104
  raise SystemExit("evaluate requires --checkpoint, --input, and --output")
105
- print(json.dumps({"report": str(evaluate(args.checkpoint, args.input, args.output))}, indent=2)); return 0
 
 
 
 
 
106
  if args.command == "export":
107
  if not args.checkpoint or not args.output:
108
  raise SystemExit("export requires --checkpoint and --output")
109
- print(json.dumps({"onnx": str(export_head(args.checkpoint, args.output))}, indent=2)); return 0
 
110
  if args.command == "export-bundle":
111
  if not args.checkpoint or not args.output:
112
  raise SystemExit("export-bundle requires --checkpoint and --output")
113
- print(json.dumps({"onnx": str(export_direct_bundle(args.checkpoint, args.output))}, indent=2)); return 0
 
 
 
114
  if args.command == "export-diffusion-bundle":
115
  if not args.checkpoint or not args.output:
116
  raise SystemExit("export-diffusion-bundle requires --checkpoint and --output")
117
- print(json.dumps({"onnx": str(export_diffusion_bundle(args.checkpoint, args.output))}, indent=2)); return 0
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
118
  raise SystemExit(f"unknown command: {args.command}")
119
 
120
 
 
5
  import argparse
6
  import json
7
  import platform
8
+ import sys
9
  from pathlib import Path
10
 
11
  from .bundle import build_bundle_manifest, verify_bundle_manifest
12
  from .calibration import calibrate_report
13
  from .data import dataset_manifest, read_jsonl, smoke_examples, synthetic_examples, write_jsonl
14
+ from .ollama import (
15
+ OllamaClient,
16
+ OllamaToolCallError,
17
+ OllamaToolCallHost,
18
+ benchmark_ollama,
19
+ tool_call_result_to_mapping,
20
+ write_benchmark,
21
+ )
22
+ from .onnx_runtime import (
23
+ OnnxRuntimeBackend,
24
+ OnnxRuntimeError,
25
+ OnnxRuntimeUnavailableError,
26
+ SyntheticAbstainBackend,
27
+ VerifiedBundle,
28
+ )
29
  from .research import build_research_packet
30
  from .training import evaluate, export_diffusion_bundle, export_direct_bundle, export_head, train
31
 
 
33
  def _parser() -> argparse.ArgumentParser:
34
  parser = argparse.ArgumentParser(prog="vons")
35
  sub = parser.add_subparsers(dest="command", required=True)
36
+ command = sub.add_parser("generate-smoke")
37
+ command.add_argument("--output", required=True)
38
+ command = sub.add_parser("generate-synthetic")
39
+ command.add_argument("--count", type=int, default=2000)
40
+ command.add_argument("--seed", type=int, default=7)
41
+ command.add_argument("--output", required=True)
42
+ command = sub.add_parser("validate-data")
43
+ command.add_argument("--input", required=True)
44
+ command.add_argument("--manifest")
45
+ command = sub.add_parser("split-data")
46
+ command.add_argument("--input", required=True)
47
+ command.add_argument(
48
+ "--split", choices=["train", "development", "calibration", "test", "smoke"], required=True
49
+ )
50
+ command.add_argument("--output", required=True)
51
+ command = sub.add_parser("ollama-check")
52
+ command.add_argument("--models", nargs="+", required=True)
53
+ command.add_argument("--host", default="http://127.0.0.1:11434")
54
+ command.add_argument("--output")
55
+ command = sub.add_parser("ollama-benchmark")
56
+ command.add_argument("--model", required=True)
57
+ command.add_argument("--input", required=True)
58
+ command.add_argument("--role", default="judge")
59
+ command.add_argument("--limit", type=int, default=200)
60
+ command.add_argument("--seed", type=int, default=7)
61
+ command.add_argument("--host", default="http://127.0.0.1:11434")
62
+ command.add_argument("--output", required=True)
63
+ command = sub.add_parser("build-research-packet")
64
+ command.add_argument("--results", required=True)
65
+ command.add_argument("--output", required=True)
66
+ command = sub.add_parser("build-bundle-manifest")
67
+ command.add_argument("--onnx", required=True)
68
+ command.add_argument("--tokenizer", required=True)
69
+ command.add_argument("--output", required=True)
70
+ command.add_argument("--checkpoint")
71
+ command.add_argument("--model-manifest")
72
+ command.add_argument("--calibration", action="append", default=[])
73
+ command.add_argument("--runtime-asset", action="append", default=[])
74
+ command.add_argument("--license", action="append", default=[])
75
+ command.add_argument("--config", action="append", default=[])
76
+ command.add_argument("--source-root")
77
+ command.add_argument("--source-file", action="append", default=[])
78
+ command = sub.add_parser("verify-bundle-manifest")
79
+ command.add_argument("--manifest", required=True)
80
+ command = sub.add_parser("calibrate")
81
+ command.add_argument("--calibration-input", required=True)
82
+ command.add_argument("--calibration-report", required=True)
83
+ command.add_argument("--test-input", required=True)
84
+ command.add_argument("--test-report", required=True)
85
+ command.add_argument("--output", required=True)
86
+ command.add_argument("--target-brier", type=float)
87
+ command.add_argument("--target-risk", type=float)
88
  for name in ("train", "evaluate", "export", "export-bundle", "export-diffusion-bundle"):
89
+ command = sub.add_parser(name)
90
+ command.add_argument("--config")
91
+ command.add_argument("--model")
92
+ command.add_argument("--input")
93
+ command.add_argument("--checkpoint")
94
+ command.add_argument("--output")
95
+ command = sub.add_parser("ollama-tool-call")
96
+ command.add_argument("--host", default="http://127.0.0.1:11434")
97
+ command.add_argument("--model", required=True)
98
+ command.add_argument("--bundle")
99
+ command.add_argument(
100
+ "--synthetic",
101
+ choices=["abstain", "choice-0", "choice-1"],
102
+ help="Use a synthetic backend instead of --bundle",
103
+ )
104
+ command.add_argument(
105
+ "--input", required=True, help='JSON file with {"messages": [...]} payload'
106
+ )
107
+ command.add_argument("--seed", type=int, default=7)
108
+ command.add_argument("--output")
109
  return parser
110
 
111
 
112
+ _MAX_TOOL_CALL_INPUT_BYTES = 262_144
113
+
114
+
115
+ def _read_tool_call_input(path: str | Path) -> dict[str, object]:
116
+ try:
117
+ with Path(path).open("rb") as handle:
118
+ raw = handle.read(_MAX_TOOL_CALL_INPUT_BYTES + 1)
119
+ if len(raw) > _MAX_TOOL_CALL_INPUT_BYTES:
120
+ raise ValueError("input exceeds size limit")
121
+ payload = json.loads(raw)
122
+ except (OSError, RecursionError, UnicodeDecodeError, json.JSONDecodeError) as exc:
123
+ raise ValueError("input could not be parsed") from exc
124
+ if not isinstance(payload, dict) or set(payload) != {"messages"}:
125
+ raise TypeError("input must be an object")
126
+ return payload
127
+
128
+
129
  def main(argv: list[str] | None = None) -> int:
130
  args = _parser().parse_args(argv)
131
  if args.command == "generate-smoke":
132
+ write_jsonl(args.output, smoke_examples())
133
+ print(json.dumps({"output": args.output, "rows": 4}, indent=2))
134
+ return 0
135
  if args.command == "generate-synthetic":
136
+ rows = synthetic_examples(args.count, seed=args.seed)
137
+ write_jsonl(args.output, rows)
138
+ print(json.dumps({"output": args.output, "rows": len(rows), "seed": args.seed}, indent=2))
139
+ return 0
140
  if args.command == "validate-data":
141
+ rows = read_jsonl(args.input)
142
+ manifest = dataset_manifest(args.input, rows)
143
  if args.manifest:
144
+ Path(args.manifest).parent.mkdir(parents=True, exist_ok=True)
145
+ Path(args.manifest).write_text(
146
+ json.dumps(manifest, indent=2, sort_keys=True), encoding="utf-8"
147
+ )
148
+ print(json.dumps(manifest, indent=2, sort_keys=True))
149
+ return 0
150
  if args.command == "split-data":
151
  rows = [row for row in read_jsonl(args.input) if row.split == args.split]
152
  if not rows:
153
  raise SystemExit(f"input has no {args.split!r} rows")
154
  write_jsonl(args.output, rows)
155
+ print(json.dumps({"output": args.output, "rows": len(rows), "split": args.split}, indent=2))
156
+ return 0
157
  if args.command == "ollama-check":
158
+ client, payload = (
159
+ OllamaClient(args.host),
160
+ {"host": args.host, "platform": platform.platform(), "models": []},
161
+ )
162
  for model in args.models:
163
  try:
164
+ info = client.show(model)
165
+ payload["models"].append(
166
+ {
167
+ "tag": info.tag,
168
+ "digest": info.digest,
169
+ "details": info.details,
170
+ "capabilities": info.capabilities,
171
+ "license_present": info.license_present,
172
+ }
173
+ )
174
  except (OSError, ValueError, KeyError, RuntimeError, TypeError) as exc:
175
  payload["models"].append({"tag": model, "error": f"{type(exc).__name__}: {exc}"})
176
  serialized = json.dumps(payload, indent=2, sort_keys=True, default=list)
177
  if args.output:
178
+ Path(args.output).parent.mkdir(parents=True, exist_ok=True)
179
+ Path(args.output).write_text(serialized + "\n", encoding="utf-8")
180
+ print(serialized)
181
+ return 0
182
  if args.command == "ollama-benchmark":
183
  rows = read_jsonl(args.input)
184
+ result = benchmark_ollama(
185
+ OllamaClient(args.host),
186
+ args.model,
187
+ rows,
188
+ role=args.role,
189
+ limit=args.limit,
190
+ seed=args.seed,
191
+ )
192
  write_benchmark(args.output, result)
193
+ print(
194
+ json.dumps(
195
+ {
196
+ key: result[key]
197
+ for key in (
198
+ "model",
199
+ "role",
200
+ "rows",
201
+ "json_valid_rate",
202
+ "judgment_accuracy",
203
+ "latency_p50_ms",
204
+ )
205
+ },
206
+ indent=2,
207
+ )
208
+ )
209
  return 0
210
  if args.command == "build-research-packet":
211
+ output = build_research_packet(results_dir=args.results, output=args.output)
212
+ print(json.dumps({"output": str(output)}, indent=2))
213
+ return 0
214
  if args.command == "build-bundle-manifest":
215
  output = build_bundle_manifest(
216
+ args.onnx,
217
+ args.tokenizer,
218
+ args.output,
219
  checkpoint_path=args.checkpoint,
220
  model_manifest_path=args.model_manifest,
221
  calibration_paths=args.calibration,
 
225
  source_root=args.source_root,
226
  source_paths=args.source_file,
227
  )
228
+ print(
229
+ json.dumps(
230
+ {"output": str(output), "verification": verify_bundle_manifest(output)}, indent=2
231
+ )
232
+ )
233
+ return 0
234
  if args.command == "verify-bundle-manifest":
235
+ print(json.dumps(verify_bundle_manifest(args.manifest), indent=2))
236
+ return 0
237
  if args.command == "calibrate":
238
  output = calibrate_report(
239
  calibration_input=args.calibration_input,
 
244
  target_risk=args.target_risk,
245
  target_brier=args.target_brier,
246
  )
247
+ print(json.dumps({"report": str(output)}, indent=2))
248
+ return 0
249
  if args.command == "train":
250
  if not args.config:
251
  raise SystemExit("train requires --config")
252
+ print(json.dumps({"checkpoint": str(train(args.config))}, indent=2))
253
+ return 0
254
  if args.command == "evaluate":
255
  if not args.checkpoint or not args.input or not args.output:
256
  raise SystemExit("evaluate requires --checkpoint, --input, and --output")
257
+ print(
258
+ json.dumps(
259
+ {"report": str(evaluate(args.checkpoint, args.input, args.output))}, indent=2
260
+ )
261
+ )
262
+ return 0
263
  if args.command == "export":
264
  if not args.checkpoint or not args.output:
265
  raise SystemExit("export requires --checkpoint and --output")
266
+ print(json.dumps({"onnx": str(export_head(args.checkpoint, args.output))}, indent=2))
267
+ return 0
268
  if args.command == "export-bundle":
269
  if not args.checkpoint or not args.output:
270
  raise SystemExit("export-bundle requires --checkpoint and --output")
271
+ print(
272
+ json.dumps({"onnx": str(export_direct_bundle(args.checkpoint, args.output))}, indent=2)
273
+ )
274
+ return 0
275
  if args.command == "export-diffusion-bundle":
276
  if not args.checkpoint or not args.output:
277
  raise SystemExit("export-diffusion-bundle requires --checkpoint and --output")
278
+ print(
279
+ json.dumps(
280
+ {"onnx": str(export_diffusion_bundle(args.checkpoint, args.output))}, indent=2
281
+ )
282
+ )
283
+ return 0
284
+ if args.command == "ollama-tool-call":
285
+ if args.synthetic == "abstain":
286
+ backend = SyntheticAbstainBackend()
287
+ elif args.synthetic == "choice-0":
288
+ from .onnx_runtime import SyntheticChoiceBackend
289
+
290
+ backend = SyntheticChoiceBackend(choice_index=0)
291
+ elif args.synthetic == "choice-1":
292
+ from .onnx_runtime import SyntheticChoiceBackend
293
+
294
+ backend = SyntheticChoiceBackend(choice_index=1)
295
+ elif args.bundle:
296
+ try:
297
+ bundle = VerifiedBundle.load(args.bundle)
298
+ except Exception: # noqa: BLE001 - boundary fail-closed
299
+ print("ollama tool-call bundle load failed", file=sys.stderr)
300
+ return 15
301
+ backend = OnnxRuntimeBackend(bundle)
302
+ else:
303
+ print("ollama-tool-call requires --bundle or --synthetic", file=sys.stderr)
304
+ return 2
305
+ try:
306
+ payload = _read_tool_call_input(args.input)
307
+ except (TypeError, ValueError):
308
+ print("ollama tool-call input parse failed", file=sys.stderr)
309
+ return 3
310
+ messages = payload.get("messages")
311
+ if not isinstance(messages, list):
312
+ print("ollama tool-call input must contain a messages list", file=sys.stderr)
313
+ return 3
314
+ if isinstance(backend, OnnxRuntimeBackend):
315
+ try:
316
+ backend.prepare()
317
+ except OnnxRuntimeUnavailableError:
318
+ print("ollama tool-call local inference dependencies are missing", file=sys.stderr)
319
+ return 16
320
+ except OnnxRuntimeError:
321
+ print("ollama tool-call local backend preflight failed", file=sys.stderr)
322
+ return 17
323
+ try:
324
+ host = OllamaToolCallHost(args.host, backend)
325
+ except OllamaToolCallError as exc:
326
+ print(f"ollama tool-call host init failed error_id={exc.error_id}", file=sys.stderr)
327
+ return 5
328
+ result = host.chat_with_tools(args.model, messages, seed=args.seed)
329
+ serialized = json.dumps(tool_call_result_to_mapping(result), indent=2, sort_keys=True)
330
+ if args.output:
331
+ Path(args.output).parent.mkdir(parents=True, exist_ok=True)
332
+ Path(args.output).write_text(serialized + "\n", encoding="utf-8")
333
+ print(serialized)
334
+ return 17 if result.error is not None else 0
335
  raise SystemExit(f"unknown command: {args.command}")
336
 
337
 
vons/ollama.py CHANGED
@@ -2,16 +2,32 @@
2
 
3
  from __future__ import annotations
4
 
 
5
  import json
 
6
  import platform
 
7
  import time
 
 
8
  import urllib.request
9
  from collections.abc import Mapping, Sequence
10
  from dataclasses import asdict, dataclass
 
11
  from pathlib import Path
12
  from typing import Any
13
 
 
 
 
 
 
 
 
 
 
14
  from .data import Example
 
15
 
16
 
17
  @dataclass(frozen=True)
@@ -41,7 +57,12 @@ class OllamaClient:
41
 
42
  def _request(self, path: str, payload: Mapping[str, Any] | None = None) -> Any:
43
  data = None if payload is None else json.dumps(payload).encode("utf-8")
44
- request = urllib.request.Request(self.host + path, data=data, headers={"Content-Type": "application/json"}, method="POST" if payload is not None else "GET")
 
 
 
 
 
45
  with urllib.request.urlopen(request, timeout=self.timeout) as response:
46
  return json.loads(response.read().decode("utf-8"))
47
 
@@ -57,28 +78,83 @@ class OllamaClient:
57
  value = self._request("/api/show", {"model": model})
58
  digest = value.get("digest")
59
  if not digest:
60
- digest = next((item.get("digest") for item in self.tags() if item.get("name") == model or item.get("model") == model), None)
61
- return OllamaModelInfo(model, digest, dict(value.get("details", {})), tuple(value.get("capabilities", ())), bool(value.get("license")))
 
 
 
 
 
 
 
 
 
 
 
 
 
62
 
63
- def chat_json(self, model: str, *, system: str, prompt: str, schema: Mapping[str, Any], seed: int = 7) -> OllamaRecord:
 
 
64
  started = time.perf_counter()
65
  created_at = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
66
  body: Mapping[str, Any] = {}
67
  try:
68
- body = self._request("/api/chat", {"model": model, "messages": [{"role": "system", "content": system}, {"role": "user", "content": prompt}], "stream": False, "format": schema, "options": {"temperature": 0, "seed": seed}, "think": False})
 
 
 
 
 
 
 
 
 
 
 
 
 
69
  response = body.get("message", {}).get("content", "")
70
  info = self.show(model)
71
  error = None
72
  except (OSError, ValueError, KeyError, RuntimeError, TypeError) as exc:
73
  response, info, error = None, None, f"{type(exc).__name__}: {exc}"
74
- return OllamaRecord(model, "chat_json", prompt, response, created_at, (time.perf_counter() - started) * 1000, {"host": self.host, "platform": platform.platform(), "ollama_version": self.version() if error is None else None, "digest": info.digest if info else None, "details": dict(info.details) if info else {}, "capabilities": list(info.capabilities) if info else [], "license_present": info.license_present if info else None, "raw_fields": sorted(body), "raw_response": body}, error)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
75
 
76
 
77
  def record_to_mapping(record: OllamaRecord) -> dict[str, Any]:
78
  return asdict(record)
79
 
80
 
81
- def benchmark_ollama(client: OllamaClient, model: str, examples: Sequence[Example], *, role: str = "judge", limit: int = 200, seed: int = 7) -> dict[str, Any]:
 
 
 
 
 
 
 
 
82
  """Measure JSON compliance and judgment on a bounded, known-label set.
83
 
84
  The model's self-reported confidence is retained only as raw output. It is
@@ -93,10 +169,20 @@ def benchmark_ollama(client: OllamaClient, model: str, examples: Sequence[Exampl
93
  system = "Return only JSON with a choice from the candidates or null and an abstain boolean. Do not call tools."
94
  records: list[dict[str, Any]] = []
95
  for row in list(examples)[:limit]:
96
- prompt = json.dumps({"state": row.state, "question": row.question, "candidates": list(row.options)}, ensure_ascii=False)
 
 
 
97
  record = client.chat_json(model, system=system, prompt=prompt, schema=schema, seed=seed)
98
  item = record_to_mapping(record)
99
- item.update({"example_id": row.id, "role": role, "expected_label": row.label, "expected_answerable": row.answerable})
 
 
 
 
 
 
 
100
  parsed: Mapping[str, Any] | None = None
101
  valid_json = False
102
  if record.response:
@@ -110,7 +196,18 @@ def benchmark_ollama(client: OllamaClient, model: str, examples: Sequence[Exampl
110
  parsed = None
111
  item["parsed"] = dict(parsed) if parsed is not None else None
112
  item["valid_json"] = valid_json
113
- item["correct"] = bool(valid_json and ((row.answerable and parsed and parsed.get("choice") == row.label and not parsed.get("abstain")) or (not row.answerable and parsed and parsed.get("abstain"))))
 
 
 
 
 
 
 
 
 
 
 
114
  records.append(item)
115
  valid = [item for item in records if item["valid_json"]]
116
  correct = [item for item in records if item["correct"]]
@@ -130,4 +227,609 @@ def benchmark_ollama(client: OllamaClient, model: str, examples: Sequence[Exampl
130
  def write_benchmark(path: str | Path, result: Mapping[str, Any]) -> None:
131
  target = Path(path)
132
  target.parent.mkdir(parents=True, exist_ok=True)
133
- target.write_text(json.dumps(dict(result), ensure_ascii=False, indent=2, sort_keys=True), encoding="utf-8")
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2
 
3
  from __future__ import annotations
4
 
5
+ import ipaddress
6
  import json
7
+ import math
8
  import platform
9
+ import secrets
10
  import time
11
+ import urllib.error
12
+ import urllib.parse
13
  import urllib.request
14
  from collections.abc import Mapping, Sequence
15
  from dataclasses import asdict, dataclass
16
+ from http.client import HTTPResponse
17
  from pathlib import Path
18
  from typing import Any
19
 
20
+ from .contract import (
21
+ Backend,
22
+ DecisionRequest,
23
+ DecisionResponse,
24
+ OptionProbability,
25
+ QuestionAnswer,
26
+ ResponseStatus,
27
+ validate_request,
28
+ )
29
  from .data import Example
30
+ from .onnx_runtime import DecisionBackend
31
 
32
 
33
  @dataclass(frozen=True)
 
57
 
58
  def _request(self, path: str, payload: Mapping[str, Any] | None = None) -> Any:
59
  data = None if payload is None else json.dumps(payload).encode("utf-8")
60
+ request = urllib.request.Request(
61
+ self.host + path,
62
+ data=data,
63
+ headers={"Content-Type": "application/json"},
64
+ method="POST" if payload is not None else "GET",
65
+ )
66
  with urllib.request.urlopen(request, timeout=self.timeout) as response:
67
  return json.loads(response.read().decode("utf-8"))
68
 
 
78
  value = self._request("/api/show", {"model": model})
79
  digest = value.get("digest")
80
  if not digest:
81
+ digest = next(
82
+ (
83
+ item.get("digest")
84
+ for item in self.tags()
85
+ if item.get("name") == model or item.get("model") == model
86
+ ),
87
+ None,
88
+ )
89
+ return OllamaModelInfo(
90
+ model,
91
+ digest,
92
+ dict(value.get("details", {})),
93
+ tuple(value.get("capabilities", ())),
94
+ bool(value.get("license")),
95
+ )
96
 
97
+ def chat_json(
98
+ self, model: str, *, system: str, prompt: str, schema: Mapping[str, Any], seed: int = 7
99
+ ) -> OllamaRecord:
100
  started = time.perf_counter()
101
  created_at = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
102
  body: Mapping[str, Any] = {}
103
  try:
104
+ body = self._request(
105
+ "/api/chat",
106
+ {
107
+ "model": model,
108
+ "messages": [
109
+ {"role": "system", "content": system},
110
+ {"role": "user", "content": prompt},
111
+ ],
112
+ "stream": False,
113
+ "format": schema,
114
+ "options": {"temperature": 0, "seed": seed},
115
+ "think": False,
116
+ },
117
+ )
118
  response = body.get("message", {}).get("content", "")
119
  info = self.show(model)
120
  error = None
121
  except (OSError, ValueError, KeyError, RuntimeError, TypeError) as exc:
122
  response, info, error = None, None, f"{type(exc).__name__}: {exc}"
123
+ return OllamaRecord(
124
+ model,
125
+ "chat_json",
126
+ prompt,
127
+ response,
128
+ created_at,
129
+ (time.perf_counter() - started) * 1000,
130
+ {
131
+ "host": self.host,
132
+ "platform": platform.platform(),
133
+ "ollama_version": self.version() if error is None else None,
134
+ "digest": info.digest if info else None,
135
+ "details": dict(info.details) if info else {},
136
+ "capabilities": list(info.capabilities) if info else [],
137
+ "license_present": info.license_present if info else None,
138
+ "raw_fields": sorted(body),
139
+ "raw_response": body,
140
+ },
141
+ error,
142
+ )
143
 
144
 
145
  def record_to_mapping(record: OllamaRecord) -> dict[str, Any]:
146
  return asdict(record)
147
 
148
 
149
+ def benchmark_ollama(
150
+ client: OllamaClient,
151
+ model: str,
152
+ examples: Sequence[Example],
153
+ *,
154
+ role: str = "judge",
155
+ limit: int = 200,
156
+ seed: int = 7,
157
+ ) -> dict[str, Any]:
158
  """Measure JSON compliance and judgment on a bounded, known-label set.
159
 
160
  The model's self-reported confidence is retained only as raw output. It is
 
169
  system = "Return only JSON with a choice from the candidates or null and an abstain boolean. Do not call tools."
170
  records: list[dict[str, Any]] = []
171
  for row in list(examples)[:limit]:
172
+ prompt = json.dumps(
173
+ {"state": row.state, "question": row.question, "candidates": list(row.options)},
174
+ ensure_ascii=False,
175
+ )
176
  record = client.chat_json(model, system=system, prompt=prompt, schema=schema, seed=seed)
177
  item = record_to_mapping(record)
178
+ item.update(
179
+ {
180
+ "example_id": row.id,
181
+ "role": role,
182
+ "expected_label": row.label,
183
+ "expected_answerable": row.answerable,
184
+ }
185
+ )
186
  parsed: Mapping[str, Any] | None = None
187
  valid_json = False
188
  if record.response:
 
196
  parsed = None
197
  item["parsed"] = dict(parsed) if parsed is not None else None
198
  item["valid_json"] = valid_json
199
+ item["correct"] = bool(
200
+ valid_json
201
+ and (
202
+ (
203
+ row.answerable
204
+ and parsed
205
+ and parsed.get("choice") == row.label
206
+ and not parsed.get("abstain")
207
+ )
208
+ or (not row.answerable and parsed and parsed.get("abstain"))
209
+ )
210
+ )
211
  records.append(item)
212
  valid = [item for item in records if item["valid_json"]]
213
  correct = [item for item in records if item["correct"]]
 
227
  def write_benchmark(path: str | Path, result: Mapping[str, Any]) -> None:
228
  target = Path(path)
229
  target.parent.mkdir(parents=True, exist_ok=True)
230
+ target.write_text(
231
+ json.dumps(dict(result), ensure_ascii=False, indent=2, sort_keys=True), encoding="utf-8"
232
+ )
233
+
234
+
235
+ _LOOPBACK_HOSTS = frozenset(
236
+ {"127.0.0.1", "localhost", "::1", "0000:0000:0000:0000:0000:0000:0000:0001"}
237
+ )
238
+ _VONS_TOOL_NAME = "vons_decide"
239
+ _ERROR_ID_BYTES = 6
240
+ _MAX_MESSAGES = 32
241
+ _MAX_MESSAGE_CONTENT_CHARS = 16_384
242
+ _MAX_TOOL_ARGUMENT_BYTES = 65_536
243
+ _MAX_REQUEST_BYTES = 262_144
244
+ _MAX_RESPONSE_BYTES = 524_288
245
+ _MAX_MODEL_NAME_CHARS = 256
246
+ _MAX_SEED = 2**31 - 1
247
+
248
+
249
+ def _strict_json_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
250
+ result: dict[str, Any] = {}
251
+ for key, value in pairs:
252
+ if key in result:
253
+ raise ValueError("duplicate JSON key")
254
+ result[key] = value
255
+ return result
256
+
257
+
258
+ def _reject_json_constant(value: str) -> None:
259
+ raise ValueError(f"invalid JSON constant: {value}")
260
+
261
+
262
+ class OllamaToolCallError(RuntimeError):
263
+ """Sanitized host error for Ollama tool-call workflows.
264
+
265
+ The message is a fixed short literal. A 12-character hex `error_id` is
266
+ attached for correlation, but no cause text, request payload, or response text
267
+ is ever echoed in the string form.
268
+ """
269
+
270
+ def __init__(self, message: str = "ollama tool-call host aborted") -> None:
271
+ super().__init__(message)
272
+ self.error_id = secrets.token_hex(_ERROR_ID_BYTES)[:12]
273
+
274
+ def sanitized(self) -> dict[str, str]:
275
+ return {"error": "ollama_tool_call_failed", "error_id": self.error_id}
276
+
277
+
278
+ def _validate_loopback_host(url: str) -> None:
279
+ """Reject a URL whose host portion is not a documented loopback address.
280
+
281
+ Runs BEFORE any socket open. Rejects URI schemes, hostnames, raw IPs, or bracket
282
+ IPv6 forms that do not resolve to ``127.0.0.1``, ``::1``, or ``localhost``.
283
+ """
284
+ if not isinstance(url, str) or not url:
285
+ raise OllamaToolCallError()
286
+ try:
287
+ parsed = urllib.parse.urlsplit(url)
288
+ hostname = parsed.hostname
289
+ port = parsed.port
290
+ except ValueError:
291
+ raise OllamaToolCallError() from None
292
+ if (
293
+ parsed.scheme not in {"http", "https"}
294
+ or hostname is None
295
+ or parsed.username is not None
296
+ or parsed.password is not None
297
+ or parsed.query
298
+ or parsed.fragment
299
+ or (port is not None and not 1 <= port <= 65535)
300
+ ):
301
+ raise OllamaToolCallError()
302
+ host_lower = hostname.lower()
303
+ if host_lower in _LOOPBACK_HOSTS:
304
+ return
305
+ try:
306
+ addr = ipaddress.ip_address(host_lower)
307
+ except ValueError:
308
+ raise OllamaToolCallError() from None
309
+ if not addr.is_loopback:
310
+ raise OllamaToolCallError()
311
+
312
+
313
+ class _LoopbackRedirectHandler(urllib.request.HTTPRedirectHandler):
314
+ """urllib redirect handler that refuses to leave loopback addresses.
315
+
316
+ Applied to every outgoing tool-call requests so a compromised local Ollama proxy cannot
317
+ bounce a tool dispatch to a remote service.
318
+ """
319
+
320
+ def redirect_request(self, req, fp, code, msg, headers, newurl): # type: ignore[override,no-untyped-def]
321
+ _validate_loopback_host(newurl)
322
+ return super().redirect_request(req, fp, code, msg, headers, newurl)
323
+
324
+ def http_error_301(self, req, fp, code, msg, headers): # type: ignore[override,no-untyped-def]
325
+ return self._handle_redirect(req, fp, code, msg, headers)
326
+
327
+ def http_error_302(self, req, fp, code, msg, headers): # type: ignore[override,no-untyped-def]
328
+ return self._handle_redirect(req, fp, code, msg, headers)
329
+
330
+ def http_error_303(self, req, fp, code, msg, headers): # type: ignore[override,no-untyped-def]
331
+ return self._handle_redirect(req, fp, code, msg, headers)
332
+
333
+ def http_error_307(self, req, fp, code, msg, headers): # type: ignore[override,no-untyped-def]
334
+ return self._handle_redirect(req, fp, code, msg, headers)
335
+
336
+ def http_error_308(self, req, fp, code, msg, headers): # type: ignore[override,no-untyped-def]
337
+ return self._handle_redirect(req, fp, code, msg, headers)
338
+
339
+ def _handle_redirect(self, req, fp, code, msg, headers): # type: ignore[no-untyped-def]
340
+ newurl = headers.get("Location") or headers.get("location")
341
+ if isinstance(newurl, bytes):
342
+ newurl = newurl.decode("latin-1")
343
+ if newurl:
344
+ _validate_loopback_host(str(newurl))
345
+ method = getattr(urllib.request.HTTPRedirectHandler, f"http_error_{code}", None)
346
+ if method is None:
347
+ raise OllamaToolCallError()
348
+ return method(self, req, fp, code, msg, headers)
349
+
350
+
351
+ _VONS_DECIDE_TOOL_SCHEMA: Mapping[str, Any] = {
352
+ "type": "function",
353
+ "function": {
354
+ "name": _VONS_TOOL_NAME,
355
+ "description": "Run a verified local Vons ONNX decision on a structured candidate set.",
356
+ "parameters": {
357
+ "type": "object",
358
+ "properties": {
359
+ "state": {
360
+ "oneOf": [{"type": "string"}, {"type": "object"}],
361
+ "description": "Serialized conversation/task state or structured object.",
362
+ },
363
+ "questions": {
364
+ "type": "array",
365
+ "minItems": 1,
366
+ "maxItems": 8,
367
+ "items": {
368
+ "type": "object",
369
+ "properties": {
370
+ "id": {"type": "string", "minLength": 1},
371
+ "type": {"type": "string", "enum": ["choice", "boolean", "score"]},
372
+ "prompt": {"type": "string", "minLength": 1},
373
+ "options": {
374
+ "type": "array",
375
+ "minItems": 2,
376
+ "maxItems": 32,
377
+ "items": {"type": "string", "minLength": 1},
378
+ },
379
+ "rubric": {
380
+ "type": "array",
381
+ "maxItems": 10,
382
+ "items": {"type": "string", "minLength": 1},
383
+ },
384
+ },
385
+ "required": ["id", "type", "prompt", "options"],
386
+ "additionalProperties": False,
387
+ },
388
+ },
389
+ "backend": {"type": "string", "enum": ["direct", "diffusion"]},
390
+ "seed": {"type": "integer", "minimum": 0},
391
+ },
392
+ "required": ["state", "questions"],
393
+ "additionalProperties": False,
394
+ },
395
+ },
396
+ }
397
+
398
+
399
+ @dataclass(frozen=True)
400
+ class OllamaToolCallResult:
401
+ """Host-owned result of a single Ollama chat-with-tools turn.
402
+
403
+ The raw Ollama message payload is preserved byte-for-byte so auditors can
404
+ correlate what the model actually returned. The validated ``backend_result`` is
405
+ populated only when (1) the model requested exactly one ``vons_decide``
406
+ call, (2) its arguments validated against ``DecisionRequest``, (3) the
407
+ local backend ran, and (4) the backend output reconciled with the request.
408
+ Every other case yields a sanitized error and leaves the backend empty.
409
+ """
410
+
411
+ model: str
412
+ error_id: str | None
413
+ raw_ollama_response: Mapping[str, Any] | None
414
+ backend_result: DecisionResponse | None
415
+ tool_invoked: bool
416
+ error: OllamaToolCallError | None
417
+
418
+
419
+ class OllamaToolCallHost:
420
+ """Host-owned Ollama chat adapter for the Vons native tool-call workflow.
421
+
422
+ Security boundaries enforced here, in order:
423
+
424
+ 1. Host address must resolve to loopback.
425
+ 2. Redirects that would leave loopback are blocked.
426
+ 3. Only the ``vons_decide`` tool is advertised; any other tool call
427
+ the model requests is rejected *before* the backend is reached.
428
+ 4. Tool-call arguments must parse to a valid ``DecisionRequest``.
429
+ 5. The local backend is the ONLY decision authority. The model's own
430
+ returned text or confidence is never used as a choice or authorization.
431
+ 6. Backend response is reconciled against the exact request question IDs.
432
+ 7. Raw Ollama output is preserved separately; no fields from it are
433
+ trusted to be a decision.
434
+ 8. All errors are sanitized literals with short id correlations; no request
435
+ text, arguments, or responses are echoed to diagnostic streams.
436
+ """
437
+
438
+ def __init__(self, host: str, backend: DecisionBackend, *, timeout: float = 120.0) -> None:
439
+ _validate_loopback_host(host)
440
+ parsed_host = urllib.parse.urlsplit(host)
441
+ if parsed_host.path not in {"", "/"}:
442
+ raise OllamaToolCallError()
443
+ if not isinstance(backend, DecisionBackend) or not isinstance(
444
+ backend.backend_type, Backend
445
+ ):
446
+ raise OllamaToolCallError()
447
+ self.host = host.rstrip("/")
448
+ self.backend = backend
449
+ if isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or timeout <= 0:
450
+ raise OllamaToolCallError()
451
+ self.timeout = timeout
452
+ self._opener = urllib.request.build_opener(
453
+ urllib.request.ProxyHandler({}),
454
+ _LoopbackRedirectHandler,
455
+ )
456
+
457
+ def _post(self, path: str, payload: Mapping[str, Any]) -> Any:
458
+ _validate_loopback_host(self.host + path)
459
+ try:
460
+ body_bytes = json.dumps(payload, allow_nan=False, separators=(",", ":")).encode("utf-8")
461
+ except (RecursionError, TypeError, ValueError) as exc:
462
+ raise OllamaToolCallError() from exc
463
+ if len(body_bytes) > _MAX_REQUEST_BYTES:
464
+ raise OllamaToolCallError()
465
+ request = urllib.request.Request(
466
+ self.host + path,
467
+ data=body_bytes,
468
+ headers={"Content-Type": "application/json"},
469
+ method="POST",
470
+ )
471
+ try:
472
+ with self._opener.open(request, timeout=self.timeout) as response:
473
+ raw = response.read(_MAX_RESPONSE_BYTES + 1)
474
+ except (urllib.error.URLError, OSError, TimeoutError) as exc:
475
+ raise OllamaToolCallError() from exc
476
+ if len(raw) > _MAX_RESPONSE_BYTES:
477
+ raise OllamaToolCallError()
478
+ if not isinstance(response, HTTPResponse) or response.status != 200:
479
+ raise OllamaToolCallError()
480
+ try:
481
+ return json.loads(
482
+ raw.decode("utf-8"),
483
+ object_pairs_hook=_strict_json_object,
484
+ parse_constant=_reject_json_constant,
485
+ )
486
+ except (RecursionError, UnicodeDecodeError, ValueError) as exc:
487
+ raise OllamaToolCallError() from exc
488
+
489
+ def _parse_tool_call(self, message: Mapping[str, Any]) -> Mapping[str, Any]:
490
+ tool_calls = message.get("tool_calls")
491
+ if not isinstance(tool_calls, list) or len(tool_calls) != 1:
492
+ raise OllamaToolCallError()
493
+ call = tool_calls[0]
494
+ if not isinstance(call, Mapping):
495
+ raise OllamaToolCallError()
496
+ if set(call) - {"id", "type", "function"}:
497
+ raise OllamaToolCallError()
498
+ if call.get("type", "function") != "function":
499
+ raise OllamaToolCallError()
500
+ call_id = call.get("id")
501
+ if call_id is not None and (
502
+ not isinstance(call_id, str)
503
+ or not call_id
504
+ or len(call_id) > _MAX_MODEL_NAME_CHARS
505
+ or any(ord(char) < 32 for char in call_id)
506
+ ):
507
+ raise OllamaToolCallError()
508
+ function = call.get("function")
509
+ if not isinstance(function, Mapping):
510
+ raise OllamaToolCallError()
511
+ if set(function) - {"index", "name", "arguments"} or not {
512
+ "name",
513
+ "arguments",
514
+ } <= set(function):
515
+ raise OllamaToolCallError()
516
+ if "index" in function and (
517
+ isinstance(function["index"], bool)
518
+ or not isinstance(function["index"], int)
519
+ or function["index"] < 0
520
+ ):
521
+ raise OllamaToolCallError()
522
+ name = function.get("name")
523
+ if name != _VONS_TOOL_NAME:
524
+ raise OllamaToolCallError()
525
+ arguments = function.get("arguments")
526
+ if isinstance(arguments, str):
527
+ if len(arguments.encode("utf-8")) > _MAX_TOOL_ARGUMENT_BYTES:
528
+ raise OllamaToolCallError()
529
+ try:
530
+ arguments = json.loads(
531
+ arguments,
532
+ object_pairs_hook=_strict_json_object,
533
+ parse_constant=_reject_json_constant,
534
+ )
535
+ except (RecursionError, ValueError) as exc:
536
+ raise OllamaToolCallError() from exc
537
+ if not isinstance(arguments, Mapping) or any(not isinstance(key, str) for key in arguments):
538
+ raise OllamaToolCallError()
539
+ try:
540
+ encoded_arguments = json.dumps(
541
+ arguments, ensure_ascii=False, allow_nan=False, separators=(",", ":")
542
+ ).encode("utf-8")
543
+ except (RecursionError, TypeError, ValueError) as exc:
544
+ raise OllamaToolCallError() from exc
545
+ if len(encoded_arguments) > _MAX_TOOL_ARGUMENT_BYTES:
546
+ raise OllamaToolCallError()
547
+ return arguments
548
+
549
+ @staticmethod
550
+ def _validate_tool_arguments(arguments: Mapping[str, Any]) -> None:
551
+ allowed_root = {"state", "questions", "backend", "seed"}
552
+ if set(arguments) - allowed_root or not {"state", "questions"} <= set(arguments):
553
+ raise OllamaToolCallError()
554
+ questions = arguments.get("questions")
555
+ if not isinstance(questions, list):
556
+ raise OllamaToolCallError()
557
+ for question in questions:
558
+ if not isinstance(question, Mapping):
559
+ raise OllamaToolCallError()
560
+ allowed_question = {"id", "type", "prompt", "options", "rubric"}
561
+ if set(question) - allowed_question or not {
562
+ "id",
563
+ "type",
564
+ "prompt",
565
+ "options",
566
+ } <= set(question):
567
+ raise OllamaToolCallError()
568
+ if "seed" in arguments:
569
+ seed = arguments["seed"]
570
+ if isinstance(seed, bool) or not isinstance(seed, int) or not 0 <= seed <= _MAX_SEED:
571
+ raise OllamaToolCallError()
572
+
573
+ def _reconcile(self, request: DecisionRequest, response: DecisionResponse) -> None:
574
+ if (
575
+ not isinstance(response, DecisionResponse)
576
+ or response.backend is not request.backend
577
+ or not isinstance(response.model_id, str)
578
+ or not response.model_id.strip()
579
+ or not isinstance(response.metadata, Mapping)
580
+ ):
581
+ raise OllamaToolCallError()
582
+ try:
583
+ metadata_bytes = json.dumps(
584
+ response.metadata,
585
+ ensure_ascii=False,
586
+ allow_nan=False,
587
+ separators=(",", ":"),
588
+ ).encode("utf-8")
589
+ except (RecursionError, TypeError, ValueError):
590
+ raise OllamaToolCallError() from None
591
+ if len(metadata_bytes) > _MAX_TOOL_ARGUMENT_BYTES:
592
+ raise OllamaToolCallError()
593
+ if not isinstance(response.answers, tuple) or len(request.questions) != len(
594
+ response.answers
595
+ ):
596
+ raise OllamaToolCallError()
597
+ for question, answer in zip(request.questions, response.answers, strict=True):
598
+ if (
599
+ not isinstance(answer, QuestionAnswer)
600
+ or not isinstance(answer.question_id, str)
601
+ or question.id != answer.question_id
602
+ or not isinstance(answer.status, ResponseStatus)
603
+ ):
604
+ raise OllamaToolCallError()
605
+ if (
606
+ not isinstance(answer.confidence, (int, float))
607
+ or isinstance(answer.confidence, bool)
608
+ or not math.isfinite(answer.confidence)
609
+ or not 0 <= answer.confidence <= 1
610
+ ):
611
+ raise OllamaToolCallError()
612
+ options = question.options or ("true", "false")
613
+ if answer.status is ResponseStatus.OK:
614
+ if (
615
+ not isinstance(answer.choice, str)
616
+ or answer.choice not in options
617
+ or answer.abstain_reason is not None
618
+ ):
619
+ raise OllamaToolCallError()
620
+ elif (
621
+ answer.choice is not None
622
+ or not isinstance(answer.abstain_reason, str)
623
+ or not answer.abstain_reason.strip()
624
+ ):
625
+ raise OllamaToolCallError()
626
+ probabilities = answer.probabilities
627
+ if not isinstance(probabilities, tuple) or any(
628
+ not isinstance(item, OptionProbability) for item in probabilities
629
+ ):
630
+ raise OllamaToolCallError()
631
+ if probabilities and tuple(item.option for item in probabilities) != options:
632
+ raise OllamaToolCallError()
633
+ if answer.status is ResponseStatus.OK and not probabilities:
634
+ raise OllamaToolCallError()
635
+ if any(
636
+ isinstance(item.probability, bool)
637
+ or not isinstance(item.probability, (int, float))
638
+ or not math.isfinite(item.probability)
639
+ or not 0 <= item.probability <= 1
640
+ for item in probabilities
641
+ ):
642
+ raise OllamaToolCallError()
643
+ if probabilities and abs(sum(item.probability for item in probabilities) - 1.0) > 1e-6:
644
+ raise OllamaToolCallError()
645
+
646
+ @staticmethod
647
+ def _validate_messages(messages: Any) -> list[dict[str, str]]:
648
+ if (
649
+ not isinstance(messages, Sequence)
650
+ or isinstance(messages, (str, bytes, bytearray, Mapping))
651
+ or not 1 <= len(messages) <= _MAX_MESSAGES
652
+ ):
653
+ raise OllamaToolCallError()
654
+ validated: list[dict[str, str]] = []
655
+ total_chars = 0
656
+ for message in messages:
657
+ if not isinstance(message, Mapping) or set(message) != {"role", "content"}:
658
+ raise OllamaToolCallError()
659
+ role, content = message.get("role"), message.get("content")
660
+ if not isinstance(role, str) or role not in {"system", "user", "assistant"}:
661
+ raise OllamaToolCallError()
662
+ if not isinstance(content, str) or not content.strip():
663
+ raise OllamaToolCallError()
664
+ if len(content) > _MAX_MESSAGE_CONTENT_CHARS:
665
+ raise OllamaToolCallError()
666
+ total_chars += len(content)
667
+ validated.append({"role": role, "content": content})
668
+ if total_chars > _MAX_REQUEST_BYTES:
669
+ raise OllamaToolCallError()
670
+ return validated
671
+
672
+ def chat_with_tools(
673
+ self, model: str, messages: Sequence[Mapping[str, Any]], *, seed: int = 7
674
+ ) -> OllamaToolCallResult:
675
+ """Run one /api/chat turn advertising only the ``vons_decide`` tool.
676
+
677
+ The caller supplies the user/system messages. The host appends exactly one
678
+ tool definition (``vons_decide``). If the model replies with exactly
679
+ one matching tool call, its arguments are validated, the backend
680
+ runs, the response reconciles, and both halves are returned. In
681
+ every other case a sanitized error is returned; no backend runs.
682
+ """
683
+ if (
684
+ not isinstance(model, str)
685
+ or not model.strip()
686
+ or len(model) > _MAX_MODEL_NAME_CHARS
687
+ or any(ord(char) < 32 for char in model)
688
+ ):
689
+ err = OllamaToolCallError()
690
+ return OllamaToolCallResult(
691
+ model="",
692
+ error_id=err.error_id,
693
+ raw_ollama_response=None,
694
+ backend_result=None,
695
+ tool_invoked=False,
696
+ error=err,
697
+ )
698
+ try:
699
+ validated_messages = self._validate_messages(messages)
700
+ if isinstance(seed, bool) or not isinstance(seed, int) or not 0 <= seed <= _MAX_SEED:
701
+ raise OllamaToolCallError()
702
+ except OllamaToolCallError as err:
703
+ err = OllamaToolCallError()
704
+ return OllamaToolCallResult(
705
+ model=model,
706
+ error_id=err.error_id,
707
+ raw_ollama_response=None,
708
+ backend_result=None,
709
+ tool_invoked=False,
710
+ error=err,
711
+ )
712
+ payload: Mapping[str, Any] = {
713
+ "model": model,
714
+ "messages": validated_messages,
715
+ "tools": [dict(_VONS_DECIDE_TOOL_SCHEMA)],
716
+ "stream": False,
717
+ "options": {"temperature": 0, "seed": seed},
718
+ }
719
+ raw: Mapping[str, Any] | None = None
720
+ try:
721
+ raw = self._post("/api/chat", payload)
722
+ except OllamaToolCallError as err:
723
+ return OllamaToolCallResult(
724
+ model=model,
725
+ error_id=err.error_id,
726
+ raw_ollama_response=raw,
727
+ backend_result=None,
728
+ tool_invoked=False,
729
+ error=err,
730
+ )
731
+ if not isinstance(raw, Mapping):
732
+ err = OllamaToolCallError()
733
+ return OllamaToolCallResult(
734
+ model=model,
735
+ error_id=err.error_id,
736
+ raw_ollama_response=raw,
737
+ backend_result=None,
738
+ tool_invoked=False,
739
+ error=err,
740
+ )
741
+ message = raw.get("message")
742
+ if not isinstance(message, Mapping):
743
+ err = OllamaToolCallError()
744
+ return OllamaToolCallResult(
745
+ model=model,
746
+ error_id=err.error_id,
747
+ raw_ollama_response=raw,
748
+ backend_result=None,
749
+ tool_invoked=False,
750
+ error=err,
751
+ )
752
+ tool_calls = message.get("tool_calls")
753
+ if tool_calls is None:
754
+ return OllamaToolCallResult(
755
+ model=model,
756
+ error_id=None,
757
+ raw_ollama_response=raw,
758
+ backend_result=None,
759
+ tool_invoked=False,
760
+ error=None,
761
+ )
762
+ try:
763
+ arguments = self._parse_tool_call(message)
764
+ self._validate_tool_arguments(arguments)
765
+ normalized_arguments = dict(arguments)
766
+ normalized_arguments.setdefault("backend", self.backend.backend_type.value)
767
+ request = DecisionRequest.from_mapping(normalized_arguments)
768
+ validate_request(request)
769
+ except OllamaToolCallError as err:
770
+ return OllamaToolCallResult(
771
+ model=model,
772
+ error_id=err.error_id,
773
+ raw_ollama_response=raw,
774
+ backend_result=None,
775
+ tool_invoked=True,
776
+ error=err,
777
+ )
778
+ except (TypeError, ValueError):
779
+ err = OllamaToolCallError()
780
+ return OllamaToolCallResult(
781
+ model=model,
782
+ error_id=err.error_id,
783
+ raw_ollama_response=raw,
784
+ backend_result=None,
785
+ tool_invoked=True,
786
+ error=err,
787
+ )
788
+ try:
789
+ backend_response = self.backend.decide(request)
790
+ except Exception: # noqa: BLE001 - backend may raise arbitrary
791
+ err = OllamaToolCallError()
792
+ return OllamaToolCallResult(
793
+ model=model,
794
+ error_id=err.error_id,
795
+ raw_ollama_response=raw,
796
+ backend_result=None,
797
+ tool_invoked=True,
798
+ error=err,
799
+ )
800
+ try:
801
+ self._reconcile(request, backend_response)
802
+ except Exception: # noqa: BLE001 - malformed backend output fails closed
803
+ err = OllamaToolCallError()
804
+ return OllamaToolCallResult(
805
+ model=model,
806
+ error_id=err.error_id,
807
+ raw_ollama_response=raw,
808
+ backend_result=None,
809
+ tool_invoked=True,
810
+ error=err,
811
+ )
812
+ return OllamaToolCallResult(
813
+ model=model,
814
+ error_id=None,
815
+ raw_ollama_response=raw,
816
+ backend_result=backend_response,
817
+ tool_invoked=True,
818
+ error=None,
819
+ )
820
+
821
+
822
+ def tool_call_result_to_mapping(result: OllamaToolCallResult) -> dict[str, Any]:
823
+ backend = None
824
+ if result.backend_result is not None:
825
+ backend = result.backend_result.to_mapping()
826
+ return {
827
+ "model": result.model,
828
+ "error_id": result.error_id,
829
+ "tool_invoked": result.tool_invoked,
830
+ "raw_ollama_response": (
831
+ dict(result.raw_ollama_response) if result.raw_ollama_response is not None else None
832
+ ),
833
+ "backend_result": backend,
834
+ "error": result.error.sanitized() if result.error is not None else None,
835
+ }
vons/onnx_runtime.py ADDED
@@ -0,0 +1,537 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """ONNX-backed decision runtime with hash-verified bundles.
2
+
3
+ Host-owned runtime layer. The caller supplies a bundle directory with a valid
4
+ ``vons.bundle.manifest/v1`` manifest; this module verifies every recorded byte
5
+ before executing the graph and strictly validates request/response against the
6
+ public ``DecisionRequest`` / ``DecisionResponse`` contract.
7
+
8
+ Synthetic backends (``SyntheticAbstainBackend``, ``SyntheticChoiceBackend``)
9
+ exist for protocol testing and must never be used as substitutes for a verified
10
+ ONNX decision run.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import hashlib
16
+ import json
17
+ from abc import ABC, abstractmethod
18
+ from collections.abc import Mapping
19
+ from dataclasses import dataclass
20
+ from pathlib import Path
21
+ from typing import Any
22
+
23
+ from .bundle import verify_bundle_manifest
24
+ from .contract import (
25
+ Backend,
26
+ DecisionRequest,
27
+ DecisionResponse,
28
+ OptionProbability,
29
+ QuestionAnswer,
30
+ ResponseStatus,
31
+ validate_request,
32
+ )
33
+
34
+
35
+ class OnnxRuntimeError(RuntimeError):
36
+ """Raised when the ONNX runtime or bundle verification fails.
37
+
38
+ The message is intentionally generic. Callers must not echo exception data
39
+ or request payloads into shared logs.
40
+ """
41
+
42
+
43
+ class OnnxRuntimeUnavailableError(OnnxRuntimeError):
44
+ """Raised when an optional local inference dependency is unavailable."""
45
+
46
+
47
+ @dataclass(frozen=True)
48
+ class VerifiedBundle:
49
+ """A manifest-verified bundle directory, ready for inference."""
50
+
51
+ root: Path
52
+ manifest_path: Path
53
+ manifest: Mapping[str, Any]
54
+ model_id: str
55
+
56
+ @classmethod
57
+ def load(cls, bundle_dir: str | Path) -> VerifiedBundle:
58
+ try:
59
+ root = Path(bundle_dir).resolve(strict=True)
60
+ except (OSError, FileNotFoundError):
61
+ raise OnnxRuntimeError("bundle path does not exist") from None
62
+ if not root.is_dir():
63
+ raise OnnxRuntimeError("bundle path is not a directory")
64
+ manifest_path = None
65
+ for candidate in (
66
+ root / "bundle-manifest.json",
67
+ root / "bundle-manifest-v1.json",
68
+ ):
69
+ if not candidate.is_file():
70
+ continue
71
+ try:
72
+ candidate_payload = json.loads(candidate.read_text(encoding="utf-8"))
73
+ except (OSError, json.JSONDecodeError):
74
+ continue
75
+ if (
76
+ isinstance(candidate_payload, Mapping)
77
+ and candidate_payload.get("schema_version") == "vons.bundle.manifest/v1"
78
+ ):
79
+ manifest_path = candidate
80
+ break
81
+ if manifest_path is None:
82
+ raise OnnxRuntimeError("bundle manifest is missing")
83
+ try:
84
+ verification = verify_bundle_manifest(manifest_path)
85
+ except Exception: # noqa: BLE001 - normalize to sanitized form
86
+ raise OnnxRuntimeError("bundle manifest verification failed") from None
87
+ _ = verification # passed; record consumed, payload never echoed
88
+ try:
89
+ manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
90
+ if not isinstance(manifest, Mapping):
91
+ raise TypeError("bundle manifest must be an object")
92
+ model_id = hashlib.sha256(manifest_path.read_bytes()).hexdigest()
93
+ except (OSError, TypeError, ValueError):
94
+ raise OnnxRuntimeError("bundle manifest could not be read") from None
95
+ return cls(root=root, manifest_path=manifest_path, manifest=manifest, model_id=model_id)
96
+
97
+
98
+ class DecisionBackend(ABC):
99
+ """Strictly-typed decision backend.
100
+
101
+ Implementations validate request input against the public contract before
102
+ execution and validate every response field before returning to the host.
103
+ No backend may emit a fallback or coerced choice when validation fails.
104
+ """
105
+
106
+ backend_type: Backend
107
+
108
+ @abstractmethod
109
+ def decide(self, request: DecisionRequest) -> DecisionResponse:
110
+ """Execute a validated request and return a validated response."""
111
+
112
+ def _validate_request(self, request: DecisionRequest) -> None:
113
+ if not isinstance(request, DecisionRequest):
114
+ raise OnnxRuntimeError("invalid decision request type")
115
+ try:
116
+ validate_request(request)
117
+ except (TypeError, ValueError) as exc:
118
+ raise OnnxRuntimeError("decision request failed validation") from exc
119
+
120
+
121
+ class SyntheticAbstainBackend(DecisionBackend):
122
+ """Test-only backend that always abstains with a deterministic reason.
123
+
124
+ The reason byte is preserved exactly so protocol round-trips can be
125
+ asserted without running model weights.
126
+ """
127
+
128
+ backend_type = Backend.DIRECT
129
+
130
+ def __init__(self, abstain_reason: str = "synthetic backend requested abstention") -> None:
131
+ self.abstain_reason = abstain_reason
132
+
133
+ def decide(self, request: DecisionRequest) -> DecisionResponse:
134
+ self._validate_request(request)
135
+ answers = tuple(
136
+ QuestionAnswer(
137
+ question_id=question.id,
138
+ choice=None,
139
+ probabilities=(),
140
+ confidence=0.0,
141
+ status=ResponseStatus.ABSTAIN,
142
+ abstain_reason=self.abstain_reason,
143
+ )
144
+ for question in request.questions
145
+ )
146
+ return DecisionResponse(
147
+ answers=answers,
148
+ backend=self.backend_type,
149
+ model_id="synthetic-abstain-v1",
150
+ metadata={"synthetic": True},
151
+ )
152
+
153
+
154
+ class SyntheticChoiceBackend(DecisionBackend):
155
+ """Test-only backend that picks a fixed option by position.
156
+
157
+ Used to validate exact question-id reconciliation and response shape
158
+ without loading model weights. Callers set ``choice_index`` to a valid
159
+ position for every question in the request; ``ValueError`` is raised
160
+ when the index is out of range.
161
+ """
162
+
163
+ backend_type = Backend.DIRECT
164
+
165
+ def __init__(self, choice_index: int = 0, confidence: float = 0.9) -> None:
166
+ if not isinstance(choice_index, int) or choice_index < 0:
167
+ raise ValueError("choice_index must be a non-negative integer")
168
+ if not 0 <= confidence <= 1:
169
+ raise ValueError("confidence must be in [0, 1]")
170
+ self.choice_index = choice_index
171
+ self.confidence = float(confidence)
172
+
173
+ def decide(self, request: DecisionRequest) -> DecisionResponse:
174
+ self._validate_request(request)
175
+ answers: list[QuestionAnswer] = []
176
+ for question in request.questions:
177
+ options = question.options or ("true", "false")
178
+ if self.choice_index >= len(options):
179
+ raise OnnxRuntimeError("synthetic backend choice index out of range")
180
+ choice = options[self.choice_index]
181
+ probs: list[OptionProbability] = []
182
+ remaining = 1.0 - self.confidence
183
+ for i, option in enumerate(options):
184
+ if i == self.choice_index:
185
+ p = self.confidence
186
+ else:
187
+ p = remaining / max(1, len(options) - 1)
188
+ probs.append(OptionProbability(option=option, probability=float(p)))
189
+ answers.append(
190
+ QuestionAnswer(
191
+ question_id=question.id,
192
+ choice=choice,
193
+ probabilities=tuple(probs),
194
+ confidence=self.confidence,
195
+ status=ResponseStatus.OK,
196
+ )
197
+ )
198
+ return DecisionResponse(
199
+ answers=tuple(answers),
200
+ backend=self.backend_type,
201
+ model_id="synthetic-choice-v1",
202
+ metadata={"synthetic": True, "choice_index": self.choice_index},
203
+ )
204
+
205
+
206
+ class OnnxRuntimeBackend(DecisionBackend):
207
+ """Verified ONNX Runtime backend.
208
+
209
+ Requires the optional local-inference dependencies. The bundle is verified
210
+ byte-for-byte before the session is created. Tokenizer files are resolved
211
+ from the verified bundle only; remote tokenizer discovery is never used.
212
+ """
213
+
214
+ def __init__(
215
+ self,
216
+ bundle: VerifiedBundle,
217
+ *,
218
+ tokenizer: Any | None = None,
219
+ session: Any | None = None,
220
+ ) -> None:
221
+ if not isinstance(bundle, VerifiedBundle):
222
+ raise OnnxRuntimeError("ONNX backend requires a verified bundle")
223
+ self.bundle = bundle
224
+ metadata = bundle.manifest.get("metadata", {})
225
+ if not isinstance(metadata, Mapping):
226
+ raise OnnxRuntimeError("bundle runtime metadata is invalid")
227
+ try:
228
+ self.backend_type = Backend(metadata.get("backend", Backend.DIRECT.value))
229
+ except (TypeError, ValueError):
230
+ raise OnnxRuntimeError("bundle backend is unsupported") from None
231
+ if self.backend_type not in {Backend.DIRECT, Backend.DIFFUSION}:
232
+ raise OnnxRuntimeError("bundle backend is unsupported")
233
+ option_count = metadata.get("option_count", 32)
234
+ sequence_length = metadata.get("sequence_length", 512)
235
+ if (
236
+ isinstance(option_count, bool)
237
+ or not isinstance(option_count, int)
238
+ or not 2 <= option_count <= 32
239
+ or isinstance(sequence_length, bool)
240
+ or not isinstance(sequence_length, int)
241
+ or not 1 <= sequence_length <= 512
242
+ ):
243
+ raise OnnxRuntimeError("bundle inference dimensions are invalid")
244
+ self.option_count = option_count
245
+ self.sequence_length = sequence_length
246
+ self._metadata = metadata
247
+ self._tokenizer = tokenizer
248
+ self._session = session
249
+ self._input_names = self._string_tuple(metadata.get("input_names"), "input_names")
250
+ self._output_names = self._string_tuple(metadata.get("output_names"), "output_names")
251
+ self._abstain_threshold = self._threshold(metadata.get("abstain_threshold", 0.55))
252
+ self._answerability_threshold = self._threshold(
253
+ metadata.get("answerability_threshold", 0.5)
254
+ )
255
+ conditioning = metadata.get("diffusion_conditioning", "pooled")
256
+ if self.backend_type is Backend.DIFFUSION and conditioning not in {
257
+ "pooled",
258
+ "token_cross_attention",
259
+ }:
260
+ raise OnnxRuntimeError("bundle diffusion conditioning is unsupported")
261
+ self._diffusion_conditioning = conditioning
262
+
263
+ @staticmethod
264
+ def _string_tuple(value: Any, name: str) -> tuple[str, ...]:
265
+ if not isinstance(value, (list, tuple)) or any(
266
+ not isinstance(item, str) or not item for item in value
267
+ ):
268
+ raise OnnxRuntimeError(f"bundle {name} is invalid")
269
+ if len(value) != len(set(value)):
270
+ raise OnnxRuntimeError(f"bundle {name} contains duplicates")
271
+ return tuple(value)
272
+
273
+ @staticmethod
274
+ def _threshold(value: Any) -> float:
275
+ if isinstance(value, bool) or not isinstance(value, (int, float)):
276
+ raise OnnxRuntimeError("bundle decision threshold is invalid")
277
+ result = float(value)
278
+ if not 0.0 <= result <= 1.0:
279
+ raise OnnxRuntimeError("bundle decision threshold is invalid")
280
+ return result
281
+
282
+ @staticmethod
283
+ def _numpy() -> Any:
284
+ try:
285
+ import numpy as np
286
+ except ImportError as exc: # pragma: no cover - depends on optional install
287
+ raise OnnxRuntimeUnavailableError("numpy is not installed") from exc
288
+ return np
289
+
290
+ def _tokenizer_path(self, *, suffix: str) -> Path:
291
+ files = self.bundle.manifest.get("files", ())
292
+ if not isinstance(files, (list, tuple)):
293
+ raise OnnxRuntimeError("bundle tokenizer inventory is invalid")
294
+ candidates = [
295
+ item
296
+ for item in files
297
+ if isinstance(item, Mapping)
298
+ and item.get("role") == "tokenizer"
299
+ and isinstance(item.get("path"), str)
300
+ and str(item["path"]).endswith(suffix)
301
+ ]
302
+ if len(candidates) != 1:
303
+ raise OnnxRuntimeError("bundle tokenizer file is missing or ambiguous")
304
+ try:
305
+ path = (self.bundle.root / str(candidates[0]["path"])).resolve(strict=True)
306
+ path.relative_to(self.bundle.root.resolve(strict=True))
307
+ except (OSError, ValueError):
308
+ raise OnnxRuntimeError("bundle tokenizer path escapes the bundle") from None
309
+ if not path.is_file():
310
+ raise OnnxRuntimeError("bundle tokenizer file is missing")
311
+ return path
312
+
313
+ def _require_tokenizer(self) -> Any:
314
+ if self._tokenizer is not None:
315
+ return self._tokenizer
316
+ try:
317
+ from tokenizers import Tokenizer
318
+ except ImportError as exc: # pragma: no cover - depends on optional install
319
+ raise OnnxRuntimeUnavailableError("tokenizers is not installed") from exc
320
+ tokenizer_path = self._tokenizer_path(suffix="tokenizer.json")
321
+ config_path = self._tokenizer_path(suffix="tokenizer_config.json")
322
+ try:
323
+ config = json.loads(config_path.read_text(encoding="utf-8"))
324
+ raw_tokenizer = Tokenizer.from_file(str(tokenizer_path))
325
+ pad_token = self._special_token_content(config.get("pad_token"))
326
+ cls_token = self._special_token_content(config.get("cls_token"))
327
+ pad_token_id = raw_tokenizer.token_to_id(pad_token) if pad_token else None
328
+ cls_token_id = raw_tokenizer.token_to_id(cls_token) if cls_token else None
329
+ except Exception: # noqa: BLE001 - sanitize third-party errors
330
+ raise OnnxRuntimeError("bundle tokenizer could not be loaded") from None
331
+ if pad_token_id is None or cls_token_id is None:
332
+ raise OnnxRuntimeError("bundle tokenizer is missing required special tokens")
333
+ self._tokenizer = _LocalTokenizer(raw_tokenizer, pad_token_id, cls_token_id)
334
+ return self._tokenizer
335
+
336
+ @staticmethod
337
+ def _special_token_content(value: Any) -> str | None:
338
+ if isinstance(value, str):
339
+ return value
340
+ if isinstance(value, Mapping) and isinstance(value.get("content"), str):
341
+ return value["content"]
342
+ return None
343
+
344
+ def _validate_session_contract(self, session: Any) -> None:
345
+ try:
346
+ input_names = {item.name for item in session.get_inputs()}
347
+ output_names = {item.name for item in session.get_outputs()}
348
+ except Exception: # noqa: BLE001 - sanitize third-party errors
349
+ raise OnnxRuntimeError("ONNX session metadata is unavailable") from None
350
+ if not self._input_names or input_names != set(self._input_names):
351
+ raise OnnxRuntimeError("ONNX graph inputs disagree with the verified manifest")
352
+ if not self._output_names or output_names != set(self._output_names):
353
+ raise OnnxRuntimeError("ONNX graph outputs disagree with the verified manifest")
354
+ expected_inputs = {
355
+ "input_ids",
356
+ "attention_mask",
357
+ "token_type_ids",
358
+ "option_mask",
359
+ }
360
+ if self.backend_type is Backend.DIFFUSION:
361
+ expected_inputs.add("initial_noise")
362
+ if input_names != expected_inputs:
363
+ raise OnnxRuntimeError("ONNX graph input contract is unsupported")
364
+ score_name = "logits" if self.backend_type is Backend.DIRECT else "scores"
365
+ if output_names != {score_name, "answerability"}:
366
+ raise OnnxRuntimeError("ONNX graph output contract is unsupported")
367
+
368
+ def prepare(self) -> None:
369
+ """Load all local runtime dependencies before a client request is sent."""
370
+ self._numpy()
371
+ self._require_tokenizer()
372
+ self._validate_session_contract(self._require_session())
373
+
374
+ def _require_session(self) -> Any:
375
+ if self._session is not None:
376
+ return self._session
377
+ try:
378
+ import onnxruntime as ort # type: ignore[import-not-found]
379
+ except ImportError as exc: # pragma: no cover - depends on optional install
380
+ raise OnnxRuntimeUnavailableError("onnxruntime is not installed") from exc
381
+ graph_item = None
382
+ for item in self.bundle.manifest.get("files", ()):
383
+ if isinstance(item, Mapping) and item.get("role") == "model_graph":
384
+ graph_item = item
385
+ break
386
+ if graph_item is None:
387
+ raise OnnxRuntimeError("bundle has no model_graph entry")
388
+ try:
389
+ graph_path = (self.bundle.root / str(graph_item["path"])).resolve(strict=True)
390
+ graph_path.relative_to(self.bundle.root.resolve(strict=True))
391
+ except (OSError, ValueError):
392
+ raise OnnxRuntimeError("bundle graph path is invalid") from None
393
+ if not graph_path.is_file():
394
+ raise OnnxRuntimeError("bundle graph file is missing")
395
+ try:
396
+ self._session = ort.InferenceSession(
397
+ str(graph_path), providers=["CPUExecutionProvider"]
398
+ )
399
+ self._validate_session_contract(self._session)
400
+ except OnnxRuntimeError:
401
+ raise
402
+ except Exception: # noqa: BLE001 - sanitize third-party errors
403
+ raise OnnxRuntimeError("ONNX session could not be created") from None
404
+ return self._session
405
+
406
+ def decide(self, request: DecisionRequest) -> DecisionResponse:
407
+ self._validate_request(request)
408
+ if request.backend is not self.backend_type:
409
+ raise OnnxRuntimeError("request backend does not match the verified bundle")
410
+ try:
411
+ from .inference import prepare_question_tensors
412
+
413
+ np = self._numpy()
414
+ tokenizer = self._require_tokenizer()
415
+ session = self._require_session()
416
+ self._validate_session_contract(session)
417
+ score_name = "logits" if self.backend_type is Backend.DIRECT else "scores"
418
+ answers: list[QuestionAnswer] = []
419
+ for question_index, question in enumerate(request.questions):
420
+ padded, _ = prepare_question_tensors(
421
+ tokenizer,
422
+ request,
423
+ question,
424
+ option_count=self.option_count,
425
+ max_sequence_budget=self.sequence_length,
426
+ )
427
+ feed: dict[str, Any] = {
428
+ "input_ids": np.asarray(padded.input_ids, dtype=np.int64)[None, :, :],
429
+ "attention_mask": np.asarray(padded.attention_mask, dtype=np.int64)[None, :, :],
430
+ "token_type_ids": np.asarray(padded.token_type_ids, dtype=np.int64)[None, :, :],
431
+ "option_mask": np.asarray(padded.option_mask, dtype=np.bool_)[None, :],
432
+ }
433
+ if self.backend_type is Backend.DIFFUSION:
434
+ seed = None if request.seed is None else request.seed + question_index
435
+ rng = np.random.default_rng(seed)
436
+ feed["initial_noise"] = rng.standard_normal(
437
+ (1, padded.allocated_candidates), dtype=np.float32
438
+ )
439
+ outputs = session.run(list(self._output_names), feed)
440
+ if not isinstance(outputs, (list, tuple)) or len(outputs) != len(
441
+ self._output_names
442
+ ):
443
+ raise OnnxRuntimeError("ONNX graph returned an invalid output list")
444
+ output_map = dict(zip(self._output_names, outputs, strict=True))
445
+ scores = np.asarray(output_map[score_name], dtype=np.float64)
446
+ raw_answerability = np.asarray(output_map["answerability"], dtype=np.float64)
447
+ live_options = question.options or ("true", "false")
448
+ if scores.shape != (1, padded.allocated_candidates):
449
+ raise OnnxRuntimeError("ONNX graph returned invalid score dimensions")
450
+ if raw_answerability.size != 1:
451
+ raise OnnxRuntimeError("ONNX graph returned invalid answerability")
452
+ live_scores = scores[0, : len(live_options)]
453
+ if not np.isfinite(live_scores).all() or not np.isfinite(raw_answerability).all():
454
+ raise OnnxRuntimeError("ONNX graph returned non-finite scores")
455
+ shifted = live_scores - np.max(live_scores)
456
+ exp_scores = np.exp(shifted)
457
+ probabilities = exp_scores / exp_scores.sum()
458
+ answerability_logit = float(raw_answerability.reshape(-1)[0])
459
+ if answerability_logit >= 0:
460
+ answerability = 1.0 / (1.0 + np.exp(-answerability_logit))
461
+ else:
462
+ exp_logit = np.exp(answerability_logit)
463
+ answerability = exp_logit / (1.0 + exp_logit)
464
+ choice_index = int(np.argmax(probabilities))
465
+ max_probability = float(probabilities[choice_index])
466
+ confidence = max_probability * float(answerability)
467
+ abstain = (
468
+ confidence < self._abstain_threshold
469
+ or answerability < self._answerability_threshold
470
+ )
471
+ answers.append(
472
+ QuestionAnswer(
473
+ question_id=question.id,
474
+ choice=None if abstain else live_options[choice_index],
475
+ probabilities=tuple(
476
+ OptionProbability(
477
+ option=option, probability=float(probabilities[index])
478
+ )
479
+ for index, option in enumerate(live_options)
480
+ ),
481
+ confidence=confidence,
482
+ status=ResponseStatus.ABSTAIN if abstain else ResponseStatus.OK,
483
+ abstain_reason=(
484
+ "below configured local decision threshold" if abstain else None
485
+ ),
486
+ )
487
+ )
488
+ return DecisionResponse(
489
+ answers=tuple(answers),
490
+ backend=self.backend_type,
491
+ model_id=self.bundle.model_id,
492
+ metadata={"verified_bundle_sha256": self.bundle.model_id},
493
+ )
494
+ except OnnxRuntimeError:
495
+ raise
496
+ except Exception: # noqa: BLE001 - sanitize tokenizer/ORT failures
497
+ raise OnnxRuntimeError("local ONNX inference failed") from None
498
+
499
+
500
+ @dataclass(frozen=True)
501
+ class _LocalEncoding:
502
+ ids: list[int]
503
+ attention_mask: list[int]
504
+ token_type_ids: list[int]
505
+
506
+
507
+ class _LocalTokenizer:
508
+ """Small adapter from the bundled Rust tokenizer to Vons tensor preparation."""
509
+
510
+ def __init__(self, tokenizer: Any, pad_token_id: int, cls_token_id: int) -> None:
511
+ self._tokenizer = tokenizer
512
+ self.pad_token_id = pad_token_id
513
+ self.cls_token_id = cls_token_id
514
+
515
+ def encode(
516
+ self,
517
+ text: str,
518
+ *,
519
+ add_special_tokens: bool = True,
520
+ truncation: bool = False,
521
+ max_length: int = 512,
522
+ **_: Any,
523
+ ) -> _LocalEncoding:
524
+ if not isinstance(text, str):
525
+ raise TypeError("tokenizer input must be text")
526
+ if truncation:
527
+ self._tokenizer.enable_truncation(max_length=max_length)
528
+ try:
529
+ encoded = self._tokenizer.encode(text, add_special_tokens=add_special_tokens)
530
+ finally:
531
+ if truncation:
532
+ self._tokenizer.no_truncation()
533
+ return _LocalEncoding(
534
+ ids=list(encoded.ids),
535
+ attention_mask=list(encoded.attention_mask),
536
+ token_type_ids=list(encoded.type_ids),
537
+ )