renor-engine 0.0.0-stage → 1.0.0

package/dist/memory/limits.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_STATEMENT_LENGTH = void 0;
+/**
+ * The longest statement `remember` admits, in UTF-16 code units (what `String.length` counts, and what
+ * a zod `.max()` on a string counts).
+ *
+ * One number for every place that stores the user's words: the MCP schema, the ledger's `statement`
+ * field and the daily-note writer all read it from here, so a statement that is admitted is a statement
+ * that is kept. They used to disagree (4000 admitted, 2000 written) and the writer cut the difference
+ * without a word.
+ */
+exports.MAX_STATEMENT_LENGTH = 4000;

package/dist/memory/requests.js

@@ -0,0 +1,183 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUEST_PAGE_LIMIT = exports.DEFAULT_ASK_AGENT_PER_HOUR = void 0;
+exports.askAgentPerHour = askAgentPerHour;
+exports.noteKnownAgent = noteKnownAgent;
+exports.askAgent = askAgent;
+exports.listRequests = listRequests;
+exports.listRequestsPage = listRequestsPage;
+exports.answerRequest = answerRequest;
+exports.closeRequest = closeRequest;
+const crypto_1 = __importDefault(require("crypto"));
+const scope_1 = require("../mvp/scope");
+const controls_1 = require("./controls");
+const sourceName_1 = require("./sourceName");
+const STATUSES = new Set(['open', 'answered', 'closed']);
+/** How many requests one sending connection may record per rolling hour, unless RENOR_ASK_AGENT_PER_HOUR says otherwise. */
+exports.DEFAULT_ASK_AGENT_PER_HOUR = 30;
+const HOUR_MS = 60 * 60 * 1000;
+/** The hourly limit for ask_agent: RENOR_ASK_AGENT_PER_HOUR when it is a positive integer, otherwise the default. */
+function askAgentPerHour() {
+    const raw = Number(process.env.RENOR_ASK_AGENT_PER_HOUR);
+    return Number.isInteger(raw) && raw > 0 ? raw : exports.DEFAULT_ASK_AGENT_PER_HOUR;
+}
+/** Records a connection name the gateway set (x-renor-agent), so ask_agent can address it. "unnamed" is never recorded. */
+function noteKnownAgent(db, agent, now = new Date()) {
+    if (agent === 'unnamed')
+        return;
+    db.prepare('INSERT OR IGNORE INTO known_agents (agent, first_seen) VALUES (?, ?)').run(agent, now.toISOString());
+}
+function isKnownAgent(db, agent) {
+    return db.prepare('SELECT 1 FROM known_agents WHERE agent = ?').get(agent) !== undefined;
+}
+function row(db, id) {
+    const found = db.prepare('SELECT * FROM agent_requests WHERE id = ?').get(id);
+    if (!found)
+        throw new Error('no request with that id');
+    return found;
+}
+function askAgent(db, args) {
+    const rawTo = args.to.trim();
+    const question = args.request.trim();
+    if (!rawTo)
+        throw new Error('ask_agent needs who it is for');
+    if (!question)
+        throw new Error('ask_agent needs a request');
+    // Store the header form, the same name stdio and hosted publish. A spelling a header cannot render is unnamed.
+    const to = (0, sourceName_1.hiveIdentity)(rawTo);
+    const from = (0, sourceName_1.hiveIdentity)(args.from);
+    if (!from)
+        throw new Error('ask_agent needs a connection name');
+    if (!to)
+        throw new Error('ask_agent cannot address unnamed: that is every connection whose key has no name. Name the key, then ask it by that name');
+    // A request is text another agent reads, so it is held to the same rule as a memory: no control
+    // character a reader cannot see (memory/controls.ts). Checked before anything is stored.
+    (0, controls_1.assertNoUnstorableControls)('ask_agent to', to);
+    (0, controls_1.assertNoUnstorableControls)('ask_agent request', question);
+    const now = args.now ?? new Date();
+    if (args.knownOnly) {
+        if (!isKnownAgent(db, to))
+            throw new Error(`no connection named ${JSON.stringify(to)} has connected to this workspace; ask_agent addresses an agent by the name on its connection key`);
+    }
+    if (args.perHour !== undefined) {
+        const since = new Date(now.getTime() - HOUR_MS).toISOString();
+        const recent = db.prepare('SELECT COUNT(*) AS n, MIN(created_at) AS oldest FROM agent_requests WHERE from_agent = ? AND created_at > ?').get(from, since);
+        if (recent.n >= args.perHour) {
+            const retry = new Date(Date.parse(recent.oldest) + HOUR_MS).toISOString();
+            throw new Error(`ask_agent is limited to ${args.perHour} requests per hour per connection; this one can ask again after ${retry}`);
+        }
+    }
+    const id = `req_${crypto_1.default.randomBytes(8).toString('hex')}`;
+    const created = now.toISOString();
+    db.prepare(`INSERT INTO agent_requests (id, scope, from_agent, to_agent, question, answer, status, created_at, answered_at, closed_at)
+     VALUES (?, ?, ?, ?, ?, NULL, 'open', ?, NULL, NULL)`).run(id, args.scope !== undefined && args.scope.trim() !== '' ? (0, scope_1.normalizeScope)(args.scope) : null, from, to, question, created);
+    return { id, status: 'open', from_agent: from, to_agent: to, created_at: created };
+}
+/** At most this many requests one list returns, the newest; the rest are counted. whats_new leads with the same number. */
+exports.REQUEST_PAGE_LIMIT = 20;
+function listWhere(args) {
+    const status = args.status ?? 'open';
+    if (!STATUSES.has(status))
+        throw new Error('list_requests status must be open, answered or closed');
+    const caller = (0, sourceName_1.hiveIdentity)(args.agent) ?? args.agent.trim();
+    let sql;
+    const params = [];
+    if (args.to !== undefined && args.to.trim() !== '') {
+        // `to` names the other party of a thread, not an inbox to read. Both directions count: the request
+        // this connection asked of that agent, and the request that agent asked of this one. A connection
+        // that is neither party to a thread cannot list it, and cannot page through it.
+        const other = (0, sourceName_1.hiveIdentity)(args.to);
+        if (!other)
+            throw new Error('list_requests cannot address unnamed: that is every connection whose key has no name. Name the key, then ask it by that name');
+        sql = 'status = ? AND ((from_agent = ? AND to_agent = ?) OR (from_agent = ? AND to_agent = ?))';
+        params.push(status, caller, other, other, caller);
+    }
+    else {
+        // With no `to` this is the caller's own inbox, exactly as it has always been.
+        sql = 'status = ? AND to_agent = ?';
+        params.push(status, caller);
+    }
+    let scopeSql = '';
+    if (args.scope !== undefined && args.scope.trim() !== '') {
+        // Every spelling of the scope (atlas, scope:atlas, project:atlas); a request asked with no scope is global.
+        const saved = (0, scope_1.savedScopeSqlPredicate)((0, scope_1.normalizeScope)(args.scope), "COALESCE(scope, 'global')");
+        scopeSql = ` AND ${saved.sql}`;
+        params.push(...saved.params);
+    }
+    return { sql: `${sql}${scopeSql}`, params, caller };
+}
+/** An answer is for the agent who asked and the one who answered; anyone else sees that it was answered, not what. */
+function visibleTo(agent, r) {
+    return r.from_agent === agent || r.to_agent === agent ? r : { ...r, answer: null };
+}
+/** Every request matching `args`, newest first. Unbounded: the tools read `listRequestsPage`. */
+function listRequests(db, args) {
+    const where = listWhere(args);
+    const rows = db.prepare(`SELECT * FROM agent_requests WHERE ${where.sql} ORDER BY created_at DESC, rowid DESC`).all(...where.params);
+    return rows.map((r) => visibleTo(args.agent, r));
+}
+/**
+ * The newest REQUEST_PAGE_LIMIT requests matching `args` (older than `args.before` when given), and how many more there
+ * are (`more_requests`, absent when none) with the call that lists them (`more_requests_hint`). What list_requests and
+ * whats_new return: a flood of requests costs a reader one bounded page, never all of it.
+ */
+function listRequestsPage(db, args) {
+    const where = listWhere(args);
+    let sql = where.sql;
+    const params = [...where.params];
+    if (args.before !== undefined && args.before.trim() !== '') {
+        // Same order as the list (created_at, then insertion): strictly after the given request in it.
+        // The anchor has to be a request this caller is a party to. Another pair's id is not a page cursor.
+        const anchor = db.prepare('SELECT created_at, rowid AS rid FROM agent_requests WHERE id = ? AND (from_agent = ? OR to_agent = ?)').get(args.before.trim(), where.caller, where.caller);
+        if (!anchor)
+            throw new Error('list_requests before must be the id of a request from whats_new or list_requests');
+        sql += ' AND (created_at < ? OR (created_at = ? AND rowid < ?))';
+        params.push(anchor.created_at, anchor.created_at, anchor.rid);
+    }
+    const rows = db.prepare(`SELECT * FROM agent_requests WHERE ${sql} ORDER BY created_at DESC, rowid DESC LIMIT ?`).all(...params, exports.REQUEST_PAGE_LIMIT);
+    const requests = rows.map((r) => visibleTo(args.agent, r));
+    if (requests.length < exports.REQUEST_PAGE_LIMIT)
+        return { requests };
+    const total = db.prepare(`SELECT COUNT(*) AS n FROM agent_requests WHERE ${sql}`).get(...params).n;
+    if (total <= requests.length)
+        return { requests };
+    const more = total - requests.length;
+    const last = requests[requests.length - 1].id;
+    return {
+        requests,
+        more_requests: more,
+        more_requests_hint: `${more} older request${more === 1 ? '' : 's'} not shown; use list_requests with before=${last}`,
+    };
+}
+function answerRequest(db, args) {
+    const found = row(db, args.id);
+    if (found.to_agent !== args.agent)
+        throw new Error('only the agent this request is for can answer it');
+    if (found.status === 'closed')
+        throw new Error('a closed request cannot be answered');
+    const answer = args.answer.trim();
+    if (!answer)
+        throw new Error('answer_request needs an answer');
+    // The same rule ask_agent holds to: an answer is text another agent reads back (memory/controls.ts).
+    (0, controls_1.assertNoUnstorableControls)('answer_request answer', answer);
+    const at = (args.now ?? new Date()).toISOString();
+    // The guard is in the statement too: a close on another handle between the read above and this write must win.
+    const changed = db.prepare(`UPDATE agent_requests SET status = 'answered', answer = ?, answered_at = ? WHERE id = ? AND status != 'closed'`).run(answer, at, args.id).changes;
+    if (changed === 0)
+        throw new Error('a closed request cannot be answered');
+    return row(db, args.id);
+}
+function closeRequest(db, args) {
+    const found = row(db, args.id);
+    if (found.to_agent !== args.agent && found.from_agent !== args.agent) {
+        throw new Error('only the agent this request is for, or the one who asked, can close it');
+    }
+    if (found.status === 'closed')
+        return found;
+    const at = (args.now ?? new Date()).toISOString();
+    db.prepare(`UPDATE agent_requests SET status = 'closed', closed_at = ? WHERE id = ?`).run(at, args.id);
+    return row(db, args.id);
+}

package/dist/memory/sourceName.js

@@ -0,0 +1,200 @@
+"use strict";
+/**
+ * The source of a memory: a short name for who or what saved it (`claude-code`, `cursor`, `executor-3`). It is stored with
+ * the entry, in the daily-note header (`- [08:30:00] (cursor) ...`) and in the ledger event (`- source: cursor`), and shown
+ * beside it ("by cursor").
+ *
+ * A client may send more than a name. An agent that builds its call by hand sometimes sends where the words came from
+ * instead: a file path (`/home/ana/project/BOARD.md`), a Windows path, a URL. That is a location, not a name, and the two
+ * stores each did the wrong thing with it. The daily-note header deletes every character that is not a letter, a digit or a
+ * hyphen, so the whole path ran together into one word (`homeanaprojectBOARDmd`), with no limit on its length; the ledger
+ * kept the path as sent, the directories of the sender's machine in it, and refused the whole save past 256 characters.
+ *
+ * Three rules, shared by both writers and by the hosted tools:
+ *  - `cleanSource`: a location is reduced to the name it ends in and the name is cut at MAX_SOURCE_LENGTH characters. A path
+ *    becomes its last component; a URL becomes its host, or with no host the last component of its path, and its userinfo
+ *    (`user:password@`) is never part of what it becomes, whatever else the URL lacks or spells oddly. A `/` or `\` is what
+ *    makes a source a location, whatever else it is: `crew/executor-7` is stored as `executor-7`. The ledger stores this.
+ *    A control character is dropped first, as a URL parser drops a tab or a newline, so a stray one never loses the save and
+ *    never hides the URL a browser would read (`ht<newline>tps://user:pw@host` is `host`).
+ *    It is not a secret scanner: a URL inside a longer text is a name like any other (RENOR_SECRET_GUARD judges the rest).
+ *  - `headerSource`: what a note header stores, which keeps letters, digits and hyphens only. It is `cleanSource` with every
+ *    run of other characters written as one hyphen instead of deleted, so the words stay apart (`Claude Code` is
+ *    `Claude-Code`, `board.md` is `board-md`).
+ *  - `productFromUserAgent`: when a client names no one, the name it gives itself, the product in its User-Agent.
+ * They decide what a NEW write stores and nothing more: an entry or event written earlier is read back exactly as it was
+ * stored, and is never rewritten.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IMPORT_SOURCE_PREFIX = exports.MAX_SOURCE_LENGTH = void 0;
+exports.cleanSource = cleanSource;
+exports.headerSource = headerSource;
+exports.hiveIdentity = hiveIdentity;
+exports.productFromUserAgent = productFromUserAgent;
+exports.isImportSource = isImportSource;
+exports.savedSource = savedSource;
+exports.authorMarker = authorMarker;
+const hiveNameHeader_cjs_1 = require("./hiveNameHeader.cjs");
+/** The longest source a write stores, in characters (code points). */
+exports.MAX_SOURCE_LENGTH = 40;
+/** `scheme:` at the start. Group 1 is the scheme. It has two letters or more: `C:\\Users` and `C://Users` are a Windows drive, not a URL. */
+const SCHEME = /^([A-Za-z][A-Za-z0-9+.-]+):/;
+/**
+ * The schemes a browser reads an authority after, whatever follows the colon: any run of `/` and `\`, none included, so
+ * `https://h`, `https:/h`, `https:\h`, `https:h` and `https:///h` are one URL. Any other scheme has an authority only after two
+ * separators (`ssh://h`), and a path after fewer: a browser reads `ssh:/user:pw@h` and `ssh:user:pw@h` as paths, and
+ * `file:/home/ana/BOARD.md` as a path (`file` is not one of these).
+ */
+const WEB_SCHEME = /^(?:https?|wss?|ftp)$/i;
+/** Where a URL's authority ends: its path, query or fragment starts. */
+const AUTHORITY_END = /[\\/?#]/;
+const SEPARATOR = /[\\/]/;
+const COMPONENT_SEPARATORS = /[\\/]+/;
+/** Every control character (C0, DEL and C1): the ledger refuses the first two in a field, and a URL parser drops a tab or a newline wherever it is. */
+const CONTROL_CHARACTERS = /\p{Cc}+/gu;
+/** The last component of a path that names something: `.` and `..` do not, and a trailing separator leaves an empty one. */
+function lastComponent(location) {
+    const components = location.split(COMPONENT_SEPARATORS);
+    for (let i = components.length - 1; i >= 0; i--) {
+        const component = components[i].trim();
+        if (component !== '' && component !== '.' && component !== '..')
+            return component;
+    }
+    return '';
+}
+/** At most MAX_SOURCE_LENGTH characters, counted as the code points they are, so a letter outside the BMP is never split. */
+function cut(name) {
+    // Code units are never fewer than code points, so a short string needs no walk.
+    if (name.length <= exports.MAX_SOURCE_LENGTH)
+        return name.trim();
+    let end = 0;
+    let count = 0;
+    for (const point of name) {
+        if (count === exports.MAX_SOURCE_LENGTH)
+            break;
+        end += point.length;
+        count++;
+    }
+    return name.slice(0, end).trim();
+}
+/**
+ * `rest` without the userinfo of an authority that only a `/`, `?` or `#` ends. A browser ends the authority of a scheme that is
+ * neither a web scheme nor `file` there and nowhere else, so its userinfo may hold a `\` (`custom://\user:pw@host`), which
+ * urlName otherwise reads as the end of a host (`smb://server\share`). Everything up to the last `@` of that authority goes first.
+ */
+function afterUserinfo(rest) {
+    const end = rest.search(/[/?#]/);
+    const authority = end === -1 ? rest : rest.slice(0, end);
+    return rest.slice(authority.lastIndexOf('@') + 1);
+}
+/**
+ * What a URL names, or null when `given` is not one (no scheme, or a scheme with no authority): its host, or when it has none
+ * (`file:///home/ana/BOARD.md`, `https://user:pass@`) the last component of its path, its query and fragment left out.
+ *
+ * The userinfo (`user:password@`) is never part of the answer, because the authority is parsed rather than matched: it is
+ * what follows the scheme's separators up to the first `/`, `\`, `?` or `#`, and its userinfo is everything up to the LAST `@`
+ * in it, so a password with an unescaped `@`, an empty host, a port with no host and every spelling of the same URL a browser
+ * reads (`https:\\`, `https:///`, `https:/`, `https:`) leave the credentials in neither the host nor the path. (A scheme that is
+ * neither a web scheme nor `file` ends it at a `/`, `?` or `#` only, so a `\` can be part of its userinfo: afterUserinfo.) A
+ * path is still a path: an `@` in `file:///home/ana/notes@2024.md` is part of a file name. A URL inside a longer text is not
+ * recognised here; that is a name like any other, and so is a one-letter scheme (a Windows drive) and
+ * `jdbc:postgresql://user:pw@host`, which a browser reads as a path.
+ */
+function urlName(given) {
+    const scheme = SCHEME.exec(given);
+    if (!scheme)
+        return null;
+    let rest = given.slice(scheme[0].length);
+    if (WEB_SCHEME.test(scheme[1]))
+        rest = rest.replace(/^[\\/]+/, '');
+    else if (/^[\\/]{2}/.test(rest))
+        rest = /^file$/i.test(scheme[1]) ? rest.slice(2) : afterUserinfo(rest.slice(2));
+    else
+        return null;
+    const end = rest.search(AUTHORITY_END);
+    const authority = end === -1 ? rest : rest.slice(0, end);
+    const hostAndPort = authority.slice(authority.lastIndexOf('@') + 1);
+    // A bracketed IPv6 host keeps its colons; otherwise the host stops at the port's colon. Always matches (possibly empty).
+    const host = /^\[[^\]]*\]|^[^:]*/.exec(hostAndPort)[0];
+    if (host.trim() !== '')
+        return host;
+    return lastComponent(end === -1 ? '' : rest.slice(end).split(/[?#]/, 1)[0]);
+}
+/**
+ * The name a write stores for the `source` a client sent: a path or a URL reduced to the name it ends in, at most
+ * MAX_SOURCE_LENGTH characters, with no control character in it. It may be empty (a source that was only blanks, controls or
+ * separators, or a URL that names nothing), which names no one. Never throws on a string.
+ */
+function cleanSource(source) {
+    // Dropped, not turned into a blank: a URL parser drops a tab or a newline too, so a control character inside the scheme or
+    // between its separators (`https:/<tab>/user:pw@host`) must not hide the URL it is in.
+    const given = source.replace(CONTROL_CHARACTERS, '').trim();
+    const url = urlName(given);
+    if (url !== null)
+        return cut(url);
+    return cut(SEPARATOR.test(given) ? lastComponent(given) : given);
+}
+/**
+ * The name a daily-note header stores: letters, digits and hyphens, and nothing else, because the header's marks (`+esc`,
+ * `, UTC-03:00`) are told apart from a source name by what a name cannot hold (dailyNote.ts). Every run of other characters
+ * is written as one hyphen instead of being deleted, none at either end; accents are composed first (a macOS file name is
+ * decomposed) and a combining mark that cannot be composed is dropped. It may be empty.
+ */
+function headerSource(source) {
+    return cleanSource(source)
+        .normalize('NFC')
+        .replace(/\p{M}+/gu, '')
+        .replace(/[^\p{L}\p{N}]+/gu, '-')
+        .replace(/^-|-$/g, '');
+}
+/**
+ * The hive name of a connection, on stdio and on hosted HTTP. It is the daily-note header form, so two
+ * spellings a header cannot tell apart are one agent. All transports first use the gateway's shared
+ * header-safe reduction, including its stable hash for names with no HTTP-renderable characters.
+ * An empty final header form, or the reserved word `unnamed`, is no name.
+ */
+function hiveIdentity(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const rendered = headerSource((0, hiveNameHeader_cjs_1.hiveNameHeader)(raw));
+    if (rendered === '' || rendered === 'unnamed')
+        return null;
+    return rendered;
+}
+/**
+ * The product a client names in its User-Agent: `claude-code/2.1.289 (external, cli)` is `claude-code`. It is the name to
+ * give a memory the client saved without saying who it is. Undefined when there is no product with a letter or a digit in it.
+ */
+function productFromUserAgent(userAgent) {
+    const header = Array.isArray(userAgent) ? userAgent[0] : userAgent;
+    if (typeof header !== 'string')
+        return undefined;
+    const product = /^\s*([^\s/()]+)/.exec(header)?.[1];
+    return product !== undefined && headerSource(product) !== '' ? product : undefined;
+}
+/**
+ * The prefix every imported fact's ledger source carries (importing/plan.ts), and only an import's: it is how a read tells
+ * an imported fact from an agent's save. A named connection's author is a header name, which has no colon, so a named agent
+ * cannot write it; a source a caller chose (typed, or the product in its User-Agent) is kept off it by savedSource.
+ */
+exports.IMPORT_SOURCE_PREFIX = 'import:';
+/** Whether a stored source names an import (`import:markdown`, `import:renor-index`). */
+function isImportSource(source) {
+    return typeof source === 'string' && source.startsWith(exports.IMPORT_SOURCE_PREFIX);
+}
+/**
+ * The ledger source of a save a caller made (remember, save_memory, retire, restore): `cleanSource`, with the import prefix
+ * written as a hyphen (`import:markdown` is `import-markdown`, as a note header writes it), so no caller records a save
+ * the way an import is recorded. The import path writes its events itself and never comes through here.
+ */
+function savedSource(source) {
+    const name = cleanSource(source);
+    return isImportSource(name) ? `import-${name.slice(exports.IMPORT_SOURCE_PREFIX.length)}` : name;
+}
+function authorMarker(author, reader) {
+    const fromOther = typeof author === 'string' && author !== '' && author !== reader;
+    return {
+        ...(fromOther ? { source: author } : {}),
+        ...(isImportSource(author) ? { untrusted: true } : {}),
+    };
+}

package/dist/memory/whatsNew.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WHATS_NEW_EXCERPT_CHARS = exports.WHATS_NEW_REQUEST_LIMIT = exports.WHATS_NEW_LIMIT = void 0;
+exports.readWhatsNew = readWhatsNew;
+const scope_1 = require("../mvp/scope");
+const requests_1 = require("./requests");
+/** How many items one call returns. A full page comes with a cursor for the rest. */
+exports.WHATS_NEW_LIMIT = 50;
+const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * At most this many open requests lead a reply (the newest); the rest are counted (`more_requests`). list_requests
+ * returns the same page: the rest come up as these are answered or closed.
+ */
+exports.WHATS_NEW_REQUEST_LIMIT = requests_1.REQUEST_PAGE_LIMIT;
+/** One feed item carries this many characters of another agent's text. list_requests still returns the full question. */
+exports.WHATS_NEW_EXCERPT_CHARS = 240;
+function excerpt(text) {
+    if (text === null)
+        return null;
+    let end = 0;
+    let count = 0;
+    for (const point of text) {
+        if (count === exports.WHATS_NEW_EXCERPT_CHARS)
+            break;
+        end += point.length;
+        count++;
+    }
+    return text.slice(0, end);
+}
+// A sixth part, "peek", marks a window opened with an explicit `since`: its pages never move the mark either.
+function cursorOf(floorAt, floorId, beforeAt, beforeId, asOf, peek) {
+    const parts = [floorAt, String(floorId), beforeAt, String(beforeId), asOf];
+    if (peek)
+        parts.push('peek');
+    return parts.join('|');
+}
+function parseCursor(cursor) {
+    const parts = cursor.split('|');
+    if ((parts.length !== 5 && !(parts.length === 6 && parts[5] === 'peek')) || !parts[0] || !parts[2] || !parts[4]) {
+        throw new Error('whats_new cursor is not one this workspace issued');
+    }
+    const floorId = Number(parts[1]);
+    const beforeId = Number(parts[3]);
+    if (!Number.isInteger(floorId) || !Number.isInteger(beforeId)) {
+        throw new Error('whats_new cursor is not one this workspace issued');
+    }
+    return { floorAt: parts[0], floorId, beforeAt: parts[2], beforeId, asOf: parts[4], peek: parts.length === 6 };
+}
+/**
+ * What was saved after this agent's mark, newest first. The mark moves to `as_of` only when the
+ * page was not full, so a bounded reply cannot skip the rest. An explicit `since` is a peek: it
+ * never moves the mark, so writes between the mark and `since` are still shown by the next plain call. This agent's own rows are left out
+ * unless `includeOwn`. The first call, with no mark, starts seven days back.
+ */
+function readWhatsNew(db, args) {
+    const limit = args.limit ?? exports.WHATS_NEW_LIMIT;
+    const now = (args.now ?? new Date()).toISOString();
+    // One scope has several spellings (atlas, scope:atlas, project:atlas): read all of them and keep one mark.
+    const scope = args.scope !== undefined && args.scope.trim() !== '' ? (0, scope_1.normalizeScope)(args.scope) : null;
+    const scopeKey = scope ? (0, scope_1.scopeSpellings)(scope)[0] : '';
+    const page = args.cursor ? parseCursor(args.cursor) : null;
+    let floorAt;
+    let floorId;
+    let asOf;
+    let beforeAt = null;
+    let beforeId = null;
+    let peek = false;
+    if (page) {
+        peek = page.peek;
+        floorAt = page.floorAt;
+        floorId = page.floorId;
+        asOf = page.asOf;
+        beforeAt = page.beforeAt;
+        beforeId = page.beforeId;
+    }
+    else if (args.since) {
+        peek = true;
+        floorAt = args.since;
+        floorId = -1;
+        asOf = now;
+    }
+    else {
+        const stored = db.prepare('SELECT last_at, last_id FROM agent_cursors WHERE agent = ? AND scope = ?').get(args.agent, scopeKey);
+        if (stored) {
+            floorAt = stored.last_at;
+            floorId = stored.last_id;
+        }
+        else {
+            floorAt = new Date(Date.parse(now) - WEEK_MS).toISOString();
+            floorId = -1;
+        }
+        asOf = now;
+    }
+    const params = [floorAt, floorAt, floorId, asOf];
+    let beforeSql = '';
+    if (beforeAt !== null && beforeId !== null) {
+        beforeSql = ' AND (created_at < ? OR (created_at = ? AND id < ?))';
+        params.push(beforeAt, beforeAt, beforeId);
+    }
+    let ownSql = '';
+    if (!args.includeOwn) {
+        ownSql = ' AND (author IS NULL OR author != ?)';
+        params.push(args.agent);
+    }
+    let scopeSql = '';
+    if (scope) {
+        // A row written without a scope (before migration 19, or a note retire/restore) is global.
+        const saved = (0, scope_1.savedScopeSqlPredicate)(scope, "COALESCE(scope, 'global')");
+        scopeSql = ` AND ${saved.sql}`;
+        params.push(...saved.params);
+    }
+    params.push(limit + 1);
+    const rows = db.prepare(`SELECT id, action, summary, created_at, author, scope FROM write_events
+      WHERE (created_at > ? OR (created_at = ? AND id > ?))
+        AND created_at < ?
+        ${beforeSql}${ownSql}${scopeSql}
+      ORDER BY created_at DESC, id DESC
+      LIMIT ?`).all(...params);
+    const more = rows.length > limit;
+    const kept = more ? rows.slice(0, limit) : rows;
+    const logged = kept.map((row) => {
+        const source = row.author && row.author !== '' ? row.author : 'unnamed';
+        const other = Boolean(row.author && row.author !== '' && row.author !== args.agent);
+        return {
+            kind: row.action,
+            at: row.created_at,
+            source,
+            scope: row.scope,
+            summary: excerpt(row.summary),
+            ...(other ? { untrusted: true } : {}),
+        };
+    });
+    // Open requests stay at the front of the first page until they are answered or closed.
+    // A later cursor page does not repeat them.
+    const waiting = args.cursor ? { requests: [] } : (0, requests_1.listRequestsPage)(db, { agent: args.agent, status: 'open', scope: args.scope });
+    const open = waiting.requests.map((request) => ({
+        kind: 'request',
+        at: request.created_at,
+        source: request.from_agent,
+        scope: request.scope,
+        summary: excerpt(request.question),
+        requestId: request.id,
+        untrusted: true,
+    }));
+    const extra = waiting.more_requests
+        ? { more_requests: waiting.more_requests, more_requests_hint: waiting.more_requests_hint }
+        : {};
+    const items = [...open, ...logged];
+    if (more) {
+        const last = kept[kept.length - 1];
+        return { items, as_of: asOf, next_since: null, cursor: cursorOf(floorAt, floorId, last.created_at, last.id, asOf, peek), ...extra };
+    }
+    if (peek)
+        return { items, as_of: asOf, next_since: asOf, cursor: null, ...extra };
+    db.prepare(`INSERT INTO agent_cursors (agent, scope, last_at, last_id) VALUES (?, ?, ?, ?)
+     ON CONFLICT(agent, scope) DO UPDATE SET last_at = excluded.last_at, last_id = excluded.last_id`).run(args.agent, scopeKey, asOf, -1);
+    return { items, as_of: asOf, next_since: asOf, cursor: null, ...extra };
+}