@amoree-code/ocean 0.0.0-stage → 1.1.0

package/dist/infrastructure/process/interactive-process.js

@@ -0,0 +1,145 @@
+import { spawn } from "node:child_process";
+import { accessSync, chmodSync, constants } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+// node-pty is optional: it has no Linux prebuild, so npm compiles it there and skips it when no
+// compiler toolchain is present. Without it, a provider still runs, attached to this terminal
+// directly, but its terminal output is not recorded.
+let ptyModule;
+const loadPty = () => (ptyModule ??= import("node-pty").catch(() => undefined));
+// node-pty's npm tarball ships its macOS spawn-helper without the executable bit, so every pty
+// spawn fails after a plain `npm install`. Restore the bit once, before the first spawn.
+let spawnHelperChecked = false;
+function ensureSpawnHelperExecutable() {
+    if (spawnHelperChecked || process.platform === "win32")
+        return;
+    spawnHelperChecked = true;
+    const root = path.resolve(path.dirname(createRequire(import.meta.url).resolve("node-pty")), "..");
+    for (const helper of [
+        path.join(root, "prebuilds", `${process.platform}-${process.arch}`, "spawn-helper"),
+        path.join(root, "build", "Release", "spawn-helper"),
+    ]) {
+        try {
+            accessSync(helper, constants.X_OK);
+        }
+        catch {
+            try {
+                chmodSync(helper, 0o755);
+            }
+            catch {
+                // Missing (a native build provides its own) or not ours to change: the spawn reports it.
+            }
+        }
+    }
+}
+export async function runInteractive(request) {
+    const pty = await loadPty();
+    if (!pty) {
+        process.stderr.write("ocean: node-pty is not installed, so this session's terminal output is not recorded (see docs/troubleshooting.md)\n");
+        return await runPassthrough(request);
+    }
+    return await new Promise((resolve, reject) => {
+        let terminal;
+        try {
+            ensureSpawnHelperExecutable();
+            terminal = pty.spawn(request.command, request.args, {
+                name: process.env.TERM || "xterm-256color",
+                cols: process.stdout.columns || 120,
+                rows: process.stdout.rows || 40,
+                cwd: request.cwd,
+                env: { ...process.env, ...request.env },
+            });
+        }
+        catch (error) {
+            reject(error);
+            return;
+        }
+        let output = "";
+        let timedOut = false;
+        let cancelled = false;
+        let timer;
+        let forceKillTimer;
+        const maxCapture = 64_000;
+        const onData = (data) => {
+            if (output.length < maxCapture)
+                output += data.slice(0, maxCapture - output.length);
+            process.stdout.write(data);
+            request.onData?.(data.slice(0, 64_000));
+        };
+        terminal.onData(onData);
+        const stdinIsTTY = Boolean(process.stdin.isTTY && process.stdin.setRawMode);
+        const onStdin = (data) => {
+            const input = data.toString();
+            request.onInput?.(input);
+            terminal.write(input);
+        };
+        if (stdinIsTTY) {
+            process.stdin.setRawMode?.(true);
+            process.stdin.resume();
+            process.stdin.on("data", onStdin);
+        }
+        const onResize = () => terminal.resize(process.stdout.columns || 120, process.stdout.rows || 40);
+        process.stdout.on("resize", onResize);
+        const stop = (reason) => {
+            if (reason === "timeout")
+                timedOut = true;
+            else
+                cancelled = true;
+            terminal.kill("SIGTERM");
+            forceKillTimer = setTimeout(() => terminal.kill("SIGKILL"), 100);
+        };
+        const onAbort = () => stop("cancel");
+        if (request.timeoutMs !== undefined)
+            timer = setTimeout(() => stop("timeout"), request.timeoutMs);
+        request.signal?.addEventListener("abort", onAbort, { once: true });
+        if (request.signal?.aborted)
+            onAbort();
+        terminal.onExit(({ exitCode }) => {
+            if (timer)
+                clearTimeout(timer);
+            if (forceKillTimer)
+                clearTimeout(forceKillTimer);
+            request.signal?.removeEventListener("abort", onAbort);
+            if (stdinIsTTY) {
+                process.stdin.off("data", onStdin);
+                process.stdin.setRawMode?.(false);
+                process.stdin.pause();
+            }
+            process.stdout.off("resize", onResize);
+            resolve({ exitCode, output, timedOut, cancelled });
+        });
+    });
+}
+export function runPassthrough(request) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(request.command, request.args, {
+            cwd: request.cwd,
+            env: { ...process.env, ...request.env },
+            stdio: "inherit",
+        });
+        const timer = request.timeoutMs === undefined
+            ? undefined
+            : setTimeout(() => child.kill("SIGTERM"), request.timeoutMs);
+        const onAbort = () => {
+            child.kill("SIGTERM");
+        };
+        request.signal?.addEventListener("abort", onAbort, { once: true });
+        child.once("error", (error) => {
+            if (timer)
+                clearTimeout(timer);
+            request.signal?.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+        child.once("close", (exitCode) => {
+            if (timer)
+                clearTimeout(timer);
+            request.signal?.removeEventListener("abort", onAbort);
+            resolve({
+                exitCode: exitCode ?? 1,
+                output: "",
+                cancelled: request.signal?.aborted,
+            });
+        });
+    });
+}
+//# sourceMappingURL=interactive-process.js.map

package/dist/infrastructure/process/process-supervisor.js

@@ -0,0 +1,194 @@
+import { StringDecoder } from "node:string_decoder";
+// The one place that decides how a headless run ends, for every provider that runs a process: the
+// run's timeout (124), its output budget (125), the process group it runs in, the signals passed
+// on to it, and how stdout becomes lines. `runHeadless` (CLI providers) and the Claude Agent SDK
+// runner both use it, so a fix to any of these lands once.
+// A process run in its own group is stopped as a whole, so a timeout or budget stop ends
+// everything it started (a tool's subprocess too), not just the leader: a surviving descendant
+// would hold the output pipe open and keep the run waiting.
+export const ownsGroup = process.platform !== "win32";
+const forwardedSignals = ["SIGINT", "SIGTERM", "SIGHUP"];
+// How long output still in the pipe gets, once the process itself has exited, before whatever
+// else holds the pipe open (a background process it left behind) is stopped and no longer awaited.
+const LINGER_MS = 500;
+export function signalTree(child, signal) {
+    if (!child?.pid)
+        return;
+    try {
+        if (ownsGroup)
+            process.kill(-child.pid, signal);
+        else
+            child.kill(signal);
+    }
+    catch {
+        // Already gone.
+    }
+}
+// Out of the terminal's process group, a run no longer receives this process's Ctrl+C or kill
+// directly; pass them on, then let the signal do what it would have done here. One set of
+// listeners serves every run in flight, so many concurrent runs never trip Node's listener warning.
+const active = new Set();
+let listening = false;
+const onExit = () => {
+    for (const child of active)
+        signalTree(child, "SIGTERM");
+};
+const onSignal = (signal) => {
+    onExit();
+    unlisten();
+    if (process.listenerCount(signal) === 0)
+        process.kill(process.pid, signal);
+};
+function unlisten() {
+    if (!listening)
+        return;
+    listening = false;
+    process.off("exit", onExit);
+    for (const signal of forwardedSignals)
+        process.off(signal, onSignal);
+}
+function endWithThisProcess(child) {
+    if (!listening) {
+        listening = true;
+        process.once("exit", onExit);
+        for (const signal of forwardedSignals)
+            process.on(signal, onSignal);
+    }
+    active.add(child);
+    return () => {
+        active.delete(child);
+        if (active.size === 0)
+            unlisten();
+    };
+}
+export function superviseProcess(options) {
+    let child;
+    let release = () => { };
+    let spawnError;
+    let stderr = "";
+    let outputBytes = 0;
+    let timedOut = false;
+    let outputLimitExceeded = false;
+    let terminating = false;
+    let killTimer;
+    let lingerTimer;
+    let letGoNow = () => { };
+    const released = new Promise((resolve) => {
+        letGoNow = resolve;
+    });
+    let closedNow = () => { };
+    const closed = new Promise((resolve) => {
+        closedNow = resolve;
+    });
+    // Whatever still holds the pipes (a descendant that left the group) no longer holds the run.
+    const letGo = () => {
+        child?.stdout?.destroy();
+        child?.stderr?.destroy();
+        letGoNow();
+    };
+    const terminate = () => {
+        if (terminating)
+            return;
+        terminating = true;
+        options.onTerminate?.();
+        signalTree(child, "SIGTERM");
+        // Not unref'd: this timer keeps the process alive until the run has been let go.
+        killTimer = setTimeout(() => {
+            signalTree(child, "SIGKILL");
+            letGo();
+        }, 100);
+    };
+    // Armed until the process has closed, not just until the output stops.
+    const timer = setTimeout(() => {
+        timedOut = true;
+        terminate();
+    }, options.timeoutMs);
+    // Raw stdout and stderr bytes count against one budget as they arrive, before anything buffers
+    // a line, so a huge or unterminated line cannot grow past the cap.
+    const withinBudget = (bytes) => {
+        if (outputLimitExceeded)
+            return false;
+        if (outputBytes + bytes > options.maxOutputBytes) {
+            outputLimitExceeded = true;
+            terminate();
+            return false;
+        }
+        outputBytes += bytes;
+        return true;
+    };
+    const decoder = new StringDecoder("utf8");
+    let pending = "";
+    const emit = (line) => {
+        if (line)
+            options.onLine?.(line);
+    };
+    return {
+        attach(spawned) {
+            child = spawned;
+            if (ownsGroup)
+                release = endWithThisProcess(spawned);
+            // A failed start (no such executable) is a failed run; the abort of a stop we asked for is not.
+            spawned.once("error", (error) => {
+                if (terminating)
+                    return;
+                spawnError = error;
+                letGo();
+            });
+            spawned.once("exit", () => {
+                if (!terminating)
+                    lingerTimer = setTimeout(letGo, LINGER_MS);
+            });
+            spawned.once("close", closedNow);
+            spawned.stdout?.on("data", (chunk) => {
+                if (!withinBudget(chunk.byteLength))
+                    return;
+                pending += decoder.write(chunk);
+                const lines = pending.split(/\r?\n/);
+                pending = lines.pop() ?? "";
+                for (const line of lines)
+                    emit(line);
+            });
+            spawned.stderr?.on("data", (chunk) => {
+                if (withinBudget(chunk.byteLength))
+                    stderr += chunk.toString("utf8");
+            });
+        },
+        closed,
+        released,
+        get spawnError() {
+            return spawnError;
+        },
+        get timedOut() {
+            return timedOut;
+        },
+        get outputLimitExceeded() {
+            return outputLimitExceeded;
+        },
+        get stderr() {
+            return stderr;
+        },
+        get stopNote() {
+            return timedOut
+                ? "Process timed out.\n"
+                : outputLimitExceeded
+                    ? "Output budget exceeded.\n"
+                    : "";
+        },
+        exitCode(code) {
+            return timedOut ? 124 : outputLimitExceeded ? 125 : (code ?? 1);
+        },
+        flush() {
+            emit(pending + decoder.end());
+            pending = "";
+        },
+        finish() {
+            clearTimeout(timer);
+            clearTimeout(lingerTimer);
+            clearTimeout(killTimer);
+            // The leader is gone; end anything it left in the group, then stop watching it.
+            signalTree(child, "SIGKILL");
+            release();
+        },
+    };
+}
+//# sourceMappingURL=process-supervisor.js.map

package/dist/infrastructure/process/service.js

@@ -0,0 +1,252 @@
+import { execFile, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { reindexBrain } from "@ocean/brain/brain/brain-reindex.js";
+import { brainIndexState } from "@ocean/brain/brain/brain-service.js";
+import { brainIndexPort } from "@ocean/brain/infrastructure/brain/brain-index.js";
+import { loadObsidianConnection } from "@ocean/services/obsidian/vault-discovery.js";
+import { watchObsidianVault } from "@ocean/services/obsidian/vault-sync.js";
+import { refreshClaudeProjects } from "../../application/pull/server-capture.js";
+import { createOllamaEmbedder } from "../providers/ollama-embedder.js";
+const HOUR_MS = 60 * 60 * 1000;
+const REINDEX_CHECK_MS = 2 * 60 * 1000;
+const CLAUDE_PROJECTS_MS = 15 * 60 * 1000;
+let reindexing = false;
+// Keeps the brain index current (T-307): a record written over MCP, an approval or a hand edit is
+// searchable within minutes, without `ocean memory reindex`. The build goes to a temp file renamed
+// into place, so a search never reads half an index. Vectors when the local embedder answers;
+// without one, an index that has vectors waits for it rather than losing them, and one without is
+// rebuilt as full text. OCEAN_NO_AUTO_REINDEX=1 turns it off.
+export async function reindexWhenStale(options = {}) {
+    if (process.env.OCEAN_NO_AUTO_REINDEX === "1")
+        return "off";
+    if (reindexing)
+        return "busy";
+    reindexing = true;
+    try {
+        const state = await brainIndexState({
+            root: options.root,
+            indexPort: brainIndexPort,
+        });
+        if (!state.stale)
+            return "fresh";
+        const embedder = await (options.embedder ?? (() => createOllamaEmbedder()))().catch(() => null);
+        if (!embedder && state.hasVectors)
+            return "waiting";
+        await reindexBrain({
+            root: options.root,
+            embedder,
+            indexPort: brainIndexPort,
+        });
+        return "rebuilt";
+    }
+    finally {
+        reindexing = false;
+    }
+}
+// The owner's Claude project names, so a conversation in a new Claude project can register it
+// (T-307). Reading the caches takes tens of seconds, so it runs here, never in a tool call.
+function startClaudeProjectsRefresh() {
+    if (process.env.OCEAN_NO_PULL_ON_START === "1")
+        return;
+    refreshClaudeProjects(os.homedir()).catch((error) => {
+        console.error(`Claude project names not refreshed: ${error instanceof Error ? error.message : String(error)}`);
+    });
+}
+function startAutoReindex() {
+    reindexWhenStale().catch((error) => {
+        console.error(`brain reindex failed: ${error instanceof Error ? error.message : String(error)}`);
+    });
+}
+// The daily `ocean pull --yes` (T-305) in a detached child; it returns at once when the last pull
+// is under a day old. Session starts run it, and so does the always-on service, so a user who only
+// opens Claude Desktop is pulled too. OCEAN_NO_PULL_ON_START=1 turns both off.
+export function startBackgroundPull() {
+    if (process.env.OCEAN_NO_PULL_ON_START === "1")
+        return;
+    try {
+        spawn(process.execPath, [process.argv[1], "pull", "--yes", "--daily"], {
+            detached: true,
+            stdio: "ignore",
+        })
+            .on("error", () => { })
+            .unref();
+    }
+    catch {
+        // no pull this time; the next try runs it
+    }
+}
+const runCommand = (command, args) => promisify(execFile)(command, args);
+function serviceContext(options) {
+    const home = options.home ?? os.homedir();
+    const domain = `gui/${process.getuid?.() ?? ""}`;
+    return {
+        home,
+        platform: options.platform ?? process.platform,
+        run: options.run ?? runCommand,
+        wait: options.wait ??
+            ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+        plist: path.join(home, "Library", "LaunchAgents", "com.ocean.runtime.plist"),
+        unit: path.join(home, ".config", "systemd", "user", "ocean.service"),
+        domain,
+        label: `${domain}/com.ocean.runtime`,
+    };
+}
+const loaded = (context) => context.run("launchctl", ["print", context.label]).then(() => true, () => false);
+// Loads the launchd job: three tries a second apart, then the error names the command that
+// starts it, since nothing else would retry it.
+async function bootstrap(context) {
+    let failure;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        if (attempt)
+            await context.wait(1000);
+        try {
+            await context.run("launchctl", [
+                "bootstrap",
+                context.domain,
+                context.plist,
+            ]);
+            return;
+        }
+        catch (error) {
+            failure = error;
+        }
+    }
+    throw new Error(`${failure instanceof Error ? failure.message : String(failure)} — the service is stopped; start it with: launchctl bootstrap ${context.domain} ${context.plist}`);
+}
+// A running service keeps the engine it started with, whatever `current` or its start file now
+// say (T-305), so a new build or a repointed start file restarts it. With the start file
+// unchanged (`reload: false`), launchd's kickstart restarts the process while the job stays
+// loaded, so KeepAlive covers it throughout (T-307). A changed file needs the job unloaded and
+// loaded again: bootout returns before launchd has removed the job, and a bootstrap while it is
+// still there fails ("Bootstrap failed: 5: Input/output error"), so it waits until `print` no
+// longer finds it (up to 5 s) and retries. systemd re-reads the unit on reload; the Windows
+// startup script has no manager and takes effect at next login. Never throws: it runs inside
+// session starts, which must not fail on it.
+export async function restartService(options = {}) {
+    const context = serviceContext(options);
+    const { run, wait } = context;
+    try {
+        if (context.platform === "darwin") {
+            if (!existsSync(context.plist))
+                return "not-installed";
+            if (options.reload === false) {
+                const kicked = await run("launchctl", [
+                    "kickstart",
+                    "-k",
+                    context.label,
+                ]).then(() => true, () => false);
+                if (!kicked)
+                    await bootstrap(context);
+                return "restarted";
+            }
+            await run("launchctl", ["bootout", context.label]).catch(() => { });
+            for (let poll = 0; poll < 20 && (await loaded(context)); poll += 1)
+                await wait(250);
+            await bootstrap(context);
+            return "restarted";
+        }
+        if (context.platform === "linux") {
+            if (!existsSync(context.unit))
+                return "not-installed";
+            await run("systemctl", ["--user", "daemon-reload"]);
+            await run("systemctl", ["--user", "try-restart", "ocean.service"]);
+            return "restarted";
+        }
+        const startup = path.join(process.env.APPDATA ?? path.join(context.home, "AppData", "Roaming"), "Microsoft", "Windows", "Start Menu", "Programs", "Startup", "ocean.cmd");
+        return context.platform === "win32" && existsSync(startup)
+            ? "next-login"
+            : "not-installed";
+    }
+    catch (error) {
+        return { failed: error instanceof Error ? error.message : String(error) };
+    }
+}
+// The safety net (T-307): every session start makes sure an installed service is loaded and
+// running, so nothing — a failed restart, a manual bootout — leaves it stopped past the next
+// session. Windows has no service manager to ask. Never throws.
+export async function ensureService(options = {}) {
+    const context = serviceContext(options);
+    try {
+        if (context.platform === "darwin") {
+            if (!existsSync(context.plist))
+                return "not-installed";
+            if (await loaded(context))
+                return "running";
+            await bootstrap(context);
+            return "started";
+        }
+        if (context.platform === "linux") {
+            if (!existsSync(context.unit))
+                return "not-installed";
+            const active = await context
+                .run("systemctl", ["--user", "is-active", "--quiet", "ocean.service"])
+                .then(() => true, () => false);
+            if (active)
+                return "running";
+            await context.run("systemctl", ["--user", "start", "ocean.service"]);
+            return "started";
+        }
+        return "unchecked";
+    }
+    catch (error) {
+        return { failed: error instanceof Error ? error.message : String(error) };
+    }
+}
+export async function runService(shutdownAfterMs) {
+    const controller = new AbortController();
+    let watcher;
+    try {
+        const connection = await loadObsidianConnection();
+        watcher = watchObsidianVault(connection, undefined, controller.signal).catch((error) => {
+            console.error(`Obsidian watcher stopped: ${error instanceof Error ? error.message : String(error)}`);
+        });
+        console.log(`Obsidian watcher enabled: ${connection.vaultPath}`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            console.error(`Obsidian watcher unavailable: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const heartbeat = setInterval(() => undefined, 60_000);
+    startBackgroundPull();
+    const dailyPull = setInterval(startBackgroundPull, HOUR_MS);
+    startAutoReindex();
+    const autoReindex = setInterval(startAutoReindex, REINDEX_CHECK_MS);
+    startClaudeProjectsRefresh();
+    const claudeProjects = setInterval(startClaudeProjectsRefresh, CLAUDE_PROJECTS_MS);
+    await new Promise((resolve) => {
+        let testShutdown;
+        const shutdown = (signal) => {
+            console.log(`Ocean runtime received ${signal}, shutting down.`);
+            clearInterval(heartbeat);
+            clearInterval(dailyPull);
+            clearInterval(autoReindex);
+            clearInterval(claudeProjects);
+            controller.abort();
+            process.off("SIGINT", shutdown);
+            process.off("SIGTERM", shutdown);
+            process.off("message", onMessage);
+            if (testShutdown)
+                clearTimeout(testShutdown);
+            resolve();
+        };
+        const onMessage = (message) => {
+            if (message === "shutdown")
+                shutdown("IPC");
+        };
+        process.on("SIGINT", shutdown);
+        process.on("SIGTERM", shutdown);
+        process.on("message", onMessage);
+        // Only now is a SIGTERM handled gracefully; announcing earlier lets a signal that
+        // arrives during startup kill the process before it can shut down cleanly.
+        console.log("Ocean runtime is running.");
+        if (shutdownAfterMs !== undefined)
+            testShutdown = setTimeout(() => shutdown("timer"), shutdownAfterMs);
+    });
+    await watcher;
+    console.log("Ocean runtime stopped.");
+}
+//# sourceMappingURL=service.js.map

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-provider.js.map