Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.
Let the boundary ask a person, not only say yes or no (#15)
Jerel Velardefcebb4a93f83
diff --git a/.env.example b/.env.exampleindex f25c4b7c..465d645e 100644--- a/.env.example+++ b/.env.example@@ -123,17 +123,33 @@ AGENT_COMPUTER_ALLOW_PRIVATE_HOSTS=true# What a Bot may do on its computer, as one JSON object. Absent uses the built-in default, which# permits the acting tools and forbids nothing, and records every action either way.#-# `deny` is evaluated first and beats `allow`. An empty `allow` permits nothing, a missing policy+# `deny` is evaluated first and beats everything. An empty `allow` permits nothing, a missing policy# permits nothing, and a rule that fails to parse denies rather than letting the action through. The# server refuses to start if this is set and malformed, so an invalid restriction never falls back to# permissive behavior.#+# `ask` is the third list, checked after `deny` and before `allow`. A match stops the Bot, puts the+# action in front of a person in the conversation, and carries on with the same action if they allow+# it, so the turn is not thrown away. Nothing an `ask` rule matches can be reached by a `deny` rule:+# forbidden stays forbidden and is never offered as a question. It has to beat `allow`, because the+# default below permits everything, and an ask checked afterwards would never fire.+#+# An answer is bound to the exact action it was given for, so allowing one button is not permission+# to press a different one, and it can only be spent once. Nobody answering within ten minutes is the+# same as nobody being asked: the action does not happen. In `dry-run` an ask interrupts nobody and is+# only recorded, because dry-run promises to change nothing.+#+# Every list judges a Bot's calls to MCP servers as well as what it does in a browser, `ask` included,+# so a rule like `intent == "write_tool" && mcp.server == "jira"` stops the call and asks rather than+# refusing it. The questions and the answers are the same three audit rows either way.+## Workspace and browser profile per Bot. Each Bot's computer is its own container with its own# volumes, so one Bot cannot read another's files or use another's logins, and every action records# which Bot took it. A rule can still restrict a single Bot with `bot.id`.## Attributes: tool.name, bot.id, actor.id, page.url, page.host, element.ref/role/name/type,-# key, file.path, file.name, file.extension, repeat.count.+# key, submit, file.path, file.name, file.extension, mcp.server/tool/effect,+# repeat.count.## repeat.count is how many times this Bot has just made this exact call, counting the one being# decided. A stuck model retries, and each retry is a real action on somebody's live website that is@@ -146,13 +162,14 @@ AGENT_COMPUTER_ALLOW_PRIVATE_HOSTS=true# another server's tools over MCP are not counted at all.## Name every route to the same effect. A form submits from a keypress in any of its fields, so a rule-# that only blocks a Submit button does not block Enter from another field. The example below refuses-# Enter outright for that reason.+# that only blocks a Submit button does not block Enter from another field, and a Bot can ask the type+# tool to press Enter for it, which arrives as `submit` rather than as a keypress. The example below+# names all three.# Functions: contains(haystack, needle) and matches(value, pattern), both case-insensitive.# `enforce` blocks; `dry-run` decides and records but lets everything through, so a new rule can be# tried against real traffic before it starts refusing anybody's work.#-# AGENT_COMPUTER_POLICY={"mode":"enforce","deny":["(intent == \"activate\" && contains(element.name, \"submit\")) || (tool.name == \"computer_key\" && key == \"Enter\")"],"allow":["true"]}+# AGENT_COMPUTER_POLICY={"mode":"enforce","deny":["(intent == \"activate\" && contains(element.name, \"submit\")) || (tool.name == \"computer_key\" && key == \"Enter\") || submit"],"ask":["intent == \"write_file\" && !matches(file.path, \"^notes/\")"],"allow":["true"]}# How long two identical calls count as the same repetition, in ms. Three minutes unset, which# assumes a retry loop is a model round trip apart: call the tool, read the failure, try again.diff --git a/app/src/components/channels/approval-request.tsx b/app/src/components/channels/approval-request.tsxnew file mode 100644index 00000000..abc1bdb9--- /dev/null+++ b/app/src/components/channels/approval-request.tsx@@ -0,0 +1,99 @@+import { useCallback, useState, useSyncExternalStore } from "react";+import { Button } from "@/components/ui/button";+import {+ answerApproval,+ closeQuestion,+ questionOn,+ watchQuestions,+} from "@/lib/approvals";++/**+ * A transcript line that grew two buttons, for the one action a boundary wanted a person to see.+ *+ * Not a modal, and the restraint is the point. A question about one click belongs where the click is+ * being reported, in sequence with everything else the Bot did, so a person can see what led up to it+ * without losing the conversation behind a dialog. A boundary that interrupts the whole screen is one+ * people learn to dismiss, and an ask rule that gets reflexively approved is worse than no rule at+ * all: it produces a record of consent that nobody actually gave.+ *+ * It draws the question its own tool call is waiting on, and nothing else. The alternative, asking+ * the server what this Bot is waiting on and showing the first unanswered thing, cannot tell one+ * question from another: a run that was stopped or a tab that was reloaded leaves its question open+ * in the registry for the rest of the ten minutes, so the card would offer somebody a stale question+ * on the line of an action nobody is being asked about, and record their Allow against the wrong+ * one. The tool call that raised the question is the only thing that knows which one is its own, so+ * it is what says so.+ */+export function ApprovalRequest({+ /** The tool call this line is reporting. Undefined before the SDK has named it. */+ toolCallId,+}: {+ toolCallId: string | undefined;+}) {+ const asking = useSyncExternalStore(watchQuestions, () =>+ questionOn(toolCallId ?? ""),+ );+ const [answering, setAnswering] = useState(false);+ const [problem, setProblem] = useState<string | null>(null);++ const answer = useCallback(+ async (granted: boolean) => {+ if (!asking) return;+ setAnswering(true);+ const result = await answerApproval(+ asking.botId,+ asking.approvalId,+ granted,+ );+ setAnswering(false);+ if (!result.ok) {+ setProblem(result.error ?? "That answer could not be recorded.");+ return;+ }+ // Taken down here rather than waiting for the call to notice, so the buttons stop being+ // pressable the moment the answer lands. The Bot's turn is still on the server working out+ // what to do with it.+ closeQuestion(toolCallId ?? "");+ setProblem(null);+ },+ [asking, toolCallId],+ );++ if (!asking) return null;++ return (+ <div className="my-1.5 rounded-md border border-border bg-card px-3 py-2">+ <p className="text-sm">{asking.question}</p>+ {asking.rule ? (+ <p className="mt-1 break-all font-mono text-muted-foreground text-xs">+ {asking.rule}+ </p>+ ) : null}+ <div className="mt-2 flex items-center gap-2">+ <Button+ disabled={answering}+ onClick={() => void answer(true)}+ size="sm"+ >+ Allow+ </Button>+ <Button+ disabled={answering}+ onClick={() => void answer(false)}+ size="sm"+ variant="outline"+ >+ Deny+ </Button>+ <span className="text-muted-foreground text-xs">+ Asked because of this rule. Allowing covers this one action.+ </span>+ </div>+ {problem ? (+ <p className="mt-2 text-destructive text-xs" role="alert">+ {problem}+ </p>+ ) : null}+ </div>+ );+}diff --git a/app/src/lib/approvals.ts b/app/src/lib/approvals.tsnew file mode 100644index 00000000..cf846107--- /dev/null+++ b/app/src/lib/approvals.ts@@ -0,0 +1,163 @@+/**+ * The questions a boundary raised, from the browser's side: reading them, answering them, and+ * knowing which tool call each one belongs to.+ *+ * One module for all of it because the two halves have to agree. A tool call that met an `ask` rule+ * holds itself open waiting for an answer, and the card a person answers on is drawn on that same+ * tool call's line in the transcript. Those are different components on different render passes, so+ * the id travels through here.+ *+ * A question is held against the tool call that raised it rather than against the Bot. The Bot's+ * list is the wrong key: nothing withdraws a question when the wait around it ends, so pressing+ * Stop, reloading the tab or a turn that errors all leave an unanswered entry sitting in the+ * server's registry until it expires. A card that showed "the oldest thing this Bot is waiting on"+ * would then put a stale question in front of somebody on an unrelated line, record their Allow+ * against an action nobody is waiting for, and leave the action they were actually looking at+ * waiting out the full ten minutes.+ */++/**+ * How long the surface holds a tool call open for an answer, and how often it looks.+ *+ * Ten minutes matches the server's own window, so the wait ends because the question expired rather+ * than because the two sides disagreed about when it had.+ */+const WAIT_FOR_ANSWER_MS = 10 * 60_000;+const WAIT_POLL_MS = 1_000;++export type PendingApproval = {+ id: string;+ botId: string;+ /** The expression that asked, shown as a rule so a person can see which boundary they are at. */+ rule: string;+ /** What is about to happen, in one sentence. */+ question: string;+ requestedAt: string;+ expiresAt: string;+ /** Absent while nobody has answered. False is an answer. */+ granted?: boolean;+ answeredBy?: string;+};++/** A question one tool call is waiting on, as its own line in the transcript needs to draw it. */+export type OpenQuestion = {+ approvalId: string;+ botId: string;+ question: string;+ rule: string | null;+};++const open = new Map<string, OpenQuestion>();+const watchers = new Set<() => void>();++/**+ * Say that this tool call is waiting on an answer, so its line can draw the card.+ *+ * Handed over rather than fetched again: the server said all of it in the reply that paused the+ * call, and a card that re-derived its question from a list would be back to guessing which entry+ * in that list was its own.+ */+export function openQuestion(toolCallId: string, question: OpenQuestion): void {+ if (!toolCallId) return;+ open.set(toolCallId, question);+ for (const watcher of watchers) watcher();+}++/** The wait is over, whichever way it went. Nothing should still be offering buttons for it. */+export function closeQuestion(toolCallId: string): void {+ if (!open.delete(toolCallId)) return;+ for (const watcher of watchers) watcher();+}++export function questionOn(toolCallId: string): OpenQuestion | undefined {+ return open.get(toolCallId);+}++export function watchQuestions(listener: () => void): () => void {+ watchers.add(listener);+ return () => {+ watchers.delete(listener);+ };+}++/**+ * The open questions for one Bot, or null if the server could not be asked.+ *+ * Null and an empty list are kept apart on purpose. A caller waiting for its own answer must not read+ * a failed request as "the question is gone", which is what an empty list means here.+ */+export async function readApprovals(+ botId: string,+): Promise<PendingApproval[] | null> {+ try {+ const response = await fetch(`/api/approvals/${botId}`, {+ credentials: "include",+ });+ if (!response.ok) return null;+ const body = (await response.json()) as { approvals?: PendingApproval[] };+ return body.approvals ?? [];+ } catch {+ return null;+ }+}++export async function answerApproval(+ botId: string,+ approvalId: string,+ granted: boolean,+): Promise<{ ok: boolean; error?: string }> {+ try {+ const response = await fetch(`/api/approvals/${botId}/${approvalId}`, {+ method: "POST",+ credentials: "include",+ headers: { "content-type": "application/json" },+ body: JSON.stringify({ granted }),+ });+ if (response.ok) return { ok: true };+ const body = (await response.json().catch(() => null)) as {+ error?: string;+ } | null;+ return {+ ok: false,+ error: body?.error ?? "That answer could not be recorded.",+ };+ } catch {+ return {+ ok: false,+ error: "The assistant's computer could not be reached.",+ };+ }+}++/**+ * Hold a tool call open until somebody answers its question.+ *+ * Polled rather than pushed. The answer arrives on a server this tab has no other channel to, and it+ * may well be given in a different tab or by a different person, so the only honest way to learn it+ * is to keep asking. A second between looks costs one request while a Bot is stopped and nothing at+ * all the rest of the time.+ */+export async function waitForApproval(+ botId: string,+ approvalId: string,+ signal: AbortSignal | undefined,+): Promise<"granted" | "declined" | "gave up" | "cancelled"> {+ const deadline = Date.now() + WAIT_FOR_ANSWER_MS;+ while (Date.now() < deadline) {+ // Stop must work out of this wait as well, or pressing it leaves a Bot parked on a question+ // nobody is going to answer.+ if (signal?.aborted) return "cancelled";+ const approvals = await readApprovals(botId);+ if (approvals) {+ const mine = approvals.find((one) => one.id === approvalId);+ // Gone from a list we did read means it expired and was swept, which is the same outcome as+ // running out of patience here. A list we could NOT read says nothing, so it is not read as an+ // answer.+ if (!mine) return "gave up";+ if (mine.granted === true) return "granted";+ if (mine.granted === false) return "declined";+ }+ await new Promise((resolve) => setTimeout(resolve, WAIT_POLL_MS));+ }+ return "gave up";+}diff --git a/app/src/lib/copilot/computer-tools.tsx b/app/src/lib/copilot/computer-tools.tsxindex ce480b13..bea0484b 100644--- a/app/src/lib/copilot/computer-tools.tsx+++ b/app/src/lib/copilot/computer-tools.tsx@@ -1,11 +1,13 @@import { useFrontendTool } from "@copilotkit/react-core/v2";import { z } from "zod";+import { ApprovalRequest } from "@/components/channels/approval-request";import { ToolLine } from "@/components/channels/tool-line";import { ComputerView } from "@/components/computer/computer-view";import {type ControlState,readControl,} from "@/components/computer/take-the-wheel";+import { closeQuestion, openQuestion, waitForApproval } from "@/lib/approvals";import { useActiveBotHolder } from "./active-bot";import { reportComputerActivity } from "./computer-activity";@@ -16,6 +18,16 @@ import { reportComputerActivity } from "./computer-activity";/** What every computer call returns to the model: either the result, or a reason it did not happen. */type ToolOutcome = Record<string, unknown> & { ok: boolean };+/**+ * What the SDK hands a running tool call, as much of it as this file needs.+ *+ * Passed around whole rather than unpicked into an abort signal, because the id matters as much as+ * the abort does: it is what lets a question about this call be drawn on this call's line and+ * nowhere else. Optional throughout, because the SDK's context argument is optional and a handler+ * that destructures it unconditionally throws on any call that omits it.+ */+type ToolCallContext = { signal?: AbortSignal; toolCall?: { id?: string } };+/*** Human-assistance wait window. Long enough for a user to return, finite so the run can unblock.*/@@ -42,7 +54,91 @@ async function waitForPerson(return "gave up";}+/**+ * The same request, carrying an answer.+ *+ * Rebuilt rather than mutated, because every acting route is a POST of one JSON object and the+ * approval is one more field on it. Sending the identical arguments matters: the server binds an+ * approval to a fingerprint of the action, so a retry that differed in any way it hashes would be+ * refused as a different action, which is exactly what that binding is for.+ */+function withApproval(+ init: RequestInit | undefined,+ approvalId: string,+): RequestInit {+ const sent =+ typeof init?.body === "string"+ ? (JSON.parse(init.body) as Record<string, unknown>)+ : {};+ return {+ ...init,+ method: "POST",+ headers: { "content-type": "application/json" },+ body: JSON.stringify({ ...sent, approvalId }),+ };+}++/**+ * One computer call, including the pause where a person is asked about it.+ *+ * The waiting lives here rather than in each tool's handler so that a tool cannot be added without+ * it: an acting route that met an ask rule and got back a bare failure would report to the model+ * that the action was impossible, when in fact nobody had been asked yet.+ */async function callComputer(+ botId: string,+ path: string,+ init?: RequestInit,+ call: ToolCallContext = {},+): Promise<ToolOutcome> {+ const signal = call.signal;+ const outcome = await sendToComputer(botId, path, init, signal);+ if (outcome.awaitingApproval !== true) return outcome;++ const approvalId = String(outcome.approvalId ?? "");+ // Put in front of the person on this call's own line rather than left to be found. The id is what+ // ties the card to the action it is about; see lib/approvals.ts for why anything looser gets it+ // wrong.+ const toolCallId = call.toolCall?.id ?? "";+ openQuestion(toolCallId, {+ approvalId,+ botId,+ question: String(outcome.question ?? outcome.reason ?? ""),+ rule: typeof outcome.rule === "string" ? outcome.rule : null,+ });+ try {+ const answer = await waitForApproval(botId, approvalId, signal);+ if (answer === "granted") {+ // Sent once, not through this function again. A second ask on the retry would mean the approval+ // did not fit the action, and looping on that would hold the turn open until the deadline instead+ // of telling the model something it can act on.+ return sendToComputer(+ botId,+ path,+ withApproval(init, approvalId),+ signal,+ );+ }+ if (answer === "cancelled") {+ return { ok: false, reason: "Stopped.", stopped: true };+ }+ return answer === "declined"+ ? { ok: false, refused: true, reason: "A person declined that." }+ : {+ ok: false,+ reason:+ "Nobody answered the request to allow that, so it did not happen. Say what you were " ++ "waiting for rather than trying another way round it.",+ };+ } finally {+ // However the wait ended, nothing should still be offering buttons for it. A run that was+ // stopped leaves its question open on the server for the rest of its ten minutes, and a card+ // that outlived its own call would be collecting consent nobody is waiting for.+ closeQuestion(toolCallId);+ }+}++async function sendToComputer(botId: string,path: string,init?: RequestInit,@@ -75,6 +171,19 @@ async function callComputer(> | null;if (!response.ok) {+ // Read before anything else a 409 can mean. The other two, stale refs and a person holding the+ // wheel, are conditions the model reacts to; this one it must not see at all, because the caller+ // above is going to wait and then send the very same request again.+ if (response.status === 409 && body?.awaitingApproval === true) {+ return {+ ok: false,+ awaitingApproval: true,+ approvalId: body.approvalId ?? "",+ question: body.question ?? "",+ rule: body.rule ?? null,+ reason: (body.error as string) ?? "Somebody is being asked about that.",+ };+ }return {ok: false,reason: (body?.error as string) ?? "That did not work.",@@ -140,14 +249,27 @@ function labelOf(result: string | undefined): string | undefined {/*** A compact transcript line that distinguishes policy refusals from ordinary failures.+ *+ * While the action is still running it also carries the place a question about it appears. The card+ * belongs on the line for the action it is about, in sequence, rather than somewhere else on the+ * screen: a person deciding whether to allow a click wants to see what the Bot did to get there.*/function ActionLine({+ toolCallId,label,detail,running,refused,failed,}: {+ /**+ * Which call this line is reporting.+ *+ * The card shows a question only when this exact call raised one, so a line for an action nobody+ * was asked about stays a line. Passing the Bot instead would draw whatever that Bot happened to+ * be waiting on, which on a second turn is somebody else's abandoned question.+ */+ toolCallId?: string;label: string;detail?: string;running?: boolean;@@ -157,13 +279,16 @@ function ActionLine({failed?: boolean;}) {return (- <ToolLine- detail={detail}- failed={failed}- label={label}- refused={refused}- running={running}- />+ <>+ <ApprovalRequest toolCallId={toolCallId} />+ <ToolLine+ detail={detail}+ failed={failed}+ label={label}+ refused={refused}+ running={running}+ />+ </>);}@@ -184,11 +309,7 @@ export function ComputerTools() {parameters: z.object({url: z.string().describe("Full web address to open, including https://"),}),- handler: async (- { url }: { url: string },- // Context is optional in the SDK.- { signal }: { signal?: AbortSignal } = {},- ) => {+ handler: async ({ url }: { url: string }, call: ToolCallContext = {}) => {const result = await callComputer(bot.current,"/navigate",@@ -197,7 +318,7 @@ export function ComputerTools() {headers: { "content-type": "application/json" },body: JSON.stringify({ url }),},- signal,+ call,);return result.ok? {@@ -209,8 +330,14 @@ export function ComputerTools() {}: result;},- render: ({ status }) => (+ render: ({ status, toolCallId }) => (<div className="my-2">+ {/*+ * Above the screen rather than through ActionLine, because opening a page draws the live+ * view instead of a line. A question about where the Bot is about to go still belongs+ * beside it.+ */}+ <ApprovalRequest toolCallId={toolCallId} /><ComputerView computerId={bot.current} active={status !== "complete"} /></div>),@@ -278,7 +405,7 @@ export function ComputerTools() {text: string;submit?: boolean;},- { signal }: { signal?: AbortSignal } = {},+ call: ToolCallContext = {},) =>callComputer(bot.current,@@ -288,10 +415,11 @@ export function ComputerTools() {headers: { "content-type": "application/json" },body: JSON.stringify(input),},- signal,+ call,),- render: ({ args, result, status }) => (+ render: ({ args, result, status, toolCallId }) => (<ActionLine+ toolCallId={toolCallId}running={status !== "complete"}label="Filled in"detail={@@ -320,7 +448,7 @@ export function ComputerTools() {}),handler: async (input: { ref: string; snapshotId: number },- { signal }: { signal?: AbortSignal } = {},+ call: ToolCallContext = {},) =>callComputer(bot.current,@@ -330,12 +458,13 @@ export function ComputerTools() {headers: { "content-type": "application/json" },body: JSON.stringify(input),},- signal,+ call,),- render: ({ args, result, status }) => {+ render: ({ args, result, status, toolCallId }) => {const outcome = outcomeOf(result);return (<ActionLine+ toolCallId={toolCallId}running={status !== "complete"}label="Clicked"detail={@@ -371,7 +500,7 @@ export function ComputerTools() {ref?: string;snapshotId?: number;},- { signal }: { signal?: AbortSignal } = {},+ call: ToolCallContext = {},) =>callComputer(bot.current,@@ -381,10 +510,11 @@ export function ComputerTools() {headers: { "content-type": "application/json" },body: JSON.stringify(input),},- signal,+ call,),- render: ({ args, result, status }) => (+ render: ({ args, result, status, toolCallId }) => (<ActionLine+ toolCallId={toolCallId}running={status !== "complete"}label="Pressed"detail={typeof args?.key === "string" ? args.key : undefined}@@ -418,7 +548,7 @@ export function ComputerTools() {}),handler: async (input: { label: string; ref: string; snapshotId: number },- { signal }: { signal?: AbortSignal } = {},+ call: ToolCallContext = {},) => {const botId = bot.current;const asked = await callComputer(@@ -429,7 +559,7 @@ export function ComputerTools() {headers: { "content-type": "application/json" },body: JSON.stringify(input),},- signal,+ call,);if (!asked.ok) return asked;@@ -437,7 +567,7 @@ export function ComputerTools() {const outcome = await waitForPerson(botId,(state) => state.secretWanted === undefined,- signal,+ call.signal,);return {ok: true,@@ -473,7 +603,7 @@ export function ComputerTools() {}),handler: async (input: { reason: string; request?: string },- { signal }: { signal?: AbortSignal } = {},+ call: ToolCallContext = {},) => {try {const response = await fetch(@@ -483,7 +613,7 @@ export function ComputerTools() {credentials: "include",headers: { "content-type": "application/json" },body: JSON.stringify(input),- ...(signal ? { signal } : {}),+ ...(call.signal ? { signal: call.signal } : {}),},);return response.ok@@ -511,10 +641,7 @@ export function ComputerTools() {"What you need the person to do, in one sentence, e.g. 'This page is asking for a code sent to your phone.'",),}),- handler: async (- input: { reason: string },- { signal }: { signal?: AbortSignal } = {},- ) => {+ handler: async (input: { reason: string }, call: ToolCallContext = {}) => {const botId = bot.current;const asked = await callComputer(botId,@@ -524,7 +651,7 @@ export function ComputerTools() {headers: { "content-type": "application/json" },body: JSON.stringify(input),},- signal,+ call,);if (!asked.ok) return asked;@@ -532,7 +659,7 @@ export function ComputerTools() {const outcome = await waitForPerson(botId,(state) => state.holder === "bot" && !state.requested,- signal,+ call.signal,);return {ok: true,@@ -560,17 +687,23 @@ export function ComputerTools() {.optional().describe("Optional folder to list. Omit for the whole workspace."),}),- handler: async (input: { path?: string }) =>- callComputer(bot.current, "/files/list", {- method: "POST",- headers: { "content-type": "application/json" },- body: JSON.stringify(input ?? {}),- }),- render: ({ result, status }) => {+ handler: async (input: { path?: string }, call: ToolCallContext = {}) =>+ callComputer(+ bot.current,+ "/files/list",+ {+ method: "POST",+ headers: { "content-type": "application/json" },+ body: JSON.stringify(input ?? {}),+ },+ call,+ ),+ render: ({ result, status, toolCallId }) => {const outcome = outcomeOf(result);const entries = Array.isArray(outcome.entries) ? outcome.entries : [];return (<ActionLine+ toolCallId={toolCallId}running={status !== "complete"}label="Listed files"detail={@@ -598,16 +731,22 @@ export function ComputerTools() {.string().describe("Path relative to your workspace, such as notes.md"),}),- handler: async (input: { path: string }) =>- callComputer(bot.current, "/files/read", {- method: "POST",- headers: { "content-type": "application/json" },- body: JSON.stringify(input),- }),- render: ({ args, result, status }) => {+ handler: async (input: { path: string }, call: ToolCallContext = {}) =>+ callComputer(+ bot.current,+ "/files/read",+ {+ method: "POST",+ headers: { "content-type": "application/json" },+ body: JSON.stringify(input),+ },+ call,+ ),+ render: ({ args, result, status, toolCallId }) => {const outcome = outcomeOf(result);return (<ActionLine+ toolCallId={toolCallId}running={status !== "complete"}label="Read file"detail={@@ -642,20 +781,29 @@ export function ComputerTools() {.optional().describe("Add to the end of the file instead of replacing it"),}),- handler: async (input: {- path: string;- contents: string;- append?: boolean;- }) =>- callComputer(bot.current, "/files/write", {- method: "POST",- headers: { "content-type": "application/json" },- body: JSON.stringify(input),- }),- render: ({ args, result, status }) => {+ handler: async (+ input: {+ path: string;+ contents: string;+ append?: boolean;+ },+ call: ToolCallContext = {},+ ) =>+ callComputer(+ bot.current,+ "/files/write",+ {+ method: "POST",+ headers: { "content-type": "application/json" },+ body: JSON.stringify(input),+ },+ call,+ ),+ render: ({ args, result, status, toolCallId }) => {const outcome = outcomeOf(result);return (<ActionLine+ toolCallId={toolCallId}running={status !== "complete"}label={args?.append === true ? "Added to file" : "Saved file"}// Show the path, never file contents.@@ -683,10 +831,7 @@ export function ComputerTools() {.optional().describe("Pixels to scroll; positive is down. Defaults to 600."),}),- handler: async (- input: { deltaY?: number },- { signal }: { signal?: AbortSignal } = {},- ) =>+ handler: async (input: { deltaY?: number }, call: ToolCallContext = {}) =>callComputer(bot.current,"/scroll",@@ -695,10 +840,11 @@ export function ComputerTools() {headers: { "content-type": "application/json" },body: JSON.stringify(input),},- signal,+ call,),- render: ({ result, status }) => (+ render: ({ result, status, toolCallId }) => (<ActionLine+ toolCallId={toolCallId}running={status !== "complete"}label="Scrolled"refused={outcomeOf(result).refused === true}diff --git a/app/src/lib/copilot/plugin-tools.tsx b/app/src/lib/copilot/plugin-tools.tsxindex 3e2ae66a..8dccdfbb 100644--- a/app/src/lib/copilot/plugin-tools.tsx+++ b/app/src/lib/copilot/plugin-tools.tsx@@ -2,6 +2,7 @@ import { useFrontendTool } from "@copilotkit/react-core/v2";import { useQuery } from "@tanstack/react-query";import { useRef, useState } from "react";import { Streamdown } from "streamdown";+import { ApprovalRequest } from "@/components/channels/approval-request";import { ToolLine } from "@/components/channels/tool-line";import { markdownComponents } from "@/lib/markdown";import * as z from "zod";@@ -152,6 +153,8 @@ function PluginTool({args ?? {},botId,context.signal,+ // So a question the boundary raises about this call is drawn on this call's own line.+ id,);if (result.ok) {@@ -188,19 +191,26 @@ function PluginTool({}return (- <ToolLine- detail={serverId}- failed={result?.isError}- label={bareName}- running={status !== "complete"}- >- {result ? (- /* The server's own words, drawn the way a Bot's prose is drawn. */- <Streamdown components={markdownComponents}>- {forDisplay(result.text)}- </Streamdown>- ) : null}- </ToolLine>+ <>+ {/*+ * A boundary can stop a tool call the same way it stops a click, so the question belongs+ * on this line rather than only on the lines about a browser.+ */}+ <ApprovalRequest toolCallId={toolCallId} />+ <ToolLine+ detail={serverId}+ failed={result?.isError}+ label={bareName}+ running={status !== "complete"}+ >+ {result ? (+ /* The server's own words, drawn the way a Bot's prose is drawn. */+ <Streamdown components={markdownComponents}>+ {forDisplay(result.text)}+ </Streamdown>+ ) : null}+ </ToolLine>+ </>);},});diff --git a/app/src/lib/plugins/queries.ts b/app/src/lib/plugins/queries.tsindex aad4c73a..a74d6ea2 100644--- a/app/src/lib/plugins/queries.ts+++ b/app/src/lib/plugins/queries.ts@@ -1,4 +1,5 @@import { queryOptions } from "@tanstack/react-query";+import { closeQuestion, openQuestion, waitForApproval } from "@/lib/approvals";/** A tool one server offers, as the Plugins page sees it. */export type PluginTool = {@@ -121,18 +122,100 @@ export type PluginCallOutcome =/*** Call a tool as a Bot, with server-side grant and policy rechecks for mid-run revocations.+ *+ * A call the boundary wants a person's answer to comes back here as a pause rather than a failure,+ * and this holds it open, puts the question on the tool call's own line, and sends the identical+ * call again with the answer attached. A tool call that reported "not allowed" to the model instead+ * would throw away the turn on work the deployment was willing to permit, which is the whole+ * difference between an ask rule and a deny rule.*/export async function callPluginTool(ref: string,args: Record<string, unknown>,agentId: string,signal?: AbortSignal,+ toolCallId?: string,): Promise<PluginCallOutcome> {+ const outcome = await sendCall(ref, args, agentId, signal);+ if (!("awaitingApproval" in outcome)) return outcome;++ openQuestion(toolCallId ?? "", {+ approvalId: outcome.approvalId,+ botId: agentId,+ question: outcome.question,+ rule: outcome.rule,+ });+ try {+ const answer = await waitForApproval(agentId, outcome.approvalId, signal);+ if (answer === "granted") {+ // Sent once, not through this function again. A second ask on the retry would mean the answer+ // did not fit the call, and looping on that would hold the turn open until the deadline+ // instead of telling the model something it can act on, so a question raised on the retry is+ // reported rather than waited on.+ const retried = await sendCall(+ ref,+ args,+ agentId,+ signal,+ outcome.approvalId,+ );+ return "awaitingApproval" in retried+ ? {+ ok: false,+ refused: false,+ reason:+ "That was allowed, but the answer did not fit the call being made, so it did not happen.",+ }+ : retried;+ }+ return answer === "declined"+ ? {+ ok: false,+ refused: true,+ reason: "A person declined that.",+ rule: outcome.rule,+ }+ : {+ ok: false,+ refused: false,+ reason:+ answer === "cancelled"+ ? "Stopped."+ : "Nobody answered the request to allow that, so it did not happen. Say what you " ++ "were waiting for rather than trying another way round it.",+ };+ } finally {+ closeQuestion(toolCallId ?? "");+ }+}++/** A question the server raised about this call, as the reply that paused it carried it. */+type AwaitingApproval = {+ awaitingApproval: true;+ approvalId: string;+ question: string;+ rule: string | null;+};++async function sendCall(+ ref: string,+ args: Record<string, unknown>,+ agentId: string,+ signal?: AbortSignal,+ approvalId?: string,+): Promise<PluginCallOutcome | AwaitingApproval> {const response = await fetch("/api/plugins/call", {method: "POST",credentials: "include",headers: { "content-type": "application/json" },- body: JSON.stringify({ ref, args, agentId }),+ body: JSON.stringify({+ ref,+ args,+ agentId,+ // Sent identically to the call that was asked about, because the server binds an answer to a+ // fingerprint of the call, arguments included: anything else comes back as a different action.+ ...(approvalId ? { approvalId } : {}),+ }),...(signal ? { signal } : {}),});@@ -141,6 +224,9 @@ export async function callPluginTool(isError?: boolean;error?: string;rule?: string | null;+ awaitingApproval?: boolean;+ approvalId?: string;+ question?: string;} | null;if (response.ok) {@@ -150,6 +236,16 @@ export async function callPluginTool(isError: body?.isError === true,};}+ // Read before anything else a 409 can mean, and never shown to the model: the caller above is+ // going to wait and then send the very same call again.+ if (response.status === 409 && body?.awaitingApproval === true) {+ return {+ awaitingApproval: true,+ approvalId: body.approvalId ?? "",+ question: body.question ?? body.error ?? "",+ rule: body.rule ?? null,+ };+ }if (response.status === 403) {return {ok: false,diff --git a/app/src/routes/_authed/admin/audit.tsx b/app/src/routes/_authed/admin/audit.tsxindex a6051ab0..84a7b809 100644--- a/app/src/routes/_authed/admin/audit.tsx+++ b/app/src/routes/_authed/admin/audit.tsx@@ -35,9 +35,11 @@ const FILTERS = [{ label: "Computer actions", search: "?eventType=computer.action_allowed" },{label: "Blocked",- // Include every refusal family, not only browser policy refusals.+ // Include every refusal family, not only browser policy refusals. A person declining a request+ // stopped an action just as surely as a deny rule did, and it leaves no action row of its own,+ // so without it here the trail's answer to "was anything blocked" is missing a whole family.search:- "?eventType=computer.action_refused,mcp.call_rejected,component.refused,component.function_refused",+ "?eventType=computer.action_refused,approval.denied,mcp.call_rejected,component.refused,component.function_refused",},{label: "Did not happen",@@ -45,6 +47,15 @@ const FILTERS = [// did not take: nothing was refused, and nothing came of it either.search: "?eventType=computer.action_failed,agent.stream_stalled",},+ {+ /*+ * The questions, so the one a person never answered can be found rather than looked for by eye.+ * A request with no answer beside it is the Bot having sat waiting while nobody was watching the+ * screen, which is the case this trail records that nothing else in the product would show.+ */+ label: "Asked a person",+ search: "?eventType=approval.requested,approval.granted,approval.denied",+ },{// Its own filter rather than a place in "Blocked". A Bot repeating itself has not been stopped by// anything, and putting it beside the refusals would make the refusals look less real.@@ -138,6 +149,7 @@ function Row({allowed?: boolean;mode?: string;rule?: string | null;+ approvedBy?: string;carriedOut?: boolean;};const element = payload.element as@@ -146,9 +158,13 @@ function Row({| undefined;const refused =event.eventType === "computer.action_refused" ||+ event.eventType === "approval.denied" ||event.eventType === "component.refused" ||event.eventType === "component.function_refused" ||event.eventType === "mcp.call_rejected";+ // The three rows a question leaves behind carry their rule at the top level rather than under a+ // decision, because no decision was reached: the policy stopped and waited for a person.+ const approval = event.eventType.startsWith("approval.");const stalled = event.eventType === "agent.stream_stalled";// Allowed by policy but not carried out. A stalled turn belongs in the same family: the Bot was// asked and the answer never arrived. Colour is how this table is read, and a row left in the@@ -254,6 +270,11 @@ function Row({{payload.failure}</div>) : null}+ {approval && typeof payload.reason === "string" ? (+ <div className="mt-0.5 text-xs text-muted-foreground">+ {payload.reason}+ </div>+ ) : null}{/** The two numbers the stall row is worth reading for. Without them every stalled turn looks* the same, and the difference between an endpoint that dies halfway through an answer and@@ -268,6 +289,17 @@ function Row({{decision.rule}</div>) : null}+ {approval && typeof payload.rule === "string" && payload.rule ? (+ <div className="mt-0.5 font-mono text-xs text-muted-foreground">+ {payload.rule}+ </div>+ ) : null}+ {/* Who stood behind an action, when the boundary asked and somebody said yes. */}+ {typeof decision.approvedBy === "string" ? (+ <div className="mt-0.5 text-xs text-muted-foreground">+ allowed by {decision.approvedBy}+ </div>+ ) : null}{decision.mode === "dry-run" && decision.carriedOut ? (<div className="text-xs text-muted-foreground">dry-run: recorded, not enforced@@ -307,6 +339,9 @@ const DECISIONS: Record<string, string> = {"computer.stopped": "A person pressed stop",// Not "Blocked". Nothing refused this; the Bot did the same thing again and the trail is saying so."computer.action_repeated": "The Bot repeated itself",+ "approval.requested": "The boundary asked a person",+ "approval.granted": "A person allowed it",+ "approval.denied": "A person declined it","component.granted": "Granted to this Bot","component.revoked": "Taken away from this Bot",diff --git a/app/src/routes/_authed/admin/boundaries.tsx b/app/src/routes/_authed/admin/boundaries.tsxindex e8e76297..7f7470c4 100644--- a/app/src/routes/_authed/admin/boundaries.tsx+++ b/app/src/routes/_authed/admin/boundaries.tsx@@ -14,17 +14,21 @@ type PolicyMode = "dry-run" | "enforce";type ActionPolicy = {mode: PolicyMode;deny: string[];+ ask: string[];allow: string[];};+type Preset = { label: string; rule: string; cost?: string };+/*** Presets are concrete CEL rules, not a separate policy language.*/-const PRESETS: { label: string; rule: string; cost?: string }[] = [+const PRESETS: Preset[] = [{label: "Never submit a form",- // `key` exists only on keypress actions; guard it by tool name to keep other actions evaluable.- rule: '(intent == "activate" && contains(element.name, "submit")) || (tool.name == "computer_key" && key == "Enter")',+ // Three doors, not two. `key` exists only on keypress actions, so it is guarded by tool name to+ // keep the rule evaluable elsewhere; `submit` is on every action and needs no guard.+ rule: '(intent == "activate" && contains(element.name, "submit")) || (tool.name == "computer_key" && key == "Enter") || submit',cost: "Also stops the Bot pressing Enter for anything else, because a form submits from Enter in any of its fields.",},{@@ -45,6 +49,26 @@ const PRESETS: { label: string; rule: string; cost?: string }[] = [},];+/**+ * The same rules a deployment might otherwise have had to forbid outright.+ *+ * Both of these are things a Bot is genuinely useful for and that nobody wants it doing unwatched+ * the first few times, which is the whole shape of this list: the boundary an operator actually+ * wants is rarely "never", it is "not without me".+ */+const ASK_PRESETS: Preset[] = [+ {+ label: "Ask before submitting a form",+ rule: '(intent == "activate" && contains(element.name, "submit")) || (tool.name == "computer_key" && key == "Enter") || submit',+ cost: "Asks about every Enter the Bot presses, because a form submits from Enter in any of its fields. Expect to be asked while it is filling one in, not only at the end.",+ },+ {+ label: "Ask before writing a file outside notes/",+ rule: 'intent == "write_file" && !matches(file.path, "^notes/")',+ cost: "Matches on the path the Bot asked for, so a folder it has not used before is a question rather than a refusal.",+ },+];+export const Route = createFileRoute("/_authed/admin/boundaries")({component: BoundariesPage,});@@ -55,6 +79,7 @@ function BoundariesPage() {const [saving, setSaving] = useState(false);const [saved, setSaved] = useState(false);const [draft, setDraft] = useState("");+ const [askDraft, setAskDraft] = useState("");const load = useCallback(async () => {try {@@ -133,6 +158,20 @@ function BoundariesPage() {setDraft("");};+ /**+ * The same rule can sit in both lists, and the deny wins.+ *+ * Not prevented, because an operator moving a rule from one list to the other will pass through+ * that state, and refusing to save it would look like a bug. What it means is stated under the+ * list instead, since the gateway decides deny first and an ask alongside it never fires.+ */+ const addAskRule = (rule: string) => {+ const trimmed = rule.trim();+ if (!trimmed || policy.ask.includes(trimmed)) return;+ void save({ ...policy, ask: [...policy.ask, trimmed] });+ setAskDraft("");+ };+return (<PageShelldescription={@@ -250,6 +289,93 @@ function BoundariesPage() {</ul></PageSection>+ <PageSection title="Ask me first">+ {policy.ask.length === 0 ? (+ <p className="mt-2 text-sm text-muted-foreground">+ No rules. Nothing stops to ask.+ </p>+ ) : (+ <ul className="mt-2 divide-y divide-border rounded-md border border-border">+ {policy.ask.map((rule) => (+ <li+ className="flex items-center justify-between gap-4 px-3 py-2"+ key={rule}+ >+ <code className="min-w-0 break-all font-mono text-xs">+ {rule}+ </code>+ <Button+ disabled={saving}+ onClick={() =>+ void save({+ ...policy,+ ask: policy.ask.filter((one) => one !== rule),+ })+ }+ size="sm"+ variant="ghost"+ >+ Remove+ </Button>+ </li>+ ))}+ </ul>+ )}++ <div className="mt-3 flex gap-2">+ <Input+ aria-label="A rule that asks a person first, written in CEL"+ className="min-w-0 flex-1 font-mono text-xs"+ onChange={(event) => {+ setAskDraft(event.target.value);+ setSaved(false);+ }}+ onKeyDown={(event) => {+ if (event.key === "Enter") addAskRule(askDraft);+ }}+ placeholder='intent == "write_file" && !matches(file.path, "^notes/")'+ value={askDraft}+ />+ <Button+ disabled={saving || askDraft.trim().length === 0}+ onClick={() => addAskRule(askDraft)}+ size="sm"+ >+ Add rule+ </Button>+ </div>++ <ul className="mt-3 space-y-2">+ {ASK_PRESETS.map((preset) => (+ <li className="flex items-start gap-3" key={preset.rule}>+ <Button+ className="shrink-0"+ disabled={saving || policy.ask.includes(preset.rule)}+ onClick={() => addAskRule(preset.rule)}+ size="sm"+ variant="outline"+ >+ {preset.label}+ </Button>+ {preset.cost ? (+ <span className="pt-1 text-xs text-muted-foreground">+ {preset.cost}+ </span>+ ) : null}+ </li>+ ))}+ </ul>++ <p className="mt-3 text-xs text-muted-foreground">+ The Bot stops and waits where one of these matches, and carries on+ with the same action if somebody allows it. Checked after the rules+ above and before the ones below, so something you have forbidden stays+ forbidden and is never offered as a question. In{" "}+ <span className="font-medium">Record it and allow it</span> nothing+ stops: a match is recorded as a question that would have been asked.+ </p>+ </PageSection>+<PageSection title="Otherwise it may"><ul className="mt-2 space-y-1">{policy.allow.map((rule) => (diff --git a/docs/architecture.md b/docs/architecture.mdindex 9e5f1401..9f322b5f 100644--- a/docs/architecture.md+++ b/docs/architecture.md@@ -54,6 +54,7 @@ Policy rules can inspect:- `page.url`, `page.host`- `element.ref`, `element.role`, `element.name`, `element.type`- `key`+- `submit`, true when a type call will press Enter when it has finished- `file.path`, `file.name`, `file.extension`- `mcp.server`, `mcp.tool`, `mcp.effect`- `repeat.count`@@ -67,12 +68,33 @@ the process that served the call, so two API replicas split it, and it covers thworkspace only: a call to another server's tools over MCP always reports one.Rules use CEL expressions plus case-insensitive `contains()` and `matches()`.-Deny rules are evaluated before allow rules. The policy engine fails closed: a-missing or empty policy permits nothing, a broken deny rule denies, and a broken-allow rule does not permit. OpenBot's shipped startup default is explicit:-`deny: []` and `allow: ["true"]`, unless `AGENT_COMPUTER_POLICY` or a saved-administrator policy replaces it. A malformed configured policy stops server-startup.+Rules are evaluated in three lists, in order: `deny`, then `ask`, then `allow`.+The policy engine fails closed: a missing or empty policy permits nothing, a+broken deny rule denies, a broken ask rule asks, and a broken allow rule does not+permit. OpenBot's shipped startup default is explicit: `deny: []`, `ask: []` and+`allow: ["true"]`, unless `AGENT_COMPUTER_POLICY` or a saved administrator policy+replaces it. A malformed configured policy stops server startup.++An `ask` match stops the action and puts it in front of a person in the+conversation, then carries on with the same call if they allow it. The pending+question lives in the server process, is bound to a fingerprint of the exact+action it was raised for, and is single use, so an approval cannot be replayed+against a different one. Answering writes `approval.granted` or `approval.denied`+under the answering person's own actor, separately from the action row, and the+question itself writes `approval.requested` when it is raised. In `dry-run` an+ask is recorded and interrupts nobody.++The same three lists judge a Bot's MCP tool calls, `ask` included: a rule such as+`intent == "write_tool" && mcp.server == "jira"` stops the call and asks rather+than refusing it, and the question is answered on the same surface, `POST+/api/approvals/:botId/:approvalId`, as one raised by a click. That surface is+mounted whether or not a computer is configured, because a question nobody can be+shown is worse than a rule that never fired.++Pending questions are held in the server process, like the snapshot cache, so a+deployment running more than one server replica can raise a question on one and+poll for it on another, where it does not exist. Both features assume a single+process today.## Computersdiff --git a/docs/configuration.md b/docs/configuration.mdindex 0657fb24..ba59015b 100644--- a/docs/configuration.md+++ b/docs/configuration.md@@ -100,7 +100,7 @@ Google OAuth client id and secret must be configured together. If Google OAuth i| `COMPUTER_SUPERVISOR_URL` | Supervisor URL for per-Bot computers. If absent, Bots share `AGENT_COMPUTER_URL`. || `SUPERVISOR_TOKEN` | Bearer token required by the supervisor. || `AGENT_COMPUTER_ALLOW_PRIVATE_HOSTS` | Local-only private-host browsing when `true`. Cloud metadata addresses are still refused. |-| `AGENT_COMPUTER_POLICY` | JSON action policy: `{"mode":"enforce","deny":[...],"allow":[...]}`. |+| `AGENT_COMPUTER_POLICY` | JSON action policy: `{"mode":"enforce","deny":[...],"ask":[...],"allow":[...]}`. || `COMPUTER_RUNTIME` | Set to `runsc` to run supervised computers under gVisor. |`agent-computer` also reads:diff --git a/server/drizzle/0001_gigantic_sumo.sql b/server/drizzle/0001_gigantic_sumo.sqlnew file mode 100644index 00000000..22458ddc--- /dev/null+++ b/server/drizzle/0001_gigantic_sumo.sql@@ -0,0 +1 @@+ALTER TABLE "action_policy" ADD COLUMN "ask" text[] DEFAULT '{}' NOT NULL;\ No newline at end of filediff --git a/server/drizzle/meta/0001_snapshot.json b/server/drizzle/meta/0001_snapshot.jsonnew file mode 100644index 00000000..edd784a6--- /dev/null+++ b/server/drizzle/meta/0001_snapshot.json@@ -0,0 +1,2510 @@+{+ "id": "c2caefc9-77dd-42f2-9d57-0cb3e87225d0",+ "prevId": "084d702b-09fd-44df-a60a-22477be02359",+ "version": "7",+ "dialect": "postgresql",+ "tables": {+ "public.accounts": {+ "name": "accounts",+ "schema": "",+ "columns": {+ "id": {+ "name": "id",+ "type": "text",+ "primaryKey": true,+ "notNull": true+ },+ "account_id": {+ "name": "account_id",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "provider_id": {+ "name": "provider_id",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "user_id": {+ "name": "user_id",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "access_token": {+ "name": "access_token",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "refresh_token": {+ "name": "refresh_token",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "id_token": {+ "name": "id_token",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "access_token_expires_at": {+ "name": "access_token_expires_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": false+ },+ "refresh_token_expires_at": {+ "name": "refresh_token_expires_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": false+ },+ "scope": {+ "name": "scope",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "password": {+ "name": "password",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "created_at": {+ "name": "created_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ },+ "updated_at": {+ "name": "updated_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {+ "accounts_provider_account_idx": {+ "name": "accounts_provider_account_idx",+ "columns": [+ {+ "expression": "provider_id",+ "isExpression": false,+ "asc": true,+ "nulls": "last"+ },+ {+ "expression": "account_id",+ "isExpression": false,+ "asc": true,+ "nulls": "last"+ }+ ],+ "isUnique": true,+ "concurrently": false,+ "method": "btree",+ "with": {}+ }+ },+ "foreignKeys": {+ "accounts_user_id_users_id_fk": {+ "name": "accounts_user_id_users_id_fk",+ "tableFrom": "accounts",+ "tableTo": "users",+ "columnsFrom": ["user_id"],+ "columnsTo": ["id"],+ "onDelete": "cascade",+ "onUpdate": "no action"+ }+ },+ "compositePrimaryKeys": {},+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.agents": {+ "name": "agents",+ "schema": "",+ "columns": {+ "id": {+ "name": "id",+ "type": "text",+ "primaryKey": true,+ "notNull": true+ },+ "name": {+ "name": "name",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "type": {+ "name": "type",+ "type": "agent_type",+ "typeSchema": "public",+ "primaryKey": false,+ "notNull": true+ },+ "configuration": {+ "name": "configuration",+ "type": "jsonb",+ "primaryKey": false,+ "notNull": true+ },+ "package_id": {+ "name": "package_id",+ "type": "uuid",+ "primaryKey": false,+ "notNull": false+ },+ "override": {+ "name": "override",+ "type": "jsonb",+ "primaryKey": false,+ "notNull": false+ },+ "created_at": {+ "name": "created_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ },+ "updated_at": {+ "name": "updated_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {},+ "foreignKeys": {+ "agents_package_id_deployment_packages_id_fk": {+ "name": "agents_package_id_deployment_packages_id_fk",+ "tableFrom": "agents",+ "tableTo": "deployment_packages",+ "columnsFrom": ["package_id"],+ "columnsTo": ["id"],+ "onDelete": "set null",+ "onUpdate": "no action"+ }+ },+ "compositePrimaryKeys": {},+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.audit_events": {+ "name": "audit_events",+ "schema": "",+ "columns": {+ "id": {+ "name": "id",+ "type": "uuid",+ "primaryKey": true,+ "notNull": true,+ "default": "gen_random_uuid()"+ },+ "actor_user_id": {+ "name": "actor_user_id",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "event_type": {+ "name": "event_type",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "target_type": {+ "name": "target_type",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "target_id": {+ "name": "target_id",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "payload": {+ "name": "payload",+ "type": "jsonb",+ "primaryKey": false,+ "notNull": true+ },+ "created_at": {+ "name": "created_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {+ "audit_events_created_at_idx": {+ "name": "audit_events_created_at_idx",+ "columns": [+ {+ "expression": "created_at",+ "isExpression": false,+ "asc": true,+ "nulls": "last"+ }+ ],+ "isUnique": false,+ "concurrently": false,+ "method": "btree",+ "with": {}+ }+ },+ "foreignKeys": {},+ "compositePrimaryKeys": {},+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.channel_agents": {+ "name": "channel_agents",+ "schema": "",+ "columns": {+ "channel_id": {+ "name": "channel_id",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "agent_id": {+ "name": "agent_id",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "created_at": {+ "name": "created_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {},+ "foreignKeys": {+ "channel_agents_channel_id_channels_id_fk": {+ "name": "channel_agents_channel_id_channels_id_fk",+ "tableFrom": "channel_agents",+ "tableTo": "channels",+ "columnsFrom": ["channel_id"],+ "columnsTo": ["id"],+ "onDelete": "cascade",+ "onUpdate": "no action"+ },+ "channel_agents_agent_id_agents_id_fk": {+ "name": "channel_agents_agent_id_agents_id_fk",+ "tableFrom": "channel_agents",+ "tableTo": "agents",+ "columnsFrom": ["agent_id"],+ "columnsTo": ["id"],+ "onDelete": "cascade",+ "onUpdate": "no action"+ }+ },+ "compositePrimaryKeys": {+ "channel_agents_channel_id_agent_id_pk": {+ "name": "channel_agents_channel_id_agent_id_pk",+ "columns": ["channel_id", "agent_id"]+ }+ },+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.channel_memberships": {+ "name": "channel_memberships",+ "schema": "",+ "columns": {+ "channel_id": {+ "name": "channel_id",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "user_id": {+ "name": "user_id",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "created_at": {+ "name": "created_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {},+ "foreignKeys": {+ "channel_memberships_channel_id_channels_id_fk": {+ "name": "channel_memberships_channel_id_channels_id_fk",+ "tableFrom": "channel_memberships",+ "tableTo": "channels",+ "columnsFrom": ["channel_id"],+ "columnsTo": ["id"],+ "onDelete": "cascade",+ "onUpdate": "no action"+ },+ "channel_memberships_user_id_users_id_fk": {+ "name": "channel_memberships_user_id_users_id_fk",+ "tableFrom": "channel_memberships",+ "tableTo": "users",+ "columnsFrom": ["user_id"],+ "columnsTo": ["id"],+ "onDelete": "cascade",+ "onUpdate": "no action"+ }+ },+ "compositePrimaryKeys": {+ "channel_memberships_channel_id_user_id_pk": {+ "name": "channel_memberships_channel_id_user_id_pk",+ "columns": ["channel_id", "user_id"]+ }+ },+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.channels": {+ "name": "channels",+ "schema": "",+ "columns": {+ "id": {+ "name": "id",+ "type": "text",+ "primaryKey": true,+ "notNull": true+ },+ "name": {+ "name": "name",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "description": {+ "name": "description",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "suggested_prompts": {+ "name": "suggested_prompts",+ "type": "text[]",+ "primaryKey": false,+ "notNull": true,+ "default": "'{}'"+ },+ "allowed_groups": {+ "name": "allowed_groups",+ "type": "text[]",+ "primaryKey": false,+ "notNull": true,+ "default": "'{}'"+ },+ "package_id": {+ "name": "package_id",+ "type": "uuid",+ "primaryKey": false,+ "notNull": false+ },+ "override": {+ "name": "override",+ "type": "jsonb",+ "primaryKey": false,+ "notNull": false+ },+ "last_message": {+ "name": "last_message",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "last_message_at": {+ "name": "last_message_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": false+ },+ "last_message_agent_id": {+ "name": "last_message_agent_id",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "created_at": {+ "name": "created_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ },+ "updated_at": {+ "name": "updated_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {+ "channels_recent_activity_idx": {+ "name": "channels_recent_activity_idx",+ "columns": [+ {+ "expression": "COALESCE(\"last_message_at\", \"created_at\") DESC",+ "asc": true,+ "isExpression": true,+ "nulls": "last"+ }+ ],+ "isUnique": false,+ "concurrently": false,+ "method": "btree",+ "with": {}+ }+ },+ "foreignKeys": {+ "channels_package_id_deployment_packages_id_fk": {+ "name": "channels_package_id_deployment_packages_id_fk",+ "tableFrom": "channels",+ "tableTo": "deployment_packages",+ "columnsFrom": ["package_id"],+ "columnsTo": ["id"],+ "onDelete": "set null",+ "onUpdate": "no action"+ },+ "channels_last_message_agent_id_agents_id_fk": {+ "name": "channels_last_message_agent_id_agents_id_fk",+ "tableFrom": "channels",+ "tableTo": "agents",+ "columnsFrom": ["last_message_agent_id"],+ "columnsTo": ["id"],+ "onDelete": "set null",+ "onUpdate": "no action"+ }+ },+ "compositePrimaryKeys": {},+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.chunks": {+ "name": "chunks",+ "schema": "",+ "columns": {+ "id": {+ "name": "id",+ "type": "uuid",+ "primaryKey": true,+ "notNull": true,+ "default": "gen_random_uuid()"+ },+ "document_id": {+ "name": "document_id",+ "type": "uuid",+ "primaryKey": false,+ "notNull": true+ },+ "position": {+ "name": "position",+ "type": "integer",+ "primaryKey": false,+ "notNull": true+ },+ "content": {+ "name": "content",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "embedding": {+ "name": "embedding",+ "type": "vector(1536)",+ "primaryKey": false,+ "notNull": true+ },+ "created_at": {+ "name": "created_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {+ "chunks_document_position_idx": {+ "name": "chunks_document_position_idx",+ "columns": [+ {+ "expression": "document_id",+ "isExpression": false,+ "asc": true,+ "nulls": "last"+ },+ {+ "expression": "position",+ "isExpression": false,+ "asc": true,+ "nulls": "last"+ }+ ],+ "isUnique": true,+ "concurrently": false,+ "method": "btree",+ "with": {}+ },+ "chunks_document_idx": {+ "name": "chunks_document_idx",+ "columns": [+ {+ "expression": "document_id",+ "isExpression": false,+ "asc": true,+ "nulls": "last"+ }+ ],+ "isUnique": false,+ "concurrently": false,+ "method": "btree",+ "with": {}+ }+ },+ "foreignKeys": {+ "chunks_document_id_documents_id_fk": {+ "name": "chunks_document_id_documents_id_fk",+ "tableFrom": "chunks",+ "tableTo": "documents",+ "columnsFrom": ["document_id"],+ "columnsTo": ["id"],+ "onDelete": "cascade",+ "onUpdate": "no action"+ }+ },+ "compositePrimaryKeys": {},+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.connector_cursors": {+ "name": "connector_cursors",+ "schema": "",+ "columns": {+ "connector_instance_id": {+ "name": "connector_instance_id",+ "type": "uuid",+ "primaryKey": true,+ "notNull": true+ },+ "cursor": {+ "name": "cursor",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "updated_at": {+ "name": "updated_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {},+ "foreignKeys": {+ "connector_cursors_connector_instance_id_connector_instances_id_fk": {+ "name": "connector_cursors_connector_instance_id_connector_instances_id_fk",+ "tableFrom": "connector_cursors",+ "tableTo": "connector_instances",+ "columnsFrom": ["connector_instance_id"],+ "columnsTo": ["id"],+ "onDelete": "cascade",+ "onUpdate": "no action"+ }+ },+ "compositePrimaryKeys": {},+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.connector_instances": {+ "name": "connector_instances",+ "schema": "",+ "columns": {+ "id": {+ "name": "id",+ "type": "uuid",+ "primaryKey": true,+ "notNull": true,+ "default": "gen_random_uuid()"+ },+ "type": {+ "name": "type",+ "type": "connector_type",+ "typeSchema": "public",+ "primaryKey": false,+ "notNull": true+ },+ "credential_id": {+ "name": "credential_id",+ "type": "uuid",+ "primaryKey": false,+ "notNull": false+ },+ "status": {+ "name": "status",+ "type": "sync_status",+ "typeSchema": "public",+ "primaryKey": false,+ "notNull": true,+ "default": "'pending'"+ },+ "source_metadata": {+ "name": "source_metadata",+ "type": "jsonb",+ "primaryKey": false,+ "notNull": true+ },+ "created_at": {+ "name": "created_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ },+ "updated_at": {+ "name": "updated_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {},+ "foreignKeys": {+ "connector_instances_credential_id_credentials_id_fk": {+ "name": "connector_instances_credential_id_credentials_id_fk",+ "tableFrom": "connector_instances",+ "tableTo": "credentials",+ "columnsFrom": ["credential_id"],+ "columnsTo": ["id"],+ "onDelete": "set null",+ "onUpdate": "no action"+ }+ },+ "compositePrimaryKeys": {},+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.credentials": {+ "name": "credentials",+ "schema": "",+ "columns": {+ "id": {+ "name": "id",+ "type": "uuid",+ "primaryKey": true,+ "notNull": true,+ "default": "gen_random_uuid()"+ },+ "kind": {+ "name": "kind",+ "type": "credential_kind",+ "typeSchema": "public",+ "primaryKey": false,+ "notNull": true+ },+ "provider": {+ "name": "provider",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "encrypted_value": {+ "name": "encrypted_value",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "key_id": {+ "name": "key_id",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "metadata": {+ "name": "metadata",+ "type": "jsonb",+ "primaryKey": false,+ "notNull": true+ },+ "revoked_at": {+ "name": "revoked_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": false+ },+ "created_at": {+ "name": "created_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ },+ "updated_at": {+ "name": "updated_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {},+ "foreignKeys": {},+ "compositePrimaryKeys": {},+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.deployment_packages": {+ "name": "deployment_packages",+ "schema": "",+ "columns": {+ "id": {+ "name": "id",+ "type": "uuid",+ "primaryKey": true,+ "notNull": true,+ "default": "gen_random_uuid()"+ },+ "tenant_id": {+ "name": "tenant_id",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "source_path": {+ "name": "source_path",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "checksum": {+ "name": "checksum",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "loaded_at": {+ "name": "loaded_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {},+ "foreignKeys": {},+ "compositePrimaryKeys": {},+ "uniqueConstraints": {+ "deployment_packages_tenant_id_unique": {+ "name": "deployment_packages_tenant_id_unique",+ "nullsNotDistinct": false,+ "columns": ["tenant_id"]+ }+ },+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.document_acls": {+ "name": "document_acls",+ "schema": "",+ "columns": {+ "id": {+ "name": "id",+ "type": "uuid",+ "primaryKey": true,+ "notNull": true,+ "default": "gen_random_uuid()"+ },+ "document_id": {+ "name": "document_id",+ "type": "uuid",+ "primaryKey": false,+ "notNull": true+ },+ "principal": {+ "name": "principal",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "effect": {+ "name": "effect",+ "type": "acl_effect",+ "typeSchema": "public",+ "primaryKey": false,+ "notNull": true+ },+ "created_at": {+ "name": "created_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {+ "document_acls_document_principal_effect_idx": {+ "name": "document_acls_document_principal_effect_idx",+ "columns": [+ {+ "expression": "document_id",+ "isExpression": false,+ "asc": true,+ "nulls": "last"+ },+ {+ "expression": "principal",+ "isExpression": false,+ "asc": true,+ "nulls": "last"+ },+ {+ "expression": "effect",+ "isExpression": false,+ "asc": true,+ "nulls": "last"+ }+ ],+ "isUnique": true,+ "concurrently": false,+ "method": "btree",+ "with": {}+ },+ "document_acls_principal_idx": {+ "name": "document_acls_principal_idx",+ "columns": [+ {+ "expression": "principal",+ "isExpression": false,+ "asc": true,+ "nulls": "last"+ }+ ],+ "isUnique": false,+ "concurrently": false,+ "method": "btree",+ "with": {}+ }+ },+ "foreignKeys": {+ "document_acls_document_id_documents_id_fk": {+ "name": "document_acls_document_id_documents_id_fk",+ "tableFrom": "document_acls",+ "tableTo": "documents",+ "columnsFrom": ["document_id"],+ "columnsTo": ["id"],+ "onDelete": "cascade",+ "onUpdate": "no action"+ }+ },+ "compositePrimaryKeys": {},+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.documents": {+ "name": "documents",+ "schema": "",+ "columns": {+ "id": {+ "name": "id",+ "type": "uuid",+ "primaryKey": true,+ "notNull": true,+ "default": "gen_random_uuid()"+ },+ "connector_instance_id": {+ "name": "connector_instance_id",+ "type": "uuid",+ "primaryKey": false,+ "notNull": true+ },+ "source_id": {+ "name": "source_id",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "title": {+ "name": "title",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "canonical_url": {+ "name": "canonical_url",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "metadata": {+ "name": "metadata",+ "type": "jsonb",+ "primaryKey": false,+ "notNull": true+ },+ "content_hash": {+ "name": "content_hash",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "deleted_at": {+ "name": "deleted_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": false+ },+ "created_at": {+ "name": "created_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ },+ "updated_at": {+ "name": "updated_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {+ "documents_connector_source_idx": {+ "name": "documents_connector_source_idx",+ "columns": [+ {+ "expression": "connector_instance_id",+ "isExpression": false,+ "asc": true,+ "nulls": "last"+ },+ {+ "expression": "source_id",+ "isExpression": false,+ "asc": true,+ "nulls": "last"+ }+ ],+ "isUnique": true,+ "concurrently": false,+ "method": "btree",+ "with": {}+ },+ "documents_connector_deleted_idx": {+ "name": "documents_connector_deleted_idx",+ "columns": [+ {+ "expression": "connector_instance_id",+ "isExpression": false,+ "asc": true,+ "nulls": "last"+ },+ {+ "expression": "deleted_at",+ "isExpression": false,+ "asc": true,+ "nulls": "last"+ }+ ],+ "isUnique": false,+ "concurrently": false,+ "method": "btree",+ "with": {}+ }+ },+ "foreignKeys": {+ "documents_connector_instance_id_connector_instances_id_fk": {+ "name": "documents_connector_instance_id_connector_instances_id_fk",+ "tableFrom": "documents",+ "tableTo": "connector_instances",+ "columnsFrom": ["connector_instance_id"],+ "columnsTo": ["id"],+ "onDelete": "cascade",+ "onUpdate": "no action"+ }+ },+ "compositePrimaryKeys": {},+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.intelligence_channel_mappings": {+ "name": "intelligence_channel_mappings",+ "schema": "",+ "columns": {+ "user_id": {+ "name": "user_id",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "channel_id": {+ "name": "channel_id",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "thread_id": {+ "name": "thread_id",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "created_at": {+ "name": "created_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ },+ "updated_at": {+ "name": "updated_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {+ "intelligence_channel_mappings_thread_idx": {+ "name": "intelligence_channel_mappings_thread_idx",+ "columns": [+ {+ "expression": "thread_id",+ "isExpression": false,+ "asc": true,+ "nulls": "last"+ }+ ],+ "isUnique": true,+ "concurrently": false,+ "method": "btree",+ "with": {}+ }+ },+ "foreignKeys": {+ "intelligence_channel_mappings_user_id_users_id_fk": {+ "name": "intelligence_channel_mappings_user_id_users_id_fk",+ "tableFrom": "intelligence_channel_mappings",+ "tableTo": "users",+ "columnsFrom": ["user_id"],+ "columnsTo": ["id"],+ "onDelete": "cascade",+ "onUpdate": "no action"+ },+ "intelligence_channel_mappings_channel_id_channels_id_fk": {+ "name": "intelligence_channel_mappings_channel_id_channels_id_fk",+ "tableFrom": "intelligence_channel_mappings",+ "tableTo": "channels",+ "columnsFrom": ["channel_id"],+ "columnsTo": ["id"],+ "onDelete": "cascade",+ "onUpdate": "no action"+ }+ },+ "compositePrimaryKeys": {+ "intelligence_channel_mappings_user_id_channel_id_pk": {+ "name": "intelligence_channel_mappings_user_id_channel_id_pk",+ "columns": ["user_id", "channel_id"]+ }+ },+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.sessions": {+ "name": "sessions",+ "schema": "",+ "columns": {+ "id": {+ "name": "id",+ "type": "text",+ "primaryKey": true,+ "notNull": true+ },+ "user_id": {+ "name": "user_id",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "token": {+ "name": "token",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "expires_at": {+ "name": "expires_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true+ },+ "ip_address": {+ "name": "ip_address",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "user_agent": {+ "name": "user_agent",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "created_at": {+ "name": "created_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ },+ "updated_at": {+ "name": "updated_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {},+ "foreignKeys": {+ "sessions_user_id_users_id_fk": {+ "name": "sessions_user_id_users_id_fk",+ "tableFrom": "sessions",+ "tableTo": "users",+ "columnsFrom": ["user_id"],+ "columnsTo": ["id"],+ "onDelete": "cascade",+ "onUpdate": "no action"+ }+ },+ "compositePrimaryKeys": {},+ "uniqueConstraints": {+ "sessions_token_unique": {+ "name": "sessions_token_unique",+ "nullsNotDistinct": false,+ "columns": ["token"]+ }+ },+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.sync_runs": {+ "name": "sync_runs",+ "schema": "",+ "columns": {+ "id": {+ "name": "id",+ "type": "uuid",+ "primaryKey": true,+ "notNull": true,+ "default": "gen_random_uuid()"+ },+ "connector_instance_id": {+ "name": "connector_instance_id",+ "type": "uuid",+ "primaryKey": false,+ "notNull": true+ },+ "status": {+ "name": "status",+ "type": "sync_status",+ "typeSchema": "public",+ "primaryKey": false,+ "notNull": true+ },+ "started_at": {+ "name": "started_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ },+ "completed_at": {+ "name": "completed_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": false+ },+ "error": {+ "name": "error",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "stats": {+ "name": "stats",+ "type": "jsonb",+ "primaryKey": false,+ "notNull": true+ }+ },+ "indexes": {+ "sync_runs_connector_started_at_idx": {+ "name": "sync_runs_connector_started_at_idx",+ "columns": [+ {+ "expression": "connector_instance_id",+ "isExpression": false,+ "asc": true,+ "nulls": "last"+ },+ {+ "expression": "started_at",+ "isExpression": false,+ "asc": true,+ "nulls": "last"+ }+ ],+ "isUnique": false,+ "concurrently": false,+ "method": "btree",+ "with": {}+ }+ },+ "foreignKeys": {+ "sync_runs_connector_instance_id_connector_instances_id_fk": {+ "name": "sync_runs_connector_instance_id_connector_instances_id_fk",+ "tableFrom": "sync_runs",+ "tableTo": "connector_instances",+ "columnsFrom": ["connector_instance_id"],+ "columnsTo": ["id"],+ "onDelete": "cascade",+ "onUpdate": "no action"+ }+ },+ "compositePrimaryKeys": {},+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.user_roles": {+ "name": "user_roles",+ "schema": "",+ "columns": {+ "user_id": {+ "name": "user_id",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "role": {+ "name": "role",+ "type": "role",+ "typeSchema": "public",+ "primaryKey": false,+ "notNull": true+ },+ "created_at": {+ "name": "created_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {},+ "foreignKeys": {+ "user_roles_user_id_users_id_fk": {+ "name": "user_roles_user_id_users_id_fk",+ "tableFrom": "user_roles",+ "tableTo": "users",+ "columnsFrom": ["user_id"],+ "columnsTo": ["id"],+ "onDelete": "cascade",+ "onUpdate": "no action"+ }+ },+ "compositePrimaryKeys": {+ "user_roles_user_id_role_pk": {+ "name": "user_roles_user_id_role_pk",+ "columns": ["user_id", "role"]+ }+ },+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.users": {+ "name": "users",+ "schema": "",+ "columns": {+ "id": {+ "name": "id",+ "type": "text",+ "primaryKey": true,+ "notNull": true+ },+ "email": {+ "name": "email",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "name": {+ "name": "name",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "image": {+ "name": "image",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "email_verified": {+ "name": "email_verified",+ "type": "boolean",+ "primaryKey": false,+ "notNull": true,+ "default": false+ },+ "groups": {+ "name": "groups",+ "type": "text[]",+ "primaryKey": false,+ "notNull": true,+ "default": "'{}'"+ },+ "created_at": {+ "name": "created_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ },+ "updated_at": {+ "name": "updated_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {},+ "foreignKeys": {},+ "compositePrimaryKeys": {},+ "uniqueConstraints": {+ "users_email_unique": {+ "name": "users_email_unique",+ "nullsNotDistinct": false,+ "columns": ["email"]+ }+ },+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.verifications": {+ "name": "verifications",+ "schema": "",+ "columns": {+ "id": {+ "name": "id",+ "type": "text",+ "primaryKey": true,+ "notNull": true+ },+ "identifier": {+ "name": "identifier",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "value": {+ "name": "value",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "expires_at": {+ "name": "expires_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true+ },+ "created_at": {+ "name": "created_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ },+ "updated_at": {+ "name": "updated_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {},+ "foreignKeys": {},+ "compositePrimaryKeys": {},+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.webhook_subscriptions": {+ "name": "webhook_subscriptions",+ "schema": "",+ "columns": {+ "id": {+ "name": "id",+ "type": "uuid",+ "primaryKey": true,+ "notNull": true,+ "default": "gen_random_uuid()"+ },+ "connector_instance_id": {+ "name": "connector_instance_id",+ "type": "uuid",+ "primaryKey": false,+ "notNull": true+ },+ "provider_subscription_id": {+ "name": "provider_subscription_id",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "expires_at": {+ "name": "expires_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": false+ },+ "created_at": {+ "name": "created_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {},+ "foreignKeys": {+ "webhook_subscriptions_connector_instance_id_connector_instances_id_fk": {+ "name": "webhook_subscriptions_connector_instance_id_connector_instances_id_fk",+ "tableFrom": "webhook_subscriptions",+ "tableTo": "connector_instances",+ "columnsFrom": ["connector_instance_id"],+ "columnsTo": ["id"],+ "onDelete": "cascade",+ "onUpdate": "no action"+ }+ },+ "compositePrimaryKeys": {},+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.action_policy": {+ "name": "action_policy",+ "schema": "",+ "columns": {+ "id": {+ "name": "id",+ "type": "text",+ "primaryKey": true,+ "notNull": true+ },+ "mode": {+ "name": "mode",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "deny": {+ "name": "deny",+ "type": "text[]",+ "primaryKey": false,+ "notNull": true+ },+ "ask": {+ "name": "ask",+ "type": "text[]",+ "primaryKey": false,+ "notNull": true,+ "default": "'{}'"+ },+ "allow": {+ "name": "allow",+ "type": "text[]",+ "primaryKey": false,+ "notNull": true+ },+ "updated_by": {+ "name": "updated_by",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "updated_at": {+ "name": "updated_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {},+ "foreignKeys": {},+ "compositePrimaryKeys": {},+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.agent_preferences": {+ "name": "agent_preferences",+ "schema": "",+ "columns": {+ "user_id": {+ "name": "user_id",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "agent_id": {+ "name": "agent_id",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "hidden_at": {+ "name": "hidden_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": false+ }+ },+ "indexes": {},+ "foreignKeys": {+ "agent_preferences_user_id_users_id_fk": {+ "name": "agent_preferences_user_id_users_id_fk",+ "tableFrom": "agent_preferences",+ "tableTo": "users",+ "columnsFrom": ["user_id"],+ "columnsTo": ["id"],+ "onDelete": "cascade",+ "onUpdate": "no action"+ },+ "agent_preferences_agent_id_agents_id_fk": {+ "name": "agent_preferences_agent_id_agents_id_fk",+ "tableFrom": "agent_preferences",+ "tableTo": "agents",+ "columnsFrom": ["agent_id"],+ "columnsTo": ["id"],+ "onDelete": "cascade",+ "onUpdate": "no action"+ }+ },+ "compositePrimaryKeys": {+ "agent_preferences_user_id_agent_id_pk": {+ "name": "agent_preferences_user_id_agent_id_pk",+ "columns": ["user_id", "agent_id"]+ }+ },+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.agent_profiles": {+ "name": "agent_profiles",+ "schema": "",+ "columns": {+ "agent_id": {+ "name": "agent_id",+ "type": "text",+ "primaryKey": true,+ "notNull": true+ },+ "owner_user_id": {+ "name": "owner_user_id",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "title": {+ "name": "title",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "role_description": {+ "name": "role_description",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "avatar_seed": {+ "name": "avatar_seed",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "visibility": {+ "name": "visibility",+ "type": "agent_visibility",+ "typeSchema": "public",+ "primaryKey": false,+ "notNull": true+ },+ "deleted_at": {+ "name": "deleted_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": false+ },+ "created_at": {+ "name": "created_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ },+ "updated_at": {+ "name": "updated_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {+ "agent_profiles_visibility_deleted_idx": {+ "name": "agent_profiles_visibility_deleted_idx",+ "columns": [+ {+ "expression": "visibility",+ "isExpression": false,+ "asc": true,+ "nulls": "last"+ },+ {+ "expression": "deleted_at",+ "isExpression": false,+ "asc": true,+ "nulls": "last"+ }+ ],+ "isUnique": false,+ "concurrently": false,+ "method": "btree",+ "with": {}+ }+ },+ "foreignKeys": {+ "agent_profiles_agent_id_agents_id_fk": {+ "name": "agent_profiles_agent_id_agents_id_fk",+ "tableFrom": "agent_profiles",+ "tableTo": "agents",+ "columnsFrom": ["agent_id"],+ "columnsTo": ["id"],+ "onDelete": "cascade",+ "onUpdate": "no action"+ },+ "agent_profiles_owner_user_id_users_id_fk": {+ "name": "agent_profiles_owner_user_id_users_id_fk",+ "tableFrom": "agent_profiles",+ "tableTo": "users",+ "columnsFrom": ["owner_user_id"],+ "columnsTo": ["id"],+ "onDelete": "set null",+ "onUpdate": "no action"+ }+ },+ "compositePrimaryKeys": {},+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.component_exclusions": {+ "name": "component_exclusions",+ "schema": "",+ "columns": {+ "component_name": {+ "name": "component_name",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "agent_id": {+ "name": "agent_id",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "withheld_by": {+ "name": "withheld_by",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "created_at": {+ "name": "created_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ },+ "updated_at": {+ "name": "updated_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {},+ "foreignKeys": {+ "component_exclusions_component_name_components_name_fk": {+ "name": "component_exclusions_component_name_components_name_fk",+ "tableFrom": "component_exclusions",+ "tableTo": "components",+ "columnsFrom": ["component_name"],+ "columnsTo": ["name"],+ "onDelete": "cascade",+ "onUpdate": "no action"+ },+ "component_exclusions_agent_id_agents_id_fk": {+ "name": "component_exclusions_agent_id_agents_id_fk",+ "tableFrom": "component_exclusions",+ "tableTo": "agents",+ "columnsFrom": ["agent_id"],+ "columnsTo": ["id"],+ "onDelete": "cascade",+ "onUpdate": "no action"+ }+ },+ "compositePrimaryKeys": {+ "component_exclusions_component_name_agent_id_pk": {+ "name": "component_exclusions_component_name_agent_id_pk",+ "columns": ["component_name", "agent_id"]+ }+ },+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.component_functions": {+ "name": "component_functions",+ "schema": "",+ "columns": {+ "component_name": {+ "name": "component_name",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "function_name": {+ "name": "function_name",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "granted_by": {+ "name": "granted_by",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "created_at": {+ "name": "created_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ },+ "updated_at": {+ "name": "updated_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {},+ "foreignKeys": {+ "component_functions_component_name_components_name_fk": {+ "name": "component_functions_component_name_components_name_fk",+ "tableFrom": "component_functions",+ "tableTo": "components",+ "columnsFrom": ["component_name"],+ "columnsTo": ["name"],+ "onDelete": "cascade",+ "onUpdate": "no action"+ }+ },+ "compositePrimaryKeys": {+ "component_functions_component_name_function_name_pk": {+ "name": "component_functions_component_name_function_name_pk",+ "columns": ["component_name", "function_name"]+ }+ },+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.components": {+ "name": "components",+ "schema": "",+ "columns": {+ "name": {+ "name": "name",+ "type": "text",+ "primaryKey": true,+ "notNull": true+ },+ "title": {+ "name": "title",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "kind": {+ "name": "kind",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "draft_description": {+ "name": "draft_description",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "published_description": {+ "name": "published_description",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "published": {+ "name": "published",+ "type": "boolean",+ "primaryKey": false,+ "notNull": true,+ "default": false+ },+ "published_at": {+ "name": "published_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": false+ },+ "updated_by": {+ "name": "updated_by",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "created_at": {+ "name": "created_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ },+ "updated_at": {+ "name": "updated_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {},+ "foreignKeys": {},+ "compositePrimaryKeys": {},+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.mcp_servers": {+ "name": "mcp_servers",+ "schema": "",+ "columns": {+ "id": {+ "name": "id",+ "type": "text",+ "primaryKey": true,+ "notNull": true+ },+ "title": {+ "name": "title",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "vendor": {+ "name": "vendor",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "url": {+ "name": "url",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "provenance": {+ "name": "provenance",+ "type": "text",+ "primaryKey": false,+ "notNull": true,+ "default": "'first-party'"+ },+ "credential_id": {+ "name": "credential_id",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "tools_refreshed_at": {+ "name": "tools_refreshed_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": false+ },+ "last_error": {+ "name": "last_error",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "added_by": {+ "name": "added_by",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "created_at": {+ "name": "created_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ },+ "updated_at": {+ "name": "updated_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {},+ "foreignKeys": {},+ "compositePrimaryKeys": {},+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.mcp_tools": {+ "name": "mcp_tools",+ "schema": "",+ "columns": {+ "server_id": {+ "name": "server_id",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "name": {+ "name": "name",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "description": {+ "name": "description",+ "type": "text",+ "primaryKey": false,+ "notNull": true,+ "default": "''"+ },+ "input_schema": {+ "name": "input_schema",+ "type": "jsonb",+ "primaryKey": false,+ "notNull": true,+ "default": "'{}'::jsonb"+ },+ "created_at": {+ "name": "created_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {},+ "foreignKeys": {+ "mcp_tools_server_id_mcp_servers_id_fk": {+ "name": "mcp_tools_server_id_mcp_servers_id_fk",+ "tableFrom": "mcp_tools",+ "tableTo": "mcp_servers",+ "columnsFrom": ["server_id"],+ "columnsTo": ["id"],+ "onDelete": "cascade",+ "onUpdate": "no action"+ }+ },+ "compositePrimaryKeys": {+ "mcp_tools_server_id_name_pk": {+ "name": "mcp_tools_server_id_name_pk",+ "columns": ["server_id", "name"]+ }+ },+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.plugin_grants": {+ "name": "plugin_grants",+ "schema": "",+ "columns": {+ "kind": {+ "name": "kind",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "ref": {+ "name": "ref",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "agent_id": {+ "name": "agent_id",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "granted_by": {+ "name": "granted_by",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "created_at": {+ "name": "created_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ },+ "updated_at": {+ "name": "updated_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {+ "plugin_grants_agent_idx": {+ "name": "plugin_grants_agent_idx",+ "columns": [+ {+ "expression": "agent_id",+ "isExpression": false,+ "asc": true,+ "nulls": "last"+ }+ ],+ "isUnique": false,+ "concurrently": false,+ "method": "btree",+ "with": {}+ }+ },+ "foreignKeys": {+ "plugin_grants_agent_id_agents_id_fk": {+ "name": "plugin_grants_agent_id_agents_id_fk",+ "tableFrom": "plugin_grants",+ "tableTo": "agents",+ "columnsFrom": ["agent_id"],+ "columnsTo": ["id"],+ "onDelete": "cascade",+ "onUpdate": "no action"+ }+ },+ "compositePrimaryKeys": {+ "plugin_grants_kind_ref_agent_id_pk": {+ "name": "plugin_grants_kind_ref_agent_id_pk",+ "columns": ["kind", "ref", "agent_id"]+ }+ },+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.sandboxed_components": {+ "name": "sandboxed_components",+ "schema": "",+ "columns": {+ "name": {+ "name": "name",+ "type": "text",+ "primaryKey": true,+ "notNull": true+ },+ "title": {+ "name": "title",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "draft_description": {+ "name": "draft_description",+ "type": "text",+ "primaryKey": false,+ "notNull": true,+ "default": "''"+ },+ "draft_html": {+ "name": "draft_html",+ "type": "text",+ "primaryKey": false,+ "notNull": true,+ "default": "''"+ },+ "draft_css": {+ "name": "draft_css",+ "type": "text",+ "primaryKey": false,+ "notNull": true,+ "default": "''"+ },+ "draft_js_functions": {+ "name": "draft_js_functions",+ "type": "text",+ "primaryKey": false,+ "notNull": true,+ "default": "''"+ },+ "draft_argument_schema": {+ "name": "draft_argument_schema",+ "type": "jsonb",+ "primaryKey": false,+ "notNull": true,+ "default": "'{}'::jsonb"+ },+ "published_description": {+ "name": "published_description",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "published_html": {+ "name": "published_html",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "published_css": {+ "name": "published_css",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "published_js_functions": {+ "name": "published_js_functions",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "published_argument_schema": {+ "name": "published_argument_schema",+ "type": "jsonb",+ "primaryKey": false,+ "notNull": false+ },+ "sample_arguments": {+ "name": "sample_arguments",+ "type": "jsonb",+ "primaryKey": false,+ "notNull": true,+ "default": "'{}'::jsonb"+ },+ "revision": {+ "name": "revision",+ "type": "integer",+ "primaryKey": false,+ "notNull": true,+ "default": 0+ },+ "published": {+ "name": "published",+ "type": "boolean",+ "primaryKey": false,+ "notNull": true,+ "default": false+ },+ "published_at": {+ "name": "published_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": false+ },+ "authored_by": {+ "name": "authored_by",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "created_at": {+ "name": "created_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ },+ "updated_at": {+ "name": "updated_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {},+ "foreignKeys": {},+ "compositePrimaryKeys": {},+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ },+ "public.skills": {+ "name": "skills",+ "schema": "",+ "columns": {+ "id": {+ "name": "id",+ "type": "text",+ "primaryKey": true,+ "notNull": true+ },+ "owner_user_id": {+ "name": "owner_user_id",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "slug": {+ "name": "slug",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "title": {+ "name": "title",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "summary": {+ "name": "summary",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "instructions": {+ "name": "instructions",+ "type": "text",+ "primaryKey": false,+ "notNull": true+ },+ "origin": {+ "name": "origin",+ "type": "text",+ "primaryKey": false,+ "notNull": true,+ "default": "'yours'"+ },+ "installed_by": {+ "name": "installed_by",+ "type": "text",+ "primaryKey": false,+ "notNull": false+ },+ "created_at": {+ "name": "created_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ },+ "updated_at": {+ "name": "updated_at",+ "type": "timestamp with time zone",+ "primaryKey": false,+ "notNull": true,+ "default": "now()"+ }+ },+ "indexes": {+ "skills_slug_key": {+ "name": "skills_slug_key",+ "columns": [+ {+ "expression": "slug",+ "isExpression": false,+ "asc": true,+ "nulls": "last"+ }+ ],+ "isUnique": true,+ "concurrently": false,+ "method": "btree",+ "with": {}+ },+ "skills_owner_idx": {+ "name": "skills_owner_idx",+ "columns": [+ {+ "expression": "owner_user_id",+ "isExpression": false,+ "asc": true,+ "nulls": "last"+ }+ ],+ "isUnique": false,+ "concurrently": false,+ "method": "btree",+ "with": {}+ }+ },+ "foreignKeys": {+ "skills_owner_user_id_users_id_fk": {+ "name": "skills_owner_user_id_users_id_fk",+ "tableFrom": "skills",+ "tableTo": "users",+ "columnsFrom": ["owner_user_id"],+ "columnsTo": ["id"],+ "onDelete": "cascade",+ "onUpdate": "no action"+ }+ },+ "compositePrimaryKeys": {},+ "uniqueConstraints": {},+ "policies": {},+ "checkConstraints": {},+ "isRLSEnabled": false+ }+ },+ "enums": {+ "public.acl_effect": {+ "name": "acl_effect",+ "schema": "public",+ "values": ["allow", "deny"]+ },+ "public.agent_type": {+ "name": "agent_type",+ "schema": "public",+ "values": ["built_in", "remote_ag_ui"]+ },+ "public.connector_type": {+ "name": "connector_type",+ "schema": "public",+ "values": ["google_drive", "onedrive"]+ },+ "public.credential_kind": {+ "name": "credential_kind",+ "schema": "public",+ "values": ["model", "connector", "agent", "mcp"]+ },+ "public.role": {+ "name": "role",+ "schema": "public",+ "values": ["admin", "user"]+ },+ "public.sync_status": {+ "name": "sync_status",+ "schema": "public",+ "values": ["pending", "running", "succeeded", "failed"]+ },+ "public.agent_visibility": {+ "name": "agent_visibility",+ "schema": "public",+ "values": ["public", "private"]+ }+ },+ "schemas": {},+ "sequences": {},+ "roles": {},+ "policies": {},+ "views": {},+ "_meta": {+ "columns": {},+ "schemas": {},+ "tables": {}+ }+}diff --git a/server/drizzle/meta/_journal.json b/server/drizzle/meta/_journal.jsonindex 540bea26..076f20a0 100644--- a/server/drizzle/meta/_journal.json+++ b/server/drizzle/meta/_journal.json@@ -8,6 +8,13 @@"when": 1786891733850,"tag": "0000_schema","breakpoints": true+ },+ {+ "idx": 1,+ "version": "7",+ "when": 1787171220703,+ "tag": "0001_gigantic_sumo",+ "breakpoints": true}]}diff --git a/server/src/app.ts b/server/src/app.tsindex 7675d476..945f5ed1 100644--- a/server/src/app.ts+++ b/server/src/app.ts@@ -19,6 +19,8 @@ import { createComponentRoutes } from "./components/routes";import type { SandboxedStore } from "./components/sandboxed";import { createSandboxedRoutes } from "./components/sandboxed-routes";import type { ComponentStore } from "./components/store";+import { createApprovalRoutes } from "./computer/approval-routes";+import type { ApprovalRegistry } from "./computer/approvals";import type { ComputerClient } from "./computer/client";import type { ComputerGateway } from "./computer/gateway";import type { PolicyStore } from "./computer/policy-store";@@ -95,6 +97,15 @@ export function createApp(* says nothing about which deployment the conversation belongs to.*/threadIdentity?: ThreadIdentity,+ /**+ * Where the questions an `ask` rule raised wait for a person.+ *+ * Deliberately not tied to the computer being configured. The same policy judges a Bot's calls to+ * somebody else's servers, so a deployment with plugins and no browser can still stop and ask, and+ * a question nobody can be shown is worse than a rule that never fired: the Bot waits out the full+ * ten minutes and then reports that nobody answered.+ */+ approvals?: ApprovalRegistry,) {const app = new Hono<{ Variables: AppVariables }>();@@ -310,6 +321,14 @@ export function createApp();}+ // Answering is its own surface because asking is not only the computer's. See approval-routes.ts.+ if (approvals && auditStore) {+ app.route(+ "/api/approvals",+ createApprovalRoutes(approvals, auditStore, requireUser),+ );+ }+if (agentProfileStore) {app.route("/api/agents",diff --git a/server/src/audit.ts b/server/src/audit.tsindex 3a826e7b..69fe18c9 100644--- a/server/src/audit.ts+++ b/server/src/audit.ts@@ -90,6 +90,29 @@ export const auditEventTypes = [// which field it went in; the value is on a path this trail is not on."computer.secret_requested","computer.secret_supplied",+ /**+ * The boundary stopping to ask a person, and what they said.+ *+ * Three rows rather than a flag on the action, because the three facts are separable and the gaps+ * between them are where the interesting failures live. A question that was asked and never+ * answered leaves only the first row, and that is the shape of "the Bot sat waiting while nobody+ * was watching the screen", which nothing else in this trail would show. An answer that was given+ * and never spent leaves the first two, which is what a stopped run looks like from here.+ *+ * `approval.granted` and `approval.denied` are written by the person answering, under their own+ * actor, minutes after the Bot's turn raised the question and often by somebody else entirely.+ * Folding consent into the action row would credit it to whoever was driving the Bot, which is the+ * one thing an approval trail must never do.+ *+ * Not named for the computer, unlike the rows above, because the same boundary judges a Bot's+ * calls to somebody else's servers and stops to ask about those too. Each row is filed against the+ * thing the question was about, a computer or a tool, so a reader filtering by either sees the+ * question, the answer and the action together rather than a grant filed under a browser for+ * something that happened in Jira.+ */+ "approval.requested",+ "approval.granted",+ "approval.denied",// The computer itself being stopped or wiped. `reset` destroys every login the Bot had, which is// both the recovery path and the most consequential button on the admin page, so who pressed it and// when is exactly the sort of thing an investigator needs and nothing else records.diff --git a/server/src/computer/approval-routes.ts b/server/src/computer/approval-routes.tsnew file mode 100644index 00000000..a4c0939a--- /dev/null+++ b/server/src/computer/approval-routes.ts@@ -0,0 +1,127 @@+/**+ * Where a person answers the questions a boundary raised, wherever it raised them.+ *+ * Its own surface rather than a pair of handlers under the computer, because the computer is not the+ * only thing the action policy judges. The same rules decide a Bot's calls to somebody else's+ * servers, an `ask` rule written about those is the shape operators reach for first, "ask me before+ * anything changes anything in Jira", and a deployment that runs plugins without a browser would+ * otherwise raise questions on a surface it never mounted: the Bot would sit for the full ten+ * minutes and then report that nobody answered, having never asked anybody.+ *+ * Answering is a person acting, so it is audited as one, under their own actor and against the thing+ * the question was about rather than against whatever endpoint they happened to press the button on.+ * The row is written here, next to the answer, because these two handlers are the only place in the+ * product where consent is recorded and a second place would eventually record it differently.+ */+import type { MiddlewareHandler } from "hono";+import { Hono } from "hono";+import { type AuditStore, recordAuditEvent } from "../audit";+import type { AppVariables } from "../auth/guards";+import {+ type ApprovalRegistry,+ type PendingApproval,+ presentable,+} from "./approvals";++/**+ * The local actor's address, matched to decide whether the id is a real users row.+ *+ * Compared against rather than imported from `auth/dev-actor` because this must not depend on the+ * authentication module's internals; this is the one fact about it that matters here.+ */+const DEV_ACTOR_EMAIL = "[email protected]";++export function createApprovalRoutes(+ approvals: ApprovalRegistry,+ auditStore: AuditStore,+ requireUser: MiddlewareHandler<{ Variables: AppVariables }>,+) {+ const routes = new Hono<{ Variables: AppVariables }>();++ /**+ * The questions this Bot is waiting on, for the surface to poll.+ *+ * A read, so no audit row, exactly like asking who holds the wheel. The interesting rows are the+ * one written when the question was raised and the one written when somebody answered it.+ */+ routes.get("/:botId", requireUser, (context) =>+ context.json({+ approvals: approvals+ .pending(context.req.param("botId") ?? "")+ .map(presentable),+ }),+ );++ routes.post("/:botId/:approvalId", requireUser, async (context) => {+ const body = (await context.req.json().catch(() => null)) as Record<+ string,+ unknown+ > | null;+ // Said explicitly, never defaulted. A body that forgot to say which way it went must not be+ // read as an approval, and reading a missing field as a refusal would be equally wrong.+ if (typeof body?.granted !== "boolean") {+ return context.json(+ { error: "Say whether this is allowed or not." },+ 400,+ );+ }++ const botId = context.req.param("botId") ?? "";+ const record = context.var.actor;+ const answered = approvals.answer(+ context.req.param("approvalId") ?? "",+ botId,+ record.id,+ body.granted,+ );+ // Nothing is broken and there is nothing to fix: the question expired, or somebody else answered+ // it, most likely in another tab. A conflict rather than a fault.+ if (!answered.ok) {+ return context.json(+ {+ error:+ "That request is no longer waiting for an answer. It may have expired, or somebody else answered it.",+ },+ 409,+ );+ }++ await recordAuditEvent(auditStore, {+ eventType: body.granted ? "approval.granted" : "approval.denied",+ targetType: answered.approval.target.type,+ targetId: answered.approval.target.id,+ // Only a real users row may go in the audit table's foreign key column. The local development+ // actor is not one, so writing it there fails the constraint and loses the row entirely. Who+ // it was is recorded in the payload regardless.+ ...(record.email === DEV_ACTOR_EMAIL ? {} : { actorUserId: record.id }),+ payload: payloadFor(answered.approval, record.id),+ });++ // Projected, like the list above. What the surface does with an answer is stop showing the+ // question, and nothing it needs for that is worth sending the binding out of this process for.+ return context.json(presentable(answered.approval));+ });++ return routes;+}++/**+ * What an answer records: the question, the boundary that raised it, and who answered.+ *+ * The Bot whose turn met the rule comes off the approval rather than out of the request, so the row+ * says which Bot it was actually about even if somebody arrives at the wrong address with a real id.+ */+function payloadFor(approval: PendingApproval, answeredBy: string) {+ return {+ bot: approval.botId,+ actor: answeredBy,+ approval: approval.id,+ rule: approval.rule,+ // The question as a person read it, so the trail records what they were shown rather than a+ // reconstruction of it.+ reason: approval.question,+ // Who was driving when the boundary stopped, which is usually not who answered. The gap between+ // the two is the reason this is its own row.+ asked: approval.actor,+ };+}diff --git a/server/src/computer/approvals.ts b/server/src/computer/approvals.tsnew file mode 100644index 00000000..a805a20f--- /dev/null+++ b/server/src/computer/approvals.ts@@ -0,0 +1,332 @@+/**+ * The questions a Bot is waiting on a person to answer, and the binding that makes an answer mean+ * exactly one thing.+ *+ * In memory, per process, and deliberately not in the database. A pending question is about a live+ * browser session and a live turn: the snapshot the refs came from, the page that is open, the model+ * that is mid-run holding the tool call. A restart takes all three with it, so a persisted approval+ * would come back as a grant for an action nobody could still perform, attached to a conversation+ * nobody is having. Worse, it would be a grant nobody remembers giving. The safe reading of a+ * restart is that every open question was withdrawn, and the safe way to guarantee that is to keep+ * the questions somewhere a restart empties.+ *+ * The important part is the fingerprint. An approval registry without one is a dialog box: a person+ * presses Allow, an id comes back, and the model may then spend that id on any action it likes.+ * Binding an approval to a hash of the action it was granted for is what stops "yes, click Place+ * order" being replayable as "yes, click Delete account", and it is the reason this is a governance+ * feature rather than a confirmation prompt.+ *+ * It lives beside the computer because that is where the boundary it serves was written, and it is+ * not only the computer's, the same policy judges a Bot's calls to somebody else's servers and those+ * raise the same questions. One registry per deployment rather than one per subsystem: a Bot waiting+ * on a person is waiting on a person, and a deployment with two of these would be a deployment where+ * the surface a person answers on decides which half of a Bot's work they can see.+ */+import { createHash, randomUUID } from "node:crypto";++/**+ * How long a question stays open.+ *+ * Ten minutes, the same window the surface gives a person to answer a request for help or a secret.+ * Long enough that somebody who walked away from the screen can still come back and decide; finite+ * because a run holding a tool call open forever is a hung Bot, and because an approval that outlives+ * anybody's memory of the question is not consent.+ */+export const APPROVAL_TTL_MS = 10 * 60_000;++/**+ * The action an approval is about, in the fields a fingerprint is taken over.+ *+ * Everything here is known to the caller before it acts and is derived from the request it is+ * actually about to make, never from anything the model asserted about it.+ */+export type ApprovalSubject = {+ botId: string;+ toolName: string;+ ref?: string | undefined;+ key?: string | undefined;+ /** True when a `computer_type` call will press Enter afterwards. See PolicyContext.submit. */+ submit?: boolean | undefined;+ filePath?: string | undefined;+ pageUrl?: string | undefined;+ /**+ * The arguments a tool call carries, for the calls whose whole meaning is in them.+ *+ * A browser action is identified by the thing it touches: a ref, a key, a path. A call to somebody+ * else's server is not. `postMessage` on the same Bot's same server is one action when it says+ * "the deploy finished" in a team channel and another when it says something else to a customer,+ * and a fingerprint that stopped at the tool name would make one person's yes cover both.+ *+ * Left out where the arguments are not the identity, so that a person who allowed a click is not+ * asked again because a snapshot id moved on.+ */+ arguments?: Record<string, unknown> | undefined;+};++export type PendingApproval = {+ id: string;+ botId: string;+ /** Who was driving the Bot when it met the rule. Not necessarily who answers. */+ actor: string;+ /** The expression that asked, so the surface and the trail can name the boundary. */+ rule: string;+ /** What is about to happen, in one sentence, as the policy phrased it. */+ question: string;+ /**+ * What the question is about, in the terms the audit trail files things under.+ *+ * Carried on the approval because the person answering arrives minutes later on a surface that+ * knows nothing but an id, and the row their answer writes has to land against the same thing the+ * action's own row will. Without it every answer would be filed against whichever subsystem+ * happened to own the endpoint they pressed the button on, so a yes to a tool call on somebody+ * else's server would be recorded as something that happened on a browser.+ */+ target: { type: string; id: string };+ /**+ * The action this approval is good for, and only this one.+ *+ * Kept on the record rather than recomputed at consumption time from whatever arrives, because the+ * whole point is to compare the action a person saw against the action being attempted.+ */+ fingerprint: string;+ requestedAt: string;+ expiresAt: string;+ /** Undefined until somebody answers. False is an answer, and a final one. */+ granted?: boolean;+ /** Who answered, recorded so the audit row credits the decision to a person rather than to a Bot. */+ answeredBy?: string;+};++/**+ * An approval as a surface is allowed to see it.+ *+ * The fingerprint is the binding between an approval and its action, the actor is the person the+ * turn belonged to, and the target is bookkeeping for the trail. None of the three is any use to a+ * browser and all three are compared or written on the server, so they do not travel.+ *+ * One projection rather than one per handler. The reading endpoint and the answering endpoint sit+ * four lines apart and return the same record, and the way that goes wrong is that somebody adds a+ * field to the record and only one of them keeps it out; a stated invariant of a security surface+ * being quietly broken by a sibling handler is a worse failure than the field itself.+ */+export type PresentedApproval = {+ id: string;+ botId: string;+ rule: string;+ question: string;+ requestedAt: string;+ expiresAt: string;+ granted?: boolean;+ answeredBy?: string;+};++export function presentable(approval: PendingApproval): PresentedApproval {+ return {+ id: approval.id,+ botId: approval.botId,+ rule: approval.rule,+ question: approval.question,+ requestedAt: approval.requestedAt,+ expiresAt: approval.expiresAt,+ ...(approval.granted === undefined ? {} : { granted: approval.granted }),+ ...(approval.answeredBy ? { answeredBy: approval.answeredBy } : {}),+ };+}++export type ApprovalAnswer =+ | { ok: true; approval: PendingApproval }+ /** One reason, because a person acts on all three identically: that question is no longer open. */+ | { ok: false; reason: "no longer open" };++export type ApprovalConsumption =+ | { ok: true; approval: PendingApproval }+ | {+ ok: false;+ reason: "unknown" | "unanswered" | "declined" | "a different action";+ };++/**+ * A stable hash of the action, used to bind one approval to one thing.+ *+ * Hashed rather than stored as a tuple so the value is a single opaque string that can be compared in+ * one line and cannot be partially matched by accident. The parts are joined with a NUL, which no+ * field can contain, so that a ref of "a" with a key of "bc" cannot produce the same fingerprint as+ * "ab" with "c".+ *+ * The Bot's id is in here first, which is what stops an approval granted on one Bot's computer being+ * spent on another's: two Bots doing the identical thing produce two different fingerprints, and+ * neither can consume the other's.+ */+export function fingerprintOf(subject: ApprovalSubject): string {+ return createHash("sha256")+ .update(+ [+ subject.botId,+ subject.toolName,+ subject.ref ?? "",+ subject.key ?? "",+ subject.submit === true ? "submit" : "",+ subject.filePath ?? "",+ subject.pageUrl ?? "",+ subject.arguments ? canonical(subject.arguments) : "",+ ].join("\u0000"),+ )+ .digest("hex");+}++/**+ * JSON with its keys in a fixed order, so two spellings of the same arguments hash the same.+ *+ * `JSON.stringify` keeps whatever order an object was built in, and the same call arrives here+ * twice: once when the question is asked and once when the answer is spent, with a parse in between.+ * Sorting makes the comparison about what the arguments say rather than about the order somebody's+ * client happened to write them in, which is not a difference anybody would understand being asked+ * about twice.+ */+function canonical(value: unknown): string {+ if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;+ if (value && typeof value === "object") {+ return `{${Object.entries(value as Record<string, unknown>)+ .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))+ .map(([key, entry]) => `${JSON.stringify(key)}:${canonical(entry)}`)+ .join(",")}}`;+ }+ // `undefined` stringifies to nothing at all, which would let a field somebody sent as undefined+ // hash the same as one they never sent.+ return JSON.stringify(value) ?? "null";+}++export type ApprovalRegistry = {+ /** Open a question. The id it returns is what a caller presents once somebody has answered. */+ request: (input: {+ botId: string;+ actor: string;+ rule: string;+ question: string;+ fingerprint: string;+ target: { type: string; id: string };+ }) => PendingApproval;+ /**+ * The open questions for one Bot, newest last, expired ones already gone.+ *+ * Includes answered-but-unspent ones, because the waiting caller learns the answer by finding its+ * own id in this list. The surface shows only the unanswered ones.+ */+ pending: (botId: string) => PendingApproval[];+ /**+ * Answer one question, on the Bot it was asked about.+ *+ * The Bot is named rather than looked up from the id, and it has to match. The id is enough to+ * find the entry, so this is not authorisation, it is bookkeeping that cannot be wrong: the+ * surface takes the Bot from the address it was called on, and the row an answer writes says which+ * Bot it was about. Without the check those two can disagree, and then the trail holds a grant+ * filed under one Bot and the action it paid for filed under another, joined by an id that appears+ * on both and reconciles neither. "Who approved what" is the one question this record exists to+ * answer.+ */+ answer: (+ id: string,+ botId: string,+ actor: string,+ granted: boolean,+ ) => ApprovalAnswer;+ /** Spend an approval on one action. Single use: a successful consumption removes it. */+ consume: (id: string, fingerprint: string) => ApprovalConsumption;+};++export function createApprovalRegistry(+ options: {+ /** Injectable so expiry can be tested without a test that sleeps for ten minutes. */+ now?: () => number;+ ttlMs?: number;+ } = {},+): ApprovalRegistry {+ const now = options.now ?? (() => Date.now());+ const ttlMs = options.ttlMs ?? APPROVAL_TTL_MS;+ const open = new Map<string, PendingApproval>();++ /**+ * Drop what has run out, on every read.+ *+ * On read rather than on a timer, because a timer keeps a process alive and adds a thing that can+ * be forgotten in a test; nothing here matters until somebody looks, and everything that looks+ * sweeps first.+ */+ const sweep = () => {+ const at = now();+ for (const [id, approval] of open) {+ if (Date.parse(approval.expiresAt) <= at) open.delete(id);+ }+ };++ return {+ request: (input) => {+ sweep();+ const at = now();+ const approval: PendingApproval = {+ id: randomUUID(),+ botId: input.botId,+ actor: input.actor,+ rule: input.rule,+ question: input.question,+ fingerprint: input.fingerprint,+ target: input.target,+ requestedAt: new Date(at).toISOString(),+ expiresAt: new Date(at + ttlMs).toISOString(),+ };+ open.set(approval.id, approval);+ return approval;+ },++ pending: (botId) => {+ sweep();+ return [...open.values()].filter((approval) => approval.botId === botId);+ },++ answer: (id, botId, actor, granted) => {+ sweep();+ const approval = open.get(id);+ // An answered question is not answerable again, whichever way it went. Otherwise a second+ // person, or the same person in a second tab, can quietly overturn a decision that the trail+ // has already recorded as made.+ //+ // A question asked about another Bot is reported the same way, because from where the caller+ // is standing it is the same fact: nothing is open here under that id.+ if (+ !approval ||+ approval.botId !== botId ||+ approval.granted !== undefined+ ) {+ return { ok: false, reason: "no longer open" };+ }+ const answered: PendingApproval = {+ ...approval,+ granted,+ answeredBy: actor,+ };+ open.set(id, answered);+ return { ok: true, approval: answered };+ },++ consume: (id, fingerprint) => {+ sweep();+ const approval = open.get(id);+ if (!approval) return { ok: false, reason: "unknown" };+ if (approval.granted === undefined) {+ return { ok: false, reason: "unanswered" };+ }+ if (approval.granted === false) return { ok: false, reason: "declined" };+ if (approval.fingerprint !== fingerprint) {+ // Left in place rather than burned. A mismatch is the replay this whole mechanism exists to+ // stop, and destroying the approval on the way past would let a model that guessed wrong take+ // the person's grant away from the action they actually meant it for.+ return { ok: false, reason: "a different action" };+ }+ // Single use. A grant is permission for one thing to happen once; leaving it spendable would+ // make "yes" mean "yes, as often as you like", which is not what anybody pressing Allow on one+ // button thinks they are agreeing to.+ open.delete(id);+ return { ok: true, approval };+ },+ };+}diff --git a/server/src/computer/gateway.ts b/server/src/computer/gateway.tsindex c435d780..bbe3b714 100644--- a/server/src/computer/gateway.ts+++ b/server/src/computer/gateway.ts@@ -18,6 +18,12 @@* The refs are opaque to the caller precisely so that the server holds the mapping.*/import { type AuditStore, recordAuditEvent } from "../audit";+import {+ type ApprovalRegistry,+ createApprovalRegistry,+ fingerprintOf,+ type PendingApproval,+} from "./approvals";import type { ComputerClient } from "./client";import {type ActionPolicy,@@ -51,6 +57,32 @@ export class ActionRefusedError extends Error {}}+/**+ * The boundary wants a person's answer before this happens.+ *+ * Emphatically not an {@link ActionRefusedError}. A refusal is final and the Bot should say so and+ * move on; this one is a pause, and the same Bot presenting the same request again with an approval+ * on it is the intended next step rather than an attempt to get around anything. Collapsing the two+ * would teach a model to give up on exactly the actions a deployment was willing to permit, which is+ * the failure that makes an ask list worse than useless.+ */+export class ActionNeedsApprovalError extends Error {+ /** What the caller presents once somebody has answered. */+ readonly approvalId: string;+ /** The question in the words a person is being shown, so the Bot can say what it is waiting for. */+ readonly question: string;+ /** The rule that asked, so the surface can name the boundary the way a refusal does. */+ readonly rule: string;++ constructor(approval: PendingApproval) {+ super(approval.question);+ this.name = "ActionNeedsApprovalError";+ this.approvalId = approval.id;+ this.question = approval.question;+ this.rule = approval.rule;+ }+}+/** Who is asking. The gateway records this; it does not decide it. */export type ActionActor = {/** The signed-in person, or the local actor when authentication is not configured. */@@ -77,6 +109,16 @@ export type ComputerGatewayOptions = {auditStore: AuditStore;/** Absent denies everything. See evaluateActionPolicy. */policy: () => ActionPolicy | undefined;+ /**+ * Where questions raised by the `ask` list wait for an answer.+ *+ * Handed in rather than owned, because the deployment has exactly one of these and the gateway is+ * not the only thing that asks: the same policy judges a Bot's calls to somebody else's servers,+ * and a person answering should see everything their Bot is waiting on rather than whichever half+ * belongs to the subsystem that happened to serve the page. A gateway built without one keeps its+ * own, which is what the tests do so they can control the clock.+ */+ approvals?: ApprovalRegistry;/*** Counts a Bot repeating itself, so that the policy can be told how many times.*@@ -105,6 +147,7 @@ type CachedSnapshot = {export function createComputerGateway(options: ComputerGatewayOptions) {const { client, auditStore, supervisor } = options;const snapshots = new Map<string, CachedSnapshot>();+ const approvals = options.approvals ?? createApprovalRegistry();const repeat = options.repeat ?? createRepeatDetector();/**@@ -165,8 +208,19 @@ export function createComputerGateway(options: ComputerGatewayOptions) {filePath?: string;targetUrl?: string;key?: string;+ /** Whether this call ends by pressing Enter. Only the type tool can, and it says so. */+ submit?: boolean;/** The person's Stop, on its way to the browser. See the acting methods below. */signal?: AbortSignal;+ /**+ * An answer a person already gave, being presented for the action it was given for.+ *+ * Carried on the request rather than held against the conversation, because the thing being+ * checked is not "has somebody approved something recently" but "was this exact action the one+ * they were shown". The id alone proves nothing; it is the id plus the fingerprint of the call+ * being made that means anything.+ */+ approvalId?: string;},run: () => Promise<T>,): Promise<T> {@@ -203,6 +257,9 @@ export function createComputerGateway(options: ComputerGatewayOptions) {actor: { id: actor.id },page: { url: pageUrl, host: hostOf(pageUrl) },repeat: { count: repetition.count },+ // Always a boolean, unlike `key`, so a rule about form submission needs no guard to stay+ // evaluable on the actions that cannot submit anything. See PolicyContext.submit.+ submit: subject.submit === true,...(intent ? { intent } : {}),...(subject.key ? { key: subject.key } : {}),...(element@@ -257,6 +314,81 @@ export function createComputerGateway(options: ComputerGatewayOptions) {}const decision = evaluateActionPolicy(options.policy(), context);++ /**+ * A decision that wants a person, resolved before anything is recorded as having happened.+ *+ * Two outcomes and no third: either an approval already exists for this exact action, in which+ * case the row below says so and names who gave it, or the question is opened and the call stops+ * here. Nothing is written as allowed or refused in the second case, because neither happened:+ * `approval.requested` is the record of where the turn actually got to.+ *+ * Dry-run never reaches this branch, because the policy forwards an ask there for the same+ * reason it forwards a deny: a mode that promises to change nothing must not start interrupting+ * people.+ */+ let approvedBy: string | undefined;+ if (decision.source === "ask" && !decision.forward) {+ const fingerprint = fingerprintOf({+ botId,+ toolName,+ ref,+ key: subject.key,+ submit: subject.submit,+ filePath,+ pageUrl,+ });+ const presented = subject.approvalId+ ? approvals.consume(subject.approvalId, fingerprint)+ : undefined;++ if (presented?.ok && presented.approval.answeredBy) {+ approvedBy = presented.approval.answeredBy;+ } else {+ // Every unsuccessful presentation asks again rather than failing: an expired approval, an id+ // spent already, a person's No being replayed, and an approval granted for a different button+ // all mean the same thing here, which is that nobody has agreed to THIS. Asking twice is+ // annoying and safe; guessing which of those deserves an error is neither.+ //+ // An approval with nobody's name on it lands here too. Nothing can produce one, because an+ // answer always records who gave it and an unanswered approval cannot be spent, and it asks+ // again rather than falling back to the person whose turn raised the question: crediting+ // consent to whoever was driving the Bot is the one thing this record must never do.+ const pending = approvals.request({+ botId,+ actor: actor.id,+ rule: decision.matched ?? "",+ question: decision.reason,+ fingerprint,+ // Where the answer's own row will be filed, decided here where what the question is about+ // is still known. See PendingApproval.target.+ target: { type: "computer", id: computerId },+ });+ await writeApprovalEvent(auditStore, {+ botId,+ actor,+ computerId,+ approval: pending,+ toolName,+ pageUrl,+ filePath,+ });+ throw new ActionNeedsApprovalError(pending);+ }+ }++ // What the boundary settled on, once a person's answer is folded in. The source stays `ask`, so+ // the row reads as "allowed, because somebody was asked and said yes" rather than as an ordinary+ // permission nobody ever questioned.+ const settled: PolicyDecision = approvedBy+ ? {+ ...decision,+ allowed: true,+ forward: true,+ reason: `Allowed by ${approvedBy}, who was asked because of the rule \`${decision.matched}\`.`,+ }+ : decision;+await write(auditStore, {toolName,botId,@@ -267,11 +399,12 @@ export function createComputerGateway(options: ComputerGatewayOptions) {...(subject.key ? { key: subject.key } : {}),filePath,pageUrl,- decision,+ decision: settled,+ ...(approvedBy ? { approvedBy } : {}),});- if (!decision.forward) {- throw new ActionRefusedError(decision.reason, decision.matched);+ if (!settled.forward) {+ throw new ActionRefusedError(settled.reason, settled.matched);}let result: T;@@ -297,7 +430,8 @@ export function createComputerGateway(options: ComputerGatewayOptions) {ref,filePath,pageUrl,- decision,+ decision: settled,+ ...(approvedBy ? { approvedBy } : {}),failure: error instanceof Error ? error.message : "The action failed.",});throw error;@@ -515,13 +649,21 @@ export function createComputerGateway(options: ComputerGatewayOptions) {botId: string,actor: ActionActor,url: string,+ /**+ * An answer a person gave to this exact call, if one has been given.+ *+ * Last and optional on every acting method, so a caller that knows nothing about approvals+ * behaves exactly as it did and a route that forgets to pass it fails by asking again rather+ * than by acting unasked.+ */+ approvalId?: string,) {return govern(computerId,"computer_navigate",botId,actor,- { targetUrl: url },+ { targetUrl: url, ...(approvalId ? { approvalId } : {}) },() => as(botId).navigate(url),);},@@ -532,13 +674,18 @@ export function createComputerGateway(options: ComputerGatewayOptions) {actor: ActionActor,input: ClickInput,signal?: AbortSignal,+ approvalId?: string,) {return govern(computerId,"computer_click",botId,actor,- { ref: input.ref, ...(signal ? { signal } : {}) },+ {+ ref: input.ref,+ ...(signal ? { signal } : {}),+ ...(approvalId ? { approvalId } : {}),+ },() => as(botId).click(input, signal),);},@@ -549,13 +696,22 @@ export function createComputerGateway(options: ComputerGatewayOptions) {actor: ActionActor,input: TypeInput,signal?: AbortSignal,+ approvalId?: string,) {return govern(computerId,"computer_type",botId,actor,- { ref: input.ref, ...(signal ? { signal } : {}) },+ {+ ref: input.ref,+ // Whether this call ends by pressing Enter, which is the third way into a form and the one+ // a rule about clicking and a rule about `key` both miss. The computer presses it itself,+ // so it never arrives here as an action of its own to be judged.+ submit: input.submit === true,+ ...(signal ? { signal } : {}),+ ...(approvalId ? { approvalId } : {}),+ },() => as(botId).type(input, signal),);},@@ -566,6 +722,7 @@ export function createComputerGateway(options: ComputerGatewayOptions) {actor: ActionActor,input: KeyInput,signal?: AbortSignal,+ approvalId?: string,) {return govern(computerId,@@ -574,7 +731,12 @@ export function createComputerGateway(options: ComputerGatewayOptions) {actor,// The key is part of the subject, so a rule can tell Enter from a letter. Form submission can// happen through a keypress as well as a click, so the policy context carries the key.- { ref: input.ref, key: input.key, ...(signal ? { signal } : {}) },+ {+ ref: input.ref,+ key: input.key,+ ...(signal ? { signal } : {}),+ ...(approvalId ? { approvalId } : {}),+ },() => as(botId).key(input, signal),);},@@ -584,9 +746,15 @@ export function createComputerGateway(options: ComputerGatewayOptions) {botId: string,actor: ActionActor,input: ScrollInput,+ approvalId?: string,) {- return govern(computerId, "computer_scroll", botId, actor, {}, () =>- as(botId).scroll(input),+ return govern(+ computerId,+ "computer_scroll",+ botId,+ actor,+ { ...(approvalId ? { approvalId } : {}) },+ () => as(botId).scroll(input),);},@@ -602,13 +770,14 @@ export function createComputerGateway(options: ComputerGatewayOptions) {botId: string,actor: ActionActor,input: ReadFileInput,+ approvalId?: string,) {return govern(computerId,"computer_read_file",botId,actor,- { filePath: input.path },+ { filePath: input.path, ...(approvalId ? { approvalId } : {}) },() => as(botId).readFile(input),);},@@ -623,13 +792,17 @@ export function createComputerGateway(options: ComputerGatewayOptions) {botId: string,actor: ActionActor,input: ListFilesInput,+ approvalId?: string,) {return govern(computerId,"computer_list_files",botId,actor,- { filePath: input.path ?? "." },+ {+ filePath: input.path ?? ".",+ ...(approvalId ? { approvalId } : {}),+ },() => as(botId).listFiles(input),);},@@ -639,13 +812,14 @@ export function createComputerGateway(options: ComputerGatewayOptions) {botId: string,actor: ActionActor,input: WriteFileInput,+ approvalId?: string,) {return govern(computerId,"computer_write_file",botId,actor,- { filePath: input.path },+ { filePath: input.path, ...(approvalId ? { approvalId } : {}) },() => as(botId).writeFile(input),);},@@ -740,6 +914,14 @@ async function write(filePath: string | undefined;pageUrl: string;decision: PolicyDecision;+ /**+ * Who allowed this, when the boundary asked and somebody said yes.+ *+ * On the action row as well as on the approval row, because the two are found by different+ * questions: a reader following one Bot's actions should not have to go and correlate ids to+ * discover that a person stood behind this particular click.+ */+ approvedBy?: string;/** Set only when a permitted action was attempted and did not succeed. */failure?: string;},@@ -792,6 +974,7 @@ async function write(mode: entry.decision.mode,source: entry.decision.source,rule: entry.decision.matched,+ ...(entry.approvedBy ? { approvedBy: entry.approvedBy } : {}),/** Present so the trail explains a dry-run row that was recorded as refused but still ran. */carriedOut: entry.decision.forward,},@@ -889,6 +1072,55 @@ async function writeControlEvent(});}+/**+ * The row for a question the boundary stopped to ask.+ *+ * Its own writer rather than a variant of either of the others, because an approval sits between+ * them and fits neither shape. It is not `write`: no decision was reached, the policy said it wanted+ * a person and the turn stopped there, and inventing an allowed-or-refused verdict for that row would+ * be the comfortable fiction the rest of this file is careful to avoid. It is not+ * `writeControlEvent`: a handover is a person taking the browser away from the Bot, whereas this is a+ * question about one specific action, so the row has to name the action or a reader cannot tell what+ * was being agreed to.+ *+ * The answer's row is written where the answer is given, which is not here. All of them carry the+ * approval id: that is what lets a reader join a request to its answer and to the action that+ * finally happened, and it is the only way to see the case that matters most, a question that was+ * asked and never answered.+ */+async function writeApprovalEvent(+ auditStore: AuditStore,+ entry: {+ botId: string;+ actor: ActionActor;+ computerId: string;+ approval: PendingApproval;+ toolName?: string;+ pageUrl?: string;+ filePath?: string | undefined;+ },+) {+ await recordAuditEvent(auditStore, {+ eventType: "approval.requested",+ targetType: "computer",+ targetId: entry.computerId,+ ...(entry.actor.userId ? { actorUserId: entry.actor.userId } : {}),+ payload: {+ bot: entry.botId,+ actor: entry.actor.id,+ approval: entry.approval.id,+ rule: entry.approval.rule,+ // The question as a person read it. Element labels are things a page displays rather than+ // things anybody typed, which is why the reason text is safe to keep here; see the note on+ // `write` above.+ reason: entry.approval.question,+ ...(entry.toolName ? { action: entry.toolName } : {}),+ ...(entry.pageUrl ? { page: entry.pageUrl } : {}),+ ...(entry.filePath ? { file: entry.filePath } : {}),+ },+ });+}+function hostOf(url: string): string {try {return new URL(url).host;diff --git a/server/src/computer/policy-store.ts b/server/src/computer/policy-store.tsindex 053ddd15..216f4119 100644--- a/server/src/computer/policy-store.ts+++ b/server/src/computer/policy-store.ts@@ -36,6 +36,7 @@ const CURRENT = "current";export const DEFAULT_ACTION_POLICY: ActionPolicy = {mode: "enforce",deny: [],+ ask: [],allow: ["true"],};@@ -73,6 +74,7 @@ export function createPolicyStore(id: CURRENT,mode: next.mode,deny: next.deny,+ ask: next.ask,allow: next.allow,updatedBy: by ?? null,updatedAt: new Date(),@@ -82,6 +84,7 @@ export function createPolicyStore(set: {mode: next.mode,deny: next.deny,+ ask: next.ask,allow: next.allow,updatedBy: by ?? null,updatedAt: new Date(),@@ -113,6 +116,7 @@ export function createPolicyStore(current = {mode: row.mode as ActionPolicy["mode"],deny: [...row.deny],+ ask: [...row.ask],allow: [...row.allow],};return "the database";@@ -124,6 +128,7 @@ function clone(policy: ActionPolicy): ActionPolicy {return {mode: policy.mode,deny: [...policy.deny],+ ask: [...policy.ask],allow: [...policy.allow],};}@@ -155,8 +160,12 @@ export function parseActionPolicy(};}- const lists: Record<"deny" | "allow", string[]> = { deny: [], allow: [] };- for (const key of ["deny", "allow"] as const) {+ const lists: Record<"deny" | "ask" | "allow", string[]> = {+ deny: [],+ ask: [],+ allow: [],+ };+ for (const key of ["deny", "ask", "allow"] as const) {const value = candidate[key] ?? [];if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {return { ok: false, error: `${key} must be a list of expressions.` };@@ -164,5 +173,11 @@ export function parseActionPolicy(lists[key] = value as string[];}- return { ok: true, policy: { mode, deny: lists.deny, allow: lists.allow } };+ // `ask` defaults to empty like the others, so a policy written before this list existed still+ // parses and still means what it meant. A deployment that has never asked anybody anything is a+ // deployment with no ask rules, not an invalid one.+ return {+ ok: true,+ policy: { mode, deny: lists.deny, ask: lists.ask, allow: lists.allow },+ };}diff --git a/server/src/computer/policy.ts b/server/src/computer/policy.tsindex 06ac3a97..b453683e 100644--- a/server/src/computer/policy.ts+++ b/server/src/computer/policy.ts@@ -11,8 +11,15 @@* thought of; an expression language can express the one they thought of. This is also the language* the enterprise gateway already speaks, so a rule written here means the same thing there.*- * Precedence: deny beats allow. A rule that removes permission must never be+ * Precedence: deny, then ask, then allow. A rule that removes permission must never be* defeated by a broader rule that grants it, or a company cannot reason about what it has forbidden.+ *+ * `ask` sits between the two, and both halves of that position are deliberate. It must not soften a+ * `deny`, because a thing a deployment has forbidden is not up for renegotiation at a prompt, and an+ * approval box in front of a tired person at the end of a task is not the review anybody signed off+ * when they wrote the deny rule. And it must beat `allow`, because the policy this product ships with+ * is `allow: ["true"]`: an ask evaluated after the allow list would be unreachable in the default+ * configuration, so the first rule anybody ever wrote here would silently do nothing.*/import { evaluate } from "cel-js";@@ -27,8 +34,18 @@ export type ActionPolicy = {* governance feature.*/mode: PolicyMode;- /** Evaluated first. Any expression true means refused, whatever `allow` says. */+ /** Evaluated first. Any expression true means refused, whatever `ask` or `allow` says. */deny: string[];+ /**+ * Any expression true means a person is asked before the action runs.+ *+ * The middle answer a boundary with two lists cannot give. "It may spend money, but not more than+ * fifty pounds without me" and "it may do this, but I want to see the first one" are the shapes+ * every deployment reaches for once it trusts a Bot enough to let it act at all, and until this+ * list existed the only way to express either was to forbid the action and have a person take the+ * wheel, which throws away the Bot's turn and everything it had worked out to get there.+ */+ ask: string[];/** Any expression true means permitted. Empty means nothing is permitted. */allow: string[];};@@ -93,6 +110,22 @@ export type PolicyContext = {* to block both routes, which the deny example in `.env.example` now does.*/key?: string;+ /**+ * Whether a `computer_type` call will press Enter when it has finished typing.+ *+ * The third door into a form, and the one a rule about clicking and a rule about `key` both miss.+ * The type tool takes a flag meaning "and submit", the computer presses Enter itself, and no+ * keypress ever reaches the gateway as its own action, so a boundary written against Enter watched+ * the Bot walk past it: a preset named "never submit a form" left the one call that submits a+ * single-field form untouched.+ *+ * Present on every action rather than only on the calls that can set it, and false is doing work+ * there. `key` is absent unless a key was pressed, which is why the presets that mention it have+ * to be guarded by tool name to stay evaluable; a rule saying `submit` should not need that+ * ceremony, because the whole point of the field is that an operator writes one short sentence+ * about form submission and it holds everywhere.+ */+ submit?: boolean;/*** What the action does, rather than which tool was called.*@@ -110,7 +143,8 @@ export type PolicyContext = {* from Enter in any field of it, and the element a keypress names is the field, not the form. The* gateway would need to know the page's structure at decision time, which it does not, refs are* held off-DOM by Playwright and the policy runs before the action reaches the browser. So a rule- * that must stop a submission still has to refuse Enter outright, and the preset says so.+ * that must stop a submission still has to refuse Enter outright, and the preset says so. `submit`+ * above covers the one case where the intention is not a guess, because the Bot asked for it.*/intent?:| "activate"@@ -166,8 +200,15 @@ export type PolicyDecision = {mode: PolicyMode;/** Which expression decided it, so the audit row can say why and an operator can find the rule. */matched: string | null;- /** Which list that expression came from. `default` means nothing matched and the floor applied. */- source: "deny" | "allow" | "default";+ /**+ * Which list that expression came from. `default` means nothing matched and the floor applied.+ *+ * `ask` is not a verdict on its own: it says the boundary wants a person's answer, and the caller+ * decides what to do about that. The gateway either finds an approval already granted for this+ * exact action or stops and asks; both outcomes are recorded with this source, so the trail can+ * tell an action a person consented to from one nothing ever questioned.+ */+ source: "deny" | "ask" | "allow" | "default";/** True when the action should actually be carried out. False for a refusal in `enforce`. */forward: boolean;/** Why, in words that go in front of a person. */@@ -247,6 +288,7 @@ export function evaluateActionPolicy(): PolicyDecision {const mode: PolicyMode = policy?.mode ?? "enforce";const deny = policy?.deny ?? [];+ const ask = policy?.ask ?? [];const allow = policy?.allow ?? [];// Deny first, and a broken deny expression still denies. One typo in a rule therefore blocks the@@ -267,6 +309,27 @@ export function evaluateActionPolicy(}}+ // Ask second, and a broken ask expression asks. The same reasoning as the deny loop, with a gentler+ // cost: a typo here interrupts somebody who was not expecting to be interrupted, which is a+ // nuisance, whereas the alternative is a rule that quietly permits exactly the thing it was written+ // to hold back. A boundary whose failures land on the permissive side is not a boundary.+ for (const expression of ask) {+ if (matches(expression, context, true)) {+ return {+ allowed: false,+ mode,+ matched: expression,+ source: "ask",+ // Nothing happens until somebody says so, except in dry-run, where the whole promise is that+ // switching the policy on changes nothing. A dry-run ask is a note in the trail saying "here+ // is where you would have been interrupted", which is precisely what an operator trying a+ // rule out against real traffic wants to find out before it starts stopping anybody.+ forward: mode === "dry-run",+ reason: describeAsk(context),+ };+ }+ }+for (const expression of allow) {if (matches(expression, context, false)) {return {@@ -292,11 +355,47 @@ export function evaluateActionPolicy(};}+/**+ * The verb a person reads, chosen from what the action does rather than which tool ran.+ *+ * A question phrased as "allow computer_write_file?" asks somebody to translate an implementation+ * detail before they can decide, and a question nobody understands gets answered yes.+ */+const ASK_VERBS: Record<string, string> = {+ activate: "press",+ type: "type into",+ navigate: "open",+ read: "look at",+ read_file: "read",+ write_file: "write to",+ list_files: "list",+ read_tool: "call",+ write_tool: "call",+};++/**+ * The question itself: what is about to happen, in one sentence.+ *+ * The rule that asked is deliberately not in here. It travels beside the question as its own field,+ * so the surface can show it as a rule and the trail can record it as one, and a person reading the+ * prompt is not made to parse CEL before they can answer a question about a button.+ */+function describeAsk(context: PolicyContext): string {+ return `The Bot wants to ${ASK_VERBS[context.intent ?? ""] ?? "act on"} ${subjectOf(context)}.`;+}+/** A refusal a person can act on: what was refused, and on what. */function describeRefusal(context: PolicyContext, expression: string): string {- // A file refusal must not be phrased as happening "on <host>": the workspace has nothing to do with- // whatever page the browser happens to be showing, and saying so sends somebody to the wrong place.- if (context.file) {+ // A file or tool refusal must not be phrased as happening "on <host>": neither the workspace nor+ // somebody else's server has anything to do with whatever page the browser happens to be showing,+ // and saying so sends somebody to the wrong place.+ if (context.mcp) {+ return (+ `This deployment's policy does not allow that: ${subjectOf(context)} ` ++ `is blocked by the rule \`${expression}\`.`+ );+ }+ if (context.file?.path) {return (`This deployment's policy does not allow that: the file ${context.file.path} ` +`is blocked by the rule \`${expression}\`.`@@ -310,3 +409,22 @@ function describeRefusal(context: PolicyContext, expression: string): string {`is blocked by the rule \`${expression}\`.`);}++/**+ * The thing an action is aimed at, named the way the person who has to decide would name it.+ *+ * Every branch is checked for content rather than presence, because a caller judging something that+ * is not a browser action fills the browser fields in with empty strings on purpose: a rule about+ * element names must evaluate to false against a tool call rather than becoming unevaluable and+ * therefore matching. Reading those blanks as "a file" produced a question with a hole in it, "The+ * Bot wants to call .", which is a sentence nobody can answer and which arrived attached to two+ * buttons.+ */+function subjectOf(context: PolicyContext): string {+ if (context.mcp) return `${context.mcp.tool} on ${context.mcp.server}`;+ if (context.file?.path) return context.file.path;+ if (context.element?.name) {+ return `“${context.element.name}” on ${context.page.host}`;+ }+ return context.page.host || "this page";+}diff --git a/server/src/computer/routes.ts b/server/src/computer/routes.tsindex 3ce1c285..f468e48b 100644--- a/server/src/computer/routes.ts+++ b/server/src/computer/routes.ts@@ -13,6 +13,7 @@ import {} from "./client";import {type ActionActor,+ ActionNeedsApprovalError,ActionRefusedError,type ComputerGateway,} from "./gateway";@@ -62,6 +63,7 @@ export function createComputerRoutes(routes.post("/:botId/navigate", requireUser, async (context) => {const body = (await context.req.json().catch(() => null)) as {url?: unknown;+ approvalId?: unknown;} | null;if (typeof body?.url !== "string" || !body.url.trim()) {return context.json({ error: "A web address is required." }, 400);@@ -79,9 +81,13 @@ export function createComputerRoutes(: { userId: context.var.actor.id }),},body.url.trim(),+ asApprovalId(body),),);} catch (error) {+ if (error instanceof ActionNeedsApprovalError) {+ return awaitingApproval(context, error);+ }if (error instanceof ActionRefusedError) {return context.json({ error: error.message, rule: error.rule }, 403);}@@ -108,12 +114,23 @@ export function createComputerRoutes(** Each one hands the gateway the computer id, the Bot, the actor and the input, and does no checking* of its own beyond the shape of the request. Where a decision gets made is a single place.+ *+ * Each also passes through whatever `approvalId` the body carried. The route does not look at it+ * or judge it: an approval means something only against the action the gateway is about to take,+ * and a route that decided anything about it would be a second place deciding.*/routes.post("/:botId/click", requireUser, (context) =>act(context, (botId, actor, body, signal) => {const ref = asRef(body);if (!ref) return badRef;- return gateway.click(botId, botId, actor, ref, signal);+ return gateway.click(+ botId,+ botId,+ actor,+ ref,+ signal,+ asApprovalId(body),+ );}),);@@ -134,6 +151,7 @@ export function createComputerRoutes(submit: body?.submit === true,},signal,+ asApprovalId(body),);}),);@@ -153,15 +171,22 @@ export function createComputerRoutes(...(ref ?? {}),},signal,+ asApprovalId(body),);}),);routes.post("/:botId/scroll", requireUser, (context) =>act(context, (botId, actor, body) =>- gateway.scroll(botId, botId, actor, {- ...(typeof body?.deltaY === "number" ? { deltaY: body.deltaY } : {}),- }),+ gateway.scroll(+ botId,+ botId,+ actor,+ {+ ...(typeof body?.deltaY === "number" ? { deltaY: body.deltaY } : {}),+ },+ asApprovalId(body),+ ),),);@@ -299,11 +324,17 @@ export function createComputerRoutes(/** The Bot's files. Through the gateway, like every other acting call. */routes.post("/:botId/files/list", requireUser, (context) =>act(context, (botId, actor, body) =>- gateway.listFiles(botId, botId, actor, {- ...(typeof body?.path === "string" && body.path.trim()- ? { path: body.path.trim() }- : {}),- }),+ gateway.listFiles(+ botId,+ botId,+ actor,+ {+ ...(typeof body?.path === "string" && body.path.trim()+ ? { path: body.path.trim() }+ : {}),+ },+ asApprovalId(body),+ ),),);@@ -312,7 +343,13 @@ export function createComputerRoutes(if (typeof body?.path !== "string" || !body.path.trim()) {return { error: "A file path is required." };}- return gateway.readFile(botId, botId, actor, { path: body.path.trim() });+ return gateway.readFile(+ botId,+ botId,+ actor,+ { path: body.path.trim() },+ asApprovalId(body),+ );}),);@@ -324,11 +361,17 @@ export function createComputerRoutes(if (typeof body?.contents !== "string") {return { error: "The contents to write are required." };}- return gateway.writeFile(botId, botId, actor, {- path: body.path.trim(),- contents: body.contents,- append: body.append === true,- });+ return gateway.writeFile(+ botId,+ botId,+ actor,+ {+ path: body.path.trim(),+ contents: body.contents,+ append: body.append === true,+ },+ asApprovalId(body),+ );}),);@@ -440,6 +483,9 @@ async function act(}return context.json(result as Record<string, unknown>);} catch (error) {+ if (error instanceof ActionNeedsApprovalError) {+ return awaitingApproval(context, error);+ }// A policy refusal is the product working. 403 with the rule that refused it, so the surface can// tell the person which boundary they met rather than reporting a malfunction.if (error instanceof ActionRefusedError) {@@ -477,6 +523,44 @@ function isBadRequest(value: unknown): value is BadRequest {);}+/**+ * A boundary that wants a person, reported as 409 rather than 403.+ *+ * 403 already means one thing to everything downstream of here: a boundary refused you and that is+ * final. The surface renders it as Blocked and the model is told to stop and say so. This is the+ * opposite condition, nothing has been refused and somebody is being asked, so reusing 403 would+ * make every ask rule read to a Bot as a deny rule and produce exactly the outcome the ask list+ * exists to avoid: a turn thrown away on an action the deployment was willing to permit.+ *+ * 409 because the existing 409s on these routes already mean "not now, and here is what to do about+ * it", which a stale snapshot and a person holding the wheel both are. `awaitingApproval` is what+ * separates this from those, and the surface checks for it before it reads a 409 as anything else.+ */+function awaitingApproval(+ context: ComputerContext,+ error: ActionNeedsApprovalError,+) {+ return context.json(+ {+ error: error.message,+ awaitingApproval: true,+ approvalId: error.approvalId,+ question: error.question,+ rule: error.rule,+ },+ 409,+ );+}++/** An answer being presented, if the caller carried one. Its meaning is decided at the gateway. */+function asApprovalId(+ body: Record<string, unknown> | null,+): string | undefined {+ return typeof body?.approvalId === "string" && body.approvalId+ ? body.approvalId+ : undefined;+}+function asRef(body: Record<string, unknown> | null,): { ref: string; snapshotId: number } | undefined {diff --git a/server/src/db/schema/computer.ts b/server/src/db/schema/computer.tsindex 517384e0..231f9d16 100644--- a/server/src/db/schema/computer.ts+++ b/server/src/db/schema/computer.ts@@ -26,6 +26,15 @@ export const actionPolicy = pgTable("action_policy", {/** `enforce` or `dry-run`. Not an enum: the policy module owns that vocabulary. */mode: text("mode").notNull(),deny: text("deny").array().notNull(),+ /**+ * The rules that stop and ask a person, rather than deciding on their own.+ *+ * Defaulted to empty rather than left nullable, so a deployment whose row was written before this+ * list existed comes back up meaning what it meant: no questions, same two answers. A nullable+ * column would put the same reasoning in every reader instead, and one of them would eventually+ * read null as something other than "asks nobody anything".+ */+ ask: text("ask").array().notNull().default([]),allow: text("allow").array().notNull(),/** Who last changed it, for the Admin page and the trail. */updatedBy: text("updated_by"),diff --git a/server/src/index.ts b/server/src/index.tsindex 45dcaa25..695d98f1 100644--- a/server/src/index.ts+++ b/server/src/index.ts@@ -17,6 +17,7 @@ import { createThreadIdentity } from "./channels/thread-identity";import { websocket as channelSocket } from "./channels/socket";import { createSandboxedStore } from "./components/sandboxed";import { createComponentStore } from "./components/store";+import { createApprovalRegistry } from "./computer/approvals";import { createComputerClient } from "./computer/client";import { createComputerGateway } from "./computer/gateway";import {@@ -197,12 +198,23 @@ const bootAuditStore = createAuditStore(database);*/const sandboxedStore = createSandboxedStore(database, bootAuditStore);+/**+ * The one place a Bot's unanswered questions live.+ *+ * Built here rather than inside either thing that raises them, because a deployment has one of+ * these and two things that ask: a Bot meeting an `ask` rule on a button and the same Bot meeting+ * one on a tool call are the same interruption to the same person, and a registry per subsystem+ * would mean the surface somebody happens to be looking at decides which of them they can answer.+ */+const approvals = createApprovalRegistry();+const pluginStore = createPluginStore({database,auditStore: bootAuditStore,credentials: credentialStore,encryptionKey: config.keyEncryptionKey,policy: () => policyStore.get(),+ approvals,});void recordAuditEvent(bootAuditStore, {@@ -344,6 +356,7 @@ const app = createApp(// Read on every decision rather than captured once, so a rule an administrator adds while the// server is running applies to the very next action instead of after a restart.policy: () => policyStore.get(),+ approvals,// Stop, reset and the listing act on containers when there are containers to act on....(supervisor ? { supervisor } : {}),// Only when a deployment has said its Bots retry on a slower rhythm than the built-in window@@ -373,6 +386,8 @@ const app = createApp(sandboxedStore,// How a thread that has no channel is named, so the direct Bot chat is in the same namespace.threadIdentity,+ // Where a person answers what the boundary stopped to ask, whichever half of the product asked.+ approvals,);/**diff --git a/server/src/plugins/routes.ts b/server/src/plugins/routes.tsindex 59c6c2a3..bfa5348f 100644--- a/server/src/plugins/routes.ts+++ b/server/src/plugins/routes.ts@@ -6,6 +6,7 @@ import { CATALOGUE } from "./catalogue";import {CatalogueEntryUnknownError,CustomServerRefusedError,+ PluginNeedsApprovalError,PluginRefusedError,type PluginStore,} from "./store";@@ -348,6 +349,7 @@ export function createPluginRoutes(ref?: string;args?: Record<string, unknown>;agentId?: string;+ approvalId?: unknown;} | null;if (!body?.ref || !body.agentId) {return context.json({ error: "A tool and a Bot are required." }, 400);@@ -359,9 +361,36 @@ export function createPluginRoutes(args: body.args ?? {},botId: body.agentId,actorId: actorEmail(context),+ // Passed through without being looked at. An approval means something only against the call+ // the store is about to make, and a route that judged it would be a second place deciding.+ ...(typeof body.approvalId === "string" && body.approvalId+ ? { approvalId: body.approvalId }+ : {}),});return context.json(result);} catch (error) {+ /**+ * A boundary that wants a person, reported as 409 rather than 403.+ *+ * 403 already means one thing to everything downstream: a boundary refused you, and that is+ * final. The surface renders it as a refusal and the model is told to stop and say so. This is+ * the opposite condition, so reusing 403 would make every ask rule about a tool call read to a+ * Bot as a deny rule, and the turn would be thrown away on work the deployment was willing to+ * permit. The same status and the same body shape the computer's acting routes use, because+ * the surface waits for both in the same way.+ */+ if (error instanceof PluginNeedsApprovalError) {+ return context.json(+ {+ error: error.message,+ awaitingApproval: true,+ approvalId: error.approvalId,+ question: error.question,+ rule: error.rule,+ },+ 409,+ );+ }if (error instanceof PluginRefusedError) {return context.json({ error: error.message, rule: error.rule }, 403);}diff --git a/server/src/plugins/store.ts b/server/src/plugins/store.tsindex 66fc4b46..9470678f 100644--- a/server/src/plugins/store.ts+++ b/server/src/plugins/store.ts@@ -1,5 +1,10 @@import { and, asc, eq, inArray, isNull, or } from "drizzle-orm";import { type AuditStore, recordAuditEvent } from "../audit";+import {+ type ApprovalRegistry,+ fingerprintOf,+ type PendingApproval,+} from "../computer/approvals";import {type ActionPolicy,evaluateActionPolicy,@@ -117,6 +122,33 @@ export class PluginRefusedError extends Error {}}+/**+ * The boundary wants a person's answer before this call is made.+ *+ * Emphatically not a {@link PluginRefusedError}, for the same reason the computer keeps the two+ * apart. A refusal is final and a model told it was refused should say so and stop; this is a pause,+ * and the identical call arriving again with an approval on it is the intended next step rather than+ * an attempt to get around anything. Collapsing them teaches a model to abandon exactly the work a+ * deployment was willing to permit, which is what makes an ask list that degrades to a deny list+ * worse than having no ask list at all.+ */+export class PluginNeedsApprovalError extends Error {+ /** What the caller presents once somebody has answered. */+ readonly approvalId: string;+ /** The question in the words a person is being shown, so the Bot can say what it is waiting for. */+ readonly question: string;+ /** The rule that asked, so the surface can name the boundary the way a refusal does. */+ readonly rule: string;++ constructor(approval: PendingApproval) {+ super(approval.question);+ this.name = "PluginNeedsApprovalError";+ this.approvalId = approval.id;+ this.question = approval.question;+ this.rule = approval.rule;+ }+}+export class CatalogueEntryUnknownError extends Error {constructor(key: string) {super(`${key} is not a server this deployment will connect to.`);@@ -159,6 +191,15 @@ export type PluginStoreOptions = {encryptionKey: string;/** Read at call time, never captured, so a policy changed a moment ago applies to this call. */policy: () => ActionPolicy;+ /**+ * Where a question raised by the `ask` list waits for an answer.+ *+ * Required rather than optional, and the same registry the computer uses. Optional would mean a+ * store built without one, which is easily done, quietly turning every ask rule about a tool call+ * into a refusal: the failure this whole path exists to avoid, arriving through a field somebody+ * forgot to pass.+ */+ approvals: ApprovalRegistry;};export function createPluginStore(options: PluginStoreOptions) {@@ -212,6 +253,74 @@ export function createPluginStore(options: PluginStoreOptions) {return { row, entry };}+ /**+ * Spend a person's answer on this call, or stop and ask them.+ *+ * The fingerprint covers the arguments as well as the tool, which is the difference between this+ * and the browser actions. A click is identified by the thing it lands on; a call to somebody+ * else's server is identified by what it says, and an approval for "post the release note in the+ * team channel" that could be spent on any other message to any other channel would be a+ * confirmation prompt wearing a governance feature's clothes.+ *+ * Returns who allowed it. Throws when nobody has, which every unsuccessful presentation counts as:+ * an expired id, one already spent, a No being replayed and an approval given for a different call+ * all mean that nobody has agreed to THIS, and asking again is both the safe answer and the one a+ * person can act on.+ */+ async function askAbout(question: {+ approvalId: string | undefined;+ botId: string;+ actorId: string;+ ref: string;+ serverId: string;+ toolName: string;+ effect: "read" | "write";+ args: Record<string, unknown>;+ rule: string;+ question: string;+ }): Promise<string> {+ const fingerprint = fingerprintOf({+ botId: question.botId,+ toolName: toolNameFor(question.ref),+ arguments: question.args,+ });+ const presented = question.approvalId+ ? options.approvals.consume(question.approvalId, fingerprint)+ : undefined;+ // An approval with nobody's name on it asks again rather than being credited to whoever was+ // driving the Bot, which is the one attribution this record must never make.+ if (presented?.ok && presented.approval.answeredBy) {+ return presented.approval.answeredBy;+ }++ const pending = options.approvals.request({+ botId: question.botId,+ actor: question.actorId,+ rule: question.rule,+ question: question.question,+ fingerprint,+ // Filed against the tool, so the answer's row lands beside the call's own row rather than+ // under whichever surface the person happened to press the button on.+ target: { type: "mcp_tool", id: question.ref },+ });+ await recordAuditEvent(auditStore, {+ eventType: "approval.requested",+ targetType: "mcp_tool",+ targetId: question.ref,+ payload: {+ bot: question.botId,+ actor: question.actorId,+ approval: pending.id,+ rule: pending.rule,+ reason: pending.question,+ server: question.serverId,+ tool: question.toolName,+ effect: question.effect,+ },+ });+ throw new PluginNeedsApprovalError(pending);+ }+return {/*** Add a server from the catalogue.@@ -736,6 +845,14 @@ export function createPluginStore(options: PluginStoreOptions) {args: Record<string, unknown>;botId: string;actorId: string;+ /**+ * An answer a person already gave, presented for the call it was given for.+ *+ * The same contract the acting routes on the computer have, and for the same reason: the id+ * alone proves nothing, it is the id together with the fingerprint of the call actually being+ * made that means anything.+ */+ approvalId?: string | undefined;}): Promise<{ text: string; isError: boolean }> {const [serverId, ...rest] = input.ref.split("/");const toolName = rest.join("/");@@ -789,10 +906,14 @@ export function createPluginStore(options: PluginStoreOptions) {* that rule is unevaluable, so it would match, so every deployment using the shipped preset* would refuse every MCP call for a reason mentioning a submit button.*- * Neutral values instead. Empty strings match no substring, no key and no extension, so a rule- * written about the browser evaluates to false against a tool call, which is the honest answer:- * a tool call did not click anything. A rule meant to catch tool calls says so, with `mcp` or- * with `intent`.+ * Neutral values instead. Empty strings match no substring, no key and no extension, and+ * `submit` is false because a tool call submits no form, so a rule written about the browser+ * evaluates to false against a tool call, which is the honest answer: a tool call did not click+ * anything. A rule meant to catch tool calls says so, with `mcp` or with `intent`.+ *+ * The blanks are for the policy engine and never for a person: the sentence a question is+ * phrased in reads them as absent rather than as an empty file path, or somebody would be+ * asked to approve "The Bot wants to call ."*/const context: PolicyContext = {tool: { name: toolNameFor(input.ref) },@@ -807,6 +928,7 @@ export function createPluginStore(options: PluginStoreOptions) {repeat: { count: 1 },element: { ref: "", role: "", name: "", type: "" },key: "",+ submit: false,file: { path: "", name: "", extension: "" },intent: effect === "write" ? "write_tool" : "read_tool",mcp: { server: serverId, tool: toolName, effect },@@ -814,8 +936,43 @@ export function createPluginStore(options: PluginStoreOptions) {const verdict = evaluateActionPolicy(options.policy(), context);+ /**+ * The third answer, handled here as well as on the computer.+ *+ * An `ask` verdict is `forward: false` in enforce mode, so a call site that knows only about+ * yes and no reads it as a refusal, and the list an operator wrote to be asked about silently+ * becomes a list of things their Bots may never do. That is the exact failure the ask list+ * exists to prevent, and it is worse here than it looks: the boundary editor and the shipped+ * configuration both offer `ask` as a general third list, and "ask me before anything changes+ * anything in Jira" is the first rule most deployments reach for.+ *+ * So the same shape as the gateway: spend an approval that fits this exact call, or open the+ * question and stop. Nothing is recorded as succeeded or rejected in the second case, because+ * neither happened yet.+ */+ const approved =+ verdict.source === "ask" && !verdict.forward+ ? await askAbout({+ approvalId: input.approvalId,+ botId: input.botId,+ actorId: input.actorId,+ ref: input.ref,+ serverId,+ toolName,+ effect,+ args,+ rule: verdict.matched ?? "",+ question: verdict.reason,+ })+ : undefined;++ // What the boundary settled on once a person's answer is folded in. The source stays `ask`, so+ // the row reads as "allowed, because somebody was asked and said yes" rather than as an+ // ordinary permission nobody ever questioned.+ const carriedOut = verdict.forward || approved !== undefined;+await recordAuditEvent(auditStore, {- eventType: verdict.forward ? "mcp.call_succeeded" : "mcp.call_rejected",+ eventType: carriedOut ? "mcp.call_succeeded" : "mcp.call_rejected",targetType: "mcp_tool",targetId: input.ref,payload: {@@ -825,16 +982,17 @@ export function createPluginStore(options: PluginStoreOptions) {tool: toolName,effect,decision: {- allowed: verdict.allowed,+ allowed: verdict.allowed || approved !== undefined,mode: verdict.mode,rule: verdict.matched,source: verdict.source,- carriedOut: verdict.forward,+ carriedOut,+ ...(approved ? { approvedBy: approved } : {}),},},});- if (!verdict.forward) {+ if (!carriedOut) {throw new PluginRefusedError(verdict.reason, verdict.matched);}diff --git a/server/tests/approval-routes.test.ts b/server/tests/approval-routes.test.tsnew file mode 100644index 00000000..94c4d399--- /dev/null+++ b/server/tests/approval-routes.test.ts@@ -0,0 +1,284 @@+import { describe, expect, test } from "bun:test";+import type { MiddlewareHandler } from "hono";+import { Hono } from "hono";+import type { AuditEventInput, AuditStore } from "../src/audit";+import type { AppVariables } from "../src/auth/guards";+import { createApprovalRoutes } from "../src/computer/approval-routes";+import {+ type ApprovalRegistry,+ createApprovalRegistry,+ fingerprintOf,+} from "../src/computer/approvals";+import type { ComputerClient } from "../src/computer/client";+import {+ ActionNeedsApprovalError,+ createComputerGateway,+} from "../src/computer/gateway";+import type { ActionPolicy } from "../src/computer/policy";+import type { SnapshotResult } from "../src/computer/schema";++/**+ * The surface a person answers on, exercised as the browser reaches it.+ *+ * Tested through the routes rather than through the registry alone, because the two things that go+ * wrong here are things only the handler can get wrong: which Bot an answer is recorded against, and+ * what the reply carries back out of the process. Neither is visible from the registry's own tests,+ * and both are the sort of thing a sibling handler quietly diverges on.+ */++const SNAPSHOT: SnapshotResult = {+ snapshotId: 7,+ url: "https://example.com/order",+ title: "Order",+ truncated: false,+ elements: [+ { ref: "e1", role: "input", name: "Customer name:", type: "text" },+ { ref: "e9", role: "button", name: "Submit order" },+ ],+};++const ASKING: ActionPolicy = {+ mode: "enforce",+ deny: [],+ ask: ['contains(element.name, "submit")'],+ allow: ["true"],+};++/** The person whose turn raised the question. Not the person who answers it. */+const DRIVER = { id: "dev-local-user" };++const MANAGER = {+ id: "manager-user",+ email: "[email protected]",+ role: "user",+} as const;++function fakeClient() {+ const calls: string[] = [];+ const client = {+ snapshot: async () => SNAPSHOT,+ click: async () => {+ calls.push("click");+ return { action: "click", url: SNAPSHOT.url, elapsedMs: 1 } as never;+ },+ forBot() {+ return client;+ },+ } as unknown as ComputerClient;+ return { client, calls };+}++/**+ * One audit store and one registry behind both halves, which is the arrangement being tested.+ *+ * The question is raised by the gateway and answered on the routes, minutes apart and by different+ * people, and the only thing joining the two rows is the approval id. A test that gave each half its+ * own store could not see whether they agree.+ */+async function surface() {+ const rows: AuditEventInput[] = [];+ const auditStore: AuditStore = {+ insert: async (event) => void rows.push(event),+ };+ const approvals: ApprovalRegistry = createApprovalRegistry();+ const { client, calls } = fakeClient();+ const gateway = createComputerGateway({+ client,+ auditStore,+ policy: () => ASKING,+ approvals,+ });+ await gateway.snapshot("bot-1");++ const requireUser: MiddlewareHandler<{ Variables: AppVariables }> = async (+ context,+ next,+ ) => {+ context.set("actor", MANAGER);+ await next();+ };+ const app = new Hono<{ Variables: AppVariables }>();+ app.route("/", createApprovalRoutes(approvals, auditStore, requireUser));++ /** A click that meets the ask rule, and the question it leaves open. */+ const ask = async (botId: string) =>+ (await gateway+ .click(botId, botId, DRIVER, { ref: "e9", snapshotId: 7 })+ .catch((caught: unknown) => caught)) as ActionNeedsApprovalError;++ return { app, approvals, gateway, ask, rows, calls };+}++const answer =+ (app: Hono<{ Variables: AppVariables }>) =>+ async (botId: string, approvalId: string, granted: boolean) =>+ app.request(`/${botId}/${approvalId}`, {+ method: "POST",+ headers: { "content-type": "application/json" },+ body: JSON.stringify({ granted }),+ });++describe("answering a question", () => {+ test("records the answer under the person who gave it and lets the action run", async () => {+ const { app, ask, rows, gateway, calls } = await surface();+ const asked = await ask("bot-1");++ const response = await answer(app)("bot-1", asked.approvalId, true);+ expect(response.status).toBe(200);++ await gateway.click(+ "bot-1",+ "bot-1",+ DRIVER,+ { ref: "e9", snapshotId: 7 },+ undefined,+ asked.approvalId,+ );++ expect(calls).toEqual(["click"]);+ // Three rows for one action, and each answers a different question: it was asked, somebody said+ // yes, it happened.+ expect(rows.map((row) => row.eventType)).toEqual([+ "approval.requested",+ "approval.granted",+ "computer.action_allowed",+ ]);+ // The answer is credited to whoever answered, not to whoever was driving the Bot, which is the+ // one thing an approval trail must never get wrong.+ expect(rows[0]?.payload.actor).toBe("dev-local-user");+ expect(rows[1]?.payload.actor).toBe("manager-user");+ expect(rows[1]?.actorUserId).toBe("manager-user");+ expect(rows[1]?.payload.asked).toBe("dev-local-user");+ const decision = rows[2]?.payload.decision as { approvedBy?: string };+ expect(decision.approvedBy).toBe("manager-user");+ });++ test("files the answer against the Bot the question was about, not the address it arrived at", async () => {+ // The Bot in the path is whatever the caller typed. Taking it from the request would put a grant+ // in the trail under one Bot and the action it paid for under another, joined by an id that+ // appears on both and reconciles neither.+ const { app, ask, rows } = await surface();+ const asked = await ask("bot-1");++ const wrongBot = await answer(app)("bot-2", asked.approvalId, true);+ expect(wrongBot.status).toBe(409);+ expect(rows.map((row) => row.eventType)).toEqual(["approval.requested"]);++ expect((await answer(app)("bot-1", asked.approvalId, true)).status).toBe(+ 200,+ );+ expect(rows[1]?.targetId).toBe("bot-1");+ expect(rows[1]?.payload.bot).toBe("bot-1");+ });++ test("never sends the binding out of the process", async () => {+ // The fingerprint is what ties an approval to one action, and it is compared here. Nothing on+ // the surface can do anything with it, and a handler that returned it would be quietly undoing+ // the invariant its sibling four lines up is careful to keep.+ const { app, ask } = await surface();+ const asked = await ask("bot-1");++ const listed = await (await app.request("/bot-1")).json();+ const answered = await (+ await answer(app)("bot-1", asked.approvalId, true)+ ).json();++ for (const record of [+ ...(listed as { approvals: Record<string, unknown>[] }).approvals,+ answered as Record<string, unknown>,+ ]) {+ expect(record.fingerprint).toBeUndefined();+ expect(record.actor).toBeUndefined();+ expect(record.target).toBeUndefined();+ expect(record.question).toContain("Submit order");+ }+ });++ test("a question nobody is waiting on any more is a conflict, not a fault", async () => {+ const { app, ask } = await surface();+ const asked = await ask("bot-1");++ expect((await answer(app)("bot-1", asked.approvalId, false)).status).toBe(+ 200,+ );+ // Answered once, and not answerable again: otherwise a second tab can quietly overturn a+ // decision the trail has already recorded as made.+ expect((await answer(app)("bot-1", asked.approvalId, true)).status).toBe(+ 409,+ );+ expect((await answer(app)("bot-1", "not-a-real-id", true)).status).toBe(+ 409,+ );+ });++ test("refuses to read a missing answer as either one", async () => {+ const { app, ask, rows } = await surface();+ const asked = await ask("bot-1");++ const response = await app.request(`/bot-1/${asked.approvalId}`, {+ method: "POST",+ headers: { "content-type": "application/json" },+ body: JSON.stringify({}),+ });+ expect(response.status).toBe(400);+ expect(rows).toHaveLength(1);+ });++ test("shows one Bot's open questions and not another's", async () => {+ const { app, ask } = await surface();+ const asked = await ask("bot-1");++ const mine = (await (await app.request("/bot-1")).json()) as {+ approvals: { id: string; rule: string }[];+ };+ expect(mine.approvals).toHaveLength(1);+ expect(mine.approvals[0]?.id).toBe(asked.approvalId);+ expect(mine.approvals[0]?.rule).toBe('contains(element.name, "submit")');++ const theirs = (await (await app.request("/bot-2")).json()) as {+ approvals: unknown[];+ };+ expect(theirs.approvals).toEqual([]);+ });++ test("a declined answer stops the action without pretending it was refused by a rule", async () => {+ const { app, ask, rows, gateway, calls } = await surface();+ const asked = await ask("bot-1");++ await answer(app)("bot-1", asked.approvalId, false);+ // Presenting a No asks again rather than going through, and nothing reached the computer.+ await expect(+ gateway.click(+ "bot-1",+ "bot-1",+ DRIVER,+ { ref: "e9", snapshotId: 7 },+ undefined,+ asked.approvalId,+ ),+ ).rejects.toThrow(ActionNeedsApprovalError);+ expect(calls).toEqual([]);+ expect(rows.map((row) => row.eventType)).toEqual([+ "approval.requested",+ "approval.denied",+ "approval.requested",+ ]);+ });++ test("an answer is spendable only on the action it was given for", async () => {+ const { app, ask, approvals } = await surface();+ const asked = await ask("bot-1");+ await answer(app)("bot-1", asked.approvalId, true);++ const elsewhere = approvals.consume(+ asked.approvalId,+ fingerprintOf({+ botId: "bot-1",+ toolName: "computer_click",+ ref: "e1",+ pageUrl: SNAPSHOT.url,+ }),+ );+ expect(elsewhere.ok).toBe(false);+ });+});diff --git a/server/tests/computer-approvals.test.ts b/server/tests/computer-approvals.test.tsnew file mode 100644index 00000000..7ecfe1fc--- /dev/null+++ b/server/tests/computer-approvals.test.ts@@ -0,0 +1,279 @@+import { describe, expect, test } from "bun:test";+import {+ type ApprovalSubject,+ createApprovalRegistry,+ fingerprintOf,+} from "../src/computer/approvals";++/**+ * What an approval has to mean, tested as properties rather than as a call sequence.+ *+ * A registry that only remembered ids would pass a naive test and be worthless: the failure it+ * exists to prevent is a person allowing one thing and a model spending that permission on another,+ * and nothing about that is visible from a green typecheck. So the cases here are the four ways a+ * grant can be stretched beyond what somebody agreed to, plus the two ways it stops being valid.+ */++const CLICK: ApprovalSubject = {+ botId: "sales-bot",+ toolName: "computer_click",+ ref: "e9",+ pageUrl: "https://example.com/order",+};++function registry(clock?: { at: number }) {+ return createApprovalRegistry(clock ? { now: () => clock.at } : {});+}++function ask(+ approvals: ReturnType<typeof registry>,+ subject: ApprovalSubject = CLICK,+) {+ return approvals.request({+ botId: subject.botId,+ actor: "[email protected]",+ rule: 'contains(element.name, "submit")',+ question: "The Bot wants to press “Submit order” on example.com.",+ fingerprint: fingerprintOf(subject),+ target: { type: "computer", id: subject.botId },+ });+}++/** Answering, on the Bot the question was asked about, which is the ordinary case. */+function answer(+ approvals: ReturnType<typeof registry>,+ id: string,+ who: string,+ granted: boolean,+ botId = CLICK.botId,+) {+ return approvals.answer(id, botId, who, granted);+}++describe("an approval", () => {+ test("is spendable on the action it was granted for", () => {+ const approvals = registry();+ const pending = ask(approvals);+ answer(approvals, pending.id, "[email protected]", true);++ const spent = approvals.consume(pending.id, fingerprintOf(CLICK));+ expect(spent.ok).toBe(true);+ if (spent.ok)+ expect(spent.approval.answeredBy).toBe("[email protected]");+ });++ test("is refused for a DIFFERENT action, which is the whole point of it", () => {+ // "Yes, click Place order" must not be replayable as "yes, click Delete account". Without this+ // the feature is a dialog box that returns a token good for anything.+ const approvals = registry();+ const pending = ask(approvals);+ answer(approvals, pending.id, "[email protected]", true);++ const elsewhere = approvals.consume(+ pending.id,+ fingerprintOf({ ...CLICK, ref: "e42" }),+ );+ expect(elsewhere.ok).toBe(false);+ if (!elsewhere.ok) expect(elsewhere.reason).toBe("a different action");+ });++ test("survives a failed replay, so the person's answer is not lost with it", () => {+ // A mismatch leaves the approval alone. Burning it would let a model that reached for the wrong+ // button take away permission for the one somebody actually meant.+ const approvals = registry();+ const pending = ask(approvals);+ answer(approvals, pending.id, "[email protected]", true);+ approvals.consume(pending.id, fingerprintOf({ ...CLICK, ref: "e42" }));++ expect(approvals.consume(pending.id, fingerprintOf(CLICK)).ok).toBe(true);+ });++ test("is good exactly once", () => {+ const approvals = registry();+ const pending = ask(approvals);+ answer(approvals, pending.id, "[email protected]", true);++ expect(approvals.consume(pending.id, fingerprintOf(CLICK)).ok).toBe(true);+ const again = approvals.consume(pending.id, fingerprintOf(CLICK));+ expect(again.ok).toBe(false);+ if (!again.ok) expect(again.reason).toBe("unknown");+ });++ test("cannot be spent before anybody has answered", () => {+ const approvals = registry();+ const pending = ask(approvals);++ const early = approvals.consume(pending.id, fingerprintOf(CLICK));+ expect(early.ok).toBe(false);+ if (!early.ok) expect(early.reason).toBe("unanswered");+ });++ test("a No is an answer, and it is final", () => {+ const approvals = registry();+ const pending = ask(approvals);+ answer(approvals, pending.id, "[email protected]", false);++ const declined = approvals.consume(pending.id, fingerprintOf(CLICK));+ expect(declined.ok).toBe(false);+ if (!declined.ok) expect(declined.reason).toBe("declined");+ });++ test("cannot be answered twice, so a decision cannot be quietly overturned", () => {+ const approvals = registry();+ const pending = ask(approvals);+ answer(approvals, pending.id, "[email protected]", false);++ const second = answer(approvals, pending.id, "[email protected]", true);+ expect(second.ok).toBe(false);+ expect(approvals.consume(pending.id, fingerprintOf(CLICK)).ok).toBe(false);+ });++ test("runs out, and stops being answerable when it does", () => {+ const clock = { at: Date.parse("2026-01-01T09:00:00.000Z") };+ const approvals = createApprovalRegistry({+ now: () => clock.at,+ ttlMs: 60_000,+ });+ const pending = ask(approvals);+ expect(approvals.pending("sales-bot")).toHaveLength(1);++ clock.at += 60_001;+ // Swept on the way past rather than on a timer, so a question nobody answered leaves no trace+ // that could later be mistaken for one somebody did.+ expect(approvals.pending("sales-bot")).toHaveLength(0);+ expect(answer(approvals, pending.id, "[email protected]", true).ok).toBe(+ false,+ );+ expect(approvals.consume(pending.id, fingerprintOf(CLICK)).ok).toBe(false);+ });++ test("an already-granted approval expires too", () => {+ const clock = { at: Date.parse("2026-01-01T09:00:00.000Z") };+ const approvals = createApprovalRegistry({+ now: () => clock.at,+ ttlMs: 60_000,+ });+ const pending = ask(approvals);+ answer(approvals, pending.id, "[email protected]", true);++ clock.at += 60_001;+ // Consent to something that was going to happen now is not consent to it happening in an hour.+ expect(approvals.consume(pending.id, fingerprintOf(CLICK)).ok).toBe(false);+ });+});++describe("an approval belongs to one Bot", () => {+ const SAME_ACTION_OTHER_BOT: ApprovalSubject = {+ ...CLICK,+ botId: "research-bot",+ };++ test("cannot be spent by another Bot doing the identical thing", () => {+ // The Bot id is inside the fingerprint, so two Bots clicking the same ref on the same page+ // produce two different bindings. Otherwise a permission given on one computer would carry over+ // to a computer with different logins and a different person's session in it.+ const approvals = registry();+ const pending = ask(approvals);+ answer(approvals, pending.id, "[email protected]", true);++ const elsewhere = approvals.consume(+ pending.id,+ fingerprintOf(SAME_ACTION_OTHER_BOT),+ );+ expect(elsewhere.ok).toBe(false);+ if (!elsewhere.ok) expect(elsewhere.reason).toBe("a different action");+ });++ test("cannot be answered from another Bot's address", () => {+ // The id is enough to find the question, so this is not authorisation, it is the trail: the row+ // an answer writes says which Bot it was about, and it is taken from the request. Without this+ // check a grant lands under one Bot and the action it pays for under another, and filtering the+ // audit page by either shows half the story.+ const approvals = registry();+ const pending = ask(approvals);++ const elsewhere = approvals.answer(+ pending.id,+ "research-bot",+ "[email protected]",+ true,+ );+ expect(elsewhere.ok).toBe(false);+ // Still open, and still answerable by somebody who arrived at the right address.+ expect(answer(approvals, pending.id, "[email protected]", true).ok).toBe(+ true,+ );+ });++ test("does not show up in another Bot's pending list", () => {+ const approvals = registry();+ ask(approvals);+ expect(approvals.pending("research-bot")).toEqual([]);+ expect(approvals.pending("sales-bot")).toHaveLength(1);+ });+});++describe("the fingerprint", () => {+ test("is the same for the same action and different for every changed part", () => {+ expect(fingerprintOf(CLICK)).toBe(fingerprintOf({ ...CLICK }));+ for (const changed of [+ { ...CLICK, botId: "other" },+ { ...CLICK, toolName: "computer_key" },+ { ...CLICK, ref: "e10" },+ { ...CLICK, key: "Enter" },+ { ...CLICK, filePath: "notes.md" },+ { ...CLICK, pageUrl: "https://example.com/other" },+ // Typing into a field and typing into it then pressing Enter are two different actions, and+ // the second one submits the form. An approval for one must not be spendable as the other.+ { ...CLICK, submit: true },+ { ...CLICK, arguments: { channel: "#general" } },+ ]) {+ expect(fingerprintOf(changed)).not.toBe(fingerprintOf(CLICK));+ }+ });++ test("reads the same arguments the same way whatever order they arrive in", () => {+ // A tool call goes through a parse between being asked about and being retried, and an approval+ // that stopped fitting because a client wrote its fields in another order would send somebody a+ // second question about the call they just allowed.+ expect(+ fingerprintOf({+ botId: "b",+ toolName: "t",+ arguments: { channel: "#general", text: "shipped" },+ }),+ ).toBe(+ fingerprintOf({+ botId: "b",+ toolName: "t",+ arguments: { text: "shipped", channel: "#general" },+ }),+ );+ });++ test("tells one set of arguments from another", () => {+ // The reason arguments are in here at all: "post the release note in the team channel" is not+ // permission to post something else somewhere else.+ expect(+ fingerprintOf({+ botId: "b",+ toolName: "t",+ arguments: { channel: "#general", text: "shipped" },+ }),+ ).not.toBe(+ fingerprintOf({+ botId: "b",+ toolName: "t",+ arguments: { channel: "#board", text: "shipped" },+ }),+ );+ });++ test("cannot be made to collide by shuffling where a boundary falls", () => {+ // The parts are joined with a separator no field can contain, so a ref of "ab" with no key is a+ // different action from a ref of "a" with a key of "b".+ expect(fingerprintOf({ botId: "b", toolName: "t", ref: "ab" })).not.toBe(+ fingerprintOf({ botId: "b", toolName: "t", ref: "a", key: "b" }),+ );+ });+});diff --git a/server/tests/computer-gateway.test.ts b/server/tests/computer-gateway.test.tsindex db7576b1..6de19372 100644--- a/server/tests/computer-gateway.test.ts+++ b/server/tests/computer-gateway.test.ts@@ -1,7 +1,9 @@import { describe, expect, test } from "bun:test";import type { AuditEventInput, AuditStore } from "../src/audit";+import { createApprovalRegistry } from "../src/computer/approvals";import type { ComputerClient } from "../src/computer/client";import {+ ActionNeedsApprovalError,ActionRefusedError,createComputerGateway,} from "../src/computer/gateway";@@ -105,7 +107,14 @@ function fakeAudit() {}const ACTOR = { id: "dev-local-user" };-const PERMISSIVE: ActionPolicy = { mode: "enforce", deny: [], allow: ["true"] };+/** A second person, with a real users row, so the approval rows can be told apart by who wrote them. */+const MANAGER = { id: "manager-user", userId: "manager-user" };+const PERMISSIVE: ActionPolicy = {+ mode: "enforce",+ deny: [],+ ask: [],+ allow: ["true"],+};async function gatewayWith(policy: ActionPolicy | undefined,@@ -114,15 +123,20 @@ async function gatewayWith() {const { client, calls } = fakeClient();const { store, rows } = fakeAudit();+ // The registry the deployment shares between everything that can ask. Held here so these tests can+ // answer a question the way a person does, without going through the surface they answer it on;+ // that surface has its own tests.+ const approvals = createApprovalRegistry();const gateway = createComputerGateway({client,auditStore: store,policy: () => policy,+ approvals,...(repeat ? { repeat } : {}),});// Every test acts on refs, so the server must hold a snapshot first, exactly as the real flow does.await gateway.snapshot("default");- return { gateway, calls, rows };+ return { gateway, approvals, calls, rows };}describe("the computer gateway", () => {@@ -232,6 +246,7 @@ describe("the computer gateway", () => {const { gateway, calls, rows } = await gatewayWith({mode: "dry-run",deny: ['contains(element.name, "submit")'],+ ask: [],allow: ["true"],});@@ -407,6 +422,264 @@ describe("the computer gateway", () => {});});+/**+ * The path where the boundary stops and asks.+ *+ * Everything above proves the gateway can say yes or no. These prove it can say "not yet", which is+ * a harder thing to get right: the action must not reach the computer, the trail must show the+ * question rather than a verdict nobody reached, and the answer must only work for the action it was+ * given for. That last one is why the error carries an id at all.+ */+describe("the gateway when the boundary asks a person", () => {+ const ASKING: ActionPolicy = {+ mode: "enforce",+ deny: [],+ ask: ['contains(element.name, "submit")'],+ allow: ["true"],+ };++ test("stops the action and asks, rather than refusing it", async () => {+ const { gateway, calls, rows } = await gatewayWith(ASKING);++ const error = await gateway+ .click("default", "bot-1", ACTOR, { ref: "e9", snapshotId: 7 })+ .catch((caught: unknown) => caught);++ expect(error).toBeInstanceOf(ActionNeedsApprovalError);+ // Not a refusal. A Bot told it was blocked gives up and says so; this one is meant to wait.+ expect(error).not.toBeInstanceOf(ActionRefusedError);+ expect(calls).toEqual([]);++ // One row, and it is the question. Nothing was allowed and nothing was refused, so writing+ // either would put a verdict in the trail that the policy never reached.+ expect(rows).toHaveLength(1);+ expect(rows[0]?.eventType).toBe("approval.requested");+ expect(rows[0]?.payload.rule).toBe('contains(element.name, "submit")');+ expect(rows[0]?.payload.action).toBe("computer_click");+ expect(rows[0]?.payload.approval).toBe(+ (error as ActionNeedsApprovalError).approvalId,+ );+ });++ test("carries the action out once a person has allowed it", async () => {+ const { gateway, approvals, calls, rows } = await gatewayWith(ASKING);+ const asked = (await gateway+ .click("default", "bot-1", ACTOR, { ref: "e9", snapshotId: 7 })+ .catch((caught: unknown) => caught)) as ActionNeedsApprovalError;++ approvals.answer(asked.approvalId, "bot-1", MANAGER.id, true);+ await gateway.click(+ "default",+ "bot-1",+ ACTOR,+ { ref: "e9", snapshotId: 7 },+ undefined,+ asked.approvalId,+ );++ expect(calls).toEqual(["click"]);+ // Two rows here, and the third is written where the answer was given: the question, and the+ // action it turned into. The action's own row says a person stood behind it and names them,+ // rather than reading as an ordinary permission nobody ever questioned.+ expect(rows.map((row) => row.eventType)).toEqual([+ "approval.requested",+ "computer.action_allowed",+ ]);+ const decision = rows[1]?.payload.decision as {+ source?: string;+ approvedBy?: string;+ };+ expect(decision.source).toBe("ask");+ expect(decision.approvedBy).toBe("manager-user");+ });++ test("an approval for one action does not carry to another", async () => {+ // The grant is bound to a fingerprint of the exact call. Pressing a different thing on the same+ // page with the same id in hand asks again rather than going through, which is the difference+ // between an approval and a token good for anything.+ const { gateway, approvals, calls } = await gatewayWith({+ ...ASKING,+ ask: ["true"],+ });+ const asked = (await gateway+ .click("default", "bot-1", ACTOR, { ref: "e9", snapshotId: 7 })+ .catch((caught: unknown) => caught)) as ActionNeedsApprovalError;+ approvals.answer(asked.approvalId, "bot-1", MANAGER.id, true);++ await expect(+ gateway.click(+ "default",+ "bot-1",+ ACTOR,+ { ref: "e1", snapshotId: 7 },+ undefined,+ asked.approvalId,+ ),+ ).rejects.toThrow(ActionNeedsApprovalError);+ expect(calls).toEqual([]);+ });++ test("a declined request asks again rather than acting", async () => {+ const { gateway, approvals, calls, rows } = await gatewayWith(ASKING);+ const asked = (await gateway+ .click("default", "bot-1", ACTOR, { ref: "e9", snapshotId: 7 })+ .catch((caught: unknown) => caught)) as ActionNeedsApprovalError;++ approvals.answer(asked.approvalId, "bot-1", MANAGER.id, false);+ await expect(+ gateway.click(+ "default",+ "bot-1",+ ACTOR,+ { ref: "e9", snapshotId: 7 },+ undefined,+ asked.approvalId,+ ),+ ).rejects.toThrow(ActionNeedsApprovalError);++ expect(calls).toEqual([]);+ // A No leaves a second question rather than a refusal row: nobody has agreed to this, and the+ // trail says so where it happened.+ expect(rows[1]?.eventType).toBe("approval.requested");+ });++ test("a type call that will press Enter is judged as one that submits", async () => {+ // The third door into a form. The computer presses Enter itself when the Bot asks it to, so no+ // keypress ever reaches the gateway as an action of its own, and a boundary written about+ // clicking and about `key` let the one call that submits a single-field form through.+ const { gateway, calls } = await gatewayWith({+ ...PERMISSIVE,+ ask: ["submit"],+ });++ await expect(+ gateway.type("default", "bot-1", ACTOR, {+ ref: "e1",+ snapshotId: 7,+ text: "SW1A 1AA",+ submit: true,+ }),+ ).rejects.toThrow(ActionNeedsApprovalError);+ expect(calls).toEqual([]);++ // Filling the same field in without submitting is not the same action and is not asked about.+ await gateway.type("default", "bot-1", ACTOR, {+ ref: "e1",+ snapshotId: 7,+ text: "SW1A 1AA",+ });+ expect(calls).toEqual(["type"]);+ });++ test("an answer given for typing is not spendable on typing and submitting", async () => {+ // Submitting is the escalation the binding has to cover: "yes, fill the postcode in" is not+ // "yes, fill it in and send the form".+ const { gateway, approvals, calls } = await gatewayWith({+ ...PERMISSIVE,+ ask: ["true"],+ });+ const asked = (await gateway+ .type("default", "bot-1", ACTOR, {+ ref: "e1",+ snapshotId: 7,+ text: "SW1A 1AA",+ })+ .catch((caught: unknown) => caught)) as ActionNeedsApprovalError;+ approvals.answer(asked.approvalId, "bot-1", MANAGER.id, true);++ await expect(+ gateway.type(+ "default",+ "bot-1",+ ACTOR,+ { ref: "e1", snapshotId: 7, text: "SW1A 1AA", submit: true },+ undefined,+ asked.approvalId,+ ),+ ).rejects.toThrow(ActionNeedsApprovalError);+ expect(calls).toEqual([]);+ });++ test("the question is visible to the surface while it is open", async () => {+ const { gateway, approvals } = await gatewayWith(ASKING);+ const asked = (await gateway+ .click("default", "bot-1", ACTOR, { ref: "e9", snapshotId: 7 })+ .catch((caught: unknown) => caught)) as ActionNeedsApprovalError;++ const waiting = approvals.pending("bot-1");+ expect(waiting).toHaveLength(1);+ expect(waiting[0]?.id).toBe(asked.approvalId);+ expect(waiting[0]?.question).toContain("Submit order");+ // Another Bot's screen must not offer somebody a question about this one's computer.+ expect(approvals.pending("bot-2")).toEqual([]);+ });++ test("dry-run records the question and lets the action through", async () => {+ // Dry-run promises a policy that changes nothing, so an ask rule under it interrupts nobody. The+ // row is what an operator switched dry-run on to read.+ const { gateway, calls, rows } = await gatewayWith({+ ...ASKING,+ mode: "dry-run",+ });++ await gateway.click("default", "bot-1", ACTOR, {+ ref: "e9",+ snapshotId: 7,+ });++ expect(calls).toEqual(["click"]);+ expect(rows).toHaveLength(1);+ expect(rows[0]?.eventType).toBe("computer.action_refused");+ const decision = rows[0]?.payload.decision as {+ source?: string;+ carriedOut?: boolean;+ };+ expect(decision.source).toBe("ask");+ expect(decision.carriedOut).toBe(true);+ });++ test("a deny beats an ask on the same action", async () => {+ // Precedence, through the gateway rather than only in the evaluator: a forbidden thing is refused+ // outright and is never put in front of a person as a question they could say yes to.+ const { gateway, calls, rows } = await gatewayWith({+ ...ASKING,+ deny: ['contains(element.name, "submit")'],+ });++ await expect(+ gateway.click("default", "bot-1", ACTOR, { ref: "e9", snapshotId: 7 }),+ ).rejects.toThrow(ActionRefusedError);+ expect(calls).toEqual([]);+ expect(rows[0]?.eventType).toBe("computer.action_refused");+ });++ test("a file write can be held back the same way a click can", async () => {+ const { gateway, calls, rows } = await gatewayWith({+ mode: "enforce",+ deny: [],+ ask: ['intent == "write_file" && !matches(file.path, "^notes/")'],+ allow: ["true"],+ });++ await expect(+ gateway.writeFile("default", "bot-1", ACTOR, {+ path: "reports/august.csv",+ contents: "anything",+ }),+ ).rejects.toThrow(ActionNeedsApprovalError);+ expect(calls).toEqual([]);+ expect(rows[0]?.payload.file).toBe("reports/august.csv");++ // A path the rule leaves alone still goes straight through, or the rule would be a deny wearing+ // a different name.+ await gateway.writeFile("default", "bot-1", ACTOR, {+ path: "notes/today.md",+ contents: "anything",+ });+ expect(calls).toEqual(["writeFile"]);+ });+});+/*** The gateway is the only place that can count this, which is why it does.*diff --git a/server/tests/computer-policy.test.ts b/server/tests/computer-policy.test.tsindex c2c8efe5..d9bb383b 100644--- a/server/tests/computer-policy.test.ts+++ b/server/tests/computer-policy.test.ts@@ -30,7 +30,12 @@ function context(overrides: Partial<PolicyContext> = {}): PolicyContext {};}-const permissive: ActionPolicy = { mode: "enforce", deny: [], allow: ["true"] };+const permissive: ActionPolicy = {+ mode: "enforce",+ deny: [],+ ask: [],+ allow: ["true"],+};describe("evaluateActionPolicy", () => {test("an absent policy refuses, rather than permitting everything", () => {@@ -42,7 +47,7 @@ describe("evaluateActionPolicy", () => {test("an empty allow list refuses", () => {const decision = evaluateActionPolicy(- { mode: "enforce", deny: [], allow: [] },+ { mode: "enforce", deny: [], ask: [], allow: [] },context(),);expect(decision.allowed).toBe(false);@@ -93,7 +98,7 @@ describe("evaluateActionPolicy", () => {test("a broken allow expression does not permit", () => {const decision = evaluateActionPolicy(- { mode: "enforce", deny: [], allow: ["also not ( valid"] },+ { mode: "enforce", deny: [], ask: [], allow: ["also not ( valid"] },context(),);expect(decision.allowed).toBe(false);@@ -105,6 +110,7 @@ describe("evaluateActionPolicy", () => {{mode: "dry-run",deny: ['contains(element.name, "submit")'],+ ask: [],allow: ["true"],},context(),@@ -164,10 +170,43 @@ describe("parseActionPolicy", () => {expect(result.ok).toBe(true);if (result.ok) {expect(result.policy.deny).toEqual([]);+ expect(result.policy.ask).toEqual([]);expect(result.policy.allow).toEqual([]);}});+ test("a policy written before the ask list existed still parses", () => {+ // Every deployment already running has a saved policy with two lists in it. Rejecting one, or+ // reading its absence as anything other than "asks nobody anything", would change what an+ // existing boundary means at the moment the server came back up.+ const result = parseActionPolicy({+ mode: "enforce",+ deny: ['contains(element.name, "pay")'],+ allow: ["true"],+ });+ expect(result.ok).toBe(true);+ if (result.ok) expect(result.policy.ask).toEqual([]);+ });++ test("keeps the ask rules it was given", () => {+ const result = parseActionPolicy({+ mode: "enforce",+ deny: [],+ ask: ['intent == "write_file"'],+ allow: ["true"],+ });+ expect(result.ok).toBe(true);+ if (result.ok)+ expect(result.policy.ask).toEqual(['intent == "write_file"']);+ });++ test("rejects an ask list that is not a list of expressions", () => {+ expect(parseActionPolicy({ mode: "enforce", ask: "everything" }).ok).toBe(+ false,+ );+ expect(parseActionPolicy({ mode: "enforce", ask: [7] }).ok).toBe(false);+ });+test.each([["not an object", "nonsense"],["a missing mode", { deny: [], allow: [] }],@@ -188,6 +227,7 @@ describe("the second door", () => {const policy = {mode: "enforce" as const,deny: ['tool.name == "computer_key" && key == "Enter"'],+ ask: [],allow: ["true"],};const refused = evaluateActionPolicy(policy, {@@ -211,6 +251,45 @@ describe("the second door", () => {});expect(allowed.allowed).toBe(true);});++ test("a rule can refuse the type tool's own Enter, which is neither a click nor a keypress", () => {+ // The type tool takes a flag meaning "and submit", and the computer presses Enter itself, so no+ // keypress ever arrives as an action of its own. A boundary written about clicking and about+ // `key` watched the one call that submits a single-field form go straight past it.+ const policy = {+ mode: "enforce" as const,+ deny: [+ '(intent == "activate" && contains(element.name, "submit")) || (tool.name == "computer_key" && key == "Enter") || submit',+ ],+ ask: [],+ allow: ["true"],+ };+ const typing = (submit: boolean): PolicyContext => ({+ tool: { name: "computer_type" },+ bot: { id: "sales" },+ actor: { id: "someone" },+ page: { url: "https://example.com/order", host: "example.com" },+ element: { ref: "e6", role: "input", name: "Postcode" },+ intent: "type",+ submit,+ });++ expect(evaluateActionPolicy(policy, typing(true)).allowed).toBe(false);+ // Filling the field in is still allowed, or the rule would stop the Bot typing at all.+ expect(evaluateActionPolicy(policy, typing(false)).allowed).toBe(true);+ // And the same rule stays evaluable on an action that cannot submit anything, which is why the+ // field is on every context rather than only on the calls that can set it.+ expect(+ evaluateActionPolicy(policy, {+ tool: { name: "computer_scroll" },+ bot: { id: "sales" },+ actor: { id: "someone" },+ page: { url: "https://example.com/order", host: "example.com" },+ intent: "read",+ submit: false,+ }).allowed,+ ).toBe(true);+ });});/**@@ -231,6 +310,7 @@ describe("a rule written about what an action does", () => {const policy = {mode: "enforce" as const,deny: ['intent == "activate" && contains(element.name, "submit")'],+ ask: [],allow: ["true"],};@@ -320,7 +400,7 @@ describe("a rule that names an identifier only some actions carry", () => {test("unguarded, it refuses a navigation that has no key at all", () => {const decision = evaluateActionPolicy(- { mode: "enforce", deny: ['key == "Enter"'], allow: ["true"] },+ { mode: "enforce", deny: ['key == "Enter"'], ask: [], allow: ["true"] },navigating,);// Failing closed on an unevaluable rule is the safe answer. The shipped preset carries the guard@@ -333,6 +413,7 @@ describe("a rule that names an identifier only some actions carry", () => {{mode: "enforce",deny: ['tool.name == "computer_key" && key == "Enter"'],+ ask: [],allow: ["true"],},navigating,@@ -345,6 +426,7 @@ describe("a rule that names an identifier only some actions carry", () => {{mode: "enforce",deny: ['tool.name == "computer_key" && key == "Enter"'],+ ask: [],allow: ["true"],},{@@ -359,6 +441,175 @@ describe("a rule that names an identifier only some actions carry", () => {});});+/**+ * The third answer, and the order it is asked in.+ *+ * Precedence is the whole design here and none of it is visible from the types. An ask that could+ * soften a deny would let a person wave through something a deployment forbade; an ask evaluated+ * after allow would never fire at all, because the shipped policy permits everything. Both mistakes+ * produce a rule that looks configured and does nothing anybody intended, so both are tested against+ * the permissive default deployments actually run.+ */+describe("asking a person", () => {+ const asking: ActionPolicy = {+ ...permissive,+ ask: ['contains(element.name, "submit")'],+ };++ test("an ask beats allow, in the configuration everybody ships with", () => {+ const decision = evaluateActionPolicy(asking, context());+ expect(decision.source).toBe("ask");+ expect(decision.allowed).toBe(false);+ // Nothing happens until somebody says so.+ expect(decision.forward).toBe(false);+ expect(decision.matched).toBe('contains(element.name, "submit")');+ });++ test("a deny beats an ask, so a forbidden thing is never offered as a question", () => {+ const decision = evaluateActionPolicy(+ { ...asking, deny: ['contains(element.name, "submit")'] },+ context(),+ );+ expect(decision.source).toBe("deny");+ });++ test("an ask rule leaves everything else alone", () => {+ const decision = evaluateActionPolicy(+ asking,+ context({ element: { ref: "e6", role: "input", name: "Quantity" } }),+ );+ expect(decision.source).toBe("allow");+ expect(decision.allowed).toBe(true);+ });++ test("a BROKEN ask expression asks, rather than quietly permitting", () => {+ // Fail-closed, the same way a broken deny denies. A typo in the rule interrupts somebody, which+ // is a nuisance; the alternative is that `allow: ["true"]` waves through exactly the action the+ // rule was written to hold back, and nothing anywhere says so.+ const decision = evaluateActionPolicy(+ { ...permissive, ask: ["this is not ( valid cel"] },+ context(),+ );+ expect(decision.source).toBe("ask");+ expect(decision.forward).toBe(false);+ });++ test("a rule about an element still asks when the element is unknown", () => {+ // `contains` on a missing field throws, and a throwing ask expression asks. An action on+ // something the server could not resolve is exactly the case a person should look at.+ const decision = evaluateActionPolicy(+ asking,+ context({ element: undefined }),+ );+ expect(decision.source).toBe("ask");+ });++ test("dry-run records the question and interrupts nobody", () => {+ // The promise of dry-run is that switching a policy on changes nothing, so an ask there is a note+ // saying where somebody would have been stopped, not a stop.+ const decision = evaluateActionPolicy(+ { ...asking, mode: "dry-run" },+ context(),+ );+ expect(decision.source).toBe("ask");+ expect(decision.allowed).toBe(false);+ expect(decision.forward).toBe(true);+ });++ test("the question names what is about to happen, and not the rule", () => {+ // The rule travels as its own field. A person answering a question about a button should not+ // have to read CEL to work out what they are agreeing to.+ const decision = evaluateActionPolicy(+ asking,+ context({ intent: "activate" }),+ );+ expect(decision.reason).toContain("Submit order");+ expect(decision.reason).toContain("example.com");+ expect(decision.reason).not.toContain("contains(");+ });++ test("a file question names the file rather than whatever page is open", () => {+ const decision = evaluateActionPolicy(+ { ...permissive, ask: ['intent == "write_file"'] },+ context({+ tool: { name: "computer_write_file" },+ intent: "write_file",+ element: undefined,+ file: {+ path: "reports/august.csv",+ name: "august.csv",+ extension: "csv",+ },+ }),+ );+ expect(decision.reason).toContain("reports/august.csv");+ expect(decision.reason).not.toContain("example.com");+ });++ test("a question about a tool call names the tool and the server", () => {+ // The context a tool call is judged in fills the browser fields with empty strings on purpose,+ // so that a rule about element names evaluates to false rather than becoming unevaluable. Read+ // as though a file were present, that produced "The Bot wants to call ." in front of a person,+ // with two buttons under it.+ const decision = evaluateActionPolicy(+ { ...permissive, ask: ['intent == "write_tool"'] },+ {+ tool: { name: "mcp__jira__editJiraIssue" },+ bot: { id: "b" },+ actor: { id: "a" },+ page: { url: "", host: "" },+ element: { ref: "", role: "", name: "", type: "" },+ key: "",+ submit: false,+ file: { path: "", name: "", extension: "" },+ intent: "write_tool",+ mcp: { server: "jira", tool: "editJiraIssue", effect: "write" },+ },+ );+ expect(decision.source).toBe("ask");+ expect(decision.reason).toBe(+ "The Bot wants to call editJiraIssue on jira.",+ );+ });++ test("a refusal of a tool call names it the same way", () => {+ const decision = evaluateActionPolicy(+ { ...permissive, deny: ['mcp.server == "jira"'] },+ {+ tool: { name: "mcp__jira__editJiraIssue" },+ bot: { id: "b" },+ actor: { id: "a" },+ page: { url: "", host: "" },+ element: { ref: "", role: "", name: "", type: "" },+ key: "",+ submit: false,+ file: { path: "", name: "", extension: "" },+ intent: "write_tool",+ mcp: { server: "jira", tool: "editJiraIssue", effect: "write" },+ },+ );+ expect(decision.reason).toContain("editJiraIssue on jira");+ // Nothing about a file, and nothing about whatever page a browser happens to be showing.+ expect(decision.reason).not.toContain("the file");+ });++ test("an empty allow list still refuses what nobody asked about", () => {+ // The floor is unchanged. An ask list is a third answer, not a way of turning default-deny into+ // default-ask: an action no rule mentions is still refused rather than put to somebody.+ const decision = evaluateActionPolicy(+ {+ mode: "enforce",+ deny: [],+ ask: ['tool.name == "computer_write_file"'],+ allow: [],+ },+ context(),+ );+ expect(decision.source).toBe("default");+ expect(decision.allowed).toBe(false);+ });+});+/*** The one attribute that separates the thirtieth click on a button from the first.*@@ -372,6 +623,7 @@ describe("a rule about a Bot repeating itself", () => {const repeating: ActionPolicy = {mode: "enforce",deny: ["repeat.count >= 10"],+ ask: [],allow: ["true"],};diff --git a/server/tests/plugin-store.integration.test.ts b/server/tests/plugin-store.integration.test.tsindex 3349ab8e..38ff4a6a 100644--- a/server/tests/plugin-store.integration.test.ts+++ b/server/tests/plugin-store.integration.test.ts@@ -2,6 +2,7 @@ import { afterAll, beforeAll, describe, expect, test } from "bun:test";import { randomUUID } from "node:crypto";import { and, eq, sql } from "drizzle-orm";import { createAuditStore } from "../src/audit";+import { createApprovalRegistry } from "../src/computer/approvals";import type { ActionPolicy } from "../src/computer/policy";import { createDatabase } from "../src/db/client";import { TEST_POOL } from "./support/database";@@ -12,7 +13,11 @@ import {mcpTools,pluginGrants,} from "../src/db/schema";-import { createPluginStore, PluginRefusedError } from "../src/plugins/store";+import {+ createPluginStore,+ PluginNeedsApprovalError,+ PluginRefusedError,+} from "../src/plugins/store";/*** The two questions a tool call has to pass, and the row each answer leaves behind.@@ -47,6 +52,9 @@ let policy: ActionPolicy = { mode: "enforce", deny: [], allow: ["true"] };*/let serverWasAlreadyConfigured = false;+/** The deployment's one registry, shared with the computer in a real deployment. */+const approvals = createApprovalRegistry();+const store = createPluginStore({database,auditStore: createAuditStore(database),@@ -56,6 +64,7 @@ const store = createPluginStore({},encryptionKey: "x".repeat(44),policy: () => policy,+ approvals,});async function auditRowsFor(targetId: string) {@@ -279,6 +288,131 @@ describe("a boundary written about the browser does not refuse tool calls", () =});});+/**+ * The third answer, which the tool-call path has to give as well as the computer.+ *+ * An ask verdict does not forward, so a call site that only knows yes and no reads it as a refusal+ * and the list an operator wrote to be asked about silently becomes a list of things their Bots may+ * never do. That is the failure the ask list exists to prevent, and it is invisible from a green+ * typecheck: everything still compiles, the audit trail still fills up, and the rows say refused.+ */+describe("a boundary can ask a person about a tool call", () => {+ test("stops the call and asks, rather than refusing it", async () => {+ await store.grant("mcp", ref, holderId, "[email protected]");+ policy = {+ mode: "enforce",+ deny: [],+ ask: ['mcp.server == "atlassian"'],+ allow: ["true"],+ };++ let thrown: unknown;+ try {+ await store.callTool({+ ref,+ args: { query: "open bugs" },+ botId: holderId,+ actorId: "[email protected]",+ });+ } catch (error) {+ thrown = error;+ } finally {+ policy = { mode: "enforce", deny: [], allow: ["true"] };+ }++ expect(thrown).toBeInstanceOf(PluginNeedsApprovalError);+ // A refusal is final and a model told it was refused gives up; this one is meant to come back.+ expect(thrown).not.toBeInstanceOf(PluginRefusedError);+ const asked = thrown as PluginNeedsApprovalError;+ // The question names the tool and the server. It used to read "The Bot wants to call ." here,+ // because the neutral file path this context carries was mistaken for a real one.+ expect(asked.question).toBe(+ "The Bot wants to call searchJiraIssues on atlassian.",+ );+ expect(asked.rule).toBe('mcp.server == "atlassian"');++ const rows = await auditRowsFor(ref);+ const question = rows.filter(+ (row) =>+ row.eventType === "approval.requested" &&+ (row.payload as { approval?: string }).approval === asked.approvalId,+ );+ expect(question).toHaveLength(1);+ // Nothing is recorded as rejected, because nothing was: the turn stopped at the question. A+ // deny rule earlier in this file leaves rejections behind, so what is asserted is that none of+ // them came from the ask list.+ expect(+ rows.some(+ (row) =>+ row.eventType === "mcp.call_rejected" &&+ (row.payload as { decision?: { source?: string } }).decision+ ?.source === "ask",+ ),+ ).toBe(false);+ });++ test("an answer is good for the call it was given for, and not for another", async () => {+ await store.grant("mcp", ref, holderId, "[email protected]");+ policy = {+ mode: "enforce",+ deny: [],+ ask: ['mcp.server == "atlassian"'],+ allow: ["true"],+ };+ const call = {+ ref,+ args: { query: "open bugs" },+ botId: holderId,+ actorId: "[email protected]",+ };++ try {+ const asked = (await store+ .callTool(call)+ .catch((error: unknown) => error)) as PluginNeedsApprovalError;+ approvals.answer(+ asked.approvalId,+ holderId,+ "[email protected]",+ true,+ );++ // The arguments are inside the binding, so a person who allowed one message to one channel has+ // not allowed a different one. This asks again rather than going through.+ const elsewhere = await store+ .callTool({+ ...call,+ args: { query: "everything" },+ approvalId: asked.approvalId,+ })+ .catch((error: unknown) => error);+ expect(elsewhere).toBeInstanceOf(PluginNeedsApprovalError);++ // The call it was actually given for gets past the boundary, which it proves by failing at the+ // network instead of as a question or a refusal.+ const allowed = await store+ .callTool({ ...call, approvalId: asked.approvalId })+ .catch((error: unknown) => error);+ expect(allowed).not.toBeInstanceOf(PluginNeedsApprovalError);+ expect(allowed).not.toBeInstanceOf(PluginRefusedError);++ const rows = await auditRowsFor(ref);+ // The row for the allowed call names who stood behind it, so the trail reads as "somebody was+ // asked and said yes" rather than as an ordinary permission nobody ever questioned.+ expect(+ rows.some(+ (row) =>+ row.eventType === "mcp.call_succeeded" &&+ (row.payload as { decision?: { approvedBy?: string } }).decision+ ?.approvedBy === "[email protected]",+ ),+ ).toBe(true);+ } finally {+ policy = { mode: "enforce", deny: [], allow: ["true"] };+ }+ });+});+describe("the trail can be read by a second reader", () => {test("a refusal names the bot, the server and the tool in queryable JSON", async () => {const [row] = await databasediff --git a/server/tests/policy-durability.integration.test.ts b/server/tests/policy-durability.integration.test.tsindex d767297c..e385963c 100644--- a/server/tests/policy-durability.integration.test.ts+++ b/server/tests/policy-durability.integration.test.ts@@ -38,7 +38,7 @@ describe("a boundary set while running", () => {const before = createPolicyStore(configured, database);await before.load();await before.set(- { mode: "enforce", deny: [rule], allow: ["true"] },+ { mode: "enforce", deny: [rule], ask: [], allow: ["true"] },);@@ -47,6 +47,24 @@ describe("a boundary set while running", () => {expect(after.get().deny).toEqual([rule]);});+ test("the rules that ask a person survive a restart too", async () => {+ // The list that stops and asks has to be as durable as the one that refuses. A boundary that+ // silently stopped asking after a deployment came back up would be indistinguishable, from the+ // trail, from one whose questions were all answered yes.+ const asking = 'intent == "write_file" && !matches(file.path, "^notes/")';+ const before = createPolicyStore(configured, database);+ await before.set({+ mode: "enforce",+ deny: [],+ ask: [asking],+ allow: ["true"],+ });++ const after = createPolicyStore(configured, database);+ expect(await after.load()).toBe("the database");+ expect(after.get().ask).toEqual([asking]);+ });+test("a deployment that never set one gets its configured default", async () => {const store = createPolicyStore(configured, database);expect(await store.load()).toBe("configuration");@@ -55,7 +73,12 @@ describe("a boundary set while running", () => {test("resetting forgets it, so a restart returns to configuration", async () => {const store = createPolicyStore(configured, database);- await store.set({ mode: "enforce", deny: [rule], allow: ["true"] });+ await store.set({+ mode: "enforce",+ deny: [rule],+ ask: [],+ allow: ["true"],+ });await store.reset();// The saved row is removed rather than overwritten, so changing what configuration says then@@ -67,8 +90,18 @@ describe("a boundary set while running", () => {test("setting twice keeps one row and the latest rule", async () => {const store = createPolicyStore(configured, database);- await store.set({ mode: "enforce", deny: ["first"], allow: ["true"] });- await store.set({ mode: "dry-run", deny: ["second"], allow: ["true"] });+ await store.set({+ mode: "enforce",+ deny: ["first"],+ ask: [],+ allow: ["true"],+ });+ await store.set({+ mode: "dry-run",+ deny: ["second"],+ ask: [],+ allow: ["true"],+ });const rows = await database.select().from(actionPolicy);// One boundary per deployment, by construction. Two rows would mean something has to choose.@@ -80,7 +113,7 @@ describe("a boundary set while running", () => {test("records who changed it", async () => {const store = createPolicyStore(configured, database);await store.set(- { mode: "enforce", deny: [rule], allow: ["true"] },+ { mode: "enforce", deny: [rule], ask: [], allow: ["true"] },);@@ -93,7 +126,12 @@ describe("a boundary set while running", () => {// bigger problems than an unsaved rule.const store = createPolicyStore(configured);expect(await store.load()).toBe("configuration");- await store.set({ mode: "enforce", deny: [rule], allow: ["true"] });+ await store.set({+ mode: "enforce",+ deny: [rule],+ ask: [],+ allow: ["true"],+ });expect(store.get().deny).toEqual([rule]);await store.reset();expect(store.get()).toEqual(configured);