Capability Package Specification

The formal standard for OOMU capability packages (.oomu Mods). This is reference material; for a walkthrough see Building a Custom Capability Package.

• Manifest schema id: https://oomu.ai/schemas/mod-manifest-v1.json
• Archive format: ZIP
• File extension: .oomu

---

1. Archive format

A capability package is a standard ZIP archive with the .oomu extension. OOMU reads it directly; no other container format is accepted.

1.1 Layout

<package>.oomu              (ZIP archive)
├── manifest.json           (required, MUST be at the archive root)
└── <entrypoint>            (e.g. engine.wasm - referenced by manifest.entrypoint)

• manifest.json must be a top-level entry in the archive. It is not searched for in subdirectories.
• The entrypoint file named by manifest.entrypoint should be present in the archive.
• Additional supporting files (e.g. README.md, LICENSE, reference data) may be included, subject to the limits below.

1.2 Archive limits

OOMU validates these on install and rejects packages that exceed them:

Compression uses the standard ZIP deflate method. The archive's central directory is parsed to enumerate and validate entries before any extraction occurs.

1.3 Installation behaviour

On install, OOMU:

1. Confirms the file is a valid .oomu ZIP archive within the limits above.
2. Reads and parses manifest.json from the archive root.
3. Extracts the contents into a staging directory inside the user's private mods folder.
4. Atomically promotes the staging directory to the final install location (a failed install leaves no partial state).
5. Records the capability in the local installed_mods table (see Local Database Schema).

Installing a package whose id matches an already-installed Mod upgrades it in place.

---

2. Manifest reference (manifest.json)

A JSON object. Field names are as written below.

2.1 Example

{
  "$schema": "https://oomu.ai/schemas/mod-manifest-v1.json",
  "id": "ai.eldris.mods.pundamentals",
  "name": "Pundamentals",
  "version": "1.0.0",
  "author": "Eldris AI Engineering",
  "description": "Forces every active agent session to formulate contextually relevant puns.",
  "min_host_version": "0.1.0",
  "entrypoint": "engine.wasm",
  "permissions": {},
  "hooks": {
    "shield_gate": {
      "on_prompt": "on_prompt_intercept"
    }
  },
  "default_system_prompt": "You are OOMU, acting with the Pundamentals Mod active. ..."
}

2.2 Fields

Unknown top-level fields are ignored, so forward-compatible additions won't break installation. The permissions object is the exception; it is validated strictly (see §2.3).

2.3 permissions

The permissions field is a structured object declaring the folders and hosts the Mod may reach. OOMU enforces these at runtime: the Mod's engine cannot access a path or host it did not declare.

"permissions": {
  "allowed_paths": ["/Users/shared/house-style"],
  "allowed_hosts": ["style.example.com", "https://api.example.com"]
}

Validation rules:

• The object accepts only these two keys. Any other key causes the manifest to be rejected (deny_unknown_fields).
• allowed_paths entries must be absolute paths. At runtime, a target path is canonicalised (symlinks resolved) and access is granted only if it sits inside a declared prefix. Relative prefixes are rejected.
• allowed_hosts entries must be a bare hostname (api.example.com) or an absolute origin (https://api.example.com). They must not include a path, query string, or fragment. At runtime the requested endpoint must use http/https and its host must match a declared entry (case-insensitive, trailing-dot normalised).
• If permissions is omitted or {}, the Mod is granted no file or network access and can only shape assistant responses (via default_system_prompt/hooks).

Display vs. enforcement. The install screen presents the declared paths and hosts to the user as permissions they're agreeing to. The same declarations are what OOMU enforces at runtime; there is no gap between what the user sees and what the Mod can do.

Note on legacy manifests. Earlier drafts used a free-form { label: detail } permissions map. That form is no longer parsed into access grants; use the structured allowed_paths / allowed_hosts object.

2.4 hooks

hooks declares the integration points where the Mod participates. Each hook value names a function inside the Mod's engine that OOMU invokes at the relevant moment.

Currently recognised:

"hooks": {
  "shield_gate": {
    "on_prompt": "on_prompt_intercept"
  }
}

• shield_gate.on_prompt; names the function that runs when a prompt is intercepted by OOMU's safety gate, allowing the Mod to participate before a prompt is processed.

The presence of a shield_gate hook is also used to infer the Mod's category when category is not set explicitly.

---

3. How a Mod takes effect

An installed Mod influences a conversation only when both conditions hold:

1. The Mod's global active state is on (is_active), and
2. The Mod is bound to the active assistant.

When active and bound, OOMU injects the Mod's default_system_prompt and any declared hooks into the turn as an active runtime contract: the assistant is instructed to treat the Mod's declared behaviour as live behaviour to perform, not descriptive metadata, while preserving safety and the agent's persona. Deactivating the Mod globally, or unbinding it from the assistant, disables its effect without uninstalling it.

Hook functions (such as shield_gate.on_prompt) are registered into a background hook registry when the Mod is active, and refreshed as Mods are installed, activated, or removed.

---

3a. Signed capability bundles

The .oomu manifest above is the foundation. A capability bundle extends it into a distributable package that can carry more than a single engine; while treating every external package as untrusted supply-chain input. Existing Mods remain valid and migrate through one adapter; bundles are not a second package system.

What a bundle can carry

Beyond the base manifest, a bundle may declare and include:

• Skills / instructions; reusable prompt and behaviour content.
• Connector declarations; the services the bundle expects.
• Task recipes; reviewed, versioned methods (see adaptive learning).
• Specialist-agent profiles; assistant roles the bundle installs.
• Assets / templates and tests, plus migration metadata.

Declared capabilities

A bundle must declare each capability class it uses, explicitly. Anything not declared is denied at runtime. The classes cover file, network, connector, model, executable, schedule, child-agent, and mutation access.

Provenance vs. review; kept separate

Sideloaded bundles are allowed but carry an explicit "not reviewed" warning and require a trust acknowledgement.

Installation and runtime enforcement

• Verified before activation: signature, publisher identity, hashes, dependency locks, minimum OOMU version, forbidden paths, and absence of hidden executable content.
• Diff and scope shown first: a human-readable capability diff and the Projects the bundle will apply to. A bundle enabled for a Project cannot broaden global grants or reach another Project.
• Transactional install: quarantine → verify → promote, with rollback, disable, and uninstall, and a retained audit receipt (capability_bundle_receipts).
• Fail closed at runtime: a request for an undeclared or revoked capability is blocked and recorded (capability_runtime_denials) with the exact mismatch.

Curated registry entries (capability_registry_entries) carry signed catalog metadata, compatibility, changelog, installed version, and revocation notices; with curation status and cryptographic signing presented as separate facts.

---

4. Validation failure reference

Common reasons a package is rejected on install:

---

Related

• Building a Custom Capability Package: the hands-on guide.
• Local Database Schema: the installed_mods table where packages are recorded.
• Privacy & Sandboxing: the containment model your package runs inside.