@songsid/agend 2.1.7-beta.4 → 2.1.7-beta.6

package/dist/delivery-outbox.d.ts

@@ -1,14 +1,16 @@
 import { EventEmitter } from "node:events";
+import type { QueueResumePolicy } from "./delivery-queue-evidence.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 interface DaemonDeliveryPort {
-    begin(deliveryId: string, targetBootId: string, attemptNo: number): "begun" | "duplicate" | "stale";
+    begin(deliveryId: string, targetBootId: string, attemptNo: number, evidence?: DeliveryAttemptEvidence): "begun" | "duplicate" | "stale";
+    markEnterStarted(deliveryId: string, targetBootId: string, attemptNo: number): boolean;
     abort(deliveryId: string, targetBootId: string, attemptNo: number, reason: string): boolean;
     complete(deliveryId: string, targetBootId: string, attemptNo: number, outcome: "delivered" | "failed" | "uncertain", evidence?: string): boolean;
     retryBeforeBegin(deliveryId: string, targetBootId: string, attemptNo: number, reason: string, delayMs?: number): boolean;
 }
-export type OutboxState = "queued" | "delivering" | "submission_started" | "retry_wait" | "delivered" | "failed" | "uncertain" | "cancelled";
+export type OutboxState = "queued" | "delivering" | "submission_started" | "reconciliation_pending" | "retry_wait" | "delivered" | "failed" | "uncertain" | "cancelled";
 export interface NewOutboxDelivery {
     operationId: string;
     sourceKey: string;
@@ -39,6 +41,143 @@ export interface OutboxDelivery {
     responseDeliveredAt: string | null;
     nextAttemptAt: string | null;
     lastError: string | null;
+    reconciliationPending: boolean;
+}
+export type DeliveryStatusSelector = {
+    deliveryId: string;
+    operationId?: never;
+    correlationId?: never;
+    messageId?: never;
+    limit?: never;
+    cursor?: never;
+} | {
+    operationId: string;
+    deliveryId?: never;
+    correlationId?: never;
+    messageId?: never;
+    limit?: number;
+    cursor?: string;
+} | {
+    correlationId: string;
+    deliveryId?: never;
+    operationId?: never;
+    messageId?: never;
+    limit?: number;
+    cursor?: string;
+}
+/**
+ * #856: the `message_id` a receiver sees in the envelope header. Lets an
+ * agent check that a peer message it is about to act on was really
+ * delivered by the fleet — a model can "see" one nobody sent.
+ */
+ | {
+    messageId: string;
+    deliveryId?: never;
+    operationId?: never;
+    correlationId?: never;
+    limit?: number;
+    cursor?: string;
+};
+/** The one mapping from validated tool/CLI arguments to a selector. */
+export declare function deliveryStatusSelector(args: {
+    delivery_id?: string;
+    operation_id?: string;
+    correlation_id?: string;
+    message_id?: string;
+    limit?: number;
+    cursor?: string;
+}): DeliveryStatusSelector;
+/** sha256 of a delivered text, as hex. The same function hashes admission and paste. */
+export declare function deliveryContentDigest(text: string): string;
+/** #926 reminders and overdue notices; never themselves the subject of a failure notice. */
+export declare const REPLY_OBLIGATION_NOTICE_KIND = "reply_obligation_notice";
+export interface DeliveryStatusItem {
+    delivery_id: string;
+    operation_id: string;
+    correlation_id: string | null;
+    source_instance: string;
+    target_instance: string;
+    kind: string;
+    state: OutboxState;
+    attempt_no: number;
+    created_at: string;
+    updated_at: string;
+    status_summary: string;
+    error_summary: string | null;
+    safe_to_retry: boolean;
+    /** Fleet message ID of the delivered envelope, when it had one. */
+    message_id: string | null;
+    /** sha256 of the delivered text as admitted (#856). */
+    content_sha256: string | null;
+    /**
+     * The text as admitted — only on a `message_id` query by the row's own
+     * source or target: the caller already sent or received it, and verifying
+     * a value (a SHA, a PR number) needs the text, not just its digest. Every
+     * other query, and operator reads, stay redacted as before (#982).
+     */
+    content?: string | null;
+    /** #926: the reply this request is owed, when it asked for one. */
+    reply_obligation?: {
+        state: "open" | "answered";
+        opened_at: string;
+        last_asked_at: string;
+        nudged_at: string | null;
+        overdue_notified_at: string | null;
+        answered_at: string | null;
+    } | 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.
+ */
+export interface ReplyObligation {
+    correlationId: string;
+    requesterInstance: string;
+    ownerInstance: string;
+    requestDeliveryId: string;
+    openedAt: string;
+    lastAskedAt: string;
+    state: "open" | "answered";
+    nudgedAt: string | null;
+    overdueNotifiedAt: string | null;
+    answeredAt: string | null;
+    answeredDeliveryId: string | null;
+}
+export interface DeliveryStatusPage {
+    items: DeliveryStatusItem[];
+    next_cursor: string | null;
+}
+export type DurableSubmissionMode = "idle_submit" | "native_queue_handoff" | "steer" | "raw_paste";
+/** Checkpoint committed with begin, before any pane paste can occur. */
+export interface DeliveryAttemptEvidence {
+    backend: string;
+    backendVersion?: string | null;
+    windowId: string | null;
+    transcriptPath: string | null;
+    transcriptOffset: number | null;
+    transcriptSessionId: string | null;
+    submissionMode: DurableSubmissionMode;
+    queueResumePolicy?: QueueResumePolicy;
+    /** sha256 of the text the target daemon received, before formatting (#856). */
+    pastedContentSha256?: string | null;
+    /** sha256 of the exact string handed to the pane write (#856). */
+    pastedBytesSha256?: string | null;
+}
+export interface DeliveryReconciliationCandidate extends OutboxDelivery {
+    attempt: {
+        targetDaemonBootId: string;
+        attemptNo: number;
+        backend: string | null;
+        backendVersion: string | null;
+        windowId: string | null;
+        transcriptPath: string | null;
+        transcriptOffset: number | null;
+        transcriptSessionId: string | null;
+        submissionMode: DurableSubmissionMode | null;
+        queueResumePolicy: QueueResumePolicy | null;
+        enterStartedAt: string | null;
+    };
 }
 export interface ClaimedOutboxDelivery extends OutboxDelivery {
     targetDaemonBootId: string;
@@ -48,6 +187,45 @@ export declare class DeliveryOutbox extends EventEmitter {
     private readonly db;
     readonly managerBootId: string;
     constructor(dbPath: string, managerBootId?: string);
+    /**
+     * #926: a delivered `requires_reply` request opens (or, asked again,
+     * re-opens) the owner's obligation. Runs inside the delivered transition.
+     * An answer admitted before the request finished its submission proof —
+     * an owner can reply while the daemon is still confirming — counts.
+     */
+    private openReplyObligation;
+    /** The owner's message back to the requester on the same correlation_id answers it — at admission. */
+    private answerReplyObligation;
+    /**
+     * #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.
+     */
+    remindReplyObligations(ownerInstance: string, opts: {
+        now?: Date;
+        graceMs: number;
+        reason: "turn-ended" | "restart";
+        since?: Date;
+    }): number;
+    /**
+     * #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
+     * the last ask or reminder. A still-working owner is never reported.
+     */
+    notifyOverdueReplyObligations(opts: {
+        now?: Date;
+        overdueMs: number;
+        ownerIdle: (owner: string) => boolean;
+    }): number;
+    /** A system notice as a durable row, like #929's outcome notices; the key makes it idempotent. */
+    private insertReplyObligationNotice;
+    /** The owner's open obligations, oldest first (#926). */
+    openReplyObligations(ownerInstance: string): ReplyObligation[];
+    getReplyObligation(correlationId: string, requesterInstance: string, ownerInstance: string): ReplyObligation | undefined;
+    /** Rows admitted before #856 get the same message_id / digest a new row would. */
+    private backfillMessageEvidence;
+    private ensureColumn;
     /** Commit admission before returning success. Duplicate source keys return their original row. */
     admit(input: NewOutboxDelivery): {
         delivery: OutboxDelivery;
@@ -55,19 +233,29 @@ export declare class DeliveryOutbox extends EventEmitter {
     };
     get(deliveryId: string): OutboxDelivery | undefined;
     getByOperation(sourceInstance: string, operationId: string): OutboxDelivery[];
+    /**
+     * Query only rows owned by the authenticated instance as source or target.
+     * This method accepts caller identity separately from user arguments so a
+     * caller cannot widen its own visibility with a forged source name.
+     */
+    queryStatusForInstance(callerInstance: string, selector: DeliveryStatusSelector): DeliveryStatusPage;
+    /** Open the existing outbox without migrations or writes for the operator CLI. */
+    static queryStatusReadOnly(dbPath: string, selector: DeliveryStatusSelector): DeliveryStatusPage;
     listPending(): OutboxDelivery[];
     nextRetryAt(): string | null;
     /** Claim the earliest eligible target row; one caller owns each target lane. */
     claimNext(managerBootId: string, targetBootIdFor: (target: string) => string | null, blockedTargets: ReadonlySet<string>): ClaimedOutboxDelivery | undefined;
     /** Idempotent begin permit, committed immediately before the pane side effect. */
-    begin(deliveryId: string, targetBootId: string, attemptNo: number): "begun" | "duplicate" | "stale";
+    begin(deliveryId: string, targetBootId: string, attemptNo: number, evidence?: DeliveryAttemptEvidence): "begun" | "duplicate" | "stale";
+    /** Write-ahead fence: commit before tmux is allowed to receive Enter. */
+    markEnterStarted(deliveryId: string, targetBootId: string, attemptNo: number): boolean;
     /** Safe only when the caller can prove no pane write occurred for this attempt. */
     abort(deliveryId: string, targetBootId: string, attemptNo: number, reason: string): boolean;
     complete(deliveryId: string, targetBootId: string, attemptNo: number, outcome: "delivered" | "failed" | "uncertain", evidence?: string): boolean;
     /** Transient pre-submit failure: state is retryable and the same row keeps its FIFO position. */
     retryBeforeBegin(deliveryId: string, targetBootId: string, attemptNo: number, reason: string, delayMs?: number): boolean;
     failBeforeBegin(deliveryId: string, reason: string): boolean;
-    /** Expire unavailable/pre-submit rows instead of leaving them queued forever. */
+    /** Bound both unavailable rows and unresolved reconciliation without stealing a live lease. */
     expireStale(nowMs?: number, maxAgeMs?: number): number;
     /** Next queued/retry expiry for bounded maintenance scheduling. */
     nextExpiryAt(): string | null;
@@ -75,14 +263,19 @@ export declare class DeliveryOutbox extends EventEmitter {
     /** Old process leases are recoverable; an old submission attempt needs evidence reconciliation. */
     recoverForBoot(managerBootId: string): {
         queued: number;
-        uncertain: number;
+        reconciliationPending: number;
     };
     /** Atomically create a post-restart notice for an accepted operation whose response was not recorded. */
     admitPostRestartOutcomeNotice(parent: OutboxDelivery, currentSourceBootId: string): OutboxDelivery | undefined;
     recoverTargetGeneration(targetInstance: string, currentTargetBootId: string): {
         queued: number;
-        uncertain: number;
+        reconciliationPending: number;
     };
+    /** Fence in-flight writes before an in-process target stop begins. */
+    markTargetReconciliationPending(targetInstance: string, targetBootId: string): number;
+    getReconciliationCandidates(targetInstance: string): DeliveryReconciliationCandidate[];
+    /** Atomically settle one old attempt using only its boot/attempt fence. */
+    reconcileAttempt(deliveryId: string, targetBootId: string, attemptNo: number, outcome: "delivered" | "retry_wait" | "uncertain", evidence: string): boolean;
     getUnansweredAccepted(sourceInstance: string, currentBootId: string): OutboxDelivery[];
     close(): void;
     /** Must be called inside the same SQLite transaction as the terminal transition. */