@kuralle-agents/cf-agent 0.7.2 → 0.8.5

package/dist/BridgeSessionStore.js

@@ -1,3 +1,4 @@
+import { DURABLE_RUNS_KEY } from '@kuralle-agents/core';
 import { getToolName, isToolUIPart } from 'ai';
 import { OrchestrationStore } from './OrchestrationStore.js';
 /**
@@ -32,7 +33,7 @@ export class BridgeSessionStore {
         const orchState = await this.orchestration.get(key);
         // Convert CF UIMessages to Kuralle ModelMessages
         const messages = convertUIMessagesToModelMessages(this.cfMessages);
-        return {
+        const session = {
             id: key,
             conversationId: key,
             channelId: 'web',
@@ -48,6 +49,10 @@ export class BridgeSessionStore {
             })),
             state: orchState?.state,
         };
+        // Restore the durable run journal so durable tools / suspend-resume can find
+        // the run (SessionRunStore reads it off the Session object).
+        session[DURABLE_RUNS_KEY] = orchState?.durableRuns ?? {};
+        return session;
     }
     /**
      * Save only orchestration state. CF handles message persistence.
@@ -66,6 +71,7 @@ export class BridgeSessionStore {
                     : String(h.timestamp),
             })),
             state: session.state,
+            durableRuns: session[DURABLE_RUNS_KEY],
         };
         await this.orchestration.save(session.id, state);
     }

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 } 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';
@@ -79,6 +79,12 @@ export declare abstract class KuralleAgent<Env = unknown, State = unknown> exten
      * Get the Durable Object ID as the session identifier.
      */
     private getSessionId;
+    /**
+     * The hex Durable Object id for this instance. Subclasses use it to mint
+     * out-of-band callbacks (e.g. a payment link) that route back to this exact DO
+     * via `namespace.idFromString(...)`, then resume it through `resumeWithSignal`.
+     */
+    protected getDurableObjectId(): string;
     /**
      * Called by CF when a chat message arrives.
      *
@@ -102,7 +108,29 @@ export declare abstract class KuralleAgent<Env = unknown, State = unknown> exten
      */
     onChatMessage(onFinish: StreamTextOnFinishCallback<ToolSet>, options?: OnChatMessageOptions): Promise<Response>;
     /**
-     * Extract the text content of the last user message from CF's messages array.
+     * Build a Kuralle runtime for this DO (fresh per request to pick up latest
+     * config). Bridges CF messages + DO-backed orchestration/working-memory state.
+     * Shared by the chat path and the durable resume path.
+     */
+    private buildRuntime;
+    /**
+     * Resume a suspended run by delivering a durable signal — the server-side
+     * counterpart to a human/out-of-band event (e.g. a paid checkout link being
+     * hit). Drives the resumed turn to completion, then persists **and broadcasts**
+     * the resumed assistant reply through CF's machinery, so a live client sees it
+     * and a reconnecting client replays it from history.
+     *
+     * Idempotent at the durable layer: delivering the same `signal.signalId` twice
+     * is deduplicated by the effect log, so a double-clicked link is safe.
+     *
+     * @returns the assistant text produced by the resumed turn (may be empty).
+     */
+    protected resumeWithSignal(signal: SignalDelivery): Promise<{
+        text: string;
+    }>;
+    /**
+     * Extract the last user turn from CF's messages as runtime input (multimodal).
+     * See `lastUserInputFromMessages`.
      */
     private getLastUserInput;
     /**
@@ -122,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,13 +19,14 @@
  * 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';
 import { createSSEResponse } from './StreamAdapter.js';
 import { DEFAULT_STREAM_CONFIG } from './types.js';
 import { durableAgentSurface } from './durable-agent-surface.js';
+import { lastUserInputFromMessages } from './cfMessageInput.js';
 /**
  * Abstract base class for running Kuralle agents on Cloudflare.
  *
@@ -83,6 +84,14 @@ export class KuralleAgent extends AIChatAgent {
     getSessionId() {
         return durableAgentSurface(this).ctx.id.toString();
     }
+    /**
+     * The hex Durable Object id for this instance. Subclasses use it to mint
+     * out-of-band callbacks (e.g. a payment link) that route back to this exact DO
+     * via `namespace.idFromString(...)`, then resume it through `resumeWithSignal`.
+     */
+    getDurableObjectId() {
+        return this.getSessionId();
+    }
     /**
      * Called by CF when a chat message arrives.
      *
@@ -110,19 +119,42 @@ export class KuralleAgent extends AIChatAgent {
         if (!lastUserMessage) {
             return new Response('No user message', { status: 400 });
         }
+        const sessionId = this.getSessionId();
+        this.runtime = this.buildRuntime();
+        const handle = this.runtime.run({
+            input: lastUserMessage,
+            sessionId,
+            userId: options?.body?.userId,
+            abortSignal: options?.abortSignal,
+        });
+        const streamConfig = {
+            ...DEFAULT_STREAM_CONFIG,
+            ...this.getStreamConfig(),
+        };
+        async function* parts() {
+            for await (const part of handle.events) {
+                yield part;
+            }
+        }
+        return createSSEResponse(parts(), streamConfig);
+    }
+    /**
+     * Build a Kuralle runtime for this DO (fresh per request to pick up latest
+     * config). Bridges CF messages + DO-backed orchestration/working-memory state.
+     * Shared by the chat path and the durable resume path.
+     */
+    buildRuntime() {
         const sessionId = this.getSessionId();
         const defaultAgentId = this.getDefaultAgentId();
-        // Build session store that bridges CF messages with Kuralle state
         const sessionStore = new BridgeSessionStore({
             sqlExecutor: this.getSql(),
             cfMessages: this.messages,
             sessionId,
             defaultAgentId,
         });
-        // Build runtime (fresh per request to pick up latest config)
         const extraConfig = this.getRuntimeConfig();
         const workingMemoryStore = this.getWorkingMemoryStore();
-        this.runtime = createRuntime({
+        return createRuntime({
             ...extraConfig,
             agents: this.getAgents(),
             defaultAgentId,
@@ -131,39 +163,45 @@ export class KuralleAgent extends AIChatAgent {
                 ? { defaultWorkingMemoryStore: workingMemoryStore }
                 : {}),
         });
-        const handle = this.runtime.run({
-            input: lastUserMessage,
-            sessionId,
-            userId: options?.body?.userId,
-            abortSignal: options?.abortSignal,
-        });
-        const streamConfig = {
-            ...DEFAULT_STREAM_CONFIG,
-            ...this.getStreamConfig(),
-        };
-        async function* parts() {
-            for await (const part of handle.events) {
-                yield part;
-            }
+    }
+    /**
+     * Resume a suspended run by delivering a durable signal — the server-side
+     * counterpart to a human/out-of-band event (e.g. a paid checkout link being
+     * hit). Drives the resumed turn to completion, then persists **and broadcasts**
+     * the resumed assistant reply through CF's machinery, so a live client sees it
+     * and a reconnecting client replays it from history.
+     *
+     * Idempotent at the durable layer: delivering the same `signal.signalId` twice
+     * is deduplicated by the effect log, so a double-clicked link is safe.
+     *
+     * @returns the assistant text produced by the resumed turn (may be empty).
+     */
+    async resumeWithSignal(signal) {
+        const sessionId = this.getSessionId();
+        const runtime = this.buildRuntime();
+        const handle = runtime.run({ sessionId, signalDelivery: signal });
+        let text = '';
+        for await (const part of handle.events) {
+            if (part.type === 'text-delta')
+                text += part.delta;
         }
-        return createSSEResponse(parts(), streamConfig);
+        await handle;
+        if (text.trim()) {
+            const assistantMessage = {
+                id: crypto.randomUUID(),
+                role: 'assistant',
+                parts: [{ type: 'text', text }],
+            };
+            await this.persistMessages([...this.messages, assistantMessage]);
+        }
+        return { text };
     }
     /**
-     * Extract the text content of the last user message from CF's messages array.
+     * Extract the last user turn from CF's messages as runtime input (multimodal).
+     * See `lastUserInputFromMessages`.
      */
     getLastUserInput() {
-        for (let i = this.messages.length - 1; i >= 0; i--) {
-            const msg = this.messages[i];
-            if (msg.role !== 'user')
-                continue;
-            const text = msg.parts
-                ?.filter((part) => part.type === 'text')
-                .map((part) => part.text)
-                .join('');
-            if (text?.trim())
-                return text;
-        }
-        return null;
+        return lastUserInputFromMessages(this.messages);
     }
     /**
      * Delete orchestration rows older than `maxAgeMs`. Returns the number of
@@ -185,12 +223,87 @@ 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.
      */
     async onRequest(request) {
         const url = new URL(request.url);
+        // Durable resume: deliver a signal to a suspended run (e.g. a paid checkout
+        // link). Body: { signalId: string, name: string, payload?: unknown }.
+        if (request.method === 'POST' && url.pathname.endsWith('/resume')) {
+            const body = (await request.json().catch(() => null));
+            if (!body || typeof body.signalId !== 'string' || typeof body.name !== 'string') {
+                return Response.json({ error: 'signalId and name are required' }, { status: 400 });
+            }
+            const { text } = await this.resumeWithSignal(body);
+            return Response.json({ ok: true, text });
+        }
         if (url.pathname.endsWith('/orchestration-state')) {
             const store = new OrchestrationStore(this.getSql());
             // OrchestrationStore is now keyed by sessionId (was a single `'default'`

package/dist/cfMessageInput.d.ts

@@ -0,0 +1,11 @@
+import type { UserInputContent } from '@kuralle-agents/core';
+import type { UIMessage } from 'ai';
+/**
+ * Map the last user turn in a CF `UIMessage[]` to runtime `UserInputContent`.
+ *
+ * Text parts → `TextPart`; file parts (images / documents / audio uploaded via the
+ * CF chat client) → `FilePart` carrying the part's URL, so multimodal input reaches
+ * the model instead of being dropped. A text-only turn collapses to a plain string.
+ * Returns `null` when the last user turn carries no usable content.
+ */
+export declare function lastUserInputFromMessages(messages: UIMessage[]): UserInputContent | null;

package/dist/cfMessageInput.js

@@ -0,0 +1,42 @@
+/**
+ * Map the last user turn in a CF `UIMessage[]` to runtime `UserInputContent`.
+ *
+ * Text parts → `TextPart`; file parts (images / documents / audio uploaded via the
+ * CF chat client) → `FilePart` carrying the part's URL, so multimodal input reaches
+ * the model instead of being dropped. A text-only turn collapses to a plain string.
+ * Returns `null` when the last user turn carries no usable content.
+ */
+export function lastUserInputFromMessages(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (!msg || msg.role !== 'user')
+            continue;
+        const content = [];
+        for (const part of msg.parts ?? []) {
+            if (part.type === 'text' && typeof part.text === 'string') {
+                content.push({ type: 'text', text: part.text });
+            }
+            else if (part.type === 'file' &&
+                typeof part.url === 'string' &&
+                typeof part.mediaType === 'string') {
+                content.push({
+                    type: 'file',
+                    data: part.url,
+                    mediaType: part.mediaType,
+                    filename: part.filename,
+                });
+            }
+        }
+        if (content.length === 0)
+            continue;
+        const hasFile = content.some((p) => p.type === 'file');
+        if (!hasFile) {
+            const text = content.map((p) => (p.type === 'text' ? p.text : '')).join('');
+            if (text.trim())
+                return text;
+            continue;
+        }
+        return content;
+    }
+    return null;
+}

package/dist/index.d.ts

@@ -29,6 +29,7 @@ export { OrchestrationStore } from './OrchestrationStore.js';
 export { SqlPersistentMemoryStore } from './SqlPersistentMemoryStore.js';
 export { createSqlExecutor } from './sqlExecutor.js';
 export { createSSEResponse } from './StreamAdapter.js';
+export { lastUserInputFromMessages } from './cfMessageInput.js';
 export type { StreamAdapterConfig, OrchestrationState, SqlExecutor, } from './types.js';
 export { DEFAULT_STREAM_CONFIG } from './types.js';
 export type { HarnessConfig, HarnessHooks, HarnessStreamPart, Session, } from '@kuralle-agents/core';

package/dist/index.js

@@ -29,4 +29,5 @@ export { OrchestrationStore } from './OrchestrationStore.js';
 export { SqlPersistentMemoryStore } from './SqlPersistentMemoryStore.js';
 export { createSqlExecutor } from './sqlExecutor.js';
 export { createSSEResponse } from './StreamAdapter.js';
+export { lastUserInputFromMessages } from './cfMessageInput.js';
 export { DEFAULT_STREAM_CONFIG } from './types.js';

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { SessionDurableRuns } from '@kuralle-agents/core';
 /**
  * SQL executor type matching Cloudflare's Durable Object sql binding.
  *
@@ -27,6 +28,13 @@ export interface OrchestrationState {
         timestamp: string;
     }>;
     state?: Record<string, unknown>;
+    /**
+     * Kuralle durable run journal (effect log + run state) for this session.
+     * `SessionRunStore` keeps the run on the Session object, so the bridge must
+     * persist + restore it here — otherwise durable tools and suspend/resume fail
+     * with "Run not found" on CF.
+     */
+    durableRuns?: SessionDurableRuns;
 }
 /**
  * Configuration for the stream adapter.

package/package.json

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