@framers/agentos 0.1.55 → 0.1.56

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

@@ -0,0 +1,98 @@
+/**
+ * @file PiiScanTool.ts
+ * @description AgentOS tool that scans text for PII (Personally Identifiable
+ * Information) without modifying it.
+ *
+ * The tool wraps the {@link PiiDetectionPipeline} and exposes it as an
+ * {@link ITool} so agents can programmatically inspect text for sensitive
+ * data before deciding how to handle it (e.g., before logging, forwarding,
+ * or storing user-provided content).
+ *
+ * Unlike the guardrail (which intercepts I/O automatically), this tool is
+ * invoked explicitly by the agent or orchestrator when scan-only semantics
+ * are needed.
+ *
+ * @module pii-redaction/tools/PiiScanTool
+ */
+import type { ISharedServiceRegistry } from '../../../ISharedServiceRegistry';
+import type { ITool, ToolExecutionContext, ToolExecutionResult, JSONSchemaObject } from '../../../../core/tools/ITool';
+import type { PiiRedactionPackOptions, PiiDetectionResult, PiiEntityType } from '../types';
+/**
+ * Input arguments accepted by the {@link PiiScanTool}.
+ *
+ * Only `text` is required.  The optional `entityTypes` array allows the
+ * caller to narrow detection to a subset of PII categories, overriding the
+ * pack-level default for this single invocation.
+ */
+export interface PiiScanInput {
+    /** The text to scan for PII entities. */
+    text: string;
+    /**
+     * Optional subset of PII entity types to scan for.
+     * When omitted the tool uses the pack-level entity type configuration.
+     */
+    entityTypes?: PiiEntityType[];
+}
+/**
+ * AgentOS tool that detects PII entities in text and returns structured
+ * detection results without modifying the original text.
+ *
+ * ### Usage by agents
+ * ```json
+ * {
+ *   "tool": "pii_scan",
+ *   "arguments": {
+ *     "text": "Contact John Smith at john@example.com"
+ *   }
+ * }
+ * ```
+ *
+ * ### Return value
+ * A {@link PiiDetectionResult} containing the list of detected entities,
+ * processing metadata, and a human-readable summary.
+ *
+ * @implements {ITool<PiiScanInput, PiiDetectionResult>}
+ */
+export declare class PiiScanTool implements ITool<PiiScanInput, PiiDetectionResult> {
+    /** Globally unique identifier for the tool. */
+    readonly id = "pii_scan";
+    /** Functional name used by LLMs in tool call requests. */
+    readonly name = "pii_scan";
+    /** Human-readable display name for UIs and logs. */
+    readonly displayName = "PII Scanner";
+    /** 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;
+    /**
+     * Construct a new PiiScanTool.
+     *
+     * @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, and detection tier flags.
+     */
+    constructor(services: ISharedServiceRegistry, options: PiiRedactionPackOptions);
+    /**
+     * Execute the PII scan on the provided text.
+     *
+     * Runs the full detection pipeline (Regex -> NLP pre-filter -> NER -> LLM
+     * judge, as configured) and returns the detection result wrapped in a
+     * {@link ToolExecutionResult}.
+     *
+     * @param args    - Input arguments containing the text to scan and optional
+     *                  entity type filter.
+     * @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 PiiDetectionResult}.
+     */
+    execute(args: PiiScanInput, context: ToolExecutionContext): Promise<ToolExecutionResult<PiiDetectionResult>>;
+}
+//# sourceMappingURL=PiiScanTool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PiiScanTool.d.ts","sourceRoot":"","sources":["../../../../../src/extensions/packs/pii-redaction/tools/PiiScanTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;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,aAAa,EACd,MAAM,UAAU,CAAC;AAOlB;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,WAAW,CAAC,EAAE,aAAa,EAAE,CAAC;CAC/B;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,WAAY,YAAW,KAAK,CAAC,YAAY,EAAE,kBAAkB,CAAC;IAKzE,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,cAAc;IAEzB,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,cAAc;IAE3B,oDAAoD;IACpD,QAAQ,CAAC,WAAW,iBAAiB;IAErC,mDAAmD;IACnD,QAAQ,CAAC,WAAW,SAIiE;IAErF,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,cAAc;IAE/B,sDAAsD;IACtD,QAAQ,CAAC,cAAc,SAAS;IAEhC,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAgBpC;IAMF,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuB;IAMhD;;;;;;;OAOG;gBAED,QAAQ,EAAE,sBAAsB,EAChC,OAAO,EAAE,uBAAuB;IASlC;;;;;;;;;;;;;OAaG;IACG,OAAO,CACX,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,kBAAkB,CAAC,CAAC;CAmDpD"}

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

@@ -0,0 +1,153 @@
+/**
+ * @file PiiScanTool.ts
+ * @description AgentOS tool that scans text for PII (Personally Identifiable
+ * Information) without modifying it.
+ *
+ * The tool wraps the {@link PiiDetectionPipeline} and exposes it as an
+ * {@link ITool} so agents can programmatically inspect text for sensitive
+ * data before deciding how to handle it (e.g., before logging, forwarding,
+ * or storing user-provided content).
+ *
+ * Unlike the guardrail (which intercepts I/O automatically), this tool is
+ * invoked explicitly by the agent or orchestrator when scan-only semantics
+ * are needed.
+ *
+ * @module pii-redaction/tools/PiiScanTool
+ */
+import { PiiDetectionPipeline } from '../PiiDetectionPipeline.js';
+// ---------------------------------------------------------------------------
+// PiiScanTool
+// ---------------------------------------------------------------------------
+/**
+ * AgentOS tool that detects PII entities in text and returns structured
+ * detection results without modifying the original text.
+ *
+ * ### Usage by agents
+ * ```json
+ * {
+ *   "tool": "pii_scan",
+ *   "arguments": {
+ *     "text": "Contact John Smith at john@example.com"
+ *   }
+ * }
+ * ```
+ *
+ * ### Return value
+ * A {@link PiiDetectionResult} containing the list of detected entities,
+ * processing metadata, and a human-readable summary.
+ *
+ * @implements {ITool<PiiScanInput, PiiDetectionResult>}
+ */
+export class PiiScanTool {
+    // -----------------------------------------------------------------------
+    // Constructor
+    // -----------------------------------------------------------------------
+    /**
+     * Construct a new PiiScanTool.
+     *
+     * @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, and detection tier flags.
+     */
+    constructor(services, options) {
+        // -----------------------------------------------------------------------
+        // ITool metadata
+        // -----------------------------------------------------------------------
+        /** Globally unique identifier for the tool. */
+        this.id = 'pii_scan';
+        /** Functional name used by LLMs in tool call requests. */
+        this.name = 'pii_scan';
+        /** Human-readable display name for UIs and logs. */
+        this.displayName = 'PII Scanner';
+        /** Detailed description for LLM tool selection. */
+        this.description = 'Scan text for Personally Identifiable Information (PII) without modifying it. ' +
+            'Returns a structured result listing all detected PII entities with their types, ' +
+            'positions, confidence scores, and detection sources. Useful for auditing or ' +
+            'deciding how to handle sensitive data before logging, forwarding, or storing it.';
+        /** 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 to scan for PII entities.',
+                },
+                entityTypes: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Optional subset of PII entity types to scan for (e.g., ["EMAIL", "PHONE"]). ' +
+                        'When omitted, all configured entity types are scanned.',
+                },
+            },
+            required: ['text'],
+        };
+        this.pipeline = new PiiDetectionPipeline(services, options);
+    }
+    // -----------------------------------------------------------------------
+    // ITool — execute
+    // -----------------------------------------------------------------------
+    /**
+     * Execute the PII scan on the provided text.
+     *
+     * Runs the full detection pipeline (Regex -> NLP pre-filter -> NER -> LLM
+     * judge, as configured) and returns the detection result wrapped in a
+     * {@link ToolExecutionResult}.
+     *
+     * @param args    - Input arguments containing the text to scan and optional
+     *                  entity type filter.
+     * @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 PiiDetectionResult}.
+     */
+    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 result = await this.pipeline.detect(args.text);
+            // If the caller provided a subset of entity types, filter the results
+            // to only include entities matching those types.
+            if (args.entityTypes && args.entityTypes.length > 0) {
+                const allowedTypes = new Set(args.entityTypes);
+                const filteredEntities = result.entities.filter((e) => allowedTypes.has(e.entityType));
+                return {
+                    success: true,
+                    output: {
+                        ...result,
+                        entities: filteredEntities,
+                        // Update summary to reflect the filtered count.
+                        summary: filteredEntities.length === 0
+                            ? 'No PII detected (after entity type filter)'
+                            : `${filteredEntities.length} ${filteredEntities.length === 1 ? 'entity' : 'entities'} found (filtered by type)`,
+                    },
+                };
+            }
+            return {
+                success: true,
+                output: result,
+            };
+        }
+        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 scan';
+            return {
+                success: false,
+                error: message,
+                details: { stack: error instanceof Error ? error.stack : undefined },
+            };
+        }
+    }
+}
+//# sourceMappingURL=PiiScanTool.js.map

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

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

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

@@ -0,0 +1,332 @@
+/**
+ * @file types.ts
+ * @description Core type definitions for the PII Redaction extension pack.
+ *
+ * This module defines all shared types used across the PII detection pipeline:
+ * entity types, detection results, redaction styles, configuration interfaces,
+ * and stable service identity constants.
+ *
+ * @module pii-redaction/types
+ */
+/**
+ * Enumeration of all PII (Personally Identifiable Information) entity categories
+ * that the detection pipeline can recognise.
+ *
+ * The union is intentionally a string-literal type rather than a TypeScript
+ * `enum` so that values can be used directly as JSON without serialisation
+ * gymnastics and tree-shaken away when not referenced.
+ *
+ * @example
+ * ```ts
+ * const myType: PiiEntityType = 'EMAIL';
+ * ```
+ */
+export type PiiEntityType = 
+/** US Social Security Number (format: NNN-NN-NNNN). */
+'SSN'
+/** Payment card numbers (Luhn-validated, 13–19 digits). */
+ | 'CREDIT_CARD'
+/** RFC 5321 email addresses. */
+ | 'EMAIL'
+/** International or domestic telephone numbers (E.164 and local variants). */
+ | 'PHONE'
+/** IPv4 and IPv6 addresses. */
+ | 'IP_ADDRESS'
+/** International Bank Account Number (ISO 13616). */
+ | 'IBAN'
+/** Passport document numbers (multi-country patterns). */
+ | 'PASSPORT'
+/** Driver's licence numbers (US state patterns and common international formats). */
+ | 'DRIVERS_LICENSE'
+/** Generic government-issued ID numbers not covered by the above. */
+ | 'GOV_ID'
+/** Date of birth — detected when contextual signals confirm a birthday. */
+ | 'DATE_OF_BIRTH'
+/** Generic API tokens and secret keys (Bearer, sk-…, gh…, etc.). */
+ | 'API_KEY'
+/** AWS Access Key IDs (AKIA…) and Secret Access Keys. */
+ | 'AWS_KEY'
+/** Blockchain wallet addresses (Bitcoin, Ethereum, etc.). */
+ | 'CRYPTO_ADDRESS'
+/** Full or partial personal names identified by NER. */
+ | 'PERSON'
+/** Company, agency, or institution names identified by NER. */
+ | 'ORGANIZATION'
+/** Geographical locations (city, country, address) identified by NER. */
+ | 'LOCATION'
+/** Clinical terminology, diagnoses, medications, or health conditions. */
+ | 'MEDICAL_TERM'
+/**
+ * Catch-all bucket for spans flagged by the LLM judge or custom denylist
+ * rules that do not map to a more specific type.
+ */
+ | 'UNKNOWN_PII';
+/**
+ * Immutable array listing every {@link PiiEntityType} value in declaration
+ * order.  Useful for iterating all types, building UI checkboxes, or asserting
+ * total coverage in tests.
+ *
+ * @example
+ * ```ts
+ * const allEnabled: PiiEntityType[] = [...ALL_PII_ENTITY_TYPES];
+ * ```
+ */
+export declare const ALL_PII_ENTITY_TYPES: readonly PiiEntityType[];
+/**
+ * A single detected PII entity span within a text.
+ *
+ * Coordinates (`start`, `end`) are UTF-16 code-unit offsets (i.e. the same
+ * unit used by `String.prototype.slice`) so they can be applied directly to
+ * the original input string without any conversion.
+ */
+export interface PiiEntity {
+    /** The semantic category of the detected PII. */
+    entityType: PiiEntityType;
+    /**
+     * The exact matched substring from the input text.
+     * Preserves original casing and surrounding punctuation that was part of
+     * the match (e.g. the angle-brackets in `<user@example.com>`).
+     */
+    text: string;
+    /**
+     * Zero-based start offset (inclusive) of the match in the original string,
+     * measured in UTF-16 code units.
+     */
+    start: number;
+    /**
+     * Zero-based end offset (exclusive) of the match in the original string,
+     * measured in UTF-16 code units.
+     * Equivalent to `start + text.length` for BMP characters.
+     */
+    end: number;
+    /**
+     * Confidence score in the range [0, 1].
+     * - `1.0` — deterministic (e.g. regex + checksum validation)
+     * - `0.7–0.99` — high-confidence NER or heuristic match
+     * - `< 0.5` — speculative; may be a false positive
+     */
+    score: number;
+    /**
+     * The detection tier that produced this entity.
+     * - `'regex'` — Tier 0 pattern matcher
+     * - `'ner'` — Tier 1 named-entity recognition model
+     * - `'llm'` — Tier 2 LLM judge
+     * - `'denylist'` — explicit denylist rule
+     */
+    source: 'regex' | 'nlp-prefilter' | 'ner-model' | 'ner' | 'llm' | 'denylist';
+    /**
+     * Arbitrary key-value metadata attached by the recogniser that produced
+     * this entity.  Examples: `{ "pattern": "US_SSN_DASHES" }` or
+     * `{ "nerLabel": "PER", "nerModel": "en_core_web_sm" }`.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Controls how detected PII spans are replaced in the redacted output.
+ *
+ * | Style | Example output |
+ * |---|---|
+ * | `'placeholder'` | `[EMAIL]` |
+ * | `'mask'` | `***` |
+ * | `'hash'` | `a3f2c1d…` (SHA-256 truncated to 8 hex chars) |
+ * | `'category-tag'` | `<PII type="EMAIL"/>` |
+ */
+export type RedactionStyle = 'placeholder' | 'mask' | 'hash' | 'category-tag';
+/**
+ * The full output of a PII detection pass over a single input string.
+ */
+export interface PiiDetectionResult {
+    /**
+     * All PII entities detected in the input, sorted by `start` offset in
+     * ascending order.  Non-overlapping spans are guaranteed; if two recognisers
+     * emit overlapping matches the one with the higher `score` is kept.
+     */
+    entities: PiiEntity[];
+    /**
+     * Length of the original input string in UTF-16 code units.
+     * Stored for downstream metrics and to avoid re-measuring.
+     */
+    inputLength: number;
+    /**
+     * Wall-clock time in milliseconds spent running all detection tiers for
+     * this particular input.
+     */
+    processingTimeMs: number;
+    /**
+     * Which detection tiers were actually executed, in execution order.
+     * Possible values: `'regex'`, `'ner'`, `'llm'`.
+     * A tier is omitted when it is disabled in {@link PiiRedactionPackOptions}
+     * or when early-exit conditions prevent it from running.
+     */
+    tiersExecuted: Array<'regex' | 'ner' | 'llm'>;
+    /**
+     * Human-readable summary of detection results, e.g.:
+     * `"3 entities found: 1×EMAIL, 1×PHONE, 1×PERSON"`.
+     * Intended for logging and observability dashboards.
+     */
+    summary: string;
+}
+/**
+ * Configuration for the optional Tier-2 LLM judge that re-examines candidate
+ * spans flagged by earlier tiers and catches context-dependent PII that
+ * regex/NER cannot reliably detect.
+ *
+ * Using a small, cheap model (e.g. `gpt-4o-mini`) is strongly recommended
+ * because the judge is called once per input chunk and latency matters.
+ */
+export interface LlmJudgeConfig {
+    /**
+     * LLM provider identifier.  Must match a key registered in the
+     * AgentOS `ProviderRegistry` (e.g. `'openai'`, `'anthropic'`,
+     * `'mistral'`).
+     */
+    provider: string;
+    /**
+     * Specific model to use for PII judgement.
+     * @example `'gpt-4o-mini'`, `'claude-haiku-3-5'`
+     */
+    model: string;
+    /**
+     * API key for the chosen provider.  If omitted, the pack will attempt to
+     * read the key from the environment using the provider's conventional
+     * variable name (e.g. `OPENAI_API_KEY`).
+     */
+    apiKey?: string;
+    /**
+     * Custom base URL for self-hosted or proxy deployments
+     * (e.g. an OpenAI-compatible local server).
+     */
+    baseUrl?: string;
+    /**
+     * Maximum number of LLM requests that may be in-flight simultaneously.
+     * Prevents rate-limit exhaustion on high-throughput agents.
+     * @default 4
+     */
+    maxConcurrency?: number;
+    /**
+     * Maximum number of (input → judgement) results to keep in the in-memory
+     * LRU cache.  Set to `0` to disable caching.
+     * @default 256
+     */
+    cacheSize?: number;
+}
+/**
+ * Top-level configuration object passed to `createPiiRedactionPack()`.
+ *
+ * All properties are optional; sensible defaults are applied by the pack
+ * factory so that a zero-config setup works out of the box.
+ */
+export interface PiiRedactionPackOptions {
+    /**
+     * Subset of {@link PiiEntityType} values to detect.
+     * Defaults to {@link ALL_PII_ENTITY_TYPES} when omitted.
+     *
+     * Narrowing this list improves performance by skipping irrelevant regex
+     * patterns and NER labels.
+     */
+    entityTypes?: PiiEntityType[];
+    /**
+     * Minimum confidence score (inclusive) required for an entity to be
+     * included in {@link PiiDetectionResult.entities}.
+     * Must be in the range [0, 1].
+     * @default 0.6
+     */
+    confidenceThreshold?: number;
+    /**
+     * Redaction style applied when replacing detected PII in output text.
+     * @default 'placeholder'
+     */
+    redactionStyle?: RedactionStyle;
+    /**
+     * Exact strings or RegExp patterns that should be unconditionally excluded
+     * from redaction even when they match a PII pattern.
+     *
+     * @example `['support@example.com', /\b192\.168\.\d+\.\d+\b/]`
+     */
+    allowlist?: Array<string | RegExp>;
+    /**
+     * Exact strings or RegExp patterns that should always be redacted as
+     * {@link PiiEntityType | `UNKNOWN_PII`} regardless of other detection
+     * results.
+     *
+     * @example `['ACME-SECRET', /employee_id:\s*\d{6}/]`
+     */
+    denylist?: Array<string | RegExp>;
+    /**
+     * Whether to load and run a local NER model (Tier 1) in addition to
+     * regex patterns (Tier 0).  Enabling this improves recall for `PERSON`,
+     * `ORGANIZATION`, and `LOCATION` at the cost of higher memory usage.
+     * @default false
+     */
+    enableNerModel?: boolean;
+    /**
+     * When provided, enables the LLM-powered Tier-2 judge for context-aware
+     * PII detection.  When omitted, Tier 2 is disabled.
+     */
+    llmJudge?: LlmJudgeConfig;
+    /**
+     * Determines which agent messages are evaluated by the guardrail hook.
+     * - `'input'` — only inbound user messages
+     * - `'output'` — only outbound assistant messages
+     * - `'both'` — evaluate and redact in both directions
+     * @default 'both'
+     */
+    guardrailScope?: 'input' | 'output' | 'both';
+    /**
+     * When `true`, the guardrail hook will also evaluate individual streaming
+     * chunks (SSE deltas) as they arrive, not just the fully-assembled message.
+     * This reduces the window during which PII could be leaked but increases
+     * CPU overhead.
+     * @default false
+     */
+    evaluateStreamingChunks?: boolean;
+    /**
+     * Maximum number of streaming chunks evaluated per request when
+     * {@link evaluateStreamingChunks} is `true`.  Older chunks are dropped
+     * once the limit is reached to bound memory growth on long streams.
+     * @default 50
+     */
+    maxStreamingEvaluations?: number;
+}
+/**
+ * Stable string identifiers for every injectable service provided by the PII
+ * redaction pack.  Values follow the AgentOS convention:
+ * `agentos:<domain>:<service-name>`.
+ *
+ * These constants are used as keys in the {@link ISharedServiceRegistry} so
+ * that other extensions and tools can look up pack services without importing
+ * concrete implementations.
+ *
+ * @example
+ * ```ts
+ * const detector = registry.get<IPiiDetectionService>(PII_SERVICE_IDS.DETECTION_SERVICE);
+ * ```
+ */
+export declare const PII_SERVICE_IDS: {
+    /**
+     * Main detection service that orchestrates all tiers and returns
+     * {@link PiiDetectionResult}.
+     */
+    readonly DETECTION_SERVICE: "agentos:pii:detection-service";
+    /**
+     * Redaction service that applies the configured {@link RedactionStyle}
+     * to a raw string given a {@link PiiDetectionResult}.
+     */
+    readonly REDACTION_SERVICE: "agentos:pii:redaction-service";
+    /**
+     * Guardrail hook factory that integrates with the AgentOS hook pipeline
+     * to intercept and sanitise agent messages automatically.
+     */
+    readonly GUARDRAIL_HOOK: "agentos:pii:guardrail-hook";
+    /**
+     * Audit logger that records redaction events for compliance reporting.
+     * Implementations may write to stdout, a file, or a remote SIEM sink.
+     */
+    readonly AUDIT_LOGGER: "agentos:pii:audit-logger";
+};
+/**
+ * Union of all {@link PII_SERVICE_IDS} values — useful for type-narrowing in
+ * registry look-ups.
+ */
+export type PiiServiceId = (typeof PII_SERVICE_IDS)[keyof typeof PII_SERVICE_IDS];
+//# sourceMappingURL=types.d.ts.map

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

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

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

@@ -0,0 +1,83 @@
+/**
+ * @file types.ts
+ * @description Core type definitions for the PII Redaction extension pack.
+ *
+ * This module defines all shared types used across the PII detection pipeline:
+ * entity types, detection results, redaction styles, configuration interfaces,
+ * and stable service identity constants.
+ *
+ * @module pii-redaction/types
+ */
+// ---------------------------------------------------------------------------
+// Canonical array of all entity types
+// ---------------------------------------------------------------------------
+/**
+ * Immutable array listing every {@link PiiEntityType} value in declaration
+ * order.  Useful for iterating all types, building UI checkboxes, or asserting
+ * total coverage in tests.
+ *
+ * @example
+ * ```ts
+ * const allEnabled: PiiEntityType[] = [...ALL_PII_ENTITY_TYPES];
+ * ```
+ */
+export const ALL_PII_ENTITY_TYPES = [
+    'SSN',
+    'CREDIT_CARD',
+    'EMAIL',
+    'PHONE',
+    'IP_ADDRESS',
+    'IBAN',
+    'PASSPORT',
+    'DRIVERS_LICENSE',
+    'GOV_ID',
+    'DATE_OF_BIRTH',
+    'API_KEY',
+    'AWS_KEY',
+    'CRYPTO_ADDRESS',
+    'PERSON',
+    'ORGANIZATION',
+    'LOCATION',
+    'MEDICAL_TERM',
+    'UNKNOWN_PII',
+];
+// ---------------------------------------------------------------------------
+// Service identity constants
+// ---------------------------------------------------------------------------
+/**
+ * Stable string identifiers for every injectable service provided by the PII
+ * redaction pack.  Values follow the AgentOS convention:
+ * `agentos:<domain>:<service-name>`.
+ *
+ * These constants are used as keys in the {@link ISharedServiceRegistry} so
+ * that other extensions and tools can look up pack services without importing
+ * concrete implementations.
+ *
+ * @example
+ * ```ts
+ * const detector = registry.get<IPiiDetectionService>(PII_SERVICE_IDS.DETECTION_SERVICE);
+ * ```
+ */
+export const PII_SERVICE_IDS = {
+    /**
+     * Main detection service that orchestrates all tiers and returns
+     * {@link PiiDetectionResult}.
+     */
+    DETECTION_SERVICE: 'agentos:pii:detection-service',
+    /**
+     * Redaction service that applies the configured {@link RedactionStyle}
+     * to a raw string given a {@link PiiDetectionResult}.
+     */
+    REDACTION_SERVICE: 'agentos:pii:redaction-service',
+    /**
+     * Guardrail hook factory that integrates with the AgentOS hook pipeline
+     * to intercept and sanitise agent messages automatically.
+     */
+    GUARDRAIL_HOOK: 'agentos:pii:guardrail-hook',
+    /**
+     * Audit logger that records redaction events for compliance reporting.
+     * Implementations may write to stdout, a file, or a remote SIEM sink.
+     */
+    AUDIT_LOGGER: 'agentos:pii:audit-logger',
+};
+//# sourceMappingURL=types.js.map