charness 3.6.1 → 3.7.0

package/dist/todos/midTurn.d.ts

@@ -0,0 +1,75 @@
+import { type SessionKey } from '../sessionKey';
+import type { TodoBoardChanges } from './board';
+/**
+ * @description Mid-turn delivery of the project board (D21, D22): a working agent learns of another topic's change
+ * inside its turn, not only at its next prompt.
+ *
+ *   Claude    — a `PostToolUse` hook (no matcher) in the launch `--settings` file prints the conversation's INBOX file,
+ *               `DATA_DIR/todos/inbox/<session id>.json`, after the agent's next tool call: ready hook JSON whose
+ *               `additionalContext` Claude reads with that tool's result (probed on Claude Code 2.1.310). The hook
+ *               moves the file before printing it, so a text is delivered once; with no file it prints nothing.
+ *   OpenCode  — a note queued INTO the running turn (`AgentAdapter.queueNoteIntoRunningTurn`: `prompt_async`, read
+ *               between steps, with nothing of the turn reset), never while a provider retry is waited out.
+ *
+ * The bot writes the inbox (atomically) only while the session works (busy, its turn not held open) and something
+ * changed since the agent last saw it; the changes count as seen once the hook took the file (the next poll finds it
+ * gone). A waiting inbox is withdrawn wherever no tool call of the session can take it any more — a turn start the bot
+ * makes (that prompt carries the changes itself), a turn's end, a turn held open, the session's start, stop or end —
+ * and its changes stay unseen for the next prompt, so the inbox dir is empty between turns. A restart forgets what was
+ * written: at worst a change is delivered twice, never lost.
+ */
+/** What opens the note a running OpenCode turn reads (agent-facing English); the board's changes follow it. */
+export declare const todoRunningTurnNoteHeader = "[Todo] Other topics of your project changed their lists while you work. No reply is needed.";
+/** Claude Code caps a hook's `additionalContext`; the text is cut below it. */
+export declare const todoInboxMaxChars = 10000;
+/** @description Where the inboxes live: `DATA_DIR/todos/inbox`. */
+export declare function getTodoInboxDir(dataDir: string): string;
+/**
+ * @description The `PostToolUse` hook's shell command. With the inbox dir empty — nearly every tool call — it reads
+ * the input whole (the CLI must never write into a closed pipe) and exits; only while an inbox waits does it start
+ * `nodePath` (the bot's own, written at every launch) to parse the input ({@link inboxHookScript}). It always exits 0 —
+ * a hook failure must never stop the agent's tool.
+ *
+ * Only the MAIN agent takes the inbox. A sub-agent's tool call fires the hook too, with the SAME `session_id` and an
+ * `agent_id` of its own (measured on Claude Code 2.1.310); taken there, the changes would land in the sub-agent's
+ * context and count as seen while the main agent never got them.
+ */
+export declare function buildTodoInboxHookCommand(inboxDir: string, nodePath?: string): string;
+/** @description The hook output Claude reads `text` from: `additionalContext` of a `PostToolUse` hook, within the cap. */
+export declare function buildTodoInboxHookOutput(text: string): string;
+/**
+ * @name TodoMidTurnDeps
+ * @description The board's peek and seen marks, the conversation's live Claude session (`null` = no Claude backend
+ * runs it), and the note into a running turn (`false` when the backend takes none, or the turn is not running now).
+ */
+export interface TodoMidTurnDeps {
+    board: {
+        peekChanges(key: SessionKey): TodoBoardChanges | null;
+        markSeenRevisions(key: SessionKey, revisions: Readonly<Record<string, number>>): void;
+    };
+    inboxDir: string;
+    getClaudeSessionId: (key: SessionKey) => string | null;
+    postRunningTurnNote: (key: SessionKey, text: string) => Promise<boolean>;
+    /** Whether a process runs (the hook that moved an inbox aside, run as the bot's own user); `kill(pid, 0)` by default. */
+    checkIsProcessAlive?: (pid: number) => boolean;
+}
+/** @name TodoMidTurn @description What the reminder poll and the prompt choke point call. */
+export interface TodoMidTurn {
+    /** The session is busy: deliver what changed since the agent last saw the board, if anything did. */
+    deliverIfPending(key: SessionKey): Promise<void>;
+    /** Inboxes the hook took since the last look count as seen. */
+    reconcile(): void;
+    /**
+     * No tool call of the session can take its inbox any more (a turn start the bot makes, a turn's end, a turn held
+     * open, the session's start, stop or end): a waiting inbox is withdrawn — counted as seen if the hook took it
+     * meanwhile — and the copies hooks that are gone moved aside and never removed go with it.
+     */
+    discardInbox(key: SessionKey): void;
+    /**
+     * At boot: every inbox left is withdrawn — this process does not know what it carries, and a session that ended
+     * never takes its own. What it carried is still unseen, so the next prompt (or poll) delivers it again.
+     */
+    clearInboxes(): void;
+}
+export declare function createTodoMidTurn(deps: TodoMidTurnDeps): TodoMidTurn;
+//# sourceMappingURL=midTurn.d.ts.map

package/dist/todos/midTurn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"midTurn.d.ts","sourceRoot":"","sources":["../../src/todos/midTurn.ts"],"names":[],"mappings":"AAEA,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAI7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEhD;;;;;;;;;;;;;;;;;GAiBG;AAEH,+GAA+G;AAC/G,eAAO,MAAM,yBAAyB,gGAAgG,CAAC;AAIvI,+EAA+E;AAC/E,eAAO,MAAM,iBAAiB,QAAS,CAAC;AASxC,mEAAmE;AACnE,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvD;AAwBD;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAyB,GAAG,MAAM,CAOvG;AAED,0HAA0H;AAC1H,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE;QACL,WAAW,CAAC,GAAG,EAAE,UAAU,GAAG,gBAAgB,GAAG,IAAI,CAAC;QACtD,iBAAiB,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC;KACvF,CAAC;IACF,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,MAAM,GAAG,IAAI,CAAC;IACvD,mBAAmB,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzE,yHAAyH;IACzH,mBAAmB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CAChD;AAGD,6FAA6F;AAC7F,MAAM,WAAW,WAAW;IAC1B,qGAAqG;IACrG,gBAAgB,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,+DAA+D;IAC/D,SAAS,IAAI,IAAI,CAAC;IAClB;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI,CAAC;IACpC;;;OAGG;IACH,YAAY,IAAI,IAAI,CAAC;CACtB;AAeD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,GAAG,WAAW,CA6EpE"}

package/dist/todos/midTurn.js

@@ -0,0 +1,214 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.todoInboxMaxChars = exports.todoRunningTurnNoteHeader = void 0;
+exports.getTodoInboxDir = getTodoInboxDir;
+exports.buildTodoInboxHookCommand = buildTodoInboxHookCommand;
+exports.buildTodoInboxHookOutput = buildTodoInboxHookOutput;
+exports.createTodoMidTurn = createTodoMidTurn;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const sessionKey_1 = require("../sessionKey");
+const jsonStreamHost_1 = require("../utils/jsonStreamHost");
+const tmuxExec_1 = require("../utils/tmuxExec");
+const store_1 = require("./store");
+/**
+ * @description Mid-turn delivery of the project board (D21, D22): a working agent learns of another topic's change
+ * inside its turn, not only at its next prompt.
+ *
+ *   Claude    — a `PostToolUse` hook (no matcher) in the launch `--settings` file prints the conversation's INBOX file,
+ *               `DATA_DIR/todos/inbox/<session id>.json`, after the agent's next tool call: ready hook JSON whose
+ *               `additionalContext` Claude reads with that tool's result (probed on Claude Code 2.1.310). The hook
+ *               moves the file before printing it, so a text is delivered once; with no file it prints nothing.
+ *   OpenCode  — a note queued INTO the running turn (`AgentAdapter.queueNoteIntoRunningTurn`: `prompt_async`, read
+ *               between steps, with nothing of the turn reset), never while a provider retry is waited out.
+ *
+ * The bot writes the inbox (atomically) only while the session works (busy, its turn not held open) and something
+ * changed since the agent last saw it; the changes count as seen once the hook took the file (the next poll finds it
+ * gone). A waiting inbox is withdrawn wherever no tool call of the session can take it any more — a turn start the bot
+ * makes (that prompt carries the changes itself), a turn's end, a turn held open, the session's start, stop or end —
+ * and its changes stay unseen for the next prompt, so the inbox dir is empty between turns. A restart forgets what was
+ * written: at worst a change is delivered twice, never lost.
+ */
+/** What opens the note a running OpenCode turn reads (agent-facing English); the board's changes follow it. */
+exports.todoRunningTurnNoteHeader = '[Todo] Other topics of your project changed their lists while you work. No reply is needed.';
+/** The inbox directory under the store's. */
+const inboxDirName = 'inbox';
+/** Claude Code caps a hook's `additionalContext`; the text is cut below it. */
+exports.todoInboxMaxChars = 10_000;
+/** A session id names a file: only these characters, so no id can reach outside the inbox. */
+const sessionIdRe = /^[A-Za-z0-9_-]+$/;
+const inboxFileExtension = '.json';
+/** A copy the hook moved aside: `<session id>.json.<the hook's process id>` (never the bot's `….tmp`). */
+const takenCopyNameRe = /^[A-Za-z0-9_-]+\.json\.(\d+)$/;
+/** Private: what the agents work on. */
+const inboxFileMode = 0o600;
+/** @description Where the inboxes live: `DATA_DIR/todos/inbox`. */
+function getTodoInboxDir(dataDir) {
+    return path.join((0, store_1.getTodosDir)(dataDir), inboxDirName);
+}
+/**
+ * The parse of a hook input, run by the bot's own `node` with the inbox dir as its argument: the input's TOP-LEVEL
+ * fields alone decide, in whatever order they come — a tool's own input or output naming `agent_id` or `session_id`
+ * is never mistaken for them. A sub-agent's call (an `agent_id`) and an id outside {@link sessionIdRe} print nothing;
+ * otherwise the session's inbox is moved aside, printed and removed.
+ */
+const inboxHookScript = [
+    'const fs = require("fs"), path = require("path");',
+    'let text = "";',
+    'process.stdin.setEncoding("utf8").on("data", (chunk) => { text += chunk; }).on("end", () => {',
+    '  try {',
+    '    const input = JSON.parse(text);',
+    '    if (input === null || typeof input !== "object" || "agent_id" in input) return;',
+    `    if (typeof input.session_id !== "string" || !${sessionIdRe.toString()}.test(input.session_id)) return;`,
+    `    const file = path.join(process.argv[1], input.session_id + "${inboxFileExtension}"), taken = file + "." + process.pid;`,
+    '    try { fs.renameSync(file, taken); } catch { return; }',
+    '    process.stdout.write(fs.readFileSync(taken, "utf8"));',
+    '    fs.rmSync(taken, { force: true });',
+    '  } catch {}',
+    '});',
+].join(' ');
+/**
+ * @description The `PostToolUse` hook's shell command. With the inbox dir empty — nearly every tool call — it reads
+ * the input whole (the CLI must never write into a closed pipe) and exits; only while an inbox waits does it start
+ * `nodePath` (the bot's own, written at every launch) to parse the input ({@link inboxHookScript}). It always exits 0 —
+ * a hook failure must never stop the agent's tool.
+ *
+ * Only the MAIN agent takes the inbox. A sub-agent's tool call fires the hook too, with the SAME `session_id` and an
+ * `agent_id` of its own (measured on Claude Code 2.1.310); taken there, the changes would land in the sub-agent's
+ * context and count as seen while the main agent never got them.
+ */
+function buildTodoInboxHookCommand(inboxDir, nodePath = process.execPath) {
+    const dir = (0, tmuxExec_1.shellSingleQuote)(inboxDir);
+    return [
+        `[ -n "$(ls -A ${dir} 2>/dev/null)" ] || { cat > /dev/null; exit 0; }`,
+        `${(0, tmuxExec_1.shellSingleQuote)(nodePath)} -e ${(0, tmuxExec_1.shellSingleQuote)(inboxHookScript)} ${dir}`,
+        'exit 0',
+    ].join('; ');
+}
+/** @description The hook output Claude reads `text` from: `additionalContext` of a `PostToolUse` hook, within the cap. */
+function buildTodoInboxHookOutput(text) {
+    const characters = [...text];
+    const fitted = characters.length <= exports.todoInboxMaxChars ? text : `${characters.slice(0, exports.todoInboxMaxChars - 1).join('')}…`;
+    return JSON.stringify({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: fitted } });
+}
+/** @description Whether two revision maps name the same peers at the same revisions. */
+function checkIsSameRevisions(left, right) {
+    const leftEntries = Object.entries(left);
+    return leftEntries.length === Object.keys(right).length && leftEntries.every(([conversationKey, revision]) => right[conversationKey] === revision);
+}
+function createTodoMidTurn(deps) {
+    const { board, inboxDir, getClaudeSessionId, postRunningTurnNote, checkIsProcessAlive = jsonStreamHost_1.checkIsPidAlive } = deps;
+    const pendingInboxes = new Map();
+    function reconcileOne(conversationKey, pending) {
+        if (fs.existsSync(pending.filePath))
+            return;
+        pendingInboxes.delete(conversationKey);
+        board.markSeenRevisions(pending.key, pending.revisions);
+    }
+    /**
+     * A copy the hook moved aside and never removed (its `node` ended between the move and the removal) would keep the
+     * inbox dir non-empty until boot. Any session's copy goes — but only once the hook that moved it is gone: a live one
+     * may be reading it this very moment, and its change already counts as seen.
+     */
+    function removeTakenLeftovers() {
+        let names;
+        try {
+            names = fs.readdirSync(inboxDir);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            const hookPid = takenCopyNameRe.exec(name)?.[1];
+            if (hookPid !== undefined && !checkIsProcessAlive(Number(hookPid)))
+                fs.rmSync(path.join(inboxDir, name), { force: true });
+        }
+    }
+    function writeInbox(filePath, text) {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+        const tempPath = `${filePath}.${process.pid}.tmp`;
+        fs.writeFileSync(tempPath, buildTodoInboxHookOutput(text), { mode: inboxFileMode });
+        fs.renameSync(tempPath, filePath);
+    }
+    return {
+        async deliverIfPending(key) {
+            const conversationKey = (0, sessionKey_1.keyToString)(key);
+            const pending = pendingInboxes.get(conversationKey);
+            if (pending)
+                reconcileOne(conversationKey, pending);
+            const changes = board.peekChanges(key);
+            if (changes === null)
+                return;
+            const sessionId = getClaudeSessionId(key);
+            if (sessionId === null) {
+                // Seen only once the note is in: a refused one (no running turn, a provider retry) waits for the next poll.
+                if (await postRunningTurnNote(key, `${exports.todoRunningTurnNoteHeader}\n\n${changes.text}`))
+                    board.markSeenRevisions(key, changes.revisions);
+                return;
+            }
+            if (!sessionIdRe.test(sessionId))
+                return;
+            const waiting = pendingInboxes.get(conversationKey);
+            // The same changes already wait for the agent's next tool call.
+            if (waiting && checkIsSameRevisions(waiting.revisions, changes.revisions))
+                return;
+            const filePath = path.join(inboxDir, `${sessionId}${inboxFileExtension}`);
+            writeInbox(filePath, changes.text);
+            pendingInboxes.set(conversationKey, { key, filePath, revisions: changes.revisions });
+        },
+        reconcile() {
+            for (const [conversationKey, pending] of pendingInboxes)
+                reconcileOne(conversationKey, pending);
+        },
+        clearInboxes() {
+            pendingInboxes.clear();
+            fs.rmSync(inboxDir, { recursive: true, force: true });
+        },
+        discardInbox(key) {
+            removeTakenLeftovers();
+            const conversationKey = (0, sessionKey_1.keyToString)(key);
+            const pending = pendingInboxes.get(conversationKey);
+            if (!pending)
+                return;
+            reconcileOne(conversationKey, pending);
+            if (!pendingInboxes.has(conversationKey))
+                return;
+            pendingInboxes.delete(conversationKey);
+            fs.rmSync(pending.filePath, { force: true });
+        },
+    };
+}
+//# sourceMappingURL=midTurn.js.map

package/dist/todos/midTurn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"midTurn.js","sourceRoot":"","sources":["../../src/todos/midTurn.ts"],"names":[],"mappings":"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"}

package/dist/todos/nag.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @description The staleness reminder of the todo registry (D10–D14), as pure decisions — modelled on
+ * `getIdleFireDecision`: every "no" names its reasons, so a log line says why nothing fired.
+ *
+ *   stale = the agent WORKED (its session reported busy) for ≥ the interval since its last `todo_update`; the clock
+ *           starts at the first turn end after that update, so a topic quiet for days is not reminded on its first turn
+ *   form a — a reminder line on the next prompt the conversation gets, from any source (no extra turn)
+ *   form b — a standalone technical prompt at a turn end, only when nothing else would reach the agent and every gate
+ *            of D12 holds (live, idle, nothing holding the turn, nothing unread, no open request, no answer tail, not
+ *            limited, not billed to API credits)
+ *   after 2 reminders in a row with no update the bot stays silent until the agent updates or a person writes
+ */
+/** The reminder interval nobody chose (D10). */
+export declare const todoReminderDefaultMinutes = 60;
+/** The intervals General offers; `0` is "off". */
+export declare const todoReminderOffMinutes = 0;
+export declare const todoReminderMinuteOptions: readonly number[];
+/** After this many reminders in a row with no update the bot stays silent (D13). */
+export declare const todoReminderMaxIgnored = 2;
+/**
+ * @name TodoNagState
+ * @description The reminder's bookkeeping of a conversation, persisted with its list. `clockStartedAt` = the first
+ * turn end after the last update (absent until then); `workedMs` = the busy time since; `ignoredCount` = reminders
+ * delivered in a row with no update.
+ */
+export interface TodoNagState {
+    clockStartedAt?: number;
+    workedMs: number;
+    ignoredCount: number;
+    lastRemindedAt?: number;
+}
+/** @name TodoReminderSettings @description The instance's settings, defaults filled in (`settings.json` `todo`). */
+export interface TodoReminderSettings {
+    isEnabled: boolean;
+    /** `0` = the reminder is off. */
+    reminderMinutes: number;
+}
+/**
+ * @name TodoStandaloneGate
+ * @description What a standalone reminder (form b) needs to hold at a turn end (D12). The first four are the
+ * wake-up engine's turn probe.
+ */
+export interface TodoStandaloneGate {
+    isActive: boolean;
+    isBusy: boolean;
+    isTurnEndBlocked: boolean;
+    hasUnconsumedInput: boolean | null;
+    hasOpenRequest: boolean;
+    /** The agent's text after a final answer is being followed (`requests/answerTail.ts`). */
+    isAnswerTailFollowed: boolean;
+    /** The account or model the conversation runs on is marked limited. */
+    isLimited: boolean;
+    /** The conversation runs on an account billed to API credits: never spend money unasked. */
+    isApiBilled: boolean;
+    /** The backend stops the process after every turn (the per-turn lifecycle): the session sleeps now. */
+    isStoppingAfterTurn: boolean;
+}
+/** @description What the reminder decided: the text to deliver, or why not. */
+export type TodoReminderDecision = {
+    shouldRemind: true;
+} | {
+    shouldRemind: false;
+    skipReasons: string[];
+};
+/** @description The bookkeeping right after an update: nothing worked, nobody reminded, the clock not started. */
+export declare function createTodoNagState(): TodoNagState;
+/** @description `nag` with `elapsedMs` of busy time added — counted only once the clock started. */
+export declare function getTodoNagStateWithWork(nag: TodoNagState, elapsedMs: number): TodoNagState;
+/** @description `nag` at a turn end: the clock starts at the first one after the update. */
+export declare function getTodoNagStateAtTurnEnd(nag: TodoNagState, nowMs: number): TodoNagState;
+/** @description `nag` after a reminder reached the agent: the work counts afresh, one more ignored until it updates. */
+export declare function getTodoNagStateAfterReminder(nag: TodoNagState, nowMs: number): TodoNagState;
+/** @description `nag` after a person wrote in the conversation: the silence after ignored reminders ends (D13). */
+export declare function getTodoNagStateAfterPersonActivity(nag: TodoNagState): TodoNagState;
+/** @description The interval in ms, or `null` when the reminder is off. `overrideMs` is the test-only timing seam. */
+export declare function getTodoReminderIntervalMs(settings: TodoReminderSettings, overrideMs: number | undefined): number | null;
+/** @description Whether the agent worked the whole interval since its last update (the reminder is due, gates aside). */
+export declare function checkIsTodoNagStale(nag: TodoNagState, intervalMs: number | null): boolean;
+/** @description Form a: whether the next prompt carries the reminder line. */
+export declare function decidePromptTodoReminder(nag: TodoNagState, intervalMs: number | null): TodoReminderDecision;
+/** @description Form b: whether a standalone reminder goes out at this turn end (D12). */
+export declare function decideStandaloneTodoReminder(nag: TodoNagState, intervalMs: number | null, gate: TodoStandaloneGate): TodoReminderDecision;
+/** @description The agent-facing reminder (D14): factual, asks for no text reply. */
+export declare function buildTodoReminderText(lastUpdateAt: number | undefined, nowMs: number): string;
+//# sourceMappingURL=nag.d.ts.map

package/dist/todos/nag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nag.d.ts","sourceRoot":"","sources":["../../src/todos/nag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,gDAAgD;AAChD,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAC7C,kDAAkD;AAClD,eAAO,MAAM,sBAAsB,IAAI,CAAC;AACxC,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAA+C,CAAC;AACvG,oFAAoF;AACpF,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAGxC;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,oHAAoH;AACpH,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,OAAO,CAAC;IACnB,iCAAiC;IACjC,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,kBAAkB,EAAE,OAAO,GAAG,IAAI,CAAC;IACnC,cAAc,EAAE,OAAO,CAAC;IACxB,0FAA0F;IAC1F,oBAAoB,EAAE,OAAO,CAAC;IAC9B,uEAAuE;IACvE,SAAS,EAAE,OAAO,CAAC;IACnB,4FAA4F;IAC5F,WAAW,EAAE,OAAO,CAAC;IACrB,uGAAuG;IACvG,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED,+EAA+E;AAC/E,MAAM,MAAM,oBAAoB,GAAG;IAAE,YAAY,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,YAAY,EAAE,KAAK,CAAC;IAAC,WAAW,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAE3G,kHAAkH;AAClH,wBAAgB,kBAAkB,IAAI,YAAY,CAEjD;AAED,oGAAoG;AACpG,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,GAAG,YAAY,CAG1F;AAED,4FAA4F;AAC5F,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAEvF;AAED,wHAAwH;AACxH,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAE3F;AAED,mHAAmH;AACnH,wBAAgB,kCAAkC,CAAC,GAAG,EAAE,YAAY,GAAG,YAAY,CAElF;AAED,sHAAsH;AACtH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAGvH;AAED,yHAAyH;AACzH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAEzF;AAYD,8EAA8E;AAC9E,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,oBAAoB,CAG3G;AAED,0FAA0F;AAC1F,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,kBAAkB,GAAG,oBAAoB,CAczI;AAED,qFAAqF;AACrF,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK7F"}

package/dist/todos/nag.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * @description The staleness reminder of the todo registry (D10–D14), as pure decisions — modelled on
+ * `getIdleFireDecision`: every "no" names its reasons, so a log line says why nothing fired.
+ *
+ *   stale = the agent WORKED (its session reported busy) for ≥ the interval since its last `todo_update`; the clock
+ *           starts at the first turn end after that update, so a topic quiet for days is not reminded on its first turn
+ *   form a — a reminder line on the next prompt the conversation gets, from any source (no extra turn)
+ *   form b — a standalone technical prompt at a turn end, only when nothing else would reach the agent and every gate
+ *            of D12 holds (live, idle, nothing holding the turn, nothing unread, no open request, no answer tail, not
+ *            limited, not billed to API credits)
+ *   after 2 reminders in a row with no update the bot stays silent until the agent updates or a person writes
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.todoReminderMaxIgnored = exports.todoReminderMinuteOptions = exports.todoReminderOffMinutes = exports.todoReminderDefaultMinutes = void 0;
+exports.createTodoNagState = createTodoNagState;
+exports.getTodoNagStateWithWork = getTodoNagStateWithWork;
+exports.getTodoNagStateAtTurnEnd = getTodoNagStateAtTurnEnd;
+exports.getTodoNagStateAfterReminder = getTodoNagStateAfterReminder;
+exports.getTodoNagStateAfterPersonActivity = getTodoNagStateAfterPersonActivity;
+exports.getTodoReminderIntervalMs = getTodoReminderIntervalMs;
+exports.checkIsTodoNagStale = checkIsTodoNagStale;
+exports.decidePromptTodoReminder = decidePromptTodoReminder;
+exports.decideStandaloneTodoReminder = decideStandaloneTodoReminder;
+exports.buildTodoReminderText = buildTodoReminderText;
+/** The reminder interval nobody chose (D10). */
+exports.todoReminderDefaultMinutes = 60;
+/** The intervals General offers; `0` is "off". */
+exports.todoReminderOffMinutes = 0;
+exports.todoReminderMinuteOptions = [exports.todoReminderOffMinutes, 30, 60, 120, 240];
+/** After this many reminders in a row with no update the bot stays silent (D13). */
+exports.todoReminderMaxIgnored = 2;
+const msPerMinute = 60 * 1000;
+/** @description The bookkeeping right after an update: nothing worked, nobody reminded, the clock not started. */
+function createTodoNagState() {
+    return { workedMs: 0, ignoredCount: 0 };
+}
+/** @description `nag` with `elapsedMs` of busy time added — counted only once the clock started. */
+function getTodoNagStateWithWork(nag, elapsedMs) {
+    if (nag.clockStartedAt === undefined || elapsedMs <= 0)
+        return nag;
+    return { ...nag, workedMs: nag.workedMs + elapsedMs };
+}
+/** @description `nag` at a turn end: the clock starts at the first one after the update. */
+function getTodoNagStateAtTurnEnd(nag, nowMs) {
+    return nag.clockStartedAt === undefined ? { ...nag, clockStartedAt: nowMs } : nag;
+}
+/** @description `nag` after a reminder reached the agent: the work counts afresh, one more ignored until it updates. */
+function getTodoNagStateAfterReminder(nag, nowMs) {
+    return { ...nag, workedMs: 0, ignoredCount: nag.ignoredCount + 1, lastRemindedAt: nowMs };
+}
+/** @description `nag` after a person wrote in the conversation: the silence after ignored reminders ends (D13). */
+function getTodoNagStateAfterPersonActivity(nag) {
+    return nag.ignoredCount === 0 ? nag : { ...nag, ignoredCount: 0 };
+}
+/** @description The interval in ms, or `null` when the reminder is off. `overrideMs` is the test-only timing seam. */
+function getTodoReminderIntervalMs(settings, overrideMs) {
+    if (!settings.isEnabled || settings.reminderMinutes === exports.todoReminderOffMinutes)
+        return null;
+    return overrideMs ?? settings.reminderMinutes * msPerMinute;
+}
+/** @description Whether the agent worked the whole interval since its last update (the reminder is due, gates aside). */
+function checkIsTodoNagStale(nag, intervalMs) {
+    return intervalMs !== null && nag.clockStartedAt !== undefined && nag.workedMs >= intervalMs;
+}
+/** @description The reasons a list is not due for a reminder in either form (empty = due). */
+function getStaleSkipReasons(nag, intervalMs) {
+    return [
+        intervalMs === null && 'the reminder is off',
+        nag.clockStartedAt === undefined && 'no turn ended since the last update',
+        intervalMs !== null && nag.workedMs < intervalMs && `worked ${Math.round(nag.workedMs / 1000)} s of ${Math.round(intervalMs / 1000)} s`,
+        nag.ignoredCount >= exports.todoReminderMaxIgnored && `silent after ${exports.todoReminderMaxIgnored} ignored reminders`,
+    ].filter((reason) => typeof reason === 'string');
+}
+/** @description Form a: whether the next prompt carries the reminder line. */
+function decidePromptTodoReminder(nag, intervalMs) {
+    const skipReasons = getStaleSkipReasons(nag, intervalMs);
+    return skipReasons.length === 0 ? { shouldRemind: true } : { shouldRemind: false, skipReasons };
+}
+/** @description Form b: whether a standalone reminder goes out at this turn end (D12). */
+function decideStandaloneTodoReminder(nag, intervalMs, gate) {
+    const skipReasons = [
+        ...getStaleSkipReasons(nag, intervalMs),
+        !gate.isActive && 'no live session (never woken for it)',
+        gate.isStoppingAfterTurn && 'the session sleeps after every turn (never woken for it)',
+        gate.isBusy && 'busy',
+        gate.isTurnEndBlocked && 'something holds the turn open',
+        gate.hasUnconsumedInput === true && 'input not taken in yet',
+        gate.hasOpenRequest && 'an open request',
+        gate.isAnswerTailFollowed && 'the text after a final answer is followed',
+        gate.isLimited && 'the account or model is limited',
+        gate.isApiBilled && 'billed to API credits',
+    ].filter((reason) => typeof reason === 'string');
+    return skipReasons.length === 0 ? { shouldRemind: true } : { shouldRemind: false, skipReasons };
+}
+/** @description The agent-facing reminder (D14): factual, asks for no text reply. */
+function buildTodoReminderText(lastUpdateAt, nowMs) {
+    const opening = lastUpdateAt === undefined
+        ? 'You have not published a todo list yet and you have been working.'
+        : `Your published todo list was last updated ${Math.max(1, Math.round((nowMs - lastUpdateAt) / msPerMinute))} min ago and you have worked since.`;
+    return `[Todo] ${opening} todo_update records in-work / queued / done; with no items it confirms the list is still accurate. No text reply is needed.`;
+}
+//# sourceMappingURL=nag.js.map

package/dist/todos/nag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nag.js","sourceRoot":"","sources":["../../src/todos/nag.ts"],"names":[],"mappings":"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"}

package/dist/todos/order.d.ts

@@ -0,0 +1,25 @@
+import { type TodoItem, type TodoPosition } from './types';
+/**
+ * @description The ONE total order over a conversation's items (D23): in-work items lead, then the queue in its
+ * order, then the closed items by the time they were closed, newest first. The queue order is the order of the open
+ * items in the stored array; these helpers read and rearrange it, never a number of their own.
+ */
+/** @description Whether an item is still to be done. */
+export declare function checkIsOpenTodoItem(item: TodoItem): boolean;
+/** @description The in-work items, in their stored order. */
+export declare function getInWorkTodoItems(items: readonly TodoItem[]): TodoItem[];
+/** @description The queue: the queued items, in their stored order — the order the agent takes them in. */
+export declare function getQueuedTodoItems(items: readonly TodoItem[]): TodoItem[];
+/** @description The closed items (done and dropped), the most recently closed first. */
+export declare function getClosedTodoItems(items: readonly TodoItem[]): TodoItem[];
+/** @description The whole list in the total order (D23). */
+export declare function getTodoItemsInOrder(items: readonly TodoItem[]): TodoItem[];
+/** @description `items` with the item `id` moved before (`top`) or after (`bottom`) every open item. */
+export declare function getTodoItemsWithMovedItem(items: readonly TodoItem[], id: string, position: TodoPosition): TodoItem[];
+/**
+ * @description `items` with the open ones rearranged: the ids of `orderedIds` first, in that order, then the open
+ * items it does not list in their relative order. The closed items keep their places — their order is their close
+ * time. Ids that are not open items are ignored (the caller rejects them first).
+ */
+export declare function getTodoItemsInRequestedOrder(items: readonly TodoItem[], orderedIds: readonly string[]): TodoItem[];
+//# sourceMappingURL=order.d.ts.map

package/dist/todos/order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"order.d.ts","sourceRoot":"","sources":["../../src/todos/order.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAE7E;;;;GAIG;AAEH,wDAAwD;AACxD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAE3D;AAED,6DAA6D;AAC7D,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,QAAQ,EAAE,CAEzE;AAED,2GAA2G;AAC3G,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,QAAQ,EAAE,CAEzE;AAED,wFAAwF;AACxF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,QAAQ,EAAE,CAEzE;AAED,4DAA4D;AAC5D,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,QAAQ,EAAE,CAE1E;AAED,wGAAwG;AACxG,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,QAAQ,EAAE,CAQpH;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,QAAQ,EAAE,CAOlH"}

package/dist/todos/order.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkIsOpenTodoItem = checkIsOpenTodoItem;
+exports.getInWorkTodoItems = getInWorkTodoItems;
+exports.getQueuedTodoItems = getQueuedTodoItems;
+exports.getClosedTodoItems = getClosedTodoItems;
+exports.getTodoItemsInOrder = getTodoItemsInOrder;
+exports.getTodoItemsWithMovedItem = getTodoItemsWithMovedItem;
+exports.getTodoItemsInRequestedOrder = getTodoItemsInRequestedOrder;
+const types_1 = require("./types");
+/**
+ * @description The ONE total order over a conversation's items (D23): in-work items lead, then the queue in its
+ * order, then the closed items by the time they were closed, newest first. The queue order is the order of the open
+ * items in the stored array; these helpers read and rearrange it, never a number of their own.
+ */
+/** @description Whether an item is still to be done. */
+function checkIsOpenTodoItem(item) {
+    return types_1.openTodoStatuses.includes(item.status);
+}
+/** @description The in-work items, in their stored order. */
+function getInWorkTodoItems(items) {
+    return items.filter((item) => item.status === 'inWork');
+}
+/** @description The queue: the queued items, in their stored order — the order the agent takes them in. */
+function getQueuedTodoItems(items) {
+    return items.filter((item) => item.status === 'queued');
+}
+/** @description The closed items (done and dropped), the most recently closed first. */
+function getClosedTodoItems(items) {
+    return items.filter((item) => !checkIsOpenTodoItem(item)).sort((left, right) => (right.closedAt ?? 0) - (left.closedAt ?? 0));
+}
+/** @description The whole list in the total order (D23). */
+function getTodoItemsInOrder(items) {
+    return [...getInWorkTodoItems(items), ...getQueuedTodoItems(items), ...getClosedTodoItems(items)];
+}
+/** @description `items` with the item `id` moved before (`top`) or after (`bottom`) every open item. */
+function getTodoItemsWithMovedItem(items, id, position) {
+    const moved = items.find((item) => item.id === id);
+    if (!moved)
+        return [...items];
+    const rest = items.filter((item) => item.id !== id);
+    if (position === 'bottom')
+        return [...rest, moved];
+    const firstOpenIndex = rest.findIndex(checkIsOpenTodoItem);
+    const insertAt = firstOpenIndex === -1 ? rest.length : firstOpenIndex;
+    return [...rest.slice(0, insertAt), moved, ...rest.slice(insertAt)];
+}
+/**
+ * @description `items` with the open ones rearranged: the ids of `orderedIds` first, in that order, then the open
+ * items it does not list in their relative order. The closed items keep their places — their order is their close
+ * time. Ids that are not open items are ignored (the caller rejects them first).
+ */
+function getTodoItemsInRequestedOrder(items, orderedIds) {
+    const openItems = items.filter(checkIsOpenTodoItem);
+    const listed = orderedIds.flatMap((id) => openItems.filter((item) => item.id === id));
+    const unlisted = openItems.filter((item) => !orderedIds.includes(item.id));
+    const reordered = [...listed, ...unlisted];
+    let nextOpenIndex = 0;
+    return items.map((item) => (checkIsOpenTodoItem(item) ? reordered[nextOpenIndex++] : item));
+}
+//# sourceMappingURL=order.js.map

package/dist/todos/order.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"order.js","sourceRoot":"","sources":["../../src/todos/order.ts"],"names":[],"mappings":"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"}