@gitkraken/core-gitlens 0.5.113 → 0.5.115

package/src/plus/agents/types.ts

@@ -1,8 +1,12 @@
 import type { IpcHandler } from '../../ipc/ipcServer.js';
 import type { UnifiedDisposable } from '../../utils/disposable.js';
 import type { Event } from '../../utils/event.js';
+import type { EndedTranscriptDetails } from './providers/claudeCodeTranscript.js';
 
-export const claudeCodeNonBlockingHookEvents = [
+/** Claude Code's native non-blocking hook event vocabulary, adopted as the canonical set for all
+ *  agents because it is a superset of every other supported agent's. Other agents map their native
+ *  event names onto these via `AgentCapabilities.eventMap` / `resolveEvent`. */
+export const canonicalNonBlockingHookEvents = [
 	'SessionStart',
 	'SessionEnd',
 	'UserPromptSubmit',
@@ -28,11 +32,11 @@ export const claudeCodeNonBlockingHookEvents = [
 	'CwdChanged',
 ] as const;
 
-export const claudeCodeBlockingHookEvents = ['PermissionRequest'] as const;
+export const canonicalBlockingHookEvents = ['PermissionRequest'] as const;
 
-export type ClaudeCodeHookEvent =
-	| (typeof claudeCodeNonBlockingHookEvents)[number]
-	| (typeof claudeCodeBlockingHookEvents)[number];
+export type AgentHookEvent =
+	| (typeof canonicalNonBlockingHookEvents)[number]
+	| (typeof canonicalBlockingHookEvents)[number];
 
 export type PermissionDecision = 'allow' | 'deny';
 
@@ -45,10 +49,14 @@ export type AgentSessionStatus =
 	| 'compacting'
 	| 'permission_requested'
 	// Terminal state: the session has ended (SessionEnd fired, or the CLI's durable store reports it
-	// `ended`). Kept in the list as a de-emphasized "completed" row until archived or 30-day-purged.
-	| 'completed';
+	// `ended`). Kept in the list as a de-emphasized "ended" row (shown as "Past" in the UI) until
+	// archived or 30-day-purged.
+	| 'ended';
 
-export type AgentSessionPhase = 'idle' | 'working' | 'waiting' | 'completed';
+export type AgentSessionPhase = 'idle' | 'working' | 'waiting' | 'ended';
+
+export type AgentSessionResumeTarget = 'default' | 'terminal';
+export type AgentSessionResumeOutcome = 'extension' | 'terminal';
 
 export function getPhaseForStatus(status: AgentSessionStatus): AgentSessionPhase {
 	switch (status) {
@@ -62,8 +70,8 @@ export function getPhaseForStatus(status: AgentSessionStatus): AgentSessionPhase
 			return 'waiting';
 		case 'idle':
 			return 'idle';
-		case 'completed':
-			return 'completed';
+		case 'ended':
+			return 'ended';
 	}
 }
 
@@ -123,6 +131,11 @@ export interface AgentSession {
 	readonly phase: AgentSessionPhase;
 	readonly statusDetail?: string;
 	readonly worktreePath?: string;
+	/** Distinct worktree roots this session has been observed in (normalized), ordered by recency —
+	 *  most recently observed LAST (so the current `worktreePath` is normally the final entry).
+	 *  Accumulated from the CLI's `cwdTimeline` and the git probe; never pruned for the session's
+	 *  lifetime. */
+	readonly visitedWorktreePaths?: readonly string[];
 	/** Common (parent) repo path shared by every worktree in this session's repo. Set together
 	 *  with `worktreePath` by `resolveGitInfo` — equal to `worktreePath` for a default-worktree
 	 *  session, otherwise the parent repo's common path. Use this for "same repo" identity
@@ -167,7 +180,7 @@ export interface AgentSession {
 	 *  the CLI's durable session record. */
 	readonly model?: string;
 	/** Why the session ended: `session-end | rotated | stale | dead-pid | pid-zero-idle | archived`.
-	 *  Present only for `completed` sessions. */
+	 *  Present only for `ended` sessions. */
 	readonly endReason?: string;
 	/** Epoch ms the session ended — matches the RPC convention for dates crossing to a webview
 	 *  (see `PastAgentSessionState.lastActivity`), and keeps `SerializedAgentSession` free of
@@ -224,6 +237,14 @@ export interface AgentSessionProvider extends UnifiedDisposable {
 	readonly name: string;
 	readonly icon: string;
 
+	/** Every {@link AgentSession.providerId} this provider can host — a DIFFERENT namespace from
+	 *  {@link id}, which names the provider itself. A provider that fronts several agents needs this
+	 *  so the host can route an action for a session it isn't tracking (a historical row, or one
+	 *  optimistically removed), where ownership-by-session-id has no answer. Omit it when the
+	 *  provider hosts exactly one agent whose session provider id equals its own {@link id}.
+	 */
+	readonly agentProviderIds?: readonly string[];
+
 	readonly onDidChangeSessions: Event<void>;
 	readonly sessions: readonly AgentSession[];
 
@@ -238,7 +259,7 @@ export interface AgentSessionProvider extends UnifiedDisposable {
 	/** Pushed by the host from its cached agent detection. Lets the provider gate its reconciliation
 	 *  poll (the CLI `list-sessions` call) so an idle window with no sessions and no installed hooks
 	 *  doesn't spawn the CLI every interval. */
-	setClaudeHooksInstalled?(installed: boolean): void;
+	setHooksInstalled?(installed: boolean): void;
 
 	/** Resolves a pending permission. Returns `true` when the resolve was routed (the local IPC
 	 *  owns the session's pending entry); `false` when no local entry exists (typically a peer-
@@ -259,57 +280,99 @@ export interface AgentSessionProvider extends UnifiedDisposable {
 	 *  window (which works whether or not the peer runs GitLens). */
 	notifyPeerOpenSession?(workspacePath: string, sessionId: string): Promise<boolean>;
 
-	/** Lists past sessions that can be resumed from `cwd`, most-recently-active first. Omitted by
-	 *  providers with no durable per-directory session store to read. Live sessions are excluded by
-	 *  the caller, not here — this reports what the store holds. The caller may also pass its live
-	 *  set via {@link ResumableSessionsOptions.excludeSessionIds} so exclusion happens before `limit`
-	 *  applies rather than after. */
-	listResumableSessions?(cwd: string, options?: ResumableSessionsOptions): Promise<ResumableSessionsResult>;
+	/** Lists historical sessions for `cwd`, most-recently-active first. Omitted by providers with no
+	 *  historical-session source. The provider owns reconciliation of its durable store, tracked
+	 *  terminal records, and archive state; callers only pass provider-local live ids to exclude.
+	 *  Each item advertises its supported actions independently, so an ended session can remain
+	 *  visible even when its transcript is missing or the harness cannot resume it. */
+	listSessionHistory?(cwd: string, options?: AgentSessionHistoryOptions): Promise<AgentSessionHistoryResult>;
 
-	/** Archives a completed (non-live) session via the CLI, dismissing it from the list. Ends an
+	/** Resumes one historical session using this harness's launcher. Providers only advertise a
+	 *  history `resume` action when this operation is wired and can service it. */
+	resumeSession?(
+		sessionId: string,
+		cwd: string,
+		target: AgentSessionResumeTarget,
+		name?: string,
+	): Promise<AgentSessionResumeOutcome | false>;
+
+	/** Monotonic count of terminal transitions — bumped whenever a session ends, is removed on end
+	 *  (legacy path), or is pruned. The host snapshots it around a history query and retries when it
+	 *  moved: any terminal transition mid-query means the answer may be missing a session, however
+	 *  the provider represents the transition (retained `ended` row or outright removal). Required —
+	 *  the host's consistency check depends on it, and an omitted counter would silently restore the
+	 *  missing-session race. A provider whose sessions never transition terminally exposes a
+	 *  constant `0`. */
+	readonly terminalGeneration: number;
+
+	/** Archives an ended (non-live) session via the CLI, dismissing it from the list. Ends an
 	 *  active session first (the CLI broadcasts a synthetic SessionEnd) — but callers should only
-	 *  offer this on `completed` sessions, and a provider refuses (returns `false`) any non-completed
+	 *  offer this on `ended` sessions, and a provider refuses (returns `false`) any non-ended
 	 *  row that resumed since the click, so the CLI never terminates live work. Resolves to `true` when
 	 *  the session was archived (removed locally; the next reconciliation poll confirms it). */
 	archiveSession?(sessionId: string): Promise<boolean>;
 
-	/** Resolves git identity + the transcript title and first/last prompt for a completed session
-	 *  lazily — called by the host when the user *opens* a completed row (the `Open Session` action),
-	 *  not on mere display. Completed sessions skip eager resolution during the poll so a 30-day
+	/** Resolves git identity + the transcript title and first/last prompt for an ended session
+	 *  lazily — called by the host when the user *opens* an ended row (the `Open Session` action),
+	 *  not on mere display. Ended sessions skip eager resolution during the poll so a 30-day
 	 *  cold-start doesn't fan out hundreds of git probes + transcript reads; the row shows its
-	 *  durable-store label until opened. No-op if the session isn't a tracked completed one. */
-	resolveCompletedSessionDetails?(sessionId: string): void;
+	 *  durable-store label until opened. No-op if the session isn't a tracked ended one. */
+	resolveEndedSessionDetails?(sessionId: string): void;
 
-	/** Lists the ids of sessions that have been archived. Used to exclude them from the "Past"
-	 *  transcript-store listing — the tracked row is gone once archived, but the transcript on disk
-	 *  survives and would otherwise resurface there. Resolves to `[]` on any error. */
-	getArchivedSessionIds?(): Promise<string[]>;
+	/** Resolves the transcript-backed detail (titles + first/last prompt) for a session lazily —
+	 *  called by the host when the user opens the past-session sheet, not on mere listing. No
+	 *  `_sessions` gate: works for a transcript-only id that was never tracked live this window. */
+	resolveSessionDetails?(sessionId: string, cwd?: string): Promise<EndedTranscriptDetails | undefined>;
 }
 
-export interface ResumableSessionsOptions {
-	/** How many sessions to detail. Discovery covers the whole store; only this many are read. */
+export type { EndedTranscriptDetails } from './providers/claudeCodeTranscript.js';
+
+export type AgentSessionHistoryDisposition = 'ended' | 'archived';
+
+export interface AgentSessionHistoryOptions {
+	/** How many sessions to detail. Discovery may cover the whole store while expensive summaries
+	 *  remain bounded. */
 	readonly limit?: number;
-	/** Session ids to skip before `limit` applies — typically the caller's live sessions.
-	 *  Excluded entries still count toward `total`. */
+	/** Provider-local session ids to skip before `limit` applies — typically the caller's live rows. */
 	readonly excludeSessionIds?: ReadonlySet<string>;
+	/** Restricts results to items that will advertise a resume action, and restricts `total` to
+	 *  counting only those — feeds the resume picker, whose "N of M" overflow header needs a
+	 *  resumable-only M. `total` stays a DISCOVERY count (an upper bound): a record whose transcript
+	 *  later proves empty or unreadable is dropped from `sessions` but still counted, since exact
+	 *  counting would mean summarizing every transcript in the store. */
+	readonly requireResume?: boolean;
+}
+
+/** Actions a provider can perform on one historical item. Action presence is the capability: a
+ *  resume action carries its required directory, while archive is appropriate to the item's
+ *  disposition. */
+export interface AgentSessionHistoryActions {
+	readonly resume?: { readonly cwd: string };
+	readonly archive?: true;
 }
 
-/** A session that is no longer running but whose transcript survives, so it can be resumed. */
-export interface ResumableAgentSession {
+/** A provider-local historical session. */
+export interface AgentSessionHistoryItem {
 	readonly id: string;
+	/** The owning agent's {@link AgentSession.providerId}. Set by the provider, which is the only
+	 *  side that knows it once one provider fronts several agents — and it has to match the live
+	 *  namespace exactly, because consumers dedupe a past row against a live one by
+	 *  `getAgentSessionIdentityKey(providerId, id)`. */
 	readonly providerId: string;
-	/** The directory the session must be resumed from — resolving it is the store's whole job. */
-	readonly cwd: string;
+	readonly disposition: AgentSessionHistoryDisposition;
+	readonly actions: AgentSessionHistoryActions;
 	readonly lastActivity: Date;
+	readonly name?: string;
 	/** Mirrors {@link AgentSession.transcriptTitles} — kept unresolved so naming stays the display
 	 *  cascade's job rather than being decided here. */
 	readonly titles?: { readonly custom?: string; readonly ai?: string; readonly agent?: string };
+	readonly firstPrompt?: string;
 	readonly lastPrompt?: string;
 }
 
-export interface ResumableSessionsResult {
-	readonly sessions: ResumableAgentSession[];
-	/** Everything the store holds for `cwd`, not just the detailed slice — drives "Showing N of M". */
+export interface AgentSessionHistoryResult {
+	readonly sessions: AgentSessionHistoryItem[];
+	/** Every matching historical record, not just the detailed slice — drives inline paging. */
 	readonly total: number;
 }
 
@@ -334,6 +397,18 @@ export interface IpcRegistrar {
 	unpublishAgents(): Promise<void>;
 }
 
+/** One entry of the host's current-agent listing, independent of the CLI's durable store.
+ *  `kind: 'background'` entries carry `state` and no `pid`, including terminal states the listing
+ *  retains; interactive entries carry `pid` and `status`. */
+export interface LiveAgentSession {
+	pid?: number;
+	cwd?: string;
+	kind?: string;
+	status?: string;
+	state?: string;
+	waitingFor?: string;
+}
+
 export interface AgentProviderCallbacks {
 	/** Host-supplied IPC service. Required for agents to receive hook events from the GK CLI. */
 	ipc: IpcRegistrar;
@@ -400,4 +475,26 @@ export interface AgentProviderCallbacks {
 	 * this to `claude-vscode.editor.open`. Throws if the extension isn't installed/active.
 	 */
 	openSessionInClaudeExtension?(sessionId: string): Promise<void>;
+
+	/** Host-side launcher wired into providers that support resumable history. Kept generic at the
+	 *  provider boundary: each harness chooses whether and when to expose it as a capability. */
+	resumeSession?(
+		sessionId: string,
+		cwd: string,
+		target: AgentSessionResumeTarget,
+		name?: string,
+	): Promise<AgentSessionResumeOutcome | false>;
+
+	/**
+	 * Host-supplied lookup of Claude's current interactive/background session listing, keyed by
+	 * session id. It revives stale durable `ended` records and narrowly corrects active records
+	 * whose last event is stale: first discovery and synthesized, unresolvable permission asks.
+	 * Terminal background states (`done`, `failed`, `stopped`) are listed but are not live; absence
+	 * from the map is unknown and must preserve record-derived state. `status` is set for
+	 * `kind: 'interactive'` entries (`'waiting'`, `'busy'`, …); `state` is set for
+	 * `kind: 'background'` entries instead (no `pid`). Declared structurally (not imported from
+	 * `@env/`) because this package cannot depend on the host's environment abstraction. Optional
+	 * on hosts with no such lookup; without it, durable records are trusted as-is.
+	 */
+	getLiveAgentSessions?(): Promise<ReadonlyMap<string, LiveAgentSession>>;
 }

package/src/plus/ai/models/promptTemplates.ts

@@ -133,7 +133,7 @@ export type PromptTemplateType =
 	| 'start-review-pullRequest'
 	| 'start-work-issue';
 
-type PromptTemplateVersions = '' | '_v2' | '_v3';
+type PromptTemplateVersions = '' | '_v2' | '_v3' | '_v4';
 
 export type PromptTemplateId<T extends PromptTemplateType = PromptTemplateType> = `${T}${PromptTemplateVersions}`;
 

package/src/plus/ai/prompts.ts

@@ -292,23 +292,35 @@ Example output structure:
 Based on the provided commit messages and associated issues, create a set of markdown changelog entries following the instructions above. Do not include any explanatory text or metadata`,
 };
 
+/** Example output block shared by the {@link generateSearchQuery} template and its structural-retry prompt */
+export const generateSearchQueryExampleJson = `{
+   "query": "[search operators here]",
+   "explanation": "[one short sentence describing the interpretation]",
+   "mode": "highlight",
+   "alternates": []
+}`;
+
 export const generateSearchQuery: PromptTemplate<'generate-searchQuery'> = {
-	id: 'generate-searchQuery_v2',
+	id: 'generate-searchQuery_v4',
 	variables: ['query', 'date', 'context', 'instructions'],
 	template: `You are an advanced AI assistant that converts natural language queries into structured Git search operators. Your task is to analyze a user's natural language query about their Git repository history and convert it into the appropriate search operators.
 
 Available search operators:
 - 'message:' - Search in commit messages (e.g. 'message:fix bug'); maps to \`git log --extended-regexp --grep=<value>\`
+- '-message:' - Exclude commits whose message contains a term (e.g. '-message:wip'); maps to \`git log --invert-grep --grep=<value>\`. Never mix 'message:' and '-message:' in the same query -- git's --invert-grep applies to every --grep pattern in the command, so combining included and excluded message terms is invalid.
 - 'author:' - Search by a specific author (e.g. 'author:eamodio' or use '@me' for current user); maps to \`git log --author=<value>\`
+- 'committer:' - Search by a specific committer (e.g. 'committer:eamodio' or use '@me' for current user); maps to \`git log --committer=<value>\`. There is no way to exclude an author or committer -- only to include one; if the user asks to exclude one, explain that limitation in the explanation field and omit the filter rather than inventing syntax.
 - 'commit:' - Search by a specific commit SHA (e.g. 'commit:4ce3a')
 - 'file:' - Search by file path (e.g. 'file:"package.json"', 'file:"*.ts"'); maps to \`git log -- <value>\`
 - 'change:' - Search by specific code changes using regular expressions (e.g. 'change:"function.*auth"', 'change:"import.*react"'); maps to \`git log -G<value>\`
-- 'type:' - Search by type -- supports stash, tip, and wip (e.g. 'type:stash', 'type:tip', 'type:wip'). Use 'type:wip' for queries about work in progress, uncommitted changes, or pending changes across worktrees.
+- 'type:' - Search by type -- supports stash, tip, merge, and wip (e.g. 'type:stash', 'type:tip', 'type:merge', 'type:wip'). Use 'type:merge' for merge commits only, and 'type:wip' for queries about work in progress, uncommitted changes, or pending changes across worktrees.
 - 'ref:' - Search for commits reachable by a reference (branch, tag, commit) or reference range. Supports single refs (e.g. 'ref:main', 'ref:v1.0'), two-dot ranges (e.g. 'ref:main..feature' for commits in feature but not in main), three-dot ranges (e.g. 'ref:main...feature' for symmetric difference), and relative refs (e.g. 'ref:HEAD~5..HEAD'); maps to \`git log <ref>\`
 - 'after:' - Search for commits after a certain date or range (e.g. 'after:2023-01-01', 'after:"6 months ago"', 'after:"last Tuesday"', 'after:"noon"', 'after:"1 month 2 days ago"'); maps to \`git log --since=<value>\`
 - 'before:' - Search for commits before a certain date or range (e.g. 'before:2023-01-01', 'before:"6 months ago"', 'before:"yesterday"', 'before:"3PM GMT"'); maps to \`git log --until=<value>\`
 
-File and change values should be double-quoted. You can use multiple message, author, file, change, and ref operators at the same time if needed.
+File and change values should be double-quoted. You can use multiple message, author, committer, file, change, and ref operators at the same time if needed.
+
+The values of 'message:', '-message:', 'author:', and 'committer:' are compiled as case-insensitive POSIX extended regular expressions (ERE). Any regex metacharacters in the user's intended literal text -- \`( ) [ ] { } . * + ? | ^ $ \\\` -- MUST be escaped with a backslash unless they are intentionally being used as regex.
 
 Use 'ref:' when the query involves exploring commit history within or between specific references. Use temporal operators ('after:', 'before:') for date-based filtering. These operators can be combined when appropriate.
 
@@ -320,11 +332,57 @@ Temporal queries leverage Git's 'approxidate' parser, which understands relative
 The current date is \${date}
 \${context}
 
+When repository refs (branches, worktrees) are listed in the context above, only use ref: values from that list — never invent a ref name.
+If the context above includes a previously failed query and the error it produced, return a corrected query that fixes that error while preserving the original intent.
+
 User Query: \${query}
 
 \${instructions}
 
-Convert the user's natural language query into the appropriate search operators. Return only the search query string without any explanatory text. If the query cannot be converted to search operators, return the original query as a message search. For complex temporal expressions that might be ambiguous, prefer simpler, more reliable relative date formats.`,
+Convert the user's natural language query into the appropriate search operators.
+
+Respond ONLY with a JSON object in this exact shape:
+- "query": the converted search query using the operators above, as a single string
+- "explanation": one short sentence, in the user's own terms, describing how their query was interpreted
+- "mode": one of "highlight", "filter", or "select" — "highlight" is the default (find and mark matches); use "filter" when the user asks to see ONLY matching commits (e.g. "only my commits", "just show", "filter to"); use "select" when the user asks to be taken to a specific commit or location (e.g. "take me to", "jump to", "what commit is X at", "where is")
+- "alternates": an array of 0-2 alternative queries for the same intent — one broader, one narrower, whichever make sense; use an empty array if none do
+
+If the query cannot be converted to search operators, put the original text in "query" as a message search with all regex metacharacters escaped, and explain that in "explanation".
+
+For complex temporal expressions that might be ambiguous, prefer simpler, more reliable relative date formats.
+
+Example output structure:
+${generateSearchQueryExampleJson}
+
+Return only the JSON object and no other text — no code fences, no explanatory text.`,
+};
+
+/** Schema counterpart of the {@link generateSearchQuery} template's described output shape */
+export const generateSearchQuerySchema: AIResponseFormat = {
+	name: 'generate_search_query',
+	schema: {
+		type: 'object',
+		additionalProperties: false,
+		required: ['query', 'explanation', 'mode', 'alternates'],
+		properties: {
+			query: { type: 'string', description: 'The converted search query using the documented operators' },
+			explanation: {
+				type: 'string',
+				description: "One short sentence, in the user's own terms, describing how the query was interpreted",
+			},
+			mode: {
+				type: 'string',
+				enum: ['highlight', 'filter', 'select'],
+				description:
+					'How the query should be applied: highlight matches, filter to only matches, or select/jump to a specific commit',
+			},
+			alternates: {
+				type: 'array',
+				items: { type: 'string' },
+				description: 'Up to 2 alternative queries for the same intent; empty array if none make sense',
+			},
+		},
+	},
 };
 
 /** Example output block shared by the {@link generateCommits} template and its structural-retry prompt */