@mattstack/rt-client 0.15.1 → 0.19.0

package/dist/client.d.ts

@@ -195,3 +195,33 @@ export declare function gateClose(a: Commands["gate:close"]["payload"], o?: RtCl
 export declare function gateSubscribe(a: Commands["gate:subscribe"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["gate:subscribe"]["data"]>>;
 export declare function gateUnsubscribe(a: Commands["gate:unsubscribe"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["gate:unsubscribe"]["data"]>>;
 export declare function gateSubscriptions(a: Commands["gate:subscriptions"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["gate:subscriptions"]["data"]>>;
+/** Provisions the room, workspace and subscription before it answers, so it
+    gets the same 60s budget as a spawn rather than the 10s default. */
+export declare function herdStart(a: Commands["herd:start"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:start"]["data"]>>;
+/** Worktree provision plus agent launch; the 10s default cannot cover it. */
+export declare function herdSpawn(a: Commands["herd:spawn"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:spawn"]["data"]>>;
+export declare function herdAsk(a: Commands["herd:ask"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:ask"]["data"]>>;
+export declare function herdMilestone(a: Commands["herd:milestone"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:milestone"]["data"]>>;
+export declare function herdAnswer(a: Commands["herd:answer"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:answer"]["data"]>>;
+/** A disposable job's report also closes its pane, one herdr CLI call under the runner's own 15s budget. */
+export declare function herdReport(a: Commands["herd:report"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:report"]["data"]>>;
+export declare function herdGates(a: Commands["herd:gates"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:gates"]["data"]>>;
+export declare function herdStatus(a: Commands["herd:status"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:status"]["data"]>>;
+export declare function herdList(a?: Commands["herd:list"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:list"]["data"]>>;
+export declare function herdResume(a: Commands["herd:resume"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:resume"]["data"]>>;
+/** Closes a herdr pane, one CLI call under the runner's own 15s budget. */
+export declare function herdClose(a: Commands["herd:close"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:close"]["data"]>>;
+/** Three sequential herdr CLI calls (pane get, tab create, pane run), each under the runner's own 15s budget. */
+export declare function herdAttend(a: Commands["herd:attend"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:attend"]["data"]>>;
+/** Closes panes, disposes worktrees and archives the room in one pass; the
+    worktree disposals alone can outrun a spawn's budget. */
+export declare function herdWrapUp(a: Commands["herd:wrap-up"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:wrap-up"]["data"]>>;
+/** Runs `herdr session stop`, one CLI call under the runner's own 15s budget. */
+export declare function herdStopHidden(_a: Commands["herd:stop-hidden"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["herd:stop-hidden"]["data"]>>;
+/** May spawn `herdr server` and wait for it to bind; budget matches bg-service's own 10s readyTimeoutMs plus margin. */
+export declare function bgEnsure(a?: Commands["bg:ensure"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["bg:ensure"]["data"]>>;
+/** Never ensures/spawns; a plain read of the current state. */
+export declare function bgStatus(o?: RtClientOptions): Promise<RtResponse<Commands["bg:status"]["data"]>>;
+/** Asks the daemon to stop the background server; refuses (ok:false) while any claim is live, naming the owners. */
+export declare function bgStop(o?: RtClientOptions): Promise<RtResponse<Commands["bg:stop"]["data"]>>;
+export declare function bgRelease(a: Commands["bg:release"]["payload"], o?: RtClientOptions): Promise<RtResponse<Commands["bg:release"]["data"]>>;

package/dist/commands.d.ts

@@ -102,12 +102,25 @@ export interface EventsBusEvent {
     value gates-store.ts's release tracking (CAS winner or loser) reacts to. */
 export declare const GATE_BY_PANE = "pane";
 export type GateStatus = "open" | "answered" | "parked" | "closed";
+export type GateOption = string | {
+    value: string;
+    label: string;
+};
+export interface GateOrigin {
+    paneId?: string;
+    tabId?: string;
+    runId?: string;
+    worktree?: string;
+    presentation?: "form" | "wait";
+}
 export interface GateQuestion {
     id: string;
     label: string;
     multi: boolean;
-    options: string[];
+    options: GateOption[];
 }
+export declare function gateOptionValue(o: GateOption): string;
+export declare function gateOptionLabel(o: GateOption): string;
 export interface GateAnswer {
     answers: Record<string, string | string[] | {
         value: string | string[];
@@ -122,6 +135,8 @@ export interface GateRow {
     kind: string;
     questions: GateQuestion[];
     meta: Record<string, unknown> | null;
+    context?: string | null;
+    origin?: GateOrigin | null;
     status: GateStatus;
     answer: GateAnswer | null;
     openedAt: number;
@@ -150,6 +165,59 @@ export interface GateSubscription {
     } | null;
     dead: boolean;
 }
+export interface HerdInfo {
+    id: string;
+    repo: string;
+    room: string;
+    workspace: string;
+    shepherdSession: string;
+    shepherdHandle: string;
+    herdrSocket: string | null;
+    hidden: boolean;
+    status: "active" | "wrapped";
+    createdAt: number;
+    wrappedAt: number | null;
+}
+/** A herd row as `herd:list` reports it: the registry row plus how many jobs hang off it. */
+export interface HerdListRow extends HerdInfo {
+    jobs: number;
+}
+export interface HerdJobInfo {
+    herd: string;
+    name: string;
+    worktree: string;
+    branch: string | null;
+    tree: string | null;
+    pane: string | null;
+    agentSession: string | null;
+    agentId: string | null;
+    handle: string;
+    status: "spawning" | "active" | "at-gate" | "at-milestone" | "done" | "closed" | "crashed";
+    disposable: boolean;
+    lastGate: string | null;
+    lastReport: number | null;
+    createdAt: number;
+    updatedAt: number;
+}
+/** `lastGateStatus`/`lastGateDelivery` come from the job's `lastGate` row: an `answered` gate whose delivery is `dead-pane` is the "answered, worker not woken" case the shepherd must act on. */
+export interface HerdStatusData {
+    herd: HerdInfo;
+    jobs: Array<HerdJobInfo & {
+        openGate: string | null;
+        paneStatus: string | null;
+        lastGateStatus: GateStatus | null;
+        lastGateDelivery: "delivered" | "dead-pane" | null;
+    }>;
+    unread: number;
+    lifecycleConnected: boolean;
+    hiddenUp: boolean | null;
+    /** The shepherd session's own `herd:<id>/` subscription row, or null when none is live. */
+    subscription: {
+        id: string;
+        dead: boolean;
+        lastDelivery: GateSubscription["lastDelivery"];
+    } | null;
+}
 /**
  * Duplicated shape on purpose, same reasoning as EventsBusEvent above:
  * these mirror lib/state/chat-store.ts's types, which rt-client cannot
@@ -270,9 +338,13 @@ export interface PaneSendResult {
     delivered: PaneDelivery;
     reason?: string;
 }
+/** `attendTab` is set only for a `bg:` ref: focus for a background pane IS
+    the attend flow (a visible tab running a terminal attach), and this is
+    that tab's id. */
 export interface PaneFocusResult {
     paneId: string;
     focused: boolean;
+    attendTab?: string;
 }
 export type Attention = {
     needs: boolean;
@@ -1004,6 +1076,10 @@ export interface Commands {
             workspace?: string;
             tab?: string;
             extraArgs?: string;
+            env?: Record<string, string>;
+            herdrSocket?: string;
+            handle?: string;
+            bg?: boolean;
         };
         data: AgentRecord;
     };
@@ -1093,9 +1169,12 @@ export interface Commands {
         };
         data: PaneSendResult;
     };
+    /** `callerWorkspace` (HERDR_WORKSPACE_ID) is required only for a `bg:`
+        ref, whose focus opens an attend tab in the caller's own workspace. */
     "pane:focus": {
         payload: {
             paneId: string;
+            callerWorkspace?: string;
         };
         data: PaneFocusResult;
     };
@@ -1276,6 +1355,8 @@ export interface Commands {
             nudge?: {
                 session: string;
             };
+            context?: string;
+            origin?: GateOrigin;
         };
         data: {
             id: string;
@@ -1373,6 +1454,179 @@ export interface Commands {
             subscriptions: GateSubscription[];
         };
     };
+    "herd:start": {
+        payload: {
+            name: string;
+            repo: string;
+            session: string;
+            hidden?: boolean;
+        };
+        data: {
+            herd: string;
+            room: string;
+            workspace: string;
+            subscription: string;
+            handle: string;
+            hidden: boolean;
+        };
+    };
+    "herd:resume": {
+        payload: {
+            herd: string;
+            session: string;
+        };
+        data: {
+            subscription: string;
+            gates: GateRow[];
+            unread: number;
+            status: HerdStatusData;
+            handle: string;
+        };
+    };
+    "herd:status": {
+        payload: {
+            herd: string;
+        };
+        data: HerdStatusData;
+    };
+    /** Active herds only unless `all`, so a shepherd's "which herd am I on" question has one answer. */
+    "herd:list": {
+        payload: {
+            all?: boolean;
+        };
+        data: {
+            herds: HerdListRow[];
+        };
+    };
+    "herd:close": {
+        payload: {
+            herd: string;
+            job: string;
+        };
+        data: {
+            job: string;
+            status: "closed";
+        };
+    };
+    /** `brief` is the brief TEXT, not a path: the CLI reads the file. It is stored at `<jobsRoot>/<herd>/<job>/job.md`, so a respawn with `dir` and no `brief` reads it back. */
+    "herd:spawn": {
+        payload: {
+            herd: string;
+            job: string;
+            brief?: string;
+            dir?: string;
+            model?: string;
+            effort?: string;
+            account?: string;
+            disposable?: boolean;
+        };
+        data: {
+            herd: string;
+            job: string;
+            pane: string;
+            worktree: string;
+            branch: string | null;
+            tree: string | null; /** null = no provisioning ran (--dir); false = cold create, worth announcing. */
+            wasOnDeck: boolean | null;
+            agentId: string;
+            sessionId: string;
+            handle: string;
+        };
+    };
+    "herd:gates": {
+        payload: {
+            herd: string;
+        };
+        data: {
+            gates: GateRow[];
+        };
+    };
+    "herd:ask": {
+        payload: {
+            herd: string;
+            job: string;
+            session: string;
+            pane?: string;
+            questions: GateQuestion[];
+            context?: string;
+        };
+        data: {
+            gate: string;
+        };
+    };
+    "herd:milestone": {
+        payload: {
+            herd: string;
+            job: string;
+            session: string;
+            pane?: string;
+            artifact: string;
+            summary?: string;
+        };
+        data: {
+            gate: string;
+            message: number;
+        };
+    };
+    "herd:answer": {
+        payload: {
+            gate: string;
+        };
+        data: {
+            gate: string;
+            status: GateStatus;
+            answer: GateAnswer | null;
+            closedReason: GateRow["closedReason"];
+        };
+    };
+    "herd:report": {
+        payload: {
+            herd: string;
+            job: string;
+            body: string;
+        };
+        data: {
+            message: number;
+        };
+    };
+    /** `callerWorkspace` is the attending session's own HERDR_WORKSPACE_ID: the attached tab opens there, not in the herd's workspace. */
+    "herd:attend": {
+        payload: {
+            herd: string;
+            job: string;
+            callerWorkspace: string;
+        };
+        data: {
+            tab: string;
+            pane: string;
+        };
+    };
+    "herd:stop-hidden": {
+        payload: Record<string, never>;
+        data: {
+            stopped: boolean;
+        };
+    };
+    "herd:wrap-up": {
+        payload: {
+            herd: string;
+            closePanes?: boolean;
+            dispose?: string[];
+            deleteJobDirs?: boolean;
+            archiveRoom?: boolean;
+        };
+        data: {
+            closed: string[];
+            workspaceClosed: boolean;
+            disposed: string[];
+            refused: Array<{
+                tree: string;
+                reason: string;
+            }>;
+            deletedJobDirs: boolean;
+            archived: boolean;
+        };
+    };
     /** Wire reply on success is always `{ok:true, repaired}` (no `data`
      *  wrapper) — `data` here documents the extra field the same way PingData
      *  does for `ping`, not the literal wire nesting (R3). */
@@ -1471,6 +1725,46 @@ export interface Commands {
         };
         data: WorktreeAdoptData;
     };
+    "bg:ensure": {
+        payload: {
+            claim?: string;
+        };
+        data: {
+            socket: string;
+            started: boolean;
+            parity: {
+                ok: boolean;
+                drift: string[];
+            } | null;
+        };
+    };
+    "bg:status": {
+        payload: Record<string, never>;
+        data: {
+            up: boolean;
+            socket: string;
+            claims: Array<{
+                owner: string;
+                pane: string | null;
+                createdAt: number;
+            }>;
+        };
+    };
+    /** Rejects (`ok:false`) naming every live claim owner while any claim is held. */
+    "bg:stop": {
+        payload: Record<string, never>;
+        data: {
+            stopped: boolean;
+        };
+    };
+    "bg:release": {
+        payload: {
+            claim: string;
+        };
+        data: {
+            released: boolean;
+        };
+    };
 }
 export type CommandName = keyof Commands;
 export declare const COMMAND_NAMES: readonly CommandName[];

package/dist/index.d.ts

@@ -1,14 +1,16 @@
 export { rtCommand, DEFAULT_SOCK } from "./transport.ts";
 export type { RtResponse, RtClientOptions } from "./transport.ts";
-export { readProjectMRs, readDiscussions, readMrsByBranch, readBranchCache, resolveForgeToken, listRuns, getRun, abandonRun, chatJoin, chatLeave, chatAck, chatClaim, chatRelease, chatPost, chatRead, chatRooms, chatWho, chatMark, chatMessages, chatSignIn, chatSignOut, chatAway, chatBack, chatBuddies, chatDm, chatArchive, chatDmOpen, eventsHead, eventsEmit, eventsWait, eventsList, agentStart, agentResume, agentGet, agentList, paneList, panePeek, paneSpawn, paneAccounts, paneDirectories, chatInvite, paneSend, paneFocus, gateOpen, gateAnswer, gateWait, gateList, gatePark, gateClose, gateSubscribe, gateUnsubscribe, gateSubscriptions, } from "./client.ts";
-export { COMMAND_NAMES, GATE_BY_PANE } from "./commands.ts";
-export type { Discussion, DemandDecl, ProjectMRsScope, ProjectMRsData, DiscussionsData, MrByBranchEntry, MrByBranchData, BranchEnrichment, Commands, CommandName, ForgeSlug, ForgeTokenData, Attention, RunSummary, RunStageRow, RunFieldRow, RunDecisionRow, RunDetail, WakeMode, ChatMember, ChatMessage, ChatClaimOutcome, RoomSummary, BuddyStatus, PresenceRow, AgentRecord, AgentSurface, AgentStatus, ChatPane, PaneAccount, PaneDirectory, InviteResult, PaneDelivery, PaneSendResult, PaneFocusResult, GateStatus, GateQuestion, GateAnswer, GateRow, GateSubscription, } from "./commands.ts";
+export { readProjectMRs, readDiscussions, readMrsByBranch, readBranchCache, resolveForgeToken, listRuns, getRun, abandonRun, chatJoin, chatLeave, chatAck, chatClaim, chatRelease, chatPost, chatRead, chatRooms, chatWho, chatMark, chatMessages, chatSignIn, chatSignOut, chatAway, chatBack, chatBuddies, chatDm, chatArchive, chatDmOpen, eventsHead, eventsEmit, eventsWait, eventsList, agentStart, agentResume, agentGet, agentList, paneList, panePeek, paneSpawn, paneAccounts, paneDirectories, chatInvite, paneSend, paneFocus, gateOpen, gateAnswer, gateWait, gateList, gatePark, gateClose, gateSubscribe, gateUnsubscribe, gateSubscriptions, herdStart, herdSpawn, herdAsk, herdMilestone, herdAnswer, herdReport, herdGates, herdStatus, herdList, herdResume, herdClose, herdAttend, herdWrapUp, herdStopHidden, bgEnsure, bgStatus, bgStop, bgRelease, } from "./client.ts";
+export { COMMAND_NAMES, GATE_BY_PANE, gateOptionValue, gateOptionLabel } from "./commands.ts";
+export type { Discussion, DemandDecl, ProjectMRsScope, ProjectMRsData, DiscussionsData, MrByBranchEntry, MrByBranchData, BranchEnrichment, Commands, CommandName, ForgeSlug, ForgeTokenData, Attention, RunSummary, RunStageRow, RunFieldRow, RunDecisionRow, RunDetail, WakeMode, ChatMember, ChatMessage, ChatClaimOutcome, RoomSummary, BuddyStatus, PresenceRow, AgentRecord, AgentSurface, AgentStatus, ChatPane, PaneAccount, PaneDirectory, InviteResult, PaneDelivery, PaneSendResult, PaneFocusResult, GateStatus, GateOption, GateOrigin, GateQuestion, GateAnswer, GateRow, GateSubscription, HerdInfo, HerdListRow, HerdJobInfo, HerdStatusData, } from "./commands.ts";
 export { subscribe, createRelay, DEFAULT_WS_URL } from "./relay.ts";
 export type { RelayEventType } from "./relay.ts";
 export { daemonHealth } from "./health.ts";
 export { repoNameForPath } from "./repos.ts";
 export { decidePlacement, openSmartPane } from "./smart-pane.ts";
 export type { Placement, PlacementOpts, HerdrCall } from "./smart-pane.ts";
+export { BG_PREFIX, parsePaneRef, formatPaneRef } from "./pane-ref.ts";
+export type { PaneServer, PaneRef } from "./pane-ref.ts";
 export { getSetting, listSettings, explainSetting, expandVariables, SCOPE_ORDER, setSettingsWarnSink } from "./settings/resolve.ts";
 export type { Scope, Provenance, ResolveOpts, Resolved, InvalidScope, ListedSetting, ExplainRow, ExpandCtx, } from "./settings/resolve.ts";
 export { setSetting, unsetSetting } from "./settings/write.ts";