@hyperdrive.bot/fleet-server 0.3.99

package/dist/server/server/agent/providers/claude/background-shell-kill-keys.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Keystrokes that drive Claude Code's *own* CLI TUI (over the PTY) to stop its
+ * background work — i.e. kill a background shell from inside Claude Code, the
+ * same keys a human presses, NOT an external OS process kill.
+ *
+ * Source of truth: the Claude Code binary binds `chat:killAgents` to the chord
+ * `ctrl+x ctrl+k`, which arms a confirm ("Press ctrl+x ctrl+k again to stop
+ * background agents"); the second identical chord confirms. We replay that.
+ *
+ * Control bytes: Ctrl+X = 0x18 (CAN), Ctrl+K = 0x0B (VT).
+ *
+ * NOTE (scope): this is Claude Code's *global* stop-background-work chord — it
+ * stops the session's background work rather than one shell selected by id. The
+ * binary exposes no per-shell-selective interactive kill binding, so paseo
+ * clears its whole background-shell set for the agent after sending it.
+ *
+ * MAINTENANCE: these bytes are coupled to Claude Code's keybindings. If a
+ * future Claude Code release rebinds `chat:killAgents`, update this module
+ * (re-derive from the binary's keybinding strings).
+ */
+export declare const CTRL_X = "\u0018";
+export declare const CTRL_K = "\v";
+/** One `ctrl+x ctrl+k` chord press. */
+export declare const KILL_BACKGROUND_CHORD = "\u0018\v";
+/**
+ * The discrete key presses to send, in order, to stop Claude Code's background
+ * work: the chord, then the chord again to confirm. Returned as separate
+ * entries so the caller delivers them as distinct PTY input events (the TUI
+ * renders the confirm prompt between them).
+ */
+export declare function buildBackgroundKillPresses(): readonly string[];
+//# sourceMappingURL=background-shell-kill-keys.d.ts.map

package/dist/server/server/agent/providers/claude/background-shell-kill-keys.js

@@ -0,0 +1,34 @@
+/**
+ * Keystrokes that drive Claude Code's *own* CLI TUI (over the PTY) to stop its
+ * background work — i.e. kill a background shell from inside Claude Code, the
+ * same keys a human presses, NOT an external OS process kill.
+ *
+ * Source of truth: the Claude Code binary binds `chat:killAgents` to the chord
+ * `ctrl+x ctrl+k`, which arms a confirm ("Press ctrl+x ctrl+k again to stop
+ * background agents"); the second identical chord confirms. We replay that.
+ *
+ * Control bytes: Ctrl+X = 0x18 (CAN), Ctrl+K = 0x0B (VT).
+ *
+ * NOTE (scope): this is Claude Code's *global* stop-background-work chord — it
+ * stops the session's background work rather than one shell selected by id. The
+ * binary exposes no per-shell-selective interactive kill binding, so paseo
+ * clears its whole background-shell set for the agent after sending it.
+ *
+ * MAINTENANCE: these bytes are coupled to Claude Code's keybindings. If a
+ * future Claude Code release rebinds `chat:killAgents`, update this module
+ * (re-derive from the binary's keybinding strings).
+ */
+export const CTRL_X = "\x18";
+export const CTRL_K = "\x0b";
+/** One `ctrl+x ctrl+k` chord press. */
+export const KILL_BACKGROUND_CHORD = `${CTRL_X}${CTRL_K}`;
+/**
+ * The discrete key presses to send, in order, to stop Claude Code's background
+ * work: the chord, then the chord again to confirm. Returned as separate
+ * entries so the caller delivers them as distinct PTY input events (the TUI
+ * renders the confirm prompt between them).
+ */
+export function buildBackgroundKillPresses() {
+    return [KILL_BACKGROUND_CHORD, KILL_BACKGROUND_CHORD];
+}
+//# sourceMappingURL=background-shell-kill-keys.js.map

package/dist/server/server/agent/providers/claude/background-task-tracker.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Tracks an agent's live Claude Code **background shells** (`Bash` invoked with
+ * `run_in_background: true`) so paseo can keep surfacing the agent as "Running"
+ * — and offer a dismiss — while those shells outlive the turn, and so the user
+ * can see WHAT is running the way the Claude Code CLI itself shows it: the
+ * command, how long it has been going, and the output it is writing.
+ *
+ * Why this exists: a backgrounded `Bash` returns its handle immediately, so the
+ * tool-call completes and the agent's lifecycle status settles to `idle` even
+ * though the shell is still alive. The liveness only shows up as two text
+ * signals in the (transport-agnostic) message stream paseo already ingests —
+ * the PTY transport feeds these by tailing Claude Code's transcript JSONL, the
+ * SDK transport by its message events, both converging on the same handler:
+ *
+ *   start → the Bash tool_result text: "Command running in background with ID: <id>"
+ *           plus "Output is being written to: <path>"
+ *   end   → a <task-notification> envelope carrying that same <id> + a terminal status
+ *
+ * Both carry the SAME id (e.g. `bjuk0pif4`), so we key the record set by it.
+ *
+ * The command itself is NOT in the tool_result — it lives in the matching
+ * `tool_use` block's input, which the caller already has cached. So the caller
+ * passes it in; this module never reaches for provider types.
+ *
+ * This module is pure (no SDK/PTY types, no filesystem) so it unit-tests
+ * cleanly and works regardless of transport. Anything that needs the disk (the
+ * output file's real birth time, reading the output back) is the caller's job.
+ */
+export type ClaudeBackgroundTaskStatus = "running" | "completed" | "failed" | "canceled";
+/**
+ * What kind of background work a record represents. Surfaced so the UI can say
+ * WHAT is holding a session open ("pending · monitoring deploy.log") instead of
+ * an unexplained spinner, which is how users end up force-quitting sessions.
+ *
+ * ⚠️ Adding a member here is not enough to make it tracked — it must also get a
+ * start pattern above AND a retirement path, and be listed in the exhaustiveness
+ * test. See `background-work-kinds.ts`.
+ */
+export type ClaudeBackgroundTaskKind = "shell" | "monitor" | "cron";
+export interface BackgroundTaskStart {
+    id: string;
+    kind: ClaudeBackgroundTaskKind;
+}
+export interface ClaudeBackgroundTaskRecord {
+    /** Harness-assigned shell id, e.g. `bjuk0pif4`. Stable across start and end. */
+    id: string;
+    /** Which flavour of background work this is. Defaults to "shell" (legacy). */
+    kind: ClaudeBackgroundTaskKind;
+    /** The shell command, from the originating `tool_use` input. Null if unseen. */
+    command: string | null;
+    /** The tool call's human description ("Run the test suite"), if it carried one. */
+    description: string | null;
+    /** Absolute path the harness streams the shell's output into, if announced. */
+    outputFile: string | null;
+    /** ISO timestamp the shell started. Resolved by the caller (see module docs). */
+    startedAt: string;
+    /** ISO timestamp the terminal notification landed, or null while running. */
+    endedAt: string | null;
+    status: ClaudeBackgroundTaskStatus;
+    /** The notification's own summary line, once it arrives. */
+    summary: string | null;
+}
+export interface NoteBackgroundShellStartInput {
+    /** Raw text of the backgrounded Bash tool_result. */
+    text: string | null | undefined;
+    /**
+     * Which tool produced this result. Scopes which announcements may be read out
+     * of `text` (see {@link extractBackgroundTaskStarts}). Production must always
+     * set it; omitting it keeps the legacy scan-everything behaviour for tests.
+     */
+    toolName?: string | null;
+    /**
+     * `run_in_background` from the originating `Bash` tool_use input: the AGENT'S
+     * INTENT, which is the only authoritative signal that a shell was actually
+     * backgrounded.
+     *
+     * The result text is not authoritative. `cat`, `grep`, `sed` and `journalctl`
+     * all reproduce whatever their target says, so a foreground Bash that merely
+     * READS an announcement used to register a task that can never retire: no such
+     * shell exists, so no `<task-notification>` will ever arrive for it. When the
+     * intent is known and false, the text is ignored.
+     *
+     * An ABSENT flag reads as `false`: current Claude Code versions set
+     * `run_in_background: true` on every backgrounded Bash and omit the key
+     * otherwise (measured: 398 `true`, 13,824 absent, 0 explicit `false`). The
+     * one known exception is Claude Code 2.1.202-2.1.208 (July 2026), which
+     * auto-backgrounded a handful of shells without the flag; those go untracked
+     * now, which is the accepted cost.
+     *
+     * `undefined` means the caller could not see the input at all. The text is
+     * trusted in that case, because refusing would silently stop tracking a real
+     * shell, which is the worse failure.
+     */
+    backgrounded?: boolean;
+    /** `command` from the originating tool_use input, when the caller has it. */
+    command?: string | null;
+    /** `description` from the originating tool_use input, when the caller has it. */
+    description?: string | null;
+    /** ISO start time. Defaults to now when the caller can't do better. */
+    startedAt?: string | null;
+}
+export interface NoteTaskNotificationInput {
+    taskId?: string | null;
+    status?: string | null;
+    summary?: string | null;
+    outputFile?: string | null;
+    /** ISO end time. Defaults to now. */
+    endedAt?: string | null;
+}
+export declare function isTerminalTaskStatus(status: string | null | undefined): boolean;
+/**
+ * Map a notification's raw status onto the record's terminal status. Anything
+ * terminal that isn't recognisably a failure or a cancel is a plain completion.
+ */
+export declare function toTerminalRecordStatus(status: string | null | undefined): Exclude<ClaudeBackgroundTaskStatus, "running">;
+/**
+ * Extract every background-task id announced in a Bash tool_result's text.
+ *
+ * Bash shells only — kept at this name and signature because it is part of the
+ * module's public surface. For all tracked kinds use
+ * {@link extractBackgroundTaskStarts}.
+ */
+export declare function extractBackgroundTaskIds(text: string | null | undefined): string[];
+/** Ids of monitors started in this text. */
+export declare function extractMonitorTaskIds(text: string | null | undefined): string[];
+/** Ids of cron jobs scheduled in this text. */
+export declare function extractCronTaskIds(text: string | null | undefined): string[];
+/** Ids of cron jobs cancelled in this text (a cron's only retirement signal). */
+export declare function extractCancelledCronTaskIds(text: string | null | undefined): string[];
+/**
+ * Ids stopped by TaskStop in this text. Unlike the cron cancel path this retires
+ * ANY kind, because TaskStop can end a shell, a monitor or a cron alike.
+ */
+export declare function extractStoppedTaskIds(text: string | null | undefined): string[];
+/**
+ * The tools whose results may announce background work. Anything else cannot
+ * start a task, however its output happens to read.
+ */
+export type BackgroundWorkToolName = "Bash" | "Monitor" | "CronCreate" | "CronDelete" | "TaskStop";
+/**
+ * Every background-work start announced in one tool_result, tagged by kind.
+ *
+ * This is the single place that decides "does this text start something that
+ * keeps the agent alive?". A new kind of background work is invisible until it
+ * is added HERE, which is precisely how monitors and crons went untracked
+ * while `deriveAgentStateBucket` happily reported those sessions as done.
+ *
+ * ⚠️ Matching is on PROSE, so it cannot tell an announcement from a QUOTE of
+ * one. Pass `toolName` and only the patterns that tool can actually emit are
+ * run. Omitting it keeps the legacy scan-everything behaviour and is for tests
+ * that feed a sample string directly; production must always pass it.
+ */
+export declare function extractBackgroundTaskStarts(text: string | null | undefined, toolName?: string | null): BackgroundTaskStart[];
+/** Extract the output-file path the harness announced alongside the id, if any. */
+export declare function extractBackgroundOutputFile(text: string | null | undefined): string | null;
+export declare class ClaudeBackgroundTaskTracker {
+    /** Live shells, keyed by harness id, in the order they started. */
+    private readonly running;
+    /** Recently finished shells, oldest first, capped at {@link FINISHED_RETENTION}. */
+    private finished;
+    /**
+     * Scan a Bash tool_result's text for background-shell launches and record each
+     * one as running. Returns the ids newly added (idempotent — re-seeing an id
+     * leaves the existing record untouched, which matters because the PTY
+     * transport replays the transcript on resume). Safe to call on any
+     * tool_result text; non-matching text adds none.
+     */
+    noteToolResultText(input: NoteBackgroundShellStartInput | string | null | undefined): string[];
+    /**
+     * Retire anything a TaskStop ended.
+     *
+     * TaskStop ends work of ANY kind and emits no `<task-notification>` (there is
+     * nothing left to notify), so this tool_result is its only retirement signal.
+     * Deliberately NOT filtered by `record.kind`, unlike the cron branch: only a
+     * cron uses the "Cancelled job" sentence, whereas TaskStop is universal.
+     */
+    private retireStoppedTasks;
+    /**
+     * A `<task-notification>` arrived. If it carries a terminal status for a task
+     * we're tracking, move it out of the live set and into the finished tail.
+     * Returns true iff the live set changed. Unknown ids and non-terminal
+     * statuses are no-ops.
+     */
+    noteTaskNotification(input: NoteTaskNotificationInput): boolean;
+    /** Explicit removal — e.g. the user dismissed/killed the shell from the UI. */
+    remove(taskId: string): boolean;
+    has(taskId: string): boolean;
+    /** Look up one record, live or recently finished. */
+    get(taskId: string): ClaudeBackgroundTaskRecord | null;
+    /** Count of still-alive background shells owned by this agent. */
+    get count(): number;
+    /** Snapshot of the live ids (start order), for surfacing a dismissable list. */
+    list(): string[];
+    /**
+     * Full records: live shells first (start order), then the recently finished
+     * tail newest-first. This is what the UI renders.
+     */
+    listRecords(): ClaudeBackgroundTaskRecord[];
+    /**
+     * Stop every live shell and retire it as canceled, keeping the rows readable.
+     *
+     * This is the dismiss path: Claude Code's `ctrl+x ctrl+k` kills the session's
+     * background work wholesale, so every live shell ends at once. They are
+     * RETIRED rather than dropped because their output files still exist and a
+     * user who just stopped a build is exactly the user who wants to read why.
+     * Returns the ids that were stopped.
+     */
+    cancelAllRunning(): string[];
+    /**
+     * Drop every live shell without retiring it. Used when the session is torn
+     * down or restarted, where the shells die with the CLI and there is nothing
+     * left to show output for.
+     */
+    clear(): void;
+    private retire;
+}
+//# sourceMappingURL=background-task-tracker.d.ts.map