@yolk-sdk/voice-runtime 0.0.1-canary.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yolk SDK contributors
+
+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,75 @@
+# @yolk-sdk/voice-runtime
+
+Provider-neutral bridge from realtime voice tool calls to Yolk tool execution.
+
+## Install
+
+```bash
+pnpm add @yolk-sdk/voice-runtime@canary @yolk-sdk/agent@canary effect
+```
+
+Canary APIs are unstable. Keep all `@yolk-sdk/*` packages on the same version.
+
+## Subpaths
+
+| Subpath | Purpose |
+| --- | --- |
+| `@yolk-sdk/voice-runtime` | Voice tool request/result schemas and execution bridge |
+
+## Imports
+
+```ts
+import { executeVoiceToolCall } from '@yolk-sdk/voice-runtime'
+```
+
+## What it provides
+
+- Normalized voice tool call request/result types.
+- `executeVoiceToolCall` for running calls through `ToolExecutor`.
+- JSON string result envelope for realtime provider adapters.
+- Typed voice bridge errors.
+
+## Example
+
+```ts
+import { Effect } from 'effect'
+import { executeVoiceToolCall } from '@yolk-sdk/voice-runtime'
+
+const result = executeVoiceToolCall({
+  callId: 'call_1',
+  name: 'search',
+  arguments: '{"query":"hello"}'
+})
+
+// Host provides ToolExecutor.
+Effect.runPromise(result)
+```
+
+Output is a provider-safe JSON string envelope:
+
+```json
+{ "result": { "content": [{ "type": "text", "text": "..." }] } }
+```
+
+Failures use:
+
+```json
+{ "error": "..." }
+```
+
+## Use it when
+
+- A realtime provider adapter receives a tool call and needs to execute it through Yolk tools.
+
+## Host responsibilities
+
+- Normalize provider tool-call events into this package's request shape.
+- Provide `ToolExecutor` and app tool policy.
+- Convert the JSON string envelope into provider-specific realtime responses.
+
+## Boundaries
+
+- No WebRTC or microphone code.
+- No OpenAI Realtime SDK imports.
+- No app tool catalogs.
+- Provider adapters convert this package's result into provider-specific realtime events.

package/dist/index.d.mts

@@ -0,0 +1,2 @@
+import { VoiceToolBridgeError, VoiceToolCallRequest, VoiceToolExecutionResult, executeVoiceToolCall } from "./tool-bridge.mjs";
+export { VoiceToolBridgeError, VoiceToolCallRequest, VoiceToolExecutionResult, executeVoiceToolCall };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { VoiceToolBridgeError, VoiceToolCallRequest, VoiceToolExecutionResult, executeVoiceToolCall } from "./tool-bridge.mjs";
+export { VoiceToolBridgeError, VoiceToolCallRequest, VoiceToolExecutionResult, executeVoiceToolCall };

package/dist/tool-bridge.d.mts

@@ -0,0 +1,24 @@
+import { Effect } from "effect";
+import * as Schema from "effect/Schema";
+import { ToolExecutor } from "@yolk-sdk/agent/loop";
+
+//#region src/tool-bridge.d.ts
+declare const VoiceToolCallRequest_base: Schema.Class<VoiceToolCallRequest, Schema.Struct<{
+  readonly callId: Schema.Trimmed;
+  readonly name: Schema.Trimmed;
+  readonly arguments: Schema.String;
+}>, {}>;
+declare class VoiceToolCallRequest extends VoiceToolCallRequest_base {}
+declare const VoiceToolExecutionResult_base: Schema.Class<VoiceToolExecutionResult, Schema.Struct<{
+  readonly toolCallId: Schema.String;
+  readonly output: Schema.String;
+}>, {}>;
+declare class VoiceToolExecutionResult extends VoiceToolExecutionResult_base {}
+declare const VoiceToolBridgeError_base: Schema.Class<VoiceToolBridgeError, Schema.TaggedStruct<"VoiceToolBridgeError", {
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+declare class VoiceToolBridgeError extends VoiceToolBridgeError_base {}
+declare const executeVoiceToolCall: (input: VoiceToolCallRequest) => Effect.Effect<VoiceToolExecutionResult, never, ToolExecutor>;
+//#endregion
+export { VoiceToolBridgeError, VoiceToolCallRequest, VoiceToolExecutionResult, executeVoiceToolCall };
+//# sourceMappingURL=tool-bridge.d.mts.map

package/dist/tool-bridge.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-bridge.d.mts","names":[],"sources":["../src/tool-bridge.ts"],"mappings":";;;;;cAEmE,yBAAA;;;;;cAMtD,oBAAA,SAA6B,yBAMxC;AAAA,cAAG,6BAAA;;;;cAEQ,wBAAA,SAAiC,6BAK5C;AAAA,cAAG,yBAAA;;;cAEQ,oBAAA,SAA6B,yBAKzC;AAAA,cA6CY,oBAAA,GAAwB,KAAA,EAAO,oBAAA,KAAoB,MAAA,CAAA,MAAA,CAAA,wBAAA,SAAA,YAAA"}

package/dist/tool-bridge.mjs

@@ -0,0 +1,44 @@
+import { Effect } from "effect";
+import * as Schema from "effect/Schema";
+import { ToolExecutor } from "@yolk-sdk/agent/loop";
+import { ToolCall } from "@yolk-sdk/agent/protocol";
+//#region src/tool-bridge.ts
+const NonEmptyTrimmedString = Schema.Trimmed.pipe(Schema.check(Schema.isNonEmpty()));
+const maxVoiceToolResultCharacters = 6e3;
+var VoiceToolCallRequest = class extends Schema.Class("VoiceToolCallRequest")({
+	callId: NonEmptyTrimmedString,
+	name: NonEmptyTrimmedString,
+	arguments: Schema.String
+}) {};
+var VoiceToolExecutionResult = class extends Schema.Class("VoiceToolExecutionResult")({
+	toolCallId: Schema.String,
+	output: Schema.String
+}) {};
+var VoiceToolBridgeError = class extends Schema.TaggedErrorClass()("VoiceToolBridgeError", { message: Schema.String }) {};
+const unknownToMessage = (error) => error instanceof Error ? error.message : String(error);
+const parseToolArguments = (raw) => Schema.decodeUnknownEffect(Schema.UnknownFromJsonString)(raw).pipe(Effect.mapError((error) => new VoiceToolBridgeError({ message: `Invalid tool arguments JSON: ${unknownToMessage(error)}` })));
+const stringifyToolOutput = (value) => Schema.encodeUnknownEffect(Schema.UnknownFromJsonString)(value).pipe(Effect.mapError((error) => new VoiceToolBridgeError({ message: `Could not serialize tool output: ${unknownToMessage(error)}` })));
+const truncateVoiceToolResult = (value) => {
+	if (value.length <= maxVoiceToolResultCharacters) return value;
+	return `${value.slice(0, maxVoiceToolResultCharacters)}\n\n[truncated for voice; summarize from available excerpt]`;
+};
+const contentToSerializable = (content) => typeof content === "string" ? truncateVoiceToolResult(content) : content;
+const makeVoiceToolExecutionResult = (toolCallId, output) => VoiceToolExecutionResult.make({
+	toolCallId,
+	output
+});
+const makeToolErrorResult = (toolCallId, error) => stringifyToolOutput({ error: error.message }).pipe(Effect.catchTag("VoiceToolBridgeError", () => Effect.succeed("{\"error\":\"Tool failed\"}")), Effect.map((output) => makeVoiceToolExecutionResult(toolCallId, output)));
+const executeVoiceToolCall = (input) => Effect.gen(function* () {
+	const executor = yield* ToolExecutor;
+	const params = yield* parseToolArguments(input.arguments);
+	const output = yield* stringifyToolOutput({ result: contentToSerializable((yield* executor.execute(ToolCall.make({
+		id: input.callId,
+		name: input.name,
+		params
+	}))).content) });
+	return makeVoiceToolExecutionResult(input.callId, output);
+}).pipe(Effect.catchTag("ToolError", (error) => makeToolErrorResult(input.callId, error)), Effect.catchTag("VoiceToolBridgeError", (error) => makeToolErrorResult(input.callId, error)));
+//#endregion
+export { VoiceToolBridgeError, VoiceToolCallRequest, VoiceToolExecutionResult, executeVoiceToolCall };
+
+//# sourceMappingURL=tool-bridge.mjs.map

package/dist/tool-bridge.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-bridge.mjs","names":[],"sources":["../src/tool-bridge.ts"],"sourcesContent":["import { Effect } from 'effect'\nimport * as Schema from 'effect/Schema'\nimport { ToolExecutor, type ToolError } from '@yolk-sdk/agent/loop'\nimport { ToolCall, type Content } from '@yolk-sdk/agent/protocol'\n\nconst NonEmptyTrimmedString = Schema.Trimmed.pipe(Schema.check(Schema.isNonEmpty()))\nconst maxVoiceToolResultCharacters = 6000\n\nexport class VoiceToolCallRequest extends Schema.Class<VoiceToolCallRequest>(\n  'VoiceToolCallRequest'\n)({\n  callId: NonEmptyTrimmedString,\n  name: NonEmptyTrimmedString,\n  arguments: Schema.String\n}) {}\n\nexport class VoiceToolExecutionResult extends Schema.Class<VoiceToolExecutionResult>(\n  'VoiceToolExecutionResult'\n)({\n  toolCallId: Schema.String,\n  output: Schema.String\n}) {}\n\nexport class VoiceToolBridgeError extends Schema.TaggedErrorClass<VoiceToolBridgeError>()(\n  'VoiceToolBridgeError',\n  {\n    message: Schema.String\n  }\n) {}\n\nconst unknownToMessage = (error: unknown) =>\n  error instanceof Error ? error.message : String(error)\n\nconst parseToolArguments = (raw: string) =>\n  Schema.decodeUnknownEffect(Schema.UnknownFromJsonString)(raw).pipe(\n    Effect.mapError(\n      error =>\n        new VoiceToolBridgeError({\n          message: `Invalid tool arguments JSON: ${unknownToMessage(error)}`\n        })\n    )\n  )\n\nconst stringifyToolOutput = (value: unknown) =>\n  Schema.encodeUnknownEffect(Schema.UnknownFromJsonString)(value).pipe(\n    Effect.mapError(\n      error =>\n        new VoiceToolBridgeError({\n          message: `Could not serialize tool output: ${unknownToMessage(error)}`\n        })\n    )\n  )\n\nconst truncateVoiceToolResult = (value: string) => {\n  if (value.length <= maxVoiceToolResultCharacters) {\n    return value\n  }\n\n  return `${value.slice(0, maxVoiceToolResultCharacters)}\\n\\n[truncated for voice; summarize from available excerpt]`\n}\n\nconst contentToSerializable = (content: Content): unknown =>\n  typeof content === 'string' ? truncateVoiceToolResult(content) : content\n\nconst makeVoiceToolExecutionResult = (toolCallId: string, output: string) =>\n  VoiceToolExecutionResult.make({ toolCallId, output })\n\nconst makeToolErrorResult = (toolCallId: string, error: ToolError | VoiceToolBridgeError) =>\n  stringifyToolOutput({ error: error.message }).pipe(\n    Effect.catchTag('VoiceToolBridgeError', () => Effect.succeed('{\"error\":\"Tool failed\"}')),\n    Effect.map(output => makeVoiceToolExecutionResult(toolCallId, output))\n  )\n\nexport const executeVoiceToolCall = (input: VoiceToolCallRequest) =>\n  Effect.gen(function* () {\n    const executor = yield* ToolExecutor\n    const params = yield* parseToolArguments(input.arguments)\n    const result = yield* executor.execute(\n      ToolCall.make({\n        id: input.callId,\n        name: input.name,\n        params\n      })\n    )\n    const output = yield* stringifyToolOutput({ result: contentToSerializable(result.content) })\n\n    return makeVoiceToolExecutionResult(input.callId, output)\n  }).pipe(\n    Effect.catchTag('ToolError', error => makeToolErrorResult(input.callId, error)),\n    Effect.catchTag('VoiceToolBridgeError', error => makeToolErrorResult(input.callId, error))\n  )\n"],"mappings":";;;;;AAKA,MAAM,wBAAwB,OAAO,QAAQ,KAAK,OAAO,MAAM,OAAO,WAAW,CAAC,CAAC;AACnF,MAAM,+BAA+B;AAErC,IAAa,uBAAb,cAA0C,OAAO,MAC/C,sBACF,EAAE;CACA,QAAQ;CACR,MAAM;CACN,WAAW,OAAO;AACpB,CAAC,EAAE,CAAC;AAEJ,IAAa,2BAAb,cAA8C,OAAO,MACnD,0BACF,EAAE;CACA,YAAY,OAAO;CACnB,QAAQ,OAAO;AACjB,CAAC,EAAE,CAAC;AAEJ,IAAa,uBAAb,cAA0C,OAAO,iBAAuC,EACtF,wBACA,EACE,SAAS,OAAO,OAClB,CACF,EAAE,CAAC;AAEH,MAAM,oBAAoB,UACxB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAEvD,MAAM,sBAAsB,QAC1B,OAAO,oBAAoB,OAAO,qBAAqB,EAAE,GAAG,EAAE,KAC5D,OAAO,UACL,UACE,IAAI,qBAAqB,EACvB,SAAS,gCAAgC,iBAAiB,KAAK,IACjE,CAAC,CACL,CACF;AAEF,MAAM,uBAAuB,UAC3B,OAAO,oBAAoB,OAAO,qBAAqB,EAAE,KAAK,EAAE,KAC9D,OAAO,UACL,UACE,IAAI,qBAAqB,EACvB,SAAS,oCAAoC,iBAAiB,KAAK,IACrE,CAAC,CACL,CACF;AAEF,MAAM,2BAA2B,UAAkB;CACjD,IAAI,MAAM,UAAU,8BAClB,OAAO;CAGT,OAAO,GAAG,MAAM,MAAM,GAAG,4BAA4B,EAAE;AACzD;AAEA,MAAM,yBAAyB,YAC7B,OAAO,YAAY,WAAW,wBAAwB,OAAO,IAAI;AAEnE,MAAM,gCAAgC,YAAoB,WACxD,yBAAyB,KAAK;CAAE;CAAY;AAAO,CAAC;AAEtD,MAAM,uBAAuB,YAAoB,UAC/C,oBAAoB,EAAE,OAAO,MAAM,QAAQ,CAAC,EAAE,KAC5C,OAAO,SAAS,8BAA8B,OAAO,QAAQ,6BAAyB,CAAC,GACvF,OAAO,KAAI,WAAU,6BAA6B,YAAY,MAAM,CAAC,CACvE;AAEF,MAAa,wBAAwB,UACnC,OAAO,IAAI,aAAa;CACtB,MAAM,WAAW,OAAO;CACxB,MAAM,SAAS,OAAO,mBAAmB,MAAM,SAAS;CAQxD,MAAM,SAAS,OAAO,oBAAoB,EAAE,QAAQ,uBAAsB,OAPpD,SAAS,QAC7B,SAAS,KAAK;EACZ,IAAI,MAAM;EACV,MAAM,MAAM;EACZ;CACF,CAAC,CACH,GACiF,OAAO,EAAE,CAAC;CAE3F,OAAO,6BAA6B,MAAM,QAAQ,MAAM;AAC1D,CAAC,EAAE,KACD,OAAO,SAAS,cAAa,UAAS,oBAAoB,MAAM,QAAQ,KAAK,CAAC,GAC9E,OAAO,SAAS,yBAAwB,UAAS,oBAAoB,MAAM,QAAQ,KAAK,CAAC,CAC3F"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@yolk-sdk/voice-runtime",
+  "version": "0.0.1-canary.0",
+  "description": "Provider-neutral voice tool-call bridge for Yolk agents.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/magoz/yolk-sdk.git",
+    "directory": "packages/voice-runtime"
+  },
+  "bugs": {
+    "url": "https://github.com/magoz/yolk-sdk/issues"
+  },
+  "homepage": "https://github.com/magoz/yolk-sdk#readme",
+  "keywords": [
+    "voice",
+    "realtime",
+    "agents",
+    "tools",
+    "effect"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "dist/**/*",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "effect": "4.0.0-beta.65",
+    "@yolk-sdk/agent": "^0.0.1-canary.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:run": "vitest run --passWithNoTests"
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export {
+  executeVoiceToolCall,
+  VoiceToolBridgeError,
+  VoiceToolCallRequest,
+  VoiceToolExecutionResult
+} from './tool-bridge.ts'

package/src/tool-bridge.ts

@@ -0,0 +1,91 @@
+import { Effect } from 'effect'
+import * as Schema from 'effect/Schema'
+import { ToolExecutor, type ToolError } from '@yolk-sdk/agent/loop'
+import { ToolCall, type Content } from '@yolk-sdk/agent/protocol'
+
+const NonEmptyTrimmedString = Schema.Trimmed.pipe(Schema.check(Schema.isNonEmpty()))
+const maxVoiceToolResultCharacters = 6000
+
+export class VoiceToolCallRequest extends Schema.Class<VoiceToolCallRequest>(
+  'VoiceToolCallRequest'
+)({
+  callId: NonEmptyTrimmedString,
+  name: NonEmptyTrimmedString,
+  arguments: Schema.String
+}) {}
+
+export class VoiceToolExecutionResult extends Schema.Class<VoiceToolExecutionResult>(
+  'VoiceToolExecutionResult'
+)({
+  toolCallId: Schema.String,
+  output: Schema.String
+}) {}
+
+export class VoiceToolBridgeError extends Schema.TaggedErrorClass<VoiceToolBridgeError>()(
+  'VoiceToolBridgeError',
+  {
+    message: Schema.String
+  }
+) {}
+
+const unknownToMessage = (error: unknown) =>
+  error instanceof Error ? error.message : String(error)
+
+const parseToolArguments = (raw: string) =>
+  Schema.decodeUnknownEffect(Schema.UnknownFromJsonString)(raw).pipe(
+    Effect.mapError(
+      error =>
+        new VoiceToolBridgeError({
+          message: `Invalid tool arguments JSON: ${unknownToMessage(error)}`
+        })
+    )
+  )
+
+const stringifyToolOutput = (value: unknown) =>
+  Schema.encodeUnknownEffect(Schema.UnknownFromJsonString)(value).pipe(
+    Effect.mapError(
+      error =>
+        new VoiceToolBridgeError({
+          message: `Could not serialize tool output: ${unknownToMessage(error)}`
+        })
+    )
+  )
+
+const truncateVoiceToolResult = (value: string) => {
+  if (value.length <= maxVoiceToolResultCharacters) {
+    return value
+  }
+
+  return `${value.slice(0, maxVoiceToolResultCharacters)}\n\n[truncated for voice; summarize from available excerpt]`
+}
+
+const contentToSerializable = (content: Content): unknown =>
+  typeof content === 'string' ? truncateVoiceToolResult(content) : content
+
+const makeVoiceToolExecutionResult = (toolCallId: string, output: string) =>
+  VoiceToolExecutionResult.make({ toolCallId, output })
+
+const makeToolErrorResult = (toolCallId: string, error: ToolError | VoiceToolBridgeError) =>
+  stringifyToolOutput({ error: error.message }).pipe(
+    Effect.catchTag('VoiceToolBridgeError', () => Effect.succeed('{"error":"Tool failed"}')),
+    Effect.map(output => makeVoiceToolExecutionResult(toolCallId, output))
+  )
+
+export const executeVoiceToolCall = (input: VoiceToolCallRequest) =>
+  Effect.gen(function* () {
+    const executor = yield* ToolExecutor
+    const params = yield* parseToolArguments(input.arguments)
+    const result = yield* executor.execute(
+      ToolCall.make({
+        id: input.callId,
+        name: input.name,
+        params
+      })
+    )
+    const output = yield* stringifyToolOutput({ result: contentToSerializable(result.content) })
+
+    return makeVoiceToolExecutionResult(input.callId, output)
+  }).pipe(
+    Effect.catchTag('ToolError', error => makeToolErrorResult(input.callId, error)),
+    Effect.catchTag('VoiceToolBridgeError', error => makeToolErrorResult(input.callId, error))
+  )