wizards 0.4.1 → 0.4.2

package/modules/calls/src/rules.ts

@@ -1,226 +0,0 @@
-import type { PluginRunReport } from "@engenty-wizards/plugin-sdk";
-import { clipText, type ThreadLang } from "@engenty-wizards/plugin-sdk/thread";
-
-/**
- * What the model works with on a call: its tools (one per command of the run), its rules in
- * the wizard's language, and the state of the run as text, which it reads after every change.
- */
-
-export const RUNNER = "call";
-
-/** The field kinds a voice can answer; the rest is texted as a link to the run page. */
-export const ASKS = [
-  "text",
-  "textarea",
-  "number",
-  "select",
-  "multiselect",
-  "date",
-  "email",
-  "url",
-  "toggle",
-  "location",
-];
-
-export const VOICES: Record<ThreadLang, string> = { de: "marin", en: "marin" };
-
-const object = (properties: Record<string, unknown>, required: string[] = []) => ({
-  type: "object",
-  properties,
-  required,
-  additionalProperties: false,
-});
-
-export const CALL_TOOLS = [
-  {
-    type: "function",
-    name: "get_state",
-    description:
-      "What the run waits for right now: the page with its fields (which are answered, which are still open, which need the screen), the review, or what the wizard is working on. Call it when unsure, and after the state changed.",
-    parameters: object({}),
-  },
-  {
-    type: "function",
-    name: "set_field",
-    description:
-      "Keeps the person's answer to one field of the current page. Call it once per field as soon as the person answered; for a choice give one of the options exactly.",
-    parameters: object(
-      {
-        field: { type: "string", description: "The field's id from the state." },
-        value: {
-          description:
-            "The answer: a string, a number, true/false for a toggle, or an array of options for a multiple choice.",
-        },
-      },
-      ["field", "value"],
-    ),
-  },
-  {
-    type: "function",
-    name: "submit_page",
-    description:
-      "Sends the current page once every required field that can be answered by voice has a value.",
-    parameters: object({}),
-  },
-  {
-    type: "function",
-    name: "accept_review",
-    description: "Accepts what the wizard made, when the person is happy with it.",
-    parameters: object({}),
-  },
-  {
-    type: "function",
-    name: "regenerate",
-    description: "Asks the wizard to make one of the shown outputs again, with what should change.",
-    parameters: object(
-      {
-        target: { type: "string", description: "The step id of the output, from the state." },
-        note: { type: "string", description: "What should change, in the person's words." },
-      },
-      ["target", "note"],
-    ),
-  },
-  {
-    type: "function",
-    name: "answer_ask",
-    description:
-      "Answers the question a running step asks before it changes something in a connected account: allow it, or skip it.",
-    parameters: object({ allow: { type: "boolean" } }, ["allow"]),
-  },
-  {
-    type: "function",
-    name: "send_link",
-    description:
-      "Texts the person a link to the run on their phone: for a page that needs the screen (a photo, a file, a signature), and for the result at the end. Say that a text is on its way.",
-    parameters: object({}),
-  },
-  {
-    type: "function",
-    name: "go_back",
-    description: "Goes back to the page before, when the person wants to change an earlier answer.",
-    parameters: object({}),
-  },
-  {
-    type: "function",
-    name: "choose_wizard",
-    description:
-      "Starts one of the wizards offered on this number, by its name, once the person said which.",
-    parameters: object({ name: { type: "string" } }, ["name"]),
-  },
-  {
-    type: "function",
-    name: "hang_up",
-    description: "Ends the call, after saying goodbye.",
-    parameters: object({}),
-  },
-] as const;
-
-export interface About {
-  title: string;
-  description?: string;
-}
-
-/** The rules the model speaks by. `lobby`: the wizards to choose from, when more than one is on. */
-export function instructions(lang: ThreadLang, about: About | null, lobby: string[]): string {
-  const de = lang === "de";
-  const who = about
-    ? [`${de ? "Du bist" : "You are"} ${about.title}.`, about.description].filter(Boolean).join(" ")
-    : de
-      ? "Du bist der Assistent dieser Nummer."
-      : "You are the assistant on this number.";
-  const choose = lobby.length
-    ? de
-      ? `Auf dieser Nummer gibt es mehrere Wizards: ${lobby.join(", ")}. Frag zuerst, welcher es sein soll, und rufe dann choose_wizard auf.`
-      : `This number offers several wizards: ${lobby.join(", ")}. Ask first which one it should be, then call choose_wizard.`
-    : "";
-  const none =
-    !about && !lobby.length
-      ? de
-        ? "Hier ist noch kein Wizard eingerichtet: sag das in einem Satz und beende das Gespräch mit hang_up."
-        : "No wizard is set up here yet: say so in one sentence and end the call with hang_up."
-      : "";
-  const rules = de
-    ? [
-        "Du führst ein Telefongespräch, das einen Wizard Schritt für Schritt ausfüllt. Die Person hat keinen Bildschirm vor sich: nur deine Stimme.",
-        "Sprich Deutsch, kurz und freundlich. Ein Satz, dann die nächste Frage. Begrüße die Person mit einem Satz und sag, worum es geht.",
-        "Frag ein Feld nach dem anderen, in der Reihenfolge des Zustands. Nach jeder Antwort rufst du set_field auf. Sind alle Felder beantwortet, die du per Sprache füllen kannst, rufst du submit_page auf.",
-        "Bei einer Auswahl nennst du die Möglichkeiten (höchstens vier auf einmal) und gibst genau eine davon weiter.",
-        "E-Mail-Adressen, Links und Zahlen wiederholst du zur Bestätigung, bevor du sie weitergibst.",
-        "Ein Feld, das den Bildschirm braucht (ein Foto, eine Datei, eine Unterschrift), kann die Person nur über einen Link ausfüllen: sag das, rufe send_link auf, und warte, bis der Zustand sich ändert.",
-        "Während der Wizard arbeitet, sagst du in einem Satz, was er gerade tut, und wartest. Erfinde nichts.",
-        "Bei einer Prüfung liest du den Text kurz zusammengefasst vor und fragst, ob er passt. Dann accept_review, oder regenerate mit dem Wunsch der Person.",
-        "Am Ende sagst du, was entstanden ist, rufst send_link auf, damit die Person alles als Link bekommt, verabschiedest dich und rufst hang_up auf.",
-      ]
-    : [
-        "You hold a phone conversation that fills in a wizard step by step. The person has no screen: only your voice.",
-        "Speak English, short and friendly. One sentence, then the next question. Greet the person in one sentence and say what this is about.",
-        "Ask one field at a time, in the order of the state. After each answer call set_field. When every field you can fill by voice is answered, call submit_page.",
-        "For a choice, name the options (at most four at a time) and pass exactly one of them on.",
-        "Read e-mail addresses, links and numbers back before passing them on.",
-        "A field that needs the screen (a photo, a file, a signature) can only be filled through a link: say so, call send_link, and wait until the state changes.",
-        "While the wizard works, say in one sentence what it is doing and wait. Never make anything up.",
-        "At a review, sum the text up in a few words and ask whether it fits. Then accept_review, or regenerate with what the person wants changed.",
-        "At the end, say what was made, call send_link so the person has it all as a link, say goodbye and call hang_up.",
-      ];
-  return [who, choose, none, "", ...rules].filter((line) => line !== undefined).join("\n");
-}
-
-/** The run as text for the model: the page with every field and what it knows, or what else it waits for. */
-export function stateText(
-  report: PluginRunReport | null,
-  draft: Record<string, unknown>,
-  lobby: string[],
-  asks: Set<string>,
-): string {
-  if (!report) {
-    return lobby.length
-      ? `[state]\nNo wizard chosen yet. Offered: ${lobby.join(", ")}. Ask which, then choose_wizard.`
-      : "[state]\nNo wizard is set up on this number.";
-  }
-  const lines = [`[state]`, `Status: ${report.status}.`];
-  const w = report.waitingFor;
-  if (report.status === "done") {
-    lines.push("The wizard is done. Say what was made, send_link, say goodbye, hang_up.");
-  } else if (report.status === "failed") {
-    lines.push(`The wizard stopped: ${report.error ?? "an error"}. Say so, send_link, hang_up.`);
-  } else if (!w) {
-    lines.push(
-      `The wizard is working on "${report.step?.title ?? "…"}". Say so in a sentence and wait; the state comes again when it is done.`,
-    );
-  } else if ("page" in w) {
-    lines.push(`Page "${w.title}" (id ${w.page}). Fields, in order:`);
-    for (const f of w.fields) {
-      if (f.shown === false) {
-        continue;
-      }
-      const value = f.id in draft ? draft[f.id] : f.value;
-      const has = value !== undefined && value !== null && value !== "";
-      const kind = f.options?.length ? `${f.kind}: ${f.options.join(" | ")}` : f.kind;
-      const how = asks.has(f.kind) ? "" : " — needs the screen: send_link";
-      lines.push(
-        `- ${f.id} "${f.label}" (${kind}${f.required ? ", required" : ""}${how}): ${has ? `answered: ${JSON.stringify(value)}` : "open"}${f.help ? ` — ${f.help}` : ""}`,
-      );
-    }
-  } else if ("review" in w) {
-    lines.push(`Review "${w.title}" (id ${w.review}) of: ${w.show.join(", ")}.`);
-    for (const output of report.outputs.filter((o) => w.show.includes(o.stepId))) {
-      lines.push(
-        `Output ${output.stepId} "${output.title}": ${output.text ? clipText(output.text, 1200) : output.json ? clipText(output.json, 600) : "(not text: a file)"}`,
-      );
-    }
-    lines.push("Ask whether it fits: accept_review, or regenerate with target and note.");
-  } else if (w.kind === "confirm") {
-    lines.push(
-      `Question (id ${w.ask}): ${w.reason} — ${w.action}. answer_ask with allow true or false.`,
-    );
-  } else {
-    lines.push("A sign-in is needed on the screen: send_link and wait.");
-  }
-  const made = report.outputs.filter((o) => o.text && (!w || !("review" in w)));
-  if (made.length && report.status === "done") {
-    for (const output of made.slice(-2)) {
-      lines.push(`Made "${output.title}": ${clipText(output.text ?? "", 600)}`);
-    }
-  }
-  return lines.join("\n");
-}

package/modules/calls/src/schema.ts

@@ -1,39 +0,0 @@
-import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
-
-/** The tables of migrations/, for Drizzle. Kept in step with the SQL by hand. */
-
-export const account = sqliteTable("calls_account", {
-  id: integer("id").primaryKey(),
-  twilioSid: text("twilio_sid").notNull(),
-  twilioToken: text("twilio_token").notNull(),
-  /** The OpenAI project the calls are handed to over SIP: proj_… */
-  openaiProject: text("openai_project").notNull(),
-  /** Signs what OpenAI posts about incoming calls: whsec_… */
-  openaiWebhookSecret: text("openai_webhook_secret").notNull(),
-  /** Where OpenAI takes the call: `eu` or `us`. */
-  region: text("region", { enum: ["eu", "us"] })
-    .notNull()
-    .default("eu"),
-  /** The Twilio number the links are texted from; none: no texts. */
-  smsFrom: text("sms_from"),
-  updatedAt: integer("updated_at", { mode: "timestamp_ms" }).notNull(),
-});
-
-export const call = sqliteTable("calls_call", {
-  /** Travels with the call as a SIP header; names it to OpenAI's webhook. */
-  token: text("token").primaryKey(),
-  /** The caller's number, E.164. */
-  caller: text("caller").notNull(),
-  /** `whatsapp`: a WhatsApp call over Meta's SIP; `phone`: a call to the Twilio number. */
-  channel: text("channel", { enum: ["whatsapp", "phone"] }).notNull(),
-  /** What a WhatsApp call button or deep link carried: a wizard's share token. */
-  payload: text("payload"),
-  twilioCallSid: text("twilio_call_sid"),
-  openaiCallId: text("openai_call_id"),
-  runId: text("run_id"),
-  status: text("status", { enum: ["ringing", "live", "done"] })
-    .notNull()
-    .default("ringing"),
-  createdAt: integer("created_at", { mode: "timestamp_ms" }).notNull(),
-  updatedAt: integer("updated_at", { mode: "timestamp_ms" }).notNull(),
-});

package/modules/calls/src/session.ts

@@ -1,353 +0,0 @@
-import type { PluginRunReport, PluginRuns } from "@engenty-wizards/plugin-sdk";
-import { type ThreadLang, toIso } from "@engenty-wizards/plugin-sdk/thread";
-import { ASKS, RUNNER, stateText } from "./rules";
-
-/**
- * One call: the run it drives, the answers collected for the current page, and the tools the
- * model calls over the WebSocket. The model hears the state of the run as text after every
- * change, and a link is texted for what a voice cannot do.
- */
-
-export interface Offered {
-  wizardId: string;
-  token: string;
-  title: string;
-  lang: ThreadLang;
-}
-
-export interface SessionDeps {
-  runs: PluginRuns;
-  /** Sends one event to the model. */
-  send(event: Record<string, unknown>): void;
-  /** Texts the caller. */
-  text(body: string): Promise<void>;
-  hangUp(): Promise<void>;
-  /** Hear the run, and call `changed` when it moves. */
-  watch(runId: string): void;
-  unwatch(runId: string): void;
-  log: { warn(...args: unknown[]): void };
-}
-
-const asks = new Set(ASKS);
-
-const YES = new Set(["true", "yes", "ja", "1", "on"]);
-const NO = new Set(["false", "no", "nein", "0", "off"]);
-
-export class CallSession {
-  runId: string | null = null;
-  lang: ThreadLang;
-  private draft: { step: string; values: Record<string, unknown> } | null = null;
-  private report: PluginRunReport | null = null;
-  private linked = false;
-  private ended = false;
-
-  constructor(
-    private readonly deps: SessionDeps,
-    readonly caller: string,
-    readonly channel: "whatsapp" | "phone",
-    private lobby: Offered[],
-    lang: ThreadLang,
-  ) {
-    this.lang = lang;
-  }
-
-  /** The wizard the call runs, started; the rules are made from it. */
-  async start(wizard: Offered): Promise<PluginRunReport | null> {
-    this.lang = wizard.lang;
-    // On WhatsApp the person is the same as in the thread: the number without its plus.
-    const id = this.channel === "whatsapp" ? this.caller.replace(/^\+/, "") : this.caller;
-    const { runId } = await this.deps.runs.start({
-      token: wizard.token,
-      person: { channel: this.channel, id },
-      runner: RUNNER,
-    });
-    this.runId = runId;
-    this.lobby = [];
-    this.draft = null;
-    this.linked = false;
-    return this.look(5);
-  }
-
-  /** The state as the model reads it. */
-  state(): string {
-    return stateText(
-      this.report,
-      this.draft?.values ?? {},
-      this.lobby.map((w) => w.title),
-      asks,
-    );
-  }
-
-  /** Tells the model the state and lets it speak: at the start, and when the run changed. */
-  async hello(): Promise<void> {
-    await this.look(0);
-    this.say(
-      this.state(),
-      this.lang === "de" ? "Begrüße die Person und beginne." : "Greet the person and begin.",
-    );
-  }
-
-  /** The run moved while nobody spoke: the model hears the new state and says what changed. */
-  async changed(): Promise<void> {
-    if (this.ended) {
-      return;
-    }
-    await this.look(0);
-    if (this.report?.status === "done" && !this.linked) {
-      await this.link().catch((err) => this.deps.log.warn("the link was not texted:", err));
-    }
-    this.say(
-      this.state(),
-      this.lang === "de"
-        ? "Sag in einem Satz, was sich getan hat, und mach weiter."
-        : "Say in one sentence what happened, and go on.",
-    );
-  }
-
-  /** The model called a tool: what it gets back. */
-  async call(name: string, args: Record<string, unknown>): Promise<string> {
-    switch (name) {
-      case "get_state":
-        await this.look(0);
-        return this.state();
-      case "choose_wizard": {
-        const wanted = String(args.name ?? "").toLowerCase();
-        const wizard =
-          this.lobby.find((w) => w.title.toLowerCase() === wanted) ??
-          this.lobby.find(
-            (w) => w.title.toLowerCase().includes(wanted) || wanted.includes(w.title.toLowerCase()),
-          );
-        if (!wizard) {
-          return `No wizard called "${args.name}". Offered: ${this.lobby.map((w) => w.title).join(", ")}.`;
-        }
-        await this.start(wizard);
-        return this.state();
-      }
-      case "send_link":
-        return this.link();
-      case "hang_up":
-        this.ended = true;
-        await this.deps.hangUp();
-        return "The call is over.";
-    }
-    if (!this.runId) {
-      return "No wizard runs yet: choose_wizard first.";
-    }
-    switch (name) {
-      case "set_field":
-        return this.setField(String(args.field ?? ""), args.value);
-      case "submit_page":
-        return this.submit();
-      case "accept_review":
-        return this.command(async (w) => {
-          if (!w || !("review" in w)) {
-            return "Nothing to review right now.";
-          }
-          await this.deps.runs.review(this.runId!, w.review, { type: "accept" });
-          return null;
-        });
-      case "regenerate":
-        return this.command(async (w) => {
-          if (!w || !("review" in w)) {
-            return "Nothing to review right now.";
-          }
-          await this.deps.runs.review(this.runId!, w.review, {
-            type: "regenerate",
-            target: String(args.target ?? w.show[0] ?? ""),
-            note: String(args.note ?? ""),
-          });
-          return null;
-        });
-      case "answer_ask":
-        return this.command(async (w) => {
-          if (!w || !("ask" in w)) {
-            return "No question is open right now.";
-          }
-          await this.deps.runs.answerAsk(this.runId!, w.ask, args.allow ? "allow" : "skip");
-          return null;
-        });
-      case "go_back":
-        return this.command(async () => {
-          await this.deps.runs.control(this.runId!, "back");
-          this.draft = null;
-          return null;
-        });
-      default:
-        return `Unknown tool ${name}.`;
-    }
-  }
-
-  stop(): void {
-    this.ended = true;
-    if (this.runId) {
-      this.deps.unwatch(this.runId);
-    }
-  }
-
-  // ── Tools ──────────────────────────────────────────────────────────────────
-
-  private async setField(id: string, raw: unknown): Promise<string> {
-    await this.look(0);
-    const w = this.report?.waitingFor;
-    if (!w || !("page" in w)) {
-      return "No page is open right now. get_state says what the run waits for.";
-    }
-    const field = w.fields.find((f) => f.id === id && f.shown !== false);
-    if (!field) {
-      return `No open field "${id}" on this page.`;
-    }
-    if (!asks.has(field.kind)) {
-      return `"${field.label}" needs the screen: send_link, then wait.`;
-    }
-    if (!this.draft || this.draft.step !== w.page) {
-      this.draft = { step: w.page, values: {} };
-    }
-    const value = this.coerce(field.kind, field.options ?? [], raw);
-    if (value instanceof Error) {
-      return value.message;
-    }
-    this.draft.values[id] = value;
-    // A later field's condition may read this answer: the page is read again with the draft.
-    await this.look(0);
-    return this.state();
-  }
-
-  /** The answer as the page takes it, or what is wrong with it. */
-  private coerce(kind: string, options: string[], raw: unknown): unknown | Error {
-    const text = raw === undefined || raw === null ? "" : String(raw).trim();
-    switch (kind) {
-      case "select": {
-        const found = options.find((o) => o.toLowerCase() === text.toLowerCase());
-        return found ?? new Error(`Pick one of: ${options.join(" | ")}.`);
-      }
-      case "multiselect": {
-        const given = Array.isArray(raw) ? raw.map(String) : text.split(/[,;]+/);
-        const picked = given
-          .map((g) => options.find((o) => o.toLowerCase() === g.trim().toLowerCase()))
-          .filter((o): o is string => Boolean(o));
-        return picked.length ? picked : new Error(`Pick from: ${options.join(" | ")}.`);
-      }
-      case "toggle": {
-        if (typeof raw === "boolean") {
-          return raw;
-        }
-        const lower = text.toLowerCase();
-        return YES.has(lower) ? true : NO.has(lower) ? false : new Error("true or false.");
-      }
-      case "number": {
-        const n = Number(text.replace(",", "."));
-        return Number.isFinite(n) ? n : new Error("A number.");
-      }
-      case "date": {
-        const iso = toIso(text);
-        return iso ?? new Error("A date as YYYY-MM-DD or DD.MM.YYYY.");
-      }
-      case "location":
-        return text ? { label: text } : new Error("An address.");
-      default:
-        return text || new Error("An answer.");
-    }
-  }
-
-  private async submit(): Promise<string> {
-    await this.look(0);
-    const w = this.report?.waitingFor;
-    if (!w || !("page" in w)) {
-      return "No page is open right now.";
-    }
-    const values = this.draft?.step === w.page ? this.draft.values : {};
-    const missing = w.fields.filter(
-      (f) =>
-        f.shown !== false &&
-        f.required &&
-        asks.has(f.kind) &&
-        (values[f.id] === undefined || values[f.id] === null || values[f.id] === ""),
-    );
-    if (missing.length) {
-      return `Still open: ${missing.map((f) => `${f.id} "${f.label}"`).join(", ")}. Ask for them first.`;
-    }
-    if (w.fields.some((f) => f.shown !== false && !asks.has(f.kind))) {
-      return "This page has a field that needs the screen: send_link and wait until the state changes.";
-    }
-    try {
-      await this.deps.runs.answerPage(this.runId!, w.page, values);
-    } catch (err) {
-      const fields = (err as { data?: { fields?: { field: string; message: string }[] } }).data
-        ?.fields;
-      return fields?.length
-        ? `Not accepted: ${fields.map((f) => `${f.field}: ${f.message}`).join("; ")}. Ask again.`
-        : `Not accepted: ${(err as Error).message}`;
-    }
-    this.draft = null;
-    await this.look(15);
-    return this.state();
-  }
-
-  /** A command on the run, then the new state. `act` answers with text where the command does not fit. */
-  private async command(
-    act: (waiting: PluginRunReport["waitingFor"]) => Promise<string | null>,
-  ): Promise<string> {
-    await this.look(0);
-    try {
-      const answer = await act(this.report?.waitingFor);
-      if (answer) {
-        return answer;
-      }
-    } catch (err) {
-      return `Not accepted: ${(err as Error).message}`;
-    }
-    await this.look(15);
-    return this.state();
-  }
-
-  /** Texts the link to the run page, once per state; the run is watched from then on. */
-  private async link(): Promise<string> {
-    if (!this.runId) {
-      return "No wizard runs yet.";
-    }
-    const url = await this.deps.runs.handoffUrl(this.runId);
-    const done = this.report?.status === "done";
-    await this.deps.text(
-      this.lang === "de"
-        ? done
-          ? `Fertig! Alles liegt hier: ${url}`
-          : `Hier geht es weiter: ${url}`
-        : done
-          ? `Done! Everything is here: ${url}`
-          : `It goes on here: ${url}`,
-    );
-    this.linked = done;
-    this.deps.watch(this.runId);
-    return "The link was texted. Say so; then wait for the state to change.";
-  }
-
-  // ── The run ────────────────────────────────────────────────────────────────
-
-  /** Reads the run as it stands, waiting a little while it works. */
-  private async look(waitSeconds: number): Promise<PluginRunReport | null> {
-    if (!this.runId) {
-      this.report = null;
-      return null;
-    }
-    this.report = await this.deps.runs.report(this.runId, {
-      waitSeconds,
-      draft: this.draft?.values,
-    });
-    if (!this.report.waitingFor && this.report.status === "running") {
-      this.deps.watch(this.runId);
-    }
-    if (this.report.status === "done" || this.report.status === "failed") {
-      this.deps.unwatch(this.runId);
-    }
-    return this.report;
-  }
-
-  /** A message with the state, and a turn of the model with what to do about it. */
-  private say(state: string, instructions: string): void {
-    this.deps.send({
-      type: "conversation.item.create",
-      item: { type: "message", role: "user", content: [{ type: "input_text", text: state }] },
-    });
-    this.deps.send({ type: "response.create", response: { instructions } });
-  }
-}