Skip to content

README.md

Latest commit

 

History

History
149 lines (107 loc) · 9.98 KB

README.md

File metadata and controls

149 lines (107 loc) · 9.98 KB
Raw

AgentOS     Frame.dev

@framers/agentos-extensions-registry

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

npm

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

Package Role
@framers/agentos-extensions Source code — the actual channel adapters, tool implementations, and extension packs
@framers/agentos-extensions-registry (this) Catalog/SDK — indexes the extensions above, stores metadata, and dynamically loads whichever packages are installed
@framers/agentos Runtime — provides ITool, IChannelAdapter, ExtensionManifest, and the agent kernel that consumes the manifest

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

Export Description
createCuratedManifest(options?) Builds an ExtensionManifest from installed extensions. Accepts channel/tool filters, secrets, and per-extension overrides.
CHANNEL_CATALOG Static catalog of all 37 channel platform entries (platform, package, SDK, required secrets)
TOOL_CATALOG Static catalog of tool extensions (web search, CLI executor, image search, etc.)
PROVIDER_CATALOG Static catalog of 27 model-provider entries: 25 LLM + 2 image (provider name, models, base URLs). 11 LLM providers ship runtime adapters in core; the rest are catalog metadata for discovery and roadmap parity.
getAvailableExtensions() Returns only extensions whose npm packages are resolvable in the current environment
getAvailableChannels() Returns only channel adapters whose packages are installed
SECRET_ENV_MAP Maps secret keys (e.g. telegram.botToken) to environment variable names

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?)

Parameter Type Default Description
channels string[] | 'all' | 'none' 'all' Which channel platforms to enable
tools string[] | 'all' | 'none' 'all' Which tool extensions to enable
secrets Record<string, string> {} Secrets map (falls back to env vars)
basePriority number 0 Base priority for all extensions
overrides Record<string, Override> {} Per-extension overrides: { enabled?, priority?, options? }

Contributing and support

Guide What
Contributing Development setup, commit and pull request rules, review threads, contribution licensing
Release guide How the daily release at 10:17 UTC publishes master to npm
Agent instructions Commands and conventions for coding agents
Code of Conduct Community standards
Security Policy Reporting vulnerabilities privately
Support Where to get help

License

Apache 2.0 — see LICENSE.