@kuralle-agents/cf-agent 0.11.0 → 0.13.0

package/dist/BridgeSessionStore.js

@@ -52,6 +52,7 @@ export class BridgeSessionStore {
         // 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 ?? {};
+        session.version = orchState?.version ?? 0;
         return session;
     }
     /**
@@ -72,6 +73,7 @@ export class BridgeSessionStore {
             })),
             state: session.state,
             durableRuns: session[DURABLE_RUNS_KEY],
+            version: session.version ?? 0,
         };
         await this.orchestration.save(session.id, state);
     }

package/dist/KuralleAgent.d.ts

@@ -23,7 +23,7 @@ import { type HarnessConfig } 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';
+import type { StreamAdapterConfig, SqlExecutor } from './types.js';
 /**
  * Abstract base class for running Kuralle agents on Cloudflare.
  *
@@ -75,6 +75,12 @@ export declare abstract class KuralleAgent<Env = unknown, State = unknown> exten
      * CF's AIChatAgent exposes this.sql as a tagged template function.
      */
     private getSql;
+    /**
+     * The DO's SQL executor, for subclasses that need to read/write Kuralle session
+     * state out-of-band (e.g. a payment-confirmation webhook handler that runs
+     * outside a chat turn). Pair with `BridgeSessionStore` + `getDurableObjectId()`.
+     */
+    protected getSqlExecutor(): SqlExecutor;
     /**
      * Get the Durable Object ID as the session identifier.
      */

package/dist/KuralleAgent.js

@@ -78,6 +78,14 @@ export class KuralleAgent extends AIChatAgent {
     getSql() {
         return durableAgentSurface(this).sql.bind(this);
     }
+    /**
+     * The DO's SQL executor, for subclasses that need to read/write Kuralle session
+     * state out-of-band (e.g. a payment-confirmation webhook handler that runs
+     * outside a chat turn). Pair with `BridgeSessionStore` + `getDurableObjectId()`.
+     */
+    getSqlExecutor() {
+        return this.getSql();
+    }
     /**
      * Get the Durable Object ID as the session identifier.
      */

package/dist/OrchestrationStore.js

@@ -1,3 +1,4 @@
+import { StaleWriteError } from '@kuralle-agents/core';
 /**
  * Lightweight store for Kuralle orchestration state, keyed by session id.
  *
@@ -54,7 +55,19 @@ export class OrchestrationStore {
     }
     async save(id, state) {
         this.ensureTable();
-        const json = JSON.stringify(state);
+        const existing = await this.get(id);
+        const expected = state.version ?? 0;
+        if (existing) {
+            const stored = existing.version ?? 0;
+            if (stored !== expected) {
+                throw new StaleWriteError(id, expected, stored);
+            }
+        }
+        else if (expected !== 0) {
+            throw new StaleWriteError(id, expected, 0);
+        }
+        const toSave = { ...state, version: expected + 1 };
+        const json = JSON.stringify(toSave);
         this.sql `
       INSERT INTO kuralle_orchestration (id, state, updated_at)
       VALUES (${id}, ${json}, datetime('now'))

package/dist/SqlTraceStore.d.ts

@@ -0,0 +1,11 @@
+import type { AgentSpan, AgentTrace, TraceListWindow, TraceStore } from '@kuralle-agents/core';
+import type { SqlExecutor } from './types.js';
+export declare class SqlTraceStore implements TraceStore {
+    private readonly sql;
+    constructor(sql: SqlExecutor);
+    write(span: AgentSpan): void;
+    putSpan(span: AgentSpan): void;
+    getTrace(traceId: string): Promise<AgentTrace | null>;
+    listTraces(sessionId: string, window?: TraceListWindow): Promise<AgentTrace[]>;
+    cleanup(maxAgeMs: number): Promise<number>;
+}

package/dist/SqlTraceStore.js

@@ -0,0 +1,50 @@
+import { traceFromSpans } from '@kuralle-agents/core/tracing';
+export class SqlTraceStore {
+    sql;
+    constructor(sql) {
+        this.sql = sql;
+        this.sql `CREATE TABLE IF NOT EXISTS kuralle_trace_spans (
+      trace_id TEXT NOT NULL,
+      span_id TEXT NOT NULL,
+      session_id TEXT NOT NULL,
+      started_at INTEGER NOT NULL,
+      payload TEXT NOT NULL,
+      PRIMARY KEY (trace_id, span_id)
+    )`;
+        this.sql `CREATE INDEX IF NOT EXISTS kuralle_trace_session_started_idx
+      ON kuralle_trace_spans (session_id, started_at DESC)`;
+    }
+    write(span) { this.putSpan(span); }
+    putSpan(span) {
+        this.sql `INSERT INTO kuralle_trace_spans (trace_id, span_id, session_id, started_at, payload)
+      VALUES (${span.traceId}, ${span.spanId}, ${span.attributes.sessionId}, ${span.startTime}, ${JSON.stringify(span)})
+      ON CONFLICT(trace_id, span_id) DO UPDATE SET
+        session_id = excluded.session_id, started_at = excluded.started_at, payload = excluded.payload`;
+    }
+    async getTrace(traceId) {
+        const rows = this.sql `SELECT trace_id, payload FROM kuralle_trace_spans
+      WHERE trace_id = ${traceId} ORDER BY started_at ASC`;
+        return traceFromSpans(rows.map((row) => JSON.parse(row.payload)));
+    }
+    async listTraces(sessionId, window) {
+        const from = window?.from?.getTime() ?? 0;
+        const to = window?.to?.getTime() ?? Number.MAX_SAFE_INTEGER;
+        const limit = window?.limit ?? 100;
+        const rows = this.sql `SELECT trace_id, MIN(started_at) AS started_at
+      FROM kuralle_trace_spans WHERE session_id = ${sessionId}
+      GROUP BY trace_id HAVING MIN(started_at) >= ${from} AND MIN(started_at) <= ${to}
+      ORDER BY started_at DESC LIMIT ${limit}`;
+        const traces = await Promise.all(rows.map((row) => this.getTrace(row.trace_id)));
+        return traces.filter((trace) => trace !== null);
+    }
+    async cleanup(maxAgeMs) {
+        const cutoff = Date.now() - maxAgeMs;
+        const before = this.sql `SELECT COUNT(*) AS count FROM (
+      SELECT trace_id FROM kuralle_trace_spans GROUP BY trace_id HAVING MIN(started_at) < ${cutoff}
+    )`[0]?.count ?? 0;
+        this.sql `DELETE FROM kuralle_trace_spans WHERE trace_id IN (
+      SELECT trace_id FROM kuralle_trace_spans GROUP BY trace_id HAVING MIN(started_at) < ${cutoff}
+    )`;
+        return Number(before);
+    }
+}

package/dist/index.d.ts

@@ -27,6 +27,7 @@ export { KuralleAgent, KuralleAgent as CfChatAgent } from './KuralleAgent.js';
 export { BridgeSessionStore } from './BridgeSessionStore.js';
 export { OrchestrationStore } from './OrchestrationStore.js';
 export { SqlPersistentMemoryStore } from './SqlPersistentMemoryStore.js';
+export { SqlTraceStore } from './SqlTraceStore.js';
 export { createSqlExecutor } from './sqlExecutor.js';
 export { createSSEResponse } from './StreamAdapter.js';
 export { lastUserInputFromMessages } from './cfMessageInput.js';

package/dist/index.js

@@ -27,6 +27,7 @@ export { KuralleAgent, KuralleAgent as CfChatAgent } from './KuralleAgent.js';
 export { BridgeSessionStore } from './BridgeSessionStore.js';
 export { OrchestrationStore } from './OrchestrationStore.js';
 export { SqlPersistentMemoryStore } from './SqlPersistentMemoryStore.js';
+export { SqlTraceStore } from './SqlTraceStore.js';
 export { createSqlExecutor } from './sqlExecutor.js';
 export { createSSEResponse } from './StreamAdapter.js';
 export { lastUserInputFromMessages } from './cfMessageInput.js';

package/dist/types.d.ts

@@ -35,6 +35,8 @@ export interface OrchestrationState {
      * with "Run not found" on CF.
      */
     durableRuns?: SessionDurableRuns;
+    /** Optimistic-concurrency version for orchestration row CAS (C2). */
+    version?: number;
 }
 /**
  * Configuration for the stream adapter.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuralle-agents/cf-agent",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Kuralle agent integration for Cloudflare Workers with AIChatAgent",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,21 +21,22 @@
   "dependencies": {
     "@cloudflare/ai-chat": "^0.8.4",
     "ai": "^6.0.90",
-    "@kuralle-agents/core": "0.11.0",
-    "@kuralle-agents/messaging": "0.11.0",
-    "@kuralle-agents/realtime-audio": "0.11.0"
+    "@kuralle-agents/core": "0.13.0",
+    "@kuralle-agents/realtime-audio": "0.13.0",
+    "@kuralle-agents/messaging": "0.13.0"
   },
   "peerDependencies": {
     "agents": ">=0.14.0 <1.0.0",
     "zod": "^4.0.0",
-    "@kuralle-agents/voice-protocol": "0.11.0"
+    "@kuralle-agents/voice-protocol": "0.13.0"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.12.7",
+    "@cloudflare/workers-types": "^4.0.0",
     "agents": "^0.15.0",
     "typescript": "^5.7.0",
     "vitest": "^3.2.4",
-    "@kuralle-agents/voice-protocol": "0.11.0"
+    "@kuralle-agents/voice-protocol": "0.13.0"
   },
   "engines": {
     "node": ">=20"
@@ -53,7 +54,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
-    "directory": "packages/kuralle-cf-agent"
+    "directory": "packages/cf-agent"
   },
   "scripts": {
     "prebuild": "rm -rf dist",