@amoree-code/ocean 0.0.0-stage → 1.1.0

package/dist/infrastructure/providers/claude-sdk.js

@@ -0,0 +1,137 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { DEFAULT_MAX_OUTPUT_BYTES } from "../process/cli-process.js";
+import { ownsGroup, superviseProcess } from "../process/process-supervisor.js";
+import { resolveOriginalExecutable } from "./provider-registry.js";
+// The plan's model, unless it leaves the client's own default ("provider-managed" or absent).
+export function explicitModel(model) {
+    return model && model !== "provider-managed" ? model : undefined;
+}
+// A Claude request as Claude Agent SDK options. The SDK turns them into Claude Code's own flags
+// (--resume, --model, --permission-mode, --add-dir) and speaks its stream protocol, so Ocean no
+// longer builds `claude -p` arguments or parses its output itself.
+export function claudeSdkOptions(request, executable) {
+    const model = explicitModel(request.model);
+    return {
+        // The user's own Claude Code, past Ocean's shims, never the SDK's bundled copy.
+        pathToClaudeCodeExecutable: executable,
+        cwd: path.resolve(request.cwd),
+        // Built fresh for every run, as for every provider: the plan's variables over this process's.
+        env: { ...process.env, ...request.env },
+        // Claude Code's own system prompt, as `claude -p` has it. Left unset, the SDK sends an empty one.
+        // Settings and CLAUDE.md need nothing: an unset settingSources loads every source, as the CLI does.
+        systemPrompt: { type: "preset", preset: "claude_code" },
+        ...(request.resumeId ? { resume: request.resumeId } : {}),
+        ...(model ? { model } : {}),
+        // Read-only is enforced with Claude Code's own controls, never only asked for in the prompt.
+        ...(request.readOnly
+            ? { permissionMode: "plan", extraArgs: { restricted: null } }
+            : {}),
+        ...(request.readDirectories?.length
+            ? { additionalDirectories: request.readDirectories }
+            : {}),
+    };
+}
+function exited(child) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return Promise.resolve(child.exitCode);
+    return new Promise((resolve) => child.once("exit", resolve));
+}
+// One headless Claude turn through the Agent SDK, with the same contract as every CLI provider:
+// Ocean spawns the process (so the session store gets its pid and its environment is the
+// plan's), every SDK message becomes a `json` event, and the run's timeout (124) and output
+// budget (125) end it exactly as they end any other provider, through the same supervisor.
+export async function runClaudeSdk(request) {
+    const executable = resolveOriginalExecutable("claude");
+    // The SDK loads only when Claude actually runs, not on every `ocean` command.
+    const { query } = await import("@anthropic-ai/claude-agent-sdk");
+    const abortController = new AbortController();
+    const events = [];
+    let terminating = false;
+    const supervision = superviseProcess({
+        timeoutMs: request.timeoutMs ?? 60_000,
+        maxOutputBytes: request.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES,
+        onTerminate: () => {
+            terminating = true;
+            abortController.abort();
+        },
+        // JSON lines reach us as the SDK's messages; lines that are not JSON never do (a crash
+        // notice, a plain-text warning), so keep those as text events, as the CLI runner does.
+        onLine: (line) => {
+            try {
+                JSON.parse(line);
+            }
+            catch {
+                const event = { type: "text", data: line };
+                events.push(event);
+                request.onEvent?.(event);
+            }
+        },
+    });
+    let child;
+    let failure;
+    let errorResult = false;
+    let code = null;
+    try {
+        const consumed = (async () => {
+            const messages = query({
+                prompt: request.prompt,
+                options: {
+                    ...claudeSdkOptions(request, executable),
+                    abortController,
+                    spawnClaudeCodeProcess: (options) => {
+                        const spawned = spawn(options.command, options.args, {
+                            cwd: options.cwd,
+                            env: options.env,
+                            signal: options.signal,
+                            stdio: ["pipe", "pipe", "pipe"],
+                            detached: ownsGroup,
+                            windowsHide: true,
+                        });
+                        child = spawned;
+                        supervision.attach(spawned);
+                        if (spawned.pid)
+                            request.onSpawn?.(spawned.pid);
+                        return spawned;
+                    },
+                },
+            });
+            for await (const message of messages) {
+                if (terminating)
+                    break;
+                const event = { type: "json", data: message };
+                events.push(event);
+                request.onEvent?.(event);
+                if (message.type === "result" && message.is_error)
+                    errorResult = true;
+            }
+        })().catch((error) => {
+            failure = error instanceof Error ? error.message : String(error);
+        });
+        // After a forced stop the run no longer waits on the SDK, whose message stream may never
+        // settle once its process and pipes are gone.
+        await Promise.race([consumed, supervision.released]);
+        if (!supervision.spawnError && child)
+            code = await exited(child);
+    }
+    finally {
+        supervision.finish();
+    }
+    if (supervision.spawnError && !supervision.timedOut)
+        throw supervision.spawnError;
+    supervision.flush();
+    const stopped = supervision.timedOut || supervision.outputLimitExceeded;
+    return {
+        exitCode: stopped || !child || code === null
+            ? supervision.exitCode(child ? code : null)
+            : code !== 0
+                ? code
+                : failure || errorResult
+                    ? 1
+                    : 0,
+        events,
+        stderr: supervision.stderr +
+            (stopped ? supervision.stopNote : failure ? `${failure}\n` : ""),
+    };
+}
+//# sourceMappingURL=claude-sdk.js.map

package/dist/infrastructure/providers/client-home.js

@@ -0,0 +1,14 @@
+import path from "node:path";
+import { oceanPath, SYSTEM_DIR } from "@ocean/core/shared/paths.js";
+export function resolveClientHome(profile) {
+    const configured = profile.clients[profile.provider]?.home;
+    if (!configured)
+        return undefined;
+    const root = path.resolve(oceanPath(SYSTEM_DIR, "clients"));
+    const resolved = path.resolve(oceanPath(configured));
+    if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) {
+        throw new Error(`Client home must stay under Ocean system/clients: ${configured}`);
+    }
+    return resolved;
+}
+//# sourceMappingURL=client-home.js.map

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

@@ -0,0 +1,146 @@
+// An in-memory BrowserProvider used by tests to exercise application-layer policy
+// (authority, approval, verification) without launching a real browser.
+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;
+}
+class FakePage {
+    url = "about:blank";
+    title = "";
+    inputs = new Map();
+    elements = [];
+    scrollY = 0;
+    clickTargets = new Map();
+}
+class FakeHandle {
+    page;
+    constructor(page) {
+        this.page = page;
+    }
+    // Test-only configuration hooks, not part of the BrowserHandle contract: they let a
+    // test script a scenario (a click that navigates, or a selector's current element
+    // count) for the application layer to verify against, without a real browser.
+    setElements(elements) {
+        this.page.elements = elements;
+    }
+    setClickTarget(selector, url) {
+        this.page.clickTargets.set(selector, url);
+    }
+    async state() {
+        return { url: this.page.url, title: this.page.title };
+    }
+    async navigate(url) {
+        this.page.url = url;
+        this.page.title = `Title for ${url}`;
+        return this.state();
+    }
+    async readText() {
+        return {
+            ...(await this.state()),
+            text: this.page.elements.map((element) => element.text).join(" "),
+        };
+    }
+    async observe() {
+        return { ...(await this.state()), elements: this.page.elements };
+    }
+    async extract(selector, attribute) {
+        const values = this.page.elements
+            .filter((element) => element.id === selector || element.name === selector)
+            .map((element) => (attribute ? null : element.text));
+        return { selector, count: values.length, values };
+    }
+    async click(selector) {
+        const urlBefore = this.page.url;
+        const target = this.page.clickTargets.get(selector);
+        if (target) {
+            this.page.url = target;
+            this.page.title = `Title for ${target}`;
+        }
+        return { ...(await this.state()), urlBefore };
+    }
+    async type(selector, text, clear = true) {
+        const current = clear ? "" : (this.page.inputs.get(selector) ?? "");
+        const value = current + text;
+        this.page.inputs.set(selector, value);
+        return { selector, typed: text.length, value };
+    }
+    async replaceText(selector, oldText, newText, occurrence = 1) {
+        const value = this.page.inputs.get(selector) ?? "";
+        const index = nthIndex(value, oldText, occurrence);
+        if (index < 0)
+            throw new Error(`Text occurrence not found: ${occurrence}`);
+        const next = value.slice(0, index) + newText + value.slice(index + oldText.length);
+        this.page.inputs.set(selector, next);
+        return { selector, oldText, newText, occurrence, value: next };
+    }
+    async select(selector, value) {
+        this.page.inputs.set(selector, value);
+        return { selector, value };
+    }
+    async scroll(deltaY = 0) {
+        this.page.scrollY = Math.max(0, this.page.scrollY + deltaY);
+        return { scrollY: this.page.scrollY };
+    }
+    async wait() {
+        return this.state();
+    }
+    async upload(selector, paths) {
+        this.page.inputs.set(selector, paths.join(","));
+        return {
+            selector,
+            attached: paths.map((filePath) => filePath.split("/").pop() ?? filePath),
+        };
+    }
+    async download(selector, destinationDir) {
+        return { selector, path: `${destinationDir}/fake-download.txt`, size: 0 };
+    }
+    async submit(_selector) {
+        const urlBefore = this.page.url;
+        const bodyBefore = this.page.elements
+            .map((element) => element.text)
+            .join(" ");
+        return {
+            ...(await this.state()),
+            urlBefore,
+            bodyBefore,
+            bodyAfter: bodyBefore,
+        };
+    }
+    async release() { }
+}
+export class FakeBrowserProvider {
+    pages = new Map();
+    launchCount = 0;
+    async detect() {
+        return { ok: true, detail: "fake provider always available" };
+    }
+    async launch(profileDir, port = 0) {
+        this.launchCount += 1;
+        const launch = {
+            pid: this.launchCount,
+            port,
+            endpoint: `fake://${profileDir}`,
+            profileDir,
+        };
+        this.pages.set(launch.endpoint, new FakePage());
+        return launch;
+    }
+    async connect(launch) {
+        const page = this.pages.get(launch.endpoint);
+        if (!page)
+            throw new Error(`No fake session for endpoint: ${launch.endpoint}`);
+        return new FakeHandle(page);
+    }
+    async close(launch) {
+        this.pages.delete(launch.endpoint);
+    }
+}
+//# sourceMappingURL=fake-browser-provider.js.map

package/dist/infrastructure/providers/ollama-embedder.js

@@ -0,0 +1,74 @@
+import { oceanEnv } from "@ocean/core/shared/paths.js";
+// Local-only embedder for the brain index (T-228). Talks to a local Ollama daemon over
+// loopback only — never a remote host, never a `:cloud` model (Ollama's proxy to
+// ollama.com). This is a hard privacy boundary, not a convenience default: brain/02-personal
+// and brain/05-knowledge content must never leave the machine to be embedded.
+const LOOPBACK_HOSTNAMES = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+export class RemoteEmbedderRefusedError extends Error {
+}
+function assertLoopback(rawUrl) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new RemoteEmbedderRefusedError(`OCEAN_OLLAMA_URL is not a valid URL: ${rawUrl}`);
+    }
+    if (!LOOPBACK_HOSTNAMES.has(url.hostname)) {
+        throw new RemoteEmbedderRefusedError(`refusing non-loopback embedder host '${url.hostname}' — only 127.0.0.1/localhost/::1 are allowed`);
+    }
+    return url;
+}
+function assertNotCloudModel(model) {
+    if (model.toLowerCase().includes("cloud")) {
+        throw new RemoteEmbedderRefusedError(`refusing ':cloud'-style model '${model}' — it proxies to a remote host`);
+    }
+}
+const DEFAULT_BATCH_SIZE = 32;
+// Creates and validates an embedder against the live Ollama daemon: confirms loopback host,
+// confirms the model name and `/api/show` report neither name a remote model, and probes
+// dimensions with a single embed call. Throws (does not silently fall back) on any refusal —
+// reindex is expected to fail loudly unless the caller explicitly passed --no-vectors.
+export async function createOllamaEmbedder(options = {}) {
+    const baseUrl = options.baseUrl ?? oceanEnv("OLLAMA_URL") ?? "http://127.0.0.1:11434";
+    const model = options.model ?? oceanEnv("EMBED_MODEL") ?? "embeddinggemma";
+    const batchSize = options.batchSize ?? DEFAULT_BATCH_SIZE;
+    const doFetch = options.fetchImpl ?? fetch;
+    const url = assertLoopback(baseUrl);
+    assertNotCloudModel(model);
+    const showResponse = await doFetch(new URL("/api/show", url), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ model }),
+    });
+    if (showResponse.ok) {
+        const show = (await showResponse.json());
+        if (show.remote_host || show.remote_model) {
+            throw new RemoteEmbedderRefusedError(`refusing model '${model}' — Ollama reports it as remote (${show.remote_host ?? show.remote_model})`);
+        }
+    }
+    const embed = async (texts) => {
+        const out = [];
+        for (let start = 0; start < texts.length; start += batchSize) {
+            const batch = texts.slice(start, start + batchSize);
+            const response = await doFetch(new URL("/api/embed", url), {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ model, input: batch }),
+            });
+            if (!response.ok) {
+                throw new Error(`Ollama /api/embed failed with status ${response.status}: ${await response.text()}`);
+            }
+            const body = (await response.json());
+            for (const embedding of body.embeddings)
+                out.push(new Float32Array(embedding));
+        }
+        return out;
+    };
+    const probe = await embed(["dimension probe"]);
+    const dimensions = probe[0]?.length ?? 0;
+    if (dimensions <= 0)
+        throw new Error(`Ollama returned an empty embedding for model '${model}'`);
+    return { model, dimensions, embed };
+}
+//# sourceMappingURL=ollama-embedder.js.map

package/dist/infrastructure/providers/openai-compatible.js

@@ -0,0 +1,268 @@
+import { redactRuntimeText } from "@ocean/core/domain/redaction/redaction.js";
+import { DEFAULT_MAX_OUTPUT_BYTES } from "../process/cli-process.js";
+// OpenAI-compatible chat completions over built-in fetch (T-245 Phase 4). Endpoints and
+// credential variable names are fixed here, never taken from a profile, so a profile cannot
+// send a credential to another host or read another provider's credential. Checked against
+// the providers' docs on 2026-10-05 (see the T-245 plan).
+export const completionEndpoints = {
+    deepseek: "https://api.deepseek.com/chat/completions",
+    openrouter: "https://openrouter.ai/api/v1/chat/completions",
+};
+export const completionCredentialEnv = {
+    deepseek: "DEEPSEEK_API_KEY",
+    openrouter: "OPENROUTER_API_KEY",
+};
+const DEFAULT_TIMEOUT_MS = 60_000;
+const MAX_COMPLETION_TOKENS = 8_192;
+const BACKOFF_BASE_MS = 500;
+const BACKOFF_MAX_MS = 8_000;
+class CompletionFailure extends Error {
+    exitCode;
+    constructor(message, exitCode) {
+        super(message);
+        this.exitCode = exitCode;
+    }
+}
+function abortableSleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted)
+            return reject(signal.reason);
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+// Reads at most `maxBytes` of the body; a larger body is cancelled, never buffered whole.
+async function readBounded(response, maxBytes) {
+    if (!response.body)
+        return "";
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel();
+            throw new CompletionFailure("Output budget exceeded.", 125);
+        }
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+function retryDelay(response, attempt) {
+    const header = Number(response.headers.get("retry-after"));
+    const backoff = BACKOFF_BASE_MS * 2 ** (attempt - 1);
+    return Math.min(BACKOFF_MAX_MS, Number.isFinite(header) && header > 0 ? header * 1_000 : backoff);
+}
+function rateLimit(response) {
+    return Object.fromEntries([...response.headers].filter(([name]) => name.startsWith("x-ratelimit-") || name === "retry-after"));
+}
+const MAX_TOOL_CALLS_PER_REPLY = 16;
+function parseToolCalls(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (!Array.isArray(value) || value.length > MAX_TOOL_CALLS_PER_REPLY)
+        throw new CompletionFailure("Malformed completion response: tool_calls", 1);
+    return value.map((call) => {
+        const { id, function: fn } = (call ?? {});
+        if (typeof id !== "string" ||
+            typeof fn?.name !== "string" ||
+            typeof fn.arguments !== "string")
+            throw new CompletionFailure("Malformed completion response: tool_calls", 1);
+        return {
+            id,
+            type: "function",
+            function: { name: fn.name, arguments: fn.arguments },
+        };
+    });
+}
+function parseReply(source, fallbackModel) {
+    let body;
+    try {
+        body = JSON.parse(source);
+    }
+    catch {
+        throw new CompletionFailure("Malformed completion response: not JSON", 1);
+    }
+    const message = body?.choices?.[0]?.message;
+    const toolCalls = parseToolCalls(message?.tool_calls);
+    const content = message?.content ?? null;
+    if (typeof content !== "string" && !(content === null && toolCalls?.length))
+        throw new CompletionFailure("Malformed completion response: no choices[0].message.content", 1);
+    return {
+        message: {
+            role: "assistant",
+            content,
+            ...(toolCalls?.length ? { tool_calls: toolCalls } : {}),
+        },
+        model: typeof body.model === "string" ? body.model : fallbackModel,
+        usage: body.usage ?? null,
+        id: typeof body.id === "string" ? body.id : null,
+    };
+}
+// One chat turn: credential check, request, bounded read, transient retries. Throws a
+// CompletionFailure (with its exit code) on anything else.
+async function chat(request, deps, emit, signal) {
+    const endpoint = deps.endpoints[request.provider];
+    const credentialName = completionCredentialEnv[request.provider];
+    if (!endpoint)
+        throw new CompletionFailure(`Unsupported completion provider: ${request.provider}`, 1);
+    // Fails before any request is made; names the variable, never its value.
+    const credential = deps.env[credentialName];
+    if (!credential)
+        throw new CompletionFailure(`Missing credential: set ${credentialName} in the environment`, 1);
+    const maxBytes = request.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+    const attempts = Math.max(1, request.maxAttempts ?? 1);
+    for (let attempt = 1;; attempt += 1) {
+        const response = await deps.fetch(endpoint, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${credential}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                model: request.model,
+                messages: request.messages,
+                max_tokens: MAX_COMPLETION_TOKENS,
+                stream: false,
+                ...(request.temperature === undefined
+                    ? {}
+                    : { temperature: request.temperature }),
+                ...(request.tools.length ? { tools: request.tools } : {}),
+            }),
+            // A redirect could carry the credential to another host; it is an error instead.
+            redirect: "error",
+            signal,
+        });
+        const meta = {
+            provider: request.provider,
+            status: response.status,
+            requestId: response.headers.get("x-request-id"),
+            rateLimit: rateLimit(response),
+            attempt,
+        };
+        if (response.ok)
+            return {
+                ...parseReply(await readBounded(response, maxBytes), request.model),
+                meta,
+            };
+        // Only 429 and 5xx are transient. Authentication, validation and policy failures are
+        // never retried.
+        const transient = response.status === 429 || response.status >= 500;
+        // An upstream error body is untrusted: it could echo the request back, so the credential
+        // is removed before it reaches stderr or the session.
+        const detail = redactRuntimeText((await readBounded(response, 4_096).catch(() => ""))
+            .split(credential)
+            .join("[REDACTED]")
+            .slice(0, 500));
+        if (!transient || attempt >= attempts) {
+            await response.body?.cancel().catch(() => undefined);
+            throw new CompletionFailure(`Completion request failed: HTTP ${response.status}${detail ? ` ${detail}` : ""}`, 1);
+        }
+        const delayMs = retryDelay(response, attempt);
+        emit({
+            type: "json",
+            data: { type: "completion_retry", ...meta, delayMs },
+        });
+        await deps.sleep(delayMs, signal);
+    }
+}
+async function complete(request, deps, emit, signal) {
+    const started = Date.now();
+    const reply = await chat({
+        provider: request.provider,
+        model: request.model,
+        temperature: request.temperature,
+        messages: [{ role: "user", content: request.prompt }],
+        tools: [],
+        maxOutputBytes: request.maxOutputBytes,
+        maxAttempts: request.maxAttempts,
+    }, deps, emit, signal);
+    if (typeof reply.message.content !== "string")
+        throw new CompletionFailure("Malformed completion response: no choices[0].message.content", 1);
+    emit({
+        type: "json",
+        data: {
+            type: "completion",
+            ...reply.meta,
+            id: reply.id,
+            model: reply.model,
+            usage: reply.usage,
+            durationMs: Date.now() - started,
+            text: reply.message.content,
+        },
+    });
+}
+function defaultDeps(overrides) {
+    return {
+        // Resolved per call, so a fetch installed after import is the one used.
+        fetch: (...args) => globalThis.fetch(...args),
+        endpoints: completionEndpoints,
+        env: process.env,
+        sleep: abortableSleep,
+        ...overrides,
+    };
+}
+// The tool loop's transport: one turn per call, under the caller's signal. A failure is
+// thrown with an `exitCode` (124 when the caller's deadline aborted it).
+export function createChatTransport(overrides = {}) {
+    const deps = defaultDeps(overrides);
+    return async ({ signal, onEvent, ...request }) => {
+        try {
+            const { meta: _meta, ...reply } = await chat(request, deps, (event) => onEvent?.(event), signal);
+            return reply;
+        }
+        catch (error) {
+            if (error instanceof CompletionFailure)
+                throw error;
+            if (signal.aborted)
+                throw signal.reason;
+            throw new CompletionFailure(`Completion request failed: ${error.message}`, 1);
+        }
+    };
+}
+export const chatTransport = createChatTransport();
+export function createCompletionExecutor(overrides = {}) {
+    const deps = defaultDeps(overrides);
+    return async (request) => {
+        const events = [];
+        const emit = (event) => {
+            events.push(event);
+            request.onEvent?.(event);
+        };
+        // One deadline covers every attempt and every backoff.
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(new CompletionFailure("Process timed out.", 124)), request.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        try {
+            await complete(request, deps, emit, controller.signal);
+            return { exitCode: 0, events, stderr: "" };
+        }
+        catch (error) {
+            const failure = error instanceof CompletionFailure
+                ? error
+                : controller.signal.aborted &&
+                    controller.signal.reason instanceof CompletionFailure
+                    ? controller.signal.reason
+                    : new CompletionFailure(`Completion request failed: ${error.message}`, 1);
+            return {
+                exitCode: failure.exitCode,
+                events,
+                stderr: `${failure.message}\n`,
+            };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+}
+export const runCompletion = createCompletionExecutor();
+//# sourceMappingURL=openai-compatible.js.map