@kuralle-syrinx/server-workers 2.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Kuralle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@kuralle-syrinx/server-workers",
+  "version": "2.1.0",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "main": "./src/worker.ts",
+  "types": "./src/worker.ts",
+  "dependencies": {
+    "@ai-sdk/openai": "^3.0.67",
+    "@kuralle-agents/core": "^0.8.5",
+    "@kuralle-agents/rag": "^0.8.5",
+    "@kuralle-agents/skills": "^0.8.5",
+    "@kuralle-agents/vectorize-store": "^0.8.5",
+    "ai": "^6.0.0",
+    "zod": "^4.1.8",
+    "@kuralle-syrinx/core": "2.1.0",
+    "@kuralle-syrinx/aisdk": "2.1.0",
+    "@kuralle-syrinx/server-websocket": "2.1.0",
+    "@kuralle-syrinx/ws": "2.1.0",
+    "@kuralle-syrinx/realtime": "2.1.0",
+    "@kuralle-syrinx/kuralle": "2.1.0",
+    "@kuralle-syrinx/cartesia": "2.1.0",
+    "@kuralle-syrinx/deepgram": "2.1.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20260601.0",
+    "esbuild": "^0.25.0",
+    "miniflare": "^4.20260601.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0",
+    "wrangler": "^4.19.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:live": "SYRINX_LIVE_WORKER_TEST=1 vitest run",
+    "verify:edge-bundle": "../../scripts/verify-edge-bundle.sh",
+    "wrangler:dry-run": "wrangler deploy --dry-run",
+    "deploy:realtime": "wrangler deploy -c wrangler.realtime.jsonc"
+  }
+}

package/src/alarm-scheduler.test.ts

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import { DurableObjectAlarmScheduler } from "./alarm-scheduler.js";
+import { MemoryDurableStorage } from "./test-storage.js";
+
+describe("DurableObjectAlarmScheduler", () => {
+  it("persists deadlines, fires due callbacks, and rearms the nearest remaining task", async () => {
+    const storage = new MemoryDurableStorage();
+    const scheduler = new DurableObjectAlarmScheduler(storage);
+    const fired: string[] = [];
+
+    scheduler.schedule("late", 1000, () => {
+      fired.push("late");
+    });
+    scheduler.schedule("soon", 50, () => {
+      fired.push("soon");
+    });
+
+    expect(storage.tasks.has("soon")).toBe(true);
+    expect(storage.alarm).toBeLessThanOrEqual(Date.now() + 1000);
+
+    await scheduler.runDue(Date.now() + 100);
+
+    expect(fired).toEqual(["soon"]);
+    expect(storage.tasks.has("soon")).toBe(false);
+    expect(storage.tasks.has("late")).toBe(true);
+  });
+
+  it("cancels persisted tasks before the alarm fires", async () => {
+    const storage = new MemoryDurableStorage();
+    const scheduler = new DurableObjectAlarmScheduler(storage);
+    let fired = false;
+
+    scheduler.schedule("task", 1, () => {
+      fired = true;
+    });
+    scheduler.cancel("task");
+    await scheduler.runDue(Date.now() + 10);
+
+    expect(fired).toBe(false);
+    expect(storage.tasks.size).toBe(0);
+  });
+});

package/src/alarm-scheduler.ts

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: MIT
+
+import type { ScheduledCallback, Scheduler } from "@kuralle-syrinx/core";
+
+type SqlCursor<T> = Iterable<T>;
+
+interface SqlStorage {
+  exec(query: string, ...bindings: unknown[]): SqlCursor<Record<string, unknown>>;
+}
+
+export interface DurableSchedulerStorage {
+  readonly sql: SqlStorage;
+  setAlarm(scheduledTime: number | Date): Promise<void>;
+  deleteAlarm(): Promise<void>;
+}
+
+export class DurableObjectAlarmScheduler implements Scheduler {
+  private readonly callbacks = new Map<string, ScheduledCallback>();
+
+  constructor(private readonly storage: DurableSchedulerStorage) {
+    this.storage.sql.exec(
+      "CREATE TABLE IF NOT EXISTS scheduled_tasks (key TEXT PRIMARY KEY, deadline_ms INTEGER NOT NULL)",
+    );
+  }
+
+  schedule(key: string, delayMs: number, cb: ScheduledCallback): void {
+    const deadlineMs = Date.now() + Math.max(0, delayMs);
+    this.callbacks.set(key, cb);
+    this.storage.sql.exec(
+      "INSERT OR REPLACE INTO scheduled_tasks (key, deadline_ms) VALUES (?, ?)",
+      key,
+      deadlineMs,
+    );
+    void this.armNext();
+  }
+
+  cancel(key: string): void {
+    this.callbacks.delete(key);
+    this.storage.sql.exec("DELETE FROM scheduled_tasks WHERE key = ?", key);
+    void this.armNext();
+  }
+
+  async runDue(nowMs = Date.now()): Promise<void> {
+    const due = [...this.storage.sql.exec(
+      "SELECT key FROM scheduled_tasks WHERE deadline_ms <= ? ORDER BY deadline_ms ASC",
+      nowMs,
+    )] as Array<{ key: string }>;
+    for (const row of due) {
+      this.storage.sql.exec("DELETE FROM scheduled_tasks WHERE key = ?", row.key);
+      const cb = this.callbacks.get(row.key);
+      this.callbacks.delete(row.key);
+      if (cb) await cb();
+    }
+    await this.armNext();
+  }
+
+  private async armNext(): Promise<void> {
+    const [next] = [...this.storage.sql.exec(
+      "SELECT deadline_ms FROM scheduled_tasks ORDER BY deadline_ms ASC LIMIT 1",
+    )] as Array<{ deadline_ms: number }>;
+    if (!next) {
+      await this.storage.deleteAlarm();
+      return;
+    }
+    await this.storage.setAlarm(next.deadline_ms);
+  }
+}

package/src/durable-session-store.test.ts

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import type { ManagedSession } from "@kuralle-syrinx/server-websocket/session-store";
+import { DurableObjectAlarmScheduler } from "./alarm-scheduler.js";
+import { DurableObjectSessionStore } from "./durable-session-store.js";
+import { MemoryDurableStorage } from "./test-storage.js";
+
+describe("DurableObjectSessionStore", () => {
+  it("persists turn metadata and restores it when the live session is recreated", async () => {
+    const storage = new MemoryDurableStorage();
+    const scheduler = new DurableObjectAlarmScheduler(storage);
+    const store = new DurableObjectSessionStore(storage, scheduler);
+
+    const first = await store.lease("s1", async () => managed("s1", "turn-a"));
+    store.update("s1", (stored) => {
+      stored.currentContextId = "turn-b";
+      stored.inputSequence.lastSequence = 7;
+    });
+    first.managed.connectionCount = 0;
+    await store.release("s1", 1000);
+
+    const recreatedStore = new DurableObjectSessionStore(storage, scheduler);
+    const second = await recreatedStore.lease("s1", async () => managed("s1", "fresh"));
+
+    expect(second.resumed).toBe(true);
+    expect(second.managed.currentContextId).toBe("turn-b");
+    expect(second.managed.inputSequence.lastSequence).toBe(7);
+  });
+
+  it("deletes retained sessions when the scheduled release fires", async () => {
+    const storage = new MemoryDurableStorage();
+    const scheduler = new DurableObjectAlarmScheduler(storage);
+    const store = new DurableObjectSessionStore(storage, scheduler);
+    const leased = await store.lease("s2", async () => managed("s2", "turn-a"));
+    leased.managed.connectionCount = 0;
+
+    await store.release("s2", 5);
+    await scheduler.runDue(Date.now() + 10);
+
+    expect(await store.get("s2")).toBeNull();
+    expect(storage.sessions.has("s2")).toBe(false);
+  });
+});
+
+function managed(id: string, currentContextId: string): ManagedSession {
+  return {
+    id,
+    session: {
+      start: async () => undefined,
+      close: async () => undefined,
+    } as ManagedSession["session"],
+    currentContextId,
+    contextSampleRates: new Map(),
+    inputSequence: { lastSequence: null },
+    turnMetricsTurns: new Map(),
+    closeTimer: null,
+    connectionCount: 0,
+  };
+}

package/src/durable-session-store.ts

@@ -0,0 +1,148 @@
+// SPDX-License-Identifier: MIT
+
+import type {
+  ManagedSession,
+  ManagedSessionLease,
+  SessionStore,
+} from "@kuralle-syrinx/server-websocket/session-store";
+import type { DurableObjectAlarmScheduler } from "./alarm-scheduler.js";
+
+type SqlCursor<T> = Iterable<T>;
+
+interface SqlStorage {
+  exec(query: string, ...bindings: unknown[]): SqlCursor<Record<string, unknown>>;
+}
+
+export interface DurableSessionStorage {
+  readonly sql: SqlStorage;
+}
+
+interface SessionRow {
+  id: string;
+  current_context_id: string;
+  last_sequence: number | null;
+  retained_until_ms: number;
+  connection_count: number;
+}
+
+export class DurableObjectSessionStore implements SessionStore {
+  private readonly sessions = new Map<string, ManagedSession>();
+  private readonly pendingLeases = new Map<string, Promise<ManagedSession>>();
+
+  constructor(
+    private readonly storage: DurableSessionStorage,
+    private readonly scheduler: DurableObjectAlarmScheduler,
+  ) {
+    this.storage.sql.exec(
+      `CREATE TABLE IF NOT EXISTS sessions (
+        id TEXT PRIMARY KEY,
+        current_context_id TEXT NOT NULL,
+        last_sequence INTEGER,
+        retained_until_ms INTEGER NOT NULL DEFAULT 0,
+        connection_count INTEGER NOT NULL DEFAULT 0,
+        updated_at_ms INTEGER NOT NULL
+      )`,
+    );
+  }
+
+  async lease(sessionId: string, create: () => Promise<ManagedSession>): Promise<ManagedSessionLease> {
+    const existing = this.sessions.get(sessionId);
+    if (existing) {
+      this.attachConnection(existing);
+      return { managed: existing, resumed: true };
+    }
+
+    let pending = this.pendingLeases.get(sessionId);
+    if (!pending) {
+      pending = create().then((managed) => {
+        const row = this.row(sessionId);
+        if (row) {
+          managed.currentContextId = row.current_context_id;
+          managed.inputSequence.lastSequence = row.last_sequence;
+        }
+        this.sessions.set(sessionId, managed);
+        this.persist(managed, 0);
+        return managed;
+      }).finally(() => {
+        this.pendingLeases.delete(sessionId);
+      });
+      this.pendingLeases.set(sessionId, pending);
+    }
+
+    const row = this.row(sessionId);
+    const managed = await pending;
+    this.attachConnection(managed);
+    return { managed, resumed: Boolean(row && row.retained_until_ms > Date.now()) };
+  }
+
+  async release(sessionId: string, retainMs: number): Promise<void> {
+    const managed = this.sessions.get(sessionId);
+    if (!managed) return;
+    if (managed.connectionCount > 0) return;
+
+    if (retainMs <= 0) {
+      this.sessions.delete(sessionId);
+      this.storage.sql.exec("DELETE FROM sessions WHERE id = ?", sessionId);
+      await managed.session.close().catch(() => undefined);
+      return;
+    }
+
+    const retainedUntilMs = Date.now() + retainMs;
+    this.persist(managed, retainedUntilMs);
+    this.scheduler.schedule(`session.retain:${sessionId}`, retainMs, async () => {
+      const current = this.sessions.get(sessionId);
+      if (!current || current.connectionCount > 0) return;
+      this.sessions.delete(sessionId);
+      this.storage.sql.exec("DELETE FROM sessions WHERE id = ?", sessionId);
+      await current.session.close().catch(() => undefined);
+    });
+  }
+
+  update(sessionId: string, mutate: (managed: ManagedSession) => void): void {
+    const managed = this.sessions.get(sessionId);
+    if (!managed) return;
+    mutate(managed);
+    this.persist(managed, 0);
+  }
+
+  async get(sessionId: string): Promise<ManagedSession | null> {
+    return this.sessions.get(sessionId) ?? null;
+  }
+
+  async listAll(): Promise<readonly ManagedSession[]> {
+    return [...this.sessions.values()];
+  }
+
+  async clear(): Promise<void> {
+    for (const managed of this.sessions.values()) {
+      await managed.session.close().catch(() => undefined);
+    }
+    this.sessions.clear();
+    this.storage.sql.exec("DELETE FROM sessions");
+  }
+
+  private attachConnection(managed: ManagedSession): void {
+    this.scheduler.cancel(`session.retain:${managed.id}`);
+    managed.connectionCount += 1;
+    this.persist(managed, 0);
+  }
+
+  private persist(managed: ManagedSession, retainedUntilMs: number): void {
+    this.storage.sql.exec(
+      `INSERT OR REPLACE INTO sessions
+        (id, current_context_id, last_sequence, retained_until_ms, connection_count, updated_at_ms)
+        VALUES (?, ?, ?, ?, ?, ?)`,
+      managed.id,
+      managed.currentContextId,
+      managed.inputSequence.lastSequence,
+      retainedUntilMs,
+      managed.connectionCount,
+      Date.now(),
+    );
+  }
+
+  private row(sessionId: string): SessionRow | null {
+    const [row] = [...this.storage.sql.exec("SELECT * FROM sessions WHERE id = ?", sessionId)] as unknown as SessionRow[];
+    return row ?? null;
+  }
+}

package/src/kuralle-realtime-agent.ts

@@ -0,0 +1,211 @@
+// SPDX-License-Identifier: MIT
+
+import { createOpenAI } from "@ai-sdk/openai";
+import {
+  defineAgent,
+  defineFlow,
+  defineTool,
+  buildToolSet,
+  createRuntime,
+  MemoryStore,
+  reply,
+  type Runtime,
+} from "@kuralle-agents/core";
+import {
+  AiSdkEmbedder,
+  VectorRetriever,
+  type VectorStoreCore,
+} from "@kuralle-agents/rag";
+import { defineSkill } from "@kuralle-agents/skills";
+import { CloudflareVectorizeStore, type VectorizeBinding } from "@kuralle-agents/vectorize-store";
+import type { VectorizeIndex } from "@cloudflare/workers-types";
+import { fromKuralleRuntime, type KuralleRuntimeLike } from "@kuralle-syrinx/kuralle";
+import type { Reasoner } from "@kuralle-syrinx/core";
+import { z } from "zod";
+
+const DEFAULT_MODEL = "gpt-4.1-mini";
+const INDEX_NAME = "kuralle-university-kb";
+
+const SCHOLARSHIP_SKILL = defineSkill({
+  name: "scholarship-guidance",
+  description: "Guide students through scholarship eligibility and application steps",
+  body: `# Scholarship Guidance
+
+1. Ask whether the student is seeking merit-based aid, need-based aid, or both.
+2. For merit: cite the Dean's Merit Scholarship (GPA ≥ 3.5).
+3. For need: cite the Need-Based Grant (FAFSA required).
+4. Always mention the application deadline of February 15.`,
+  allowedTools: [],
+});
+
+let bookingCounter = 0;
+
+const createBookingTool = defineTool({
+  name: "create_booking",
+  description: "Finalize the advisor appointment booking. Only call after the user has explicitly confirmed the details.",
+  input: z.object({}),
+  execute: async () => {
+    bookingCounter += 1;
+    return { bookingRef: `ADV-${bookingCounter}` };
+  },
+});
+
+const recordBookingDetails = defineTool({
+  name: "record_booking_details",
+  description: "Record the student's name, program, and preferred date once all three are known.",
+  input: z.object({ name: z.string(), program: z.string(), preferredDate: z.string() }),
+  execute: async (details) => details,
+});
+
+const requestTranscriptTool = defineTool({
+  name: "request_transcript",
+  description: "Submit an official transcript request for the given studentId.",
+  input: z.object({ studentId: z.string() }),
+  execute: async ({ studentId }) => ({ requestRef: `TR-${studentId}` }),
+});
+
+const replyBooked = reply({
+  id: "reply-booked",
+  grounding: { knowledge: { autoRetrieve: false } },
+  instructions: ({ state }) =>
+    `The advisor appointment is booked. Confirm it to the user and include this exact reference verbatim: ${String(state["bookingRef"] ?? "")}.`,
+  next: () => ({ end: "booked" }),
+});
+
+const confirmBooking = reply({
+  id: "confirm-booking",
+  grounding: { knowledge: { autoRetrieve: false } },
+  instructions: ({ state }) =>
+    `Summarize the advisor appointment — name: ${String(state["name"] ?? "")}, program: ${String(state["program"] ?? "")}, date: ${String(state["preferredDate"] ?? "")} — and ask the user to confirm. ONLY when the user clearly confirms, call create_booking to finalize. If they want changes, ask for the corrected detail.`,
+  tools: buildToolSet({ create_booking: createBookingTool }),
+  next: (turn) => {
+    const r = turn.toolResults.find((t) => t.name === "create_booking");
+    if (r?.result && typeof r.result === "object") return { goto: replyBooked, data: r.result as Record<string, unknown> };
+    return "stay";
+  },
+});
+
+const collectBooking = reply({
+  id: "collect-booking",
+  grounding: { knowledge: { autoRetrieve: false } },
+  instructions:
+    "Help the user book an advisor appointment. If you don't yet have all three of name, program, and preferred date, ask for the missing ones. Once you have all three, call record_booking_details.",
+  tools: buildToolSet({ record_booking_details: recordBookingDetails }),
+  next: (turn) => {
+    const r = turn.toolResults.find((t) => t.name === "record_booking_details");
+    if (r?.result && typeof r.result === "object") return { goto: confirmBooking, data: r.result as Record<string, unknown> };
+    return "stay";
+  },
+});
+
+const bookingFlow = defineFlow({
+  name: "book-advisor-appointment",
+  description: "Book an appointment with an academic advisor",
+  start: collectBooking,
+  nodes: [collectBooking, confirmBooking, replyBooked],
+});
+
+const replyTranscript = reply({
+  id: "reply-transcript",
+  grounding: { knowledge: { autoRetrieve: false } },
+  instructions: ({ state }) =>
+    `Confirm the transcript request was submitted. Include this exact request reference verbatim: ${String(state["requestRef"] ?? "")}.`,
+  next: () => ({ end: "requested" }),
+});
+
+const collectTranscript = reply({
+  id: "collect-transcript",
+  grounding: { knowledge: { autoRetrieve: false } },
+  instructions:
+    "Help the user request an official transcript. If you don't have their student ID, ask for it. Once you have it, call request_transcript with that studentId.",
+  tools: buildToolSet({ request_transcript: requestTranscriptTool }),
+  next: (turn) => {
+    const r = turn.toolResults.find((t) => t.name === "request_transcript");
+    if (r?.result && typeof r.result === "object") return { goto: replyTranscript, data: r.result as Record<string, unknown> };
+    return "stay";
+  },
+});
+
+const transcriptFlow = defineFlow({
+  name: "request-transcript",
+  description: "Request an official academic transcript",
+  start: collectTranscript,
+  nodes: [collectTranscript, replyTranscript],
+});
+
+export interface KuralleRealtimeEnv {
+  readonly OPENAI_API_KEY?: string;
+  readonly OPENAI_MODEL?: string;
+  readonly VECTORIZE: VectorizeIndex;
+}
+
+export interface CreateRealtimeKuralleReasonerOptions {
+  readonly sessionId: string;
+  readonly userId?: string;
+}
+
+let runtimePromise: Promise<Runtime> | undefined;
+
+function vectorStore(env: KuralleRealtimeEnv): VectorStoreCore {
+  return new CloudflareVectorizeStore({ binding: env.VECTORIZE as unknown as VectorizeBinding });
+}
+
+async function createUniversityRuntime(env: KuralleRealtimeEnv): Promise<Runtime> {
+  const apiKey = requireKey(env.OPENAI_API_KEY, "OPENAI_API_KEY");
+  const openai = createOpenAI({ apiKey });
+  const model = openai(env.OPENAI_MODEL?.trim() || DEFAULT_MODEL);
+  const embedder = new AiSdkEmbedder({ model: openai.embedding("text-embedding-3-small") });
+  const retriever = new VectorRetriever({
+    vectorStore: vectorStore(env),
+    embedder,
+    indexName: INDEX_NAME,
+    topK: 3,
+  });
+
+  const agent = defineAgent({
+    id: "university",
+    model,
+    instructions:
+      "You are a friendly university support assistant. Answer admissions, program, tuition, and scholarship questions clearly and concisely for voice.",
+    knowledge: { autoRetrieve: true },
+    skills: [SCHOLARSHIP_SKILL],
+    flows: [bookingFlow, transcriptFlow],
+    tools: {
+      create_booking: createBookingTool,
+      request_transcript: requestTranscriptTool,
+    },
+    memory: { workingMemory: { autoLoad: [{ scope: "user", key: "USER" }] } },
+  });
+
+  return createRuntime({
+    agents: [agent],
+    defaultAgentId: "university",
+    sessionStore: new MemoryStore(),
+    knowledge: { retriever, embedder },
+  });
+}
+
+function getRuntime(env: KuralleRealtimeEnv): Promise<Runtime> {
+  return (runtimePromise ??= createUniversityRuntime(env));
+}
+
+export async function createRealtimeKuralleReasoner(
+  env: KuralleRealtimeEnv,
+  opts: CreateRealtimeKuralleReasonerOptions,
+): Promise<Reasoner> {
+  const runtime = await getRuntime(env);
+  return fromKuralleRuntime(runtime as unknown as KuralleRuntimeLike, {
+    sessionId: opts.sessionId,
+    userId: opts.userId ?? "voice",
+  });
+}
+
+export type KuralleCascadeEnv = KuralleRealtimeEnv;
+export type CreateCascadeKuralleReasonerOptions = CreateRealtimeKuralleReasonerOptions;
+export const createCascadeKuralleReasoner = createRealtimeKuralleReasoner;
+
+function requireKey(value: string | undefined, name: string): string {
+  const trimmed = value?.trim();
+  if (!trimmed) throw new Error(`${name} is required to start a realtime voice session`);
+  return trimmed;
+}