ocean-crew 0.0.0-stage → 0.4.0

package/dist/host/work/learning.js

@@ -0,0 +1,1021 @@
+// Learning from work. After a long turn a Bot's chat is marked for review. When the
+// team has been idle for a while, and at most every few hours, one background pass
+// reads what was said since the last pass and asks whether it taught a skill worth
+// keeping or a lasting project rule. Most work teaches nothing, so most passes propose
+// nothing. A proposal waits as a card in the Bot's chat until approved, and declined
+// changes are remembered so the same idea does not come back.
+//
+// its model-facing texts. A failed parse, a failed chat read or a failed approval keeps
+// the work queued instead of advancing the cursor; an answered card stays in the chat
+// part it was answered in. The review runs on memory.ts's one-shot model call
+// (`rt.botShot`); without that slice the pass warns and leaves everything queued.
+import { createHash, randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { access, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { listenGlobal } from "../core/events.js";
+import { replaceFile } from "../core/files.js";
+import { validateCapabilityName } from "./capabilities.js";
+import { looksLikeKey, looksSecret, writtenIn } from "./memory.js";
+export const LEARNING = {
+    minTurnMs: 3 * 60_000,
+    idleMs: 10 * 60_000,
+    intervalMs: 12 * 60 * 60_000,
+    tickMs: 60_000,
+    readMs: 15_000,
+    textMax: 24_000,
+    userTextMax: 8_000,
+    userLineMax: 2_000,
+    botLineMax: 1_200,
+    learnedMax: 5,
+    descriptionMax: 300,
+    contentMax: 8_000,
+    declinedMax: 20,
+    agentsFileMax: 16_000,
+    agentsEditMax: 400,
+};
+const clip = (text, max) => (text.length > max ? `${text.slice(0, max)} […]` : text);
+export const hashOf = (text) => createHash("sha256")
+    .update(String(text ?? ""))
+    .digest("hex")
+    .slice(0, 16);
+// The answer of the review's model: one JSON object, perhaps in a code fence.
+export function parseJson(text) {
+    const raw = String(text ?? "").trim();
+    // A skill's content may hold code fences of its own, so read the whole answer first
+    // and fall back to a fenced block only when that fails.
+    const fenced = /^```(?:json)?\s*([\s\S]*?)```\s*$/.exec(raw)?.[1];
+    for (const candidate of [raw, fenced]) {
+        if (candidate === undefined)
+            continue;
+        const start = candidate.indexOf("{");
+        const end = candidate.lastIndexOf("}");
+        if (start === -1 || end < start)
+            continue;
+        try {
+            const value = JSON.parse(candidate.slice(start, end + 1));
+            if (value && typeof value === "object" && !Array.isArray(value))
+                return value;
+        }
+        catch {
+            // Try the next candidate.
+        }
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// The skill review.
+export function skillSystem() {
+    return [
+        "You review a stretch of finished work by an AI Bot and decide whether it taught a skill worth keeping.",
+        'A skill is a short document that a future Bot loads when a task of the same class comes up. Strong models already do most tasks well without one, so a weak or narrow skill only adds noise. Most work teaches nothing new: answer "none" unless every test below passes.',
+        "",
+        "Tests:",
+        "1. Reusable: tasks of this class will come up again in later, different work. A rule that only fits this task, file, bug, or pull request fails.",
+        "2. Missing knowledge: it gives constraints or context that a capable model does not have or gets wrong: requirements and corrections the user stated, project or tool conventions found by trial and error, pitfalls that cost time, how this user wants the result checked or delivered. General know-how fails, and so does anything that reading the code or the docs shows at once.",
+        "3. Earned: the work shows it. The user asked for it or corrected the Bot, or a non-obvious way was found after one that failed. Never invent rules the work did not show.",
+        "4. Not covered: no listed skill already says it. When a learned skill of this Bot covers the class, update that skill instead of making a new one. Also update a learned skill that the work showed to be wrong, outdated, or missing a step.",
+        "",
+        "Never put in a skill: one-off facts, task progress, file lists, dates, version, pull request or issue numbers, pasted errors or logs, facts about the user that are not about how to work (memory keeps those), or keys, passwords, and tokens.",
+        'Write rules that stand alone, not the story of this work: a reason says why the rule matters, never when or how it was broken ("the user corrected this before", "version 1.2 missed it"). Examples must be general: do not name the files, functions, values, or fixes that this work happened to touch, not even as an example, and write a placeholder such as `<file>:<line>` instead; name something only when the rule is about it, such as a check the user wants run.',
+        "",
+        "Form:",
+        '- name: the class of task, lowercase letters, digits, and single hyphens, 32 characters at most, e.g. "release-checks", never "fix-login-bug".',
+        "- description: one sentence, 200 characters at most, that says when to use the skill. Be concrete about the trigger.",
+        "- content: Markdown, 600 words at most. The rules as short imperative lines, each with a brief reason when it is not obvious; numbered steps only where order matters; how to check the work is done. Keep what is still true when you update, and remove what the work showed to be wrong.",
+        "",
+        "Answer with one JSON object only, one of:",
+        '{"action":"none","reason":"<one sentence>"}',
+        '{"action":"create","name":"…","description":"…","content":"…","why":"<one sentence: what in this work shows the skill is needed>"}',
+        '{"action":"update","name":"<a learned skill listed>","description":"…","content":"<the whole new content>","why":"<one sentence>"}',
+    ].join("\n");
+}
+// `learned`: this Bot's learned skills, in full. `library`: every other skill on the
+// team, by name and description. `declined`: proposals the user turned down.
+export function skillRequest({ bot, lines, learned = [], library = [], declined = [], language, limit = LEARNING.learnedMax, }) {
+    const parts = [`The Bot: ${bot.name}${bot.role ? `, ${bot.role}` : ""}.`];
+    parts.push(learned.length === 0
+        ? "This Bot has no learned skills yet."
+        : `This Bot's learned skills (${learned.length} of ${limit}${learned.length >= limit ? "; at the limit, only update one" : ""}):\n${learned
+            .map((skill) => `<skill name="${skill.name}">\ndescription: ${skill.description}\n${skill.content ?? ""}\n</skill>`)
+            .join("\n")}`);
+    if (library.length > 0)
+        parts.push(`Other skills on the team:\n${library.map((skill) => `- ${skill.name}: ${skill.description}`).join("\n")}`);
+    if (declined.length > 0)
+        parts.push(`Proposals the user declined. Do not propose them again unless this work shows something new:\n${declined
+            .map((entry) => `- ${entry.name}: ${entry.description}`)
+            .join("\n")}`);
+    if (language)
+        parts.push(`Write the description and the content in ${language}.`);
+    parts.push(`The work, oldest first ("User:" lines are the user's own words):\n<work>\n${lines.join("\n")}\n</work>`);
+    return parts.join("\n\n");
+}
+export function agentsSystem() {
+    return [
+        "You review a stretch of finished work that AI Bots did in one project folder, and decide whether the project's AGENTS.md should change.",
+        'Every agent that works in this folder reads AGENTS.md at the start of every task. So each line costs attention on every task: a file that is short and current helps; a long or stale one hurts. Most work should change nothing: answer "none" unless a change passes every test below.',
+        "",
+        "What belongs in AGENTS.md:",
+        "- How the user wants agents to work here: requirements, rules, and corrections the user stated, especially ones the user had to repeat.",
+        "- How the user wants to be talked to: language, length, format, what to report.",
+        "- Things to always do and never do in this project, with a short reason when it is not obvious.",
+        "- Project facts an agent needs on almost every task and cannot see at once from the code: the command that checks the work, a folder that must not be touched, a step that must come before a commit or a push.",
+        "",
+        "Tests for each change:",
+        "1. Almost every task: the rule matters to most future work in this folder, not to one kind of task. A procedure for one kind of task belongs in a skill, not here.",
+        "2. Earned: the work shows it. The user said it, or repeated it, or corrected an agent, or the same problem came back. Never invent rules the work did not show.",
+        "3. Not obvious: a capable agent would not do it anyway, and reading the code or the docs does not show it at once.",
+        "4. Lasting: still true next month. Never add task progress, plans, dates, versions, pull request or issue numbers, file lists, pasted errors or logs, or keys, passwords, and tokens.",
+        "5. Not already said: if the file already says it, change nothing; if the file says it unclearly or partly, replace that line instead of adding one.",
+        "",
+        "Also remove or fix lines the work shows to be wrong or outdated, such as a rule the user reversed, and merge lines that say the same thing. Do not remove a line only because this work did not use it. Keep the user's own words and the file's language and style; do not rewrite lines that are fine.",
+        "",
+        "Answer with one JSON object only, one of:",
+        '{"action":"none","reason":"<one sentence>"}',
+        '{"action":"edit","edits":[<1 to 3 edits>]}',
+        "Each edit is one of:",
+        '{"op":"add","after":"<an exact whole line of the file to add below, or empty for the end>","text":"<the new line or lines>","why":"<one sentence: what in this work shows it>"}',
+        '{"op":"replace","old":"<exact text of the file, one or more whole lines>","text":"<the new text>","why":"…"}',
+        '{"op":"remove","old":"<exact text of the file, one or more whole lines>","why":"…"}',
+        'Write new lines in the form the file already uses, such as "- " bullets under the right heading.',
+    ].join("\n");
+}
+// The folder, its AGENTS.md, declined edits, and work.
+export function agentsRequest({ folder, current, lines, declined = [], language, }) {
+    const parts = [`Project folder: ${folder}`];
+    parts.push(current === undefined ? "There is no AGENTS.md yet." : `Current AGENTS.md:\n\`\`\`md\n${current}\n\`\`\``);
+    const turnedDown = declined
+        .filter((entry) => entry.kind === "agents" && entry.folder === folder)
+        .flatMap((entry) => entry.edits ?? [])
+        .map((edit) => `- ${edit.op}: ${clip(edit.text || edit.old || "", 200)}`);
+    if (turnedDown.length > 0)
+        parts.push(`Changes the user turned down before; do not propose them again:\n${turnedDown.join("\n")}`);
+    if (language)
+        parts.push(`The user writes in ${language}.`);
+    parts.push(`The work, oldest first:\n${lines.join("\n")}`);
+    return parts.join("\n\n");
+}
+// What keeps a proposal from the user, or undefined when it may be shown.
+// Skills often talk about code such as `password == input`; read keys everywhere, but
+// password wording only outside code.
+const holdsSecret = (text) => looksLikeKey(text) || looksSecret(text.replace(/```[\s\S]*?```/g, " ").replace(/`[^`\n]*`/g, " "));
+const textOf = (value) => (typeof value === "string" ? value : "");
+const lineBlock = (value) => value.split(/\r?\n/);
+const occurrences = (lines, block) => {
+    const found = [];
+    for (let at = 0; at <= lines.length - block.length; at += 1) {
+        if (block.every((line, index) => lines[at + index] === line))
+            found.push(at);
+    }
+    return found;
+};
+export function withoutReviewedAgentsRecords(records, reviewedOrders) {
+    const reviewed = new Set(reviewedOrders);
+    return records.filter((record) => !reviewed.has(record.order));
+}
+export function applyEdits(current, edits) {
+    let text = current ?? "";
+    let newline = text.includes("\r\n") ? "\r\n" : "\n";
+    let trailing = text.endsWith("\n");
+    let lines = text === "" ? [] : text.split(/\r?\n/);
+    if (trailing)
+        lines.pop();
+    for (const edit of edits) {
+        if (!["add", "replace", "remove"].includes(String(edit.op)))
+            throw new Error("unknown edit operation");
+        if (edit.op === "add") {
+            const added = lineBlock(textOf(edit.text));
+            const after = textOf(edit.after);
+            if (current === undefined && after !== "")
+                throw new Error("a new AGENTS.md can only add at the end");
+            if (!text) {
+                lines = added;
+                trailing = true;
+            }
+            else if (!after) {
+                lines.push(...added);
+                trailing = true;
+            }
+            else {
+                const positions = occurrences(lines, [after]);
+                if (positions.length !== 1)
+                    throw new Error("the add anchor must occur once as a whole line");
+                const at = positions[0];
+                lines.splice(at + 1, 0, ...added);
+            }
+        }
+        else {
+            const old = lineBlock(textOf(edit.old));
+            if (current === undefined)
+                throw new Error("a new AGENTS.md can only add lines");
+            const positions = occurrences(lines, old);
+            if (positions.length !== 1)
+                throw new Error("the old text must occur once as whole lines");
+            const at = positions[0];
+            const replacement = edit.op === "replace" ? lineBlock(textOf(edit.text)) : [];
+            lines.splice(at, old.length, ...replacement);
+        }
+        text = lines.join(newline) + (trailing && lines.length > 0 ? newline : "");
+        newline = text.includes("\r\n") ? "\r\n" : "\n";
+        trailing = text.endsWith("\n");
+        lines = text === "" ? [] : text.split(/\r?\n/);
+        if (trailing)
+            lines.pop();
+    }
+    return text;
+}
+// The review's answer as a proposal. A single edit written as the answer itself, with
+// its operation as the action, is that edit; a replacement with no text removes; lines
+// one edit names that stand apart in the file, each once, are one edit each.
+export function agentsAnswer(reply, current) {
+    let answer = parseJson(reply);
+    if (answer !== undefined && answer.action !== undefined && ["add", "replace", "remove"].includes(answer.action)) {
+        const { action, ...edit } = answer;
+        answer = { action: "edit", edits: [{ op: action, ...edit }] };
+    }
+    if (answer === undefined || !Array.isArray(answer.edits))
+        return answer;
+    const lines = lineBlock(current ?? "");
+    const apart = (edit) => {
+        if (edit?.op !== "replace" && edit?.op !== "remove")
+            return [edit];
+        const old = lineBlock(textOf(edit.old));
+        const text = lineBlock(textOf(edit.text));
+        if (old.length < 2 ||
+            occurrences(lines, old).length > 0 ||
+            old.some((line) => occurrences(lines, [line]).length !== 1))
+            return [edit];
+        if (edit.op === "replace" && text.length !== old.length)
+            return [edit];
+        return old.map((line, index) => ({
+            ...edit,
+            op: edit.op,
+            old: line,
+            ...(edit.op === "replace" ? { text: text[index] } : {}),
+        }));
+    };
+    const removes = (edit) => ({
+        op: "remove",
+        ...(edit.old !== undefined ? { old: edit.old } : {}),
+        ...(edit.after !== undefined ? { after: edit.after } : {}),
+        ...(edit.why !== undefined ? { why: edit.why } : {}),
+    });
+    const edits = answer.edits.map((edit) => edit?.op === "replace" && textOf(edit.text).trim() === "" ? removes(edit) : edit);
+    return { ...answer, edits: edits.flatMap(apart) };
+}
+export function agentsProblem(proposal, current) {
+    if (proposal === undefined)
+        return "the answer is not a JSON object";
+    if (proposal.action === "none")
+        return undefined;
+    if (proposal.action !== "edit")
+        return `unknown action ${String(proposal.action)}`;
+    if (!Array.isArray(proposal.edits) || proposal.edits.length < 1 || proposal.edits.length > 3)
+        return "an edit needs 1 to 3 changes";
+    const initial = current ?? "";
+    let result = initial;
+    for (const edit of proposal.edits) {
+        if (!edit || !["add", "replace", "remove"].includes(String(edit.op)))
+            return "unknown edit operation";
+        const text = textOf(edit.text);
+        const old = textOf(edit.old);
+        const after = textOf(edit.after);
+        const why = textOf(edit.why);
+        if (why.trim() === "")
+            return "each edit needs a reason";
+        if (edit.op !== "remove" && text === "")
+            return "an add or replacement needs text";
+        if (text.length > LEARNING.agentsEditMax)
+            return `edit text must have at most ${LEARNING.agentsEditMax} characters`;
+        if (holdsSecret(text) || holdsSecret(why))
+            return "it looks like it holds a secret";
+        if (/#\d{2,}|\b\d{4}-\d{2}-\d{2}\b|\bv\d+\.\d+/u.test(text))
+            return "the edit contains a task number, date, or version";
+        const lines = lineBlock(result);
+        if (edit.op === "add") {
+            if (typeof edit.after !== "string")
+                return "an add needs an anchor";
+            if (current === undefined && after !== "")
+                return "a new AGENTS.md can only add at the end";
+            if (after !== "" && (after.includes("\n") || occurrences(lines, [after]).length !== 1))
+                return "the add anchor must be one exact whole line";
+        }
+        else {
+            if (current === undefined)
+                return "a new AGENTS.md can only add lines";
+            if (old === "" ||
+                old.startsWith("\n") ||
+                old.endsWith("\n") ||
+                occurrences(lines, lineBlock(old)).length !== 1)
+                return "the old text must occur exactly once as whole lines";
+        }
+        result = applyEdits(result, [edit]);
+    }
+    if (result.length > Math.max(initial.length + 800, 4_000))
+        return "the resulting AGENTS.md is too large";
+    if (result === initial)
+        return "the edits change nothing";
+    return undefined;
+}
+export function skillProblem(proposal, { skills, learned, limit = LEARNING.learnedMax, }) {
+    if (proposal === undefined)
+        return "the answer is not a JSON object";
+    const { action } = proposal;
+    if (action === "none")
+        return undefined;
+    if (action !== "create" && action !== "update")
+        return `unknown action ${String(action)}`;
+    let name;
+    try {
+        name = validateCapabilityName(proposal.name);
+    }
+    catch (error) {
+        return error.message;
+    }
+    const description = typeof proposal.description === "string" ? proposal.description.trim() : "";
+    const content = typeof proposal.content === "string" ? proposal.content.trim() : "";
+    const why = typeof proposal.why === "string" ? proposal.why.trim() : "";
+    if (description === "" || description.length > LEARNING.descriptionMax)
+        return `the description must have 1 to ${LEARNING.descriptionMax} characters`;
+    if (content === "" || content.length > LEARNING.contentMax)
+        return `the content must have 1 to ${LEARNING.contentMax} characters`;
+    if (holdsSecret(description) || holdsSecret(content) || holdsSecret(why))
+        return "it looks like it holds a secret";
+    const existing = Object.hasOwn(skills, name) ? skills[name] : undefined;
+    if (action === "create") {
+        if (existing !== undefined)
+            return `${name} already exists`;
+        if (learned.length >= limit)
+            return `the Bot already keeps ${limit} learned skills`;
+    }
+    else {
+        if (existing === undefined || existing.kind !== "skill" || !learned.includes(name))
+            return `${name} is not a learned skill of this Bot`;
+        if (String(existing.content ?? "").trim() === content &&
+            String(existing.description ?? "").trim() === description)
+            return "the update changes nothing";
+    }
+    return undefined;
+}
+export function install(rt) {
+    const { ctx, config, home, state } = rt;
+    const settings = { ...LEARNING, ...(config.learningTimes ?? {}) };
+    const on = config.learning !== false && config.memory !== false;
+    const emptyView = () => ({});
+    if (!on) {
+        Object.assign(rt, {
+            learningView: emptyView,
+            learningSettledView: emptyView,
+            learningEndpoint: async () => {
+                throw new Error("Learning is turned off on this host");
+            },
+            learningRun: async () => 0,
+        });
+        return;
+    }
+    const learningConfig = config;
+    const root = join(home, "learning");
+    const path = join(root, "state.json");
+    // `pending`: Bot id → chats with a long turn since the last pass. `agentsPending`:
+    // folder → queued work waiting for AGENTS.md review. `cursors`: newest line read.
+    // `proposals`: waiting for the user, by id. `settled`: answered ones, by id, with the
+    // outcome; their cards stay in the chat part they were answered in. `learned`: skill
+    // names learned by Bot.
+    let saved;
+    const data = () => {
+        if (saved !== undefined)
+            return saved;
+        let parsed = {};
+        try {
+            parsed = JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch (error) {
+            if (error?.code !== "ENOENT")
+                rt.warn("ocean-crew: unreadable learning state %s: %s", path, error?.message ?? error);
+        }
+        const store = parsed;
+        store.pending ??= {};
+        store.cursors ??= {};
+        store.proposals ??= {};
+        store.settled ??= {};
+        store.declined ??= [];
+        store.learned ??= {};
+        store.agentsPending ??= {};
+        saved = store;
+        return store;
+    };
+    let stopped = false;
+    let writing = Promise.resolve();
+    const persist = () => {
+        if (stopped)
+            return writing;
+        const text = JSON.stringify(data(), null, 1);
+        writing = writing
+            .then(async () => {
+            await mkdir(dirname(path), { recursive: true });
+            const temp = `${path}.${process.pid}.tmp`;
+            await writeFile(temp, text, "utf8");
+            await replaceFile(temp, path);
+        })
+            .catch((error) => rt.warn("ocean-crew: saving the learning state failed: %s", error?.message ?? error));
+        return writing;
+    };
+    // A turn in a Bot's own chat that ran long marks the chat for the next pass.
+    const started = new Map();
+    const noted = new Map();
+    let lastActivity = Date.now();
+    listenGlobal(ctx, "agent/status", ({ agent, status }) => {
+        if (stopped)
+            return;
+        const id = agent?.id;
+        if (id === undefined || !rt.isBotSession(id))
+            return;
+        lastActivity = Date.now();
+        if (status !== "idle") {
+            if (!started.has(id))
+                started.set(id, Date.now());
+            return;
+        }
+        const since = started.get(id);
+        started.delete(id);
+        const botId = rt.chatOwners.get(id);
+        if (since === undefined || botId === undefined || Date.now() - since < settings.minTurnMs)
+            return;
+        const pending = data().pending;
+        pending[botId] = [...new Set([...(pending[botId] ?? []), id])];
+        noted.set(id, (noted.get(id) ?? 0) + 1);
+        void persist();
+    });
+    const partLines = (sessionId, signal) => {
+        const reader = rt.partLines;
+        if (typeof reader !== "function")
+            throw new Error("The conversation record is not available on this host");
+        return reader(sessionId, signal, { pages: Number.POSITIVE_INFINITY });
+    };
+    // After the text budget, keep scanning to the cursor for user corrections.
+    async function linesSince(sessionId) {
+        const cursor = data().cursors[sessionId];
+        const kept = [];
+        const userLines = [];
+        const keptRecords = [];
+        const userRecords = [];
+        let used = 0;
+        let userUsed = 0;
+        let overBudget = false;
+        let through;
+        for await (const line of partLines(sessionId, AbortSignal.timeout(settings.readMs))) {
+            through ??= line.seq;
+            if (cursor !== undefined && line.seq !== undefined && line.seq <= cursor)
+                break;
+            const text = clip(line.text, line.who === "user" ? settings.userLineMax : settings.botLineMax);
+            if (!overBudget && used + text.length <= settings.textMax) {
+                kept.push(text);
+                keptRecords.push({ text, time: line.time });
+                used += text.length;
+                continue;
+            }
+            overBudget = true;
+            if (text.startsWith("User: ") && userUsed + text.length <= settings.userTextMax) {
+                userLines.push(text);
+                userRecords.push({ text, time: line.time });
+                userUsed += text.length;
+            }
+        }
+        return { lines: [...kept, ...userLines].reverse(), work: [...keptRecords, ...userRecords].reverse(), through };
+    }
+    const skillsOf = () => {
+        const found = {};
+        for (const [name, item] of Object.entries(state.capabilities?.items ?? {}))
+            if (item?.kind === "skill")
+                found[name] = item;
+        return found;
+    };
+    const learnedOf = (bot) => (data().learned[bot.id] ?? []).filter((name) => skillsOf()[name] !== undefined && (bot.capabilities ?? []).includes(name));
+    const waitingFor = (botId) => Object.values(data().proposals).filter((entry) => entry.botId === botId);
+    const redact = (text) => {
+        const service = rt.redactSecrets;
+        return typeof service === "function" ? service(text) : text;
+    };
+    const language = (lines) => {
+        const detected = writtenIn(lines.filter((line) => line.startsWith("User: ")).map((line) => line.slice(6)), rt.uiLanguage?.() ?? "");
+        return detected === "" ? undefined : detected;
+    };
+    async function botShot(bot, system, text) {
+        const shot = rt.botShot;
+        if (typeof shot !== "function")
+            throw new Error("The model review is not available on this host");
+        return shot(bot, system, text, { sessionId: rt.chatOf(bot.id), kind: "memory" });
+    }
+    async function reviewSkill(bot, lines) {
+        const skills = skillsOf();
+        const learned = learnedOf(bot);
+        const library = Object.values(skills)
+            .filter((item) => !learned.includes(item.name))
+            .map((item) => ({ name: item.name, description: String(item.description ?? "") }));
+        const text = skillRequest({
+            bot,
+            lines,
+            learned: learned.map((name) => skills[name]),
+            library,
+            declined: data().declined.filter((entry) => entry.kind !== "agents"),
+            language: language(lines),
+            limit: settings.learnedMax,
+        });
+        const reply = await botShot(bot, skillSystem(), text);
+        const proposal = parseJson(reply);
+        if (["description", "content", "why"].some((key) => {
+            const value = proposal?.[key];
+            return typeof value === "string" && redact(value) !== value;
+        })) {
+            rt.warn("ocean-crew: the skill review of %s proposed content containing a saved secret", bot.name);
+            return undefined;
+        }
+        const problem = skillProblem(proposal, { skills, learned, limit: settings.learnedMax });
+        if (problem !== undefined) {
+            rt.warn("ocean-crew: the skill review of %s proposed nothing usable: %s", bot.name, problem);
+            return undefined;
+        }
+        if (proposal === undefined || proposal.action === "none")
+            return undefined;
+        const name = proposal.name.trim();
+        const previous = proposal.action === "update" ? skills[name] : undefined;
+        return {
+            id: randomUUID(),
+            kind: "skill",
+            action: proposal.action,
+            botId: bot.id,
+            at: Date.now(),
+            name,
+            description: proposal.description.trim(),
+            content: proposal.content.trim(),
+            why: typeof proposal.why === "string" ? clip(proposal.why.trim(), 300) : "",
+            ...(previous !== undefined
+                ? {
+                    previous: {
+                        description: String(previous.description ?? ""),
+                        content: String(previous.content ?? ""),
+                    },
+                    base: hashOf(`${previous.description}\n${previous.content}`),
+                }
+                : {}),
+        };
+    }
+    async function reviewAgents(bot, folder, current, lines) {
+        const request = agentsRequest({ folder, current, lines, declined: data().declined, language: language(lines) });
+        const reply = await botShot(bot, agentsSystem(), request);
+        const answer = agentsAnswer(reply, current);
+        if (answer === undefined || answer === null || typeof answer !== "object")
+            throw new Error("the answer is not a JSON object");
+        if (Array.isArray(answer.edits) &&
+            answer.edits.some((edit) => [edit?.text, edit?.why].some((value) => typeof value === "string" && redact(value) !== value))) {
+            rt.warn("ocean-crew: the AGENTS.md review of %s proposed content containing a saved secret", bot.name);
+            return undefined;
+        }
+        const problem = agentsProblem(answer, current);
+        if (problem !== undefined) {
+            if (answer?.action !== "none")
+                rt.warn("ocean-crew: the AGENTS.md review of %s proposed nothing usable: %s", bot.name, problem);
+            return undefined;
+        }
+        if (answer.action === "none" || !Array.isArray(answer.edits))
+            return undefined;
+        const content = applyEdits(current, answer.edits);
+        return {
+            id: randomUUID(),
+            kind: "agents",
+            botId: bot.id,
+            at: Date.now(),
+            folder,
+            path: join(folder, "AGENTS.md"),
+            base: hashOf(current ?? ""),
+            exists: current !== undefined,
+            edits: answer.edits.map((edit) => ({
+                op: edit.op,
+                ...(typeof edit.after === "string" ? { after: edit.after } : {}),
+                ...(typeof edit.old === "string" ? { old: edit.old } : {}),
+                ...(typeof edit.text === "string" ? { text: edit.text } : {}),
+                ...(typeof edit.why === "string" ? { why: edit.why } : {}),
+            })),
+            content,
+        };
+    }
+    const exists = async (target) => {
+        try {
+            await access(target);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    async function agentsFile(folder) {
+        const target = join(folder, "AGENTS.md");
+        try {
+            const content = await readFile(target, "utf8");
+            return content.length <= LEARNING.agentsFileMax ? content : undefined;
+        }
+        catch (error) {
+            if (error?.code === "ENOENT")
+                return undefined;
+            throw error;
+        }
+    }
+    function queueAgentsWork(folder, bot, records) {
+        if (records.length === 0)
+            return;
+        if (data().agentsPending[folder] === undefined)
+            data().agentsPending[folder] = { botId: bot.id, records: [] };
+        const queue = data().agentsPending[folder];
+        if (rt.botOf(queue.botId) === undefined)
+            queue.botId = bot.id;
+        queue.records ??= [];
+        let order = queue.records.reduce((max, item) => Math.max(max, item.order ?? 0), -1) + 1;
+        for (const item of records)
+            queue.records.push({ botId: bot.id, text: item.text, time: item.time, order: order++ });
+        const max = settings.textMax + settings.userTextMax;
+        let size = queue.records.reduce((sum, item) => sum + item.text.length, 0);
+        const removed = new Set();
+        const oldest = [...queue.records].sort((a, b) => (a.time ?? 0) - (b.time ?? 0) || a.order - b.order);
+        for (const item of oldest) {
+            if (size <= max)
+                break;
+            if (item.text.startsWith("User: "))
+                continue;
+            removed.add(item);
+            size -= item.text.length;
+        }
+        for (const item of oldest) {
+            if (size <= max)
+                break;
+            if (!item.text.startsWith("User: "))
+                continue;
+            removed.add(item);
+            size -= item.text.length;
+        }
+        if (removed.size > 0)
+            queue.records = queue.records.filter((item) => !removed.has(item));
+        if (queue.records.length === 0)
+            delete data().agentsPending[folder];
+    }
+    // One pass over every Bot with a long turn since the last one. A Bot with a proposal
+    // still waiting is skipped: its chat is read again in the next pass.
+    let running;
+    async function run() {
+        if (stopped)
+            return 0;
+        if (running !== undefined)
+            return running;
+        running = (async () => {
+            const store = data();
+            store.lastRun = Date.now();
+            let made = 0;
+            for (const [botId, pendingSessions] of Object.entries(store.pending)) {
+                if (stopped)
+                    break;
+                const bot = rt.botOf(botId);
+                if (bot === undefined) {
+                    delete store.pending[botId];
+                    continue;
+                }
+                if (waitingFor(botId).length > 0)
+                    continue;
+                const sessions = [...pendingSessions];
+                const notedAtStart = new Map(sessions.map((sessionId) => [sessionId, noted.get(sessionId)]));
+                try {
+                    const read = [];
+                    for (const sessionId of sessions)
+                        read.push({ sessionId, ...(await linesSince(sessionId)) });
+                    if (stopped)
+                        return made;
+                    const lines = read.flatMap((entry) => entry.lines);
+                    const proposal = lines.length === 0 ? undefined : await reviewSkill(bot, lines);
+                    if (stopped)
+                        return made;
+                    if (proposal !== undefined) {
+                        store.proposals[proposal.id] = proposal;
+                        made += 1;
+                    }
+                    if (learningConfig.agentsMd !== false) {
+                        for (const entry of read) {
+                            try {
+                                if (typeof rt.sessionFolder !== "function" || typeof rt.real !== "function")
+                                    continue;
+                                const agent = (await rt.resolveAgent(entry.sessionId));
+                                const reported = rt.sessionFolder(agent.session);
+                                if (!reported)
+                                    continue;
+                                const folder = await rt.real(reported);
+                                try {
+                                    await rt.workFolder?.(folder);
+                                }
+                                catch {
+                                    continue;
+                                }
+                                if (!(await exists(join(folder, ".git"))) && !(await exists(join(folder, "AGENTS.md"))))
+                                    continue;
+                                queueAgentsWork(folder, bot, entry.work ?? []);
+                            }
+                            catch (error) {
+                                rt.warn("ocean-crew: the AGENTS.md folder lookup for %s failed: %s", entry.sessionId, error?.message ?? error);
+                            }
+                        }
+                    }
+                    for (const entry of read)
+                        if (entry.through !== undefined)
+                            store.cursors[entry.sessionId] = entry.through;
+                    const remaining = (store.pending[botId] ?? []).filter((sessionId) => !notedAtStart.has(sessionId) || noted.get(sessionId) !== notedAtStart.get(sessionId));
+                    if (remaining.length === 0)
+                        delete store.pending[botId];
+                    else
+                        store.pending[botId] = remaining;
+                }
+                catch (error) {
+                    rt.warn("ocean-crew: the learning review of %s failed: %s", bot.name, error?.message ?? error);
+                }
+            }
+            if (learningConfig.agentsMd !== false) {
+                for (const [folder, group] of Object.entries(store.agentsPending)) {
+                    if (stopped)
+                        break;
+                    let bot = rt.botOf(group.botId);
+                    if (bot === undefined) {
+                        const contributor = group.records.find((item) => rt.botOf(item.botId) !== undefined);
+                        if (contributor === undefined) {
+                            delete store.agentsPending[folder];
+                            continue;
+                        }
+                        group.botId = contributor.botId;
+                        bot = rt.botOf(group.botId);
+                    }
+                    if (bot === undefined)
+                        continue;
+                    if (Object.values(store.proposals).some((entry) => entry.kind === "agents" && entry.folder === folder))
+                        continue;
+                    try {
+                        const reviewRecords = [...group.records];
+                        const reviewedOrders = reviewRecords.map((item) => item.order);
+                        const current = await agentsFile(folder);
+                        if (stopped)
+                            return made;
+                        if (current === undefined && (await exists(join(folder, "AGENTS.md"))))
+                            continue;
+                        const lines = [];
+                        let used = 0;
+                        let userUsed = 0;
+                        let overBudget = false;
+                        for (const item of reviewRecords.sort((a, b) => (a.time ?? 0) - (b.time ?? 0) || a.order - b.order)) {
+                            if (!overBudget && used + item.text.length <= settings.textMax) {
+                                lines.push(item.text);
+                                used += item.text.length;
+                                continue;
+                            }
+                            overBudget = true;
+                            if (item.text.startsWith("User: ") && userUsed + item.text.length <= settings.userTextMax) {
+                                lines.push(item.text);
+                                userUsed += item.text.length;
+                            }
+                        }
+                        if (lines.length === 0)
+                            continue;
+                        const proposal = await reviewAgents(bot, folder, current, lines);
+                        if (stopped)
+                            return made;
+                        if (proposal !== undefined) {
+                            store.proposals[proposal.id] = proposal;
+                            made += 1;
+                        }
+                        const queue = store.agentsPending[folder];
+                        if (queue !== undefined) {
+                            queue.records = withoutReviewedAgentsRecords(queue.records ?? [], reviewedOrders);
+                            if (queue.records.length === 0)
+                                delete store.agentsPending[folder];
+                        }
+                    }
+                    catch (error) {
+                        rt.warn("ocean-crew: the AGENTS.md review of %s failed: %s", folder, error?.message ?? error);
+                    }
+                }
+            }
+            await persist();
+            return made;
+        })().finally(() => {
+            running = undefined;
+        });
+        return running;
+    }
+    const due = () => {
+        if (stopped)
+            return false;
+        const store = data();
+        const hasPending = Object.values(store.pending).some((sessions) => sessions.length > 0) ||
+            (learningConfig.agentsMd !== false &&
+                Object.values(store.agentsPending).some((queue) => (queue.records?.length ?? 0) > 0));
+        if (!hasPending || rt.readOnly() !== undefined)
+            return false;
+        if (Object.keys(rt.workView?.() ?? {}).length > 0 || Date.now() - lastActivity < settings.idleMs)
+            return false;
+        return store.lastRun === undefined || Date.now() - store.lastRun >= settings.intervalMs;
+    };
+    ctx.effect(() => {
+        const timer = setInterval(() => {
+            if (due())
+                void run().catch((error) => rt.warn("ocean-crew: learning pass failed: %s", error?.message ?? error));
+        }, settings.tickMs);
+        timer.unref?.();
+        return () => {
+            stopped = true;
+            clearInterval(timer);
+            // A new host may take over after disposal; finish only writes already queued.
+            return writing;
+        };
+    }, "ocean-crew: learning");
+    // The user's answer to a card.
+    async function answer({ id, approve }) {
+        const store = data();
+        const proposal = Object.hasOwn(store.proposals, id) ? store.proposals[id] : undefined;
+        if (proposal === undefined)
+            throw Object.assign(new Error("This proposal is no longer open"), { code: "bot/stale" });
+        // The answered card stays where it was, read-only, with how it ended. A waiting card
+        // shows in the Bot's current chat part, so that is where it stays.
+        const settle = (outcome) => {
+            delete store.proposals[id];
+            const kept = { ...proposal };
+            delete kept.saved;
+            store.settled[id] = {
+                ...kept,
+                sessionId: rt.chatOf(proposal.botId),
+                outcome,
+                settledAt: Date.now(),
+            };
+        };
+        if (approve !== true) {
+            settle("declined");
+            const decline = proposal.kind === "agents"
+                ? {
+                    kind: "agents",
+                    folder: proposal.folder,
+                    edits: proposal.edits.map(({ op, text, old }) => ({ op, text, old })),
+                    at: Date.now(),
+                }
+                : { kind: "skill", name: proposal.name, description: proposal.description, at: Date.now() };
+            store.declined = [...store.declined, decline].slice(-settings.declinedMax);
+            await persist();
+            return { applied: false };
+        }
+        // A failed approval keeps the card, so the user can still decline it.
+        if (proposal.kind === "agents")
+            await applyAgents(proposal);
+        else
+            await applySkill(proposal);
+        settle("approved");
+        await persist();
+        return { applied: true };
+    }
+    const agentsApplying = new Map();
+    async function applyAgents(proposal) {
+        const target = proposal.path;
+        const previous = agentsApplying.get(target) ?? Promise.resolve();
+        let release = () => { };
+        const lock = new Promise((resolve) => {
+            release = resolve;
+        });
+        const queued = previous.catch(() => undefined).then(() => lock);
+        agentsApplying.set(target, queued);
+        await previous.catch(() => undefined);
+        try {
+            if (typeof rt.real !== "function" || typeof rt.workFolder !== "function")
+                throw new Error("The project folders are not available on this host");
+            const folder = await rt.real(proposal.folder);
+            await rt.workFolder(folder);
+            if (join(folder, "AGENTS.md") !== target)
+                throw new Error("AGENTS.md changed since this was proposed");
+            const readCurrent = async () => {
+                try {
+                    return await readFile(target, "utf8");
+                }
+                catch (error) {
+                    if (error?.code !== "ENOENT")
+                        throw error;
+                    return undefined;
+                }
+            };
+            const checkCurrent = (current) => {
+                const existsNow = current !== undefined;
+                if (existsNow !== proposal.exists || hashOf(current ?? "") !== proposal.base)
+                    throw new Error("AGENTS.md changed since this was proposed");
+            };
+            checkCurrent(await readCurrent());
+            const temp = `${target}.${process.pid}.${randomUUID()}.tmp`;
+            try {
+                await writeFile(temp, proposal.content, "utf8");
+                checkCurrent(await readCurrent());
+                await replaceFile(temp, target);
+            }
+            finally {
+                await unlink(temp).catch(() => undefined);
+            }
+        }
+        finally {
+            release();
+            if (agentsApplying.get(target) === queued)
+                agentsApplying.delete(target);
+        }
+    }
+    // The capability list is capabilities.ts's; without that slice an approved proposal
+    // cannot be applied and the card stays open, so the user can still decline it.
+    const capability = (name) => {
+        const found = rt[name];
+        return typeof found === "function" ? found : undefined;
+    };
+    async function applySkill(proposal) {
+        const bot = rt.botOf(proposal.botId);
+        if (bot === undefined)
+            throw new Error("The Bot that learned this skill is gone");
+        const current = skillsOf()[proposal.name];
+        const store = data();
+        if (proposal.action === "create") {
+            if (proposal.saved) {
+                if (current === undefined ||
+                    current.description !== proposal.description ||
+                    current.content !== proposal.content)
+                    throw new Error(`${proposal.name} changed since this was proposed`);
+                store.learned[bot.id] = [...new Set([...(store.learned[bot.id] ?? []), current.name])];
+                await persist();
+            }
+            else {
+                if (current !== undefined)
+                    throw new Error(`A skill named ${proposal.name} exists now`);
+                const save = capability("capabilitySave");
+                if (save === undefined)
+                    throw new Error("The capability library is not available on this host");
+                const item = await save({ name: proposal.name, kind: "skill", description: proposal.description, content: proposal.content }, { botId: bot.id, ui: false });
+                proposal.saved = true;
+                store.learned[bot.id] = [...new Set([...(store.learned[bot.id] ?? []), item.name])];
+                await persist();
+            }
+        }
+        else if (proposal.action === "update") {
+            if (current === undefined || hashOf(`${current.description}\n${current.content}`) !== proposal.base)
+                throw new Error(`${proposal.name} changed since this was proposed`);
+            const save = capability("capabilitySave");
+            if (save === undefined)
+                throw new Error("The capability library is not available on this host");
+            const item = await save({ name: proposal.name, kind: "skill", description: proposal.description, content: proposal.content }, { botId: bot.id, ui: false });
+            store.learned[bot.id] = [...new Set([...(store.learned[bot.id] ?? []), item.name])];
+            await persist();
+        }
+        if (!(bot.capabilities ?? []).includes(proposal.name)) {
+            const endpoint = capability("capabilityEndpoint");
+            if (endpoint === undefined)
+                throw new Error("The capability library is not available on this host");
+            await endpoint("bot-capability", { botId: bot.id, name: proposal.name, attached: true });
+        }
+    }
+    async function learningEndpoint(endpoint, body) {
+        if (endpoint === "learning-answer")
+            return answer({ id: String(body.id ?? ""), approve: body.approve === true });
+        throw new Error(`Unknown endpoint ${endpoint}`);
+    }
+    async function removeLearned(name) {
+        const learned = data().learned;
+        const deleted = String(name ?? "");
+        for (const [botId, names] of Object.entries(learned)) {
+            learned[botId] = (Array.isArray(names) ? names : []).filter((entry) => entry !== deleted);
+        }
+        await persist();
+    }
+    // Per Bot, its proposals waiting for the user.
+    const learningView = () => {
+        const byBot = {};
+        for (const entry of Object.values(data().proposals)) {
+            byBot[entry.botId] = [...(byBot[entry.botId] ?? []), entry];
+        }
+        return byBot;
+    };
+    // Per Bot, the answered proposals of its current chat part.
+    const learningSettledView = () => {
+        const byBot = {};
+        for (const entry of Object.values(data().settled)) {
+            if (rt.botOf(entry.botId) !== undefined && entry.sessionId === rt.chatOf(entry.botId))
+                byBot[entry.botId] = [...(byBot[entry.botId] ?? []), entry];
+        }
+        return byBot;
+    };
+    // A skill removed through the capability library is no longer learned by any Bot.
+    const capabilityDelete = rt.capabilityDelete;
+    rt.capabilityDelete = async (...args) => {
+        const result = typeof capabilityDelete === "function" ? await capabilityDelete(...args) : undefined;
+        await removeLearned(args[0]);
+        return result;
+    };
+    const capabilityEndpoint = rt.capabilityEndpoint;
+    rt.capabilityEndpoint = async (endpoint, body, ...args) => {
+        const result = typeof capabilityEndpoint === "function"
+            ? await capabilityEndpoint(endpoint, body, ...args)
+            : undefined;
+        if (endpoint === "capability-delete")
+            await removeLearned(body?.name);
+        return result;
+    };
+    Object.assign(rt, { learningView, learningSettledView, learningEndpoint, learningRun: run });
+}