@framers/agentos 0.1.55 → 0.1.56

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

@@ -0,0 +1,271 @@
+/**
+ * @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 { GuardrailAction } from '../../../core/guardrails/IGuardrailService.js';
+import { AgentOSResponseChunkType } from '../../../api/types/AgentOSResponse.js';
+import { PiiDetectionPipeline } from './PiiDetectionPipeline.js';
+import { redactText } from './RedactionEngine.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/**
+ * Default maximum number of streaming evaluations (sentence flushes) allowed
+ * per stream before the guardrail stops scanning.  Prevents unbounded CPU
+ * usage on very long streams.
+ */
+const DEFAULT_MAX_STREAMING_EVALUATIONS = 50;
+/**
+ * Regex matching sentence-boundary positions in accumulated buffer text.
+ *
+ * Matches:
+ * - `. ` (period + space)
+ * - `? ` (question mark + space)
+ * - `! ` (exclamation mark + space)
+ * - `\n` (newline)
+ *
+ * The `g` flag is intentional so `lastIndex` tracks all boundaries in a
+ * single pass via `matchAll`.
+ */
+const SENTENCE_BOUNDARY_RE = /[.?!]\s|\n/g;
+// ---------------------------------------------------------------------------
+// PiiRedactionGuardrail
+// ---------------------------------------------------------------------------
+/**
+ * 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 class PiiRedactionGuardrail {
+    // -----------------------------------------------------------------------
+    // Constructor
+    // -----------------------------------------------------------------------
+    /**
+     * 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, options, getSecret) {
+        /**
+         * Per-stream sentence-boundary buffers for output evaluation.
+         * Keys are `AgentOSResponseChunk.streamId` strings.
+         */
+        this.streamBuffers = new Map();
+        // Build the detection pipeline with the provided options.
+        this.pipeline = new PiiDetectionPipeline(services, options, getSecret);
+        // Resolve configuration with sensible defaults.
+        this.redactionStyle = options.redactionStyle ?? 'placeholder';
+        this.scope = options.guardrailScope ?? 'both';
+        this.maxStreamingEvaluations =
+            options.maxStreamingEvaluations ?? DEFAULT_MAX_STREAMING_EVALUATIONS;
+        // Build the GuardrailConfig from pack options.
+        this.config = {
+            evaluateStreamingChunks: options.evaluateStreamingChunks ?? false,
+            maxStreamingEvaluations: this.maxStreamingEvaluations,
+        };
+    }
+    // -----------------------------------------------------------------------
+    // IGuardrailService — evaluateInput
+    // -----------------------------------------------------------------------
+    /**
+     * 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.
+     */
+    async evaluateInput(payload) {
+        // Skip input evaluation when scope is output-only.
+        if (this.scope === 'output') {
+            return null;
+        }
+        // Extract the text input from the payload.
+        const text = payload.input.textInput;
+        // Nothing to scan if the input has no text content.
+        if (!text) {
+            return null;
+        }
+        // Run the full detection pipeline over the input text.
+        const detectionResult = await this.pipeline.detect(text);
+        // No PII found — allow the input through unchanged.
+        if (detectionResult.entities.length === 0) {
+            return null;
+        }
+        // PII was found — redact the input text and return a SANITIZE action.
+        const redacted = redactText(text, detectionResult.entities, this.redactionStyle);
+        return {
+            action: GuardrailAction.SANITIZE,
+            modifiedText: redacted,
+            reason: detectionResult.summary,
+            reasonCode: 'PII_REDACTED',
+            metadata: {
+                entityCount: detectionResult.entities.length,
+                tiersExecuted: detectionResult.tiersExecuted,
+                processingTimeMs: detectionResult.processingTimeMs,
+            },
+        };
+    }
+    // -----------------------------------------------------------------------
+    // IGuardrailService — evaluateOutput
+    // -----------------------------------------------------------------------
+    /**
+     * 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.
+     */
+    async evaluateOutput(payload) {
+        // Skip output evaluation when scope is input-only.
+        if (this.scope === 'input') {
+            return null;
+        }
+        const { chunk } = payload;
+        // Determine the text content to buffer based on chunk type.
+        let textToBuffer = null;
+        let isStreamEnd = false;
+        if (chunk.type === AgentOSResponseChunkType.TEXT_DELTA) {
+            // TEXT_DELTA chunks carry incremental text in `textDelta`.
+            textToBuffer = chunk.textDelta ?? null;
+        }
+        else if (chunk.type === AgentOSResponseChunkType.FINAL_RESPONSE) {
+            // FINAL_RESPONSE may carry the complete response text.
+            textToBuffer =
+                chunk.finalResponseText ?? null;
+            isStreamEnd = true;
+        }
+        // Mark stream end when isFinal is set regardless of chunk type.
+        if (chunk.isFinal) {
+            isStreamEnd = true;
+        }
+        // Nothing to evaluate if there is no text content and stream is not ending.
+        if (!textToBuffer && !isStreamEnd) {
+            return null;
+        }
+        // Retrieve or create the per-stream buffer state.
+        const streamId = chunk.streamId;
+        let state = this.streamBuffers.get(streamId);
+        if (!state) {
+            state = { buffer: '', evaluations: 0, lastSeenAt: Date.now() };
+            this.streamBuffers.set(streamId, state);
+        }
+        // Update the last-seen timestamp.
+        state.lastSeenAt = Date.now();
+        // Append new text to the buffer.
+        if (textToBuffer) {
+            state.buffer += textToBuffer;
+        }
+        // Check whether the evaluation limit has been reached.
+        if (state.evaluations >= this.maxStreamingEvaluations && !isStreamEnd) {
+            // Limit reached — pass through without evaluation.
+            return null;
+        }
+        // Determine whether a sentence boundary exists in the buffer.
+        const hasSentenceBoundary = SENTENCE_BOUNDARY_RE.test(state.buffer);
+        // Reset the regex lastIndex since we used `test()` which advances it.
+        SENTENCE_BOUNDARY_RE.lastIndex = 0;
+        // Only evaluate when we have a sentence boundary or the stream is ending.
+        if (!hasSentenceBoundary && !isStreamEnd) {
+            return null;
+        }
+        // Increment the evaluation counter.
+        state.evaluations++;
+        // Run detection against the full buffer text.
+        const detectionResult = await this.pipeline.detect(state.buffer);
+        // Clean up buffer on stream end.
+        if (isStreamEnd) {
+            this.streamBuffers.delete(streamId);
+        }
+        // No PII found — allow the chunk through unchanged.
+        if (detectionResult.entities.length === 0) {
+            return null;
+        }
+        // PII was found — redact against the BUFFER text (not the individual
+        // chunk delta) since entity offsets are buffer-relative.
+        const redacted = redactText(state.buffer, detectionResult.entities, this.redactionStyle);
+        // Reset the buffer to empty after redaction since the sanitised text
+        // replaces the entire accumulated buffer.
+        if (!isStreamEnd) {
+            state.buffer = '';
+        }
+        return {
+            action: GuardrailAction.SANITIZE,
+            modifiedText: redacted,
+            reason: detectionResult.summary,
+            reasonCode: 'PII_REDACTED',
+            metadata: {
+                entityCount: detectionResult.entities.length,
+                tiersExecuted: detectionResult.tiersExecuted,
+                processingTimeMs: detectionResult.processingTimeMs,
+                streamId,
+                evaluationNumber: state?.evaluations,
+            },
+        };
+    }
+}
+//# sourceMappingURL=PiiRedactionGuardrail.js.map

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

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

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

@@ -0,0 +1,61 @@
+/**
+ * @file RedactionEngine.ts
+ * @description Applies configurable redaction transformations to PII entity
+ * spans detected in a text string.
+ *
+ * The engine processes entity spans in **reverse order** (highest start offset
+ * first) so that replacing a span never invalidates the offsets of earlier
+ * spans that have not yet been processed.  This is the standard slice-and-join
+ * pattern for in-place text replacement with absolute positions.
+ *
+ * ## Supported redaction styles
+ *
+ * | Style | Example input | Example output |
+ * |---|---|---|
+ * | `placeholder` | `John Smith` (PERSON) | `[PERSON]` |
+ * | `mask` | `John Smith` | `J*** S****` |
+ * | `hash` | `John Smith` (PERSON) | `[PERSON:a1b2c3d4e5]` |
+ * | `category-tag` | `John Smith` (PERSON) | `<PII type="PERSON">REDACTED</PII>` |
+ *
+ * @module pii-redaction/RedactionEngine
+ */
+import type { PiiEntity, RedactionStyle } from './types';
+/**
+ * Applies PII redaction to `text` by replacing each entity span with a token
+ * generated according to the specified {@link RedactionStyle}.
+ *
+ * ### Algorithm
+ *
+ * 1. If `entities` is empty, return `text` unchanged.
+ * 2. Sort entities by `start` offset in **descending** order (right to left).
+ * 3. Iteratively replace each span via `String.prototype.slice` — because
+ *    processing proceeds right-to-left, earlier spans retain their original
+ *    offsets and can be replaced without adjustment.
+ * 4. Return the final redacted string.
+ *
+ * The function assumes that the provided `entities` are **non-overlapping**.
+ * Overlapping spans must be resolved by {@link mergeEntities} before calling
+ * this function.  Overlapping spans produce undefined output.
+ *
+ * @param text     - The original input string to redact.
+ * @param entities - Non-overlapping PII entities to redact.  May be unsorted;
+ *                   the function sorts internally.
+ * @param style    - How each PII span should be replaced.
+ * @returns The redacted string with all PII spans replaced according to
+ *          `style`.
+ *
+ * @example
+ * ```ts
+ * const redacted = redactText(
+ *   'Contact John Smith at john@example.com please',
+ *   [
+ *     { entityType: 'PERSON', text: 'John Smith', start: 8, end: 18, score: 0.95, source: 'ner-model' },
+ *     { entityType: 'EMAIL',  text: 'john@example.com', start: 22, end: 38, score: 1.0, source: 'regex' },
+ *   ],
+ *   'placeholder',
+ * );
+ * // → 'Contact [PERSON] at [EMAIL] please'
+ * ```
+ */
+export declare function redactText(text: string, entities: PiiEntity[], style: RedactionStyle): string;
+//# sourceMappingURL=RedactionEngine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RedactionEngine.d.ts","sourceRoot":"","sources":["../../../../src/extensions/packs/pii-redaction/RedactionEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAgJzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,SAAS,EAAE,EACrB,KAAK,EAAE,cAAc,GACpB,MAAM,CAwBR"}

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

@@ -0,0 +1,207 @@
+/**
+ * @file RedactionEngine.ts
+ * @description Applies configurable redaction transformations to PII entity
+ * spans detected in a text string.
+ *
+ * The engine processes entity spans in **reverse order** (highest start offset
+ * first) so that replacing a span never invalidates the offsets of earlier
+ * spans that have not yet been processed.  This is the standard slice-and-join
+ * pattern for in-place text replacement with absolute positions.
+ *
+ * ## Supported redaction styles
+ *
+ * | Style | Example input | Example output |
+ * |---|---|---|
+ * | `placeholder` | `John Smith` (PERSON) | `[PERSON]` |
+ * | `mask` | `John Smith` | `J*** S****` |
+ * | `hash` | `John Smith` (PERSON) | `[PERSON:a1b2c3d4e5]` |
+ * | `category-tag` | `John Smith` (PERSON) | `<PII type="PERSON">REDACTED</PII>` |
+ *
+ * @module pii-redaction/RedactionEngine
+ */
+import { createHash } from 'crypto';
+// ---------------------------------------------------------------------------
+// Style implementation helpers
+// ---------------------------------------------------------------------------
+/**
+ * Produces a `[TYPE]` placeholder token for the given entity.
+ *
+ * This is the most compact style — the original value is fully discarded and
+ * only the entity category is preserved.  Useful when downstream consumers
+ * only need to know that a PII span existed, not even its rough shape.
+ *
+ * @example `[PERSON]`, `[EMAIL]`, `[SSN]`
+ *
+ * @param entity - The detected PII entity to redact.
+ * @returns Replacement string.
+ */
+function applyPlaceholder(entity) {
+    return `[${entity.entityType}]`;
+}
+/**
+ * Produces a word-masked version of the original text.
+ *
+ * Each word in the matched text is masked by keeping its first character and
+ * replacing every subsequent character with `*`.  Word boundaries are defined
+ * by one or more whitespace characters (`\s+`).
+ *
+ * Non-alphabetic first characters (digits, punctuation) are preserved as-is;
+ * only the trailing characters of each word are replaced.
+ *
+ * @example
+ * - `'John Smith'` → `'J*** S****'`
+ * - `'john@example.com'` → `'j***@*****.***'`  (no spaces → single word)
+ *
+ * @param entity - The detected PII entity to redact.
+ * @returns Replacement string with per-word masking applied.
+ */
+function applyMask(entity) {
+    // Split on whitespace boundaries.  Each segment is treated as one "word".
+    return entity.text
+        .split(/(\s+)/)
+        .map((segment) => {
+        // Preserve whitespace segments as-is so spacing is maintained.
+        if (/^\s+$/.test(segment)) {
+            return segment;
+        }
+        if (segment.length <= 1) {
+            // Single-character word — nothing to mask.
+            return segment;
+        }
+        // Keep the first character; replace the rest with '*'.
+        return segment[0] + '*'.repeat(segment.length - 1);
+    })
+        .join('');
+}
+/**
+ * Produces a deterministic content-based hash token for the given entity.
+ *
+ * The replacement token embeds the entity type and a truncated SHA-256 digest
+ * (10 lowercase hex characters) of the **original text**.  This preserves
+ * de-duplication semantics: the same input text always produces the same token,
+ * so consumers can detect when the same PII value appeared multiple times
+ * without being able to recover the original value.
+ *
+ * @example `[PERSON:a1b2c3d4e5]` (exact hash depends on input text)
+ *
+ * @param entity - The detected PII entity to redact.
+ * @returns Replacement string of the form `[TYPE:xxxxxxxxxx]`.
+ */
+function applyHash(entity) {
+    // Compute a SHA-256 digest of the original matched text.
+    const digest = createHash('sha256').update(entity.text, 'utf8').digest('hex');
+    // Truncate to 10 hex characters — enough entropy to identify duplicates
+    // while keeping the token compact.
+    const shortHash = digest.slice(0, 10);
+    return `[${entity.entityType}:${shortHash}]`;
+}
+/**
+ * Produces an XML-style PII category tag wrapping a generic `REDACTED`
+ * placeholder.
+ *
+ * The tag makes the redaction visible to any downstream parser that understands
+ * the `<PII>` schema, enabling programmatic unredaction if the original values
+ * are stored separately with an audit trail.
+ *
+ * @example `<PII type="PERSON">REDACTED</PII>`
+ *
+ * @param entity - The detected PII entity to redact.
+ * @returns Replacement string.
+ */
+function applyCategoryTag(entity) {
+    return `<PII type="${entity.entityType}">REDACTED</PII>`;
+}
+// ---------------------------------------------------------------------------
+// Router
+// ---------------------------------------------------------------------------
+/**
+ * Returns the replacement string for a single entity according to the chosen
+ * {@link RedactionStyle}.
+ *
+ * @param entity - The entity span to redact.
+ * @param style  - How the PII value should be replaced.
+ * @returns The replacement text to splice into the output string.
+ *
+ * @throws {Error} When an unrecognised style value is passed (compile-time
+ *                 exhaustiveness check via the `never` branch).
+ */
+function getReplacementText(entity, style) {
+    switch (style) {
+        case 'placeholder':
+            return applyPlaceholder(entity);
+        case 'mask':
+            return applyMask(entity);
+        case 'hash':
+            return applyHash(entity);
+        case 'category-tag':
+            return applyCategoryTag(entity);
+        default: {
+            // TypeScript exhaustiveness guard — should never be reached at runtime
+            // if the type system is intact.
+            const _exhaustive = style;
+            throw new Error(`Unknown redaction style: ${String(_exhaustive)}`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Applies PII redaction to `text` by replacing each entity span with a token
+ * generated according to the specified {@link RedactionStyle}.
+ *
+ * ### Algorithm
+ *
+ * 1. If `entities` is empty, return `text` unchanged.
+ * 2. Sort entities by `start` offset in **descending** order (right to left).
+ * 3. Iteratively replace each span via `String.prototype.slice` — because
+ *    processing proceeds right-to-left, earlier spans retain their original
+ *    offsets and can be replaced without adjustment.
+ * 4. Return the final redacted string.
+ *
+ * The function assumes that the provided `entities` are **non-overlapping**.
+ * Overlapping spans must be resolved by {@link mergeEntities} before calling
+ * this function.  Overlapping spans produce undefined output.
+ *
+ * @param text     - The original input string to redact.
+ * @param entities - Non-overlapping PII entities to redact.  May be unsorted;
+ *                   the function sorts internally.
+ * @param style    - How each PII span should be replaced.
+ * @returns The redacted string with all PII spans replaced according to
+ *          `style`.
+ *
+ * @example
+ * ```ts
+ * const redacted = redactText(
+ *   'Contact John Smith at john@example.com please',
+ *   [
+ *     { entityType: 'PERSON', text: 'John Smith', start: 8, end: 18, score: 0.95, source: 'ner-model' },
+ *     { entityType: 'EMAIL',  text: 'john@example.com', start: 22, end: 38, score: 1.0, source: 'regex' },
+ *   ],
+ *   'placeholder',
+ * );
+ * // → 'Contact [PERSON] at [EMAIL] please'
+ * ```
+ */
+export function redactText(text, entities, style) {
+    // Fast path: nothing to redact.
+    if (entities.length === 0) {
+        return text;
+    }
+    // Sort by start offset descending so that right-most spans are replaced
+    // first, preserving the validity of earlier offsets.
+    const sorted = entities.slice().sort((a, b) => b.start - a.start);
+    // Apply replacements left-fold over the string, processing right-to-left.
+    let result = text;
+    for (const entity of sorted) {
+        const replacement = getReplacementText(entity, style);
+        // Splice: keep everything before the span, insert replacement, keep
+        // everything after the span.
+        result =
+            result.slice(0, entity.start) +
+                replacement +
+                result.slice(entity.end);
+    }
+    return result;
+}
+//# sourceMappingURL=RedactionEngine.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RedactionEngine.js","sourceRoot":"","sources":["../../../../src/extensions/packs/pii-redaction/RedactionEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAGpC,8EAA8E;AAC9E,+BAA+B;AAC/B,8EAA8E;AAE9E;;;;;;;;;;;GAWG;AACH,SAAS,gBAAgB,CAAC,MAAiB;IACzC,OAAO,IAAI,MAAM,CAAC,UAAU,GAAG,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAS,SAAS,CAAC,MAAiB;IAClC,0EAA0E;IAC1E,OAAO,MAAM,CAAC,IAAI;SACf,KAAK,CAAC,OAAO,CAAC;SACd,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QACf,+DAA+D;QAC/D,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YAC1B,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;YACxB,2CAA2C;YAC3C,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,uDAAuD;QACvD,OAAO,OAAO,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACrD,CAAC,CAAC;SACD,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAS,SAAS,CAAC,MAAiB;IAClC,yDAAyD;IACzD,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAE9E,wEAAwE;IACxE,mCAAmC;IACnC,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAEtC,OAAO,IAAI,MAAM,CAAC,UAAU,IAAI,SAAS,GAAG,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAS,gBAAgB,CAAC,MAAiB;IACzC,OAAO,cAAc,MAAM,CAAC,UAAU,kBAAkB,CAAC;AAC3D,CAAC;AAED,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,SAAS,kBAAkB,CAAC,MAAiB,EAAE,KAAqB;IAClE,QAAQ,KAAK,EAAE,CAAC;QACd,KAAK,aAAa;YAChB,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAElC,KAAK,MAAM;YACT,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC;QAE3B,KAAK,MAAM;YACT,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC;QAE3B,KAAK,cAAc;YACjB,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAElC,OAAO,CAAC,CAAC,CAAC;YACR,uEAAuE;YACvE,gCAAgC;YAChC,MAAM,WAAW,GAAU,KAAK,CAAC;YACjC,MAAM,IAAI,KAAK,CAAC,4BAA4B,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QACrE,CAAC;IACH,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,UAAU,UAAU,CACxB,IAAY,EACZ,QAAqB,EACrB,KAAqB;IAErB,gCAAgC;IAChC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,wEAAwE;IACxE,qDAAqD;IACrD,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAElE,0EAA0E;IAC1E,IAAI,MAAM,GAAG,IAAI,CAAC;IAClB,KAAK,MAAM,MAAM,IAAI,MAAM,EAAE,CAAC;QAC5B,MAAM,WAAW,GAAG,kBAAkB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAEtD,oEAAoE;QACpE,6BAA6B;QAC7B,MAAM;YACJ,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC;gBAC7B,WAAW;gBACX,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

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

@@ -0,0 +1,90 @@
+/**
+ * @file index.ts
+ * @description Pack factory for the PII Redaction extension pack.
+ *
+ * This module exports the main `createPiiRedactionPack()` factory function
+ * that assembles the guardrail, scan tool, and redact tool into a single
+ * {@link ExtensionPack} ready for registration with the AgentOS extension
+ * manager.
+ *
+ * It also exports a `createExtensionPack()` bridge function that conforms to
+ * the AgentOS manifest factory convention, delegating to
+ * `createPiiRedactionPack()` with options extracted from the
+ * {@link ExtensionPackContext}.
+ *
+ * ### Lifecycle
+ *
+ * Components are built eagerly at pack creation time for direct programmatic
+ * use.  When the pack is activated by the extension manager, the `onActivate`
+ * hook rebuilds all components with the manager's shared service registry and
+ * secret resolver, ensuring heavyweight services (NLP models, NER weights)
+ * are shared across the agent.
+ *
+ * @module pii-redaction
+ */
+import type { ExtensionPack, ExtensionPackContext } from '../../manifest';
+import type { PiiRedactionPackOptions } from './types';
+/**
+ * Re-export all types from the PII redaction type definitions so consumers
+ * can import everything from a single entry point:
+ * ```ts
+ * import { createPiiRedactionPack, PiiEntityType } from './pii-redaction';
+ * ```
+ */
+export * from './types';
+/**
+ * Create an ExtensionPack that bundles the PII redaction guardrail with
+ * the `pii_scan` and `pii_redact` tools.
+ *
+ * ### Default behaviour (zero-config)
+ * When called without options, the pack detects all 18 PII entity types at
+ * a confidence threshold of 0.5, redacts using the `placeholder` style
+ * (`[EMAIL]`), and evaluates both input and output.
+ *
+ * ### Activation lifecycle
+ * The pack uses mutable internal state (`state.services`, `state.getSecret`)
+ * that is upgraded when the extension manager calls `onActivate` with its
+ * shared service registry and secret resolver.  All three components
+ * (guardrail, scan tool, redact tool) are rebuilt at that point so they
+ * share NLP/NER model instances with other extensions.
+ *
+ * @param options - Optional pack-level configuration.  All properties have
+ *                  sensible defaults; see {@link PiiRedactionPackOptions}.
+ * @returns A fully-configured {@link ExtensionPack} with one guardrail and
+ *          two tools.
+ *
+ * @example
+ * ```ts
+ * import { createPiiRedactionPack } from './pii-redaction';
+ *
+ * const pack = createPiiRedactionPack({
+ *   entityTypes: ['EMAIL', 'PHONE', 'SSN'],
+ *   redactionStyle: 'mask',
+ *   guardrailScope: 'both',
+ * });
+ * ```
+ */
+export declare function createPiiRedactionPack(options?: PiiRedactionPackOptions): ExtensionPack;
+/**
+ * AgentOS manifest factory function.
+ *
+ * This function conforms to the convention expected by the extension loader
+ * when resolving packs from manifests.  It extracts `options` from the
+ * {@link ExtensionPackContext} and delegates to {@link createPiiRedactionPack}.
+ *
+ * @param context - Manifest context containing optional pack options, secret
+ *                  resolver, and shared service registry.
+ * @returns A fully-configured {@link ExtensionPack}.
+ *
+ * @example
+ * ```ts
+ * // In an AgentOS manifest:
+ * {
+ *   "packs": [
+ *     { "module": "./pii-redaction", "options": { "redactionStyle": "hash" } }
+ *   ]
+ * }
+ * ```
+ */
+export declare function createExtensionPack(context: ExtensionPackContext): ExtensionPack;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/extensions/packs/pii-redaction/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAG1E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AASvD;;;;;;GAMG;AACH,cAAc,SAAS,CAAC;AAMxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,CAAC,EAAE,uBAAuB,GAChC,aAAa,CA2Gf;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAEhF"}