commandmate 0.31.3 → 0.32.0

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

@@ -0,0 +1,400 @@
+"use strict";
+/**
+ * Getting B's answer into A's composer (Issue #2377).
+ *
+ * ## Two moments, one path
+ *
+ * Something has to notice that B finished. Two things do, and they are the two
+ * `lib/polling/structured-history-gate`'s header describes:
+ *
+ *  - **Tools with a transcript** (claude, codex, antigravity, command-code, and
+ *    opencode over its stream). Their reader answers `true` only for a turn the
+ *    agent has CLOSED, which is a stronger statement than any amount of quiet,
+ *    so the capture is delivered as soon as it lands. Both triggers of that
+ *    capture — the Stop hook and the poller — reach the same function, which is
+ *    why this module needs one hook and not two.
+ *  - **Tools without one** (copilot, gemini, vibe-local). What a finished turn
+ *    leaves behind is the poller's copy of the SCREEN, judged by a string
+ *    analysis of a frame that may still be being drawn. The Issue asks for
+ *    「完了検知 + 数秒の静穏」, and {@link RELAY_SCRAPE_QUIET_MS} is that quiet:
+ *    the newest row is re-read after the delay and only delivered once it has
+ *    stopped moving.
+ *
+ * ## Deciding is not delivering
+ *
+ * A finished turn produces a STASH, not a send. A is frequently mid-turn when B
+ * finishes, and typing into a running composer interrupts it — so the body waits
+ * in the ledger (durable, survives a restart) and the pump retries it whenever
+ * A is next able to take it. That separation is also what makes the double
+ * detection harmless: `stashRelayPayload` is guarded on `pending_kind IS NULL`,
+ * so two producers finding one turn cost one delivery.
+ *
+ * Nothing here throws. Every entry point is called from a poller tick, a hook
+ * receiver or a timer, and in all three a failure must cost the relay, never the
+ * caller.
+ *
+ * @module lib/relay/relay-delivery
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetRelayDeliveryState = resetRelayDeliveryState;
+exports.findWorkerReply = findWorkerReply;
+exports.notifyRelayTurnCompleted = notifyRelayTurnCompleted;
+exports.notifyRelayPromptWaiting = notifyRelayPromptWaiting;
+exports.sweepExpiredRelays = sweepExpiredRelays;
+exports.pumpRelayDeliveries = pumpRelayDeliveries;
+exports.runRelayMaintenanceTick = runRelayMaintenanceTick;
+const db_instance_1 = require("../../lib/db/db-instance");
+const relay_db_1 = require("../../lib/db/relay-db");
+const chat_db_1 = require("../../lib/db/chat-db");
+const models_1 = require("../../types/models");
+const model_change_push_notifier_1 = require("../../lib/push/model-change-push-notifier");
+const send_user_message_1 = require("../../lib/session/send-user-message");
+const relay_messages_1 = require("../../lib/relay/relay-messages");
+const relay_policy_1 = require("../../lib/relay/relay-policy");
+const relay_readiness_1 = require("../../lib/relay/relay-readiness");
+const relay_session_ref_1 = require("../../lib/relay/relay-session-ref");
+const relay_system_line_1 = require("../../lib/relay/relay-system-line");
+const logger_1 = require("../../lib/logger");
+const logger = (0, logger_1.createLogger)('relay-delivery');
+/**
+ * How many assistant rows back the reply is looked for.
+ *
+ * A turn can write several rows (a narration then a summary), and the relay
+ * wants the last one that is actually the agent talking. Bounded because an
+ * unbounded read of a long-lived worktree's history is a large query for one
+ * line of answer.
+ */
+const REPLY_LOOKBACK_MESSAGES = 40;
+/** How many times the scrape path re-reads before it gives up on stability. */
+const SCRAPE_STABILITY_ATTEMPTS = 3;
+const inFlight = (globalThis.__relayDeliveryInFlight ??= new Set());
+/** Forget every in-flight delivery. Test seam. */
+function resetRelayDeliveryState() {
+    inFlight.clear();
+    globalThis.__relayPumpRunning = false;
+}
+function senderLabel(db, relay) {
+    const worker = (0, relay_session_ref_1.resolveRelaySession)(db, relay.to);
+    return { alias: worker.alias, worktreeId: worker.worktreeId };
+}
+/**
+ * The newest thing B actually said, at or after `since`.
+ *
+ * Three kinds of row are stepped over, and each exclusion is load-bearing:
+ * prompt rows (a question is not an answer, and the confirmation notice is a
+ * separate delivery), relay SYSTEM rows (this session's own transcript
+ * furniture — delivering "Reply from X" back to X is the smallest possible
+ * loop), and empty bodies.
+ */
+function findWorkerReply(db, worker, since) {
+    const messages = (0, chat_db_1.getMessages)(db, worker.worktreeId, {
+        limit: REPLY_LOOKBACK_MESSAGES,
+        cliToolId: worker.cliToolId,
+        instanceId: worker.instanceId,
+        matchResolvedInstance: true,
+    });
+    // `getMessages` answers newest-first, so the first candidate IS the newest.
+    for (const message of messages) {
+        if (message.role !== 'assistant')
+            continue;
+        if (message.messageType === 'prompt')
+            continue;
+        if (message.requestId?.startsWith(chat_db_1.RELAY_SYSTEM_REQUEST_ID_PREFIX))
+            continue;
+        if (message.content.trim() === '')
+            continue;
+        return message.timestamp.getTime() < since ? null : message;
+    }
+    return null;
+}
+/** The options of B's open dialog, in the shape the notice lists them. */
+function promptOptionsOf(message) {
+    const data = message.promptData;
+    if (!(0, models_1.isAnswerablePromptData)(data))
+        return [];
+    if (data.type === 'yes_no') {
+        return data.options.map((label) => ({ key: label, label }));
+    }
+    return data.options.map((option) => ({
+        key: String(option.number),
+        label: option.label,
+    }));
+}
+/**
+ * Stash B's finished reply against every relay that is waiting for it.
+ *
+ * @returns How many relays took a payload from this call
+ */
+function stashReplyForOpenRelays(db, worker, now) {
+    const relays = (0, relay_db_1.listOpenRelaysTo)(db, {
+        worktreeId: worker.worktreeId,
+        instanceId: worker.instanceId,
+    });
+    if (relays.length === 0)
+        return 0;
+    let stashed = 0;
+    for (const relay of relays) {
+        // `createdAt` and not "the last time we looked": a reply written BEFORE the
+        // relay existed answered somebody else's question, and delivering it would
+        // hand session A the previous turn — the exact failure a bare `capture`
+        // after a `wait` has always had.
+        const reply = findWorkerReply(db, worker, relay.createdAt);
+        if (!reply)
+            continue;
+        const body = (0, relay_messages_1.buildRelayReplyMessage)(senderLabel(db, relay), reply.content);
+        if ((0, relay_db_1.stashRelayPayload)(db, relay.id, 'reply', body, now))
+            stashed += 1;
+    }
+    return stashed;
+}
+/** Sleep, so the scrape path can wait out its quiet window. */
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/**
+ * B finished a turn. Deliver it, or arrange to.
+ *
+ * @param worker - The session that finished
+ * @param options.settled - True when the completion came from the agent's own
+ *   transcript, i.e. the turn is closed and no quiet window is needed
+ */
+async function notifyRelayTurnCompleted(worker, options) {
+    try {
+        const db = (0, db_instance_1.getDbInstance)();
+        const waiting = (0, relay_db_1.listOpenRelaysTo)(db, {
+            worktreeId: worker.worktreeId,
+            instanceId: worker.instanceId,
+        });
+        if (waiting.length === 0)
+            return;
+        if (options.settled) {
+            if (stashReplyForOpenRelays(db, worker, Date.now()) > 0)
+                void pumpRelayDeliveries();
+            return;
+        }
+        // The scrape path. The row that is newest now may be a frame mid-draw, so
+        // the delivery waits until the newest row stops changing — bounded, because
+        // an agent that keeps writing is an agent whose next completion will trigger
+        // this again anyway.
+        let previousId = null;
+        for (let attempt = 0; attempt < SCRAPE_STABILITY_ATTEMPTS; attempt += 1) {
+            const before = findWorkerReply(db, worker, 0);
+            previousId = before?.id ?? null;
+            await sleep(relay_policy_1.RELAY_SCRAPE_QUIET_MS);
+            const after = findWorkerReply(db, worker, 0);
+            if ((after?.id ?? null) === previousId) {
+                if (stashReplyForOpenRelays(db, worker, Date.now()) > 0)
+                    void pumpRelayDeliveries();
+                return;
+            }
+        }
+        logger.info('relay-scrape-never-settled', {
+            worktreeId: worker.worktreeId,
+            instanceId: worker.instanceId,
+            attempts: SCRAPE_STABILITY_ATTEMPTS,
+        });
+    }
+    catch (error) {
+        logger.warn('relay-turn-completed-failed', {
+            worktreeId: worker.worktreeId,
+            instanceId: worker.instanceId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * B stopped on a confirmation. Tell A, once per distinct dialog.
+ *
+ * The relay stays OPEN: answering the prompt lets B finish, and the reply is
+ * delivered from the `prompt` state. What changes is that A now knows why
+ * nothing has arrived, which is the whole difference between a delegation that
+ * is slow and one that is stuck.
+ */
+function notifyRelayPromptWaiting(worker) {
+    try {
+        const db = (0, db_instance_1.getDbInstance)();
+        const relays = (0, relay_db_1.listOpenRelaysTo)(db, {
+            worktreeId: worker.worktreeId,
+            instanceId: worker.instanceId,
+        });
+        if (relays.length === 0)
+            return;
+        const prompt = (0, chat_db_1.getLatestOpenPromptMessage)(db, worker.worktreeId, worker.cliToolId, worker.instanceId);
+        if (!prompt)
+            return;
+        const locale = (0, model_change_push_notifier_1.resolveReadersLocale)(db);
+        const options = promptOptionsOf(prompt);
+        const question = (0, models_1.isAnswerablePromptData)(prompt.promptData)
+            ? prompt.promptData.question
+            : (prompt.promptData?.question ?? prompt.content);
+        let stashed = 0;
+        for (const relay of relays) {
+            // The dialog's own row id is the signature: a wait that lasts twenty
+            // minutes is ONE row, so A is told once however many polls observe it.
+            if ((0, relay_db_1.getRelayPromptSignature)(db, relay.id) === prompt.id)
+                continue;
+            const body = (0, relay_messages_1.buildRelayPromptMessage)(locale, senderLabel(db, relay), {
+                question,
+                options,
+            });
+            if ((0, relay_db_1.stashRelayPayload)(db, relay.id, 'prompt', body)) {
+                // The signature is recorded HERE, before the delivery, and not after it:
+                // it is what stops every later poll of the same twenty-minute dialog
+                // from stashing the same notice again while A is still busy. The state
+                // moving to `prompt` is an OPEN state, so the reply that follows once
+                // the dialog is answered can still be stashed and delivered.
+                (0, relay_db_1.markRelayPromptNotified)(db, relay.id, prompt.id);
+                stashed += 1;
+            }
+        }
+        if (stashed > 0)
+            void pumpRelayDeliveries();
+    }
+    catch (error) {
+        logger.warn('relay-prompt-notify-failed', {
+            worktreeId: worker.worktreeId,
+            instanceId: worker.instanceId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Close every relay whose deadline has passed, telling A once.
+ *
+ * The stash goes in BEFORE the state changes, because `stashRelayPayload` only
+ * accepts an open relay — and the once-ness the Issue asks for comes from
+ * {@link markRelayExpired} being a guarded update, not from this ordering.
+ */
+function sweepExpiredRelays(db, now = Date.now()) {
+    let expired = 0;
+    for (const relay of (0, relay_db_1.listExpiredOpenRelays)(db, now)) {
+        try {
+            const locale = (0, model_change_push_notifier_1.resolveReadersLocale)(db);
+            // A payload that never went out is superseded by the expiry notice: A
+            // asked for an answer, and what they are getting is the news that there
+            // will not be one.
+            (0, relay_db_1.clearRelayPending)(db, relay.id, now);
+            const body = (0, relay_messages_1.buildRelayExpiredMessage)(locale, senderLabel(db, relay), relay.expiresAt - relay.createdAt);
+            const stashed = (0, relay_db_1.stashRelayPayload)(db, relay.id, 'expired', body, now);
+            if (!(0, relay_db_1.markRelayExpired)(db, relay.id, now)) {
+                if (stashed)
+                    (0, relay_db_1.clearRelayPending)(db, relay.id, now);
+                continue;
+            }
+            expired += 1;
+            (0, relay_system_line_1.writeRelaySystemLine)(db, relay.id, 'expired', (0, relay_session_ref_1.resolveRelaySession)(db, relay.from), (0, relay_session_ref_1.resolveRelaySession)(db, relay.to), now);
+        }
+        catch (error) {
+            logger.warn('relay-expire-failed', {
+                relayId: relay.id,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return expired;
+}
+/**
+ * Try to put one stashed payload into A's composer.
+ *
+ * The order — readiness, then send, then ledger — is deliberate. Marking first
+ * would lose the answer whenever the send failed, and the send path has real
+ * refusals in it (`prompt_waiting`, a session that went away mid-attempt). A
+ * repeat delivery is prevented by the in-flight set within a process and by
+ * `markRelayDelivered`'s guarded update across one, which is the idempotency the
+ * Issue asks for by name.
+ */
+async function deliverOne(db, relayId, kind, body) {
+    const relay = (0, relay_db_1.getRelayById)(db, relayId);
+    if (!relay)
+        return 'skipped';
+    const requester = (0, relay_session_ref_1.resolveRelaySession)(db, relay.from);
+    const hold = await (0, relay_readiness_1.findRelayHoldReason)(requester.worktreeId, requester.cliToolId, requester.instanceId);
+    if (hold) {
+        logger.debug('relay-delivery-held', { relayId, kind, reason: hold });
+        return 'held';
+    }
+    const result = await (0, send_user_message_1.sendUserMessage)(db, {
+        worktreeId: requester.worktreeId,
+        content: body,
+        cliToolId: requester.cliToolId,
+        instanceId: requester.instanceId,
+        messageType: 'relay',
+        // The pointer back at the ledger. Also `session_relays.sent_request_id` for
+        // a reply, which carries a UNIQUE index — so a second delivery of the same
+        // relay cannot be recorded even if one were somehow attempted.
+        requestId: kind === 'reply' ? (0, chat_db_1.relayRequestId)(relay.id) : undefined,
+    });
+    if (!result.ok) {
+        logger.info('relay-delivery-refused', { relayId, kind, stage: result.stage });
+        return result.stage === 'prompt_waiting' ? 'held' : 'failed';
+    }
+    const now = Date.now();
+    if (kind === 'reply') {
+        if (!(0, relay_db_1.markRelayDelivered)(db, relay.id, (0, chat_db_1.relayRequestId)(relay.id), now)) {
+            // Somebody closed it underneath us. The message is already in A's
+            // composer, which is the outcome that mattered.
+            logger.info('relay-already-closed-on-deliver', { relayId });
+        }
+        (0, relay_system_line_1.writeRelaySystemLine)(db, relay.id, 'replied', requester, (0, relay_session_ref_1.resolveRelaySession)(db, relay.to), now);
+    }
+    else if (kind === 'prompt') {
+        (0, relay_system_line_1.writeRelaySystemLine)(db, relay.id, 'waiting', requester, (0, relay_session_ref_1.resolveRelaySession)(db, relay.to), now);
+    }
+    (0, relay_db_1.clearRelayPending)(db, relay.id, now);
+    logger.info('relay-delivered', { relayId, kind, to: `${requester.worktreeId}/${requester.instanceId}` });
+    return 'delivered';
+}
+/**
+ * Deliver every stashed payload that can be delivered now.
+ *
+ * Single-flight: a pump already running is the pump, and a second entry — the
+ * timer firing while a first pass awaits a capture — would read the same rows
+ * and race its own sends.
+ */
+async function pumpRelayDeliveries() {
+    if (globalThis.__relayPumpRunning)
+        return;
+    globalThis.__relayPumpRunning = true;
+    try {
+        const db = (0, db_instance_1.getDbInstance)();
+        for (const item of (0, relay_db_1.listRelaysWithPendingPayload)(db)) {
+            if (inFlight.has(item.relay.id))
+                continue;
+            inFlight.add(item.relay.id);
+            try {
+                await deliverOne(db, item.relay.id, item.kind, item.body);
+            }
+            catch (error) {
+                logger.warn('relay-delivery-failed', {
+                    relayId: item.relay.id,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            finally {
+                inFlight.delete(item.relay.id);
+            }
+        }
+    }
+    catch (error) {
+        logger.warn('relay-pump-failed', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    finally {
+        globalThis.__relayPumpRunning = false;
+    }
+}
+/** One tick of the background loop: sweep the deadlines, then deliver. */
+async function runRelayMaintenanceTick() {
+    try {
+        sweepExpiredRelays((0, db_instance_1.getDbInstance)());
+    }
+    catch (error) {
+        logger.warn('relay-sweep-failed', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    await pumpRelayDeliveries();
+}

package/dist/server/src/lib/relay/relay-messages.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * Every sentence a relay puts in front of an agent or a reader (Issue #2377).
+ *
+ * ## Why the text is here and not in `locales/`
+ *
+ * Two of the four go into an AGENT's composer, which makes them prompts rather
+ * than labels: the `[from …]` header is what tells session A that the paragraph
+ * underneath it was written by somebody else, and a key that resolved to its own
+ * name — a renamed namespace, a dictionary that failed to load — would hand A an
+ * unattributed wall of text from another session and no way to tell. The same
+ * argument `buildDelegationBrief` makes in `lib/cli/command-reference`, and the
+ * same shape `buildModelChangedSentence` uses for the model-change history row
+ * (#2357): both languages written out side by side so a change to one is
+ * visibly a change to the other.
+ *
+ * The UI's own labels — the badges, the chat strip — ARE in `locales/`, because
+ * those are labels.
+ *
+ * ## The header is machine-readable on purpose
+ *
+ * {@link RELAY_HEADER_PREFIX} opens every delivered body in both languages, so
+ * a reader (a human, an agent, a later `capture`) can recognise a relayed
+ * message without knowing which language the server was speaking. The body
+ * after it is B's own text, untouched — summarising or translating it is out of
+ * scope by the Issue's own words.
+ *
+ * @module lib/relay/relay-messages
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RELAY_HEADER_PREFIX = void 0;
+exports.buildRelayHeader = buildRelayHeader;
+exports.buildRelayReplyMessage = buildRelayReplyMessage;
+exports.buildRelayPromptMessage = buildRelayPromptMessage;
+exports.buildRelayExpiredMessage = buildRelayExpiredMessage;
+exports.buildRelaySystemLine = buildRelaySystemLine;
+/**
+ * The literal every relayed body starts with.
+ *
+ * `[from ` and not a localized word: it is the one token a consumer may match
+ * on, and it has to mean the same thing in both dictionaries.
+ */
+exports.RELAY_HEADER_PREFIX = '[from ';
+/** How long a quoted prompt question may be before it is elided. */
+const PROMPT_SUMMARY_MAX_CHARS = 200;
+/** How many options of a confirmation are listed before the rest are counted. */
+const PROMPT_OPTIONS_MAX = 9;
+/**
+ * `[from <alias> / <worktree>]` — the attribution line.
+ *
+ * Both fields, always: an alias alone is ambiguous across worktrees (every
+ * repository's roster tends to contain a `Codex 2`) and a worktree alone does
+ * not say which of its sessions answered.
+ */
+function buildRelayHeader(sender) {
+    return `${exports.RELAY_HEADER_PREFIX}${sender.alias} / ${sender.worktreeId}]`;
+}
+/**
+ * B's reply, attributed.
+ *
+ * The body is passed through verbatim — no summary, no translation, no
+ * re-wrapping. A blank body still gets a header: "they finished and said
+ * nothing" is information, and swallowing the delivery would leave A waiting on
+ * a relay that has already closed.
+ */
+function buildRelayReplyMessage(sender, reply) {
+    const body = reply.trim();
+    return body === ''
+        ? `${buildRelayHeader(sender)} (no reply body)`
+        : `${buildRelayHeader(sender)} ${body}`;
+}
+/** Collapse whitespace and clip, so a 40-line dialog is one readable line. */
+function squeeze(text, max) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
+}
+const PROMPT_TEMPLATES = {
+    en: {
+        waiting: 'is waiting for a confirmation:',
+        options: 'Options:',
+        more: '(+{n} more)',
+    },
+    ja: {
+        waiting: '確認待ちです:',
+        options: '選択肢:',
+        more: '(他 {n} 件)',
+    },
+};
+/**
+ * "They are blocked on a dialog, and here is what it asks."
+ *
+ * Deliberately NOT an instruction to answer it. `respond` on somebody else's
+ * dialog picks whatever option happens to be highlighted (#1681), and the
+ * delegation brief already forbids it; this notice exists so A can decide what
+ * to do, which is usually to tell a human.
+ */
+function buildRelayPromptMessage(locale, sender, notice) {
+    const t = PROMPT_TEMPLATES[locale];
+    const head = `${buildRelayHeader(sender)} ${t.waiting} ${squeeze(notice.question, PROMPT_SUMMARY_MAX_CHARS)}`;
+    if (notice.options.length === 0)
+        return head;
+    const shown = notice.options.slice(0, PROMPT_OPTIONS_MAX);
+    const rest = notice.options.length - shown.length;
+    const listed = shown.map((o) => `${o.key}) ${squeeze(o.label, 60)}`).join('  ');
+    const more = rest > 0 ? ` ${t.more.replace('{n}', String(rest))}` : '';
+    return `${head}\n${t.options} ${listed}${more}`;
+}
+const EXPIRED_TEMPLATES = {
+    en: 'The reply you were waiting for did not arrive within {hours}h; the relay has expired.',
+    ja: '待っていた返信が {hours} 時間以内に届かなかったため、委任は期限切れになりました。',
+};
+/**
+ * The single line an expired relay leaves in A's composer.
+ *
+ * One line and one only — the Issue's "1行だけ通知". The once-ness is enforced
+ * by the ledger (`markRelayExpired` is a guarded update), not by this string.
+ */
+function buildRelayExpiredMessage(locale, sender, ttlMs) {
+    const hours = Math.max(1, Math.round(ttlMs / 3_600_000));
+    return `${buildRelayHeader(sender)} ${EXPIRED_TEMPLATES[locale].replace('{hours}', String(hours))}`;
+}
+const SYSTEM_TEMPLATES = {
+    en: {
+        requested: 'Delegated to {alias}; waiting for the reply.',
+        replied: 'Reply from {alias}.',
+        waiting: '{alias} is waiting for a confirmation.',
+        expired: 'The delegation to {alias} expired without a reply.',
+    },
+    ja: {
+        requested: '{alias} へ委任、返信待ち',
+        replied: '{alias} から返信',
+        waiting: '{alias} が確認待ち',
+        expired: '{alias} への委任が返信のないまま期限切れ',
+    },
+};
+/**
+ * The one-line system row the chat surface and History both show.
+ *
+ * Written into `chat_messages` exactly as the model-change row is (#2357), in
+ * the readers' language, because a stored row cannot be re-rendered per viewer.
+ */
+function buildRelaySystemLine(locale, kind, alias) {
+    return SYSTEM_TEMPLATES[locale][kind].replace('{alias}', alias);
+}

package/dist/server/src/lib/relay/relay-policy.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * The four rules that stop relays from becoming a loop (Issue #2377).
+ *
+ * A relay is a standing instruction that fires on somebody else's turn, so the
+ * failure mode it introduces is not "a wrong answer" but "two agents talking to
+ * each other forever, each one's reply being the other's next prompt". None of
+ * the guards below is expensive; all four exist because the cheap version of
+ * this feature has no natural stopping point.
+ *
+ *  1. **A relayed message may not open a relay** (`RELAY_CHAIN_BLOCKED`). The
+ *     default. `--allow-relay-chain` is the deliberate override, and the flag is
+ *     named after what it permits rather than after what it disables.
+ *  2. **Chains are bounded** (`RELAY_HOPS_EXCEEDED`). Even with the override,
+ *     depth stops at {@link MAX_RELAY_HOPS}.
+ *  3. **One open relay per direction** (`RELAY_DUPLICATE_PENDING`). A second
+ *     standing instruction from A to B says nothing the first does not, and both
+ *     would fire on the same finished turn.
+ *  4. **A session may not relay to itself** (`RELAY_SELF_TARGET`), which is a
+ *     one-message loop with no second party in it at all.
+ *
+ * Pure: every decision is a function of values the caller already read. The
+ * database work — finding the parent relay, counting the open ones — is
+ * `relay-service`'s, so the rules can be tested without a schema.
+ *
+ * @module lib/relay/relay-policy
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RELAY_PUMP_INTERVAL_MS = exports.RELAY_SCRAPE_QUIET_MS = exports.MAX_OPEN_RELAYS_PER_PAIR = exports.MAX_RELAY_HOPS = exports.MAX_RELAY_TTL_MS = exports.MIN_RELAY_TTL_MS = exports.DEFAULT_RELAY_TTL_MS = void 0;
+exports.isSameEndpoint = isSameEndpoint;
+exports.decideRelayCreation = decideRelayCreation;
+exports.isRelayRefusal = isRelayRefusal;
+exports.resolveRelayTtlMs = resolveRelayTtlMs;
+/** How long a relay stands before it is swept. 24h, per the Issue. */
+exports.DEFAULT_RELAY_TTL_MS = 24 * 60 * 60 * 1000;
+/** Shortest TTL a caller may ask for: one minute. */
+exports.MIN_RELAY_TTL_MS = 60 * 1000;
+/** Longest TTL a caller may ask for: seven days. */
+exports.MAX_RELAY_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * How deep a chain may go.
+ *
+ * Three, by the Issue. Depth 1 is a relay nothing relayed into; a relay opened
+ * while answering one is 2, and so on. A request that would create depth 4 is
+ * refused — `--allow-relay-chain` widens the door, it does not remove the wall.
+ */
+exports.MAX_RELAY_HOPS = 3;
+/** How many open relays one from→to direction may hold at once. */
+exports.MAX_OPEN_RELAYS_PER_PAIR = 1;
+/**
+ * How long a scrape-only tool must sit still before its pane counts as a reply.
+ *
+ * copilot, gemini and vibe-local keep no transcript, so what a completed turn
+ * leaves behind is the poller's copy of the SCREEN — and the poller's completion
+ * judgement is a string analysis of a frame that is still being drawn. Delivering
+ * on the first such judgement is how a half-written answer reaches session A as
+ * "the reply". The relay therefore waits, re-reads the newest row and delivers
+ * only if nothing newer arrived: the Issue's 「完了検知 + 数秒の静穏」.
+ *
+ * Tools with a transcript skip this entirely — their reader answers `true` only
+ * for a turn the agent has closed, which is a stronger statement than any amount
+ * of quiet.
+ */
+exports.RELAY_SCRAPE_QUIET_MS = 4_000;
+/** How often the pump retries deliveries and sweeps expired relays. */
+exports.RELAY_PUMP_INTERVAL_MS = 15_000;
+/** Whether two endpoints name the same session. */
+function isSameEndpoint(a, b) {
+    return a.worktreeId === b.worktreeId && a.instanceId === b.instanceId;
+}
+/**
+ * Apply all four rules and hand back the depth, or the refusal.
+ *
+ * Order matters only for which sentence an operator sees first, and it is the
+ * order they can act on: "you are the same session" is a typo, "this would be a
+ * chain" is a flag away, "the chain is too deep" and "you already have one" are
+ * decisions about work in flight.
+ */
+function decideRelayCreation(input) {
+    if (isSameEndpoint(input.from, input.to)) {
+        return {
+            code: 'RELAY_SELF_TARGET',
+            message: 'A session cannot relay a reply to itself. --reply-to must name a different '
+                + 'worktree or a different agent instance.',
+        };
+    }
+    const hops = input.parentHops === null ? 1 : input.parentHops + 1;
+    if (input.parentHops !== null && !input.allowRelayChain) {
+        return {
+            code: 'RELAY_CHAIN_BLOCKED',
+            message: 'The last message this session was given arrived over a relay, so opening '
+                + 'another one would chain two deliveries together. Pass --allow-relay-chain '
+                + 'if that is what you mean.',
+        };
+    }
+    if (hops > exports.MAX_RELAY_HOPS) {
+        return {
+            code: 'RELAY_HOPS_EXCEEDED',
+            message: `Relay chains stop at ${exports.MAX_RELAY_HOPS} hops; this one would be ${hops}. `
+                + 'Report the reply to whoever asked instead of forwarding it again.',
+        };
+    }
+    if (input.openBetween >= exports.MAX_OPEN_RELAYS_PER_PAIR) {
+        return {
+            code: 'RELAY_DUPLICATE_PENDING',
+            message: 'There is already an open relay between these two sessions. Wait for it, or '
+                + 'withdraw it with `commandmate relays cancel <id>`.',
+        };
+    }
+    return { ok: true, hops };
+}
+/** Whether a verdict is a refusal. */
+function isRelayRefusal(verdict) {
+    return 'code' in verdict;
+}
+/**
+ * Clamp a requested TTL into the supported window.
+ *
+ * Clamped rather than refused: the TTL is a sweep deadline, not a promise, and
+ * an operator who asked for a year gets the longest one that keeps the ledger
+ * from accumulating rows nobody will ever collect.
+ */
+function resolveRelayTtlMs(requested) {
+    if (requested === undefined || !Number.isFinite(requested))
+        return exports.DEFAULT_RELAY_TTL_MS;
+    return Math.min(exports.MAX_RELAY_TTL_MS, Math.max(exports.MIN_RELAY_TTL_MS, Math.trunc(requested)));
+}