open-multi-agent-kit 0.78.0

package/dist/util/worktree.js

@@ -0,0 +1,165 @@
+import { isAbsolute, join, relative, resolve } from "path";
+import { mkdir, readdir, access, lstat, realpath, rm } from "fs/promises";
+import { runShell } from "./shell.js";
+import { getProjectRoot } from "./fs.js";
+const WORKTREE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+export function validateWorktreeId(value, label = "worktree id") {
+    if (!WORKTREE_ID_PATTERN.test(value) || value === "." || value === "..") {
+        throw new Error(`Invalid ${label}`);
+    }
+    return value;
+}
+export function getWorktreesRoot() {
+    return resolve(getProjectRoot(), ".omk", "worktrees");
+}
+function isPathContained(parent, child) {
+    const rel = relative(parent, child);
+    return rel.length > 0 && !rel.startsWith("..") && !isAbsolute(rel);
+}
+async function assertNoSymlinkInExistingPath(root, target) {
+    const rel = relative(root, target);
+    const parts = rel.split(/[\\/]+/).filter(Boolean);
+    let current = root;
+    for (const part of parts) {
+        current = join(current, part);
+        try {
+            const entry = await lstat(current);
+            if (entry.isSymbolicLink()) {
+                throw new Error(`Refusing symlink in worktree path: ${current}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                return;
+            throw error;
+        }
+    }
+}
+export async function resolveSafeWorktreePath(candidatePath) {
+    const root = getWorktreesRoot();
+    const resolved = resolve(candidatePath);
+    if (!isPathContained(root, resolved)) {
+        throw new Error(`Worktree path escapes ${root}`);
+    }
+    try {
+        const rootEntry = await lstat(root);
+        if (rootEntry.isSymbolicLink()) {
+            throw new Error(`Refusing symlink worktrees root: ${root}`);
+        }
+        const [realRoot, realTarget] = await Promise.all([
+            realpath(root),
+            realpath(resolved).catch((error) => {
+                if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                    return resolved;
+                throw error;
+            }),
+        ]);
+        if (realTarget !== resolved && !isPathContained(realRoot, realTarget)) {
+            throw new Error(`Worktree path resolves outside ${root}`);
+        }
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+            throw error;
+    }
+    await assertNoSymlinkInExistingPath(root, resolved);
+    return resolved;
+}
+function buildWorktreePath(runId, leafId) {
+    return join(getWorktreesRoot(), validateWorktreeId(runId, "runId"), validateWorktreeId(leafId, "nodeId"));
+}
+export async function createWorktree(runId, nodeId) {
+    const worktreePath = await resolveSafeWorktreePath(buildWorktreePath(runId, nodeId));
+    await mkdir(worktreePath, { recursive: true });
+    const branchName = `work/${runId}/${nodeId}`;
+    const result = await runShell("git", ["worktree", "add", worktreePath, "-b", branchName], {
+        cwd: getProjectRoot(),
+        timeout: 15000,
+    });
+    if (result.failed) {
+        // If branch already exists, try using the existing branch
+        const retry = await runShell("git", ["worktree", "add", worktreePath, branchName], {
+            cwd: getProjectRoot(),
+            timeout: 15000,
+        });
+        if (retry.failed) {
+            throw new Error(`Failed to create worktree at ${worktreePath}: ${retry.stderr}`);
+        }
+    }
+    return worktreePath;
+}
+export async function removeWorktreeDirectory(path) {
+    const worktreePath = await resolveSafeWorktreePath(path);
+    await rm(worktreePath, { recursive: true, force: true });
+}
+export async function removeWorktree(path) {
+    const worktreePath = await resolveSafeWorktreePath(path);
+    const result = await runShell("git", ["worktree", "remove", "--force", worktreePath], { timeout: 15000 });
+    if (result.failed) {
+        throw new Error(`Failed to remove worktree at ${worktreePath}: ${result.stderr}`);
+    }
+}
+export async function listWorktrees(runId) {
+    const worktreesDir = await resolveSafeWorktreePath(join(getWorktreesRoot(), validateWorktreeId(runId, "runId")));
+    try {
+        await access(worktreesDir);
+    }
+    catch {
+        return [];
+    }
+    const entries = await readdir(worktreesDir, { withFileTypes: true });
+    return entries
+        .filter((e) => e.isDirectory() && WORKTREE_ID_PATTERN.test(e.name))
+        .map((e) => join(worktreesDir, e.name));
+}
+export async function createAttemptWorktree(runId, nodeId, attempt) {
+    validateWorktreeId(runId, "runId");
+    validateWorktreeId(nodeId, "nodeId");
+    if (!Number.isInteger(attempt) || attempt < 0 || attempt > 999) {
+        throw new Error(`Invalid attempt`);
+    }
+    const attemptId = attempt.toString().padStart(3, "0");
+    const leafId = `attempt-${nodeId}-${attemptId}`;
+    const worktreePath = await resolveSafeWorktreePath(buildWorktreePath(runId, leafId));
+    await mkdir(worktreePath, { recursive: true });
+    const branchName = `work/${runId}/${nodeId}/${attemptId}`;
+    const result = await runShell("git", ["worktree", "add", worktreePath, "-b", branchName], {
+        cwd: getProjectRoot(),
+        timeout: 15000,
+    });
+    if (result.failed) {
+        const retry = await runShell("git", ["worktree", "add", worktreePath, branchName], {
+            cwd: getProjectRoot(),
+            timeout: 15000,
+        });
+        if (retry.failed) {
+            throw new Error(`Failed to create worktree at ${worktreePath}: ${retry.stderr}`);
+        }
+    }
+    return worktreePath;
+}
+export async function removeAttemptWorktree(runId, nodeId, attempt) {
+    validateWorktreeId(runId, "runId");
+    validateWorktreeId(nodeId, "nodeId");
+    if (!Number.isInteger(attempt) || attempt < 0 || attempt > 999) {
+        throw new Error(`Invalid attempt`);
+    }
+    const attemptId = attempt.toString().padStart(3, "0");
+    const worktreePath = join(getWorktreesRoot(), runId, `attempt-${nodeId}-${attemptId}`);
+    await removeWorktree(worktreePath);
+}
+export async function listAttemptWorktrees(runId, nodeId) {
+    validateWorktreeId(nodeId, "nodeId");
+    const worktreesDir = await resolveSafeWorktreePath(join(getWorktreesRoot(), validateWorktreeId(runId, "runId")));
+    try {
+        await access(worktreesDir);
+    }
+    catch {
+        return [];
+    }
+    const prefix = `attempt-${nodeId}-`;
+    const entries = await readdir(worktreesDir, { withFileTypes: true });
+    return entries
+        .filter((e) => e.isDirectory() && e.name.startsWith(prefix) && WORKTREE_ID_PATTERN.test(e.name))
+        .map((e) => join(worktreesDir, e.name));
+}

package/dist/ux/explain-loop-decision.d.ts

@@ -0,0 +1,4 @@
+import type { EnvMergeTraceEntry } from "../contracts/worker-context.js";
+import type { LoopDecision } from "../orchestration/loop-state.js";
+export declare function explainLoopDecision(decision: LoopDecision): string[];
+export declare function explainEnvMergeTrace(trace: readonly EnvMergeTraceEntry[]): string[];

package/dist/ux/explain-loop-decision.js

@@ -0,0 +1,55 @@
+export function explainLoopDecision(decision) {
+    if (decision.risk.deadlock > 0) {
+        return [
+            "OMK paused because pending tasks cannot run yet.",
+            `Pending: ${formatList(decision.nodeSets.pending)}`,
+            `Blocked: ${formatList(decision.nodeSets.blocked)}`,
+            `Failed: ${formatList(decision.nodeSets.failed)}`,
+            `Suggested next step: ${decision.action === "replan" ? "replan remaining work" : decision.action}`,
+        ];
+    }
+    if (!decision.progress.madeProgress) {
+        return [
+            "OMK detected no progress in the last loop window.",
+            "This usually means a dependency is blocked, a required artifact is missing, or approval is needed.",
+            `Current action: ${decision.action}`,
+            `Reason: ${decision.reason}`,
+        ];
+    }
+    if (decision.failedNodes.length > 0 || decision.blockedNodes.length > 0) {
+        return [
+            "OMK found work that needs repair or replanning.",
+            `Failed: ${formatList(decision.failedNodes)}`,
+            `Blocked: ${formatList(decision.blockedNodes)}`,
+            `Reason: ${decision.reason}`,
+        ];
+    }
+    if (decision.action === "close") {
+        return [
+            "OMK is done.",
+            "All required tasks and evidence gates are closed.",
+        ];
+    }
+    return [`OMK selected action: ${decision.action}`, decision.reason];
+}
+export function explainEnvMergeTrace(trace) {
+    const preserved = trace.filter((entry) => entry.action === "preserve-non-empty").map((entry) => entry.key);
+    const dropped = trace.filter((entry) => entry.action === "drop-empty").map((entry) => entry.key);
+    const overwritten = trace.filter((entry) => entry.action === "overwrite").map((entry) => entry.key);
+    const lines = ["OMK protected your runtime environment."];
+    if (preserved.length > 0)
+        lines.push(`Preserved non-empty keys: ${formatList(unique(preserved))}`);
+    if (dropped.length > 0)
+        lines.push(`Ignored empty keys: ${formatList(unique(dropped))}`);
+    if (overwritten.length > 0)
+        lines.push(`Overwritten keys: ${formatList(unique(overwritten))}`);
+    if (lines.length === 1)
+        lines.push("No suspicious env overwrite was detected.");
+    return lines;
+}
+function formatList(values) {
+    return values.length > 0 ? values.join(", ") : "none";
+}
+function unique(values) {
+    return [...new Set(values)].sort();
+}

package/dist/ux/intent-router.d.ts

@@ -0,0 +1,15 @@
+import type { OmkUxMode } from "./natural-entrypoint.js";
+export type OmkUxIntent = "chat" | "explain" | "plan" | "edit" | "fix" | "review" | "test" | "parallel" | "diagnose";
+export interface RepoSignals {
+    hasUncommittedChanges?: boolean;
+    largeRepo?: boolean;
+}
+export interface RoutedPrompt {
+    intent: OmkUxIntent;
+    mode: OmkUxMode;
+    safety: "read-only" | "ask-before-edit" | "workspace-write";
+    execution: "plan-only" | "guided" | "auto";
+    reason: string;
+}
+export declare function routeNaturalPrompt(prompt: string, repoSignals?: RepoSignals, requestedMode?: OmkUxMode): RoutedPrompt;
+export declare function classifyPromptIntent(prompt: string, repoSignals?: RepoSignals): OmkUxIntent;

package/dist/ux/intent-router.js

@@ -0,0 +1,64 @@
+export function routeNaturalPrompt(prompt, repoSignals = {}, requestedMode) {
+    const intent = classifyPromptIntent(prompt, repoSignals);
+    const mode = requestedMode ?? defaultModeForIntent(intent);
+    return {
+        intent,
+        mode,
+        safety: safetyForMode(mode),
+        execution: executionForMode(mode),
+        reason: reasonForIntent(intent),
+    };
+}
+export function classifyPromptIntent(prompt, repoSignals = {}) {
+    const lowered = prompt.toLowerCase();
+    if (/\b(explain|what is|how does|describe|설명|이거 뭐|어떻게 동작)\b/i.test(prompt))
+        return "explain";
+    if (/\b(review|audit|검토|리뷰|코드리뷰)\b/i.test(prompt))
+        return "review";
+    if (/\b(test|failing|pytest|vitest|jest|테스트|실패)\b/i.test(prompt))
+        return "fix";
+    if (/\b(debug|diagnose|왜|원인|진단)\b/i.test(prompt))
+        return "diagnose";
+    if (/\b(plan|design|architecture|설계|계획)\b/i.test(prompt))
+        return "plan";
+    if (/\b(refactor|fix|change|add|remove|implement|수정|추가|고쳐|구현|리팩터)\b/i.test(prompt))
+        return "edit";
+    if (repoSignals.hasUncommittedChanges && /\b(clean|diff|changes|변경)\b/i.test(lowered))
+        return "review";
+    if (prompt.length > 180 || repoSignals.largeRepo)
+        return "parallel";
+    return "chat";
+}
+function defaultModeForIntent(intent) {
+    if (intent === "explain" || intent === "chat" || intent === "plan")
+        return "plan";
+    if (intent === "review" || intent === "diagnose")
+        return "review";
+    return "guided";
+}
+function safetyForMode(mode) {
+    if (mode === "plan" || mode === "safe" || mode === "review")
+        return "read-only";
+    if (mode === "autopilot")
+        return "workspace-write";
+    return "ask-before-edit";
+}
+function executionForMode(mode) {
+    if (mode === "plan" || mode === "safe" || mode === "review")
+        return "plan-only";
+    if (mode === "autopilot")
+        return "auto";
+    return "guided";
+}
+function reasonForIntent(intent) {
+    switch (intent) {
+        case "fix": return "test or failing-work keywords detected";
+        case "review": return "review/audit language detected";
+        case "explain": return "explanation request detected";
+        case "plan": return "planning/design language detected";
+        case "edit": return "code-change language detected";
+        case "diagnose": return "debug/diagnosis language detected";
+        case "parallel": return "large or complex prompt likely benefits from worker split";
+        default: return "default conversational coding task";
+    }
+}

package/dist/ux/natural-entrypoint.d.ts

@@ -0,0 +1,21 @@
+import type { Command } from "commander";
+export type OmkUxMode = "plan" | "guided" | "act" | "review" | "autopilot" | "safe";
+export interface NaturalPromptOptions {
+    runId?: string;
+    provider?: string;
+    model?: string;
+    mode?: OmkUxMode;
+    mcpScope?: "all" | "project" | "none";
+    workers?: string;
+    dryRun?: boolean;
+    json?: boolean;
+    noWatch?: boolean;
+}
+export interface NaturalPromptInvocation {
+    prompt: string;
+    options: NaturalPromptOptions;
+}
+export declare function extractNaturalPromptInvocation(args: readonly string[], knownCommands: ReadonlySet<string>): NaturalPromptInvocation | undefined;
+export declare function knownCommandNames(program: Command): Set<string>;
+export declare function looksLikeNaturalPrompt(value: string): boolean;
+export declare function normalizeMode(value: string | undefined): OmkUxMode | undefined;

package/dist/ux/natural-entrypoint.js

@@ -0,0 +1,122 @@
+const TASK_WORDS = /\b(fix|add|change|remove|refactor|review|audit|test|explain|plan|debug|diagnose|implement|write|update|repair)\b/i;
+const NON_LATIN = /[^\u0000-\u007f]/u;
+export function extractNaturalPromptInvocation(args, knownCommands) {
+    if (args.length === 0)
+        return undefined;
+    const options = {};
+    const promptParts = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index] ?? "";
+        if (arg === "--") {
+            promptParts.push(...args.slice(index + 1));
+            break;
+        }
+        if (arg === "-r") {
+            const parsed = optionValue("runId", undefined, args[index + 1]);
+            if (!parsed)
+                return undefined;
+            Object.assign(options, parsed.options);
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--")) {
+            const parsed = parseNaturalOption(arg, args[index + 1]);
+            if (!parsed)
+                return undefined;
+            Object.assign(options, parsed.options);
+            if (parsed.consumedValue)
+                index += 1;
+            continue;
+        }
+        promptParts.push(arg);
+    }
+    if (promptParts.length === 0)
+        return undefined;
+    const first = promptParts[0]?.trim() ?? "";
+    if (knownCommands.has(first))
+        return undefined;
+    const prompt = promptParts.join(" ").trim();
+    if (!looksLikeNaturalPrompt(prompt))
+        return undefined;
+    return { prompt, options };
+}
+export function knownCommandNames(program) {
+    const names = new Set();
+    for (const command of program.commands) {
+        names.add(command.name());
+        for (const alias of command.aliases())
+            names.add(alias);
+    }
+    return names;
+}
+export function looksLikeNaturalPrompt(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return false;
+    if (trimmed.startsWith("/"))
+        return false;
+    return trimmed.includes(" ") || NON_LATIN.test(trimmed) || TASK_WORDS.test(trimmed) || trimmed.length >= 18;
+}
+function parseNaturalOption(arg, next) {
+    const [name, inlineValue] = splitOption(arg);
+    switch (name) {
+        case "--dry-run":
+            return { options: { dryRun: true }, consumedValue: false };
+        case "--json":
+            return { options: { json: true }, consumedValue: false };
+        case "--no-watch":
+            return { options: { noWatch: true }, consumedValue: false };
+        case "--provider":
+            return optionValue("provider", inlineValue, next);
+        case "--run-id":
+            return optionValue("runId", inlineValue, next);
+        case "--model":
+            return optionValue("model", inlineValue, next);
+        case "--mode":
+            return modeOption(inlineValue, next);
+        case "--mcp-scope":
+            return mcpScopeOption(inlineValue, next);
+        case "--workers":
+            return optionValue("workers", inlineValue, next);
+        default:
+            return undefined;
+    }
+}
+function splitOption(arg) {
+    const index = arg.indexOf("=");
+    if (index < 0)
+        return [arg, undefined];
+    return [arg.slice(0, index), arg.slice(index + 1)];
+}
+function optionValue(key, inlineValue, next) {
+    const value = inlineValue ?? next;
+    if (!value || value.startsWith("--"))
+        return undefined;
+    return { options: { [key]: value }, consumedValue: inlineValue === undefined };
+}
+function modeOption(inlineValue, next) {
+    const value = normalizeMode(inlineValue ?? next);
+    if (!value)
+        return undefined;
+    return { options: { mode: value }, consumedValue: inlineValue === undefined };
+}
+function mcpScopeOption(inlineValue, next) {
+    const value = inlineValue ?? next;
+    if (value === "all" || value === "project" || value === "none") {
+        return { options: { mcpScope: value }, consumedValue: inlineValue === undefined };
+    }
+    return undefined;
+}
+export function normalizeMode(value) {
+    const normalized = value?.trim().toLowerCase();
+    if (!normalized)
+        return undefined;
+    if (normalized === "guided-edit" || normalized === "edit")
+        return "guided";
+    if (normalized === "auto")
+        return "autopilot";
+    if (["plan", "guided", "act", "review", "autopilot", "safe"].includes(normalized)) {
+        return normalized;
+    }
+    return undefined;
+}

package/dist/version.d.ts

@@ -0,0 +1,11 @@
+export declare const OMK_PACKAGE_NAME = "open-multi-agent-kit";
+export declare const OMK_RUNTIME_VERSION = "v1.2";
+export declare const OMK_CONTRACT_VERSION = "omk.contract.v1";
+export declare const OMK_EVIDENCE_SCHEMA_VERSION = "omk.evidence.v1";
+export declare const OMK_DECISION_SCHEMA_VERSION = "omk.decision.v1";
+export declare const OMK_RUN_MANIFEST_SCHEMA_VERSION = "omk.run-manifest.v1";
+export declare const OMK_PROVIDER_SCHEMA_VERSION = "omk.provider.v1";
+export declare const OMK_VERSION_SCHEMA_VERSION = "omk.version.v1";
+export declare const OMK_PROOF_BUNDLE_SCHEMA_VERSION = "omk.proof-bundle.v1";
+export declare const OMK_RELEASE_CHANNEL = "pre-1.0";
+export declare const OMK_SCHEMA_VERSIONS: readonly ["omk.evidence.v1", "omk.decision.v1", "omk.run-manifest.v1", "omk.provider.v1", "omk.version.v1", "omk.proof-bundle.v1"];

package/dist/version.js

@@ -0,0 +1,18 @@
+export const OMK_PACKAGE_NAME = "open-multi-agent-kit";
+export const OMK_RUNTIME_VERSION = "v1.2";
+export const OMK_CONTRACT_VERSION = "omk.contract.v1";
+export const OMK_EVIDENCE_SCHEMA_VERSION = "omk.evidence.v1";
+export const OMK_DECISION_SCHEMA_VERSION = "omk.decision.v1";
+export const OMK_RUN_MANIFEST_SCHEMA_VERSION = "omk.run-manifest.v1";
+export const OMK_PROVIDER_SCHEMA_VERSION = "omk.provider.v1";
+export const OMK_VERSION_SCHEMA_VERSION = "omk.version.v1";
+export const OMK_PROOF_BUNDLE_SCHEMA_VERSION = "omk.proof-bundle.v1";
+export const OMK_RELEASE_CHANNEL = "pre-1.0";
+export const OMK_SCHEMA_VERSIONS = [
+    OMK_EVIDENCE_SCHEMA_VERSION,
+    OMK_DECISION_SCHEMA_VERSION,
+    OMK_RUN_MANIFEST_SCHEMA_VERSION,
+    OMK_PROVIDER_SCHEMA_VERSION,
+    OMK_VERSION_SCHEMA_VERSION,
+    OMK_PROOF_BUNDLE_SCHEMA_VERSION,
+];

package/dist/web-bridge/host.d.ts

@@ -0,0 +1,8 @@
+import { type WebBridgeResponseEnvelope } from "../contracts/web-bridge.js";
+interface BridgeHostOptions {
+    root?: string;
+    now?: Date;
+}
+export declare function handleWebBridgeRequest(rawRequest: unknown, options?: BridgeHostOptions): Promise<WebBridgeResponseEnvelope>;
+export declare function digestParams(params: unknown): string;
+export {};

package/dist/web-bridge/host.js

@@ -0,0 +1,109 @@
+import { createHash } from "crypto";
+import { WEB_BRIDGE_SCHEMA_VERSION, assertReadOnlyWebBridgeRequest, createWebBridgeErrorResponse, createWebBridgeOkResponse, getDefaultWebBridgeCapabilities, isWebBridgeMutation, sanitizeWebBridgePageSnapshot, validateWebBridgeRequest, } from "../contracts/web-bridge.js";
+import { getWebBridgeStatus, readLatestWebBridgePageContext, writeWebBridgePageContext, } from "./status.js";
+export async function handleWebBridgeRequest(rawRequest, options = {}) {
+    let request;
+    try {
+        request = validateWebBridgeRequest(rawRequest);
+    }
+    catch (err) {
+        return createWebBridgeErrorResponse("unknown", "invalid_schema", err instanceof Error ? err.message : String(err));
+    }
+    if (isWebBridgeMutation(request.method)) {
+        const approvalError = validateMutationApproval(request, options.now ?? new Date());
+        if (approvalError)
+            return createWebBridgeErrorResponse(request.requestId, "approval_required", approvalError, { retryable: false });
+        return createWebBridgeErrorResponse(request.requestId, "unsafe_mutation", "Approved browser mutations are not executed by the read-only OMK web bridge v1", { retryable: false });
+    }
+    try {
+        assertReadOnlyWebBridgeRequest(request);
+        switch (request.method) {
+            case "bridge.ping":
+                return createWebBridgeOkResponse(request.requestId, { pong: true, schemaVersion: WEB_BRIDGE_SCHEMA_VERSION });
+            case "bridge.capabilities":
+                return createWebBridgeOkResponse(request.requestId, getDefaultWebBridgeCapabilities());
+            case "bridge.status":
+                return createWebBridgeOkResponse(request.requestId, await getWebBridgeStatus({ root: options.root }));
+            case "browser.tabs.list": {
+                const snapshot = await readLatestWebBridgePageContext(options.root);
+                const tabs = extractTabsFromParams(request.params) ?? snapshot?.tabs ?? (snapshot?.tab ? [snapshot.tab] : []);
+                return createWebBridgeOkResponse(request.requestId, { tabs });
+            }
+            case "browser.page.read": {
+                const snapshot = extractSnapshotFromParams(request.params) ?? await readLatestWebBridgePageContext(options.root);
+                if (!snapshot)
+                    return createWebBridgeErrorResponse(request.requestId, "not_connected", "No web bridge page snapshot is available", { retryable: true });
+                return createWebBridgeOkResponse(request.requestId, sanitizeWebBridgePageSnapshot(snapshot));
+            }
+            case "browser.selection.read": {
+                const snapshot = extractSnapshotFromParams(request.params) ?? await readLatestWebBridgePageContext(options.root);
+                return createWebBridgeOkResponse(request.requestId, { selectedText: snapshot?.selectedText ?? "" });
+            }
+            case "browser.dom.query": {
+                const snapshot = extractSnapshotFromParams(request.params) ?? await readLatestWebBridgePageContext(options.root);
+                if (!snapshot?.dom)
+                    return createWebBridgeErrorResponse(request.requestId, "not_connected", "No DOM snapshot is available", { retryable: true });
+                return createWebBridgeOkResponse(request.requestId, { dom: snapshot.dom });
+            }
+            case "browser.screenshot.capture": {
+                const snapshot = extractSnapshotFromParams(request.params) ?? await readLatestWebBridgePageContext(options.root);
+                if (!snapshot?.screenshot)
+                    return createWebBridgeErrorResponse(request.requestId, "not_connected", "No screenshot artifact is available", { retryable: true });
+                return createWebBridgeOkResponse(request.requestId, { screenshot: snapshot.screenshot });
+            }
+            case "orchestration.context.write": {
+                const snapshot = extractSnapshotFromParams(request.params);
+                if (!snapshot)
+                    return createWebBridgeErrorResponse(request.requestId, "invalid_schema", "orchestration.context.write requires a snapshot payload");
+                const runId = extractRunIdFromParams(request.params);
+                const written = await writeWebBridgePageContext(snapshot, { root: options.root, runId });
+                return createWebBridgeOkResponse(request.requestId, written);
+            }
+            default:
+                return createWebBridgeErrorResponse(request.requestId, "unknown_method", `Unknown web bridge method: ${request.method}`);
+        }
+    }
+    catch (err) {
+        return createWebBridgeErrorResponse(request.requestId, "internal_error", err instanceof Error ? err.message : String(err));
+    }
+}
+function validateMutationApproval(request, now) {
+    const approval = request.approval;
+    if (!approval)
+        return "Mutating browser actions require explicit approval";
+    if (approval.method !== request.method)
+        return "Approval is bound to a different method";
+    const expiresAt = Date.parse(approval.expiresAt);
+    if (!Number.isFinite(expiresAt) || expiresAt <= now.getTime())
+        return "Approval is expired or invalid";
+    const expectedDigest = digestParams(request.params);
+    if (approval.argsDigest !== expectedDigest)
+        return "Approval args digest does not match the requested action";
+    return null;
+}
+export function digestParams(params) {
+    return createHash("sha256").update(JSON.stringify(params ?? null)).digest("hex").slice(0, 24);
+}
+function extractSnapshotFromParams(params) {
+    if (!params || typeof params !== "object" || Array.isArray(params))
+        return null;
+    const record = params;
+    const snapshot = record.snapshot ?? record.page ?? record.context;
+    if (!snapshot || typeof snapshot !== "object" || Array.isArray(snapshot))
+        return null;
+    return sanitizeWebBridgePageSnapshot(snapshot);
+}
+function extractTabsFromParams(params) {
+    if (!params || typeof params !== "object" || Array.isArray(params))
+        return null;
+    const tabs = params.tabs;
+    if (!Array.isArray(tabs))
+        return null;
+    return sanitizeWebBridgePageSnapshot({ tabs }).tabs ?? [];
+}
+function extractRunIdFromParams(params) {
+    if (!params || typeof params !== "object" || Array.isArray(params))
+        return undefined;
+    const runId = params.runId;
+    return typeof runId === "string" && runId.trim() ? runId : undefined;
+}

package/dist/web-bridge/native-host.d.ts

@@ -0,0 +1,6 @@
+export declare function runWebBridgeNativeHost(): Promise<void>;
+export declare function runNativeMessagingLoop(input?: NodeJS.ReadStream & {
+    fd: 0;
+}, output?: NodeJS.WriteStream & {
+    fd: 1;
+}): Promise<void>;

package/dist/web-bridge/native-host.js

@@ -0,0 +1,40 @@
+import { stdin, stdout } from "process";
+import { WEB_BRIDGE_MAX_PAYLOAD_BYTES } from "../contracts/web-bridge.js";
+import { handleWebBridgeRequest } from "./host.js";
+export async function runWebBridgeNativeHost() {
+    await runNativeMessagingLoop(process.stdin, process.stdout);
+}
+export async function runNativeMessagingLoop(input = stdin, output = stdout) {
+    let buffer = Buffer.alloc(0);
+    input.on("data", async (chunk) => {
+        buffer = Buffer.concat([buffer, chunk]);
+        while (buffer.length >= 4) {
+            const length = buffer.readUInt32LE(0);
+            if (length > WEB_BRIDGE_MAX_PAYLOAD_BYTES) {
+                buffer = Buffer.alloc(0);
+                writeNativeMessage(output, { schemaVersion: 1, requestId: "unknown", ok: false, error: { code: "payload_too_large", message: "Native message payload is too large" } });
+                return;
+            }
+            if (buffer.length < 4 + length)
+                return;
+            const payload = buffer.subarray(4, 4 + length).toString("utf-8");
+            buffer = buffer.subarray(4 + length);
+            let parsed;
+            try {
+                parsed = JSON.parse(payload);
+            }
+            catch (err) {
+                writeNativeMessage(output, { schemaVersion: 1, requestId: "unknown", ok: false, error: { code: "invalid_schema", message: err instanceof Error ? err.message : String(err) } });
+                continue;
+            }
+            writeNativeMessage(output, await handleWebBridgeRequest(parsed));
+        }
+    });
+    await new Promise((resolve) => input.on("end", resolve));
+}
+function writeNativeMessage(output, payload) {
+    const body = Buffer.from(JSON.stringify(payload), "utf-8");
+    const header = Buffer.alloc(4);
+    header.writeUInt32LE(body.length, 0);
+    output.write(Buffer.concat([header, body]));
+}