@songsid/agend 2.2.0-beta.1 → 2.2.0-beta.11

package/dist/delivery-outbox.d.ts

@@ -1,8 +1,10 @@
 import { EventEmitter } from "node:events";
 import type { QueueResumePolicy } from "./delivery-queue-evidence.js";
+import { type HumanOrigin, type HumanReceiptRow, type HumanReceiptProof } from "./human-delivery-receipts.js";
 export declare const DURABLE_DELIVERY_MAX_ATTEMPTS = 8;
 export declare const DURABLE_DELIVERY_MAX_AGE_MS: number;
 export declare const DURABLE_DELIVERY_ABORT_BACKOFF_MS = 5000;
+export declare const DEFAULT_REPLY_OBLIGATION_TTL_MS: number;
 export interface DaemonDeliveryPort {
     begin(deliveryId: string, targetBootId: string, attemptNo: number, evidence?: DeliveryAttemptEvidence): "begun" | "duplicate" | "stale";
     markEnterStarted(deliveryId: string, targetBootId: string, attemptNo: number): boolean;
@@ -39,6 +41,10 @@ export interface NewOutboxDelivery {
     kind: string;
     correlationId?: string;
     payload: Record<string, unknown>;
+    /** Validated again at the atomic admission boundary using sourceInstance. */
+    forwards?: readonly string[];
+    /** Requested mode before transient predecessor/capability fallback; pins forwarded retries. */
+    requestedKind?: string;
 }
 export interface OutboxDelivery {
     deliveryId: string;
@@ -145,6 +151,17 @@ export interface DeliveryStatusItem {
      * other query, and operator reads, stay redacted as before (#982).
      */
     content?: string | null;
+    /** Recorded explicit disclosures; never inferred from the message text. */
+    forwarded_by?: Array<{
+        source_instance: string;
+        message_id: string;
+        forwarded_at: string;
+    }>;
+    /** Only trusted human evidence rows carry origin. Agent relays never inherit it. */
+    origin?: HumanOrigin;
+    wire_content_sha256?: string | null;
+    delivered_at?: string | null;
+    proof_kind?: HumanReceiptProof["tag"] | null;
     /**
      * How the message was routed, in send_to_instance's own words: `steer` (into the live turn) or `idle_queue` (as the
      * next message). The fleet decided this at admission; it is the row's kind.
@@ -158,18 +175,26 @@ export interface DeliveryStatusItem {
     consumed_via: ConsumedVia | null;
     /** #926: the reply this request is owed, when it asked for one. */
     reply_obligation?: {
-        state: "open" | "answered";
+        state: "open" | "answered" | "expired";
         opened_at: string;
         last_asked_at: string;
         nudged_at: string | null;
         overdue_notified_at: string | null;
         answered_at: string | null;
+        expired_at?: string | null;
     } | null;
+    /**
+     * #1641: while `queued` / `retry_wait`, why the target is not taking it, in words (`The CLI appears stuck.`, paused, a
+     * dialog, a login failure); null when nothing known holds it (it is simply next in line). Added by the fleet, which
+     * knows the target's live state; absent on other states.
+     */
+    waiting_reason?: string | null;
 }
 /**
  * #926: a peer asked with `requires_reply` and the owner has not answered it
  * through the fleet yet. Terminal text is not an answer: only a message the
- * owner sends back to the requester with the same correlation_id closes it.
+ * owner sends back to the requester with the same correlation_id answers it.
+ * #1694 can separately expire its automatic tracking without recording an answer.
  */
 export interface ReplyObligation {
     correlationId: string;
@@ -178,11 +203,12 @@ export interface ReplyObligation {
     requestDeliveryId: string;
     openedAt: string;
     lastAskedAt: string;
-    state: "open" | "answered";
+    state: "open" | "answered" | "expired";
     nudgedAt: string | null;
     overdueNotifiedAt: string | null;
     answeredAt: string | null;
     answeredDeliveryId: string | null;
+    expiredAt: string | null;
 }
 export interface DeliveryStatusPage {
     items: DeliveryStatusItem[];
@@ -219,8 +245,17 @@ export interface DeliveryReconciliationCandidate extends OutboxDelivery {
         enterStartedAt: string | null;
     };
 }
-/** The exact statement `needsAttention` runs; exported so the plan test checks this text and no copy of it. */
-export declare const NEEDS_ATTENTION_SQL = "\n  SELECT delivery_id, state, source_instance, target_instance, kind, finished_at, last_error\n  FROM deliveries INDEXED BY idx_delivery_attention\n  WHERE state IN ('uncertain','failed') AND acknowledged_at IS NULL AND finished_at >= ?\n  ORDER BY finished_at DESC LIMIT ?";
+/**
+ * The exact statement `needsAttention` runs; exported so the plan test checks this text and no copy of it. A silent
+ * schedule's raw paste is never an item (#1647): nobody can act on it, the next run goes ahead anyway, and the fleet's
+ * notice to the leader (with the cause) is its whole report. Every human-originated row stays.
+ */
+export declare const NEEDS_ATTENTION_SQL = "\n  SELECT delivery_id, state, source_instance, target_instance, kind, finished_at, last_error\n  FROM deliveries INDEXED BY idx_delivery_attention\n  WHERE state IN ('uncertain','failed') AND acknowledged_at IS NULL AND finished_at >= ?\n    AND NOT (kind = 'raw_paste' AND source_key LIKE 'schedule:%')\n  ORDER BY finished_at DESC LIMIT ?";
+/** A silent schedule's raw paste (fleet-manager admits it as `raw_paste` under a `schedule:` source key). */
+export declare function isSilentScheduleDelivery(row: {
+    kind: string;
+    sourceKey: string | null;
+}): boolean;
 export interface NeedsAttentionDelivery {
     deliveryId: string;
     state: "uncertain" | "failed";
@@ -239,6 +274,8 @@ export declare class DeliveryOutbox extends EventEmitter {
     readonly managerBootId: string;
     constructor(dbPath: string, managerBootId?: string);
     private initialize;
+    /** SQLite cannot widen a CHECK with ADD COLUMN; preserve all old rows in one transaction. */
+    private migrateReplyObligationExpiry;
     /**
      * #926: a delivered `requires_reply` request opens (or, asked again,
      * re-opens) the owner's obligation. Runs inside the delivered transition.
@@ -251,15 +288,22 @@ export declare class DeliveryOutbox extends EventEmitter {
     /**
      * #926 safety net 1: remind an owner that has not answered. `turn-ended`
      * reminds once per ask, after the grace (a reply seconds after the ask is
-     * normal); `restart` reminds once per restart, because the interrupted turn
-     * does not resume on its own. Marked in the same transaction as the notice.
+     * normal); `restart` batches once per daemon boot, because the interrupted
+     * turn does not resume on its own. Marked in the same transaction as the notice.
      */
     remindReplyObligations(ownerInstance: string, opts: {
         now?: Date;
         graceMs: number;
         reason: "turn-ended" | "restart";
         since?: Date;
+        restartId?: string;
     }): number;
+    private recordReplyRestart;
+    /** Expiry is terminal for this ask; a later delivered re-ask can reopen the same tuple. */
+    expireReplyObligations(opts?: {
+        now?: Date;
+        ttlMs?: number;
+    }): ReplyObligation[];
     /**
      * #926 safety net 2 (poll-on-timeout, in code): tell the requester once when
      * the owner is not working and nothing has come back for `overdueMs` since
@@ -277,8 +321,15 @@ export declare class DeliveryOutbox extends EventEmitter {
      * so it still arrives when the target is down right now (a General that the
      * same broken CLI stopped). `sourceKey` makes it idempotent: the same key is
      * admitted once. Returns whether it was newly admitted.
+     *
+     * `place` (#1823) addresses it to a chat: the notice is about something there (a poll's results), so the instance's
+     * answer goes there too. Without it the notice belongs to no chat.
      */
-    admitSystemNotice(target: string, sourceKey: string, content: string, now?: Date): boolean;
+    admitSystemNotice(target: string, sourceKey: string, content: string, now?: Date, place?: {
+        chatId: string;
+        threadId?: string;
+        adapterId?: string;
+    }): boolean;
     /** The owner's open obligations, oldest first (#926). */
     openReplyObligations(ownerInstance: string): ReplyObligation[];
     getReplyObligation(correlationId: string, requesterInstance: string, ownerInstance: string): ReplyObligation | undefined;
@@ -291,6 +342,17 @@ export declare class DeliveryOutbox extends EventEmitter {
         inserted: boolean;
     };
     get(deliveryId: string): OutboxDelivery | undefined;
+    createHumanReceipt(input: {
+        targetInstance: string;
+        originalBody: string;
+        origin: HumanOrigin;
+        inputKind: string;
+        managerBootId: string;
+    }): HumanReceiptRow;
+    markHumanReceiptUncertain(id: string, target: string): void;
+    getHumanReceipt(id: string): HumanReceiptRow | undefined;
+    bindHumanReceipt(id: string, target: string, ownerKey: string, wire: string, managerBootId: string): HumanReceiptRow;
+    settleHumanReceipt(id: string, target: string, ownerKey: string, proof: unknown, currentOwnerKey: string | null): boolean;
     getByOperation(sourceInstance: string, operationId: string): OutboxDelivery[];
     /**
      * Query only rows owned by the authenticated instance as source or target.