@kuralle-agents/core 0.8.0 → 0.9.0

package/dist/runtime/openRun.d.ts

@@ -12,6 +12,11 @@ export interface OpenRunOptions {
     userId?: string;
     input?: UserInputContent;
     selection?: ResolvedSelection;
+    /** Agent-initiated turn: no user input; a wake note is appended instead. */
+    wake?: {
+        reason: string;
+        payload?: Record<string, unknown>;
+    };
     agentId?: string;
     seedMessages?: ModelMessage[];
     historyDelta?: ModelMessage[];

package/dist/runtime/openRun.js

@@ -71,6 +71,23 @@ export async function openRun(agentsById, options) {
             await options.sessionStore.save(sessionAfterPersist);
         }
     }
+    if (options.wake && !hasInput) {
+        const payloadNote = options.wake.payload
+            ? ` Context: ${JSON.stringify(options.wake.payload)}.`
+            : '';
+        const wakeMessage = {
+            role: 'system',
+            content: `[Scheduled wake: ${options.wake.reason}]${payloadNote} ` +
+                'There is no new user message. Re-engage the user proactively per your instructions; ' +
+                'if a task is in progress, follow up on it gently.',
+        };
+        runState.messages = [...runState.messages, wakeMessage];
+        runState.updatedAt = Date.now();
+        await runStore.putRunState(runState);
+        const sessionAfterPersist = (await options.sessionStore.get(options.sessionId)) ?? session;
+        sessionAfterPersist.messages = [...sessionAfterPersist.messages, wakeMessage];
+        await options.sessionStore.save(sessionAfterPersist);
+    }
     const agent = agentsById.get(runState.activeAgentId);
     if (!agent) {
         throw new Error(`Unknown activeAgentId "${runState.activeAgentId}"`);

package/dist/runtime/policies/agentTurn.d.ts

@@ -6,6 +6,10 @@ export interface PreTurnResult {
     proceed: boolean;
     userMessage: string;
     blockedMessage?: string;
+    /** Id of the processor/policy that blocked (set when `proceed` is false). */
+    blockedBy?: string;
+    /** Machine-readable block reason (set when `proceed` is false). */
+    blockedReason?: string;
 }
 export interface PostTurnResult {
     proceed: boolean;

package/dist/runtime/policies/agentTurn.js

@@ -1,11 +1,24 @@
 import { appendConversationAudit } from '../../audit/record.js';
 import { SAFE_DEGRADED_MESSAGE } from '../../flow/degrade.js';
 import { runInputProcessors, runOutputProcessors } from '../../processors/ProcessorRunner.js';
+function userTextProjection(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .filter((part) => part.type === 'text' && typeof part.text === 'string')
+        .map((part) => part.text)
+        .join('\n');
+}
+// Guards must see multimodal turns too: a WhatsApp image whose CAPTION carries
+// a card number is still PII; an injection attempt in a caption is still an
+// injection. Project the text parts — file/image parts pass through untouched.
 function latestUserMessage(messages) {
     for (let index = messages.length - 1; index >= 0; index -= 1) {
         const message = messages[index];
-        if (message?.role === 'user' && typeof message.content === 'string') {
-            return message.content;
+        if (message?.role === 'user') {
+            return userTextProjection(message.content);
         }
     }
     return '';
@@ -91,6 +104,8 @@ async function runRefinementPolicies(ctx, userMessage) {
                 proceed: false,
                 userMessage: current,
                 blockedMessage: decision.userFacingMessage ?? decision.rationale ?? 'Input blocked',
+                blockedBy: policy.name,
+                blockedReason: decision.rationale,
             };
         }
         if (decision.decision === 'rewrite') {
@@ -138,7 +153,7 @@ async function runValidationPolicies(ctx, userMessage, assistantOutput, toolCall
                 proceed: false,
                 text: safe,
                 blockedMessage: safe,
-                control: { type: 'escalate', reason: decision.rationale },
+                control: { type: 'escalate', reason: decision.rationale, category: decision.escalationReason },
                 confidence: decision.confidence,
             };
         }
@@ -170,10 +185,16 @@ export async function applyPreTurnPolicies(ctx) {
                 proceed: false,
                 userMessage,
                 blockedMessage: outcome.message,
+                blockedBy: outcome.processorId,
+                blockedReason: outcome.reason,
             };
         }
         if (outcome.input !== userMessage) {
             patchLatestUserMessage(ctx.runState.messages, outcome.input);
+            patchLatestUserMessage(ctx.session.messages, outcome.input);
+            // Persist immediately: a redaction (e.g. PII) must replace the raw
+            // value in the durable record, not only in this turn's memory.
+            await ctx.runStore.putRunState(ctx.runState);
         }
     }
     return runRefinementPolicies(ctx, latestUserMessage(ctx.runState.messages));
@@ -210,7 +231,17 @@ function patchLatestUserMessage(messages, next) {
     for (let index = messages.length - 1; index >= 0; index -= 1) {
         const message = messages[index];
         if (message?.role === 'user') {
-            messages[index] = { role: 'user', content: next };
+            if (Array.isArray(message.content)) {
+                // Multimodal turn: rewrite the text while preserving file/image parts.
+                const mediaParts = message.content.filter((part) => part.type !== 'text');
+                messages[index] = {
+                    role: 'user',
+                    content: [{ type: 'text', text: next }, ...mediaParts],
+                };
+            }
+            else {
+                messages[index] = { role: 'user', content: next };
+            }
             return;
         }
     }

package/dist/runtime/userInput.d.ts

@@ -10,6 +10,8 @@ import { type UserContent, type TranscriptionModel } from 'ai';
  * input buffer are all persisted through the `SessionStore` (JSON/Redis/Postgres).
  */
 export type UserInputContent = UserContent;
+/** Merge multiple user inputs into one turn (ingress coalescing / mid-turn drain). */
+export declare function mergeUserInputContents(items: UserInputContent[]): UserInputContent | undefined;
 /** Text projection of user input — for confirm-gate parsing, choice matching, and
  *  extraction hints. Non-text parts are dropped. A plain string returns as-is. */
 export declare function userInputToText(input: UserInputContent): string;

package/dist/runtime/userInput.js

@@ -23,6 +23,26 @@ function audioSource(data) {
     }
     return data;
 }
+/** Merge multiple user inputs into one turn (ingress coalescing / mid-turn drain). */
+export function mergeUserInputContents(items) {
+    if (items.length === 0)
+        return undefined;
+    if (items.length === 1)
+        return items[0];
+    const parts = [];
+    for (const item of items) {
+        if (typeof item === 'string') {
+            if (item.length > 0)
+                parts.push({ type: 'text', text: item });
+        }
+        else {
+            parts.push(...item);
+        }
+    }
+    if (parts.length === 0)
+        return '';
+    return parts;
+}
 /** Text projection of user input — for confirm-gate parsing, choice matching, and
  *  extraction hints. Non-text parts are dropped. A plain string returns as-is. */
 export function userInputToText(input) {

package/dist/scheduler/index.d.ts

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+import type { Tool } from '../types/effectTool.js';
+import type { HarnessStreamPart, TurnHandle } from '../types/stream.js';
+/**
+ * Deferred-work scheduling for proactive (agent-initiated) turns.
+ *
+ * One `Scheduler` contract across the framework: the engagement layer's
+ * broadcast/drip jobs and the runtime's wake turns ride the same interface.
+ * Backends: `createInProcessScheduler` (dev, timer-based), Cloudflare DO
+ * alarms via `@kuralle-agents/cf-agent`, or any queue (BullMQ, Cloud Tasks)
+ * implementing the two methods.
+ */
+export interface ScheduledJob {
+    kind: string;
+    payload: Record<string, unknown>;
+}
+export interface Scheduler {
+    enqueue(job: ScheduledJob, opts?: {
+        delayMs?: number;
+    }): Promise<string>;
+    cancel(jobId: string): Promise<void>;
+}
+export type InjectableTimer = {
+    set(fn: () => void, ms: number): unknown;
+    clear(handle: unknown): void;
+};
+/**
+ * Default in-process scheduler (timer-based). For single-process/dev.
+ * Inject a durable adapter (DO alarms, BullMQ, Cloud Tasks) for
+ * multi-process / serverless.
+ */
+export declare function createInProcessScheduler(opts: {
+    run: (job: ScheduledJob) => void | Promise<void>;
+    timer?: InjectableTimer;
+}): Scheduler;
+export declare const WAKE_JOB_KIND = "kuralle.wake";
+export interface WakeOptions {
+    /** Why the agent is waking — composed into the wake note the model sees. */
+    reason: string;
+    /** Structured context for the wake turn (e.g. the abandoned cart id). */
+    payload?: Record<string, unknown>;
+}
+export interface WakeJobPayload extends WakeOptions {
+    sessionId: string;
+}
+export declare function wakeJob(wake: WakeJobPayload): ScheduledJob;
+export declare function isWakeJob(job: ScheduledJob): boolean;
+/** What a wake turn produced — handed to the host's delivery function. */
+export interface WakeDelivery {
+    sessionId: string;
+    reason: string;
+    payload?: Record<string, unknown>;
+    /** Full stream of the wake turn (text, tool events, interactive parts…). */
+    parts: HarnessStreamPart[];
+    /** Concatenated assistant text of the wake turn. */
+    text: string;
+}
+/** The runtime surface a wake runner needs (satisfied by `Runtime`). */
+export interface WakeRunnable {
+    run(opts: {
+        sessionId: string;
+        wake: WakeOptions;
+    }): TurnHandle;
+}
+/**
+ * Build the scheduler executor for wake jobs: runs the agent-initiated turn
+ * and hands the produced parts to `deliver` (e.g. the messaging outbound
+ * pipeline — which keeps the send window-safe). Compose with your own job
+ * kinds: `run: (job) => isWakeJob(job) ? runWake(job) : runMine(job)`.
+ */
+export declare function createWakeJobRunner(runtime: WakeRunnable, opts: {
+    deliver: (delivery: WakeDelivery) => Promise<void>;
+    onError?: (error: unknown, job: ScheduledJob) => void;
+}): (job: ScheduledJob) => Promise<void>;
+declare const scheduleFollowupInput: z.ZodObject<{
+    delayMinutes: z.ZodNumber;
+    reason: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Durable tool letting the agent schedule its own follow-up wake turn
+ * ("I'll check back in an hour"). Safe for `globalTools` — it only schedules;
+ * the wake turn itself goes through the full guard/window pipeline.
+ */
+export declare function createScheduleFollowupTool(scheduler: Scheduler): Tool<z.infer<typeof scheduleFollowupInput>, {
+    scheduled: boolean;
+    jobId: string;
+    inMinutes: number;
+}>;
+export {};

package/dist/scheduler/index.js

@@ -0,0 +1,104 @@
+import { z } from 'zod';
+import { defineTool } from '../tools/effect/defineTool.js';
+const defaultTimer = {
+    set: (fn, ms) => setTimeout(fn, ms),
+    clear: (handle) => clearTimeout(handle),
+};
+/**
+ * Default in-process scheduler (timer-based). For single-process/dev.
+ * Inject a durable adapter (DO alarms, BullMQ, Cloud Tasks) for
+ * multi-process / serverless.
+ */
+export function createInProcessScheduler(opts) {
+    const timer = opts.timer ?? defaultTimer;
+    let nextJobId = 0;
+    const handles = new Map();
+    return {
+        async enqueue(job, options) {
+            const jobId = String(++nextJobId);
+            const delayMs = options?.delayMs ?? 0;
+            const handle = timer.set(() => {
+                handles.delete(jobId);
+                void opts.run(job);
+            }, delayMs);
+            handles.set(jobId, handle);
+            return jobId;
+        },
+        async cancel(jobId) {
+            const handle = handles.get(jobId);
+            if (handle === undefined)
+                return;
+            timer.clear(handle);
+            handles.delete(jobId);
+        },
+    };
+}
+// ── Wake jobs (agent-initiated turns) ────────────────────────────────────────
+export const WAKE_JOB_KIND = 'kuralle.wake';
+export function wakeJob(wake) {
+    return { kind: WAKE_JOB_KIND, payload: { ...wake } };
+}
+export function isWakeJob(job) {
+    return job.kind === WAKE_JOB_KIND;
+}
+/**
+ * Build the scheduler executor for wake jobs: runs the agent-initiated turn
+ * and hands the produced parts to `deliver` (e.g. the messaging outbound
+ * pipeline — which keeps the send window-safe). Compose with your own job
+ * kinds: `run: (job) => isWakeJob(job) ? runWake(job) : runMine(job)`.
+ */
+export function createWakeJobRunner(runtime, opts) {
+    return async (job) => {
+        if (!isWakeJob(job)) {
+            return;
+        }
+        const { sessionId, reason, payload } = job.payload;
+        try {
+            const handle = runtime.run({ sessionId, wake: { reason, payload } });
+            const parts = [];
+            let text = '';
+            for await (const part of handle.events) {
+                parts.push(part);
+                if (part.type === 'text-delta') {
+                    text += part.delta;
+                }
+            }
+            const result = await handle;
+            await opts.deliver({ sessionId, reason, payload, parts, text: text || result.text });
+        }
+        catch (error) {
+            if (opts.onError) {
+                opts.onError(error, job);
+            }
+            else {
+                console.warn(`[Kuralle] wake turn failed for session ${sessionId}:`, error);
+            }
+        }
+    };
+}
+const scheduleFollowupInput = z.object({
+    delayMinutes: z.number().min(1).describe('How many minutes from now to follow up'),
+    reason: z
+        .string()
+        .describe('Why the follow-up is needed, e.g. "user said they would decide after lunch"'),
+});
+/**
+ * Durable tool letting the agent schedule its own follow-up wake turn
+ * ("I'll check back in an hour"). Safe for `globalTools` — it only schedules;
+ * the wake turn itself goes through the full guard/window pipeline.
+ */
+export function createScheduleFollowupTool(scheduler) {
+    return defineTool({
+        name: 'schedule_followup',
+        description: 'Schedule a follow-up message to the user after a delay. Use when the user asks you to check back later, or a pending task warrants a proactive follow-up.',
+        input: scheduleFollowupInput,
+        execute: async (args, ctx) => {
+            const sessionId = ctx?.session.id;
+            if (!sessionId) {
+                throw new Error('schedule_followup requires a session context');
+            }
+            const jobId = await scheduler.enqueue(wakeJob({ sessionId, reason: args.reason }), { delayMs: Math.round(args.delayMinutes * 60_000) });
+            return { scheduled: true, jobId, inMinutes: args.delayMinutes };
+        },
+    });
+}

package/dist/types/channel.d.ts

@@ -4,6 +4,7 @@ import type { RunContext } from './run-context.js';
 import type { FlowNode } from './flow.js';
 import type { AnyTool } from './effectTool.js';
 import type { DispatchMode } from '../runtime/dispatchMode.js';
+import type { EscalationReason } from '../escalation/types.js';
 export type DriverOutputCapability = 'kuralle-controlled-text' | 'kuralle-controlled-tts' | 'native-realtime';
 export interface HostControlContext {
     dispatchMode: DispatchMode;
@@ -67,6 +68,7 @@ export type TurnControl = {
 } | {
     type: 'escalate';
     reason: string;
+    category?: EscalationReason;
 } | {
     type: 'recover';
     reason?: string;

package/dist/types/stream.d.ts

@@ -1,5 +1,6 @@
 import type { ConversationOutcome } from '../outcomes/types.js';
 import type { ChoiceOption } from './selection.js';
+import type { EscalationReason } from '../escalation/types.js';
 /**
  * Authoritative runtime stream union (`runFlow` / `Runtime` emit).
  * `types/voice.ts` defines a separate voice/realtime union that intentionally
@@ -77,6 +78,34 @@ export type HarnessStreamPart = {
     rationale: string;
     userFacingMessage: string;
     handlerOutcome?: 'queued' | 'connected' | 'failed';
+} | {
+    /** An agent-initiated (scheduled wake) turn — there is no new user message. */
+    type: 'wake';
+    reason: string;
+} | {
+    type: 'escalation';
+    reason: string;
+    category?: EscalationReason;
+    /** Result of the configured escalation handler. */
+    outcome: 'queued' | 'connected' | 'failed';
+    /** The LLM handoff brief included in the request, when generated. */
+    summary?: string;
+} | {
+    type: 'context-compacted';
+    /** Estimated history tokens before/after compaction. */
+    beforeTokens: number;
+    afterTokens: number;
+    /** Number of older messages folded into the summary. */
+    summarizedCount: number;
+} | {
+    type: 'compaction-skipped';
+    reason: string;
+} | {
+    type: 'context-overflow-recovered';
+    /** Partial assistant/tool messages stripped from the failed turn. */
+    strippedCount: number;
+    /** Whether the forced post-recovery compaction actually compacted. */
+    compacted: boolean;
 } | {
     type: 'error';
     error: string;

package/guides/GUARDRAILS.md

@@ -65,6 +65,50 @@ const runtime = new Runtime({
 });
 ```
 
+## Built-in Guards (0.8.5)
+
+Production-ready processors and validators ship with core — wire them into
+`AgentConfig.guardrails` / `AgentConfig.validate`:
+
+```ts
+import {
+  createPromptInjectionGuard,
+  createPiiInputGuard,
+  createPiiOutputGuard,
+  createModerationGuard,
+  createGroundingValidator,
+} from '@kuralle-agents/core';
+
+const agent = defineAgent({
+  id: 'shop',
+  instructions: '...',
+  guardrails: {
+    input: [
+      createPromptInjectionGuard(),                  // deterministic injection patterns → block
+      createPiiInputGuard(),                         // Luhn-checked cards + emails → redact (PCI default)
+      createModerationGuard({ model: controlModel }), // LLM policy classifier → block
+    ],
+    output: [createPiiOutputGuard()],
+  },
+  validate: [
+    // state-grounded "no invented actions" gate — rewrite-not-block
+    createGroundingValidator({ model: controlModel }),
+  ],
+});
+```
+
+- PII detectors default to `['credit-card', 'email']`; `phone`/`iban` are
+  opt-in (they collide with order ids). Cards are Luhn-validated, IBANs
+  checksum-validated — order numbers don't false-positive.
+- The moderation guard fails **open** by default (`onError: 'block'` for
+  zero-tolerance deployments); deterministic guards still run during an
+  outage.
+- The grounding validator flags completed-action claims unsupported by this
+  turn's tool calls, flow state, or citations and rewrites them out; if no
+  safe rewrite exists, it blocks.
+- A pre-turn block emits a `safety-blocked` stream part with the moderator id
+  and rationale, then the user-facing message.
+
 ## Output Redaction
 
 `outputRedaction` is a defense-in-depth filter for streamed text.

package/package.json

@@ -6,7 +6,7 @@
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
     "directory": "packages/kuralle-core"
   },
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "A framework for structured conversational AI agents",
   "publishConfig": {
     "access": "public"
@@ -103,7 +103,7 @@
     "typescript": "^5.3.0",
     "vitest": "^3.2.4",
     "zod": "^4.0.0",
-    "@kuralle-agents/realtime-audio": "0.8.0"
+    "@kuralle-agents/realtime-audio": "0.9.0"
   },
   "dependencies": {
     "chrono-node": "^2.6.0"