@framers/agentos 0.1.55 → 0.1.56

package/dist/extensions/packs/pii-redaction/recognizers/RegexRecognizer.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @file RegexRecognizer.ts
+ * @description Tier 1 PII recogniser that delegates pattern matching to the
+ * `openredaction` library.
+ *
+ * OpenRedaction ships with 500+ curated regex patterns covering emails, SSNs,
+ * credit cards, phone numbers, IP addresses, IBANs, passports, API keys, and
+ * many more.  This recogniser wraps its `OpenRedaction.detect()` method,
+ * normalises the results into the pipeline's {@link PiiEntity} shape, and
+ * applies entity-type filtering so only the categories requested by the caller
+ * are evaluated.
+ *
+ * @module pii-redaction/recognizers
+ */
+import type { PiiEntity, PiiEntityType } from '../types';
+import type { IEntityRecognizer, RecognizeOptions } from './IEntityRecognizer';
+/**
+ * Tier 1 entity recogniser backed by the `openredaction` library.
+ *
+ * ### How it works
+ * 1. On construction an {@link OpenRedaction} instance is created with the
+ *    full set of mapped patterns pre-loaded and pre-compiled.
+ * 2. When {@link recognize} is called, pattern names are optionally filtered
+ *    to the requested {@link PiiEntityType} subset.
+ * 3. `OpenRedaction.detect()` runs all active patterns against the input and
+ *    returns raw detections with position offsets.
+ * 4. Results are mapped to {@link PiiEntity} objects with a fixed high score
+ *    (>= 0.85) because regex matches are deterministic.
+ *
+ * ### Thread safety
+ * Each call to `recognize` creates a fresh `OpenRedaction` instance with
+ * only the needed patterns so there is no shared mutable state between
+ * concurrent invocations.
+ *
+ * @example
+ * ```ts
+ * const recognizer = new RegexRecognizer();
+ * const entities = await recognizer.recognize(
+ *   'Email me at alice@example.com',
+ *   { entityTypes: ['EMAIL'] },
+ * );
+ * // entities[0].entityType === 'EMAIL'
+ * // entities[0].score >= 0.85
+ * ```
+ */
+export declare class RegexRecognizer implements IEntityRecognizer {
+    /** @inheritdoc */
+    readonly name = "RegexRecognizer";
+    /** @inheritdoc */
+    readonly supportedEntities: PiiEntityType[];
+    /**
+     * Minimum confidence score assigned to regex-based detections.
+     * Regex matches are deterministic so they receive a high baseline; the
+     * openredaction library may report its own `confidence` which we bump
+     * to at least this floor value.
+     */
+    private static readonly MIN_SCORE;
+    /**
+     * Lazily-resolved reference to the `OpenRedaction` constructor from the
+     * `openredaction` package.  Stored after first successful dynamic import
+     * to avoid repeated module resolution on subsequent calls.
+     */
+    private OpenRedactionCtor;
+    /**
+     * Scan the input text for PII entities using openredaction regex patterns.
+     *
+     * @param input   - Raw text to analyse.
+     * @param options - Optional filtering and context hints.
+     * @returns Array of detected {@link PiiEntity} objects, possibly empty.
+     */
+    recognize(input: string, options?: RecognizeOptions): Promise<PiiEntity[]>;
+    /** @inheritdoc */
+    dispose(): Promise<void>;
+    /**
+     * Lazily imports the `openredaction` module and caches its constructor.
+     *
+     * @returns The `OpenRedaction` class constructor.
+     * @throws If the `openredaction` package is not installed.
+     */
+    private ensureOpenRedaction;
+    /**
+     * Resolves the list of openredaction pattern names to activate for the
+     * given entity-type filter.
+     *
+     * When no filter is provided, all mapped patterns are returned.
+     *
+     * @param entityTypes - Optional subset of {@link PiiEntityType} to detect.
+     * @returns Array of openredaction pattern name strings.
+     */
+    private resolvePatternNames;
+    /**
+     * Converts raw openredaction detection objects into {@link PiiEntity}
+     * instances, filtering out any that don't map to a requested entity type.
+     *
+     * @param detections  - Raw detections from `OpenRedaction.detect()`.
+     * @param input       - The original input text (used to extract `text`
+     *                      from positional offsets when needed).
+     * @param entityTypes - Optional entity-type filter for post-filtering.
+     * @returns Mapped and filtered array of {@link PiiEntity}.
+     */
+    private mapDetections;
+}
+//# sourceMappingURL=RegexRecognizer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RegexRecognizer.d.ts","sourceRoot":"","sources":["../../../../../src/extensions/packs/pii-redaction/recognizers/RegexRecognizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AA2F/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,eAAgB,YAAW,iBAAiB;IACvD,kBAAkB;IAClB,SAAgB,IAAI,qBAAqB;IAEzC,kBAAkB;IAClB,SAAgB,iBAAiB,EAAE,aAAa,EAAE,CAehD;IAEF;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAEzC;;;;OAIG;IACH,OAAO,CAAC,iBAAiB,CAA+E;IAExG;;;;;;OAMG;IACU,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAsBvF,kBAAkB;IACL,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAUrC;;;;;OAKG;YACW,mBAAmB;IAajC;;;;;;;;OAQG;IACH,OAAO,CAAC,mBAAmB;IAe3B;;;;;;;;;OASG;IACH,OAAO,CAAC,aAAa;CA2CtB"}

package/dist/extensions/packs/pii-redaction/recognizers/RegexRecognizer.js

@@ -0,0 +1,275 @@
+/**
+ * @file RegexRecognizer.ts
+ * @description Tier 1 PII recogniser that delegates pattern matching to the
+ * `openredaction` library.
+ *
+ * OpenRedaction ships with 500+ curated regex patterns covering emails, SSNs,
+ * credit cards, phone numbers, IP addresses, IBANs, passports, API keys, and
+ * many more.  This recogniser wraps its `OpenRedaction.detect()` method,
+ * normalises the results into the pipeline's {@link PiiEntity} shape, and
+ * applies entity-type filtering so only the categories requested by the caller
+ * are evaluated.
+ *
+ * @module pii-redaction/recognizers
+ */
+// ---------------------------------------------------------------------------
+// Mapping from openredaction pattern type strings to PiiEntityType
+// ---------------------------------------------------------------------------
+/**
+ * Maps openredaction's built-in pattern `type` strings to our canonical
+ * {@link PiiEntityType} values.
+ *
+ * Only types that have a direct or near-direct counterpart are listed.
+ * Unmapped openredaction types are silently dropped so that we don't pollute
+ * downstream consumers with categories they can't act on.
+ */
+const OPENREDACTION_TYPE_MAP = {
+    EMAIL: 'EMAIL',
+    SSN: 'SSN',
+    CREDIT_CARD: 'CREDIT_CARD',
+    PHONE_US: 'PHONE',
+    PHONE_UK: 'PHONE',
+    PHONE_UK_MOBILE: 'PHONE',
+    PHONE_INTERNATIONAL: 'PHONE',
+    IPV4: 'IP_ADDRESS',
+    IPV6: 'IP_ADDRESS',
+    IBAN: 'IBAN',
+    PASSPORT_US: 'PASSPORT',
+    PASSPORT_UK: 'PASSPORT',
+    PASSPORT_MRZ_TD3: 'PASSPORT',
+    PASSPORT_MRZ_TD1: 'PASSPORT',
+    DRIVING_LICENSE_US: 'DRIVERS_LICENSE',
+    DRIVING_LICENSE_UK: 'DRIVERS_LICENSE',
+    DATE_OF_BIRTH: 'DATE_OF_BIRTH',
+    GENERIC_API_KEY: 'API_KEY',
+    OPENAI_API_KEY: 'API_KEY',
+    GOOGLE_API_KEY: 'API_KEY',
+    STRIPE_API_KEY: 'API_KEY',
+    GITHUB_TOKEN: 'API_KEY',
+    BEARER_TOKEN: 'API_KEY',
+    AWS_ACCESS_KEY: 'AWS_KEY',
+    AWS_SECRET_KEY: 'AWS_KEY',
+    BITCOIN_ADDRESS: 'CRYPTO_ADDRESS',
+    ETHEREUM_ADDRESS: 'CRYPTO_ADDRESS',
+    LITECOIN_ADDRESS: 'CRYPTO_ADDRESS',
+    MONERO_ADDRESS: 'CRYPTO_ADDRESS',
+    RIPPLE_ADDRESS: 'CRYPTO_ADDRESS',
+    CARDANO_ADDRESS: 'CRYPTO_ADDRESS',
+    SOLANA_ADDRESS: 'CRYPTO_ADDRESS',
+    NAME: 'PERSON',
+    TAX_ID: 'GOV_ID',
+    NATIONAL_INSURANCE_UK: 'GOV_ID',
+    NHS_NUMBER: 'GOV_ID',
+    ITIN: 'GOV_ID',
+    SIN_CA: 'GOV_ID',
+};
+/**
+ * Inverse map: for a given {@link PiiEntityType}, lists all openredaction
+ * pattern type strings that map to it.  Built lazily on first access.
+ */
+let piiTypeToPatternNames = null;
+/**
+ * Builds (or returns the cached) inverse mapping from {@link PiiEntityType}
+ * to openredaction pattern names.
+ */
+function getPiiTypeToPatternNames() {
+    if (piiTypeToPatternNames)
+        return piiTypeToPatternNames;
+    piiTypeToPatternNames = new Map();
+    for (const [patternName, piiType] of Object.entries(OPENREDACTION_TYPE_MAP)) {
+        const existing = piiTypeToPatternNames.get(piiType) ?? [];
+        existing.push(patternName);
+        piiTypeToPatternNames.set(piiType, existing);
+    }
+    return piiTypeToPatternNames;
+}
+// ---------------------------------------------------------------------------
+// Default patterns to load when no entity-type filter is applied
+// ---------------------------------------------------------------------------
+/**
+ * The full list of openredaction pattern names we want available by default.
+ * This is the union of all values in {@link OPENREDACTION_TYPE_MAP}.
+ */
+const DEFAULT_PATTERN_NAMES = Object.keys(OPENREDACTION_TYPE_MAP);
+// ---------------------------------------------------------------------------
+// RegexRecognizer
+// ---------------------------------------------------------------------------
+/**
+ * Tier 1 entity recogniser backed by the `openredaction` library.
+ *
+ * ### How it works
+ * 1. On construction an {@link OpenRedaction} instance is created with the
+ *    full set of mapped patterns pre-loaded and pre-compiled.
+ * 2. When {@link recognize} is called, pattern names are optionally filtered
+ *    to the requested {@link PiiEntityType} subset.
+ * 3. `OpenRedaction.detect()` runs all active patterns against the input and
+ *    returns raw detections with position offsets.
+ * 4. Results are mapped to {@link PiiEntity} objects with a fixed high score
+ *    (>= 0.85) because regex matches are deterministic.
+ *
+ * ### Thread safety
+ * Each call to `recognize` creates a fresh `OpenRedaction` instance with
+ * only the needed patterns so there is no shared mutable state between
+ * concurrent invocations.
+ *
+ * @example
+ * ```ts
+ * const recognizer = new RegexRecognizer();
+ * const entities = await recognizer.recognize(
+ *   'Email me at alice@example.com',
+ *   { entityTypes: ['EMAIL'] },
+ * );
+ * // entities[0].entityType === 'EMAIL'
+ * // entities[0].score >= 0.85
+ * ```
+ */
+export class RegexRecognizer {
+    constructor() {
+        /** @inheritdoc */
+        this.name = 'RegexRecognizer';
+        /** @inheritdoc */
+        this.supportedEntities = [
+            'SSN',
+            'CREDIT_CARD',
+            'EMAIL',
+            'PHONE',
+            'IP_ADDRESS',
+            'IBAN',
+            'PASSPORT',
+            'DRIVERS_LICENSE',
+            'DATE_OF_BIRTH',
+            'API_KEY',
+            'AWS_KEY',
+            'CRYPTO_ADDRESS',
+            'PERSON',
+            'GOV_ID',
+        ];
+        /**
+         * Lazily-resolved reference to the `OpenRedaction` constructor from the
+         * `openredaction` package.  Stored after first successful dynamic import
+         * to avoid repeated module resolution on subsequent calls.
+         */
+        this.OpenRedactionCtor = null;
+    }
+    /**
+     * Scan the input text for PII entities using openredaction regex patterns.
+     *
+     * @param input   - Raw text to analyse.
+     * @param options - Optional filtering and context hints.
+     * @returns Array of detected {@link PiiEntity} objects, possibly empty.
+     */
+    async recognize(input, options) {
+        // Determine which openredaction patterns to activate based on the
+        // caller's entity-type filter.
+        const patternNames = this.resolvePatternNames(options?.entityTypes);
+        // Nothing to do if no patterns map to the requested entity types.
+        if (patternNames.length === 0)
+            return [];
+        // Lazily import openredaction (avoids top-level side effects and keeps
+        // the module optional for environments that don't need regex detection).
+        const Ctor = await this.ensureOpenRedaction();
+        // Create a scoped instance with only the relevant patterns loaded.
+        const instance = new Ctor({ patterns: patternNames });
+        // Run detection — openredaction returns a promise.
+        const result = await instance.detect(input);
+        // Map openredaction detections to our PiiEntity shape.
+        return this.mapDetections(result.detections, input, options?.entityTypes);
+    }
+    /** @inheritdoc */
+    async dispose() {
+        // No long-lived resources to release; each `recognize` call creates its
+        // own scoped OpenRedaction instance.
+        this.OpenRedactionCtor = null;
+    }
+    // -----------------------------------------------------------------------
+    // Private helpers
+    // -----------------------------------------------------------------------
+    /**
+     * Lazily imports the `openredaction` module and caches its constructor.
+     *
+     * @returns The `OpenRedaction` class constructor.
+     * @throws If the `openredaction` package is not installed.
+     */
+    async ensureOpenRedaction() {
+        if (this.OpenRedactionCtor)
+            return this.OpenRedactionCtor;
+        // Dynamic import so the dependency is optional at the module level.
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const mod = await import('openredaction');
+        this.OpenRedactionCtor = mod.OpenRedaction;
+        return this.OpenRedactionCtor;
+    }
+    /**
+     * Resolves the list of openredaction pattern names to activate for the
+     * given entity-type filter.
+     *
+     * When no filter is provided, all mapped patterns are returned.
+     *
+     * @param entityTypes - Optional subset of {@link PiiEntityType} to detect.
+     * @returns Array of openredaction pattern name strings.
+     */
+    resolvePatternNames(entityTypes) {
+        // No filter → use everything we have mapped.
+        if (!entityTypes || entityTypes.length === 0)
+            return DEFAULT_PATTERN_NAMES;
+        const inverse = getPiiTypeToPatternNames();
+        const names = [];
+        for (const piiType of entityTypes) {
+            const mapped = inverse.get(piiType);
+            if (mapped)
+                names.push(...mapped);
+        }
+        return names;
+    }
+    /**
+     * Converts raw openredaction detection objects into {@link PiiEntity}
+     * instances, filtering out any that don't map to a requested entity type.
+     *
+     * @param detections  - Raw detections from `OpenRedaction.detect()`.
+     * @param input       - The original input text (used to extract `text`
+     *                      from positional offsets when needed).
+     * @param entityTypes - Optional entity-type filter for post-filtering.
+     * @returns Mapped and filtered array of {@link PiiEntity}.
+     */
+    mapDetections(detections, input, entityTypes) {
+        const entities = [];
+        const allowedTypes = entityTypes ? new Set(entityTypes) : null;
+        for (const det of detections) {
+            const mappedType = OPENREDACTION_TYPE_MAP[det.type];
+            // Skip detections whose openredaction type has no mapping.
+            if (!mappedType)
+                continue;
+            // Skip if the mapped type isn't in the caller's requested set.
+            if (allowedTypes && !allowedTypes.has(mappedType))
+                continue;
+            // Compute start/end offsets from the position tuple.
+            const [start, end] = det.position;
+            // Extract the matched text span from the input for consistency.
+            const text = det.value ?? input.slice(start, end);
+            // Confidence: take the higher of openredaction's score and our floor.
+            const score = Math.max(det.confidence ?? RegexRecognizer.MIN_SCORE, RegexRecognizer.MIN_SCORE);
+            entities.push({
+                entityType: mappedType,
+                text,
+                start,
+                end,
+                score,
+                source: 'regex',
+                metadata: {
+                    openredactionType: det.type,
+                    placeholder: det.placeholder,
+                    severity: det.severity,
+                },
+            });
+        }
+        return entities;
+    }
+}
+/**
+ * Minimum confidence score assigned to regex-based detections.
+ * Regex matches are deterministic so they receive a high baseline; the
+ * openredaction library may report its own `confidence` which we bump
+ * to at least this floor value.
+ */
+RegexRecognizer.MIN_SCORE = 0.85;
+//# sourceMappingURL=RegexRecognizer.js.map

package/dist/extensions/packs/pii-redaction/recognizers/RegexRecognizer.js.map

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

package/dist/extensions/packs/pii-redaction/tools/PiiRedactTool.d.ts

@@ -0,0 +1,118 @@
+/**
+ * @file PiiRedactTool.ts
+ * @description AgentOS tool that detects and redacts PII (Personally
+ * Identifiable Information) from text, returning both the redacted output
+ * and the detection metadata.
+ *
+ * This tool wraps both the {@link PiiDetectionPipeline} and the
+ * {@link redactText} engine, providing a single-step "detect then redact"
+ * operation.  Agents invoke it when they need sanitised text output, for
+ * example before storing user-provided content in a database or forwarding
+ * it to an external API.
+ *
+ * @module pii-redaction/tools/PiiRedactTool
+ */
+import type { ISharedServiceRegistry } from '../../../ISharedServiceRegistry';
+import type { ITool, ToolExecutionContext, ToolExecutionResult, JSONSchemaObject } from '../../../../core/tools/ITool';
+import type { PiiRedactionPackOptions, PiiDetectionResult, RedactionStyle } from '../types';
+/**
+ * Input arguments accepted by the {@link PiiRedactTool}.
+ *
+ * Only `text` is required.  The optional `redactionStyle` allows the caller
+ * to override the pack-level default for this single invocation.
+ */
+export interface PiiRedactInput {
+    /** The text from which PII should be redacted. */
+    text: string;
+    /**
+     * Optional override for the redaction style.
+     * When omitted the tool uses the pack-level redaction style configuration.
+     */
+    redactionStyle?: RedactionStyle;
+}
+/**
+ * Output returned by the {@link PiiRedactTool} on successful execution.
+ *
+ * Contains both the redacted text and the full detection result so callers
+ * can inspect what was found and how confident the detections were.
+ */
+export interface PiiRedactOutput {
+    /** The text with all detected PII spans replaced. */
+    redactedText: string;
+    /** The original input text (for reference / diff comparison). */
+    originalText: string;
+    /**
+     * Whether any PII was detected and redacted.
+     * When `false`, `redactedText` is identical to `originalText`.
+     */
+    wasRedacted: boolean;
+    /** Full detection result including entities, timing, and summary. */
+    detectionResult: PiiDetectionResult;
+}
+/**
+ * AgentOS tool that detects PII in text and returns a redacted version.
+ *
+ * ### Usage by agents
+ * ```json
+ * {
+ *   "tool": "pii_redact",
+ *   "arguments": {
+ *     "text": "My SSN is 123-45-6789",
+ *     "redactionStyle": "mask"
+ *   }
+ * }
+ * ```
+ *
+ * ### Return value
+ * A {@link PiiRedactOutput} containing the redacted text, the original text,
+ * a boolean flag indicating whether any PII was found, and the full
+ * {@link PiiDetectionResult} for audit / observability.
+ *
+ * @implements {ITool<PiiRedactInput, PiiRedactOutput>}
+ */
+export declare class PiiRedactTool implements ITool<PiiRedactInput, PiiRedactOutput> {
+    /** Globally unique identifier for the tool. */
+    readonly id = "pii_redact";
+    /** Functional name used by LLMs in tool call requests. */
+    readonly name = "pii_redact";
+    /** Human-readable display name for UIs and logs. */
+    readonly displayName = "PII Redactor";
+    /** Detailed description for LLM tool selection. */
+    readonly description: string;
+    /** Tool category for filtering and grouping. */
+    readonly category = "security";
+    /** This tool is read-only and has no side effects. */
+    readonly hasSideEffects = false;
+    /** JSON Schema describing the expected input arguments. */
+    readonly inputSchema: JSONSchemaObject;
+    /** Detection pipeline instance shared across invocations. */
+    private readonly pipeline;
+    /** Default redaction style from pack-level configuration. */
+    private readonly defaultRedactionStyle;
+    /**
+     * Construct a new PiiRedactTool.
+     *
+     * @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, and detection
+     *                   tier flags.
+     */
+    constructor(services: ISharedServiceRegistry, options: PiiRedactionPackOptions);
+    /**
+     * Execute the PII redaction on the provided text.
+     *
+     * Runs the full detection pipeline, then applies the configured (or
+     * overridden) redaction style to all detected PII spans.  Returns both
+     * the sanitised text and the raw detection result for audit purposes.
+     *
+     * @param args    - Input arguments containing the text to redact and an
+     *                  optional redaction style override.
+     * @param context - Tool execution context (unused by this tool but required
+     *                  by the ITool interface).
+     * @returns A promise resolving to the tool execution result containing the
+     *          {@link PiiRedactOutput}.
+     */
+    execute(args: PiiRedactInput, context: ToolExecutionContext): Promise<ToolExecutionResult<PiiRedactOutput>>;
+}
+//# sourceMappingURL=PiiRedactTool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PiiRedactTool.d.ts","sourceRoot":"","sources":["../../../../../src/extensions/packs/pii-redaction/tools/PiiRedactTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAC9E,OAAO,KAAK,EACV,KAAK,EACL,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EACjB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EACV,uBAAuB,EACvB,kBAAkB,EAClB,cAAc,EACf,MAAM,UAAU,CAAC;AAQlB;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,qDAAqD;IACrD,YAAY,EAAE,MAAM,CAAC;IAErB,iEAAiE;IACjE,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;IAErB,qEAAqE;IACrE,eAAe,EAAE,kBAAkB,CAAC;CACrC;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,aAAc,YAAW,KAAK,CAAC,cAAc,EAAE,eAAe,CAAC;IAK1E,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,gBAAgB;IAE3B,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,gBAAgB;IAE7B,oDAAoD;IACpD,QAAQ,CAAC,WAAW,kBAAkB;IAEtC,mDAAmD;IACnD,QAAQ,CAAC,WAAW,SAI+B;IAEnD,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,cAAc;IAE/B,sDAAsD;IACtD,QAAQ,CAAC,cAAc,SAAS;IAEhC,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAiBpC;IAMF,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuB;IAEhD,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAiB;IAMvD;;;;;;;;OAQG;gBAED,QAAQ,EAAE,sBAAsB,EAChC,OAAO,EAAE,uBAAuB;IAUlC;;;;;;;;;;;;;OAaG;IACG,OAAO,CACX,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,eAAe,CAAC,CAAC;CA6CjD"}

package/dist/extensions/packs/pii-redaction/tools/PiiRedactTool.js

@@ -0,0 +1,152 @@
+/**
+ * @file PiiRedactTool.ts
+ * @description AgentOS tool that detects and redacts PII (Personally
+ * Identifiable Information) from text, returning both the redacted output
+ * and the detection metadata.
+ *
+ * This tool wraps both the {@link PiiDetectionPipeline} and the
+ * {@link redactText} engine, providing a single-step "detect then redact"
+ * operation.  Agents invoke it when they need sanitised text output, for
+ * example before storing user-provided content in a database or forwarding
+ * it to an external API.
+ *
+ * @module pii-redaction/tools/PiiRedactTool
+ */
+import { PiiDetectionPipeline } from '../PiiDetectionPipeline.js';
+import { redactText } from '../RedactionEngine.js';
+// ---------------------------------------------------------------------------
+// PiiRedactTool
+// ---------------------------------------------------------------------------
+/**
+ * AgentOS tool that detects PII in text and returns a redacted version.
+ *
+ * ### Usage by agents
+ * ```json
+ * {
+ *   "tool": "pii_redact",
+ *   "arguments": {
+ *     "text": "My SSN is 123-45-6789",
+ *     "redactionStyle": "mask"
+ *   }
+ * }
+ * ```
+ *
+ * ### Return value
+ * A {@link PiiRedactOutput} containing the redacted text, the original text,
+ * a boolean flag indicating whether any PII was found, and the full
+ * {@link PiiDetectionResult} for audit / observability.
+ *
+ * @implements {ITool<PiiRedactInput, PiiRedactOutput>}
+ */
+export class PiiRedactTool {
+    // -----------------------------------------------------------------------
+    // Constructor
+    // -----------------------------------------------------------------------
+    /**
+     * Construct a new PiiRedactTool.
+     *
+     * @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, and detection
+     *                   tier flags.
+     */
+    constructor(services, options) {
+        // -----------------------------------------------------------------------
+        // ITool metadata
+        // -----------------------------------------------------------------------
+        /** Globally unique identifier for the tool. */
+        this.id = 'pii_redact';
+        /** Functional name used by LLMs in tool call requests. */
+        this.name = 'pii_redact';
+        /** Human-readable display name for UIs and logs. */
+        this.displayName = 'PII Redactor';
+        /** Detailed description for LLM tool selection. */
+        this.description = 'Detect and redact Personally Identifiable Information (PII) from text. ' +
+            'Returns both the redacted text and detection metadata including entity types, ' +
+            'positions, and confidence scores. Use this to sanitise text before storing, ' +
+            'logging, or forwarding it to external systems.';
+        /** Tool category for filtering and grouping. */
+        this.category = 'security';
+        /** This tool is read-only and has no side effects. */
+        this.hasSideEffects = false;
+        /** JSON Schema describing the expected input arguments. */
+        this.inputSchema = {
+            type: 'object',
+            properties: {
+                text: {
+                    type: 'string',
+                    description: 'The text from which PII should be redacted.',
+                },
+                redactionStyle: {
+                    type: 'string',
+                    enum: ['placeholder', 'mask', 'hash', 'category-tag'],
+                    description: 'How detected PII should be replaced. Defaults to the pack-level setting ' +
+                        '(typically "placeholder"). Options: "placeholder" ([EMAIL]), "mask" (j***@*****), ' +
+                        '"hash" ([EMAIL:a1b2c3d4e5]), "category-tag" (<PII type="EMAIL">REDACTED</PII>).',
+                },
+            },
+            required: ['text'],
+        };
+        this.pipeline = new PiiDetectionPipeline(services, options);
+        this.defaultRedactionStyle = options.redactionStyle ?? 'placeholder';
+    }
+    // -----------------------------------------------------------------------
+    // ITool — execute
+    // -----------------------------------------------------------------------
+    /**
+     * Execute the PII redaction on the provided text.
+     *
+     * Runs the full detection pipeline, then applies the configured (or
+     * overridden) redaction style to all detected PII spans.  Returns both
+     * the sanitised text and the raw detection result for audit purposes.
+     *
+     * @param args    - Input arguments containing the text to redact and an
+     *                  optional redaction style override.
+     * @param context - Tool execution context (unused by this tool but required
+     *                  by the ITool interface).
+     * @returns A promise resolving to the tool execution result containing the
+     *          {@link PiiRedactOutput}.
+     */
+    async execute(args, context) {
+        try {
+            // Validate that the required `text` argument is present and non-empty.
+            if (!args.text || typeof args.text !== 'string') {
+                return {
+                    success: false,
+                    error: 'The "text" argument is required and must be a non-empty string.',
+                };
+            }
+            // Run the detection pipeline.
+            const detectionResult = await this.pipeline.detect(args.text);
+            // Determine which redaction style to use (per-call override or default).
+            const style = args.redactionStyle ?? this.defaultRedactionStyle;
+            // Apply redaction to detected entity spans.
+            const redacted = redactText(args.text, detectionResult.entities, style);
+            // Build the output payload.
+            const output = {
+                redactedText: redacted,
+                originalText: args.text,
+                wasRedacted: detectionResult.entities.length > 0,
+                detectionResult,
+            };
+            return {
+                success: true,
+                output,
+            };
+        }
+        catch (error) {
+            // Wrap unexpected errors in a failed ToolExecutionResult rather than
+            // letting them propagate as unhandled exceptions.
+            const message = error instanceof Error
+                ? error.message
+                : 'Unknown error during PII redaction';
+            return {
+                success: false,
+                error: message,
+                details: { stack: error instanceof Error ? error.stack : undefined },
+            };
+        }
+    }
+}
+//# sourceMappingURL=PiiRedactTool.js.map

package/dist/extensions/packs/pii-redaction/tools/PiiRedactTool.js.map

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