open-multi-agent-kit 0.80.7 → 0.90.0

package/examples/extensions/aside-computer-use/observation-snapshot.ts

@@ -0,0 +1,121 @@
+import type { ElementSummary, Observation, ObservationSnapshot, ObservationSnapshotQuality } from "./types.ts";
+
+const FULL_ELEMENT_COVERAGE_COUNT = 5;
+
+export function createObservationSnapshot(
+	observation: Observation,
+	previous?: ObservationSnapshot,
+): ObservationSnapshot {
+	const url = normalizeWhitespace(observation.url);
+	const title = observation.title === undefined ? undefined : normalizeWhitespace(observation.title);
+	const text = observation.text === undefined ? "" : normalizeWhitespace(observation.text);
+	const elements = summarizeElements(observation);
+	const fingerprint = stableHash(
+		stableStringify({
+			url,
+			title: title ?? "",
+			text,
+			elements: elements.map((element) => ({ selector: element.selector, value: element.value })),
+		}),
+	);
+
+	return {
+		id: `obs_${fingerprint.slice(0, 16)}`,
+		fingerprint,
+		url,
+		...(title !== undefined ? { title } : {}),
+		textDigest: stableHash(text),
+		textLength: observation.text?.length ?? 0,
+		elements,
+		quality: createQuality(url, title, text, elements, fingerprint, previous),
+	};
+}
+
+function summarizeElements(observation: Observation): readonly ElementSummary[] {
+	return [...(observation.dom ?? [])]
+		.map((element) => ({
+			selector: normalizeWhitespace(element.selector),
+			value: normalizeWhitespace(element.value),
+		}))
+		.sort((left, right) => {
+			const selectorOrder = left.selector.localeCompare(right.selector);
+			if (selectorOrder !== 0) {
+				return selectorOrder;
+			}
+			return left.value.localeCompare(right.value);
+		})
+		.map((element) => ({
+			selector: element.selector,
+			value: element.value,
+			fingerprint: `el_${stableHash(`${element.selector}\u0000${element.value}`).slice(0, 16)}`,
+		}));
+}
+
+function createQuality(
+	url: string,
+	title: string | undefined,
+	text: string,
+	elements: readonly ElementSummary[],
+	fingerprint: string,
+	previous: ObservationSnapshot | undefined,
+): ObservationSnapshotQuality {
+	const evidenceCount = [url.length > 0, (title ?? "").length > 0, text.length > 0, elements.length > 0].filter(
+		Boolean,
+	).length;
+
+	return {
+		parse: urlParseQuality(url),
+		freshness: previous === undefined || previous.fingerprint !== fingerprint ? 1 : 0,
+		elementCoverage: clamp01(elements.length / FULL_ELEMENT_COVERAGE_COUNT),
+		evidenceCoverage: clamp01(evidenceCount / 4),
+	};
+}
+
+function urlParseQuality(url: string): number {
+	if (url.length === 0) {
+		return 0;
+	}
+	try {
+		new URL(url);
+		return 1;
+	} catch {
+		return 0.5;
+	}
+}
+
+function stableStringify(value: unknown): string {
+	if (value === null || typeof value !== "object") {
+		return JSON.stringify(value) ?? "undefined";
+	}
+	if (Array.isArray(value)) {
+		return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+	}
+
+	const record = value as Readonly<Record<string, unknown>>;
+	const entries = Object.entries(record).sort(([left], [right]) => left.localeCompare(right));
+	return `{${entries.map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue)}`).join(",")}}`;
+}
+
+function normalizeWhitespace(value: string): string {
+	return value.trim().replace(/\s+/gu, " ");
+}
+
+function clamp01(value: number): number {
+	if (!Number.isFinite(value)) {
+		return 0;
+	}
+	return Math.min(1, Math.max(0, value));
+}
+
+function stableHash(value: string): string {
+	return `${stableHashPart(value, 0x811c9dc5)}${stableHashPart(value, 0x45d9f3b)}`;
+}
+
+function stableHashPart(value: string, seed: number): string {
+	let hash = seed;
+	for (let index = 0; index < value.length; index += 1) {
+		hash ^= value.charCodeAt(index);
+		hash = Math.imul(hash, 0x01000193) >>> 0;
+	}
+	return hash.toString(16).padStart(8, "0");
+}

package/examples/extensions/aside-computer-use/package.json

@@ -0,0 +1,16 @@
+{
+	"name": "omk-extension-aside-computer-use",
+	"private": true,
+	"version": "0.1.0",
+	"type": "module",
+	"scripts": {
+		"clean": "echo 'nothing to clean'",
+		"build": "echo 'nothing to build'",
+		"check": "echo 'nothing to check'"
+	},
+	"omk": {
+		"extensions": [
+			"./index.ts"
+		]
+	}
+}

package/examples/extensions/aside-computer-use/policy.ts

@@ -0,0 +1,257 @@
+/**
+ * Policy: load, merge, and validate the OMK-owned Aside policy.
+ *
+ * The policy is OMK's parallel gate layered on top of Aside's own Allow/Ask/Deny
+ * modes. OMK's deny is always final. Defaults use yolo mode with
+ * localhost/test origins only and all critical mutations denied.
+ *
+ * Loading merges (later wins where safe):
+ *   defaults  ←  global ~/.omk/agent/extensions/aside-policy.json
+ *             ←  project <cwd>/.omk/aside-policy.json
+ *
+ * Security floors are restrictive: deny/approval lists are unioned, evidence
+ * defaults cannot be disabled by normal config, and numeric limits are clamped.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { AsideMode } from "./types.ts";
+
+/** Limits + evidence settings bound on every task. */
+export interface PolicyLimits {
+	maxSteps: number;
+	maxRetries: number;
+	maxWallTimeSeconds: number;
+	maxDownloads: number;
+}
+
+export interface PolicyEvidence {
+	captureFinalScreenshot: boolean;
+	recordFinalUrl: boolean;
+	requireDomAssertions: boolean;
+	hashDownloadedFiles: boolean;
+}
+
+export interface PrivilegedR3ActionGrant {
+	readonly kind: string;
+	readonly asideTool?: string;
+	readonly origin: string;
+	readonly selectorOrLabel?: string;
+	readonly expiresAt: string;
+	readonly reason: string;
+}
+
+export interface AsidePolicy {
+	executable: string;
+	transport: "mcp-stdio";
+	defaultMode: AsideMode;
+	allowedOrigins: readonly string[];
+	deniedActions: readonly string[];
+	approvalRequiredActions: readonly string[];
+	/** Compatibility surface. Generic verbs are bounded by the authorizer. */
+	privilegedR3Actions: readonly string[];
+	/** Structured R3 grants with origin, expiry, reason, and optional exact target. */
+	privilegedR3ActionGrants?: readonly PrivilegedR3ActionGrant[];
+	limits: PolicyLimits;
+	evidence: PolicyEvidence;
+	allowReadAnyOrigin: boolean;
+}
+
+export interface PolicyLoadDiagnostic {
+	readonly path: string;
+	readonly source: "global" | "project";
+	readonly message: string;
+}
+
+export interface PolicyLoadResult {
+	readonly policy: AsidePolicy;
+	readonly diagnostics: readonly PolicyLoadDiagnostic[];
+}
+
+export const DEFAULT_POLICY: AsidePolicy = {
+	executable: "aside",
+	transport: "mcp-stdio",
+	defaultMode: "yolo",
+	allowedOrigins: ["http://localhost:*", "https://localhost:*", "http://127.0.0.1:*", "https://127.0.0.1:*"],
+	deniedActions: ["credential_export", "payment", "security_setting_change", "account_deletion", "pay"],
+	approvalRequiredActions: ["submit", "send_message", "publish", "delete", "change_permission"],
+	privilegedR3Actions: [],
+	privilegedR3ActionGrants: [],
+	limits: { maxSteps: 80, maxRetries: 2, maxWallTimeSeconds: 900, maxDownloads: 10 },
+	evidence: {
+		captureFinalScreenshot: true,
+		recordFinalUrl: true,
+		requireDomAssertions: true,
+		hashDownloadedFiles: true,
+	},
+	allowReadAnyOrigin: false,
+};
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function asStringArray(value: unknown): readonly string[] | undefined {
+	if (!Array.isArray(value)) return undefined;
+	return value.filter((v): v is string => typeof v === "string");
+}
+
+function asNonEmptyString(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function unionStringArrays(left: readonly string[], right: readonly string[]): readonly string[] {
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const value of [...left, ...right]) {
+		const trimmed = value.trim();
+		if (!trimmed) continue;
+		const key = trimmed.toLowerCase();
+		if (seen.has(key)) continue;
+		seen.add(key);
+		out.push(trimmed);
+	}
+	return out;
+}
+
+function clampInteger(value: unknown, fallback: number, min: number, max: number): number {
+	const numeric = typeof value === "number" && Number.isFinite(value) ? value : fallback;
+	const integer = Math.trunc(numeric);
+	return Math.min(max, Math.max(min, integer));
+}
+
+function clonePolicy(policy: AsidePolicy): AsidePolicy {
+	return {
+		...policy,
+		allowedOrigins: [...policy.allowedOrigins],
+		deniedActions: [...policy.deniedActions],
+		approvalRequiredActions: [...policy.approvalRequiredActions],
+		privilegedR3Actions: [...policy.privilegedR3Actions],
+		privilegedR3ActionGrants: [...(policy.privilegedR3ActionGrants ?? [])],
+		limits: { ...policy.limits },
+		evidence: { ...policy.evidence },
+	};
+}
+
+function grantKindNeedsTarget(kind: string): boolean {
+	const normalized = kind
+		.trim()
+		.toLowerCase()
+		.replace(/[\s_-]+/g, "_");
+	return normalized === "click" || normalized === "submit";
+}
+
+function asPrivilegedR3ActionGrant(value: unknown): PrivilegedR3ActionGrant | undefined {
+	if (!isObject(value)) return undefined;
+	const kind = asNonEmptyString(value.kind);
+	const origin = asNonEmptyString(value.origin);
+	const expiresAt = asNonEmptyString(value.expiresAt);
+	const reason = asNonEmptyString(value.reason);
+	if (!kind || !origin || !expiresAt || !reason) return undefined;
+	if (Number.isNaN(Date.parse(expiresAt))) return undefined;
+	const selectorOrLabel = asNonEmptyString(value.selectorOrLabel);
+	if (grantKindNeedsTarget(kind) && !selectorOrLabel) return undefined;
+	const asideTool = asNonEmptyString(value.asideTool);
+	return asideTool
+		? { kind, asideTool, origin, selectorOrLabel, expiresAt, reason }
+		: { kind, origin, selectorOrLabel, expiresAt, reason };
+}
+
+function asPrivilegedR3ActionGrantArray(value: unknown): readonly PrivilegedR3ActionGrant[] | undefined {
+	if (!Array.isArray(value)) return undefined;
+	return value
+		.map((entry) => asPrivilegedR3ActionGrant(entry))
+		.filter((entry): entry is PrivilegedR3ActionGrant => entry !== undefined);
+}
+
+/** Merge a partial override into a policy. Unknown fields are ignored. */
+export function mergePolicy(base: AsidePolicy, override: Record<string, unknown>): AsidePolicy {
+	const next = clonePolicy(base);
+	if (typeof override.executable === "string") next.executable = override.executable;
+	if (
+		override.defaultMode === "readonly" ||
+		override.defaultMode === "guard" ||
+		override.defaultMode === "full" ||
+		override.defaultMode === "yolo"
+	) {
+		next.defaultMode = override.defaultMode;
+	}
+	const origins = asStringArray(override.allowedOrigins);
+	if (origins) next.allowedOrigins = origins;
+	const denied = asStringArray(override.deniedActions);
+	if (denied) next.deniedActions = unionStringArrays(base.deniedActions, denied);
+	const approval = asStringArray(override.approvalRequiredActions);
+	if (approval) next.approvalRequiredActions = unionStringArrays(base.approvalRequiredActions, approval);
+	const priv = asStringArray(override.privilegedR3Actions);
+	if (priv) next.privilegedR3Actions = unionStringArrays(base.privilegedR3Actions, priv);
+	const structuredPriv = asPrivilegedR3ActionGrantArray(override.privilegedR3ActionGrants);
+	if (structuredPriv) next.privilegedR3ActionGrants = [...(base.privilegedR3ActionGrants ?? []), ...structuredPriv];
+	if (typeof override.allowReadAnyOrigin === "boolean") next.allowReadAnyOrigin = override.allowReadAnyOrigin;
+	if (isObject(override.limits)) {
+		const l = override.limits;
+		next.limits = {
+			maxSteps: clampInteger(l.maxSteps, base.limits.maxSteps, 1, 500),
+			maxRetries: clampInteger(l.maxRetries, base.limits.maxRetries, 0, 10),
+			maxWallTimeSeconds: clampInteger(l.maxWallTimeSeconds, base.limits.maxWallTimeSeconds, 1, 3600),
+			maxDownloads: clampInteger(l.maxDownloads, base.limits.maxDownloads, 0, 100),
+		};
+	}
+	if (isObject(override.evidence)) {
+		const e = override.evidence;
+		next.evidence = {
+			captureFinalScreenshot: base.evidence.captureFinalScreenshot || e.captureFinalScreenshot === true,
+			recordFinalUrl: base.evidence.recordFinalUrl || e.recordFinalUrl === true,
+			requireDomAssertions: base.evidence.requireDomAssertions || e.requireDomAssertions === true,
+			hashDownloadedFiles: base.evidence.hashDownloadedFiles || e.hashDownloadedFiles === true,
+		};
+	}
+	return next;
+}
+
+function diagnosticMessage(error: unknown): string {
+	return error instanceof Error ? error.message : "unknown policy parse error";
+}
+
+function readJsonIfExists(
+	path: string,
+	source: "global" | "project",
+	diagnostics: PolicyLoadDiagnostic[],
+): Record<string, unknown> | undefined {
+	if (!existsSync(path)) return undefined;
+	try {
+		const raw = readFileSync(path, "utf8");
+		const parsed = JSON.parse(raw);
+		if (isObject(parsed)) return parsed;
+		diagnostics.push({ path, source, message: "policy root must be a JSON object" });
+		return undefined;
+	} catch (error) {
+		diagnostics.push({ path, source, message: diagnosticMessage(error) });
+		return undefined;
+	}
+}
+
+/**
+ * Load the effective policy and non-fatal diagnostics. Malformed files are
+ * skipped so the restrictive default policy remains in force.
+ */
+export function loadPolicyWithDiagnostics(cwd: string, globalDir?: string): PolicyLoadResult {
+	const agentDir = globalDir ?? join(homedir(), ".omk", "agent");
+	const diagnostics: PolicyLoadDiagnostic[] = [];
+	let policy = clonePolicy(DEFAULT_POLICY);
+	const globalFile = readJsonIfExists(join(agentDir, "extensions", "aside-policy.json"), "global", diagnostics);
+	if (globalFile) policy = mergePolicy(policy, globalFile);
+	const projectFile = readJsonIfExists(join(cwd, ".omk", "aside-policy.json"), "project", diagnostics);
+	if (projectFile) policy = mergePolicy(policy, projectFile);
+	return { policy, diagnostics };
+}
+
+/**
+ * Load the effective policy by merging defaults with global + project files.
+ * Missing/unreadable files are skipped and defaults remain.
+ */
+export function loadPolicy(cwd: string, globalDir?: string): AsidePolicy {
+	return loadPolicyWithDiagnostics(cwd, globalDir).policy;
+}

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

@@ -0,0 +1,200 @@
+/**
+ * Risk authorizer — turns a (action, risk band, policy) triple into an
+ * allow / approve / deny decision. This is the core safety gate.
+ *
+ * Policy (always enforced, in this order, first match wins):
+ *   1. Denied actions → DENY (cannot be overridden by mode or allowlist).
+ *   2. Mutating unresolved/non-http/foreign origin → DENY.
+ *   3. R0 respects allowReadAnyOrigin: foreign reads deny unless explicitly enabled.
+ *   4. R3 → DENY unless an exact unexpired privilege matches; then APPROVE.
+ *   5. R2 → APPROVE (human confirmation required before execution).
+ *   6. R1 → ALLOW only on allowed origin and within policy gates.
+ *
+ * Pure module — no I/O.
+ */
+
+import type { PrivilegedR3ActionGrant } from "./policy.ts";
+import type { Authorization, BrowserAction, RiskLevel } from "./types.ts";
+import { originMatches, resolveOrigin } from "./url-origin.ts";
+
+/** Public policy surface consumed by the authorizer (subset of AsidePolicy). */
+export interface AuthorizerPolicy {
+	readonly deniedActions: readonly string[];
+	readonly approvalRequiredActions?: readonly string[];
+	/** Compatibility surface. Only known critical action/tool exact matches are honored. */
+	readonly privilegedR3Actions: readonly string[];
+	readonly privilegedR3ActionGrants?: readonly PrivilegedR3ActionGrant[];
+	readonly allowedOrigins: readonly string[];
+	readonly allowReadAnyOrigin: boolean;
+}
+
+const LEGACY_PRIVILEGEABLE_R3_ACTIONS = new Set([
+	"delete",
+	"payment",
+	"pay",
+	"account_deletion",
+	"credential_export",
+	"security_setting_change",
+]);
+
+function normalizeName(name: string): string {
+	return name
+		.trim()
+		.toLowerCase()
+		.replace(/[\s-]+/g, "_");
+}
+
+function normalizeTarget(value: string): string {
+	return value
+		.trim()
+		.toLowerCase()
+		.replace(/[_\-.]+/g, " ")
+		.replace(/[^a-z0-9]+/g, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+function actionCandidates(action: BrowserAction): readonly string[] {
+	return [action.kind, action.asideTool].filter((value): value is string => typeof value === "string");
+}
+
+function actionDenied(action: BrowserAction, denied: readonly string[]): boolean {
+	const set = new Set(denied.map(normalizeName));
+	return actionCandidates(action).some((candidate) => set.has(normalizeName(candidate)));
+}
+
+function actionRequiresApproval(action: BrowserAction, approvalRequired: readonly string[]): boolean {
+	const set = new Set(approvalRequired.map(normalizeName));
+	return actionCandidates(action).some((candidate) => set.has(normalizeName(candidate)));
+}
+
+function legacyPrivileged(action: BrowserAction, allow: readonly string[]): boolean {
+	const set = new Set(allow.map(normalizeName));
+	return actionCandidates(action).some((candidate) => {
+		const normalized = normalizeName(candidate);
+		return LEGACY_PRIVILEGEABLE_R3_ACTIONS.has(normalized) && set.has(normalized);
+	});
+}
+
+function stringValue(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+
+function targetValues(action: BrowserAction): readonly string[] {
+	const values: string[] = [];
+	if (action.description.trim()) values.push(action.description);
+	const args = action.asideArgs;
+	if (!args) return values.map(normalizeTarget);
+	for (const key of ["selector", "label", "ariaLabel", "accessibleName", "name", "text", "target", "locator"]) {
+		const value = stringValue(args[key]);
+		if (value) values.push(value);
+	}
+	return values.map(normalizeTarget);
+}
+
+function grantExpired(expiresAt: string): boolean {
+	const timestamp = Date.parse(expiresAt);
+	return Number.isNaN(timestamp) || timestamp <= Date.now();
+}
+
+function grantKindNeedsTarget(kind: string): boolean {
+	const normalized = normalizeName(kind);
+	return normalized === "click" || normalized === "submit";
+}
+
+function structuredGrantMatches(
+	action: BrowserAction,
+	targetOrigin: string | undefined,
+	grant: PrivilegedR3ActionGrant,
+): boolean {
+	if (!targetOrigin) return false;
+	if (normalizeName(grant.kind) !== normalizeName(action.kind)) return false;
+	if (grant.asideTool && normalizeName(grant.asideTool) !== normalizeName(action.asideTool ?? "")) return false;
+	if (grantExpired(grant.expiresAt)) return false;
+	if (!originMatches(targetOrigin, [grant.origin])) return false;
+	const expectedTarget = grant.selectorOrLabel ? normalizeTarget(grant.selectorOrLabel) : undefined;
+	if (!expectedTarget) return !grantKindNeedsTarget(grant.kind);
+	return targetValues(action).some((value) => value === expectedTarget);
+}
+
+function structuredPrivileged(
+	action: BrowserAction,
+	targetOrigin: string | undefined,
+	grants: readonly PrivilegedR3ActionGrant[] | undefined,
+): boolean {
+	if (!grants) return false;
+	return grants.some((grant) => structuredGrantMatches(action, targetOrigin, grant));
+}
+
+/**
+ * Decide how the controller should handle an action.
+ *
+ * @example
+ * authorize(action, "R0", policy).decision  // "allow"
+ * authorize(submitAction, "R2", policy).decision // "approve"
+ */
+export function authorize(action: BrowserAction, risk: RiskLevel, policy: AuthorizerPolicy): Authorization {
+	const targetOrigin = resolveOrigin(action.url ?? "");
+
+	// 1. Denied actions are absolute.
+	if (actionDenied(action, policy.deniedActions)) {
+		return { decision: "deny", reason: "action is on the denied list", risk, targetOrigin };
+	}
+
+	const originAllowed = originMatches(targetOrigin, policy.allowedOrigins);
+	const mutating = risk === "R1" || risk === "R2" || risk === "R3";
+
+	// 2. Mutating actions must have a resolved http(s) origin in the allowlist.
+	if (mutating && !originAllowed) {
+		return {
+			decision: "deny",
+			reason: `target origin not in allowedOrigins: ${targetOrigin ?? "(none)"}`,
+			risk,
+			targetOrigin,
+		};
+	}
+
+	// 3. R0 read-only observation follows allowReadAnyOrigin exactly.
+	if (risk === "R0") {
+		if (policy.allowReadAnyOrigin) {
+			return {
+				decision: "allow",
+				reason: "R0 read-only observation with any-origin reads enabled",
+				risk,
+				targetOrigin,
+			};
+		}
+		if (originAllowed) {
+			return { decision: "allow", reason: "R0 read-only observation on allowed origin", risk, targetOrigin };
+		}
+		return {
+			decision: "deny",
+			reason: `R0 read origin not in allowedOrigins: ${targetOrigin ?? "(none)"}`,
+			risk,
+			targetOrigin,
+		};
+	}
+
+	// 4. R3 default-deny unless explicitly and narrowly privileged.
+	if (risk === "R3") {
+		if (
+			structuredPrivileged(action, targetOrigin, policy.privilegedR3ActionGrants) ||
+			legacyPrivileged(action, policy.privilegedR3Actions)
+		) {
+			return { decision: "approve", reason: "privileged R3 action — approval required", risk, targetOrigin };
+		}
+		return { decision: "deny", reason: "R3 critical mutation denied by default", risk, targetOrigin };
+	}
+
+	if (actionRequiresApproval(action, policy.approvalRequiredActions ?? [])) {
+		return { decision: "approve", reason: "action requires approval by policy", risk, targetOrigin };
+	}
+
+	// 5. R2 needs human approval.
+	if (risk === "R2") {
+		return { decision: "approve", reason: "R2 external mutation — approval required", risk, targetOrigin };
+	}
+
+	// 6. R1: origin gate already passed, so allow.
+	return { decision: "allow", reason: "R1 on allowed origin", risk, targetOrigin };
+}