@framers/agentos 0.1.56 → 0.1.58

package/README.md

@@ -548,6 +548,22 @@ type ExtensionPackResolver =
 3. `ExtensionManager` provides runtime access: `getTools()`, `getGuardrails()`, `getWorkflows()`, etc.
 4. `MultiRegistryLoader` supports loading from multiple remote registries
 
+**Lifecycle context and shared services:**
+
+- `ExtensionLifecycleContext.getSecret(secretId)` gives packs host-resolved secrets at activation time
+- `ExtensionLifecycleContext.services` provides a shared `ISharedServiceRegistry` for lazy singleton reuse across packs
+- heavyweight dependencies such as NLP pipelines, ONNX models, embedding functions, and NLI models should be loaded through the shared registry rather than per-descriptor globals
+
+**Built-in guardrail packs exported by `@framers/agentos`:**
+
+| Pack | Import Path | Guardrail ID | Tool IDs | Purpose |
+|------|-------------|--------------|----------|---------|
+| PII Redaction | `@framers/agentos-ext-pii-redaction` | `pii-redaction-guardrail` | `pii_scan`, `pii_redact` | Four-tier PII detection and redaction |
+| ML Classifiers | `@framers/agentos-ext-ml-classifiers` | `ml-classifier-guardrail` | `classify_content` | Toxicity, prompt-injection, and jailbreak detection |
+| Topicality | `@framers/agentos-ext-topicality` | `topicality-guardrail` | `check_topic` | On-topic enforcement and session drift detection |
+| Code Safety | `@framers/agentos-ext-code-safety` | `code-safety-guardrail` | `scan_code` | Regex-based code risk scanning across fenced code and tool args |
+| Grounding Guard | `@framers/agentos-ext-grounding-guard` | `grounding-guardrail` | `check_grounding` | RAG-source claim verification and hallucination detection |
+
 ---
 
 ### Planning Engine
@@ -692,24 +708,32 @@ See [`docs/SAFETY_PRIMITIVES.md`](docs/SAFETY_PRIMITIVES.md) for the full safety
 Content-level input/output filtering:
 
 ```typescript
-enum GuardrailAction {
-  ALLOW    = 'allow',     // Pass through unchanged
-  FLAG     = 'flag',      // Pass through but log for review
-  SANITIZE = 'sanitize',  // Replace with modified content (e.g., PII redaction)
-  BLOCK    = 'block',     // Reject entirely, terminate stream
-}
-
 interface IGuardrailService {
-  evaluateInput?(input: AgentOSInput, context: GuardrailContext): Promise<GuardrailEvaluationResult>;
-  evaluateOutput?(output: string, context: GuardrailContext): Promise<GuardrailEvaluationResult>;
+  config?: {
+    evaluateStreamingChunks?: boolean;
+    maxStreamingEvaluations?: number;
+    canSanitize?: boolean;
+    timeoutMs?: number;
+  };
+
+  evaluateInput?(payload: GuardrailInputPayload): Promise<GuardrailEvaluationResult | null>;
+  evaluateOutput?(payload: GuardrailOutputPayload): Promise<GuardrailEvaluationResult | null>;
 }
 ```
 
+`GuardrailOutputPayload` also carries `ragSources?: RagRetrievedChunk[]`, which enables grounding-aware output checks against retrieved context.
+
 Guardrails run at two points in the request lifecycle:
-1. **Pre-processing** -- `evaluateInput()` inspects user input before it reaches the LLM
-2. **Post-processing** -- `evaluateOutput()` inspects the LLM response before streaming to the client
+1. **Pre-processing** -- `evaluateInput()` inspects user input before orchestration
+2. **Post-processing** -- `evaluateOutput()` inspects streaming chunks and/or the final response before emission
 
-Multiple guardrails can be composed via the extension system, and each receives full context (user ID, session ID, persona ID, custom metadata) for context-aware policy decisions.
+When multiple guardrails are registered, AgentOS uses a **two-phase dispatcher**:
+1. **Phase 1 (sequential sanitizers)** -- guardrails with `config.canSanitize === true` run in registration order so each sanitizer sees the cumulative sanitized text
+2. **Phase 2 (parallel classifiers)** -- all remaining guardrails run concurrently with worst-action aggregation (`BLOCK > FLAG > ALLOW`)
+
+`ParallelGuardrailDispatcher` powers both input evaluation and output stream wrapping, with per-guardrail `timeoutMs` fail-open behavior for slow or degraded classifiers.
+
+Multiple guardrails can be composed via the extension system, and each receives full context (user ID, session ID, persona ID, conversation ID, metadata) for context-aware policy decisions.
 
 See [`docs/GUARDRAILS_USAGE.md`](docs/GUARDRAILS_USAGE.md) for implementation patterns.
 
@@ -1435,13 +1459,19 @@ await agent.initialize({
 import {
   AgentOS,
   type IGuardrailService,
-  type GuardrailContext,
   GuardrailAction,
+  type GuardrailInputPayload,
+  type GuardrailOutputPayload,
 } from '@framers/agentos';
 import { createTestAgentOSConfig } from '@framers/agentos/config/AgentOSConfig';
 
 const piiGuardrail: IGuardrailService = {
-  async evaluateInput(input, context) {
+  config: {
+    evaluateStreamingChunks: true,
+    canSanitize: true,
+  },
+
+  async evaluateInput({ input }: GuardrailInputPayload) {
     // Check for SSN patterns in user input
     const ssnPattern = /\b\d{3}-\d{2}-\d{4}\b/g;
     if (input.textInput && ssnPattern.test(input.textInput)) {
@@ -1455,8 +1485,15 @@ const piiGuardrail: IGuardrailService = {
     return { action: GuardrailAction.ALLOW };
   },
 
-  async evaluateOutput(output, context) {
-    if (output.toLowerCase().includes('password')) {
+  async evaluateOutput({ chunk }: GuardrailOutputPayload) {
+    const text =
+      chunk.type === 'TEXT_DELTA'
+        ? chunk.textDelta ?? ''
+        : chunk.type === 'FINAL_RESPONSE'
+          ? chunk.finalResponseText ?? ''
+          : '';
+
+    if (text.toLowerCase().includes('password')) {
       return {
         action: GuardrailAction.BLOCK,
         reason: 'Output contains potentially sensitive credential information',
@@ -1472,6 +1509,11 @@ const config = await createTestAgentOSConfig();
 await agent.initialize({ ...config, guardrailService: piiGuardrail });
 ```
 
+> **For production PII redaction**, use the built-in `createPiiRedactionPack()` extension
+> instead of hand-rolled regex. It provides four-tier detection (regex + NLP + BERT NER +
+> LLM-as-judge), streaming support, and configurable redaction styles. See
+> [GUARDRAILS_USAGE.md](docs/GUARDRAILS_USAGE.md) for full examples.
+
 ### Channel Adapters
 
 ```typescript
@@ -1557,6 +1599,7 @@ import { CircuitBreaker, CostGuard, StuckDetector } from '@framers/agentos/core/
 
 // Guardrails
 import { GuardrailAction } from '@framers/agentos/core/guardrails';
+import { ParallelGuardrailDispatcher } from '@framers/agentos/core/guardrails';
 
 // Tools
 import type { ITool, ToolExecutionResult } from '@framers/agentos/core/tools';
@@ -1571,6 +1614,14 @@ import { GraphRAGEngine } from '@framers/agentos/rag/graphrag';
 // Skills
 import { SkillRegistry, SkillLoader } from '@framers/agentos/skills';
 
+// Extension runtime helpers and built-in guardrail packs
+import { SharedServiceRegistry } from '@framers/agentos';
+import { createPiiRedactionPack } from '@framers/agentos-ext-pii-redaction';
+import { createMLClassifierPack } from '@framers/agentos-ext-ml-classifiers';
+import { createTopicalityPack } from '@framers/agentos-ext-topicality';
+import { createCodeSafetyPack } from '@framers/agentos-ext-code-safety';
+import { createGroundingGuardPack } from '@framers/agentos-ext-grounding-guard';
+
 // Deep imports (wildcard exports)
 import { SomeType } from '@framers/agentos/core/safety/CircuitBreaker';
 import { SomeConfig } from '@framers/agentos/config/ToolOrchestratorConfig';

package/dist/api/types/AgentOSResponse.d.ts

@@ -118,6 +118,13 @@ export interface AgentOSFinalResponseChunk extends AgentOSResponseChunk {
     };
     updatedConversationContext?: ConversationContext;
     activePersonaDetails?: Partial<IPersonaDefinition>;
+    /**
+     * RAG source chunks that were used to generate this response.
+     * Populated by the GMI when RAG retrieval was performed.
+     * Used by grounding guardrails to verify response faithfulness.
+     * Undefined when no RAG retrieval was performed.
+     */
+    ragSources?: import('../../rag').RagRetrievedChunk[];
 }
 /**
  * @typedef {Object} AgentOSErrorChunk

package/dist/api/types/AgentOSResponse.d.ts.map

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

package/dist/core/guardrails/IGuardrailService.d.ts

@@ -166,6 +166,13 @@ export interface GuardrailOutputPayload {
     context: GuardrailContext;
     /** The response chunk to evaluate */
     chunk: AgentOSResponse;
+    /**
+     * RAG source chunks retrieved for this request.
+     * Available to output guardrails for grounding verification.
+     * Persists across all chunks in a stream (not just the final chunk).
+     * Undefined when no RAG retrieval was performed.
+     */
+    ragSources?: import('../../rag').RagRetrievedChunk[];
 }
 /**
  * Configuration for guardrail evaluation behavior.
@@ -220,6 +227,38 @@ export interface GuardrailConfig {
      * @default undefined (no limit)
      */
     maxStreamingEvaluations?: number;
+    /**
+     * Whether this guardrail may return SANITIZE actions that modify content.
+     *
+     * When true, this guardrail runs in Phase 1 (sequential) of the parallel
+     * dispatcher — it sees and can modify text produced by prior sanitizers.
+     * Each sanitizer receives the cumulative sanitized text from all preceding
+     * sanitizers in registration order.
+     *
+     * When false or omitted, this guardrail runs in Phase 2 (parallel) on
+     * the already-sanitized text from Phase 1. It may return BLOCK, FLAG, or
+     * ALLOW. If a Phase 2 guardrail returns SANITIZE, the action is
+     * **downgraded to FLAG** with a warning logged, because concurrent
+     * sanitization would produce non-deterministic results.
+     *
+     * @default false
+     */
+    canSanitize?: boolean;
+    /**
+     * Maximum time in milliseconds to wait for this guardrail's evaluation.
+     *
+     * If exceeded, the evaluation is abandoned (fail-open), a warning is
+     * logged, and the guardrail contributes nothing to the result. Prevents
+     * a slow guardrail (e.g., LLM-based) from blocking the entire pipeline.
+     *
+     * **Safety note:** Do NOT set timeoutMs on safety-critical guardrails
+     * (e.g., CSAM detection, compliance-mandatory filters) because fail-open
+     * on timeout means content passes unchecked. Only use on guardrails
+     * where a missed evaluation is acceptable.
+     *
+     * @default undefined (no timeout — wait indefinitely)
+     */
+    timeoutMs?: number;
 }
 /**
  * Contract for implementing custom guardrail logic.

package/dist/core/guardrails/IGuardrailService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IGuardrailService.d.ts","sourceRoot":"","sources":["../../../src/core/guardrails/IGuardrailService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,oBAAY,eAAe;IACzB;;;OAGG;IACH,KAAK,UAAU;IAEf;;;OAGG;IACH,IAAI,SAAS;IAEb;;;;OAIG;IACH,QAAQ,aAAa;IAErB;;;;OAIG;IACH,KAAK,UAAU;CAChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IAEf,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAElB,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,qCAAqC;IACrC,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,yBAAyB;IACxC,8DAA8D;IAC9D,MAAM,EAAE,eAAe,CAAC;IAExB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEnC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,kDAAkD;IAClD,OAAO,EAAE,gBAAgB,CAAC;IAE1B,2CAA2C;IAC3C,KAAK,EAAE,YAAY,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,sBAAsB;IACrC,kDAAkD;IAClD,OAAO,EAAE,gBAAgB,CAAC;IAE1B,qCAAqC;IACrC,KAAK,EAAE,eAAe,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAElC;;;;;;;;OAQG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,MAAM,CAAC,EAAE,eAAe,CAAC;IAEzB;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC,CAAC;IAE1F;;;;;;;;;;;;;;OAcG;IACH,cAAc,CAAC,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC,CAAC;CAC7F"}
+{"version":3,"file":"IGuardrailService.d.ts","sourceRoot":"","sources":["../../../src/core/guardrails/IGuardrailService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,oBAAY,eAAe;IACzB;;;OAGG;IACH,KAAK,UAAU;IAEf;;;OAGG;IACH,IAAI,SAAS;IAEb;;;;OAIG;IACH,QAAQ,aAAa;IAErB;;;;OAIG;IACH,KAAK,UAAU;CAChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IAEf,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAElB,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,qCAAqC;IACrC,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,yBAAyB;IACxC,8DAA8D;IAC9D,MAAM,EAAE,eAAe,CAAC;IAExB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEnC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,kDAAkD;IAClD,OAAO,EAAE,gBAAgB,CAAC;IAE1B,2CAA2C;IAC3C,KAAK,EAAE,YAAY,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,sBAAsB;IACrC,kDAAkD;IAClD,OAAO,EAAE,gBAAgB,CAAC;IAE1B,qCAAqC;IACrC,KAAK,EAAE,eAAe,CAAC;IAEvB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,WAAW,EAAE,iBAAiB,EAAE,CAAC;CACtD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAElC;;;;;;;;OAQG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAEjC;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,MAAM,CAAC,EAAE,eAAe,CAAC;IAEzB;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC,CAAC;IAE1F;;;;;;;;;;;;;;OAcG;IACH,cAAc,CAAC,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC,CAAC;CAC7F"}

package/dist/core/guardrails/ParallelGuardrailDispatcher.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @module ParallelGuardrailDispatcher
+ *
+ * Two-phase parallel guardrail dispatcher that separates sanitizers
+ * (sequential, order-dependent) from classifiers (parallel, independent).
+ *
+ * **Phase 1 (Sequential):** Guardrails with `config.canSanitize === true`
+ * run one-at-a-time in registration order. Each sanitizer receives the
+ * cumulative output of all preceding sanitizers. A BLOCK here short-circuits
+ * the entire pipeline.
+ *
+ * **Phase 2 (Parallel):** Remaining guardrails run concurrently via
+ * `Promise.allSettled`. They receive the fully-sanitized text from Phase 1.
+ * If any Phase 2 guardrail returns SANITIZE, it is **downgraded to FLAG**
+ * because concurrent sanitization would produce non-deterministic results.
+ *
+ * The final outcome uses "worst-wins" aggregation:
+ * BLOCK (severity 3) > FLAG (severity 2) > ALLOW (severity 0).
+ *
+ * @example
+ * ```typescript
+ * import { ParallelGuardrailDispatcher } from '../../core/guardrails';
+ *
+ * const outcome = await ParallelGuardrailDispatcher.evaluateInput(
+ *   [piiRedactor, toxicityClassifier, policyGuard],
+ *   userInput,
+ *   guardrailContext,
+ * );
+ * ```
+ */
+import type { AgentOSInput } from '../../api/types/AgentOSInput';
+import { type AgentOSResponse } from '../../api/types/AgentOSResponse';
+import { type GuardrailContext, type IGuardrailService } from './IGuardrailService';
+import type { GuardrailInputOutcome, GuardrailOutputOptions } from './guardrailDispatcher';
+/**
+ * Stateless two-phase parallel guardrail dispatcher.
+ *
+ * All methods are static — no instantiation needed. The class exists purely
+ * as a namespace to keep the two public entry points grouped.
+ */
+export declare class ParallelGuardrailDispatcher {
+    /**
+     * Evaluate user input through registered guardrails using two-phase execution.
+     *
+     * **Phase 1 (Sequential — sanitizers):**
+     * Guardrails with `config.canSanitize === true` run one-at-a-time in
+     * registration order. Each sees (and may modify) the cumulative sanitized
+     * input. A BLOCK result short-circuits immediately — Phase 2 never runs.
+     *
+     * **Phase 2 (Parallel — classifiers):**
+     * All remaining guardrails run concurrently via `Promise.allSettled` on
+     * the text produced by Phase 1. A Phase 2 SANITIZE is downgraded to FLAG.
+     *
+     * **Aggregation:** worst-wins (BLOCK > FLAG > ALLOW). The singular
+     * `evaluation` field is set to the first BLOCK, else the worst-severity
+     * evaluation, else the last evaluation by registration order.
+     *
+     * @param services  - Array of guardrail services (already normalized)
+     * @param input     - User input to evaluate
+     * @param context   - Conversational context for policy decisions
+     * @returns Outcome with sanitized input and all evaluations in registration order
+     */
+    static evaluateInput(services: IGuardrailService[], input: AgentOSInput, context: GuardrailContext): Promise<GuardrailInputOutcome>;
+    /**
+     * Wrap a response stream with two-phase guardrail filtering.
+     *
+     * Partitions services into four groups (once, up front):
+     * 1. **Streaming sanitizers** (`canSanitize && evaluateStreamingChunks`)
+     * 2. **Streaming parallel** classifiers (`evaluateStreamingChunks && !canSanitize`)
+     * 3. **Final sanitizers** (`canSanitize && !evaluateStreamingChunks`)
+     * 4. **Final parallel** classifiers (the rest with `evaluateOutput`)
+     *
+     * For each TEXT_DELTA chunk: Phase 1 runs streaming sanitizers sequentially
+     * (with per-service rate limiting), then Phase 2 runs streaming classifiers
+     * in parallel.
+     *
+     * For each isFinal chunk: Phase 1 runs final sanitizers sequentially, then
+     * Phase 2 runs final classifiers in parallel. All services with
+     * `evaluateOutput` participate in final evaluation.
+     *
+     * A BLOCK in either phase terminates the stream immediately with an error
+     * chunk.
+     *
+     * @param services  - Array of guardrail services (already normalized)
+     * @param context   - Conversational context for policy decisions
+     * @param stream    - Source response stream to filter
+     * @param options   - Stream options and input evaluations to embed
+     * @returns Wrapped async generator with guardrail filtering applied
+     */
+    static wrapOutput(services: IGuardrailService[], context: GuardrailContext, stream: AsyncGenerator<AgentOSResponse, void, undefined>, options: GuardrailOutputOptions): AsyncGenerator<AgentOSResponse, void, undefined>;
+}
+//# sourceMappingURL=ParallelGuardrailDispatcher.d.ts.map

package/dist/core/guardrails/ParallelGuardrailDispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParallelGuardrailDispatcher.d.ts","sourceRoot":"","sources":["../../../src/core/guardrails/ParallelGuardrailDispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EACL,KAAK,eAAe,EAGrB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAEL,KAAK,gBAAgB,EAErB,KAAK,iBAAiB,EACvB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAqH3F;;;;;GAKG;AACH,qBAAa,2BAA2B;IAKtC;;;;;;;;;;;;;;;;;;;;OAoBG;WACU,aAAa,CACxB,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,qBAAqB,CAAC;IAwIjC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;WACW,UAAU,CACtB,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,cAAc,CAAC,eAAe,EAAE,IAAI,EAAE,SAAS,CAAC,EACxD,OAAO,EAAE,sBAAsB,GAC9B,cAAc,CAAC,eAAe,EAAE,IAAI,EAAE,SAAS,CAAC;CAmRpD"}