@framers/agentos-extensions-registry

Extension catalog for AgentOS — metadata, query helpers, and createCuratedManifest() factory.

What this package is

This is the catalog and SDK for AgentOS extensions. It does not contain extension source code — it provides:

• Static metadata catalogs (CHANNEL_CATALOG, TOOL_CATALOG, PROVIDER_CATALOG) describing every known extension: its name, package, SDK, required secrets, and capabilities.
• Query helpers (getChannelEntry(), getToolEntry(), getProviderEntry()) for looking up catalog entries at runtime.
• Dynamic loader (createCuratedManifest()) that resolves which extension packages are actually installed, then builds an ExtensionManifest the AgentOS runtime can consume.

Architecture: catalog vs. source code

Dependency direction: this package depends on @framers/agentos for runtime types (peer dep) and references extension packages from @framers/agentos-extensions as optional dependencies. Only installed extensions are loaded; missing packages are silently skipped.

Lazy and optional by design

The catalog and the runtime are decoupled on purpose. The four DI layers below operate independently, so a host pays for exactly what it installs and uses.

Layer 1: optional peerDependenciesMeta per extension

Every catalog entry in CHANNEL_CATALOG, TOOL_CATALOG, and PROVIDER_CATALOG references its npm package by name only. This package does not import them eagerly. peerDependenciesMeta.optional: true keeps npm install from pulling extension source unless the host explicitly adds the package to its own package.json.

Layer 2: import.meta.resolve() skips uninstalled packages at manifest build

createCuratedManifest() walks the requested filter (tools: 'all' | string[] | 'none', channels: ...) and calls import.meta.resolve(packageName) per entry. Failures are swallowed; the entry is dropped from the output manifest. The runtime never sees an unresolvable pack. getAvailableExtensions() and getAvailableChannels() expose this resolution state for hosts that want to surface installed extensions in their own UI or logs.

Layer 3: per-extension requiredSecrets in catalog metadata

CHANNEL_CATALOG and TOOL_CATALOG entries declare which secret keys an extension expects (mapped to environment variables via SECRET_ENV_MAP). When the runtime activates a descriptor, it consults requiredSecrets and skips activation if a non-optional secret is unresolvable. A pack can also read a secret its entry does not require. The LLM judge in pii-redaction is one: it runs only when the host sets the pack's llmJudge option, and when that option carries no apiKey the judge asks AgentOS for the secret <provider>.apiKey (from extensionSecrets, else that provider's environment variable, such as OPENAI_API_KEY), then pii.llm.apiKey (from extensionSecrets only). A key alone never turns the judge on. The LLM tiers of topicality and ml-classifiers take no secret: they run when the host passes an llmInvoker callback in the pack's options.

Layer 4: heavy resources defer to SharedServiceRegistry

The runtime's ExtensionLifecycleContext.services exposes a getOrCreate(key, factory) API. Nothing is registered at activation: a pack passes the factory with the key on the first call that needs the resource, the registry runs it then, and later calls for that key (other tools in the same pack, its guardrail, other packs on the same registry) share the cached instance. has(key) stays false until that factory has run. The BERT NER model in pii-redaction (about 109 MB at its default q8 weights, key agentos:nlp:ner-pipeline) and the NLI entailment pipeline in grounding-guard lazy-load this way. Two packs load their model on first use without the shared registry: ml-classifiers loads its one ONNX model (toxic-bert) inside its guardrail on the first classification, and topicality loads its embedding model (all-MiniLM-L6-v2) once per process on the first input it checks.

What this looks like end-to-end

// 1. Host installs the registry SDK + only the extensions it wants.
//    npm install @framers/agentos @framers/agentos-extensions-registry
//                @framers/agentos-ext-pii-redaction

import { AgentOS } from '@framers/agentos';
import { createCuratedManifest } from '@framers/agentos-extensions-registry';

// 2. Manifest build resolves only what's installed.
const manifest = await createCuratedManifest({ tools: 'all' });
// → manifest.packs.length === 1 (only the PII redaction pack made it).

// 3. AgentOS activates the pack. Nothing loads and nothing is registered:
//    services.has('agentos:nlp:ner-pipeline') is false.
//    The PII guard reads the final reply only (its evaluateStreamingChunks
//    option is false by default), so hold streamed output or the streamed
//    text reaches the person before the redaction. guardrailOutputMode (and
//    requiredGuardrails) exist from @framers/agentos 0.13.3; an older core
//    ignores the option and streams.
const agent = new AgentOS();
await agent.initialize({ extensionManifest: manifest, guardrailOutputMode: 'hold' });

// 4. The first scan that needs the NER tier asks the registry for
//    'agentos:nlp:ner-pipeline', and the model loads then. Later scans and
//    the pack's pii_scan and pii_redact tools share it.

For dispatcher mechanics (Phase 1 sequential sanitizers, Phase 2 parallel classifiers, worst-action aggregation, mid-stream override), see Guardrails. For the full lifecycle, see Extension Loading and Auto-Loading Extensions.

Installation

pnpm add @framers/agentos-extensions-registry

Then install whichever extension packages you need (e.g. @framers/agentos-ext-telegram). Only installed packages will be loaded by createCuratedManifest().

Main exports

Usage

import { createCuratedManifest } from '@framers/agentos-extensions-registry';

// Load all installed extensions
const manifest = await createCuratedManifest({ channels: 'all', tools: 'all' });

// Or selectively enable specific channels
const manifest = await createCuratedManifest({
  channels: ['telegram', 'discord', 'slack'],
  tools: 'all',
  secrets: {
    'telegram.botToken': process.env.TELEGRAM_BOT_TOKEN,
    'discord.botToken': process.env.DISCORD_BOT_TOKEN,
    'slack.botToken': process.env.SLACK_BOT_TOKEN,
  },
});

// Pass to AgentOS runtime
const agent = new AgentOS();
await agent.initialize({ extensionManifest: manifest });

createCuratedManifest(options?)

Contributing and support

License

Apache 2.0 — see LICENSE.