`@vons/decision-sdk`

The TypeScript package mirrors the Vons Python request/response contract and keeps KASI policy and execution in the host. It contains no tool executor and does not treat a model-produced risk or confidence value as permission.

The contract-only entry point remains small, while the optional ./onnx subpath uses pinned onnxruntime-web@1.30.0 and @huggingface/tokenizers@0.2.0 for local browser inference. Applications provide a model backend through DecisionBackend; the runtime helper verifies bundle bytes, uses the declared WASM or WebGPU provider, and does not silently fall back from an unavailable accelerator. callFingerprint returns a canonical JSON consent key. Hosts that persist consent for the Python adapter should SHA-256 this key before storage so the cross-language fingerprint format remains identical.

Node 22+ can load the source directly with its TypeScript type stripping during early development. A release build should type-check and bundle the package with the consuming application's toolchain.

The local smoke harness covers both pilot bundles and both providers. Build it and serve the repository root so the browser can fetch the ignored ORT runtime files and the existing pilot artifacts:

npm ci
npm run build:browser
cd ../..
python3 -m http.server 8765 --bind 127.0.0.1

Open http://127.0.0.1:8765/sdk/typescript/demo/. The smoke page reports session-load and one-request timings, optional Chromium JS-heap observations, provider evidence, and the contract response. These are diagnostic smoke values, not the repeated benchmark protocol.

Source preview

For a UI that does not require serving the development workspace, build the Chrome side-panel extension with npm run build:extension. It packages the runtime locally and accepts a user-selected, hash-verified model folder. The guide explains installation and the separate model requirement.

MCP stdio server (local-only, ONNX runtime backend)

This SDK ships a small, local-only Model Context Protocol (MCP) stdio server in src/mcp.ts and src/mcp-cli.ts. It is strictly for hosts that already have a user-supplied, hash-verified ONNX decision bundle on the local filesystem. The server uses these exact, pinned npm dependencies:

@modelcontextprotocol/server 2.1.0
zod 4.6.5

What it exposes

Exactly one MCP tool and one read-only MCP resource:

Tool: vons_decide — takes a strict DecisionRequest JSON object mirroring the shared contract (state, questions[], optional backend, optional non-negative integer seed), validates it through the shared validateRequest → DecisionBackend.decide → validateResponse pipeline, and returns a JSON-serialized DecisionResponse as a single MCP text content item. Malformed inputs raise an explicit MCP application error; no fake choice, no silent fallback, and no coerced success. Explicit abstentions (status=abstain, choice=null, abstain_reason) round-trip exactly as returned by the backend.
Resource: vons://bundle/manifest/metadata — non-sensitive metadata only. Returns schema_version, backend, model_id (if declared), option_count, and sequence_length. No local filesystem path is emitted. Never includes file bytes, file hashes, tokenizer contents, graph data, or runtime asset digests.

What it explicitly does NOT do

Per the Vons pilot scope and AGENTS.md host boundary:

No HTTP listener, no network, no remote MCP service.
Writes MCP JSON-RPC messages only to stdout.
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.
Never executes downstream tools, never authorizes actions, never runs host-side tooling.
Never performs silent fallback decisions or substitutes a fake choice when the input is invalid or the backend fails.
No auto-discovery of bundles, no search for manifests, no default paths. The user must pass an explicit --bundle <dir>.
No request contents, response contents, or manifest asset hashes are ever written to any file, network, or stderr log line outside the MCP stdout JSON-RPC channel.

CLI usage

node --experimental-strip-types sdk/typescript/src/mcp-cli.ts --bundle <dir> \
  [--manifest-sha256 <64-char-hex>] [--provider wasm|webgpu]

--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.

Codex project-local stdio setup example

Create or edit config.toml in the Codex project's .codex/ directory (or its equivalent config location for your workspace):

[mcp_servers.vons]
command = "node"
args = [
  "--experimental-strip-types",
  "/absolute/path/to/Vons/sdk/typescript/src/mcp-cli.ts",
  "--bundle",
  "/absolute/path/to/user-supplied-hash-verified-vons-bundle",
  # Optional: remove these two arguments to skip pinning; otherwise replace the placeholder.
  "--manifest-sha256",
  "<64-char-lowercase-manifest-sha256>"
]

The host is responsible for consent, validation, and execution around this server.

Claude Code project-local stdio setup example

Create or edit .mcp.json in the project root. Remove the optional flag/value pair to skip pinning; otherwise replace the placeholder with the lowercase SHA-256 of bundle-manifest-v1.json before use.

{
  "mcpServers": {
    "vons": {
      "command": "node",
      "args": [
        "--experimental-strip-types",
        "/absolute/path/to/Vons/sdk/typescript/src/mcp-cli.ts",
        "--bundle",
        "/absolute/path/to/user-supplied-hash-verified-vons-bundle",
        "--manifest-sha256",
        "<64-char-lowercase-manifest-sha256>",
        "--provider",
        "wasm"
      ]
    }
  }
}

Both examples assume Node 22+ is on PATH and that the bundle directory was previously verified by the host. The CLI starts in stdio protocol mode and never forks an HTTP listener.

Filesystem loader (strict)

The CLI --bundle <dir> argument accepts local directory paths (including shell-resolved relative forms like ../my-bundle), then realpath-resolves the selected root before opening. URL schemes such as https://, http://, or file:// are rejected for --bundle itself. After the bundle root is resolved, the manifest loader in mcp.ts applies the following strict checks to each manifest-declared relative file path and to the bundle manifest itself:

URLs (https://, http://, file://, data://, ftp://)
Absolute paths and /-rooted file paths
Any occurrence of .., including URL-encoded %2e%2e or similar
Windows drive letters and backslashes
Query strings (?) or fragments (#)
Symlinks or real paths that escape the realpath()-resolved bundle root

Declared files must also match entries inside a vons.bundle.manifest/v1 manifest named bundle-manifest-v1.json. Unknown, duplicate, or non-existent declared files abort the server start with a clear error and exit code 3.

This package is private in npm metadata until an npm release is requested. Its files allowlist includes source, this guide and the software license. Models, tokenizers, datasets, generated demo JavaScript and dependencies are intentionally excluded from the public source export. Build the demos locally and supply your own reviewed model bundles before opening the smoke, benchmark or parity pages.

The Vons Community and Commercial License 1.0 permits qualifying noncommercial use without a fee. Enterprise and other commercial use require a separate written agreement; contact oswarld@inlevel9.com. This is source-available software. Dependencies retain their own terms, and the research articles' CC BY 4.0 license does not grant commercial SDK rights.