@kuralle-syrinx/mastra 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/README.md

@@ -0,0 +1,43 @@
+# @kuralle-syrinx/mastra
+
+The Mastra adapter for the Syrinx [`Reasoner`](../core/README.md#the-reasoner-seam) seam: **`fromMastraAgent(agent) → Reasoner`**. Drop it into [`ReasoningBridge`](../aisdk/README.md) to drive the voice pipeline with a Mastra `Agent` instead of a raw AI SDK backend — no pipeline change.
+
+## Usage
+
+```ts
+import { Agent } from "@mastra/core/agent";
+import { createOpenAI } from "@ai-sdk/openai";
+import { ReasoningBridge } from "@kuralle-syrinx/aisdk";
+import { fromMastraAgent } from "@kuralle-syrinx/mastra";
+
+const agent = new Agent({
+  name: "support",
+  instructions: "You are a helpful voice assistant.",
+  model: createOpenAI({ apiKey })("gpt-4.1-mini"),
+});
+session.registerPlugin("bridge", new ReasoningBridge(fromMastraAgent(agent)));
+```
+
+## How it maps
+
+`fromMastraAgent` awaits `agent.stream(messages)` and iterates `output.fullStream` (a `ReadableStream<{type,payload}>`), mapping each chunk → `ReasoningPart`:
+
+| Mastra chunk | → |
+|---|---|
+| `text-delta` (`payload.text`) | `text-delta` |
+| `tool-call` (`payload.{toolCallId,toolName,args}`) | `tool-call` |
+| `tool-result` (`payload.{toolCallId,toolName,result}`) | `tool-result` |
+| `tool-call-suspended` (`payload.suspendPayload`, `output.runId`) | terminal `suspended` (Sprint 3 / suspend-resume) |
+| `finish` (`payload.stepResult.reason`) | `finish` (stop/tool/length) or terminal `error` for abnormal reasons |
+| `error` (`payload.error`) | terminal `error` |
+| anything else | dropped |
+
+Verified against `@mastra/core@1.41.0`. A `turn.resume` routes to `agent.resumeStream(data, {runId})` instead of `stream(...)`. No buffering — each chunk is yielded immediately.
+
+`MastraAgentLike` is the minimal structural type the adapter needs (`stream` + `resumeStream`) — the concrete `@mastra/core` `Agent` satisfies it.
+
+## Gotchas
+
+- **`@mastra/core` is a `peerDependency`** — the consumer instantiates and owns the `Agent` (and its Mastra version). The adapter only touches `stream`/`resumeStream`/`fullStream`/`runId`.
+- **Node / `nodejs_compat` only.** `@mastra/core` imports `events`/`fs`/`path`/`crypto` and won't bundle for a plain browser/edge target (`--platform=browser`). On Cloudflare Workers it requires `nodejs_compat` (see `@kuralle-syrinx/server-workers-mastra`). The lean AI-SDK product worker deliberately keeps Mastra out of its bundle.
+- **History stays bridge-owned** (RFC §4.5): run the agent stateless-per-turn (no Mastra memory) so the bridge's spoken-prefix barge-in remains authoritative.

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@kuralle-syrinx/mastra",
+  "version": "2.1.0",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "dependencies": {
+    "@kuralle-syrinx/core": "2.1.0"
+  },
+  "peerDependencies": {
+    "@mastra/core": ">=1.41.0 <2"
+  },
+  "devDependencies": {
+    "@mastra/core": "^1.41.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/from-mastra.test.ts

@@ -0,0 +1,283 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import type { Reasoner, ReasonerTurn, ReasoningPart } from "@kuralle-syrinx/core";
+import { fromMastraAgent, type MastraAgentLike, type MastraChunk } from "./from-mastra.js";
+
+function baseTurn(): ReasonerTurn {
+  return {
+    userText: "Hi",
+    messages: [{ role: "system", content: "test" }],
+    signal: new AbortController().signal,
+  };
+}
+
+function textDelta(text: string): MastraChunk {
+  return { type: "text-delta", payload: { text } };
+}
+
+function toolCall(toolCallId: string, toolName: string, args: Record<string, unknown>): MastraChunk {
+  return { type: "tool-call", payload: { toolCallId, toolName, args } };
+}
+
+function toolResult(toolCallId: string, toolName: string, result: unknown): MastraChunk {
+  return { type: "tool-result", payload: { toolCallId, toolName, result } };
+}
+
+function errorChunk(error: unknown): MastraChunk {
+  return { type: "error", payload: { error } };
+}
+
+function finish(reason: string): MastraChunk {
+  return { type: "finish", payload: { stepResult: { reason } } };
+}
+
+function chunksToStream(chunks: MastraChunk[]): ReadableStream<MastraChunk> {
+  return new ReadableStream({
+    start(controller) {
+      for (const ch of chunks) controller.enqueue(ch);
+      controller.close();
+    },
+  });
+}
+
+function delayedStream(first: MastraChunk): { stream: ReadableStream<MastraChunk>; release: () => void } {
+  let release!: () => void;
+  const gate = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  const stream = new ReadableStream<MastraChunk>({
+    async start(controller) {
+      controller.enqueue(first);
+      await gate;
+      controller.close();
+    },
+  });
+  return { stream, release };
+}
+
+function fakeAgent(
+  chunks: MastraChunk[] | ReadableStream<MastraChunk>,
+  opts?: {
+    runId?: string;
+    resume?: {
+      chunks: MastraChunk[] | ReadableStream<MastraChunk>;
+      runId?: string;
+    };
+    spy?: {
+      streamCalled?: boolean;
+      resumeCalled?: boolean;
+      resumeData?: unknown;
+      resumeOptions?: { runId: string; toolCallId?: string; abortSignal?: AbortSignal };
+    };
+  },
+): MastraAgentLike {
+  const spy = opts?.spy;
+  return {
+    async stream() {
+      if (spy) spy.streamCalled = true;
+      return {
+        runId: opts?.runId ?? "r1",
+        fullStream: chunks instanceof ReadableStream ? chunks : chunksToStream(chunks),
+      };
+    },
+    async resumeStream(resumeData, options) {
+      if (spy) {
+        spy.resumeCalled = true;
+        spy.resumeData = resumeData;
+        spy.resumeOptions = options;
+      }
+      const resumeChunks = opts?.resume?.chunks ?? [];
+      return {
+        runId: opts?.resume?.runId ?? opts?.runId ?? "r1",
+        fullStream:
+          resumeChunks instanceof ReadableStream ? resumeChunks : chunksToStream(resumeChunks),
+      };
+    },
+  };
+}
+
+async function collectParts(reasoner: Reasoner, turn: ReasonerTurn): Promise<ReasoningPart[]> {
+  const parts: ReasoningPart[] = [];
+  for await (const part of reasoner.stream(turn)) {
+    parts.push(part);
+  }
+  return parts;
+}
+
+describe("fromMastraAgent", () => {
+  it("maps happy path: deltas, tool-call, tool-result, finish:stop", async () => {
+    const reasoner = fromMastraAgent(
+      fakeAgent([
+        textDelta("Hello "),
+        textDelta("world."),
+        toolCall("tc-1", "get_weather", { city: "NYC" }),
+        toolResult("tc-1", "get_weather", { temp: 72 }),
+        finish("stop"),
+      ]),
+    );
+
+    const parts = await collectParts(reasoner, baseTurn());
+
+    expect(parts).toEqual([
+      { type: "text-delta", text: "Hello " },
+      { type: "text-delta", text: "world." },
+      {
+        type: "tool-call",
+        toolId: "tc-1",
+        toolName: "get_weather",
+        args: { city: "NYC" },
+      },
+      {
+        type: "tool-result",
+        toolId: "tc-1",
+        toolName: "get_weather",
+        result: JSON.stringify({ temp: 72 }),
+      },
+      { type: "finish", reason: "stop", text: "Hello world." },
+    ]);
+  });
+
+  it("maps error chunk to terminal error", async () => {
+    const reasoner = fromMastraAgent(
+      fakeAgent([textDelta("partial"), errorChunk(new Error("provider failed"))]),
+    );
+
+    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("provider failed");
+      expect(parts[1].recoverable).toBe(false);
+    }
+  });
+
+  it("maps abnormal finish (content-filter) to terminal error", async () => {
+    const reasoner = fromMastraAgent(fakeAgent([finish("content-filter")]));
+
+    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(
+        "Mastra provider did not complete normally: content-filter",
+      );
+      expect(parts[0].recoverable).toBe(false);
+    }
+  });
+
+  it("maps finish(length) to finish with accumulated text", async () => {
+    const reasoner = fromMastraAgent(fakeAgent([textDelta("truncated"), finish("length")]));
+
+    const parts = await collectParts(reasoner, baseTurn());
+
+    expect(parts).toEqual([
+      { type: "text-delta", text: "truncated" },
+      { type: "finish", reason: "length", text: "truncated" },
+    ]);
+  });
+
+  it("drops reasoning-delta and workflow chunks", async () => {
+    const reasoner = fromMastraAgent(
+      fakeAgent([
+        { type: "reasoning-delta", payload: { text: "thinking..." } },
+        { type: "workflow-step", payload: { step: 1 } },
+        textDelta("answer"),
+        finish("stop"),
+      ]),
+    );
+
+    const parts = await collectParts(reasoner, baseTurn());
+
+    expect(parts).toEqual([
+      { type: "text-delta", text: "answer" },
+      { type: "finish", reason: "stop", text: "answer" },
+    ]);
+  });
+
+  it("yields first text-delta before source stream completes (no buffering)", async () => {
+    const { stream, release } = delayedStream(textDelta("immediate"));
+    const reasoner = fromMastraAgent(fakeAgent(stream));
+
+    const iterator = reasoner.stream(baseTurn())[Symbol.asyncIterator]();
+    const first = await iterator.next();
+
+    expect(first.done).toBe(false);
+    expect(first.value).toEqual({ type: "text-delta", text: "immediate" });
+    release();
+  });
+
+  it("returns without yielding when turn.signal is already aborted (barge-in)", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const turn: ReasonerTurn = { ...baseTurn(), signal: controller.signal };
+
+    const reasoner = fromMastraAgent(
+      fakeAgent([textDelta("should not appear"), finish("stop")]),
+    );
+
+    const parts = await collectParts(reasoner, turn);
+
+    expect(parts).toEqual([]);
+  });
+
+  it("maps tool-call-suspended to terminal suspended part", async () => {
+    const reasoner = fromMastraAgent(
+      fakeAgent(
+        [
+          {
+            type: "tool-call-suspended",
+            payload: { suspendPayload: { message: "Approve the refund?" } },
+          },
+        ],
+        { runId: "run-1" },
+      ),
+    );
+
+    const parts = await collectParts(reasoner, baseTurn());
+
+    expect(parts).toEqual([
+      {
+        type: "suspended",
+        runId: "run-1",
+        prompt: "Approve the refund?",
+        payload: { message: "Approve the refund?" },
+      },
+    ]);
+  });
+
+  it("resume turn calls resumeStream instead of stream", async () => {
+    const spy = {
+      streamCalled: false,
+      resumeCalled: false,
+      resumeData: undefined as unknown,
+      resumeOptions: undefined as
+        | { runId: string; toolCallId?: string; abortSignal?: AbortSignal }
+        | undefined,
+    };
+    const reasoner = fromMastraAgent(
+      fakeAgent([], {
+        resume: { chunks: [textDelta("Done."), finish("stop")], runId: "run-1" },
+        spy,
+      }),
+    );
+
+    const turn: ReasonerTurn = {
+      ...baseTurn(),
+      resume: { runId: "run-1", data: { approved: true } },
+    };
+    const parts = await collectParts(reasoner, turn);
+
+    expect(spy.streamCalled).toBe(false);
+    expect(spy.resumeCalled).toBe(true);
+    expect(spy.resumeData).toEqual({ approved: true });
+    expect(spy.resumeOptions).toEqual({ runId: "run-1", abortSignal: turn.signal });
+    expect(parts).toEqual([
+      { type: "text-delta", text: "Done." },
+      { type: "finish", reason: "stop", text: "Done." },
+    ]);
+  });
+});

package/src/from-mastra.ts

@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: MIT
+import type { Reasoner, ReasonerTurn, ReasonerMessage, ReasoningPart } from "@kuralle-syrinx/core";
+import { categorizeLlmError, isRecoverable } from "@kuralle-syrinx/core";
+
+type MastraStreamOutput = { readonly runId: string; readonly fullStream: ReadableStream<MastraChunk> };
+
+export interface MastraAgentLike {
+  stream(
+    messages: MastraMessage[],
+    options?: { abortSignal?: AbortSignal },
+  ): Promise<MastraStreamOutput>;
+  resumeStream(
+    resumeData: unknown,
+    options: { runId: string; toolCallId?: string; abortSignal?: AbortSignal },
+  ): Promise<MastraStreamOutput>;
+}
+
+export interface MastraChunk {
+  readonly type: string;
+  readonly payload: Record<string, unknown>;
+}
+
+type MastraMessage = { role: "system" | "user" | "assistant" | "tool"; content: string };
+
+export function fromMastraAgent(agent: MastraAgentLike): Reasoner {
+  return { stream: (turn) => streamFromMastra(agent, turn) };
+}
+
+function buildMessages(turn: ReasonerTurn): MastraMessage[] {
+  return [
+    ...turn.messages.map((m: ReasonerMessage) => ({ role: m.role, content: m.content })),
+    { role: "user", content: turn.userText },
+  ];
+}
+
+async function* streamFromMastra(
+  agent: MastraAgentLike,
+  turn: ReasonerTurn,
+): AsyncGenerator<ReasoningPart> {
+  const out = turn.resume
+    ? await agent.resumeStream(turn.resume.data, {
+        runId: turn.resume.runId,
+        abortSignal: turn.signal,
+      })
+    : await agent.stream(buildMessages(turn), { abortSignal: turn.signal });
+  let acc = "";
+  for await (const chunk of out.fullStream) {
+    if (turn.signal.aborted) return;
+    switch (chunk.type) {
+      case "text-delta": {
+        const t = String(chunk.payload.text ?? "");
+        acc += t;
+        yield { type: "text-delta", text: t };
+        break;
+      }
+      case "tool-call":
+        yield {
+          type: "tool-call",
+          toolId: String(chunk.payload.toolCallId ?? ""),
+          toolName: String(chunk.payload.toolName ?? ""),
+          args: toRecord(chunk.payload.args),
+        };
+        break;
+      case "tool-result":
+        yield {
+          type: "tool-result",
+          toolId: String(chunk.payload.toolCallId ?? ""),
+          toolName: String(chunk.payload.toolName ?? ""),
+          result: stringifyResult(chunk.payload.result),
+        };
+        break;
+      case "error":
+        yield toErrorPart(chunk.payload.error);
+        return;
+      case "finish": {
+        const reason = chunk.payload.stepResult as { reason?: string } | undefined;
+        const finishReason = reason?.reason;
+        if (finishReason === "stop" || finishReason === "tool-calls" || finishReason === "length") {
+          yield {
+            type: "finish",
+            reason: finishReason === "tool-calls" ? "tool" : finishReason,
+            text: acc,
+          };
+          return;
+        }
+        yield toErrorPart(
+          new Error(`Mastra provider did not complete normally: ${String(finishReason)}`),
+        );
+        return;
+      }
+      case "tool-call-suspended": {
+        const sp = chunk.payload.suspendPayload as Record<string, unknown> | undefined;
+        const prompt =
+          typeof sp?.["message"] === "string"
+            ? (sp["message"] as string)
+            : typeof sp?.["prompt"] === "string"
+              ? (sp["prompt"] as string)
+              : undefined;
+        yield {
+          type: "suspended",
+          runId: out.runId,
+          prompt,
+          payload: chunk.payload.suspendPayload,
+        };
+        return;
+      }
+      default:
+        break;
+    }
+  }
+  yield toErrorPart(new Error("Mastra stream ended without a finish chunk"));
+}
+
+function toErrorPart(error: unknown): ReasoningPart {
+  const cause = error instanceof Error ? error : new Error(String(error));
+  return { type: "error", cause, recoverable: isRecoverable(categorizeLlmError(cause)) };
+}
+
+function stringifyResult(r: unknown): string {
+  return typeof r === "string" ? r : JSON.stringify(r);
+}
+
+function toRecord(value: unknown): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return {};
+  return value as Record<string, unknown>;
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+// SPDX-License-Identifier: MIT
+export { fromMastraAgent, type MastraAgentLike, type MastraChunk } from "./from-mastra.js";

package/tsconfig.json

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