@kuralle-agents/core 0.7.2 → 0.8.5

package/dist/index.d.ts

@@ -12,6 +12,8 @@ export { buildMarkOutcomeTool, OUTCOMES_MARK_TOOL_NAME } from './outcomes/index.
 export { EvalRunner } from './eval/EvalRunner.js';
 export { scoreTurn, aggregateScores } from './eval/scoring.js';
 export type { EvalScenario, EvalTurn, ScenarioScore, TurnScore } from './eval/types.js';
+export { simulateConversation, createJudge, runSimulationSuite, DEFAULT_JUDGE_DIMENSIONS, } from './eval/simulation.js';
+export type { SimulatedUserPersona, SimulatedTranscriptTurn, SimulationResult, SimulationEnd, SimulatableRuntime, SimulateConversationOptions, JudgeDimension, JudgeVerdict, CreateJudgeOptions, ConversationJudge, SimulationScenario, SimulationSuiteResult, RunSimulationSuiteOptions, } from './eval/simulation.js';
 export { SessionWorkingMemory } from './runtime/WorkingMemory.js';
 export type { Tool, ToolSet, ToolDefinition, ToolWithFiller, ToolExecutionOptions, ToolExecutionContext, } from './tools/Tool.js';
 export { createTool, createToolWithFiller } from './tools/Tool.js';
@@ -34,6 +36,14 @@ export type { Metrics } from './hooks/builtin/metrics.js';
 export { createObservabilityHooks } from './hooks/builtin/observability.js';
 export type { ObservabilityConfig } from './hooks/builtin/observability.js';
 export type { SessionTrace, TraceStreamEvent } from './types/telemetry.js';
+export { createPromptInjectionGuard } from './processors/builtin/promptInjectionGuard.js';
+export type { PromptInjectionGuardOptions } from './processors/builtin/promptInjectionGuard.js';
+export { createPiiInputGuard, createPiiOutputGuard, redactPii, } from './processors/builtin/piiGuard.js';
+export type { PiiDetector, PiiGuardOptions, PiiMatch, PiiScanResult, } from './processors/builtin/piiGuard.js';
+export { createModerationGuard, createModerationOutputGuard, } from './processors/builtin/moderationGuard.js';
+export type { ModerationGuardOptions } from './processors/builtin/moderationGuard.js';
+export { createGroundingValidator } from './capabilities/validators/groundingValidator.js';
+export type { GroundingValidatorOptions } from './capabilities/validators/groundingValidator.js';
 export { ToolEnforcer, createToolEnforcer } from './guards/ToolEnforcer.js';
 export * as StopConditions from './guards/StopConditions.js';
 export * from './guards/rules.js';
@@ -47,6 +57,8 @@ export type { MemoryEntry, SearchMemoryRequest, SearchMemoryResponse, MemoryInge
 export { InMemoryMemoryService } from './memory/index.js';
 export { preloadMemoryContext } from './memory/index.js';
 export { extractMemories } from './memory/index.js';
+export { createFactMemoryService } from './memory/index.js';
+export type { FactMemoryServiceOptions } from './memory/index.js';
 export type { PersistentMemoryStore, PersistentMemoryBlock, PersistentMemoryConfig, MemoryBlockScope, WorkingMemoryBlockSpec, WorkingMemoryConfig, } from './memory/index.js';
 export { FilePersistentMemoryStore, InMemoryPersistentMemoryStore, RoutedPersistentMemoryStore, TieredPersistentMemoryStore, scanMemoryWrite, buildMemoryBlockTool, DEFAULT_BLOCK_CHAR_LIMIT, DEFAULT_AUTO_LOAD_BLOCKS, } from './memory/index.js';
 export type { RoutedPersistentMemoryStoreConfig, MemoryRouteFn, } from './memory/index.js';
@@ -55,6 +67,10 @@ export { resolveAgentWorkspace, type ResolvedAgentWorkspace, } from './runtime/r
 export { DEFAULT_CONTEXT_BUDGET, VOICE_CONTEXT_BUDGET, computeMessageHistoryBudget, truncateToTokenBudget, formatMemoryWithBudget, estimateTokenCount, ContextBudget, } from './runtime/ContextBudget.js';
 export type { ContextBudgetConfig } from './runtime/ContextBudget.js';
 export { TokenAccumulator } from './runtime/TokenAccumulator.js';
+export { compactMessages, estimateMessagesTokens, DEFAULT_COMPACTION_TRIGGER_TOKENS, DEFAULT_COMPACTION_KEEP_RECENT, } from './runtime/compaction.js';
+export type { CompactionConfig, CompactionResult } from './runtime/compaction.js';
+export { isContextOverflowError, recoverFromContextOverflow, } from './runtime/contextOverflow.js';
+export type { OverflowRecoveryResult } from './runtime/contextOverflow.js';
 export { applyPromptCache, applyAnthropicCacheControl, buildOpenAIResponsesProviderOptions, isAnthropicLanguageModel, isOpenAIResponsesModel, } from './runtime/promptCache.js';
 export type { AnthropicCacheTtl, OpenAIResponsesCompactOptions } from './runtime/promptCache.js';
 export { handoffFilters, removeToolHistory, keepRecentMessages, removeKeys, composeFilters, } from './runtime/handoffFilters.js';
@@ -64,7 +80,10 @@ export type { ToolExecutor, ConversationState, ConversationEventLog, Conversatio
 export type * from './types/index.js';
 export { CapabilityHost, ExtractionCapability, GuardrailCapability, AutoRetrieveCapability, PassThroughRefinement, PassThroughValidation, toGeminiDeclarations, toAISDKTools, } from './capabilities/index.js';
 export type { Capability, CapabilityAction, ExtractionToolResponseEnvelope, FlowReconfigureTransition, ToolDeclaration, PromptSection as CapabilityPromptSection, GeminiFunctionDeclaration, ExtractionCapabilityConfig, RetrieveProvider, AutoRetrieveCapabilityConfig, RefinementCapability, RefineInput, RefineDecision, ValidationCapability, ValidateInput, ValidateDecision, SourceRef, } from './capabilities/index.js';
-export type { EscalationOutcome, EscalationReason } from './escalation/types.js';
+export type { EscalationOutcome, EscalationReason, EscalationRequest, EscalationHandler, EscalationConfig, } from './escalation/types.js';
+export { buildEscalationRequest, ensureSessionMetadata } from './escalation/escalation.js';
+export { createInProcessScheduler, createWakeJobRunner, createScheduleFollowupTool, wakeJob, isWakeJob, WAKE_JOB_KIND, } from './scheduler/index.js';
+export type { Scheduler, ScheduledJob, InjectableTimer, WakeOptions, WakeJobPayload, WakeDelivery, WakeRunnable, } from './scheduler/index.js';
 export { filterAuditEntries } from './audit/index.js';
 export type { AuditConfig, AuditEntryBase, AuditEntryType, AuditListOptions, AuditReplayOptions, ConversationAuditEntry, ConversationAuditLog, } from './audit/types.js';
 export type { RealtimeAudioClient, RealtimeSessionConfig, RealtimeAudioConfig, RealtimeToolResponse, RealtimeEventMap, RealtimeSessionHandle, } from './realtime/index.js';
@@ -90,10 +109,13 @@ export type { HarnessStreamPart } from './types/stream.js';
 export { harnessToUIMessageStream } from './ai-sdk/uiMessageStream.js';
 export type { KuralleMetadata, KuralleDataParts, KuralleUIMessage, } from './ai-sdk/uiMessageStream.js';
 export type { ChoiceOption, ResolvedSelection } from './types/selection.js';
-export type { RunState, StepRecord } from './runtime/durable/types.js';
+export type { RunState, StepRecord, SignalDelivery, SessionDurableRuns, PersistedRun, } from './runtime/durable/types.js';
+export { DURABLE_RUNS_KEY } from './runtime/durable/types.js';
 export type { RunStore } from './runtime/durable/RunStore.js';
 export type { ChannelDriver, TextDriver } from './runtime/channels/index.js';
 export type { TurnResult } from './types/channel.js';
-export type { RunContext } from './types/run-context.js';
+export type { RunContext, ToolContext, ActionContext } from './types/run-context.js';
+export type { AnyTool } from './types/effectTool.js';
 export { createRuntime, Runtime, type HarnessConfig, type RunOptions, } from './runtime/Runtime.js';
 export type { RuntimeLike } from './runtime/RuntimeLike.js';
+export { userInputToText, hasMediaParts, transcribeAudioParts, type UserInputContent, } from './runtime/userInput.js';

package/dist/index.js

@@ -7,6 +7,7 @@ export { InMemoryConversationStore } from './conversations/index.js';
 export { buildMarkOutcomeTool, OUTCOMES_MARK_TOOL_NAME } from './outcomes/index.js';
 export { EvalRunner } from './eval/EvalRunner.js';
 export { scoreTurn, aggregateScores } from './eval/scoring.js';
+export { simulateConversation, createJudge, runSimulationSuite, DEFAULT_JUDGE_DIMENSIONS, } from './eval/simulation.js';
 export { SessionWorkingMemory } from './runtime/WorkingMemory.js';
 export { createTool, createToolWithFiller } from './tools/Tool.js';
 export { createHandoffTool, isHandoffResult } from './tools/handoff.js';
@@ -20,6 +21,10 @@ export { HookRunner, createHookRunner } from './hooks/HookRunner.js';
 export { loggingHooks, createLoggingHooks } from './hooks/builtin/logging.js';
 export { createMetricsHooks, InMemoryMetrics } from './hooks/builtin/metrics.js';
 export { createObservabilityHooks } from './hooks/builtin/observability.js';
+export { createPromptInjectionGuard } from './processors/builtin/promptInjectionGuard.js';
+export { createPiiInputGuard, createPiiOutputGuard, redactPii, } from './processors/builtin/piiGuard.js';
+export { createModerationGuard, createModerationOutputGuard, } from './processors/builtin/moderationGuard.js';
+export { createGroundingValidator } from './capabilities/validators/groundingValidator.js';
 export { ToolEnforcer, createToolEnforcer } from './guards/ToolEnforcer.js';
 export * as StopConditions from './guards/StopConditions.js';
 export * from './guards/rules.js';
@@ -29,15 +34,20 @@ export { getTemplate, registerTemplate, listTemplates, getAllTemplates } from '.
 export { InMemoryMemoryService } from './memory/index.js';
 export { preloadMemoryContext } from './memory/index.js';
 export { extractMemories } from './memory/index.js';
+export { createFactMemoryService } from './memory/index.js';
 export { FilePersistentMemoryStore, InMemoryPersistentMemoryStore, RoutedPersistentMemoryStore, TieredPersistentMemoryStore, scanMemoryWrite, buildMemoryBlockTool, DEFAULT_BLOCK_CHAR_LIMIT, DEFAULT_AUTO_LOAD_BLOCKS, } from './memory/index.js';
 export { wireWorkingMemory, loadWorkingMemoryBlocks, formatWorkingMemorySection, resolveWorkingMemoryStore, } from './runtime/grounding/workingMemory.js';
 export { resolveAgentWorkspace, } from './runtime/resolveAgentWorkspace.js';
 export { DEFAULT_CONTEXT_BUDGET, VOICE_CONTEXT_BUDGET, computeMessageHistoryBudget, truncateToTokenBudget, formatMemoryWithBudget, estimateTokenCount, ContextBudget, } from './runtime/ContextBudget.js';
 export { TokenAccumulator } from './runtime/TokenAccumulator.js';
+export { compactMessages, estimateMessagesTokens, DEFAULT_COMPACTION_TRIGGER_TOKENS, DEFAULT_COMPACTION_KEEP_RECENT, } from './runtime/compaction.js';
+export { isContextOverflowError, recoverFromContextOverflow, } from './runtime/contextOverflow.js';
 export { applyPromptCache, applyAnthropicCacheControl, buildOpenAIResponsesProviderOptions, isAnthropicLanguageModel, isOpenAIResponsesModel, } from './runtime/promptCache.js';
 export { handoffFilters, removeToolHistory, keepRecentMessages, removeKeys, composeFilters, } from './runtime/handoffFilters.js';
 export { DefaultToolExecutor, DefaultConversationState, DefaultConversationEventLog, DefaultAgentStateController, createFoundation, } from './foundation/index.js';
 export { CapabilityHost, ExtractionCapability, GuardrailCapability, AutoRetrieveCapability, PassThroughRefinement, PassThroughValidation, toGeminiDeclarations, toAISDKTools, } from './capabilities/index.js';
+export { buildEscalationRequest, ensureSessionMetadata } from './escalation/escalation.js';
+export { createInProcessScheduler, createWakeJobRunner, createScheduleFollowupTool, wakeJob, isWakeJob, WAKE_JOB_KIND, } from './scheduler/index.js';
 export { filterAuditEntries } from './audit/index.js';
 export { defineAgent, defineFlow, reply, collect, action, decide, confirmGate, } from './authoring/index.js';
 export { defineTool } from './types/effectTool.js';
@@ -47,4 +57,6 @@ export { SkillsCapability, wireAgentSkills, collectRegisteredNames, validateSkil
 export { buildToolSet, toolToAiSdk, wrapAiSdkTool, ToolApprovalDeniedError, ToolTimeoutError, } from './tools/effect/index.js';
 export { parseConfirmation } from './flow/confirmParse.js';
 export { harnessToUIMessageStream } from './ai-sdk/uiMessageStream.js';
+export { DURABLE_RUNS_KEY } from './runtime/durable/types.js';
 export { createRuntime, Runtime, } from './runtime/Runtime.js';
+export { userInputToText, hasMediaParts, transcribeAudioParts, } from './runtime/userInput.js';

package/dist/memory/factMemoryService.d.ts

@@ -0,0 +1,28 @@
+import type { LanguageModel } from 'ai';
+import type { MemoryService } from './MemoryService.js';
+import type { PersistentMemoryStore } from './blocks/types.js';
+/**
+ * Fact-extracting cross-session memory, backed by a `PersistentMemoryStore`
+ * block per user (scope `user`, owner = `session.userId`, one fact per line).
+ *
+ * Unlike the raw-message ingestion path (`extractMemories`), this service
+ * runs an LLM merge at ingest: existing facts + the new transcript produce
+ * the COMPLETE updated fact list (still-true facts kept, changed ones
+ * updated, obsolete ones dropped) — so the block stays small, current, and
+ * deduplicated instead of growing append-only.
+ *
+ * Works on every block backend: file (node), Postgres/Redis adapters, and
+ * Cloudflare DO SQLite via `SqlPersistentMemoryStore`.
+ */
+export interface FactMemoryServiceOptions {
+    store: PersistentMemoryStore;
+    /** Extractor/merger model, run at temperature 0. */
+    model: LanguageModel;
+    /** Block key per user. Default: `'FACTS'`. */
+    blockKey?: string;
+    /** Char limit for the fact block. Default: `DEFAULT_BLOCK_CHAR_LIMIT`. */
+    charLimit?: number;
+    /** Max facts kept per user. Default: 25. */
+    maxFacts?: number;
+}
+export declare function createFactMemoryService(options: FactMemoryServiceOptions): MemoryService;

package/dist/memory/factMemoryService.js

@@ -0,0 +1,137 @@
+import { generateObject } from 'ai';
+import { z } from 'zod';
+import { DEFAULT_BLOCK_CHAR_LIMIT } from './blocks/types.js';
+import { scanMemoryWrite } from './blocks/safetyScanner.js';
+const factsSchema = z.object({
+    facts: z.array(z.string()),
+});
+function parseFactLines(content) {
+    return content
+        .split('\n')
+        .map((line) => line.replace(/^-\s*/, '').trim())
+        .filter((line) => line.length > 0);
+}
+function renderTranscript(session) {
+    const lines = [];
+    for (const message of session.messages) {
+        if (message.role !== 'user' && message.role !== 'assistant')
+            continue;
+        const content = typeof message.content === 'string'
+            ? message.content
+            : Array.isArray(message.content)
+                ? message.content
+                    .filter((part) => part.type === 'text')
+                    .map((part) => part.text)
+                    .join('\n')
+                : '';
+        if (content.trim()) {
+            lines.push(`${message.role}: ${content}`);
+        }
+    }
+    return lines.join('\n');
+}
+const QUERY_TOKEN_MIN_LENGTH = 4;
+function lexicalScore(query, fact) {
+    const factLower = fact.toLowerCase();
+    const tokens = query
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((token) => token.length >= QUERY_TOKEN_MIN_LENGTH);
+    if (tokens.length === 0)
+        return 0;
+    let hits = 0;
+    for (const token of tokens) {
+        if (factLower.includes(token))
+            hits += 1;
+    }
+    return hits / tokens.length;
+}
+export function createFactMemoryService(options) {
+    const blockKey = options.blockKey ?? 'FACTS';
+    const charLimit = options.charLimit ?? DEFAULT_BLOCK_CHAR_LIMIT;
+    const maxFacts = options.maxFacts ?? 25;
+    return {
+        async addSessionToMemory(session) {
+            if (!session.userId)
+                return;
+            const transcript = renderTranscript(session);
+            if (!transcript.trim())
+                return;
+            try {
+                const existing = await options.store.loadBlock('user', session.userId, blockKey);
+                const existingFacts = existing ? parseFactLines(existing.content) : [];
+                const { object } = await generateObject({
+                    model: options.model,
+                    schema: factsSchema,
+                    temperature: 0,
+                    system: [
+                        'You maintain the long-term memory of a customer-facing assistant.',
+                        'From the EXISTING FACTS and the NEW CONVERSATION, produce the complete updated fact list about this user.',
+                        'Keep facts that are still true, update ones that changed, drop obsolete or duplicate ones.',
+                        'Only durable facts worth remembering across conversations: stable preferences, profile details',
+                        '(name, address, sizes), recurring context (orders they reference, their business).',
+                        'Exclude one-off details, small talk, and sensitive payment data (card numbers, passwords).',
+                        `At most ${maxFacts} facts, each a single self-contained sentence under 200 characters.`,
+                    ].join('\n'),
+                    prompt: [
+                        `EXISTING FACTS:\n${existingFacts.length > 0 ? existingFacts.map((f) => `- ${f}`).join('\n') : '(none)'}`,
+                        `NEW CONVERSATION:\n${transcript}`,
+                    ].join('\n\n'),
+                });
+                const safeFacts = object.facts
+                    .map((fact) => fact.trim())
+                    .filter((fact) => fact.length > 0 && scanMemoryWrite(fact).safe)
+                    .slice(0, maxFacts);
+                let content = safeFacts.map((fact) => `- ${fact}`).join('\n');
+                while (content.length > charLimit && safeFacts.length > 0) {
+                    safeFacts.pop();
+                    content = safeFacts.map((fact) => `- ${fact}`).join('\n');
+                }
+                await options.store.saveBlock({
+                    key: blockKey,
+                    scope: 'user',
+                    content,
+                    charLimit,
+                    updatedAt: new Date().toISOString(),
+                }, session.userId);
+            }
+            catch (error) {
+                // Memory must never take down a turn — ingest failures are logged, not thrown.
+                console.warn(`[Kuralle] fact-memory ingest failed for user ${session.userId}:`, error instanceof Error ? error.message : error);
+            }
+        },
+        async searchMemory(request) {
+            const block = await options.store.loadBlock('user', request.userId, blockKey);
+            if (!block) {
+                return { memories: [] };
+            }
+            const facts = parseFactLines(block.content);
+            const createdAt = block.updatedAt ? new Date(block.updatedAt) : new Date();
+            const limit = request.limit ?? 10;
+            const scored = facts.map((fact, index) => ({
+                fact,
+                index,
+                score: lexicalScore(request.query, fact),
+            }));
+            const relevant = scored.filter((entry) => entry.score > 0);
+            // Facts are few and curated: when nothing matches lexically, return them
+            // all (up to limit) — continuity beats false-negative emptiness.
+            const selected = (relevant.length > 0 ? relevant.sort((a, b) => b.score - a.score) : scored)
+                .slice(0, limit);
+            return {
+                memories: selected.map((entry) => ({
+                    id: `${request.userId}:${blockKey}:${entry.index}`,
+                    sessionId: 'fact-memory',
+                    userId: request.userId,
+                    content: entry.fact,
+                    author: 'memory',
+                    createdAt,
+                    score: entry.score,
+                })),
+            };
+        },
+        async deleteMemories(userId) {
+            await options.store.deleteBlock('user', userId, blockKey);
+        },
+    };
+}

package/dist/memory/index.d.ts

@@ -3,6 +3,7 @@ export type { MemoryEntry, SearchMemoryRequest, SearchMemoryResponse, MemoryInge
 export { InMemoryMemoryService } from './stores/InMemoryMemoryService.js';
 export { preloadMemoryContext } from './preloadMemory.js';
 export { extractMemories } from './utils.js';
+export { createFactMemoryService, type FactMemoryServiceOptions, } from './factMemoryService.js';
 export type { PersistentMemoryStore, PersistentMemoryBlock, PersistentMemoryConfig, MemoryBlockScope, } from './blocks/types.js';
 export type { WorkingMemoryBlockSpec, WorkingMemoryConfig } from '../types/grounding.js';
 export { DEFAULT_BLOCK_CHAR_LIMIT, DEFAULT_AUTO_LOAD_BLOCKS, } from './blocks/types.js';

package/dist/memory/index.js

@@ -1,6 +1,7 @@
 export { InMemoryMemoryService } from './stores/InMemoryMemoryService.js';
 export { preloadMemoryContext } from './preloadMemory.js';
 export { extractMemories } from './utils.js';
+export { createFactMemoryService, } from './factMemoryService.js';
 export { DEFAULT_BLOCK_CHAR_LIMIT, DEFAULT_AUTO_LOAD_BLOCKS, } from './blocks/types.js';
 export { InMemoryPersistentMemoryStore } from './blocks/InMemoryPersistentMemoryStore.js';
 export { FilePersistentMemoryStore, } from './blocks/FilePersistentMemoryStore.js';

package/dist/processors/builtin/moderationGuard.d.ts

@@ -0,0 +1,24 @@
+import type { LanguageModel } from 'ai';
+import type { InputProcessor, OutputProcessor } from '../../types/processors.js';
+export interface ModerationGuardOptions {
+    /** Classifier model. Use a small/fast model — this runs on every turn it guards. */
+    model: LanguageModel;
+    /** Policy categories to flag. Defaults cover the standard abuse set. */
+    categories?: string[];
+    /** User-facing message when content is flagged. */
+    message?: string;
+    /**
+     * What to do when the classifier itself errors. `allow` (default) fails open —
+     * deterministic guards still run and an outage does not take the agent down.
+     * `block` fails closed for zero-tolerance deployments.
+     */
+    onError?: 'allow' | 'block';
+    id?: string;
+}
+/**
+ * LLM moderation guard over inbound user text. Runs the configured model as a
+ * temperature-0 classifier against the policy categories and blocks on a match.
+ */
+export declare function createModerationGuard(options: ModerationGuardOptions): InputProcessor;
+/** LLM moderation guard over assistant output — the post-turn counterpart. */
+export declare function createModerationOutputGuard(options: ModerationGuardOptions): OutputProcessor;

package/dist/processors/builtin/moderationGuard.js

@@ -0,0 +1,101 @@
+import { generateObject } from 'ai';
+import { z } from 'zod';
+const DEFAULT_CATEGORIES = [
+    'violence or threats of violence',
+    'sexual content involving minors',
+    'self-harm encouragement or instructions',
+    'hate or harassment targeting a protected group',
+    'facilitation of clearly illegal activity (weapons, drugs, fraud)',
+];
+const moderationSchema = z.object({
+    flagged: z.boolean(),
+    category: z.union([z.string(), z.null()]),
+    rationale: z.union([z.string(), z.null()]),
+});
+async function classify(model, categories, role, text, abortSignal) {
+    const { object } = await generateObject({
+        model,
+        schema: moderationSchema,
+        temperature: 0,
+        abortSignal,
+        system: [
+            `You are a content-policy classifier. Flag the ${role} ONLY if it clearly falls into one of these categories:`,
+            ...categories.map((category) => `- ${category}`),
+            'Ordinary rudeness, frustration, or sensitive-but-legitimate topics (health, finance, returns/refunds) are NOT flagged.',
+            'Respond with flagged=false unless the text is a clear match.',
+        ].join('\n'),
+        prompt: text,
+    });
+    return object;
+}
+/**
+ * LLM moderation guard over inbound user text. Runs the configured model as a
+ * temperature-0 classifier against the policy categories and blocks on a match.
+ */
+export function createModerationGuard(options) {
+    const categories = options.categories ?? DEFAULT_CATEGORIES;
+    const onError = options.onError ?? 'allow';
+    return {
+        id: options.id ?? 'moderation-guard',
+        name: 'Moderation guard',
+        description: 'LLM content-policy classifier over user input.',
+        process: async ({ input, context }) => {
+            let verdict;
+            try {
+                verdict = await classify(options.model, categories, 'user message', input, context.abortSignal);
+            }
+            catch {
+                if (onError === 'block') {
+                    return {
+                        action: 'block',
+                        reason: 'moderation-error',
+                        message: options.message ?? "Sorry, I can't help with that.",
+                    };
+                }
+                return { action: 'allow' };
+            }
+            if (!verdict.flagged) {
+                return { action: 'allow' };
+            }
+            return {
+                action: 'block',
+                reason: `moderation: ${verdict.category ?? 'flagged'}`,
+                message: options.message ?? "Sorry, I can't help with that.",
+            };
+        },
+    };
+}
+/** LLM moderation guard over assistant output — the post-turn counterpart. */
+export function createModerationOutputGuard(options) {
+    const categories = options.categories ?? DEFAULT_CATEGORIES;
+    const onError = options.onError ?? 'allow';
+    return {
+        id: options.id ?? 'moderation-output-guard',
+        name: 'Moderation output guard',
+        description: 'LLM content-policy classifier over assistant output.',
+        process: async ({ text, context }) => {
+            let verdict;
+            try {
+                verdict = await classify(options.model, categories, 'assistant response', text, context.abortSignal);
+            }
+            catch {
+                if (onError === 'block') {
+                    return {
+                        action: 'block',
+                        reason: 'moderation-error',
+                        message: options.message ?? 'Sorry, I cannot provide that response.',
+                    };
+                }
+                return { action: 'allow' };
+            }
+            if (!verdict.flagged) {
+                return { action: 'allow' };
+            }
+            return {
+                action: 'block',
+                reason: `moderation: ${verdict.category ?? 'flagged'}`,
+                message: options.message ?? 'Sorry, I cannot provide that response.',
+            };
+        },
+    };
+}

package/dist/processors/builtin/piiGuard.d.ts

@@ -0,0 +1,41 @@
+import type { InputProcessor, OutputProcessor } from '../../types/processors.js';
+/**
+ * Deterministic PII detection + redaction over message text.
+ *
+ * Detectors are conservative by default: `credit-card` (separator-tolerant,
+ * Luhn-validated so order/tracking numbers don't false-positive) and `email`.
+ * `phone` and `iban` are opt-in because their shapes collide with order ids,
+ * reference codes, and similar commerce artifacts.
+ */
+export type PiiDetector = 'credit-card' | 'email' | 'phone' | 'iban';
+export interface PiiGuardOptions {
+    /** Which detectors to run. Default: `['credit-card', 'email']`. */
+    detect?: PiiDetector[];
+    /** `redact` replaces matches in place; `block` refuses the message. Default: `redact`. */
+    mode?: 'redact' | 'block';
+    /** User-facing message when `mode: 'block'` trips. */
+    message?: string;
+    id?: string;
+}
+export interface PiiMatch {
+    detector: PiiDetector;
+    matchedText: string;
+}
+export interface PiiScanResult {
+    text: string;
+    matches: PiiMatch[];
+}
+/**
+ * Scan and redact PII in `text`. Returns the redacted text plus the list of
+ * matches (detector + original matched text) so callers can audit what was
+ * found without re-detecting.
+ */
+export declare function redactPii(text: string, detect?: PiiDetector[]): PiiScanResult;
+/**
+ * PII guard over inbound user text. `redact` mode rewrites the message before
+ * the model (and persisted history) sees the raw value — credit-card redaction
+ * inbound is the PCI-relevant default for commerce agents.
+ */
+export declare function createPiiInputGuard(options?: PiiGuardOptions): InputProcessor;
+/** PII guard over assistant output — stops the model echoing sensitive values back. */
+export declare function createPiiOutputGuard(options?: PiiGuardOptions): OutputProcessor;

package/dist/processors/builtin/piiGuard.js

@@ -0,0 +1,143 @@
+const DEFAULT_DETECTORS = ['credit-card', 'email'];
+const EMAIL_PATTERN = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
+// 13-19 digits with optional single space/dash separators; candidates are
+// Luhn-checked before redaction so plain long numbers survive.
+const CARD_CANDIDATE_PATTERN = /\b(?:\d[ -]?){12,18}\d\b/g;
+// Opt-in: international or separator-formatted numbers with 9+ digits total.
+const PHONE_PATTERN = /(?:\+\d{1,3}[ -.]?)?(?:\(\d{2,4}\)[ -.]?)?\d{2,4}[ -.]\d{3,4}[ -.]?\d{3,4}\b|\+\d{9,15}\b/g;
+const IBAN_PATTERN = /\b[A-Z]{2}\d{2}(?:[ ]?[A-Z0-9]){11,30}\b/g;
+function luhnValid(digits) {
+    let sum = 0;
+    let double = false;
+    for (let index = digits.length - 1; index >= 0; index -= 1) {
+        let digit = digits.charCodeAt(index) - 48;
+        if (double) {
+            digit *= 2;
+            if (digit > 9)
+                digit -= 9;
+        }
+        sum += digit;
+        double = !double;
+    }
+    return sum % 10 === 0;
+}
+function ibanChecksumValid(candidate) {
+    const compact = candidate.replace(/\s+/g, '').toUpperCase();
+    if (compact.length < 15 || compact.length > 34)
+        return false;
+    const rearranged = compact.slice(4) + compact.slice(0, 4);
+    let remainder = 0;
+    for (const char of rearranged) {
+        const value = /[A-Z]/.test(char) ? String(char.charCodeAt(0) - 55) : char;
+        for (const digit of value) {
+            remainder = (remainder * 10 + (digit.charCodeAt(0) - 48)) % 97;
+        }
+    }
+    return remainder === 1;
+}
+/**
+ * Scan and redact PII in `text`. Returns the redacted text plus the list of
+ * matches (detector + original matched text) so callers can audit what was
+ * found without re-detecting.
+ */
+export function redactPii(text, detect = DEFAULT_DETECTORS) {
+    const matches = [];
+    let current = text;
+    if (detect.includes('credit-card')) {
+        current = current.replace(CARD_CANDIDATE_PATTERN, (candidate) => {
+            const digits = candidate.replace(/[ -]/g, '');
+            if (digits.length < 13 || digits.length > 19 || !luhnValid(digits)) {
+                return candidate;
+            }
+            matches.push({ detector: 'credit-card', matchedText: candidate });
+            return '[redacted card number]';
+        });
+    }
+    if (detect.includes('iban')) {
+        current = current.replace(IBAN_PATTERN, (candidate) => {
+            if (!ibanChecksumValid(candidate)) {
+                return candidate;
+            }
+            matches.push({ detector: 'iban', matchedText: candidate });
+            return '[redacted iban]';
+        });
+    }
+    if (detect.includes('email')) {
+        current = current.replace(EMAIL_PATTERN, (candidate) => {
+            matches.push({ detector: 'email', matchedText: candidate });
+            return '[redacted email]';
+        });
+    }
+    if (detect.includes('phone')) {
+        current = current.replace(PHONE_PATTERN, (candidate) => {
+            const digits = candidate.replace(/\D/g, '');
+            if (digits.length < 9 || digits.length > 15) {
+                return candidate;
+            }
+            matches.push({ detector: 'phone', matchedText: candidate });
+            return '[redacted phone]';
+        });
+    }
+    return { text: current, matches };
+}
+/**
+ * PII guard over inbound user text. `redact` mode rewrites the message before
+ * the model (and persisted history) sees the raw value — credit-card redaction
+ * inbound is the PCI-relevant default for commerce agents.
+ */
+export function createPiiInputGuard(options = {}) {
+    const detect = options.detect ?? DEFAULT_DETECTORS;
+    const mode = options.mode ?? 'redact';
+    return {
+        id: options.id ?? 'pii-input-guard',
+        name: 'PII input guard',
+        description: `Detects ${detect.join(', ')} in user input and ${mode}s it.`,
+        process: ({ input }) => {
+            const scan = redactPii(input, detect);
+            if (scan.matches.length === 0) {
+                return { action: 'allow' };
+            }
+            if (mode === 'block') {
+                return {
+                    action: 'block',
+                    reason: `pii-detected: ${scan.matches.map((m) => m.detector).join(', ')}`,
+                    message: options.message ??
+                        'For your security, please do not share sensitive details like card numbers in chat.',
+                };
+            }
+            return {
+                action: 'modify',
+                input: scan.text,
+                reason: `pii-redacted: ${scan.matches.map((m) => m.detector).join(', ')}`,
+            };
+        },
+    };
+}
+/** PII guard over assistant output — stops the model echoing sensitive values back. */
+export function createPiiOutputGuard(options = {}) {
+    const detect = options.detect ?? DEFAULT_DETECTORS;
+    const mode = options.mode ?? 'redact';
+    return {
+        id: options.id ?? 'pii-output-guard',
+        name: 'PII output guard',
+        description: `Detects ${detect.join(', ')} in assistant output and ${mode}s it.`,
+        process: ({ text }) => {
+            const scan = redactPii(text, detect);
+            if (scan.matches.length === 0) {
+                return { action: 'allow' };
+            }
+            if (mode === 'block') {
+                return {
+                    action: 'block',
+                    reason: `pii-detected: ${scan.matches.map((m) => m.detector).join(', ')}`,
+                    message: options.message ?? 'Sorry, I cannot share that information.',
+                };
+            }
+            return {
+                action: 'modify',
+                text: scan.text,
+                reason: `pii-redacted: ${scan.matches.map((m) => m.detector).join(', ')}`,
+            };
+        },
+    };
+}

package/dist/processors/builtin/promptInjectionGuard.d.ts

@@ -0,0 +1,16 @@
+import type { InputProcessor } from '../../types/processors.js';
+export interface PromptInjectionGuardOptions {
+    /** User-facing message when a pattern matches. */
+    message?: string;
+    id?: string;
+}
+/**
+ * Deterministic prompt-injection guard over inbound user text. Reuses the
+ * injection pattern set that already protects persistent memory writes
+ * (`scanMemoryWrite`) — one audited pattern source, two enforcement points.
+ *
+ * False positive cost: the turn is refused with a polite message and the user
+ * can rephrase. False negative cost: instruction override — so the patterns
+ * err toward catching more.
+ */
+export declare function createPromptInjectionGuard(options?: PromptInjectionGuardOptions): InputProcessor;