@frockbot/plugin-voice 0.0.0 → 0.3.21

package/frockbot.json

@@ -0,0 +1,25 @@
+{
+  "schemaVersion": 4,
+  "id": "voice",
+  "displayName": "Voice",
+  "version": "0.0.1",
+  "compatibility": { "frockbot": ">=0.0.1" },
+  "dependencies": {
+    "flock": ">=0.0.1",
+    "memory": ">=0.0.1",
+    "shell": ">=0.0.1",
+    "ui-theme": ">=0.0.1"
+  },
+  "contributions": {
+    "backend": [
+      { "entry": "./user", "host": "user" },
+      { "entry": "./backend", "host": "gateway" }
+    ],
+    "client": {
+      "entry": "./client",
+      "mounts": [{ "slot": "frockbot.header-actions", "order": 20 }],
+      "outlets": []
+    }
+  },
+  "permissions": []
+}

package/package.json

@@ -1,14 +1,53 @@
 {
   "name": "@frockbot/plugin-voice",
-  "version": "0.0.0",
-  "description": "Placeholder reserving this name for trusted publishing. Superseded by the first release.",
-  "license": "UNLICENSED",
+  "version": "0.3.21",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./ask": "./src/ask.ts",
+    "./backend": "./src/backend.ts",
+    "./bot": "./src/bot.ts",
+    "./client": "./src/client/index.ts",
+    "./frockbot.json": "./frockbot.json",
+    "./ledger": "./src/ledger.ts",
+    "./manifest": "./src/manifest.ts",
+    "./package.json": "./package.json",
+    "./prompt": "./src/prompt.ts",
+    "./shared": "./src/shared.ts",
+    "./tools": "./src/tools.ts",
+    "./user": "./src/user.ts"
+  },
+  "frockbot": {
+    "manifest": "./frockbot.json"
+  },
+  "scripts": {
+    "test": "bun test src",
+    "typecheck": "vue-tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@frockbot/client-core": "0.3.21",
+    "@frockbot/client-ui": "0.3.21",
+    "@frockbot/kernel-contracts": "0.3.21",
+    "@frockbot/plugin-flock": "0.3.21",
+    "@frockbot/plugin-shell": "0.3.21",
+    "@frockbot/protocol": "0.3.21",
+    "cordis": "4.0.0-rc.8",
+    "vue": "3.5.41"
+  },
+  "devDependencies": {
+    "@types/bun": "1.4.0",
+    "@vitejs/plugin-vue": "6.0.8",
+    "typescript": "npm:typescript-native-bridge@6.0.3-bridge.16.tsgo.7.0.2",
+    "vite": "8.2.2",
+    "vue-tsc": "3.3.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/timoconnellaus/frockbot.git",
     "directory": "packages/plugin-voice"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/ask.test.ts

@@ -0,0 +1,129 @@
+import { describe, expect, test } from "bun:test";
+import { askBotFromVoiceV1, type VoiceAskHostV1 } from "./ask.js";
+import { VoiceLedgerV1, type VoiceLedgerStorageV1 } from "./ledger.js";
+
+function memoryStorage(): VoiceLedgerStorageV1 {
+  const values = new Map<string, unknown>();
+  const surface = {
+    get: <T>(key: string) => Promise.resolve(values.get(key) as T | undefined),
+    put: (key: string, value: unknown) => {
+      values.set(key, value);
+      return Promise.resolve();
+    },
+    delete: (key: string) => Promise.resolve(values.delete(key)),
+    list: async <T>({ prefix }: { prefix: string }) =>
+      new Map(
+        [...values]
+          .filter(([key]) => key.startsWith(prefix))
+          .map(([key, value]) => [key, value as T]),
+      ),
+  };
+  return { ...surface, transaction: (callback) => callback(surface) };
+}
+
+describe("Voice ask coordinator", () => {
+  test("a replay reaches one idempotent target Turn", async () => {
+    const ledger = new VoiceLedgerV1(memoryStorage());
+    const admitted = new Set<string>();
+    let targetTurns = 0;
+    const deferred: Promise<void>[] = [];
+    const host: VoiceAskHostV1 = {
+      listBots: () =>
+        Promise.resolve([
+          { botId: "research", name: "Research", status: "active" },
+        ]),
+      reserveAgentTurn: (request) =>
+        Promise.resolve({
+          schemaVersion: 1,
+          status: "reserved",
+          requesterId: request.requesterId,
+          runId: request.runId,
+          held: 1,
+          limit: 8,
+        }),
+      releaseAgentTurn: () => Promise.resolve(),
+      runAgent: async (request) => {
+        if (!admitted.has(request.command.runId)) {
+          admitted.add(request.command.runId);
+          targetTurns += 1;
+        }
+      },
+      defer(task) {
+        deferred.push(task);
+      },
+    };
+    const input = {
+      userId: "user-1",
+      sessionId: "voice-1",
+      callId: "call-1",
+      bot: "Research",
+      question: "What changed?",
+      at: "2026-09-04T01:02:03.000Z",
+    };
+
+    const first = await askBotFromVoiceV1(ledger, host, input);
+    const replay = await askBotFromVoiceV1(ledger, host, {
+      ...input,
+      // Gemini can redeliver the same function-call id in a later frame. The
+      // original durable ask time is retained while target admission reuses
+      // the same run id.
+      at: "2026-09-04T01:02:04.000Z",
+    });
+    await Promise.all(deferred);
+
+    expect(first).toEqual(replay);
+    expect(first).toMatchObject({
+      status: "accepted",
+      message: "I've asked Research. I'll tell you when Research answers.",
+    });
+    expect(targetTurns).toBe(1);
+  });
+
+  test("refuses a second outstanding ask to the same Bot and session", async () => {
+    const ledger = new VoiceLedgerV1(memoryStorage());
+    const deferred: Promise<void>[] = [];
+    const host: VoiceAskHostV1 = {
+      listBots: () =>
+        Promise.resolve([
+          { botId: "research", name: "Research", status: "active" },
+        ]),
+      reserveAgentTurn: (request) =>
+        Promise.resolve({
+          schemaVersion: 1,
+          status: "reserved",
+          requesterId: request.requesterId,
+          runId: request.runId,
+          held: 1,
+          limit: 8,
+        }),
+      releaseAgentTurn: () => Promise.resolve(),
+      runAgent: () => new Promise(() => {}),
+      defer(task) {
+        deferred.push(task);
+      },
+    };
+    await askBotFromVoiceV1(ledger, host, {
+      userId: "user-1",
+      sessionId: "voice-1",
+      callId: "call-1",
+      bot: "research",
+      question: "First?",
+      at: "2026-09-04T01:02:03.000Z",
+    });
+
+    await expect(
+      askBotFromVoiceV1(ledger, host, {
+        userId: "user-1",
+        sessionId: "voice-1",
+        callId: "call-2",
+        bot: "research",
+        question: "Second?",
+        at: "2026-09-04T01:02:04.000Z",
+      }),
+    ).resolves.toEqual({
+      status: "refused",
+      message:
+        "Research is already answering a Voice question from this session.",
+    });
+  });
+});

package/src/ask.ts

@@ -0,0 +1,191 @@
+import type { AgentTurnSlotReceiptV1 } from "@frockbot/plugin-flock/quota";
+import type { VoiceLedgerV1 } from "./ledger.js";
+import type { VoiceBotSummaryV1 } from "./tools.js";
+
+export interface VoiceAskHostV1 {
+  listBots(): Promise<readonly VoiceBotSummaryV1[]>;
+  reserveAgentTurn(request: {
+    schemaVersion: 1;
+    userId: string;
+    requesterId: string;
+    runId: string;
+    reservedAt: string;
+  }): Promise<AgentTurnSlotReceiptV1>;
+  releaseAgentTurn(request: {
+    schemaVersion: 1;
+    userId: string;
+    requesterId: string;
+    runId: string;
+  }): Promise<void>;
+  runAgent(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    command: {
+      runId: string;
+      sessionId: string;
+      acceptedAt: string;
+      text: string;
+      source: { kind: "voice"; messageId: string };
+    };
+  }): Promise<unknown>;
+  defer(task: Promise<void>): void;
+}
+
+export type VoiceAskResultV1 =
+  | {
+      status: "accepted";
+      message: string;
+      askId: string;
+      runId: string;
+      botId: string;
+      botName: string;
+    }
+  | { status: "refused"; message: string };
+
+async function digestIdV1(prefix: string, parts: readonly string[]) {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(parts.join("\u0000")),
+  );
+  const hex = [...new Uint8Array(digest)]
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+  return `${prefix}-${hex.slice(0, 32)}`;
+}
+
+function botNamed(
+  bots: readonly VoiceBotSummaryV1[],
+  requested: string,
+): VoiceBotSummaryV1 | undefined {
+  return (
+    bots.find((bot) => bot.botId === requested) ??
+    bots.find((bot) => bot.name.toLowerCase() === requested.toLowerCase())
+  );
+}
+
+/**
+ * User-authority coordinator for `ask_bot`.
+ *
+ * It returns after durable intent and admission scheduling, never after the
+ * Bot's answer. A repeated Gemini function call derives the same ids and may
+ * safely call the target again: the target Bot's run admission is the
+ * idempotency fence, so a crash between this object and that fence cannot
+ * become either a lost ask or a second Turn.
+ */
+export async function askBotFromVoiceV1(
+  ledger: VoiceLedgerV1,
+  host: VoiceAskHostV1,
+  input: {
+    userId: string;
+    sessionId: string;
+    callId: string;
+    bot: string;
+    question: string;
+    at: string;
+  },
+): Promise<VoiceAskResultV1> {
+  const target = botNamed(await host.listBots(), input.bot);
+  if (!target || target.status !== "active") {
+    return {
+      status: "refused",
+      message: `I can't ask ${input.bot} because that Bot isn't active.`,
+    };
+  }
+  const askId = await digestIdV1("voice-ask", [
+    input.userId,
+    input.sessionId,
+    input.callId,
+  ]);
+  const runId = await digestIdV1("agent", [input.userId, target.botId, askId]);
+  const requesterId = `voice-${input.sessionId}`;
+  const recorded = await ledger.recordAsk({
+    schemaVersion: 1,
+    type: "voice/ask",
+    askId,
+    sessionId: input.sessionId,
+    botId: target.botId,
+    botName: target.name,
+    question: input.question,
+    runId,
+    askedAt: input.at,
+  });
+  if (recorded.status === "refused") {
+    return { status: "refused", message: recorded.reason };
+  }
+  if (recorded.record.failed) {
+    return { status: "refused", message: recorded.record.failed.reason };
+  }
+  const accepted = {
+    status: "accepted" as const,
+    message: `I've asked ${target.name}. I'll tell you when ${target.name} answers.`,
+    askId,
+    runId,
+    botId: target.botId,
+    botName: target.name,
+  };
+  if (recorded.record.answered) return accepted;
+
+  const reservation = await host.reserveAgentTurn({
+    schemaVersion: 1,
+    userId: input.userId,
+    requesterId,
+    runId,
+    reservedAt: input.at,
+  });
+  if (reservation.status === "refused") {
+    const message =
+      "I can't ask another Bot right now because eight agent requests are already running.";
+    await ledger.recordFailed({
+      schemaVersion: 1,
+      type: "voice/failed",
+      askId,
+      botId: target.botId,
+      runId,
+      reason: message,
+      failedAt: input.at,
+    });
+    return { status: "refused", message };
+  }
+
+  host.defer(
+    host
+      .runAgent({
+        schemaVersion: 1,
+        userId: input.userId,
+        botId: target.botId,
+        command: {
+          runId,
+          sessionId: `${input.userId}:${target.botId}`,
+          acceptedAt: input.at,
+          text: input.question,
+          source: { kind: "voice", messageId: askId },
+        },
+      })
+      .then(() => undefined)
+      .catch(async (error) => {
+        const message = `I couldn't get an answer from ${target.name}: ${
+          error instanceof Error ? error.message : "the Bot run failed"
+        }`.slice(0, 2_000);
+        try {
+          await ledger.recordFailed({
+            schemaVersion: 1,
+            type: "voice/failed",
+            askId,
+            botId: target.botId,
+            runId,
+            reason: message,
+            failedAt: new Date().toISOString(),
+          });
+        } finally {
+          await host.releaseAgentTurn({
+            schemaVersion: 1,
+            userId: input.userId,
+            requesterId,
+            runId,
+          });
+        }
+      }),
+  );
+  return accepted;
+}

package/src/backend.ts

@@ -0,0 +1,63 @@
+import { defineGatewayContribution } from "@frockbot/kernel-contracts/contributions";
+import type { Plugin } from "cordis";
+
+export interface VoiceGatewayHostV1 {
+  readVoiceAssistant(userId: string): Promise<unknown>;
+  openVoiceAssistant(userId: string, request: Request): Promise<Response>;
+}
+
+export interface VoiceBackendRouteContributionV1 {
+  packageId: "voice";
+  route(
+    request: Request,
+    url: URL,
+    context: { userId?: string; client: "browser" | "desktop" },
+  ): Promise<Response | undefined>;
+}
+
+export function createVoiceBackendContributionV1(
+  host: VoiceGatewayHostV1,
+): VoiceBackendRouteContributionV1 {
+  return {
+    packageId: "voice",
+    async route(request, url, context) {
+      if (!context.userId) return undefined;
+      if (url.pathname === "/api/voice") {
+        if (request.method !== "GET") {
+          return Response.json(
+            { error: "method not allowed" },
+            { status: 405 },
+          );
+        }
+        return Response.json(await host.readVoiceAssistant(context.userId));
+      }
+      if (url.pathname === "/api/voice/assistant") {
+        if (request.method !== "GET") {
+          return Response.json(
+            { error: "method not allowed" },
+            { status: 405 },
+          );
+        }
+        return host.openVoiceAssistant(context.userId, request);
+      }
+      return undefined;
+    },
+  };
+}
+
+export namespace createVoiceBackendContributionV1 {
+  export function plugin(
+    host: VoiceGatewayHostV1,
+    lifecycle: { mount(value: VoiceBackendRouteContributionV1): () => void },
+  ): Plugin {
+    return () => lifecycle.mount(createVoiceBackendContributionV1(host));
+  }
+}
+
+export const backendContribution = defineGatewayContribution<
+  VoiceGatewayHostV1,
+  VoiceBackendRouteContributionV1
+>({
+  specifier: "@frockbot/plugin-voice/backend",
+  create: createVoiceBackendContributionV1.plugin,
+});

package/src/bot.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from "bun:test";
+import type { SessionEvent } from "@frockbot/kernel-contracts";
+import { VoiceAnswerOutboxV1, voiceAnswerFromSettledTurnV1 } from "./bot.js";
+
+describe("Voice Bot answer projection", () => {
+  test("takes the first text send from the settled Voice Turn", () => {
+    const delivery = voiceAnswerFromSettledTurnV1({
+      userId: "user-1",
+      botId: "research",
+      runId: "agent-1",
+      turn: 2,
+      origin: { kind: "voice", messageId: "ask-1" },
+      events: [
+        {
+          type: "send/to-user",
+          seq: 1,
+          timestamp: "2026-09-04T01:02:03.000Z",
+          turn: 2,
+          step: 1,
+          occurrenceId: "2:1:0",
+          payload: { type: "text", text: "First answer." },
+        },
+        {
+          type: "send/to-user",
+          seq: 2,
+          timestamp: "2026-09-04T01:02:04.000Z",
+          turn: 2,
+          step: 2,
+          occurrenceId: "2:2:0",
+          payload: { type: "text", text: "Second answer." },
+        },
+        {
+          type: "turn/end",
+          seq: 3,
+          timestamp: "2026-09-04T01:02:05.000Z",
+          turn: 2,
+          outcome: "completed",
+        },
+      ] as SessionEvent[],
+    });
+    expect(delivery).toMatchObject({
+      outcome: "answered",
+      askId: "ask-1",
+      answer: "First answer.",
+    });
+  });
+
+  test("keeps a delivery until the User ledger accepts it", async () => {
+    const values = new Map<string, unknown>();
+    const outbox = new VoiceAnswerOutboxV1({
+      get: (key) => Promise.resolve(values.get(key) as never),
+      put: (key, value) => {
+        values.set(key, value);
+        return Promise.resolve();
+      },
+      delete: (key) => Promise.resolve(values.delete(key)),
+    });
+    const delivery = {
+      schemaVersion: 1 as const,
+      outcome: "answered" as const,
+      userId: "user-1",
+      askId: "ask-1",
+      botId: "research",
+      runId: "agent-1",
+      answer: "Done.",
+      at: "2026-09-04T01:02:03.000Z",
+    };
+    await outbox.append(delivery);
+    await expect(
+      outbox.drain({
+        recordVoiceAnswer: () => Promise.reject(new Error("away")),
+      }),
+    ).rejects.toThrow("away");
+    expect(await outbox.state()).toMatchObject({ pending: 1 });
+    await outbox.drain({ recordVoiceAnswer: () => Promise.resolve() });
+    expect(await outbox.state()).toMatchObject({ pending: 0 });
+  });
+});