@kuralle-agents/core 0.8.0 → 0.8.5

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.8.5",
   "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.8.5"
   },
   "dependencies": {
     "chrono-node": "^2.6.0"