session-events.ts

/**
 * AUTO-GENERATED FILE - DO NOT EDIT
 * Generated from: session-events.schema.json
 */

/**
 * Union of all session event variants emitted by the Copilot CLI runtime.
 */
export type SessionEvent =
  | StartEvent
  | ResumeEvent
  | RemoteSteerableChangedEvent
  | ErrorEvent
  | IdleEvent
  | TitleChangedEvent
  | ScheduleCreatedEvent
  | ScheduleCancelledEvent
  | ScheduleRearmedEvent
  | AutopilotObjectiveChangedEvent
  | InfoEvent
  | WarningEvent
  | ModelChangeEvent
  | ModeChangedEvent
  | SessionLimitsChangedEvent
  | PermissionsChangedEvent
  | PlanChangedEvent
  | TodosChangedEvent
  | WorkspaceFileChangedEvent
  | HandoffEvent
  | TruncationEvent
  | SnapshotRewindEvent
  | ShutdownEvent
  | UsageCheckpointEvent
  | ContextChangedEvent
  | UsageInfoEvent
  | CompactionStartEvent
  | CompactionCompleteEvent
  | TaskCompleteEvent
  | UserMessageEvent
  | PendingMessagesModifiedEvent
  | AssistantTurnStartEvent
  | AssistantIntentEvent
  | AssistantServerToolProgressEvent
  | AssistantReasoningEvent
  | AssistantReasoningDeltaEvent
  | AssistantToolCallDeltaEvent
  | AssistantStreamingDeltaEvent
  | AssistantMessageEvent
  | AssistantMessageStartEvent
  | AssistantMessageDeltaEvent
  | AssistantTurnEndEvent
  | AssistantIdleEvent
  | AssistantUsageEvent
  | ModelCallFailureEvent
  | AbortEvent
  | ToolUserRequestedEvent
  | ToolExecutionStartEvent
  | ToolExecutionPartialResultEvent
  | ToolExecutionProgressEvent
  | ToolExecutionCompleteEvent
  | SkillInvokedEvent
  | SubagentStartedEvent
  | SubagentCompletedEvent
  | SubagentFailedEvent
  | SubagentSelectedEvent
  | SubagentDeselectedEvent
  | HookStartEvent
  | HookEndEvent
  | HookProgressEvent
  | BinaryAssetEvent
  | SystemMessageEvent
  | SystemNotificationEvent
  | PermissionRequestedEvent
  | PermissionCompletedEvent
  | UserInputRequestedEvent
  | UserInputCompletedEvent
  | ElicitationRequestedEvent
  | ElicitationCompletedEvent
  | SamplingRequestedEvent
  | SamplingCompletedEvent
  | McpOauthRequiredEvent
  | McpOauthCompletedEvent
  | McpHeadersRefreshRequiredEvent
  | McpHeadersRefreshCompletedEvent
  | CustomNotificationEvent
  | ExternalToolRequestedEvent
  | ExternalToolCompletedEvent
  | CommandQueuedEvent
  | CommandExecuteEvent
  | CommandCompletedEvent
  | AutoModeSwitchRequestedEvent
  | AutoModeSwitchCompletedEvent
  | SessionLimitsExhaustedRequestedEvent
  | SessionLimitsExhaustedCompletedEvent
  | AutoModeResolvedEvent
  | ManagedSettingsResolvedEvent
  | CommandsChangedEvent
  | CapabilitiesChangedEvent
  | ExitPlanModeRequestedEvent
  | ExitPlanModeCompletedEvent
  | ToolsUpdatedEvent
  | BackgroundTasksChangedEvent
  | SkillsLoadedEvent
  | CustomAgentsUpdatedEvent
  | McpServersLoadedEvent
  | McpServerStatusChangedEvent
  | McpToolsListChangedEvent
  | McpResourcesListChangedEvent
  | McpPromptsListChangedEvent
  | ExtensionsLoadedEvent
  | CanvasOpenedEvent
  | CanvasRegistryChangedEvent
  | CanvasClosedEvent
  | CanvasUnavailableEvent
  | CanvasRecordedEvent
  | CanvasRemovedEvent
  | ExtensionsAttachmentsPushedEvent
  | McpAppToolCallCompleteEvent;
/**
 * Hosting platform type of the repository (github or ado)
 */
export type WorkingDirectoryContextHostType =
  /** Repository is hosted on GitHub. */
  | "github"
  /** Repository is hosted on Azure DevOps. */
  | "ado";
/**
 * Allowed values for the `ContextTier` enumeration.
 */
export type ContextTier =
  /** Default context tier with standard context window size. */
  | "default"
  /** Extended context tier with a larger context window. */
  | "long_context";
/**
 * Reasoning summary mode used for model calls, if applicable (e.g. "none", "concise", "detailed")
 */
export type ReasoningSummary =
  /** Do not request reasoning summaries from the model. */
  | "none"
  /** Request a concise summary of the model's reasoning. */
  | "concise"
  /** Request a detailed summary of the model's reasoning. */
  | "detailed";
/**
 * Output verbosity level used for supported model calls (e.g. "low", "medium", "high")
 */
export type Verbosity =
  /** A terse response was requested. */
  | "low"
  /** A medium amount of response detail was requested. */
  | "medium"
  /** A more detailed response was requested. */
  | "high";
/**
 * The type of operation performed on the autopilot objective state file
 */
export type AutopilotObjectiveChangedOperation =
  /** Autopilot objective state file was created for a new objective. */
  | "create"
  /** Autopilot objective state file was updated for an existing objective. */
  | "update"
  /** Autopilot objective state file was deleted or cleared. */
  | "delete";
/**
 * Current autopilot objective status, if one exists
 */
export type AutopilotObjectiveChangedStatus =
  /** Objective is active and can drive autopilot continuations. */
  | "active"
  /** Objective is paused and will not drive autopilot continuations. */
  | "paused"
  /** Legacy objective state indicating the previous continuation cap was reached. */
  | "cap_reached"
  /** Objective was completed by the agent. */
  | "completed";
/**
 * The session mode the agent is operating in
 */
export type SessionMode =
  /** The agent is responding interactively to the user. */
  | "interactive"
  /** The agent is preparing a plan before making changes. */
  | "plan"
  /** The agent is working autonomously toward task completion. */
  | "autopilot";
/**
 * Allow-all mode for the session.
 */
/** @experimental */
export type PermissionAllowAllMode =
  /** Permission requests follow the normal approval flow. */
  | "off"
  /** Tool, path, and URL permission requests are automatically approved. */
  | "on"
  /** Permission requests follow the normal approval flow with an LLM advisory recommendation attached; clients may choose to auto-approve requests the judge evaluated as acceptable. */
  | "auto";
/**
 * The type of operation performed on the plan file
 */
export type PlanChangedOperation =
  /** The plan file was created. */
  | "create"
  /** The plan file was updated. */
  | "update"
  /** The plan file was deleted. */
  | "delete";
/**
 * Whether the file was newly created or updated
 */
export type WorkspaceFileChangedOperation =
  /** The workspace file was created. */
  | "create"
  /** The workspace file was updated. */
  | "update";
/**
 * Origin type of the session being handed off
 */
export type HandoffSourceType =
  /** The handoff originated from a remote session. */
  | "remote"
  /** The handoff originated from a local session. */
  | "local";
/**
 * Whether the session ended normally ("routine") or due to a crash/fatal error ("error")
 */
export type ShutdownType =
  /** The session ended normally. */
  | "routine"
  /** The session ended because of a crash or fatal error. */
  | "error";
/**
 * The agent mode that was active when this message was sent
 */
export type UserMessageAgentMode =
  /** The agent is responding interactively to the user. */
  | "interactive"
  /** The agent is preparing a plan before making changes. */
  | "plan"
  /** The agent is working autonomously toward task completion. */
  | "autopilot"
  /** The agent is in shell-focused UI mode. */
  | "shell";
/**
 * A user message attachment — a file, directory, code selection, blob, GitHub reference, GitHub-anchored pointer, or extension-supplied context payload
 */
export type Attachment =
  | AttachmentFile
  | AttachmentDirectory
  | AttachmentSelection
  | AttachmentGitHubReference
  | AttachmentGitHubCommit
  | AttachmentGitHubRelease
  | AttachmentGitHubActionsJob
  | AttachmentGitHubRepository
  | AttachmentGitHubFileDiff
  | AttachmentGitHubTreeComparison
  | AttachmentGitHubUrl
  | AttachmentGitHubFile
  | AttachmentGitHubSnippet
  | AttachmentBlob
  | AttachmentExtensionContext;
/**
 * Why the binary data is absent: it exceeded the inline size limit, or its asset was unavailable
 */
export type OmittedBinaryOmittedReason =
  /** Bytes exceeded the session's inline size limit. */
  | "too_large"
  /** The referenced binary asset could not be found (e.g. a truncated log). */
  | "asset_unavailable";
/**
 * Type of GitHub reference
 */
export type AttachmentGitHubReferenceType =
  /** GitHub issue reference. */
  | "issue"
  /** GitHub pull request reference. */
  | "pr"
  /** GitHub discussion reference. */
  | "discussion";
/**
 * How this user message was delivered to the agentic loop, relative to whether the loop was already running. This is the timing axis only; the message's origin (human vs. system/command/schedule/skill/etc.) is carried separately by `source`. A system-injected message has a delivery too — e.g. a background-task notification waking an idle agent is `idle`, the same mechanism as a human starting a fresh turn.
 */
export type UserMessageDelivery =
  /** Delivered while the loop was idle; starts its own run immediately (a human's fresh turn, or a system notification waking an idle agent). */
  | "idle"
  /** Injected into the current in-flight run while the agent was busy (immediate mode). */
  | "steering"
  /** Enqueued while the agent was busy; processed as its own run afterward. */
  | "queued";
/**
 * Tool call type: "function" for standard tool calls, "custom" for grammar-based tool calls. Defaults to "function" when absent.
 */
export type AssistantMessageToolRequestType =
  /** Standard function-style tool call. */
  | "function"
  /** Custom grammar-based tool call. */
  | "custom";
/**
 * The system that produced a citation.
 */
/** @experimental */
export type CitationProvider =
  /** Citation produced by an Anthropic (Claude) model response. */
  | "anthropic"
  /** Citation produced by an OpenAI model response. */
  | "openai"
  /** Citation synthesized client-side by the runtime from tool output. */
  | "client";
/**
 * Location within a cited source (character, page, or content-block range) that supports a span.
 */
/** @experimental */
export type CitationLocation = CitationLocationChar | CitationLocationPage | CitationLocationBlock;
/**
 * API endpoint used for this model call, matching CAPI supported_endpoints vocabulary
 */
export type AssistantUsageApiEndpoint =
  /** Chat Completions API endpoint. */
  | "/chat/completions"
  /** Anthropic Messages API endpoint. */
  | "/v1/messages"
  /** Responses API endpoint. */
  | "/responses"
  /** WebSocket Responses API endpoint. */
  | "ws:/responses";
/**
 * For HTTP 400 failures only: whether the response carried a structured CAPI error envelope (structured_error, a deterministic validation failure) or no error body (bodyless, the transient gateway/proxy signature). Absent for non-400 failures.
 */
export type ModelCallFailureBadRequestKind =
  /** The 400 response carried no error body (transient gateway/proxy signature). */
  | "bodyless"
  /** The 400 response carried a structured CAPI error envelope (deterministic validation failure). */
  | "structured_error";
/**
 * Where the failed model call originated
 */
export type ModelCallFailureSource =
  /** Model call from the top-level agent. */
  | "top_level"
  /** Model call from a sub-agent. */
  | "subagent"
  /** Model call from MCP sampling. */
  | "mcp_sampling";
/**
 * Finite reason code describing why the current turn was aborted
 */
export type AbortReason =
  /** The local user requested the abort, for example by pressing Ctrl+C in the CLI. */
  | "user_initiated"
  /** A remote command requested the abort. */
  | "remote_command"
  /** An MCP server delivered a user.abort notification. */
  | "user_abort";
/**
 * Allowed values for the `ToolExecutionStartToolDescriptionMetaUIVisibility` enumeration.
 */
export type ToolExecutionStartToolDescriptionMetaUIVisibility =
  /** Tool is callable by the model (LLM tool surface) */
  | "model"
  /** Tool is callable by the MCP App view (iframe) via session.mcp.apps.callTool */
  | "app";
/**
 * A model-facing binary result as persisted: full inline data, a size-omitted marker, or a deduplicated asset reference
 */
/** @experimental */
export type PersistedBinaryResult = PersistedBinaryImage | OmittedBinaryResult | BinaryAssetReference;
/**
 * Binary result type discriminator. Use "image" for images and "resource" for other binary data.
 */
export type PersistedBinaryImageType =
  /** Binary image data. */
  | "image"
  /** Other binary resource data. */
  | "resource";
/**
 * Binary result type discriminator. Use "image" for images and "resource" for other binary data.
 */
export type OmittedBinaryType =
  /** Binary image data. */
  | "image"
  /** Other binary resource data. */
  | "resource";
/**
 * Binary result type discriminator. Use "image" for images and "resource" for other binary data.
 */
export type BinaryAssetReferenceType =
  /** Binary image data. */
  | "image"
  /** Other binary resource data. */
  | "resource";
/**
 * A content block within a tool result, which may be text, terminal output, image, audio, or a resource
 */
export type ToolExecutionCompleteContent =
  | ToolExecutionCompleteContentText
  | ToolExecutionCompleteContentTerminal
  | ToolExecutionCompleteContentShellExit
  | ToolExecutionCompleteContentImage
  | ToolExecutionCompleteContentAudio
  | ToolExecutionCompleteContentResourceLink
  | ToolExecutionCompleteContentResource;
/**
 * Theme variant this icon is intended for
 */
export type ToolExecutionCompleteContentResourceLinkIconTheme =
  /** Icon intended for light themes. */
  | "light"
  /** Icon intended for dark themes. */
  | "dark";
/**
 * The embedded resource contents, either text or base64-encoded binary
 */
export type ToolExecutionCompleteContentResourceDetails = EmbeddedTextResourceContents | EmbeddedBlobResourceContents;
/**
 * Allowed values for the `ToolExecutionCompleteToolDescriptionMetaUIVisibility` enumeration.
 */
export type ToolExecutionCompleteToolDescriptionMetaUIVisibility =
  /** Tool is callable by the model (LLM tool surface) */
  | "model"
  /** Tool is callable by the MCP App view (iframe) via session.mcp.apps.callTool */
  | "app";
/**
 * What triggered the skill invocation: `user-invoked` (explicit user action, such as via a slash command or UI affordance), `agent-invoked` (agent requested the skill), or `context-load` (loaded as part of another context, such as preloading skills configured on a custom agent or subagent)
 */
export type SkillInvokedTrigger =
  /** Skill invocation requested explicitly by the user, such as via a slash command or UI affordance. */
  | "user-invoked"
  /** Skill invocation requested by the agent. */
  | "agent-invoked"
  /** Skill content loaded as part of another context, such as a configured custom agent or subagent. */
  | "context-load";
/**
 * Binary asset type discriminator. Use "image" for images and "resource" otherwise.
 */
export type BinaryAssetType =
  /** Binary image data. */
  | "image"
  /** Other binary resource data. */
  | "resource";
/**
 * Message role: "system" for system prompts, "developer" for developer-injected instructions
 */
export type SystemMessageRole =
  /** System prompt message. */
  | "system"
  /** Developer instruction message. */
  | "developer";
/**
 * Structured metadata identifying what triggered this notification
 */
export type SystemNotification =
  | SystemNotificationAgentCompleted
  | SystemNotificationAgentIdle
  | SystemNotificationNewInboxMessage
  | SystemNotificationShellCompleted
  | SystemNotificationShellDetachedCompleted
  | SystemNotificationInstructionDiscovered;
/**
 * Whether the agent completed successfully or failed
 */
export type SystemNotificationAgentCompletedStatus =
  /** The agent completed successfully. */
  | "completed"
  /** The agent failed. */
  | "failed";
/**
 * Details of the permission being requested
 */
export type PermissionRequest =
  | PermissionRequestShell
  | PermissionRequestWrite
  | PermissionRequestRead
  | PermissionRequestMcp
  | PermissionRequestUrl
  | PermissionRequestMemory
  | PermissionRequestCustomTool
  | PermissionRequestHook
  | PermissionRequestExtensionManagement
  | PermissionRequestExtensionPermissionAccess;
/**
 * Whether this is a store or vote memory operation
 */
export type PermissionRequestMemoryAction =
  /** Store a new memory. */
  | "store"
  /** Vote on an existing memory. */
  | "vote";
/**
 * Vote direction (vote only)
 */
export type PermissionRequestMemoryDirection =
  /** Vote that the memory is useful or accurate. */
  | "upvote"
  /** Vote that the memory is incorrect or outdated. */
  | "downvote";
/**
 * Derived user-facing permission prompt details for UI consumers
 */
export type PermissionPromptRequest =
  | PermissionPromptRequestCommands
  | PermissionPromptRequestWrite
  | PermissionPromptRequestRead
  | PermissionPromptRequestMcp
  | PermissionPromptRequestUrl
  | PermissionPromptRequestMemory
  | PermissionPromptRequestCustomTool
  | PermissionPromptRequestPath
  | PermissionPromptRequestHook
  | PermissionPromptRequestExtensionManagement
  | PermissionPromptRequestExtensionPermissionAccess;
/**
 * Outcome of the auto-approval safety judge for a permission request. Present only when auto mode is enabled; its absence means the judge did not evaluate the request (auto mode was off).
 */
/** @experimental */
export type AutoApprovalRecommendation =
  /** The judge evaluated the request and recommends automatically approving it. */
  | "approve"
  /** The judge evaluated the request and does not recommend auto-approving it; explicit approval is required. Whether that means prompting, denying, or something else is the consumer's decision. */
  | "requireApproval"
  /** Auto mode is enabled, but this request category is never auto-approvable (for example, sandbox-bypass requests), so the judge was not consulted. */
  | "excluded"
  /** The judge was consulted but did not return a usable recommendation, so the request requires explicit approval. */
  | "error";
/**
 * Underlying permission kind that needs path approval
 */
export type PermissionPromptRequestPathAccessKind =
  /** Read access to a filesystem path. */
  | "read"
  /** Shell command access involving a filesystem path. */
  | "shell"
  /** Write access to a filesystem path. */
  | "write";
/**
 * The result of the permission request
 */
export type PermissionResult =
  | PermissionApproved
  | PermissionApprovedForSession
  | PermissionApprovedForLocation
  | PermissionCancelled
  | PermissionDeniedByRules
  | PermissionDeniedNoApprovalRuleAndCouldNotRequestFromUser
  | PermissionDeniedInteractivelyByUser
  | PermissionDeniedByContentExclusionPolicy
  | PermissionDeniedByPermissionRequestHook;
/**
 * The approval to add as a session-scoped rule
 */
export type UserToolSessionApproval =
  | UserToolSessionApprovalCommands
  | UserToolSessionApprovalRead
  | UserToolSessionApprovalWrite
  | UserToolSessionApprovalMcp
  | UserToolSessionApprovalMemory
  | UserToolSessionApprovalCustomTool
  | UserToolSessionApprovalExtensionManagement
  | UserToolSessionApprovalExtensionPermissionAccess;
/**
 * Elicitation mode; "form" for structured input, "url" for browser-based. Defaults to "form" when absent.
 */
export type ElicitationRequestedMode =
  /** Structured form-based elicitation. */
  | "form"
  /** Browser URL-based elicitation. */
  | "url";
/**
 * The user action: "accept" (submitted form), "decline" (explicitly refused), or "cancel" (dismissed)
 */
export type ElicitationCompletedAction =
  /** The user submitted the requested form. */
  | "accept"
  /** The user explicitly declined the request. */
  | "decline"
  /** The user dismissed the request. */
  | "cancel";
/**
 * Reason the runtime is requesting host-provided MCP OAuth credentials
 */
export type McpOauthRequestReason =
  /** Initial credentials are required before connecting to the MCP server. */
  | "initial"
  /** The current host-provided credential was rejected and a replacement is requested. */
  | "refresh"
  /** The server requires a new host authorization flow before continuing. */
  | "reauth"
  /** The server requires a credential with additional scope or audience. */
  | "upscope";
/**
 * How the pending MCP OAuth request was completed
 */
export type McpOauthCompletionOutcome =
  /** The request completed with a token-backed OAuth provider. */
  | "token"
  /** The request completed without an OAuth provider. */
  | "cancelled";
/**
 * Why dynamic headers are being requested.
 */
export type McpHeadersRefreshRequiredReason =
  /** The transport is making its first dynamic header request for this server. */
  | "startup"
  /** The previously cached dynamic headers expired. */
  | "ttl-expired"
  /** The server returned 401 and stale dynamic headers were invalidated. */
  | "auth-failed";
/**
 * How the pending MCP headers refresh request resolved.
 */
export type McpHeadersRefreshCompletedOutcome =
  /** The host supplied dynamic headers. */
  | "headers"
  /** The host responded with no dynamic headers. */
  | "none"
  /** No response arrived within the bounded window. */
  | "timeout";
/**
 * The user's auto-mode-switch choice
 */
export type AutoModeSwitchResponse =
  /** Switch models for this request. */
  | "yes"
  /** Switch models now and keep using the replacement automatically. */
  | "yes_always"
  /** Do not switch models. */
  | "no";
/**
 * User action selected for an exhausted session limit.
 */
export type SessionLimitsExhaustedResponseAction =
  /** Increase the current max by an exact AI Credits amount. */
  | "add"
  /** Set a new absolute max AI Credits value. */
  | "set"
  /** Remove the current session limit. */
  | "unset"
  /** Leave the limit unchanged and cancel the blocked model request. */
  | "cancel";
/**
 * Coarse request-difficulty bucket for UX explainability
 */
export type AutoModeResolvedReasoningBucket =
  /** The request looks low-reasoning; a lighter model is appropriate. */
  | "low"
  /** The request needs a moderate amount of reasoning. */
  | "medium"
  /** The request looks high-reasoning; a stronger model is appropriate. */
  | "high";
/**
 * Which channel supplied the effective enterprise managed settings (highest-authority present layer wins wholesale)
 */
export type ManagedSettingsResolvedSource =
  /** Account/org policy self-fetched from the GitHub managed-settings endpoint (higher authority). */
  | "server"
  /** Device-level MDM policy discovered from plist/registry/file (lower authority). */
  | "device"
  /** No managed policy is in force (no layer contributed). */
  | "none";
/**
 * Exit plan mode action
 */
export type ExitPlanModeAction =
  /** Exit plan mode without starting implementation. */
  | "exit_only"
  /** Exit plan mode and continue in interactive mode. */
  | "interactive"
  /** Exit plan mode and continue autonomously. */
  | "autopilot"
  /** Exit plan mode and continue with parallel autonomous workers. */
  | "autopilot_fleet";
/**
 * Source location type (e.g., project, personal-copilot, plugin, builtin)
 */
export type SkillSource =
  /** Skill defined in the current project's skill directories. */
  | "project"
  /** Skill discovered from a parent directory in the current workspace tree. */
  | "inherited"
  /** Skill defined in the user's Copilot skill directory. */
  | "personal-copilot"
  /** Skill defined in the user's personal agents skill directory. */
  | "personal-agents"
  /** Skill provided by an installed plugin. */
  | "plugin"
  /** Skill loaded from a configured custom skill directory. */
  | "custom"
  /** Skill bundled with the runtime. */
  | "builtin";
/**
 * Configuration source: user, workspace, plugin, or builtin
 */
export type McpServerSource =
  /** Server configured in the user's global MCP configuration. */
  | "user"
  /** Server configured by the current workspace. */
  | "workspace"
  /** Server contributed by an installed plugin. */
  | "plugin"
  /** Server bundled with the runtime. */
  | "builtin";
/**
 * Connection status: connected, failed, needs-auth, pending, disabled, or not_configured
 */
export type McpServerStatus =
  /** The server is connected and available. */
  | "connected"
  /** The server failed to connect or initialize. */
  | "failed"
  /** The server requires authentication before it can connect. */
  | "needs-auth"
  /** The server connection is still being established. */
  | "pending"
  /** The server is configured but disabled. */
  | "disabled"
  /** The server is not configured for this session. */
  | "not_configured";
/**
 * Transport mechanism: stdio, http, sse (deprecated), or memory (in-process MCP server)
 */
export type McpServerTransport =
  /** Server communicates over stdio with a local child process. */
  | "stdio"
  /** Server communicates over streamable HTTP. */
  | "http"
  /** Server communicates over Server-Sent Events (deprecated). */
  | "sse"
  /** Server is backed by an in-memory runtime implementation. */
  | "memory";
/**
 * Discovery source
 */
export type ExtensionsLoadedExtensionSource =
  /** Extension discovered from the current project. */
  | "project"
  /** Extension discovered from the user's extension directory. */
  | "user"
  /** Extension contributed by an installed plugin. */
  | "plugin"
  /** Extension discovered from the current session's state directory. */
  | "session";
/**
 * Current status: running, disabled, failed, or starting
 */
export type ExtensionsLoadedExtensionStatus =
  /** The extension process is running. */
  | "running"
  /** The extension is installed but disabled. */
  | "disabled"
  /** The extension failed to start or crashed. */
  | "failed"
  /** The extension process is starting. */
  | "starting";

/**
 * Session event "session.start". Session initialization metadata including context and configuration
 */
export interface StartEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: StartData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.start".
   */
  type: "session.start";
}
/**
 * Session initialization metadata including context and configuration
 */
export interface StartData {
  /**
   * Whether the session was already in use by another client at start time
   */
  alreadyInUse?: boolean;
  context?: WorkingDirectoryContext;
  /**
   * Context tier selected at session creation time for models with tiered context pricing; null when no tier is selected (e.g., non-tiered model)
   */
  contextTier?: ContextTier | null;
  /**
   * Version string of the Copilot application
   */
  copilotVersion: string;
  /**
   * When set, identifies a parent session whose context this session continues — e.g., a detached headless rem-agent run launched on the parent's interactive shutdown. Telemetry from this session is reported under the parent's session_id.
   */
  detachedFromSpawningParentSessionId?: string;
  /**
   * Identifier of the software producing the events (e.g., "copilot-agent")
   */
  producer: string;
  /**
   * Reasoning effort level used for model calls, if applicable (e.g. "none", "low", "medium", "high", "xhigh", "max")
   */
  reasoningEffort?: string;
  reasoningSummary?: ReasoningSummary;
  /**
   * Whether this session supports remote steering via GitHub
   */
  remoteSteerable?: boolean;
  /**
   * Model selected at session creation time, if any
   */
  selectedModel?: string;
  /**
   * Unique identifier for the session
   */
  sessionId: string;
  sessionLimits?: SessionLimitsConfig;
  /**
   * ISO 8601 timestamp when the session was created
   */
  startTime: string;
  verbosity?: Verbosity;
  /**
   * Schema version number for the session event format
   */
  version: number;
}
/**
 * Working directory and git context at session start
 */
export interface WorkingDirectoryContext {
  /**
   * Base commit of current git branch at session start time
   */
  baseCommit?: string;
  /**
   * Current git branch name
   */
  branch?: string;
  /**
   * Current working directory path
   */
  cwd: string;
  /**
   * Root directory of the git repository, resolved via git rev-parse
   */
  gitRoot?: string;
  /**
   * Head commit of current git branch at session start time
   */
  headCommit?: string;
  hostType?: WorkingDirectoryContextHostType;
  /**
   * Repository identifier derived from the git remote URL ("owner/name" for GitHub, "org/project/repo" for Azure DevOps)
   */
  repository?: string;
  /**
   * Raw host string from the git remote URL (e.g. "github.com", "mycompany.ghe.com", "dev.azure.com")
   */
  repositoryHost?: string;
}
/**
 * Optional session limits.
 */
export interface SessionLimitsConfig {
  /**
   * Maximum AI Credits allowed across the session's current accounting window.
   */
  maxAiCredits?: number;
}
/**
 * Session event "session.resume". Session resume metadata including current context and event count
 */
export interface ResumeEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ResumeData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.resume".
   */
  type: "session.resume";
}
/**
 * Session resume metadata including current context and event count
 */
export interface ResumeData {
  /**
   * Whether the session was already in use by another client at resume time
   */
  alreadyInUse?: boolean;
  context?: WorkingDirectoryContext;
  /**
   * Context tier currently selected at resume time; null when no tier is active
   */
  contextTier?: ContextTier | null;
  /**
   * When true, tool calls and permission requests left in flight by the previous session lifetime remain pending after resume and the agentic loop awaits their results. User sends are queued behind the pending work until all such requests reach a terminal state. When false (the default), any such tool calls and permission requests are immediately marked as interrupted on resume.
   */
  continuePendingWork?: boolean;
  /**
   * Total number of persisted events in the session at the time of resume
   */
  eventCount: number;
  /**
   * On-disk byte size of the session's persisted events.jsonl file at resume time; omitted when the file does not exist or cannot be stat'd
   */
  eventsFileSizeBytes?: number;
  /**
   * Reasoning effort level used for model calls, if applicable (e.g. "none", "low", "medium", "high", "xhigh", "max")
   */
  reasoningEffort?: string;
  reasoningSummary?: ReasoningSummary;
  /**
   * Whether this session supports remote steering via GitHub
   */
  remoteSteerable?: boolean;
  /**
   * ISO 8601 timestamp when the session was resumed
   */
  resumeTime: string;
  /**
   * Model currently selected at resume time
   */
  selectedModel?: string;
  /**
   * Session limits currently configured at resume time; null when no limits are active
   */
  sessionLimits?: SessionLimitsConfig | null;
  /**
   * True when this resume attached to a session that the runtime already had running in-memory (for example, an extension joining a session another client was actively driving). False (or omitted) for cold resumes — the runtime had to reconstitute the session from its persisted event log.
   */
  sessionWasActive?: boolean;
  verbosity?: Verbosity;
}
/**
 * Session event "session.remote_steerable_changed". Notifies that the session's remote steering capability has changed
 */
export interface RemoteSteerableChangedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: RemoteSteerableChangedData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.remote_steerable_changed".
   */
  type: "session.remote_steerable_changed";
}
/**
 * Notifies that the session's remote steering capability has changed
 */
export interface RemoteSteerableChangedData {
  /**
   * Whether this session now supports remote steering via GitHub
   */
  remoteSteerable: boolean;
}
/**
 * Session event "session.error". Error details for timeline display including message and optional diagnostic information
 */
export interface ErrorEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ErrorData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.error".
   */
  type: "session.error";
}
/**
 * Error details for timeline display including message and optional diagnostic information
 */
export interface ErrorData {
  /**
   * Only set on `errorType: "rate_limit"`. When `true`, the runtime will follow this error with an `auto_mode_switch.requested` event (or silently switch if `continueOnAutoMode` is enabled). UI clients can use this flag to suppress duplicate rendering of the rate-limit error when they show their own auto-mode-switch prompt.
   */
  eligibleForAutoSwitch?: boolean;
  /**
   * Fine-grained error code from the upstream provider, when available. For `errorType: "rate_limit"`, this is one of the `RateLimitErrorCode` values (e.g., `"user_weekly_rate_limited"`, `"user_global_rate_limited"`, `"rate_limited"`, `"user_model_rate_limited"`, `"integration_rate_limited"`). For `errorType: "quota"`, this is the CAPI quota error code (e.g., `"quota_exceeded"`, `"session_quota_exceeded"`, `"billing_not_configured"`).
   */
  errorCode?: string;
  /**
   * Category of error (e.g., "authentication", "authorization", "quota", "rate_limit", "context_limit", "query")
   */
  errorType: string;
  /**
   * Human-readable error message
   */
  message: string;
  /**
   * GitHub request tracing ID (x-github-request-id header) for correlating with server-side logs
   */
  providerCallId?: string;
  /**
   * Copilot service request ID (x-copilot-service-request-id header) for CAPI log correlation
   */
  serviceRequestId?: string;
  /**
   * Error stack trace, when available
   */
  stack?: string;
  /**
   * HTTP status code from the upstream request, if applicable
   */
  statusCode?: number;
  /**
   * Optional URL associated with this error that the user can open in a browser
   */
  url?: string;
}
/**
 * Session event "session.idle". Payload indicating the session is idle with no background agents or attached shell commands in flight
 */
export interface IdleEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: IdleData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.idle".
   */
  type: "session.idle";
}
/**
 * Payload indicating the session is idle with no background agents or attached shell commands in flight
 */
export interface IdleData {
  /**
   * True when the preceding agentic loop was cancelled via abort signal
   */
  aborted?: boolean;
}
/**
 * Session event "session.title_changed". Session title change payload containing the new display title
 */
export interface TitleChangedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: TitleChangedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.title_changed".
   */
  type: "session.title_changed";
}
/**
 * Session title change payload containing the new display title
 */
export interface TitleChangedData {
  /**
   * The new display title for the session
   */
  title: string;
}
/**
 * Session event "session.schedule_created". Scheduled prompt registered via /every or /after
 */
export interface ScheduleCreatedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ScheduleCreatedData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.schedule_created".
   */
  type: "session.schedule_created";
}
/**
 * Scheduled prompt registered via /every or /after
 */
export interface ScheduleCreatedData {
  /**
   * Absolute fire time (epoch milliseconds) for a one-shot calendar schedule
   */
  at?: number;
  /**
   * 5-field cron expression for a recurring calendar schedule, evaluated in `tz`
   */
  cron?: string;
  /**
   * Optional user-facing label shown in the timeline instead of the actual prompt (e.g. `/skill-name args` when the prompt is a skill invocation expansion)
   */
  displayPrompt?: string;
  /**
   * Sequential id assigned to the scheduled prompt within the session
   */
  id: number;
  /**
   * Interval between ticks in milliseconds (relative-interval schedules)
   */
  intervalMs?: number;
  /**
   * Prompt text that gets enqueued on every tick
   */
  prompt: string;
  /**
   * Whether the schedule re-arms after each tick (`/every`) or fires once (`/after`)
   */
  recurring?: boolean;
  /**
   * True for a self-paced (`dynamic`) schedule: no fixed cadence; the model arms each next run via the `manage_schedule` `wakeup` action. `nextRunAt` is model-controlled rather than auto-computed.
   */
  selfPaced?: boolean;
  /**
   * IANA timezone the `cron` expression is evaluated in
   */
  tz?: string;
}
/**
 * Session event "session.schedule_cancelled". Scheduled prompt cancelled from the schedule manager dialog
 */
export interface ScheduleCancelledEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ScheduleCancelledData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.schedule_cancelled".
   */
  type: "session.schedule_cancelled";
}
/**
 * Scheduled prompt cancelled from the schedule manager dialog
 */
export interface ScheduleCancelledData {
  /**
   * Id of the scheduled prompt that was cancelled
   */
  id: number;
}
/**
 * Session event "session.schedule_rearmed". Self-paced schedule re-armed for its next run
 */
export interface ScheduleRearmedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ScheduleRearmedData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.schedule_rearmed".
   */
  type: "session.schedule_rearmed";
}
/**
 * Self-paced schedule re-armed for its next run
 */
export interface ScheduleRearmedData {
  /**
   * Id of the self-paced schedule that was re-armed
   */
  id: number;
  /**
   * Absolute time (epoch milliseconds) the model armed the next run to fire
   */
  nextRunAt: number;
}
/**
 * Session event "session.autopilot_objective_changed". Autopilot objective state file operation details indicating what changed
 */
export interface AutopilotObjectiveChangedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: AutopilotObjectiveChangedData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.autopilot_objective_changed".
   */
  type: "session.autopilot_objective_changed";
}
/**
 * Autopilot objective state file operation details indicating what changed
 */
export interface AutopilotObjectiveChangedData {
  /**
   * Current autopilot objective id, if one exists
   */
  id?: number;
  operation: AutopilotObjectiveChangedOperation;
  status?: AutopilotObjectiveChangedStatus;
}
/**
 * Session event "session.info". Informational message for timeline display with categorization
 */
export interface InfoEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: InfoData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.info".
   */
  type: "session.info";
}
/**
 * Informational message for timeline display with categorization
 */
export interface InfoData {
  /**
   * Category of informational message (e.g., "notification", "timing", "context_window", "mcp", "snapshot", "configuration", "authentication", "model")
   */
  infoType: string;
  /**
   * Human-readable informational message for display in the timeline
   */
  message: string;
  /**
   * Optional actionable tip displayed with this message
   */
  tip?: string;
  /**
   * Optional URL associated with this message that the user can open in a browser
   */
  url?: string;
}
/**
 * Session event "session.warning". Warning message for timeline display with categorization
 */
export interface WarningEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: WarningData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.warning".
   */
  type: "session.warning";
}
/**
 * Warning message for timeline display with categorization
 */
export interface WarningData {
  /**
   * Human-readable warning message for display in the timeline
   */
  message: string;
  /**
   * Optional URL associated with this warning that the user can open in a browser
   */
  url?: string;
  /**
   * Category of warning (e.g., "subscription", "policy", "mcp")
   */
  warningType: string;
}
/**
 * Session event "session.model_change". Model change details including previous and new model identifiers
 */
export interface ModelChangeEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ModelChangeData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.model_change".
   */
  type: "session.model_change";
}
/**
 * Model change details including previous and new model identifiers
 */
export interface ModelChangeData {
  /**
   * Reason the change happened, when not user-initiated. Currently `"rate_limit_auto_switch"` for changes triggered by the auto-mode-switch rate-limit recovery path. UI clients can use this to render contextual copy.
   */
  cause?: string;
  /**
   * Context tier after the model change; null explicitly clears a previously selected tier
   */
  contextTier?: ContextTier | null;
  /**
   * Newly selected model identifier
   */
  newModel: string;
  /**
   * Model that was previously selected, if any
   */
  previousModel?: string;
  /**
   * Reasoning effort level before the model change, if applicable
   */
  previousReasoningEffort?: string;
  previousReasoningSummary?: ReasoningSummary;
  previousVerbosity?: Verbosity;
  /**
   * Reasoning effort level after the model change, if applicable
   */
  reasoningEffort?: string | null;
  reasoningSummary?: ReasoningSummary;
  verbosity?: Verbosity;
}
/**
 * Session event "session.mode_changed". Agent mode change details including previous and new modes
 */
export interface ModeChangedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ModeChangedData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.mode_changed".
   */
  type: "session.mode_changed";
}
/**
 * Agent mode change details including previous and new modes
 */
export interface ModeChangedData {
  newMode: SessionMode;
  previousMode: SessionMode;
}
/**
 * Session event "session.session_limits_changed". Session limits update details. Null clears the limits.
 */
export interface SessionLimitsChangedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: SessionLimitsChangedData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.session_limits_changed".
   */
  type: "session.session_limits_changed";
}
/**
 * Session limits update details. Null clears the limits.
 */
export interface SessionLimitsChangedData {
  /**
   * Current session limits, or null when no limits are active
   */
  sessionLimits: SessionLimitsConfig | null;
}
/**
 * Session event "session.permissions_changed". Permissions change details carrying the aggregate allow-all transition.
 */
export interface PermissionsChangedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: PermissionsChangedData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.permissions_changed".
   */
  type: "session.permissions_changed";
}
/**
 * Permissions change details carrying the aggregate allow-all transition.
 */
export interface PermissionsChangedData {
  /**
   * Allow-all mode after the change
   *
   * @experimental
   */
  allowAllPermissionMode?: PermissionAllowAllMode;
  /**
   * Aggregate allow-all flag after the change
   */
  allowAllPermissions: boolean;
  /**
   * Allow-all mode before the change
   *
   * @experimental
   */
  previousAllowAllPermissionMode?: PermissionAllowAllMode;
  /**
   * Aggregate allow-all flag before the change
   */
  previousAllowAllPermissions: boolean;
}
/**
 * Session event "session.plan_changed". Plan file operation details indicating what changed
 */
export interface PlanChangedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: PlanChangedData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.plan_changed".
   */
  type: "session.plan_changed";
}
/**
 * Plan file operation details indicating what changed
 */
export interface PlanChangedData {
  operation: PlanChangedOperation;
}
/**
 * Session event "session.todos_changed". Signal-only event: the agent's todos or todo_deps table was written to. No payload — clients should call session.plan.readSqlTodosWithDependencies() to fetch the current state. Events arrive in order; clients can debounce on arrival if needed.
 */
export interface TodosChangedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: TodosChangedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.todos_changed".
   */
  type: "session.todos_changed";
}
/**
 * Signal-only event: the agent's todos or todo_deps table was written to. No payload — clients should call session.plan.readSqlTodosWithDependencies() to fetch the current state. Events arrive in order; clients can debounce on arrival if needed.
 */
export interface TodosChangedData {}
/**
 * Session event "session.workspace_file_changed". Workspace file change details including path and operation type
 */
export interface WorkspaceFileChangedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: WorkspaceFileChangedData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.workspace_file_changed".
   */
  type: "session.workspace_file_changed";
}
/**
 * Workspace file change details including path and operation type
 */
export interface WorkspaceFileChangedData {
  operation: WorkspaceFileChangedOperation;
  /**
   * Relative path within the session workspace files directory
   */
  path: string;
}
/**
 * Session event "session.handoff". Session handoff metadata including source, context, and repository information
 */
export interface HandoffEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: HandoffData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.handoff".
   */
  type: "session.handoff";
}
/**
 * Session handoff metadata including source, context, and repository information
 */
export interface HandoffData {
  /**
   * Additional context information for the handoff
   */
  context?: string;
  /**
   * ISO 8601 timestamp when the handoff occurred
   */
  handoffTime: string;
  /**
   * GitHub host URL for the source session (e.g., https://github.com or https://tenant.ghe.com)
   */
  host?: string;
  /**
   * Session ID of the remote session being handed off
   */
  remoteSessionId?: string;
  repository?: HandoffRepository;
  sourceType: HandoffSourceType;
  /**
   * Summary of the work done in the source session
   */
  summary?: string;
}
/**
 * Repository context for the handed-off session
 */
export interface HandoffRepository {
  /**
   * Git branch name, if applicable
   */
  branch?: string;
  /**
   * Repository name
   */
  name: string;
  /**
   * Repository owner (user or organization)
   */
  owner: string;
}
/**
 * Session event "session.truncation". Conversation truncation statistics including token counts and removed content metrics
 */
export interface TruncationEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: TruncationData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.truncation".
   */
  type: "session.truncation";
}
/**
 * Conversation truncation statistics including token counts and removed content metrics
 */
export interface TruncationData {
  /**
   * Number of messages removed by truncation
   */
  messagesRemovedDuringTruncation: number;
  /**
   * Identifier of the component that performed truncation (e.g., "BasicTruncator")
   */
  performedBy: string;
  /**
   * Number of conversation messages after truncation
   */
  postTruncationMessagesLength: number;
  /**
   * Total tokens in conversation messages after truncation
   */
  postTruncationTokensInMessages: number;
  /**
   * Number of conversation messages before truncation
   */
  preTruncationMessagesLength: number;
  /**
   * Total tokens in conversation messages before truncation
   */
  preTruncationTokensInMessages: number;
  /**
   * Maximum token count for the model's context window
   */
  tokenLimit: number;
  /**
   * Number of tokens removed by truncation
   */
  tokensRemovedDuringTruncation: number;
}
/**
 * Session event "session.snapshot_rewind". Session rewind details including target event and count of removed events
 */
export interface SnapshotRewindEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: SnapshotRewindData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.snapshot_rewind".
   */
  type: "session.snapshot_rewind";
}
/**
 * Session rewind details including target event and count of removed events
 */
export interface SnapshotRewindData {
  /**
   * Number of events that were removed by the rewind
   */
  eventsRemoved: number;
  /**
   * Event ID that was rewound to; this event and all after it were removed
   */
  upToEventId: string;
}
/**
 * Session event "session.shutdown". Session termination metrics including usage statistics, code changes, and shutdown reason
 */
export interface ShutdownEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ShutdownData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.shutdown".
   */
  type: "session.shutdown";
}
/**
 * Session termination metrics including usage statistics, code changes, and shutdown reason
 */
export interface ShutdownData {
  codeChanges: ShutdownCodeChanges;
  /**
   * Non-system message token count at shutdown
   */
  conversationTokens?: number;
  /**
   * Model that was selected at the time of shutdown
   */
  currentModel?: string;
  /**
   * Total tokens in context window at shutdown
   */
  currentTokens?: number;
  /**
   * Error description when shutdownType is "error"
   */
  errorReason?: string;
  /**
   * On-disk byte size of the session's persisted events.jsonl file at shutdown time; omitted when the file does not exist or cannot be stat'd
   */
  eventsFileSizeBytes?: number;
  /**
   * Per-model usage breakdown, keyed by model identifier
   */
  modelMetrics: {
    [k: string]: ShutdownModelMetric | undefined;
  };
  /**
   * Unix timestamp (milliseconds) when the session started
   */
  sessionStartTime: number;
  shutdownType: ShutdownType;
  /**
   * System message token count at shutdown
   */
  systemTokens?: number;
  /**
   * Session-wide per-token-type accumulated token counts
   */
  tokenDetails?: {
    [k: string]: ShutdownTokenDetail | undefined;
  };
  /**
   * Tool definitions token count at shutdown
   */
  toolDefinitionsTokens?: number;
  /**
   * Cumulative time spent in API calls during the session, in milliseconds
   */
  totalApiDurationMs: number;
  /**
   * Session-wide accumulated nano-AI units cost
   *
   * @experimental
   */
  totalNanoAiu?: number;
  /**
   * Total number of premium API requests used during the session
   *
   * @internal
   */
  totalPremiumRequests?: number;
}
/**
 * Aggregate code change metrics for the session
 */
export interface ShutdownCodeChanges {
  /**
   * List of file paths that were modified during the session
   */
  filesModified: string[];
  /**
   * Total number of lines added during the session
   */
  linesAdded: number;
  /**
   * Total number of lines removed during the session
   */
  linesRemoved: number;
}
/**
 * Per-model shutdown metrics with request counts, token usage, nano-AI units, and token details.
 */
export interface ShutdownModelMetric {
  requests: ShutdownModelMetricRequests;
  /**
   * Token count details per type
   */
  tokenDetails?: {
    [k: string]: ShutdownModelMetricTokenDetail | undefined;
  };
  /**
   * Accumulated nano-AI units cost for this model
   *
   * @experimental
   */
  totalNanoAiu?: number;
  usage: ShutdownModelMetricUsage;
}
/**
 * Request count and cost metrics
 */
export interface ShutdownModelMetricRequests {
  /**
   * Cumulative cost multiplier for requests to this model
   *
   * @experimental
   */
  cost?: number;
  /**
   * Total number of API requests made to this model
   *
   * @experimental
   */
  count?: number;
}
/**
 * A token-type entry in a shutdown model metric, storing the accumulated token count.
 */
export interface ShutdownModelMetricTokenDetail {
  /**
   * Accumulated token count for this token type
   */
  tokenCount: number;
}
/**
 * Token usage breakdown
 */
export interface ShutdownModelMetricUsage {
  /**
   * Total tokens read from prompt cache across all requests
   */
  cacheReadTokens: number;
  /**
   * Total tokens written to prompt cache across all requests
   */
  cacheWriteTokens: number;
  /**
   * Total input tokens consumed across all requests to this model
   */
  inputTokens: number;
  /**
   * Total output tokens produced across all requests to this model
   */
  outputTokens: number;
  /**
   * Total reasoning tokens produced across all requests to this model
   */
  reasoningTokens?: number;
}
/**
 * A session-wide shutdown token-type entry storing the accumulated token count.
 */
export interface ShutdownTokenDetail {
  /**
   * Accumulated token count for this token type
   */
  tokenCount: number;
}
/**
 * Session event "session.usage_checkpoint". Durable session usage checkpoint for reconstructing aggregate accounting on resume
 */
export interface UsageCheckpointEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: UsageCheckpointData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.usage_checkpoint".
   */
  type: "session.usage_checkpoint";
}
/**
 * Durable session usage checkpoint for reconstructing aggregate accounting on resume
 */
export interface UsageCheckpointData {
  /**
   * Session-wide accumulated nano-AI units cost at checkpoint time
   */
  totalNanoAiu: number;
  /**
   * Total number of premium API requests used at checkpoint time
   *
   * @internal
   */
  totalPremiumRequests?: number;
}
/**
 * Session event "session.context_changed". Updated working directory and git context after the change
 */
export interface ContextChangedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: WorkingDirectoryContext;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.context_changed".
   */
  type: "session.context_changed";
}
/**
 * Session event "session.usage_info". Current context window usage statistics including token and message counts
 */
export interface UsageInfoEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: UsageInfoData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.usage_info".
   */
  type: "session.usage_info";
}
/**
 * Current context window usage statistics including token and message counts
 */
export interface UsageInfoData {
  /**
   * Token count from non-system messages (user, assistant, tool)
   */
  conversationTokens?: number;
  /**
   * Current number of tokens in the context window
   */
  currentTokens: number;
  /**
   * Whether this is the first usage_info event emitted in this session
   */
  isInitial?: boolean;
  /**
   * Current number of messages in the conversation
   */
  messagesLength: number;
  /**
   * Token count from system message(s)
   */
  systemTokens?: number;
  /**
   * Maximum token count for the model's context window
   */
  tokenLimit: number;
  /**
   * Token count from tool definitions
   */
  toolDefinitionsTokens?: number;
}
/**
 * Session event "session.compaction_start". Context window breakdown at the start of LLM-powered conversation compaction
 */
export interface CompactionStartEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: CompactionStartData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.compaction_start".
   */
  type: "session.compaction_start";
}
/**
 * Context window breakdown at the start of LLM-powered conversation compaction
 */
export interface CompactionStartData {
  /**
   * Token count from non-system messages (user, assistant, tool) at compaction start
   */
  conversationTokens?: number;
  /**
   * Model identifier used for compaction, when known
   */
  model?: string;
  /**
   * Token count from system message(s) at compaction start
   */
  systemTokens?: number;
  /**
   * Token count from tool definitions at compaction start
   */
  toolDefinitionsTokens?: number;
}
/**
 * Session event "session.compaction_complete". Conversation compaction results including success status, metrics, and optional error details
 */
export interface CompactionCompleteEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: CompactionCompleteData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.compaction_complete".
   */
  type: "session.compaction_complete";
}
/**
 * Conversation compaction results including success status, metrics, and optional error details
 */
export interface CompactionCompleteData {
  /**
   * Checkpoint snapshot number created for recovery
   */
  checkpointNumber?: number;
  /**
   * File path where the checkpoint was stored
   */
  checkpointPath?: string;
  compactionTokensUsed?: CompactionCompleteCompactionTokensUsed;
  /**
   * Token count from non-system messages (user, assistant, tool) after compaction
   */
  conversationTokens?: number;
  /**
   * User-supplied focus instructions provided to a manual `/compact` invocation. Omitted for automatic compaction and for manual compaction with no focus text.
   */
  customInstructions?: string;
  /**
   * Error message if compaction failed
   */
  error?: string;
  /**
   * Number of messages removed during compaction
   */
  messagesRemoved?: number;
  /**
   * Total tokens in conversation after compaction
   */
  postCompactionTokens?: number;
  /**
   * Number of messages before compaction
   */
  preCompactionMessagesLength?: number;
  /**
   * Total tokens in conversation before compaction
   */
  preCompactionTokens?: number;
  /**
   * GitHub request tracing ID (x-github-request-id header) for the compaction LLM call
   */
  requestId?: string;
  /**
   * Copilot service request ID (x-copilot-service-request-id header) for the compaction LLM call
   */
  serviceRequestId?: string;
  /**
   * For failed compaction only: the HTTP status code of the compaction LLM call failure, when it carried one. Absent for successful compaction and for failures without an HTTP status (e.g. an empty model response or a transport error).
   */
  statusCode?: number;
  /**
   * Whether compaction completed successfully
   */
  success: boolean;
  /**
   * LLM-generated summary of the compacted conversation history
   */
  summaryContent?: string;
  /**
   * Token count from system message(s) after compaction
   */
  systemTokens?: number;
  /**
   * Number of tokens removed during compaction
   */
  tokensRemoved?: number;
  /**
   * Token count from tool definitions after compaction
   */
  toolDefinitionsTokens?: number;
}
/**
 * Token usage breakdown for the compaction LLM call (aligned with assistant.usage format)
 */
export interface CompactionCompleteCompactionTokensUsed {
  /**
   * Cached input tokens reused in the compaction LLM call
   */
  cacheReadTokens?: number;
  /**
   * Tokens written to prompt cache in the compaction LLM call
   */
  cacheWriteTokens?: number;
  /**
   * Per-request cost and usage data from the CAPI copilot_usage response field
   *
   * @internal
   */
  copilotUsage?: CompactionCompleteCompactionTokensUsedCopilotUsage;
  /**
   * Duration of the compaction LLM call in milliseconds
   */
  duration?: number;
  /**
   * Input tokens consumed by the compaction LLM call
   */
  inputTokens?: number;
  /**
   * Model identifier used for the compaction LLM call
   */
  model?: string;
  /**
   * Output tokens produced by the compaction LLM call
   */
  outputTokens?: number;
}
/**
 * Per-request cost and usage data from the CAPI copilot_usage response field
 */
/** @internal */
export interface CompactionCompleteCompactionTokensUsedCopilotUsage {
  /**
   * Itemized token usage breakdown
   *
   * @internal
   */
  tokenDetails?: CompactionCompleteCompactionTokensUsedCopilotUsageTokenDetail[];
  /**
   * Total cost in nano-AI units for this request
   */
  totalNanoAiu: number;
}
/**
 * Token usage detail for a single billing category
 */
export interface CompactionCompleteCompactionTokensUsedCopilotUsageTokenDetail {
  /**
   * Number of tokens in this billing batch
   */
  batchSize: number;
  /**
   * Cost per batch of tokens
   */
  costPerBatch: number;
  /**
   * Total token count for this entry
   */
  tokenCount: number;
  /**
   * Token category (e.g., "input", "output")
   */
  tokenType: string;
}
/**
 * Session event "session.task_complete". Task completion notification with summary from the agent
 */
export interface TaskCompleteEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: TaskCompleteData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.task_complete".
   */
  type: "session.task_complete";
}
/**
 * Task completion notification with summary from the agent
 */
export interface TaskCompleteData {
  /**
   * Whether the tool call succeeded. False when validation failed (e.g., invalid arguments)
   */
  success?: boolean;
  /**
   * Summary of the completed task, provided by the agent
   */
  summary?: string;
}
/**
 * Session event "user.message". Payload of `user.message` with displayed and model-transformed content, attachments, source/delivery metadata, mode, and telemetry IDs.
 */
export interface UserMessageEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: UserMessageData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "user.message".
   */
  type: "user.message";
}
/**
 * Payload of `user.message` with displayed and model-transformed content, attachments, source/delivery metadata, mode, and telemetry IDs.
 */
export interface UserMessageData {
  agentMode?: UserMessageAgentMode;
  /**
   * Files, selections, or GitHub references attached to the message
   */
  attachments?: Attachment[];
  /**
   * The user's message text as displayed in the timeline
   */
  content: string;
  delivery?: UserMessageDelivery;
  /**
   * CAPI interaction ID for correlating this user message with its turn
   */
  interactionId?: string;
  /**
   * True when this user message was auto-injected by autopilot's continuation loop rather than typed by the user; used to distinguish autopilot-driven turns in telemetry.
   */
  isAutopilotContinuation?: boolean;
  /**
   * Path-backed native document attachments that stayed on the tagged_files path flow because native upload could not read them or would exceed the request size limit
   */
  nativeDocumentPathFallbackPaths?: string[];
  /**
   * Parent agent task ID for background telemetry correlated to this user turn
   */
  parentAgentTaskId?: string;
  /**
   * Origin of this message, used for timeline filtering (e.g., "skill-pdf" for skill-injected messages that should be hidden from the user)
   */
  source?: string;
  /**
   * Normalized document MIME types that were sent natively instead of through tagged_files XML
   */
  supportedNativeDocumentMimeTypes?: string[];
  /**
   * Transformed version of the message sent to the model, with XML wrapping, timestamps, and other augmentations for prompt caching
   */
  transformedContent?: string;
}
/**
 * File attachment
 */
export interface AttachmentFile {
  /**
   * Internal: content-addressed id of the session.binary_asset event holding this attachment's model-facing bytes (e.g. "sha256:..."). Absent externally.
   */
  assetId?: string;
  /**
   * Internal: decoded byte length of the attachment's model-facing bytes. Absent externally.
   */
  byteLength?: number;
  /**
   * User-facing display name for the attachment
   */
  displayName: string;
  lineRange?: AttachmentFileLineRange;
  /**
   * Internal: MIME type of the file's model-facing bytes (post-resize for images). Set when the file's bytes are interned to an asset. Absent externally.
   */
  mimeType?: string;
  omittedReason?: OmittedBinaryOmittedReason;
  /**
   * Absolute file path
   */
  path: string;
  /**
   * Frozen rendered line this attachment contributed to the <tagged_files> prompt block (e.g. "* /path (123 lines)"). Captured at send time so resumed history reproduces the exact text the model saw, independent of later filesystem changes. Present only for attachments routed to <tagged_files> (mutually exclusive with assetId, which marks bytes sent natively).
   */
  taggedFilesEntry?: string;
  /**
   * Attachment type discriminator
   */
  type: "file";
}
/**
 * Optional line range to scope the attachment to a specific section of the file
 */
export interface AttachmentFileLineRange {
  /**
   * End line number (1-based, inclusive)
   */
  end: number;
  /**
   * Start line number (1-based)
   */
  start: number;
}
/**
 * Directory attachment
 */
export interface AttachmentDirectory {
  /**
   * User-facing display name for the attachment
   */
  displayName: string;
  /**
   * Absolute directory path
   */
  path: string;
  /**
   * Frozen rendered line this attachment contributed to the <tagged_files> prompt block (e.g. "* /path (12 items)"). Captured at send time so resumed history reproduces the exact text the model saw, independent of later filesystem changes.
   */
  taggedFilesEntry?: string;
  /**
   * Attachment type discriminator
   */
  type: "directory";
}
/**
 * Code selection attachment from an editor
 */
export interface AttachmentSelection {
  /**
   * User-facing display name for the selection
   */
  displayName: string;
  /**
   * Absolute path to the file containing the selection
   */
  filePath: string;
  selection: AttachmentSelectionDetails;
  /**
   * The selected text content
   */
  text: string;
  /**
   * Attachment type discriminator
   */
  type: "selection";
}
/**
 * Position range of the selection within the file
 */
export interface AttachmentSelectionDetails {
  end: AttachmentSelectionDetailsEnd;
  start: AttachmentSelectionDetailsStart;
}
/**
 * End position of the selection
 */
export interface AttachmentSelectionDetailsEnd {
  /**
   * End character offset within the line (0-based)
   */
  character: number;
  /**
   * End line number (0-based)
   */
  line: number;
}
/**
 * Start position of the selection
 */
export interface AttachmentSelectionDetailsStart {
  /**
   * Start character offset within the line (0-based)
   */
  character: number;
  /**
   * Start line number (0-based)
   */
  line: number;
}
/**
 * GitHub issue, pull request, or discussion reference
 */
export interface AttachmentGitHubReference {
  /**
   * Issue, pull request, or discussion number
   */
  number: number;
  referenceType: AttachmentGitHubReferenceType;
  /**
   * Current state of the referenced item (e.g., open, closed, merged)
   */
  state: string;
  /**
   * Title of the referenced item
   */
  title: string;
  /**
   * Attachment type discriminator
   */
  type: "github_reference";
  /**
   * URL to the referenced item on GitHub
   */
  url: string;
}
/**
 * Pointer to a GitHub commit.
 */
export interface AttachmentGitHubCommit {
  /**
   * First line of the commit message
   */
  message: string;
  /**
   * Full commit SHA
   */
  oid: string;
  repo: GitHubRepoRef;
  /**
   * Attachment type discriminator
   */
  type: "github_commit";
  /**
   * URL to the commit on GitHub
   */
  url: string;
}
/**
 * Pointer to a GitHub repository.
 */
export interface GitHubRepoRef {
  /**
   * Numeric GitHub repository id
   */
  id?: number;
  /**
   * Repository name (without owner)
   */
  name: string;
  /**
   * Repository owner login (user or organization)
   */
  owner: string;
}
/**
 * Pointer to a GitHub release.
 */
export interface AttachmentGitHubRelease {
  /**
   * Human-readable release name
   */
  name: string;
  repo: GitHubRepoRef;
  /**
   * Git tag the release is anchored to
   */
  tagName: string;
  /**
   * Attachment type discriminator
   */
  type: "github_release";
  /**
   * URL to the release on GitHub
   */
  url: string;
}
/**
 * Pointer to a GitHub Actions job.
 */
export interface AttachmentGitHubActionsJob {
  /**
   * Terminal conclusion of the job when finished (e.g., success, failure, cancelled). Absent for in-progress jobs.
   */
  conclusion?: string;
  /**
   * Job id within the workflow run
   */
  jobId: number;
  /**
   * Display name of the job
   */
  jobName: string;
  repo: GitHubRepoRef;
  /**
   * Attachment type discriminator
   */
  type: "github_actions_job";
  /**
   * URL to the job on GitHub
   */
  url: string;
  /**
   * Display name of the workflow the job ran in
   */
  workflowName: string;
}
/**
 * Pointer to a GitHub repository.
 */
export interface AttachmentGitHubRepository {
  /**
   * Short description of the repository
   */
  description?: string;
  /**
   * Git ref this attachment is anchored at (branch, tag, or commit). When absent the default branch is implied.
   */
  ref?: string;
  repo: GitHubRepoRef;
  /**
   * Attachment type discriminator
   */
  type: "github_repository";
  /**
   * URL to the repository on GitHub
   */
  url: string;
}
/**
 * Pointer to a single-file diff. At least one of `head` and `base` must be present.
 */
export interface AttachmentGitHubFileDiff {
  base?: AttachmentGitHubFileDiffSide;
  head?: AttachmentGitHubFileDiffSide;
  /**
   * Attachment type discriminator
   */
  type: "github_file_diff";
  /**
   * URL to the diff on GitHub (e.g., a commit, compare, or PR-file URL)
   */
  url: string;
}
/**
 * One side of a file diff (head or base)
 */
export interface AttachmentGitHubFileDiffSide {
  /**
   * Repository-relative path to the file
   */
  path: string;
  /**
   * Git ref (branch, tag, or commit SHA) the file is read at
   */
  ref: string;
  repo: GitHubRepoRef;
}
/**
 * Pointer to a comparison between two git revisions.
 */
export interface AttachmentGitHubTreeComparison {
  base: AttachmentGitHubTreeComparisonSide;
  head: AttachmentGitHubTreeComparisonSide;
  /**
   * Attachment type discriminator
   */
  type: "github_tree_comparison";
  /**
   * URL to the comparison on GitHub
   */
  url: string;
}
/**
 * One side of a tree comparison (head or base)
 */
export interface AttachmentGitHubTreeComparisonSide {
  repo: GitHubRepoRef;
  /**
   * Git revision (branch, tag, or commit SHA)
   */
  revision: string;
}
/**
 * Generic GitHub URL reference.
 */
export interface AttachmentGitHubUrl {
  /**
   * Attachment type discriminator
   */
  type: "github_url";
  /**
   * URL to the GitHub resource
   */
  url: string;
}
/**
 * Pointer to a file in a GitHub repository at a specific ref.
 */
export interface AttachmentGitHubFile {
  /**
   * Repository-relative path to the file
   */
  path: string;
  /**
   * Git ref the file is read at (branch, tag, or commit SHA)
   */
  ref: string;
  repo: GitHubRepoRef;
  /**
   * Attachment type discriminator
   */
  type: "github_file";
  /**
   * URL to the file on GitHub
   */
  url: string;
}
/**
 * Pointer to a line range inside a file in a GitHub repository.
 */
export interface AttachmentGitHubSnippet {
  lineRange: AttachmentFileLineRange;
  /**
   * Repository-relative path to the file
   */
  path: string;
  /**
   * Git ref the file is read at (branch, tag, or commit SHA)
   */
  ref: string;
  repo: GitHubRepoRef;
  /**
   * Attachment type discriminator
   */
  type: "github_snippet";
  /**
   * URL to the snippet on GitHub (with line anchor)
   */
  url: string;
}
/**
 * Blob attachment with inline base64-encoded data
 */
export interface AttachmentBlob {
  /**
   * Internal: content-addressed id of the session.binary_asset event holding this attachment's model-facing bytes (e.g. "sha256:..."). Absent externally.
   */
  assetId?: string;
  /**
   * Internal: decoded byte length of the attachment's model-facing bytes. Absent externally.
   */
  byteLength?: number;
  /**
   * Base64-encoded content. Present on input and for external consumers; replaced by an internal `assetId` reference in persisted events when interned to a content-addressed asset.
   */
  data?: string;
  /**
   * User-facing display name for the attachment
   */
  displayName?: string;
  /**
   * MIME type of the inline data
   */
  mimeType: string;
  omittedReason?: OmittedBinaryOmittedReason;
  /**
   * Attachment type discriminator
   */
  type: "blob";
}
/**
 * Structured context contributed by an extension. Composer pills displayed in the host are forwarded back through session.send.attachments, then rendered into the model prompt as an <extension_context> XML block.
 */
export interface AttachmentExtensionContext {
  /**
   * Provider-local canvas identifier when the push was bound to a canvas instance
   */
  canvasId?: string;
  /**
   * ISO 8601 timestamp captured by the runtime when the push was accepted
   */
  capturedAt: string;
  /**
   * Owning extension identifier. Runtime-derived from the caller's connection when produced via session.extensions.sendAttachmentsToMessage; preserved verbatim on subsequent transports.
   */
  extensionId: string;
  /**
   * Open canvas instance identifier when the push was bound to a canvas instance
   */
  instanceId?: string;
  /**
   * Caller-supplied JSON payload
   */
  payload?: {
    [k: string]: unknown | undefined;
  };
  /**
   * Human-readable composer pill label
   */
  title: string;
  /**
   * Attachment type discriminator
   */
  type: "extension_context";
}
/**
 * Session event "pending_messages.modified". Empty payload; the event signals that the pending message queue has changed
 */
export interface PendingMessagesModifiedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: PendingMessagesModifiedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "pending_messages.modified".
   */
  type: "pending_messages.modified";
}
/**
 * Empty payload; the event signals that the pending message queue has changed
 */
export interface PendingMessagesModifiedData {}
/**
 * Session event "assistant.turn_start". Turn initialization metadata including identifier and interaction tracking
 */
export interface AssistantTurnStartEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: AssistantTurnStartData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "assistant.turn_start".
   */
  type: "assistant.turn_start";
}
/**
 * Turn initialization metadata including identifier and interaction tracking
 */
export interface AssistantTurnStartData {
  /**
   * CAPI interaction ID for correlating this turn with upstream telemetry
   */
  interactionId?: string;
  /**
   * Model identifier used for this turn, when known
   */
  model?: string;
  /**
   * Identifier for this turn within the agentic loop, typically a stringified turn number
   */
  turnId: string;
}
/**
 * Session event "assistant.intent". Agent intent description for current activity or plan
 */
export interface AssistantIntentEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: AssistantIntentData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "assistant.intent".
   */
  type: "assistant.intent";
}
/**
 * Agent intent description for current activity or plan
 */
export interface AssistantIntentData {
  /**
   * Short description of what the agent is currently doing or planning to do
   */
  intent: string;
}
/**
 * Session event "assistant.server_tool_progress". Live progress signal for a provider-hosted server tool (e.g. hosted web search) while it runs, before the finalized serverTools envelope lands on the terminal assistant.message
 */
export interface AssistantServerToolProgressEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: AssistantServerToolProgressData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "assistant.server_tool_progress".
   */
  type: "assistant.server_tool_progress";
}
/**
 * Live progress signal for a provider-hosted server tool (e.g. hosted web search) while it runs, before the finalized serverTools envelope lands on the terminal assistant.message
 */
export interface AssistantServerToolProgressData {
  /**
   * Kind of hosted server tool that is running. Only `web_search` is emitted today.
   */
  kind: string;
  /**
   * Position of the hosted tool call in the response output. Stable across the call's lifecycle events (unlike the provider's per-event item id, which CAPI rotates), so the host keys the live in-progress row on it.
   */
  outputIndex: number;
  /**
   * Lifecycle status of the hosted call: `in_progress`, `searching`, or `completed`.
   */
  status: string;
}
/**
 * Session event "assistant.reasoning". Assistant reasoning content for timeline display with complete thinking text
 */
export interface AssistantReasoningEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: AssistantReasoningData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "assistant.reasoning".
   */
  type: "assistant.reasoning";
}
/**
 * Assistant reasoning content for timeline display with complete thinking text
 */
export interface AssistantReasoningData {
  /**
   * The complete extended thinking text from the model
   */
  content: string;
  /**
   * Unique identifier for this reasoning block
   */
  reasoningId: string;
}
/**
 * Session event "assistant.reasoning_delta". Streaming reasoning delta for incremental extended thinking updates
 */
export interface AssistantReasoningDeltaEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: AssistantReasoningDeltaData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "assistant.reasoning_delta".
   */
  type: "assistant.reasoning_delta";
}
/**
 * Streaming reasoning delta for incremental extended thinking updates
 */
export interface AssistantReasoningDeltaData {
  /**
   * Incremental text chunk to append to the reasoning content
   */
  deltaContent: string;
  /**
   * Reasoning block ID this delta belongs to, matching the corresponding assistant.reasoning event
   */
  reasoningId: string;
}
/**
 * Session event "assistant.tool_call_delta". Streaming tool-call input delta for incremental tool-call updates
 */
export interface AssistantToolCallDeltaEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: AssistantToolCallDeltaData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "assistant.tool_call_delta".
   */
  type: "assistant.tool_call_delta";
}
/**
 * Streaming tool-call input delta for incremental tool-call updates
 */
export interface AssistantToolCallDeltaData {
  /**
   * Raw provider tool input fragment to append for this tool call. Function/tool-use providers stream serialized JSON argument text (so newlines inside JSON string values may appear as escaped `\n` until the accumulated JSON is parsed); custom tool calls stream raw custom input.
   */
  inputDelta: string;
  /**
   * Tool call ID this delta belongs to, matching the corresponding assistant.message tool request
   */
  toolCallId: string;
  /**
   * Name of the tool being invoked, when known from the stream
   */
  toolName?: string;
  toolType?: AssistantMessageToolRequestType;
}
/**
 * Session event "assistant.streaming_delta". Streaming response progress with cumulative byte count
 */
export interface AssistantStreamingDeltaEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: AssistantStreamingDeltaData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "assistant.streaming_delta".
   */
  type: "assistant.streaming_delta";
}
/**
 * Streaming response progress with cumulative byte count
 */
export interface AssistantStreamingDeltaData {
  /**
   * Cumulative total bytes received from the streaming response so far
   */
  totalResponseSizeBytes: number;
}
/**
 * Session event "assistant.message". Assistant response containing text content, optional tool requests, and interaction metadata
 */
export interface AssistantMessageEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: AssistantMessageData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "assistant.message".
   */
  type: "assistant.message";
}
/**
 * Assistant response containing text content, optional tool requests, and interaction metadata
 */
export interface AssistantMessageData {
  /**
   * Provider's completion / response identifier; shared across all chunks of a single API call. Used to group multi-chunk assistant utterances.
   */
  apiCallId?: string;
  /**
   * Provider-agnostic citations linking spans of this message's content to the sources that support them. Experimental; only populated when citation emission is enabled.
   *
   * @experimental
   */
  citations?: Citations;
  /**
   * Client-minted request id (x-request-id header) echoed by the server. Distinct from requestId (x-github-request-id) and serviceRequestId (x-copilot-service-request-id).
   */
  clientRequestId?: string;
  /**
   * The assistant's text response content
   */
  content: string;
  /**
   * Encrypted reasoning content from OpenAI models. Session-bound and stripped on resume.
   */
  encryptedContent?: string;
  /**
   * CAPI interaction ID for correlating this message with upstream telemetry
   */
  interactionId?: string;
  /**
   * Unique identifier for this assistant message
   */
  messageId: string;
  /**
   * Model that produced this assistant message, if known
   */
  model?: string;
  /**
   * Actual output token count from the API response (completion_tokens), used for accurate token accounting
   */
  outputTokens?: number;
  /**
   * @deprecated
   * Tool call ID of the parent tool invocation when this event originates from a sub-agent
   */
  parentToolCallId?: string;
  /**
   * Generation phase for phased-output models (e.g., thinking vs. response phases)
   */
  phase?: string;
  /**
   * Opaque/encrypted extended thinking data from Anthropic models. Session-bound and stripped on resume.
   */
  reasoningOpaque?: string;
  /**
   * Readable reasoning text from the model's extended thinking
   */
  reasoningText?: string;
  /**
   * OpenAI-compatible wire field the provider used for reasoning (e.g. reasoning_content/reasoning). Populated only when non-canonical, so the dialect round-trips across turns.
   */
  reasoningWireField?: string;
  /**
   * GitHub request tracing ID (x-github-request-id header) for correlating with server-side logs
   */
  requestId?: string;
  serverTools?: AssistantMessageServerTools;
  /**
   * Copilot service request ID (x-copilot-service-request-id header) for CAPI log correlation
   */
  serviceRequestId?: string;
  /**
   * Tool invocations requested by the assistant in this message
   */
  toolRequests?: AssistantMessageToolRequest[];
  /**
   * Identifier for the agent loop turn that produced this message, matching the corresponding assistant.turn_start event
   */
  turnId?: string;
}
/**
 * Provider-agnostic citations linking spans of the assistant's response to their supporting sources.
 */
/** @experimental */
export interface Citations {
  /**
   * Deduplicated set of sources referenced by the citation spans.
   */
  sources: CitationSource[];
  /**
   * Spans of generated text annotated with the sources that support them.
   */
  spans: CitationSpan[];
}
/**
 * A source that backs one or more cited spans in the assistant's response.
 */
/** @experimental */
export interface CitationSource {
  /**
   * Stable, turn-scoped identifier for this source, referenced by CitationReference.sourceId.
   */
  id: string;
  /**
   * File path relative to the agent's workspace root, when the source is a file.
   */
  path?: string;
  provider: CitationProvider;
  /**
   * Human-readable title of the source.
   */
  title?: string;
  /**
   * URL of the source, when it is a web resource.
   */
  url?: string;
}
/**
 * A contiguous span of generated assistant text and the source references that support it.
 */
/** @experimental */
export interface CitationSpan {
  /**
   * End offset of the cited span within the final assistant message content (UTF-16 code units, zero-based, exclusive).
   */
  endIndex: number;
  /**
   * The sources that support this span of generated text.
   */
  references: CitationReference[];
  /**
   * Start offset of the cited span within the final assistant message content (UTF-16 code units, zero-based, inclusive).
   */
  startIndex: number;
}
/**
 * A single citation occurrence linking a span of generated text to a supporting source.
 */
/** @experimental */
export interface CitationReference {
  /**
   * The exact text from the source that supports the cited span, when provided by the model.
   */
  citedText?: string;
  location?: CitationLocation;
  /**
   * Provider-native citation correlation data (e.g. Anthropic search_result_index / document_index), passed through opaquely for debugging and forward compatibility.
   */
  providerMetadata?: {
    [k: string]: unknown | undefined;
  };
  /**
   * Identifier of the CitationSource this reference points to (CitationSource.id).
   */
  sourceId: string;
}
/**
 * A character range within the source's text content.
 */
/** @experimental */
export interface CitationLocationChar {
  /**
   * End character offset within the source text (zero-based, exclusive).
   */
  endIndex: number;
  /**
   * Start character offset within the source text (zero-based, inclusive).
   */
  startIndex: number;
  /**
   * Citation location type discriminator
   */
  type: "char";
}
/**
 * A page range within a paginated source document.
 */
/** @experimental */
export interface CitationLocationPage {
  /**
   * Last page number of the cited range (inclusive).
   */
  endPage: number;
  /**
   * First page number of the cited range.
   */
  startPage: number;
  /**
   * Citation location type discriminator
   */
  type: "page";
}
/**
 * A content-block range within a structured source document.
 */
/** @experimental */
export interface CitationLocationBlock {
  /**
   * Index of the last content block of the cited range (zero-based, exclusive).
   */
  endBlock: number;
  /**
   * Index of the first content block of the cited range (zero-based, inclusive).
   */
  startBlock: number;
  /**
   * Citation location type discriminator
   */
  type: "block";
}
/**
 * Neutral provider-tagged server-side tool-use payload (tool search, advisor) for verbatim round-tripping
 */
/** @experimental */
export interface AssistantMessageServerTools {
  advisorModel?: string;
  functionCallNamespaces?: {
    [k: string]: string | undefined;
  };
  items?: unknown[];
  provider: string;
  rawContentBlocks?: unknown[];
}
/**
 * A tool invocation request from the assistant
 */
export interface AssistantMessageToolRequest {
  /**
   * Arguments to pass to the tool, format depends on the tool
   */
  arguments?: {
    [k: string]: unknown | undefined;
  };
  /**
   * Resolved intention summary describing what this specific call does
   */
  intentionSummary?: string | null;
  /**
   * Name of the MCP server hosting this tool, when the tool is an MCP tool
   */
  mcpServerName?: string;
  /**
   * Original tool name on the MCP server, when the tool is an MCP tool
   */
  mcpToolName?: string;
  /**
   * Name of the tool being invoked
   */
  name: string;
  /**
   * Unique identifier for this tool call
   */
  toolCallId: string;
  /**
   * Human-readable display title for the tool
   */
  toolTitle?: string;
  type?: AssistantMessageToolRequestType;
}
/**
 * Session event "assistant.message_start". Streaming assistant message start metadata
 */
export interface AssistantMessageStartEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: AssistantMessageStartData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "assistant.message_start".
   */
  type: "assistant.message_start";
}
/**
 * Streaming assistant message start metadata
 */
export interface AssistantMessageStartData {
  /**
   * Message ID this start event belongs to, matching subsequent deltas and assistant.message
   */
  messageId: string;
  /**
   * Generation phase this message belongs to for phased-output models
   */
  phase?: string;
}
/**
 * Session event "assistant.message_delta". Streaming assistant message delta for incremental response updates
 */
export interface AssistantMessageDeltaEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: AssistantMessageDeltaData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "assistant.message_delta".
   */
  type: "assistant.message_delta";
}
/**
 * Streaming assistant message delta for incremental response updates
 */
export interface AssistantMessageDeltaData {
  /**
   * Incremental text chunk to append to the message content
   */
  deltaContent: string;
  /**
   * Message ID this delta belongs to, matching the corresponding assistant.message event
   */
  messageId: string;
  /**
   * @deprecated
   * Tool call ID of the parent tool invocation when this event originates from a sub-agent
   */
  parentToolCallId?: string;
}
/**
 * Session event "assistant.turn_end". Turn completion metadata including the turn identifier
 */
export interface AssistantTurnEndEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: AssistantTurnEndData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "assistant.turn_end".
   */
  type: "assistant.turn_end";
}
/**
 * Turn completion metadata including the turn identifier
 */
export interface AssistantTurnEndData {
  /**
   * Model identifier used for this turn, when known
   */
  model?: string;
  /**
   * Identifier of the turn that has ended, matching the corresponding assistant.turn_start event
   */
  turnId: string;
}
/**
 * Session event "assistant.idle". Payload emitted whenever the main agent's processing loop goes idle, including while related background work (running agents or in-flight attached shell commands) is still pending and the session-level idle event is therefore deferred
 */
export interface AssistantIdleEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: AssistantIdleData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "assistant.idle".
   */
  type: "assistant.idle";
}
/**
 * Payload emitted whenever the main agent's processing loop goes idle, including while related background work (running agents or in-flight attached shell commands) is still pending and the session-level idle event is therefore deferred
 */
export interface AssistantIdleData {
  /**
   * True when the preceding agentic loop was cancelled via abort signal
   */
  aborted?: boolean;
}
/**
 * Session event "assistant.usage". LLM API call usage metrics including tokens, costs, quotas, and billing information
 */
export interface AssistantUsageEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: AssistantUsageData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "assistant.usage".
   */
  type: "assistant.usage";
}
/**
 * LLM API call usage metrics including tokens, costs, quotas, and billing information
 */
export interface AssistantUsageData {
  /**
   * Completion ID from the model provider (e.g., chatcmpl-abc123)
   */
  apiCallId?: string;
  apiEndpoint?: AssistantUsageApiEndpoint;
  /**
   * Number of tokens read from prompt cache
   */
  cacheReadTokens?: number;
  /**
   * Number of tokens written to prompt cache
   */
  cacheWriteTokens?: number;
  /**
   * Whether the model response was blocked or truncated by content filtering (finish_reason === 'content_filter'). For Anthropic models this corresponds to a 'refusal' stop reason.
   */
  contentFilterTriggered?: boolean;
  copilotUsage?: AssistantUsageCopilotUsage;
  /**
   * Model multiplier cost for billing purposes
   *
   * @experimental
   */
  cost?: number;
  /**
   * Duration of the API call in milliseconds
   */
  duration?: number;
  /**
   * Finish reason reported by the model for this API call (e.g. "stop", "length", "tool_calls", "content_filter"). Normalized to OpenAI vocabulary; for Anthropic models a "refusal" stop reason maps to "content_filter".
   */
  finishReason?: string;
  /**
   * What initiated this API call (e.g., "sub-agent", "mcp-sampling"); absent for user-initiated calls
   */
  initiator?: string;
  /**
   * Number of input tokens consumed
   */
  inputTokens?: number;
  /**
   * Average inter-token latency in milliseconds. Only available for streaming requests
   */
  interTokenLatencyMs?: number;
  /**
   * Model identifier used for this API call
   */
  model: string;
  /**
   * Number of output tokens produced
   */
  outputTokens?: number;
  /**
   * @deprecated
   * Parent tool call ID when this usage originates from a sub-agent
   */
  parentToolCallId?: string;
  /**
   * GitHub request tracing ID (x-github-request-id header) for server-side log correlation
   */
  providerCallId?: string;
  /**
   * Per-quota resource usage snapshots, keyed by quota identifier
   *
   * @internal
   */
  quotaSnapshots?: {
    [k: string]: AssistantUsageQuotaSnapshot | undefined;
  };
  /**
   * Reasoning effort level used for model calls, if applicable (e.g. "none", "low", "medium", "high", "xhigh", "max")
   */
  reasoningEffort?: string;
  /**
   * Number of output tokens used for reasoning (e.g., chain-of-thought)
   */
  reasoningTokens?: number;
  /**
   * Copilot service request ID (x-copilot-service-request-id header) for CAPI log correlation
   */
  serviceRequestId?: string;
  /**
   * Time to first token in milliseconds. Only available for streaming requests
   */
  timeToFirstTokenMs?: number;
}
/**
 * Per-request cost and usage data from the CAPI copilot_usage response field
 */
export interface AssistantUsageCopilotUsage {
  /**
   * Itemized token usage breakdown
   *
   * @internal
   */
  tokenDetails?: AssistantUsageCopilotUsageTokenDetail[];
  /**
   * Total cost in nano-AI units for this request
   */
  totalNanoAiu: number;
}
/**
 * Token usage detail for a single billing category
 */
export interface AssistantUsageCopilotUsageTokenDetail {
  /**
   * Number of tokens in this billing batch
   */
  batchSize: number;
  /**
   * Cost per batch of tokens
   */
  costPerBatch: number;
  /**
   * Total token count for this entry
   */
  tokenCount: number;
  /**
   * Token category (e.g., "input", "output")
   */
  tokenType: string;
}
/**
 * Internal per-quota snapshot for assistant usage, including entitlement, consumed requests, overage, reset date, and remaining quota.
 */
/** @internal */
export interface AssistantUsageQuotaSnapshot {
  /**
   * Total requests allowed by the entitlement
   *
   * @internal
   */
  entitlementRequests: number;
  /**
   * Whether the user currently has quota available for use
   *
   * @internal
   */
  hasQuota?: boolean;
  /**
   * Whether the user has an unlimited usage entitlement
   *
   * @internal
   */
  isUnlimitedEntitlement: boolean;
  /**
   * Number of additional usage requests made this period
   *
   * @internal
   */
  overage: number;
  /**
   * Whether additional usage is allowed when quota is exhausted
   *
   * @internal
   */
  overageAllowedWithExhaustedQuota: boolean;
  /**
   * Pay-as-you-go additional-usage budget cap in AI credits (1 credit = $0.01); present only when CAPI emits a finite value
   *
   * @internal
   */
  overageEntitlement?: number;
  /**
   * Percentage of quota remaining (0 to 100)
   *
   * @internal
   */
  remainingPercentage: number;
  /**
   * Date when the quota resets
   *
   * @internal
   */
  resetDate?: string;
  /**
   * Whether this snapshot uses token-based billing (AI-credits allocation)
   *
   * @internal
   */
  tokenBasedBilling?: boolean;
  /**
   * Whether usage is still permitted after quota exhaustion
   *
   * @internal
   */
  usageAllowedWithExhaustedQuota: boolean;
  /**
   * Number of requests already consumed
   *
   * @internal
   */
  usedRequests: number;
}
/**
 * Session event "model.call_failure". Failed LLM API call metadata for telemetry
 */
export interface ModelCallFailureEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ModelCallFailureData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "model.call_failure".
   */
  type: "model.call_failure";
}
/**
 * Failed LLM API call metadata for telemetry
 */
export interface ModelCallFailureData {
  /**
   * Completion ID from the model provider (e.g., chatcmpl-abc123)
   */
  apiCallId?: string;
  badRequestKind?: ModelCallFailureBadRequestKind;
  /**
   * Duration of the failed API call in milliseconds
   */
  durationMs?: number;
  /**
   * For HTTP 400 failures only: the `code` from the CAPI error envelope (e.g. 'model_max_prompt_tokens_exceeded') identifying which deterministic validation failure occurred. Raw server-controlled string, emitted only through restricted telemetry. Absent for bodyless or non-400 failures.
   */
  errorCode?: string;
  /**
   * Raw provider/runtime error message for restricted telemetry
   */
  errorMessage?: string;
  /**
   * For HTTP 400 failures only: the `type` from the CAPI error envelope (e.g. 'websocket_error'), a coarser companion to errorCode for envelopes that carry no code. Raw server-controlled string, emitted only through restricted telemetry. Absent for bodyless or non-400 failures.
   */
  errorType?: string;
  /**
   * What initiated this API call (e.g., "sub-agent", "mcp-sampling"); absent for user-initiated calls
   */
  initiator?: string;
  /**
   * Model identifier used for the failed API call
   */
  model?: string;
  /**
   * GitHub request tracing ID (x-github-request-id header) for server-side log correlation
   */
  providerCallId?: string;
  /**
   * Per-quota usage snapshots parsed from the failed response's quota headers, keyed by quota identifier. Present when the error response carried quota headers (e.g. a 402 once the additional spend limit is reached) so the UI can refresh the quota display on failure.
   *
   * @internal
   */
  quotaSnapshots?: {
    [k: string]: AssistantUsageQuotaSnapshot | undefined;
  };
  requestFingerprint?: ModelCallFailureRequestFingerprint;
  /**
   * Copilot service request ID (x-copilot-service-request-id header) for CAPI log correlation
   */
  serviceRequestId?: string;
  source: ModelCallFailureSource;
  /**
   * HTTP status code from the failed request
   */
  statusCode?: number;
}
/**
 * Content-free structural summary of the failing request for diagnosing malformed 4xx calls
 */
export interface ModelCallFailureRequestFingerprint {
  /**
   * Total number of image content parts
   */
  imagePartCount: number;
  /**
   * Image parts whose media type cannot be determined (rejected by strict providers)
   */
  imagePartsMissingMediaType: number;
  /**
   * Role of the final message in the request
   */
  lastMessageRole?: string;
  /**
   * Total number of messages in the request
   */
  messageCount: number;
  /**
   * Tool calls whose name is missing or empty (rejected by strict providers)
   */
  namelessToolCallCount: number;
  /**
   * Total number of tool calls across assistant messages
   */
  toolCallCount: number;
  /**
   * Number of "tool" result messages in the request
   */
  toolResultMessageCount: number;
}
/**
 * Session event "abort". Turn abort information including the reason for termination
 */
export interface AbortEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: AbortData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "abort".
   */
  type: "abort";
}
/**
 * Turn abort information including the reason for termination
 */
export interface AbortData {
  reason: AbortReason;
}
/**
 * Session event "tool.user_requested". User-initiated tool invocation request with tool name and arguments
 */
export interface ToolUserRequestedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ToolUserRequestedData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "tool.user_requested".
   */
  type: "tool.user_requested";
}
/**
 * User-initiated tool invocation request with tool name and arguments
 */
export interface ToolUserRequestedData {
  /**
   * Arguments for the tool invocation
   */
  arguments?: {
    [k: string]: unknown | undefined;
  };
  /**
   * Unique identifier for this tool call
   */
  toolCallId: string;
  /**
   * Name of the tool the user wants to invoke
   */
  toolName: string;
}
/**
 * Session event "tool.execution_start". Tool execution startup details including MCP server information when applicable
 */
export interface ToolExecutionStartEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ToolExecutionStartData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "tool.execution_start".
   */
  type: "tool.execution_start";
}
/**
 * Tool execution startup details including MCP server information when applicable
 */
export interface ToolExecutionStartData {
  /**
   * Arguments passed to the tool
   */
  arguments?: {
    [k: string]: unknown | undefined;
  };
  /**
   * When true, the tool output should be displayed expanded (verbatim) in the CLI timeline
   */
  displayVerbatim?: boolean;
  /**
   * Name of the MCP server hosting this tool, when the tool is an MCP tool
   */
  mcpServerName?: string;
  /**
   * Original tool name on the MCP server, when the tool is an MCP tool
   */
  mcpToolName?: string;
  /**
   * Model identifier that generated this tool call
   */
  model?: string;
  /**
   * @deprecated
   * Tool call ID of the parent tool invocation when this event originates from a sub-agent
   */
  parentToolCallId?: string;
  shellToolInfo?: ToolExecutionStartShellToolInfo;
  /**
   * Unique identifier for this tool call
   */
  toolCallId: string;
  toolDescription?: ToolExecutionStartToolDescription;
  /**
   * Name of the tool being executed
   */
  toolName: string;
  /**
   * Identifier for the agent loop turn this tool was invoked in, matching the corresponding assistant.turn_start event
   */
  turnId?: string;
}
/**
 * Shell-aware path hints for a shell tool's command, captured at start time so consumers can snapshot a file's pre-image before the tool runs.
 */
export interface ToolExecutionStartShellToolInfo {
  /**
   * Whether the command includes a file write redirection (e.g., > or >>).
   */
  hasWriteFileRedirection: boolean;
  /**
   * File paths the command may read or write, derived from the command at start time. Produced by the same shell-aware extractor as PermissionRequestShell.possiblePaths, so it is present even when the command is auto-approved and no permission request fires.
   */
  possiblePaths: string[];
}
/**
 * Tool definition metadata, present for MCP tools with MCP Apps support
 */
export interface ToolExecutionStartToolDescription {
  _meta?: ToolExecutionStartToolDescriptionMeta;
  /**
   * Tool description
   */
  description?: string;
  /**
   * Tool name
   */
  name: string;
}
/**
 * MCP Apps metadata for UI resource association
 */
export interface ToolExecutionStartToolDescriptionMeta {
  ui?: ToolExecutionStartToolDescriptionMetaUI;
}
/**
 * MCP Apps tool `_meta.ui` resource URI and visibility captured on `tool.execution_start`.
 */
export interface ToolExecutionStartToolDescriptionMetaUI {
  /**
   * URI of the UI resource
   */
  resourceUri?: string;
  /**
   * Who can access this tool
   */
  visibility?: ToolExecutionStartToolDescriptionMetaUIVisibility[];
}
/**
 * Session event "tool.execution_partial_result". Streaming tool execution output for incremental result display
 */
export interface ToolExecutionPartialResultEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ToolExecutionPartialData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "tool.execution_partial_result".
   */
  type: "tool.execution_partial_result";
}
/**
 * Streaming tool execution output for incremental result display
 */
export interface ToolExecutionPartialData {
  /**
   * Incremental output chunk from the running tool
   */
  partialOutput: string;
  /**
   * Tool call ID this partial result belongs to
   */
  toolCallId: string;
}
/**
 * Session event "tool.execution_progress". Tool execution progress notification with status message
 */
export interface ToolExecutionProgressEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ToolExecutionProgressData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "tool.execution_progress".
   */
  type: "tool.execution_progress";
}
/**
 * Tool execution progress notification with status message
 */
export interface ToolExecutionProgressData {
  /**
   * Human-readable progress status message (e.g., from an MCP server)
   */
  progressMessage: string;
  /**
   * Tool call ID this progress notification belongs to
   */
  toolCallId: string;
}
/**
 * Session event "tool.execution_complete". Tool execution completion results including success status, detailed output, and error information
 */
export interface ToolExecutionCompleteEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ToolExecutionCompleteData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "tool.execution_complete".
   */
  type: "tool.execution_complete";
}
/**
 * Tool execution completion results including success status, detailed output, and error information
 */
export interface ToolExecutionCompleteData {
  error?: ToolExecutionCompleteError;
  /**
   * CAPI interaction ID for correlating this tool execution with upstream telemetry
   */
  interactionId?: string;
  /**
   * Whether this tool call was explicitly requested by the user rather than the assistant
   */
  isUserRequested?: boolean;
  /**
   * FIDES IFC label projected from tool ingress metadata (MCP `CallToolResult._meta` or synthesized built-in ingress labels). Persisted as `{ ifc: ... }` so the label survives session resume, including model-visible failure results. Experimental.
   *
   * @experimental
   */
  mcpMeta?: {
    [k: string]: unknown | undefined;
  };
  /**
   * Model identifier that generated this tool call
   */
  model?: string;
  /**
   * @deprecated
   * Tool call ID of the parent tool invocation when this event originates from a sub-agent
   */
  parentToolCallId?: string;
  result?: ToolExecutionCompleteResult;
  /**
   * Whether this tool execution ran inside a sandbox container
   */
  sandboxed?: boolean;
  /**
   * Whether the tool execution completed successfully
   */
  success: boolean;
  /**
   * Unique identifier for the completed tool call
   */
  toolCallId: string;
  toolDescription?: ToolExecutionCompleteToolDescription;
  /**
   * Tool-specific telemetry data (e.g., CodeQL check counts, grep match counts)
   */
  toolTelemetry?: {
    [k: string]: unknown | undefined;
  };
  /**
   * Identifier for the agent loop turn this tool was invoked in, matching the corresponding assistant.turn_start event
   */
  turnId?: string;
}
/**
 * Error details when the tool execution failed
 */
export interface ToolExecutionCompleteError {
  /**
   * Machine-readable error code
   */
  code?: string;
  /**
   * Human-readable error message
   */
  message: string;
}
/**
 * Tool execution result on success
 */
export interface ToolExecutionCompleteResult {
  /**
   * Model-facing binary results (base64 inline or size-omitted markers) sent to the LLM for this tool call
   *
   * @experimental
   */
  binaryResultsForLlm?: PersistedBinaryResult[];
  /**
   * Provider-neutral source material this tool makes available to the model as citable content. Persisted so it survives session resume. Experimental.
   *
   * @experimental
   */
  citableSources?: CitableSource[];
  /**
   * Concise tool result text sent to the LLM for chat completion, potentially truncated for token efficiency
   */
  content: string;
  /**
   * Structured content blocks (text, images, audio, resources) returned by the tool in their native format
   */
  contents?: ToolExecutionCompleteContent[];
  /**
   * Full detailed tool result for UI/timeline display, preserving complete content such as diffs. Falls back to content when absent.
   */
  detailedContent?: string;
  /**
   * FIDES IFC label projected from tool ingress metadata (MCP `CallToolResult._meta` or synthesized built-in ingress labels) — persisted as `{ ifc: ... }` (only the `ifc` key, not the whole `_meta`). Persisted so the FIDES IFC label survives session resume: the engine rehydrates accumulated taint by replaying these on load. Populated for ingress sources when FIDES IFC is on. Experimental.
   *
   * @experimental
   */
  mcpMeta?: {
    [k: string]: unknown | undefined;
  };
  /**
   * Structured content (arbitrary JSON) returned verbatim by the MCP tool
   */
  structuredContent?: {
    [k: string]: unknown | undefined;
  };
  uiResource?: ToolExecutionCompleteUIResource;
}
/**
 * Binary result returned by a tool for the model
 */
export interface PersistedBinaryImage {
  /**
   * Base64-encoded binary data
   */
  data: string;
  /**
   * Human-readable description of the binary data
   */
  description?: string;
  /**
   * Optional metadata from the producing tool.
   */
  metadata?: {
    [k: string]: unknown | undefined;
  };
  /**
   * MIME type of the binary data
   */
  mimeType: string;
  type: PersistedBinaryImageType;
}
/**
 * A binary result whose data was omitted from persistence due to the inline size limit
 */
/** @experimental */
export interface OmittedBinaryResult {
  /**
   * Decoded byte length of the omitted binary data
   */
  byteLength: number;
  /**
   * Human-readable description of the binary data
   */
  description?: string;
  /**
   * Optional metadata from the producing tool.
   */
  metadata?: {
    [k: string]: unknown | undefined;
  };
  /**
   * MIME type of the omitted binary data
   */
  mimeType: string;
  omittedReason: OmittedBinaryOmittedReason;
  type: OmittedBinaryType;
}
/**
 * A reference to binary data persisted once on a session.binary_asset event and shared by id
 */
/** @experimental */
export interface BinaryAssetReference {
  /**
   * Content-addressed id of the session.binary_asset event that holds this binary's bytes (e.g. "sha256:...").
   */
  assetId: string;
  /**
   * Decoded byte length of the referenced binary data
   */
  byteLength: number;
  /**
   * Human-readable description of the binary data
   */
  description?: string;
  /**
   * Optional metadata from the producing tool.
   */
  metadata?: {
    [k: string]: unknown | undefined;
  };
  /**
   * MIME type of the referenced binary data
   */
  mimeType: string;
  type: BinaryAssetReferenceType;
}
/**
 * A source supplied by a tool that should be made available to the model as citable content.
 */
/** @experimental */
export interface CitableSource {
  /**
   * The source text made available to the model as citable content.
   */
  content: string;
  /**
   * Stable identifier for this source within the tool result. Used for deduplication and may be used by future provider integrations to correlate response citations back to the originating source.
   */
  id: string;
  /**
   * File path relative to the agent's workspace root, when the source is a file.
   */
  path?: string;
  /**
   * Human-readable title of the source.
   */
  title?: string;
  /**
   * URL of the source, when it is a web resource.
   */
  url?: string;
}
/**
 * Plain text content block
 */
export interface ToolExecutionCompleteContentText {
  /**
   * The text content
   */
  text: string;
  /**
   * Content block type discriminator
   */
  type: "text";
}
/**
 * @deprecated
 * Deprecated for shell command exit metadata. Use ToolExecutionCompleteContentShellExit instead.
 */
export interface ToolExecutionCompleteContentTerminal {
  /**
   * Working directory where the command was executed
   */
  cwd?: string;
  /**
   * Process exit code, if the command has completed
   */
  exitCode?: number;
  /**
   * Terminal/shell output text
   */
  text: string;
  /**
   * Content block type discriminator
   */
  type: "terminal";
}
/**
 * Shell command exit metadata with optional output preview
 */
export interface ToolExecutionCompleteContentShellExit {
  /**
   * Working directory where the shell command was executed
   */
  cwd?: string;
  /**
   * Exit code from the completed shell command
   */
  exitCode: number;
  /**
   * Output associated with this shell command, if available. May be partial, truncated, or a preview; not guaranteed to be full output.
   */
  outputPreview?: string;
  /**
   * Whether outputPreview is known to be incomplete or truncated
   */
  outputTruncated?: boolean;
  /**
   * Shell id, as assigned by Copilot runtime
   */
  shellId: string;
  /**
   * Content block type discriminator
   */
  type: "shell_exit";
}
/**
 * Image content block with base64-encoded data
 */
export interface ToolExecutionCompleteContentImage {
  /**
   * Base64-encoded image data
   */
  data: string;
  /**
   * MIME type of the image (e.g., image/png, image/jpeg)
   */
  mimeType: string;
  /**
   * Content block type discriminator
   */
  type: "image";
}
/**
 * Audio content block with base64-encoded data
 */
export interface ToolExecutionCompleteContentAudio {
  /**
   * Base64-encoded audio data
   */
  data: string;
  /**
   * MIME type of the audio (e.g., audio/wav, audio/mpeg)
   */
  mimeType: string;
  /**
   * Content block type discriminator
   */
  type: "audio";
}
/**
 * Resource link content block referencing an external resource
 */
export interface ToolExecutionCompleteContentResourceLink {
  /**
   * Human-readable description of the resource
   */
  description?: string;
  /**
   * Icons associated with this resource
   */
  icons?: ToolExecutionCompleteContentResourceLinkIcon[];
  /**
   * MIME type of the resource content
   */
  mimeType?: string;
  /**
   * Resource name identifier
   */
  name: string;
  /**
   * Size of the resource in bytes
   */
  size?: number;
  /**
   * Human-readable display title for the resource
   */
  title?: string;
  /**
   * Content block type discriminator
   */
  type: "resource_link";
  /**
   * URI identifying the resource
   */
  uri: string;
}
/**
 * Icon image for a resource
 */
export interface ToolExecutionCompleteContentResourceLinkIcon {
  /**
   * MIME type of the icon image
   */
  mimeType?: string;
  /**
   * Available icon sizes (e.g., ['16x16', '32x32'])
   */
  sizes?: string[];
  /**
   * URL or path to the icon image
   */
  src: string;
  theme?: ToolExecutionCompleteContentResourceLinkIconTheme;
}
/**
 * Embedded resource content block with inline text or binary data
 */
export interface ToolExecutionCompleteContentResource {
  resource: ToolExecutionCompleteContentResourceDetails;
  /**
   * Content block type discriminator
   */
  type: "resource";
}
/**
 * Embedded text resource contents identified by a URI, with an optional MIME type and a text payload.
 */
export interface EmbeddedTextResourceContents {
  /**
   * MIME type of the text content
   */
  mimeType?: string;
  /**
   * Text content of the resource
   */
  text: string;
  /**
   * URI identifying the resource
   */
  uri: string;
}
/**
 * Embedded binary resource contents identified by a URI, with an optional MIME type and a base64-encoded blob.
 */
export interface EmbeddedBlobResourceContents {
  /**
   * Base64-encoded binary content of the resource
   */
  blob: string;
  /**
   * MIME type of the blob content
   */
  mimeType?: string;
  /**
   * URI identifying the resource
   */
  uri: string;
}
/**
 * MCP Apps UI resource content for rendering in a sandboxed iframe
 */
export interface ToolExecutionCompleteUIResource {
  _meta?: ToolExecutionCompleteUIResourceMeta;
  /**
   * Base64-encoded HTML content
   */
  blob?: string;
  /**
   * MIME type of the content
   */
  mimeType: string;
  /**
   * HTML content as a string
   */
  text?: string;
  /**
   * The ui:// URI of the resource
   */
  uri: string;
}
/**
 * Resource-level UI metadata (CSP, permissions, visual preferences)
 */
export interface ToolExecutionCompleteUIResourceMeta {
  ui?: ToolExecutionCompleteUIResourceMetaUI;
}
/**
 * MCP Apps UI resource metadata for a completed tool result, including CSP, permissions, domain, and border preference.
 */
export interface ToolExecutionCompleteUIResourceMetaUI {
  csp?: ToolExecutionCompleteUIResourceMetaUICsp;
  domain?: string;
  permissions?: ToolExecutionCompleteUIResourceMetaUIPermissions;
  prefersBorder?: boolean;
}
/**
 * CSP domain allowlists for an MCP Apps UI resource, including connect, resource, frame, and base URI domains.
 */
export interface ToolExecutionCompleteUIResourceMetaUICsp {
  baseUriDomains?: string[];
  connectDomains?: string[];
  frameDomains?: string[];
  resourceDomains?: string[];
}
/**
 * Browser permission metadata for an MCP Apps UI resource, including camera, microphone, geolocation, and clipboard-write.
 */
export interface ToolExecutionCompleteUIResourceMetaUIPermissions {
  camera?: ToolExecutionCompleteUIResourceMetaUIPermissionsCamera;
  clipboardWrite?: ToolExecutionCompleteUIResourceMetaUIPermissionsClipboardWrite;
  geolocation?: ToolExecutionCompleteUIResourceMetaUIPermissionsGeolocation;
  microphone?: ToolExecutionCompleteUIResourceMetaUIPermissionsMicrophone;
}
/**
 * Marker object for camera permission on an MCP Apps UI resource.
 */
export interface ToolExecutionCompleteUIResourceMetaUIPermissionsCamera {}
/**
 * Marker object for clipboard-write permission on an MCP Apps UI resource.
 */
export interface ToolExecutionCompleteUIResourceMetaUIPermissionsClipboardWrite {}
/**
 * Marker object for geolocation permission on an MCP Apps UI resource.
 */
export interface ToolExecutionCompleteUIResourceMetaUIPermissionsGeolocation {}
/**
 * Marker object for microphone permission on an MCP Apps UI resource.
 */
export interface ToolExecutionCompleteUIResourceMetaUIPermissionsMicrophone {}
/**
 * Tool definition metadata, present for MCP tools with MCP Apps support
 */
export interface ToolExecutionCompleteToolDescription {
  _meta?: ToolExecutionCompleteToolDescriptionMeta;
  /**
   * Tool description
   */
  description?: string;
  /**
   * Tool name
   */
  name: string;
}
/**
 * MCP Apps metadata for UI resource association
 */
export interface ToolExecutionCompleteToolDescriptionMeta {
  ui?: ToolExecutionCompleteToolDescriptionMetaUI;
}
/**
 * MCP Apps tool `_meta.ui` resource URI and visibility captured on `tool.execution_complete`.
 */
export interface ToolExecutionCompleteToolDescriptionMetaUI {
  /**
   * URI of the UI resource
   */
  resourceUri?: string;
  /**
   * Who can access this tool
   */
  visibility?: ToolExecutionCompleteToolDescriptionMetaUIVisibility[];
}
/**
 * Session event "skill.invoked". Skill invocation details including content, allowed tools, and plugin metadata
 */
export interface SkillInvokedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: SkillInvokedData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "skill.invoked".
   */
  type: "skill.invoked";
}
/**
 * Skill invocation details including content, allowed tools, and plugin metadata
 */
export interface SkillInvokedData {
  /**
   * Tool names that should be auto-approved when this skill is active
   */
  allowedTools?: string[];
  /**
   * Full content of the skill file, injected into the conversation for the model
   */
  content: string;
  /**
   * Description of the skill from its SKILL.md frontmatter
   */
  description?: string;
  /**
   * Model identifier active when the skill was invoked, when known
   */
  model?: string;
  /**
   * Name of the invoked skill
   */
  name: string;
  /**
   * File path to the SKILL.md definition
   */
  path: string;
  /**
   * Name of the plugin this skill originated from, when applicable
   */
  pluginName?: string;
  /**
   * Version of the plugin this skill originated from, when applicable
   */
  pluginVersion?: string;
  /**
   * Source identifier for where the skill was discovered. Known values include: project (workspace skill), inherited (parent-directory skill), personal-copilot (~/.copilot/skills), personal-agents (~/.agents/skills), custom (configured directory), plugin (installed plugin), builtin (bundled runtime skill), and remote (org/enterprise skill)
   */
  source?: string;
  trigger?: SkillInvokedTrigger;
}
/**
 * Session event "subagent.started". Sub-agent startup details including parent tool call and agent information
 */
export interface SubagentStartedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: SubagentStartedData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "subagent.started".
   */
  type: "subagent.started";
}
/**
 * Sub-agent startup details including parent tool call and agent information
 */
export interface SubagentStartedData {
  /**
   * Description of what the sub-agent does
   */
  agentDescription: string;
  /**
   * Human-readable display name of the sub-agent
   */
  agentDisplayName: string;
  /**
   * Internal name of the sub-agent
   */
  agentName: string;
  /**
   * Model the sub-agent will run with, when known at start.
   */
  model?: string;
  /**
   * Tool call ID of the parent tool invocation that spawned this sub-agent
   */
  toolCallId: string;
}
/**
 * Session event "subagent.completed". Sub-agent completion details for successful execution
 */
export interface SubagentCompletedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: SubagentCompletedData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "subagent.completed".
   */
  type: "subagent.completed";
}
/**
 * Sub-agent completion details for successful execution
 */
export interface SubagentCompletedData {
  /**
   * Human-readable display name of the sub-agent
   */
  agentDisplayName: string;
  /**
   * Internal name of the sub-agent
   */
  agentName: string;
  /**
   * Wall-clock duration of the sub-agent execution in milliseconds
   */
  durationMs?: number;
  /**
   * Model used by the sub-agent
   */
  model?: string;
  /**
   * Tool call ID of the parent tool invocation that spawned this sub-agent
   */
  toolCallId: string;
  /**
   * Total tokens (input + output) consumed by the sub-agent
   */
  totalTokens?: number;
  /**
   * Total number of tool calls made by the sub-agent
   */
  totalToolCalls?: number;
}
/**
 * Session event "subagent.failed". Sub-agent failure details including error message and agent information
 */
export interface SubagentFailedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: SubagentFailedData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "subagent.failed".
   */
  type: "subagent.failed";
}
/**
 * Sub-agent failure details including error message and agent information
 */
export interface SubagentFailedData {
  /**
   * Human-readable display name of the sub-agent
   */
  agentDisplayName: string;
  /**
   * Internal name of the sub-agent
   */
  agentName: string;
  /**
   * Wall-clock duration of the sub-agent execution in milliseconds
   */
  durationMs?: number;
  /**
   * Error message describing why the sub-agent failed
   */
  error: string;
  /**
   * Model selected for the sub-agent, when known
   */
  model?: string;
  /**
   * Tool call ID of the parent tool invocation that spawned this sub-agent
   */
  toolCallId: string;
  /**
   * Total tokens (input + output) consumed before the sub-agent failed
   */
  totalTokens?: number;
  /**
   * Total number of tool calls made before the sub-agent failed
   */
  totalToolCalls?: number;
}
/**
 * Session event "subagent.selected". Custom agent selection details including name and available tools
 */
export interface SubagentSelectedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: SubagentSelectedData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "subagent.selected".
   */
  type: "subagent.selected";
}
/**
 * Custom agent selection details including name and available tools
 */
export interface SubagentSelectedData {
  /**
   * Human-readable display name of the selected custom agent
   */
  agentDisplayName: string;
  /**
   * Internal name of the selected custom agent
   */
  agentName: string;
  /**
   * List of tool names available to this agent, or null for all tools
   */
  tools: string[] | null;
}
/**
 * Session event "subagent.deselected". Empty payload; the event signals that the custom agent was deselected, returning to the default agent
 */
export interface SubagentDeselectedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: SubagentDeselectedData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "subagent.deselected".
   */
  type: "subagent.deselected";
}
/**
 * Empty payload; the event signals that the custom agent was deselected, returning to the default agent
 */
export interface SubagentDeselectedData {}
/**
 * Session event "hook.start". Hook invocation start details including type and input data
 */
export interface HookStartEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: HookStartData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "hook.start".
   */
  type: "hook.start";
}
/**
 * Hook invocation start details including type and input data
 */
export interface HookStartData {
  /**
   * Unique identifier for this hook invocation
   */
  hookInvocationId: string;
  /**
   * Type of hook being invoked (e.g., "preToolUse", "postToolUse", "sessionStart")
   */
  hookType: string;
  /**
   * Input data passed to the hook
   */
  input?: {
    [k: string]: unknown | undefined;
  };
}
/**
 * Session event "hook.end". Hook invocation completion details including output, success status, and error information
 */
export interface HookEndEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: HookEndData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "hook.end".
   */
  type: "hook.end";
}
/**
 * Hook invocation completion details including output, success status, and error information
 */
export interface HookEndData {
  error?: HookEndError;
  /**
   * Identifier matching the corresponding hook.start event
   */
  hookInvocationId: string;
  /**
   * Type of hook that was invoked (e.g., "preToolUse", "postToolUse", "sessionStart")
   */
  hookType: string;
  /**
   * Output data produced by the hook
   */
  output?: {
    [k: string]: unknown | undefined;
  };
  /**
   * Whether the hook completed successfully
   */
  success: boolean;
}
/**
 * Error details when the hook failed
 */
export interface HookEndError {
  /**
   * Human-readable error message
   */
  message: string;
  /**
   * Source label of the hook that errored (e.g. the plugin it was loaded from), when known
   */
  source?: string;
  /**
   * Error stack trace, when available
   */
  stack?: string;
}
/**
 * Session event "hook.progress". Ephemeral progress update from a running hook process
 */
export interface HookProgressEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: HookProgressData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "hook.progress".
   */
  type: "hook.progress";
}
/**
 * Ephemeral progress update from a running hook process
 */
export interface HookProgressData {
  /**
   * Human-readable progress message from the hook process
   */
  message: string;
  /**
   * When true, this status message replaces the previous temporary one instead of accumulating
   */
  temporary?: boolean;
}
/**
 * Session event "session.binary_asset". Canonical bytes for a content-addressed binary asset shared by reference across events
 */
/** @experimental */
export interface BinaryAssetEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: BinaryAssetData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.binary_asset".
   */
  type: "session.binary_asset";
}
/**
 * Canonical bytes for a content-addressed binary asset shared by reference across events
 */
export interface BinaryAssetData {
  /**
   * Content-addressed id for this binary asset (e.g. "sha256:...").
   */
  assetId: string;
  /**
   * Decoded byte length of the binary asset
   */
  byteLength: number;
  /**
   * Base64-encoded binary data
   */
  data: string;
  /**
   * Human-readable description of the binary data
   */
  description?: string;
  /**
   * Optional metadata from the producing tool.
   */
  metadata?: {
    [k: string]: unknown | undefined;
  };
  /**
   * MIME type of the binary asset
   */
  mimeType: string;
  type: BinaryAssetType;
}
/**
 * Session event "system.message". System/developer instruction content with role and optional template metadata
 */
export interface SystemMessageEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: SystemMessageData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "system.message".
   */
  type: "system.message";
}
/**
 * System/developer instruction content with role and optional template metadata
 */
export interface SystemMessageData {
  /**
   * The system or developer prompt text sent as model input
   */
  content: string;
  metadata?: SystemMessageMetadata;
  /**
   * Optional name identifier for the message source
   */
  name?: string;
  role: SystemMessageRole;
}
/**
 * Metadata about the prompt template and its construction
 */
export interface SystemMessageMetadata {
  /**
   * Version identifier of the prompt template used
   */
  promptVersion?: string;
  /**
   * Template variables used when constructing the prompt
   */
  variables?: {
    [k: string]: unknown | undefined;
  };
}
/**
 * Session event "system.notification". System-generated notification for runtime events like background task completion
 */
export interface SystemNotificationEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: SystemNotificationData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "system.notification".
   */
  type: "system.notification";
}
/**
 * System-generated notification for runtime events like background task completion
 */
export interface SystemNotificationData {
  /**
   * The notification text, typically wrapped in <system_notification> XML tags
   */
  content: string;
  kind: SystemNotification;
}
/**
 * System notification metadata for a background agent that completed or failed, including agent ID, type, status, description, and prompt.
 */
export interface SystemNotificationAgentCompleted {
  /**
   * Unique identifier of the background agent
   */
  agentId: string;
  /**
   * Type of the agent (e.g., explore, task, general-purpose)
   */
  agentType: string;
  /**
   * Human-readable description of the agent task
   */
  description?: string;
  /**
   * The full prompt given to the background agent
   */
  prompt?: string;
  status: SystemNotificationAgentCompletedStatus;
  /**
   * Type discriminator. Always "agent_completed".
   */
  type: "agent_completed";
}
/**
 * System notification metadata for a background agent that became idle, including agent ID, type, and description.
 */
export interface SystemNotificationAgentIdle {
  /**
   * Unique identifier of the background agent
   */
  agentId: string;
  /**
   * Type of the agent (e.g., explore, task, general-purpose)
   */
  agentType: string;
  /**
   * Human-readable description of the agent task
   */
  description?: string;
  /**
   * Type discriminator. Always "agent_idle".
   */
  type: "agent_idle";
}
/**
 * System notification metadata for a new inbox message, including entry ID, sender details, and summary.
 */
export interface SystemNotificationNewInboxMessage {
  /**
   * Unique identifier of the inbox entry
   */
  entryId: string;
  /**
   * Human-readable name of the sender
   */
  senderName: string;
  /**
   * Category of the sender (e.g., sidekick-agent, plugin, hook)
   */
  senderType: string;
  /**
   * Short summary shown before the agent decides whether to read the inbox
   */
  summary: string;
  /**
   * Type discriminator. Always "new_inbox_message".
   */
  type: "new_inbox_message";
}
/**
 * System notification metadata for a shell session that completed, including shell ID, optional exit code, and description.
 */
export interface SystemNotificationShellCompleted {
  /**
   * Human-readable description of the command
   */
  description?: string;
  /**
   * Exit code of the shell command, if available
   */
  exitCode?: number;
  /**
   * Unique identifier of the shell session
   */
  shellId: string;
  /**
   * Type discriminator. Always "shell_completed".
   */
  type: "shell_completed";
}
/**
 * System notification metadata for a detached shell session that completed, including shell ID and description.
 */
export interface SystemNotificationShellDetachedCompleted {
  /**
   * Human-readable description of the command
   */
  description?: string;
  /**
   * Unique identifier of the detached shell session
   */
  shellId: string;
  /**
   * Type discriminator. Always "shell_detached_completed".
   */
  type: "shell_detached_completed";
}
/**
 * System notification metadata for an instruction file discovered during tool access, including source, trigger file, and tool.
 */
export interface SystemNotificationInstructionDiscovered {
  /**
   * Human-readable label for the timeline (e.g., 'AGENTS.md from packages/billing/')
   */
  description?: string;
  /**
   * Relative path to the discovered instruction file
   */
  sourcePath: string;
  /**
   * Path of the file access that triggered discovery
   */
  triggerFile: string;
  /**
   * Tool command that triggered discovery (currently always 'view')
   */
  triggerTool: string;
  /**
   * Type discriminator. Always "instruction_discovered".
   */
  type: "instruction_discovered";
}
/**
 * Session event "permission.requested". Permission request notification requiring client approval with request details
 */
export interface PermissionRequestedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: PermissionRequestedData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "permission.requested".
   */
  type: "permission.requested";
}
/**
 * Permission request notification requiring client approval with request details
 */
export interface PermissionRequestedData {
  permissionRequest: PermissionRequest;
  promptRequest?: PermissionPromptRequest;
  /**
   * Unique identifier for this permission request; used to respond via session.respondToPermission()
   */
  requestId: string;
  /**
   * When true, this permission was already resolved by a permissionRequest hook and requires no client action
   */
  resolvedByHook?: boolean;
}
/**
 * Shell command permission request
 */
export interface PermissionRequestShell {
  /**
   * Whether the UI can offer session-wide approval for this command pattern
   */
  canOfferSessionApproval: boolean;
  /**
   * Parsed command identifiers found in the command text
   */
  commands: PermissionRequestShellCommand[];
  /**
   * The complete shell command text to be executed
   */
  fullCommandText: string;
  /**
   * Whether the command includes a file write redirection (e.g., > or >>)
   */
  hasWriteFileRedirection: boolean;
  /**
   * Human-readable description of what the command intends to do
   */
  intention: string;
  /**
   * Permission kind discriminator
   */
  kind: "shell";
  /**
   * File paths that may be read or written by the command
   */
  possiblePaths: string[];
  /**
   * URLs that may be accessed by the command
   */
  possibleUrls: PermissionRequestShellPossibleUrl[];
  /**
   * True when the model has requested to run this command outside the sandbox (it set requestSandboxBypass: true and the host opted in via sandbox.allowBypass). This is a request, not a grant: the command runs unsandboxed only if the user approves this permission request. Hosts should highlight the elevated risk in the approval UI.
   */
  requestSandboxBypass?: boolean;
  /**
   * Model-provided justification for the sandbox-bypass request. Only meaningful when requestSandboxBypass is true.
   */
  requestSandboxBypassReason?: string;
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
  /**
   * Optional warning message about risks of running this command
   */
  warning?: string;
}
/**
 * A parsed command identifier in a shell permission request, including whether it is read-only.
 */
export interface PermissionRequestShellCommand {
  /**
   * Command identifier (e.g., executable name)
   */
  identifier: string;
  /**
   * Whether this command is read-only (no side effects)
   */
  readOnly: boolean;
}
/**
 * A URL that may be accessed by a command in a shell permission request.
 */
export interface PermissionRequestShellPossibleUrl {
  /**
   * URL that may be accessed by the command
   */
  url: string;
}
/**
 * File write permission request
 */
export interface PermissionRequestWrite {
  /**
   * Whether the UI can offer session-wide approval for file write operations
   */
  canOfferSessionApproval: boolean;
  /**
   * Unified diff showing the proposed changes
   */
  diff: string;
  /**
   * Path of the file being written to
   */
  fileName: string;
  /**
   * Human-readable description of the intended file change
   */
  intention: string;
  /**
   * Permission kind discriminator
   */
  kind: "write";
  /**
   * Complete new file contents for newly created files
   */
  newFileContents?: string;
  /**
   * True when a built-in file tool (apply_patch / str_replace_editor) asked to write a path the sandbox filesystem policy would block, and the host opted in via sandbox.allowBypass. This is a request, not a grant: the write happens unsandboxed only if the user approves this permission request. Hosts should highlight the elevated risk in the approval UI.
   */
  requestSandboxBypass?: boolean;
  /**
   * Justification for the sandbox-bypass request. Only meaningful when requestSandboxBypass is true.
   */
  requestSandboxBypassReason?: string;
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
}
/**
 * File or directory read permission request
 */
export interface PermissionRequestRead {
  /**
   * Human-readable description of why the file is being read
   */
  intention: string;
  /**
   * Permission kind discriminator
   */
  kind: "read";
  /**
   * Path of the file or directory being read
   */
  path: string;
  /**
   * True when the model has requested to run this search outside the sandbox (it set requestSandboxBypass: true and the host opted in via sandbox.allowBypass). This is a request, not a grant: the search runs unsandboxed only if the user approves this permission request. Hosts should highlight the elevated risk in the approval UI.
   */
  requestSandboxBypass?: boolean;
  /**
   * Model-provided justification for the sandbox-bypass request. Only meaningful when requestSandboxBypass is true.
   */
  requestSandboxBypassReason?: string;
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
}
/**
 * MCP tool invocation permission request
 */
export interface PermissionRequestMcp {
  /**
   * Arguments to pass to the MCP tool
   */
  args?: {
    [k: string]: unknown | undefined;
  };
  /**
   * Permission kind discriminator
   */
  kind: "mcp";
  /**
   * Whether this MCP tool is read-only (no side effects)
   */
  readOnly: boolean;
  /**
   * Name of the MCP server providing the tool
   */
  serverName: string;
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
  /**
   * Internal name of the MCP tool
   */
  toolName: string;
  /**
   * Human-readable title of the MCP tool
   */
  toolTitle: string;
}
/**
 * URL access permission request
 */
export interface PermissionRequestUrl {
  /**
   * Human-readable description of why the URL is being accessed
   */
  intention: string;
  /**
   * Permission kind discriminator
   */
  kind: "url";
  /**
   * True when this URL fetch is requesting to bypass the sandbox network policy: either the model set requestSandboxBypass: true, or the tool re-issued the request as an interactive bypass after the network policy denied the approved URL (host opted in via sandbox.allowBypass). This is a request, not a grant: the fetch runs only if the user approves this permission request. Hosts should highlight the elevated risk in the approval UI.
   */
  requestSandboxBypass?: boolean;
  /**
   * Model-provided justification for the sandbox-bypass request. Only meaningful when requestSandboxBypass is true.
   */
  requestSandboxBypassReason?: string;
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
  /**
   * URL to be fetched
   */
  url: string;
}
/**
 * Memory operation permission request
 */
export interface PermissionRequestMemory {
  action?: PermissionRequestMemoryAction;
  /**
   * Source references for the stored fact (store only)
   */
  citations?: string;
  direction?: PermissionRequestMemoryDirection;
  /**
   * The fact being stored or voted on
   */
  fact: string;
  /**
   * Permission kind discriminator
   */
  kind: "memory";
  /**
   * Reason for the vote (vote only)
   */
  reason?: string;
  /**
   * Topic or subject of the memory (store only)
   */
  subject?: string;
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
}
/**
 * Custom tool invocation permission request
 */
export interface PermissionRequestCustomTool {
  /**
   * Arguments to pass to the custom tool
   */
  args?: {
    [k: string]: unknown | undefined;
  };
  /**
   * Permission kind discriminator
   */
  kind: "custom-tool";
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
  /**
   * Description of what the custom tool does
   */
  toolDescription: string;
  /**
   * Name of the custom tool
   */
  toolName: string;
}
/**
 * Hook confirmation permission request
 */
export interface PermissionRequestHook {
  /**
   * Optional message from the hook explaining why confirmation is needed
   */
  hookMessage?: string;
  /**
   * Permission kind discriminator
   */
  kind: "hook";
  /**
   * Arguments of the tool call being gated
   */
  toolArgs?: {
    [k: string]: unknown | undefined;
  };
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
  /**
   * Name of the tool the hook is gating
   */
  toolName: string;
}
/**
 * Extension management permission request
 */
export interface PermissionRequestExtensionManagement {
  /**
   * Name of the extension being managed
   */
  extensionName?: string;
  /**
   * Permission kind discriminator
   */
  kind: "extension-management";
  /**
   * The extension management operation (scaffold, reload)
   */
  operation: string;
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
}
/**
 * Extension permission access request
 */
export interface PermissionRequestExtensionPermissionAccess {
  /**
   * Capabilities the extension is requesting
   */
  capabilities: string[];
  /**
   * Name of the extension requesting permission access
   */
  extensionName: string;
  /**
   * Permission kind discriminator
   */
  kind: "extension-permission-access";
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
}
/**
 * Shell command permission prompt
 */
export interface PermissionPromptRequestCommands {
  /**
   * Auto-approval judge information for this request; present only when auto mode is enabled.
   *
   * @experimental
   */
  autoApproval?: PermissionAutoApproval;
  /**
   * Whether the UI can offer session-wide approval for this command pattern
   */
  canOfferSessionApproval: boolean;
  /**
   * Command identifiers covered by this approval prompt
   */
  commandIdentifiers: string[];
  /**
   * The complete shell command text to be executed
   */
  fullCommandText: string;
  /**
   * Human-readable description of what the command intends to do
   */
  intention: string;
  /**
   * Prompt kind discriminator
   */
  kind: "commands";
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
  /**
   * Optional warning message about risks of running this command
   */
  warning?: string;
}
/**
 * Auto-approval judge information attached to a permission request. Present (non-null) only when the session's allow-all mode is "auto"; its absence means auto mode was off and the judge did not evaluate the request. The `recommendation` conveys the judge's disposition for this request.
 */
/** @experimental */
export interface PermissionAutoApproval {
  /**
   * Human-readable reason for the judge's recommendation, when available.
   */
  reason?: string;
  recommendation: AutoApprovalRecommendation;
}
/**
 * File write permission prompt
 */
export interface PermissionPromptRequestWrite {
  /**
   * Auto-approval judge information for this request; present only when auto mode is enabled.
   *
   * @experimental
   */
  autoApproval?: PermissionAutoApproval;
  /**
   * Whether the UI can offer session-wide approval for file write operations
   */
  canOfferSessionApproval: boolean;
  /**
   * Unified diff showing the proposed changes
   */
  diff: string;
  /**
   * Path of the file being written to
   */
  fileName: string;
  /**
   * Human-readable description of the intended file change
   */
  intention: string;
  /**
   * Prompt kind discriminator
   */
  kind: "write";
  /**
   * Complete new file contents for newly created files
   */
  newFileContents?: string;
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
}
/**
 * File read permission prompt
 */
export interface PermissionPromptRequestRead {
  /**
   * Auto-approval judge information for this request; present only when auto mode is enabled.
   *
   * @experimental
   */
  autoApproval?: PermissionAutoApproval;
  /**
   * Human-readable description of why the file is being read
   */
  intention: string;
  /**
   * Prompt kind discriminator
   */
  kind: "read";
  /**
   * Path of the file or directory being read
   */
  path: string;
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
}
/**
 * MCP tool invocation permission prompt
 */
export interface PermissionPromptRequestMcp {
  /**
   * Arguments to pass to the MCP tool
   */
  args?: {
    [k: string]: unknown | undefined;
  };
  /**
   * Auto-approval judge information for this request; present only when auto mode is enabled.
   *
   * @experimental
   */
  autoApproval?: PermissionAutoApproval;
  /**
   * Prompt kind discriminator
   */
  kind: "mcp";
  /**
   * Name of the MCP server providing the tool
   */
  serverName: string;
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
  /**
   * Internal name of the MCP tool
   */
  toolName: string;
  /**
   * Human-readable title of the MCP tool
   */
  toolTitle: string;
}
/**
 * URL access permission prompt
 */
export interface PermissionPromptRequestUrl {
  /**
   * Auto-approval judge information for this request; present only when auto mode is enabled.
   *
   * @experimental
   */
  autoApproval?: PermissionAutoApproval;
  /**
   * Human-readable description of why the URL is being accessed
   */
  intention: string;
  /**
   * Prompt kind discriminator
   */
  kind: "url";
  /**
   * True when this URL fetch is requesting to bypass the sandbox network policy: either the model set requestSandboxBypass: true, or the tool re-issued the request as an interactive bypass after the network policy denied the approved URL (host opted in via sandbox.allowBypass). This is a request, not a grant: the fetch runs only if the user approves this permission request. Hosts should highlight the elevated risk in the approval UI.
   */
  requestSandboxBypass?: boolean;
  /**
   * Model-provided justification for the sandbox-bypass request. Only meaningful when requestSandboxBypass is true.
   */
  requestSandboxBypassReason?: string;
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
  /**
   * URL to be fetched
   */
  url: string;
}
/**
 * Memory operation permission prompt
 */
export interface PermissionPromptRequestMemory {
  action?: PermissionRequestMemoryAction;
  /**
   * Auto-approval judge information for this request; present only when auto mode is enabled.
   *
   * @experimental
   */
  autoApproval?: PermissionAutoApproval;
  /**
   * Source references for the stored fact (store only)
   */
  citations?: string;
  direction?: PermissionRequestMemoryDirection;
  /**
   * The fact being stored or voted on
   */
  fact: string;
  /**
   * Prompt kind discriminator
   */
  kind: "memory";
  /**
   * Reason for the vote (vote only)
   */
  reason?: string;
  /**
   * Topic or subject of the memory (store only)
   */
  subject?: string;
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
}
/**
 * Custom tool invocation permission prompt
 */
export interface PermissionPromptRequestCustomTool {
  /**
   * Arguments to pass to the custom tool
   */
  args?: {
    [k: string]: unknown | undefined;
  };
  /**
   * Auto-approval judge information for this request; present only when auto mode is enabled.
   *
   * @experimental
   */
  autoApproval?: PermissionAutoApproval;
  /**
   * Prompt kind discriminator
   */
  kind: "custom-tool";
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
  /**
   * Description of what the custom tool does
   */
  toolDescription: string;
  /**
   * Name of the custom tool
   */
  toolName: string;
}
/**
 * Path access permission prompt
 */
export interface PermissionPromptRequestPath {
  accessKind: PermissionPromptRequestPathAccessKind;
  /**
   * Auto-approval judge information for this request; present only when auto mode is enabled.
   *
   * @experimental
   */
  autoApproval?: PermissionAutoApproval;
  /**
   * Prompt kind discriminator
   */
  kind: "path";
  /**
   * File paths that require explicit approval
   */
  paths: string[];
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
}
/**
 * Hook confirmation permission prompt
 */
export interface PermissionPromptRequestHook {
  /**
   * Auto-approval judge information for this request; present only when auto mode is enabled.
   *
   * @experimental
   */
  autoApproval?: PermissionAutoApproval;
  /**
   * Optional message from the hook explaining why confirmation is needed
   */
  hookMessage?: string;
  /**
   * Prompt kind discriminator
   */
  kind: "hook";
  /**
   * Arguments of the tool call being gated
   */
  toolArgs?: {
    [k: string]: unknown | undefined;
  };
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
  /**
   * Name of the tool the hook is gating
   */
  toolName: string;
}
/**
 * Extension management permission prompt
 */
export interface PermissionPromptRequestExtensionManagement {
  /**
   * Auto-approval judge information for this request; present only when auto mode is enabled.
   *
   * @experimental
   */
  autoApproval?: PermissionAutoApproval;
  /**
   * Name of the extension being managed
   */
  extensionName?: string;
  /**
   * Prompt kind discriminator
   */
  kind: "extension-management";
  /**
   * The extension management operation (scaffold, reload)
   */
  operation: string;
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
}
/**
 * Extension permission access prompt
 */
export interface PermissionPromptRequestExtensionPermissionAccess {
  /**
   * Auto-approval judge information for this request; present only when auto mode is enabled.
   *
   * @experimental
   */
  autoApproval?: PermissionAutoApproval;
  /**
   * Capabilities the extension is requesting
   */
  capabilities: string[];
  /**
   * Name of the extension requesting permission access
   */
  extensionName: string;
  /**
   * Prompt kind discriminator
   */
  kind: "extension-permission-access";
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
}
/**
 * Session event "permission.completed". Permission request completion notification signaling UI dismissal
 */
export interface PermissionCompletedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: PermissionCompletedData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "permission.completed".
   */
  type: "permission.completed";
}
/**
 * Permission request completion notification signaling UI dismissal
 */
export interface PermissionCompletedData {
  /**
   * Request ID of the resolved permission request; clients should dismiss any UI for this request
   */
  requestId: string;
  result: PermissionResult;
  /**
   * Optional tool call ID associated with this permission prompt; clients may use it to correlate UI created from tool-scoped prompts
   */
  toolCallId?: string;
}
/**
 * Permission response variant indicating the request was approved without persisting an approval rule.
 */
export interface PermissionApproved {
  /**
   * The permission request was approved
   */
  kind: "approved";
}
/**
 * Permission response variant that approves a request and remembers the provided approval for the rest of the session.
 */
export interface PermissionApprovedForSession {
  approval: UserToolSessionApproval;
  /**
   * Approved and remembered for the rest of the session
   */
  kind: "approved-for-session";
}
/**
 * Session-scoped tool-approval rule for specific shell command identifiers.
 */
export interface UserToolSessionApprovalCommands {
  /**
   * Command identifiers approved by the user
   */
  commandIdentifiers: string[];
  /**
   * Command approval kind
   */
  kind: "commands";
}
/**
 * Session-scoped tool-approval rule for read-only filesystem operations.
 */
export interface UserToolSessionApprovalRead {
  /**
   * Read approval kind
   */
  kind: "read";
}
/**
 * Session-scoped tool-approval rule for filesystem write operations.
 */
export interface UserToolSessionApprovalWrite {
  /**
   * Write approval kind
   */
  kind: "write";
}
/**
 * Session-scoped tool-approval rule for an MCP server tool, or all tools on the server when `toolName` is null.
 */
export interface UserToolSessionApprovalMcp {
  /**
   * MCP tool approval kind
   */
  kind: "mcp";
  /**
   * MCP server name
   */
  serverName: string;
  /**
   * Optional MCP tool name, or null for all tools on the server
   */
  toolName: string | null;
}
/**
 * Session-scoped tool-approval rule for writes to long-term memory.
 */
export interface UserToolSessionApprovalMemory {
  /**
   * Memory approval kind
   */
  kind: "memory";
}
/**
 * Session-scoped tool-approval rule for a custom tool, keyed by tool name.
 */
export interface UserToolSessionApprovalCustomTool {
  /**
   * Custom tool approval kind
   */
  kind: "custom-tool";
  /**
   * Custom tool name
   */
  toolName: string;
}
/**
 * Session-scoped tool-approval rule for extension-management operations, optionally narrowed by operation.
 */
export interface UserToolSessionApprovalExtensionManagement {
  /**
   * Extension management approval kind
   */
  kind: "extension-management";
  /**
   * Optional operation identifier
   */
  operation?: string;
}
/**
 * Session-scoped tool-approval rule for an extension's permission-gated capability access, keyed by extension name.
 */
export interface UserToolSessionApprovalExtensionPermissionAccess {
  /**
   * Extension name
   */
  extensionName: string;
  /**
   * Extension permission access approval kind
   */
  kind: "extension-permission-access";
}
/**
 * Permission response variant that approves a request and persists the provided approval to a project location key.
 */
export interface PermissionApprovedForLocation {
  approval: UserToolSessionApproval;
  /**
   * Approved and persisted for this project location
   */
  kind: "approved-for-location";
  /**
   * The location key (git root or cwd) to persist the approval to
   */
  locationKey: string;
}
/**
 * Permission response variant indicating the request was cancelled before use, with an optional reason.
 */
export interface PermissionCancelled {
  /**
   * The permission request was cancelled before a response was used
   */
  kind: "cancelled";
  /**
   * Optional explanation of why the request was cancelled
   */
  reason?: string;
}
/**
 * Permission response variant denied because matching approval rules explicitly blocked the request.
 */
export interface PermissionDeniedByRules {
  /**
   * Denied because approval rules explicitly blocked it
   */
  kind: "denied-by-rules";
  /**
   * Rules that denied the request
   */
  rules: PermissionRule[];
}
/**
 * A permission approval or denial rule matched against a tool request, identified by a rule kind with an optional argument value.
 */
export interface PermissionRule {
  /**
   * Argument value matched against the request, or null when the rule kind has no argument (e.g. 'read', 'write', 'memory').
   */
  argument: string | null;
  /**
   * The rule kind, such as Shell or GitHubMCP
   */
  kind: string;
}
/**
 * Permission response variant denied because no approval rule matched and user confirmation was unavailable.
 */
export interface PermissionDeniedNoApprovalRuleAndCouldNotRequestFromUser {
  /**
   * Denied because no approval rule matched and user confirmation was unavailable
   */
  kind: "denied-no-approval-rule-and-could-not-request-from-user";
}
/**
 * Permission response variant denied in an interactive user prompt, with optional feedback and force-reject flag.
 */
export interface PermissionDeniedInteractivelyByUser {
  /**
   * Optional feedback from the user explaining the denial
   */
  feedback?: string;
  /**
   * Whether to force-reject the current agent turn
   */
  forceReject?: boolean;
  /**
   * Denied by the user during an interactive prompt
   */
  kind: "denied-interactively-by-user";
}
/**
 * Permission response variant denying a path under content exclusion policy, with the path and message.
 */
export interface PermissionDeniedByContentExclusionPolicy {
  /**
   * Denied by the organization's content exclusion policy
   */
  kind: "denied-by-content-exclusion-policy";
  /**
   * Human-readable explanation of why the path was excluded
   */
  message: string;
  /**
   * File path that triggered the exclusion
   */
  path: string;
}
/**
 * Permission response variant denied by a permission-request hook, with optional message and interrupt flag.
 */
export interface PermissionDeniedByPermissionRequestHook {
  /**
   * Whether to interrupt the current agent turn
   */
  interrupt?: boolean;
  /**
   * Denied by a permission request hook registered by an extension or plugin
   */
  kind: "denied-by-permission-request-hook";
  /**
   * Optional message from the hook explaining the denial
   */
  message?: string;
}
/**
 * Session event "user_input.requested". User input request notification with question and optional predefined choices
 */
export interface UserInputRequestedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: UserInputRequestedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "user_input.requested".
   */
  type: "user_input.requested";
}
/**
 * User input request notification with question and optional predefined choices
 */
export interface UserInputRequestedData {
  /**
   * Whether the user can provide a free-form text response in addition to predefined choices
   */
  allowFreeform?: boolean;
  /**
   * Predefined choices for the user to select from, if applicable
   */
  choices?: string[];
  /**
   * The question or prompt to present to the user
   */
  question: string;
  /**
   * Unique identifier for this input request; used to respond via session.respondToUserInput()
   */
  requestId: string;
  /**
   * The LLM-assigned tool call ID that triggered this request; used by remote UIs to correlate responses
   */
  toolCallId?: string;
}
/**
 * Session event "user_input.completed". User input request completion with the user's response
 */
export interface UserInputCompletedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: UserInputCompletedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "user_input.completed".
   */
  type: "user_input.completed";
}
/**
 * User input request completion with the user's response
 */
export interface UserInputCompletedData {
  /**
   * The user's answer to the input request
   */
  answer?: string;
  /**
   * Request ID of the resolved user input request; clients should dismiss any UI for this request
   */
  requestId: string;
  /**
   * Whether the answer was typed as free-form text rather than selected from choices
   */
  wasFreeform?: boolean;
}
/**
 * Session event "elicitation.requested". Elicitation request; may be form-based (structured input) or URL-based (browser redirect)
 */
export interface ElicitationRequestedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ElicitationRequestedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "elicitation.requested".
   */
  type: "elicitation.requested";
}
/**
 * Elicitation request; may be form-based (structured input) or URL-based (browser redirect)
 */
export interface ElicitationRequestedData {
  /**
   * The source that initiated the request (MCP server name, or absent for agent-initiated)
   */
  elicitationSource?: string;
  /**
   * Message describing what information is needed from the user
   */
  message: string;
  mode?: ElicitationRequestedMode;
  requestedSchema?: ElicitationRequestedSchema;
  /**
   * Unique identifier for this elicitation request; used to respond via session.respondToElicitation()
   */
  requestId: string;
  /**
   * Tool call ID from the LLM completion; used to correlate with CompletionChunk.toolCall.id for remote UIs
   */
  toolCallId?: string;
  /**
   * URL to open in the user's browser (url mode only)
   */
  url?: string;
}
/**
 * JSON Schema describing the form fields to present to the user (form mode only)
 */
export interface ElicitationRequestedSchema {
  /**
   * Form field definitions, keyed by field name
   */
  properties: {
    [k: string]: unknown | undefined;
  };
  /**
   * List of required field names
   */
  required?: string[];
  /**
   * Schema type indicator (always 'object')
   */
  type: "object";
}
/**
 * Session event "elicitation.completed". Elicitation request completion with the user's response
 */
export interface ElicitationCompletedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ElicitationCompletedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "elicitation.completed".
   */
  type: "elicitation.completed";
}
/**
 * Elicitation request completion with the user's response
 */
export interface ElicitationCompletedData {
  action?: ElicitationCompletedAction;
  /**
   * The submitted form data when action is 'accept'; keys match the requested schema fields
   */
  content?: {
    [k: string]: ElicitationCompletedContent | undefined;
  };
  /**
   * Request ID of the resolved elicitation request; clients should dismiss any UI for this request
   */
  requestId: string;
}
/**
 * Opaque JSON value submitted for one field in accepted `elicitation.completed` form content.
 */
export interface ElicitationCompletedContent {
  [k: string]: unknown | undefined;
}
/**
 * Session event "sampling.requested". Sampling request from an MCP server; contains the server name and a requestId for correlation
 */
export interface SamplingRequestedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: SamplingRequestedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "sampling.requested".
   */
  type: "sampling.requested";
}
/**
 * Sampling request from an MCP server; contains the server name and a requestId for correlation
 */
export interface SamplingRequestedData {
  /**
   * The JSON-RPC request ID from the MCP protocol
   */
  mcpRequestId: {
    [k: string]: unknown | undefined;
  };
  /**
   * Unique identifier for this sampling request; used to respond via session.respondToSampling()
   */
  requestId: string;
  /**
   * Name of the MCP server that initiated the sampling request
   */
  serverName: string;
}
/**
 * Session event "sampling.completed". Sampling request completion notification signaling UI dismissal
 */
export interface SamplingCompletedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: SamplingCompletedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "sampling.completed".
   */
  type: "sampling.completed";
}
/**
 * Sampling request completion notification signaling UI dismissal
 */
export interface SamplingCompletedData {
  /**
   * Request ID of the resolved sampling request; clients should dismiss any UI for this request
   */
  requestId: string;
}
/**
 * Session event "mcp.oauth_required". OAuth authentication request for an MCP server
 */
export interface McpOauthRequiredEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: McpOauthRequiredData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "mcp.oauth_required".
   */
  type: "mcp.oauth_required";
}
/**
 * OAuth authentication request for an MCP server
 */
export interface McpOauthRequiredData {
  httpResponse?: McpOauthHttpResponse;
  reason: McpOauthRequestReason;
  /**
   * Unique identifier for this OAuth request; used to respond via session.mcp.oauth.handlePendingRequest
   */
  requestId: string;
  /**
   * Raw OAuth protected-resource metadata document fetched for the MCP server, if available
   */
  resourceMetadata?: string;
  /**
   * Display name of the MCP server that requires OAuth
   */
  serverName: string;
  /**
   * URL of the MCP server that requires OAuth
   */
  serverUrl: string;
  staticClientConfig?: McpOauthRequiredStaticClientConfig;
  wwwAuthenticateParams?: McpOauthWWWAuthenticateParams;
}
/**
 * Raw HTTP response details from the OAuth auth challenge, as observed by the runtime.
 */
export interface McpOauthHttpResponse {
  /**
   * Complete UTF-8 response body for host-specific challenge handling, including an empty string for an empty body. Omitted when the complete body is not valid UTF-8; body read failures fail the HTTP operation rather than exposing a partial response.
   */
  body?: string;
  /**
   * HTTP response headers as observed by the runtime. Order and casing are transport-dependent, and duplicate header names may appear multiple times.
   */
  headers: HeaderEntry[];
  /**
   * HTTP status code returned with the auth challenge.
   */
  statusCode: number;
}
/**
 * Single HTTP header entry as a name/value pair.
 */
export interface HeaderEntry {
  /**
   * HTTP response header name as observed by the runtime.
   */
  name: string;
  /**
   * HTTP response header value as observed by the runtime.
   */
  value: string;
}
/**
 * Static OAuth client configuration, if the server specifies one
 */
export interface McpOauthRequiredStaticClientConfig {
  /**
   * OAuth client ID for the server
   */
  clientId: string;
  /**
   * Optional OAuth client secret for confidential static clients, when the runtime can resolve one
   */
  clientSecret?: string;
  /**
   * Optional non-default OAuth grant type. When set to 'client_credentials', the OAuth flow runs headlessly using the client_id + keychain-stored secret (no browser, no callback server).
   */
  grantType?: "client_credentials";
  /**
   * Whether this is a public OAuth client
   */
  publicClient?: boolean;
}
/**
 * OAuth WWW-Authenticate parameters parsed from an MCP auth challenge
 */
export interface McpOauthWWWAuthenticateParams {
  /**
   * OAuth error from the WWW-Authenticate error parameter, if present
   */
  error?: string;
  /**
   * Protected resource metadata URL from the WWW-Authenticate resource_metadata parameter, if present
   */
  resourceMetadataUrl?: string;
  /**
   * Requested OAuth scopes from the WWW-Authenticate scope parameter, if present
   */
  scope?: string;
}
/**
 * Session event "mcp.oauth_completed". MCP OAuth request completion notification
 */
export interface McpOauthCompletedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: McpOauthCompletedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "mcp.oauth_completed".
   */
  type: "mcp.oauth_completed";
}
/**
 * MCP OAuth request completion notification
 */
export interface McpOauthCompletedData {
  outcome: McpOauthCompletionOutcome;
  /**
   * Request ID of the resolved OAuth request
   */
  requestId: string;
}
/**
 * Session event "mcp.headers_refresh_required". Dynamic headers refresh request for a remote MCP server
 */
export interface McpHeadersRefreshRequiredEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: McpHeadersRefreshRequiredData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "mcp.headers_refresh_required".
   */
  type: "mcp.headers_refresh_required";
}
/**
 * Dynamic headers refresh request for a remote MCP server
 */
export interface McpHeadersRefreshRequiredData {
  reason: McpHeadersRefreshRequiredReason;
  /**
   * Unique identifier for this headers refresh request; used to respond via session.mcp.headers.handlePendingHeadersRefreshRequest()
   */
  requestId: string;
  /**
   * Display name of the remote MCP server requesting headers
   */
  serverName: string;
  /**
   * URL of the remote MCP server requesting headers
   */
  serverUrl: string;
}
/**
 * Session event "mcp.headers_refresh_completed". MCP headers refresh request completion notification
 */
export interface McpHeadersRefreshCompletedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: McpHeadersRefreshCompletedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "mcp.headers_refresh_completed".
   */
  type: "mcp.headers_refresh_completed";
}
/**
 * MCP headers refresh request completion notification
 */
export interface McpHeadersRefreshCompletedData {
  outcome: McpHeadersRefreshCompletedOutcome;
  /**
   * Request ID of the resolved headers refresh request
   */
  requestId: string;
}
/**
 * Session event "session.custom_notification". Opaque custom notification data. Consumers may branch on source and name, but payload semantics are source-defined.
 */
export interface CustomNotificationEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: CustomNotificationData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.custom_notification".
   */
  type: "session.custom_notification";
}
/**
 * Opaque custom notification data. Consumers may branch on source and name, but payload semantics are source-defined.
 */
export interface CustomNotificationData {
  /**
   * Source-defined custom notification name
   */
  name: string;
  payload: CustomNotificationPayload;
  /**
   * Namespace for the custom notification producer
   */
  source: string;
  subject?: CustomNotificationSubject;
  /**
   * Optional source-defined payload schema version
   */
  version?: number;
}
/**
 * Source-defined JSON payload for the custom notification
 */
export interface CustomNotificationPayload {
  [k: string]: unknown | undefined;
}
/**
 * Optional source-defined string identifiers describing the payload subject
 */
export interface CustomNotificationSubject {
  [k: string]: string | undefined;
}
/**
 * Session event "external_tool.requested". External tool invocation request for client-side tool execution
 */
export interface ExternalToolRequestedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ExternalToolRequestedData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "external_tool.requested".
   */
  type: "external_tool.requested";
}
/**
 * External tool invocation request for client-side tool execution
 */
export interface ExternalToolRequestedData {
  /**
   * Arguments to pass to the external tool
   */
  arguments?: {
    [k: string]: unknown | undefined;
  };
  /**
   * Unique identifier for this request; used to respond via session.respondToExternalTool()
   */
  requestId: string;
  /**
   * Session ID that this external tool request belongs to
   */
  sessionId: string;
  /**
   * Tool call ID assigned to this external tool invocation
   */
  toolCallId: string;
  /**
   * Name of the external tool to invoke
   */
  toolName: string;
  /**
   * W3C Trace Context traceparent header for the execute_tool span
   */
  traceparent?: string;
  /**
   * W3C Trace Context tracestate header for the execute_tool span
   */
  tracestate?: string;
  /**
   * Active session working directory, when known.
   */
  workingDirectory?: string;
}
/**
 * Session event "external_tool.completed". External tool completion notification signaling UI dismissal
 */
export interface ExternalToolCompletedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ExternalToolCompletedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral?: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "external_tool.completed".
   */
  type: "external_tool.completed";
}
/**
 * External tool completion notification signaling UI dismissal
 */
export interface ExternalToolCompletedData {
  /**
   * Request ID of the resolved external tool request; clients should dismiss any UI for this request
   */
  requestId: string;
}
/**
 * Session event "command.queued". Queued slash command dispatch request for client execution
 */
export interface CommandQueuedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: CommandQueuedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "command.queued".
   */
  type: "command.queued";
}
/**
 * Queued slash command dispatch request for client execution
 */
export interface CommandQueuedData {
  /**
   * The slash command text to be executed (e.g., /help, /clear)
   */
  command: string;
  /**
   * Unique identifier for this request; used to respond via session.respondToQueuedCommand()
   */
  requestId: string;
}
/**
 * Session event "command.execute". Registered command dispatch request routed to the owning client
 */
export interface CommandExecuteEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: CommandExecuteData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "command.execute".
   */
  type: "command.execute";
}
/**
 * Registered command dispatch request routed to the owning client
 */
export interface CommandExecuteData {
  /**
   * Raw argument string after the command name
   */
  args: string;
  /**
   * The full command text (e.g., /deploy production)
   */
  command: string;
  /**
   * Command name without leading /
   */
  commandName: string;
  /**
   * Unique identifier; used to respond via session.commands.handlePendingCommand()
   */
  requestId: string;
}
/**
 * Session event "command.completed". Queued command completion notification signaling UI dismissal
 */
export interface CommandCompletedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: CommandCompletedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "command.completed".
   */
  type: "command.completed";
}
/**
 * Queued command completion notification signaling UI dismissal
 */
export interface CommandCompletedData {
  /**
   * Request ID of the resolved command request; clients should dismiss any UI for this request
   */
  requestId: string;
}
/**
 * Session event "auto_mode_switch.requested". Auto mode switch request notification requiring user approval
 */
export interface AutoModeSwitchRequestedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: AutoModeSwitchRequestedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "auto_mode_switch.requested".
   */
  type: "auto_mode_switch.requested";
}
/**
 * Auto mode switch request notification requiring user approval
 */
export interface AutoModeSwitchRequestedData {
  /**
   * The rate limit error code that triggered this request
   */
  errorCode?: string;
  /**
   * Unique identifier for this request; used to respond via session.respondToAutoModeSwitch()
   */
  requestId: string;
  /**
   * Seconds until the rate limit resets, when known. Lets clients render a humanized reset time alongside the prompt.
   */
  retryAfterSeconds?: number;
}
/**
 * Session event "auto_mode_switch.completed". Auto mode switch completion notification
 */
export interface AutoModeSwitchCompletedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: AutoModeSwitchCompletedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "auto_mode_switch.completed".
   */
  type: "auto_mode_switch.completed";
}
/**
 * Auto mode switch completion notification
 */
export interface AutoModeSwitchCompletedData {
  /**
   * Request ID of the resolved request; clients should dismiss any UI for this request
   */
  requestId: string;
  response: AutoModeSwitchResponse;
}
/**
 * Session event "session_limits_exhausted.requested". Session limit exhaustion notification requiring user action.
 */
export interface SessionLimitsExhaustedRequestedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: SessionLimitsExhaustedRequestedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session_limits_exhausted.requested".
   */
  type: "session_limits_exhausted.requested";
}
/**
 * Session limit exhaustion notification requiring user action.
 */
export interface SessionLimitsExhaustedRequestedData {
  /**
   * Configured max AI Credits for the current accounting window.
   */
  maxAiCredits: number;
  /**
   * Unique identifier for this request; used to respond via session.ui.handlePendingSessionLimitsExhausted().
   */
  requestId: string;
  /**
   * AI Credits already consumed in the current accounting window.
   */
  usedAiCredits: number;
}
/**
 * Session event "session_limits_exhausted.completed". Session limit exhaustion prompt completion notification.
 */
export interface SessionLimitsExhaustedCompletedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: SessionLimitsExhaustedCompletedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session_limits_exhausted.completed".
   */
  type: "session_limits_exhausted.completed";
}
/**
 * Session limit exhaustion prompt completion notification.
 */
export interface SessionLimitsExhaustedCompletedData {
  /**
   * Request ID of the resolved request; clients should dismiss any UI for this request.
   */
  requestId: string;
  response: SessionLimitsExhaustedResponse;
}
/**
 * The user's selected action for an exhausted session limit.
 */
export interface SessionLimitsExhaustedResponse {
  action: SessionLimitsExhaustedResponseAction;
  /**
   * AI Credits to add to the current max when action is 'add'.
   */
  additionalAiCredits?: number;
  /**
   * New absolute max AI Credits when action is 'set'.
   */
  maxAiCredits?: number;
}
/**
 * Session event "session.auto_mode_resolved". Auto Intent resolution: the concrete model the session settled on for the first prompt of an auto-mode session, and why. Lets SDK clients render the chosen model and the full reason it was picked. The core selection fields (chosenModel/reasoningBucket/categoryScores) are stable; the routing-analytics fields (predictedLabel/confidence/candidateModels) mirror the upstream intent service and may evolve, hence the event's experimental stability.
 */
/** @experimental */
export interface AutoModeResolvedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: AutoModeResolvedData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.auto_mode_resolved".
   */
  type: "session.auto_mode_resolved";
}
/**
 * Auto Intent resolution: the concrete model the session settled on for the first prompt of an auto-mode session, and why. Lets SDK clients render the chosen model and the full reason it was picked. The core selection fields (chosenModel/reasoningBucket/categoryScores) are stable; the routing-analytics fields (predictedLabel/confidence/candidateModels) mirror the upstream intent service and may evolve, hence the event's experimental stability.
 */
/** @experimental */
export interface AutoModeResolvedData {
  /**
   * Ordered candidate model list the router returned, when not a fallback
   */
  candidateModels?: string[];
  /**
   * Per-category classifier scores (0-1) behind the bucket: the granular HYDRA capability scores (reasoning, code_gen, debugging, tool_use), or the binary needs_reasoning/no_reasoning scores when HYDRA didn't run. Lets clients show a breakdown rather than just the bucket.
   */
  categoryScores?: {
    [k: string]: number | undefined;
  };
  /**
   * The concrete model the session will use after any intent refinement
   */
  chosenModel: string;
  /**
   * Classifier confidence for the predicted label, when available
   */
  confidence?: number;
  /**
   * The predicted classifier label (e.g. `needs_reasoning`), when available
   */
  predictedLabel?: string;
  reasoningBucket?: AutoModeResolvedReasoningBucket;
}
/**
 * Session event "session.managed_settings_resolved". Enterprise managed-settings resolution: the effective managed settings the session applied and where they came from, so SDK clients can show users what is enterprise-managed and by which authority. Fires whenever managed policy is (re)applied — at session start, on resume, and on account switch. This is an ephemeral live snapshot (delivered to subscribers but not persisted to the session event log), because at session start it resolves before `session.start` is emitted; for a session-independent pull, use the SDK `getManagedSettings()` API, which returns the identical payload. Managed settings have a single authoritative source, so the highest-authority present layer (server > device) wins wholesale; `bypassPermissionsDisabled` is deny-wins across layers. Marked experimental while the managed-settings surface stabilizes.
 */
/** @experimental */
export interface ManagedSettingsResolvedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ManagedSettingsResolvedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.managed_settings_resolved".
   */
  type: "session.managed_settings_resolved";
}
/**
 * Enterprise managed-settings resolution: the effective managed settings the session applied and where they came from, so SDK clients can show users what is enterprise-managed and by which authority. Fires whenever managed policy is (re)applied — at session start, on resume, and on account switch. This is an ephemeral live snapshot (delivered to subscribers but not persisted to the session event log), because at session start it resolves before `session.start` is emitted; for a session-independent pull, use the SDK `getManagedSettings()` API, which returns the identical payload. Managed settings have a single authoritative source, so the highest-authority present layer (server > device) wins wholesale; `bypassPermissionsDisabled` is deny-wins across layers. Marked experimental while the managed-settings surface stabilizes.
 */
/** @experimental */
export interface ManagedSettingsResolvedData {
  /**
   * Whether enterprise policy disables bypass-permissions ("yolo") mode for this session. Deny-wins across layers, and forced on when `failClosed` is true.
   */
  bypassPermissionsDisabled: boolean;
  /**
   * Whether the device (MDM/plist/registry/file) managed-settings layer was present
   */
  deviceManaged: boolean;
  /**
   * Whether managed policy could not be determined (e.g. a failed server fetch) and the session fell back to the fail-closed restriction. When true, restrictions such as disabling bypass-permissions are enforced even though `settings` may be absent.
   */
  failClosed: boolean;
  /**
   * The setting keys under enterprise management in the effective managed settings (e.g. `model`, `enabledPlugins`, `permissions`). Empty when no managed settings are in force.
   */
  managedKeys: string[];
  /**
   * Whether the server (account/org) managed-settings layer was present
   */
  serverManaged: boolean;
  /**
   * The effective (resolved) managed settings values, so clients can render exactly what is enforced. Absent when no managed policy is in force.
   */
  settings?: {
    [k: string]: unknown | undefined;
  };
  source: ManagedSettingsResolvedSource;
}
/**
 * Session event "commands.changed". SDK command registration change notification
 */
export interface CommandsChangedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: CommandsChangedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "commands.changed".
   */
  type: "commands.changed";
}
/**
 * SDK command registration change notification
 */
export interface CommandsChangedData {
  /**
   * Current list of registered SDK commands
   */
  commands: CommandsChangedCommand[];
}
/**
 * A single slash command available in the session, as listed by the `commands.changed` event.
 */
export interface CommandsChangedCommand {
  /**
   * Optional human-readable command description.
   */
  description?: string;
  /**
   * Slash command name without the leading slash.
   */
  name: string;
}
/**
 * Session event "capabilities.changed". Session capability change notification
 */
export interface CapabilitiesChangedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: CapabilitiesChangedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "capabilities.changed".
   */
  type: "capabilities.changed";
}
/**
 * Session capability change notification
 */
export interface CapabilitiesChangedData {
  ui?: CapabilitiesChangedUI;
}
/**
 * UI capability changes
 */
export interface CapabilitiesChangedUI {
  /**
   * Whether canvas rendering is now supported
   */
  canvases?: boolean;
  /**
   * Whether elicitation is now supported
   */
  elicitation?: boolean;
  /**
   * Whether MCP Apps (SEP-1865) UI passthrough is now supported
   */
  mcpApps?: boolean;
}
/**
 * Session event "exit_plan_mode.requested". Plan approval request with plan content and available user actions
 */
export interface ExitPlanModeRequestedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ExitPlanModeRequestedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "exit_plan_mode.requested".
   */
  type: "exit_plan_mode.requested";
}
/**
 * Plan approval request with plan content and available user actions
 */
export interface ExitPlanModeRequestedData {
  /**
   * Available actions the user can take
   */
  actions: ExitPlanModeAction[];
  /**
   * Full content of the plan file
   */
  planContent: string;
  recommendedAction: ExitPlanModeAction;
  /**
   * Unique identifier for this request; used to respond via session.respondToExitPlanMode()
   */
  requestId: string;
  /**
   * Summary of the plan that was created
   */
  summary: string;
}
/**
 * Session event "exit_plan_mode.completed". Plan mode exit completion with the user's approval decision and optional feedback
 */
export interface ExitPlanModeCompletedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ExitPlanModeCompletedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "exit_plan_mode.completed".
   */
  type: "exit_plan_mode.completed";
}
/**
 * Plan mode exit completion with the user's approval decision and optional feedback
 */
export interface ExitPlanModeCompletedData {
  /**
   * Whether the plan was approved by the user
   */
  approved?: boolean;
  /**
   * Whether edits should be auto-approved without confirmation
   */
  autoApproveEdits?: boolean;
  /**
   * Free-form feedback from the user if they requested changes to the plan
   */
  feedback?: string;
  /**
   * Request ID of the resolved exit plan mode request; clients should dismiss any UI for this request
   */
  requestId: string;
  selectedAction?: ExitPlanModeAction;
}
/**
 * Session event "session.tools_updated". Payload of `session.tools_updated` identifying the model whose resolved tools were updated.
 */
export interface ToolsUpdatedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ToolsUpdatedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.tools_updated".
   */
  type: "session.tools_updated";
}
/**
 * Payload of `session.tools_updated` identifying the model whose resolved tools were updated.
 */
export interface ToolsUpdatedData {
  /**
   * Identifier of the model the resolved tools apply to.
   */
  model: string;
}
/**
 * Session event "session.background_tasks_changed". Empty payload for `session.background_tasks_changed`, indicating background task state changed.
 */
export interface BackgroundTasksChangedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: BackgroundTasksChangedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.background_tasks_changed".
   */
  type: "session.background_tasks_changed";
}
/**
 * Empty payload for `session.background_tasks_changed`, indicating background task state changed.
 */
export interface BackgroundTasksChangedData {}
/**
 * Session event "session.skills_loaded". Payload of `session.skills_loaded` listing resolved skill metadata.
 */
export interface SkillsLoadedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: SkillsLoadedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.skills_loaded".
   */
  type: "session.skills_loaded";
}
/**
 * Payload of `session.skills_loaded` listing resolved skill metadata.
 */
export interface SkillsLoadedData {
  /**
   * Array of resolved skill metadata
   */
  skills: SkillsLoadedSkill[];
}
/**
 * A single resolved skill in `session.skills_loaded`, including source, invocability, enabled state, path, and argument hint.
 */
export interface SkillsLoadedSkill {
  /**
   * Optional freeform hint describing the skill's expected arguments, from the `argument-hint` frontmatter field
   */
  argumentHint?: string;
  /**
   * Description of what the skill does
   */
  description: string;
  /**
   * Whether the skill is currently enabled
   */
  enabled: boolean;
  /**
   * Unique identifier for the skill
   */
  name: string;
  /**
   * Absolute path to the skill file, if available
   */
  path?: string;
  source: SkillSource;
  /**
   * Whether the skill can be invoked by the user as a slash command
   */
  userInvocable: boolean;
}
/**
 * Session event "session.custom_agents_updated". Payload of `session.custom_agents_updated` with loaded custom agents plus non-fatal warnings and fatal errors.
 */
export interface CustomAgentsUpdatedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: CustomAgentsUpdatedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.custom_agents_updated".
   */
  type: "session.custom_agents_updated";
}
/**
 * Payload of `session.custom_agents_updated` with loaded custom agents plus non-fatal warnings and fatal errors.
 */
export interface CustomAgentsUpdatedData {
  /**
   * Array of loaded custom agent metadata
   */
  agents: CustomAgentsUpdatedAgent[];
  /**
   * Fatal errors from agent loading
   */
  errors: string[];
  /**
   * Non-fatal warnings from agent loading
   */
  warnings: string[];
}
/**
 * A single loaded custom agent in `session.custom_agents_updated`, with identity, source, tools, invocability, and model override.
 */
export interface CustomAgentsUpdatedAgent {
  /**
   * Description of what the agent does
   */
  description: string;
  /**
   * Human-readable display name
   */
  displayName: string;
  /**
   * Unique identifier for the agent
   */
  id: string;
  /**
   * Model override for this agent, if set
   */
  model?: string;
  /**
   * Internal name of the agent
   */
  name: string;
  /**
   * Source location: user, project, inherited, remote, or plugin
   */
  source: string;
  /**
   * List of tool names available to this agent, or null when all tools are available
   */
  tools: string[] | null;
  /**
   * Whether the agent can be selected by the user
   */
  userInvocable: boolean;
}
/**
 * Session event "session.mcp_servers_loaded". Payload of `session.mcp_servers_loaded` listing MCP server status summaries.
 */
export interface McpServersLoadedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: McpServersLoadedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.mcp_servers_loaded".
   */
  type: "session.mcp_servers_loaded";
}
/**
 * Payload of `session.mcp_servers_loaded` listing MCP server status summaries.
 */
export interface McpServersLoadedData {
  /**
   * Array of MCP server status summaries
   */
  servers: McpServersLoadedServer[];
}
/**
 * A single MCP server status summary in `session.mcp_servers_loaded`, including name, status, source, transport, and plugin metadata.
 */
export interface McpServersLoadedServer {
  /**
   * Error message if the server failed to connect
   */
  error?: string;
  /**
   * Server name (config key)
   */
  name: string;
  /**
   * Name of the plugin that supplied the effective MCP server config, only when source is plugin
   */
  pluginName?: string;
  /**
   * Version of the plugin that supplied the effective MCP server config, only when source is plugin
   */
  pluginVersion?: string;
  source?: McpServerSource;
  status: McpServerStatus;
  transport?: McpServerTransport;
}
/**
 * Session event "session.mcp_server_status_changed". Payload of `session.mcp_server_status_changed` for one MCP server's status and optional failure error.
 */
export interface McpServerStatusChangedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: McpServerStatusChangedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.mcp_server_status_changed".
   */
  type: "session.mcp_server_status_changed";
}
/**
 * Payload of `session.mcp_server_status_changed` for one MCP server's status and optional failure error.
 */
export interface McpServerStatusChangedData {
  /**
   * Error message if the server entered a failed state
   */
  error?: string;
  /**
   * Name of the MCP server whose status changed
   */
  serverName: string;
  status: McpServerStatus;
}
/**
 * Session event "mcp.tools.list_changed". Payload identifying the MCP server associated with a list change.
 */
export interface McpToolsListChangedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: McpListChangedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "mcp.tools.list_changed".
   */
  type: "mcp.tools.list_changed";
}
/**
 * Payload identifying the MCP server associated with a list change.
 */
export interface McpListChangedData {
  /**
   * Name of the MCP server whose list changed
   */
  serverName: string;
}
/**
 * Session event "mcp.resources.list_changed". Payload identifying the MCP server associated with a list change.
 */
export interface McpResourcesListChangedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: McpListChangedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "mcp.resources.list_changed".
   */
  type: "mcp.resources.list_changed";
}
/**
 * Session event "mcp.prompts.list_changed". Payload identifying the MCP server associated with a list change.
 */
export interface McpPromptsListChangedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: McpListChangedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "mcp.prompts.list_changed".
   */
  type: "mcp.prompts.list_changed";
}
/**
 * Session event "session.extensions_loaded". Payload of `session.extensions_loaded` listing discovered extensions and their statuses.
 */
export interface ExtensionsLoadedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ExtensionsLoadedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.extensions_loaded".
   */
  type: "session.extensions_loaded";
}
/**
 * Payload of `session.extensions_loaded` listing discovered extensions and their statuses.
 */
export interface ExtensionsLoadedData {
  /**
   * Array of discovered extensions and their status
   */
  extensions: ExtensionsLoadedExtension[];
}
/**
 * A single extension discovered by `session.extensions_loaded`, including qualified ID, source, and current status.
 */
export interface ExtensionsLoadedExtension {
  /**
   * Source-qualified extension ID (e.g., 'project:my-ext', 'user:auth-helper', 'plugin:my-plugin:my-ext')
   */
  id: string;
  /**
   * Extension name (directory name)
   */
  name: string;
  source: ExtensionsLoadedExtensionSource;
  status: ExtensionsLoadedExtensionStatus;
}
/**
 * Session event "session.canvas.opened". Payload of `session.canvas.opened` with canvas instance and provider IDs plus optional icon, title, status, URL, and input.
 */
/** @experimental */
export interface CanvasOpenedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: CanvasOpenedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.canvas.opened".
   */
  type: "session.canvas.opened";
}
/**
 * Payload of `session.canvas.opened` with canvas instance and provider IDs plus optional icon, title, status, URL, and input.
 */
/** @experimental */
export interface CanvasOpenedData {
  /**
   * Provider-local canvas identifier
   */
  canvasId: string;
  /**
   * Owning provider identifier
   */
  extensionId: string;
  /**
   * Owning extension display name, when available
   */
  extensionName?: string;
  /**
   * Host-local PNG path for the canvas icon, when supplied
   */
  icon?: string;
  /**
   * Input supplied when the instance was opened
   */
  input?: {
    [k: string]: unknown | undefined;
  };
  /**
   * Stable caller-supplied canvas instance identifier
   */
  instanceId: string;
  /**
   * Provider-supplied status text
   */
  status?: string;
  /**
   * Rendered title
   */
  title?: string;
  /**
   * URL for web-rendered canvases
   */
  url?: string;
}
/**
 * Session event "session.canvas.registry_changed". Payload of `session.canvas.registry_changed` listing the canvas declarations currently available.
 */
/** @experimental */
export interface CanvasRegistryChangedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: CanvasRegistryChangedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.canvas.registry_changed".
   */
  type: "session.canvas.registry_changed";
}
/**
 * Payload of `session.canvas.registry_changed` listing the canvas declarations currently available.
 */
/** @experimental */
export interface CanvasRegistryChangedData {
  /**
   * Canvas declarations currently available
   */
  canvases: CanvasRegistryChangedCanvas[];
}
/**
 * A single canvas declaration in `session.canvas.registry_changed`, including provider IDs, display metadata, input schema, and actions.
 */
/** @experimental */
export interface CanvasRegistryChangedCanvas {
  /**
   * Actions the agent or host may invoke
   */
  actions?: CanvasRegistryChangedCanvasAction[];
  /**
   * Provider-local canvas identifier
   */
  canvasId: string;
  /**
   * Short, single-sentence description shown to the agent in canvas catalogs.
   */
  description: string;
  /**
   * Human-readable canvas name
   */
  displayName: string;
  /**
   * Owning provider identifier
   */
  extensionId: string;
  /**
   * Owning extension display name, when available
   */
  extensionName?: string;
  /**
   * Host-local PNG path for the canvas icon, when supplied
   */
  icon?: string;
  /**
   * JSON Schema for canvas open input
   */
  inputSchema?: {
    [k: string]: unknown | undefined;
  };
}
/**
 * A single action within a canvas declaration, with its name, optional description, and optional input schema.
 */
/** @experimental */
export interface CanvasRegistryChangedCanvasAction {
  /**
   * Action description
   */
  description?: string;
  /**
   * JSON Schema for action input
   */
  inputSchema?: {
    [k: string]: unknown | undefined;
  };
  /**
   * Action name
   */
  name: string;
}
/**
 * Session event "session.canvas.closed". Payload of `session.canvas.closed` with the closed canvas instance ID, provider ID, and canvas ID.
 */
/** @experimental */
export interface CanvasClosedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: CanvasClosedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.canvas.closed".
   */
  type: "session.canvas.closed";
}
/**
 * Payload of `session.canvas.closed` with the closed canvas instance ID, provider ID, and canvas ID.
 */
/** @experimental */
export interface CanvasClosedData {
  /**
   * Provider-local canvas identifier
   */
  canvasId: string;
  /**
   * Owning provider identifier
   */
  extensionId: string;
  /**
   * Stable caller-supplied identifier of the canvas instance that was closed
   */
  instanceId: string;
}
/**
 * Session event "session.canvas.unavailable". Transient signal that an open canvas instance's provider has dropped (for example the extension is reloading mid-session). The host should keep the panel mounted and surface a reconnecting affordance rather than tearing it down; a subsequent `session.canvas.opened` for the same instanceId clears the affordance once the provider reconnects with a fresh url. Ephemeral and never persisted, so it is never replayed on cold resume.
 */
/** @experimental */
export interface CanvasUnavailableEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: CanvasUnavailableData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.canvas.unavailable".
   */
  type: "session.canvas.unavailable";
}
/**
 * Transient signal that an open canvas instance's provider has dropped (for example the extension is reloading mid-session). The host should keep the panel mounted and surface a reconnecting affordance rather than tearing it down; a subsequent `session.canvas.opened` for the same instanceId clears the affordance once the provider reconnects with a fresh url. Ephemeral and never persisted, so it is never replayed on cold resume.
 */
/** @experimental */
export interface CanvasUnavailableData {
  /**
   * Provider-local canvas identifier
   */
  canvasId: string;
  /**
   * Owning provider identifier
   */
  extensionId: string;
  /**
   * Stable caller-supplied identifier of the canvas instance whose provider became unavailable
   */
  instanceId: string;
}
/**
 * Session event "session.canvas.recorded". Durable record that a canvas instance is open, used to restore open canvases on cold session resume. Intentionally omits the transient url and availability.
 */
/** @experimental */
export interface CanvasRecordedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: CanvasRecordedData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.canvas.recorded".
   */
  type: "session.canvas.recorded";
}
/**
 * Durable record that a canvas instance is open, used to restore open canvases on cold session resume. Intentionally omits the transient url and availability.
 */
/** @experimental */
export interface CanvasRecordedData {
  /**
   * Provider-local canvas identifier
   */
  canvasId: string;
  /**
   * Owning provider identifier
   */
  extensionId: string;
  /**
   * Input supplied when the instance was opened
   */
  input?: {
    [k: string]: unknown | undefined;
  };
  /**
   * Stable caller-supplied canvas instance identifier
   */
  instanceId: string;
  /**
   * Rendered title
   */
  title?: string;
}
/**
 * Session event "session.canvas.removed". Durable record that a canvas instance was closed, superseding a prior instance_recorded during resume replay.
 */
/** @experimental */
export interface CanvasRemovedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: CanvasRemovedData;
  /**
   * When true, the event is transient and not persisted to the session event log on disk
   */
  ephemeral?: boolean;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.canvas.removed".
   */
  type: "session.canvas.removed";
}
/**
 * Durable record that a canvas instance was closed, superseding a prior instance_recorded during resume replay.
 */
/** @experimental */
export interface CanvasRemovedData {
  /**
   * Provider-local canvas identifier
   */
  canvasId: string;
  /**
   * Owning provider identifier
   */
  extensionId: string;
  /**
   * Stable caller-supplied identifier of the canvas instance that was closed
   */
  instanceId: string;
}
/**
 * Session event "session.extensions.attachments_pushed". Payload of `session.extensions.attachments_pushed` with extension-contributed attachments for the next send.
 */
export interface ExtensionsAttachmentsPushedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ExtensionsAttachmentsPushedData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "session.extensions.attachments_pushed".
   */
  type: "session.extensions.attachments_pushed";
}
/**
 * Payload of `session.extensions.attachments_pushed` with extension-contributed attachments for the next send.
 */
export interface ExtensionsAttachmentsPushedData {
  /**
   * Attachments contributed by an extension; the host should surface these as composer pills and forward them via the next session.send call.
   */
  attachments: Attachment[];
}
/**
 * Session event "mcp_app.tool_call_complete". MCP App view called a tool on a connected MCP server (SEP-1865)
 */
export interface McpAppToolCallCompleteEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: McpAppToolCallCompleteData;
  /**
   * Always true for events that are transient and not persisted to the session event log on disk.
   */
  ephemeral: true;
  /**
   * Unique event identifier (UUID v4), generated when the event is emitted
   */
  id: string;
  /**
   * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
   */
  parentId: string | null;
  /**
   * ISO 8601 timestamp when the event was created
   */
  timestamp: string;
  /**
   * Type discriminator. Always "mcp_app.tool_call_complete".
   */
  type: "mcp_app.tool_call_complete";
}
/**
 * MCP App view called a tool on a connected MCP server (SEP-1865)
 */
export interface McpAppToolCallCompleteData {
  /**
   * Arguments passed to the tool by the app view, if any
   */
  arguments?: {
    [k: string]: unknown | undefined;
  };
  /**
   * Wall-clock duration of the underlying tools/call in milliseconds
   */
  durationMs: number;
  error?: McpAppToolCallCompleteError;
  /**
   * Standard MCP CallToolResult returned by the server. Present whether or not the call set isError.
   */
  result?: {
    [k: string]: unknown | undefined;
  };
  /**
   * Name of the MCP server hosting the tool
   */
  serverName: string;
  /**
   * True when the call completed without throwing AND the MCP CallToolResult did not set isError
   */
  success: boolean;
  toolMeta?: McpAppToolCallCompleteToolMeta;
  /**
   * MCP tool name that was invoked
   */
  toolName: string;
}
/**
 * Set when the underlying tools/call threw an error before returning a CallToolResult
 */
export interface McpAppToolCallCompleteError {
  /**
   * Human-readable error message
   */
  message: string;
}
/**
 * The tool's `_meta.ui` block at the time of the call, so consumers can decide whether to forward the result to the model without re-listing tools.
 */
export interface McpAppToolCallCompleteToolMeta {
  ui?: McpAppToolCallCompleteToolMetaUI;
}
/**
 * MCP App tool `_meta.ui` resource URI and SEP-1865 visibility captured with an `mcp_app.tool_call_complete` result.
 */
export interface McpAppToolCallCompleteToolMetaUI {
  /**
   * `ui://` URI declared by the tool's `_meta.ui.resourceUri`
   */
  resourceUri?: string;
  /**
   * Tool visibility per SEP-1865 (typically a subset of `["model","app"]`)
   */
  visibility?: string[];
}