@kuralle-syrinx/kuralle 4.2.0 → 4.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuralle-syrinx/kuralle",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "private": false,
   "description": "kuralle-agents bridge for Syrinx — run a kuralle runtime as the voice pipeline's reasoner",
   "keywords": [
@@ -24,15 +24,15 @@
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "dependencies": {
-    "@kuralle-syrinx/core": "4.2.0"
+    "@kuralle-syrinx/core": "4.3.0"
   },
   "peerDependencies": {
-    "@kuralle-agents/core": ">=0.8.0"
+    "@kuralle-agents/core": ">=0.13.0 <1"
   },
   "devDependencies": {
-    "@kuralle-agents/core": "^0.8.5",
+    "@kuralle-agents/core": "^0.13.0",
     "typescript": "^5.7.0",
-    "vitest": "^2.1.0"
+    "vitest": "^3.2.6"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/from-kuralle.ts

@@ -4,6 +4,7 @@ import type { Reasoner, ReasonerTurn, ReasoningPart } from "@kuralle-syrinx/core
 import { categorizeLlmError, isRecoverable } from "@kuralle-syrinx/core";
 
 export interface KuralleStreamPart {
+  readonly [key: string]: unknown;
   readonly type: string;
   readonly delta?: string;
   readonly toolName?: string;
@@ -16,6 +17,8 @@ export interface KuralleStreamPart {
   readonly options?: unknown;
   readonly prompt?: string;
   readonly sessionId?: string;
+  readonly userFacingMessage?: string;
+  readonly payload?: unknown;
 }
 
 export interface KuralleMessageLike {
@@ -26,7 +29,18 @@ export interface KuralleMessageLike {
 export interface KuralleStoredSession {
   readonly id: string;
   messages: KuralleMessageLike[];
-  [key: string]: unknown;
+  /**
+   * Durable-run bookkeeping the bridge reads for flow-resume. Optional and unknown-typed
+   * because kuralle owns its shape.
+   *
+   * This was a `[key: string]: unknown` catch-all, which made the interface unsatisfiable
+   * by any concrete type: a real `Session` has no index signature, so it could never be
+   * assigned here. Nothing caught that, because nothing type-checked the bridge against
+   * the real Runtime — see `real-runtime.compile-check.ts`. Only this one key is read.
+   */
+  durableRuns?: unknown;
+  /** Working-memory blob the bridge inspects on resume. Kuralle owns its shape. */
+  workingMemory?: unknown;
 }
 
 export interface KuralleSessionStoreLike {
@@ -45,9 +59,32 @@ export interface KuralleRunOptions {
   readonly userId?: string;
   readonly agentId?: string;
   readonly abortSignal?: AbortSignal;
-  readonly historyDelta?: ReadonlyArray<{ readonly role: string; readonly content: string }>;
+  /**
+   * Prior turns seeded into an empty kuralle session (G4 resume-by-seed).
+   *
+   * Deliberately narrower than it looks: the real `Runtime.run` takes `ModelMessage[]`,
+   * whose `role` is a union, so a `string` role here would be too wide to assign — and a
+   * mutable array, so `ReadonlyArray` would not assign either. The producer
+   * (`buildHistoryDeltaSeed`) already filters to user/assistant, so this only makes the
+   * declaration honest about what the code was doing.
+   *
+   * `real-runtime.compile-check.ts` pins this against the actual Runtime type.
+   */
+  historyDelta?: Array<{ role: "user" | "assistant"; content: string }>;
 }
 
+/**
+ * The slice of kuralle's `Runtime` this bridge calls, as a loose structural shape.
+ *
+ * Deliberately hand-written rather than `Pick<Runtime, ...>`. Deriving was tried and is
+ * strictly worse here: it drags in `TurnHandle`, `HarnessStreamPart`, `Session` and
+ * `RunOptions` wholesale, so every test fake and adapter would have to construct
+ * full-fidelity kuralle objects to call a bridge whose whole point is loose coupling.
+ *
+ * The drift that freedom costs is contained by `real-runtime.compile-check.ts`, which
+ * asserts the REAL `Runtime` still satisfies this shape. That check is what was missing —
+ * not stricter types. It is the same pattern `cf-agents` uses for the agents SDK.
+ */
 export interface KuralleRuntimeLike {
   run(opts: KuralleRunOptions): KuralleTurnHandle;
   getSession?(sessionId: string): Promise<KuralleStoredSession | null>;
@@ -101,7 +138,10 @@ function seedHistoryDelta(
 ): Pick<KuralleRunOptions, "historyDelta"> | Record<string, never> {
   if (session && session.messages.length > 0) return {};
   const delta = messages
-    .filter((message) => message.role === "user" || message.role === "assistant")
+    .filter(
+      (message): message is typeof message & { role: "user" | "assistant" } =>
+        message.role === "user" || message.role === "assistant",
+    )
     .map((message) => ({ role: message.role, content: message.content }));
   return delta.length > 0 ? { historyDelta: delta } : {};
 }
@@ -243,10 +283,18 @@ export async function* streamFromKuralle(
             payload: part,
           };
           return;
+        case "safety-blocked":
+          yield {
+            type: "blocked",
+            userFacingMessage: String(part.userFacingMessage ?? "This request cannot be completed."),
+            payload: part,
+          };
+          return;
         case "done":
           yield { type: "finish", reason: "stop", text: acc };
           return;
         default:
+          yield { type: "control", name: part.type, payload: part };
           break;
       }
       if (aborted) break;

package/src/real-runtime.compile-check.ts

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: MIT
+//
+// Compile-only proof that the REAL `@kuralle-agents/core` Runtime satisfies the
+// structural `KuralleRuntimeLike` this bridge consumes. Type-checked by
+// `tsc --noEmit`; never executed.
+//
+// Why this file exists: the bridge deliberately types against a structural interface
+// rather than importing kuralle's types, so a consumer can supply any runtime-shaped
+// object. The cost of that freedom is that nothing was verifying the real Runtime
+// still fits — the package pinned `^0.8.5` in devDeps while npm shipped 0.13.0, five
+// minors and a package-folder rename later, and no check would have failed. If kuralle
+// changes `run` / `getSession` / `getSessionStore`, this file stops compiling.
+//
+// Mirrors the same pattern as `packages/cf-agents/src/real-agent.compile-check.ts`.
+
+import type { HarnessStreamPart, Runtime } from "@kuralle-agents/core";
+import { fromKuralleRuntime, type KuralleRuntimeLike } from "./from-kuralle.js";
+
+// The three surfaces the bridge actually calls. If the real Runtime drifts from any
+// of them, this assignment fails to type-check.
+declare const realRuntime: Runtime;
+const asBridgeRuntime: KuralleRuntimeLike = realRuntime;
+
+// And the real thing composes into the seam the voice pipeline consumes.
+export const reasonerFromRealRuntime = fromKuralleRuntime(asBridgeRuntime, {
+  sessionId: "compile-check-session",
+});
+
+// ---------------------------------------------------------------------------
+// Part-type literals
+// ---------------------------------------------------------------------------
+//
+// `KuralleStreamPart.type` is `string`, so `streamFromKuralle`'s switch is matching
+// bare string literals with nothing pinning them to reality. The shape check above
+// would stay green if kuralle renamed `"done"` to `"finish"` — and the bridge treats a
+// missing `done` as "stream ended without a done part", i.e. EVERY turn would fail with
+// a terminal error while the type system reported no problem.
+//
+// kuralle exports `HarnessStreamPart` as a discriminated union of literal types, so the
+// switch cases can be pinned at compile time. Keep this list in sync with the `case`
+// arms in `streamFromKuralle`; if upstream renames or drops one, this stops compiling.
+
+/** Exactly the part types handled by explicit `streamFromKuralle` case arms. */
+type BridgedPartType =
+  | "text-delta"
+  | "tool-call"
+  | "tool-result"
+  | "error"
+  | "paused"
+  | "interactive"
+  | "safety-blocked"
+  | "done";
+
+type _AssertTrue<T extends true> = T;
+type _BridgedPartTypesStillExistUpstream = _AssertTrue<
+  BridgedPartType extends HarnessStreamPart["type"] ? true : false
+>;

package/src/from-kuralle.test.ts

@@ -1,350 +0,0 @@
-// SPDX-License-Identifier: MIT
-
-import { describe, expect, it } from "vitest";
-import type { Reasoner, ReasonerTurn, ReasoningPart } from "@kuralle-syrinx/core";
-import {
-  buildKuralleTurnRunOptions,
-  fromKuralleRuntime,
-  reconcileSpokenPrefix,
-  rewriteLastAssistant,
-  type KuralleMessageLike,
-  type KuralleRunOptions,
-  type KuralleRuntimeLike,
-  type KuralleSessionStoreLike,
-  type KuralleStoredSession,
-  type KuralleStreamPart,
-} from "./from-kuralle.js";
-
-function baseTurn(): ReasonerTurn {
-  return {
-    userText: "Hi",
-    messages: [{ role: "system", content: "test" }],
-    signal: new AbortController().signal,
-  };
-}
-
-function textDelta(delta: string): KuralleStreamPart {
-  return { type: "text-delta", delta };
-}
-
-function toolCall(toolCallId: string, toolName: string, args: Record<string, unknown>): KuralleStreamPart {
-  return { type: "tool-call", toolCallId, toolName, args };
-}
-
-function toolResult(toolCallId: string, toolName: string, result: unknown): KuralleStreamPart {
-  return { type: "tool-result", toolCallId, toolName, result };
-}
-
-function errorPart(error: string): KuralleStreamPart {
-  return { type: "error", error };
-}
-
-function done(sessionId?: string): KuralleStreamPart {
-  return { type: "done", sessionId };
-}
-
-async function* partsToEvents(parts: KuralleStreamPart[]): AsyncIterable<KuralleStreamPart> {
-  for (const p of parts) yield p;
-}
-
-function fakeRuntime(
-  parts: KuralleStreamPart[],
-  spy?: {
-    runOpts?: {
-      input?: string;
-      sessionId?: string;
-      userId?: string;
-      agentId?: string;
-      abortSignal?: AbortSignal;
-    };
-  },
-): KuralleRuntimeLike {
-  return {
-    run(opts) {
-      if (spy) spy.runOpts = opts;
-      return { events: partsToEvents(parts) };
-    },
-  };
-}
-
-async function collectParts(reasoner: Reasoner, turn: ReasonerTurn): Promise<ReasoningPart[]> {
-  const collected: ReasoningPart[] = [];
-  for await (const part of reasoner.stream(turn)) {
-    collected.push(part);
-  }
-  return collected;
-}
-
-describe("fromKuralleRuntime G4 resume-by-seed (historyDelta)", () => {
-  const turnWithContext = (): ReasonerTurn => ({
-    userText: "Second question",
-    messages: [
-      { role: "system", content: "sys" },
-      { role: "user", content: "First question" },
-      { role: "assistant", content: "First answer" },
-    ],
-    signal: new AbortController().signal,
-  });
-
-  it("seeds prior turn.messages into an EMPTY kuralle session (fresh isolate resume)", async () => {
-    const spy: { runOpts?: KuralleRunOptions } = {};
-    const runtime: KuralleRuntimeLike = {
-      run(opts) {
-        spy.runOpts = opts;
-        return { events: partsToEvents([textDelta("ok"), done()]) };
-      },
-      getSession: async () => null,
-    };
-    const reasoner = fromKuralleRuntime(runtime, { sessionId: "sess-1" });
-
-    await collectParts(reasoner, turnWithContext());
-
-    expect(spy.runOpts?.input).toBe("Second question");
-    expect(spy.runOpts?.historyDelta).toEqual([
-      { role: "user", content: "First question" },
-      { role: "assistant", content: "First answer" },
-    ]);
-  });
-
-  it("does NOT seed into a non-empty session (no double-applied history, R6)", async () => {
-    const spy: { runOpts?: KuralleRunOptions } = {};
-    const runtime: KuralleRuntimeLike = {
-      run(opts) {
-        spy.runOpts = opts;
-        return { events: partsToEvents([textDelta("ok"), done()]) };
-      },
-      getSession: async () => ({
-        id: "sess-1",
-        messages: [{ role: "user", content: "already there" }],
-      }),
-    };
-    const reasoner = fromKuralleRuntime(runtime, { sessionId: "sess-1" });
-
-    await collectParts(reasoner, turnWithContext());
-
-    expect(spy.runOpts?.input).toBe("Second question");
-    expect(spy.runOpts?.historyDelta).toBeUndefined();
-  });
-});
-
-describe("fromKuralleRuntime", () => {
-  it("maps happy path: text deltas and done to finish:stop", async () => {
-    const reasoner = fromKuralleRuntime(
-      fakeRuntime([textDelta("Hi"), textDelta(" there"), done("sess-1")]),
-      { sessionId: "sess-1" },
-    );
-
-    const parts = await collectParts(reasoner, baseTurn());
-
-    expect(parts).toEqual([
-      { type: "text-delta", text: "Hi" },
-      { type: "text-delta", text: " there" },
-      { type: "finish", reason: "stop", text: "Hi there" },
-    ]);
-  });
-
-  it("maps tool-call and tool-result with toolId from toolCallId", async () => {
-    const reasoner = fromKuralleRuntime(
-      fakeRuntime([
-        toolCall("tc-1", "lookup", { id: "123" }),
-        toolResult("tc-1", "lookup", { found: true }),
-        done(),
-      ]),
-      { sessionId: "sess-1" },
-    );
-
-    const parts = await collectParts(reasoner, baseTurn());
-
-    expect(parts).toEqual([
-      {
-        type: "tool-call",
-        toolId: "tc-1",
-        toolName: "lookup",
-        args: { id: "123" },
-      },
-      {
-        type: "tool-result",
-        toolId: "tc-1",
-        toolName: "lookup",
-        result: JSON.stringify({ found: true }),
-      },
-      { type: "finish", reason: "stop", text: "" },
-    ]);
-  });
-
-  it("maps error part to terminal error", async () => {
-    const reasoner = fromKuralleRuntime(fakeRuntime([errorPart("boom")]), { sessionId: "sess-1" });
-
-    const parts = await collectParts(reasoner, baseTurn());
-
-    expect(parts).toHaveLength(1);
-    expect(parts[0]?.type).toBe("error");
-    if (parts[0]?.type === "error") {
-      expect(parts[0].cause.message).toBe("boom");
-      expect(parts[0].recoverable).toBe(false);
-    }
-  });
-
-  it("yields terminal error when stream ends without done", async () => {
-    const reasoner = fromKuralleRuntime(fakeRuntime([textDelta("partial")]), { sessionId: "sess-1" });
-
-    const parts = await collectParts(reasoner, baseTurn());
-
-    expect(parts).toHaveLength(2);
-    expect(parts[0]).toEqual({ type: "text-delta", text: "partial" });
-    expect(parts[1]?.type).toBe("error");
-    if (parts[1]?.type === "error") {
-      expect(parts[1].cause.message).toBe("Kuralle stream ended without a done part");
-      expect(parts[1].recoverable).toBe(false);
-    }
-  });
-
-  it("returns without yielding when turn.signal is already aborted", async () => {
-    const controller = new AbortController();
-    controller.abort();
-    const turn: ReasonerTurn = { ...baseTurn(), signal: controller.signal };
-
-    const reasoner = fromKuralleRuntime(
-      fakeRuntime([textDelta("should not appear"), done()]),
-      { sessionId: "sess-1" },
-    );
-
-    const parts = await collectParts(reasoner, turn);
-
-    expect(parts).toEqual([]);
-  });
-
-  it("passes only userText to run, not turn.messages", async () => {
-    const spy: { runOpts?: { input?: string; sessionId?: string } } = {};
-    const reasoner = fromKuralleRuntime(fakeRuntime([done()], spy), { sessionId: "sess-42" });
-
-    const turn: ReasonerTurn = {
-      userText: "What is my name?",
-      messages: [
-        { role: "system", content: "ignored" },
-        { role: "user", content: "also ignored" },
-      ],
-      signal: new AbortController().signal,
-    };
-    await collectParts(reasoner, turn);
-
-    expect(spy.runOpts?.input).toBe("What is my name?");
-    expect(spy.runOpts?.sessionId).toBe("sess-42");
-  });
-
-  it("flow resume pre-appends user message and omits input", async () => {
-    const sessionId = "sess-flow";
-    const store = createMockSessionStore(sessionId, [{ role: "assistant", content: "What is your name?" }]);
-    const session = (await store.get(sessionId))!;
-    session.durableRuns = {
-      [sessionId]: {
-        runState: {
-          activeFlow: "book-advisor-appointment",
-          messages: [{ role: "assistant", content: "What is your name?" }],
-        },
-        steps: [],
-      },
-    };
-    await store.save(session);
-
-    const runtime: KuralleRuntimeLike = {
-      run: () => ({ events: partsToEvents([done()]) }),
-      getSession: (id) => store.get(id),
-      getSessionStore: () => store,
-    };
-
-    const opts = await buildKuralleTurnRunOptions(runtime, {
-      sessionId,
-      userText: "Priya, CS masters, Friday",
-    });
-
-    expect(opts.input).toBeUndefined();
-    expect(opts.historyDelta).toBeUndefined();
-    const saved = await store.get(sessionId);
-    expect(saved?.messages.at(-1)).toEqual({ role: "user", content: "Priya, CS masters, Friday" });
-    const runMessages = (
-      saved?.durableRuns as Record<string, { runState: { messages: KuralleMessageLike[] } }>
-    )[sessionId]?.runState.messages;
-    expect(runMessages?.at(-1)).toEqual({ role: "user", content: "Priya, CS masters, Friday" });
-  });
-
-  it("rewriteLastAssistant truncates only when spoken prefix is shorter", () => {
-    const messages: KuralleMessageLike[] = [
-      { role: "user", content: "Hi" },
-      { role: "assistant", content: "Hello there friend" },
-    ];
-    expect(rewriteLastAssistant(messages, "Hello")).toEqual([
-      { role: "user", content: "Hi" },
-      { role: "assistant", content: "Hello" },
-    ]);
-    expect(rewriteLastAssistant(messages, "Hello there friend")).toStrictEqual(messages);
-  });
-
-  it("after barge-in abort, reconciles persisted assistant message to spoken prefix", async () => {
-    const fullText = "Hello there friend";
-    const spokenPrefix = "Hello";
-    const sessionId = "sess-barge";
-    const store = createMockSessionStore(sessionId, []);
-
-    await reconcileSpokenPrefix(
-      { run: () => ({ events: partsToEvents([]) }), getSessionStore: () => store },
-      sessionId,
-      spokenPrefix,
-    );
-    let session = await store.get(sessionId);
-    expect(session?.messages).toEqual([]);
-
-    session = (await store.get(sessionId)) ?? { id: sessionId, messages: [] };
-    session.messages = [{ role: "assistant", content: fullText }];
-    await store.save(session);
-
-    await reconcileSpokenPrefix(
-      { run: () => ({ events: partsToEvents([]) }), getSessionStore: () => store },
-      sessionId,
-      spokenPrefix,
-    );
-    session = await store.get(sessionId);
-    expect(session?.messages.at(-1)).toEqual({ role: "assistant", content: spokenPrefix });
-  });
-
-  it("reconcileSpokenPrefix rewrites durable run messages", async () => {
-    const sessionId = "sess-durable";
-    const store = createMockSessionStore(sessionId, []);
-    const session = (await store.get(sessionId))!;
-    session.messages = [{ role: "assistant", content: "full reply text" }];
-    session.durableRuns = {
-      [sessionId]: {
-        runState: { messages: [{ role: "assistant", content: "full reply text" }] },
-        steps: [],
-      },
-    };
-    await store.save(session);
-
-    await reconcileSpokenPrefix(
-      { run: () => ({ events: partsToEvents([]) }), getSessionStore: () => store },
-      sessionId,
-      "full",
-    );
-
-    const saved = await store.get(sessionId);
-    expect(saved?.messages.at(-1)).toEqual({ role: "assistant", content: "full" });
-    const runState = (saved?.durableRuns as Record<string, { runState: { messages: KuralleMessageLike[] } }>)[sessionId]
-      ?.runState;
-    expect(runState?.messages.at(-1)).toEqual({ role: "assistant", content: "full" });
-  });
-});
-
-function createMockSessionStore(sessionId: string, messages: KuralleMessageLike[]): KuralleSessionStoreLike {
-  const sessions = new Map<string, KuralleStoredSession>([
-    [sessionId, { id: sessionId, messages: [...messages] }],
-  ]);
-  return {
-    async get(id) {
-      const session = sessions.get(id);
-      return session ? structuredClone(session) : null;
-    },
-    async save(session) {
-      sessions.set(session.id, structuredClone(session));
-    },
-  };
-}

package/tsconfig.json

@@ -1,13 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "types": ["vitest/globals"],
-    "noEmit": true
-  },
-  "include": ["src/**/*.ts"]
-}