@frockbot/plugin-voice 0.0.0 → 0.3.21

package/src/tools.ts

@@ -0,0 +1,254 @@
+import type { VoicePendingAnswerV1, VoiceToolNameV1 } from "./shared.js";
+
+export interface VoiceBotSummaryV1 {
+  botId: string;
+  name: string;
+  status: "active" | "archived";
+}
+
+export interface VoiceBotActivityV1 {
+  botId: string;
+  since: string;
+  runs: Array<{
+    runId: string;
+    status: string;
+    startedAt: string;
+    partialText?: string;
+  }>;
+  tasks: Array<{ taskId: string; title: string; status: string }>;
+  pendingInbox: number;
+}
+
+export interface VoiceMemoryHitV1 {
+  scope: "user" | "bot";
+  botId?: string;
+  path: string;
+  snippet: string;
+  score: number;
+}
+
+export interface VoiceToolHostV1 {
+  listBots(): Promise<readonly VoiceBotSummaryV1[]>;
+  botActivity(botId: string, since?: string): Promise<VoiceBotActivityV1>;
+  memorySearch(input: {
+    query: string;
+    botId?: string;
+  }): Promise<readonly VoiceMemoryHitV1[]>;
+  pendingAnswers(): Promise<readonly VoicePendingAnswerV1[]>;
+  askBot(input: {
+    sessionId: string;
+    callId: string;
+    bot: string;
+    question: string;
+    at: string;
+  }): Promise<unknown>;
+}
+
+export interface VoiceToolExecutionContextV1 {
+  sessionId: string;
+  callId: string;
+  at: string;
+}
+
+export interface GeminiFunctionDeclarationV1 {
+  name: VoiceToolNameV1;
+  description: string;
+  parameters: Record<string, unknown>;
+}
+
+export interface VoiceToolSpecV1 {
+  declaration: GeminiFunctionDeclarationV1;
+  label(args: Record<string, unknown>): string;
+  execute(
+    host: VoiceToolHostV1,
+    args: Record<string, unknown>,
+    context: VoiceToolExecutionContextV1,
+  ): Promise<unknown>;
+}
+
+function noExtraArgs(args: Record<string, unknown>): void {
+  if (Object.keys(args).length > 0)
+    throw new Error("tool arguments are invalid");
+}
+
+function stringArg(
+  args: Record<string, unknown>,
+  name: string,
+  max: number,
+  required = true,
+): string | undefined {
+  const value = args[name];
+  if (value === undefined && !required) return undefined;
+  if (
+    typeof value !== "string" ||
+    value.trim().length === 0 ||
+    value.length > max
+  ) {
+    throw new Error(`${name} must be a bounded string`);
+  }
+  return value.trim();
+}
+
+function only(args: Record<string, unknown>, names: readonly string[]): void {
+  const allowed = new Set(names);
+  if (Object.keys(args).some((name) => !allowed.has(name))) {
+    throw new Error("tool arguments are invalid");
+  }
+}
+
+function boundedJson(value: unknown): unknown {
+  const json = JSON.stringify(value);
+  if (json.length <= 16_000) return value;
+  return { truncated: true, summary: json.slice(0, 15_000) };
+}
+
+/** The transport remains table-driven as Voice adds effectful tools. */
+export const VOICE_TOOL_TABLE_V1: Readonly<
+  Record<VoiceToolNameV1, VoiceToolSpecV1>
+> = {
+  list_bots: {
+    declaration: {
+      name: "list_bots",
+      description: "List this person's Bots and whether each is active.",
+      parameters: { type: "OBJECT", properties: {} },
+    },
+    label: () => "Checked your Bots",
+    async execute(host, args) {
+      noExtraArgs(args);
+      return { bots: (await host.listBots()).slice(0, 50) };
+    },
+  },
+  bot_activity: {
+    declaration: {
+      name: "bot_activity",
+      description:
+        "Read one Bot's recent runs, in-progress reply, running tasks, and waiting inbox items.",
+      parameters: {
+        type: "OBJECT",
+        properties: {
+          bot: { type: "STRING", description: "The Bot id." },
+          since: {
+            type: "STRING",
+            description: "Optional ISO timestamp for the oldest activity.",
+          },
+        },
+        required: ["bot"],
+      },
+    },
+    label: (args) => `Checked ${String(args.bot ?? "a Bot")}'s activity`,
+    async execute(host, args) {
+      only(args, ["bot", "since"]);
+      const botId = stringArg(args, "bot", 128)!;
+      const since = stringArg(args, "since", 64, false);
+      if (since && !Number.isFinite(Date.parse(since))) {
+        throw new Error("since must be an ISO timestamp");
+      }
+      return boundedJson(await host.botActivity(botId, since));
+    },
+  },
+  memory_search: {
+    declaration: {
+      name: "memory_search",
+      description:
+        "Search durable User memory and Bot memory without waking a Computer.",
+      parameters: {
+        type: "OBJECT",
+        properties: {
+          query: { type: "STRING", description: "What to look for." },
+          bot: {
+            type: "STRING",
+            description: "Optional Bot id. Omit to search all Bot tiers.",
+          },
+        },
+        required: ["query"],
+      },
+    },
+    label: () => "Searched memory",
+    async execute(host, args) {
+      only(args, ["query", "bot"]);
+      return {
+        results: (
+          await host.memorySearch({
+            query: stringArg(args, "query", 512)!,
+            ...(stringArg(args, "bot", 128, false)
+              ? { botId: stringArg(args, "bot", 128, false)! }
+              : {}),
+          })
+        ).slice(0, 24),
+      };
+    },
+  },
+  pending_answers: {
+    declaration: {
+      name: "pending_answers",
+      description: "Read Bot answers waiting to be spoken to this person.",
+      parameters: { type: "OBJECT", properties: {} },
+    },
+    label: () => "Checked answers waiting for you",
+    async execute(host, args) {
+      noExtraArgs(args);
+      return { answers: (await host.pendingAnswers()).slice(0, 32) };
+    },
+  },
+  ask_bot: {
+    declaration: {
+      name: "ask_bot",
+      description:
+        "Ask one active Bot a question on this person's behalf. The Bot answers later; do not wait for it.",
+      parameters: {
+        type: "OBJECT",
+        properties: {
+          bot: {
+            type: "STRING",
+            description: "The Bot id or exact Bot name.",
+          },
+          question: {
+            type: "STRING",
+            description: "The complete question to send to the Bot.",
+          },
+        },
+        required: ["bot", "question"],
+      },
+    },
+    label: (args) => `Asked ${String(args.bot ?? "a Bot")}`,
+    async execute(host, args, context) {
+      only(args, ["bot", "question"]);
+      return host.askBot({
+        ...context,
+        bot: stringArg(args, "bot", 128)!,
+        question: stringArg(args, "question", 2_000)!,
+      });
+    },
+  },
+};
+
+export const VOICE_FUNCTION_DECLARATIONS_V1 = Object.values(
+  VOICE_TOOL_TABLE_V1,
+).map((tool) => tool.declaration);
+
+export async function executeVoiceToolV1(
+  host: VoiceToolHostV1,
+  input: {
+    name: string;
+    args?: unknown;
+    context?: VoiceToolExecutionContextV1;
+  },
+): Promise<{ name: VoiceToolNameV1; label: string; result: unknown }> {
+  const tool = VOICE_TOOL_TABLE_V1[input.name as VoiceToolNameV1];
+  if (!tool) throw new Error("That Voice tool is unavailable.");
+  const args = input.args ?? {};
+  if (!args || typeof args !== "object" || Array.isArray(args)) {
+    throw new Error("tool arguments must be an object");
+  }
+  const record = args as Record<string, unknown>;
+  const context = input.context ?? {
+    sessionId: "voice-tool",
+    callId: "voice-tool-call",
+    at: new Date(0).toISOString(),
+  };
+  return {
+    name: input.name as VoiceToolNameV1,
+    label: tool.label(record).slice(0, 160),
+    result: await tool.execute(host, record, context),
+  };
+}

package/src/user.ts

@@ -0,0 +1,145 @@
+import { defineUserBackendContribution } from "@frockbot/kernel-contracts/contributions";
+import type { Plugin } from "cordis";
+import { askBotFromVoiceV1, type VoiceAskHostV1 } from "./ask.js";
+import { VoiceLedgerV1, type VoiceLedgerStorageV1 } from "./ledger.js";
+import { executeVoiceToolV1, type VoiceToolHostV1 } from "./tools.js";
+import type {
+  VoiceOfflineReasonV1,
+  VoicePendingAnswerV1,
+  VoiceToolCallEntryV1,
+  VoiceTranscriptEntryV1,
+} from "./shared.js";
+
+export interface VoiceUserBackendHostV1
+  extends Omit<VoiceToolHostV1, "askBot">, VoiceAskHostV1 {
+  storage: VoiceLedgerStorageV1;
+  userId(): string;
+}
+
+export class VoiceUserBackendContributionV1 {
+  readonly packageId = "voice";
+  readonly ledger: VoiceLedgerV1;
+
+  constructor(private readonly host: VoiceUserBackendHostV1) {
+    this.ledger = new VoiceLedgerV1(host.storage);
+  }
+
+  start(input: { sessionId: string; deviceId: string; at: string }) {
+    return this.ledger.start(input);
+  }
+
+  end(input: {
+    sessionId: string;
+    at: string;
+    reason: VoiceOfflineReasonV1;
+    seconds: number;
+  }) {
+    return this.ledger.end(input);
+  }
+
+  saveResumptionHandle(input: {
+    sessionId: string;
+    handle: string;
+    at: string;
+  }) {
+    return this.ledger.saveResumptionHandle(input);
+  }
+
+  appendTranscript(sessionId: string, entry: VoiceTranscriptEntryV1) {
+    return this.ledger.appendTranscript(sessionId, entry);
+  }
+
+  async executeTool(input: {
+    sessionId: string;
+    callId: string;
+    name: string;
+    args?: unknown;
+    at: string;
+  }) {
+    const executed = await executeVoiceToolV1(
+      {
+        ...this.host,
+        askBot: (ask) =>
+          askBotFromVoiceV1(this.ledger, this.host, {
+            userId: this.host.userId(),
+            ...ask,
+          }),
+      },
+      {
+        name: input.name,
+        args: input.args,
+        context: {
+          sessionId: input.sessionId,
+          callId: input.callId,
+          at: input.at,
+        },
+      },
+    );
+    await this.ledger.appendToolCall(input.sessionId, {
+      schemaVersion: 1,
+      id: input.callId,
+      name: executed.name,
+      label: executed.label,
+      at: input.at,
+    } satisfies VoiceToolCallEntryV1);
+    return executed;
+  }
+
+  recordPendingAnswer(answer: VoicePendingAnswerV1) {
+    return this.ledger.recordPendingAnswer(answer);
+  }
+
+  recordAnswerDelivery(delivery: import("./shared.js").VoiceAnswerDeliveryV1) {
+    return delivery.outcome === "answered"
+      ? this.ledger.recordAnswered({
+          schemaVersion: 1,
+          type: "voice/answered",
+          askId: delivery.askId,
+          botId: delivery.botId,
+          runId: delivery.runId,
+          answer: delivery.answer,
+          answeredAt: delivery.at,
+        })
+      : this.ledger.recordFailed({
+          schemaVersion: 1,
+          type: "voice/failed",
+          askId: delivery.askId,
+          botId: delivery.botId,
+          runId: delivery.runId,
+          reason: delivery.reason,
+          failedAt: delivery.at,
+        });
+  }
+
+  markBriefed(input: {
+    askIds: readonly string[];
+    sessionId: string;
+    at: string;
+  }) {
+    return this.ledger.markBriefed(input);
+  }
+
+  view() {
+    return this.ledger.view();
+  }
+}
+
+export interface VoiceUserApplicationHostV1 {
+  voice: VoiceUserBackendHostV1;
+}
+
+export function createVoiceUserBackendPluginV1(
+  host: VoiceUserBackendHostV1,
+  lifecycle: { mount(value: VoiceUserBackendContributionV1): () => void },
+): Plugin {
+  return () => lifecycle.mount(new VoiceUserBackendContributionV1(host));
+}
+
+export const userContribution = defineUserBackendContribution<
+  VoiceUserApplicationHostV1,
+  VoiceUserBackendContributionV1
+>({
+  specifier: "@frockbot/plugin-voice/user",
+  create: (host, lifecycle) =>
+    createVoiceUserBackendPluginV1(host.voice, lifecycle),
+});

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "types": ["bun", "vite/client"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.vue"]
+}

package/README.md

@@ -1,3 +0,0 @@
-# @frockbot/plugin-voice
-
-Placeholder reserving this name. See https://github.com/timoconnellaus/frockbot.