@gitkraken/core-gitlens 0.5.109 → 0.5.111

package/src/plus/agents/providers/claudeCodeTranscript.ts

@@ -2,6 +2,7 @@ import { createReadStream } from 'fs';
 import { open, readdir, stat } from 'fs/promises';
 import { homedir } from 'os';
 import { basename, join } from 'path';
+import { createInterface } from 'readline';
 
 export interface TranscriptTitles {
 	custom?: string;
@@ -30,6 +31,12 @@ export interface TranscriptSessionListing {
 	readonly total: number;
 }
 
+export interface CompletedTranscriptDetails {
+	titles: TranscriptTitles;
+	firstPrompt?: string;
+	lastPrompt?: string;
+}
+
 interface CacheEntry {
 	path: string;
 	mtimeMs: number;
@@ -147,12 +154,70 @@ export class ClaudeCodeTranscriptReader {
 		this._generations.delete(sessionId);
 	}
 
+	/**
+	 * One-shot read for a *completed* (terminal, static) session: extracts the transcript titles plus
+	 * the first and last user prompts. Unlike {@link resolve}, it bypasses the tail cache — a finished
+	 * transcript never grows, so it's read once on demand (when a completed row is opened) and the
+	 * result applied to the session. `last-prompt` entries carry the prompt as of that point; the first
+	 * one bearing a value is the session's opening prompt, the last its most recent. Returns `undefined`
+	 * when no transcript is found (archived/purged) — the caller keeps whatever durable-store fields it
+	 * already has.
+	 *
+	 * Streams the file line-by-line rather than buffering it whole: a finished transcript can run to
+	 * tens of MB, but this keeps only one line resident at a time. A *full* scan (not a head/tail
+	 * window) is required for correctness — when the first turn is large the opening `last-prompt` sits
+	 * past any fixed head window, and a windowed read would then mistake a later prompt for the first,
+	 * poisoning the derived session name.
+	 */
+	async resolveCompletedDetails(
+		sessionId: string,
+		cwd: string | undefined,
+	): Promise<CompletedTranscriptDetails | undefined> {
+		const path = await this.locateTranscript(sessionId, cwd);
+		if (path == null) return undefined;
+
+		let stats;
+		try {
+			stats = await stat(path);
+		} catch (ex) {
+			// A transcript that vanished is terminal; an I/O or permission failure must propagate so
+			// the caller retries rather than caching this session as permanently unresolvable.
+			if (!isMissingEntry(ex)) throw ex;
+
+			return undefined;
+		}
+		if (stats.size === 0) return undefined;
+
+		const titles: TranscriptTitles = {};
+		let firstPrompt: string | undefined;
+		let lastPrompt: string | undefined;
+
+		const rl = createInterface({ input: createReadStream(path, { encoding: 'utf8' }), crlfDelay: Infinity });
+		try {
+			for await (const line of rl) {
+				applyTitleLine(line, sessionId, titles);
+				if (!line.includes('last-prompt')) continue;
+
+				const entry = parseSummaryLine(line, sessionId);
+				if (entry?.type === 'last-prompt' && entry.lastPrompt != null && entry.lastPrompt.length > 0) {
+					firstPrompt ??= entry.lastPrompt;
+					lastPrompt = entry.lastPrompt;
+				}
+			}
+		} finally {
+			rl.close();
+		}
+
+		return { titles: titles, firstPrompt: firstPrompt, lastPrompt: lastPrompt };
+	}
+
 	/**
 	 * Lists the transcripts of sessions whose working directory is `cwd`, most-recently-active first,
 	 * summarizing until `limit` summarizable transcripts are found (bounded by a small scan slack) —
 	 * not just the first `limit` on disk, since junk transcripts (dropped below) would otherwise starve
-	 * the result. `excludeSessionIds` is skipped before `limit` applies, but excluded entries still
-	 * count toward `total`.
+	 * the result. `excludeSessionIds` is skipped before `limit` applies, and excluded entries are also
+	 * dropped from `total` — they're already shown elsewhere (e.g. as live sessions), so a caller's
+	 * "N of M" count must not double-count them.
 	 *
 	 * Claude homes a transcript under the directory encoding the session's *current* cwd, migrating the
 	 * file if the session `cd`s — so this directory is exactly the set `claude --resume <id>` can find
@@ -192,7 +257,7 @@ export class ClaudeCodeTranscriptReader {
 		// limit <= 0 means "no ceiling" — summarize every candidate.
 		if (limit <= 0) {
 			pushSummaries(await Promise.allSettled(candidates.map(e => this.resolveSummary(e))));
-			return { sessions: sessions, total: entries.length };
+			return { sessions: sessions, total: candidates.length };
 		}
 
 		const ceiling = Math.min(candidates.length, limit + listScanSlack);
@@ -205,7 +270,7 @@ export class ClaudeCodeTranscriptReader {
 			pushSummaries(await Promise.allSettled(batch.map(e => this.resolveSummary(e))));
 		}
 
-		return { sessions: sessions, total: entries.length };
+		return { sessions: sessions, total: candidates.length };
 	}
 
 	/** Discovers every transcript in `dir`, newest first. The directory also holds one sibling
@@ -353,7 +418,11 @@ export class ClaudeCodeTranscriptReader {
 		let dirs: string[];
 		try {
 			dirs = await readdir(root);
-		} catch {
+		} catch (ex) {
+			// Only a missing projects root means "no transcript". A transient failure propagates so the
+			// caller retries instead of caching a permanent miss.
+			if (!isMissingEntry(ex)) throw ex;
+
 			return undefined;
 		}
 
@@ -377,7 +446,9 @@ export class ClaudeCodeTranscriptReader {
 		let dirs: string[];
 		try {
 			dirs = await readdir(root);
-		} catch {
+		} catch (ex) {
+			if (!isMissingEntry(ex)) throw ex;
+
 			return undefined;
 		}
 
@@ -501,7 +572,10 @@ async function fileExists(path: string): Promise<boolean> {
 	try {
 		const stats = await stat(path);
 		return stats.isFile();
-	} catch {
+	} catch (ex) {
+		// See {@link isMissingEntry}: only a genuine absence is an answer.
+		if (!isMissingEntry(ex)) throw ex;
+
 		return false;
 	}
 }
@@ -510,11 +584,23 @@ async function directoryExists(path: string): Promise<boolean> {
 	try {
 		const stats = await stat(path);
 		return stats.isDirectory();
-	} catch {
-		return false;
+	} catch (ex) {
+		// "Not there" is an answer; anything else (EACCES, EIO, a mount hiccup) is a transient
+		// failure the caller must be able to tell apart — see {@link isMissingEntry}.
+		if (isMissingEntry(ex)) return false;
+
+		throw ex;
 	}
 }
 
+/** True for the "path simply isn't there" errno codes, as opposed to a transient I/O or permission
+ *  failure. Callers cache a genuine absence as terminal, so a transient failure must not look like
+ *  one — it would pin a session to its fallback name until the window reloads. */
+function isMissingEntry(ex: unknown): boolean {
+	const code = (ex as NodeJS.ErrnoException | undefined)?.code;
+	return code === 'ENOENT' || code === 'ENOTDIR';
+}
+
 function readSlice(path: string, start: number, end: number): Promise<Buffer> {
 	return new Promise((resolve, reject) => {
 		const chunks: Buffer[] = [];

package/src/plus/agents/types.ts

@@ -43,9 +43,12 @@ export type AgentSessionStatus =
 	| 'waiting'
 	| 'idle'
 	| 'compacting'
-	| 'permission_requested';
+	| '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';
 
-export type AgentSessionPhase = 'idle' | 'working' | 'waiting';
+export type AgentSessionPhase = 'idle' | 'working' | 'waiting' | 'completed';
 
 export function getPhaseForStatus(status: AgentSessionStatus): AgentSessionPhase {
 	switch (status) {
@@ -59,6 +62,8 @@ export function getPhaseForStatus(status: AgentSessionStatus): AgentSessionPhase
 			return 'waiting';
 		case 'idle':
 			return 'idle';
+		case 'completed':
+			return 'completed';
 	}
 }
 
@@ -101,6 +106,12 @@ export interface PendingPermission {
 	readonly questionText?: string;
 	/** Question-mode: total number of questions in the batch. */
 	readonly questionCount?: number;
+	/** `false` when GitLens holds no blocking hook entry to answer this ask, so `resolvePermission`
+	 *  can never route an Allow/Deny — the user must respond in the agent's own session. Set for
+	 *  elicitations (delivered on a non-blocking hook) and for asks discovered by the reconciliation
+	 *  poll instead of this window's IPC path. Surfaces must render an explanatory, button-less card
+	 *  when this is `false`. */
+	readonly resolvable?: boolean;
 }
 
 export interface AgentSession {
@@ -152,6 +163,16 @@ export interface AgentSession {
 	readonly isInWorkspace: boolean;
 	readonly lastPrompt?: string;
 	readonly firstPrompt?: string;
+	/** The model the session is running (e.g. `claude-opus-4-5`). Arrives on every hook event and in
+	 *  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. */
+	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
+	 *  another `Date`→string override. */
+	readonly endedAt?: number;
 	/** Per-file activity record covering both read-class (Read/NotebookRead) and edit-class
 	 *  (Edit/Write/MultiEdit/NotebookEdit) tool calls. Populated on PreToolUse; each path is retained
 	 *  and fades for the configured decay window measured from its own last PostToolUse — the tail
@@ -210,6 +231,10 @@ export interface AgentSessionProvider extends UnifiedDisposable {
 	stop(): void;
 	updateWorkspacePaths?(workspacePaths: string[]): void;
 
+	/** Forces an ungated reconciliation with the provider's durable session store (e.g. the sidebar's
+	 *  Refresh action). Omitted by providers with no durable store to poll. */
+	sync?(): Promise<void>;
+
 	/** 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. */
@@ -240,6 +265,25 @@ export interface AgentSessionProvider extends UnifiedDisposable {
 	 *  set via {@link ResumableSessionsOptions.excludeSessionIds} so exclusion happens before `limit`
 	 *  applies rather than after. */
 	listResumableSessions?(cwd: string, options?: ResumableSessionsOptions): Promise<ResumableSessionsResult>;
+
+	/** Archives a completed (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
+	 *  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
+	 *  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;
+
+	/** 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[]>;
 }
 
 export interface ResumableSessionsOptions {

package/src/plus/ai/errors.ts

@@ -120,3 +120,33 @@ export function classifyNetworkError(ex: unknown): AIErrorReason.NoNetwork | AIE
 	}
 	return sawFetchFailed ? AIErrorReason.NoNetwork : undefined;
 }
+
+/**
+ * Whether an error means AI itself is unavailable, rather than this particular request being
+ * unacceptable. The distinction matters to any caller running a loop: an unavailable-AI failure will
+ * repeat identically for every remaining item, so the loop should stop and say so, while a
+ * request-shaped failure (too large, no data) may well succeed on the next item.
+ *
+ * `RequestTooLarge` and `NoRequestData` are therefore deliberately excluded — they're properties of
+ * the one request that failed.
+ */
+export function isAIUnavailableError(ex: unknown): ex is AIError {
+	if (!(ex instanceof AIError)) return false;
+
+	switch (ex.reason) {
+		case AIErrorReason.DeniedByOrganization:
+		case AIErrorReason.DeniedByUser:
+		case AIErrorReason.NoEntitlement:
+		case AIErrorReason.RateLimitExceeded:
+		case AIErrorReason.RateLimitOrFundsExceeded:
+		case AIErrorReason.ServiceCapacityExceeded:
+		case AIErrorReason.Unauthorized:
+		case AIErrorReason.UserQuotaExceeded:
+		case AIErrorReason.NoNetwork:
+		case AIErrorReason.Unreachable:
+		case AIErrorReason.ModelNotSupported:
+			return true;
+		default:
+			return false;
+	}
+}

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

@@ -15,6 +15,11 @@ export interface AIModel<Provider extends AIProviders = AIProviders, Model exten
 	readonly temperature?: number | null;
 
 	readonly consumptionRateLabel?: string;
+
+	/** Whether the model supports native structured output (JSON schema); absent means capable
+	 *  (new models default on). Populated by dynamic catalogs (GitKraken, OpenRouter) and set to
+	 *  false on legacy static-registry entries; provider-wide gaps override the provider hook */
+	readonly supportsStructuredOutputs?: boolean;
 }
 
 export interface AIModelDescriptor<Provider extends AIProviders = AIProviders, Model extends string = string> {
@@ -50,36 +55,61 @@ export interface AIProviderDescriptorWithConfiguration<
 }
 
 export const openAIModels = <T extends OpenAIProviders>(provider: AIProviderDescriptor<T>): AIModel<T>[] => [
+	{
+		id: 'gpt-5.6',
+		name: 'GPT-5.6 Sol',
+		maxTokens: { input: 922000, output: 128000 }, // 1.05M context, but OpenAI caps input at 922k
+		provider: provider,
+	},
+	{
+		id: 'gpt-5.6-sol',
+		name: 'GPT-5.6 Sol',
+		maxTokens: { input: 922000, output: 128000 },
+		provider: provider,
+		hidden: true,
+	},
+	{
+		id: 'gpt-5.6-terra',
+		name: 'GPT-5.6 Terra',
+		maxTokens: { input: 922000, output: 128000 },
+		provider: provider,
+	},
+	{
+		id: 'gpt-5.6-luna',
+		name: 'GPT-5.6 Luna',
+		maxTokens: { input: 922000, output: 128000 },
+		provider: provider,
+		default: true,
+	},
 	{
 		id: 'gpt-5.5',
 		name: 'GPT-5.5',
-		maxTokens: { input: 400000, output: 128000 },
+		maxTokens: { input: 922000, output: 128000 },
 		provider: provider,
 	},
 	{
 		id: 'gpt-5.5-pro',
 		name: 'GPT-5.5 Pro',
-		maxTokens: { input: 400000, output: 272000 },
+		maxTokens: { input: 922000, output: 128000 },
 		provider: provider,
 		hidden: true,
 	},
 	{
 		id: 'gpt-5.4',
 		name: 'GPT-5.4',
-		maxTokens: { input: 400000, output: 128000 },
+		maxTokens: { input: 922000, output: 128000 },
 		provider: provider,
 	},
 	{
 		id: 'gpt-5.4-mini',
 		name: 'GPT-5.4 mini',
-		maxTokens: { input: 400000, output: 128000 },
+		maxTokens: { input: 272000, output: 128000 },
 		provider: provider,
-		default: true,
 	},
 	{
 		id: 'gpt-5.4-nano',
 		name: 'GPT-5.4 nano',
-		maxTokens: { input: 400000, output: 128000 },
+		maxTokens: { input: 272000, output: 128000 },
 		provider: provider,
 	},
 	{
@@ -310,6 +340,7 @@ export const openAIModels = <T extends OpenAIProviders>(provider: AIProviderDesc
 		provider: provider,
 		temperature: null,
 		hidden: true,
+		supportsStructuredOutputs: false,
 	},
 	{
 		id: 'o1-preview-2024-09-12',
@@ -318,6 +349,7 @@ export const openAIModels = <T extends OpenAIProviders>(provider: AIProviderDesc
 		provider: provider,
 		temperature: null,
 		hidden: true,
+		supportsStructuredOutputs: false,
 	},
 	{
 		id: 'o1-mini',
@@ -326,6 +358,7 @@ export const openAIModels = <T extends OpenAIProviders>(provider: AIProviderDesc
 		provider: provider,
 		temperature: null,
 		hidden: true,
+		supportsStructuredOutputs: false,
 	},
 	{
 		id: 'o1-mini-2024-09-12',
@@ -334,6 +367,7 @@ export const openAIModels = <T extends OpenAIProviders>(provider: AIProviderDesc
 		provider: provider,
 		temperature: null,
 		hidden: true,
+		supportsStructuredOutputs: false,
 	},
 	{
 		id: 'gpt-4o',
@@ -362,6 +396,8 @@ export const openAIModels = <T extends OpenAIProviders>(provider: AIProviderDesc
 		maxTokens: { input: 128000, output: 4096 },
 		provider: provider,
 		hidden: true,
+		// json_schema needs gpt-4o-2024-08-06+ (or o1+); the flagged legacy ids reject it with a 400
+		supportsStructuredOutputs: false,
 	},
 	{
 		id: 'chatgpt-4o-latest',
@@ -369,6 +405,7 @@ export const openAIModels = <T extends OpenAIProviders>(provider: AIProviderDesc
 		maxTokens: { input: 128000, output: 16384 },
 		provider: provider,
 		hidden: true,
+		supportsStructuredOutputs: false,
 	},
 	{
 		id: 'gpt-4o-mini',
@@ -390,6 +427,7 @@ export const openAIModels = <T extends OpenAIProviders>(provider: AIProviderDesc
 		maxTokens: { input: 128000, output: 4096 },
 		provider: provider,
 		hidden: true,
+		supportsStructuredOutputs: false,
 	},
 	{
 		id: 'gpt-4-turbo-2024-04-09',
@@ -397,6 +435,7 @@ export const openAIModels = <T extends OpenAIProviders>(provider: AIProviderDesc
 		maxTokens: { input: 128000, output: 4096 },
 		provider: provider,
 		hidden: true,
+		supportsStructuredOutputs: false,
 	},
 	{
 		id: 'gpt-4-turbo-preview',
@@ -404,6 +443,7 @@ export const openAIModels = <T extends OpenAIProviders>(provider: AIProviderDesc
 		maxTokens: { input: 128000, output: 4096 },
 		provider: provider,
 		hidden: true,
+		supportsStructuredOutputs: false,
 	},
 	{
 		id: 'gpt-4-0125-preview',
@@ -411,6 +451,7 @@ export const openAIModels = <T extends OpenAIProviders>(provider: AIProviderDesc
 		maxTokens: { input: 128000, output: 4096 },
 		provider: provider,
 		hidden: true,
+		supportsStructuredOutputs: false,
 	},
 	{
 		id: 'gpt-4-1106-preview',
@@ -418,6 +459,7 @@ export const openAIModels = <T extends OpenAIProviders>(provider: AIProviderDesc
 		maxTokens: { input: 128000, output: 4096 },
 		provider: provider,
 		hidden: true,
+		supportsStructuredOutputs: false,
 	},
 	{
 		id: 'gpt-4',
@@ -425,6 +467,7 @@ export const openAIModels = <T extends OpenAIProviders>(provider: AIProviderDesc
 		maxTokens: { input: 8192, output: 4096 },
 		provider: provider,
 		hidden: true,
+		supportsStructuredOutputs: false,
 	},
 	{
 		id: 'gpt-4-0613',
@@ -432,6 +475,7 @@ export const openAIModels = <T extends OpenAIProviders>(provider: AIProviderDesc
 		maxTokens: { input: 8192, output: 4096 },
 		provider: provider,
 		hidden: true,
+		supportsStructuredOutputs: false,
 	},
 	{
 		id: 'gpt-4-32k',
@@ -439,6 +483,7 @@ export const openAIModels = <T extends OpenAIProviders>(provider: AIProviderDesc
 		maxTokens: { input: 32768, output: 4096 },
 		provider: provider,
 		hidden: true,
+		supportsStructuredOutputs: false,
 	},
 	{
 		id: 'gpt-4-32k-0613',
@@ -446,6 +491,7 @@ export const openAIModels = <T extends OpenAIProviders>(provider: AIProviderDesc
 		maxTokens: { input: 32768, output: 4096 },
 		provider: provider,
 		hidden: true,
+		supportsStructuredOutputs: false,
 	},
 	{
 		id: 'gpt-3.5-turbo',
@@ -453,6 +499,7 @@ export const openAIModels = <T extends OpenAIProviders>(provider: AIProviderDesc
 		maxTokens: { input: 16385, output: 4096 },
 		provider: provider,
 		hidden: true,
+		supportsStructuredOutputs: false,
 	},
 	{
 		id: 'gpt-3.5-turbo-0125',
@@ -460,6 +507,7 @@ export const openAIModels = <T extends OpenAIProviders>(provider: AIProviderDesc
 		maxTokens: { input: 16385, output: 4096 },
 		provider: provider,
 		hidden: true,
+		supportsStructuredOutputs: false,
 	},
 	{
 		id: 'gpt-3.5-turbo-1106',
@@ -467,6 +515,7 @@ export const openAIModels = <T extends OpenAIProviders>(provider: AIProviderDesc
 		maxTokens: { input: 16385, output: 4096 },
 		provider: provider,
 		hidden: true,
+		supportsStructuredOutputs: false,
 	},
 	{
 		id: 'gpt-3.5-turbo-16k',
@@ -474,5 +523,6 @@ export const openAIModels = <T extends OpenAIProviders>(provider: AIProviderDesc
 		maxTokens: { input: 16385, output: 4096 },
 		provider: provider,
 		hidden: true,
+		supportsStructuredOutputs: false,
 	},
 ];

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

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

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

@@ -3,19 +3,77 @@ import type { Event } from '../../../utils/event.js';
 import type { AIProviders } from '../constants.js';
 import type { AIActionType, AIModel } from './model.js';
 
-export type AIChatMessageRole = 'assistant' | 'system' | 'user';
+export type AIChatMessageRole = 'assistant' | 'system' | 'tool' | 'user';
+
+/** A tool the model may call. `parameters` is a JSON Schema object — it maps to OpenAI's
+ *  `function.parameters` and Anthropic's `input_schema` unchanged. */
+export interface AIToolDefinition {
+	readonly name: string;
+	readonly description: string;
+	readonly parameters: Record<string, unknown>;
+}
+
+export interface AIToolCall {
+	readonly id: string;
+	readonly name: string;
+	readonly args: Record<string, unknown>;
+	/** Opaque provider reasoning token (the GitKraken proxy's `thought_signature`), base64-encoded.
+	 *  Must be echoed back on the next turn's assistant message or Anthropic rejects the tool result. */
+	readonly providerSignature?: string;
+}
 
 export type AISystemChatMessage = AIChatMessage<'system'>;
 export interface AIChatMessage<T extends AIChatMessageRole = 'assistant' | 'user'> {
 	role: T;
 	content: string;
+	/** Tool calls this assistant turn requested. Only sent to providers with `supportsTools`. */
+	toolCalls?: readonly AIToolCall[];
+	/** On `tool`-role messages, the {@link AIToolCall.id} this result answers. */
+	toolCallId?: string;
+	/** On `tool`-role messages, the name of the tool that produced this result. */
+	toolName?: string;
 }
 
+export type JSONSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';
+
+/** Portable JSON Schema subset accepted by every capable provider (OpenAI strict, Azure, Anthropic,
+ *  Gemini, Mistral, xAI, Ollama). Keep schemas within it: object root, `additionalProperties: false`
+ *  on every object, every property in `required` (model optionals as `['x', 'null']` unions), and no
+ *  pattern/format/min/max/recursion. */
+export type JSONSchema = {
+	readonly type: JSONSchemaType | readonly JSONSchemaType[];
+	readonly description?: string;
+	readonly properties?: Readonly<Record<string, JSONSchema>>;
+	readonly required?: readonly string[];
+	readonly items?: JSONSchema;
+	readonly enum?: readonly string[];
+	readonly additionalProperties?: boolean;
+};
+
+/** Canonical response format, shaped like OpenAI's `response_format.json_schema`; providers
+ *  translate it (the OpenAI envelope is always sent `strict: true`) */
+export type AIResponseFormat = {
+	/** OpenAI-envelope only ([a-zA-Z0-9_-], ≤64 chars); Anthropic/Ollama drop it */
+	readonly name: string;
+	readonly schema: JSONSchema;
+};
+
+export type AIFinishReason = 'length' | 'content_filter' | 'refusal';
+
 export interface AIProviderResponse<T> {
 	readonly id: string;
 	readonly content: string;
 	readonly model: AIModel;
 
+	/** Abnormal completion only (truncated/filtered/refused); undefined on a normal stop */
+	readonly finishReason?: AIFinishReason;
+
+	/** Tool calls the model requested. Present only when `tools` were sent and the model used them. */
+	readonly toolCalls?: readonly AIToolCall[];
+	/** Set when the request was retried without tools because the provider rejected them, so the
+	 *  caller can stop offering tools for the rest of the session. */
+	readonly toolsRejected?: boolean;
+
 	readonly usage?: {
 		readonly promptTokens?: number;
 		readonly completionTokens?: number;
@@ -37,6 +95,10 @@ export interface AIProvider<Provider extends AIProviders = AIProviders> extends
 	readonly id: Provider;
 	readonly name: string;
 
+	/** Whether this provider's wire format carries tool definitions, tool calls, and tool results.
+	 *  Providers that omit it never receive tool-shaped messages — callers fall back to text-only. */
+	readonly supportsTools?: boolean;
+
 	onDidChange?: Event<void>;
 
 	configured(silent: boolean): Promise<boolean>;
@@ -46,13 +108,18 @@ export interface AIProvider<Provider extends AIProviders = AIProviders> extends
 		action: T,
 		model: AIModel<Provider>,
 		apiKey: string,
-		getMessages: (maxInputTokens: number, retries: number) => Promise<AIChatMessage[]>,
+		getMessages: (maxInputTokens: number, retries: number) => Promise<AIChatMessage<AIChatMessageRole>[]>,
 		options: {
 			signal: AbortSignal;
 			modelOptions?: { outputTokens?: number; temperature?: number };
 			/** Opaque session ID the GitKraken provider sends as `GK-Conversation-ID` so the backend
 			 *  charges its per-feature fee once per session; ignored by all other providers. */
 			conversationId?: string;
+			/** Schema for the provider to enforce natively when the model supports it; providers
+			 *  without support ignore it and the prompt's JSON description carries the load. */
+			responseFormat?: AIResponseFormat;
+			/** Tools to advertise to the model. Only passed to providers with `supportsTools`. */
+			tools?: readonly AIToolDefinition[];
 		},
 	): Promise<AIProviderResponse<void> | undefined>;
 }