open-multi-agent-kit 0.80.6 → 0.80.8

package/examples/extensions/aside-computer-use/risk-classifier.ts

@@ -0,0 +1,205 @@
+/**
+ * Risk classifier — maps a browser action to a risk band (R0..R3).
+ *
+ * Intent-based: the action's facade `kind`, description, underlying Aside tool,
+ * and stringifiable `asideArgs` metadata all contribute signals. Risk is the max
+ * across signals; critical signals always win.
+ *
+ * Pure module — no I/O.
+ */
+
+import type { BrowserAction, RiskLevel } from "./types.ts";
+
+/** Verbs that force an otherwise-lower action into a critical band. */
+const R3_PHRASES = [
+	"pay",
+	"payment",
+	"checkout",
+	"purchase",
+	"delete account",
+	"account deletion",
+	"close account",
+	"transfer fund",
+	"transfer funds",
+	"wire transfer",
+	"2fa",
+	"two factor",
+	"mfa",
+	"disable security",
+	"security setting",
+	"security settings",
+	"password",
+	"passkey",
+	"credential",
+	"credential export",
+	"api key",
+	"copy api key",
+	"export api key",
+	"private key",
+	"seed phrase",
+	"recovery phrase",
+	"secret token",
+	"access token",
+	"connect wallet",
+	"wallet connect",
+	"connect account",
+	"oauth grant",
+	"grant oauth",
+	"broad permission grant",
+	"install extension",
+	"install app",
+];
+
+const R2_PHRASES = [
+	"submit",
+	"send",
+	"post",
+	"publish",
+	"create issue",
+	"open issue",
+	"comment",
+	"reply",
+	"merge",
+	"deploy",
+	"approve",
+	"grant",
+	"change permission",
+	"invite",
+	"share",
+	"follow",
+	"like",
+	"rate",
+	"review submit",
+	"enter in form",
+	"enter form",
+	"oauth",
+	"sign in with",
+	"authorize app",
+];
+
+const SENSITIVE_INPUT_PHRASES = [
+	"password",
+	"passcode",
+	"passkey",
+	"2fa",
+	"two factor",
+	"mfa",
+	"otp",
+	"one time password",
+	"token",
+	"api key",
+	"private key",
+	"secret",
+	"seed phrase",
+	"recovery phrase",
+];
+
+/** Kind → baseline risk band. Unknown kinds default to R1 (treat as mutating-ish, unknown). */
+const KIND_BAND: Readonly<Record<string, RiskLevel>> = {
+	open_page: "R1",
+	navigate: "R1",
+	read_text: "R0",
+	read_dom: "R0",
+	inspect: "R0",
+	screenshot: "R0",
+	take_screenshot: "R0",
+	console_log: "R0",
+	wait: "R0",
+	download: "R1",
+	fill_form: "R1",
+	type: "R1",
+	input: "R1",
+	press_key: "R1",
+	key_press: "R1",
+	click_locator: "R1",
+	click: "R1",
+	scroll: "R0",
+	hover: "R0",
+	submit: "R2",
+	send_message: "R2",
+	create_issue: "R2",
+	publish: "R2",
+	comment: "R2",
+	change_permission: "R2",
+	delete: "R3",
+	payment: "R3",
+	pay: "R3",
+	account_deletion: "R3",
+	security_setting_change: "R3",
+	credential_export: "R3",
+};
+
+const BAND_ORDER: readonly RiskLevel[] = ["R0", "R1", "R2", "R3"];
+
+function maxBand(a: RiskLevel, b: RiskLevel): RiskLevel {
+	return BAND_ORDER.indexOf(a) >= BAND_ORDER.indexOf(b) ? a : b;
+}
+
+function stringifyAsideArgs(args: Readonly<Record<string, unknown>> | undefined): string {
+	if (!args) return "";
+	try {
+		return JSON.stringify(args, (_key: string, value: unknown) =>
+			typeof value === "bigint" ? value.toString() : value,
+		);
+	} catch {
+		return Object.keys(args).join(" ");
+	}
+}
+
+function normalizeText(value: string): string {
+	return value
+		.replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+		.toLowerCase()
+		.replace(/[_\-.]+/g, " ")
+		.replace(/[^a-z0-9]+/g, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+function normalizeKind(value: string): string {
+	return normalizeText(value).replace(/\s+/g, "_");
+}
+
+function containsPhrase(normalizedText: string, phrase: string): boolean {
+	const normalizedPhrase = normalizeText(phrase);
+	return ` ${normalizedText} `.includes(` ${normalizedPhrase} `);
+}
+
+function containsAnyPhrase(normalizedText: string, phrases: readonly string[]): boolean {
+	return phrases.some((phrase) => containsPhrase(normalizedText, phrase));
+}
+
+function isSensitiveTyping(action: BrowserAction, normalizedHaystack: string): boolean {
+	const kind = normalizeKind(action.kind);
+	if (kind !== "type" && kind !== "fill_form" && kind !== "input") return false;
+	return containsAnyPhrase(normalizedHaystack, SENSITIVE_INPUT_PHRASES);
+}
+
+function isEnterInForm(normalizedHaystack: string): boolean {
+	if (containsPhrase(normalizedHaystack, "enter in form") || containsPhrase(normalizedHaystack, "enter form"))
+		return true;
+	return (
+		(containsPhrase(normalizedHaystack, "key enter") || containsPhrase(normalizedHaystack, "press enter")) &&
+		(containsPhrase(normalizedHaystack, "form true") || containsPhrase(normalizedHaystack, "input form"))
+	);
+}
+
+/**
+ * Classify a browser action into a risk band.
+ *
+ * @example
+ * classifyRisk({ kind: "screenshot", description: "" })          // "R0"
+ * classifyRisk({ kind: "submit", description: "post comment" })   // "R2"
+ * classifyRisk({ kind: "click", description: "Pay now" })         // "R3"
+ */
+export function classifyRisk(action: BrowserAction): RiskLevel {
+	const baseline = KIND_BAND[normalizeKind(action.kind)] ?? "R1";
+	const haystack = normalizeText(
+		`${action.kind} ${action.description ?? ""} ${action.asideTool ?? ""} ${stringifyAsideArgs(action.asideArgs)}`,
+	);
+	if (isSensitiveTyping(action, haystack)) return "R3";
+	if (containsAnyPhrase(haystack, R3_PHRASES)) return "R3";
+	let risk = baseline;
+	if (containsAnyPhrase(haystack, R2_PHRASES) || isEnterInForm(haystack)) risk = maxBand(risk, "R2");
+	return risk;
+}

package/examples/extensions/aside-computer-use/schema-fingerprint.ts

@@ -0,0 +1,80 @@
+/**
+ * Stable schema fingerprint for MCP tool inputSchema drift detection.
+ *
+ * Aside ships updates; a tool named the same way may later accept broader
+ * arguments. Fingerprinting lets OMK detect that the schema changed and refuse
+ * to auto-promote a previously-approved tool without re-review.
+ *
+ * Deterministic canonicalization: arrays preserve order, object keys are sorted
+ * recursively, cycles throw, and non-JSON schema values throw. The digest is a
+ * versioned SHA-256 string so future canonicalization changes can use a new
+ * prefix without conflating approvals.
+ *
+ * Pure module.
+ */
+
+import { createHash } from "node:crypto";
+
+const SCHEMA_FINGERPRINT_PREFIX = "aside-schema-v1:";
+
+function assertJsonObject(value: object): void {
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) {
+		throw new TypeError("non-json schema value: object prototype is not plain JSON");
+	}
+}
+
+/** Deterministic canonicalization of a JSON value. */
+function canonicalize(value: unknown, ancestors: Set<object>): string {
+	if (value === null) return "null";
+	if (typeof value === "string") return JSON.stringify(value);
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new TypeError("non-json schema value: non-finite number");
+		return `n:${value}`;
+	}
+	if (typeof value === "boolean") return value ? "true" : "false";
+	if (
+		typeof value === "undefined" ||
+		typeof value === "function" ||
+		typeof value === "symbol" ||
+		typeof value === "bigint"
+	) {
+		throw new TypeError(`non-json schema value: ${typeof value}`);
+	}
+	if (typeof value === "object") {
+		if (ancestors.has(value)) throw new TypeError("schema contains a cycle");
+		ancestors.add(value);
+		try {
+			if (Array.isArray(value)) {
+				return `[${value.map((item) => canonicalize(item, ancestors)).join(",")}]`;
+			}
+			assertJsonObject(value);
+			const obj = value as Record<string, unknown>;
+			const keys = Object.keys(obj).sort();
+			const body = keys.map((key) => `${JSON.stringify(key)}:${canonicalize(obj[key], ancestors)}`).join(",");
+			return `{${body}}`;
+		} finally {
+			ancestors.delete(value);
+		}
+	}
+	throw new TypeError("non-json schema value: unsupported value");
+}
+
+/**
+ * Return a versioned SHA-256 fingerprint for a tool inputSchema.
+ * Two equal fingerprints mean structurally identical schemas under v1
+ * canonicalization.
+ *
+ * @example
+ * schemaFingerprint({ type: "object", properties: { url: { type: "string" } } })
+ */
+export function schemaFingerprint(schema: Readonly<Record<string, unknown>>): string {
+	const digest = createHash("sha256").update(canonicalize(schema, new Set<object>()), "utf8").digest("hex");
+	return `${SCHEMA_FINGERPRINT_PREFIX}${digest}`;
+}
+
+/** Compare a live fingerprint to an approved one. */
+export function schemaDrift(live: string, approved: string | undefined): boolean {
+	if (!approved) return true; // nothing approved yet → drift by definition
+	return live !== approved;
+}

package/examples/extensions/aside-computer-use/session-binding.ts

@@ -0,0 +1,161 @@
+/**
+ * Session binding store + per-browser-profile mutation mutex.
+ *
+ * A single browser profile (cookies, tabs, form state) must not receive two
+ * mutating actions concurrently, or tabs/navigation/forms can corrupt each
+ * other. Read-only observation on a separate tab may run in parallel.
+ *
+ * The mutex is keyed on `accountId:browserProfileId` and provides FIFO grants
+ * within this process. Pending waiters can be aborted, timed out, or rejected
+ * by clear() during shutdown.
+ */
+
+export interface OMKSessionBinding {
+	readonly omkSessionId: string;
+	asideProcessId?: number;
+	asideSessionId?: string;
+	accountId: string;
+	browserProfileId: string;
+	activeTabIds: string[];
+	permissionMode: string;
+	allowedOrigins: readonly string[];
+	evidenceDirectory: string;
+	readonly createdAt: number;
+	lastActivityAt: number;
+}
+
+export interface MutationLockOptions {
+	readonly waitTimeoutMs?: number;
+	readonly signal?: AbortSignal;
+}
+
+type Release = () => void;
+
+interface LockWaiter {
+	readonly resolve: (release: Release) => void;
+	readonly reject: (error: Error) => void;
+	readonly signal?: AbortSignal;
+	timer: NodeJS.Timeout | undefined;
+	onAbort: (() => void) | undefined;
+	settled: boolean;
+}
+
+interface LockState {
+	active: boolean;
+	readonly queue: LockWaiter[];
+}
+
+export class SessionBindingStore {
+	private readonly bindings = new Map<string, OMKSessionBinding>();
+	private readonly locks = new Map<string, LockState>();
+
+	bind(binding: OMKSessionBinding): void {
+		this.bindings.set(binding.omkSessionId, binding);
+	}
+
+	get(omkSessionId: string): OMKSessionBinding | undefined {
+		return this.bindings.get(omkSessionId);
+	}
+
+	update(omkSessionId: string, patch: Partial<OMKSessionBinding>): OMKSessionBinding | undefined {
+		const current = this.bindings.get(omkSessionId);
+		if (!current) return undefined;
+		const next: OMKSessionBinding = { ...current, ...patch, createdAt: current.createdAt };
+		this.bindings.set(omkSessionId, next);
+		return next;
+	}
+
+	/** Acquire the mutation lock for a profile; resolves the release function. */
+	async acquireMutationLock(
+		accountId: string,
+		profileId: string,
+		options: MutationLockOptions = {},
+	): Promise<Release> {
+		const key = `${accountId}:${profileId}`;
+		if (options.signal?.aborted) return Promise.reject(new Error(`mutation lock wait aborted: ${key}`));
+		const state = this.getLockState(key);
+		if (!state.active) {
+			state.active = true;
+			return this.createRelease(key, state);
+		}
+		return new Promise<Release>((resolve, reject) => {
+			const waiter: LockWaiter = {
+				resolve,
+				reject,
+				signal: options.signal,
+				timer: undefined,
+				onAbort: undefined,
+				settled: false,
+			};
+			waiter.onAbort = () => this.rejectWaiter(key, state, waiter, new Error(`mutation lock wait aborted: ${key}`));
+			options.signal?.addEventListener("abort", waiter.onAbort, { once: true });
+			if (options.waitTimeoutMs !== undefined) {
+				waiter.timer = setTimeout(() => {
+					this.rejectWaiter(key, state, waiter, new Error(`mutation lock wait timed out: ${key}`));
+				}, options.waitTimeoutMs);
+				waiter.timer.unref?.();
+			}
+			state.queue.push(waiter);
+		});
+	}
+
+	/** Release all bindings + reject pending lock waiters (shutdown). */
+	clear(): void {
+		this.bindings.clear();
+		for (const [key, state] of this.locks) {
+			for (const waiter of state.queue.splice(0)) {
+				this.rejectWaiter(key, state, waiter, new Error(`mutation lock queue cleared: ${key}`));
+			}
+		}
+		this.locks.clear();
+	}
+
+	private getLockState(key: string): LockState {
+		const existing = this.locks.get(key);
+		if (existing) return existing;
+		const state: LockState = { active: false, queue: [] };
+		this.locks.set(key, state);
+		return state;
+	}
+
+	private createRelease(key: string, state: LockState): Release {
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			if (this.locks.get(key) !== state) return;
+			this.grantNext(key, state);
+		};
+	}
+
+	private grantNext(key: string, state: LockState): void {
+		while (state.queue.length > 0) {
+			const waiter = state.queue.shift();
+			if (!waiter || waiter.settled) continue;
+			waiter.settled = true;
+			this.cleanupWaiter(waiter);
+			state.active = true;
+			waiter.resolve(this.createRelease(key, state));
+			return;
+		}
+		state.active = false;
+		this.locks.delete(key);
+	}
+
+	private rejectWaiter(key: string, state: LockState, waiter: LockWaiter, error: Error): void {
+		if (waiter.settled) return;
+		waiter.settled = true;
+		this.cleanupWaiter(waiter);
+		const index = state.queue.indexOf(waiter);
+		if (index !== -1) state.queue.splice(index, 1);
+		waiter.reject(error);
+		if (!state.active && state.queue.length === 0 && this.locks.get(key) === state) this.locks.delete(key);
+	}
+
+	private cleanupWaiter(waiter: LockWaiter): void {
+		if (waiter.timer) clearTimeout(waiter.timer);
+		if (waiter.signal && waiter.onAbort) waiter.signal.removeEventListener("abort", waiter.onAbort);
+		waiter.timer = undefined;
+		waiter.onAbort = undefined;
+	}
+}