@amoree-code/ocean 0.0.0-stage → 1.2.0

package/dist/infrastructure/providers/playwright-browser-provider.js

@@ -0,0 +1,380 @@
+// The only file in Ocean permitted to know a browser engine. Everything above the
+// BrowserProvider boundary (browser-provider.ts) stays engine-neutral.
+//
+// Depends on `playwright-core`, not `playwright`: playwright-core ships the driver and
+// API without downloading a Chromium binary on install, so `pnpm install` stays light and
+// a missing browser binary is a reportable `detect()` failure rather than an install-time
+// requirement.
+//
+// A session survives between CLI invocations: the browser is launched as its own
+// detached process with a remote-debugging port, and later invocations reconnect over
+// CDP by port. Without this, a multi-step browser task would mean a new browser per
+// step, which is not a session.
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import net from "node:net";
+import path from "node:path";
+import { oceanEnv } from "@ocean/core/shared/paths.js";
+// A download's suggested filename comes from the remote page/server (e.g. a
+// Content-Disposition header) and must never be trusted as a path: it can contain `../`,
+// an absolute path, or backslash separators aimed at escaping destinationDir.
+export function safeDownloadFilename(suggested) {
+    const normalized = suggested.replace(/\\/g, "/");
+    const base = path.posix.basename(normalized).trim();
+    return !base || base === "." || base === ".." ? "download" : base;
+}
+export function resolveDownloadPath(destinationDir, suggestedFilename) {
+    const resolvedDir = path.resolve(destinationDir);
+    const candidate = path.resolve(resolvedDir, safeDownloadFilename(suggestedFilename));
+    if (candidate !== resolvedDir &&
+        !candidate.startsWith(resolvedDir + path.sep)) {
+        throw new Error(`Download path escapes destination directory: ${suggestedFilename}`);
+    }
+    return candidate;
+}
+async function freePort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            const port = typeof address === "object" && address ? address.port : 0;
+            server.close(() => resolve(port));
+        });
+    });
+}
+async function fetchWebSocketDebuggerUrl(port) {
+    try {
+        const response = await fetch(`http://127.0.0.1:${port}/json/version`, {
+            signal: AbortSignal.timeout(1000),
+        });
+        const body = (await response.json());
+        return body.webSocketDebuggerUrl ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function _nthIndex(value, needle, occurrence) {
+    let from = 0;
+    for (let current = 1; current <= occurrence; current += 1) {
+        const index = value.indexOf(needle, from);
+        if (index < 0)
+            return -1;
+        if (current === occurrence)
+            return index;
+        from = index + needle.length;
+    }
+    return -1;
+}
+function resolveChromiumExecutable() {
+    const candidates = [
+        oceanEnv("BROWSER_EXECUTABLE"),
+        "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+        "/usr/bin/google-chrome",
+        "/usr/bin/chromium-browser",
+        "/usr/bin/chromium",
+    ].filter((candidate) => Boolean(candidate));
+    return candidates.find((candidate) => existsSync(candidate)) ?? null;
+}
+export class PlaywrightBrowserProvider {
+    async detect() {
+        const executable = resolveChromiumExecutable();
+        if (!executable)
+            return {
+                ok: false,
+                detail: "no Chromium-family browser binary found; set OCEAN_BROWSER_EXECUTABLE",
+            };
+        return { ok: true, detail: executable };
+    }
+    async launch(profileDir, port) {
+        const executable = resolveChromiumExecutable();
+        if (!executable)
+            throw new Error("Browser capability denied: no browser binary detected");
+        const resolvedPort = port ?? (await freePort());
+        await mkdir(profileDir, { recursive: true });
+        const child = spawn(executable, [
+            `--remote-debugging-port=${resolvedPort}`,
+            `--remote-debugging-address=127.0.0.1`,
+            `--user-data-dir=${profileDir}`,
+            "--no-first-run",
+            "--no-default-browser-check",
+            "--headless=new",
+            "--disable-gpu",
+            "about:blank",
+        ], { stdio: "ignore", detached: true });
+        child.unref();
+        let endpoint = null;
+        for (let attempt = 0; attempt < 100 && !endpoint; attempt += 1) {
+            endpoint = await fetchWebSocketDebuggerUrl(resolvedPort);
+            if (!endpoint)
+                await new Promise((resolve) => setTimeout(resolve, 200));
+        }
+        if (!endpoint) {
+            child.kill();
+            throw new Error("Browser did not expose a debugging endpoint within the timeout");
+        }
+        return { pid: child.pid ?? -1, port: resolvedPort, endpoint, profileDir };
+    }
+    async connect(launch) {
+        const { chromium } = await import("playwright-core");
+        const browser = await chromium.connectOverCDP(`http://127.0.0.1:${launch.port}`);
+        const context = browser.contexts()[0] ?? (await browser.newContext());
+        const page = context.pages()[0] ?? (await context.newPage());
+        return new PlaywrightHandle(browser, page);
+    }
+    async close(launch) {
+        if (launch.pid > 0) {
+            try {
+                process.kill(launch.pid, "SIGTERM");
+            }
+            catch {
+                /* already exited */
+            }
+        }
+    }
+}
+class PlaywrightHandle {
+    browser;
+    page;
+    constructor(browser, page) {
+        this.browser = browser;
+        this.page = page;
+    }
+    async state() {
+        return { url: this.page.url(), title: await this.page.title() };
+    }
+    async navigate(url, timeoutMs = 30_000) {
+        await this.page.goto(url, {
+            timeout: timeoutMs,
+            waitUntil: "domcontentloaded",
+        });
+        return this.state();
+    }
+    async readText() {
+        const text = ((await this.page.innerText("body")) ||
+            (await this.page.locator("body").textContent()) ||
+            "").slice(0, 20_000);
+        return { ...(await this.state()), text };
+    }
+    async observe() {
+        const elements = (await this.page.$$eval("a,button,input,select,textarea,[role=button]", (nodes) => nodes.slice(0, 120).map((node) => {
+            const element = node;
+            return {
+                tag: element.tagName.toLowerCase(),
+                type: element.type ?? null,
+                name: element.name || null,
+                id: element.id || null,
+                text: (element.innerText || element.value || "")
+                    .trim()
+                    .slice(0, 80),
+                visible: Boolean(element.offsetWidth || element.offsetHeight),
+            };
+        })));
+        return { ...(await this.state()), elements };
+    }
+    async extract(selector, attribute) {
+        const values = attribute
+            ? await this.page.$$eval(selector, (nodes, attr) => nodes.map((node) => node.getAttribute(attr)), attribute)
+            : await this.page.$$eval(selector, (nodes) => nodes.map((node) => node.innerText?.trim() ||
+                node.value?.trim() ||
+                ""));
+        return { selector, count: values.length, values: values.slice(0, 200) };
+    }
+    async click(selector, timeoutMs = 15_000) {
+        const urlBefore = this.page.url();
+        await this.page.click(selector, { timeout: timeoutMs });
+        await this.page.waitForTimeout(300);
+        return { ...(await this.state()), urlBefore };
+    }
+    async type(selector, text, clear = true) {
+        let locator = this.editorLocator(selector);
+        await locator.waitFor({ state: "visible", timeout: 15_000 });
+        const nestedEditor = locator.locator("textarea, input").first();
+        if ((await nestedEditor.count()) > 0)
+            locator = nestedEditor;
+        const kind = await locator.evaluate((node) => ({
+            tag: node.tagName.toLowerCase(),
+            contentEditable: node instanceof HTMLElement && node.isContentEditable,
+            value: "value" in node ? String(node.value) : null,
+        }));
+        if (kind.contentEditable ||
+            (kind.tag !== "input" && kind.tag !== "textarea")) {
+            await locator.click();
+            if (clear) {
+                await this.page.keyboard.press("ControlOrMeta+A");
+                await this.page.keyboard.press("Backspace");
+            }
+            await this.page.keyboard.insertText(text);
+        }
+        else {
+            if (clear)
+                await locator.fill("");
+            await locator.pressSequentially(text, { timeout: 15_000 });
+        }
+        const value = await locator.evaluate((node) => {
+            if ("value" in node)
+                return String(node.value);
+            return (node.textContent || node.innerText || "").trim();
+        });
+        return { selector, typed: text.length, value };
+    }
+    async replaceText(selector, oldText, newText, occurrence = 1) {
+        if (!oldText)
+            throw new Error("old-text must not be empty");
+        if (!Number.isInteger(occurrence) || occurrence < 1)
+            throw new Error("occurrence must be a positive integer");
+        const locator = this.editorLocator(selector);
+        await locator.waitFor({ state: "visible", timeout: 15_000 });
+        const editorKind = await locator.evaluate((node) => ({
+            monaco: node.classList.contains("monaco-editor") ||
+                Boolean(node.querySelector(".monaco-editor")),
+            codeMirror: node.classList.contains("CodeMirror") ||
+                Boolean(node.querySelector(".CodeMirror")),
+        }));
+        if (editorKind.monaco) {
+            const input = locator.locator("textarea.inputarea").first();
+            await input.click();
+            await this.page.keyboard.press("ControlOrMeta+f");
+            await this.page.keyboard.insertText(oldText);
+            for (let index = 1; index < occurrence; index += 1)
+                await this.page.keyboard.press("Enter");
+            await this.page.keyboard.press("Escape");
+            await this.page.keyboard.insertText(newText);
+            const value = await locator.locator(".view-lines").innerText();
+            if (value.includes(oldText))
+                throw new Error(`Text occurrence was not replaced: ${occurrence}`);
+            return { selector, oldText, newText, occurrence, value };
+        }
+        const result = await locator.evaluate((node, input) => {
+            const root = node;
+            const nthIndexInPage = (value, needle, occurrence) => {
+                let from = 0;
+                for (let current = 1; current <= occurrence; current += 1) {
+                    const index = value.indexOf(needle, from);
+                    if (index < 0)
+                        return -1;
+                    if (current === occurrence)
+                        return index;
+                    from = index + needle.length;
+                }
+                return -1;
+            };
+            const global = window;
+            const editors = global.monaco?.editor?.getEditors?.() ?? [];
+            const editor = editors.find((candidate) => candidate.getDomNode?.() === root);
+            const model = editor?.getModel?.() ??
+                global.monaco?.editor
+                    ?.getModels?.()
+                    .find((candidate) => candidate.getValue().includes(input.oldText));
+            if (model) {
+                const matches = model.findMatches(input.oldText);
+                const match = matches[input.occurrence - 1];
+                if (!match)
+                    throw new Error(`Text occurrence not found: ${input.occurrence}`);
+                model.pushEditOperations([], [{ range: match.range, text: input.newText }], null);
+                return { value: model.getValue(), occurrence: input.occurrence };
+            }
+            const target = root.matches("textarea,input")
+                ? root
+                : root.querySelector("textarea,input");
+            const value = target && "value" in target
+                ? String(target.value)
+                : (root.textContent ?? "");
+            const index = nthIndexInPage(value, input.oldText, input.occurrence);
+            if (index < 0)
+                throw new Error(`Text occurrence not found: ${input.occurrence}`);
+            const next = value.slice(0, index) +
+                input.newText +
+                value.slice(index + input.oldText.length);
+            if (target) {
+                target.value = next;
+                target.dispatchEvent(new Event("input", { bubbles: true }));
+            }
+            else
+                root.textContent = next;
+            return { value: next, occurrence: input.occurrence };
+        }, { oldText, newText, occurrence });
+        return {
+            selector,
+            oldText,
+            newText,
+            occurrence: result.occurrence,
+            value: result.value,
+        };
+    }
+    editorLocator(selector) {
+        const separator = " >>> ";
+        const frameIndex = selector.indexOf(separator);
+        if (frameIndex >= 0) {
+            const frameSelector = selector.slice(0, frameIndex);
+            const editorSelector = selector.slice(frameIndex + separator.length);
+            if (!frameSelector || !editorSelector)
+                throw new Error("Editor frame selector must use 'frame >>> editor'.");
+            return this.page
+                .frameLocator(frameSelector)
+                .locator(editorSelector)
+                .first();
+        }
+        return this.page.locator(selector).first();
+    }
+    async select(selector, value) {
+        await this.page.selectOption(selector, value, { timeout: 15_000 });
+        return {
+            selector,
+            value: await this.page.inputValue(selector, { timeout: 5_000 }),
+        };
+    }
+    async scroll(deltaY = 600) {
+        await this.page.mouse.wheel(0, deltaY);
+        await this.page.waitForTimeout(150);
+        const scrollY = await this.page.evaluate(() => Math.round(window.scrollY));
+        return { scrollY };
+    }
+    async wait(options) {
+        const timeout = options.timeoutMs ?? 15_000;
+        if (options.selector)
+            await this.page.waitForSelector(options.selector, { timeout });
+        if (options.urlContains)
+            await this.page.waitForURL(`**${options.urlContains}**`, { timeout });
+        return this.state();
+    }
+    async upload(selector, paths) {
+        await this.page.setInputFiles(selector, paths, { timeout: 15_000 });
+        const attached = await this.page.$eval(selector, (node) => Array.from(node.files ?? []).map((file) => file.name));
+        return { selector, attached };
+    }
+    async download(selector, destinationDir, timeoutMs = 60_000) {
+        const [download] = await Promise.all([
+            this.page.waitForEvent("download", { timeout: timeoutMs }),
+            this.page.click(selector, { timeout: timeoutMs }),
+        ]);
+        await mkdir(destinationDir, { recursive: true });
+        const targetPath = resolveDownloadPath(destinationDir, download.suggestedFilename());
+        await download.saveAs(targetPath);
+        const { statSync } = await import("node:fs");
+        const size = existsSync(targetPath) ? statSync(targetPath).size : 0;
+        return { selector, path: targetPath, size };
+    }
+    async submit(selector, timeoutMs = 20_000) {
+        const urlBefore = this.page.url();
+        const bodyBefore = (await this.page.innerText("body")).slice(0, 20_000);
+        await this.page.click(selector, { timeout: timeoutMs });
+        try {
+            await this.page.waitForLoadState("domcontentloaded", {
+                timeout: timeoutMs,
+            });
+        }
+        catch {
+            /* best-effort */
+        }
+        await this.page.waitForTimeout(400);
+        const bodyAfter = (await this.page.innerText("body")).slice(0, 20_000);
+        return { ...(await this.state()), urlBefore, bodyBefore, bodyAfter };
+    }
+    async release() {
+        await this.browser.close();
+    }
+}
+//# sourceMappingURL=playwright-browser-provider.js.map

package/dist/infrastructure/providers/provider-capabilities.js

@@ -0,0 +1,50 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { providerCapabilitySchema, } from "@ocean/core/domain/providers/provider-capability.js";
+const execFileAsync = promisify(execFile);
+const commands = {
+    claude: "claude",
+    codex: "codex",
+    gemini: "gemini",
+    antigravity: "agy",
+    hermes: "hermes",
+    kilo: "kilo",
+    kimi: "kimi",
+};
+export async function discoverProviderCapabilities(provider) {
+    const command = commands[provider];
+    let installed = false;
+    try {
+        await execFileAsync("which", [command]);
+        installed = true;
+    }
+    catch {
+        /* represented as unavailable */
+    }
+    const contextTransport = provider === "hermes"
+        ? "environment-hint"
+        : provider === "claude"
+            ? "print-system-prompt-only"
+            : "provider-prompt-option-headless-only";
+    return providerCapabilitySchema.parse({
+        provider,
+        command,
+        installed,
+        headless: true,
+        resume: provider === "claude",
+        streaming: true,
+        structuredOutput: true,
+        authentication: "cli-managed",
+        interactive: true,
+        interactiveContext: provider === "hermes" ? "partial" : "not-proven",
+        contextTransport,
+        inputCapture: "bounded-terminal",
+    });
+}
+export function assertProviderCapability(capability, requirement) {
+    if (!capability.installed)
+        throw new Error(`Provider CLI not installed: ${capability.command}`);
+    if (!capability[requirement])
+        throw new Error(`Provider ${capability.provider} does not support ${requirement}`);
+}
+//# sourceMappingURL=provider-capabilities.js.map

package/dist/infrastructure/providers/provider-invocation.js

@@ -0,0 +1,184 @@
+import { spawn } from "node:child_process";
+import { evaluateGuard, } from "@ocean/loop/operations/write-guard.js";
+import { redactRuntimeText } from "../observability/runtime-logger.js";
+import { resolveOriginalExecutable } from "./provider-registry.js";
+export const PROVIDER_HEADLESS = {
+    claude: {
+        args: (prompt) => ["-p", prompt, "--output-format", "json"],
+        parse: "json",
+    },
+    codex: {
+        args: (prompt) => ["exec", prompt, "--skip-git-repo-check"],
+        parse: "text",
+    },
+    gemini: { args: (prompt) => ["-p", prompt, "--skip-trust"], parse: "text" },
+};
+export function providerHeadlessSupport(provider) {
+    const spec = PROVIDER_HEADLESS[provider];
+    if (!spec)
+        return {
+            supported: false,
+            reason: `provider '${provider}' has no verified headless contract in Ocean — it stays gated as unsupported`,
+        };
+    return { supported: true, spec };
+}
+const MAX_OUTPUT_CHARS = 4_000;
+function sessionIdOf(event) {
+    for (const key of ["session_id", "sessionId"]) {
+        const value = event[key];
+        if (typeof value === "string" && value.length > 0)
+            return value;
+    }
+    const nested = event.session;
+    if (nested && typeof nested === "object") {
+        const value = nested.id;
+        if (typeof value === "string" && value.length > 0)
+            return value;
+    }
+    return null;
+}
+// Tolerant, deterministic stream parsing: a malformed line is counted, never thrown, and an
+// unterminated trailing line is reported as partial rather than silently dropped.
+export function parseProviderStream(text, mode = "json") {
+    if (mode === "text")
+        return {
+            events: [],
+            malformedLines: 0,
+            partial: false,
+            providerSessionId: null,
+        };
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return {
+            events: [],
+            malformedLines: 0,
+            partial: false,
+            providerSessionId: null,
+        };
+    try {
+        const single = JSON.parse(trimmed);
+        return {
+            events: [single],
+            malformedLines: 0,
+            partial: false,
+            providerSessionId: sessionIdOf(single),
+        };
+    }
+    catch {
+        // Fall through to line-by-line parsing.
+    }
+    const endsCleanly = text.endsWith("\n");
+    const lines = text.split("\n");
+    const events = [];
+    let malformedLines = 0;
+    let partial = false;
+    let providerSessionId = null;
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index].trim();
+        if (!line)
+            continue;
+        const isLast = index === lines.length - 1;
+        try {
+            const event = JSON.parse(line);
+            events.push(event);
+            providerSessionId = providerSessionId ?? sessionIdOf(event);
+        }
+        catch {
+            if (isLast && !endsCleanly)
+                partial = true;
+            else
+                malformedLines += 1;
+        }
+    }
+    return { events, malformedLines, partial, providerSessionId };
+}
+function result(request, status, reason, overrides = {}) {
+    return {
+        provider: request.provider,
+        status,
+        exitCode: null,
+        durationMs: 0,
+        providerSessionId: null,
+        oceanSessionId: request.oceanSessionId,
+        parentSessionId: request.parentSessionId ?? null,
+        malformedLines: 0,
+        partial: false,
+        output: "",
+        reason,
+        guard: null,
+        ...overrides,
+    };
+}
+// Every external provider action goes through here, and the guard runs before the process is
+// ever spawned. A denial returns a structured result; it never reaches spawn().
+export async function invokeProviderHeadless(request) {
+    const support = providerHeadlessSupport(request.provider);
+    if (!support.supported)
+        return result(request, "unsupported", support.reason);
+    const decision = evaluateGuard(request.guard);
+    if (!decision.allowed) {
+        return result(request, "denied", `provider invocation denied by the Ocean write guard: ${decision.reason}`, { guard: decision });
+    }
+    let executable;
+    try {
+        executable =
+            request.executable ?? resolveOriginalExecutable(request.provider);
+    }
+    catch (error) {
+        return result(request, "unavailable", `provider '${request.provider}' is not available on this machine: ${error instanceof Error ? error.message : String(error)}`, { guard: decision });
+    }
+    const started = Date.now();
+    const timeoutMs = request.timeoutMs ?? 120_000;
+    return await new Promise((resolve) => {
+        const child = spawn(executable, support.spec.args(request.prompt), {
+            cwd: request.cwd,
+            // stdin is closed: a headless invocation must never depend on an interactive prompt.
+            stdio: ["ignore", "pipe", "pipe"],
+            env: process.env,
+        });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            child.kill("SIGKILL");
+            resolve(result(request, "timeout", `provider '${request.provider}' exceeded the ${timeoutMs}ms budget and was terminated`, {
+                durationMs: Date.now() - started,
+                guard: decision,
+                output: redactRuntimeText(stdout).slice(0, MAX_OUTPUT_CHARS),
+            }));
+        }, timeoutMs);
+        child.stdout.on("data", (chunk) => {
+            stdout += String(chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += String(chunk);
+        });
+        const finish = (exitCode, failureReason) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            const parsed = parseProviderStream(stdout, support.spec.parse);
+            const ok = exitCode === 0 && !failureReason;
+            resolve(result(request, ok ? "completed" : "failed", failureReason ??
+                (ok
+                    ? `provider '${request.provider}' completed`
+                    : `provider '${request.provider}' exited with code ${exitCode}`), {
+                exitCode,
+                durationMs: Date.now() - started,
+                providerSessionId: parsed.providerSessionId,
+                malformedLines: parsed.malformedLines,
+                partial: parsed.partial,
+                // Output is redacted and clipped: provider stdout/stderr never lands in a result raw.
+                output: redactRuntimeText(stdout || stderr).slice(0, MAX_OUTPUT_CHARS),
+                guard: decision,
+            }));
+        };
+        child.on("error", (error) => finish(null, `provider '${request.provider}' could not be executed: ${error.message}`));
+        child.on("close", (code) => finish(code));
+    });
+}
+//# sourceMappingURL=provider-invocation.js.map

package/dist/infrastructure/providers/provider-registry.js

@@ -0,0 +1,77 @@
+import { accessSync, constants, existsSync, readFileSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { registryFile } from "@ocean/core/shared/fs-utils.js";
+import { oceanEnv, oceanPath, SYSTEM_DIR } from "@ocean/core/shared/paths.js";
+const builtInProviders = [
+    { id: "claude", command: "claude", interactive: true, headless: true },
+    { id: "codex", command: "codex", interactive: true, headless: true },
+    { id: "gemini", command: "gemini", interactive: true, headless: true },
+    { id: "antigravity", command: "agy", interactive: true, headless: true },
+    { id: "hermes", command: "hermes", interactive: true, headless: true },
+];
+const providerRegistryPath = () => registryFile("providers.json");
+export function builtInProviderRecords() {
+    return builtInProviders.map((provider) => ({ ...provider }));
+}
+export function loadProviderRegistry() {
+    const file = providerRegistryPath();
+    if (!existsSync(file))
+        return builtInProviderRecords();
+    const parsed = JSON.parse(readFileSync(file, "utf8"));
+    const custom = Array.isArray(parsed.providers) ? parsed.providers : [];
+    const merged = new Map();
+    for (const provider of [...builtInProviders, ...custom])
+        merged.set(provider.id, provider);
+    return [...merged.values()];
+}
+export async function saveProviderRegistry(providers) {
+    await mkdir(path.dirname(providerRegistryPath()), { recursive: true });
+    await writeFile(providerRegistryPath(), `${JSON.stringify({ version: 1, providers }, null, 2)}\n`);
+}
+export function findProvider(value, providers = loadProviderRegistry()) {
+    const provider = providers.find((candidate) => candidate.id === value || candidate.command === value);
+    if (!provider)
+        throw new Error(`Provider is not registered: ${value}`);
+    return provider;
+}
+export function resolveOriginalExecutable(command, env = process.env) {
+    const shimRoot = path.resolve(oceanEnv("SHIM_DIR", env) ?? oceanPath(SYSTEM_DIR, "runtime", "shims"));
+    const pathEntries = (env.PATH ?? "").split(path.delimiter).filter(Boolean);
+    const names = process.platform === "win32"
+        ? [command, `${command}.exe`, `${command}.cmd`, `${command}.bat`]
+        : [command];
+    for (const directory of pathEntries) {
+        if (path.resolve(directory) === shimRoot || isOceanShimDirectory(directory))
+            continue;
+        for (const name of names) {
+            const candidate = path.join(directory, name);
+            try {
+                accessSync(candidate, constants.X_OK);
+                return candidate;
+            }
+            catch {
+                // Continue through PATH until the first executable outside Ocean's shim directory.
+            }
+        }
+    }
+    throw new Error(`Provider executable not found outside Ocean shims: ${command}`);
+}
+export function validateExplicitExecutable(commandPath) {
+    if (!path.isAbsolute(commandPath))
+        throw new Error(`Provider executable must be an absolute path: ${commandPath}`);
+    const resolved = path.resolve(commandPath);
+    try {
+        accessSync(resolved, constants.X_OK);
+    }
+    catch {
+        throw new Error(`Provider executable is missing or not executable: ${resolved}`);
+    }
+    return resolved;
+}
+function isOceanShimDirectory(directory) {
+    const resolved = path.resolve(directory);
+    return (path.basename(resolved) === "shims" &&
+        path.basename(path.dirname(resolved)) === "runtime");
+}
+//# sourceMappingURL=provider-registry.js.map