@framers/agentos-ext-pii-redaction

Four-tier PII detection and redaction for @framers/agentos. Scrubs personally identifiable information from agent inputs and outputs using a layered pipeline: regex recognizers, NER models, entity merging, and a redaction engine.

What it does

Scans every message flowing through the agent for PII (names, addresses, phone numbers, emails, government IDs, payment information, free-form sensitive entities) and redacts matches before the message reaches downstream tools, the LLM, or storage.

The four tiers:

1. Regex recognizers — fast, deterministic detection of structured PII (phone, email, SSN, credit-card-like patterns)
2. NER pipeline — model-based detection of unstructured PII (person names, locations, organizations)
3. Entity merger — deduplicates and resolves overlapping spans across recognizers
4. Redaction engine — applies the configured masking strategy (replace, hash, tokenize, or remove) per entity type

Install

npm install @framers/agentos-ext-pii-redaction

Peer dependency: @framers/agentos.

Quickstart

import { AgentOS } from '@framers/agentos';
import { createPiiRedactionGuardrail } from '@framers/agentos-ext-pii-redaction';

const agentos = new AgentOS();
await agentos.initialize({
  extensionManifest: {
    packs: [
      {
        factory: () =>
          createPiiRedactionGuardrail({
            categories: ['email', 'phone', 'ssn', 'person', 'credit-card'],
            strategy: 'replace',
          }),
        enabled: true,
      },
    ],
  },
});

Public API

• PiiDetectionPipeline, EntityMerger, RedactionEngine — composable pipeline pieces
• PiiRedactionGuardrail — guardrail wiring the pipeline for the AgentOS contract
• createPiiRedactionGuardrail(options?) — factory returning an ExtensionPack
• createExtensionPack(context) — auto-discoverable factory used by AgentOS extension auto-pickup
• recognizers/ — individual recognizer modules

See src/types.ts for PiiRedactionPackOptions.

Examples

• test/ — redaction fixtures across recognizer types

Lazy loading and optional install

This package is an optional dependency of @framers/agentos-extensions-registry. The registry ships catalog metadata for every extension, but createCuratedManifest() calls import.meta.resolve() per entry and silently skips anything not installed. npm install @framers/agentos-ext-pii-redaction is the gate.

The 110MB BERT NER model does not load at activation. The pack registers a factory under the pii:ner-model key in SharedServiceRegistry and the model file enters the module graph only on the first scan that needs it. Subsequent scans, the streaming guardrail, and both pii_scan / pii_redact tools share the same instance.

The optional LLM-judge tier is gated by requiredSecrets: [{ id: 'anthropic.apiKey', optional: true }]. Without the key, the descriptor is skipped and the rest of the pack activates unchanged.

The streaming guardrail registers with config.canSanitize = true and config.evaluateStreamingChunks = true, so it runs in Phase 1 of the two-phase dispatcher. SANITIZE results chain sequentially through other Phase 1 sanitizers, then the redacted text feeds Phase 2 classifiers in parallel.

For the full DI model and end-to-end walkthrough, see How extensions stay optional and lazy and the auto-loading guide.

License

Apache 2.0 — see the repo root LICENSE.