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.
/**
* What would this policy have decided, about actions that already happened?
*
* A boundary is written blind: an administrator types a CEL rule, saves it, and finds out what it
* actually matches from the refusals it produces. The trail already holds everything needed to do
* better — every computer action is recorded with the same facts the gateway judged it on — so a
* candidate policy can be replayed over that history and answer, before it is saved, "these are the
* actions you would have decided differently."
*
* Replay, not simulation: the context handed to `evaluateActionPolicy` here is rebuilt from the
* audit row exactly as the gateway built it at decision time, through the same helpers. A rule that
* behaves one way here and another way live would make this feature worse than absent.
*/
import type { AuditEvent, AuditInitiator } from "../audit";
import { describeFile, hostOf, intentOf } from "./gateway";
import {
type ActionPolicy,
evaluateActionPolicy,
type PolicyContext,
policyInitiator,
} from "./policy";
/**
* The event types that record a policy DECISION about a computer action. In one place, for the query.
*
* Not `computer.action_failed`: the gateway writes that beside the decision row when a permitted
* action is attempted and does not succeed, so it is a second row for an action already recorded
* here, not a decision of its own. Replaying it too would score the action twice — see
* {@link dryRunAgainstHistory}.
*/
export const REPLAYABLE_EVENT_TYPES = [
"computer.action_allowed",
"computer.action_refused",
] as const;
/** One action the candidate policy would have decided differently. */
export type DryRunChange = {
id: string;
createdAt: string;
action: string;
bot: string;
page: string;
/** For a person reading the list; absent on file and command actions. */
element: { role: string; name: string } | null;
command: string | null;
file: string | null;
/** What the policy in force decided, from the action's decision row. */
was: "allowed" | "refused";
would: "allowed" | "refused";
/** The candidate rule that decided it, or null for the default refusal. */
rule: string | null;
reason: string;
};
export type DryRunReport = {
/** Rows replayed. Bounded by what the caller asked the trail for, and says so. */
scanned: number;
wouldRefuse: number;
wouldAllow: number;
unchanged: number;
/** Capped; the counts above are over everything scanned. */
changes: DryRunChange[];
};
/** Changes returned in full detail. The counts still cover every scanned row. */
const CHANGES_CAP = 50;
/**
* The gateway's context, rebuilt from what it recorded.
*
* Field for field against the context the gateway constructs: absent browser facts become neutral
* empty strings rather than missing keys, because cel-js throws on an unbound identifier and a
* throw fails closed — a replay that refused everything the moment a rule named `command` would
* report a boundary far stricter than the one being proposed. `intent` is not stored on the row; it
* is derived from the tool and key here exactly as the gateway derives it at decision time.
*
* Null when the row does not carry enough to replay — a row from before a field existed, or a
* hand-inserted one. Skipped rather than guessed at.
*/
/**
* The initiator an audit payload carries, narrowed back to the union.
*
* Its own reader rather than the one in `callback-token.ts`: that one narrows a value this
* deployment signed and can trust the shape of, and this one reads a stored row that may predate the
* field, have been written by an older version, or been inserted by hand. Anything it does not
* recognise reads as absent, and `policyInitiator` turns that into a person.
*/
function initiatorFromPayload(value: unknown): AuditInitiator | undefined {
if (!value || typeof value !== "object") return undefined;
const kind = (value as { kind?: unknown }).kind;
if (kind === "person" || kind === "deployment") return { kind };
if (kind !== "routine" && kind !== "handoff") return undefined;
const id = (value as { id?: unknown }).id;
return typeof id === "string" && id ? { kind, id } : undefined;
}
export function contextFromAuditPayload(
payload: Record<string, unknown>,
): PolicyContext | null {
const action = payload.action;
const bot = payload.bot;
if (typeof action !== "string" || typeof bot !== "string") return null;
const text = (value: unknown): string =>
typeof value === "string" ? value : "";
const page = text(payload.page);
const key = text(payload.key);
const file = text(payload.file);
// Stored as an object on element actions, absent on file and command actions, and the literal
// sentence "not in the current snapshot" when the server could not identify the element. Only the
// object shape carries fields a rule can match; the other two replay as the neutral element.
const element =
payload.element && typeof payload.element === "object"
? (payload.element as Record<string, unknown>)
: null;
const intent = intentOf(action, key || undefined);
return {
tool: { name: action },
bot: { id: bot },
actor: { id: text(payload.actor) },
page: { url: page, host: hostOf(page) },
...(intent ? { intent } : {}),
key,
element: {
// The ref travels beside the element on the row, not inside it.
ref: text(payload.ref),
role: text(element?.role),
name: text(element?.name),
type: text(element?.type),
},
file: file ? describeFile(file) : { path: "", name: "", extension: "" },
command: text(payload.command),
mcp: { server: "", tool: "", effect: "" },
/*
* Read off the row when it is there, neutral when it is not. The rows this replays are computer
* actions, which carry no initiator today, so in practice this is a person — but reading it
* rather than hardcoding it means a replay stays honest the day those rows do carry one, and a
* rule being tested against history is judged on what actually happened.
*/
initiator: policyInitiator(initiatorFromPayload(payload.initiator)),
};
}
/**
* Replay judged actions under a candidate policy and report what changes.
*
* "Was" comes from the row's event type, which records what the policy in force decided — including
* a dry-run policy's refusals, which were recorded and then carried out. That is the honest
* baseline: the question this answers is "what would decide differently than was decided", not
* "what would run differently than ran".
*
* A `computer.action_failed` row is skipped rather than scored. It is the outcome of an action whose
* decision row is already in this history, so counting it would score that action twice — and worse,
* a dry-run policy carries a refused action out, so a refused-then-failed action would arrive as a
* decision row that says "refused" and a failure row that reads as "allowed", inventing a change no
* policy made. The decision is on the decision row; the failure row only says it did not finish.
* Callers should exclude it from the query too ({@link REPLAYABLE_EVENT_TYPES}); this guards the
* function against being handed one regardless.
*/
export function dryRunAgainstHistory(
policy: ActionPolicy,
events: AuditEvent[],
): DryRunReport {
const report: DryRunReport = {
scanned: 0,
wouldRefuse: 0,
wouldAllow: 0,
unchanged: 0,
changes: [],
};
for (const event of events) {
// Both carry a decision row already in this history, so scoring the outcome row would count the
// action twice; a stop is skipped for the same reason a failure is.
if (
event.eventType === "computer.action_failed" ||
event.eventType === "computer.action_stopped"
)
continue;
const context = contextFromAuditPayload(event.payload);
if (!context) continue;
report.scanned += 1;
const was =
event.eventType === "computer.action_refused" ? "refused" : "allowed";
const decision = evaluateActionPolicy(policy, context);
const would = decision.allowed ? "allowed" : "refused";
if (was === would) {
report.unchanged += 1;
continue;
}
if (would === "refused") report.wouldRefuse += 1;
else report.wouldAllow += 1;
if (report.changes.length >= CHANGES_CAP) continue;
report.changes.push({
id: event.id,
createdAt: event.createdAt,
action: context.tool.name,
bot: context.bot.id,
page: context.page.url,
element:
context.element?.role || context.element?.name
? {
role: context.element.role,
name: context.element.name,
}
: null,
command: context.command || null,
file: context.file?.path || null,
was,
would,
rule: decision.matched,
reason: decision.reason,
});
}
return report;
}