ocean-crew 0.0.0-stage → 0.4.0

package/dist/host/chat/chat-index.js

@@ -0,0 +1,344 @@
+// Reading a Bot's own chat: Session history pages, the SQLite FTS5 index, and the
+// search, latest, and around reads behind read_own_chat.
+//
+// Chat index. read_own_chat searches a SQLite FTS5 table of every part of a Bot's own
+// chat, ranked by BM25. The trigram tokenizer matches any run of three or more
+// characters, so Chinese needs no word splitting; shorter words fall back to LIKE.
+// The index is derived from the Session logs: a part catches up when it is read, an
+// ended part is sealed once it is complete, and deleting the file only costs a
+// rebuild. Without SQLite, read_own_chat scans the logs as before.
+import { mkdir, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { ANCHOR_LINE_MAX, HISTORY_PAGE, HISTORY_PAGES_MAX, HISTORY_TIMEOUT_MS, OWN_CHAT_BRIEF, OWN_CHAT_LINE_MAX, OWN_CHAT_READ, OWN_CHAT_SEARCH, } from "../core/constants.js";
+import { excerpt } from "../core/text.js";
+const INDEX_VERSION = 3;
+const AROUND_LINES = 6;
+const SEARCH_TERMS_MAX = 6;
+const ANY_TERM_HITS = 50;
+const INDEX_TIMEOUT_MS = 120_000;
+// A part still gets a few events (a title, a late reply) just after it ends.
+const SEAL_AFTER_MS = 60_000;
+const likeOf = (term) => `%${term.replace(/[\\%_]/g, (char) => `\\${char}`)}%`;
+// Each term is a quoted FTS5 phrase when trigrams can match it, else a LIKE filter.
+export function termQuery(terms, sessions, limit, hidden) {
+    const long = terms.filter((term) => [...term].length >= 3);
+    const short = terms.filter((term) => [...term].length < 3);
+    const where = ["session IN (SELECT value FROM json_each(?))"];
+    const args = [JSON.stringify(sessions)];
+    if (hidden !== undefined) {
+        where.push("NOT (session = ? AND seq >= ?)");
+        args.push(hidden.session, hidden.from);
+    }
+    if (long.length > 0) {
+        where.unshift("lines MATCH ?");
+        args.unshift(long.map((term) => `"${term.replace(/"/g, '""')}"`).join(" "));
+    }
+    for (const term of short) {
+        where.push("text LIKE ? ESCAPE '\\'");
+        args.push(likeOf(term));
+    }
+    return {
+        sql: `SELECT text, session, seq, time, who FROM lines WHERE ${where.join(" AND ")} ORDER BY ${long.length > 0 ? "rank" : "time DESC"} LIMIT ${limit}`,
+        args,
+    };
+}
+export function install(rt) {
+    const { ctx, home } = rt;
+    const controller = () => ctx.sessionController;
+    const partLines = (sessionId, signal) => rt.partLines(sessionId, signal);
+    const indexPath = join(home, "chat-index.sqlite");
+    let chatIndex;
+    let indexOpening;
+    // A Session's events from newest to oldest, also for an archived part.
+    async function* eventsBackwards(sessionId, signal, maxPages = HISTORY_PAGES_MAX) {
+        const agent = (await rt.resolveAgent(sessionId));
+        const throughSeq = Number(agent.session?.seq) - 1;
+        let beforeSeq;
+        for (let pages = 0; throughSeq >= 0 && pages < maxPages; pages += 1) {
+            const page = await controller().page({
+                address: { kind: "session", sessionId },
+                throughSeq,
+                ...(beforeSeq === undefined ? {} : { beforeSeq }),
+                maxMessages: HISTORY_PAGE,
+            }, signal);
+            const events = page.records.map((record) => record.event);
+            for (let index = events.length - 1; index >= 0; index -= 1)
+                yield events[index];
+            if (!page.hasMore || events.length === 0)
+                return;
+            beforeSeq = events[0].seq;
+        }
+    }
+    function createIndex(db) {
+        try {
+            db.exec("PRAGMA journal_mode = WAL");
+            const version = Number(db.prepare("PRAGMA user_version").get()?.user_version);
+            if (version !== INDEX_VERSION) {
+                db.exec(`
+          DROP TABLE IF EXISTS lines;
+          DROP TABLE IF EXISTS marks;
+          CREATE VIRTUAL TABLE lines USING fts5(text, session UNINDEXED, seq UNINDEXED, time UNINDEXED, who UNINDEXED, tokenize = 'trigram');
+          CREATE TABLE marks (session TEXT PRIMARY KEY, through INTEGER NOT NULL, keep INTEGER NOT NULL, sealed INTEGER NOT NULL, turn INTEGER NOT NULL);
+          PRAGMA user_version = ${INDEX_VERSION};`);
+            }
+            return {
+                db,
+                mark: db.prepare("SELECT through, keep, sealed, turn FROM marks WHERE session = ?"),
+                setMark: db.prepare("INSERT OR REPLACE INTO marks (session, through, keep, sealed, turn) VALUES (?, ?, ?, ?, ?)"),
+                insert: db.prepare("INSERT INTO lines (text, session, seq, time, who) VALUES (?, ?, ?, ?, ?)"),
+                before: db.prepare("SELECT text, session, seq, time, who FROM lines WHERE session = ? AND seq < ? ORDER BY seq DESC LIMIT ?"),
+                from: db.prepare("SELECT text, session, seq, time, who FROM lines WHERE session = ? AND seq >= ? ORDER BY seq LIMIT ?"),
+            };
+        }
+        catch (error) {
+            db.close();
+            throw error;
+        }
+    }
+    function openIndex() {
+        if (chatIndex !== undefined)
+            return Promise.resolve(chatIndex);
+        if (indexOpening !== undefined)
+            return indexOpening;
+        const opening = (async () => {
+            let DatabaseSync;
+            try {
+                // Loaded at run time on purpose: `node:sqlite` is an optional native module,
+                // and a host without it must still load and scan the logs (see the file head).
+                ({ DatabaseSync } = (await import("node:sqlite")));
+                await mkdir(home, { recursive: true });
+            }
+            catch (error) {
+                rt.warn("ocean-crew: no chat index, read_own_chat scans the logs: %s", error);
+                return null;
+            }
+            // A damaged file is rebuilt from the logs once.
+            for (const fresh of [false, true]) {
+                try {
+                    if (fresh)
+                        await unlink(indexPath).catch(() => undefined);
+                    return createIndex(new DatabaseSync(indexPath));
+                }
+                catch (error) {
+                    if (fresh)
+                        rt.warn("ocean-crew: no chat index, read_own_chat scans the logs: %s", error);
+                }
+            }
+            return null;
+        })();
+        let tracked;
+        tracked = opening.then((index) => {
+            // The plugin may have been disposed while the file opened.
+            if (indexOpening !== tracked) {
+                index?.db.close();
+                return null;
+            }
+            chatIndex = index ?? undefined;
+            return index;
+        });
+        indexOpening = tracked;
+        return tracked;
+    }
+    ctx.effect(() => () => {
+        chatIndex?.db.close();
+        chatIndex = undefined;
+        indexOpening = undefined;
+    }, "ocean-crew: chat index");
+    // Adds what a part said since its mark. Reads of one part wait for each other, so no
+    // line is added twice.
+    const catchingUp = new Map();
+    function catchUp(index, part) {
+        const running = catchingUp.get(part.sessionId);
+        if (running !== undefined)
+            return running;
+        const job = (async () => {
+            const mark = index.mark.get(part.sessionId);
+            if (mark?.sealed)
+                return;
+            const through = mark?.through ?? -1;
+            const events = [];
+            for await (const event of eventsBackwards(part.sessionId, AbortSignal.timeout(INDEX_TIMEOUT_MS), Infinity)) {
+                if (event.seq <= through)
+                    break;
+                events.push(event);
+            }
+            if (events.length > 0 && events[events.length - 1].seq !== through + 1)
+                throw new Error(`the history of ${part.sessionId} came back with a gap`);
+            events.reverse();
+            if (index !== chatIndex)
+                return;
+            let keep = mark ? mark.keep === 1 : false;
+            let turn = mark?.turn ?? -1;
+            const seal = part.endedAt !== undefined && Date.now() - part.endedAt > SEAL_AFTER_MS;
+            index.db.exec("BEGIN");
+            try {
+                let last = through;
+                for (const event of events) {
+                    last = event.seq;
+                    if (event.type === "turn/start")
+                        turn = event.seq;
+                    const entry = rt.historyEntry(event, false);
+                    if (entry === undefined)
+                        continue;
+                    if (entry.answer === true) {
+                        if (keep)
+                            index.insert.run(entry.text, part.sessionId, event.seq, event.time ?? 0, "you");
+                        continue;
+                    }
+                    keep = entry.keepAnswers === true;
+                    if (entry.text !== "")
+                        index.insert.run(entry.text, part.sessionId, event.seq, event.time ?? 0, entry.who ?? "");
+                }
+                index.setMark.run(part.sessionId, last, keep ? 1 : 0, seal ? 1 : 0, turn);
+                index.db.exec("COMMIT");
+            }
+            catch (error) {
+                index.db.exec("ROLLBACK");
+                throw error;
+            }
+        })().finally(() => catchingUp.delete(part.sessionId));
+        catchingUp.set(part.sessionId, job);
+        return job;
+    }
+    // A message's anchor: its part (once there are several) and its seq in that part.
+    const anchorOf = (parts, row) => {
+        const part = parts.find((item) => item.sessionId === row.session);
+        return `${parts.length > 1 ? `part ${part?.number ?? "?"} ` : ""}#${row.seq}`;
+    };
+    const rowLine = (parts, row, terms = [], max = OWN_CHAT_LINE_MAX) => {
+        const lower = row.text.toLowerCase();
+        const wanted = terms.find((term) => lower.includes(term)) ?? "";
+        const text = row.who === "user" ? `User: ${row.text}` : row.who === "you" ? `You: ${row.text}` : row.text;
+        return `[${anchorOf(parts, row)} · ${rt.clock(row.time)}] ${excerpt(text, wanted, max)}`;
+    };
+    // Every part, caught up. Asked from the current part, the turn that asks is left out
+    // (`hidden`): it is in context, and its own question would match.
+    async function indexedParts(botId, askingId) {
+        const index = await openIndex();
+        if (index === null)
+            return { index, parts: [] };
+        const parts = rt.partsOf(botId);
+        // A part that cannot be read now is searched as far as it was indexed.
+        for (const part of parts)
+            await catchUp(index, part).catch((error) => rt.warn("ocean-crew: indexing %s failed: %s", part.sessionId, error));
+        const turn = askingId !== undefined && askingId === parts.at(-1)?.sessionId
+            ? index.mark.get(askingId)?.turn
+            : undefined;
+        return {
+            index,
+            parts,
+            hidden: turn === undefined || turn < 0 ? undefined : { session: askingId, from: turn },
+        };
+    }
+    // Messages with all the words, best first; with none of them having all, those with
+    // the most of them. Shown oldest first.
+    async function searchOwnChat(botId, query, { askingId, limit = OWN_CHAT_SEARCH } = {}) {
+        const terms = [...new Set(query.toLowerCase().split(/\s+/).filter(Boolean))].slice(0, SEARCH_TERMS_MAX);
+        const { index, parts, hidden } = await indexedParts(botId, askingId);
+        if (index === null)
+            return { lines: await scanOwnChat(botId, query, limit), every: true };
+        const sessions = parts.map((part) => part.sessionId);
+        const run = (wanted, max) => {
+            const { sql, args } = termQuery(wanted, sessions, max, hidden);
+            return index.db.prepare(sql).all(...args);
+        };
+        const byTime = (a, b) => a.time - b.time || sessions.indexOf(a.session) - sessions.indexOf(b.session) || a.seq - b.seq;
+        let rows = run(terms, limit);
+        let every = true;
+        if (rows.length === 0 && terms.length > 1) {
+            every = false;
+            const found = new Map();
+            for (const term of terms) {
+                for (const row of run([term], ANY_TERM_HITS)) {
+                    const key = `${row.session}#${row.seq}`;
+                    const hit = found.get(key) ?? { row, count: 0 };
+                    hit.count += 1;
+                    found.set(key, hit);
+                }
+            }
+            rows = [...found.values()]
+                .sort((a, b) => b.count - a.count || b.row.time - a.row.time)
+                .slice(0, limit)
+                .map((hit) => hit.row);
+        }
+        return { lines: rows.sort(byTime).map((row) => rowLine(parts, row, terms)), every };
+    }
+    // The latest messages across all parts, oldest first.
+    async function latestOwnChat(botId, { askingId, limit = OWN_CHAT_READ } = {}) {
+        const { index, parts, hidden } = await indexedParts(botId, askingId);
+        if (index === null)
+            return scanOwnChat(botId, "", limit);
+        const rows = [];
+        for (const part of [...parts].reverse()) {
+            const below = hidden?.session === part.sessionId ? hidden.from : Number.MAX_SAFE_INTEGER;
+            rows.push(...index.before.all(part.sessionId, below, limit - rows.length));
+            if (rows.length >= limit)
+                break;
+        }
+        return rows.reverse().map((row) => rowLine(parts, row));
+    }
+    // The messages around an anchor, in its part.
+    async function aroundOwnChat(botId, anchor) {
+        const { index, parts } = await indexedParts(botId);
+        if (index === null)
+            return { error: "Anchors need the chat index, which is unavailable here. Search with words instead." };
+        const found = /(?:part\s*)?(\d+)?\s*#\s*(\d+)/i.exec(anchor);
+        if (found === null)
+            return {
+                error: `"${anchor}" is not an anchor. Anchors look like "part 2 #1234", or "#1234" in the current part.`,
+            };
+        const number = found[1] === undefined ? parts.length : Number(found[1]);
+        const part = parts[number - 1];
+        if (part === undefined)
+            return { error: `Your own chat has no part ${number}.` };
+        const seq = Number(found[2]);
+        const rows = [
+            ...index.before.all(part.sessionId, seq, AROUND_LINES).reverse(),
+            ...index.from.all(part.sessionId, seq, AROUND_LINES + 1),
+        ];
+        return {
+            part,
+            exact: rows.some((row) => row.seq === seq),
+            lines: rows.map((row) => rowLine(parts, row, [], row.seq === seq ? ANCHOR_LINE_MAX : OWN_CHAT_LINE_MAX)),
+        };
+    }
+    // Without the index: what the user, other Bots, and the Bot itself said, across all
+    // parts, oldest first, by reading the logs.
+    async function scanOwnChat(botId, query, limit) {
+        const wanted = query.toLowerCase();
+        const parts = rt.partsOf(botId);
+        const signal = AbortSignal.timeout(HISTORY_TIMEOUT_MS);
+        const lines = [];
+        for (const part of [...parts].reverse()) {
+            for await (const line of partLines(part.sessionId, signal)) {
+                if (wanted !== "" && !line.text.toLowerCase().includes(wanted))
+                    continue;
+                lines.push(`[${parts.length > 1 ? `part ${part.number} · ` : ""}${rt.clock(line.time)}] ${excerpt(line.text, wanted)}`);
+                if (lines.length >= limit)
+                    break;
+            }
+            if (lines.length >= limit)
+                break;
+        }
+        return lines.reverse();
+    }
+    // The parts of a Bot's own chat, for the model: when each ran.
+    const partIndex = (parts) => parts
+        .map((part) => `part ${part.number} (${rt.clock(part.startedAt)} – ${part.endedAt === undefined ? "now" : rt.clock(part.endedAt)})`)
+        .join(", ");
+    async function ownChatBrief(member) {
+        let lines = [];
+        try {
+            lines = await latestOwnChat(member.id, { limit: OWN_CHAT_BRIEF });
+        }
+        catch (error) {
+            rt.warn("ocean-crew: brief for %s failed: %s", member.name, error);
+        }
+        return [
+            "Your own chat with the user so far (latest messages, oldest first; private, so share only what the group needs):",
+            lines.length > 0 ? lines.join("\n") : "Nothing yet.",
+            "This brief does not change. Call read_own_chat when you need something newer or older from your own chat.",
+        ].join("\n");
+    }
+    Object.assign(rt, { eventsBackwards, searchOwnChat, latestOwnChat, aroundOwnChat, partIndex, ownChatBrief });
+}

package/dist/host/chat/delivery.js

@@ -0,0 +1,231 @@
+// Delivery: how one Bot, the user, or Ocean Crew itself puts a message into a Bot
+// Session. A relay carries a header line, a producer source that turns and resume read,
+// and its exchange record. A message past MESSAGE_INLINE_MAX goes as a DSH file instead
+// of whole into every Session it reaches.
+import { randomUUID } from "node:crypto";
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+import { HISTORY_TIMEOUT_MS, LONG_HEAD, MESSAGE_INLINE_MAX, READ_LINE_MAX, SOURCE_KIND, TEXT_KEPT, TEXT_SHOW_MAX, } from "../core/constants.js";
+import { headOf, textOf } from "../core/text.js";
+// The roles recorded as team exchanges; the others inform a turn without waiting for it.
+const EXCHANGE_ROLES = new Set(["request", "reply", "stopped"]);
+const createRelayMessage = createUserMessage;
+const sessionsService = (ctx) => ctx.sessions;
+const attachmentsService = (ctx) => ctx.get?.("attachments");
+// What one delivered message says above its text. The wording is what the model reads
+// and what the client shows; it is part of the public behavior, so it is kept verbatim.
+export function headerFor(role, fromName, roomName, audience, note = "new message", deferred = false, { resumed = false, retried = false, resent = false, asker } = {}) {
+    // What came back for work another Bot gave this one says where its answer goes.
+    const goesOn = asker === undefined
+        ? ""
+        : ` · for the work ${asker} asked you for; your answer goes to ${asker} once everything you handed on is back`;
+    if (deferred && role === "reply")
+        return `[Reply from ${fromName} · you read it during your last task; go on with the work it is for now${goesOn}]`;
+    if (deferred && role === "report")
+        return `[Group chat "${roomName}" · replies to your post · you read them during your last task; go on with the work they are for now${goesOn}]`;
+    if (deferred && role !== "room")
+        return `[Message from ${fromName} · you read it during your last task; answer it now]`;
+    if (retried && role !== "room")
+        return "[Your last reply wrote a tool call as text, so nothing ran]";
+    if (resumed && role === "resume")
+        return "[DeepSeek Harness restarted while you were working]";
+    if (resumed && role !== "room")
+        return `[Message from ${fromName} · DeepSeek Harness restarted while you were working on it]`;
+    if (resent && role === "reply")
+        return `[Reply from ${fromName} · DeepSeek Harness restarted before it could reach you]`;
+    if (resent && role !== "room")
+        return `[Message from ${fromName} · DeepSeek Harness restarted before it could reach you]`;
+    if (role === "reply")
+        return `[Reply from ${fromName}${goesOn}]`;
+    if (role === "stopped")
+        return `[Stopped by ${fromName}]`;
+    if (role === "room")
+        return `[Group chat "${roomName}" · ${note}]`;
+    if (role === "report")
+        return `[Group chat "${roomName}" · replies to your post${goesOn}]`;
+    if (role === "kickoff")
+        return "[Bot team setup]";
+    if (role === "continue")
+        return "[Retry after a failed turn]";
+    // The editor can be the user or a Bot (its own tool call, or a Main Bot's): the
+    // header stays neutral about who changed the profile.
+    if (role === "update")
+        return "[Your profile was updated — follow the latest version]";
+    if (role === "secret")
+        return "[Secret card]";
+    if (audience === "user")
+        return `[Message from ${fromName} · the user sees your reply here]`;
+    return `[Message from ${fromName}]`;
+}
+export function install(rt) {
+    const { ctx, state } = rt;
+    // The Agent a Session is on now, opened if needed. A Session DSH cannot open rejects
+    // with the code DSH gave, so the caller can tell a gone Session from a failure.
+    const resolveAgent = async (sessionId) => {
+        const controller = ctx.sessionController;
+        const resolved = await controller.resolveAgent(sessionId);
+        if ("error" in resolved)
+            throw Object.assign(new Error(resolved.error?.message ?? "Session unavailable"), {
+                code: resolved.error?.code,
+            });
+        rt.hideBotUnusedTools?.(resolved.agent);
+        return resolved.agent;
+    };
+    // `sessionId` defaults to the recipient's own chat; group turns name its group Session.
+    // `deferred`: a request the Bot already read mid-turn, handed back to answer in a turn
+    // of its own; its exchange was recorded when it first arrived. `resumed` and
+    // `retried` carry on a turn a restart cut off or that wrote its tool call as text;
+    // their exchange is recorded already too. `resent` is a message a shutdown cancelled;
+    // its first send may not have been recorded. `askedBy` is the member whose @mention
+    // called a group turn. `fromRoomId`: the group whose Session the sender wrote from;
+    // the reply goes back to that Session. `images` and `files` go along as image and
+    // file blocks, which DSH projects for the recipient's model and tools. `length`: the
+    // whole message's length when it went as a file (attachLong). `work`: the work a
+    // result that came back goes on with.
+    // one its recipient had not read, under that one's exchange.
+    async function deliver(args) {
+        const { fromId, toId, sessionId, text, role, replyTo, roomId, audience, note, exchangeId = randomUUID(), steer = false, deferred = false, resumed = false, retried = false, resent = false, merged = false, askedBy, fromRoomId, images = [], files = [], length, work, } = args;
+        const from = rt.botOf(fromId);
+        const to = rt.botOf(toId);
+        if (to === undefined)
+            throw new Error(`Unknown Bot ${toId}`);
+        const fromName = from?.name ?? "You";
+        const room = rt.roomOf(roomId);
+        const asker = work === undefined ? undefined : rt.botOf(state.works?.[work]?.from)?.name;
+        // Session events reject `undefined` members, so optional fields are omitted instead.
+        const source = {
+            kind: SOURCE_KIND,
+            form: "relay",
+            role,
+            exchangeId,
+            senderName: fromName,
+            ...(work ? { work } : {}),
+            ...(fromId ? { senderSessionId: fromId } : {}),
+            ...(replyTo ? { replyTo } : {}),
+            ...(roomId ? { roomId } : {}),
+            ...(audience === "user" ? { audience } : {}),
+            ...(deferred ? { deferred: true } : {}),
+            ...(resumed ? { resumed: true } : {}),
+            ...(retried ? { retried: true } : {}),
+            ...(askedBy ? { askedBy } : {}),
+            ...(fromRoomId ? { senderRoomId: fromRoomId } : {}),
+        };
+        const targetSessionId = sessionId ?? rt.chatOf(toId);
+        await rt.ensureCapabilities?.(targetSessionId);
+        const agent = await resolveAgent(targetSessionId);
+        // A steered message cuts into a running turn at its next step; a follow-up queues
+        // for the next turn.
+        const message = createRelayMessage({
+            content: [
+                {
+                    type: "text",
+                    text: `${headerFor(role, fromName, room?.name, audience, note, deferred, { resumed, retried, resent, asker })}\n${text}`,
+                },
+                ...images.map((attachment) => ({ type: "image", attachment })),
+                ...files.map((attachment) => ({ type: "file", attachment })),
+            ],
+            source,
+        });
+        if (steer)
+            agent.steer(message);
+        else
+            agent.followup(message);
+        await sessionsService(ctx).flush(agent.session);
+        if (EXCHANGE_ROLES.has(role) && !deferred && !resumed && !retried) {
+            // failed delivery as delivered. The whole text is in its file, or in the
+            // Session it goes to; exchangeText reads it back there.
+            const kept = headOf(text, TEXT_KEPT);
+            const whole = length !== undefined
+                ? { length, files }
+                : kept.length < text.length
+                    ? { length: text.length, sessionId: targetSessionId }
+                    : {};
+            const entry = {
+                id: exchangeId,
+                from: fromId ?? "",
+                to: toId,
+                text: kept,
+                ...whole,
+                role,
+                time: Date.now(),
+                ...(replyTo ? { replyTo } : {}),
+                ...(audience === "user" ? { audience } : {}),
+            };
+            const earlier = state.exchanges.findIndex((other) => other.id === exchangeId);
+            if (earlier === -1)
+                state.exchanges.push(entry);
+            else if (merged)
+                state.exchanges[earlier] = entry;
+            void rt.save().catch(() => { });
+        }
+        return exchangeId;
+    }
+    // A message between Bots, whole, from the Session it was delivered to: the message
+    // there is its header line, then the text. `whole` is false when only the start could
+    // be read (the Session is gone, or the message is past what the dialog shows).
+    async function exchangeText(entry) {
+        if (entry.length === undefined)
+            return { text: entry.text, whole: true };
+        const files = entry.files ?? [];
+        if (files.length > 0)
+            return (await fileText(files[0])) ?? { text: entry.text, whole: false };
+        try {
+            // The durable Session log reader is a later module's; without it the call throws
+            // and the start of the message, said to be only that, is the answer.
+            for await (const event of rt.eventsBackwards(entry.sessionId ?? rt.chatOf(entry.to), AbortSignal.timeout(HISTORY_TIMEOUT_MS))) {
+                if (event.type !== "user/message" || event.data?.source?.exchangeId !== entry.id)
+                    continue;
+                const delivered = textOf(event.data.content);
+                const text = delivered.slice(delivered.indexOf("\n") + 1);
+                return { text: headOf(text, TEXT_SHOW_MAX), whole: text.length <= TEXT_SHOW_MAX };
+            }
+        }
+        catch (error) {
+            rt.warn("ocean-crew: message %s not read back: %s", entry.id, error);
+        }
+        return { text: entry.text, whole: false };
+    }
+    // A message a Bot sends past MESSAGE_INLINE_MAX goes as a DSH file: it is stored once,
+    // not in every Session it reaches, and the model reads it with its file tools when it
+    // needs it. Undefined when this DSH cannot store files.
+    async function attachLong(text, name) {
+        if (text.length <= MESSAGE_INLINE_MAX)
+            return { text, files: [] };
+        try {
+            const attachments = attachmentsService(ctx);
+            const file = await attachments?.saveFile?.({ data: new TextEncoder().encode(text), name });
+            if (file === undefined)
+                return undefined;
+            // The file stays verbatim, so a line past what the read tool shows needs
+            // another way.
+            const wide = text.split("\n").some((line) => line.length > READ_LINE_MAX);
+            const note = `[A long message: ${text.length} characters. Its start is below; all of it is in the attached file. Read the file before you act on it.${wide ? ` Some lines are longer than the ${READ_LINE_MAX} characters the read tool shows of a line; read those with a shell command.` : ""}]`;
+            return { text: `${note}\n${headOf(text, LONG_HEAD)}…`, files: [file], length: text.length };
+        }
+        catch (error) {
+            rt.warn("ocean-crew: long message not stored as a file: %s", error);
+            return undefined;
+        }
+    }
+    // The text of a stored file, up to what the dialogs show.
+    async function fileText(file) {
+        const attachments = attachmentsService(ctx);
+        if (attachments?.readFileStream === undefined)
+            return undefined;
+        const decoder = new TextDecoder();
+        let text = "";
+        try {
+            for await (const chunk of attachments.readFileStream(file, AbortSignal.timeout(HISTORY_TIMEOUT_MS))) {
+                text += decoder.decode(chunk, { stream: true });
+                if (text.length > TEXT_SHOW_MAX)
+                    return { text: headOf(text, TEXT_SHOW_MAX), whole: false };
+            }
+        }
+        catch (error) {
+            rt.warn("ocean-crew: file %s not read: %s", file?.name, error);
+            return undefined;
+        }
+        text += decoder.decode();
+        return { text, whole: true };
+    }
+    Object.assign(rt, { resolveAgent, deliver, exchangeText, attachLong, fileText });
+}