@phnx-labs/agents-cli 1.22.115 → 1.22.116

package/dist/lib/feed/answer.d.ts

@@ -1,14 +1,133 @@
 import { type ActiveSession } from '../session/active.js';
 import { type MessageReceipt } from './feed.js';
+/**
+ * Total budget for one answer. Sits below the AGI Menu's 30s abandon so the
+ * operator always gets a typed verdict instead of a timeout.
+ */
+export declare const ANSWER_DEADLINE_MS = 20000;
+/** Slice of the budget the optional PR-review enrichment may spend. */
+export declare const PR_ENRICHMENT_BUDGET_MS = 4000;
+/** Budget for the forwarded leg — the remote repeats the local work under its own deadline. */
+export declare const REMOTE_ANSWER_TIMEOUT_MS = 25000;
+/**
+ * A claim older than this with no receipt was stranded by a kill, not left in
+ * flight: it exceeds a full local deadline plus the remote leg, so no live
+ * delivery can still be running behind it.
+ */
+export declare const STRANDED_CLAIM_MS = 60000;
+/**
+ * How long to watch a `resume` child before giving up on a verdict. A resume
+ * runs the agent's whole next turn — minutes — so waiting for exit would blow the
+ * operator deadline on every headless answer. Only a clean early exit is booked;
+ * a non-zero exit or a still-running child is unknown, because neither proves
+ * the agent did or did not accept the prompt.
+ */
+export declare const RESUME_SETTLE_MS = 2000;
+/**
+ * How long a caller that LOST the claim waits for the holder's receipt before
+ * reporting unknown. The holder is mid-delivery — a double-clicked answer is the
+ * common case — so a short wait turns "I can't tell" into the real receipt,
+ * without ever delivering a second copy.
+ */
+export declare const HOLDER_RECEIPT_WAIT_MS = 400;
+/** Why an answer could not be delivered — the discriminant the operator UI branches on. */
+export type AnswerFailureCode = 'malformed_key' | 'no_session' | 'stale' | 'unverified' | 'unauthorized' | 'unknown_choice' | 'empty_answer' | 'refused' | 'rail_failed' | 'timeout' | 'remote_failed';
+/** A CONFIRMED failure: nothing reached a rail, the claim is released, retry is safe. */
+export declare class AnswerError extends Error {
+    readonly code: AnswerFailureCode;
+    constructor(message: string, code: AnswerFailureCode);
+}
+/**
+ * An UNCONFIRMED outcome: something may have been delivered. The claim is kept
+ * so a retry cannot double-send, and the operator is offered a delivery check
+ * rather than a resend.
+ */
+export declare class AnswerUnknownError extends Error {
+    constructor(message: string);
+}
+/**
+ *   delivered        — this call handed the answer to a rail.
+ *   already_answered — another claim owns it; the reported evidence is that claim's.
+ *   unknown          — something may have landed; do NOT resend, check delivery.
+ *   failed           — confirmed: nothing was delivered.
+ */
+export type AnswerStatus = 'delivered' | 'already_answered' | 'unknown' | 'failed';
+/**
+ *   receipt     — a real {@link MessageReceipt} exists on the block.
+ *   unconfirmed — no receipt evidence either way. The card must NOT be cleared.
+ *   failed      — confirmed failure, including a `dropped`/`expired` receipt.
+ */
+export type AnswerDelivery = 'receipt' | 'unconfirmed' | 'failed';
+export interface FeedAnswerResult {
+    status: AnswerStatus;
+    /** How much the CLI can actually vouch for. */
+    delivery: AnswerDelivery;
+    /** The block's real receipt. Absent means no rail ever reported one. */
+    receipt?: MessageReceipt;
+    /**
+     * The AGENT's own evidence that it received the answer — a `consumed` or
+     * `continued` receipt. A `queued` receipt is delivery, never resolution, so it
+     * leaves this false. Removal of the item from the feed resolves the card on
+     * its own; this flag only ever adds evidence, it never withholds it.
+     */
+    resolved: boolean;
+    /** Human explanation for a failure, an unknown, or an unconfirmed delivery. */
+    reason?: string;
+    /** Set when `status` is `failed`. */
+    code?: AnswerFailureCode;
+    attentionKey: string;
+    blockId?: string;
+    /** The device that owns the item — the exact target a delivery check re-queries. */
+    host?: string;
+    /**
+     * Stable identity of the delivery attempt (the claim timestamp). A delivery
+     * check correlates its read-only answer with the attempt it is checking, so
+     * "still unconfirmed" is distinguishable from "a newer attempt replaced it".
+     */
+    attempt?: string;
+}
 interface VerifiedOperator {
     id?: string;
     verified: boolean;
     label?: string;
 }
-interface FeedAnswerResult {
-    status: 'delivered' | 'already_answered';
-    receipt: MessageReceipt;
+export interface ParsedAttentionKey {
+    host: string;
+    sessionId: string;
+    generation: string;
 }
+/**
+ * Split `<host>/<session>/<generation>` (attention.ts `attentionKey`). Fails
+ * loud on a malformed key: the old `slice(0, indexOf('/'))` returned a truncated
+ * host for a key with no separator, which then routed the answer at random.
+ */
+export declare function parseAttentionKey(key: string): ParsedAttentionKey;
+/**
+ * Whether THIS machine owns the item. The exact local/remote choice: the key's
+ * host is compared through the same {@link normalizeHost} the machine id is
+ * minted with, so `Yosemite-M4.local` and `yosemite-m4` are one machine.
+ */
+export declare function answerOwnerIsLocal(host: string, self?: string): boolean;
+/**
+ * What a stored receipt proves. The lifecycle vocabulary is fixed by
+ * `MessageReceipt`, and each member means exactly one thing here:
+ *   queued            — a rail took the answer. Delivery, never resolution.
+ *   consumed/continued— the agent itself acknowledged it. This resolves the item.
+ *   dropped/expired   — terminal failure; it is the newest truth for its message
+ *                       (the write rank puts it top precisely so it cannot be
+ *                       regressed), which is exactly why it must not read as success.
+ */
+export declare function classifyReceipt(receipt: MessageReceipt): {
+    delivery: AnswerDelivery;
+    resolved: boolean;
+};
+/**
+ * Read-only reconciliation of an attention item's delivery state — what powers
+ * "Check delivery" on an unconfirmed answer. It NEVER claims, routes, adopts or
+ * resends; it reports the stored claim and the block's real receipt so an
+ * operator can tell "still unconfirmed" from "the agent has it".
+ */
+export declare function checkAnswerDelivery(attentionKey: string, feedRoot?: string, expectedAttempt?: string): FeedAnswerResult;
 /** Atomically claim the first answer, then route it over the session's recorded reply rail. */
 export declare function claimAndRouteAttentionAnswer(input: {
     attentionKey: string;
@@ -18,13 +137,43 @@ export declare function claimAndRouteAttentionAnswer(input: {
     feedRoot?: string;
     mailboxRoot?: string;
     sessions?: ActiveSession[];
+    deadlineMs?: number;
 }): Promise<FeedAnswerResult>;
-/** Forward a fleet attention answer to the device that owns its scope. */
+/**
+ * The remote `agents feed answer` argv for a forwarded answer. Exported so the
+ * exact tokens that cross the hop are asserted directly.
+ */
+export declare function remoteAnswerArgv(input: {
+    attentionKey: string;
+    choiceId?: string;
+    text?: string;
+    operatorId?: string;
+    check?: boolean;
+    attempt?: string;
+}): string[];
+/**
+ * Forward a fleet attention answer to the device that owns its scope.
+ *
+ * Every token is POSIX-quoted with the canonical {@link shellQuote} before the
+ * remote login shell parses it, so a multiline answer or one carrying `$`, `"`,
+ * `` ` ``, `;` or a newline arrives byte-identical. The transport is the
+ * canonical bounded {@link sshExecAsync} — it disables ControlMaster whenever a
+ * timeout is set, so the bound actually tears the remote command down instead of
+ * orphaning it behind a control socket.
+ *
+ * A timeout is reported UNKNOWN: the remote may well have delivered before the
+ * link was cut, so the operator is offered a delivery check, never an implicit
+ * resend. The returned receipt is verified to be about the key that was asked
+ * for, so a mismatched or truncated remote reply cannot be trusted as one.
+ */
 export declare function forwardFeedAnswer(input: {
     host: string;
     attentionKey: string;
     choiceId?: string;
     text?: string;
     operatorId?: string;
+    check?: boolean;
+    attempt?: string;
+    timeoutMs?: number;
 }): Promise<FeedAnswerResult>;
 export {};