/** * relays Command - the standing delegations this machine is holding (#2377) * * commandmate relays [--worktree ] [--instance ] [--json] * commandmate relays --id [--json] (Issue #3957: one relay, open or closed) * commandmate relays cancel * commandmate relays resolve --payload --attempt --confirm|--retry|--discard * (Issue #4082: settle a delivery held as uncertain) * * ## Why a command and not a flag on `ls` * * A relay is the one piece of state in CommandMate that belongs to TWO sessions * at once: session A is owed an answer, session B owes one, and neither * worktree's own listing can show that without inventing a column for the other * side. So the listing is its own thing, and it prints the pair — `from` and * `to`, `→` between them — rather than a status word per row. * * With no `--worktree` it asks the session it is running inside (`whoami`'s * resolution) and prints that session's two sides. That is the shape an agent * uses: "what am I waiting for, and what do I owe?" is a question about the * caller, and making the caller name itself is what #2376 exists to stop. * * ## What this module exports besides the command * * The `--reply-to` plumbing, because `send` and `ask` both take that flag and * both have to turn one string into the two ids the ledger stores. Keeping * {@link resolveRelayEndpoint} here rather than in `send.ts` is what stops the * two commands from resolving `self` two different ways. */ import { Command } from 'commander'; import { ApiClient } from '../utils/api-client'; import type { CommandTarget } from './command-target'; /** * The codes `POST /api/relays` refuses with. * * Mirrors `RelayRefusalCode` in `lib/relay/relay-policy` plus the route's own * not-found; duplicated rather than imported so the CLI bundle does not pull the * server's database graph in for four strings. * * Not `RELAY_TOOL_POLICY_DENIED` (Issue #4437): that one is exit 33, and `ApiClient` * throws it as a `ToolPolicyDeniedError`, which {@link registerRelay} passes on. */ export declare const RELAY_REFUSAL_CODES: Set; /** One end of a relay, as the API wants it. */ export interface RelayEndpointArg { worktreeId: string; instanceId: string; /** * Issue #4496: on the `to` end only, the tool the send asked for (`--agent`), which * `POST /api/relays` judges rule 0 by for an ad-hoc instance. An older server ignores it. */ cliToolId?: string; } /** The text `--reply-to` is documented with, shared by `send` and `ask`. */ export declare const REPLY_TO_OPTION_DESCRIPTION: string; /** The text `--allow-relay-chain` is documented with. */ export declare const ALLOW_RELAY_CHAIN_DESCRIPTION: string; /** * Turn one `--reply-to` value into the two ids the ledger stores. * * Exits 2 rather than throwing: every failure here is a bad option value or a * shell that is not inside a CommandMate session, and both are things the * operator fixes on the command line. * * @param client - API client * @param spec - The raw `--reply-to` value */ export declare function resolveRelayEndpoint(client: ApiClient, spec: string): Promise; /** * The resolved endpoint for a worktree, with or without a named instance. * * Also what `send` / `ask` use for the relay's OTHER end — the session being * asked — because the ledger stores a resolved id at both ends and the send's * own `--instance` may have been omitted (meaning "the primary one", which only * the server can name). * * @param client - API client * @param worktreeId - Worktree ID * @param selector - An instance id or roster alias, or undefined * @param requestedAgent - The `--agent` value, if the caller gave one */ export declare function resolveEndpointForWorktree(client: ApiClient, worktreeId: string, selector: string | undefined, requestedAgent?: string): Promise; /** What {@link registerRelay} needs. */ export interface RegisterRelayInput { /** The session that will receive the reply. */ from: RelayEndpointArg; /** The session being asked. */ to: RelayEndpointArg; allowRelayChain?: boolean; /** * Runs when the relay could not be opened, refused or not, before the command ends * (Issue #4133): a refusal exits right here, past any caller's own handling. */ onFailure?: () => Promise; } /** A relay {@link registerRelay} opened (Issue #3957). */ export interface RegisteredRelay { id: string; /** * The server confirmed `bindMode: 'bound'`: the relay id goes on the send, * and only that send's reply is delivered. False on an older server. */ bound: boolean; } /** The one line an older server's relay gets on stderr (Issue #3957). */ export declare const LEGACY_RELAY_NOTICE: string; /** * Open a relay, printing the server's own refusal and exiting 2 on one. * * Exit 2 and not a bespoke code: every refusal is a decision the operator can * change (drop the flag, cancel the other relay, stop forwarding), which is what * `CONFIG_ERROR` means everywhere else in this CLI. * * Issue #3957: asks for `bind: true` and believes it only when the answer says * `bindMode: 'bound'`. A server that does not know the flag answers without * the key; the relay is then the legacy kind and its id is not sent along. * * Issue #4437: a relay with antigravity at either end that the tool policy refuses * (409 `RELAY_TOOL_POLICY_DENIED`) is not one of these: after `onFailure` it is thrown * on as a `ToolPolicyDeniedError`, and the command reports it with exit 33 (its * `--json` included) before anything is sent. * * @returns The relay id, and whether it is bound */ export declare function registerRelay(client: ApiClient, input: RegisterRelayInput): Promise; /** Withdraw a relay, best effort. Used when the send it accompanied failed. */ export declare function cancelRelayQuietly(client: ApiClient, relayId: string): Promise; /** * Print where a relay whose send could not be confirmed stands (Issue #3957). * * The relay is left open — withdrawing it would drop a reply that may well be * on its way — and the message is not resent, which could make it arrive twice. */ export declare function printRelayUnconfirmedNotice(relayId: string, worktreeId?: string, target?: CommandTarget): void; export declare function createRelaysCommand(): Command; //# sourceMappingURL=relays.d.ts.map