@framers/agentos 0.1.55 → 0.1.56

package/dist/extensions/packs/pii-redaction/PiiDetectionPipeline.js

@@ -0,0 +1,456 @@
+/**
+ * @file PiiDetectionPipeline.ts
+ * @description Orchestrates the four-tier PII detection pipeline: Regex →
+ * NLP pre-filter → NER model → LLM judge.  Each tier is gated by the
+ * previous tier's output or configuration flags so that only the work needed
+ * is performed, keeping median latency low for clean or simple inputs.
+ *
+ * ## Tier overview
+ *
+ * | Tier | Class                  | Always runs?                                  |
+ * |------|------------------------|-----------------------------------------------|
+ * | 1    | RegexRecognizer        | Yes                                           |
+ * | 2    | NlpPrefilterRecognizer | Yes (when available / compromise installed)   |
+ * | 3    | NerModelRecognizer     | Only when Tier 2 found PERSON/ORG/LOC         |
+ * | 4    | LlmJudgeRecognizer     | Only for ambiguous entities (0.3 < score < 0.7)|
+ *
+ * After tiers 1–3 produce raw candidates, {@link mergeEntities} collapses
+ * overlapping spans.  Tier 4 then re-examines the ambiguous slice.  Finally
+ * the merged list is threshold-filtered and sorted by start offset.
+ *
+ * @module pii-redaction/PiiDetectionPipeline
+ */
+import { ALL_PII_ENTITY_TYPES } from './types.js';
+import { RegexRecognizer } from './recognizers/RegexRecognizer.js';
+import { NlpPrefilterRecognizer } from './recognizers/NlpPrefilterRecognizer.js';
+import { NerModelRecognizer } from './recognizers/NerModelRecognizer.js';
+import { LlmJudgeRecognizer } from './recognizers/LlmJudgeRecognizer.js';
+import { mergeEntities } from './EntityMerger.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/**
+ * Window of characters scanned to each side of an entity when performing
+ * context enhancement in Step 2.  ±50 chars provides enough context for
+ * keyword phrases like "social security number:" while remaining cheap.
+ */
+const CONTEXT_WINDOW_CHARS = 50;
+/**
+ * Score boost applied when a strong context keyword is found within the
+ * {@link CONTEXT_WINDOW_CHARS} window around a matching entity.
+ */
+const CONTEXT_BOOST_STRONG = 0.2;
+/**
+ * Score boost applied when a weaker/generic context keyword is found.
+ */
+const CONTEXT_BOOST_WEAK = 0.15;
+/**
+ * Lower bound (exclusive) of the ambiguous score range that triggers the
+ * LLM judge.  Entities with score ≤ this value are assumed to be too weak
+ * to bother re-examining.
+ */
+const LLM_JUDGE_SCORE_LOW = 0.3;
+/**
+ * Upper bound (exclusive) of the ambiguous score range.  Entities at or
+ * above this value have sufficient confidence without needing LLM
+ * verification.
+ */
+const LLM_JUDGE_SCORE_HIGH = 0.7;
+/**
+ * Default confidence threshold applied when none is specified in
+ * {@link PiiRedactionPackOptions}.  Matches the documented default.
+ */
+const DEFAULT_CONFIDENCE_THRESHOLD = 0.5;
+// ---------------------------------------------------------------------------
+// Context-keyword definitions
+// ---------------------------------------------------------------------------
+/**
+ * Mapping of {@link PiiEntityType} to the context keyword groups that signal
+ * the entity is genuine PII in context.  Keywords are matched
+ * case-insensitively.
+ *
+ * Each entry is a tuple of [keywords, boostAmount]:
+ * - Strong keywords (more specific phrases) → {@link CONTEXT_BOOST_STRONG}
+ * - Weak keywords (generic labels)          → {@link CONTEXT_BOOST_WEAK}
+ */
+const CONTEXT_KEYWORDS = {
+    SSN: [
+        { keywords: ['social security', 'ssn:', 'ss#'], boost: CONTEXT_BOOST_STRONG },
+        { keywords: ['tax id', 'government id'], boost: CONTEXT_BOOST_WEAK },
+    ],
+    PERSON: [
+        { keywords: ['name:', 'full name', 'first name', 'last name', 'patient', 'employee'], boost: CONTEXT_BOOST_STRONG },
+        { keywords: ['mr.', 'mrs.', 'ms.', 'dr.', 'prof.'], boost: CONTEXT_BOOST_WEAK },
+    ],
+    DATE_OF_BIRTH: [
+        { keywords: ['date of birth', 'dob:', 'born on', 'birthday'], boost: CONTEXT_BOOST_STRONG },
+        { keywords: ['birth', 'age:'], boost: CONTEXT_BOOST_WEAK },
+    ],
+    LOCATION: [
+        { keywords: ['address:', 'mailing address', 'home address', 'street', 'city', 'zip code', 'postal code'], boost: CONTEXT_BOOST_STRONG },
+        { keywords: ['lives at', 'resides at', 'located at'], boost: CONTEXT_BOOST_WEAK },
+    ],
+    PHONE: [
+        { keywords: ['phone:', 'tel:', 'mobile:', 'cell:', 'fax:', 'telephone', 'contact number'], boost: CONTEXT_BOOST_STRONG },
+        { keywords: ['call', 'reach me at'], boost: CONTEXT_BOOST_WEAK },
+    ],
+    EMAIL: [
+        { keywords: ['email:', 'e-mail:', 'contact:', 'email address'], boost: CONTEXT_BOOST_STRONG },
+        { keywords: ['send to', 'reply to', '@'], boost: CONTEXT_BOOST_WEAK },
+    ],
+    CREDIT_CARD: [
+        { keywords: ['credit card', 'card number', 'cc:', 'visa', 'mastercard', 'amex'], boost: CONTEXT_BOOST_STRONG },
+        { keywords: ['payment', 'billing', 'expires'], boost: CONTEXT_BOOST_WEAK },
+    ],
+    PASSPORT: [
+        { keywords: ['passport', 'passport number', 'passport no.', 'travel document'], boost: CONTEXT_BOOST_STRONG },
+        { keywords: ['identity', 'nationality', 'issued by'], boost: CONTEXT_BOOST_WEAK },
+    ],
+};
+// ---------------------------------------------------------------------------
+// PiiDetectionPipeline
+// ---------------------------------------------------------------------------
+/**
+ * Four-tier PII detection pipeline that orchestrates Regex, NLP pre-filter,
+ * NER model, and LLM judge recognisers into a single `detect()` call.
+ *
+ * ### Construction
+ * ```ts
+ * const pipeline = new PiiDetectionPipeline(serviceRegistry, packOptions, getSecret);
+ * const result = await pipeline.detect('Call me at 555-123-4567');
+ * ```
+ *
+ * ### Lifecycle
+ * The pipeline is designed to be constructed once at pack startup and reused
+ * across many `detect()` calls.  Recognisers are constructed eagerly but load
+ * their heavy dependencies (NLP models, NER weights) lazily on first use.
+ *
+ * ### Concurrency
+ * `detect()` is safe to call concurrently from multiple async contexts:
+ * - Regex and NLP recognisers create fresh scoped instances per call.
+ * - The NER model pipeline is shared and thread-safe via the service registry.
+ * - The LLM judge uses an internal semaphore to cap concurrent requests.
+ */
+export class PiiDetectionPipeline {
+    // -----------------------------------------------------------------------
+    // Constructor
+    // -----------------------------------------------------------------------
+    /**
+     * Construct a new PiiDetectionPipeline.
+     *
+     * All recognisers are instantiated here but do not load their heavy
+     * dependencies (NLP libraries, transformer models) until the first call
+     * to {@link detect}.
+     *
+     * @param services   - Shared service registry for lazy-loading NLP/NER
+     *                     models so they are shared across the agent.
+     * @param options    - Pack-level configuration including entity type
+     *                     filter, confidence threshold, allow/denylists, and
+     *                     optional LLM judge config.
+     * @param getSecret  - Optional function to look up credential secrets by
+     *                     ID (e.g. `'openai.apiKey'`, `'pii.llm.apiKey'`).
+     *                     Used to resolve the LLM judge API key when not
+     *                     provided explicitly in {@link LlmJudgeConfig.apiKey}.
+     */
+    constructor(services, options, getSecret) {
+        // ---- Resolve entity types ----
+        this.entityTypes = options.entityTypes ?? [...ALL_PII_ENTITY_TYPES];
+        // ---- Resolve confidence threshold ----
+        this.confidenceThreshold = options.confidenceThreshold ?? DEFAULT_CONFIDENCE_THRESHOLD;
+        // ---- Resolve NER model flag ----
+        // `enableNerModel !== false` means "true unless explicitly disabled".
+        this.enableNerModel = options.enableNerModel !== false;
+        // ---- Resolve allow/denylist (normalise RegExp entries to strings) ----
+        // MergeOptions only accepts string[] for allow/denylist, so we strip
+        // RegExp entries here.  RegExp entries are useful for the broader pack
+        // but the merger works with string exact-match lists.
+        this.allowlist = (options.allowlist ?? [])
+            .filter((v) => typeof v === 'string');
+        this.denylist = (options.denylist ?? [])
+            .filter((v) => typeof v === 'string');
+        // ---- Instantiate recognisers ----
+        this.regexRecognizer = new RegexRecognizer();
+        this.nlpPrefilter = new NlpPrefilterRecognizer(services);
+        this.nerRecognizer = new NerModelRecognizer(services);
+        // ---- Instantiate LLM judge if configured ----
+        if (options.llmJudge) {
+            const resolvedConfig = this.resolveJudgeApiKey(options.llmJudge, getSecret);
+            this.llmJudge = new LlmJudgeRecognizer(resolvedConfig);
+        }
+        else {
+            this.llmJudge = null;
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Public API
+    // -----------------------------------------------------------------------
+    /**
+     * Run all applicable detection tiers over `text` and return a
+     * {@link PiiDetectionResult} with the merged, threshold-filtered entity
+     * list and pipeline metadata.
+     *
+     * ### Processing steps
+     * 1. **Tier 1 (Regex)** — Always executed.  Deterministic pattern matching.
+     * 2. **Context enhancement** — Scans ±{@link CONTEXT_WINDOW_CHARS} chars
+     *    around each Tier 1 entity for keyword signals and boosts scores.
+     * 3. **Tier 2 (NLP)** — Always attempted; degrades gracefully if `compromise`
+     *    is not installed.
+     * 4. **Tier 3 (NER)** — Runs only when:
+     *    - `enableNerModel !== false`, AND
+     *    - Tier 2 found at least one PERSON, ORGANIZATION, or LOCATION candidate.
+     * 5. **Merge** — {@link mergeEntities} collapses overlapping spans and applies
+     *    allow/denylists.  Threshold is NOT applied yet.
+     * 6. **Tier 4 (LLM judge)** — Applied only to entities in the ambiguous score
+     *    band (0.3 < score < 0.7) and only when `llmJudge` is configured.
+     *    `null` results (NOT_PII) are discarded.
+     * 7. **Threshold filter** — Entities with `score < confidenceThreshold` are
+     *    removed from the final output.
+     * 8. **Sort + summary** — Sorted by start offset; summary string built.
+     *
+     * @param text - The raw input text to analyse.
+     * @returns A {@link PiiDetectionResult} containing detected entities and
+     *          pipeline execution metadata.
+     */
+    async detect(text) {
+        // Track wall-clock time from the very start of detection.
+        const startTime = Date.now();
+        // Accumulates all raw entities from tiers 1–3 before merging.
+        const rawEntities = [];
+        // Tracks which tiers were actually executed (for observability).
+        const tiersExecuted = [];
+        // -----------------------------------------------------------------------
+        // Tier 1: Regex recogniser — always runs.
+        // -----------------------------------------------------------------------
+        const tier1Entities = await this.regexRecognizer.recognize(text, {
+            entityTypes: this.entityTypes,
+        });
+        tiersExecuted.push('regex');
+        rawEntities.push(...tier1Entities);
+        // -----------------------------------------------------------------------
+        // Step 2: Context enhancement — boost scores based on surrounding keywords.
+        // -----------------------------------------------------------------------
+        const tier1Enhanced = this.applyContextEnhancement(tier1Entities, text);
+        // Replace the tier1 entities in rawEntities with their enhanced versions.
+        // We rebuild the slice since arrays are reference-ordered.
+        rawEntities.splice(0, tier1Entities.length, ...tier1Enhanced);
+        // -----------------------------------------------------------------------
+        // Tier 2: NLP pre-filter — always attempted.
+        // -----------------------------------------------------------------------
+        const tier2Entities = await this.nlpPrefilter.recognize(text, {
+            entityTypes: this.entityTypes,
+        });
+        // Even if compromise is unavailable (returns []), we still push nothing.
+        rawEntities.push(...tier2Entities);
+        // -----------------------------------------------------------------------
+        // Tier 3: NER model — gated on Tier 2 finding NER-class candidates.
+        // -----------------------------------------------------------------------
+        /** Entity types that gate Tier 3 execution. */
+        const NER_GATE_TYPES = new Set(['PERSON', 'ORGANIZATION', 'LOCATION']);
+        const tier2HasNerCandidates = tier2Entities.some((e) => NER_GATE_TYPES.has(e.entityType));
+        if (this.enableNerModel && tier2HasNerCandidates) {
+            // Tier 2 found at least one name/org/location candidate — run NER for
+            // higher-accuracy confirmation.
+            const tier3Entities = await this.nerRecognizer.recognize(text, {
+                entityTypes: this.entityTypes,
+                // Provide Tier 2 results as prior context so NER can skip confirmed spans.
+                priorEntities: tier2Entities,
+            });
+            rawEntities.push(...tier3Entities);
+            // Record 'ner' in tiersExecuted (we reuse the same label for both NLP
+            // tiers since PiiDetectionResult.tiersExecuted uses 'ner' as the value
+            // representing all NER-type processing).
+            tiersExecuted.push('ner');
+        }
+        // -----------------------------------------------------------------------
+        // Step 5: Merge — collapse overlapping spans; apply allow/denylist.
+        //         Do NOT apply threshold yet (LLM judge needs the full list).
+        // -----------------------------------------------------------------------
+        const mergedEntities = mergeEntities(rawEntities, {
+            allowlist: this.allowlist,
+            denylist: this.denylist,
+            // Intentionally no confidenceThreshold here — applied post LLM judge.
+        }, text);
+        // -----------------------------------------------------------------------
+        // Tier 4: LLM judge — only for ambiguous-score entities.
+        // -----------------------------------------------------------------------
+        let judgedEntities;
+        if (this.llmJudge !== null) {
+            judgedEntities = await this.runLlmJudge(mergedEntities, text);
+            tiersExecuted.push('llm');
+        }
+        else {
+            judgedEntities = mergedEntities;
+        }
+        // -----------------------------------------------------------------------
+        // Step 7: Final threshold filter.
+        // -----------------------------------------------------------------------
+        const thresholded = judgedEntities.filter((e) => e.score >= this.confidenceThreshold);
+        // -----------------------------------------------------------------------
+        // Step 8: Sort by start offset and build summary.
+        // -----------------------------------------------------------------------
+        const sorted = thresholded.slice().sort((a, b) => a.start - b.start);
+        const summary = this.buildSummary(sorted);
+        return {
+            entities: sorted,
+            inputLength: text.length,
+            processingTimeMs: Date.now() - startTime,
+            tiersExecuted,
+            summary,
+        };
+    }
+    // -----------------------------------------------------------------------
+    // Private helpers
+    // -----------------------------------------------------------------------
+    /**
+     * Applies context enhancement to Tier 1 regex entities.
+     *
+     * For each entity, a window of ±{@link CONTEXT_WINDOW_CHARS} characters
+     * around the entity is scanned for known context keywords.  When a
+     * matching keyword is found for that entity's type, the entity's score is
+     * boosted by the keyword's associated {@link CONTEXT_BOOST_STRONG} or
+     * {@link CONTEXT_BOOST_WEAK} amount, capped at 1.0.
+     *
+     * Entities whose type has no context-keyword mapping are returned
+     * unchanged.  A new array of entities is returned — the originals are not
+     * mutated.
+     *
+     * @param entities - Raw Tier 1 entities to enhance.
+     * @param text     - Full input text (used to extract context windows).
+     * @returns New array of entities with potentially boosted scores.
+     */
+    applyContextEnhancement(entities, text) {
+        return entities.map((entity) => {
+            const keywordGroups = CONTEXT_KEYWORDS[entity.entityType];
+            // No context keywords defined for this entity type — return as-is.
+            if (!keywordGroups || keywordGroups.length === 0)
+                return entity;
+            // Extract the context window around this entity.
+            const ctxStart = Math.max(0, entity.start - CONTEXT_WINDOW_CHARS);
+            const ctxEnd = Math.min(text.length, entity.end + CONTEXT_WINDOW_CHARS);
+            const contextSlice = text.slice(ctxStart, ctxEnd).toLowerCase();
+            // Accumulate the total boost from all matched keyword groups.
+            let totalBoost = 0;
+            for (const group of keywordGroups) {
+                // Check if any keyword in this group appears in the context window.
+                const matched = group.keywords.some((kw) => contextSlice.includes(kw));
+                if (matched) {
+                    // Only apply the group's boost once even if multiple keywords match.
+                    totalBoost += group.boost;
+                    // Once we've found a strong-boost match there is no point continuing
+                    // to look for weaker matches; break early to avoid double-boosting.
+                    if (group.boost >= CONTEXT_BOOST_STRONG)
+                        break;
+                }
+            }
+            if (totalBoost === 0)
+                return entity;
+            // Cap the final score at 1.0 to stay within the valid range.
+            const boostedScore = Math.min(1.0, entity.score + totalBoost);
+            return { ...entity, score: boostedScore };
+        });
+    }
+    /**
+     * Runs the LLM judge over entities in the ambiguous score band
+     * (LLM_JUDGE_SCORE_LOW < score < LLM_JUDGE_SCORE_HIGH).
+     *
+     * Entities outside the ambiguous band are passed through as-is.
+     * For ambiguous entities, `judge()` is awaited in parallel (up to the
+     * semaphore limit configured in LlmJudgeRecognizer).  Entities judged to
+     * be NOT_PII (null return) are discarded.
+     *
+     * @param entities - Merged entity list from Steps 5.
+     * @param text     - Full input text passed to the judge for context.
+     * @returns Updated entity list after LLM judgement.
+     */
+    async runLlmJudge(entities, text) {
+        // The judge is guaranteed non-null at call sites — assert for TS.
+        const judge = this.llmJudge;
+        // Partition entities into clear (pass-through) and ambiguous (judge) groups.
+        const clearEntities = [];
+        const ambiguousEntities = [];
+        for (const entity of entities) {
+            if (entity.score > LLM_JUDGE_SCORE_LOW && entity.score < LLM_JUDGE_SCORE_HIGH) {
+                ambiguousEntities.push(entity);
+            }
+            else {
+                clearEntities.push(entity);
+            }
+        }
+        // Short-circuit if no entities need judging.
+        if (ambiguousEntities.length === 0)
+            return clearEntities;
+        // Fire all judge calls concurrently — the semaphore inside LlmJudgeRecognizer
+        // throttles actual concurrency to the configured maxConcurrency.
+        const judgeResults = await Promise.all(ambiguousEntities.map((entity) => judge.judge(entity, text)));
+        // Collect non-null results (null = judge determined NOT_PII → discard).
+        const confirmedEntities = judgeResults.filter((r) => r !== null);
+        // Combine confirmed ambiguous entities with the clear (non-ambiguous) ones.
+        return [...clearEntities, ...confirmedEntities];
+    }
+    /**
+     * Resolves the API key for the LLM judge using a three-level fallback:
+     *
+     * 1. Explicit `config.apiKey` (highest priority — caller-supplied).
+     * 2. Provider-specific secret via `getSecret('<provider>.apiKey')`.
+     * 3. Pack-specific generic secret via `getSecret('pii.llm.apiKey')`.
+     *
+     * Returns a new {@link LlmJudgeConfig} with `apiKey` set to the resolved
+     * value (or the original value if a key was already present).
+     *
+     * @param config    - Original LLM judge configuration.
+     * @param getSecret - Optional secret resolver function.
+     * @returns Config with `apiKey` resolved to the best available value.
+     */
+    resolveJudgeApiKey(config, getSecret) {
+        // 1. If an explicit apiKey is already present, use it directly.
+        if (config.apiKey)
+            return config;
+        if (!getSecret)
+            return config;
+        // 2. Provider-specific secret: e.g. 'openai.apiKey' or 'anthropic.apiKey'.
+        const providerKey = getSecret(`${config.provider}.apiKey`);
+        if (providerKey)
+            return { ...config, apiKey: providerKey };
+        // 3. Pack-specific generic secret.
+        const packKey = getSecret('pii.llm.apiKey');
+        if (packKey)
+            return { ...config, apiKey: packKey };
+        // No key found via any path — return config unchanged (LlmJudgeRecognizer
+        // will fail open when it cannot authenticate, returning original entities).
+        return config;
+    }
+    /**
+     * Builds a human-readable summary string from the final entity list.
+     *
+     * Format: `"<n> entities found: <count>×<TYPE>, ..."` or
+     * `"No PII detected"` when the list is empty.
+     *
+     * Entity types are sorted alphabetically for deterministic output, and
+     * only types that are actually present appear in the summary.
+     *
+     * @example
+     * ```
+     * "3 entities found: 1×EMAIL, 1×PERSON, 1×PHONE"
+     * "No PII detected"
+     * ```
+     *
+     * @param entities - Final threshold-filtered, sorted entity list.
+     * @returns Human-readable summary string.
+     */
+    buildSummary(entities) {
+        if (entities.length === 0)
+            return 'No PII detected';
+        // Count occurrences of each entity type.
+        const typeCounts = new Map();
+        for (const entity of entities) {
+            typeCounts.set(entity.entityType, (typeCounts.get(entity.entityType) ?? 0) + 1);
+        }
+        // Build sorted count strings for stable output.
+        const countParts = Array.from(typeCounts.entries())
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([type, count]) => `${count}×${type}`);
+        const noun = entities.length === 1 ? 'entity' : 'entities';
+        return `${entities.length} ${noun} found: ${countParts.join(', ')}`;
+    }
+}
+//# sourceMappingURL=PiiDetectionPipeline.js.map

package/dist/extensions/packs/pii-redaction/PiiDetectionPipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PiiDetectionPipeline.js","sourceRoot":"","sources":["../../../../src/extensions/packs/pii-redaction/PiiDetectionPipeline.ts"],"names":[],"mappings":"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"}

package/dist/extensions/packs/pii-redaction/PiiRedactionGuardrail.d.ts

@@ -0,0 +1,121 @@
+/**
+ * @file PiiRedactionGuardrail.ts
+ * @description Guardrail service that intercepts agent input and/or output to
+ * detect and redact PII (Personally Identifiable Information) in real time.
+ *
+ * The guardrail integrates with the AgentOS guardrail hook pipeline via the
+ * {@link IGuardrailService} interface, providing two evaluation paths:
+ *
+ * - **Input evaluation** (`evaluateInput`): Scans the user's text input before
+ *   it enters the orchestration pipeline and returns a SANITIZE action with
+ *   redacted text when PII is found.
+ *
+ * - **Output evaluation** (`evaluateOutput`): Uses a sentence-boundary buffer
+ *   keyed by `streamId` to accumulate streaming text deltas.  When a sentence
+ *   boundary is detected (`. `, `? `, `! `, or `\n`) the buffer is scanned
+ *   for PII and redacted text is returned as a SANITIZE action.  Entity
+ *   offsets are always relative to the buffer, not individual chunks.
+ *
+ * Which evaluation path(s) are active is controlled by the
+ * {@link PiiRedactionPackOptions.guardrailScope} option:
+ * - `'input'`  -- only `evaluateInput` is active
+ * - `'output'` -- only `evaluateOutput` is active
+ * - `'both'`   -- both paths are active (default)
+ *
+ * @module pii-redaction/PiiRedactionGuardrail
+ */
+import type { ISharedServiceRegistry } from '../../ISharedServiceRegistry';
+import type { IGuardrailService, GuardrailConfig, GuardrailInputPayload, GuardrailOutputPayload, GuardrailEvaluationResult } from '../../../core/guardrails/IGuardrailService';
+import type { PiiRedactionPackOptions } from './types';
+/**
+ * AgentOS guardrail service that detects and redacts PII from both inbound
+ * user messages and outbound agent responses.
+ *
+ * ### Construction
+ * ```ts
+ * const guardrail = new PiiRedactionGuardrail(registry, options, getSecret);
+ * ```
+ *
+ * ### Thread safety
+ * The guardrail maintains per-stream mutable state for output evaluation.
+ * Concurrent calls with **different** `streamId` values are safe.  Concurrent
+ * calls with the **same** `streamId` are serialised by the AgentOS streaming
+ * pipeline so no additional locking is required.
+ *
+ * @implements {IGuardrailService}
+ */
+export declare class PiiRedactionGuardrail implements IGuardrailService {
+    /**
+     * Guardrail configuration exposed to the AgentOS hook pipeline.
+     * Controls whether streaming chunks are evaluated and the per-request
+     * evaluation cap.
+     */
+    readonly config: GuardrailConfig;
+    /** Detection pipeline shared across all evaluations. */
+    private readonly pipeline;
+    /** Redaction style applied when replacing detected PII spans. */
+    private readonly redactionStyle;
+    /** Which evaluation paths are active: 'input', 'output', or 'both'. */
+    private readonly scope;
+    /** Maximum sentence-boundary evaluations per stream. */
+    private readonly maxStreamingEvaluations;
+    /**
+     * Per-stream sentence-boundary buffers for output evaluation.
+     * Keys are `AgentOSResponseChunk.streamId` strings.
+     */
+    private readonly streamBuffers;
+    /**
+     * Construct a new PiiRedactionGuardrail.
+     *
+     * @param services  - Shared service registry forwarded to the detection
+     *                    pipeline for lazy-loading NLP/NER models.
+     * @param options   - Pack-level configuration controlling entity types,
+     *                    confidence threshold, redaction style, guardrail scope,
+     *                    and streaming behaviour.
+     * @param getSecret - Optional secret resolver for the LLM judge API key.
+     */
+    constructor(services: ISharedServiceRegistry, options: PiiRedactionPackOptions, getSecret?: (id: string) => string | undefined);
+    /**
+     * Evaluate inbound user text for PII before the orchestration pipeline
+     * processes it.
+     *
+     * When PII is found the method returns a {@link GuardrailAction.SANITIZE}
+     * result containing the redacted text.  When no PII is found (or the
+     * input has no text) it returns `null` to signal the content should pass
+     * through unchanged.
+     *
+     * This method is a no-op (returns `null`) when `guardrailScope` is set
+     * to `'output'`.
+     *
+     * @param payload - Input payload containing the user's text and context.
+     * @returns Evaluation result with redacted text, or `null` if clean.
+     */
+    evaluateInput(payload: GuardrailInputPayload): Promise<GuardrailEvaluationResult | null>;
+    /**
+     * Evaluate outbound agent response chunks for PII using a sentence-boundary
+     * buffer.
+     *
+     * ### Buffering strategy
+     *
+     * Text deltas are accumulated per-stream in an internal buffer.  The buffer
+     * is scanned for PII only when a sentence boundary is detected (`. `, `? `,
+     * `! `, or `\n`) or when the stream ends (`isFinal === true` or chunk type
+     * is `FINAL_RESPONSE`).
+     *
+     * Entity offsets from the detection pipeline are relative to the **buffer**
+     * text, not individual chunk deltas, so redaction replacement is always
+     * positionally correct.
+     *
+     * An internal evaluation counter enforces {@link maxStreamingEvaluations}
+     * per stream.  Once the limit is reached subsequent chunks pass through
+     * unevaluated.
+     *
+     * This method is a no-op (returns `null`) when `guardrailScope` is set
+     * to `'input'`.
+     *
+     * @param payload - Output payload containing the response chunk and context.
+     * @returns Evaluation result with redacted buffer text, or `null` if clean.
+     */
+    evaluateOutput(payload: GuardrailOutputPayload): Promise<GuardrailEvaluationResult | null>;
+}
+//# sourceMappingURL=PiiRedactionGuardrail.d.ts.map

package/dist/extensions/packs/pii-redaction/PiiRedactionGuardrail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PiiRedactionGuardrail.d.ts","sourceRoot":"","sources":["../../../../src/extensions/packs/pii-redaction/PiiRedactionGuardrail.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAC3E,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,yBAAyB,EAC1B,MAAM,4CAA4C,CAAC;AAGpD,OAAO,KAAK,EAAE,uBAAuB,EAAkB,MAAM,SAAS,CAAC;AAoDvE;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,qBAAsB,YAAW,iBAAiB;IAK7D;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IAMjC,wDAAwD;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuB;IAEhD,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAEhD,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8B;IAEpD,wDAAwD;IACxD,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAS;IAEjD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAkC;IAMhE;;;;;;;;;OASG;gBAED,QAAQ,EAAE,sBAAsB,EAChC,OAAO,EAAE,uBAAuB,EAChC,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS;IAsBhD;;;;;;;;;;;;;;OAcG;IACG,aAAa,CACjB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC;IA0C5C;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,cAAc,CAClB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC;CA8G7C"}