@mattstack/rt-client 0.16.0 → 0.19.1

package/dist/client.d.ts

@@ -195,3 +195,36 @@ 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"]>>;
+/** A cold ensure spawns `herdr server`, waits out bg-service's own 10s
+    readyTimeoutMs, then runs its parity probes sequentially -- the 15s
+    default budget every other rt-client call inherits can lose that race,
+    so this is the one wrapper that widens its own. */
+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

@@ -128,6 +128,7 @@ export interface GateAnswer {
     }>;
     by: string;
     answeredAt: number;
+    overridden?: boolean;
 }
 export interface GateRow {
     id: string;
@@ -143,6 +144,8 @@ export interface GateRow {
     parkedAt: number | null;
     closedAt: number | null;
     closedReason: "abandoned" | "superseded" | "pruned" | null;
+    /** Set only when `closedReason` is "superseded": the id of the gate that superseded this one. */
+    supersededBy: string | null;
     agent: string | null;
     pane: string | null;
     nudge: {
@@ -153,6 +156,8 @@ export interface GateRow {
         at: number;
     } | null;
     released: boolean;
+    owner: string | null;
+    escalatedAt: number | null;
 }
 export interface GateSubscription {
     id: string;
@@ -164,6 +169,66 @@ export interface GateSubscription {
         at: number;
     } | null;
     dead: boolean;
+    scope: "prefix" | "owner";
+    ownerRef: string | null;
+}
+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;
+    /** Whether the shepherd session's own inbox socket is reachable right now, probed fresh on every status call -- honest liveness, not the subscription row's bookkeeping. */
+    push: {
+        state: "reachable" | "unreachable";
+        lastDelivery: GateSubscription["lastDelivery"];
+    };
 }
 /**
  * Duplicated shape on purpose, same reasoning as EventsBusEvent above:
@@ -285,9 +350,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;
@@ -559,9 +628,12 @@ export interface WorktreeCreateData {
 }
 export interface WorktreeDisposeData {
     disposed: string[];
+    /** `detail` is set only for a refusal whose bare `reason` code can't name
+        what a human needs to act on it (the run id and stage for `running-run`). */
     refused: Array<{
         tree: string;
         reason: string;
+        detail?: string;
     }>;
     recoverable: Array<{
         tree: string;
@@ -587,6 +659,7 @@ export interface WorktreeAdoptData {
     refused: Array<{
         tree: string;
         reason: string;
+        detail?: string;
     }>;
 }
 /** Duplicated shape on purpose: mirrors lib/endpoint/store.ts's EndpointClaim. */
@@ -1019,6 +1092,10 @@ export interface Commands {
             workspace?: string;
             tab?: string;
             extraArgs?: string;
+            env?: Record<string, string>;
+            herdrSocket?: string;
+            handle?: string;
+            bg?: boolean;
         };
         data: AgentRecord;
     };
@@ -1108,9 +1185,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;
     };
@@ -1304,12 +1384,21 @@ export interface Commands {
      * `conflict:true` and the WINNING row, so every consumer gets the winner
      * typed with no envelope hacks. `ok:false` is reserved for
      * not-found/closed/validation failures.
+     *
+     * Owner enforcement adds two structured rejections beyond the plain
+     * `{ok:false, error:string}` shape (see `GateAnswerResult` in
+     * `lib/daemon/handlers/gate.ts`): a herd-owned gate answered by anyone but
+     * the owning shepherd's session, the answering pane, or an explicit human
+     * `override` returns `{ok:false, error:"owned-by", owner}`; a closed gate
+     * returns `{ok:false, error:"gate-closed", reason, supersededBy?}`.
      */
     "gate:answer": {
         payload: {
             id: string;
             answers: GateAnswer["answers"];
             by: string;
+            session?: string;
+            override?: boolean;
         };
         data: {
             row: GateRow;
@@ -1366,6 +1455,8 @@ export interface Commands {
         payload: {
             subjectPrefix: string;
             session: string;
+            scope?: "owner";
+            ownerRef?: string;
         };
         data: {
             id: string;
@@ -1390,6 +1481,180 @@ 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"; /** Advisory: a resumable run can still write into this job's worktree after close, so this warns rather than blocking. */
+            warning?: string;
+        };
+    };
+    /** `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). */
@@ -1488,6 +1753,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 { 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, } 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";