commandmate 0.49.2 → 0.50.0

package/dist/server/src/lib/db/relay-bind-db-delivery.js

@@ -0,0 +1,223 @@
+"use strict";
+/**
+ * The relay ledger's delivery attempts (Issue #4064, v63), split out of
+ * `relay-bind-db` (Issue #4095).
+ *
+ * `relay-bind-db` re-exports every public name here. This module imports only
+ * `relay-bind-db-base`.
+ *
+ * @module lib/db/relay-bind-db-delivery
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RELAY_DELIVERY_SERVER_RESTARTED = void 0;
+exports.claimRelayPayloadDelivery = claimRelayPayloadDelivery;
+exports.isCurrentRelayPayloadAttempt = isCurrentRelayPayloadAttempt;
+exports.completeRelayPayloadDelivery = completeRelayPayloadDelivery;
+exports.endRelayPayloadAttempt = endRelayPayloadAttempt;
+exports.releaseRelayPayloadDelivery = releaseRelayPayloadDelivery;
+exports.holdRelayPayloadDelivery = holdRelayPayloadDelivery;
+exports.recoverInterruptedRelayDeliveries = recoverInterruptedRelayDeliveries;
+exports.recoverInterruptedRelayDeliveryRefs = recoverInterruptedRelayDeliveryRefs;
+exports.listRelaysWithDeliveryHold = listRelaysWithDeliveryHold;
+const relay_bind_db_base_1 = require("./relay-bind-db-base");
+/**
+ * Take one payload for delivery, durably, before its first key (Issue #4064).
+ *
+ * One conditional UPDATE on the payload the caller read — its id, kind and
+ * body — and on it not being taken already. Only the caller this answers for
+ * may send it; a payload replaced, delivered, held or taken meanwhile answers
+ * null and nothing is written. A throw (the database refused the write) means
+ * the same: do not send.
+ *
+ * @returns The payload's id (minted for a row that had none), or null
+ */
+function claimRelayPayloadDelivery(db, input) {
+    const now = input.now ?? Date.now();
+    const payloadId = input.payloadId ?? input.mintPayloadId;
+    const result = db
+        .prepare(`
+      UPDATE session_relays
+      SET delivery_state = 'attempting', delivery_attempt_id = ?, delivery_owner = ?,
+          delivery_reason = NULL, delivery_at = ?, payload_id = ?
+      WHERE id = ? AND pending_kind = ? AND pending_body = ? AND payload_id IS ?
+        AND delivery_state IS NULL
+    `)
+        .run(input.attemptId, input.owner, now, payloadId, input.relayId, input.kind, input.body, input.payloadId);
+    return result.changes === 1 ? payloadId : null;
+}
+/**
+ * Whether `ref` is still the attempt in progress on the row: the same payload,
+ * the same attempt id, and still `attempting` (Issue #4082).
+ *
+ * Every result writer asks this BEFORE its first side effect. An attempt held
+ * as `uncertain` meanwhile (another boot's recovery), resolved, or replaced by
+ * a retry's new attempt is stale: its late success or failure must not close
+ * the relay, empty a payload, promote a reply or end the newer attempt.
+ */
+function isCurrentRelayPayloadAttempt(db, ref) {
+    const row = db
+        .prepare(`
+      SELECT 1 AS hit FROM session_relays
+      WHERE id = ? AND payload_id = ? AND delivery_attempt_id = ? AND delivery_state = 'attempting'
+    `)
+        .get(ref.relayId, ref.payloadId, ref.attemptId);
+    return row !== undefined;
+}
+/**
+ * The attempt delivered its payload: empty the slot (if it still holds that
+ * payload) and drop the attempt, in one transaction (Issue #4064).
+ *
+ * Issue #4082: only while the attempt is still the one in progress
+ * ({@link isCurrentRelayPayloadAttempt}); a stale attempt writes nothing.
+ *
+ * @returns Whether the attempt was still the one on the row
+ */
+function completeRelayPayloadDelivery(db, ref) {
+    const now = ref.now ?? Date.now();
+    return db.transaction(() => {
+        if (!isCurrentRelayPayloadAttempt(db, ref))
+            return false;
+        return endRelayPayloadAttempt(db, { ...ref, now });
+    })();
+}
+/**
+ * The writes behind {@link completeRelayPayloadDelivery}, without its check:
+ * empty the slot if it still holds the payload, and end the attempt. For a
+ * caller that checked the attempt itself, in its own transaction, before a
+ * write that empties the payload (the reply's close).
+ *
+ * @returns Whether the attempt was ended
+ */
+function endRelayPayloadAttempt(db, ref) {
+    const now = ref.now ?? Date.now();
+    db.prepare(`
+    UPDATE session_relays
+    SET pending_kind = NULL, pending_body = NULL, payload_id = NULL, updated_at = ?
+    WHERE id = ? AND payload_id = ? AND delivery_attempt_id = ? AND delivery_state = 'attempting'
+  `).run(now, ref.relayId, ref.payloadId, ref.attemptId);
+    const result = db
+        .prepare(`
+      UPDATE session_relays
+      SET delivery_state = NULL, delivery_attempt_id = NULL, delivery_owner = NULL,
+          delivery_reason = NULL, delivery_at = NULL, updated_at = ?
+      WHERE id = ? AND delivery_attempt_id = ? AND delivery_state = 'attempting'
+    `)
+        .run(now, ref.relayId, ref.attemptId);
+    return result.changes === 1;
+}
+/**
+ * The attempt is known not to have sent (`not-sent`, `prompt_waiting`): the
+ * payload is queued again (Issue #4064).
+ *
+ * @returns Whether the attempt was still the one on the row
+ */
+function releaseRelayPayloadDelivery(db, ref) {
+    const result = db
+        .prepare(`
+      UPDATE session_relays
+      SET delivery_state = NULL, delivery_attempt_id = NULL, delivery_owner = NULL,
+          delivery_reason = NULL, delivery_at = NULL, updated_at = ?
+      WHERE id = ? AND payload_id = ? AND delivery_attempt_id = ? AND delivery_state = 'attempting'
+    `)
+        .run(ref.now ?? Date.now(), ref.relayId, ref.payloadId, ref.attemptId);
+    return result.changes === 1;
+}
+/**
+ * Whether the attempt reached A is not known: hold the payload as `uncertain`,
+ * with the reason (Issue #4064). It stays in the slot — readable, and blocking
+ * the relay's later deliveries — and is never sent again automatically.
+ *
+ * @returns Whether the attempt was still the one on the row
+ */
+function holdRelayPayloadDelivery(db, ref) {
+    const now = ref.now ?? Date.now();
+    const result = db
+        .prepare(`
+      UPDATE session_relays
+      SET delivery_state = 'uncertain', delivery_reason = ?, delivery_at = ?, updated_at = ?
+      WHERE id = ? AND payload_id = ? AND delivery_attempt_id = ? AND delivery_state = 'attempting'
+    `)
+        .run(ref.reason, now, now, ref.relayId, ref.payloadId, ref.attemptId);
+    return result.changes === 1;
+}
+/** {@link recoverInterruptedRelayDeliveries}' reason. */
+exports.RELAY_DELIVERY_SERVER_RESTARTED = 'server-restarted';
+/**
+ * An attempt another boot left `attempting` stopped somewhere between its
+ * claim and its result: hold it as `uncertain` (Issue #4064). Every relay —
+ * legacy or bound, open or closed — and every kind. A payload that was in fact
+ * never typed (the server stopped right after the claim) is held too; that is
+ * the price of never typing one twice.
+ *
+ * Safe to run again: this boot's own attempts are not touched.
+ *
+ * @returns How many were held
+ */
+function recoverInterruptedRelayDeliveries(db, boot, now = Date.now()) {
+    return recoverInterruptedRelayDeliveryRefs(db, boot, now).length;
+}
+/**
+ * {@link recoverInterruptedRelayDeliveries}, answering WHICH attempts this call
+ * moved to `uncertain` (Issue #4082): the relay, payload and attempt of each
+ * row whose guarded write took, so the requester can be told about exactly
+ * those — not a row another boot held first, not one already `uncertain`, not
+ * this boot's own `attempting`.
+ *
+ * One transaction: the rows are read and each is moved under its own attempt
+ * id, so a row resolved or retried between the read and the write is not
+ * reported.
+ */
+function recoverInterruptedRelayDeliveryRefs(db, boot, now = Date.now()) {
+    return db.transaction(() => {
+        const rows = db
+            .prepare(`
+        SELECT id, payload_id, delivery_attempt_id FROM session_relays
+        WHERE delivery_state = 'attempting' AND (delivery_owner IS NULL OR delivery_owner <> ?)
+      `)
+            .all(boot);
+        const held = [];
+        const hold = db.prepare(`
+      UPDATE session_relays
+      SET delivery_state = 'uncertain', delivery_reason = ?, delivery_at = ?, updated_at = ?
+      WHERE id = ? AND delivery_attempt_id IS ? AND delivery_state = 'attempting'
+        AND (delivery_owner IS NULL OR delivery_owner <> ?)
+    `);
+        for (const row of rows) {
+            const result = hold.run(exports.RELAY_DELIVERY_SERVER_RESTARTED, now, now, row.id, row.delivery_attempt_id, boot);
+            if (result.changes !== 1)
+                continue;
+            // A row without the ids is held all the same, and simply not reported:
+            // a line could not name what to resolve.
+            if (row.payload_id === null || row.delivery_attempt_id === null)
+                continue;
+            held.push({ relayId: row.id, payloadId: row.payload_id, attemptId: row.delivery_attempt_id, now });
+        }
+        return held;
+    })();
+}
+/**
+ * Every relay, open or closed, whose payload is under a delivery hold
+ * (Issue #4064), oldest first. With an endpoint, those with it at either end;
+ * with a worktree only, those with that worktree at either end.
+ */
+function listRelaysWithDeliveryHold(db, scope = {}) {
+    const clauses = ['delivery_state IS NOT NULL'];
+    const params = [];
+    if (scope.endpoint) {
+        clauses.push('((from_worktree_id = ? AND from_instance_id = ?) OR (to_worktree_id = ? AND to_instance_id = ?))');
+        const { worktreeId, instanceId } = scope.endpoint;
+        params.push(worktreeId, instanceId, worktreeId, instanceId);
+    }
+    else if (scope.worktreeId) {
+        clauses.push('(from_worktree_id = ? OR to_worktree_id = ?)');
+        params.push(scope.worktreeId, scope.worktreeId);
+    }
+    const rows = db
+        .prepare(`
+      SELECT ${relay_bind_db_base_1.RELAY_COLUMNS} FROM session_relays
+      WHERE ${clauses.join(' AND ')}
+      ORDER BY created_at ASC
+    `)
+        .all(...params);
+    return rows.map(relay_bind_db_base_1.mapRelay);
+}

package/dist/server/src/lib/db/relay-bind-db-pending.js

@@ -0,0 +1,183 @@
+"use strict";
+/**
+ * The relay ledger's second slot — a reply waiting behind a prompt notice —
+ * and the held count, split out of `relay-bind-db` (Issue #4095).
+ *
+ * `relay-bind-db` re-exports every public name here. This module imports only
+ * `relay-bind-db-base`.
+ *
+ * @module lib/db/relay-bind-db-pending
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setRelayPendingReply = setRelayPendingReply;
+exports.replaceRelayPromptWithReply = replaceRelayPromptWithReply;
+exports.promoteRelayPendingReply = promoteRelayPendingReply;
+exports.replaceRelayPromptWithPendingReply = replaceRelayPromptWithPendingReply;
+exports.clearRelayPendingReply = clearRelayPendingReply;
+exports.clearRelayPendingReplyUnlessHeld = clearRelayPendingReplyUnlessHeld;
+exports.countHeldRelays = countHeldRelays;
+const types_1 = require("../../lib/relay/types");
+const relay_bind_db_base_1 = require("./relay-bind-db-base");
+/**
+ * Put a reply in the second slot while a prompt notice holds the first.
+ *
+ * Only one: the first reply to finish is the one kept.
+ */
+function setRelayPendingReply(db, id, reply, now = Date.now()) {
+    const result = db
+        .prepare(`
+      UPDATE session_relays SET pending_reply = ?, updated_at = ?
+      WHERE id = ? AND pending_kind = 'prompt' AND pending_reply IS NULL
+        AND state IN (${relay_bind_db_base_1.OPEN_STATE_PLACEHOLDERS})
+    `)
+        .run(JSON.stringify(reply), now, id, ...types_1.OPEN_RELAY_STATES);
+    return result.changes === 1;
+}
+/**
+ * Replace an unclaimed prompt notice with the reply that made it moot.
+ *
+ * Conditional on the notice's own payload id, so a notice that was replaced or
+ * delivered meanwhile is not overwritten — and (Issue #4064) on the notice not
+ * being under a delivery hold: one whose delivery may have reached A is kept,
+ * and the reply waits in the second slot behind it.
+ *
+ * Issue #4082: a reply already waiting in the second slot (it finished while
+ * the notice was held, and the hold was then retried) goes first — the first
+ * reply to finish is the one kept, as {@link setRelayPendingReply} keeps it —
+ * and the given one is dropped. Either way the second slot is emptied in the
+ * same write, so no older reply is left behind a closed relay. An unreadable
+ * waiting reply is dropped and the given one takes the slot.
+ *
+ * @returns Which reply took the first slot, or null when nothing was replaced
+ */
+function replaceRelayPromptWithReply(db, id, promptPayloadId, reply, now = Date.now()) {
+    return db.transaction(() => {
+        const row = db
+            .prepare(`
+        SELECT pending_reply FROM session_relays
+        WHERE id = ? AND pending_kind = 'prompt' AND payload_id IS ? AND delivery_state IS NULL
+          AND state IN (${relay_bind_db_base_1.OPEN_STATE_PLACEHOLDERS})
+      `)
+            .get(id, promptPayloadId, ...types_1.OPEN_RELAY_STATES);
+        if (!row)
+            return null;
+        const waiting = row.pending_reply === null ? null : (0, relay_bind_db_base_1.parseJson)(row.pending_reply, null);
+        const taken = waiting ?? reply;
+        db.prepare(`
+      UPDATE session_relays
+      SET pending_kind = 'reply', pending_body = ?, payload_id = ?, overlap = ?,
+          pending_reply = NULL, updated_at = ?
+      WHERE id = ?
+    `).run(taken.body, taken.payloadId, taken.overlap, now, id);
+        return waiting ? 'waiting-reply' : 'reply';
+    })();
+}
+/**
+ * Move the second slot into the first once the prompt notice is gone.
+ *
+ * Atomic: the reply becomes the pending payload and leaves `pending_reply` in
+ * one write, so the pump finds it and nothing finds it twice.
+ */
+function promoteRelayPendingReply(db, id, now = Date.now()) {
+    return db.transaction(() => {
+        const row = db
+            .prepare(`
+        SELECT pending_reply FROM session_relays
+        WHERE id = ? AND pending_kind IS NULL AND pending_reply IS NOT NULL
+          AND state IN (${relay_bind_db_base_1.OPEN_STATE_PLACEHOLDERS})
+      `)
+            .get(id, ...types_1.OPEN_RELAY_STATES);
+        if (!row)
+            return false;
+        const reply = (0, relay_bind_db_base_1.parseJson)(row.pending_reply, null);
+        if (!reply) {
+            db.prepare('UPDATE session_relays SET pending_reply = NULL WHERE id = ?').run(id);
+            return false;
+        }
+        db.prepare(`
+      UPDATE session_relays
+      SET pending_kind = 'reply', pending_body = ?, payload_id = ?, overlap = ?,
+          pending_reply = NULL, updated_at = ?
+      WHERE id = ?
+    `).run(reply.body, reply.payloadId, reply.overlap, now, id);
+        return true;
+    })();
+}
+/**
+ * A prompt notice whose delivery did not go out, while a reply waits in the
+ * second slot: the reply takes the first slot in its place (Issue #3957).
+ *
+ * Conditional on the notice's own payload id, in one transaction, so a notice
+ * replaced meanwhile is left alone and the reply is not moved twice. Issue
+ * #4064: never a notice under a delivery hold.
+ */
+function replaceRelayPromptWithPendingReply(db, id, promptPayloadId, now = Date.now()) {
+    return db.transaction(() => {
+        const row = db
+            .prepare(`
+        SELECT pending_reply FROM session_relays
+        WHERE id = ? AND pending_kind = 'prompt' AND payload_id IS ? AND pending_reply IS NOT NULL
+          AND delivery_state IS NULL
+          AND state IN (${relay_bind_db_base_1.OPEN_STATE_PLACEHOLDERS})
+      `)
+            .get(id, promptPayloadId, ...types_1.OPEN_RELAY_STATES);
+        if (!row)
+            return false;
+        const reply = (0, relay_bind_db_base_1.parseJson)(row.pending_reply, null);
+        if (!reply)
+            return false;
+        db.prepare(`
+      UPDATE session_relays
+      SET pending_kind = 'reply', pending_body = ?, payload_id = ?, overlap = ?,
+          pending_reply = NULL, updated_at = ?
+      WHERE id = ?
+    `).run(reply.body, reply.payloadId, reply.overlap, now, id);
+        return true;
+    })();
+}
+/** Empty the second slot (an expiry or a cancel supersedes it). */
+function clearRelayPendingReply(db, id, now = Date.now()) {
+    db.prepare('UPDATE session_relays SET pending_reply = NULL, updated_at = ? WHERE id = ?').run(now, id);
+}
+/**
+ * Empty the second slot unless the first is under a delivery hold (Issue #4082).
+ *
+ * For the expiry sweep: a reply waiting behind a held notice is kept, so that
+ * settling the hold later decides what happens to it (a closed relay's waiting
+ * reply is then discarded explicitly, with a line in the requester's history).
+ * A cancel still empties it unconditionally ({@link clearRelayPendingReply}).
+ *
+ * @returns Whether the slot was emptied (false also when it was already empty)
+ */
+function clearRelayPendingReplyUnlessHeld(db, id, now = Date.now()) {
+    const result = db
+        .prepare(`
+      UPDATE session_relays SET pending_reply = NULL, updated_at = ?
+      WHERE id = ? AND pending_reply IS NOT NULL AND delivery_state IS NULL
+    `)
+        .run(now, id);
+    return result.changes === 1;
+}
+/**
+ * How many payloads are held as `uncertain` (Issue #4082): the held axis of
+ * the relay counts, apart from the per-state counts. Open relays and closed
+ * ones alike, one per row (a row holds at most one payload), `attempting`
+ * not included (it is still pending), and never narrowed by a period — a hold
+ * is something to settle now, however old its relay.
+ */
+function countHeldRelays(db, scope = {}) {
+    const clauses = ["delivery_state = 'uncertain'"];
+    const params = [];
+    if (scope.worktreeId && scope.instanceId) {
+        clauses.push('((from_worktree_id = ? AND from_instance_id = ?) OR (to_worktree_id = ? AND to_instance_id = ?))');
+        params.push(scope.worktreeId, scope.instanceId, scope.worktreeId, scope.instanceId);
+    }
+    else if (scope.worktreeId) {
+        clauses.push('(from_worktree_id = ? OR to_worktree_id = ?)');
+        params.push(scope.worktreeId, scope.worktreeId);
+    }
+    const row = db
+        .prepare(`SELECT COUNT(*) AS n FROM session_relays WHERE ${clauses.join(' AND ')}`)
+        .get(...params);
+    return row.n;
+}