@staix/agent-hub 0.12.29 → 0.12.31

package/src/hub/bus.ts

@@ -1,6 +1,8 @@
-import { appendNote, DIGEST, HUB, keepNotes, MAX_HOP, newEnvelope, noteLine, parseMarker, quoteNotes, replyAudience, type Envelope, type EnvelopeOpts, type PeerId, type PeerState, type Priority } from "./envelope.ts";
+import { appendNote, DIGEST, HUB, keepNotes, MAX_HOP, mergePrefaces, newEnvelope, noteLine, parseMarker, quoteNotes, replyAudience, uniqueMemoryLines, type Envelope, type EnvelopeOpts, type PeerId, type PeerState, type Priority } from "./envelope.ts";
 import type { PeerAdapter, DeliveryReceipt } from "./peers.ts";
-import { DeliveryJournal, type JournalDelivery, type JournalDeliveryState } from "./delivery-journal.ts";
+import { DeliveryJournal, MAX_ENVELOPE_BODY, type JournalDelivery, type JournalDeliveryState } from "./delivery-journal.ts";
+import { DELIVERY_RETRY_WARNING } from "./delivery-hints.ts";
+import { PreEffectToolRefusal } from "./tool-refusal.ts";
 
 export type { DeliveryReceipt } from "./peers.ts";
 
@@ -135,6 +137,8 @@ export class Bus {
   onDelivered?: (peer: PeerId, originals: Envelope[]) => void;
   /** Before deliver's synchronous busy transition, with originals rather than a condensed digest. */
   onDeliver?: (peer: PeerId, originals: Envelope[]) => void;
+  /** Final rendered journal payload, and its first positive acknowledgement. Observation cannot alter settlement. */
+  onMemoryDelivery?: (peer: PeerId, deliveryId: string, out: Envelope[], field: "rendered" | "delivered") => void;
   /** Synchronous native failure observation, before queue callbacks can finish turn metrics. */
   onDeliveryFailed?: (peer: PeerId) => void;
   private recoveryHeld = false;
@@ -246,10 +250,11 @@ export class Bus {
     catch { this.storageError = "delivery journal unavailable"; throw new Error("delivery journal unavailable"); }
   }
 
-  private durableHandoff(peer: PeerId, deliveryId: string, originals: Envelope[], out: Envelope[]): void {
+  private durableHandoff(peer: PeerId, deliveryId: string, originals: Envelope[], out: Envelope[], observe = true): void {
     if (!this.journal) return;
     const delivery = { id: deliveryId, peer, state: "dispatching" as const, createdAt: Date.now(), originals, out };
     this.journal.checkpointDelivery(this.snapshotWithoutJournal(), delivery);
+    if (observe) this.memoryDelivery(peer, deliveryId, out, "rendered", originals);
   }
 
   private snapshotWithoutJournal(): BusSnapshot {
@@ -259,6 +264,7 @@ export class Bus {
   /** Stop new deliveries while a coordinator takes a stable snapshot. Existing adapter turns are left alone. */
   setRecoveryHold(held: boolean): void {
     this.recoveryHeld = held;
+    if (!held) this.onQueues?.(); // restored holds need classification even when no peer is attached
     if (!held) for (const id of this.peers.keys()) void this.drain(id);
   }
 
@@ -327,7 +333,7 @@ export class Bus {
     this.queues.clear();
     for (const [id, queue] of Object.entries(snapshot.queues ?? {})) this.queues.set(id, queue.map((e) => ({ ...e, ...(e.to ? { to: [...e.to] } : {}) })));
     this.prefaces.clear();
-    for (const [id, e] of Object.entries(snapshot.prefaces ?? {})) this.prefaces.set(id, { ...e, ...(e.to ? { to: [...e.to] } : {}) });
+    for (const [id, e] of Object.entries(snapshot.prefaces ?? {})) this.prefaces.set(id, { ...e, body: uniqueMemoryLines(e.body), ...(e.to ? { to: [...e.to] } : {}) });
     this.seen.clear();
     for (const e of snapshot.seen ?? []) this.seen.set(e.id, { ...e, ...(e.to ? { to: [...e.to] } : {}) });
     this.attempts.clear();
@@ -357,16 +363,41 @@ export class Bus {
 
   queueShow(id: string): JournalDelivery | undefined { return this.journal?.get(id) ?? this.queueList().find((d) => d.id === id); }
 
-  resolveDelivery(id: string, revision: number, action: "completed" | "retry" | "discard", reason: string): void {
+  heldDeliveryHints(peer: string) { return this.storageError ? undefined : this.journal?.heldDeliveryHints(peer); }
+
+  /** Consent is for this peer's held row only, never authority to complete/discard or release a pause. */
+  retryDelivery(peer: string, id: string): void {
+    const refuse = () => { throw new PreEffectToolRefusal("recipient retry unavailable; inspect the held delivery or ask the person"); };
+    if (this.closed || this.recoveryHeld || this.storageError || peer === "user" || peer === HUB) return refuse();
+    const row = this.queueShow(id);
+    if (!row || row.peer !== peer || row.state !== "needs_review" || !this.journal || this.journal.retryEvidence(peer, row.originals) !== "unused") return refuse();
+    this.resolveDelivery(id, row.revision, "retry", "recipient requested one uncertain redelivery", `peer:${peer}`);
+  }
+
+  private retryOut(peer: string, originals: Envelope[], out: Envelope[]): Envelope[] {
+    if (!out.length || !this.journal || !this.journal.retryWarning(peer, originals)) return out;
+    return out.map((env, index) => {
+      if (index !== 0) return env;
+      const prefix = `${DELIVERY_RETRY_WARNING}\n\n`, marker = "\n[cut: rendered body exceeds delivery limit]";
+      if (prefix.length + env.body.length <= MAX_ENVELOPE_BODY) return { ...env, body: prefix + env.body };
+      let end = MAX_ENVELOPE_BODY - prefix.length - marker.length;
+      // The journal cap uses UTF-16 length; never cut between a Unicode surrogate pair.
+      if (Array.from(env.body.slice(end - 1, end + 1))[0]?.length === 2) end--;
+      return { ...env, body: prefix + env.body.slice(0, end) + marker };
+    });
+  }
+
+  resolveDelivery(id: string, revision: number, action: "completed" | "retry" | "discard", reason: string, actor: string = "user"): void {
     if (!this.journal || this.storageError) throw new Error("delivery journal unavailable");
     const record = this.queueShow(id);
     if (!record) throw new Error("unknown delivery");
     const previous = this.journal.resolution(id);
     if (previous) {
-      this.journal.resolve(id, revision, action, reason); // verifies identical request; no second enqueue
+      this.journal.resolve(id, revision, action, reason, revision, actor); // verifies identical request; no second enqueue
       return;
     }
-    if (["dispatching", "accepted"].includes(record.state) || this.peers.get(record.peer)?.state === "busy") throw new Error("active delivery cannot be resolved");
+    const recipientConsent = actor === `peer:${record.peer}` && action === "retry" && record.state === "needs_review";
+    if (["dispatching", "accepted"].includes(record.state) || (this.peers.get(record.peer)?.state === "busy" && !recipientConsent)) throw new Error("active delivery cannot be resolved");
     if (record.revision !== revision) throw new Error("stale delivery revision");
     if (record.state === "queued" && action === "retry") throw new Error("queued delivery is already scheduled");
     if (action === "retry" && (this.queues.get(record.peer)?.length ?? 0) + record.originals.length > this.opts.queueCap) throw new Error("recipient queue is full");
@@ -378,17 +409,17 @@ export class Bus {
       this.journal.transaction(() => {
         if (!this.journal!.get(id)) this.journal!.createDelivery({ ...record });
         const current = this.journal!.get(id)!;
-        this.journal!.resolve(id, current.revision, action, reason, revision);
+        this.journal!.resolve(id, current.revision, action, reason, revision, actor);
         if (record.state === "queued") {
           const ids = new Set(record.originals.map((env) => env.id));
           queue.splice(0, queue.length, ...queue.filter((env) => !ids.has(env.id)));
         }
-        if (action === "retry") {
+        if (action === "retry" || action === "completed" && actor === "hub") {
           for (const env of record.originals) {
             if (env.from === HUB && env.kind === "presence") this.restorePreface(record.peer, env);
-            else if (!queue.some((old) => old.id === env.id)) queue.push(env);
+            else if (action === "retry" && !queue.some((old) => old.id === env.id)) queue.push(env);
           }
-          this.queues.set(record.peer, queue);
+          if (action === "retry") this.queues.set(record.peer, queue);
         }
         this.persist();
       });
@@ -433,8 +464,12 @@ export class Bus {
     const before = this.journal.get(id);
     const state: JournalDeliveryState = receipt.state === "accepted" ? "accepted" : receipt.state === "completed" ? "completed" : receipt.state === "failed_safe" ? "failed" : "needs_review";
     if (state === "failed" || state === "needs_review") this.deliveryFailed(peer);
-    this.journal.transition(id, state, receipt.reason);
-    if (before?.state === "dispatching" && (state === "accepted" || state === "completed")) this.delivered(peer, before.originals);
+    if (state === "completed") this.journal.completeDelivered(id, peer, "adapter", receipt.reason);
+    else this.journal.transition(id, state, receipt.reason);
+    if (before?.state === "dispatching" && (state === "accepted" || state === "completed")) {
+      this.memoryDelivery(peer, id, before.out, "delivered", before.originals);
+      this.delivered(peer, before.originals);
+    }
     if (state === "failed") {
       if (before) this.failed(peer, before.originals, before.originals.some((e) => e.private) ? "private delivery failed" : receipt.reason, receipt.quota === true && before.state === "dispatching");
     }
@@ -457,8 +492,9 @@ export class Bus {
     for (const [id, owner] of this.activeDeliveries) {
       if (owner !== peer) continue;
       const row = this.journal.get(id);
-      if (row?.out.some((e) => e.id === envelopeId)) {
-        this.journal.transition(id, "completed", "correlated reply");
+      if (row?.peer === peer && ["dispatching", "accepted"].includes(row.state) && row.out.some((e) => e.id === envelopeId)) {
+        this.journal.completeDelivered(id, peer, "reply", "correlated reply");
+        if (row.state === "dispatching") this.memoryDelivery(peer, id, row.out, "delivered", row.originals);
         this.activeDeliveries.delete(id);
         this.refreshRecoveryHold(peer);
         this.onQueues?.();
@@ -529,12 +565,12 @@ export class Bus {
 
   /** Context the hub wants the peer to see once: it rides in front of the next delivery instead of costing a turn of its own. */
   preface(id: PeerId, text: string): void {
-    const body = quoteNotes(text);
+    const body = uniqueMemoryLines(quoteNotes(text));
     const existing = this.prefaces.get(id);
     if (existing) {
-      // Recovery and session recall may both contribute context. Keep the original id/hop so a queued
-      // preface remains deduplicated and append the new, separately generated context.
-      this.prefaces.set(id, { ...existing, body: `${existing.body}\n\n${body}` });
+      // A fresh daemon recalls again after restoring queued context. Merge repeated blocks,
+      // retain distinct context and keep the original envelope id/hop for retry bookkeeping.
+      this.prefaces.set(id, { ...existing, body: mergePrefaces(existing.body, body) });
       this.persist();
       return;
     }
@@ -545,14 +581,14 @@ export class Bus {
   /** Another peer's shared note: rides in the preface like recall. The newest NOTES_KEPT stay; older ones remain in claude-mem. */
   note(id: PeerId, line: string): void {
     const existing = this.prefaces.get(id);
-    this.prefaces.set(id, existing ? { ...existing, body: keepNotes(appendNote(existing.body, line), NOTES_KEPT) } : newEnvelope(HUB, line, { to: [id], kind: "presence" }));
+    this.prefaces.set(id, existing ? { ...existing, body: keepNotes(uniqueMemoryLines(appendNote(existing.body, line)), NOTES_KEPT) } : newEnvelope(HUB, uniqueMemoryLines(line), { to: [id], kind: "presence" }));
     this.persist();
   }
 
   /** A preface that went out with a failed delivery comes back ahead of whatever was prefaced meanwhile, instead of replacing it. */
   private restorePreface(id: PeerId, env: Envelope): void {
     const now = this.prefaces.get(id);
-    this.prefaces.set(id, !now ? env : now.id === env.id ? now : { ...env, body: keepNotes(`${env.body}\n\n${now.body}`, NOTES_KEPT) });
+    this.prefaces.set(id, !now ? { ...env, body: uniqueMemoryLines(env.body) } : now.id === env.id ? { ...now, body: uniqueMemoryLines(now.body) } : { ...env, body: keepNotes(mergePrefaces(env.body, now.body), NOTES_KEPT) });
   }
 
   /** Returns the peers the envelope was queued for. */
@@ -637,6 +673,11 @@ export class Bus {
     return this.seen.get(id);
   }
 
+  /** The envelopes most recently handed to a peer, used to distinguish a received request from an unread queue. */
+  lastDeliveredTo(peer: PeerId): Envelope[] {
+    return this.lastDelivery.get(peer)?.out ?? [];
+  }
+
   /**
    * Take back an envelope that has not been delivered yet (a request that has expired). True when it was removed from a
    * queue now; an envelope whose steer is still in flight is not in any queue, so its id is remembered and it is
@@ -684,6 +725,11 @@ export class Bus {
     this.emit({ t: "stale", env, peer, reason });
   }
 
+  private memoryDelivery(peer: PeerId, id: string, out: Envelope[], field: "rendered" | "delivered", originals: Envelope[] = out): void {
+    if ([...out, ...originals].some(env => env.private)) return;
+    try { this.onMemoryDelivery?.(peer, id, out, field); } catch { /* optional telemetry never alters delivery */ }
+  }
+
   private delivered(peer: PeerId, originals: Envelope[]): void {
     try { this.onDelivered?.(peer, originals); } catch { /* observation must never affect delivery settlement */ }
   }
@@ -766,14 +812,20 @@ export class Bus {
     if (index < 0) return;
     this.steering++;
     const deliveryId = crypto.randomUUID();
+    let removed = false, handedOff = false;
     try {
+      const out = this.retryOut(id, [env], [env]);
       queue.splice(index, 1);
-      this.durableHandoff(id, deliveryId, [env], [env]);
+      removed = true;
+      this.durableHandoff(id, deliveryId, [env], out);
+      handedOff = true;
       this.activeDeliveries.set(deliveryId, id);
-      try { await peer.steer([env], deliveryId); }
+      try { await peer.steer(out, deliveryId); }
       catch { this.uncertain(id, deliveryId, "steering outcome is uncertain"); }
-    } catch { this.storageError = "delivery journal unavailable"; }
-    finally { this.steering--; this.onQueues?.(); }
+    } catch {
+      if (removed && !handedOff) queue.splice(index, 0, env);
+      this.storageError = "delivery journal unavailable";
+    } finally { this.steering--; this.onQueues?.(); }
   }
 
   /** Holds on a peer's queue, for a drain and a pull alike: off roster, recovery, an uncertain delivery, a pause (console, budget, conductor). */
@@ -812,14 +864,16 @@ export class Bus {
     if (!preface && !queue.length) return [];
     const queued = [...queue];
     const batch = [...(preface ? [preface] : []), ...this.take(id, queue)];
-    this.prefaces.delete(id);
-    // Before the checkpoint, as in a drain, so the persisted snapshot carries it; on a failure the bus stops anyway.
-    this.remember(batch);
+    let out: Envelope[] = [];
+    const deliveryId = crypto.randomUUID();
     try {
-      const deliveryId = crypto.randomUUID();
+      out = this.retryOut(id, batch, batch);
+      this.prefaces.delete(id);
+      // Before the checkpoint, as in a drain, so the persisted snapshot carries it; a failed policy read rolls back too.
+      this.remember(out);
       this.journal?.transaction(() => {
-        this.durableHandoff(id, deliveryId, batch, batch); // its bus snapshot is the queue after this pull
-        this.journal!.transition(deliveryId, "completed", "read through hub_inbox");
+        this.durableHandoff(id, deliveryId, batch, out, false); // observe only after this outer transaction commits
+        this.journal!.completeDelivered(deliveryId, id, "pull", "read through hub_inbox");
       });
     } catch (error) {
       queue.splice(0, queue.length, ...queued);
@@ -827,9 +881,13 @@ export class Bus {
       this.storageError = "delivery journal unavailable";
       throw error;
     }
+    if (this.journal) {
+      this.memoryDelivery(id, deliveryId, out, "rendered", batch);
+      this.memoryDelivery(id, deliveryId, out, "delivered", batch);
+    }
     this.failureStreak.delete(id); this.lastFailure.delete(id); // read, as a completed push receipt clears them
     this.onQueues?.();
-    return batch;
+    return out;
   }
 
   private async drain(id: PeerId): Promise<void> {
@@ -851,8 +909,11 @@ export class Bus {
         const delivery = preface ? [preface, ...batch] : batch;
         const mayCondense = this.opts.condense && !delivery.some((e) => e.priority === "important");
         this.condensing += mayCondense ? 1 : 0;
-        const out = mayCondense ? await this.opts.condense!(delivery).catch(() => delivery) : delivery;
-        this.condensing -= mayCondense ? 1 : 0;
+        let out: Envelope[];
+        try {
+          const condensed = mayCondense ? await this.opts.condense!(delivery).catch(() => delivery) : delivery;
+          out = this.retryOut(id, delivery, condensed);
+        } finally { this.condensing -= mayCondense ? 1 : 0; }
         // A session that cannot show pushes may have taken the peer while this was condensed (issue #205).
         if (!this.deliverable(id)) {
           if (!this.journal) { if (preface) this.restorePreface(id, preface); queue.unshift(...batch.filter((e) => !this.withdrawn.has(e.id))); }
@@ -864,16 +925,25 @@ export class Bus {
           this.dropIrrelevant(id, queue);
           continue;
         }
+        const deliveryId = crypto.randomUUID();
         if (this.journal) {
           if (this.prefaces.get(id) !== preface || batch.some((e) => !queue.some((item) => item.id === e.id))) continue;
+          const queued = [...queue], seen = [...this.seen];
           for (const env of batch) queue.splice(queue.findIndex((item) => item.id === env.id), 1);
           this.prefaces.delete(id);
-        }
-        this.remember(out);
+          this.remember(out); // the checkpoint must retain rendered reply ids across a restart
+          try { this.durableHandoff(id, deliveryId, delivery, out); }
+          catch (error) {
+            queue.splice(0, queue.length, ...queued);
+            if (preface) this.prefaces.set(id, preface);
+            this.seen.clear();
+            for (const [key, env] of seen) this.seen.set(key, env);
+            throw error;
+          }
+          this.activeDeliveries.set(deliveryId, id);
+        } else this.remember(out);
         this.lastDelivery.set(id, { out, originals: delivery });
         this.preparing.delete(id); // from here on the transport/journal owns settlement
-        const deliveryId = crypto.randomUUID();
-        if (this.journal) { this.durableHandoff(id, deliveryId, delivery, out); this.activeDeliveries.set(deliveryId, id); }
         try {
           try { this.onDeliver?.(id, delivery); } catch { /* observation must never affect delivery */ }
           if (this.journal) await peer.deliver(out, deliveryId);