@phnx-labs/agents-cli 1.20.88 → 1.20.90

package/dist/commands/sessions.d.ts

@@ -1,4 +1,4 @@
-import type { Command } from 'commander';
+import { type Command } from 'commander';
 import type { SessionAgentId, SessionMeta, ViewMode } from '../lib/session/types.js';
 import { type ActiveSession } from '../lib/session/active.js';
 import { gatherRemoteList, runOnPeer } from '../lib/session/remote-list.js';
@@ -17,6 +17,10 @@ interface SessionsOptions extends SessionFilterOptions {
     /** Also list sessions from the user's own unmanaged ~/.<agent> installs. */
     unmanaged?: boolean;
     query?: string;
+    /** Resolve one historical selector to metadata only (requires --json). */
+    resolve?: string;
+    /** Versioned internal peer protocol; old/unsafe peers must reject it. */
+    resolveSafeV1?: string;
     limit?: string;
     sort?: string;
     json?: boolean;
@@ -40,6 +44,8 @@ interface SessionsOptions extends SessionFilterOptions {
     flat?: boolean;
     /** With --active: show only sessions waiting on user input; exit 1 if any. */
     waiting?: boolean;
+    /** Show only favorited (starred) sessions — the `f` key's flag twin. */
+    favorites?: boolean;
     /** Enrich the listing with live glyphs/preview for running rows. Default on;
      * `--no-live` sets this false. Commander's `--no-` convention. */
     live?: boolean;
@@ -120,6 +126,29 @@ export declare function liveGlyphAndPreview(a: ActiveSession | undefined): {
  * exported for the row tests.
  */
 export declare function liveStatusWord(a: ActiveSession | undefined): string;
+/**
+ * True when a session is blocked on a human — the `--waiting` contract.
+ *
+ * NOT `status === 'input_required'`. `foldHostLink` rewrites that status to
+ * `orphaned` when nothing is attached, and a session waiting on a question with
+ * NOBODY watching is the most acute case `--waiting` exists to surface, not one
+ * it should drop. The underlying `activity` is never rewritten, so it is the
+ * honest signal here.
+ *
+ * But `activity` is never rewritten for a DEAD session either: one that died
+ * mid-question keeps `waiting_input` forever, and answering it is not a thing a
+ * human can do — it needs a relaunch. `--waiting` is a scriptable gate ("does
+ * anything need me?"), so a corpse must not trip it.
+ *
+ * `closed` and `crashed` are unconditionally dead, so they are excluded outright.
+ * `abandoned` is NOT: it fires on transcript staleness before the liveness check,
+ * so it also covers the live-but-forgotten case — an interactive session that
+ * asked a question and sat untouched over a long weekend is still answerable, and
+ * is exactly what this gate exists for. It is excluded only when we positively
+ * know its process is gone; unknown liveness (an older peer, a row with no pid)
+ * stays excluded rather than inventing a human who can answer.
+ */
+export declare function isAwaitingUser(s: ActiveSession): boolean;
 /**
  * The tracker/PR ref for a session's dedicated column: the ticket id when known,
  * else `PR#<n>`, else empty. Pulled out of the trailing badge blob so refs align
@@ -136,11 +165,17 @@ export declare function linkCwdCell(s: Pick<SessionMeta, 'cwd' | '_remote'>, lab
  * (null when unknown) alongside the raw fields, so every active row is joinable.
  * `project` uses the same derivation SessionMeta does — basename(cwd) (see
  * discover.ts) — so the active view and the history view join identically.
+ *
+ * `viewingIn` flattens to the same display string the row renderer prints —
+ * `'codium tab 3'` / `'detached'` / null — so a consumer can tell a watched
+ * session from an orphaned one (its terminal died, the agent is still running)
+ * without re-implementing the tmux client lookup.
  */
-export declare function serializeActiveSessionsForJson(sessions: ActiveSession[]): Array<ActiveSession & {
+export declare function serializeActiveSessionsForJson(sessions: ActiveSession[]): Array<Omit<ActiveSession, 'viewingIn'> & {
     ticketId: string | null;
     project: string | null;
     prLink: string | null;
+    viewingIn: string | null;
 }>;
 /**
  * Compact owner display for the `--active` owner column: the local-part of a
@@ -224,6 +259,10 @@ export declare function mergeLocalFirst(sessions: SessionMeta[], localMachine: s
  * `--json --host` remote fan-out so both emit byte-identical row shapes.
  */
 export declare function serializeSessionsJson(sessions: SessionMeta[]): string;
+/** The intentionally small metadata contract emitted by `sessions --resolve`.
+ * Transcript locations, extracted plans, account data, costs, and other indexed
+ * payload stay local to the machine that owns them. */
+export declare function serializeResolvedSessionsJson(sessions: SessionMeta[]): string;
 /**
  * Whether the local machine's sessions belong in an `--active` view. Local is
  * included by default; an explicit `--host`/`--device` list scopes the view to
@@ -275,6 +314,17 @@ export declare function isBareBrowserListing(options: SessionsOptions, query: st
  * `runSessionBrowser` picker cannot represent.
  */
 export declare function hasNoBrowserDisqualifyingFlags(options: SessionsOptions, query: string | undefined): boolean;
+/**
+ * The one-line live status banner shown above a session preview: the glyph, the
+ * status word, and — when the session needs a human or has LOST one — a plain
+ * sentence saying so. Shared by `--preview` and the interactive browser's preview
+ * pane so both explain a state the same way.
+ *
+ * `crashed` and `orphaned` are the states a glyph alone cannot carry: nobody
+ * reads "orphan" and knows it means "still running in tmux with no window
+ * attached", so those two spell it out.
+ */
+export declare function formatLiveStatusHeadline(live: ActiveSession | undefined, favorite?: boolean): string;
 /**
  * Whether a session belongs to `team`, from either end: it spawned the team, or
  * it is one of the team's teammates. Case-insensitive, matching the SQL
@@ -299,7 +349,7 @@ export declare function teamBadge(session: SessionMeta): {
  * (tracker/PR ref, pulled out of the badge blob so refs align) is only rendered
  * when `showTicket` — otherwise a listing with no refs would waste a column of
  * dashes and needlessly truncate the topic. Worktree stays a trailing badge. */
-export declare function flatSessionRow(session: SessionMeta, live?: ActiveSession, showTicket?: boolean, cols?: PickerColumns): string;
+export declare function flatSessionRow(session: SessionMeta, live?: ActiveSession, showTicket?: boolean, cols?: PickerColumns, favorite?: boolean): string;
 /**
  * Group key for the overview: prefer the indexed project name; else fold the cwd
  * to its repo — a worktree (`.../<repo>/.agents/worktrees/<slug>`) folds to the
@@ -364,6 +414,19 @@ export interface PickerColumns {
      * off for a plain transcript listing, where no row has a host.
      */
     showHost?: boolean;
+    /**
+     * Render the favorite marker column. Like every other conditional column here,
+     * it earns its 2 cells only when some row in the pool is actually starred — a
+     * user who has never favorited anything pays nothing for the feature.
+     */
+    showFavorite?: boolean;
+    /**
+     * Render the live status column (`working` / `waiting` / `orphan` / `crashed`).
+     * Live-only, gated the same way as {@link showHost}: it comes from the
+     * active-session scan, so the running-filtered browser sets it and a plain
+     * transcript listing — where no row has a status — leaves it off.
+     */
+    showStatus?: boolean;
     /**
      * Cells the picker prepends before each row: 2 for the single-select cursor
      * ('> '), 6 for the multi-select cursor + checkbox ('> [x] '). Reserved from
@@ -393,7 +456,7 @@ export declare function pickerColumnsFor(sessions: SessionMeta[]): PickerColumns
  * resolvable host (cloud rows, an unreadable process env).
  */
 export declare function liveHostLabel(a: ActiveSession | undefined): string;
-export declare function formatPickerLabel(s: SessionMeta, query: string, cols?: PickerColumns, ssh?: SshOriginTag, host?: string): string;
+export declare function formatPickerLabel(s: SessionMeta, query: string, cols?: PickerColumns, ssh?: SshOriginTag, host?: string, favorite?: boolean, live?: ActiveSession): string;
 /**
  * Pick a hint to show above the picker. Deterministic (keys off the pool size)
  * so it stays fixed across the picker's re-renders within a single run.
@@ -460,7 +523,9 @@ export interface SessionQueryResolution {
  * search (a bare id must not surface every transcript that merely mentions it).
  * A genuine search phrase keeps the ranked metadata+content search.
  */
-export declare function resolveSessionQuery(pool: SessionMeta[], query: string): SessionQueryResolution;
+export declare function resolveSessionQuery(pool: SessionMeta[], query: string, options?: {
+    indexFallback?: boolean;
+}): SessionQueryResolution;
 /** Filter and rank sessions by a multi-term search query across metadata and content. */
 export declare function filterSessionsByQuery(sessions: SessionMeta[], query: string | undefined): SessionMeta[];
 /**
@@ -483,36 +548,60 @@ export interface FleetResolveDeps {
     gatherRemoteList: typeof gatherRemoteList;
     runOnPeer: typeof runOnPeer;
 }
-/** One distinct machine that reported the id, plus its winning row. */
+/** One distinct machine that reported a logical session, plus its winning row. */
 interface FleetHit {
     machine: string;
     session: SessionMeta;
 }
-/** Group a fleet sweep's rows to the DISTINCT machines that hold the id. Each
- * peer answered `sessions <id> --json --local`, which (post-fix) id-resolves and
- * so returns the matching row(s); a peer with a synced MIRROR of the same id can
- * emit more than one row, so we keep the first per machine. Rows the peer somehow
- * returned that do NOT match the id (defensive against version skew) are dropped
- * so a stray content hit can never masquerade as an exact resolution. */
-export declare function fleetHitsById(rows: SessionMeta[], id: string): FleetHit[];
-/**
- * Locate a full session id across the online fleet and render it from the machine
+/** One logical session returned by the fleet, including every machine holding a copy. */
+export interface FleetSessionCandidate {
+    id: string;
+    hits: FleetHit[];
+}
+export type MetadataResolveOutcome = {
+    kind: 'resolved';
+    session: SessionMeta;
+} | {
+    kind: 'not-found';
+} | {
+    kind: 'ambiguous';
+    candidates: FleetSessionCandidate[];
+} | {
+    kind: 'partial';
+    failedPeers: string[];
+};
+/** Resolve a fleet sweep through the same canonical full-id / prefix resolver as
+ * local lookups, then group copies by logical session id. Synced mirrors of one
+ * session therefore stay one candidate even when several machines report them;
+ * distinct ids sharing a prefix remain distinct ambiguity candidates. */
+export declare function fleetCandidatesByQuery(rows: SessionMeta[], query: string): FleetSessionCandidate[];
+/** Fixed peer argv for the metadata resolver. Scope flags compose identically on
+ * every host; `--all` removes the SSH login cwd/time window, not agent/project filters. */
+export declare function metadataResolveForwardedArgs(selector: string, scope: Pick<SessionFilterOptions, 'agent' | 'project'>): string[];
+/** Resolution must fail closed when any selected peer did not answer. Choosing
+ * from a partial fleet can turn an unseen candidate into a false unique match. */
+export declare function metadataResolveOutcome(localMatches: SessionMeta[], remote: {
+    sessions: SessionMeta[];
+    unreachable: string[];
+}, selector: string): MetadataResolveOutcome;
+/**
+ * Locate a full session id or short id prefix across the online fleet and render it from the machine
  * that holds it. The local disk already missed; this fans `sessions <id> --json
  * --all` out to every registered online peer (or the explicit `hosts` set),
  * groups the rows to distinct machines, then:
  *
- *   - exactly one machine  → delegate rendering to that peer via `runOnPeer`
+ *   - exactly one logical session → delegate rendering to one peer via `runOnPeer`
  *     (its transcript and agent binary live there — a local `--host` hop would
  *     re-discover locally and dead-end), returning `'rendered'`.
- *   - more than one machine → print the conflict with machine labels so the user
- *     can disambiguate with `--device <host>`, returning `'conflict'`.
+ *   - more than one logical session → print every full-id candidate with its
+ *     machine labels, returning `'conflict'`.
  *   - none                 → `'not-found'`, letting the caller print the local
  *     "no session on this machine" message.
  *
- * No fuzzy/content fallback: the sweep forwards a UUID, each peer id-resolves it,
- * and `fleetHitsById` drops anything that isn't an exact id match.
+ * No fuzzy/content fallback: the sweep forwards the id selector and every result
+ * is resolved through `resolveSessionQuery`, the same id-only resolver used locally.
  */
-export declare function resolveSessionAcrossFleet(id: string, mode: ViewMode, hosts?: string[], deps?: FleetResolveDeps): Promise<'rendered' | 'conflict' | 'not-found'>;
+export declare function resolveSessionAcrossFleet(query: string, mode: ViewMode, hosts?: string[], deps?: FleetResolveDeps): Promise<'rendered' | 'conflict' | 'not-found'>;
 /** Register the `agents sessions` command with all its options and help text. */
 export declare function registerSessionsCommands(program: Command): void;
 export {};