AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
// In a frame, what the page changes beyond the host list asks first
// (components/embed/EmbedProvider.tsx, FrameConfirm.tsx).
//
// A page that frames this one (a host origin, or any page frame-ancestors
// lets in) can't read or click inside the frame, but it can make the frame
// invisible, lay its own buttons over it and catch clicks meant for those.
// So in a frame, approving, rejecting or cancelling a card, sending a chat
// message as the person, and any other change the host list doesn't already
// let the host make itself (a setting, Handle it for me, People) that follows
// a click, first asks inside the frame, naming what will happen; its Yes
// counts only once the browser has reported the question seen (lib/seen.ts).
// A browser that can't report it gets no Yes: the person goes to `page`, this
// app's own, top level. Outside a frame nothing changes.
//
// The embedded shell checks every request the page sends against
// `frameActionFor`, so no call site can forget.
// scripts/cardActions.test.mjs fails when lib/api.ts calls a card action this
// doesn't name.
//
// No imports, so `npm test` can exercise this.
export type CardAction = {
verb: "approve" | "reject" | "cancel" | "change";
// The card's decision id, when it has one (its details are shown too).
decisionId: number | null;
// What will happen, in a sentence.
what: string;
// A card action always asks in a frame. Any other change only when it
// follows a click (it could have been lured); one the page makes on its
// own can't have been.
card: boolean;
// The card's own page, where a browser that can't tell the frame is seen
// answers it instead (null: the page that asked, opened on its own).
page: string | null;
};
type HostCall = readonly [method: string, pattern: string];
const BACKEND = "/api/backend";
const READS = new Set(["GET", "HEAD", "OPTIONS"]);
// Chat messages are on the host list, but only a host's own are read-only:
// sent from this app's page in a frame, a turn is the person's own, with
// every tool. So in a frame they are refused like a card action.
const CHAT_SENDS = new Set(["/chat", "/chat/upload", "/chat/add"]);
// The changes a lured click would most like to make, said plainly.
const NAMED_CHANGES: readonly (readonly [RegExp, string])[] = [
[/^\/delegation\/handle-it/, "Change Handle it for me: what the Executive sends as you without asking."],
[/^\/delegation\//, "Change what the Executive may do as you (Delegate)."],
[/^\/executive\/(pause|resume)$/, "Pause or resume the Executive."],
[/^\/people(\/|$)/, "Change People: who is on the roster and what they may do."],
[/^\/departments(\/|$)/, "Change a department or who leads it."],
[/^\/(settings|workspace|notifications)(\/|$)/, "Change a setting."],
[/^\/(documents|knowledge)(\/|$)/, "Change the company knowledge the Executive relies on."],
];
// Writes a frame may make without asking: they change nothing anyone acts on.
const HARMLESS = /^\/sessions\/[^/]+\/typing$/;
function verbFromBody(body: unknown): "approve" | "reject" | null {
if (typeof body !== "string") return null;
try {
const parsed = JSON.parse(body) as { decision?: unknown };
return parsed.decision === "approve" || parsed.decision === "reject" ? parsed.decision : null;
} catch {
return null;
}
}
function backendPath(url: string): string | null {
let path: string;
try {
path = new URL(url, "http://this.app").pathname;
} catch {
return null;
}
return path.startsWith(`${BACKEND}/`) ? path.slice(BACKEND.length) : null;
}
/** The card action a request is, or null for anything else. */
export function cardActionFor(method: string, url: string, body?: unknown): CardAction | null {
if (method.toUpperCase() !== "POST") return null;
const path = backendPath(url);
if (path === null) return null;
let m = /^\/decisions\/(\d+)\/(approve|reject|cancel)$/.exec(path);
if (m) {
const id = Number(m[1]);
const verb = m[2] as "approve" | "reject" | "cancel";
const what =
verb === "approve"
? `Approve card ${id}: what it shows is carried out now, as you.`
: verb === "reject"
? `Dismiss card ${id}: nothing on it will happen.`
: `Cancel card ${id}: what it started stops, and nothing more on it will happen.`;
return { verb, decisionId: id, what, card: true, page: `/cards/${id}` };
}
m = /^\/alerts\/(\d+)\/approve$/.exec(path);
if (m) {
return {
verb: "approve",
decisionId: null,
what: `Approve the proposal on alert ${m[1]}: what it proposes is carried out now, as you.`,
card: true,
page: null,
};
}
m = /^\/workflows\/runs\/([^/]+)\/decision$/.exec(path);
if (m) {
const verb = verbFromBody(body) ?? "approve";
const run = decodeURIComponent(m[1]);
return {
verb,
decisionId: null,
what:
verb === "approve"
? `Sign off workflow run ${run}: it carries on with what it was waiting to do.`
: `Turn down workflow run ${run}: it stops where it is waiting.`,
card: true,
page: null,
};
}
m = /^\/people\/requests\/(\d+)\/(approve|decline)$/.exec(path);
if (m) {
return m[2] === "approve"
? { verb: "approve", decisionId: null, what: `Add the person in request ${m[1]} to People, as you answered it.`, card: true, page: null }
: { verb: "reject", decisionId: null, what: `Decline request ${m[1]}: they are not added to People.`, card: true, page: null };
}
return null;
}
/** The chat message a send carries (JSON or a form), cut short, or "". */
export function messageOf(body: unknown): string {
let message: unknown = null;
if (typeof body === "string") {
try {
message = (JSON.parse(body) as { message?: unknown }).message;
} catch {
return "";
}
} else if (body !== null && typeof body === "object" && typeof (body as FormData).get === "function") {
message = (body as FormData).get("message");
}
if (typeof message !== "string") return "";
const text = message.replace(/\s+/g, " ").trim();
return text.length > 160 ? `${text.slice(0, 159)}…` : text;
}
function onHostList(calls: readonly HostCall[], method: string, path: string): boolean {
const segments = path.split("/").slice(1).map((s) => {
try {
return decodeURIComponent(s);
} catch {
return s;
}
});
return calls.some(([callMethod, pattern]) => {
if (callMethod !== method) return false;
const parts = pattern.split("/").slice(1);
return parts.length === segments.length && parts.every((p, i) => /^\{[a-z_]+\}$/.test(p) || p === segments[i]);
});
}
/**
* What a request from a framed page would change, or null when it may go
* straight through: a read, anything outside the backend proxy, a typing
* notice, and a call on the host list the host could make with the same
* effect itself (not a chat message: the host's are read-only, this page's
* are not).
*/
export function frameActionFor(
method: string,
url: string,
body: unknown,
hostCalls: readonly HostCall[],
): CardAction | null {
const verb = method.toUpperCase();
if (READS.has(verb)) return null;
const card = cardActionFor(verb, url, body);
if (card) return card;
const path = backendPath(url);
if (path === null || HARMLESS.test(path)) return null;
if (verb === "POST" && CHAT_SENDS.has(path)) {
const words = messageOf(body);
return {
verb: "change",
decisionId: null,
what:
`Send ${words ? `"${words}"` : "this message"} to the Executive as you. ` +
"It can act on it: send, schedule or change things.",
// Always: a queued message or Try again may carry words that weren't
// typed here.
card: true,
page: null,
};
}
if (onHostList(hostCalls, verb, path)) return null;
const named = NAMED_CHANGES.find(([re]) => re.test(path));
return {
verb: "change",
decisionId: null,
what: `${named ? named[1] : "Make this change in Open Executive, as you."} (${verb} ${path.slice(0, 120)})`,
card: false,
page: null,
};
}
/**
* Where a browser that can't tell the frame is seen answers `action`: the
* card's own page, or else the page that asked (`pathname` + `search`), in
* both cases without `embed`, so it opens as this app's own page.
*/
export function ownPageFor(action: CardAction, pathname: string, search: string): string {
if (action.page) return action.page;
const params = new URLSearchParams(search);
params.delete("embed");
const query = params.toString();
const path = pathname.startsWith("/") && !pathname.startsWith("//") ? pathname : "/";
return query ? `${path}?${query}` : path;
}
export class CardActionNotConfirmed extends Error {
constructor() {
super("Not confirmed, so nothing was done.");
this.name = "CardActionNotConfirmed";
}
}
// A change made this soon after a click or a key in the frame may have been
// lured, so it asks; later than that, the page made it on its own.
export const AFTER_INPUT_MS = 10_000;
export type FrameAsk = { action: CardAction; resolve: (ok: boolean) => void };
export type FrameGate = {
// window.fetch in the frame: asks first where `frameActionFor` says so.
fetch: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
// A trusted click, key, drop or paste in the frame.
input: () => void;
// The person's answer in FrameConfirm.
answer: (ok: boolean) => void;
};
/**
* The frame's check on every request (EmbedProvider): a card action always
* asks, and any other change off `hostCalls` asks when it follows input
* within AFTER_INPUT_MS. `show` puts the question up (FrameConfirm), or takes
* it down with null. One question at a time: a second change while one is
* asked is refused. A No, or a refusal, throws CardActionNotConfirmed and
* never reaches `send`.
*/
export function frameGate(
send: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>,
hostCalls: readonly HostCall[],
show: (ask: FrameAsk | null) => void,
now: () => number = Date.now,
): FrameGate {
let pending: FrameAsk | null = null;
let lastInput = 0;
const confirm = (action: CardAction) =>
new Promise<boolean>((resolve) => {
if (pending) return resolve(false);
pending = { action, resolve };
show(pending);
});
return {
fetch: async (input, init) => {
const method = init?.method ?? (input instanceof Request ? input.method : "GET");
const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
const action = frameActionFor(method, url, init?.body, hostCalls);
const asks = action !== null && (action.card || now() - lastInput < AFTER_INPUT_MS);
if (asks && !(await confirm(action))) throw new CardActionNotConfirmed();
return send(input, init);
},
input: () => {
lastInput = now();
},
answer: (ok) => {
const current = pending;
pending = null;
// A Yes is input too: what the confirmed change sets off next asks again.
lastInput = now();
show(null);
current?.resolve(ok);
},
};
}