@bridge4dev/runner 0.11.0

package/dist/supervisor.d.ts

@@ -0,0 +1,216 @@
+import { JournalStore } from './journal.js';
+import { selfUpdate, type SelfUpdateOutcome } from './self-update.js';
+import type { RunnerWsClient } from './ws-client.js';
+import type { SessionDescriptor } from './protocol.js';
+import type { AgentAdapter } from './adapters/types.js';
+import type { McpConfig } from './adapters/types.js';
+export interface SupervisorOptions {
+    adapters: Partial<Record<'CLAUDE' | 'CODEX', AgentAdapter>>;
+    mcp?: McpConfig;
+    journals?: JournalStore;
+    /**
+     * The API this runner is paired with — the only origin an update package may
+     * come from, and where message attachments are fetched from. Absent means the
+     * `self_update` command is refused outright and attachments cannot be pulled.
+     */
+    apiUrl?: string;
+    /** This server's runner token — used to fetch message attachments. */
+    runnerToken?: string;
+    /** Test seam for the `self_update` command. */
+    selfUpdate?: typeof selfUpdate;
+    /**
+     * Called after a successful update, once the reply is on the wire. The daemon
+     * exits here and systemd starts the new build; without a handler the runner
+     * reports the new version only after the next manual restart.
+     */
+    onRestartRequested?: (outcome: SelfUpdateOutcome) => void;
+    /**
+     * Local ceiling on concurrent agent processes, from the runner's own config
+     * (layer 1). When set it wins over the API's number if it is stricter — the
+     * machine's owner decides how much of their machine an agent fleet may take.
+     */
+    maxSessionsLimit?: number;
+}
+export declare class Supervisor {
+    private readonly ws;
+    private readonly opts;
+    private static readonly ORPHAN_MESSAGE_CAP;
+    /** A finished session's journal is kept this long for a late reconnect. */
+    private static readonly JOURNAL_TTL_MS;
+    /** Backstop: events the API will never accept must not pile up forever. */
+    private static readonly JOURNAL_HARD_TTL_MS;
+    private readonly sessions;
+    /**
+     * How many agents may run at once, as told by the API (session 8). Starts at
+     * 1 so a runner talking to an API that predates the field behaves exactly as
+     * it did before: one agent, others parked.
+     */
+    private serverMaxSessions;
+    /** Messages for sessions this runner does not track yet, keyed by session. */
+    private readonly orphanMessages;
+    private readonly journals;
+    private readonly authRelay;
+    /** Serialises repo-mutating git commands per workspace repo (QA-99 MAJOR-1). */
+    private readonly repoLocks;
+    /** An update is installing right now — a second one would fight it. */
+    private selfUpdateInFlight;
+    constructor(ws: RunnerWsClient, opts: SupervisorOptions);
+    get activeSessionIds(): string[];
+    private onFrame;
+    private startSession;
+    /**
+     * Spin the adapter up — for a fresh session, a resume-on-next-message, or a
+     * free CHAT session with no prompt at all (the agent boots, reports its
+     * capabilities and waits for the first message).
+     *
+     * Returns whether an agent process actually started: a caller holding a user
+     * message needs to know, because a refused launch means the message has to
+     * stay queued rather than be marked delivered (session 9).
+     */
+    private launchAgent;
+    /** Warn the user when this share of the budget is gone. */
+    private static readonly BUDGET_WARN_RATIO;
+    /** Is the agent actually working right now (i.e. should the clock run)? */
+    private static isBillable;
+    /**
+     * Start or stop the budget clock to match the session's current state.
+     *
+     * MUST be called from every place that changes `lastReported` — not just
+     * reportStatus. `sendEvent` sets WAITING_PERMISSION directly and the API
+     * infers WAITING_INPUT from a `question` event, and those two states are
+     * exactly where an ask-mode session spends its time waiting for a human.
+     */
+    private syncBudgetClock;
+    /**
+     * Agent time spent so far, INCLUDING the slice currently in flight. Reading
+     * `activeMs` alone made every RUNNING→RUNNING re-report (a follow-up message,
+     * a reconnect) re-arm the timer from a stale figure, so a busy session could
+     * slide past its limit indefinitely.
+     */
+    private static spentMs;
+    /** Total budget in ms, or null when the workspace has no time limit. */
+    private budgetMsFor;
+    private armBudgetTimers;
+    private clearBudgetTimers;
+    /**
+     * The agent has worked for as long as it was allowed. Stop it cleanly and
+     * keep everything needed to pick it back up — this is NOT a failure, and
+     * reporting it as one is what made five of the first twelve prod sessions
+     * look broken.
+     */
+    private pauseForBudget;
+    private pumpEvents;
+    /**
+     * Deliver messages that were held because every slot was taken.
+     *
+     * Called whenever an agent process ends. Without it a message typed into a
+     * parked session while the server was full would sit in the queue until the
+     * next reconnect: the user would see their own bubble in the feed and no
+     * answer, which is the worst possible reading of "the server is busy".
+     */
+    private drainSessionsWaitingForCapacity;
+    /** The ceiling actually in force: the API's number, lowered by local config. */
+    get maxSessions(): number;
+    /**
+     * Adopt a ceiling announced by the API.
+     *
+     * `undefined` means "this API does not know about the field" — only then do
+     * we fall back to the historical single slot. A number that is merely out of
+     * range is CLAMPED, never treated as absent: silently collapsing a server to
+     * one agent because of a typo in a config field is a much worse failure than
+     * capping it (QA-102 MINOR-5).
+     */
+    private static readonly MAX_SESSIONS_HARD_CAP;
+    private setMaxSessions;
+    /**
+     * Sessions holding a slot right now. A session already asked to stop or park
+     * does not count: its process is winding down and its `session` handle stays
+     * set until `pumpEvents` sees the stream end — waiting for that would make
+     * parking look like it freed nothing.
+     */
+    private liveSessionCount;
+    /**
+     * Make room for one more agent process.
+     *
+     * Up to `maxSessions` agents run side by side, each in its own worktree. Over
+     * that, idle-but-resumable sessions (REVIEW / WAITING_INPUT) are parked —
+     * their provider session survives on disk and relaunches on the next message,
+     * so parking costs context nothing. Only mid-turn sessions (RUNNING /
+     * WAITING_PERMISSION) genuinely hold a slot; when they fill the ceiling this
+     * returns false and the caller tells the user rather than thrashing.
+     */
+    private ensureCapacity;
+    /** Idle after a finished turn — safe to kill the process and resume later. */
+    private isParkable;
+    private park;
+    private forwardEvent;
+    private onUserMessage;
+    /**
+     * Run delivery work for one session, strictly after whatever is already
+     * queued for it. Order is the whole point: two messages typed seconds apart
+     * must reach the agent in the order they were typed, however long the first
+     * one's attachments take to download.
+     */
+    private enqueueDelivery;
+    /** Did this session go away (stop, teardown, resume) while we were awaiting? */
+    private isStale;
+    /**
+     * Bring the user's files onto this machine and fold their paths into the
+     * prompt. Returns the text unchanged when there is nothing to fetch.
+     *
+     * A failure here never costs the message: the agent still gets what the user
+     * typed, plus a note naming the files that did not make it.
+     */
+    private materializeAttachments;
+    /**
+     * Hand a message to the agent, or hold it if there is nowhere to put it yet.
+     *
+     * `held` carries the journal records this text was built from, so a delivery
+     * resolves them and a refusal puts exactly those records back in the queue —
+     * the message is retired from disk only once an agent has it.
+     */
+    private deliverMessage;
+    /**
+     * Deliver messages that raced session start (already journaled).
+     *
+     * Async since session 10: a held message may carry files, and this is the
+     * first point at which the worktree they belong in certainly exists. Callers
+     * fire and forget — a failure here is logged, and the records stay on disk.
+     */
+    private flushPendingMessages;
+    /** Stop the current turn without ending the session (VS-Code-style Stop). */
+    private interruptSession;
+    /** Live model / interaction-mode switch (persisted for the next relaunch). */
+    private applySettings;
+    private stopSession;
+    private reconcile;
+    /**
+     * Housekeeping for the journal directory. Safe to call any time: live
+     * sessions are skipped and a journal still holding unacked events survives
+     * until the hard expiry.
+     */
+    pruneJournals(): void;
+    private runCommand;
+    /**
+     * Serialise commands that mutate the shared workspace repo. Two sessions of
+     * one workspace can hit «Применить» at the same moment; interleaved
+     * `merge --squash` + `commit` would land both change sets in one commit and
+     * mark the other session failed (QA-99 MAJOR-1).
+     */
+    private withRepoLock;
+    /**
+     * Same lock, keyed by the shared repository rather than by whichever path the
+     * caller happened to have. A worktree commit and a workspace squash-merge
+     * touch one repo, so they must take one key (see `repoKeyFor`).
+     */
+    private withRepoLockFor;
+    /** A session actively mid-turn in this worktree — git writes must wait. */
+    private isWorktreeBusy;
+    private static readonly EVENT_PAYLOAD_CAP;
+    private sendEvent;
+    private reportStatus;
+    /** Graceful daemon shutdown: kill agents, keep sessions resumable server-side. */
+    shutdown(): void;
+}
+export declare function composeInitialPrompt(descriptor: SessionDescriptor): string;
+//# sourceMappingURL=supervisor.d.ts.map