Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

11.6 KB
Raw Blame
// Plain-words view of a custom workflow: its schedule, and what a revision
// changes compared with the saved version. Pure (type imports only), so the
// node test runner can load it.
import type { DynamicStep, DynamicWorkflowDef } from "./api";

const DAYS: Record<string, string> = {
  mon: "Monday",
  tue: "Tuesday",
  wed: "Wednesday",
  thu: "Thursday",
  fri: "Friday",
  sat: "Saturday",
  sun: "Sunday",
};

/** Plain-words rendering of the cadence DSL (daily@HH:MM, weekly@DOW@HH:MM, quarterly@DD-HH:MM). */
export function describeCadence(cadence: string | null | undefined): string {
  if (!cadence) return "Only when you run it";
  const parts = cadence.split("@");
  if (parts[0] === "daily" && parts[1]) return `Every day at ${parts[1]} UTC`;
  if (parts[0] === "weekly" && parts[1] && parts[2]) {
    const day = DAYS[parts[1].toLowerCase()] ?? parts[1];
    return `Every ${day} at ${parts[2]} UTC`;
  }
  if (parts[0] === "quarterly" && parts[1]) {
    const [dd, time] = parts[1].split("-");
    return `Quarterly on day ${Number(dd)} at ${time} UTC`;
  }
  return cadence;
}

/** How to name people, specialists and tools — supplied by the page. */
export interface ChangeLabels {
  person: (id: number | null | undefined) => string;
  specialist: (key: string | undefined) => string;
  tool: (name: string) => string;
}

const ON_TIMEOUT: Record<string, string> = {
  escalate: "flags it for you",
  auto_proceed: "carries on as if approved",
  fail: "stops the run",
};

function list(items: string[]): string {
  if (items.length <= 1) return items.join("");
  return `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
}

function stepWho(step: DynamicStep, labels: ChangeLabels): string {
  if (step.kind === "specialist") return labels.specialist(step.specialist);
  if (step.kind === "approval_gate") return `sign-off from ${labels.person(step.person_id)}`;
  if (step.kind === "action")
    return `uses ${step.tools.length} ${step.tools.length === 1 ? "tool" : "tools"}`;
  return "final write-up";
}

function stepText(step: DynamicStep): string {
  if (step.kind === "approval_gate") return step.question;
  if (step.kind === "synthesis") return step.instructions ?? "";
  return step.goal;
}

// What a sign-off asks for. Anything but approve/reject is a question, not
// permission: the run carries on whatever the answer, so say so.
const REPLY_SHAPE: Record<string, string> = {
  approve_reject: "an approve/reject decision (the run stops unless approved)",
  free_text: "a written reply (the run continues whatever the answer)",
  numeric: "a number (the run continues whatever the answer)",
  document: "a document (the run continues whatever the answer)",
};
const REPLY_SHAPE_SHORT: Record<string, string> = {
  approve_reject: "an approve/reject decision",
  free_text: "a written reply",
  numeric: "a number",
  document: "a document",
};

// Fields each step kind's sentences cover, and the defaults the server fills
// in, so a field the model left out reads the same as its default. Any other
// field that differs still gets a line (see `otherFieldsDiffer`).
const STEP_DEFAULTS: Record<string, Record<string, unknown>> = {
  common: { kind: undefined, id: undefined, title: undefined, description: "" },
  specialist: { specialist: undefined, goal: undefined, rag_query: "", playbook: "" },
  approval_gate: {
    person_id: undefined,
    question: undefined,
    timeout_hours: 48,
    on_timeout: "escalate",
    expected_reply_shape: "approve_reject",
  },
  synthesis: { instructions: "", specialist: "cso" },
  action: { goal: undefined, tools: undefined, max_tool_calls: 20 },
};

function field(obj: object, key: string, defaults: Record<string, unknown>): unknown {
  const v = (obj as Record<string, unknown>)[key];
  return v === undefined || v === null ? defaults[key] : v;
}

/** True when a field not in `covered` differs (a field this file doesn't know yet). */
function otherFieldsDiffer(a: object, b: object, covered: string[]): boolean {
  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
  for (const k of keys) {
    if (covered.includes(k)) continue;
    const va = (a as Record<string, unknown>)[k];
    const vb = (b as Record<string, unknown>)[k];
    if (JSON.stringify(va ?? null) !== JSON.stringify(vb ?? null)) return true;
  }
  return false;
}

function stepChanges(a: DynamicStep, b: DynamicStep, labels: ChangeLabels): string[] {
  const out: string[] = [];
  const name = `“${b.title}”`;
  const defaults = { ...STEP_DEFAULTS.common, ...STEP_DEFAULTS[b.kind] };
  const get = (s: DynamicStep, k: string) => field(s, k, defaults);
  if (a.title !== b.title) out.push(`Renamed step “${a.title}” to ${name}`);
  if (a.kind === "specialist" && b.kind === "specialist" && a.specialist !== b.specialist)
    out.push(`${name} is now handled by ${labels.specialist(b.specialist)} instead of ${labels.specialist(a.specialist)}`);
  if (a.kind === "synthesis" && b.kind === "synthesis" && get(a, "specialist") !== get(b, "specialist"))
    out.push(`${name} is now written by ${labels.specialist(b.specialist)} instead of ${labels.specialist(a.specialist)}`);
  if (a.kind === "approval_gate" && b.kind === "approval_gate") {
    if (a.person_id !== b.person_id)
      out.push(`${name}: sign-off from ${labels.person(b.person_id)} instead of ${labels.person(a.person_id)}`);
    const sa = String(get(a, "expected_reply_shape"));
    const sb = String(get(b, "expected_reply_shape"));
    if (sa !== sb)
      out.push(`${name} now asks for ${REPLY_SHAPE[sb] ?? sb}, not ${REPLY_SHAPE_SHORT[sa] ?? sa}`);
    const ha = get(a, "timeout_hours");
    const hb = get(b, "timeout_hours");
    if (ha !== hb) out.push(`${name}: waits up to ${hb} hours for an answer (was ${ha})`);
    const tb = String(get(b, "on_timeout"));
    if (get(a, "on_timeout") !== tb) out.push(`${name}: if nobody answers, it now ${ON_TIMEOUT[tb] ?? tb}`);
  }
  if (a.kind === "action" && b.kind === "action") {
    const added = b.tools.filter((t) => !a.tools.includes(t));
    const removed = a.tools.filter((t) => !b.tools.includes(t));
    if (added.length) out.push(`${name} can now use ${list(added.map(labels.tool))}`);
    if (removed.length) out.push(`${name} no longer uses ${list(removed.map(labels.tool))}`);
    const ma = get(a, "max_tool_calls");
    const mb = get(b, "max_tool_calls");
    if (ma !== mb) out.push(`${name} may now use tools up to ${mb} times a run (was ${ma})`);
  }
  if (a.kind === "specialist" && b.kind === "specialist") {
    if (get(a, "playbook") !== get(b, "playbook"))
      out.push(
        b.playbook
          ? `${name} now follows the “${b.playbook}” playbook`
          : `${name} no longer follows a playbook`
      );
    if (get(a, "rag_query") !== get(b, "rag_query"))
      out.push(`${name} looks up different things in your documents`);
  }
  if (stepText(a).trim() !== stepText(b).trim()) out.push(`New instructions for ${name}`);
  if (String(get(a, "description")).trim() !== String(get(b, "description")).trim())
    out.push(`Updated the description of ${name}`);
  if (otherFieldsDiffer(a, b, Object.keys(defaults))) out.push(`Changed other settings of ${name}`);
  return out;
}

// Top-level fields covered above, plus ones the server owns (not changes).
const TOP_LEVEL_FIELDS = [
  "name", "title", "description", "section", "estimated_minutes", "input_fields", "steps",
  "cadence", "cadence_person_id", "is_active", "created_at", "updated_at", "owner_person_id",
];

/** Plain words for what a sign-off asks for (shown on the review card). */
export function replyShapeLabel(shape: string | undefined): string | null {
  if (!shape || shape === "approve_reject") return null;
  return REPLY_SHAPE_SHORT[shape] ?? shape;
}

/**
 * What `after` changes compared with `before`, one plain sentence per change.
 * Empty when nothing a person would notice changed.
 */
export function describeChanges(
  before: DynamicWorkflowDef,
  after: DynamicWorkflowDef,
  labels: ChangeLabels
): string[] {
  const out: string[] = [];

  if (before.title !== after.title) out.push(`Renamed “${before.title}” to “${after.title}”`);
  if ((before.description ?? "").trim() !== (after.description ?? "").trim())
    out.push("Updated the description");
  if (before.section !== after.section) out.push(`Moved from ${before.section} to ${after.section}`);
  if (before.estimated_minutes !== after.estimated_minutes)
    out.push(`Expected to take about ${after.estimated_minutes} min (was ${before.estimated_minutes})`);

  // Schedule.
  const ca = before.cadence || null;
  const cb = after.cadence || null;
  if (ca !== cb) {
    out.push(
      cb
        ? `Schedule: ${describeCadence(cb)}, sent to ${labels.person(after.cadence_person_id)} (was: ${describeCadence(ca)})`
        : `Schedule: only when you run it (was: ${describeCadence(ca)})`
    );
  } else if (cb && before.cadence_person_id !== after.cadence_person_id) {
    out.push(
      `Scheduled results go to ${labels.person(after.cadence_person_id)} instead of ${labels.person(before.cadence_person_id)}`
    );
  }

  // Inputs, matched by field name.
  const fieldsBefore = new Map(before.input_fields.map((f) => [f.name, f]));
  const fieldsAfter = new Map(after.input_fields.map((f) => [f.name, f]));
  for (const f of after.input_fields) {
    const old = fieldsBefore.get(f.name);
    if (!old) {
      out.push(`Asks for “${f.label}” on each run${f.required === false ? " (optional)" : ""}`);
      continue;
    }
    if (old.label !== f.label) out.push(`Input “${old.label}” is now called “${f.label}”`);
    if ((old.required !== false) !== (f.required !== false))
      out.push(`“${f.label}” is now ${f.required === false ? "optional" : "required"}`);
    if (
      (old.description ?? "").trim() !== (f.description ?? "").trim() ||
      !!old.multiline !== !!f.multiline ||
      otherFieldsDiffer(old, f, ["name", "label", "required", "description", "multiline"])
    )
      out.push(`Changed how the form asks for “${f.label}”`);
  }
  for (const f of before.input_fields)
    if (!fieldsAfter.has(f.name)) out.push(`No longer asks for “${f.label}”`);

  // Steps: matched by id, then by title for any the revision re-numbered.
  const unmatched = new Map(before.steps.map((s) => [s.id, s]));
  const pairs: [DynamicStep | null, DynamicStep][] = after.steps.map((s) => {
    const old = unmatched.get(s.id);
    if (old && old.kind === s.kind) {
      unmatched.delete(s.id);
      return [old, s];
    }
    return [null, s];
  });
  for (const pair of pairs) {
    if (pair[0]) continue;
    const s = pair[1];
    const byTitle = Array.from(unmatched.values()).find(
      (o) => o.kind === s.kind && o.title === s.title
    );
    if (byTitle) {
      unmatched.delete(byTitle.id);
      pair[0] = byTitle;
    }
  }
  pairs.forEach(([old, s], i) => {
    if (!old) out.push(`Added step ${i + 1}: “${s.title}” (${stepWho(s, labels)})`);
    else out.push(...stepChanges(old, s, labels));
  });
  for (const old of unmatched.values()) out.push(`Removed step “${old.title}”`);

  const kept = pairs.flatMap(([old]) => (old ? [old.id] : []));
  const keptBefore = before.steps.map((s) => s.id).filter((id) => kept.includes(id));
  if (kept.join("\n") !== keptBefore.join("\n")) out.push("Changed the order of the steps");

  if (otherFieldsDiffer(before, after, TOP_LEVEL_FIELDS)) out.push("Changed other settings");

  return out;
}

/** Tool names a revision adds that the saved version's steps did not use. */
export function addedTools(before: DynamicWorkflowDef, after: DynamicWorkflowDef): string[] {
  const had = new Set(before.steps.flatMap((s) => (s.kind === "action" ? s.tools : [])));
  return Array.from(
    new Set(after.steps.flatMap((s) => (s.kind === "action" ? s.tools : [])))
  ).filter((t) => !had.has(t));
}