@datalayer/agent-runtimes 1.5.70 → 1.5.71

package/lib/portable/sessionList.d.ts

@@ -0,0 +1,426 @@
+/**
+ * The person's sessions in one list (VSCODE VS-04, VS-12; DESKTOP DK-09,
+ * DK-25): on Datalayer (the record, through ai-agents) and on this machine
+ * (a local runtime's `GET /api/v1/apps/sessions`, which lists every local
+ * session since the file store is one) — grouped by place then application,
+ * each row as `loop sessions list` prints it (title, state with the turn
+ * phase, agent and harness, turns, lineage, *not held*), filtered by
+ * application, state and title, the archived hidden; the person's team runs
+ * with their seats.
+ *
+ * The rule of two holders (DESKTOP D-12): a session `open` on this machine
+ * and held by none of the host's own runtimes is open in another host (VS
+ * Code, a terminal) and is not resumed from here until it is `paused`.
+ *
+ * Pure: no host API, no network. The host fetches and draws; the verbs are
+ * the chat's (`loop.session.action`).
+ *
+ * @module portable/sessionList
+ */
+import { type SessionRow, type SessionState } from './activity';
+/** Where a session runs: Datalayer's record, or a local runtime of one folder. */
+export type SessionPlace = {
+    kind: 'datalayer';
+} | {
+    kind: 'local';
+    folder: string;
+    folderName: string;
+    url: string;
+};
+/**
+ * One key per place.
+ *
+ * @param place - The place.
+ *
+ * @returns `datalayer`, or `local:<folder>`.
+ */
+export declare function placeKey(place: SessionPlace): string;
+/**
+ * The place as a list labels it.
+ *
+ * @param place - The place.
+ *
+ * @returns *On Datalayer*, or *On this machine — <folder>*.
+ */
+export declare function placeLabel(place: SessionPlace): string;
+/**
+ * Where a session is listed on Datalayer: the record, through ai-agents, for its opener.
+ *
+ * @param aiAgentsUrl - ai-agents' base URL.
+ * @param openedBy - The person's uid.
+ *
+ * @returns The URL.
+ */
+export declare function datalayerSessionsUrl(aiAgentsUrl: string, openedBy: string): string;
+/** The session API's list route on a runtime. */
+export declare const LOCAL_SESSIONS_PATH = "/api/v1/apps/sessions";
+/** The application a session belongs to, as the list groups it. */
+export interface SessionApplication {
+    /** The application's uid, else its id on the runtime, else empty. */
+    key: string;
+    /** Its name, else its id, else its uid. */
+    name: string;
+}
+/** A session as listed, with the application it belongs to and its folder when the row names one. */
+export interface ListedSession {
+    row: SessionRow;
+    application: SessionApplication;
+    /**
+     * The folder a local harness session runs in — the row's `workspace`
+     * (agent-runtimes 1.5.71, DESKTOP DK-26), else its `harness_session`'s;
+     * empty when the row names none.
+     */
+    workspace: string;
+}
+/**
+ * The application of a raw session row: ai-agents' rows carry `app_uid`;
+ * a runtime's rows carry `app: {id, name}` and `instance.app_uid`.
+ *
+ * @param raw - The row as answered.
+ *
+ * @returns The application's key and name.
+ */
+export declare function applicationOf(raw: Record<string, unknown>): SessionApplication;
+/**
+ * The folder a raw row names for its harness session: `workspace` on the
+ * row (the list's rows since 1.5.71), else `harness_session.workspace`
+ * (`GET /sessions/{uid}` on a runtime that holds it).
+ *
+ * @param raw - The row as answered.
+ *
+ * @returns The folder, or empty.
+ */
+export declare function workspaceOf(raw: Record<string, unknown>): string;
+/**
+ * One listed session from a raw row: refused by `sessionRowOf` when it is
+ * malformed, never defaulted.
+ *
+ * @param raw - The row as answered.
+ *
+ * @returns The session with its application and folder.
+ */
+export declare function listedSessionOf(raw: Record<string, unknown>): ListedSession;
+/**
+ * The sessions a list route answered (`{sessions, has_more}`), each with its
+ * application; a row whose state is none of the three is refused by
+ * `sessionRowOf`, never defaulted.
+ *
+ * @param body - The route's answer.
+ *
+ * @returns The sessions, in the route's order.
+ *
+ * @throws Error when the answer lists no sessions, or a row is malformed.
+ */
+export declare function listedSessionsOf(body: unknown): ListedSession[];
+/** What the list is narrowed to; empty strings narrow nothing. */
+export interface SessionFilter {
+    /** An application's key or name, matched case-insensitively. */
+    app: string;
+    /** One state, or any. */
+    state: SessionState | '';
+    /** A piece of the title, matched case-insensitively. */
+    title: string;
+    /** One place's kind, or any. */
+    place?: SessionPlace['kind'] | '';
+}
+/** Nothing narrowed. */
+export declare const NO_FILTER: SessionFilter;
+/**
+ * The sessions the filter keeps: the archived never, then by application,
+ * state and title.
+ *
+ * @param sessions - The sessions listed.
+ * @param filter - What to keep.
+ *
+ * @returns The sessions kept, in order.
+ */
+export declare function filterSessions<T extends ListedSession>(sessions: readonly T[], filter: SessionFilter): T[];
+/**
+ * The filter in words, for a view's description.
+ *
+ * @param filter - The filter.
+ *
+ * @returns *application: x · state: open · title: y*, or empty when nothing is narrowed.
+ */
+export declare function filterSaid(filter: SessionFilter): string;
+/** One application's sessions under a place. */
+export interface SessionGroup<T extends ListedSession = ListedSession> {
+    application: SessionApplication;
+    sessions: T[];
+}
+/**
+ * The sessions grouped by application, in the order the applications first appear.
+ *
+ * @param sessions - The sessions kept.
+ *
+ * @returns The groups.
+ */
+export declare function groupByApplication<T extends ListedSession>(sessions: readonly T[]): SessionGroup<T>[];
+/**
+ * A row's label: its title, else its uid.
+ *
+ * @param row - The session.
+ *
+ * @returns The label.
+ */
+export declare function rowLabel(row: SessionRow): string;
+/**
+ * A row's description, as `loop sessions list` prints it: the state with the
+ * turn phase, the agent with its harness, the turns, the lineage, *not held*
+ * for an open session whose runtime is gone.
+ *
+ * @param row - The session.
+ *
+ * @returns The parts joined with ` · `.
+ */
+export declare function rowDescription(row: SessionRow): string;
+/**
+ * The icon of a row's state, as a codicon id: the turn phase as its icon when open.
+ *
+ * @param row - The session.
+ *
+ * @returns A codicon id.
+ */
+export declare function stateIconOf(row: Pick<SessionRow, 'state' | 'turn'>): string;
+/**
+ * The context value a host's menus match: `session-<state>-<place kind>`.
+ *
+ * @param row - The session.
+ * @param place - Its place.
+ *
+ * @returns E.g. `session-paused-local`.
+ */
+export declare function contextValueOf(row: Pick<SessionRow, 'state'>, place: SessionPlace): string;
+/**
+ * The one row a place that did not answer shows.
+ *
+ * @param place - The place.
+ * @param message - What went wrong, the server's words.
+ *
+ * @returns The sentence.
+ */
+export declare function placeProblemSentence(place: SessionPlace, message: string): string;
+/** The sentence under a place with no session. */
+export declare const NOTHING_LISTED = "No session yet.";
+/** The sentence under *On Datalayer* while signed out. */
+export declare const SIGNED_OUT_SENTENCE = "Sign in to Datalayer to see your sessions there.";
+/**
+ * The sentence under *On this machine* while no local runtime runs.
+ *
+ * @param howToStart - How the host starts one: *Datalayer: Start the local runtime*, *File → Work in a folder…*.
+ *
+ * @returns The sentence.
+ */
+export declare function noLocalRuntimeSentence(howToStart: string): string;
+/** The sentence under *On this machine* while no folder was ever worked in (DK-09). */
+export declare const NO_LOCAL_SESSION_YET = "No session on this machine yet \u2014 File \u2192 Work in a folder\u2026";
+/** What one place answered: its sessions, or why it did not. */
+export type SessionsOfPlace = {
+    place: SessionPlace;
+    sessions: ListedSession[];
+    problem?: undefined;
+} | {
+    place: SessionPlace;
+    sessions?: undefined;
+    problem: string;
+};
+/** A session with its place, as the merged list holds it. */
+export interface SessionEntry extends ListedSession {
+    place: SessionPlace;
+    /**
+     * The session is `open` on this machine and held by none of the host's
+     * own runtimes: open in VS Code or a terminal (D-12).
+     */
+    elsewhere: boolean;
+}
+/** A place in the merged list: its entries by application, or its problem. */
+export interface PlaceGroup {
+    place: SessionPlace;
+    groups: SessionGroup<SessionEntry>[];
+    /** The one row the place shows instead of sessions, when it has one. */
+    note: string;
+}
+/**
+ * Whether a row listed on this machine is held elsewhere: `open`, and held
+ * by none of the host's runtimes — the local runtime that listed it says
+ * `held` for its own and `false` for every other runtime's.
+ *
+ * @param row - The session.
+ * @param place - Its place.
+ *
+ * @returns Whether another host holds it.
+ */
+export declare function heldElsewhere(row: Pick<SessionRow, 'state' | 'held'>, place: SessionPlace): boolean;
+/**
+ * The two places merged into one list: each place's sessions grouped by
+ * application (the archived hidden, the filter applied), the same uid
+ * listed once per place, a place that did not answer one note, a place
+ * with nothing one note.
+ *
+ * @param places - What each place answered, Datalayer first.
+ * @param filter - What to keep.
+ *
+ * @returns The places in order, each with its groups or its note.
+ */
+export declare function mergePlaces(places: readonly SessionsOfPlace[], filter?: SessionFilter): PlaceGroup[];
+/**
+ * Where a session is, in words: *on Datalayer*, *on this machine · <folder>*,
+ * or *on this machine · folder unknown* when the row names none (DK-26).
+ *
+ * @param entry - The session with its place.
+ *
+ * @returns The sentence.
+ */
+export declare function placeSaid(entry: Pick<SessionEntry, 'place' | 'workspace'>): string;
+/** The sentence when a session held elsewhere is resumed from here (D-12). */
+export declare const ELSEWHERE_SENTENCE = "This session is open in VS Code or a terminal: pause it there to resume it here.";
+/**
+ * Why a session cannot be resumed from here, or null when it can: an
+ * `open` session held elsewhere waits until it is `paused`; an `ended`
+ * one is over; one `open` and held here is already in front.
+ *
+ * @param entry - The session with its place.
+ *
+ * @returns The sentence, or null.
+ */
+export declare function resumeRefusal(entry: Pick<SessionEntry, 'row' | 'elsewhere'>): string | null;
+/**
+ * An entry's description: the row's, then where it is, then *open in VS
+ * Code or a terminal* when it is held elsewhere.
+ *
+ * @param entry - The session with its place.
+ *
+ * @returns The parts joined with ` · `.
+ */
+export declare function entryDescription(entry: SessionEntry): string;
+/** A seat of a team run: its execution, its session when it has one. */
+export interface TeamSeat {
+    executionId: string;
+    /** The seat's id, from `team:<team>/<seat>`. */
+    seat: string;
+    /** The execution's state word. */
+    status: string;
+    /** The seat's session on Datalayer, when the control plane bound one. */
+    sessionUid: string;
+    /** The execution's status message, when it has one. */
+    statusMessage: string;
+}
+/** A team run: the root execution and its seats. */
+export interface TeamRun {
+    executionId: string;
+    team: string;
+    /** The run's state as a session's (MH-22). */
+    state: SessionState;
+    /** The execution's own state word. */
+    status: string;
+    goal: string;
+    createdAt: string;
+    updatedAt: string;
+    /** The supervisor's last line, when the execution carries one. */
+    steering: string;
+    seats: TeamSeat[];
+}
+/** A seat's agent id names its team: `team:<team>/<seat>`. */
+export declare const TEAM_PREFIX = "team:";
+/**
+ * A team run's state as a session's (MH-22): `created|assigned|running|waiting|retrying`
+ * → `open`, `paused` → `paused`, `completed|failed|cancelled|terminated` → `ended`.
+ *
+ * @param status - The execution's state word.
+ *
+ * @returns The session state.
+ *
+ * @throws Error for any other word.
+ */
+export declare function teamStateOf(status: string): SessionState;
+/**
+ * The team of an execution, from its seat's agent id; empty for none.
+ *
+ * @param agentId - The execution's agent id.
+ *
+ * @returns The team's id.
+ */
+export declare function teamOf(agentId: string): string;
+/**
+ * The seat of an execution, from its agent id; the id itself when it names no seat.
+ *
+ * @param agentId - The execution's agent id.
+ *
+ * @returns The seat.
+ */
+export declare function seatOf(agentId: string): string;
+/**
+ * The person's team runs from the control plane's executions
+ * (`GET /api/ai-agents/v1/orchestration/executions`): each root execution of
+ * a team, newest first, with its seats (the executions below it, by parent),
+ * each seat's session uid when the binding carries one.
+ *
+ * @param executions - The executions answered.
+ *
+ * @returns The runs.
+ *
+ * @throws Error for an execution without an id, or a state word that is none.
+ */
+export declare function teamRunsOf(executions: readonly unknown[]): TeamRun[];
+/**
+ * Where the control plane lists the person's executions.
+ *
+ * @param aiAgentsUrl - ai-agents' base URL.
+ *
+ * @returns The URL.
+ */
+export declare function executionsUrl(aiAgentsUrl: string): string;
+/**
+ * A team run's label: its team and its goal's first line.
+ *
+ * @param run - The run.
+ *
+ * @returns The label.
+ */
+export declare function teamRunLabel(run: TeamRun): string;
+/**
+ * A team run's description: its state, its seats, its supervisor's last line.
+ *
+ * @param run - The run.
+ *
+ * @returns The parts joined with ` · `.
+ */
+export declare function teamRunDescription(run: TeamRun): string;
+/**
+ * A seat's description: its state and whether its session can be opened.
+ *
+ * @param seat - The seat.
+ *
+ * @returns The parts joined with ` · `.
+ */
+export declare function teamSeatDescription(seat: TeamSeat): string;
+/** The sentence under *Teams* when the person has no run. */
+export declare const NO_TEAM_RUN = "No team run yet.";
+/** The sentence under *Teams* when the control plane did not answer. */
+export declare function teamsProblemSentence(message: string): string;
+/** A session as a host watches it for the person's attention: its state, its turn, where it is. */
+export interface SessionAttention {
+    /** What tells sessions apart: the session's uid, or the chat's choice. */
+    key: string;
+    title: string;
+    /** The agent bound to it. */
+    agent: string;
+    state: 'open' | 'paused' | 'ended';
+    /** The turn's phase of an open session; `''` when unknown. */
+    turn: 'idle' | 'running' | 'waiting' | '';
+    /** Whether its runtime holds it; `null` when unknown. */
+    held: boolean | null;
+    /** The chat shows it. */
+    inFront: boolean;
+    /** The first line of what it last answered, when known. */
+    lastAnswer?: string;
+}
+/**
+ * The sessions of a place as a host watches them (VS-10, DK-14): one row
+ * per session listed, by its uid, none in front — the chat says which is.
+ *
+ * @param listed - The place's sessions as read.
+ *
+ * @returns The rows.
+ */
+export declare function attentionRowsOf(listed: readonly ListedSession[]): SessionAttention[];