@edspencer/paddock 0.0.1 → 0.56.0

package/packages/server/dist/subagents.d.ts

@@ -0,0 +1,337 @@
+import { type ChatMessage, type ChatToolCall } from "@herdctl/core";
+import type { MessageSender } from "./message-provenance.js";
+import type { TurnNotice } from "./turn-notice.js";
+import { type SessionTokenUsage } from "./usage.js";
+/** Tool names that launch a sub-agent. `Task` = classic Claude Code, `Agent` = Agent SDK. */
+export declare const SUBAGENT_TOOL_NAMES: Set<string>;
+/**
+ * A `Task`/`Agent` launch recovered LIVE from a raw SDK message's `tool_use`
+ * block (issue #429). `subagentType`/`description` come straight from the tool
+ * INPUT the launching assistant message carries — so a consumer can enrich the
+ * live tool card with the real sub-agent type + title the instant it starts,
+ * WITHOUT waiting for the history-path subagent-join (which only runs on reload).
+ */
+export interface SubagentLaunch {
+    toolUseId: string;
+    subagentType?: string;
+    description?: string;
+}
+/**
+ * Extract every `Task`/`Agent` `tool_use` block from a single raw SDK message,
+ * with `subagent_type` + `description` read directly from the tool input. Returns
+ * [] for any message that carries no sub-agent launch (the common case). This is
+ * the live counterpart to {@link readTaskToolUses} (which recovers the same fields
+ * from the transcript on disk): it lets ws-turn enrich the live `chat:tool_start`
+ * / `chat:tool_call` frames as the launch streams, closing the "generic launch-ack
+ * live, only enriches on refresh" gap (#429). The message shape is loosely typed
+ * in core, so every field access is guarded.
+ */
+export declare function extractSubagentLaunches(m: unknown): SubagentLaunch[];
+/** Both sessionId and toolUseId are path segments — keep them inside `.chats/`. */
+export declare const SAFE_SEGMENT: RegExp;
+/**
+ * Max files retained per mtime cache.
+ *
+ * Was 64, which a real project blows straight through: one live-scale project
+ * holds 514 transcript files across 234 chats, so a single sweep of
+ * `/chats/usage` evicted every entry before the next sweep could reuse one — the
+ * cache was pure overhead. Measured on that corpus (issue #537), raising the cap
+ * took the warm full-project usage call from ~440ms to ~29ms.
+ *
+ * The entries are token tallies and tool-use records, not transcript text, so
+ * this is cheap: forcing every one of the 1,515 sessions in that corpus through
+ * both the usage and sub-agent-listing paths and then running GC retained
+ * **1.4 MB** at this cap versus **1.3 MB** at 64 — a ~0.1 MB difference for a
+ * 15× speedup.
+ */
+export declare const MTIME_CACHE_MAX = 1024;
+export type MtimeCache<T> = Map<string, {
+    mtimeMs: number;
+    value: T;
+}>;
+/** The file's mtime in epoch ms, or undefined if it can't be stat'd. */
+export declare function statMtimeMs(file: string): Promise<number | undefined>;
+/** Return the cached value if the recorded mtime still matches (LRU-touch on hit). */
+export declare function mtimeCacheGet<T>(cache: MtimeCache<T>, file: string, mtimeMs: number): {
+    hit: true;
+    value: T;
+} | {
+    hit: false;
+};
+/** Store a value against the file's mtime, evicting the least-recently-used past the cap. */
+export declare function mtimeCacheSet<T>(cache: MtimeCache<T>, file: string, mtimeMs: number, value: T): void;
+/** The parent-turn view of a sub-agent launch, recovered from the main transcript. */
+export interface TaskToolUse {
+    toolUseId: string;
+    subagentType?: string;
+    description?: string;
+    prompt?: string;
+}
+/** A sub-agent's `.meta.json` sidecar, plus the resolved path to its transcript. */
+export interface SubagentMeta {
+    toolUseId: string;
+    agentType?: string;
+    description?: string;
+    spawnDepth?: number;
+    /**
+     * This sub-agent's own agent id (the `<hex>` of its `agent-<hex>` transcript),
+     * and — when it was itself spawned by another sub-agent — that parent sub-agent's
+     * agent id (`parentAgentId` in the sidecar; absent for a depth-1 sub-agent whose
+     * parent is the main session). Together these form the sub-agent tree used for the
+     * recursive per-card cost rollup (see {@link subagentCosts}).
+     */
+    agentId?: string;
+    parentAgentId?: string;
+    /** Absolute path to the sibling `agent-<hex>.jsonl`. */
+    transcriptPath: string;
+}
+/**
+ * A paddock-enriched tool call: core's `ChatToolCall` plus the sub-agent fields
+ * we recover for `Task`/`Agent` blocks. All additive and optional, so non-Task
+ * tool calls (and older transcripts) are unaffected.
+ */
+export type EnrichedToolCall = ChatToolCall & {
+    toolUseId?: string;
+    subagentType?: string;
+    description?: string;
+    prompt?: string;
+    /** True when a sub-agent transcript exists on disk for this tool_use. */
+    hasSubagent?: boolean;
+    /**
+     * The sub-agent's actual run time (first→last transcript timestamp), in ms.
+     * The tool call's own `durationMs` only measures how long the *launch* took —
+     * the Task/Agent tool returns immediately ("launched successfully") while the
+     * sub-agent runs on — so this is the meaningful figure to surface.
+     */
+    subagentDurationMs?: number;
+    /**
+     * The sub-agent's estimated API-rate cost in USD (issue #166), as the RECURSIVE
+     * total of this sub-agent plus every sub-agent it (transitively) spawned — priced
+     * per-model from the merged token usage of its whole subtree (see
+     * {@link subagentCosts}). `null` when the entire subtree has no priceable usage;
+     * `undefined` for a non-sub-agent tool. Cost only: {@link subagentDurationMs}
+     * stays per-agent because nested children run in parallel (overlapping wall-clock),
+     * so summing durations would mislead — dollars are additive regardless.
+     */
+    subagentCostUsd?: number | null;
+    /** True when this tool ran detached: a `run_in_background` launch, `Monitor`,
+     *  or a background-task op (`BashOutput`/`TaskOutput`/`TaskStop`/`KillShell`). */
+    background?: boolean;
+    /** The background task id, parsed from the launch output (bg `Bash` / `Monitor`). */
+    taskId?: string;
+    /** Terminal state of the linked task: "completed" | "killed" | "timed out" |
+     *  "persistent" | "running". Derived from the matching `<task-notification>`. */
+    taskStatus?: string;
+    /** The completion `<summary>` folded in from the matching task-notification
+     *  (e.g. `Background command "…" completed (exit code 0)`). */
+    taskResultSummary?: string;
+    /** For `Monitor`: the streamed `<event>` lines, in order, grouped by task id. */
+    monitorEvents?: string[];
+    /** Inline diff for an `Edit`/`MultiEdit`/`Write` (issue #232 → #237), now sourced
+     *  from `toolUseResult.structuredPatch` (real file line numbers). */
+    editDiff?: EditDiff;
+    /** File + line-range for a `Read` — drives the `basename · lines a–b of N` header. */
+    readInfo?: ReadInfo;
+    /** Split stdout/stderr + status affordances for a `Bash` (issue #237). */
+    bashDetails?: BashDetails;
+    /** Match/file counts for a `Grep`/`Glob` (issue #237). */
+    searchInfo?: SearchInfo;
+    /** Status transition for a `TaskUpdate` (issue #237). */
+    taskUpdate?: TaskUpdateInfo;
+    /** Subject/description for a `TaskCreate` (issue #237). */
+    taskCreate?: TaskCreateInfo;
+};
+/**
+ * One line of a rendered diff: added (`+`), removed (`-`), or unchanged context,
+ * with the real source line numbers recovered from the transcript's git-style
+ * hunks (issue #237). `oldLine` is set on context + deletions, `newLine` on
+ * context + additions.
+ */
+export interface DiffLine {
+    t: "+" | "-" | " ";
+    text: string;
+    oldLine?: number;
+    newLine?: number;
+}
+/** One git-style hunk with real file offsets (`@@ -oldStart,oldLines +newStart,newLines @@`). */
+export interface DiffHunk {
+    oldStart: number;
+    oldLines: number;
+    newStart: number;
+    newLines: number;
+    lines: DiffLine[];
+}
+/**
+ * A structured diff for an edit tool call (issue #232 → generalized #237). Sourced
+ * from `toolUseResult.structuredPatch` — the git-style hunks Claude Code already
+ * computed, with **real file line numbers** — so the hand-rolled LCS diff is gone.
+ * `Edit`/`MultiEdit` carry one hunk per changed region; `Write` carries the
+ * whole-file create as additions.
+ */
+export interface EditDiff {
+    filePath?: string;
+    kind: "edit" | "multiedit" | "write";
+    additions: number;
+    deletions: number;
+    hunks: DiffHunk[];
+    /** True when a hunk was truncated for size; the stats still reflect the full edit. */
+    truncated?: boolean;
+    /** True when the file changed between the read and the edit (`toolUseResult.userModified`). */
+    userModified?: boolean;
+}
+/** File + line-range recovered for a `Read` (issue #237). */
+export interface ReadInfo {
+    filePath?: string;
+    basename?: string;
+    /** 1-based first line returned. */
+    startLine?: number;
+    /** Number of lines returned. */
+    numLines?: number;
+    /** Total lines in the file. */
+    totalLines?: number;
+    /** True when the read target is an image file (by extension) — issue #239. */
+    isImage?: boolean;
+    /**
+     * The read target's path relative to the project dir, set only when it's an
+     * image that resolves INSIDE the project dir so the web can render it inline via
+     * the raw file endpoint (issue #239). Absent for a non-image read, an image
+     * outside the project dir.
+     */
+    projectRelPath?: string;
+}
+/** Split output + status affordances recovered for a `Bash` (issue #237). */
+export interface BashDetails {
+    /** Present (with `stderr`) only when there IS stderr to split out; else undefined
+     *  and the generic merged `output` renders. */
+    stdout?: string;
+    stderr?: string;
+    interrupted?: boolean;
+    /** Human-readable exit hint, e.g. "No matches found". */
+    returnCodeInterpretation?: string;
+    /** Short git affordance from `gitOperation`, e.g. "push → main". */
+    gitHint?: string;
+}
+/** Match/file counts recovered for a `Grep`/`Glob` (issue #237). */
+export interface SearchInfo {
+    kind: "grep" | "glob";
+    numFiles?: number;
+    /** Grep content-mode: number of matching lines. */
+    numLines?: number;
+    /** Glob: total matches found (may exceed the returned/`truncated` set). */
+    totalMatches?: number;
+    truncated?: boolean;
+}
+/** Status transition recovered for a `TaskUpdate` (issue #237). */
+export interface TaskUpdateInfo {
+    taskId?: string;
+    updatedFields?: string[];
+    from?: string;
+    to?: string;
+}
+/** Subject/description recovered for a `TaskCreate` (issue #237). */
+export interface TaskCreateInfo {
+    taskId?: string;
+    subject?: string;
+    description?: string;
+}
+export type EnrichedMessage = Omit<ChatMessage, "toolCall"> & {
+    toolCall?: EnrichedToolCall;
+    /** True when this `<task-notification>` was folded into a background tool block
+     *  (issue #230), so the web suppresses the standalone status pill. */
+    bgConsumed?: boolean;
+    /** Who injected this machine-added turn (issue #290); absent ⇒ human-typed. */
+    sender?: MessageSender;
+    /** Context-window fill (tokens) as of this message — the nearest assistant
+     *  turn's `input + cache_read + cache_creation`, forward-filled across the
+     *  turns between (issue #451). Drives the per-message hover meter + the
+     *  fork/revert-from-here anchor. Absent before the first assistant turn. */
+    contextTokens?: number;
+    /** A surfaced turn-ending condition (issue #329): a subscription/usage-limit
+     *  hit recovered from the transcript on reload. Present only on the synthetic
+     *  notice message appended by the history endpoint; the web renders it as a
+     *  distinct notice turn instead of an assistant bubble. */
+    notice?: TurnNotice;
+};
+/**
+ * Task/Agent launches recovered from one transcript, split by whether the launch
+ * has come back yet.
+ *
+ * They are kept apart because they join to herdctl's parsed messages by DIFFERENT
+ * cursors: core emits one message per paired call, plus a `pending:true` message
+ * for each still-unpaired launch. Interleaving them in a single list is what used
+ * to misalign a completed sub-agent that ran in parallel with a live one.
+ */
+export interface TaskToolUses {
+    /** Launches with a matching tool_result, in file order. */
+    paired: TaskToolUse[];
+    /** Launches still in flight (no tool_result yet), in file order. */
+    pending: TaskToolUse[];
+}
+/**
+ * Stream the main session transcript and recover, in file order, every
+ * `Task`/`Agent` tool_use that was **paired** with a tool_result. Pairing is
+ * tracked so the returned list aligns 1:1 with herdctl's parsed tool messages
+ * for completed calls.
+ *
+ * Paired-only by design — {@link readTaskUsesFromFile} exposes the in-flight
+ * launches separately, and mixing them here would break that alignment.
+ */
+export declare function readTaskToolUses(projectDir: string, sessionId: string): Promise<TaskToolUse[]>;
+/**
+ * Live sub-agent enrichment for a tool frame (issue #429). When the tool is a
+ * `Task`/`Agent` launch this turn already recovered (via {@link extractSubagentLaunches}),
+ * return the real sub-agent type + title plus `hasSubagent: true`, so the client
+ * renders the enriched, expandable card the moment the launch streams — instead of
+ * the generic "Agent · <ms>" launch-ack that only filled in on refresh. A safe
+ * spread for any non-sub-agent tool (returns an empty object). `hasSubagent` is set
+ * optimistically: a `Task`/`Agent` launch is expected to write a sub-agent
+ * transcript, and the client's expand path degrades gracefully (a "waiting…"
+ * placeholder) until the sidecar appears on disk.
+ */
+export declare function subagentLaunchFields(launches: Map<string, SubagentLaunch>, toolName: string, toolUseId: string | undefined): {
+    subagentType?: string;
+    description?: string;
+    hasSubagent?: boolean;
+};
+/**
+ * Read the `subagents/*.meta.json` sidecars for a session, keyed by `toolUseId`.
+ * Returns an empty map when the session has no sub-agents (the common case) or
+ * the directory is missing/unreadable.
+ */
+export declare function listSubagents(projectDir: string, sessionId: string): Promise<Map<string, SubagentMeta>>;
+/**
+ * Parse a single sub-agent's transcript into messages, reusing core's parser.
+ * Returns [] when the `toolUseId` doesn't correspond to a known sub-agent or the
+ * transcript is missing. Both segments are validated to stay inside `.chats/`.
+ */
+export declare function readSubagentMessages(projectDir: string, sessionId: string, toolUseId: string): Promise<EnrichedMessage[]>;
+/**
+ * Enrich a session's parsed messages: attach the recovered sub-agent fields
+ * (`toolUseId`, `subagentType`, `description`, `prompt`, `hasSubagent`) to every
+ * `Task`/`Agent` tool message, joining by file order. Non-Task tool calls and
+ * sessions without sub-agents pass through unchanged (a cheap early return).
+ */
+export declare function enrichWithSubagents(projectDir: string, sessionId: string, messages: ChatMessage[]): Promise<EnrichedMessage[]>;
+/**
+ * A chat's cumulative token usage *including every sub-agent it spawned* (issue
+ * #242).
+ *
+ * The per-chat cost/token headline (issue #152) originally priced only the main
+ * transcript, but a chat's `Task`/`Agent` sub-agents run in their own sibling
+ * transcripts (`.chats/<sessionId>/subagents/agent-*.jsonl`) — so a chat that
+ * fanned work out to sub-agents under-reported its true spend, sometimes by ~90%.
+ * This folds those transcripts back in: the four token totals and the per-model
+ * buckets gain every sub-agent's usage, so both the token figure and the
+ * per-model-priced dollar estimate reflect the whole chat.
+ *
+ * `contextTokens` and `turnCount` stay main-only: those describe the parent's
+ * last-turn context-window fill (what the ContextMeter shows), a distinct concept
+ * from lifetime spend — each sub-agent has its own, separate context window.
+ *
+ * No double-counting: herdctl writes sub-agent (`isSidechain`) turns to the
+ * sibling files, never into the main transcript, so `main + sub-agents` is a
+ * clean sum. Nested sub-agents (spawnDepth > 1) sit flat in the same `subagents/`
+ * dir, so their usage is included too. Returns the main usage unchanged when the
+ * chat spawned no sub-agents (the common case — a cheap early return).
+ */
+export declare function readSessionTokenUsageWithSubagents(projectDir: string, sessionId: string): Promise<SessionTokenUsage>;