@cello-protocol/daemon 0.0.194 → 0.0.195

package/dist/refusal-notices.d.ts

@@ -0,0 +1,196 @@
+/**
+ * CELLO Daemon — REFUSALS THE OPERATOR CAN ACTUALLY SEE
+ *
+ * Split out of `session-node-manager.ts` by 037-SESSIONCORE.
+ *
+ * ⚠️ THE POINT OF THIS MODULE IS THAT A REFUSAL HAS A READER. Every inbound refusal already logged a
+ * reason, an impact and a guidance, and they were good — and they had no consumer. From the
+ * receiving operator's chair a refused message simply never arrives: the conversation goes quiet
+ * with a full explanation sitting in a file they have no reason to open, and they conclude the other
+ * person stopped replying.
+ *
+ * DURABLE, and that is the half that makes it useful — a restart must not lose the notice, because
+ * the question it answers ("why did they go quiet?") outlives the process that refused.
+ *
+ * Moved verbatim, comments included.
+ */
+import type { Logger } from "./types.js";
+import type { DaemonDatabase } from "./sqlcipher-db.js";
+import type { SessionQueries } from "./session-queries.js";
+import { type RefusalKind } from "./refusal-reasons.js";
+import { type RefusalNotice } from "./session-node-types.js";
+/** What the refusal surface needs from the manager. */
+export interface RefusalNoticeContext {
+    readonly logger: Logger;
+    readonly queries: SessionQueries;
+    /** A function: the manager opens its database after construction. Re-exposed below as `#db`. */
+    db(): DaemonDatabase | null;
+    requireAgentId(agentName: string): string;
+    sessionKey(agentName: string, sessionId: string): string;
+    unkey(key: string, agentName: string): string | null;
+}
+export declare class RefusalNotices {
+    #private;
+    constructor(ctx: RefusalNoticeContext);
+    /**
+     * The one read path behind both doors. `sessionId` narrows it; omitted, it spans the agent.
+     *
+     * A single implementation on purpose: the per-consumer rule and the order-of-magnitude rule are
+     * the two properties this unit must not lose, and two copies of them is two things to keep true.
+     */
+    drainRefusals(agentName: string, consumerId: string, sessionId?: string): {
+        notices: RefusalNotice[];
+        truncated: boolean;
+    };
+    /**
+     * ─── DOD-M15-NO-SILENT-REFUSAL-1: refusals the RECEIVING operator can actually see ────────────
+     *
+     * Every inbound refusal already logs a `reason`, an `impact` and a `guidance` — and they are
+     * good. They had no reader. From the receiving operator's chair a refused message simply never
+     * arrives: the conversation goes quiet with a full explanation sitting in a file they have no
+     * reason to open, and they conclude the other person stopped replying.
+     *
+     * **DURABLE, and that is the half that makes this useful.** The predecessor kept notices in a
+     * `Map` on this instance and drained them on the receive path for one session. So a restart lost
+     * them, and an agent NOBODY IS ATTENDING lost them too — the connection is live, the daemon is
+     * up, and the notice only ever reaches whoever happens to call `cello_receive` on that exact
+     * session. `cello_check_notifications` now reads them as its own inbox category.
+     *
+     * **DEDUPLICATED PER SESSION PER REASON, and that is the design, not an optimisation.** A skewed
+     * peer turns one problem into a flood: the first refusal of a kind is the signal, the ninetieth is
+     * noise that trains the operator to ignore the surface. `count` keeps the scale visible without
+     * repeating the alert.
+     *
+     * **NEVER carries the content.** It failed verification; surfacing it is the injection path the
+     * cross-check exists to close. The operator learns that a message was refused and why — never
+     * what it said.
+     */
+    /**
+     * Record an inbound refusal for the operator. First of its kind per session is the signal.
+     *
+     * ⚠️ **DOES NOT THROW, and that is a decision with a cost — stated so it is not mistaken for an
+     * oversight.** Every call site here has already decided to refuse and is about to return a reason
+     * to its caller; a throw would replace that clean refusal with an exception on the ingest path,
+     * changing what the SENDER observes because this daemon could not file a note. So a persistence
+     * failure is logged at ERROR under `session.refusal.persist.failed`, carrying the reason, the
+     * impact and the guidance verbatim — the forensic record survives even when the operator-facing
+     * one does not. It is not silent; it is one surface short, and the log says which notice was lost.
+     */
+    noteContentRefusal(agentName: string, sessionId: string, reason: string, 
+    /**
+     * ALL THREE REQUIRED, and that is the enforcement rather than the convention.
+     *
+     * The DoD clause is "every reason calls this with an impact and a guidance", and an optional
+     * field makes that a thing a reviewer checks by reading thirteen call sites. `kind` is required
+     * for the same reason one level up: the header over a list of refusals is composed from it, and
+     * a notice that could omit it would silently inherit whichever header happened to be first.
+     */
+    detail: {
+        kind: RefusalKind;
+        impact: string;
+        guidance: string;
+    }): void;
+    /**
+     * DOD-M15-NO-SILENT-REFUSAL-1 — the per-session byte cap, from the operator's chair.
+     *
+     * This is the harshest refusal on the inbound path and the one that reads least like a fault:
+     * once the cap is crossed, EVERY later message from that sender on that session is refused, for
+     * the life of the session. The counterparty is told nothing either, so from both chairs the other
+     * person simply stopped replying.
+     *
+     * One method rather than two copies because the cap is checked twice — once before the screening
+     * await and once after, against freshly-read totals — and a notice that differs between the two
+     * would describe a different refusal depending on timing.
+     */
+    /**
+     * DOD-M15-REFUSEDEVIDENCE-1 — **THE BYTE CAP RETAINS NOTHING, and that is a ruling, not an
+     * oversight.**
+     *
+     * Retention is universal everywhere else in this method. Here it is not, because retaining would
+     * defeat the very bound it enforces: a session already over its storage budget cannot be given
+     * more storage as a reward for exceeding it, and `#getReceivedBytesTotal` counts quarantined bytes
+     * precisely so that budget is honest.
+     *
+     * Andre, 2026-09-03: *"The message limit is the message limit, already handled by the cap. If
+     * you're unknown and you have 25 MB and you just tried to send me one gig, well that's it."*
+     *
+     * The ABUSE is still evidenced — this notice records the reason, the cap and the tier, and every
+     * message the session did retain is still there. What is not kept is the oversized payload.
+     */
+    noteSizeCapRefusal(agentName: string, sessionId: string, cap: number, tier: number): void;
+    /**
+     * Drain the refusals a GIVEN CONSUMER has not been shown yet, and remember what it was shown.
+     *
+     * ─── Why this is keyed by consumer, and not by a single flag ──────────────────────────────────
+     *
+     * It used to set one `surfaced: boolean` on the notice. Two MCP windows attending the same agent
+     * is the ordinary case, and under that flag whoever read FIRST consumed the notice — the second
+     * window was told nothing, permanently. **That is the same defect `takeReceivedContent` had**, and
+     * the comment above the delivery loop in `session-content-handlers.ts` spells out why it was
+     * removed: *"reading is non-destructive by construction. Nothing one consumer does mutates state
+     * another consumer reads."*
+     *
+     * ─── Why the count has a reader ───────────────────────────────────────────────────────────────
+     *
+     * A reason RE-ANNOUNCES to a consumer when its count has grown by an order of magnitude since that
+     * consumer last saw it (1 → 10 → 100 → …), marked `repeat: true`. That keeps the first refusal the
+     * signal and the ninetieth silent, which is the dedup's point, while still making a skew that has
+     * swallowed hundreds of messages visible — at a handful of announcements per session, not one per
+     * message.
+     *
+     * ─── What a restart does, deliberately ────────────────────────────────────────────────────────
+     *
+     * The notices survive; the read state is keyed by IPC connection id, which does not. So after a
+     * restart every notice is unseen again and the next reader is told. That is the correct direction:
+     * a fresh window has not been told anything, and re-announcing costs one line where staying silent
+     * costs the whole point of storing it.
+     */
+    takeContentRefusals(agentName: string, sessionId: string, 
+    /**
+     * REQUIRED, deliberately — no default.
+     *
+     * It had one (`"default"`), and a default is the defect this method was rewritten to remove,
+     * lying in wait: any future call site that omits the argument silently shares ONE bucket across
+     * every window, the first reader consumes the notice for all the others, and nothing fails to
+     * compile and no test goes red. The parameter existing is not the protection; being unable to
+     * forget it is.
+     */
+    consumerId: string): Array<Omit<RefusalNotice, "sessionId">>;
+    /**
+     * DOD-M15-NO-SILENT-REFUSAL-1: the operator has seen these and does not want to see them again.
+     *
+     * ⚠️ **WITHOUT THIS THE NOTICES ARE PERMANENT, and that is what makes people stop reading the
+     * inbox.** "Already shown you" is tracked per WINDOW — a new MCP connection has been told nothing,
+     * so it is told everything. Someone on an older build messages you, you sort it out with them,
+     * they upgrade, and every new session you ever open still opens with that refusal.
+     *
+     * Dismissing does NOT turn anything off. If the cause fires again the notice comes back, because
+     * a fresh refusal writes a fresh row. The operator is saying "I know", not "stop telling me".
+     *
+     * Returns how many were cleared, so the caller can say so rather than claiming a silent success.
+     */
+    dismissContentRefusals(agentName: string, sessionId: string): number;
+    /**
+     * DOD-M15-NO-SILENT-REFUSAL-1: every unshown refusal for an agent, ACROSS its sessions.
+     *
+     * The inbox's door. `takeContentRefusals` answers for one session because its caller already holds
+     * one; `cello_check_notifications` holds an agent and nothing else, and the case this whole line
+     * exists for is that nobody is attending any of that agent's sessions — so a per-session read
+     * cannot reach it. Same store, same per-consumer rule, same re-announce.
+     */
+    takeAgentContentRefusals(agentName: string, consumerId: string): {
+        notices: RefusalNotice[];
+        truncated: boolean;
+    };
+    /**
+     * Drop the IN-MEMORY fallback notices for one session.
+     *
+     * ⚠️ THE DURABLE ROWS ARE NOT TOUCHED, and the omission is deliberate rather than forgotten. They
+     * live in `content_refusal_notices` keyed on agent_id + session_id, and the question they answer —
+     * "why did my counterparty go quiet?" — outlives the session that produced it. Only the in-memory
+     * fallback, which exists for the case where the write to disk failed, is dropped here; leaving it
+     * would let a store that is already in trouble grow without bound in memory as well.
+     */
+    evictSession(agentName: string, sessionId: string): void;
+}
+//# sourceMappingURL=refusal-notices.d.ts.map

package/dist/refusal-notices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refusal-notices.d.ts","sourceRoot":"","sources":["../src/refusal-notices.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGvE,OAAO,EACL,KAAK,aAAa,EAGnB,MAAM,yBAAyB,CAAC;AAEjC,uDAAuD;AACvD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,gGAAgG;IAChG,EAAE,IAAI,cAAc,GAAG,IAAI,CAAC;IAC5B,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1C,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IACzD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CACtD;AAED,qBAAa,cAAc;;gBAGb,GAAG,EAAE,oBAAoB;IAkBrC;;;;;OAKG;IACH,aAAa,CACX,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB;QAAE,OAAO,EAAE,aAAa,EAAE,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE;IAgLnD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH;;;;;;;;;;OAUG;IACH,kBAAkB,CAChB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM;IACd;;;;;;;OAOG;IACH,MAAM,EAAE;QAAE,IAAI,EAAE,WAAW,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAC9D,IAAI;IA0FP;;;;;;;;;;;OAWG;IACH;;;;;;;;;;;;;;OAcG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAuBzF;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,mBAAmB,CACjB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM;IACjB;;;;;;;;OAQG;IACH,UAAU,EAAE,MAAM,GACjB,KAAK,CAAC,IAAI,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC;IAS1C;;;;;;;;;;;;OAYG;IACH,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAapE;;;;;;;OAOG;IACH,wBAAwB,CACtB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB;QAAE,OAAO,EAAE,aAAa,EAAE,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE;IAInD;;;;;;;;OAQG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;CAGzD"}