charness 0.0.0-stage → 3.0.0

package/dist/requests/answerRequest.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.answerBodyMaxLength = void 0;
+exports.answerRequest = answerRequest;
+const sessionKey_1 = require("../sessionKey");
+const answerSink_1 = require("../platform/answerSink");
+/**
+ * @description The `answer_request` contract (request/answer core S3), kept out
+ * of the MCP surface so the rules are testable without HTTP:
+ *
+ *   unknown id, or an id outside the caller's scope → refused, nothing sent
+ *     (the two read the same, so a session cannot probe other topics' ids)
+ *   delivery through the request platform's answer sink fails → refused, the
+ *     request is unchanged and the agent may retry
+ *   delivered, request open:   progress → counted, stays open
+ *                              question / final → closes the request
+ *   delivered, request closed: nothing changes (a late answer from a turn that
+ *     outlived its request is still delivered — content is never dropped); a
+ *     superseded request's result names the request that replaced it and says
+ *     its prompt follows — the agent answers only what that one adds, never the
+ *     same work twice (Claude Code delivers a message written mid-turn only
+ *     after the turn ends, so this is the normal order there)
+ */
+/** The longest answer body accepted; the sinks split it to their surface's limits. */
+exports.answerBodyMaxLength = 100_000;
+/** The answer kinds that close an open request, and the close reason each records. */
+const closingAnswerReasons = {
+    progress: null,
+    question: 'question',
+    final: 'final',
+};
+function buildUnknownRequestError(requestId) {
+    return `Unknown request id "${requestId}". Answer only the request ids given to you in this conversation; nothing was sent.`;
+}
+/** The agent-facing line for an answer to a request that was open when it was delivered. */
+function buildOpenAnswerMessage(requestId, kind, wasClosedMeanwhile) {
+    if (wasClosedMeanwhile) {
+        return `Delivered. Request ${requestId} had just been closed (by a newer request or another answer), so nothing about it changed.`;
+    }
+    if (kind === 'progress') {
+        return `Delivered. Request ${requestId} stays open — send the full result with kind "final" (or "question" if you need the requester) at the end of your turn.`;
+    }
+    return `Delivered. Request ${requestId} is now closed (${kind}).`;
+}
+/** The agent-facing line for an answer delivered to a request that was already closed. */
+function buildClosedAnswerMessage(requestId, closed) {
+    const replacedBy = closed.closeReason === 'superseded' && closed.supersededBy !== undefined
+        ? ` by request ${closed.supersededBy} from the same requester; its prompt follows — reply only to what it adds, or say briefly that the answer is above`
+        : '';
+    return `Delivered. Request ${requestId} was already closed (${closed.closeReason}${replacedBy}), so nothing about it changed.`;
+}
+/** @description Deliver one answer and apply the close rules. */
+async function answerRequest(deps, args) {
+    await deps.ledger.whenLoaded();
+    const lookup = deps.ledger.getRequest(args.requestId);
+    if (!lookup || !args.checkIsConversationInScope(lookup.conversationKey)) {
+        return { ok: false, error: buildUnknownRequestError(args.requestId) };
+    }
+    const key = (0, sessionKey_1.tryKeyFromString)(lookup.conversationKey);
+    if (!key) {
+        return { ok: false, error: `Request ${args.requestId} belongs to a conversation this bot cannot address; nothing was sent.` };
+    }
+    const sinkLookup = (0, answerSink_1.getAnswerSink)(deps.answerSinks, key);
+    if (!sinkLookup.ok) {
+        return { ok: false, error: `Answers cannot be delivered to platform "${key.platform}" by this bot; nothing was sent.` };
+    }
+    const delivery = await sinkLookup.sink.deliverAnswer(key, {
+        requestId: args.requestId,
+        kind: args.kind,
+        body: args.body,
+        origin: lookup.request.origin,
+        isRequestOpen: lookup.isOpen,
+    });
+    if (!delivery.ok) {
+        return { ok: false, error: `The answer was NOT delivered: ${delivery.error}. Request ${args.requestId} is unchanged; you may retry.` };
+    }
+    const warning = delivery.warning ? ` Note: ${delivery.warning}` : '';
+    if (!lookup.isOpen) {
+        deps.onAnswerDelivered?.(key, args.requestId, args.kind);
+        return { ok: true, message: `${buildClosedAnswerMessage(args.requestId, lookup.request)}${warning}` };
+    }
+    const closeReason = closingAnswerReasons[args.kind];
+    const changed = closeReason
+        ? await deps.ledger.closeRequest(args.requestId, closeReason)
+        : await deps.ledger.updateOpenRequest(args.requestId, (current) => ({
+            progressAnswerCount: current.progressAnswerCount + 1,
+            // An answer proves the agent read the request: a later wake-up reminds, never re-posts it (R21),
+            // and a post retry still pending is moot (R28).
+            ...(current.prompt !== undefined && current.isPromptTakenIn !== true ? { isPromptTakenIn: true } : {}),
+            ...(current.nextPostRetryAt !== undefined ? { nextPostRetryAt: undefined } : {}),
+        }));
+    // After the close: whoever hears it sees the request as it now stands.
+    deps.onAnswerDelivered?.(key, args.requestId, args.kind);
+    return { ok: true, message: `${buildOpenAnswerMessage(args.requestId, args.kind, changed === null)}${warning}` };
+}
+//# sourceMappingURL=answerRequest.js.map

package/dist/requests/answerRequest.js.map

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

package/dist/requests/answerTail.d.ts

@@ -0,0 +1,83 @@
+import type { OutboundHints } from '../platform/outbound';
+import type { SessionTurnProbe } from './wakeUpRules';
+/**
+ * @description The answer tail: what the agent writes into its own stream AFTER
+ * its final answer, as pure decisions (the wake-up engine holds the state and
+ * acts). In a view that hides the stream the requester sees only the answers, so
+ * work the agent goes on with after its final answer never reaches them, and the
+ * request is closed: nothing else would ever remind the agent.
+ *
+ *   final answer                        → a fresh tail (any answer_request call ends the previous one)
+ *   its own text after it               → counted in messages (a pause starts a new one)
+ *   a message later than 30 s after it,
+ *     or 2 messages in all              → the tail is worth a reminder
+ *   that, and the turn ended            → remind the agent once, in the same session
+ *   that, and 30 min with no new text   → remind it even if the turn still looks busy
+ *
+ * A short closing line right after the answer is no tail. The agent's reply to a
+ * reminder is a final answer again, so its own tail is followed too (a result a
+ * background job brings later still reaches the requester), up to
+ * {@link answerTailMaxReminders} reminders per answered request: never a loop.
+ */
+/** After the answer, text later than this means the agent went on working. */
+export declare const answerTailGraceMs = 30000;
+/** Messages after the answer that make a tail worth a reminder, however soon they came. */
+export declare const answerTailMessageCount = 2;
+/**
+ * A pause in the agent's text longer than this starts a new message. The
+ * adapters emit a message in chunks a fraction of a second apart (stream
+ * batches, scrape polls), so one message never spans such a pause.
+ */
+export declare const answerTailMessageGapMs = 5000;
+/** With no new text for this long, a tail is reminded even if the session still reports a turn. */
+export declare const answerTailSilenceMs: number;
+/** Reminders one answered request may get; its later final answers start no tail. */
+export declare const answerTailMaxReminders = 3;
+/**
+ * @name AnswerTail
+ * @description The agent's own text after a final answer to `requestId`.
+ * `lastOutputAt` is undefined until it writes anything.
+ */
+export interface AnswerTail {
+    requestId: string;
+    answeredAt: number;
+    messageCount: number;
+    lastOutputAt?: number;
+    /** Some text came later than {@link answerTailGraceMs} after the answer. */
+    hasLateOutput: boolean;
+}
+/**
+ * @description Whether an `output` event is the agent's own text, the kind a
+ * tail counts: not a sub-agent's chunk, a compaction summary, a native question
+ * (shown in every view) or a whole block the bot made (the resume context, a
+ * retry notice). The bot also leaves out spinner bursts and API-error lines.
+ */
+export declare function checkIsAgentProseOutput(output: string, hints: OutboundHints | undefined): boolean;
+/** @description The tail of a final answer just delivered. */
+export declare function createAnswerTail(requestId: string, nowMs: number): AnswerTail;
+/** @description The tail after one more chunk of the agent's text. */
+export declare function addAnswerTailOutput(tail: AnswerTail, nowMs: number): AnswerTail;
+/** @description Whether the agent wrote enough after its answer to be reminded of it. */
+export declare function checkIsAnswerTailWorthReminder(tail: AnswerTail): boolean;
+/**
+ * @name AnswerTailDecision
+ * @description `wait` — keep watching; `drop` — nothing can come of this tail
+ * any more; `remind` — tell the agent now.
+ */
+export type AnswerTailDecision = 'wait' | 'drop' | 'remind';
+/**
+ * @description What to do with a tail, given the session now. Nothing while a
+ * question, compaction, limit wait or session start holds the turn. A tail not
+ * worth a reminder is dropped once the session stopped: no more text can come
+ * without a new message, and a new message is a new request. One worth it is
+ * reminded once the turn ended (an idle session, or one that stopped), or after
+ * {@link answerTailSilenceMs} of quiet even if the session still reports a turn.
+ */
+export declare function decideAnswerTail(tail: AnswerTail, probe: SessionTurnProbe, nowMs: number): AnswerTailDecision;
+/**
+ * @description The reminder forwarded into the agent's session. Agent-facing,
+ * English on every surface. It names the answered request: `answer_request`
+ * still delivers an answer to a closed request.
+ */
+export declare function buildAnswerTailReminder(requestId: string): string;
+//# sourceMappingURL=answerTail.d.ts.map

package/dist/requests/answerTail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"answerTail.d.ts","sourceRoot":"","sources":["../../src/requests/answerTail.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD;;;;;;;;;;;;;;;;;;GAkBG;AAEH,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,QAAS,CAAC;AACxC,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,IAAI,CAAC;AACxC;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,OAAQ,CAAC;AAC5C,mGAAmG;AACnG,eAAO,MAAM,mBAAmB,QAAiB,CAAC;AAClD,qFAAqF;AACrF,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,SAAS,GAAG,OAAO,CAGjG;AAED,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,CAE7E;AAED,sEAAsE;AACtE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,CAQ/E;AAED,yFAAyF;AACzF,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAExE;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE5D;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,GAAG,kBAAkB,CAK7G;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOjE"}

package/dist/requests/answerTail.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.answerTailMaxReminders = exports.answerTailSilenceMs = exports.answerTailMessageGapMs = exports.answerTailMessageCount = exports.answerTailGraceMs = void 0;
+exports.checkIsAgentProseOutput = checkIsAgentProseOutput;
+exports.createAnswerTail = createAnswerTail;
+exports.addAnswerTailOutput = addAnswerTailOutput;
+exports.checkIsAnswerTailWorthReminder = checkIsAnswerTailWorthReminder;
+exports.decideAnswerTail = decideAnswerTail;
+exports.buildAnswerTailReminder = buildAnswerTailReminder;
+/**
+ * @description The answer tail: what the agent writes into its own stream AFTER
+ * its final answer, as pure decisions (the wake-up engine holds the state and
+ * acts). In a view that hides the stream the requester sees only the answers, so
+ * work the agent goes on with after its final answer never reaches them, and the
+ * request is closed: nothing else would ever remind the agent.
+ *
+ *   final answer                        → a fresh tail (any answer_request call ends the previous one)
+ *   its own text after it               → counted in messages (a pause starts a new one)
+ *   a message later than 30 s after it,
+ *     or 2 messages in all              → the tail is worth a reminder
+ *   that, and the turn ended            → remind the agent once, in the same session
+ *   that, and 30 min with no new text   → remind it even if the turn still looks busy
+ *
+ * A short closing line right after the answer is no tail. The agent's reply to a
+ * reminder is a final answer again, so its own tail is followed too (a result a
+ * background job brings later still reaches the requester), up to
+ * {@link answerTailMaxReminders} reminders per answered request: never a loop.
+ */
+/** After the answer, text later than this means the agent went on working. */
+exports.answerTailGraceMs = 30_000;
+/** Messages after the answer that make a tail worth a reminder, however soon they came. */
+exports.answerTailMessageCount = 2;
+/**
+ * A pause in the agent's text longer than this starts a new message. The
+ * adapters emit a message in chunks a fraction of a second apart (stream
+ * batches, scrape polls), so one message never spans such a pause.
+ */
+exports.answerTailMessageGapMs = 5_000;
+/** With no new text for this long, a tail is reminded even if the session still reports a turn. */
+exports.answerTailSilenceMs = 30 * 60 * 1000;
+/** Reminders one answered request may get; its later final answers start no tail. */
+exports.answerTailMaxReminders = 3;
+/**
+ * @description Whether an `output` event is the agent's own text, the kind a
+ * tail counts: not a sub-agent's chunk, a compaction summary, a native question
+ * (shown in every view) or a whole block the bot made (the resume context, a
+ * retry notice). The bot also leaves out spinner bursts and API-error lines.
+ */
+function checkIsAgentProseOutput(output, hints) {
+    if (!output.trim())
+        return false;
+    return !hints?.isSubagent && !hints?.isCompactionSummary && !hints?.isQuestion && !hints?.isComplete;
+}
+/** @description The tail of a final answer just delivered. */
+function createAnswerTail(requestId, nowMs) {
+    return { requestId, answeredAt: nowMs, messageCount: 0, hasLateOutput: false };
+}
+/** @description The tail after one more chunk of the agent's text. */
+function addAnswerTailOutput(tail, nowMs) {
+    const isNewMessage = tail.lastOutputAt === undefined || nowMs - tail.lastOutputAt > exports.answerTailMessageGapMs;
+    return {
+        ...tail,
+        messageCount: tail.messageCount + (isNewMessage ? 1 : 0),
+        lastOutputAt: nowMs,
+        hasLateOutput: tail.hasLateOutput || nowMs - tail.answeredAt > exports.answerTailGraceMs,
+    };
+}
+/** @description Whether the agent wrote enough after its answer to be reminded of it. */
+function checkIsAnswerTailWorthReminder(tail) {
+    return tail.hasLateOutput || tail.messageCount >= exports.answerTailMessageCount;
+}
+/**
+ * @description What to do with a tail, given the session now. Nothing while a
+ * question, compaction, limit wait or session start holds the turn. A tail not
+ * worth a reminder is dropped once the session stopped: no more text can come
+ * without a new message, and a new message is a new request. One worth it is
+ * reminded once the turn ended (an idle session, or one that stopped), or after
+ * {@link answerTailSilenceMs} of quiet even if the session still reports a turn.
+ */
+function decideAnswerTail(tail, probe, nowMs) {
+    if (probe.isTurnEndBlocked)
+        return 'wait';
+    if (!checkIsAnswerTailWorthReminder(tail))
+        return probe.isActive ? 'wait' : 'drop';
+    if (!probe.isBusy)
+        return 'remind';
+    return tail.lastOutputAt !== undefined && nowMs - tail.lastOutputAt >= exports.answerTailSilenceMs ? 'remind' : 'wait';
+}
+/**
+ * @description The reminder forwarded into the agent's session. Agent-facing,
+ * English on every surface. It names the answered request: `answer_request`
+ * still delivers an answer to a closed request.
+ */
+function buildAnswerTailReminder(requestId) {
+    return [
+        `[Reminder · after your final answer to request ${requestId}]`,
+        'You kept working after that answer and wrote more in your own output. The requester does not see it: only answer_request reaches them.',
+        `If any of it matters to them (a result, a change, a problem), send it with answer_request (requestId "${requestId}", kind "final"). ` +
+            'If nothing new came of it, send nothing.',
+    ].join('\n');
+}
+//# sourceMappingURL=answerTail.js.map

package/dist/requests/answerTail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"answerTail.js","sourceRoot":"","sources":["../../src/requests/answerTail.ts"],"names":[],"mappings":";;;AA0DA,0DAGC;AAGD,4CAEC;AAGD,kDAQC;AAGD,wEAEC;AAiBD,4CAKC;AAOD,0DAOC;AAnHD;;;;;;;;;;;;;;;;;;GAkBG;AAEH,8EAA8E;AACjE,QAAA,iBAAiB,GAAG,MAAM,CAAC;AACxC,2FAA2F;AAC9E,QAAA,sBAAsB,GAAG,CAAC,CAAC;AACxC;;;;GAIG;AACU,QAAA,sBAAsB,GAAG,KAAK,CAAC;AAC5C,mGAAmG;AACtF,QAAA,mBAAmB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAClD,qFAAqF;AACxE,QAAA,sBAAsB,GAAG,CAAC,CAAC;AAgBxC;;;;;GAKG;AACH,SAAgB,uBAAuB,CAAC,MAAc,EAAE,KAAgC;IACtF,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE;QAAE,OAAO,KAAK,CAAC;IACjC,OAAO,CAAC,KAAK,EAAE,UAAU,IAAI,CAAC,KAAK,EAAE,mBAAmB,IAAI,CAAC,KAAK,EAAE,UAAU,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC;AACvG,CAAC;AAED,8DAA8D;AAC9D,SAAgB,gBAAgB,CAAC,SAAiB,EAAE,KAAa;IAC/D,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;AACjF,CAAC;AAED,sEAAsE;AACtE,SAAgB,mBAAmB,CAAC,IAAgB,EAAE,KAAa;IACjE,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,KAAK,SAAS,IAAI,KAAK,GAAG,IAAI,CAAC,YAAY,GAAG,8BAAsB,CAAC;IAC3G,OAAO;QACL,GAAG,IAAI;QACP,YAAY,EAAE,IAAI,CAAC,YAAY,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACxD,YAAY,EAAE,KAAK;QACnB,aAAa,EAAE,IAAI,CAAC,aAAa,IAAI,KAAK,GAAG,IAAI,CAAC,UAAU,GAAG,yBAAiB;KACjF,CAAC;AACJ,CAAC;AAED,yFAAyF;AACzF,SAAgB,8BAA8B,CAAC,IAAgB;IAC7D,OAAO,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,YAAY,IAAI,8BAAsB,CAAC;AAC3E,CAAC;AASD;;;;;;;GAOG;AACH,SAAgB,gBAAgB,CAAC,IAAgB,EAAE,KAAuB,EAAE,KAAa;IACvF,IAAI,KAAK,CAAC,gBAAgB;QAAE,OAAO,MAAM,CAAC;IAC1C,IAAI,CAAC,8BAA8B,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;IACnF,IAAI,CAAC,KAAK,CAAC,MAAM;QAAE,OAAO,QAAQ,CAAC;IACnC,OAAO,IAAI,CAAC,YAAY,KAAK,SAAS,IAAI,KAAK,GAAG,IAAI,CAAC,YAAY,IAAI,2BAAmB,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC;AACjH,CAAC;AAED;;;;GAIG;AACH,SAAgB,uBAAuB,CAAC,SAAiB;IACvD,OAAO;QACL,kDAAkD,SAAS,GAAG;QAC9D,wIAAwI;QACxI,yGAAyG,SAAS,oBAAoB;YACpI,0CAA0C;KAC7C,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/requests/limitWaitAnswer.d.ts

@@ -0,0 +1,87 @@
+import type { SessionKey } from '../sessionKey';
+import { type AnswerSinks } from '../platform/answerSink';
+import type { RequestLedger } from './requestLedger';
+import type { RequestWakeUpEngine } from './wakeUpEngine';
+/**
+ * @description The bot's own answer to an open request when a usage/session
+ * limit stops the agent (request/answer core S5): the requester learns the
+ * answer is delayed and until when, instead of hearing nothing for hours.
+ *
+ * It is a `progress` answer delivered straight through the platform's sink —
+ * deliberately NOT through `answer_request`: the agent did not send it, so it
+ * does not count as the agent's progress note and starts no 15-minute follow-up.
+ *
+ * Deduplicated per REQUEST and per wait: every request open during a limit wait
+ * hears about it once — the one open when the limit hit, and one opened later in
+ * the same wait (a scheduled run, a tracker event: they do not cancel the wait).
+ */
+/**
+ * @name UsageLimitWait
+ * @description How the limit wait ends: after the provider's reset time, at the
+ * bot's next attempt (the reset time is unknown), or not by itself at all
+ * (`/auto_continue_limits` is off). `fireAt` is when the bot resumes.
+ */
+export type UsageLimitWait = {
+    kind: 'afterReset';
+    resetAt: number;
+    fireAt: number;
+} | {
+    kind: 'nextAttempt';
+    fireAt: number;
+} | {
+    kind: 'autoResumeOff';
+};
+/**
+ * @description Identifies one limit wait across its repeated errors: an armed
+ * wait by its resume instant (every arming gets a new one), the auto-resume-off
+ * wait by its kind (it has no instant, and it ends only with the request).
+ */
+export declare function getUsageLimitWaitIdentity(wait: UsageLimitWait): string;
+/**
+ * @name ArmedLimitWait
+ * @description The topic's armed usage-limit resume, as the bot's retry manager
+ * holds it. `wait` is absent for a resume re-armed from `state.json` at boot
+ * (which keeps only the instant).
+ */
+export interface ArmedLimitWait {
+    fireAt: number;
+    wait?: UsageLimitWait;
+}
+/**
+ * @name LimitEpisodeState
+ * @description The topic's usage-limit situation when a request is opened.
+ */
+export interface LimitEpisodeState {
+    armedLimitWait: ArmedLimitWait | null;
+    /** A limit hit with auto-resume off, and the operator has not written since. */
+    isAutoResumeOffNoticed: boolean;
+    isAutoResumeOn: boolean;
+}
+/**
+ * @description The limit wait a request opened right now falls into, or `null`
+ * when the topic is not waiting out a limit. An operator message cancels the
+ * wait BEFORE its request is opened, so only a request that does not cancel it
+ * (a scheduled run, a tracker event) ever lands here.
+ */
+export declare function getLimitWaitForNewRequest(episode: LimitEpisodeState): UsageLimitWait | null;
+export interface LimitWaitAnswerDeps {
+    ledger: Pick<RequestLedger, 'listOpenRequestsOf' | 'updateOpenRequest'>;
+    engine: Pick<RequestWakeUpEngine, 'stopWakingForLimitWait'>;
+    answerSinks: AnswerSinks;
+}
+/**
+ * @name LimitWaitAnswerOutcome
+ * @description `notAnswered` (no open request, or the delivery failed) leaves the
+ * caller's plain limit notice to say it; after `answered` or `alreadyAnswered`
+ * the notice would say the same thing twice.
+ */
+export type LimitWaitAnswerOutcome = 'answered' | 'alreadyAnswered' | 'notAnswered';
+/**
+ * @description Tell every open request of the conversation (one per requester at
+ * most) about a limit wait, once per request and wait. With auto-resume off
+ * nothing will continue the work, so the requests also stop being woken
+ * (liftable: a later wait that ends with a resume lifts it). `answered` when at
+ * least one request was answered now; `alreadyAnswered` when every one had been.
+ */
+export declare function answerOpenRequestForLimitWait(deps: LimitWaitAnswerDeps, key: SessionKey, wait: UsageLimitWait, body: string): Promise<LimitWaitAnswerOutcome>;
+//# sourceMappingURL=limitWaitAnswer.d.ts.map

package/dist/requests/limitWaitAnswer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limitWaitAnswer.d.ts","sourceRoot":"","sources":["../../src/requests/limitWaitAnswer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D;;;;;;;;;;;;GAYG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC;AAE9B;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAEtE;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,cAAc,GAAG,IAAI,CAAC;IACtC,gFAAgF;IAChF,sBAAsB,EAAE,OAAO,CAAC;IAChC,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,GAAG,IAAI,CAO3F;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,oBAAoB,GAAG,mBAAmB,CAAC,CAAC;IACxE,MAAM,EAAE,IAAI,CAAC,mBAAmB,EAAE,wBAAwB,CAAC,CAAC;IAC5D,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,UAAU,GAAG,iBAAiB,GAAG,aAAa,CAAC;AAEpF;;;;;;GAMG;AACH,wBAAsB,6BAA6B,CACjD,IAAI,EAAE,mBAAmB,EACzB,GAAG,EAAE,UAAU,EACf,IAAI,EAAE,cAAc,EACpB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,sBAAsB,CAAC,CAOjC"}

package/dist/requests/limitWaitAnswer.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getUsageLimitWaitIdentity = getUsageLimitWaitIdentity;
+exports.getLimitWaitForNewRequest = getLimitWaitForNewRequest;
+exports.answerOpenRequestForLimitWait = answerOpenRequestForLimitWait;
+const answerSink_1 = require("../platform/answerSink");
+/**
+ * @description Identifies one limit wait across its repeated errors: an armed
+ * wait by its resume instant (every arming gets a new one), the auto-resume-off
+ * wait by its kind (it has no instant, and it ends only with the request).
+ */
+function getUsageLimitWaitIdentity(wait) {
+    return wait.kind === 'autoResumeOff' ? wait.kind : `resumeAt:${wait.fireAt}`;
+}
+/**
+ * @description The limit wait a request opened right now falls into, or `null`
+ * when the topic is not waiting out a limit. An operator message cancels the
+ * wait BEFORE its request is opened, so only a request that does not cancel it
+ * (a scheduled run, a tracker event) ever lands here.
+ */
+function getLimitWaitForNewRequest(episode) {
+    if (episode.armedLimitWait) {
+        return episode.armedLimitWait.wait ?? { kind: 'nextAttempt', fireAt: episode.armedLimitWait.fireAt };
+    }
+    // Turning auto-resume back on ends the "I continue when you write" promise.
+    if (episode.isAutoResumeOffNoticed && !episode.isAutoResumeOn)
+        return { kind: 'autoResumeOff' };
+    return null;
+}
+/**
+ * @description Tell every open request of the conversation (one per requester at
+ * most) about a limit wait, once per request and wait. With auto-resume off
+ * nothing will continue the work, so the requests also stop being woken
+ * (liftable: a later wait that ends with a resume lifts it). `answered` when at
+ * least one request was answered now; `alreadyAnswered` when every one had been.
+ */
+async function answerOpenRequestForLimitWait(deps, key, wait, body) {
+    const outcomes = [];
+    for (const request of deps.ledger.listOpenRequestsOf(key)) {
+        outcomes.push(await answerOneRequestForLimitWait(deps, key, request, wait, body));
+    }
+    if (outcomes.includes('answered'))
+        return 'answered';
+    return outcomes.includes('alreadyAnswered') ? 'alreadyAnswered' : 'notAnswered';
+}
+async function answerOneRequestForLimitWait(deps, key, request, wait, body) {
+    const identity = getUsageLimitWaitIdentity(wait);
+    // The common repeat (another frame of the same error) costs no state write.
+    if (request.limitWaitAnsweredFor === identity)
+        return 'alreadyAnswered';
+    // Claimed under the ledger lock: a repeated error and a request opened at the same moment must not answer twice.
+    let isClaimed = false;
+    const claimed = await deps.ledger.updateOpenRequest(request.id, (current) => {
+        isClaimed = current.limitWaitAnsweredFor !== identity;
+        return isClaimed ? { limitWaitAnsweredFor: identity } : {};
+    });
+    if (!claimed)
+        return 'notAnswered';
+    if (!isClaimed)
+        return 'alreadyAnswered';
+    if (wait.kind === 'autoResumeOff')
+        await deps.engine.stopWakingForLimitWait(key);
+    const lookup = (0, answerSink_1.getAnswerSink)(deps.answerSinks, key);
+    const result = lookup.ok
+        ? await lookup.sink.deliverAnswer(key, {
+            requestId: request.id,
+            kind: 'progress',
+            body,
+            origin: request.origin,
+            isRequestOpen: true,
+        })
+        : lookup;
+    if (!result.ok) {
+        console.warn(`[requests] limit answer for ${request.id} not delivered: ${result.error}`);
+        // Unclaimed, so the next error of this wait tries again.
+        await deps.ledger.updateOpenRequest(request.id, (current) => current.limitWaitAnsweredFor === identity ? { limitWaitAnsweredFor: undefined } : {});
+        return 'notAnswered';
+    }
+    if (result.warning)
+        console.warn(`[requests] limit answer for ${request.id} delivered partly: ${result.warning}`);
+    return 'answered';
+}
+//# sourceMappingURL=limitWaitAnswer.js.map

package/dist/requests/limitWaitAnswer.js.map

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

package/dist/requests/requestGroup.d.ts

@@ -0,0 +1,44 @@
+import { type SessionKey } from '../sessionKey';
+import type { RequestOrigin } from './types';
+/**
+ * @description The MERGE rule of the request ledger, in one place: a new request
+ * supersedes an earlier open one ONLY when both have the same group key — the
+ * conversation (the surface and the topic / thread / issue the message belongs
+ * to, i.e. the `SessionKey`) AND the requester. Two people writing in a row in
+ * one topic therefore keep two open requests, each owed its own answer; two
+ * messages in a row from one person merge into the newer request.
+ *
+ * The requester is a connector-owned fact in the origin's attributes (a Telegram
+ * user id, a tracker account id, the scheduler's marker); an origin without one
+ * reads as the empty requester, so every such request in a conversation shares
+ * one group — the behaviour the ledger had before requesters existed.
+ */
+/** The origin attribute that names who raised the request (the part of the group key the conversation does not carry). */
+export declare const requestRequesterAttribute = "requester";
+/**
+ * The requester of an origin that names none — and of every open request
+ * persisted before requesters existed. The ledger lets the conversation's next
+ * request supersede such a request whoever raised it (`requestLedger.ts`).
+ */
+export declare const emptyRequester = "";
+/**
+ * @name RequestGroupKey
+ * @description What an open request is filed under: its conversation and its requester.
+ */
+export interface RequestGroupKey {
+    conversation: SessionKey;
+    requester: string;
+}
+/** @description The requester an origin names, or the empty requester when it names none. */
+export declare function getRequestRequester(origin: RequestOrigin): string;
+/** @description The group a request of `origin` in `conversation` belongs to. */
+export declare function getRequestGroupKey(conversation: SessionKey, origin: RequestOrigin): RequestGroupKey;
+/**
+ * @description The persisted form (`state.json` `openRequests` field name). An
+ * empty requester yields the bare conversation key, so entries written before
+ * requesters existed read back unchanged.
+ */
+export declare function requestGroupKeyToString(group: RequestGroupKey): string;
+/** @description Non-throwing decoder of {@link requestGroupKeyToString}; `null` for a field of an unknown platform. */
+export declare function tryRequestGroupKeyFromString(serialized: string): RequestGroupKey | null;
+//# sourceMappingURL=requestGroup.d.ts.map

package/dist/requests/requestGroup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestGroup.d.ts","sourceRoot":"","sources":["../../src/requests/requestGroup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C;;;;;;;;;;;;GAYG;AAEH,0HAA0H;AAC1H,eAAO,MAAM,yBAAyB,cAAc,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,cAAc,KAAK,CAAC;AASjC;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,UAAU,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,6FAA6F;AAC7F,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAEjE;AAED,iFAAiF;AACjF,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,GAAG,eAAe,CAEnG;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAGtE;AAED,uHAAuH;AACvH,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAOvF"}

package/dist/requests/requestGroup.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emptyRequester = exports.requestRequesterAttribute = void 0;
+exports.getRequestRequester = getRequestRequester;
+exports.getRequestGroupKey = getRequestGroupKey;
+exports.requestGroupKeyToString = requestGroupKeyToString;
+exports.tryRequestGroupKeyFromString = tryRequestGroupKeyFromString;
+const sessionKey_1 = require("../sessionKey");
+/**
+ * @description The MERGE rule of the request ledger, in one place: a new request
+ * supersedes an earlier open one ONLY when both have the same group key — the
+ * conversation (the surface and the topic / thread / issue the message belongs
+ * to, i.e. the `SessionKey`) AND the requester. Two people writing in a row in
+ * one topic therefore keep two open requests, each owed its own answer; two
+ * messages in a row from one person merge into the newer request.
+ *
+ * The requester is a connector-owned fact in the origin's attributes (a Telegram
+ * user id, a tracker account id, the scheduler's marker); an origin without one
+ * reads as the empty requester, so every such request in a conversation shares
+ * one group — the behaviour the ledger had before requesters existed.
+ */
+/** The origin attribute that names who raised the request (the part of the group key the conversation does not carry). */
+exports.requestRequesterAttribute = 'requester';
+/**
+ * The requester of an origin that names none — and of every open request
+ * persisted before requesters existed. The ledger lets the conversation's next
+ * request supersede such a request whoever raised it (`requestLedger.ts`).
+ */
+exports.emptyRequester = '';
+/**
+ * Separates the conversation key from the requester in the persisted group key:
+ * the ASCII unit separator, which no `SessionKey` codec produces (keys are
+ * printable); the requester is URI-encoded so it can never contain it either.
+ */
+const requestGroupSeparator = '\u001f';
+/** @description The requester an origin names, or the empty requester when it names none. */
+function getRequestRequester(origin) {
+    return origin.attributes[exports.requestRequesterAttribute] ?? exports.emptyRequester;
+}
+/** @description The group a request of `origin` in `conversation` belongs to. */
+function getRequestGroupKey(conversation, origin) {
+    return { conversation, requester: getRequestRequester(origin) };
+}
+/**
+ * @description The persisted form (`state.json` `openRequests` field name). An
+ * empty requester yields the bare conversation key, so entries written before
+ * requesters existed read back unchanged.
+ */
+function requestGroupKeyToString(group) {
+    const conversationKey = (0, sessionKey_1.keyToString)(group.conversation);
+    return group.requester === exports.emptyRequester ? conversationKey : `${conversationKey}${requestGroupSeparator}${encodeURIComponent(group.requester)}`;
+}
+/** @description Non-throwing decoder of {@link requestGroupKeyToString}; `null` for a field of an unknown platform. */
+function tryRequestGroupKeyFromString(serialized) {
+    const separatorIndex = serialized.indexOf(requestGroupSeparator);
+    const conversationKey = separatorIndex === -1 ? serialized : serialized.slice(0, separatorIndex);
+    const conversation = (0, sessionKey_1.tryKeyFromString)(conversationKey);
+    if (!conversation)
+        return null;
+    const requester = separatorIndex === -1 ? exports.emptyRequester : decodeURIComponent(serialized.slice(separatorIndex + 1));
+    return { conversation, requester };
+}
+//# sourceMappingURL=requestGroup.js.map

package/dist/requests/requestGroup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestGroup.js","sourceRoot":"","sources":["../../src/requests/requestGroup.ts"],"names":[],"mappings":";;;AA4CA,kDAEC;AAGD,gDAEC;AAOD,0DAGC;AAGD,oEAOC;AAvED,8CAA+E;AAG/E;;;;;;;;;;;;GAYG;AAEH,0HAA0H;AAC7G,QAAA,yBAAyB,GAAG,WAAW,CAAC;AAErD;;;;GAIG;AACU,QAAA,cAAc,GAAG,EAAE,CAAC;AAEjC;;;;GAIG;AACH,MAAM,qBAAqB,GAAG,QAAQ,CAAC;AAWvC,6FAA6F;AAC7F,SAAgB,mBAAmB,CAAC,MAAqB;IACvD,OAAO,MAAM,CAAC,UAAU,CAAC,iCAAyB,CAAC,IAAI,sBAAc,CAAC;AACxE,CAAC;AAED,iFAAiF;AACjF,SAAgB,kBAAkB,CAAC,YAAwB,EAAE,MAAqB;IAChF,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,mBAAmB,CAAC,MAAM,CAAC,EAAE,CAAC;AAClE,CAAC;AAED;;;;GAIG;AACH,SAAgB,uBAAuB,CAAC,KAAsB;IAC5D,MAAM,eAAe,GAAG,IAAA,wBAAW,EAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACxD,OAAO,KAAK,CAAC,SAAS,KAAK,sBAAc,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,GAAG,eAAe,GAAG,qBAAqB,GAAG,kBAAkB,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;AACnJ,CAAC;AAED,uHAAuH;AACvH,SAAgB,4BAA4B,CAAC,UAAkB;IAC7D,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACjE,MAAM,eAAe,GAAG,cAAc,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;IACjG,MAAM,YAAY,GAAG,IAAA,6BAAgB,EAAC,eAAe,CAAC,CAAC;IACvD,IAAI,CAAC,YAAY;QAAE,OAAO,IAAI,CAAC;IAC/B,MAAM,SAAS,GAAG,cAAc,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,sBAAc,CAAC,CAAC,CAAC,kBAAkB,CAAC,UAAU,CAAC,KAAK,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC,CAAC;IACpH,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC;AACrC,CAAC"}