@codingame/monaco-vscode-api 36.2.7 → 37.1.0

package/vscode/src/vs/platform/agentHost/common/state/sessionState.d.ts

@@ -1,7 +1,10 @@
 import { URI as ResourceURI } from "../../../../base/common/uri.js";
 import { IProductService } from "../../../product/common/productService.service.js";
-import { TerminalState, ToolResultFileEditContent, type ActiveTurn, type ChangesetState, type ChatState, type ChatSummary, type ChatInputRequest, type PendingMessage, type Turn, type AnnotationsState, type URI as ProtocolURI, type RootState, type SessionState, type SessionSummary, type TextRange, type ToolCallCancelledState, type ToolCallCompletedState, type ToolCallResult, type ToolCallState, type ToolResultContent, type ToolResultSubagentContent, type UsageInfo, type Message } from "./protocol/state.js";
-export { ChangesetOperationScope, ChangesetOperationStatus, ChangesetStatus, CustomizationLoadStatus, CustomizationType, MessageAttachmentKind, MessageKind, PendingMessageKind, PolicyState, ResponsePartKind, ChatInputAnswerState as SessionInputAnswerState, ChatInputAnswerValueKind as SessionInputAnswerValueKind, ChatInputQuestionKind as SessionInputQuestionKind, ChatInputResponseKind as SessionInputResponseKind, ChatOriginKind, SessionLifecycle, SessionStatus, ToolCallCancellationReason, ToolCallConfirmationReason, ToolCallContributorKind, ToolCallStatus, ToolResultContentType, TurnState, type ActiveTurn, type AgentCustomization, type AgentCapabilities, type AgentInfo, type AgentSelection, type Annotation, type AnnotationEntry, type AnnotationsState, type AnnotationsSummary, type Changeset, type ChangesetFile, type ChangesetOperation, type ChangesetState, type ChatState, type ChatSummary, type ChatInteractivity, type ChatOrigin, type ChildCustomization, type ClientPluginCustomization, type ConfigPropertySchema, type ConfigSchema, type ContentRef, type Customization, type CustomizationDegradedState, type CustomizationErrorState, type CustomizationLoadedState, type CustomizationLoadingState, type CustomizationLoadState, type DirectoryCustomization, type ErrorInfo, type HookCustomization, type FileEdit as ISessionFileDiff, type ToolResultEmbeddedResourceContent as IToolResultBinaryContent, type MarkdownResponsePart, type McpServerCustomization, type MessageAttachment, type MessageResourceAttachment, type MessageEmbeddedResourceAttachment, type MessageAnnotationsAttachment, type ModelSelection, type PendingMessage, type PluginCustomization, type ProjectInfo, type PromptCustomization, type ReasoningResponsePart, type ResponsePart, type RootState, type RuleCustomization, type SessionActiveClient, type SessionConfigState, type ChatInputAnswer as SessionInputAnswer, type ChatInputOption as SessionInputOption, type ChatInputQuestion as SessionInputQuestion, type ChatInputRequest as SessionInputRequest, type SessionModelInfo, type SessionState, type SessionSummary, type SkillCustomization, type Snapshot, type StringOrMarkdown, type TerminalState, type TextRange, type ToolAnnotations, type ToolCallCancelledState, type ToolCallCompletedState, type ToolCallPendingConfirmationState, type ToolCallPendingResultConfirmationState, type ToolCallResponsePart, type ToolCallResult, type ToolCallRunningState, type ToolCallState, type ToolCallStreamingState, type ToolCallContributor, type ToolDefinition, type ToolResultContent, type ToolResultFileEditContent, type ToolResultShellExitContent, type ToolResultSubagentContent, type ToolResultTextContent, type Turn, type URI, type UsageInfo, type Message } from "./protocol/state.js";
+import { SessionStatus, TerminalState, ToolResultFileEditContent, ChatInteractivity, type ActiveTurn, type ChangesetState, type ChatState, type ChatSummary, type ErrorInfo, type ErrorResponsePart, type PendingMessage, type Turn, type AnnotationsState, type AutomationState, type AutomationRunState, type URI as ProtocolURI, type RootState, type SessionState, type SessionSummary, type TextRange, type ToolCallCancelledState, type ToolCallCompletedState, type ToolCallResult, type ToolCallState, type ToolInput, type ToolResultContent, type ToolResultSubagentContent, type UsageInfo, type Message } from "./protocol/state.js";
+export { ChangesetOperationScope, ChangesetOperationStatus, ChangesetStatus, CustomizationLoadStatus, CustomizationType, MessageAttachmentKind, MessageKind, PendingMessageKind, PolicyState, ResponsePartKind, ChatInteractivity, ChatOriginKind, SessionLifecycle, SessionStatus, ToolCallCancellationReason, ToolCallConfirmationReason, ToolCallContributorKind, ToolCallRiskAssessmentKind, ToolCallRiskAssessmentStatus, ToolCallStatus, ToolResultContentType, TurnState, type ActiveTurn, type AgentCustomization, type AgentCapabilities, type AgentInfo, type AgentSelection, type Annotation, type AnnotationEntry, type AnnotationOrigin, type AnnotationsState, type AnnotationsSummary, type Changeset, type ChangesetFile, type ChangesetOperation, type ChangesetState, type ChatState, type ChatSummary, type ChatOrigin, type ChildCustomization, type ClientPluginCustomization, type ConfigPropertySchema, type ConfigSchema, type ContentRef, type Customization, type CustomizationDegradedState, type CustomizationErrorState, type CustomizationLoadedState, type CustomizationLoadingState, type CustomizationLoadState, type DirectoryCustomization, type ErrorInfo, type HookCustomization, type FileEdit as ISessionFileDiff, type ToolResultEmbeddedResourceContent as IToolResultBinaryContent, type MarkdownResponsePart, type McpServerCustomization, type MessageAttachment, type MessageResourceAttachment, type MessageEmbeddedResourceAttachment, type MessageAnnotationsAttachment, type MessageChatAttachment, type ModelSelection, type PendingMessage, type PluginCustomization, type ProjectInfo, type PromptCustomization, type ReasoningResponsePart, type ErrorResponsePart, type ResponsePart, type RootState, type RuleCustomization, type SessionActiveClient, type AutomationState, type AutomationRunState, type SessionConfigState, type SessionModelInfo, type SessionState, type SessionSummary, type SkillCustomization, type Snapshot, type StringOrMarkdown, type TerminalState, type TextRange, type ToolAnnotations, type ToolCallCancelledState, type ToolCallCompletedState, type ToolCallPendingConfirmationState, type ToolCallPendingResultConfirmationState, type ToolCallResponsePart, type ToolCallResult, type ToolCallRiskAssessment, type ToolCallRiskAssessmentCompleteState, type ToolCallRiskAssessmentLoadingState, type ToolCallRunningState, type ToolCallState, type ToolCallStreamingState, type ToolCallContributor, type ToolDefinition, type ToolInput, type ToolResultContent, type ToolResultFileEditContent, type TerminalCommandResult, type ToolResultSubagentContent, type ToolResultTerminalContent, type ToolResultTextContent, type Turn, type URI, type UsageInfo, type Message } from "./protocol/state.js";
+export declare function getErrorResponsePart(turn: Turn | ActiveTurn | undefined): ErrorResponsePart | undefined;
+export declare function createErrorResponsePart(error: ErrorInfo, resumable?: boolean): ErrorResponsePart;
+export declare function mergeLogicalTurnUsage(previous: UsageInfo | undefined, current: UsageInfo | undefined): UsageInfo | undefined;
 /**
  * Well-known keys that may appear on {@link UsageInfo._meta}.
  * Clients MAY read these to provide enhanced UI (e.g. credit cost display).
@@ -9,16 +12,24 @@ export { ChangesetOperationScope, ChangesetOperationStatus, ChangesetStatus, Cus
 export interface UsageInfoMeta {
     /** Per-turn credit cost reported by the backend. */
     cost?: number;
+    /** The concrete model selected by Copilot Auto and the routing explanation. */
+    autoModeResolved?: IAutoModeResolvedInfo;
     /** Copilot-specific usage breakdown, including nano-AIU totals. */
     copilotUsage?: {
+        /** This turn's nano-AIU cost. */
         totalNanoAiu?: number;
+        /**
+         * The whole session's accumulated nano-AIU cost, as reported by the
+         * backend rather than summed from the turns. Clients SHOULD prefer this
+         * over adding up per-turn totals: it is authoritative, and it also
+         * covers work billed outside any turn (e.g. an out-of-turn compaction).
+         */
+        sessionTotalNanoAiu?: number;
         [key: string]: unknown;
     };
     /**
-     * Per-category account quota snapshots reported by the backend on the
-     * model-call usage event, keyed by quota type (e.g. `chat`,
-     * `premium_interactions`). Clients MAY use these to keep the account quota
-     * UI current without a separate quota fetch.
+     * Per-category account quota snapshots from the model-call usage event. Keyed by quota type:
+     * `premium_models` (or `premium_interactions` on older backends), `chat`, `session`, `weekly`.
      */
     quotaSnapshots?: {
         [quotaType: string]: {
@@ -30,10 +41,107 @@ export interface UsageInfoMeta {
             readonly overageAllowedWithExhaustedQuota?: boolean;
             /** ISO 8601 date when the quota resets, if applicable. */
             readonly resetDate?: string;
+            /** Whether this snapshot is billed against an AI-credits allocation. */
+            readonly tokenBasedBilling?: boolean;
+            /** Additional-usage budget cap in AI credits, when the backend reports one. */
+            readonly overageEntitlement?: number;
         } | undefined;
     };
+    /**
+     * Per-source context-window attribution breakdown reported by the SDK's
+     * `session.rpc.metadata.getContextAttribution()`. Populated asynchronously
+     * after each usage event and piped to the context-usage widget as
+     * `promptTokenDetails`.
+     */
+    contextAttribution?: IContextAttributionData;
+    /**
+     * Per-model token totals accumulated across every model call in the turn,
+     * including calls made by subagents and the summarization call a compaction
+     * performs. Unlike {@link UsageInfo.inputTokens}, which describes only the
+     * most recent model call, these are whole-turn sums, so clients can report
+     * what a completed turn consumed in aggregate.
+     */
+    turnTokenTotals?: readonly ITurnTokenTotal[];
+    /** Per-model token totals for this turn only, excluding descendant sub-agents (sum a tree without double-counting). */
+    directTurnTokenTotals?: readonly ITurnTokenTotal[];
+    /** Copilot usage for this turn only. The root's {@link copilotUsage} stays inclusive of descendants. */
+    directCopilotUsage?: {
+        readonly totalNanoAiu?: number;
+    };
     [key: string]: unknown;
 }
+/**
+ * Singleton channel containing the host-owned automation catalogue.
+ */
+export declare const AHP_AUTOMATIONS_SCHEME = "ahp-automations";
+export declare const AUTOMATION_CATALOG_URI = "ahp-automations://";
+/**
+ * Returns whether `uri` identifies the singleton automation catalogue channel,
+ * including forms normalized by the workbench {@link ResourceURI} class.
+ */
+export declare function isAhpAutomationCatalogChannel(uri: string): boolean;
+/** Returns whether `uri` identifies one automation-run channel. */
+export declare function isAhpAutomationRunChannel(uri: string): boolean;
+export declare function isMessageHiddenFromTranscript(message: Message): boolean;
+/** Whether only the message's request row is hidden while its response remains visible. */
+export declare function isMessageRequestHiddenFromTranscript(message: Message): boolean;
+export declare function readMessageSystemInitiatedLabel(message: Message): string | undefined;
+export declare function withMessageHiddenFromTranscript(message: Message, hidden: boolean | undefined): Message;
+/** Marks only the message's request row as hidden while preserving its response. */
+export declare function withMessageRequestHiddenFromTranscript(message: Message, hidden: boolean | undefined): Message;
+export declare function withMessageSystemInitiatedLabel(message: Message, label: string): Message;
+/**
+ * Whether `turn` is a hidden system notification the host appended purely to
+ * carry a message (e.g. an Agent Merge status change). It never reaches the
+ * provider and never captures a checkpoint, so it can never own file changes
+ * and must be skipped when resolving a "last turn" for per-turn changes.
+ *
+ * A *visible* system notification (a background-agent completion, an Agent
+ * Merge repair prompt) is a real turn and is deliberately not matched.
+ * A hidden workspace-continuation request is also a real provider turn.
+ */
+export declare function isHostNoticeTurn(turn: {
+    readonly message: Message;
+}): boolean;
+/** Returns the last turn id that can own file changes, or `undefined` if there is none. */
+export declare function lastAttributableTurnId(turns: readonly {
+    readonly id: string;
+    readonly message: Message;
+}[] | undefined): string | undefined;
+/** Whole-turn token consumption attributed to a single model. */
+export interface ITurnTokenTotal {
+    readonly model: string;
+    readonly inputTokens: number;
+    readonly cachedTokens: number;
+    readonly outputTokens: number;
+}
+export interface IAutoModeResolvedInfo {
+    readonly chosenModel: string;
+    readonly reasoningBucket?: "low" | "medium" | "high";
+    readonly categoryScores?: Readonly<Record<string, number | undefined>>;
+    readonly predictedLabel?: string;
+    readonly confidence?: number;
+    readonly candidateModels?: readonly string[];
+}
+/**
+ * Mirrors the SDK's `SessionContextAttribution` shape — a flat list of
+ * per-source entries describing what occupies the session's context window.
+ */
+export interface IContextAttributionData {
+    readonly totalTokens: number;
+    readonly entries: readonly IContextAttributionEntry[];
+    readonly compactions: {
+        readonly count: number;
+    };
+}
+export interface IContextAttributionEntry {
+    readonly kind: string;
+    readonly id: string;
+    readonly label: string;
+    readonly tokens: number;
+    readonly parentId?: string;
+    readonly attributes?: Readonly<Record<string, string | undefined>>;
+}
 /**
  * Reads the well-known {@link UsageInfoMeta} keys from a usage report's open
  * `_meta` bag, ignoring unrelated provider-specific keys and validating each
@@ -43,8 +151,20 @@ export interface UsageInfoMeta {
  * type. Returns an empty object when the bag is absent.
  */
 export declare function readUsageInfoMeta(usage: UsageInfo | undefined): UsageInfoMeta;
+/**
+ * Whether a usage report actually records consumption, as opposed to merely
+ * existing.
+ *
+ * A turn can carry a token-less {@link UsageInfo} that exists only to hold
+ * routing metadata — notably a Copilot Auto turn restored from the event log,
+ * which keeps `_meta.autoModeResolved` even though the usage event itself is
+ * ephemeral and was never persisted. Callers that ask "does this turn have
+ * usage?" almost always mean "does it have numbers to show", so route that
+ * question through here rather than testing the object for truthiness.
+ */
+export declare function hasReportedUsage(usage: UsageInfo | undefined): boolean;
 export { ChangesetOperationTargetKind, type ChangesetOperationFollowUp, type ChangesetOperationTarget } from "./protocol/commands.js";
-export { ChatInputAnswerState, ChatInputAnswerValueKind, ChatInputQuestionKind, ChatInputResponseKind, type ChatInputAnswer, type ChatInputOption, type ChatInputQuestion, type ChatInputRequest, } from "./protocol/state.js";
+export { ChatInputAnswerState, ChatInputAnswerValueKind, ChatInputQuestionKind, ChatInputResponseKind, type ChatInputAnswer, type ChatInputOption, type ChatInputQuestion, type ChatInputRequest, type InputRequestResponsePart, } from "./protocol/state.js";
 /**
  * The kind of file edit operation. Derived from the presence/absence of
  * `before`/`after` in {@link ToolResultFileEditContent}.
@@ -136,6 +256,8 @@ export type ToolCallStatusString = ToolCallState["status"];
  * Returns `undefined` if there are no text content parts.
  */
 export declare function getToolOutputText(result: ToolCallResult): string | undefined;
+/** Returns inline tool input, leaving referenced content to asynchronous consumers. */
+export declare function getInlineToolInput(toolInput: ToolInput | undefined): string | undefined;
 /**
  * Extracts file edit content entries from a tool call result's `content` array.
  * Returns an empty array if there are no file edit content parts.
@@ -198,14 +320,37 @@ export declare function createDefaultChatSummary(session: SessionSummary, chatUr
  * session's `chats` catalog in sync with a chat's denormalized state.
  */
 export declare function chatSummaryFromState(state: ChatState): ChatSummary;
-export declare function createActiveTurn(id: string, message: Message): ActiveTurn;
+/**
+ * The effective interactivity of a chat given its session's archived state.
+ *
+ * `interactivity` is the general read-only mechanism (e.g. subagent worker
+ * chats are `ReadOnly`). An archived session is read-only too, so its
+ * interactive chats are downgraded to `ReadOnly`. `Hidden` chats stay hidden —
+ * archiving only downgrades `Full` chats. Absent interactivity defaults to
+ * `Full` for backward compatibility.
+ *
+ * The host uses this to enforce read-only turns off a single signal
+ * ({@link isChatReadOnly}) rather than special-casing archived; the same rule
+ * is mirrored client-side to hide the composer.
+ */
+export declare function effectiveChatInteractivity(interactivity: ChatInteractivity | undefined, sessionArchived: boolean): ChatInteractivity;
+/**
+ * Whether a chat rejects user-dispatched turns, given its own interactivity and
+ * its session's archived state. `true` for `ReadOnly` chats (including archived
+ * sessions' interactive chats). See {@link effectiveChatInteractivity}.
+ */
+export declare function isChatReadOnly(interactivity: ChatInteractivity | undefined, sessionArchived: boolean): boolean;
+export declare function createActiveTurn(id: string, message: Message, startedAt: string): ActiveTurn;
+export declare function getTurnError(turn: Turn | undefined): ErrorInfo | undefined;
 export declare enum StateComponents {
     Root = 0,
     Session = 1,
     Chat = 2,
     Terminal = 3,
     Changeset = 4,
-    Annotations = 5
+    Annotations = 5,
+    AutomationCatalog = 6,
+    AutomationRun = 7
 }
 export type ComponentToState = {
     [StateComponents.Root]: RootState;
@@ -214,6 +359,8 @@ export type ComponentToState = {
     [StateComponents.Terminal]: TerminalState;
     [StateComponents.Changeset]: ChangesetState;
     [StateComponents.Annotations]: AnnotationsState;
+    [StateComponents.AutomationCatalog]: AutomationState;
+    [StateComponents.AutomationRun]: AutomationRunState;
 };
 /** Scheme used by chat channel URIs (`ahp-chat://...`). */
 export declare const AHP_CHAT_SCHEME = "ahp-chat";
@@ -260,6 +407,9 @@ export declare function parseDefaultChatUri(uri: ProtocolURI | ResourceURI): str
 export declare function parseRequiredSessionUriFromChatUri(uri: ProtocolURI | ResourceURI): string;
 /** Returns `true` when `uri` is the default chat of its session. */
 export declare function isDefaultChatUri(uri: ProtocolURI | ResourceURI): boolean;
+export declare function getSessionChatResource(state: Pick<SessionState, "defaultChat"> & {
+    readonly chats: readonly Pick<ChatSummary, "resource">[];
+}, chatId: string): ProtocolURI | undefined;
 /**
  * Resolves a feature-level `(session, chat)` pair to the single chat URI used by
  * the agent session/chat surface. A session always owns a DEFAULT chat addressed
@@ -268,21 +418,31 @@ export declare function isDefaultChatUri(uri: ProtocolURI | ResourceURI): boolea
  * agents never re-derive "is this the default chat?".
  */
 export declare function resolveChatUri(session: ResourceURI, chat: ResourceURI): ResourceURI;
+/**
+ * Resolves the URI a chat's persisted data is stored under — the same
+ * {@link resolveChatUri} rule applied to a chat channel URI alone, recovering
+ * the owning session from the channel. Agents key their per-session database
+ * and data directory by this value, so anything reading or writing that storage
+ * from outside the agent must derive it the same way. Returns `undefined` when
+ * `chatChannel` is not a parseable chat channel URI.
+ */
+export declare function chatStorageUri(chatChannel: ProtocolURI | ResourceURI): ResourceURI | undefined;
 /** Returns `true` when `uri` identifies a chat channel. */
 export declare function isAhpChatChannel(uri: string): boolean;
 /**
  * A single chat's effective session context: the shared {@link SessionState}
- * (working directory, active clients, config, customizations/MCP scope, …)
+ * (working directories, active clients, config, customizations/MCP scope, …)
  * resolved for one chat and merged with that chat's conversation contents.
  *
- * The protocol moved turns and pending/input state off the session and onto a
- * per-chat channel, and lets a chat override session defaults (e.g.
- * {@link ChatState.workingDirectory}). This composite recombines the session
- * with one of its chats — default or peer — so consumers read the chat's
- * effective context and conversation through one object without walking back to
- * the session to re-derive shared state. The inherited
- * {@link SessionState.workingDirectory} carries the chat's *effective* working
- * directory (its own override when present, else the session default).
+ * The protocol moved turns and pending state off the session and onto a
+ * per-chat channel, and lets a chat override the session's working directories
+ * with a subset (e.g. {@link ChatState.workingDirectories}). This composite
+ * recombines the session with one of its chats — default or peer — so consumers
+ * read the chat's effective context and conversation through one object without
+ * walking back to the session to re-derive shared state. The
+ * {@link ISessionWithDefaultChat.workingDirectories} carry the chat's *effective*
+ * working directories (its own subset override when present, else the session's
+ * full set).
  */
 export interface ISessionWithDefaultChat extends SessionState {
     /** Completed turns of this chat. */
@@ -293,15 +453,13 @@ export interface ISessionWithDefaultChat extends SessionState {
     steeringMessage?: PendingMessage;
     /** Queued messages pending on this chat. */
     queuedMessages?: PendingMessage[];
-    /** Input requests outstanding on this chat. */
-    inputRequests?: ChatInputRequest[];
     /** Draft input of this chat. */
     draft?: Message;
 }
 /**
  * Projects a {@link SessionState} and one of its {@link ChatState | chats}
  * (default or peer) into that chat's {@link ISessionWithDefaultChat | effective
- * session context}. Per-chat overrides (currently the working directory) are
+ * session context}. Per-chat overrides (the working-directories subset) are
  * layered over the session defaults, and the conversation fields are taken from
  * the chat. When the chat state is absent (e.g. not yet hydrated) the
  * conversation fields default to empty and the session defaults apply.
@@ -343,6 +501,63 @@ export declare const SESSION_META_GIT_KEY = "git";
  * not know about GitHub state.
  */
 export declare const SESSION_META_GITHUB_KEY = "github";
+/** Reserved key for durable source-control workflow provenance. */
+export declare const SESSION_META_SOURCE_CONTROL_KEY = "vscode.sourceControl";
+export declare const SESSION_META_PROMPT_CACHE_KEY = "vscode.promptCache";
+export declare const SESSION_META_MULTI_ROOT_KEY = "multiRoot";
+/** Reserved key for whether a session was first discovered in a provider-native catalog. */
+export declare const SESSION_META_EXTERNAL_KEY = "vscode.external";
+/** Multi-root workspace provenance attached by the creating client. */
+export interface ISessionMultiRootMetadata {
+    readonly workspaceFile: string;
+}
+/** Reads validated multi-root workspace provenance from session metadata. */
+export declare function readSessionMultiRootMetadata(meta: SessionMeta | undefined): ISessionMultiRootMetadata | undefined;
+/** Parses validated multi-root workspace provenance from its persisted JSON representation. */
+export declare function parseSessionMultiRootMetadata(value: string | undefined): ISessionMultiRootMetadata | undefined;
+/** Returns session metadata with the multi-root workspace provenance updated or removed. */
+export declare function withSessionMultiRootMetadata(meta: SessionMeta | undefined, multiRoot: ISessionMultiRootMetadata | undefined): SessionMeta | undefined;
+/** Latest known prompt-cache state for the model active in an agent session. */
+export interface ISessionPromptCacheState {
+    readonly modelId: string;
+    readonly cacheExpiresAt: string;
+}
+/** Reads the latest known prompt-cache state from session metadata. */
+export declare function readSessionPromptCacheState(meta: SessionMeta | undefined): ISessionPromptCacheState | undefined;
+/** Returns session metadata with the prompt-cache slot updated or removed. */
+export declare function withSessionPromptCacheState(meta: SessionMeta | undefined, promptCache: ISessionPromptCacheState | undefined): SessionMeta | undefined;
+/** Reserved key for the harness-owned new-session folder-picker decision. */
+export declare const SESSION_META_FOLDER_PICKER_KEY = "vscode.folderPicker";
+/**
+ * Harness-owned decision about the multi-root new-session Folder picker for an
+ * agent-host session, carried under {@link SessionMeta} at
+ * {@link SESSION_META_FOLDER_PICKER_KEY}.
+ *
+ * The provider (harness) owns this because the signal differs per backend — for
+ * example Copilot hides the picker when at most one workspace folder carries
+ * hooks under `.github/hooks/` (pinning that folder as {@link primary} when
+ * exactly one does), since the Copilot agent only applies hooks from the primary
+ * working directory, and shows the picker when several folders carry hooks so
+ * the user resolves the ambiguity. When {@link primary} is set, it names the
+ * working directory the client should auto-select before the session starts.
+ */
+export interface ISessionFolderPickerDecision {
+    /** Whether the client should hide the multi-root Folder picker. */
+    readonly hidden: boolean;
+    /**
+     * The working directory the client should auto-select as the primary, as a
+     * URI string. Present only when the harness pins a specific folder (it
+     * always accompanies `hidden: true`, but a `hidden` decision need not pin
+     * one — e.g. when no folder carries hooks the current selection is kept).
+     */
+    readonly primary?: string;
+}
+/** Reads the validated folder-picker decision from session metadata. */
+export declare function readSessionFolderPickerDecision(meta: SessionMeta | undefined): ISessionFolderPickerDecision | undefined;
+/** Parses the validated folder-picker decision from its persisted JSON representation. */
+export declare function parseSessionFolderPickerDecision(value: string | undefined): ISessionFolderPickerDecision | undefined;
+/** Returns session metadata with the folder-picker decision updated or removed. */
+export declare function withSessionFolderPickerDecision(meta: SessionMeta | undefined, decision: ISessionFolderPickerDecision | undefined): SessionMeta | undefined;
 /**
  * Git state of a session's working directory, carried under
  * {@link SessionMeta} at {@link SESSION_META_GIT_KEY}. Used by clients to
@@ -358,6 +573,12 @@ export interface ISessionGitState {
     readonly hasGitHubRemote?: boolean;
     /** Current branch name. */
     readonly branchName?: string;
+    /**
+     * Whether `HEAD` is detached, which is why {@link branchName} is absent.
+     * Distinguishes a legitimately branch-less checkout from git state left
+     * behind by a probe that failed before it could resolve the branch.
+     */
+    readonly isDetachedHead?: boolean;
     /** Base branch the work targets (e.g. `main`). */
     readonly baseBranchName?: string;
     /** Upstream tracking branch (e.g. `origin/feature`). */
@@ -368,11 +589,31 @@ export interface ISessionGitState {
     readonly outgoingChanges?: number;
     /** Number of files with uncommitted changes. */
     readonly uncommittedChanges?: number;
+    /** Whether the current branch has commits not contained in its local base branch. */
+    readonly hasBaseBranchChanges?: boolean;
     /** GitHub repository owner parsed from the working copy's GitHub remote (preferring `origin`, falling back to the first GitHub remote). */
     readonly githubOwner?: string;
+    /** GitHub owner parsed from the current branch's upstream or push remote. */
+    readonly githubHeadOwner?: string;
     /** GitHub repository name parsed from the working copy's GitHub remote (preferring `origin`, falling back to the first GitHub remote). */
     readonly githubRepo?: string;
 }
+export declare enum SessionSourceControlOutcome {
+    Merge = "merge",
+    PullRequest = "pullRequest"
+}
+/** Durable source-control workflow provenance for a session. */
+export interface ISessionSourceControlState {
+    readonly merge?: {
+        /** Resulting target-branch HEAD after the most recent successful merge. */
+        readonly commit: string;
+    };
+    readonly latestOutcome?: SessionSourceControlOutcome;
+}
+/** Reads validated source-control workflow provenance from session metadata. */
+export declare function readSessionSourceControlState(meta: SessionMeta | undefined): ISessionSourceControlState | undefined;
+/** Returns session metadata with source-control workflow provenance updated. */
+export declare function withSessionSourceControlState(meta: SessionMeta | undefined, state: ISessionSourceControlState | undefined): SessionMeta | undefined;
 /**
  * GitHub state of a session, carried under {@link SessionMeta} at
  * {@link SESSION_META_GITHUB_KEY}. Used by clients to drive GitHub-specific
@@ -387,9 +628,46 @@ export interface ISessionGitHubState {
     readonly owner?: string;
     /** The name of the GitHub repository. */
     readonly repo?: string;
-    /** The URL of the GitHub pull request. */
-    readonly pullRequestUrl?: string;
+    /** GitHub pull request URLs found for the session's checkouts, most recent first. */
+    readonly pullRequestUrls?: readonly string[];
+    /** Pull requests that predate a folder-isolated session. An empty array is a captured baseline. */
+    readonly initialPullRequestUrls?: readonly string[];
+    /** Pull requests explicitly associated through user intent, most recent first. */
+    readonly associatedPullRequestUrls?: readonly string[];
+    /** Last host-observed state of {@link pullRequestStateUrl}. */
+    readonly pullRequestState?: "open" | "closed" | "merged";
+    /** Pull request URL to which {@link pullRequestState} applies. */
+    readonly pullRequestStateUrl?: string;
+    /**
+     * The name of the branch the most recent {@link pullRequestUrls} entry was found (or created) for.
+     * A pull request always relates to a branch: when the working copy switches
+     * to a different branch the host keeps reporting the known pull request but
+     * resumes looking for one that belongs to the newly checked out branch.
+     */
+    readonly pullRequestBranchName?: string;
 }
+/**
+ * Whether the known pull request of `gitHubState` belongs to `branchName`.
+ *
+ * State persisted before pull requests were tracked per branch has no
+ * {@link ISessionGitHubState.pullRequestBranchName}; such a pull request is
+ * optimistically treated as belonging to the given branch so existing sessions
+ * keep their pull request affordances until the host has verified which branch
+ * it actually belongs to.
+ */
+export declare function hasSessionPullRequestForBranch(gitHubState: ISessionGitHubState | undefined, branchName: string | undefined): boolean;
+/** Returns pull requests related to the session rather than inherited from its folder checkout. */
+export declare function getSessionRelatedPullRequestUrls(gitHubState: ISessionGitHubState | undefined): readonly string[];
+/** Maximum pull requests retained for a session. */
+export declare const MAX_SESSION_PULL_REQUEST_REFERENCES = 10;
+/** Normalized key for comparing pull request URLs irrespective of case and trailing slashes. */
+export declare function getSessionPullRequestUrlKey(url: string): string;
+/** Returns GitHub state with `pullRequestUrl` moved to the front of its bounded history. */
+export declare function withMostRecentSessionPullRequest(gitHubState: ISessionGitHubState | undefined, pullRequestUrl: string, branchName: string): ISessionGitHubState;
+/** Returns state that promotes a pull request from the folder baseline into the session. */
+export declare function withMostRecentRelatedSessionPullRequest(gitHubState: ISessionGitHubState | undefined, pullRequestUrl: string, branchName: string): ISessionGitHubState;
+/** Returns state that records a pull request in the folder-session baseline. */
+export declare function withInitialSessionPullRequest(gitHubState: ISessionGitHubState | undefined, pullRequestUrl?: string): ISessionGitHubState;
 /**
  * Reads the well-known git-state payload from {@link SessionMeta}, if
  * present. Returns `undefined` when the meta bag is absent or the value at
@@ -402,6 +680,20 @@ export interface ISessionGitHubState {
  * reads a detached meta snapshot without retaining the owning state.
  */
 export declare function readSessionGitState(meta: SessionMeta | undefined): ISessionGitState | undefined;
+/**
+ * Whether a session's git state should be recomputed because it does not
+ * describe a usable checkout.
+ *
+ * A state that was never computed obviously qualifies. So does one that is
+ * missing its branch without a detached `HEAD` to explain it: `git status` is
+ * the only probe that reports the branch, so such a state is the residue of a
+ * probe that failed, and consumers that key off the branch (Agent Merge binds
+ * its pull request that way) stay stranded until it is recomputed. A detached
+ * `HEAD` is a legitimate branch-less checkout and must not be mistaken for it,
+ * or every caller would refresh in a loop against a repository that will never
+ * report a branch.
+ */
+export declare function needsSessionGitStateRefresh(gitState: ISessionGitState | undefined): boolean;
 /**
  * Returns a new {@link SessionMeta} with the git-state payload set to
  * `gitState`, or with the git slot removed if `gitState` is `undefined`.
@@ -426,6 +718,33 @@ export declare function readSessionGitHubState(meta: SessionSummaryMeta | undefi
  * Returns `undefined` if the result would be empty.
  */
 export declare function withSessionGitHubState(meta: SessionSummaryMeta | undefined, gitHubState: ISessionGitHubState | undefined): SessionSummaryMeta | undefined;
+/**
+ * Reserved key under {@link SessionSummaryMeta} recording how deeply a session
+ * was spawned via the `create_session` host tool (0 for a top-level, user-created
+ * session). Used to bound recursive session creation. VS Code-specific convention
+ * layered on top of the protocol's generic `_meta` bag.
+ */
+export declare const SESSION_META_SPAWN_DEPTH_KEY = "agentHost/sessionSpawnDepth";
+/**
+ * Reads the `create_session` spawn depth from a {@link SessionSummaryMeta} bag,
+ * returning `0` when the key is absent or not a finite number.
+ */
+export declare function readSessionSpawnDepth(meta: SessionSummaryMeta | undefined): number;
+/**
+ * Returns a new {@link SessionSummaryMeta} with the `create_session` spawn depth
+ * set to `depth`, preserving any other keys in the bag.
+ */
+export declare function withSessionSpawnDepth(meta: SessionSummaryMeta | undefined, depth: number): SessionSummaryMeta;
+export declare const SESSION_META_CREATED_BY_SESSION_KEY = "agentHost/createdBySession";
+export declare const AH_META_CREATED_BY_SESSION_DB_KEY = "agentHost.createdBySession";
+export interface ISessionCreationReference {
+    readonly session: string;
+    readonly chat?: string;
+    readonly turnId?: string;
+}
+export declare function readSessionCreationReference(meta: SessionSummaryMeta | undefined): ISessionCreationReference | undefined;
+export declare function parseSessionCreationReference(value: string | undefined): ISessionCreationReference | undefined;
+export declare function withSessionCreationReference(meta: SessionSummaryMeta | undefined, creationReference: ISessionCreationReference): SessionSummaryMeta;
 /**
  * Reserved key under {@link SessionSummaryMeta} marking a session as
  * workspace-less: a session with no workspace/folder binding (surfaced in the
@@ -443,6 +762,37 @@ export declare const SESSION_META_WORKSPACELESS_KEY = "workspaceless";
  * on resume) and never persist it themselves.
  */
 export declare const AH_META_WORKSPACELESS_DB_KEY = "agentHost.workspaceless";
+/** Session-database marker indicating that retained turns include workspace-transition boundaries. */
+export declare const AH_META_HAS_WORKSPACE_TRANSITIONS_DB_KEY = "agentHost.hasWorkspaceTransitions";
+/** Summary metadata mirror of {@link AH_META_HAS_WORKSPACE_TRANSITIONS_DB_KEY}. */
+export declare const SESSION_META_HAS_WORKSPACE_TRANSITIONS_KEY = "hasWorkspaceTransitions";
+/** Blocks turns for a session whose provider could not be detached from an untrusted working directory. */
+export declare const AH_META_WORKSPACE_CONVERSION_QUARANTINED_DB_KEY = "agentHost.workspaceConversionQuarantined";
+/**
+ * Session-database metadata key recording whether a session is archived. Written by
+ * the AH orchestrator (`AgentSideEffects` on `SessionIsArchivedChanged`) and read by
+ * both the orchestrator (`AgentService` restore/list) and agents (e.g. `CopilotAgent`
+ * decides whether to recreate a missing worktree vs. resume read-only for history).
+ * {@link AH_META_IS_DONE_DB_KEY} is the legacy name kept for sessions persisted before
+ * the rename; readers fall back to it when {@link AH_META_IS_ARCHIVED_DB_KEY} is absent.
+ */
+export declare const AH_META_IS_ARCHIVED_DB_KEY = "isArchived";
+/** Timestamp written only when merged-session cleanup automatically archives a session. */
+export declare const AH_META_AUTO_ARCHIVED_AT_DB_KEY = "agentHost.autoArchivedAt";
+/** Legacy metadata key for the archived flag; see {@link AH_META_IS_ARCHIVED_DB_KEY}. */
+export declare const AH_META_IS_DONE_DB_KEY = "isDone";
+/**
+ * Session-database metadata key recording whether a session has been read. This is
+ * the only durable representation of read state; the in-memory truth is
+ * {@link SessionStatus.IsRead}. The host owns it — no agent SDK tracks read state.
+ */
+export declare const AH_META_IS_READ_DB_KEY = "isRead";
+/** Returns `status` with `flag` set or cleared. */
+export declare function withSessionStatusFlag(status: SessionStatus, flag: SessionStatus, set: boolean): SessionStatus;
+/** Whether the {@link SessionStatus.IsRead} flag bit is set. */
+export declare function isSessionStatusRead(status: SessionStatus | undefined): boolean;
+/** Whether the {@link SessionStatus.IsArchived} flag bit is set. */
+export declare function isSessionStatusArchived(status: SessionStatus | undefined): boolean;
 /**
  * Reads the workspace-less marker from {@link SessionSummaryMeta}. Returns
  * `true` only when the well-known key is present and set to boolean `true`.
@@ -454,6 +804,62 @@ export declare function readSessionWorkspaceless(meta: SessionSummaryMeta | unde
  * if the result would be empty.
  */
 export declare function withSessionWorkspaceless(meta: SessionSummaryMeta | undefined, workspaceless: boolean): SessionSummaryMeta | undefined;
+/** Whether retained turns in this session include host-owned workspace transitions. */
+export declare function readSessionHasWorkspaceTransitions(meta: SessionSummaryMeta | undefined): boolean;
+/** Returns summary metadata with the workspace-transition history marker updated. */
+export declare function withSessionHasWorkspaceTransitions(meta: SessionSummaryMeta | undefined, hasTransitions: boolean): SessionSummaryMeta | undefined;
+/** Whether the session was first discovered in a provider-native catalog. */
+export declare function readSessionExternal(meta: SessionSummaryMeta | undefined): boolean;
+/** Returns a copy of `meta` with the external-session provenance marker updated. */
+export declare function withSessionExternal(meta: SessionSummaryMeta | undefined, external: boolean): SessionSummaryMeta | undefined;
+/**
+ * `_meta` key marking a session as an un-adopted legacy Copilot CLI session
+ * surfaced (only under the migrate setting) as adoptable. Clients read it to
+ * avoid passively subscribing to — and thereby migrating — the session before
+ * the user opens it. Cleared implicitly once the session is adopted (it no
+ * longer surfaces as adoptable).
+ */
+export declare const SESSION_META_EHCLI_ADOPTABLE_KEY = "ehcliAdoptable";
+/** Whether the session is an un-adopted legacy Copilot CLI session surfaced as adoptable. */
+export declare function readSessionEhcliAdoptable(meta: SessionSummaryMeta | undefined): boolean;
+/** Returns a new {@link SessionSummaryMeta} with the adoptable-legacy marker set. */
+export declare function withSessionEhcliAdoptable(meta: SessionSummaryMeta | undefined): SessionSummaryMeta;
+/**
+ * Session-DB key recording that a session was adopted from a legacy Copilot CLI
+ * (extension-host) chat. Unlike {@link SESSION_META_EHCLI_ADOPTABLE_KEY} this
+ * survives adoption, so consumers can keep treating the session as legacy for
+ * the rest of its life — a migrated session must not change how it is listed.
+ */
+export declare const AH_META_EHCLI_ADOPTED_DB_KEY = "agentHost.ehcliAdopted";
+/** `_meta` key mirroring {@link AH_META_EHCLI_ADOPTED_DB_KEY} on a summary. */
+export declare const SESSION_META_EHCLI_ADOPTED_KEY = "ehcliAdopted";
+/** Whether the session was adopted from a legacy Copilot CLI chat. */
+export declare function readSessionEhcliAdopted(meta: SessionSummaryMeta | undefined): boolean;
+/** Returns a copy of `meta` with the adopted-legacy provenance marker updated. */
+export declare function withSessionEhcliAdopted(meta: SessionSummaryMeta | undefined, adopted: boolean): SessionSummaryMeta | undefined;
+/**
+ * Session-DB key recording the id of the final turn that existed when a legacy
+ * Copilot CLI session was adopted. It marks the boundary between the migrated
+ * (checkpoint-less) history and any turns added after adoption, so a consumer
+ * that substitutes the session-wide changeset for a migrated turn's absent
+ * per-turn changeset (see the chat editor fallback) can target exactly that
+ * turn and never a post-adoption one.
+ */
+export declare const AH_META_EHCLI_LAST_TURN_DB_KEY = "agentHost.ehcliLastMigratedTurn";
+/** `_meta` key mirroring {@link AH_META_EHCLI_LAST_TURN_DB_KEY} on a summary. */
+export declare const SESSION_META_EHCLI_LAST_TURN_KEY = "ehcliLastMigratedTurn";
+/** The id of the last turn migrated when the legacy Copilot CLI session was adopted, if recorded. */
+export declare function readSessionEhcliLastMigratedTurn(meta: SessionSummaryMeta | undefined): string | undefined;
+/** Returns a copy of `meta` with the last-migrated-turn marker set, or unchanged when `turnId` is empty. */
+export declare function withSessionEhcliLastMigratedTurn(meta: SessionSummaryMeta | undefined, turnId: string | undefined): SessionSummaryMeta | undefined;
+/**
+ * Whether a session should be matched against a workspace folder by its project
+ * (repository) root in addition to its working directories. True only for
+ * legacy Copilot CLI sessions, which run out of a worktree outside the
+ * repository; agent-host-native worktree sessions are deliberately not surfaced
+ * in a window opened on their source repository.
+ */
+export declare function readSessionMatchesByProjectRoot(meta: SessionSummaryMeta | undefined): boolean;
 /**
  * VS Code-side alias for the protocol's open `_meta` property bag on
  * {@link RootState}. Keys SHOULD be namespaced to avoid collisions; values MUST