@kuralle-agents/cf-agent 0.8.0 → 0.8.5

package/dist/KuralleAgent.d.ts

@@ -20,7 +20,7 @@
  */
 import { AIChatAgent } from '@cloudflare/ai-chat';
 import { type HarnessConfig } from '@kuralle-agents/core';
-import type { PersistentMemoryStore, SignalDelivery } from '@kuralle-agents/core';
+import type { PersistentMemoryStore, SignalDelivery, ScheduledJob, Scheduler, WakeJobPayload } from '@kuralle-agents/core';
 import type { StreamTextOnFinishCallback, ToolSet } from 'ai';
 import type { OnChatMessageOptions } from '@cloudflare/ai-chat';
 import type { StreamAdapterConfig } from './types.js';
@@ -150,6 +150,31 @@ export declare abstract class KuralleAgent<Env = unknown, State = unknown> exten
      * ```
      */
     protected cleanupOrchestrationRows(maxAgeMs: number): Promise<number>;
+    /**
+     * Durable scheduler backed by the agents SDK's DO-alarm scheduling
+     * (`this.schedule`). Jobs survive isolate restarts and fire in this exact
+     * DO via `runScheduledKuralleJob`. Satisfies the core `Scheduler` contract,
+     * so engagement drips/broadcasts and runtime wake turns can share it.
+     */
+    protected wakeScheduler(): Scheduler;
+    /**
+     * Schedule a proactive wake turn for this DO's conversation (cart
+     * abandonment nudge, "check back in an hour", delivery follow-up).
+     * Returns the schedule id (cancellable via `wakeScheduler().cancel`).
+     */
+    protected scheduleWake(delayMs: number, wake: Omit<WakeJobPayload, 'sessionId'>): Promise<string>;
+    /**
+     * DO-alarm callback for scheduled jobs. Wake jobs run an agent-initiated
+     * turn and persist + broadcast the assistant reply through CF's machinery
+     * (same path as `resumeWithSignal`); other job kinds go to
+     * `onScheduledJob` for subclasses to handle.
+     */
+    runScheduledKuralleJob(job: ScheduledJob): Promise<void>;
+    /**
+     * Override to handle non-wake scheduled jobs (engagement drips, cleanup…).
+     * Default: no-op with a warning, so a mis-routed job is visible.
+     */
+    protected onScheduledJob(job: ScheduledJob): Promise<void>;
     /**
      * HTTP endpoint handler.
      * Adds Kuralle-specific endpoints on top of CF's defaults.

package/dist/KuralleAgent.js

@@ -19,7 +19,7 @@
  * is stored in a separate lightweight SQLite table via OrchestrationStore.
  */
 import { AIChatAgent } from '@cloudflare/ai-chat';
-import { createRuntime } from '@kuralle-agents/core';
+import { createRuntime, isWakeJob, wakeJob } from '@kuralle-agents/core';
 import { BridgeSessionStore } from './BridgeSessionStore.js';
 import { OrchestrationStore } from './OrchestrationStore.js';
 import { SqlPersistentMemoryStore } from './SqlPersistentMemoryStore.js';
@@ -223,6 +223,71 @@ export class KuralleAgent extends AIChatAgent {
         const store = new OrchestrationStore(this.getSql());
         return store.cleanup(maxAgeMs);
     }
+    /**
+     * Durable scheduler backed by the agents SDK's DO-alarm scheduling
+     * (`this.schedule`). Jobs survive isolate restarts and fire in this exact
+     * DO via `runScheduledKuralleJob`. Satisfies the core `Scheduler` contract,
+     * so engagement drips/broadcasts and runtime wake turns can share it.
+     */
+    wakeScheduler() {
+        return {
+            enqueue: async (job, opts) => {
+                const delaySeconds = Math.max(0, Math.ceil((opts?.delayMs ?? 0) / 1000));
+                const schedule = await this.schedule(delaySeconds, 'runScheduledKuralleJob', job);
+                return schedule.id;
+            },
+            cancel: async (jobId) => {
+                await this.cancelSchedule(jobId);
+            },
+        };
+    }
+    /**
+     * Schedule a proactive wake turn for this DO's conversation (cart
+     * abandonment nudge, "check back in an hour", delivery follow-up).
+     * Returns the schedule id (cancellable via `wakeScheduler().cancel`).
+     */
+    async scheduleWake(delayMs, wake) {
+        return this.wakeScheduler().enqueue(wakeJob({ ...wake, sessionId: this.getSessionId() }), { delayMs });
+    }
+    /**
+     * DO-alarm callback for scheduled jobs. Wake jobs run an agent-initiated
+     * turn and persist + broadcast the assistant reply through CF's machinery
+     * (same path as `resumeWithSignal`); other job kinds go to
+     * `onScheduledJob` for subclasses to handle.
+     */
+    async runScheduledKuralleJob(job) {
+        if (!isWakeJob(job)) {
+            await this.onScheduledJob(job);
+            return;
+        }
+        const { reason, payload } = job.payload;
+        const runtime = this.buildRuntime();
+        const handle = runtime.run({
+            sessionId: this.getSessionId(),
+            wake: { reason, payload },
+        });
+        let text = '';
+        for await (const part of handle.events) {
+            if (part.type === 'text-delta')
+                text += part.delta;
+        }
+        await handle;
+        if (text.trim()) {
+            const assistantMessage = {
+                id: crypto.randomUUID(),
+                role: 'assistant',
+                parts: [{ type: 'text', text }],
+            };
+            await this.persistMessages([...this.messages, assistantMessage]);
+        }
+    }
+    /**
+     * Override to handle non-wake scheduled jobs (engagement drips, cleanup…).
+     * Default: no-op with a warning, so a mis-routed job is visible.
+     */
+    async onScheduledJob(job) {
+        console.warn(`[KuralleAgent] Unhandled scheduled job kind: ${job.kind}`);
+    }
     /**
      * HTTP endpoint handler.
      * Adds Kuralle-specific endpoints on top of CF's defaults.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuralle-agents/cf-agent",
-  "version": "0.8.0",
+  "version": "0.8.5",
   "description": "Kuralle agent integration for Cloudflare Workers with AIChatAgent",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,20 +21,20 @@
   "dependencies": {
     "@cloudflare/ai-chat": "^0.8.4",
     "ai": "^6.0.90",
-    "@kuralle-agents/core": "0.8.0",
-    "@kuralle-agents/realtime-audio": "0.8.0"
+    "@kuralle-agents/core": "0.8.5",
+    "@kuralle-agents/realtime-audio": "0.8.5"
   },
   "peerDependencies": {
     "agents": ">=0.14.0 <1.0.0",
     "zod": "^4.0.0",
-    "@kuralle-agents/voice-protocol": "0.8.0"
+    "@kuralle-agents/voice-protocol": "0.8.5"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.12.7",
     "agents": "^0.15.0",
     "typescript": "^5.7.0",
     "vitest": "^3.2.4",
-    "@kuralle-agents/voice-protocol": "0.8.0"
+    "@kuralle-agents/voice-protocol": "0.8.5"
   },
   "engines": {
     "node": ">=20"