@gitkraken/core-gitlens 0.6.0 → 0.7.1

package/dist/plus/agents/providers/gkAgentProvider.d.ts

@@ -1,243 +1,240 @@
-import type { AgentProviderCallbacks, AgentSession, AgentSessionHistoryOptions, AgentSessionHistoryResult, AgentSessionProvider, AgentSessionResumeOutcome, AgentSessionResumeTarget, PermissionDecision, PermissionSuggestion } from '../types.js';
-import type { EndedTranscriptDetails } from './claudeCodeTranscript.js';
-import { ClaudeCodeTranscriptReader } from './claudeCodeTranscript.js';
+import { Event } from "../../../utils/event.js";
+import { ClaudeCodeTranscriptReader, EndedTranscriptDetails } from "./claudeCodeTranscript.js";
+import { AgentProviderCallbacks, AgentSession, AgentSessionHistoryOptions, AgentSessionHistoryResult, AgentSessionProvider, AgentSessionResumeOutcome, AgentSessionResumeTarget, PermissionDecision, PermissionSuggestion } from "../types.js";
+//#region ../plus/agents/src/providers/gkAgentProvider.d.ts
 export declare class GkAgentProvider implements AgentSessionProvider {
-    private readonly callbacks;
-    /** Identifies the PROVIDER, not an agent: this one hosts every `gk ai hook` client GitLens has
-     *  a descriptor for. A session's own agent identity lives on {@link AgentSession.providerId}
-     *  (`claudeCode`, `codex`, …), sourced from {@link AgentCapabilities} — never from here. */
-    readonly id = "gkAgents";
-    readonly name = "Coding Agents";
-    readonly icon = "robot";
-    readonly agentProviderIds: readonly string[];
-    private readonly _onDidChangeSessions;
-    readonly onDidChangeSessions: import("../../../utils/event.js").Event<void>;
-    private _sessions;
-    private _ipcStarted;
-    private _disposed;
-    private _handlerDisposables;
-    private readonly _pendingPermissions;
-    /** `sessionId -> cwd currently being probed`, and the newest cwd requested while that probe runs.
-     *  A probe's answer is only valid for the cwd it was started with, so a session that moves
-     *  mid-flight must supersede rather than dedupe — otherwise the older lookup lands last and
-     *  overwrites the newer location with the directory the session already left. */
-    private readonly _resolveGitInfoInFlight;
-    private readonly _resolveGitInfoPending;
-    /** Short-TTL cache of the machine-global archived-session id list. Holds the in-flight promise so
-     *  concurrent per-worktree `getPastSessions` calls share one CLI spawn; `archiveSession` clears it. */
-    private _archivedSessionIdsCache;
-    private readonly _sessionBookkeeping;
-    /** Per-session timers for the deferred `Stop → idle` commit. The handle is cleared (and the
-     *  transition cancelled) by any non-idle status update arriving before the timer fires. */
-    private readonly _pendingIdleTimers;
-    private _workspacePaths;
-    private _staleCheckTimer;
-    /** When the last poll actually ran (gated or not) — paces the idle cadence above. */
-    private _lastSyncAt;
-    /** Whether agent hooks are installed, pushed by the host via {@link setHooksInstalled}.
-     *  Fail-open (`true`) until the first push lands so a fresh window with real hooks isn't
-     *  suppressed on its first ticks. Gates the reconciliation poll in {@link syncSessions}. */
-    private _hooksInstalled;
-    /** Whether the CLI supports `list-sessions --status` (and with it the durable ended-session
-     *  store). Optimistic until the poll's flagless fallback proves otherwise. When unsupported,
-     *  ended rows are untenable — no poll can ever confirm or archive one — so `SessionEnd`
-     *  reverts to removing the session and reconciliation drops any ended stragglers. */
-    private _statusFilterSupported;
-    protected _transcriptReader: ClaudeCodeTranscriptReader;
-    private _terminalGeneration;
-    /** Ended-transcript detail results, cached forever per window — an ended transcript is
-     *  immutable, so once resolved it never needs a second read. Keyed by session id. */
-    private readonly _sessionDetailsCache;
-    constructor(callbacks: AgentProviderCallbacks);
-    get sessions(): readonly AgentSession[];
-    get terminalGeneration(): number;
-    /** Single choke point for every terminal transition — a session ending, being removed on end
-     *  (legacy path), being pruned, or a fresh ended record being discovered. Bumps the generation
-     *  the host's history queries validate against (a transition mid-query means the answer may be
-     *  missing a session) and drops the transcript listing caches, whose warm entries may predate
-     *  the transcript the transition just left behind. */
-    private noteTerminalTransition;
-    start(workspacePaths: string[]): void;
-    stop(): void;
-    sync(): Promise<void>;
-    updateWorkspacePaths(workspacePaths: string[]): void;
-    setHooksInstalled(installed: boolean): void;
-    /** Reads Claude history from its transcript store and tracked terminal records. The exact project
-     *  directory preserves legacy sessions that predate the CLI's durable records. Recent ended
-     *  records add an authoritative worktree-to-session association, so their ids are also recovered
-     *  from other project directories when Claude left the transcript behind after a cwd/worktree
-     *  move. A tracked record with no readable transcript remains visible and archivable, but does not
-     *  advertise Resume. Archive filtering stays provider-local so ids from another harness cannot
-     *  suppress Claude rows. `requireResume` drops the transcript-less tracked records, leaving only
-     *  rows that carry a resume action — and a `total` counting only those. */
-    listSessionHistory(cwd: string, options?: AgentSessionHistoryOptions): Promise<AgentSessionHistoryResult>;
-    resumeSession(sessionId: string, cwd: string, target: AgentSessionResumeTarget, name?: string): Promise<AgentSessionResumeOutcome | false>;
-    dispose(): void;
-    [Symbol.dispose](): void;
-    private ensureIpcServer;
-    private handleSessionEvent;
-    private sessionTag;
-    /** The owning agent's descriptor for a tracked session, resolved from the session's own
-     *  `providerId`. `undefined` when the session isn't tracked (pruned/archived since) or carries a
-     *  `providerId` the descriptor table doesn't know — callers pick their own fallback rather than
-     *  silently assuming Claude Code. */
-    private getSessionCapabilities;
-    /** Whether the session's agent leaves a transcript on disk for {@link ClaudeCodeTranscriptReader}
-     *  to tail. Fails OPEN when no descriptor resolves, so an unknown/absent `providerId` can never
-     *  suppress the Claude path this reader exists for. */
-    private supportsTranscripts;
-    private getBookkeeping;
-    /** Returns the active decay window in milliseconds — the cooldown between PostToolUse and
-     *  dropping the path from the bookkeeping. Reads through the host callback every time so a
-     *  setting change takes effect on the next Pre/Post pair without re-wiring (existing timers
-     *  keep their original timeout — acceptable since they're short-lived relative to the setting). */
-    private get activityDecayMs();
-    /** Locates the *parent* session id that owns the given session id — returns the id itself when
-     *  it matches a top-level session, otherwise the `id` of the parent that holds it under
-     *  `subagents[]`. Returns `undefined` when neither match (session no longer exists). Used to
-     *  route per-session bookkeeping changes to the right top-level `syncSessionFileActivity` call.
-     *  Tool events are parent-keyed (the CLI sends a sub-agent's tool events under the parent id),
-     *  so the `subagents[]` branch is a defensive fallback for any other-keyed caller. */
-    private findOwningParentId;
-    private resetBookkeeping;
-    /** Turn-end settle (Stop): the agent finished its turn, so nothing is "live" anymore — but
-     *  the per-operation decay tail must survive. Heat fades over {@link activityDecayMs} measured
-     *  from when each *tool* finished (the PostToolUse cooldown), NOT from when the turn ends, so a
-     *  Stop must not cancel those cooldowns or clear `lastTouchedAt`. We only reset turn-scoped
-     *  state and force-finish any path whose PostToolUse never arrived before Stop: drop its
-     *  refcount to 0 (flipping `editing`/`reading` off so the pulse stops) and schedule the same
-     *  decay eviction a normal completion would. Contrast {@link resetBookkeeping}, which hard-
-     *  wipes everything for SessionStart/SessionEnd (the agent is gone, not merely between turns). */
-    private settleBookkeeping;
-    private cancelPendingFileClears;
-    private cancelPendingReadClears;
-    /** Extracts the targeted file path from a PreToolUse/PostToolUse event. Tries the raw
-     *  `hookInput.tool_input` passthrough first, falls back to the projected `event.toolInput`
-     *  for older CLI versions that only fill the top-level fields. Treats an empty-object
-     *  `hookInput.tool_input` as missing — `??` would have kept it (truthy) and shadowed a
-     *  populated `event.toolInput`. */
-    private getEventFilePath;
-    /** Stamps the per-path/per-kind `lastTouchedAt[kind]` to the current epoch ms. Stamped on every
-     *  PreToolUse for the matching kind so `serializeFileActivity` can emit `readAt`/`editedAt` as
-     *  a relative `now - timestamp` delta. */
-    private stampLastTouched;
-    /** Drops the `lastTouchedAt[kind]` slot for `filePath`, and the whole entry when neither kind
-     *  remains. Mirrors the cooldown-timer eviction in `scheduleClear*` — once the path is gone
-     *  from the count map for that kind, its timestamp is no longer load-bearing. */
-    private clearLastTouched;
-    /** Records that a file-mutating tool call is in flight against `filePath` so consumers can
-     *  highlight the path. Refcounts per path — keyed by path (not `tool_use_id`, which the GK CLI
-     *  doesn't reliably surface) so parallel calls bump the count and Post/Pre order doesn't matter.
-     *  Returns whether the parent's published `fileActivity` actually changed so callers can fire
-     *  when the surrounding {@link updateSessionStatus} short-circuits. */
-    private trackToolUseFile;
-    /** Decrements the in-flight refcount for a finished tool call's file. While the count stays
-     *  above zero (overlapping parallel calls) the path remains marked. When the count drops to
-     *  zero, leaves the entry in place at count `0` and schedules a {@link activityDecayMs}
-     *  cooldown before actually dropping it — so a recently-edited file lingers as a decay tail
-     *  on the treemap. A Pre arriving during cooldown cancels the timer and bumps the count back
-     *  above zero. Returns whether the parent's published `fileActivity` changed (i.e. `editing`
-     *  flipped off) so the PostToolUse caller can fire when its `updateSessionStatus` short-
-     *  circuits (a parallel tool still in flight keeps activeToolCount > 0). */
-    private scheduleClearToolUseFile;
-    /** Schedules (replacing any prior timer) the {@link activityDecayMs} cooldown that finally
-     *  drops `filePath` from the edit bookkeeping once it has fully decayed. Shared by the
-     *  PostToolUse cooldown path and the Stop settle ({@link settleBookkeeping}); the path stays
-     *  in `currentFileCounts` at count 0 meanwhile so its `editedAt` keeps aging on the client. */
-    private scheduleFileDecayEviction;
-    /** Drops a tracked tool call's file immediately (no cooldown). Used for PermissionDenied,
-     *  where the tool never ran — keeping the "live" badge would be misleading.
-     *  Returns whether the published list changed. */
-    private untrackToolUseFile;
-    /** Mirror of {@link getEventFilePath} for read-only file tools. */
-    private getEventReadPath;
-    /** Refcount mirror of {@link trackToolUseFile} for read-only file tools. */
-    private trackToolUseRead;
-    /** Cooldown mirror of {@link scheduleClearToolUseFile} for read-only file tools. Returns
-     *  whether the parent's published `fileActivity` changed (i.e. `reading` flipped off). */
-    private scheduleClearToolUseRead;
-    /** Read-class mirror of {@link scheduleFileDecayEviction}. */
-    private scheduleReadDecayEviction;
-    /** Immediate-drop mirror of {@link untrackToolUseFile} for read-only file tools. */
-    private untrackToolUseRead;
-    /** Convenience wrapper that resolves the parent for a possibly-sub-agent session id, then calls
-     *  {@link syncSessionFileActivity}. Tool-call handlers call this without knowing whether the
-     *  session is a top-level or sub-agent session. Returns `false` when the session isn't found
-     *  (already pruned / unknown peer id). */
-    private syncSessionFileActivityForChild;
-    /** Rebuilds the parent session's `fileActivity` array from its bookkeeping and writes it onto
-     *  the session in place. Returns whether the *structural* shape changed (paths/kinds/flags) —
-     *  timestamps are always refreshed regardless, but a fire is gated on structural change so
-     *  non-meaningful drift doesn't churn the wire.
-     *
-     *  No separate sub-agent rollup is needed: the GK CLI keys a sub-agent's tool events under its
-     *  PARENT session id (with `agentId` set), so they accumulate in the parent's own bookkeeping
-     *  directly and are already reflected here. Sub-agent serialized objects carry no `fileActivity`. */
-    private syncSessionFileActivity;
-    /** Defer the `Stop → idle` commit. If the agent produces a non-idle event within
-     *  `stopToIdleDebounceMs`, `cancelPendingIdleTransition` (called from `updateSessionStatus`)
-     *  cancels this and the session stays in its prior phase — no working → idle → working flicker.
-     *
-     *  Intentionally takes no context: the caller is expected to apply any event metadata
-     *  synchronously before scheduling. Carrying Stop-time context into the timer would let
-     *  in-window metadata mutations (e.g. `CwdChanged` updating `_sessions[i].cwd` directly)
-     *  get reverted when the deferred commit replays the stale context through `ensureSession`. */
-    private scheduleIdleTransition;
-    private cancelPendingIdleTransition;
-    /** Stable phase-since: if we're oscillating back into the phase we were just in (within a
-     *  short window), restore its original timestamp so the displayed elapsed time doesn't snap
-     *  to 0. Otherwise records the current phase as the new "prior" and returns `now`. */
-    private resolvePhaseSince;
-    /** Extracts the ask identity a settlement event refers to. `PostToolUse`/`PermissionDenied`
-     *  carry `hookInput.tool_use_id` and `hookInput.tool_input` in production; the top-level
-     *  `event.toolName`/`event.toolInput` are the older-CLI fallback. Input is canonicalized so key
-     *  order (or arriving via the fallback field instead of `hookInput`) doesn't defeat comparison. */
-    private settledByFromEvent;
-    private resolveAllPending;
-    private rejectAllPending;
-    private clearStalePermission;
-    resolvePermission(sessionId: string, decision: PermissionDecision, updatedPermissions?: PermissionSuggestion[]): boolean;
-    archiveSession(sessionId: string): Promise<boolean>;
-    /** Lists the ids of sessions the CLI has archived, so callers (the "Past" transcript listing) can
-     *  exclude them — the tracked row is gone, but the transcript on disk survives and would otherwise
-     *  resurface there. Resolves to `[]` on any error, including a CLI too old to support the
-     *  `archived` status filter. */
-    getArchivedSessionIds(): Promise<string[]>;
-    private fetchArchivedSessionIds;
-    resolveEndedSessionDetails(sessionId: string): void;
-    /** No `_sessions` gate, unlike {@link resolveEndedSessionDetails} — must work for a
-     *  transcript-only id this window never tracked live (past-session-sheet callers). */
-    resolveSessionDetails(sessionId: string, cwd?: string): Promise<EndedTranscriptDetails | undefined>;
-    private applyEndedTranscriptDetails;
-    private matchesWorkspace;
-    private resolveWorkspacePath;
-    private updateSessionWithPermission;
-    private updateSessionStatus;
-    private ensureSession;
-    private resolveGitInfo;
-    private resolveTranscriptTitles;
-    /** Transitions the session at `index` to the terminal `ended` state in place: keeps the row,
-     *  stamps `endedAt` as its activity time, clears transient state (statusDetail, pendingPermission,
-     *  subagents), and tears down its bookkeeping/timers. Shared by the live `SessionEnd` path and the
-     *  poll backstop for a `SessionEnd` the live path missed. Does not fire change events — the caller
-     *  batches those. */
-    private endSession;
-    private pruneDeadSessions;
-    protected syncSessions(options?: {
-        gate?: boolean;
-    }): Promise<void>;
-    protected querySiblingWindowSessions(): Promise<void>;
-    private fetchPeerSessions;
-    /** Find the peer GitLens window whose discovery file claims `workspacePath`, and POST to its
-     *  `/agents/sessions/open` route to ask its Claude Code extension to open the session.
-     *
-     *  Resolves to `true` when at least one peer claimed the workspace AND was reachable (the POST
-     *  completed with any HTTP status). The peer's response shape (`{ opened: boolean }`) is logged
-     *  for diagnostics but does NOT affect the return value — an `opened: false` peer is still the
-     *  right window for the caller to focus, since it's the window that owns the session. Resolves
-     *  to `false` when no peer claimed the workspace OR every claimer was unreachable; the caller
-     *  treats that as "no peer to focus" and opens a new window instead of replacing the current
-     *  one. Best-effort: swallows scan, JSON-parse errors. */
-    notifyPeerOpenSession(workspacePath: string, sessionId: string): Promise<boolean>;
+  private readonly callbacks;
+  /** Identifies the PROVIDER, not an agent: this one hosts every `gk ai hook` client GitLens has
+   *  a descriptor for. A session's own agent identity lives on {@link AgentSession.providerId}
+   *  (`claudeCode`, `codex`, …), sourced from {@link AgentCapabilities} — never from here. */
+  readonly id = "gkAgents";
+  readonly name = "Coding Agents";
+  readonly icon = "robot";
+  readonly agentProviderIds: readonly string[];
+  private readonly _onDidChangeSessions;
+  readonly onDidChangeSessions: Event<void>;
+  private _sessions;
+  private _ipcStarted;
+  private _disposed;
+  private _handlerDisposables;
+  private readonly _pendingPermissions;
+  /** `sessionId -> cwd currently being probed`, and the newest cwd requested while that probe runs.
+   *  A probe's answer is only valid for the cwd it was started with, so a session that moves
+   *  mid-flight must supersede rather than dedupe — otherwise the older lookup lands last and
+   *  overwrites the newer location with the directory the session already left. */
+  private readonly _resolveGitInfoInFlight;
+  private readonly _resolveGitInfoPending;
+  /** Short-TTL cache of the machine-global archived-session id list. Holds the in-flight promise so
+   *  concurrent per-worktree `getPastSessions` calls share one CLI spawn; `archiveSession` clears it. */
+  private _archivedSessionIdsCache;
+  private readonly _sessionBookkeeping;
+  /** Per-session timers for the deferred `Stop → idle` commit. The handle is cleared (and the
+   *  transition cancelled) by any non-idle status update arriving before the timer fires. */
+  private readonly _pendingIdleTimers;
+  private _workspacePaths;
+  private _staleCheckTimer;
+  /** When the last poll actually ran (gated or not) — paces the idle cadence above. */
+  private _lastSyncAt;
+  /** Whether agent hooks are installed, pushed by the host via {@link setHooksInstalled}.
+   *  Fail-open (`true`) until the first push lands so a fresh window with real hooks isn't
+   *  suppressed on its first ticks. Gates the reconciliation poll in {@link syncSessions}. */
+  private _hooksInstalled;
+  /** Whether the CLI supports `list-sessions --status` (and with it the durable ended-session
+   *  store). Optimistic until the poll's flagless fallback proves otherwise. When unsupported,
+   *  ended rows are untenable — no poll can ever confirm or archive one — so `SessionEnd`
+   *  reverts to removing the session and reconciliation drops any ended stragglers. */
+  private _statusFilterSupported;
+  protected _transcriptReader: ClaudeCodeTranscriptReader;
+  private _terminalGeneration;
+  /** Ended-transcript detail results, cached forever per window — an ended transcript is
+   *  immutable, so once resolved it never needs a second read. Keyed by session id. */
+  private readonly _sessionDetailsCache;
+  constructor(callbacks: AgentProviderCallbacks);
+  get sessions(): readonly AgentSession[];
+  get terminalGeneration(): number;
+  /** Single choke point for every terminal transition — a session ending, being removed on end
+   *  (legacy path), being pruned, or a fresh ended record being discovered. Bumps the generation
+   *  the host's history queries validate against (a transition mid-query means the answer may be
+   *  missing a session) and drops the transcript listing caches, whose warm entries may predate
+   *  the transcript the transition just left behind. */
+  private noteTerminalTransition;
+  start(workspacePaths: string[]): void;
+  stop(): void;
+  sync(): Promise<void>;
+  updateWorkspacePaths(workspacePaths: string[]): void;
+  setHooksInstalled(installed: boolean): void;
+  /** Reads Claude history from its transcript store and tracked terminal records. The exact project
+   *  directory preserves legacy sessions that predate the CLI's durable records. Recent ended
+   *  records add an authoritative worktree-to-session association, so their ids are also recovered
+   *  from other project directories when Claude left the transcript behind after a cwd/worktree
+   *  move. A tracked record with no readable transcript remains visible and archivable, but does not
+   *  advertise Resume. Archive filtering stays provider-local so ids from another harness cannot
+   *  suppress Claude rows. `requireResume` drops the transcript-less tracked records, leaving only
+   *  rows that carry a resume action — and a `total` counting only those. */
+  listSessionHistory(cwd: string, options?: AgentSessionHistoryOptions): Promise<AgentSessionHistoryResult>;
+  resumeSession(providerId: string, sessionId: string, cwd: string, target: AgentSessionResumeTarget, name?: string): Promise<AgentSessionResumeOutcome | false>;
+  private resumeActionFor;
+  dispose(): void;
+  [Symbol.dispose](): void;
+  private ensureIpcServer;
+  private handleSessionEvent;
+  private sessionTag;
+  /** The owning agent's descriptor for a tracked session, resolved from the session's own
+   *  `providerId`. `undefined` when the session isn't tracked (pruned/archived since) or carries a
+   *  `providerId` the descriptor table doesn't know — callers pick their own fallback rather than
+   *  silently assuming Claude Code. */
+  private getSessionCapabilities;
+  /** Whether the session's agent leaves a transcript on disk for {@link ClaudeCodeTranscriptReader}
+   *  to tail. Fails OPEN when no descriptor resolves, so an unknown/absent `providerId` can never
+   *  suppress the Claude path this reader exists for. */
+  private supportsTranscripts;
+  private getBookkeeping;
+  /** Returns the active decay window in milliseconds — the cooldown between PostToolUse and
+   *  dropping the path from the bookkeeping. Reads through the host callback every time so a
+   *  setting change takes effect on the next Pre/Post pair without re-wiring (existing timers
+   *  keep their original timeout — acceptable since they're short-lived relative to the setting). */
+  private get activityDecayMs();
+  /** Locates the *parent* session id that owns the given session id — returns the id itself when
+   *  it matches a top-level session, otherwise the `id` of the parent that holds it under
+   *  `subagents[]`. Returns `undefined` when neither match (session no longer exists). Used to
+   *  route per-session bookkeeping changes to the right top-level `syncSessionFileActivity` call.
+   *  Tool events are parent-keyed (the CLI sends a sub-agent's tool events under the parent id),
+   *  so the `subagents[]` branch is a defensive fallback for any other-keyed caller. */
+  private findOwningParentId;
+  private resetBookkeeping;
+  /** Turn-end settle (Stop): the agent finished its turn, so nothing is "live" anymore — but
+   *  the per-operation decay tail must survive. Heat fades over {@link activityDecayMs} measured
+   *  from when each *tool* finished (the PostToolUse cooldown), NOT from when the turn ends, so a
+   *  Stop must not cancel those cooldowns or clear `lastTouchedAt`. We only reset turn-scoped
+   *  state and force-finish any path whose PostToolUse never arrived before Stop: drop its
+   *  refcount to 0 (flipping `editing`/`reading` off so the pulse stops) and schedule the same
+   *  decay eviction a normal completion would. Contrast {@link resetBookkeeping}, which hard-
+   *  wipes everything for SessionStart/SessionEnd (the agent is gone, not merely between turns). */
+  private settleBookkeeping;
+  private cancelPendingFileClears;
+  private cancelPendingReadClears;
+  /** Extracts the targeted file path from a PreToolUse/PostToolUse event. Tries the raw
+   *  `hookInput.tool_input` passthrough first, falls back to the projected `event.toolInput`
+   *  for older CLI versions that only fill the top-level fields. Treats an empty-object
+   *  `hookInput.tool_input` as missing — `??` would have kept it (truthy) and shadowed a
+   *  populated `event.toolInput`. */
+  private getEventFilePath;
+  /** Stamps the per-path/per-kind `lastTouchedAt[kind]` to the current epoch ms. Stamped on every
+   *  PreToolUse for the matching kind so `serializeFileActivity` can emit `readAt`/`editedAt` as
+   *  a relative `now - timestamp` delta. */
+  private stampLastTouched;
+  /** Drops the `lastTouchedAt[kind]` slot for `filePath`, and the whole entry when neither kind
+   *  remains. Mirrors the cooldown-timer eviction in `scheduleClear*` — once the path is gone
+   *  from the count map for that kind, its timestamp is no longer load-bearing. */
+  private clearLastTouched;
+  /** Records that a file-mutating tool call is in flight against `filePath` so consumers can
+   *  highlight the path. Refcounts per path — keyed by path (not `tool_use_id`, which the GK CLI
+   *  doesn't reliably surface) so parallel calls bump the count and Post/Pre order doesn't matter.
+   *  Returns whether the parent's published `fileActivity` actually changed so callers can fire
+   *  when the surrounding {@link updateSessionStatus} short-circuits. */
+  private trackToolUseFile;
+  /** Decrements the in-flight refcount for a finished tool call's file. While the count stays
+   *  above zero (overlapping parallel calls) the path remains marked. When the count drops to
+   *  zero, leaves the entry in place at count `0` and schedules a {@link activityDecayMs}
+   *  cooldown before actually dropping it — so a recently-edited file lingers as a decay tail
+   *  on the treemap. A Pre arriving during cooldown cancels the timer and bumps the count back
+   *  above zero. Returns whether the parent's published `fileActivity` changed (i.e. `editing`
+   *  flipped off) so the PostToolUse caller can fire when its `updateSessionStatus` short-
+   *  circuits (a parallel tool still in flight keeps activeToolCount > 0). */
+  private scheduleClearToolUseFile;
+  /** Schedules (replacing any prior timer) the {@link activityDecayMs} cooldown that finally
+   *  drops `filePath` from the edit bookkeeping once it has fully decayed. Shared by the
+   *  PostToolUse cooldown path and the Stop settle ({@link settleBookkeeping}); the path stays
+   *  in `currentFileCounts` at count 0 meanwhile so its `editedAt` keeps aging on the client. */
+  private scheduleFileDecayEviction;
+  /** Drops a tracked tool call's file immediately (no cooldown). Used for PermissionDenied,
+   *  where the tool never ran — keeping the "live" badge would be misleading.
+   *  Returns whether the published list changed. */
+  private untrackToolUseFile;
+  /** Mirror of {@link getEventFilePath} for read-only file tools. */
+  private getEventReadPath;
+  /** Refcount mirror of {@link trackToolUseFile} for read-only file tools. */
+  private trackToolUseRead;
+  /** Cooldown mirror of {@link scheduleClearToolUseFile} for read-only file tools. Returns
+   *  whether the parent's published `fileActivity` changed (i.e. `reading` flipped off). */
+  private scheduleClearToolUseRead;
+  /** Read-class mirror of {@link scheduleFileDecayEviction}. */
+  private scheduleReadDecayEviction;
+  /** Immediate-drop mirror of {@link untrackToolUseFile} for read-only file tools. */
+  private untrackToolUseRead;
+  /** Convenience wrapper that resolves the parent for a possibly-sub-agent session id, then calls
+   *  {@link syncSessionFileActivity}. Tool-call handlers call this without knowing whether the
+   *  session is a top-level or sub-agent session. Returns `false` when the session isn't found
+   *  (already pruned / unknown peer id). */
+  private syncSessionFileActivityForChild;
+  /** Rebuilds the parent session's `fileActivity` array from its bookkeeping and writes it onto
+   *  the session in place. Returns whether the *structural* shape changed (paths/kinds/flags) —
+   *  timestamps are always refreshed regardless, but a fire is gated on structural change so
+   *  non-meaningful drift doesn't churn the wire.
+   *
+   *  No separate sub-agent rollup is needed: the GK CLI keys a sub-agent's tool events under its
+   *  PARENT session id (with `agentId` set), so they accumulate in the parent's own bookkeeping
+   *  directly and are already reflected here. Sub-agent serialized objects carry no `fileActivity`. */
+  private syncSessionFileActivity;
+  /** Defer the `Stop → idle` commit. If the agent produces a non-idle event within
+   *  `stopToIdleDebounceMs`, `cancelPendingIdleTransition` (called from `updateSessionStatus`)
+   *  cancels this and the session stays in its prior phase — no working → idle → working flicker.
+   *
+   *  Intentionally takes no context: the caller is expected to apply any event metadata
+   *  synchronously before scheduling. Carrying Stop-time context into the timer would let
+   *  in-window metadata mutations (e.g. `CwdChanged` updating `_sessions[i].cwd` directly)
+   *  get reverted when the deferred commit replays the stale context through `ensureSession`. */
+  private scheduleIdleTransition;
+  private cancelPendingIdleTransition;
+  /** Stable phase-since: if we're oscillating back into the phase we were just in (within a
+   *  short window), restore its original timestamp so the displayed elapsed time doesn't snap
+   *  to 0. Otherwise records the current phase as the new "prior" and returns `now`. */
+  private resolvePhaseSince;
+  /** Extracts the ask identity a settlement event refers to. `PostToolUse`/`PermissionDenied`
+   *  carry `hookInput.tool_use_id` and `hookInput.tool_input` in production; the top-level
+   *  `event.toolName`/`event.toolInput` are the older-CLI fallback. Input is canonicalized so key
+   *  order (or arriving via the fallback field instead of `hookInput`) doesn't defeat comparison. */
+  private settledByFromEvent;
+  private resolveAllPending;
+  private rejectAllPending;
+  private clearStalePermission;
+  resolvePermission(sessionId: string, decision: PermissionDecision, updatedPermissions?: PermissionSuggestion[]): boolean;
+  archiveSession(sessionId: string): Promise<boolean>;
+  /** Lists the ids of sessions the CLI has archived, so callers (the "Past" transcript listing) can
+   *  exclude them — the tracked row is gone, but the transcript on disk survives and would otherwise
+   *  resurface there. Resolves to `[]` on any error, including a CLI too old to support the
+   *  `archived` status filter. */
+  getArchivedSessionIds(): Promise<string[]>;
+  private fetchArchivedSessionIds;
+  resolveEndedSessionDetails(sessionId: string): void;
+  /** No `_sessions` gate, unlike {@link resolveEndedSessionDetails} — must work for a
+   *  transcript-only id this window never tracked live (past-session-sheet callers). */
+  resolveSessionDetails(sessionId: string, cwd?: string): Promise<EndedTranscriptDetails | undefined>;
+  private applyEndedTranscriptDetails;
+  private resolveWorkspacePath;
+  private updateSessionWithPermission;
+  private updateSessionStatus;
+  private ensureSession;
+  private resolveGitInfo;
+  private resolveTranscriptTitles;
+  /** Transitions the session at `index` to the terminal `ended` state in place: keeps the row,
+   *  stamps `endedAt` as its activity time, clears transient state (statusDetail, pendingPermission,
+   *  subagents), and tears down its bookkeeping/timers. Shared by the live `SessionEnd` path and the
+   *  poll backstop for a `SessionEnd` the live path missed. Does not fire change events — the caller
+   *  batches those. */
+  private endSession;
+  private pruneDeadSessions;
+  protected syncSessions(options?: {
+    gate?: boolean;
+  }): Promise<void>;
+  /** Relays an open-session request to whichever GitLens window hosts `sessionId`, via the GK
+   *  CLI's `gk ai hook open-session` relay — the CLI resolves the target window itself from its
+   *  own discovery-file view of every publishing GitLens window, so this process never scans for
+   *  peers directly. `--exclude-address` keeps the CLI from routing the request back to this
+   *  window when it also (redundantly) claims the session. Resolves to `false` on any spawn or
+   *  parse failure, or when the CLI predates the `open-session` hook command — never throws, and
+   *  never falls back to a direct peer HTTP call. */
+  relayOpenSession(sessionId: string, path: string): Promise<boolean>;
 }
+//#endregion
 //# sourceMappingURL=gkAgentProvider.d.ts.map