@amoree-code/ocean 0.0.0-stage → 1.1.0

package/node_modules/@ocean/brain/dist/memory/brain-dump.js

@@ -0,0 +1,145 @@
+import { mkdir, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { redactRuntimeText } from "@ocean/core/domain/redaction/redaction.js";
+import { localDate, localMoment, localTime, } from "@ocean/core/shared/local-date.js";
+import { INBOX_DIR, oceanPath, oceanRoot } from "@ocean/core/shared/paths.js";
+import { findGitRoot } from "@ocean/core/shared/project-resolution.js";
+// Same fallback title stamped on a session with no explicit title (see
+// daily-narrative.ts) — never meaningful content on its own.
+const GENERIC_TITLE = /^(claude|codex|hermes|kimi|gemini|copilot|kilo|antigravity|openhands) session$/i;
+function safeText(value, max = 400) {
+    return redactRuntimeText(value).replace(/\s+/g, " ").trim().slice(0, max);
+}
+function isGenericContent(text) {
+    const trimmed = (text ?? "").trim();
+    return trimmed.length === 0 || GENERIC_TITLE.test(trimmed);
+}
+const MIN_USEFUL_SLUG_LENGTH = 3;
+// ASCII-only by design: ranks a Latin-alphabet slug of the title over one
+// derived from the (already ASCII) project name, and falls back to the
+// session id only when both are too short to be useful — e.g. a title in a
+// non-Latin script, where this strips down to nothing.
+function slugify(text, maxLength = 60) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, maxLength)
+        .replace(/-+$/g, "");
+}
+async function uniqueFilename(directory, base, ext) {
+    let existing;
+    try {
+        existing = new Set(await readdir(directory));
+    }
+    catch {
+        existing = new Set();
+    }
+    if (!existing.has(`${base}${ext}`))
+        return `${base}${ext}`;
+    for (let suffix = 2; suffix < 1000; suffix++) {
+        const candidate = `${base}-${suffix}${ext}`;
+        if (!existing.has(candidate))
+            return candidate;
+    }
+    return `${base}-${Date.now()}${ext}`;
+}
+/**
+ * One human-readable Markdown file per session under brain/00-inbox/brain-dump/,
+ * separate from the machine-oriented kernel/bridge/sessions/summaries/ dump. Prefers
+ * the cheap model narrative (see model-narrative.ts) and falls back to the
+ * same deterministic heuristics as daily-narrative.ts when it is unavailable.
+ * When lesson-learning.ts already found signals for this session (corrections,
+ * repeated procedures, explicit decisions), they're mirrored under
+ * "## Signals" — the same events already surfaced in brain/01-daily/, so a
+ * later cross-session sweep has one place to look instead of two.
+ *
+ * Skipped for the same low-value case daily-narrative.ts skips: a generic
+ * title with no real (git) project behind it — nothing a human would want to
+ * read later.
+ */
+export async function writeBrainDump(input) {
+    const { session, events, narrative, changedFiles, observations } = input;
+    const workLog = narrative?.workLog ??
+        (() => {
+            const objectiveEvent = events.find((event) => event.type === "user_input" || event.type === "resume_requested");
+            return safeText(objectiveEvent?.data ?? session.title, 200);
+        })();
+    const hasRealProject = findGitRoot(session.workingDirectory) !== null;
+    if (isGenericContent(workLog) && !hasRealProject)
+        return null;
+    const decision = narrative?.decision ??
+        events
+            .filter((event) => event.type === "provider_output" ||
+            event.type === "text" ||
+            event.type === "json")
+            .map((event) => safeText(event.data, 500))
+            .find((text) => /\bdecision\s*:/i.test(text));
+    const problem = narrative?.problem ??
+        events
+            .filter((event) => event.type === "error" || event.type === "provider_blocked")
+            .map((event) => safeText(event.data, 500))[0];
+    const nextAction = narrative?.next ?? input.nextAction ?? session.nextAction;
+    const hasNextAction = nextAction &&
+        nextAction !== "Review the summary and verify the next action.";
+    const started = localMoment(session.createdAt);
+    const time = localTime(started);
+    const date = localDate(started);
+    const project = path.basename(session.workingDirectory) || session.workingDirectory;
+    const status = session.status === "completed" && (input.exitCode ?? 0) === 0
+        ? "completed"
+        : "failed";
+    const title = isGenericContent(workLog) ? project : workLog;
+    const lines = [
+        `# ${title}`,
+        "",
+        `- Date: ${date} ${time}`,
+        `- Provider: ${session.provider}`,
+        `- Project: ${project}`,
+        `- Status: ${status}`,
+        "",
+        "## What happened",
+        "",
+        workLog || "No objective was captured.",
+        ...(decision ? ["", "## Decision", "", decision] : []),
+        ...(problem ? ["", "## Problem", "", problem] : []),
+        ...(changedFiles.length
+            ? [
+                "",
+                "## Files changed",
+                "",
+                ...changedFiles.map((f) => `- ${safeText(f, 240)}`),
+            ]
+            : []),
+        ...(hasNextAction
+            ? ["", "## Next", "", safeText(nextAction, 300)]
+            : []),
+        ...(observations?.length
+            ? [
+                "",
+                "## Signals",
+                "",
+                ...observations.map((o) => `- [${o.signalType}] ${safeText(o.summary, 300)} (confidence ${o.confidence})`),
+            ]
+            : []),
+        "",
+        "---",
+        "",
+        `Session id: ${session.sessionId} · Raw events: \`ocean session events ${session.sessionId}\``,
+    ];
+    const directory = oceanPath(INBOX_DIR, "brain-dump");
+    await mkdir(directory, { recursive: true });
+    const titleSlug = slugify(title);
+    const slug = titleSlug.length >= MIN_USEFUL_SLUG_LENGTH
+        ? titleSlug
+        : slugify(project).length >= MIN_USEFUL_SLUG_LENGTH
+            ? slugify(project)
+            : session.sessionId.slice(0, 8);
+    const filename = await uniqueFilename(directory, `${date}-${time.replace(":", "")}-${slug}`, ".md");
+    const file = path.join(directory, filename);
+    await writeFile(file, `${lines.join("\n")}\n`, "utf8");
+    return {
+        brainDumpPath: path.relative(oceanRoot(), file).split(path.sep).join("/"),
+    };
+}
+//# sourceMappingURL=brain-dump.js.map

package/node_modules/@ocean/brain/dist/memory/daily-narrative.js

@@ -0,0 +1,142 @@
+import { mkdir, readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { redactRuntimeText } from "@ocean/core/domain/redaction/redaction.js";
+import { atomicWrite, withFileLock } from "@ocean/core/shared/fs-utils.js";
+import { localDate } from "@ocean/core/shared/local-date.js";
+import { DAILY_DIR, oceanPath } from "@ocean/core/shared/paths.js";
+import { findGitRoot } from "@ocean/core/shared/project-resolution.js";
+const dailyTemplate = (date) => `# Daily — ${date}\n\n## Focus\n\n## Work log\n\n## Decisions\n\n## Problems\n\n## Next\n\n## Observations\n`;
+// The literal fallback title stamped on a session with no explicit title
+// (see run request construction) — never meaningful content on its own.
+const GENERIC_TITLE = /^claude session$/i;
+function safeText(value, max = 240) {
+    return redactRuntimeText(value).replace(/\s+/g, " ").trim().slice(0, max);
+}
+function isGenericContent(text) {
+    const trimmed = (text ?? "").trim();
+    return trimmed.length === 0 || GENERIC_TITLE.test(trimmed);
+}
+// Markup a client wraps around a prompt (`<ide_opened_file>…</ide_opened_file>`,
+// `<task-notification>…`) is not what the session was about. Client tags carry `_` or `-`,
+// which HTML tag names never do, so a prompt about `<button>Save</button>` keeps its words.
+const CLIENT_TAG = "[a-z][a-z0-9]*(?:[_-][a-z0-9]+)+";
+function withoutClientMarkup(text) {
+    return text
+        .replace(new RegExp(`<(${CLIENT_TAG})\\b[^>]*>[\\s\\S]*?<\\/\\1>`, "gi"), " ")
+        .replace(new RegExp(`<\\/?${CLIENT_TAG}\\b[^>]*>`, "gi"), " ");
+}
+// Local wall-clock date and time, like the SessionEnd hook's own line: a UTC stamp put one
+// session three hours apart in the same log, and after midnight UTC into another day's file.
+function localStamp(now = new Date()) {
+    const pad = (value) => String(value).padStart(2, "0");
+    return {
+        date: localDate(now),
+        time: `${pad(now.getHours())}:${pad(now.getMinutes())}`,
+    };
+}
+function insertUnderHeading(content, heading, line) {
+    // A client that reports one session end twice must not log it twice.
+    if (content.split("\n").includes(line))
+        return content;
+    const marker = `${heading}\n`;
+    const index = content.indexOf(marker);
+    if (index < 0)
+        return `${content.trimEnd()}\n\n${heading}\n${line}\n`;
+    const insertAt = index + marker.length;
+    return `${content.slice(0, insertAt)}${line}\n${content.slice(insertAt)}`;
+}
+// Read-modify-write of today's daily file. Two sessions closing out at once would otherwise
+// each write back their own copy and drop the other's lines (T-257), so it runs under the
+// file lock and lands atomically.
+async function updateDailyFile(update) {
+    const { date } = localStamp();
+    const directory = oceanPath(DAILY_DIR);
+    const file = path.join(directory, `${date}.md`);
+    await mkdir(directory, { recursive: true });
+    await withFileLock(file, async () => {
+        let content;
+        try {
+            content = await readFile(file, "utf8");
+        }
+        catch (error) {
+            // Only a missing file starts from the template: any other read failure must not
+            // replace a real day's log with an empty one.
+            if (error.code !== "ENOENT")
+                throw error;
+            content = dailyTemplate(date);
+        }
+        // A symlinked daily file keeps its link: the write goes to the real file.
+        const target = await realpath(file).catch(() => file);
+        await atomicWrite(target, update(content));
+    });
+}
+/**
+ * Human-readable narrative entry appended to today's
+ * brain/01-daily/YYYY-MM-DD.md at session closeout. A field from `narrative`
+ * (produced by a cheap model call — see model-narrative.ts) is used verbatim
+ * when present; any field it omits (including when the model call was
+ * skipped or failed entirely) falls back to the deterministic heuristic
+ * below, so this never depends on the model call succeeding.
+ */
+export async function appendDailyNarrative(input) {
+    const { session, events, narrative } = input;
+    const inserts = [];
+    const { time } = localStamp();
+    const project = path.basename(session.workingDirectory) || session.workingDirectory;
+    const status = session.status === "completed" && (input.exitCode ?? 0) === 0
+        ? "completed"
+        : "failed";
+    const workLog = narrative?.workLog ??
+        (() => {
+            const objectiveEvent = events.find((event) => event.type === "user_input" || event.type === "resume_requested");
+            // A prompt that was only client markup falls back to the session's title.
+            const prompt = safeText(withoutClientMarkup(objectiveEvent?.data ?? ""));
+            return safeText(prompt || session.title, 160);
+        })();
+    // Skip an entry with nothing to say (the SessionEnd hook already notes that a session
+    // ended), and the doubly-useless case: only the generic placeholder title AND no real
+    // project (root/home session, no git repo). A generic title in a real project, or real
+    // content with no project, still gets logged.
+    const hasRealProject = findGitRoot(session.workingDirectory) !== null;
+    const skipWorkLog = !workLog.trim() || (isGenericContent(workLog) && !hasRealProject);
+    if (!skipWorkLog) {
+        inserts.push([
+            "## Work log",
+            `- ${time} ${session.provider} session in ${project}: ${workLog} — ${status}`,
+        ]);
+    }
+    const decisionLine = narrative?.decision ??
+        events
+            .filter((event) => event.type === "provider_output" ||
+            event.type === "text" ||
+            event.type === "json")
+            .map((event) => safeText(event.data, 500))
+            .find((text) => /\bdecision\s*:/i.test(text));
+    if (decisionLine)
+        inserts.push(["## Decisions", `- ${decisionLine}`]);
+    const problemLine = narrative?.problem ??
+        events
+            .filter((event) => event.type === "error" || event.type === "provider_blocked")
+            .map((event) => safeText(event.data, 500))[0];
+    if (problemLine)
+        inserts.push(["## Problems", `- ${problemLine}`]);
+    const nextAction = narrative?.next ?? input.nextAction ?? session.nextAction;
+    if (nextAction &&
+        nextAction !== "Review the summary and verify the next action.") {
+        inserts.push(["## Next", `- [${project}] ${safeText(nextAction, 240)}`]);
+    }
+    await updateDailyFile((content) => inserts.reduce((next, [heading, line]) => insertUnderHeading(next, heading, line), content));
+}
+/**
+ * Appends newly detected observations (corrections, repeated procedures,
+ * explicit decisions, proven verifications — see lesson-learning.ts) to
+ * today's brain/01-daily/YYYY-MM-DD.md, so they surface next to the
+ * session narrative instead of sitting only in 05-knowledge/lessons.
+ */
+export async function appendObservations(session, observations) {
+    if (!observations.length)
+        return;
+    const project = path.basename(session.workingDirectory) || session.workingDirectory;
+    await updateDailyFile((content) => observations.reduce((next, observation) => insertUnderHeading(next, "## Observations", `- [${observation.signalType}] ${safeText(observation.summary, 300)} _(${project}, confidence ${observation.confidence})_`), content));
+}
+//# sourceMappingURL=daily-narrative.js.map

package/node_modules/@ocean/brain/dist/memory/index-sync.js

@@ -0,0 +1,124 @@
+import { readFileSync } from "node:fs";
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { oceanPath, STORE_DIR } from "@ocean/core/shared/paths.js";
+import { conflictsFile, lessonsDir } from "./lessons.js";
+const generatedStart = "## Records (generated)";
+async function markdownFiles(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (entry.name.startsWith(".") || entry.name === "archive")
+            continue;
+        const full = path.join(directory, entry.name);
+        if (entry.isDirectory())
+            files.push(...(await markdownFiles(full)));
+        else if (entry.name.endsWith(".md"))
+            files.push(full);
+    }
+    return files;
+}
+function title(content, fallback) {
+    const frontmatter = content.match(/^---\n([\s\S]*?)\n---/m)?.[1] ?? "";
+    const declared = frontmatter
+        .match(/^(?:title|name):\s*["']?(.+?)["']?\s*$/m)?.[1]
+        ?.trim();
+    if (declared)
+        return declared;
+    const heading = content.match(/^#\s+(.+)$/m)?.[1]?.trim();
+    if (heading &&
+        !/^(decision|discovery|failure|solution|research|result|architecture)$/i.test(heading))
+        return heading;
+    const summary = content
+        .replace(/^---[\s\S]*?---\s*/m, "")
+        .split("\n")
+        .map((line) => line.trim())
+        .find((line) => line &&
+        !line.startsWith("#") &&
+        !line.startsWith("`") &&
+        !line.startsWith("|") &&
+        !line.startsWith("-"));
+    if (summary)
+        return summary.replace(/[*_`]/g, "").slice(0, 120);
+    return (fallback.split("/").at(-1)?.replace(/\.md$/, "").replace(/[-_]+/g, " ") ??
+        fallback);
+}
+function relativeRecord(root, file) {
+    return path.relative(root, file).split(path.sep).join("/");
+}
+function links(content) {
+    return new Set([...content.matchAll(/\]\(([^)#]+)(?:#[^)]+)?\)/g)].map((match) => match[1]));
+}
+// Lesson records are machine-managed (T-230) and found through the brain index, so the curated
+// KNOWLEDGE.md neither demands nor lists them. CONFLICTS.md beside them waits on a human, so it
+// stays an indexed record.
+function isLessonRecord(store, file) {
+    if (store !== "knowledge" || file === conflictsFile())
+        return false;
+    const relative = path.relative(lessonsDir(), file);
+    return (relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative));
+}
+async function syncStore(store, apply) {
+    const root = oceanPath(STORE_DIR[store]);
+    const indexName = store === "memory" ? "MEMORY.md" : "KNOWLEDGE.md";
+    const index = path.join(root, indexName);
+    const current = await readFile(index, "utf8");
+    const recordFiles = (await markdownFiles(root)).filter((file) => path.basename(file) !== indexName && !isLessonRecord(store, file));
+    const known = links(current);
+    const missing = recordFiles.filter((file) => !known.has(relativeRecord(root, file)));
+    const broken = [];
+    for (const link of known) {
+        if (!link.startsWith("http") &&
+            !(await awaitedExists(path.resolve(root, link))))
+            broken.push(link);
+    }
+    if (!apply)
+        return {
+            store,
+            missing: missing.map((file) => relativeRecord(root, file)),
+            broken,
+            changed: false,
+        };
+    const generated = [
+        generatedStart,
+        "",
+        ...recordFiles.map((file) => {
+            const relative = relativeRecord(root, file);
+            return `- [${title(readFileSync(file, "utf8"), relative)}](${relative})`;
+        }),
+    ].join("\n");
+    const next = current.includes(generatedStart)
+        ? `${current.slice(0, current.indexOf(generatedStart)).trimEnd()}\n\n${generated}\n`
+        : `${current.trimEnd()}\n\n${generated}\n`;
+    const changed = next !== current;
+    if (changed)
+        await writeFile(index, next);
+    return {
+        store,
+        missing: missing.map((file) => relativeRecord(root, file)),
+        broken,
+        changed,
+    };
+}
+async function awaitedExists(file) {
+    try {
+        await readFile(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function syncMemoryIndexes(apply) {
+    return Promise.all([
+        syncStore("memory", apply),
+        syncStore("knowledge", apply),
+    ]);
+}
+export async function doctorMemoryIndexes() {
+    const results = await syncMemoryIndexes(false);
+    const missing = results.flatMap((result) => result.missing.map((file) => `${result.store}/${file}`));
+    const broken = results.flatMap((result) => result.broken.map((file) => `${result.store}/${file}`));
+    return { ok: missing.length === 0 && broken.length === 0, missing, broken };
+}
+//# sourceMappingURL=index-sync.js.map

package/node_modules/@ocean/brain/dist/memory/lesson-activation.js

@@ -0,0 +1,93 @@
+import { truncateUtf8 } from "@ocean/core/shared/fs-utils.js";
+import { brainSearch } from "../brain/brain-service.js";
+import { effectiveConfidence, readLesson } from "./lessons.js";
+// Which lessons a run starts with (T-230 P3). Candidates come from the brain index, not a
+// substring match on the lesson's name; the lesson file then has the last word, so a lesson
+// retired or decayed since the index was built never activates.
+export const MIN_ACTIVE_CONFIDENCE = 0.2;
+const LESSONS_PATH_PREFIX = "knowledge/lessons/";
+const MAX_QUERY_TOKENS = 8;
+const HITS_PER_TOKEN = 5;
+// The index ANDs every token of a query, so a whole prompt would match nothing: each
+// distinctive word is asked separately and a lesson is ranked by how many of them it answers.
+const STOPWORDS = new Set("the and for you are but not can was has how why who all any its our out one see now new did let may way too via per use get about after again also because before being between could does doing from have into just like make more most other should some than that their them then there these they this those through using very want what when where which while with would your".split(" "));
+export function queryTokens(prompt) {
+    const seen = new Set();
+    for (const match of prompt
+        .toLocaleLowerCase()
+        .matchAll(/[\p{L}\p{N}][\p{L}\p{N}-]{2,}/gu))
+        if (!STOPWORDS.has(match[0]))
+            seen.add(match[0]);
+    return [...seen]
+        .sort((a, b) => b.length - a.length || a.localeCompare(b))
+        .slice(0, MAX_QUERY_TOKENS);
+}
+export async function selectActiveLessons(prompt, options) {
+    const tokens = queryTokens(prompt);
+    if (!tokens.length)
+        return [];
+    const matched = new Map();
+    // A token whose search fails (no index built, one that predates record scopes, a transient
+    // lock) is skipped: with no index at all nothing activates, which is the safe default, and
+    // `ocean memory reindex` brings lessons back.
+    const results = await Promise.all(tokens.map((token) => brainSearch({
+        query: token,
+        root: options.root,
+        limit: HITS_PER_TOKEN,
+        types: ["experiential"],
+        pathPrefix: LESSONS_PATH_PREFIX,
+        scope: { project: null },
+        indexPort: options.indexPort,
+    }).catch(() => null)));
+    for (const result of results)
+        for (const hit of result?.results ?? [])
+            matched.set(hit.id, (matched.get(hit.id) ?? 0) + 1);
+    // A short prompt has few tokens to match; a long one must match more than a stray word.
+    const needed = tokens.length >= 3 ? 2 : 1;
+    const ranked = [];
+    for (const [id, matches] of matched) {
+        if (matches < needed)
+            continue;
+        // A lesson file that cannot be read is skipped: lessons are optional context and one
+        // bad file must not fail the run that merely matched it.
+        const lesson = await readLesson(id).catch(() => null);
+        if (lesson?.status !== "active")
+            continue;
+        const confidence = effectiveConfidence(lesson, options.now);
+        if (confidence < MIN_ACTIVE_CONFIDENCE)
+            continue;
+        ranked.push({ lesson, matches, confidence });
+    }
+    ranked.sort((a, b) => b.matches - a.matches ||
+        b.confidence - a.confidence ||
+        a.lesson.id.localeCompare(b.lesson.id));
+    const selected = [];
+    let bytes = 0;
+    for (const { lesson, confidence } of ranked) {
+        const remaining = options.maxBytes - bytes;
+        if (remaining <= 0)
+            break;
+        const ref = {
+            id: lesson.id,
+            title: lesson.title,
+            sourceSessionId: lesson.sourceSessionId,
+            confidence,
+        };
+        const size = Buffer.byteLength(lesson.body);
+        if (size <= remaining) {
+            selected.push({ ...ref, body: lesson.body, truncated: false });
+            bytes += size;
+            continue;
+        }
+        // A usable pointer: the command that prints the full lesson.
+        const marker = `\n[truncated to the run budget; full text: \`ocean skill list ${lesson.id}\`]`;
+        const markerBytes = Buffer.byteLength(marker);
+        if (remaining <= markerBytes)
+            break;
+        const body = `${truncateUtf8(lesson.body, remaining - markerBytes)}${marker}`;
+        selected.push({ ...ref, body, truncated: true });
+        bytes += Buffer.byteLength(body);
+    }
+    return selected;
+}
+//# sourceMappingURL=lesson-activation.js.map