@framers/agentos 0.1.0

package/dist/core/evaluation/LLMJudge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LLMJudge.js","sourceRoot":"","sources":["../../../src/core/evaluation/LLMJudge.ts"],"names":[],"mappings":"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"}

package/dist/core/evaluation/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @file index.ts
+ * @description Evaluation framework exports.
+ * @module AgentOS/Evaluation
+ */
+export * from './IEvaluator';
+export * from './Evaluator';
+export * from './LLMJudge';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/evaluation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/evaluation/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/core/evaluation/index.js

@@ -0,0 +1,9 @@
+/**
+ * @file index.ts
+ * @description Evaluation framework exports.
+ * @module AgentOS/Evaluation
+ */
+export * from './IEvaluator.js';
+export * from './Evaluator.js';
+export * from './LLMJudge.js';
+//# sourceMappingURL=index.js.map

package/dist/core/evaluation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/evaluation/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

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

@@ -0,0 +1,142 @@
+import type { AgentOSInput } from '../../api/types/AgentOSInput';
+import type { AgentOSResponse } from '../../api/types/AgentOSResponse';
+/**
+ * High-level outcome emitted by a guardrail evaluation.
+ * The action instructs AgentOS (or the host) how to proceed.
+ */
+export declare enum GuardrailAction {
+    /**
+     * Allow the content to pass through unchanged.
+     */
+    ALLOW = "allow",
+    /**
+     * Allow the request/response but record metadata (e.g. for analytics).
+     */
+    FLAG = "flag",
+    /**
+     * Continue processing after replacing user/assistant content with a sanitised version.
+     */
+    SANITIZE = "sanitize",
+    /**
+     * Block the interaction entirely and return an error back to the host.
+     */
+    BLOCK = "block"
+}
+/**
+ * Lightweight description of the conversational context
+ * that is relevant for guardrail decisions.
+ */
+export interface GuardrailContext {
+    userId: string;
+    sessionId: string;
+    personaId?: string;
+    conversationId?: string;
+    mode?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result returned by a guardrail evaluation stage.
+ */
+export interface GuardrailEvaluationResult {
+    action: GuardrailAction;
+    /**
+     * Optional short reason that can be shown to the end user or logged.
+     */
+    reason?: string;
+    /**
+     * Machine readable code (e.g. policy identifier).
+     */
+    reasonCode?: string;
+    /**
+     * Additional metadata that hosts may want to persist.
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Free-form details (stack traces, moderation results, etc.).
+     */
+    details?: unknown;
+    /**
+     * Replacement text to use when {@link GuardrailAction.SANITIZE} is returned.
+     */
+    modifiedText?: string | null;
+}
+/**
+ * Payload supplied to the guardrail service before a request
+ * enters the orchestration pipeline.
+ */
+export interface GuardrailInputPayload {
+    context: GuardrailContext;
+    input: AgentOSInput;
+}
+/**
+ * Payload supplied to the guardrail service right before
+ * a response chunk is emitted to the host.
+ */
+export interface GuardrailOutputPayload {
+    context: GuardrailContext;
+    chunk: AgentOSResponse;
+}
+/**
+ * Configuration for guardrail evaluation behavior.
+ */
+export interface GuardrailConfig {
+    /**
+     * If true, evaluates TEXT_DELTA chunks during streaming (real-time redaction).
+     * If false, only evaluates FINAL_RESPONSE chunks (default, faster, lower cost).
+     *
+     * **Performance Impact:**
+     * - Streaming evaluation: Adds 1-500ms latency per TEXT_DELTA chunk
+     * - Final-only evaluation: Adds 1-500ms latency once per response
+     *
+     * **Cost Impact:**
+     * - Streaming evaluation: May trigger LLM calls per chunk (if using LLM-powered guardrails)
+     * - Final-only evaluation: Single evaluation per response
+     *
+     * **Use Cases:**
+     * - Streaming: Real-time PII redaction, immediate blocking of harmful content
+     * - Final-only: Cost-sensitive deployments, policy checks that need full context
+     *
+     * @default false
+     */
+    evaluateStreamingChunks?: boolean;
+    /**
+     * Maximum number of streaming chunks to evaluate per request.
+     * Only applies when evaluateStreamingChunks is true.
+     * Set to limit cost/performance impact of streaming evaluation.
+     *
+     * @default undefined (no limit)
+     */
+    maxStreamingEvaluations?: number;
+}
+/**
+ * Contract that host applications can implement to inject
+ * custom guardrail logic (moderation, policy enforcement, censorship).
+ *
+ * Both methods are optional to keep the package lightweight — provide
+ * implementations for the stages you care about.
+ */
+export interface IGuardrailService {
+    /**
+     * Optional configuration for guardrail evaluation behavior.
+     */
+    config?: GuardrailConfig;
+    /**
+     * Evaluate user input before the orchestration pipeline executes.
+     * Returning {@link GuardrailAction.BLOCK} will prevent the request from being processed.
+     */
+    evaluateInput?(payload: GuardrailInputPayload): Promise<GuardrailEvaluationResult | null>;
+    /**
+     * Inspect the agent's response chunks before they are streamed to the client.
+     * You can flag, sanitise, or block chunks.
+     *
+     * **Evaluation Timing:**
+     * - If `config.evaluateStreamingChunks === true`: Called for every TEXT_DELTA chunk
+     * - Otherwise: Called only for FINAL_RESPONSE chunks
+     *
+     * **Performance Note:**
+     * Streaming evaluation adds latency per chunk. Use final-only evaluation unless
+     * real-time redaction is required.
+     */
+    evaluateOutput?(payload: GuardrailOutputPayload): Promise<GuardrailEvaluationResult | null>;
+}
+//# sourceMappingURL=IGuardrailService.d.ts.map

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

@@ -0,0 +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;;;GAGG;AACH,oBAAY,eAAe;IACzB;;OAEG;IACH,KAAK,UAAU;IACf;;OAEG;IACH,IAAI,SAAS;IACb;;OAEG;IACH,QAAQ,aAAa;IACrB;;OAEG;IACH,KAAK,UAAU;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,eAAe,CAAC;IACxB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,gBAAgB,CAAC;IAC1B,KAAK,EAAE,YAAY,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,gBAAgB,CAAC;IAC1B,KAAK,EAAE,eAAe,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;;;;;;;;;OAiBG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAElC;;;;;;OAMG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,MAAM,CAAC,EAAE,eAAe,CAAC;IAEzB;;;OAGG;IACH,aAAa,CAAC,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC,CAAC;IAE1F;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC,CAAC;CAC7F"}

package/dist/core/guardrails/IGuardrailService.js

@@ -0,0 +1,24 @@
+/**
+ * High-level outcome emitted by a guardrail evaluation.
+ * The action instructs AgentOS (or the host) how to proceed.
+ */
+export var GuardrailAction;
+(function (GuardrailAction) {
+    /**
+     * Allow the content to pass through unchanged.
+     */
+    GuardrailAction["ALLOW"] = "allow";
+    /**
+     * Allow the request/response but record metadata (e.g. for analytics).
+     */
+    GuardrailAction["FLAG"] = "flag";
+    /**
+     * Continue processing after replacing user/assistant content with a sanitised version.
+     */
+    GuardrailAction["SANITIZE"] = "sanitize";
+    /**
+     * Block the interaction entirely and return an error back to the host.
+     */
+    GuardrailAction["BLOCK"] = "block";
+})(GuardrailAction || (GuardrailAction = {}));
+//# sourceMappingURL=IGuardrailService.js.map

package/dist/core/guardrails/IGuardrailService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IGuardrailService.js","sourceRoot":"","sources":["../../../src/core/guardrails/IGuardrailService.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,CAAN,IAAY,eAiBX;AAjBD,WAAY,eAAe;IACzB;;OAEG;IACH,kCAAe,CAAA;IACf;;OAEG;IACH,gCAAa,CAAA;IACb;;OAEG;IACH,wCAAqB,CAAA;IACrB;;OAEG;IACH,kCAAe,CAAA;AACjB,CAAC,EAjBW,eAAe,KAAf,eAAe,QAiB1B"}

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

@@ -0,0 +1,36 @@
+import type { AgentOSInput } from '../../api/types/AgentOSInput';
+import { AgentOSResponse } from '../../api/types/AgentOSResponse';
+import { type GuardrailContext, type GuardrailEvaluationResult, type IGuardrailService } from './IGuardrailService';
+/**
+ * Outcome of an input guardrail evaluation.
+ */
+export interface GuardrailInputOutcome {
+    sanitizedInput: AgentOSInput;
+    evaluation?: GuardrailEvaluationResult | null;
+    evaluations?: GuardrailEvaluationResult[];
+}
+export interface GuardrailOutputOptions {
+    streamId: string;
+    personaId?: string;
+    inputEvaluations?: GuardrailEvaluationResult[] | null;
+}
+/**
+ * Runs the guardrail service against the inbound request.
+ * Returns the (potentially modified) input and the evaluation metadata.
+ */
+export declare function evaluateInputGuardrails(service: IGuardrailService | IGuardrailService[] | undefined, input: AgentOSInput, context: GuardrailContext): Promise<GuardrailInputOutcome>;
+/**
+ * Creates an async generator that emits a terminal guardrail error chunk.
+ */
+export declare function createGuardrailBlockedStream(context: GuardrailContext, evaluation: GuardrailEvaluationResult, options?: GuardrailOutputOptions): AsyncGenerator<AgentOSResponse, void, undefined>;
+/**
+ * Wraps a response stream and applies guardrail checks before yielding chunks
+ * to the host.
+ *
+ * **Evaluation Strategy:**
+ * - Guardrails with `config.evaluateStreamingChunks === true` evaluate TEXT_DELTA chunks (real-time)
+ * - All guardrails evaluate FINAL_RESPONSE chunks (final check)
+ * - This allows cost/performance tradeoffs per guardrail
+ */
+export declare function wrapOutputGuardrails(service: IGuardrailService | IGuardrailService[] | undefined, context: GuardrailContext, stream: AsyncGenerator<AgentOSResponse, void, undefined>, options: GuardrailOutputOptions): AsyncGenerator<AgentOSResponse, void, undefined>;
+//# sourceMappingURL=guardrailDispatcher.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"guardrailDispatcher.d.ts","sourceRoot":"","sources":["../../../src/core/guardrails/guardrailDispatcher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EACL,eAAe,EAIhB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACvB,MAAM,qBAAqB,CAAC;AAW7B;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,cAAc,EAAE,YAAY,CAAC;IAC7B,UAAU,CAAC,EAAE,yBAAyB,GAAG,IAAI,CAAC;IAC9C,WAAW,CAAC,EAAE,yBAAyB,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,yBAAyB,EAAE,GAAG,IAAI,CAAC;CACvD;AASD;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,iBAAiB,GAAG,iBAAiB,EAAE,GAAG,SAAS,EAC5D,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,qBAAqB,CAAC,CAmDhC;AAED;;GAEG;AACH,wBAAuB,4BAA4B,CACjD,OAAO,EAAE,gBAAgB,EACzB,UAAU,EAAE,yBAAyB,EACrC,OAAO,CAAC,EAAE,sBAAsB,GAC/B,cAAc,CAAC,eAAe,EAAE,IAAI,EAAE,SAAS,CAAC,CAkBlD;AAED;;;;;;;;GAQG;AACH,wBAAuB,oBAAoB,CACzC,OAAO,EAAE,iBAAiB,GAAG,iBAAiB,EAAE,GAAG,SAAS,EAC5D,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,CA8IlD"}

package/dist/core/guardrails/guardrailDispatcher.js

@@ -0,0 +1,240 @@
+import { uuidv4 } from '../../utils/uuid.js';
+import { AgentOSResponseChunkType, } from '../../api/types/AgentOSResponse.js';
+import { GuardrailAction, } from './IGuardrailService.js';
+// Type guard to narrow services that implement evaluateOutput
+function hasEvaluateOutput(svc) {
+    return typeof svc.evaluateOutput === 'function';
+}
+/**
+ * Runs the guardrail service against the inbound request.
+ * Returns the (potentially modified) input and the evaluation metadata.
+ */
+export async function evaluateInputGuardrails(service, input, context) {
+    const services = Array.isArray(service)
+        ? service.filter(Boolean)
+        : service
+            ? [service]
+            : [];
+    if (services.length === 0) {
+        return { sanitizedInput: input, evaluations: [] };
+    }
+    let sanitizedInput = input;
+    const evaluations = [];
+    for (const currentService of services) {
+        if (!currentService?.evaluateInput) {
+            continue;
+        }
+        let evaluation = null;
+        try {
+            evaluation = await currentService.evaluateInput({ context, input: sanitizedInput });
+        }
+        catch (error) {
+            console.warn('[AgentOS][Guardrails] evaluateInput failed.', error);
+            continue;
+        }
+        if (!evaluation) {
+            continue;
+        }
+        evaluations.push(evaluation);
+        if (evaluation.action === GuardrailAction.SANITIZE && evaluation.modifiedText !== undefined) {
+            sanitizedInput = {
+                ...sanitizedInput,
+                textInput: evaluation.modifiedText,
+            };
+            continue;
+        }
+        if (evaluation.action === GuardrailAction.BLOCK) {
+            return { sanitizedInput, evaluation, evaluations };
+        }
+    }
+    return {
+        sanitizedInput,
+        evaluation: evaluations.at(-1) ?? null,
+        evaluations,
+    };
+}
+/**
+ * Creates an async generator that emits a terminal guardrail error chunk.
+ */
+export async function* createGuardrailBlockedStream(context, evaluation, options) {
+    const streamId = options?.streamId ?? uuidv4();
+    const errorChunk = {
+        type: AgentOSResponseChunkType.ERROR,
+        streamId,
+        gmiInstanceId: 'guardrail',
+        personaId: options?.personaId ?? context.personaId ?? 'unknown_persona',
+        isFinal: true,
+        timestamp: new Date().toISOString(),
+        code: evaluation.reasonCode ?? 'GUARDRAIL_BLOCKED',
+        message: evaluation.reason ?? 'Request blocked by guardrail policy.',
+        details: {
+            action: evaluation.action,
+            metadata: evaluation.metadata,
+            context,
+        },
+    };
+    yield errorChunk;
+}
+/**
+ * Wraps a response stream and applies guardrail checks before yielding chunks
+ * to the host.
+ *
+ * **Evaluation Strategy:**
+ * - Guardrails with `config.evaluateStreamingChunks === true` evaluate TEXT_DELTA chunks (real-time)
+ * - All guardrails evaluate FINAL_RESPONSE chunks (final check)
+ * - This allows cost/performance tradeoffs per guardrail
+ */
+export async function* wrapOutputGuardrails(service, context, stream, options) {
+    const services = Array.isArray(service)
+        ? service.filter(Boolean)
+        : service
+            ? [service]
+            : [];
+    // Separate guardrails by evaluation mode
+    const streamingGuardrails = services.filter((svc) => svc.config?.evaluateStreamingChunks === true && hasEvaluateOutput(svc));
+    const _finalOnlyGuardrails = services.filter((svc) => svc.config?.evaluateStreamingChunks !== true && typeof svc.evaluateOutput === 'function');
+    const guardrailEnabled = services.some((svc) => typeof svc.evaluateOutput === 'function');
+    const serializedInputEvaluations = (options.inputEvaluations ?? []).map(serializeEvaluation);
+    let inputMetadataApplied = serializedInputEvaluations.length === 0;
+    // Track streaming evaluations for rate limiting
+    const streamingEvaluationCounts = new Map();
+    for await (const chunk of stream) {
+        let currentChunk = chunk;
+        if (!inputMetadataApplied && serializedInputEvaluations.length > 0) {
+            currentChunk = withGuardrailMetadata(currentChunk, { input: serializedInputEvaluations });
+            inputMetadataApplied = true;
+        }
+        // Evaluate streaming chunks (TEXT_DELTA) if guardrails are configured for it
+        if (streamingGuardrails.length > 0 &&
+            chunk.type === AgentOSResponseChunkType.TEXT_DELTA &&
+            !chunk.isFinal) {
+            const outputEvaluations = [];
+            let workingChunk = currentChunk;
+            for (const svc of streamingGuardrails) {
+                const svcId = svc.id || 'unknown';
+                const currentCount = streamingEvaluationCounts.get(svcId) || 0;
+                const maxEvals = svc.config?.maxStreamingEvaluations;
+                // Skip if rate limit reached
+                if (maxEvals !== undefined && currentCount >= maxEvals) {
+                    continue;
+                }
+                let evaluation = null;
+                try {
+                    const evalRes = await svc.evaluateOutput({ context, chunk: workingChunk });
+                    streamingEvaluationCounts.set(svcId, currentCount + 1);
+                    evaluation = evalRes ?? null;
+                }
+                catch (error) {
+                    console.warn('[AgentOS][Guardrails] evaluateOutput (streaming) failed.', error);
+                }
+                if (!evaluation) {
+                    continue;
+                }
+                outputEvaluations.push(evaluation);
+                if (evaluation.action === GuardrailAction.BLOCK) {
+                    yield* createGuardrailBlockedStream(context, evaluation, options);
+                    return;
+                }
+                // For TEXT_DELTA chunks, sanitize modifies the textDelta field
+                if (evaluation.action === GuardrailAction.SANITIZE && evaluation.modifiedText !== undefined) {
+                    workingChunk = {
+                        ...workingChunk,
+                        textDelta: evaluation.modifiedText,
+                    };
+                }
+            }
+            if (outputEvaluations.length > 0) {
+                workingChunk = withGuardrailMetadata(workingChunk, {
+                    output: outputEvaluations.map(serializeEvaluation),
+                });
+            }
+            currentChunk = workingChunk;
+        }
+        // Evaluate final chunks (all guardrails)
+        if (guardrailEnabled && chunk.isFinal) {
+            const outputEvaluations = [];
+            let workingChunk = currentChunk;
+            for (const svc of services) {
+                if (!svc?.evaluateOutput) {
+                    continue;
+                }
+                let evaluation = null;
+                try {
+                    evaluation = await svc.evaluateOutput({ context, chunk: workingChunk });
+                }
+                catch (error) {
+                    console.warn('[AgentOS][Guardrails] evaluateOutput (final) failed.', error);
+                }
+                if (!evaluation) {
+                    continue;
+                }
+                outputEvaluations.push(evaluation);
+                if (evaluation.action === GuardrailAction.BLOCK) {
+                    yield* createGuardrailBlockedStream(context, evaluation, options);
+                    return;
+                }
+                if (evaluation.action === GuardrailAction.SANITIZE &&
+                    workingChunk.type === AgentOSResponseChunkType.FINAL_RESPONSE) {
+                    workingChunk = {
+                        ...workingChunk,
+                        finalResponseText: evaluation.modifiedText !== undefined
+                            ? evaluation.modifiedText
+                            : workingChunk.finalResponseText,
+                    };
+                }
+            }
+            if (outputEvaluations.length > 0) {
+                workingChunk = withGuardrailMetadata(workingChunk, {
+                    output: outputEvaluations.map(serializeEvaluation),
+                });
+            }
+            currentChunk = workingChunk;
+        }
+        yield currentChunk;
+    }
+}
+function serializeEvaluation(evaluation) {
+    return {
+        action: evaluation.action,
+        reason: evaluation.reason,
+        reasonCode: evaluation.reasonCode,
+        metadata: evaluation.metadata,
+    };
+}
+function withGuardrailMetadata(chunk, entry) {
+    const existingMetadata = chunk.metadata ?? {};
+    const existingGuardrail = existingMetadata.guardrail ?? {};
+    const existingInput = Array.isArray(existingGuardrail.input)
+        ? existingGuardrail.input
+        : existingGuardrail.input
+            ? [existingGuardrail.input]
+            : [];
+    const existingOutput = Array.isArray(existingGuardrail.output)
+        ? existingGuardrail.output
+        : existingGuardrail.output
+            ? [existingGuardrail.output]
+            : [];
+    const incomingInput = normalizeMetadata(entry.input);
+    const incomingOutput = normalizeMetadata(entry.output);
+    const mergedInput = existingInput.concat(incomingInput);
+    const mergedOutput = existingOutput.concat(incomingOutput);
+    const guardrail = {
+        ...existingGuardrail,
+        ...(mergedInput.length ? { input: mergedInput } : {}),
+        ...(mergedOutput.length ? { output: mergedOutput } : {}),
+    };
+    return {
+        ...chunk,
+        metadata: {
+            ...existingMetadata,
+            guardrail,
+        },
+    };
+}
+function normalizeMetadata(entry) {
+    if (!entry) {
+        return [];
+    }
+    return Array.isArray(entry) ? entry : [entry];
+}
+//# sourceMappingURL=guardrailDispatcher.js.map

package/dist/core/guardrails/guardrailDispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardrailDispatcher.js","sourceRoot":"","sources":["../../../src/core/guardrails/guardrailDispatcher.ts"],"names":[],"mappings":"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"}

package/dist/core/hitl/HumanInteractionManager.d.ts

@@ -0,0 +1,146 @@
+/**
+ * @file HumanInteractionManager.ts
+ * @description Implementation of the Human-in-the-Loop Manager for AgentOS.
+ * Manages structured collaboration between AI agents and human operators.
+ *
+ * @module AgentOS/HITL
+ * @version 1.0.0
+ */
+import type { ILogger } from '../../logging/ILogger';
+import type { IHumanInteractionManager, PendingAction, ApprovalDecision, ClarificationRequest, ClarificationResponse, DraftOutput, EditedOutput, EscalationContext, EscalationDecision, WorkflowCheckpoint, CheckpointDecision, HumanFeedback, HITLStatistics, HITLNotificationHandler } from './IHumanInteractionManager';
+/**
+ * Configuration for HumanInteractionManager.
+ */
+export interface HumanInteractionManagerConfig {
+    /** Logger instance */
+    logger?: ILogger;
+    /** Default timeout for requests in ms */
+    defaultTimeoutMs?: number;
+    /** Notification handler */
+    notificationHandler?: HITLNotificationHandler;
+    /** Maximum pending requests per type */
+    maxPendingPerType?: number;
+    /** Auto-reject on timeout (vs returning timeout response) */
+    autoRejectOnTimeout?: boolean;
+}
+/**
+ * Implementation of the Human-in-the-Loop Manager.
+ *
+ * Features:
+ * - Approval requests with severity levels
+ * - Clarification requests with options
+ * - Output review and editing
+ * - Escalation handling
+ * - Workflow checkpoints
+ * - Feedback collection for learning
+ *
+ * @implements {IHumanInteractionManager}
+ */
+export declare class HumanInteractionManager implements IHumanInteractionManager {
+    private readonly logger?;
+    private readonly defaultTimeoutMs;
+    private readonly maxPendingPerType;
+    private readonly autoRejectOnTimeout;
+    private notificationHandler?;
+    /** Pending approval requests */
+    private readonly pendingApprovals;
+    /** Pending clarification requests */
+    private readonly pendingClarifications;
+    /** Pending edit requests */
+    private readonly pendingEdits;
+    /** Pending escalations */
+    private readonly pendingEscalations;
+    /** Pending checkpoints */
+    private readonly pendingCheckpoints;
+    /** Feedback history */
+    private readonly feedbackHistory;
+    /** Statistics */
+    private stats;
+    private approvedCount;
+    private totalResponseTimeMs;
+    private responseCount;
+    /**
+     * Creates a new HumanInteractionManager instance.
+     *
+     * @param config - Configuration options
+     */
+    constructor(config?: HumanInteractionManagerConfig);
+    /**
+     * Requests human approval before executing an action.
+     */
+    requestApproval(action: PendingAction): Promise<ApprovalDecision>;
+    /**
+     * Submits an approval decision.
+     */
+    submitApprovalDecision(decision: ApprovalDecision): Promise<void>;
+    /**
+     * Requests clarification from a human.
+     */
+    requestClarification(request: ClarificationRequest): Promise<ClarificationResponse>;
+    /**
+     * Submits a clarification response.
+     */
+    submitClarification(response: ClarificationResponse): Promise<void>;
+    /**
+     * Requests human review and potential editing of agent output.
+     */
+    requestEdit(draft: DraftOutput): Promise<EditedOutput>;
+    /**
+     * Submits an edited output.
+     */
+    submitEdit(edited: EditedOutput): Promise<void>;
+    /**
+     * Escalates a situation to human control.
+     */
+    escalate(context: EscalationContext): Promise<EscalationDecision>;
+    /**
+     * Submits an escalation decision.
+     */
+    submitEscalationDecision(escalationId: string, decision: EscalationDecision): Promise<void>;
+    /**
+     * Creates a checkpoint for human review.
+     */
+    checkpoint(checkpoint: WorkflowCheckpoint): Promise<CheckpointDecision>;
+    /**
+     * Submits a checkpoint decision.
+     */
+    submitCheckpointDecision(decision: CheckpointDecision): Promise<void>;
+    /**
+     * Records human feedback for agent improvement.
+     */
+    recordFeedback(feedback: HumanFeedback): Promise<void>;
+    /**
+     * Gets feedback history for an agent.
+     */
+    getFeedbackHistory(agentId: string, options?: {
+        limit?: number;
+        since?: Date;
+        type?: HumanFeedback['feedbackType'];
+    }): Promise<HumanFeedback[]>;
+    /**
+     * Gets all pending requests awaiting human response.
+     */
+    getPendingRequests(): Promise<{
+        approvals: PendingAction[];
+        clarifications: ClarificationRequest[];
+        edits: DraftOutput[];
+        escalations: EscalationContext[];
+        checkpoints: WorkflowCheckpoint[];
+    }>;
+    /**
+     * Cancels a pending request.
+     */
+    cancelRequest(requestId: string, reason: string): Promise<void>;
+    /**
+     * Gets HITL interaction statistics.
+     */
+    getStatistics(): HITLStatistics;
+    /**
+     * Sets the notification handler.
+     */
+    setNotificationHandler(handler: HITLNotificationHandler): void;
+    private sendNotification;
+    private updatePendingCount;
+    private updateResponseTime;
+}
+//# sourceMappingURL=HumanInteractionManager.d.ts.map