Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

Extension packs

extension-pack.v1 (proposed, ADR 0067; built): one installable unit over the existing carriers (tool-pack archives, inline files by sha256, hashed assets); extension-pack.toml (pending hashes, per-component from) and the extension-pack.json record share one shape; crates/extension_pack holds the one validator the CLI and the gateway call (unknown fields, closed kinds, categories, steps and capabilities, contract ranges, trust rules, inline hashes and sizes) and lists held components with their reasons; vulpine pack check and vulpine pack build run offline, the build is reproducible and prints the tools index packs[] entry.

Living doc, checked against the code 2026-11-14

extension-pack.v1 — one installable unit over the existing carriers: the manifest, its record and the one validator

  • Status: accepted with ADR 0067, version 1.0. Built:
    • the types, the validator, contract ranges and the record writer, in crates/extension_pack;
    • vulpine pack check and vulpine pack build, in crates/vulpine_cli/src/ext_pack_verbs.rs;
    • the tools index’s packs[] array, in crates/vulpine_cli/src/pack.rs;
    • the Admin protocol and the gateway’s pack manager (crates/voice_gateway/src/packs/: the registry, receipts, the closed steps, the second catalog root), behind [packs] enabled = false. Its verify step runs this validator on a built record from a local folder.

The folder

path what
extension-pack.toml the source: the manifest below, with pending: hashes and, per component, an optional from
extension-pack.json the record vulpine pack build writes: the same fields, every computable hash filled, no from
<component id>/<path> each inline file a component lists (a source may read it from <from>/<path> instead)
<archive> a tool-pack.v1 archive a tool-pack component names, when it is present

from is a path relative to the pack’s folder, so a first-party source under packs/<id>/ can name a component where it lives (from = "../../catalog/hardpoints/mynah-nemotron"). The build copies every inline file to <component id>/<path> in its out folder (default <dir>/dist), so a built folder is self-contained and checks as a record. A symlink is never read.

The manifest

The validator holds the manifest’s fields to these rules:

rule refuses with
a field the v1 shape does not name, at any level unknown_field:<name> or unknown_field:<component>.<name>
schema is vulpine.extension-pack.v1; id is ^[a-z][a-z0-9-]{1,47}$ and not a built-in’s (core) schema, id_invalid, id_collision:pack
version, min_gateway are x.y.z; title 1-48 characters, summary 1-200; license set semver:<field>, title, summary, license
category, publisher (first_party, local), targets, requires tokens, capabilities, approval from their closed sets category, publisher, targets, requires:<token>, capability_unknown, approval
model_load is ask (installing never loads a model) model_load
every [contracts] range and [[depends]] range is >= M.m, < N range_invalid:<name>
[steps] names only the closed step set; no phase beyond install, enable, remove step_not_allowed:<phase>:<step>, unknown_field:steps.<phase>
a component’s kind is known and its carrier is its kind’s kind_unknown:<id>, carrier:<id>
a component’s contract is declared in [contracts] with the same range (none only for a model) contract_not_declared:<id>, contract_missing:<id>
a local pack reuses no bundled catalog id id_collision:<id>
a pi_extension is never in a local pack, targets pane (with pane_hosts in targets) or brain pi_extension_in_local_pack:<id>, target:<id>, target_undeclared:<id>
with audio_in in the pack’s capabilities, every hardpoint, helper and engine is local_only audio_in_not_local_only:<id>
a voice is consent = "required" and local_only voice_consent:<id>
an asset has bytes, license, sources (https://<fetch_host>/…, reach:fleet, hf-cache) and blake3 with a reach: source asset_bytes, asset_license, asset_sources, source_form, fetch_host_undeclared:<id>:<host>, asset_blake3
a tool-pack component names <…>.tar.gz and its sha256 archive:<id>, hash_form:<id>.sha256
hashes are sha256:<64 hex> (or blake3:), or pending:ci / pending:owner hash_form:<id>/<path>
an inline file is present (when its hash is stated), matches its sha256, is under 1 MiB, is not a Mach-O; a pack’s inline files under 8 MiB file_missing, file_sha256_mismatch, inline_file_too_large, inline_macho, inline_pack_too_large
a record carries no from from_in_record:<id>

A component this build cannot open installs held, never half working: a contract outside THIS_BUILD_SPEAKS (contract_unsupported), the kinds avatar, look and herdr_plugin, and a brain-side pi_extension. A first-party component whose id is still in the bundled catalog gets a note.

vulpine pack check and vulpine pack build

vulpine pack check <dir|extension-pack.toml|extension-pack.json> [--catalog <repo>] [--json]
vulpine pack build <dir> [--out <folder>] [--url-base <url>] [--catalog <repo>] [--json]
  • check runs the validator on a source or a record and its folder. The report, vulpine.extension-pack-check.v1, lists refusals ({reason, subject}), held ({component, reason, detail}) and notes.
  • build checks the source, fills every hash it can compute (inline files, an archive present), checks the result as a record against the out folder and writes it atomically. The same source gives the same bytes. Its report, vulpine.extension-pack-build.v1, carries the record’s sha256, what is still pending: and the packs[] entry.
  • The bundled catalog’s ids come from --catalog, else VULPINE_REPO, else the checkout holding the folder; without one, the collision check is skipped and a note says so.
  • Exit codes: 0 ok, 1 refused (or the manifest does not parse), 2 I/O, 64 usage.

The tools index’s packs[]

vulpine.tools-index.v1 has an optional packs array; an older reader ignores it. Each entry: id, version, category, publisher (first_party only; local packs are never listed), title, summary, url (the record’s; its files sit beside it, <id>/<version>/extension-pack.json under the release base), sha256 and size of the record, min_gateway, license, capabilities, egress, approval. An (id, version) listed twice refuses the index. A revoked[] entry names a pack by its id. The index is signed as tool-pack.v1 signs it.

Versions

A v1 reader refuses an unknown field. A pack that needs a new field raises min_gateway. A new category, kind or step is a minor revision of this contract and of THIS_BUILD_SPEAKS.

Was this page helpful?