session-events.ts

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

/** A value that can be represented losslessly on the SDK JSON wire. */
export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };

/**
 * 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
  | IndexedSearchEvent
  | WarningEvent
  | ModelChangeEvent
  | ModelDeselectedEvent
  | AutoTierRecommendationEvent
  | AutoTierSwitchFailedEvent
  | ModeChangedEvent
  | ModeNoticeDeliveredEvent
  | SessionLimitsChangedEvent
  | PermissionsChangedEvent
  | PlanChangedEvent
  | TodosChangedEvent
  | WorkspaceFileChangedEvent
  | HandoffEvent
  | TruncationEvent
  | SnapshotRewindEvent
  | ShutdownEvent
  | UsageCheckpointEvent
  | ContextChangedEvent
  | UsageInfoEvent
  | ContextClearedEvent
  | CompactionStartEvent
  | CompactionCompleteEvent
  | TaskCompleteEvent
  | CompletionReceiptEvent
  | FusionRouteStartedEvent
  | FusionRouteFailedEvent
  | FusionResolvedEvent
  | FusionCompletedEvent
  | PermissionRecoveryEvent
  | UserMessageEvent
  | PendingMessagesModifiedEvent
  | AssistantTurnStartEvent
  | AssistantIntentEvent
  | AssistantFusionPhaseStartedEvent
  | AssistantFusionPhaseActivityEvent
  | AssistantFusionPhaseCompletedEvent
  | AssistantFusionPhaseFailedEvent
  | AssistantServerToolProgressEvent
  | AssistantReasoningEvent
  | AssistantReasoningDeltaEvent
  | AssistantToolCallDeltaEvent
  | AssistantStreamingDeltaEvent
  | AssistantMessageEvent
  | AssistantMessageStartEvent
  | AssistantMessageDeltaEvent
  | AssistantTurnEndEvent
  | AssistantIdleEvent
  | AssistantUsageEvent
  | ModelCallFailureEvent
  | ModelCallFinishedEvent
  | AbortEvent
  | ToolUserRequestedEvent
  | ToolExecutionStartEvent
  | ToolExecutionPartialResultEvent
  | ToolExecutionProgressEvent
  | ToolExecutionCompleteEvent
  | ToolSearchActivatedEvent
  | SkillInvokedEvent
  | SubagentStartedEvent
  | SubagentConfiguredEvent
  | SubagentCompletedEvent
  | SubagentFailedEvent
  | SubagentSelectedEvent
  | SubagentDeselectedEvent
  | HookStartEvent
  | HookEndEvent
  | HookProgressEvent
  | BinaryAssetEvent
  | SystemMessageEvent
  | SystemNotificationEvent
  | PermissionRequestedEvent
  | PermissionCompletedEvent
  | PermissionCarriedForwardEvent
  | PermissionMessageAuthorizationEvent
  | PermissionMessageAuthorizationReadEvent
  | PermissionMessageAuthorizationDegradedEvent
  | PermissionAssentDetectedEvent
  | PermissionContextualAuthorizationEvent
  | UserInputRequestedEvent
  | UserInputCompletedEvent
  | ElicitationRequestedEvent
  | ElicitationCompletedEvent
  | SamplingRequestedEvent
  | SamplingCompletedEvent
  | McpOauthRequiredEvent
  | McpOauthCompletedEvent
  | McpHeadersRefreshRequiredEvent
  | McpHeadersRefreshCompletedEvent
  | CustomNotificationEvent
  | UIEphemeralQueryEvent
  | ExternalToolRequestedEvent
  | ExternalToolCompletedEvent
  | CommandQueuedEvent
  | CommandExecuteEvent
  | CommandCompletedEvent
  | AutoModeSwitchRequestedEvent
  | AutoModeSwitchCompletedEvent
  | SessionLimitsExhaustedRequestedEvent
  | SessionLimitsExhaustedCompletedEvent
  | AutoModeResolvedEvent
  | ManagedSettingsResolvedEvent
  | ManagedSettingsEnforcedEvent
  | CommandsChangedEvent
  | CapabilitiesChangedEvent
  | ExitPlanModeRequestedEvent
  | ExitPlanModeCompletedEvent
  | ToolsUpdatedEvent
  | BackgroundTasksChangedEvent
  | FactoryRunUpdatedEvent
  | FactoryRunStartedEvent
  | FactoryRunSettledEvent
  | SkillsLoadedEvent
  | CustomAgentsUpdatedEvent
  | McpServersLoadedEvent
  | McpServerStatusChangedEvent
  | McpServerRemovedEvent
  | McpServerNeedsReconnectEvent
  | McpToolsListChangedEvent
  | McpResourcesListChangedEvent
  | McpPromptsListChangedEvent
  | ExtensionsLoadedEvent
  | CanvasOpenedEvent
  | CanvasRegistryChangedEvent
  | CanvasClosedEvent
  | CanvasUnavailableEvent
  | CanvasRecordedEvent
  | CanvasRemovedEvent
  | ExtensionsAttachmentsPushedEvent
  | McpAppToolCallCompleteEvent;
/**
 * Routing preference used when the session model is `auto`. `fast` is an integrator-only latency preset and is not a first-party GitHub Copilot product preference.
 */
export type AutoTier =
  /** Optimize for efficiency. */
  | "efficiency"
  /** Balance efficiency and intelligence. */
  | "balance"
  /** Optimize for intelligence. */
  | "intelligence"
  /** Integrator-only preset that optimizes for latency. */
  | "fast";
/**
 * 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";
/**
 * What the user must do to recover from a failure, named as an action rather than as one client's affordance. The runtime cannot know which affordance a client offers — a slash command, a settings pane, a link — so the accompanying message stays host-agnostic and each client renders its own copy from this value. Absent when the runtime knows of no action the user can take.
 */
export type RemediationAction =
  /** Authenticate again with the Copilot backend. The current credential is absent, expired, or rejected. */
  | "sign_in"
  /** Authenticate as a different account. The current account exists but lacks access to the requested resource. */
  | "switch_account"
  /** Inspect which account is currently authenticated before deciding what to change. */
  | "show_account"
  /** Review or widen the sandbox policy. The blocked path or host is named by the accompanying message or by the tool result the action arrived with. */
  | "review_sandbox_policy"
  /** Permit outbound network access in the sandbox policy. */
  | "allow_sandbox_outbound";
/**
 * 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";
/**
 * Who created the schedule: `user` (an explicit user action such as `/every` or `/after`) or `model` (the agent via the `manage_schedule` tool). Gates whether a scheduled skill that opted out of model invocation may fire: only user-created schedules may.
 */
export type ScheduleOrigin =
  /** The schedule was created by an explicit user action, such as `/every` or `/after`. */
  | "user"
  /** The schedule was created by the agent via the `manage_schedule` tool. */
  | "model";
/**
 * 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";
/**
 * Transient indexed-search status and diagnostics from the live runtime service. Never persisted or used to infer activation from session history.
 */
export type IndexedSearchData =
  | {
      /**
       * Indexed-search event variant discriminator.
       */
      kind: "status";
      state: IndexedSearchState;
    }
  | {
      disabledReason?: IndexedSearchDisabledReason;
      /**
       * Whether the repository meets the automatic indexing file-count threshold, when known.
       */
      eligible?: boolean;
      /**
       * Startup failure details. May contain sensitive user data; restricted telemetry only.
       */
      errorMessage?: string;
      /**
       * Number of text files counted in the repository.
       */
      fileCount?: number;
      /**
       * Whether indexed search was explicitly enabled through the environment.
       */
      forcedByEnv: boolean;
      /**
       * Indexed-search event variant discriminator.
       */
      kind: "startup";
      outcome: IndexedSearchOutcome;
      /**
       * Wall-clock duration of startup in milliseconds.
       */
      startupDurationMs: number;
      /**
       * Whether waiting for index readiness was requested, including skipped attempts.
       */
      warmStart: boolean;
    }
  | {
      /**
       * Server failure details. May contain sensitive user data; restricted telemetry only.
       */
      errorMessage?: string;
      errorType: IndexedSearchErrorType;
      /**
       * Process exit code, when available.
       */
      exitCode?: number;
      /**
       * Indexed-search event variant discriminator.
       */
      kind: "server_error";
    }
  | {
      /**
       * Number of added files.
       */
      addedFileCount?: number;
      /**
       * Number of modified files.
       */
      changedFileCount?: number;
      /**
       * Number of deleted files.
       */
      deletedFileCount?: number;
      /**
       * Indexed-search event variant discriminator.
       */
      kind: "incremental";
      phase: IndexedSearchIncrementalPhase;
      /**
       * Total number of detected changes.
       */
      totalChangeCount?: number;
      /**
       * Total incremental indexing duration in milliseconds.
       */
      totalDurationMs?: number;
      /**
       * Index update duration in milliseconds.
       */
      updateDurationMs?: number;
      /**
       * Workspace scan duration in milliseconds.
       */
      walkDurationMs?: number;
    };
/**
 * Live indexed-search state for this session activation, never inferred from persisted history.
 */
export type IndexedSearchState =
  /** Indexed search is not active for this session. */
  | "disabled"
  /** Indexed-search startup is in progress. */
  | "starting"
  /** The indexed-search server started successfully; its index may still be warming. */
  | "enabled"
  /** The indexed-search server and its index are ready. */
  | "ready"
  /** Indexed-search startup or the active server failed. */
  | "failed";
/**
 * Configuration, policy, or workspace condition that disabled indexed search.
 */
export type IndexedSearchDisabledReason =
  /** Indexed search was explicitly disabled by the environment. */
  | "use_tgrep_false"
  /** Search uses the external ripgrep binary instead of bundled search. */
  | "use_builtin_ripgrep_false"
  /** Organization policy disables indexed search. */
  | "organization"
  /** Authentication has not resolved organization policy. */
  | "organization_policy_auth_pending"
  /** Organization policy could not be determined. */
  | "organization_policy_unknown"
  /** The workspace uses a virtualized or network filesystem. */
  | "virtual_filesystem"
  /** The workspace is inside a Windows cloud-sync root. */
  | "cloud_sync_root"
  /** The Windows cloud-sync safety check failed. */
  | "cloud_sync_detection_failed"
  /** The workspace is not available on the runtime's local filesystem. */
  | "workspace_not_local";
/**
 * Result of an indexed-search startup attempt.
 */
export type IndexedSearchOutcome =
  /** A new indexed-search server was started. */
  | "started"
  /** The repository has too few files for automatic indexing. */
  | "skipped_below_threshold"
  /** No Git repository was found and indexing was not forced. */
  | "skipped_no_gitroot"
  /** Configuration, policy, or workspace safety disabled indexing. */
  | "skipped_disabled"
  /** An existing indexed-search server was reused. */
  | "reused_existing"
  /** The startup attempt failed. */
  | "failed";
/**
 * Category of an indexed-search server failure.
 */
export type IndexedSearchErrorType =
  /** The indexed-search server could not be spawned. */
  | "spawn_error"
  /** The indexed-search server exited unexpectedly. */
  | "unexpected_exit"
  /** The indexed-search server was terminated by a signal. */
  | "killed_by_signal";
/**
 * Phase of an incremental indexed-search update.
 */
export type IndexedSearchIncrementalPhase =
  /** A workspace scan found changes to index. */
  | "changes_detected"
  /** The incremental index update completed. */
  | "updated";
/**
 * Origin of an effective session model change.
 */
export type ModelChangeSource =
  /** The user selected a model directly with `/model <id>`. */
  | "model_command"
  /** The user selected the model with `/settings`. */
  | "settings_command"
  /** The user selected the model with the `/config` alias. */
  | "config_command"
  /** The user selected the model in the model picker, including the picker opened by bare `/model`. */
  | "model_picker"
  /** Organization-managed settings selected the model. */
  | "managed_settings"
  /** Repository settings selected the model. */
  | "repo_settings"
  /** Startup model resolution selected the model. */
  | "startup"
  /** Selecting an agent selected its configured model. */
  | "agent"
  /** Entering, leaving, or reconfiguring plan mode selected the model. */
  | "plan_mode"
  /** The runtime selected the model automatically, such as rate-limit recovery or refusal fallback. */
  | "automatic"
  /** The user selected the promoted model from the changeboarding card or its keyboard shortcut. */
  | "changeboarding_shortcut"
  /** An SDK or RPC caller selected the model. */
  | "sdk";
/**
 * Why the session no longer has an explicitly selected model.
 */
export type ModelDeselectedReason =
  /** A host-managed provider snapshot no longer publishes the selected model. */
  "provider_withdrawn";
/**
 * Auto preferences that Copilot API can recommend.
 */
export type RecommendedAutoTier =
  /** Optimize for efficiency. */
  | "efficiency"
  /** Balance efficiency and intelligence. */
  | "balance"
  /** Optimize for intelligence. */
  | "intelligence";
/**
 * Terminal reason an Auto preference activation failed.
 */
export type AutoTierSwitchFailureReason =
  /** The candidate model was rejected by model policy. */
  | "policy_rejected"
  /** The Auto routing request failed or returned an unusable response. */
  | "request_failed"
  /** The runtime could not prepare the Auto routing request. */
  | "setup_failed"
  /** The provider does not support Auto routing. */
  | "unsupported";
/**
 * Permission mode for the session.
 */
/** @experimental */
export type PermissionMode =
  /** Permission requests follow the normal approval flow. */
  | "manual"
  /** Permission requests include an LLM safety recommendation; clients may automatically approve requests judged acceptable. */
  | "assisted"
  /** Tool, path, and URL permission requests are automatically approved. */
  | "allow-all";
/**
 * 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";
/**
 * What initiated a conversation compaction
 */
export type CompactionTrigger =
  /** Background compaction started automatically because context utilization crossed the background threshold. */
  | "threshold"
  /** Compaction forced by a context-limit model response (e.g. HTTP 413) before retrying the request. */
  | "context_limit_retry"
  /** User-requested compaction, e.g. the /compact command or the history.compact API. */
  | "manual"
  /** Emergency compaction triggered by high process memory usage. */
  | "memory_pressure"
  /** Compaction requested while switching to a model with a smaller context window. */
  | "model_switch";
/**
 * Category of structured task blocker
 */
export type TaskBlockerKind =
  /** Autopilot permission recovery requires intervention or has no safe autonomous path. */
  "permission_recovery";
/**
 * Runtime handling applied to a recovery attempt
 */
export type PermissionRecoveryAttemptDisposition =
  /** The request was denied without prompting so the agent could try an alternative. */
  | "deferred"
  /** The request was surfaced to an interactive responder. */
  | "prompted"
  /** The interactive responder approved the request. */
  | "approved"
  /** The interactive responder denied the request or became unavailable. */
  | "denied"
  /** The request exhausted unattended recovery and produced a blocked outcome. */
  | "blocked"
  /** A tool call succeeded as an equivalent alternative. */
  | "succeeded";
/**
 * Controlled reason for an individual attempt disposition
 */
export type PermissionRecoveryAttemptReason =
  /** The attempt required permission that Assisted Permissions could not grant. */
  | "permission_required"
  /** The request repeated an earlier attempt. */
  | "repeated_attempt"
  /** The request exceeded the bounded number of distinct attempts. */
  | "attempts_exhausted"
  /** The interactive responder approved the request. */
  | "permission_approved"
  /** The interactive responder denied the request. */
  | "permission_denied"
  /** The interactive responder became unavailable. */
  | "responder_unavailable"
  /** The tool call succeeded without the blocked permission. */
  | "equivalent_alternative_succeeded";
/**
 * Relationship of an attempt to earlier permission requests
 */
export type PermissionRecoveryAttemptRelation =
  /** The first denied permission request in the episode. */
  | "initial"
  /** A request equivalent to an earlier attempt. */
  | "retry"
  /** A distinct request or a successful alternative tool call. */
  | "alternative";
/**
 * Action selected when autonomous recovery cannot continue
 */
export type PermissionRecoveryOnBlocked =
  /** Surface the existing permission prompt to a response-capable client. */
  | "ask"
  /** Return a structured unsuccessful blocked outcome because no responder is available. */
  | "fail";
/**
 * Controlled reason for a permission-recovery episode transition
 */
export type PermissionRecoveryReason =
  /** An action required permission that Assisted Permissions could not grant. */
  | "permission_required"
  /** The agent repeated an equivalent permission request instead of making progress. */
  | "repeated_attempt"
  /** The bounded number of distinct permission attempts was exhausted. */
  | "attempts_exhausted"
  /** A responder approved the escalated permission request. */
  | "permission_approved"
  /** A responder denied the escalated permission request. */
  | "permission_denied"
  /** The response-capable client became unavailable while escalation was pending. */
  | "responder_unavailable"
  /** A later tool call succeeded without requiring the blocked permission. */
  | "equivalent_alternative_succeeded";
/**
 * Lifecycle state of a permission-recovery episode
 */
export type PermissionRecoveryStatus =
  /** Autopilot may try a bounded equivalent alternative. */
  | "recovering"
  /** An interactive permission response is required. */
  | "awaiting_approval"
  /** The episode ended through approval or a successful equivalent alternative. */
  | "resolved"
  /** No autonomous path remains and the task requires intervention. */
  | "blocked";
/**
 * Semantic result of evaluating a task completion request
 */
export type TaskCompletionOutcome =
  /** The completion request was accepted and the objective is complete. */
  | "completed"
  /** The completion request was rejected because more work or validation remains. */
  | "continue"
  /** Completion cannot proceed without intervention; the active objective is paused when one is identified. */
  | "blocked";
/**
 * Structured terminal status from a tool completion event.
 */
export type CompletionReceiptToolStatus =
  /** The tool completed successfully. */
  | "success"
  /** The tool failed without a more specific structured status. */
  | "failure"
  /** The tool exceeded its time budget. */
  | "timeout"
  /** The user rejected the tool call. */
  | "rejected"
  /** The permissions service denied the tool call. */
  | "denied";
/**
 * Runtime reason the completion decision was accepted.
 */
export type CompletionReceiptStopReason =
  /** The model reached a natural terminal response. */
  | "natural"
  /** A terminal tool ended the interaction. */
  | "terminal_tool"
  /** The configured agentStop continuation limit was reached. */
  | "agent_stop_block_limit";
/**
 * Kind of turn for which HydraFusion routing is running.
 */
/** @experimental */
export type FusionTurnKind =
  /** A user-message turn. */
  | "user"
  /** A conversation-compaction turn. */
  | "compaction";
/**
 * Server-recommended routing behavior for a later HydraFusion turn.
 */
/** @experimental */
export type FusionFollowUpAction =
  /** Reuse the durable primary model without routing. */
  | "reuse_primary"
  /** Request a new routing decision. */
  | "reroute";
/**
 * Validated HydraFusion execution pattern.
 */
/** @experimental */
export type FusionPattern =
  /** Run one primary solver phase. */
  | "single"
  /** Run a primary phase, a judge, and an optional repair. */
  | "cascade"
  /** Run a primary draft, a read-only critique, and a revision. */
  | "critique";
/**
 * HydraFusion phase kind.
 */
/** @experimental */
export type FusionPhaseKind =
  /** Primary solver phase. */
  | "primary"
  /** Read-only cascade judge phase. */
  | "judge"
  /** Cascade repair phase. */
  | "repair"
  /** Initial critique-pattern draft phase. */
  | "draft"
  /** Read-only critique phase. */
  | "critic"
  /** Critique-pattern revision phase. */
  | "revision"
  /** Follow-up phase continuing from the resolved model. */
  | "follow_up";
/**
 * Conversation scope in which a HydraFusion phase executes.
 */
/** @experimental */
export type FusionConversationScope =
  /** Canonical root conversation history. */
  | "root"
  /** Isolated read-only review history that does not enter the root conversation. */
  | "review";
/**
 * 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";
/**
 * Content-safe activity observed while a HydraFusion phase is running.
 */
/** @experimental */
export type FusionPhaseActivityKind =
  /** The provider produced additional private output bytes. */
  | "model_output"
  /** A tool began executing inside the phase. */
  | "tool_started"
  /** A tool finished executing inside the phase. */
  | "tool_completed";
/**
 * How a durable phase checkpoint contributes its exact message to canonical root history.
 */
/** @experimental */
/** @internal */
export type FusionProjectionMode =
  /** Append the exact root message immediately. */
  | "append"
  /** Hold a terminal message outside canonical history until the final commit selects it. */
  | "staged"
  /** Do not project the checkpoint into root history. */
  | "none";
/**
 * Durable outcome status of a HydraFusion phase.
 */
/** @experimental */
export type FusionPhaseStatus =
  /** The phase completed successfully. */
  | "succeeded"
  /** The phase failed. */
  | "failed"
  /** The phase was cancelled. */
  | "cancelled";
/**
 * 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;
/**
 * Hosted program caller type
 */
export type AssistantMessageToolRequestCallerType = "program";
/**
 * 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";
/**
 * Transport used for a successful model call
 */
export type AssistantUsageTransport =
  /** HTTP transport, including SSE streams. */
  | "http"
  /** WebSocket transport. */
  | "websocket";
/**
 * 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";
/**
 * Boundary that produced a model call failure
 */
export type ModelCallFailureKind =
  /** The provider returned an API error response. */
  | "api"
  /** The request transport failed before a usable API response completed. */
  | "transport";
/**
 * 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";
/**
 * Transport used for a failed model call
 */
export type ModelCallFailureTransport =
  /** HTTP transport, including SSE streams. */
  | "http"
  /** WebSocket transport. */
  | "websocket";
/**
 * Final outcome of one logical model dispatch after response acceptance processing
 */
export type ModelCallFinishedOutcome =
  /** The provider response was accepted for continued agent processing. */
  | "success"
  /** The dispatch ended with a provider or transport error. */
  | "error"
  /** The dispatch was cancelled before an accepted response was produced. */
  | "cancelled"
  /** The provider response was rejected during post-response acceptance processing. */
  | "rejected";
/**
 * 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"
  /** Autopilot stopped the run because the active objective reached its user-set --max-ai-credits limit. */
  | "autopilot_credit_limit";
/**
 * Configuration source: user, workspace, plugin, builtin, or managed
 */
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"
  /** Server supplied by a trusted host-managed catalog. */
  | "managed";
/**
 * 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";
/**
 * 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";
/**
 * Authority or runtime mechanism responsible for sub-agent model selection.
 */
export type SubagentModelSelectionSource =
  /** Explicit model supplied by the parent agent on the task call and selected for dispatch. */
  | "explicit_override"
  /** Required model policy configured for the sub-agent. */
  | "configured_required"
  /** Non-required model preference configured for the sub-agent. */
  | "configured_preference"
  /** Complementary-model default selected for the sub-agent. */
  | "complementary_default"
  /** Model inherited from the parent session. */
  | "session_inheritance"
  /** Default model declared by the agent definition. */
  | "agent_definition_default"
  /** Runtime policy, Auto mode, or an experiment selected the model. */
  | "runtime_policy";
/**
 * Where the model input for a task-tool sub-agent came from.
 */
export type SubagentTaskModelSource =
  /** The spawning agent supplied the task tool's model argument. */
  | "task_argument"
  /** The task omitted a model and the per-sub-agent settings entry supplied a concrete one. */
  | "subagent_configuration"
  /** The task omitted a model and the user-defined custom agent's definition supplied one. */
  | "custom_agent_definition"
  /** Neither the task call, the per-sub-agent settings entry, nor a custom agent definition supplied a model. */
  | "unset";
/**
 * 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
  | SystemNotificationFactoryCompleted
  | SystemNotificationUnclassified;
/**
 * Whether the agent completed successfully or failed
 */
export type SystemNotificationAgentCompletedStatus =
  /** The agent completed successfully. */
  | "completed"
  /** The agent failed. */
  | "failed";
/**
 * Durable metadata describing who initiated a factory pause.
 */
export type SystemNotificationFactoryPauseInfo =
  | {
      /**
       * Factory pause initiator discriminator.
       */
      type: "user";
    }
  | {
      /**
       * Stable author-defined checkpoint key that initiated the pause.
       */
      key: string;
      /**
       * Factory pause initiator discriminator.
       */
      type: "checkpoint";
    };
/**
 * Terminal status reached by a factory execution attempt.
 */
export type SystemNotificationFactoryCompletedStatus =
  /** The factory completed successfully. */
  | "completed"
  /** The factory was halted. */
  | "halted"
  /** The factory attempt paused intentionally. */
  | "paused"
  /** The factory was cancelled. */
  | "cancelled"
  /** The factory failed. */
  | "error";
/**
 * Details of the permission being requested
 */
export type PermissionRequest =
  | PermissionRequestShell
  | PermissionRequestWrite
  | PermissionRequestRead
  | PermissionRequestMcp
  | PermissionRequestUrl
  | PermissionRequestMemory
  | PermissionRequestCustomTool
  | PermissionRequestHook
  | PermissionRequestExtensionManagement
  | PermissionRequestFactory
  | PermissionRequestExtensionPermissionAccess
  | PermissionRequestExtensionEnvAccess;
/**
 * Advisory recommendation the runtime attaches to a permission request whose origin it can vouch for by construction. Unlike the auto-approval judge this does not depend on auto mode and does not evaluate what the tool call does; its absence simply means the runtime has no opinion and the request follows the host's normal approval flow.
 */
/** @experimental */
export type PermissionRecommendation =
  /** The runtime vouches for the request's origin and recommends approving it without prompting. The host still owns the decision and may deny it; deny rules, managed policy, and the auto-approval safety judge all outrank this recommendation. */
  "approve";
/**
 * Whether this is a store or vote memory operation
 */
export type PermissionRequestMemoryAction =
  /** Store a new memory. */
  | "store"
  /** Vote on an existing memory. */
  | "vote";
/**
 * Why the assisted-approval judge produced no usable recommendation. Present only alongside an `error` recommendation, where the human-readable reason is a fixed string and therefore cannot distinguish these cases. Intended to make a judge failure reportable by a consumer that has no access to the host's logs.
 */
/** @experimental */
export type AssistedApprovalJudgeFailureReason =
  /** The judge model call exceeded its deadline. */
  | "timeout"
  /** The judge model call was cancelled before it returned. */
  | "abort"
  /** The judge model call completed but returned no content. */
  | "empty_response"
  /** The judge model call failed (for example a transport, authentication, or rate-limit error). */
  | "model_error"
  /** The judge model replied, but the reply carried no ALLOW/DENY verdict. */
  | "parse_error";
/**
 * Outcome of the assisted-approval safety judge for a permission request. Present only in assisted mode; its absence means the judge did not evaluate the request.
 */
/** @experimental */
export type AssistedApprovalRecommendation =
  /** The judge evaluated the request and recommends automatically approving it. */
  | "approve"
  /** The judge evaluated the request and does not recommend automatically approving it; explicit approval is required. Whether that means prompting, denying, or something else is the consumer's decision. */
  | "requireApproval"
  /** Assisted mode is enabled, but this request category is never automatically 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";
/**
 * 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";
/**
 * Scope of a stored memory.
 */
export type PermissionRequestMemoryScope =
  /** Store the memory for the current repository. */
  | "repository"
  /** Store the memory for the current user. */
  | "user";
/**
 * Operation gated by a factory permission request.
 */
export type FactoryPermissionOperation =
  /** Running a registered factory, which spends subagents, active time, and AI credits under the approved limits. */
  | "run"
  /** Authoring a factory, which writes JavaScript into a session-scoped extension and loads it. */
  | "author";
/**
 * Derived user-facing permission prompt details for UI consumers
 */
export type PermissionPromptRequest =
  | PermissionPromptRequestCommands
  | PermissionPromptRequestWrite
  | PermissionPromptRequestRead
  | PermissionPromptRequestMcp
  | PermissionPromptRequestUrl
  | PermissionPromptRequestMemory
  | PermissionPromptRequestCustomTool
  | PermissionPromptRequestPath
  | PermissionPromptRequestHook
  | PermissionPromptRequestExtensionManagement
  | PermissionPromptRequestFactory
  | PermissionPromptRequestExtensionPermissionAccess
  | PermissionPromptRequestExtensionEnvAccess;
/**
 * 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";
/**
 * Controlled reason or actor responsible for a permission response.
 */
export type PermissionDecisionSource =
  /** The response followed the assisted-approval judge recommendation. */
  | "assisted_approval"
  /** A human supplied the response through an interactive prompt. */
  | "human_response"
  /** The host applied a standing policy or override rather than a judge recommendation or human decision. */
  | "host_policy"
  /** The host denied the request because no interactive user response was available. */
  | "unattended_fallback"
  /** A live authorization record from an earlier human decision in this session contained the proposal, so it ran without another prompt. This is not a new human decision and never mints authority of its own. */
  | "authorization_carry_forward";
/**
 * 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
  | UserToolSessionApprovalFactory
  | UserToolSessionApprovalExtensionPermissionAccess
  | UserToolSessionApprovalExtensionEnvAccess;
/**
 * Which direction a message-backed authorization claim moves authority in.
 */
/** @experimental */
export type PermissionMessageAuthorizationPolarity =
  /** The human's words authorized an effect. */
  | "grant"
  /** The human's words refused an effect. */
  | "denial";
/**
 * 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";
/**
 * Opaque JSON value submitted for one field in accepted `elicitation.completed` form content.
 */
export type ElicitationCompletedContent = JsonValue | undefined;
/**
 * 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"
  /** The host credential broker rejected or failed the refresh. */
  | "error"
  /** No response arrived within the bounded window. */
  | "timeout";
/**
 * Source-defined JSON payload for the custom notification
 */
export type CustomNotificationPayload = JsonValue;
/**
 * Lifecycle phase for a Rust-owned ephemeral query stream.
 */
/** @experimental */
export type UIEphemeralQueryPhase =
  /** The ephemeral query stream has begun. */
  | "started"
  /** A partial result chunk was produced by the stream. */
  | "chunk"
  /** The ephemeral query stream finished successfully. */
  | "completed"
  /** The ephemeral query stream ended with an error. */
  | "failed"
  /** The ephemeral query stream was cancelled before completing. */
  | "aborted";
/**
 * 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";
/**
 * Summary of which managed-settings channels contributed to the effective session policy. Use the per-channel booleans for exact provenance.
 */
export type ManagedSettingsResolvedSource =
  /** Only the server/account channel contributed. */
  | "server"
  /** Only the device MDM/plist/registry/file channel contributed. */
  | "device"
  /** Only session-local SDK-host injection contributed. */
  | "client"
  /** A policy helper registered by device or server policy contributed. Device registration takes priority when present. */
  | "policyHelper"
  /** More than one channel contributed. Ordinary keys resolve device over server over policy helper per key, while permissions compose restrictively across all present layers. */
  | "mixed"
  /** No managed policy is in force (no channel contributed). */
  | "none";
/**
 * The category of runtime action that enterprise managed settings governed (blocked or capped)
 */
export type ManagedSettingsEnforcedAction =
  /** An attempt to turn on a bypass-permissions ("yolo") escalation was refused or capped because policy disables bypass-permissions mode. */
  "bypass_permissions_blocked";
/**
 * For a `bypass_permissions_blocked` action, which permission-escalation primitive was refused
 */
export type ManagedSettingsEnforcedEscalation =
  /** Full allow-all permissions — automatically approving tools, paths, and URLs. */
  | "allow_all"
  /** Automatic approval of all tool permission requests. */
  | "approve_all"
  /** Assisted mode — keeps normal prompt paths and adds an LLM recommendation, distinct from allow-all. */
  | "assisted_approval"
  /** Unrestricted filesystem access outside the session's allowed directories. */
  | "unrestricted_paths"
  /** Unrestricted URL fetch access. */
  | "unrestricted_urls"
  /** A server-wide MCP "Always Allow" (or `--allow-tool <server>`) blanket that would auto-approve every tool from an MCP server. Capped to per-tool approval; each tool still prompts. */
  | "server_wide_mcp_approval";
/**
 * 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";
/**
 * Terminal status a factory run committed. A settled run is never `pending` or `running`, so those two members of the run-status domain are deliberately absent.
 */
export type FactoryRunSettledStatus =
  /** The factory body resolved and its result was committed. */
  | "completed"
  /** The run was stopped by a limit, an approval refusal or another policy decision. */
  | "halted"
  /** The attempt paused intentionally while preserving resumable run state. */
  | "paused"
  /** The run was cancelled by its caller or by session disposal. */
  | "cancelled"
  /** The run failed, with `failureType` carrying the class when it has one. */
  | "error";
/**
 * Source location type (e.g., project, personal-copilot, plugin, builtin, sdk)
 */
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"
  /** Pathless skill supplied lazily by an SDK skill provider. */
  | "sdk";
/**
 * Whether configured models are advisory preferences or required constraints
 */
export type AgentModelPolicy =
  /** Treat the authored models as advisory preferences that callers may override. */
  | "preferred"
  /** Require subagent execution to use one of the authored models. */
  | "required";
/**
 * Connection status: connected, failed, needs-auth, pending, disabled, stopped, 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 was intentionally stopped and can be restarted on demand when policy permits; a server quarantined by restrictive managed policy stays stopped and cannot be restarted until the policy allows it. */
  | "stopped"
  /** The server is not configured for this session. */
  | "not_configured";
/**
 * 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;
  autoTier?: AutoTier;
  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;
  githubMcpToolConfig?: GitHubMcpToolConfig;
  /**
   * 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;
  /**
   * Set on the immediate preliminary event of a working-directory change, before the git context is resolved. A settled follow-up event (enriched with git context, or cwd-only for a non-repository) is always emitted afterward, so observers may defer to it. Absent on standalone/final events (e.g. relay context changes).
   */
  pendingGitContext?: boolean;
  /**
   * 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;
}
/**
 * Per-session configuration for the built-in GitHub MCP server
 */
export interface GitHubMcpToolConfig {
  /**
   * Additional GitHub MCP tools requested by the session
   */
  additionalTools?: string[];
  /**
   * Additional GitHub MCP toolsets requested by the session
   */
  additionalToolsets?: string[];
  /**
   * Whether to use the read-write endpoint and request all toolsets
   */
  enableAllTools?: boolean;
  /**
   * Whether to request the GitHub MCP insiders build
   */
  enableInsidersMode?: boolean;
}
/**
 * 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;
  autoTier?: AutoTier;
  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 or omitted, pending work is normally marked as interrupted unless the resume passively joined live work owned by another client; sessionWasActive distinguishes that case.
   */
  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 passively joined a session that already had live work running in the runtime - an agent turn, a native queue run, a queued resume continuation, or an in-flight send (for example, an extension joining a session another client was actively driving). False (or omitted) when the session had no live work or when the resume explicitly abandoned pending work, including cold resumes and suspended sessions that remain resident in memory.
   */
  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;
  remediation?: RemediationAction;
  /**
   * 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;
  mode?: SessionMode;
}
/**
 * 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;
  origin?: ScheduleOrigin;
  /**
   * 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.indexed_search". Transient indexed-search status and diagnostics from the live runtime service. Never persisted or used to infer activation from session history.
 */
export interface IndexedSearchEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: IndexedSearchData;
  /**
   * 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.indexed_search".
   */
  type: "session.indexed_search";
}
/**
 * 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;
  remediation?: RemediationAction;
  /**
   * 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 {
  /**
   * Committed Auto preference after the model configuration change, when applicable.
   */
  autoTier?: AutoTier | null;
  /**
   * Reason the change happened, when not user-initiated. `"rate_limit_auto_switch"` for changes triggered by the auto-mode-switch rate-limit recovery path, or `"refusal_fallback"` when the active model declined a request (content refusal) and the runtime switched to the configured refusal-fallback model. 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;
  previousAutoTier?: AutoTier;
  /**
   * 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;
  source?: ModelChangeSource;
  verbosity?: Verbosity;
}
/**
 * Session event "session.model_deselected". The model the user had explicitly selected is no longer available, because the host that published it withdrew it, so the session no longer has an explicit selection. The next turn resolves a default as though the user had never chosen a model. Clients should stop presenting the previous model as selected. This event is durable because resume rebuilds the selected model from the event log; without it a resumed session would restore a model its provider no longer serves. Reasoning effort, verbosity, and other session-level preferences are deliberately unchanged, because they belong to the session rather than to the model.
 */
export interface ModelDeselectedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ModelDeselectedData;
  /**
   * 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_deselected".
   */
  type: "session.model_deselected";
}
/**
 * The model the user had explicitly selected is no longer available, because the host that published it withdrew it, so the session no longer has an explicit selection. The next turn resolves a default as though the user had never chosen a model. Clients should stop presenting the previous model as selected. This event is durable because resume rebuilds the selected model from the event log; without it a resumed session would restore a model its provider no longer serves. Reasoning effort, verbosity, and other session-level preferences are deliberately unchanged, because they belong to the session rather than to the model.
 */
export interface ModelDeselectedData {
  /**
   * Model that was selected before the host withdrew it.
   */
  previousModel: string;
  reason: ModelDeselectedReason;
}
/**
 * Session event "session.auto_tier_recommendation". Live-only Auto preference recommendation from Copilot API after a successful Auto model call.
 */
/** @experimental */
export interface AutoTierRecommendationEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: AutoTierRecommendationData;
  /**
   * 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.auto_tier_recommendation".
   */
  type: "session.auto_tier_recommendation";
}
/**
 * Live-only Auto preference recommendation from Copilot API after a successful Auto model call.
 */
/** @experimental */
export interface AutoTierRecommendationData {
  recommendedAutoTier: RecommendedAutoTier;
}
/**
 * Session event "session.auto_tier_switch_failed". A transient Auto preference failure emitted when the runtime cannot mint or accept a usable model and token pair. The previously effective preference remains active, so SDK clients can surface a non-blocking failure without changing their committed-tier state. This event is ephemeral and is not persisted or replayed on resume.
 */
export interface AutoTierSwitchFailedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: AutoTierSwitchFailedData;
  /**
   * 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.auto_tier_switch_failed".
   */
  type: "session.auto_tier_switch_failed";
}
/**
 * A transient Auto preference failure emitted when the runtime cannot mint or accept a usable model and token pair. The previously effective preference remains active, so SDK clients can surface a non-blocking failure without changing their committed-tier state. This event is ephemeral and is not persisted or replayed on resume.
 */
export interface AutoTierSwitchFailedData {
  effectiveAutoTier?: AutoTier;
  reason: AutoTierSwitchFailureReason;
  /**
   * Auto preference that failed to activate, or null when returning to provider-default routing failed.
   */
  requestedAutoTier: AutoTier | null;
}
/**
 * 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.mode_notice_delivered". Records that a mode transition notice reached the model so cache-stable mode tools can remain offered across resume.
 */
export interface ModeNoticeDeliveredEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ModeNoticeDeliveredData;
  /**
   * 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_notice_delivered".
   */
  type: "session.mode_notice_delivered";
}
/**
 * Records that a mode transition notice reached the model so cache-stable mode tools can remain offered across resume.
 */
export interface ModeNoticeDeliveredData {
  /**
   * Model-visible transition notice persisted for a mid-turn delivery
   */
  content?: string;
  mode: 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". Permission-mode transition details.
 */
/** @experimental */
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";
}
/**
 * Permission-mode transition details.
 */
/** @experimental */
export interface PermissionsChangedData {
  /**
   * Explicit LLM judge model override used by assisted mode; omitted when the provider default applies
   *
   * @experimental
   */
  assistedApprovalModel?: string;
  /**
   * Permission mode after the change
   *
   * @experimental
   */
  mode?: PermissionMode;
  /**
   * Permission mode before the change
   *
   * @experimental
   */
  previousMode?: PermissionMode;
}
/**
 * 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 {
  /**
   * Per-agent usage breakdown, keyed by agent instance identifier. The main conversation uses the stable key `main`.
   */
  agentMetrics?: {
    [k: string]: ShutdownAgentMetric | undefined;
  };
  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;
}
/**
 * Usage attributed to one agent instance at session shutdown.
 */
export interface ShutdownAgentMetric {
  /**
   * Human-readable label for this subagent invocation, copied from the originating `subagent.started` event. For task-tool subagents this is the invocation's task description rather than the agent's configured display name, so group by `agentName` for stable per-agent labels.
   */
  agentDisplayName?: string;
  /**
   * Configured agent name, when this is a subagent
   */
  agentName?: string;
  /**
   * Per-model usage for this agent, keyed by model identifier
   */
  modelMetrics: {
    [k: string]: ShutdownModelMetric | undefined;
  };
  /**
   * Time spent in model API calls by this agent, in milliseconds
   */
  totalApiDurationMs: number;
  /**
   * Accumulated nano-AI units cost for this agent
   */
  totalNanoAiu: 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;
}
/**
 * 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;
}
/**
 * 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 {
  /**
   * Internal per-model prompt-cache state used to restore expiration tracking on resume
   *
   * @internal
   */
  modelCacheState?: UsageCheckpointModelCacheState[];
  /**
   * Internal per-conversation prompt-cache-break detector baselines restored on resume
   *
   * @internal
   */
  promptCacheBreakState?: JsonValue[];
  /**
   * 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;
}
/**
 * Internal prompt-cache expiration state for one model
 */
/** @internal */
export interface UsageCheckpointModelCacheState {
  /**
   * Latest known prompt-cache expiration
   */
  cacheExpiresAt: string;
  /**
   * Retained cache lifetime in seconds, used to refresh expiration after a cache read
   *
   * @internal
   */
  cacheTtlSeconds: number;
  /**
   * Model identifier associated with this cache state
   */
  modelId: string;
}
/**
 * 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.context_cleared". Context-cleared details emitted when the host clears the conversation (the session.history.clearContext RPC / Session.clearContextMessages)
 */
export interface ContextClearedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ContextClearedData;
  /**
   * 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_cleared".
   */
  type: "session.context_cleared";
}
/**
 * Context-cleared details emitted when the host clears the conversation (the session.history.clearContext RPC / Session.clearContextMessages)
 */
export interface ContextClearedData {
  /**
   * Optional initial message set after clearing
   */
  initialMessage?: string;
  /**
   * Number of conversation messages that were cleared
   */
  messagesCleared: 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;
  /**
   * Total context tokens (system + conversation + tool definitions) at compaction start, when known
   */
  currentTokens?: number;
  /**
   * Model identifier used for compaction, when known
   */
  model?: string;
  /**
   * Token count from system message(s) at compaction start
   */
  systemTokens?: number;
  /**
   * Model context window token limit the compaction is targeting, when known
   */
  tokenLimit?: number;
  /**
   * Token count from tool definitions at compaction start
   */
  toolDefinitionsTokens?: number;
  trigger?: CompactionTrigger;
}
/**
 * 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 {
  /**
   * Authoritative active-factory reminder appended to the compacted context
   *
   * @internal
   */
  activeFactorySummary?: string;
  /**
   * Canonical model identifier used for model-specific behavior when replaying compaction
   */
  behaviorModelId?: string;
  /**
   * 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;
  responsesReasoning?: ResponsesReasoning;
  /**
   * 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;
  /**
   * Model context window token limit the compaction was targeting, when known
   */
  tokenLimit?: number;
  /**
   * Number of tokens removed during compaction
   */
  tokensRemoved?: number;
  /**
   * Token count from tool definitions after compaction
   */
  toolDefinitionsTokens?: number;
  trigger?: CompactionTrigger;
}
/**
 * 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 {
  /**
   * Default billing model for token details that do not identify their own model
   *
   * @internal
   */
  model?: string;
  /**
   * 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;
  /**
   * Model responsible for this billing entry
   */
  model?: string;
  /**
   * Total token count for this entry
   */
  tokenCount: number;
  /**
   * Token category (e.g., "input", "output")
   */
  tokenType: string;
}
/**
 * Original request-level and effective conversation reasoning effort for a Responses history boundary
 */
export interface ResponsesReasoning {
  /**
   * Effective effort selected before this message, independent of the response-level reasoning field
   */
  effort: string;
  /**
   * Original request-level effort, retained while replaying this conversation prefix
   */
  initialEffort: string;
  /**
   * Provider model whose reasoning settings this boundary records
   */
  model: 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 {
  blocker?: TaskBlocker;
  /**
   * Active autopilot objective ID evaluated by the completion reviewer
   */
  objectiveId?: number;
  outcome?: TaskCompletionOutcome;
  /**
   * Label-safe runtime rationale for the completion decision (e.g. a cancellation or pause/resume downgrade), when one applies. Reviewer-authored rationale is intentionally omitted here because this event has no IFC label channel; the reviewer's findings remain available through its own labeled sub-agent events
   */
  reason?: string;
  /**
   * Whether the task was accepted as complete. False when validation failed or completion was rejected or blocked by the reviewer
   */
  success?: boolean;
  /**
   * Summary of the completed task, provided by the agent
   */
  summary?: string;
}
/**
 * Structured reason that the task cannot continue without intervention
 */
/** @experimental */
export interface TaskBlocker {
  kind: TaskBlockerKind;
  permissionRecovery: PermissionRecoveryData;
  reason: PermissionRecoveryReason;
  /**
   * Whether a later user response or steering message can resume the task
   */
  resumable: boolean;
}
/**
 * Authoritative snapshot of an Autopilot permission-recovery episode
 */
export interface PermissionRecoveryData {
  /**
   * Ordered privacy-safe record of permission attempts and the successful alternative, when any
   */
  attempts: PermissionRecoveryAttempt[];
  /**
   * Stable identifier shared by every transition in this recovery episode
   */
  episodeId: string;
  /**
   * Maximum number of distinct autonomous permission attempts allowed before escalation
   */
  maxAttempts: number;
  onBlocked: PermissionRecoveryOnBlocked;
  reason: PermissionRecoveryReason;
  status: PermissionRecoveryStatus;
}
export interface PermissionRecoveryAttempt {
  /**
   * Unique identifier for this attempt record
   */
  attemptId: string;
  disposition: PermissionRecoveryAttemptDisposition;
  /**
   * One-based position of this attempt in the episode
   */
  ordinal: number;
  /**
   * Controlled permission request kind, such as shell, path, URL, or tool
   */
  permissionKind: string;
  reason: PermissionRecoveryAttemptReason;
  relation: PermissionRecoveryAttemptRelation;
  /**
   * SHA-256 fingerprint of normalized request data; raw permission arguments are not included
   */
  requestFingerprint: string;
  /**
   * Tool-call identifier associated with this attempt, when available
   */
  toolCallId?: string;
}
/**
 * Session event "session.completion_receipt". Behavior-neutral record of structured runtime facts present when an agent completion decision is accepted.
 */
/** @experimental */
export interface CompletionReceiptEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: CompletionReceiptData;
  /**
   * 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.completion_receipt".
   */
  type: "session.completion_receipt";
}
/**
 * Behavior-neutral record of structured runtime facts present when an agent completion decision is accepted.
 */
/** @experimental */
export interface CompletionReceiptData {
  /**
   * One-based accepted completion receipt ordinal in the durable session history.
   */
  attempt: number;
  eventRange: CompletionReceiptEventRange;
  /**
   * Number of failed structured tool completions in the covered range.
   */
  failedToolCount: number;
  finalTool?: CompletionReceiptFinalTool;
  /**
   * Version of the completion receipt payload.
   */
  schemaVersion: number;
  /**
   * Identifier of the assistant turn-end event that supplied the accepted completion boundary. This is the receipt's idempotency key, and always equals eventRange.endEventId.
   */
  sourceEventId: string;
  stopReason: CompletionReceiptStopReason;
  /**
   * Number of successful structured tool completions in the covered range.
   */
  successfulToolCount: number;
}
/**
 * Inclusive durable event range summarized by a completion receipt.
 */
export interface CompletionReceiptEventRange {
  /**
   * Identifier of the assistant turn-end event that ends the covered exchange. Always equals the receipt's sourceEventId, so either field is a valid join key.
   */
  endEventId: string;
  /**
   * Identifier of the user message that starts the covered exchange.
   */
  startEventId: string;
}
/**
 * Final structured tool completion in the covered event range.
 */
export interface CompletionReceiptFinalTool {
  /**
   * Process exit code from a structured shell result, when available.
   */
  exitCode?: number;
  status: CompletionReceiptToolStatus;
  /**
   * Unique identifier of the completed tool call.
   */
  toolCallId: string;
  /**
   * Tool name from the matching tool execution start event, when available.
   */
  toolName?: string;
}
/**
 * Session event "session.fusion_route_started". Experimental transient signal that HydraFusion routing has started for an eligible turn.
 */
/** @experimental */
export interface FusionRouteStartedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: FusionRouteStartedData;
  /**
   * 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.fusion_route_started".
   */
  type: "session.fusion_route_started";
}
/**
 * Experimental transient signal that HydraFusion routing has started for an eligible turn.
 */
/** @experimental */
export interface FusionRouteStartedData {
  /**
   * Identifier for this routing attempt before a durable Fusion turn exists.
   */
  attemptId: string;
  /**
   * HydraFusion routing policy requested for the turn.
   */
  policy?: string;
  /**
   * Synthetic HydraFusion model selected for the session.
   */
  syntheticModel?: string;
  turnKind: FusionTurnKind;
}
/**
 * Session event "session.fusion_route_failed". Experimental durable HydraFusion routing failure and the deterministic concrete fallback selected for the turn.
 */
/** @experimental */
export interface FusionRouteFailedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: FusionRouteFailedData;
  /**
   * 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.fusion_route_failed".
   */
  type: "session.fusion_route_failed";
}
/**
 * Experimental durable HydraFusion routing failure and the deterministic concrete fallback selected for the turn.
 */
/** @experimental */
export interface FusionRouteFailedData {
  /**
   * Identifier of the routing attempt that failed.
   */
  attemptId: string;
  /**
   * Provider or validation error detail, when available.
   */
  errorMessage?: string;
  /**
   * Concrete model selected as the deterministic fallback.
   */
  fallbackModel: string;
  /**
   * HydraFusion routing policy requested for the turn.
   */
  policy: string;
  /**
   * Stable machine-readable reason for the routing failure.
   */
  reason: string;
  /**
   * Elapsed routing time in milliseconds before the failure.
   */
  routingLatencyMs?: number;
  /**
   * Synthetic HydraFusion model selected for the session.
   */
  syntheticModel: string;
}
/**
 * Session event "session.fusion_resolved". Experimental durable validated HydraFusion route and turn policy.
 */
/** @experimental */
export interface FusionResolvedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: FusionResolvedData;
  /**
   * 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.fusion_resolved".
   */
  type: "session.fusion_resolved";
}
/**
 * Experimental durable validated HydraFusion route and turn policy.
 */
/** @experimental */
export interface FusionResolvedData {
  /**
   * Version of the validated HydraFusion event contract.
   */
  contractVersion: number;
  /**
   * Concrete model used when the planned primary model cannot execute.
   */
  fallbackModel: string;
  followUp?: FusionFollowUpRecommendation;
  /**
   * Concrete model recommended for eligible follow-up turns.
   */
  followUpModel: string;
  /**
   * Stable identifier for the resolved HydraFusion turn.
   */
  fusionId: string;
  /**
   * Version of the executable model universe used for selection.
   */
  modelUniverseVersion?: string;
  pattern: FusionPattern;
  /**
   * Presentation-neutral phase plan for clients that render workflow progress.
   *
   * @experimental
   */
  phasePlan?: FusionPhasePlanStep[];
  /**
   * Version of the validated execution-plan format.
   */
  planVersion?: string;
  /**
   * HydraFusion routing policy used to resolve the plan.
   */
  policy: string;
  /**
   * Version of the local routing policy.
   */
  policyVersion?: string;
  /**
   * Concrete model selected for the primary solver phase.
   */
  primaryModel: string;
  /**
   * Router implementation that supplied the plan.
   */
  routeSource?: string;
  /**
   * Elapsed time in milliseconds required to resolve and validate the route.
   */
  routingLatencyMs?: number;
  /**
   * Identifier of the local policy rule that matched.
   */
  ruleId?: string;
  /**
   * Zero-based index of the local policy rule that matched.
   */
  ruleIndex?: number;
  /**
   * Human-readable name of the local policy rule that matched.
   */
  ruleName?: string;
  scores?: FusionScores;
  /**
   * Concrete model selected for the review or judge phase, when required.
   */
  secondaryModel: string | null;
  /**
   * Synthetic HydraFusion model selected for the session.
   */
  syntheticModel: string;
  /**
   * Identifier of the session turn associated with the route.
   */
  turnId: string;
}
/**
 * Durable server recommendation for subsequent HydraFusion turns.
 */
/** @experimental */
export interface FusionFollowUpRecommendation {
  compactionTurn: FusionFollowUpAction;
  userTurn: FusionFollowUpAction;
}
/**
 * Presentation-neutral phase planned for a HydraFusion turn.
 */
/** @experimental */
export interface FusionPhasePlanStep {
  /**
   * Whether the phase executes only when an earlier phase requests it.
   */
  conditional: boolean;
  kind: FusionPhaseKind;
  /**
   * Semantic role assigned to the phase.
   */
  role: string;
  scope: FusionConversationScope;
}
/**
 * Validated HydraFusion routing capability scores.
 */
/** @experimental */
export interface FusionScores {
  /**
   * Code-generation capability score returned by the authenticated router.
   */
  codeGen: number;
  /**
   * Debugging capability score returned by the authenticated router.
   */
  debugging: number;
  /**
   * Reasoning capability score returned by the authenticated router.
   */
  reasoning: number;
  /**
   * Tool-use capability score returned by the authenticated router.
   */
  toolUse: number;
}
/**
 * Session event "session.fusion_completed". Experimental durable aggregate outcome of a HydraFusion turn.
 */
/** @experimental */
export interface FusionCompletedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: FusionCompletedData;
  /**
   * 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.fusion_completed".
   */
  type: "session.fusion_completed";
}
/**
 * Experimental durable aggregate outcome of a HydraFusion turn.
 */
/** @experimental */
export interface FusionCompletedData {
  /**
   * Total cached input tokens reported across all phases.
   */
  cachedTokens: number;
  /**
   * Total tokens written to prompt cache across all phases.
   */
  cacheWriteTokens?: number;
  /**
   * Idempotency identifier for the authoritative final commit.
   */
  commitId: string;
  /**
   * Reason the turn used a degraded route, when applicable.
   */
  degradedReason: string | null;
  /**
   * Total elapsed execution time for the HydraFusion turn in milliseconds.
   */
  durationMs: number;
  /**
   * Concrete model that supplied the authoritative final content.
   */
  finalSourceModel: string | null;
  /**
   * Phase whose output supplied the authoritative final content.
   */
  finalSourcePhaseId: string | null;
  /**
   * Concrete model recommended for eligible follow-up turns.
   */
  followUpModel: string;
  /**
   * Stable identifier for the completed HydraFusion turn.
   */
  fusionId: string;
  /**
   * Total input tokens consumed across all phases.
   */
  inputTokens: number;
  /**
   * Stable aggregate outcome of the HydraFusion turn.
   */
  outcome: string;
  /**
   * Total output tokens produced across all phases.
   */
  outputTokens: number;
  pattern: FusionPattern;
  /**
   * Number of concrete phases attempted by the turn.
   */
  phaseCount: number;
  /**
   * Total concrete model requests made across all phases.
   */
  requestCount: number;
  /**
   * Synthetic HydraFusion model selected for the session.
   */
  syntheticModel: string;
  /**
   * Total normalized AI-unit cost reported across all phases, in nano-AIU.
   */
  totalNanoAiu: number;
  /**
   * Identifier of the session turn associated with the completion.
   */
  turnId: string;
}
/**
 * Session event "session.permission_recovery". Authoritative snapshot of an Autopilot permission-recovery episode
 */
export interface PermissionRecoveryEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: PermissionRecoveryData;
  /**
   * 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.permission_recovery".
   */
  type: "session.permission_recovery";
}
/**
 * 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;
  /**
   * Stable identity of the logical user message, matching the ID returned by send and retained by pending queue snapshots
   */
  messageId?: string;
  /**
   * 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;
  responsesReasoning?: ResponsesReasoning;
  /**
   * Origin of this message, used for timeline filtering and attribution (e.g., `skill-pdf` for hidden skill injection or `agent-<agent-id>` for an inter-agent prompt)
   */
  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;
  /**
   * The agent-loop turn ID that consumed this message; absent when no agent-loop turn consumed it
   */
  turnId?: 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?: JsonValue;
  /**
   * 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.fusion_phase_started". Experimental transient HydraFusion phase/model/role signal.
 */
/** @experimental */
export interface AssistantFusionPhaseStartedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: FusionPhaseStartedData;
  /**
   * 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.fusion_phase_started".
   */
  type: "assistant.fusion_phase_started";
}
/**
 * Experimental transient HydraFusion phase/model/role signal.
 */
/** @experimental */
export interface FusionPhaseStartedData {
  conversationScope: FusionConversationScope;
  /**
   * Identifier of the HydraFusion turn containing the phase.
   */
  fusionId: string;
  /**
   * Concrete model executing the phase.
   */
  model: string;
  pattern: FusionPattern;
  /**
   * Stable identifier for the concrete phase.
   */
  phaseId: string;
  phaseKind: FusionPhaseKind;
  /**
   * Semantic role assigned to the phase.
   */
  role: string;
}
/**
 * Session event "assistant.fusion_phase_activity". Experimental content-safe activity signal for a running HydraFusion phase.
 */
/** @experimental */
export interface AssistantFusionPhaseActivityEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: FusionPhaseActivityData;
  /**
   * 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.fusion_phase_activity".
   */
  type: "assistant.fusion_phase_activity";
}
/**
 * Experimental content-safe activity signal for a running HydraFusion phase.
 */
/** @experimental */
export interface FusionPhaseActivityData {
  activity: FusionPhaseActivityKind;
  conversationScope: FusionConversationScope;
  /**
   * Identifier of the HydraFusion turn containing the phase.
   */
  fusionId: string;
  pattern: FusionPattern;
  /**
   * Stable identifier for the concrete phase.
   */
  phaseId: string;
  phaseKind: FusionPhaseKind;
  /**
   * Semantic role assigned to the phase.
   */
  role: string;
  /**
   * Opaque hashed correlation token for matching tool-started and tool-completed activity within this Fusion activity stream. It is not the tool call identifier exposed by tool lifecycle events.
   */
  toolCallId?: string;
  /**
   * Cumulative private response bytes observed for this model call. The event never includes response text.
   */
  totalResponseSizeBytes?: number;
}
/**
 * Session event "assistant.fusion_phase_completed". Experimental durable HydraFusion phase output and lossless replay checkpoint.
 */
/** @experimental */
export interface AssistantFusionPhaseCompletedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: FusionPhaseCompletedData;
  /**
   * 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.fusion_phase_completed".
   */
  type: "assistant.fusion_phase_completed";
}
/**
 * Experimental durable HydraFusion phase output and lossless replay checkpoint.
 */
/** @experimental */
export interface FusionPhaseCompletedData {
  /**
   * Provider-normalized textual output produced by the phase.
   */
  content: string;
  conversationScope: FusionConversationScope;
  /**
   * Elapsed execution time for the phase in milliseconds.
   */
  durationMs: number;
  /**
   * Identifier of the HydraFusion turn containing the phase.
   */
  fusionId: string;
  /**
   * Concrete model that executed the phase.
   */
  model: string;
  /**
   * Stable identifier for the completed phase.
   */
  phaseId: string;
  phaseKind: FusionPhaseKind;
  /**
   * Exact provider-normalized message used to reconstruct canonical model history.
   *
   * @internal
   */
  projectionMessage?: JsonValue;
  /**
   * Projection action for the exact internal message.
   *
   * @internal
   */
  projectionMode?: FusionProjectionMode;
  /**
   * Semantic role assigned to the completed phase.
   */
  role: string;
  /**
   * Terminal request held outside canonical state until selected by the final commit.
   *
   * @internal
   */
  stagedTerminal?: FusionStagedTerminal;
  status: FusionPhaseStatus;
  usage: FusionPhaseUsage;
  /**
   * Structured judge or critic verdict, when the phase produces one.
   */
  verdict: string | null;
}
/**
 * Internal durable terminal request staged by a HydraFusion phase until an idempotent final commit selects it.
 */
/** @experimental */
/** @internal */
export interface FusionStagedTerminal {
  arguments: string;
  assistantMessage: JsonValue;
  phaseId: string;
  toolCallId: string;
  toolName: string;
}
/**
 * Aggregate concrete-model usage for one HydraFusion phase.
 */
/** @experimental */
export interface FusionPhaseUsage {
  /**
   * Total cached input tokens reported for the phase.
   */
  cachedTokens: number;
  /**
   * Total tokens written to prompt cache during the phase.
   */
  cacheWriteTokens?: number;
  /**
   * Total input tokens consumed by the phase.
   */
  inputTokens: number;
  /**
   * Total output tokens produced by the phase.
   */
  outputTokens: number;
  /**
   * Number of concrete model requests made by the phase.
   */
  requestCount: number;
  /**
   * Total normalized AI-unit cost reported for the phase, in nano-AIU.
   */
  totalNanoAiu: number;
}
/**
 * Session event "assistant.fusion_phase_failed". Experimental durable typed HydraFusion phase failure and degradation transition.
 */
/** @experimental */
export interface AssistantFusionPhaseFailedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: FusionPhaseFailedData;
  /**
   * 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.fusion_phase_failed".
   */
  type: "assistant.fusion_phase_failed";
}
/**
 * Experimental durable typed HydraFusion phase failure and degradation transition.
 */
/** @experimental */
export interface FusionPhaseFailedData {
  conversationScope: FusionConversationScope;
  /**
   * Identifier of the fallback phase used to continue the turn after degradation.
   */
  degradedToPhaseId?: string;
  /**
   * Elapsed execution time before the phase failed, in milliseconds.
   */
  durationMs: number;
  /**
   * Provider or execution error detail, when available.
   */
  errorMessage?: string;
  /**
   * Identifier of the HydraFusion turn containing the phase.
   */
  fusionId: string;
  /**
   * Concrete model that attempted the phase.
   */
  model: string;
  /**
   * Stable identifier for the failed phase.
   */
  phaseId: string;
  phaseKind: FusionPhaseKind;
  /**
   * Stable machine-readable reason for the phase failure.
   */
  reason: string;
  /**
   * Semantic role assigned to the failed phase.
   */
  role: string;
  status: FusionPhaseStatus;
  usage: FusionPhaseUsage;
}
/**
 * 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;
  /**
   * Per-request treatment/eligibility signal returned by the Copilot API in the `X-GitHub-Copilot-Request-TE` response header for the associated model call; `false` when the header was absent or unparseable.
   */
  rte?: boolean;
}
/**
 * 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;
  /**
   * Total messages the model call's response was split into, one per reasoning boundary. Absent for a single-message response; the last chunk is the one where chunkIndex is chunkCount - 1.
   */
  chunkCount?: number;
  /**
   * Zero-based position of this message within its model call's response. Absent when the response was not split into chunks.
   */
  chunkIndex?: number;
  /**
   * 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;
  /**
   * Experimental HydraFusion source attribution for this ordinary authoritative assistant message.
   *
   * @experimental
   */
  fusion?: FusionAttribution;
  /**
   * 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;
  /**
   * Logical ID of the primary user message that initiated this run, matching the messageId returned by session.send (or the last messageId of session.sendMessages). Stable across model/tool iterations, steering messages, and stop-hook corrections. Subagent runs use their own initiating message ID, not the parent's. Absent for runs without an associated initiating message, such as empty batches.
   */
  originatingMessageId?: 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;
  reasoningBlocks?: AssistantMessageReasoningBlocks;
  /**
   * 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;
  /**
   * Per-request treatment/eligibility signal returned by the Copilot API in the `X-GitHub-Copilot-Request-TE` response header for the associated model call; `false` when the header was absent or unparseable.
   */
  rte?: boolean;
  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?: JsonValue;
  /**
   * 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";
}
/**
 * Experimental attribution linking an ordinary event to the HydraFusion turn, phase, and concrete source that produced it.
 */
/** @experimental */
export interface FusionAttribution {
  /**
   * Idempotency identifier for the authoritative commit, when the event belongs to the selected output.
   */
  commitId?: string;
  /**
   * Conversation scope in which the concrete phase executed.
   */
  conversationScope?: string;
  /**
   * Stable identifier for the HydraFusion turn that produced the event.
   */
  fusionId: string;
  /**
   * HydraFusion orchestration pattern selected for the turn.
   */
  pattern: string;
  /**
   * Identifier of the concrete phase that produced the event.
   */
  phaseId?: string;
  /**
   * Kind of concrete phase that produced the event.
   */
  phaseKind?: string;
  /**
   * HydraFusion routing policy used for the turn.
   */
  policy: string;
  /**
   * Semantic role assigned to the concrete phase.
   */
  role?: string;
  /**
   * Concrete model that produced the attributed event.
   */
  sourceModel?: string;
  /**
   * Phase whose output supplied the authoritative content, when different from the executing phase.
   */
  sourcePhaseId?: string;
  /**
   * Synthetic HydraFusion model selected for the session.
   */
  syntheticModel: string;
}
/**
 * Neutral provider-tagged reasoning content blocks preserved verbatim for round-tripping
 */
/** @experimental */
export interface AssistantMessageReasoningBlocks {
  /**
   * Provider-native reasoning items or content blocks preserved verbatim, in order. A single response can carry several, and provider signatures or identifiers may depend on their exact content and ordering.
   */
  blocks?: JsonValue[];
  /**
   * Model provider that produced these reasoning blocks.
   */
  provider: string;
}
/**
 * Neutral provider-tagged server-side tool-use payload (tool search, advisor) for verbatim round-tripping
 */
/** @experimental */
export interface AssistantMessageServerTools {
  /**
   * Advisor model identifier associated with the server-tool payload.
   */
  advisorModel?: string;
  /**
   * Provider function-call namespaces keyed by function-call identifier.
   */
  functionCallNamespaces?: {
    [k: string]: string | undefined;
  };
  /**
   * Provider-native server-tool call and output items preserved verbatim for replay.
   */
  items?: JsonValue[];
  /**
   * Model provider that produced this server-tool payload.
   */
  provider: string;
  /**
   * Raw provider content blocks retained for verbatim round-tripping.
   */
  rawContentBlocks?: JsonValue[];
}
/**
 * A tool invocation request from the assistant
 */
export interface AssistantMessageToolRequest {
  /**
   * Arguments to pass to the tool, format depends on the tool
   */
  arguments?: JsonValue;
  caller?: AssistantMessageToolRequestCaller;
  /**
   * 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;
}
/**
 * Hosted program that requested this client tool call
 */
export interface AssistantMessageToolRequestCaller {
  /**
   * Provider-assigned identifier for the hosted caller.
   */
  callerId: string;
  type: AssistantMessageToolRequestCallerType;
}
/**
 * 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 {
  /**
   * Number of accepted speculative prediction tokens
   */
  acceptedPredictionTokens?: number;
  /**
   * Completion ID from the model provider (e.g., chatcmpl-abc123)
   */
  apiCallId?: string;
  apiEndpoint?: AssistantUsageApiEndpoint;
  /**
   * Number of tools available to the model for this call
   *
   * @internal
   */
  availableToolCount?: number;
  /**
   * Whether the provider reported prompt-cache usage details for this call
   *
   * @internal
   */
  cacheDetailsReported?: boolean;
  /**
   * Updated prompt-cache expiration for this model call. Present only when the call establishes or refreshes known cache state.
   */
  cacheExpiresAt?: string;
  /**
   * Number of tokens read from prompt cache
   */
  cacheReadTokens?: number;
  /**
   * Effective prompt-cache lifetime in seconds for this call
   *
   * @internal
   */
  cacheTtlSeconds?: 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;
  /**
   * How the prompt-cache frontier was determined for this call
   *
   * @internal
   */
  frontierSource?: string;
  /**
   * Experimental HydraFusion attribution for this concrete model call's usage.
   *
   * @experimental
   */
  fusion?: FusionAttribution;
  /**
   * 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;
  /**
   * Coarse classification of the interaction that produced this call, mirroring the session's per-request agent context (e.g. `conversation-agent`, `conversation-subagent`, `conversation-sampling`, `conversation-background`, `conversation-compaction`, `conversation-user`). Non-billing; lets consumers attribute a model call to a call class (e.g. sub-agent/sidekick) independently of the billing initiator. Absent when the runtime did not classify the request.
   */
  interactionType?: string;
  /**
   * Average inter-token latency in milliseconds. Only available for streaming requests
   */
  interTokenLatencyMs?: number;
  /**
   * Whether Auto mode was selected for this model call
   */
  isAuto?: boolean;
  /**
   * Whether this model call used a bring-your-own-key provider
   */
  isByok?: boolean;
  /**
   * Requested maximum output tokens used for this model call
   */
  maxOutputTokens?: number;
  /**
   * Effective maximum prompt-token limit used for this model call
   */
  maxPromptTokens?: number;
  /**
   * Model identifier used for this API call
   */
  model: string;
  /**
   * Number of tool calls returned by the model
   *
   * @internal
   */
  numToolCalls?: number;
  /**
   * Number of output tokens produced
   */
  outputTokens?: number;
  /**
   * Time to first observable model output in milliseconds. Includes text, reasoning, and tool-call output; only available for streaming requests that produce observable output.
   */
  outputTtftMs?: 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;
  reasoningSummary?: ReasoningSummary;
  /**
   * Number of output tokens used for reasoning (e.g., chain-of-thought)
   */
  reasoningTokens?: number;
  /**
   * Number of rejected speculative prediction tokens
   */
  rejectedPredictionTokens?: number;
  /**
   * Per-request treatment/eligibility signal returned by the Copilot API in the `X-GitHub-Copilot-Request-TE` response header for the associated model call; `false` when the header was absent or unparseable.
   */
  rte?: boolean;
  /**
   * Copilot service request ID (x-copilot-service-request-id header) for CAPI log correlation
   */
  serviceRequestId?: string;
  /**
   * Number of prior thinking blocks the provider dropped while transforming the request
   *
   * @internal
   */
  thinkingDroppedBlocks?: number;
  /**
   * Recognized provider-reported reasons for dropped thinking blocks, in response order
   *
   * @internal
   */
  thinkingDroppedReasons?: string[];
  /**
   * Time to first token in milliseconds. Only available for streaming requests
   */
  timeToFirstTokenMs?: number;
  /**
   * Tool-call counts keyed by tool name
   *
   * @internal
   */
  toolCounts?: {
    [k: string]: number | undefined;
  };
  /**
   * Number of tokens used by tool definitions for this call
   *
   * @internal
   */
  toolTokenCount?: number;
  transport?: AssistantUsageTransport;
}
/**
 * Per-request cost and usage data from the CAPI copilot_usage response field
 */
export interface AssistantUsageCopilotUsage {
  /**
   * Default billing model for token details that do not identify their own model
   */
  model?: string;
  /**
   * 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;
  /**
   * Model responsible for this billing entry
   */
  model?: string;
  /**
   * 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;
  apiEndpoint?: AssistantUsageApiEndpoint;
  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;
  failureKind?: ModelCallFailureKind;
  /**
   * Experimental HydraFusion attribution for this failed concrete model call.
   *
   * @experimental
   */
  fusion?: FusionAttribution;
  /**
   * What initiated this API call (e.g., "sub-agent", "mcp-sampling"); absent for user-initiated calls
   */
  initiator?: string;
  /**
   * Authoritative interaction classification for the failed call, matching `assistant.usage.interactionType` (for example `conversation-agent`, `conversation-subagent`, or `conversation-sampling`). Absent when the producer cannot classify the interaction.
   */
  interactionType?: string;
  /**
   * Whether the session selected Auto mode for the failed call
   */
  isAuto?: boolean;
  /**
   * Whether the failed call used a bring-your-own-key provider
   */
  isByok?: boolean;
  /**
   * Effective maximum output-token limit for the failed call
   */
  maxOutputTokens?: number;
  /**
   * Effective maximum prompt-token limit for the failed call
   */
  maxPromptTokens?: number;
  /**
   * 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;
  };
  /**
   * Reasoning effort level used for the failed model call, if applicable
   */
  reasoningEffort?: string;
  requestFingerprint?: ModelCallFailureRequestFingerprint;
  /**
   * Per-request treatment/eligibility signal returned by the Copilot API in the `X-GitHub-Copilot-Request-TE` response header for the associated model call; `false` when the header was absent or unparseable.
   */
  rte?: boolean;
  /**
   * 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;
  transport?: ModelCallFailureTransport;
}
/**
 * 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 "model.call_finished". Final lifecycle outcome for one logical model dispatch. A logical dispatch may include internal reconnect or fallback work, so event count is not provider HTTP-request count.
 */
export interface ModelCallFinishedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ModelCallFinishedData;
  /**
   * 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_finished".
   */
  type: "model.call_finished";
}
/**
 * Final lifecycle outcome for one logical model dispatch. A logical dispatch may include internal reconnect or fallback work, so event count is not provider HTTP-request count.
 */
export interface ModelCallFinishedData {
  /**
   * Whether an accepted successful response requested the exact name and command semantics of a built-in file edit tool, including an external tool explicitly replacing that built-in name. Absent when the logical dispatch did not produce an accepted response.
   */
  containsBuiltInFileEditRequest?: boolean;
  /**
   * Monotonic elapsed time spent in the logical model dispatch, including any internal transport reconnect or fallback and excluding orchestrator retry backoff, tool execution, confirmations, and post-response processing
   */
  dispatchDurationMs: number;
  /**
   * Version of the built-in file-edit semantic classifier used for this event
   */
  editClassifierVersion: number;
  /**
   * Identifier of the user interaction that owns the model dispatch, matching assistant.turn_start.interactionId when available
   */
  interactionId?: string;
  outcome: ModelCallFinishedOutcome;
  /**
   * Agent-loop iteration within the interaction that initiated the model dispatch
   */
  turnId: string;
}
/**
 * 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?: JsonValue;
  /**
   * 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?: JsonValue;
  /**
   * When true, the tool output should be displayed expanded (verbatim) in the CLI timeline
   */
  displayVerbatim?: boolean;
  /**
   * Experimental HydraFusion attribution for this tool execution.
   *
   * @experimental
   */
  fusion?: FusionAttribution;
  /**
   * Preferred lookup name for the MCP server hosting this tool: the configured (namespaced) config-map key when the tool carries one, otherwise the display name from `mcpServerName`. Present when the tool is an MCP tool; this is the name unrestricted provenance telemetry hashes so it joins with `mcp_server_setup`, which keys off the configured name too.
   */
  mcpConfigServerName?: string;
  mcpConfigSource?: McpServerSource;
  /**
   * 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;
  mcpTransport?: McpServerTransport;
  /**
   * 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;
  /**
   * Per-request treatment/eligibility signal returned by the Copilot API in the `X-GitHub-Copilot-Request-TE` response header for the associated model call; `false` when the header was absent or unparseable.
   */
  rte?: boolean;
  shellToolInfo?: ToolExecutionStartShellToolInfo;
  /**
   * Unique identifier for this tool call
   */
  toolCallId: string;
  toolDescription?: ToolExecutionStartToolDescription;
  /**
   * Name of the tool being executed
   */
  toolName: string;
  /**
   * Human-readable display title for the tool, when the selected tool descriptor has a non-empty title.
   */
  toolTitle?: 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 {
  /**
   * The command with a redundant leading `cd` into the working directory removed, present only when there was one to remove. Computed with the same routine the shell driver applies before spawning, so a surface that renders this shows the text that actually runs. Consumers that display it should keep the original tool arguments available on demand.
   *
   * @experimental
   */
  displayCommand?: string;
  /**
   * 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;
  /**
   * Experimental HydraFusion attribution for this tool completion.
   *
   * @experimental
   */
  fusion?: FusionAttribution;
  /**
   * 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?: JsonValue;
  /**
   * 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;
  /**
   * Per-request treatment/eligibility signal returned by the Copilot API in the `X-GitHub-Copilot-Request-TE` response header for the associated model call; `false` when the header was absent or unparseable.
   */
  rte?: boolean;
  /**
   * Whether this tool execution ran inside a sandbox container
   */
  sandboxed?: boolean;
  /**
   * Experimental shell completion facts captured before the persisted result contents are stripped.
   *
   * @experimental
   */
  shellExecution?: ToolExecutionCompleteShellExecution;
  /**
   * 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]: JsonValue | 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;
  remediation?: RemediationAction;
}
/**
 * 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[];
  /**
   * Detailed tool result for UI/timeline display, preserving complete content such as diffs for most tools. Successful skill invocations intentionally use the concise model-facing content here; the authoritative skill body is carried by the corresponding skill invocation event. 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?: JsonValue;
  /**
   * Structured content (arbitrary JSON) returned verbatim by the MCP tool
   */
  structuredContent?: JsonValue;
  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]: JsonValue | 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]: JsonValue | 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]: JsonValue | 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;
  /**
   * Path reported in the shell session's filesystem namespace when shell output exceeded the configured large-output threshold.
   */
  outputFilePath?: string;
  /**
   * 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;
  /**
   * Optional dedicated origin for the rendered MCP Apps UI resource.
   */
  domain?: string;
  permissions?: ToolExecutionCompleteUIResourceMetaUIPermissions;
  /**
   * Whether the host should render a border around the MCP Apps UI resource.
   */
  prefersBorder?: boolean;
}
/**
 * CSP domain allowlists for an MCP Apps UI resource, including connect, resource, frame, and base URI domains.
 */
export interface ToolExecutionCompleteUIResourceMetaUICsp {
  /**
   * Domains the UI resource may use as document base URIs.
   */
  baseUriDomains?: string[];
  /**
   * Domains the UI resource may connect to.
   */
  connectDomains?: string[];
  /**
   * Domains the UI resource may embed as nested frames.
   */
  frameDomains?: string[];
  /**
   * Domains from which the UI resource may load scripts, styles, images, and other resources.
   */
  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 {}
/**
 * Experimental shell completion facts retained independently of the full tool result.
 */
/** @experimental */
export interface ToolExecutionCompleteShellExecution {
  /**
   * Process exit code reported by the shell driver.
   */
  exitCode: number;
}
/**
 * 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 "tool_search.activated". Persisted generic client-side tool activations restored when a session resumes.
 */
export interface ToolSearchActivatedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ToolSearchActivatedData;
  /**
   * 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_search.activated".
   */
  type: "tool_search.activated";
}
/**
 * Persisted generic client-side tool activations restored when a session resumes.
 */
export interface ToolSearchActivatedData {
  /**
   * Tool-search strategy that activated the definitions.
   */
  strategy: string;
  /**
   * Names of tool definitions activated by this search invocation.
   */
  toolNames: string[];
}
/**
 * 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;
  /**
   * Whether model invocation is disabled for this skill
   */
  disableModelInvocation?: boolean;
  /**
   * Projected chat-message count when the skill was invoked. New writers persist this so replay does not need to reconstruct superseded history; readers derive it for legacy events when absent.
   */
  invokedAtTurn?: number;
  /**
   * 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, or an empty string for an SDK-provided skill without a filesystem identity
   */
  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), remote (org/enterprise skill), and sdk (SDK-provided 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;
  /**
   * Type of the sub-agent selected at spawn time.
   */
  agentType?: string;
  /**
   * Whether the sub-agent runs synchronously or in the background.
   */
  executionMode?: string;
  /**
   * Root id of the factory run that spawned this sub-agent, when it was spawned by one.
   */
  factoryRunId?: string;
  /**
   * Model the sub-agent will run with, when known at start.
   */
  model?: string;
  modelSelectionSource?: SubagentModelSelectionSource;
  /**
   * Task-registry ID of the spawning sub-agent. Absent when the root session spawned this child.
   */
  parentId?: string;
  /**
   * Whether this sub-agent can be resumed. Currently always false.
   */
  resumable?: boolean;
  taskModelSource?: SubagentTaskModelSource;
  /**
   * Tool call ID of the parent tool invocation that spawned this sub-agent
   */
  toolCallId: string;
}
/**
 * Session event "subagent.configured". Resolved runtime configuration for a configured sub-agent
 */
export interface SubagentConfiguredEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: SubagentConfiguredData;
  /**
   * 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.configured".
   */
  type: "subagent.configured";
}
/**
 * Resolved runtime configuration for a configured sub-agent
 */
export interface SubagentConfiguredData {
  /**
   * Resolved context tier, when configured for the model
   */
  contextTier?: string;
  /**
   * Resolved model the sub-agent will run with
   */
  model: string;
  /**
   * Whether the sub-agent accepts follow-up turns
   */
  multiTurn: boolean;
  /**
   * Resolved reasoning effort, when configured for the model
   */
  reasoningEffort?: 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;
  /**
   * Whether the sub-agent was torn down by cancellation - its own abort, or an ancestor being killed - instead of finishing its work. Cancellation is not a failure, so the run still reports completion; this distinguishes a torn-down sub-agent from one that ran to the end.
   */
  cancelled?: boolean;
  /**
   * Whether the first model actually dispatched matched the user's configured preference
   */
  configuredModelMatchesActual?: boolean;
  /**
   * Concrete model the user configured for this sub-agent via `/subagents`, when present
   */
  configuredModelPreference?: string;
  /**
   * Wall-clock duration of the sub-agent execution in milliseconds
   */
  durationMs?: number;
  /**
   * Whether the explicit task-call model matched the user's configured preference
   */
  explicitModelMatchesPreference?: boolean;
  /**
   * Explicit model supplied by the parent agent on the task call, when present
   */
  explicitModelOverride?: string;
  /**
   * First model for which the sub-agent started an inference request, when one was dispatched
   */
  firstDispatchedModel?: string;
  /**
   * Model used by the sub-agent
   */
  model?: string;
  /**
   * Why an explicit task-call model did not become the effective model
   */
  modelOverrideReason?: string;
  modelSelectionSource?: SubagentModelSelectionSource;
  /**
   * 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;
  /**
   * Whether the first model actually dispatched matched the user's configured preference
   */
  configuredModelMatchesActual?: boolean;
  /**
   * Concrete model the user configured for this sub-agent via `/subagents`, when present
   */
  configuredModelPreference?: string;
  /**
   * Wall-clock duration of the sub-agent execution in milliseconds
   */
  durationMs?: number;
  /**
   * Error message describing why the sub-agent failed
   */
  error: string;
  /**
   * Whether the explicit task-call model matched the user's configured preference
   */
  explicitModelMatchesPreference?: boolean;
  /**
   * Explicit model supplied by the parent agent on the task call, when present
   */
  explicitModelOverride?: string;
  /**
   * First model for which the sub-agent started an inference request, when one was dispatched
   */
  firstDispatchedModel?: string;
  /**
   * Model selected for the sub-agent, when known
   */
  model?: string;
  /**
   * Why an explicit task-call model did not become the effective model
   */
  modelOverrideReason?: string;
  modelSelectionSource?: SubagentModelSelectionSource;
  /**
   * 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. For postToolUse hooks the retained copy served by session.eventLog.read (and by a resumed session) drops the tool result's inline `contents`/`uiResource`/`skillInvocation` and replaces duplicated text result fields with a `[copilot:elided ...]` marker; the live subscription stream still delivers the full value. Canonical tool output remains in the adjacent tool.execution_complete event, while an invoked skill's authoritative body remains in its skill invocation event.
   */
  input?: JsonValue;
  /**
   * Tool call ID of the parent tool invocation when this event originates from a sub-agent
   */
  parentToolCallId?: string;
}
/**
 * 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. Durable and resumed postToolUse receipts may omit messages owned by a successful skill invocation and replace an unchanged skill sessionLog copy with an elision marker; hook-modified or re-sourced values are preserved, and the authoritative body remains in the skill invocation event.
   */
  output?: JsonValue;
  /**
   * Tool call ID of the parent tool invocation when this event originates from a sub-agent
   */
  parentToolCallId?: string;
  /**
   * 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]: JsonValue | 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;
  /**
   * Optional ordered structured blocks corresponding to content, retained for prompt-cache layout restoration.
   */
  contentBlocks?: SystemMessageContentBlock[];
  /**
   * Logical interaction identifier for the model run receiving this prompt
   */
  interactionId?: string;
  metadata?: SystemMessageMetadata;
  /**
   * Optional name identifier for the message source
   */
  name?: string;
  role: SystemMessageRole;
}
/**
 * One persisted structured system-message block and its cache intent
 */
export interface SystemMessageContentBlock {
  /**
   * Explicit prompt-cache intent. True places a breakpoint after this block, false suppresses one, and absence preserves the provider's legacy default.
   */
  cacheBreakpoint?: boolean;
  /**
   * Text content for this system-message block.
   */
  content: string;
  /**
   * Diagnostic classification indicating whether the block is stable across equivalent sessions.
   */
  isStatic?: boolean;
}
/**
 * Metadata about the prompt template and its construction
 */
export interface SystemMessageMetadata {
  /**
   * Version identifier of the prompt template or structured prompt layout used
   */
  promptVersion?: string;
  /**
   * Template variables used when constructing the prompt
   */
  variables?: {
    [k: string]: JsonValue | 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;
  responsesReasoning?: ResponsesReasoning;
}
/**
 * System notification metadata for a background agent that completed or failed, including agent ID, type, status, description, and prompt.
 */
export interface SystemNotificationAgentCompleted {
  /**
   * Unique task identifier
   */
  agentId: string;
  /**
   * Type of the agent (e.g., explore, task, general-purpose)
   */
  agentType: string;
  /**
   * Human-readable description of the agent task
   */
  description?: string;
  /**
   * Friendly, non-unique name intended for display
   */
  displayName?: 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 task identifier
   */
  agentId: string;
  /**
   * Type of the agent (e.g., explore, task, general-purpose)
   */
  agentType: string;
  /**
   * Human-readable description of the agent task
   */
  description?: string;
  /**
   * Friendly, non-unique name intended for display
   */
  displayName?: 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";
}
/**
 * System notification metadata for a factory execution attempt that reached a terminal state.
 */
export interface SystemNotificationFactoryCompleted {
  /**
   * Execution attempt that reached this terminal state.
   */
  attempt: number;
  /**
   * Consumed AI usage in nano-AIU.
   */
  consumedNanoAiu: number;
  /**
   * Subagents consumed by the run across all attempts.
   */
  consumedSubagents: number;
  /**
   * Accumulated active execution time in milliseconds.
   */
  elapsedMs: number;
  /**
   * Persisted factory name.
   */
  factoryName: string;
  /**
   * Machine-readable terminal failure details, when present.
   */
  failure?: JsonValue;
  pauseInfo?: SystemNotificationFactoryPauseInfo;
  /**
   * Bounded prompt-safe preview of the completed result.
   */
  resultPreview?: string;
  /**
   * Actionable run_factory resume guidance for a resource-limit failure.
   */
  retryGuidance?: string;
  /**
   * Factory run identifier.
   */
  runId: string;
  status: SystemNotificationFactoryCompletedStatus;
  /**
   * Type discriminator. Always "factory_completed".
   */
  type: "factory_completed";
}
/**
 * System notification metadata from an external host that does not match a runtime-owned notification kind.
 */
export interface SystemNotificationUnclassified {
  /**
   * Opaque metadata supplied by the external host, when present.
   */
  metadata?: JsonValue;
  /**
   * Type discriminator. Always "unclassified".
   */
  type: "unclassified";
}
/**
 * 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 {
  agentMode?: SessionMode;
  permissionMode?: PermissionMode;
  permissionRequest: PermissionRequest;
  promptRequest?: PermissionPromptRequest;
  /**
   * Permission-recovery episode that authorized this request to surface for interactive attention
   */
  recoveryEpisodeId?: string;
  /**
   * 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;
  /**
   * Neutral risk metadata supplied by the tool host. Consumers may display this value but must not use it to bypass the permission decision.
   */
  riskAssessment?: JsonValue;
}
/**
 * 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[];
  /**
   * Parsed command segments, including arguments, used for managed policy matching
   */
  commandSegments?: PermissionRequestShellCommandSegment[];
  /**
   * 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";
  /**
   * Whether managed policy requires a human response and forbids host auto-approval
   */
  managedApprovalRequired?: boolean;
  /**
   * 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 tool is asking to run this command outside the sandbox, either because the command detaches and cannot be sandboxed at all, or because a sandboxed run looked blocked (host opted in via sandbox.allowBypass). The model cannot ask for this; only the tool raises it. 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;
  /**
   * What the tool tells the user about the bypass on offer: which policy rule blocked the call, or why it cannot be sandboxed. Only meaningful when requestSandboxBypass is true.
   */
  requestSandboxBypassReason?: string;
  /**
   * True when the requested escalation is a permissive retry rather than a full bypass: the command re-runs inside the sandbox with its file and process restrictions recording instead of blocking, while the network policy stays enforced. Always accompanied by requestSandboxBypass, so hosts that do not recognize this field still treat the request as the escalation it is. Hosts that do recognize it must not describe the command as running outside the sandbox, which would overstate the privilege being granted.
   */
  requestSandboxPermissive?: boolean;
  /**
   * Runtime-resolved canonical object each possiblePaths entry names, keyed by the requested spelling, used for authorization identity checks. Internal and experimental; clients should continue to display possiblePaths.
   *
   * @experimental
   */
  resolvedPaths?: {
    [k: string]: string | undefined;
  };
  /**
   * Runtime-resolved canonical working directory the command runs in, used for authorization identity checks. Internal and experimental; clients should not display it.
   *
   * @experimental
   */
  resolvedWorkingDirectory?: 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 parsed shell command segment used for argument-aware managed policy matching.
 */
export interface PermissionRequestShellCommandSegment {
  /**
   * Full text of this command segment, including arguments
   */
  fullCommandText: string;
  /**
   * Command identifier (e.g., executable name)
   */
  identifier: string;
}
/**
 * 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";
  /**
   * Whether managed policy requires a human response and forbids host auto-approval
   */
  managedApprovalRequired?: boolean;
  /**
   * 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;
  /**
   * Runtime-resolved canonical path used for authorization identity checks. Internal and experimental; clients should continue to display fileName.
   *
   * @experimental
   */
  resolvedPath?: 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";
  /**
   * Whether managed policy requires a human response and forbids host auto-approval
   */
  managedApprovalRequired?: boolean;
  /**
   * Path of the file or directory being read
   */
  path: string;
  /**
   * True when the tool is asking to re-run this search outside the sandbox, after a sandboxed run looked blocked (host opted in via sandbox.allowBypass). The model cannot ask for this; only the tool raises it. 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;
  /**
   * What the tool tells the user about the bypass on offer: which policy rule blocked the call, or why it cannot be sandboxed. Only meaningful when requestSandboxBypass is true.
   */
  requestSandboxBypassReason?: string;
  /**
   * Runtime-resolved canonical path used for authorization identity checks. Internal and experimental; clients should continue to display path.
   *
   * @experimental
   */
  resolvedPath?: 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?: JsonValue;
  /**
   * Permission kind discriminator
   */
  kind: "mcp";
  /**
   * Advisory runtime permission recommendation. The SDK host remains responsible for deciding the request and may reject it.
   *
   * @experimental
   */
  permissionRecommendation?: PermissionRecommendation;
  /**
   * 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";
  /**
   * Whether managed policy requires a human response and forbids host auto-approval
   */
  managedApprovalRequired?: boolean;
  /**
   * Immediately preceding URL when this request is for a redirect target
   */
  redirectedFrom?: string;
  /**
   * True when the tool is asking to run this URL fetch outside the sandbox, after the network policy denied the approved URL or the sandbox proxy could not reach it (host opted in via sandbox.allowBypass). The model cannot ask for this; only the tool raises it. 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;
  /**
   * What the tool tells the user about the bypass on offer: which policy rule blocked the call, or why it cannot be sandboxed. 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;
  /**
   * Assisted-approval judge information for this request; present only in assisted mode.
   *
   * @experimental
   */
  assistedApproval?: PermissionAssistedApproval;
  /**
   * 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;
  /**
   * Repository name with owner associated with the stored memory (store only)
   */
  repoNwo?: string;
  scope?: PermissionRequestMemoryScope;
  /**
   * Topic or subject of the memory (store only)
   */
  subject?: string;
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
}
/**
 * Assisted-approval judge information attached to a permission request. Present only in assisted mode; its absence means the judge did not evaluate the request. The `recommendation` conveys the judge's disposition for this request.
 */
/** @experimental */
export interface PermissionAssistedApproval {
  evaluation?: PermissionApprovalEvaluation;
  failureReason?: AssistedApprovalJudgeFailureReason;
  /**
   * Model id that produced the recommendation, when the judge was consulted and reported one. Absent for `excluded` (the judge was not consulted) and for failures that occurred before a model was selected.
   */
  model?: string;
  /**
   * Human-readable reason for the judge's recommendation, when available.
   */
  reason?: string;
  recommendation: AssistedApprovalRecommendation;
}
/**
 * Bounded runtime attribution, independent of free-text rationale. Telemetry revalidates this vocabulary before standard collection.
 */
export interface PermissionApprovalEvaluation {
  /**
   * Stage that produced this attribution.
   */
  evaluationStage: /** The attribution stage is unknown. */
    | "unknown"
    /** The request resolved before assisted-approval evaluation. */
    | "not_reached"
    /** A runtime gate skipped the judge. */
    | "pre_judge"
    /** The judge interface produced the evaluation. */
    | "judge"
    /** A cached recommendation or another request's outcome was reused. */
    | "reuse";
  /**
   * Whether the request invoked the judge interface. A cached recommendation retains the original attempt fact. Omitted means unknown, including inherited outcomes.
   */
  judgeAttempted?: boolean;
  /**
   * Status of the local judge interface, not proof of a model network call.
   */
  judgeStatus: /** No authoritative attribution is available. */
    | "unknown"
    /** This evaluation did not invoke the judge interface. */
    | "not_called"
    /** The judge interface returned a usable verdict. */
    | "completed"
    /** The judge interface returned an error. */
    | "failed"
    /** This evaluation reused a cached recommendation. */
    | "cached"
    /** This request inherited another decision without local judge attribution. */
    | "inherited";
  /**
   * Machine-readable runtime gate reason, never a command, path or human rationale.
   */
  reasonCode: /** Attribution is missing or outside the supported vocabulary. */
    | "unknown"
    /** The request resolved before assisted-approval evaluation. */
    | "not-reached"
    /** Assisted approval was inactive for this request. */
    | "inactive"
    /** The judge was skipped because authorization extraction could not safely establish a complete recent history. */
    | "authorization-history-incomplete"
    /** Managed policy required a human decision. */
    | "managed-approval-required"
    /** The request asked to bypass sandbox restrictions. */
    | "sandbox-bypass"
    /** An action field exceeded the judge input limit. */
    | "action-too-long"
    /** The script path was not authorized for inspection. */
    | "path-not-authorized"
    /** The script working directory was invalid. */
    | "invalid-working-directory"
    /** The script snapshot could not be read. */
    | "unreadable"
    /** The script path was not a regular file. */
    | "not-regular-file"
    /** The script snapshot exceeded the size limit. */
    | "too-large"
    /** The script snapshot was not UTF-8. */
    | "non-utf8"
    /** The script interpreter could not be inspected. */
    | "interpreter-unavailable"
    /** The interpreter snapshot exceeded the size limit. */
    | "interpreter-too-large"
    /** The shell environment could not be reviewed. */
    | "shell-environment-unreviewable"
    /** A script path could not be represented for review. */
    | "unrepresentable-path"
    /** An interpreter wrapped a script that could not be reviewed. */
    | "interpreter-wrapped-script"
    /** The script invocation could not be reviewed. */
    | "unreviewable-script-invocation"
    /** The script argument binding could not be reviewed. */
    | "argument-binding-unreviewable"
    /** The script review metadata was malformed. */
    | "malformed-script-action-review"
    /** The script snapshot manifest was malformed. */
    | "malformed-script-action-manifest"
    /** Script review was unavailable. */
    | "unavailable"
    /** The judge interface returned a usable verdict. */
    | "judge-verdict"
    /** The judge interface returned an error. */
    | "judge-error"
    /** The request inherited an outcome from another decision. */
    | "inherited";
}
/**
 * Custom tool invocation permission request
 */
export interface PermissionRequestCustomTool {
  /**
   * Arguments to pass to the custom tool
   */
  args?: JsonValue;
  /**
   * Permission kind discriminator
   */
  kind: "custom-tool";
  /**
   * Whether the tool declared that permission may be skipped unless a deny rule matches
   */
  skipPermission?: boolean;
  /**
   * 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?: JsonValue;
  /**
   * 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;
}
/**
 * Factory run or authoring permission request
 */
export interface PermissionRequestFactory {
  /**
   * Canonical key used for scoped factory approvals
   */
  approvalKey: string;
  /**
   * Whether this factory is eligible for persistent approval
   */
  canPersistApproval: boolean;
  /**
   * Factory-declared AI-credit limit before any run/resume caller override is applied.
   */
  declaredMaxAiCredits?: number;
  /**
   * Factory-declared concurrent-subagent limit before any run/resume caller override is applied.
   */
  declaredMaxConcurrentSubagents?: number;
  /**
   * Factory-declared total-subagent limit before any run/resume caller override is applied.
   */
  declaredMaxTotalSubagents?: number;
  /**
   * Factory-declared active-time limit in seconds before any run/resume caller override is applied.
   */
  declaredTimeoutSeconds?: number;
  /**
   * Factory description
   */
  description: string;
  /**
   * Permission kind discriminator
   */
  kind: "factory";
  /**
   * Effective AI-credit limit; omitted means unlimited
   */
  maxAiCredits?: number;
  /**
   * Effective concurrent-subagent limit; omitted means unlimited
   */
  maxConcurrentSubagents?: number;
  /**
   * Effective total-subagent limit; omitted means unlimited
   */
  maxTotalSubagents?: number;
  /**
   * Factory name
   */
  name: string;
  operation: FactoryPermissionOperation;
  /**
   * Declared factory phases
   */
  phases: FactoryPermissionPhase[];
  /**
   * Effective active-time limit in seconds; omitted means unlimited
   */
  timeoutSeconds?: number;
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
}
/**
 * A declared phase shown in a factory permission prompt.
 */
export interface FactoryPermissionPhase {
  /**
   * Optional phase detail
   */
  detail?: string;
  /**
   * Phase title
   */
  title: 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;
}
/**
 * Extension sensitive environment variable access request
 */
export interface PermissionRequestExtensionEnvAccess {
  /**
   * Names of the sensitive environment variables the extension is requesting. Values never appear here.
   *
   * @minItems 1
   */
  environmentVariables: [string, ...string[]];
  /**
   * Name of the extension requesting environment variable access
   */
  extensionName: string;
  /**
   * Permission kind discriminator
   */
  kind: "extension-env-access";
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
}
/**
 * Shell command permission prompt
 */
export interface PermissionPromptRequestCommands {
  /**
   * Assisted-approval judge information for this request; present only in assisted mode.
   *
   * @experimental
   */
  assistedApproval?: PermissionAssistedApproval;
  /**
   * 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";
  /**
   * Whether managed policy requires a human response and forbids host auto-approval
   */
  managedApprovalRequired?: boolean;
  /**
   * True when the shell command is requesting sandbox escalation. This is a request, not a grant.
   */
  requestSandboxBypass?: boolean;
  /**
   * Reason for the sandbox escalation request.
   */
  requestSandboxBypassReason?: string;
  /**
   * True when the escalation is a permissive retry that keeps the sandbox and network policy attached while recording file and process accesses instead of blocking them.
   */
  requestSandboxPermissive?: boolean;
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
  /**
   * Optional warning message about risks of running this command
   */
  warning?: string;
}
/**
 * File write permission prompt
 */
export interface PermissionPromptRequestWrite {
  /**
   * Assisted-approval judge information for this request; present only in assisted mode.
   *
   * @experimental
   */
  assistedApproval?: PermissionAssistedApproval;
  /**
   * 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";
  /**
   * Whether managed policy requires a human response and forbids host auto-approval
   */
  managedApprovalRequired?: boolean;
  /**
   * Complete new file contents for newly created files
   */
  newFileContents?: string;
  /**
   * Runtime-resolved canonical path used for authorization identity checks. Internal and experimental; clients should continue to display fileName.
   *
   * @experimental
   */
  resolvedPath?: string;
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
}
/**
 * File read permission prompt
 */
export interface PermissionPromptRequestRead {
  /**
   * Assisted-approval judge information for this request; present only in assisted mode.
   *
   * @experimental
   */
  assistedApproval?: PermissionAssistedApproval;
  /**
   * Human-readable description of why the file is being read
   */
  intention: string;
  /**
   * Prompt kind discriminator
   */
  kind: "read";
  /**
   * Whether managed policy requires a human response and forbids host auto-approval
   */
  managedApprovalRequired?: boolean;
  /**
   * Path of the file or directory being read
   */
  path: string;
  /**
   * Runtime-resolved canonical path used for authorization identity checks. Internal and experimental; clients should continue to display path.
   *
   * @experimental
   */
  resolvedPath?: 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?: JsonValue;
  /**
   * Assisted-approval judge information for this request; present only in assisted mode.
   *
   * @experimental
   */
  assistedApproval?: PermissionAssistedApproval;
  /**
   * Whether the host may offer a server-wide "approve all tools from this server" blanket. Absent is treated as true; the runtime sends false when managed policy disables bypass-permissions mode, which forbids the server-wide escalation while still allowing per-tool approval.
   */
  canOfferServerWideApproval?: boolean;
  /**
   * Prompt kind discriminator
   */
  kind: "mcp";
  /**
   * Advisory runtime permission recommendation. The host remains responsible for deciding the request and may reject it.
   *
   * @experimental
   */
  permissionRecommendation?: PermissionRecommendation;
  /**
   * 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 {
  /**
   * Assisted-approval judge information for this request; present only in assisted mode.
   *
   * @experimental
   */
  assistedApproval?: PermissionAssistedApproval;
  /**
   * Human-readable description of why the URL is being accessed
   */
  intention: string;
  /**
   * Prompt kind discriminator
   */
  kind: "url";
  /**
   * Whether managed policy requires a human response and forbids host auto-approval
   */
  managedApprovalRequired?: boolean;
  /**
   * Immediately preceding URL when this prompt is for a redirect target
   */
  redirectedFrom?: string;
  /**
   * True when the tool is asking to run this URL fetch outside the sandbox, after the network policy denied the approved URL or the sandbox proxy could not reach it (host opted in via sandbox.allowBypass). The model cannot ask for this; only the tool raises it. 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;
  /**
   * What the tool tells the user about the bypass on offer: which policy rule blocked the call, or why it cannot be sandboxed. 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;
  /**
   * Assisted-approval judge information for this request; present only in assisted mode.
   *
   * @experimental
   */
  assistedApproval?: PermissionAssistedApproval;
  /**
   * 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?: JsonValue;
  /**
   * Assisted-approval judge information for this request; present only in assisted mode.
   *
   * @experimental
   */
  assistedApproval?: PermissionAssistedApproval;
  /**
   * 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;
  /**
   * Assisted-approval judge information for this request; present only in assisted mode.
   *
   * @experimental
   */
  assistedApproval?: PermissionAssistedApproval;
  /**
   * 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 {
  /**
   * Assisted-approval judge information for this request; present only in assisted mode.
   *
   * @experimental
   */
  assistedApproval?: PermissionAssistedApproval;
  /**
   * 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?: JsonValue;
  /**
   * 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 {
  /**
   * Assisted-approval judge information for this request; present only in assisted mode.
   *
   * @experimental
   */
  assistedApproval?: PermissionAssistedApproval;
  /**
   * 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;
}
/**
 * Factory run or authoring permission prompt
 */
export interface PermissionPromptRequestFactory {
  /**
   * Canonical key used for scoped factory approvals
   */
  approvalKey: string;
  /**
   * Assisted-approval judge information for this request; present only in assisted mode.
   *
   * @experimental
   */
  assistedApproval?: PermissionAssistedApproval;
  /**
   * Whether this factory is eligible for persistent approval
   */
  canPersistApproval: boolean;
  /**
   * Factory-declared AI-credit limit before any run/resume caller override is applied.
   */
  declaredMaxAiCredits?: number;
  /**
   * Factory-declared concurrent-subagent limit before any run/resume caller override is applied.
   */
  declaredMaxConcurrentSubagents?: number;
  /**
   * Factory-declared total-subagent limit before any run/resume caller override is applied.
   */
  declaredMaxTotalSubagents?: number;
  /**
   * Factory-declared active-time limit in seconds before any run/resume caller override is applied.
   */
  declaredTimeoutSeconds?: number;
  /**
   * Factory description
   */
  description: string;
  /**
   * Prompt kind discriminator
   */
  kind: "factory";
  /**
   * Whether managed policy requires a human response and forbids host auto-approval
   */
  managedApprovalRequired?: boolean;
  /**
   * Effective AI-credit limit; omitted means unlimited
   */
  maxAiCredits?: number;
  /**
   * Effective concurrent-subagent limit; omitted means unlimited
   */
  maxConcurrentSubagents?: number;
  /**
   * Effective total-subagent limit; omitted means unlimited
   */
  maxTotalSubagents?: number;
  /**
   * Factory name
   */
  name: string;
  operation: FactoryPermissionOperation;
  /**
   * Declared factory phases
   */
  phases: FactoryPermissionPhase[];
  /**
   * Effective active-time limit in seconds; omitted means unlimited
   */
  timeoutSeconds?: number;
  /**
   * Tool call ID that triggered this permission request
   */
  toolCallId?: string;
}
/**
 * Extension permission access prompt
 */
export interface PermissionPromptRequestExtensionPermissionAccess {
  /**
   * Assisted-approval judge information for this request; present only in assisted mode.
   *
   * @experimental
   */
  assistedApproval?: PermissionAssistedApproval;
  /**
   * 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;
}
/**
 * Extension sensitive environment variable access prompt
 */
export interface PermissionPromptRequestExtensionEnvAccess {
  /**
   * Assisted-approval judge information for this request; present only in assisted mode.
   *
   * @experimental
   */
  assistedApproval?: PermissionAssistedApproval;
  /**
   * Names of the sensitive environment variables the extension is requesting. Values never appear here.
   *
   * @minItems 1
   */
  environmentVariables: [string, ...string[]];
  /**
   * Name of the extension requesting environment variable access
   */
  extensionName: string;
  /**
   * Prompt kind discriminator
   */
  kind: "extension-env-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 {
  blocker?: TaskBlocker;
  /**
   * Who decided this permission request. Absent on completions recorded before this field existed, which consumers must treat as "not a human decision" rather than assuming one. Authorization records are minted only for `human_response`; an assisted-approval verdict, a host policy, an unattended fallback, and a hook resolution all produce the same `result` a person does, so this is the only field that distinguishes them.
   *
   * @experimental
   */
  decisionSource?: PermissionDecisionSource;
  /**
   * Permission-recovery episode settled by this response, when the request was escalated by Autopilot
   */
  recoveryEpisodeId?: string;
  /**
   * 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";
  /**
   * Whether a managed approval policy already handled this request
   */
  managedApprovalHandled?: boolean;
}
/**
 * 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";
  /**
   * Whether a managed approval policy already handled this request
   */
  managedApprovalHandled?: boolean;
}
/**
 * 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 factory approval, optionally narrowed by approval key.
 */
export interface UserToolSessionApprovalFactory {
  /**
   * Optional factory operation name or canonical approval key
   */
  approvalKey?: string;
  /**
   * Factory approval kind
   */
  kind: "factory";
}
/**
 * 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";
}
/**
 * Session-scoped tool-approval rule for an extension's access to sensitive environment variables, keyed by extension name and the exact set of variable names.
 */
export interface UserToolSessionApprovalExtensionEnvAccess {
  /**
   * Names of the sensitive environment variables this approval covers. Values are never persisted.
   *
   * @minItems 1
   */
  environmentVariables: [string, ...string[]];
  /**
   * Extension name
   */
  extensionName: string;
  /**
   * Extension environment access approval kind
   */
  kind: "extension-env-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;
  /**
   * Whether a managed approval policy already handled this request
   */
  managedApprovalHandled?: boolean;
}
/**
 * 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 "permission.carriedForward". Records that a live authorization record from an earlier human decision in this session contained a permission proposal, so it ran without another prompt. This mints no authority: it accounts for one more effect against the prior grant, which is what lets a replayed session agree with the live one about how much of that grant is left.
 */
/** @experimental */
export interface PermissionCarriedForwardEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: PermissionCarriedForwardData;
  /**
   * 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.carriedForward".
   */
  type: "permission.carriedForward";
}
/**
 * Records that a live authorization record from an earlier human decision in this session contained a permission proposal, so it ran without another prompt. This mints no authority: it accounts for one more effect against the prior grant, which is what lets a replayed session agree with the live one about how much of that grant is left.
 */
/** @experimental */
export interface PermissionCarriedForwardData {
  /**
   * Always `authorization_carry_forward`. Stated explicitly so a consumer reading this event cannot mistake it for a human, host-policy, or assisted-approval decision.
   *
   * @experimental
   */
  decisionSource: PermissionDecisionSource;
  /**
   * Identity of the prior authorization record that contained the proposal.
   *
   * @experimental
   */
  recordId: string;
  /**
   * Authorization edge minted for this admission. Not a prompt id: no prompt was raised, so no client should expect a request with this id.
   *
   * @experimental
   */
  requestId: string;
  /**
   * Tool call this admission authorizes. Its execution receipts the prior grant, which is how a single-effect approval is spent rather than carried forward again.
   *
   * @experimental
   */
  toolCallId: string;
}
/**
 * Session event "permission.messageAuthorization". Freezes one blinded, verbatim-verified authorization claim the runtime minted from a human user message, so a resumed session re-establishes the same grant deterministically instead of re-running the extraction model. This mints no authority on its own: it records what a blinded proposer pointed at and the trusted discriminator the runtime established, and deterministic establishment runs on replay. Persisted so recorded authority survives compaction and process resume.
 */
/** @experimental */
export interface PermissionMessageAuthorizationEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: PermissionMessageAuthorizationData;
  /**
   * 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.messageAuthorization".
   */
  type: "permission.messageAuthorization";
}
/**
 * Freezes one blinded, verbatim-verified authorization claim the runtime minted from a human user message, so a resumed session re-establishes the same grant deterministically instead of re-running the extraction model. This mints no authority on its own: it records what a blinded proposer pointed at and the trusted discriminator the runtime established, and deterministic establishment runs on replay. Persisted so recorded authority survives compaction and process resume.
 */
/** @experimental */
export interface PermissionMessageAuthorizationData {
  /**
   * The kind of effect authorized, as an action-class identifier.
   *
   * @experimental
   */
  actionClass: string;
  /**
   * Whether the claim granted or denied authority.
   *
   * @experimental
   */
  polarity: PermissionMessageAuthorizationPolarity;
  /**
   * Deterministic identity of the record, derived from the turn and span offsets so re-extracting the same span mints nothing new.
   *
   * @experimental
   */
  recordId: string;
  /**
   * End byte offset of the authorizing span within the turn.
   *
   * @experimental
   */
  spanEnd: number;
  /**
   * Start byte offset of the authorizing span within the turn.
   *
   * @experimental
   */
  spanStart: number;
  /**
   * Concrete named targets that appear verbatim inside the span.
   *
   * @experimental
   */
  targetMembers?: string[];
  /**
   * The task the permission is scoped to, when the human named one.
   *
   * @experimental
   */
  task?: string;
  /**
   * The human turn the quoted span was read from.
   *
   * @experimental
   */
  turnIndex: number;
  /**
   * The trusted version discriminator, when one exists. Exact shell-command grants carry the byte-identical commands grounded in the human span; world-derived classes carry a file object, remote tip, or runner only when that state was captured safely. An opaque object mirroring the runtime's adjacently-tagged resolution.
   *
   * @experimental
   */
  world?: JsonValue;
}
/**
 * Session event "permission.messageAuthorizationRead". Records that one human turn has been read by the blinded authorization proposer, whether or not it minted anything, so a resumed session does not re-run the extraction model on a turn the live session already read. Also records whether that pass activates ongoing extraction; contextual-assent-only passes do not, so unrelated future messages remain outside extraction.
 */
/** @experimental */
export interface PermissionMessageAuthorizationReadEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: PermissionMessageAuthorizationReadData;
  /**
   * 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.messageAuthorizationRead".
   */
  type: "permission.messageAuthorizationRead";
}
/**
 * Records that one human turn has been read by the blinded authorization proposer, whether or not it minted anything, so a resumed session does not re-run the extraction model on a turn the live session already read. Also records whether that pass activates ongoing extraction; contextual-assent-only passes do not, so unrelated future messages remain outside extraction.
 */
/** @experimental */
export interface PermissionMessageAuthorizationReadData {
  /**
   * Whether this read activates ongoing message-backed extraction. False for a contextual-assent-only pass while auto-approval is off, so unrelated future messages remain outside extraction.
   *
   * @experimental
   */
  activatesExtraction?: boolean;
  /**
   * The human turn that was read by the proposer.
   *
   * @experimental
   */
  turnIndex: number;
}
/**
 * Session event "permission.messageAuthorizationDegraded". Records that message-backed authorization could not safely represent one human turn before compaction. The runtime may compact the original message after this marker is durable, but message-derived carry-forward and assisted auto-approval remain disabled for the rest of the session so subsequent commands continue through the ordinary permission prompt.
 */
/** @experimental */
export interface PermissionMessageAuthorizationDegradedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: PermissionMessageAuthorizationDegradedData;
  /**
   * 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.messageAuthorizationDegraded".
   */
  type: "permission.messageAuthorizationDegraded";
}
/**
 * Records that message-backed authorization could not safely represent one human turn before compaction. The runtime may compact the original message after this marker is durable, but message-derived carry-forward and assisted auto-approval remain disabled for the rest of the session so subsequent commands continue through the ordinary permission prompt.
 */
/** @experimental */
export interface PermissionMessageAuthorizationDegradedData {
  /**
   * The human turn that could not be represented safely.
   *
   * @experimental
   */
  turnIndex: number;
}
/**
 * Session event "permission.assentDetected". Records that deterministic text recognition found likely assent in the human turn immediately following a root Autopilot permission request that was blocked because no interactive response was available. This event grants no authority; its model-facing projection only suggests retrying the unchanged operation.
 */
/** @experimental */
export interface PermissionAssentDetectedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: PermissionAssentDetectedData;
  /**
   * 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.assentDetected".
   */
  type: "permission.assentDetected";
}
/**
 * Records that deterministic text recognition found likely assent in the human turn immediately following a root Autopilot permission request that was blocked because no interactive response was available. This event grants no authority; its model-facing projection only suggests retrying the unchanged operation.
 */
/** @experimental */
export interface PermissionAssentDetectedData {
  /**
   * Permission request the likely assent may refer to. The runtime derives this from the preceding durable blocker; the human message and extraction model do not choose it.
   *
   * @experimental
   */
  requestId: string;
  /**
   * Human turn whose text triggered the deterministic assent recognizer.
   *
   * @experimental
   */
  turnIndex: number;
}
/**
 * Session event "permission.contextualAuthorization". Freezes a blinded contextual authorization proposal whose verbatim human span was deterministically bound to the immediately preceding blocked permission request. The event carries no action fields; replay re-derives the exact action from the earlier permission request and mints a one-shot message grant only when the binding and span still verify.
 */
/** @experimental */
export interface PermissionContextualAuthorizationEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: PermissionContextualAuthorizationData;
  /**
   * 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.contextualAuthorization".
   */
  type: "permission.contextualAuthorization";
}
/**
 * Freezes a blinded contextual authorization proposal whose verbatim human span was deterministically bound to the immediately preceding blocked permission request. The event carries no action fields; replay re-derives the exact action from the earlier permission request and mints a one-shot message grant only when the binding and span still verify.
 */
/** @experimental */
export interface PermissionContextualAuthorizationData {
  /**
   * Whether the contextual human span granted or denied authority.
   *
   * @experimental
   */
  polarity: PermissionMessageAuthorizationPolarity;
  /**
   * Deterministic identity of the contextual message grant.
   *
   * @experimental
   */
  recordId: string;
  /**
   * Original blocked permission request selected by deterministic event ordering, never by the extraction model.
   *
   * @experimental
   */
  requestId: string;
  /**
   * End byte offset of the contextual decision span within the turn.
   *
   * @experimental
   */
  spanEnd: number;
  /**
   * Start byte offset of the contextual decision span within the turn.
   *
   * @experimental
   */
  spanStart: number;
  /**
   * Human turn containing the contextual decision.
   *
   * @experimental
   */
  turnIndex: number;
}
/**
 * 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]: JsonValue | 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;
}
/**
 * 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: JsonValue;
  /**
   * 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;
}
/**
 * Optional source-defined string identifiers describing the payload subject
 */
export interface CustomNotificationSubject {
  [k: string]: string | undefined;
}
/**
 * Session event "ui.ephemeral_query". Ordered output and terminal state for a transient query that does not modify conversation history.
 */
/** @experimental */
export interface UIEphemeralQueryEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: UIEphemeralQueryData;
  /**
   * 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 "ui.ephemeral_query".
   */
  type: "ui.ephemeral_query";
}
/**
 * Ordered output and terminal state for a transient query that does not modify conversation history.
 */
/** @experimental */
export interface UIEphemeralQueryData {
  /**
   * Full response text, present for the `completed` phase.
   */
  answer?: string;
  /**
   * Ordered text delta, present for the `chunk` phase.
   */
  chunk?: string;
  /**
   * Model or transport failure message, present for the `failed` phase.
   */
  error?: string;
  phase: UIEphemeralQueryPhase;
  /**
   * Runtime-minted query identifier.
   */
  requestId: string;
}
/**
 * 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?: JsonValue;
  /**
   * Stable provider identity captured with an extension-owned tool definition; hosts use it to route the request to the same provider that was offered to the model
   */
  providerId?: string | null;
  /**
   * 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 {
  /**
   * Models offered to the router for this resolution
   */
  availableModels?: string[];
  /**
   * 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;
  /**
   * The chosen model's score shortfall relative to the top candidate
   */
  chosenShortfall?: number;
  /**
   * Classifier confidence for the predicted label, when available
   */
  confidence?: number;
  /**
   * End-to-end client wait time for the router request in milliseconds
   */
  endToEndLatencyMs?: number;
  /**
   * Whether the router fell back to the standard Auto selection
   */
  fallback?: boolean;
  /**
   * Server-provided reason for falling back, when available
   */
  fallbackReason?: string;
  /**
   * Whether the routed prompt contained an image
   */
  hasImage?: boolean;
  /**
   * The predicted classifier label (e.g. `needs_reasoning`), when available
   */
  predictedLabel?: string;
  reasoningBucket?: AutoModeResolvedReasoningBucket;
  /**
   * Server-reported router processing time in milliseconds
   */
  routerLatencyMs?: number;
  /**
   * The routing method the server applied, when Auto Intent ran
   */
  routingMethod?: string;
  /**
   * Whether a sticky model choice overrode the router result
   */
  stickyOverride?: boolean;
}
/**
 * Session event "session.managed_settings_resolved". Enterprise managed-settings resolution: the effective managed settings the session applied and which channels contributed, so SDK clients can show users what is enterprise-managed. 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. Device values take precedence over server values, then the policy helper, per ordinary key, while permissions compose restrictively across device, server, policy-helper, and SDK-client layers. The account-scoped `getManagedSettings()` API does not include session-local client injection. 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 which channels contributed, so SDK clients can show users what is enterprise-managed. 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. Device values take precedence over server values, then the policy helper, per ordinary key, while permissions compose restrictively across device, server, policy-helper, and SDK-client layers. The account-scoped `getManagedSettings()` API does not include session-local client injection. 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 a session-local permissions layer injected by the SDK host was present
   */
  clientManaged?: boolean;
  /**
   * Whether an actual 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 at least two managed sources supplied permission allowlists, so enforcement intersects them and the flattened settings payload omits `permissions.allow`.
   */
  permissionsAllowIntersected?: boolean;
  /**
   * Whether the policy-helper managed-settings layer was present. The policy helper is the weakest channel: it fills keys no enterprise source set and can never replace one.
   */
  policyHelperManaged?: boolean;
  /**
   * Whether the effective sandbox policy forces the sandbox on *only* because managed policy could not be determined, rather than because the policy requires it. Lets clients tell a user whose `--no-sandbox` was overridden that the sandbox stayed on as a fail-closed fallback, instead of attributing it to an administrator who set no such policy.
   */
  sandboxEnabledByUndeterminedPolicy?: boolean;
  /**
   * 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?: JsonValue;
  source: ManagedSettingsResolvedSource;
}
/**
 * Session event "session.managed_settings_enforced". Runtime enforcement of enterprise managed settings: fires when the session blocks or caps a runtime action because enterprise policy governs it, so SDK clients can explain *why* an action was governed. Unlike `session.managed_settings_resolved` (which reports *what* is managed), this reports a concrete governed action — e.g. a user or host tried to turn on a bypass-permissions escalation while policy disables it. Emitted live (not persisted to the session event log) on user/host-initiated attempts only, never for silent policy application. Marked experimental while the managed-settings surface stabilizes.
 */
/** @experimental */
export interface ManagedSettingsEnforcedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: ManagedSettingsEnforcedData;
  /**
   * 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_enforced".
   */
  type: "session.managed_settings_enforced";
}
/**
 * Runtime enforcement of enterprise managed settings: fires when the session blocks or caps a runtime action because enterprise policy governs it, so SDK clients can explain *why* an action was governed. Unlike `session.managed_settings_resolved` (which reports *what* is managed), this reports a concrete governed action — e.g. a user or host tried to turn on a bypass-permissions escalation while policy disables it. Emitted live (not persisted to the session event log) on user/host-initiated attempts only, never for silent policy application. Marked experimental while the managed-settings surface stabilizes.
 */
/** @experimental */
export interface ManagedSettingsEnforcedData {
  action: ManagedSettingsEnforcedAction;
  escalation?: ManagedSettingsEnforcedEscalation;
  /**
   * Whether the enforcement was forced by fail-closed handling (managed policy could not be determined) rather than an explicit managed setting. When true, `setting` still names the restriction that was applied.
   */
  failClosed: boolean;
  /**
   * A human-readable explanation of why the action was governed, suitable for surfacing to the user.
   */
  message: string;
  /**
   * The managed setting key responsible for the enforcement (e.g. `permissions.disableBypassPermissionsMode`).
   */
  setting: string;
}
/**
 * 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[];
  /**
   * Model the session had selected when the plan was authored, when one is known
   */
  model?: string;
  /**
   * 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 "factory.run_updated". Ephemeral invalidation signal for a changed factory run.
 */
/** @experimental */
export interface FactoryRunUpdatedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: FactoryRunUpdatedData;
  /**
   * 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 "factory.run_updated".
   */
  type: "factory.run_updated";
}
/**
 * Ephemeral invalidation signal for a changed factory run.
 */
/** @experimental */
export interface FactoryRunUpdatedData {
  /**
   * Monotonic revision now available for the run.
   */
  revision: number;
  /**
   * Factory run identifier.
   */
  runId: string;
}
/**
 * Session event "factory.run_started". Ephemeral signal that a factory run attempt began executing.
 */
/** @experimental */
export interface FactoryRunStartedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: FactoryRunStartedData;
  /**
   * 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 "factory.run_started".
   */
  type: "factory.run_started";
}
/**
 * Ephemeral signal that a factory run attempt began executing.
 */
/** @experimental */
export interface FactoryRunStartedData {
  /**
   * Attempt number this start committed; a resumed run increments it.
   */
  attempt: number;
  /**
   * Name of the factory this run executes. Low cardinality by construction.
   */
  factoryName: string;
  /**
   * Identifier of the factory run that started.
   */
  runId: string;
}
/**
 * Session event "factory.run_settled". Ephemeral signal that a factory run reached a terminal status.
 */
/** @experimental */
export interface FactoryRunSettledEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: FactoryRunSettledData;
  /**
   * 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 "factory.run_settled".
   */
  type: "factory.run_settled";
}
/**
 * Ephemeral signal that a factory run reached a terminal status.
 */
/** @experimental */
export interface FactoryRunSettledData {
  /**
   * AI credits this run consumed, in nano-AIU.
   */
  consumedNanoAiu: number;
  /**
   * Subagents this run consumed against its limits.
   */
  consumedSubagents: number;
  /**
   * Active milliseconds accumulated across every attempt of this run.
   */
  elapsedMs: number;
  /**
   * Typed failure class recorded on the run, when it failed with one (e.g. `factory_limit_reached`).
   */
  failureType?: string;
  /**
   * Identifier of the factory run that settled.
   */
  runId: string;
  status: FactoryRunSettledStatus;
}
/**
 * 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;
  /**
   * Canonical slash command name used to invoke the skill, without the leading '/'
   */
  commandName?: 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 authored model configuration.
 */
export interface CustomAgentsUpdatedAgent {
  /**
   * Description of what the agent does
   */
  description: string;
  /**
   * Whether model-driven invocation is disabled for this agent.
   */
  disableModelInvocation?: boolean;
  /**
   * Human-readable display name
   */
  displayName: string;
  /**
   * Unique identifier for the agent
   */
  id: string;
  /**
   * Model override for this agent, if set
   */
  model?: string;
  modelPolicy?: AgentModelPolicy;
  /**
   * Authored model ids in priority order, if configured
   */
  models?: 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 {
  /**
   * Human-readable display name supplied by a managed server catalog.
   */
  displayName?: string;
  /**
   * 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;
  serverMetadata?: McpServerMetadata;
  source?: McpServerSource;
  status: McpServerStatus;
  transport?: McpServerTransport;
}
/**
 * Server-advertised metadata learned through modern discovery or legacy initialization.
 */
export interface McpServerMetadata {
  /**
   * Non-empty natural-language guidance for using the server, or null when the server omitted instructions or advertised an empty string.
   */
  instructions: string | null;
}
/**
 * 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 "session.mcp_server_removed". Payload of `session.mcp_server_removed` identifying an MCP server the graph no longer runs.
 */
export interface McpServerRemovedEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: McpServerRemovedData;
  /**
   * 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_removed".
   */
  type: "session.mcp_server_removed";
}
/**
 * Payload of `session.mcp_server_removed` identifying an MCP server the graph no longer runs.
 */
export interface McpServerRemovedData {
  /**
   * Name of the MCP server that was removed from the graph
   */
  serverName: string;
}
/**
 * Session event "session.mcp_server_needs_reconnect". Payload of `session.mcp_server_needs_reconnect` identifying an MCP server whose connection must be re-established.
 */
export interface McpServerNeedsReconnectEvent {
  /**
   * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
   */
  agentId?: string;
  data: McpServerNeedsReconnectData;
  /**
   * 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_needs_reconnect".
   */
  type: "session.mcp_server_needs_reconnect";
}
/**
 * Payload of `session.mcp_server_needs_reconnect` identifying an MCP server whose connection must be re-established.
 */
export interface McpServerNeedsReconnectData {
  /**
   * Name of the MCP server that needs to reconnect
   */
  serverName: string;
}
/**
 * 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?: JsonValue;
  /**
   * 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?: JsonValue;
}
/**
 * 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?: JsonValue;
  /**
   * 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?: JsonValue;
  /**
   * 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]: JsonValue | 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]: JsonValue | 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[];
}