@skaile/workspaces 0.8.5

package/dist/types/src/events.d.ts

@@ -0,0 +1,1075 @@
+/**
+ * Agent Events — the unified event stream.
+ *
+ * These are the real-time events emitted by agent drivers (bridge, vm-agent)
+ * and consumed by runners, gateways, and frontends. Persistent events are
+ * wrapped in a {@link Message} envelope by the host's persistence layer.
+ */
+import type { CapabilityDeregisterEvent, CapabilityInvokedEvent, CapabilityRegisterEvent, RenderInvokedEvent } from "./capabilities.js";
+import type { IncompatibleProtocolEvent, ProtocolInfoEvent, SessionInitAckEvent, SessionInitMismatchEvent } from "./lifecycle.js";
+import type { LogEntry } from "./logging.js";
+/**
+ * Discriminated union of every event the Skaile agent runtime can emit.
+ *
+ * Persistent events are wrapped in a `MessageV2` envelope by the host's persistence
+ * layer. Transient events are forwarded over the transport but not appended to the
+ * message store. Narrow via `event.type` or a `switch` statement.
+ *
+ * @docLink packages/types/events#agent-event
+ */
+export type AgentEvent = TextEvent | ToolCallEvent | ToolResultEvent | QuestionEvent | QuestionReplyEvent | ErrorEvent | StatusEvent | DevServerEvent | FileChangeEvent | SubagentEvent | FinishedEvent | StateChangedEvent | HandoffEvent | ConnectorResponseEvent | ConnectorQueryResponseEvent | ConnectorsAvailableEvent | LifecycleCompleteEvent | TypingEvent | UserMessageEvent | SyncStatusEvent | SecretsReadyEvent | ConfiguredEvent | MountMountedEvent | MountUnmountedEvent | MountChangedEvent | MountSyncStatusEvent | DebugResultEvent | LogEntryEvent | ValidationWarningEvent | SkillsChangedEvent | CommandsAvailableEvent | FlowBreadcrumbEvent | SessionInfoEvent | ReactionAddedEvent | ReactionRemovedEvent | ResourceStatusEvent | ConnectorStatusEvent | CustomMessageEvent | SnapshotEvent | CompactionAttemptEvent | ResumeAttemptedEvent | ResumeFailedEvent | CapabilityRegisterEvent | CapabilityDeregisterEvent | CapabilityInvokedEvent | RenderInvokedEvent | ProtocolInfoEvent | IncompatibleProtocolEvent | SessionInitAckEvent | SessionInitMismatchEvent | SystemPromptComposedEvent;
+/**
+ * A text message from the agent to the user.
+ *
+ * The most common event type, containing plain-text content generated by the agent.
+ *
+ * @docLink packages/types/events#text-event
+ */
+export type TextEvent = {
+    type: "text";
+    content: string;
+};
+/**
+ * A tool call request from the agent.
+ *
+ * Indicates the agent wants to invoke a tool with the given name and input arguments.
+ * The platform should execute the tool and return the result via {@link ToolResultEvent}.
+ *
+ * @property tool - The name of the tool to invoke (must match a registered tool)
+ * @property input - The input arguments to pass to the tool (structure depends on the tool)
+ * @property summary - Short human-readable summary of the tool call
+ *
+ * @see {@link TextEvent} for plain text messages
+ * @see {@link ToolResultEvent} for tool execution results
+ * @category Events
+ * @since 1.0.0
+ * @docLink packages/types/events#tool-call-event
+ */
+export type ToolCallEvent = {
+    type: "tool_call";
+    tool: string;
+    input: unknown;
+    summary: string;
+};
+/**
+ * The result of a tool execution.
+ *
+ * Contains the output returned by a tool after it has been executed.
+ * This event is typically sent by the platform in response to a {@link ToolCallEvent}.
+ *
+ * @property tool - The name of the tool that was executed
+ * @property output - The result data returned by the tool (structure depends on the tool)
+ * @property summary - Short human-readable summary of the result
+ *
+ * @see {@link ToolCallEvent} for the corresponding tool invocation
+ * @category Events
+ * @since 1.0.0
+ * @docLink packages/types/events#tool-result-event
+ */
+export type ToolResultEvent = {
+    type: "tool_result";
+    tool: string;
+    output: unknown;
+    summary: string;
+};
+/**
+ * A question posed by the agent to the user.
+ *
+ * Used when the agent needs clarification or input from the user to proceed.
+ * The question may include multiple-choice options to guide the user's response.
+ *
+ * @property question - The question text to display to the user
+ * @property options - Optional array of suggested answers (when provided, user should select one)
+ *
+ * @see {@link QuestionReplyEvent} for the user's response
+ * @category Events
+ * @since 1.0.0
+ * @docLink packages/types/events#question-event
+ */
+export type QuestionEvent = {
+    type: "question";
+    question: string;
+    options?: string[];
+};
+/**
+ * The user's reply to a question asked by the agent.
+ *
+ * Sent in response to a {@link QuestionEvent} when the user provides an answer.
+ *
+ * @property answer - The user's response text
+ *
+ * @see {@link QuestionEvent} for the original question
+ * @category Events
+ * @since 1.0.0
+ * @docLink packages/types/events#question-event
+ */
+export type QuestionReplyEvent = {
+    type: "question_reply";
+    answer: string;
+};
+/**
+ * An error condition encountered during agent execution.
+ *
+ * Indicates something went wrong during the agent's operation.
+ * The severity determines whether execution can continue.
+ *
+ * @property message - Human-readable description of the error
+ * @property fatal - When true, indicates the error is unrecoverable and execution should stop
+ *
+ * @category Events
+ * @since 1.0.0
+ * @docLink packages/types/events#error-event
+ */
+export type ErrorEvent = {
+    type: "error";
+    message: string;
+    fatal: boolean;
+    category?: ErrorCategory;
+    /**
+     * Short actionable advice for display to the user. Set by the bridge's
+     * error classifier when it recognises the upstream failure mode (e.g.
+     * "Quota exhausted on the configured Anthropic account — try again
+     * after the rate-limit window resets"). Optional.
+     */
+    hint?: string;
+};
+/**
+ * A status change notification for the agent.
+ *
+ * Emitted when the agent's execution phase changes (e.g., thinking → working → idle).
+ *
+ * @see {@link AgentPhase} for available phase values
+ * @category Events
+ * @since 1.0.0
+ * @docLink packages/types/events#supporting-types
+ */
+export type StatusEvent = {
+    type: "status";
+    phase: AgentPhase;
+};
+/**
+ * Emitted when a dev server (e.g. Vite, Next.js) starts, becomes ready, or crashes.
+ *
+ * The platform uses this to surface a preview URL in the session UI.
+ *
+ * @category Events
+ * @since 1.0.0
+ * @docLink packages/types/events#agent-event
+ */
+export type DevServerEvent = {
+    type: "dev_server";
+    url: string;
+    status: "starting" | "ready" | "crashed";
+};
+/**
+ * A file system change event.
+ *
+ * Emitted when files are created, edited, deleted, or conflicted.
+ *
+ * @property type - Always "file_changed"
+ * @property path - The file path that changed
+ * @property action - What happened: create, edit, delete, or conflict
+ * @property mountId - Which mount triggered the change, if any
+ *
+ * @category Events
+ * @since 1.0.0
+ * @docLink packages/types/events#file-change-event
+ */
+export type FileChangeEvent = {
+    type: "file_changed";
+    path: string;
+    action: "create" | "edit" | "delete" | "conflict";
+    /** Which mount triggered the change, if any. */
+    mountId?: string;
+};
+/**
+ * Status update for a subagent dispatched by the primary agent.
+ *
+ * Emitted when a named subagent starts or finishes execution. On "finished",
+ * carries structured output with a summary, changed files, and concerns.
+ *
+ * @docLink packages/types/events#agent-event
+ */
+export type SubagentEvent = {
+    type: "subagent";
+    name: string;
+    status: "started" | "finished";
+    description: string;
+    /** Flow node this subagent is executing (set by orchestrator) */
+    nodeId?: string;
+    /** Structured output from the subagent (set on "finished") */
+    output?: {
+        summary: string;
+        filesChanged: string[];
+        status: string;
+        concerns: string[];
+    };
+};
+/**
+ * Per-turn token usage reported by a driver.
+ *
+ * All fields are optional so the type can represent partial data — different
+ * providers expose different subsets:
+ *
+ * | Provider  | input | output | cacheRead | cacheCreation | reasoning |
+ * |-----------|-------|--------|-----------|---------------|-----------|
+ * | Anthropic |   y   |   y    |     y     |       y       |     -     |
+ * | OpenAI    |   y*  |   y    |     y     |       -       |     y     |
+ *
+ * `*` Anthropic's `inputTokens` excludes cached/cache-creation reads (they
+ * are reported separately). OpenAI's `inputTokens` is the *total* including
+ * cached tokens — consumers that want a strict "fresh input" count must
+ * subtract `cacheReadTokens` themselves.
+ *
+ * @category Cost
+ * @since 3.1.0
+ * @docLink packages/types/events#token-usage
+ */
+export type TokenUsage = {
+    /** Input/prompt tokens consumed by the turn (provider-specific semantics — see type docstring). */
+    inputTokens?: number;
+    /** Output/completion tokens generated by the model. */
+    outputTokens?: number;
+    /** Tokens served from the provider's prompt cache (Anthropic: cache_read_input_tokens; OpenAI: cached_input_tokens). */
+    cacheReadTokens?: number;
+    /** Tokens written to the prompt cache for future reads (Anthropic-only — OpenAI does not expose this). */
+    cacheCreationTokens?: number;
+    /** Reasoning tokens consumed by OpenAI reasoning models (o1, o3, ...). */
+    reasoningTokens?: number;
+    /** Total tokens for the turn when the provider supplies one. */
+    totalTokens?: number;
+};
+/**
+ * Emitted when the agent completes a turn.
+ *
+ * Carries cost / usage data and optionally a custom message payload for dynamic
+ * rendering via the v2 capability registry (`customType` + `customData` fields).
+ *
+ * `costUsd` semantics: Anthropic's SDK reports per-turn cost in USD natively
+ * (passed through). Drivers that do not surface a provider-reported cost emit
+ * `0` — consumers that distinguish "free" from "not reported" should pair
+ * `costUsd === 0` with `tokens` being present/absent.
+ *
+ * @docLink packages/types/events#finished-event
+ */
+export type FinishedEvent = {
+    type: "finished";
+    summary: string;
+    costUsd: number;
+    /**
+     * Per-turn token usage when the driver tracks it. Absent for drivers
+     * that do not surface usage (e.g. omp RPC today). Added in 3.1.0.
+     */
+    tokens?: TokenUsage;
+    /** True when the response was cancelled by the user (partial content). */
+    cancelled?: boolean;
+    /** Custom message type (e.g. "gif") — clients render via a registered dynamic component. */
+    customType?: string;
+    /** Structured data for custom message types — used as component props. */
+    customData?: Record<string, unknown>;
+};
+/**
+ * Emitted when a shared state store's snapshot changes.
+ *
+ * Carries the full serialized state snapshot for the named store (e.g. "flow", "session").
+ * Frontends and the platform gateway subscribe to build reactive state views.
+ *
+ * @docLink packages/types/events#agent-event
+ */
+export type StateChangedEvent = {
+    type: "state_changed";
+    /** Store identifier, e.g. "flow", "session" */
+    store: string;
+    /** Serialized state snapshot */
+    state: Record<string, unknown>;
+};
+/**
+ * Emitted when the orchestrator hands execution off to a specific flow node and skill.
+ *
+ * Carries the context sources and approximate context size used to curate
+ * the handoff prompt so operators can diagnose context-window decisions.
+ *
+ * @docLink packages/types/events#agent-event
+ */
+export type HandoffEvent = {
+    type: "handoff";
+    /** Flow node being handed off to */
+    nodeId: string;
+    /** Skill being executed */
+    skillId: string;
+    /** Node IDs that contributed context to this handoff */
+    contextSources: string[];
+    /** Approximate size of curated context in characters */
+    contextSize: number;
+};
+/**
+ * Response to a `ConnectorRequestCommand` (wire type: `"resource_response"`).
+ *
+ * Correlates to the originating request via `requestId` and carries the
+ * operation result or an error string. The wire `type:` string stays as
+ * `"resource_response"` for protocol stability.
+ *
+ * @docLink packages/types/events#agent-event
+ */
+export type ConnectorResponseEvent = {
+    type: "resource_response";
+    /** Correlates to the originating resource_request. */
+    requestId: string;
+    /** Which connector handled the request. */
+    resourceId: string;
+    /** Which operation was performed. */
+    operation: ConnectorOperation;
+    /** Result data — shape depends on the operation. */
+    data?: unknown;
+    /** Error message if the operation failed. */
+    error?: string;
+};
+/**
+ * Response to a `ConnectorQueryCommand`. Carries the JSON-encoded result of
+ * a `ConnectorManager.executeOp` call, correlated by `requestId`.
+ *
+ * Persistence: transient. Hosts that want to record the query side effects
+ * should rely on the runner's structured log stream, not on this event.
+ *
+ * @docLink packages/types/events#connector-query-response-event
+ * @since 2.2.0
+ */
+export type ConnectorQueryResponseEvent = {
+    type: "connector_query_response";
+    /** Correlates to the originating ConnectorQueryCommand. */
+    requestId: string;
+    /** Whether the underlying executeOp resolved without throwing. */
+    ok: boolean;
+    /** JSON-encoded executeOp result, when `ok === true`. */
+    result?: string;
+    /** Error message when `ok === false`. */
+    error?: string;
+};
+/**
+ * Emitted after session boot listing all connected mounts and connectors.
+ *
+ * Consumers use this event to populate the resource explorer and build initial
+ * connector status maps. The wire type is `"resources_available"`.
+ *
+ * @docLink packages/types/events#agent-event
+ */
+export type ConnectorsAvailableEvent = {
+    type: "resources_available";
+    /** All connected mounts with their metadata. */
+    mounts: MountInfo[];
+    /** All connected connectors with their metadata. */
+    connectors: ConnectorInfo[];
+};
+/**
+ * Emitted whenever a connector's connection state changes.
+ *
+ * Transient — not persisted to the message store. Consumed exclusively by
+ * `ResourceClient._handleEvent()` in `@skaile/workspaces/store` to maintain the
+ * reactive `connectorStatus` map.
+ *
+ * @docLink packages/types/events#connector-status-event
+ */
+export interface ConnectorStatusEvent {
+    type: "connector_status";
+    /** Matches ConnectorDeclaration.id. */
+    connectorId: string;
+    /** Current connection state. */
+    status: "connecting" | "connected" | "error" | "disconnected";
+    /** Present when status === "error". */
+    error?: string;
+    /** Round-trip latency in milliseconds from the last health check. */
+    latencyMs?: number;
+}
+/**
+ * Emitted when a lifecycle phase (hibernate, close, compact) completes across all resources.
+ *
+ * Carries per-resource results so the platform can surface which resources failed
+ * during the phase. The `phase` field identifies which lifecycle stage completed.
+ *
+ * @docLink packages/types/events#agent-event
+ */
+export type LifecycleCompleteEvent = {
+    type: "lifecycle_complete";
+    /** Which lifecycle phase completed. */
+    phase: LifecyclePhase;
+    /** Per-resource results. */
+    results: LifecycleResult[];
+};
+/**
+ * Transient — broadcast when a user or agent adds an emoji reaction to a message.
+ *
+ * Not persisted as a message. Consumed by frontends to update the reaction display in real time.
+ *
+ * @docLink packages/types/events#reaction-events
+ */
+export type ReactionAddedEvent = {
+    type: "reaction_added";
+    /** ID of the message being reacted to. */
+    messageId: string;
+    /** Sequence number of the target message (for efficient frontend lookup). */
+    messageSeq: number;
+    emoji: string;
+    userId: string;
+    userName: string;
+};
+/**
+ * Transient — broadcast when a user removes a reaction from a message.
+ *
+ * Not persisted as a message. Consumed by frontends to update the reaction display in real time.
+ *
+ * @docLink packages/types/events#reaction-events
+ */
+export type ReactionRemovedEvent = {
+    type: "reaction_removed";
+    messageId: string;
+    messageSeq: number;
+    emoji: string;
+    userId: string;
+};
+/**
+ * Transient typing indicator — not persisted.
+ *
+ * Broadcast to all session subscribers when a participant starts or stops typing.
+ * Frontends use this to render the "X is typing..." indicator.
+ *
+ * @docLink packages/types/events#typing-user-message-secrets-ready-configured-events
+ */
+export type TypingEvent = {
+    type: "typing";
+    userId: string;
+    userName: string;
+    isTyping: boolean;
+};
+/**
+ * Transient echo of a user message broadcast to all session subscribers — not persisted.
+ *
+ * Carries reply-threading fields so clients can detect parent-message relationships
+ * and route mention-style notifications.
+ *
+ * @docLink packages/types/events#typing-user-message-secrets-ready-configured-events
+ */
+export type UserMessageEvent = {
+    type: "user_message";
+    senderId: string;
+    senderName: string;
+    content: string;
+    /** Set when this user message is a reply to a previous message. */
+    parentMessageId?: string;
+    /** Sender id of the parent message — lets clients detect "reply to me". */
+    parentSenderId?: string;
+    /** When true, clients should treat this reply as a mention-style notification target. */
+    notifyParent?: boolean;
+    /**
+     * Routing mode of the message envelope.
+     *  - `"Public"` (default when omitted) — broadcast to every session
+     *    subscriber (humans + agent).
+     *  - `"Private"` — visible only to the sender plus everyone listed in
+     *    `privateRecipientIds`.
+     *  - `"HumansOnly"` — visible to all human subscribers; the agent is
+     *    excluded from broadcast and notifications.
+     *
+     * **Invariant (NOT enforced by the type system):** producers MUST populate
+     * a non-empty `privateRecipientIds` whenever this is `"Private"`. The
+     * shape is intentionally flat (rather than a discriminated union) to
+     * keep wire compat with older consumers, but this means TypeScript will
+     * not catch violations at the call site. **Persistence-layer
+     * implementations MUST validate this invariant on intake** and reject /
+     * downgrade / log a violation rather than persist a Private message
+     * with no recipients (which would be visible to nobody and effectively
+     * lost).
+     *
+     * Reference platform implementation: `PlatformMessageStore.append`
+     * throws on `Private + empty recipientIds` to fail fast.
+     */
+    visibilityMode?: "Public" | "Private" | "HumansOnly";
+    /**
+     * Recipient list for `visibilityMode: "Private"`. Each entry is either a
+     * user id (matching the platform's user-id shape) or the sentinel
+     * `"__agent__"` when the agent itself is an explicit recipient (i.e. the
+     * sender wrote `@agent_`).
+     *
+     * MUST be non-empty when `visibilityMode === "Private"` — see the
+     * invariant note on `visibilityMode` above.
+     *
+     * Empty / absent for `Public` and `HumansOnly` — recipient sets in those
+     * modes are implicit (everyone / everyone-except-agent).
+     */
+    privateRecipientIds?: string[];
+};
+/**
+ * Transient signal that provisioned secrets have been stored and resources initialized.
+ *
+ * The platform waits for this event after sending a `SecretProvisionCommand` before
+ * allowing further session interaction.
+ *
+ * @docLink packages/types/events#typing-user-message-secrets-ready-configured-events
+ */
+export type SecretsReadyEvent = {
+    type: "secrets_ready";
+};
+/**
+ * Transient ACK emitted once the agent has finished processing a `configure`
+ * command (shared state stores registered, MCP tools rebuilt, active flows
+ * rehydrated). Backends await this before releasing the session so prompts
+ * can't race the configure handler and start the driver with stale tools.
+ *
+ * @docLink packages/types/events#typing-user-message-secrets-ready-configured-events
+ */
+export type ConfiguredEvent = {
+    type: "configured";
+};
+/**
+ * Emitted when a mount is successfully attached to the workspace.
+ *
+ * Carries the mount id, filesystem path, driver name, and access level.
+ *
+ * @docLink packages/types/events#agent-event
+ */
+export type MountMountedEvent = {
+    type: "mount_mounted";
+    id: string;
+    mountPath: string;
+    driver: string;
+    access: string;
+};
+/**
+ * Emitted when a mount is detached from the workspace.
+ *
+ * @docLink packages/types/events#agent-event
+ */
+export type MountUnmountedEvent = {
+    type: "mount_unmounted";
+    id: string;
+};
+/**
+ * Emitted when a file changes within a mounted source.
+ *
+ * Similar to `FileChangeEvent` but scoped to a specific mount by `id`.
+ *
+ * @docLink packages/types/events#agent-event
+ */
+export type MountChangedEvent = {
+    type: "mount_changed";
+    id: string;
+    path: string;
+    action: "create" | "edit" | "delete" | "conflict";
+};
+/**
+ * Progress update for a mount's initial synchronization phase.
+ *
+ * Emitted repeatedly during the sync lifecycle (enumerating, stubs_ready,
+ * downloading, initial_sync_complete). Carries file counts for progress display.
+ *
+ * @docLink packages/types/events#agent-event
+ */
+export type MountSyncStatusEvent = {
+    type: "mount_sync_status";
+    id: string;
+    phase: SyncStatusPhase;
+    totalFiles: number;
+    downloadedFiles: number;
+    stubFiles: number;
+    message: string;
+};
+/**
+ * Persisted chat event summarizing a flow lifecycle milestone.
+ *
+ * The gateway diffs each incoming flow state_changed event against the
+ * previous snapshot and emits breadcrumbs for user-meaningful transitions
+ * — flow start/end, approval requests, input requests, and node failures.
+ * Per-node traffic (running/complete/skipped) is NOT emitted as a
+ * breadcrumb to keep the chat stream readable; that detail lives on the
+ * flow execution panel.
+ *
+ * Breadcrumbs are persisted via the dispatcher's normal message store path
+ * and rendered on the frontend as collapsed cards that expand inline.
+ *
+ * @docLink packages/types/events#flow-breadcrumb-event
+ */
+export type FlowBreadcrumbEvent = {
+    type: "flow_breadcrumb";
+    kind: "flow_started" | "flow_finished" | "flow_failed" | "flow_cancelled" | "approval_pending" | "input_pending" | "approval_resolved" | "input_resolved" | "node_failed";
+    runId: string;
+    flowId: string;
+    flowName: string;
+    /** Node that triggered this breadcrumb, if the kind is node-scoped. */
+    nodeId?: string;
+    /** Human-readable node label (from flow definition `data.label`). */
+    nodeName?: string;
+    /** User ID of the actor that caused the transition (if applicable). */
+    actorUserId?: string;
+    /** One-line summary for the collapsed card rendering. */
+    summary?: string;
+};
+/**
+ * The session lifecycle phase being executed. Carried in `LifecycleCompleteEvent.phase`
+ * and the `lifecycle` command's `phase` field.
+ *
+ * @docLink packages/types/events#supporting-types
+ */
+export type LifecyclePhase = "hibernate" | "close" | "compact";
+/**
+ * Per-resource result of a lifecycle phase, carried in `LifecycleCompleteEvent.results`.
+ *
+ * @docLink packages/types/events#supporting-types
+ */
+export type LifecycleResult = {
+    id: string;
+    ok: boolean;
+    error?: string;
+    /** Human-readable detail (e.g. commit SHA, branch name). */
+    detail?: string;
+};
+/**
+ * Metadata for a mounted filesystem source, carried in `ConnectorsAvailableEvent.mounts`.
+ *
+ * Re-declared here to avoid a dependency on `@skaile/workspaces/connectors`; mirrors the
+ * connector package's `MountInfo` type.
+ *
+ * @docLink packages/types/events#supporting-types
+ */
+export type MountInfo = {
+    id: string;
+    driver: string;
+    access: "read-only" | "read-write";
+    mountPath: string;
+    mounted: boolean;
+    source: string;
+};
+/**
+ * Operations a connector can perform. Used in `ConnectorRequestCommand.operation`
+ * and `ConnectorResponseEvent.operation`.
+ *
+ * @docLink packages/types/events#supporting-types
+ */
+export type ConnectorOperation = "list" | "read" | "write" | "delete" | "search";
+/**
+ * A single entry in a connector directory listing (result of a `list` operation).
+ *
+ * Re-declared here to avoid a dependency on `@skaile/workspaces/connectors`.
+ *
+ * @docLink packages/types/events#supporting-types
+ */
+export type ConnectorEntry = {
+    name: string;
+    path: string;
+    type: "file" | "directory" | "key" | "row" | "message";
+    size?: number;
+    modifiedAt?: string;
+};
+/**
+ * File or key content returned by a connector `read` operation.
+ *
+ * Re-declared here to avoid a dependency on `@skaile/workspaces/connectors`.
+ *
+ * @docLink packages/types/events#supporting-types
+ */
+export type ConnectorContent = {
+    data: string;
+    encoding?: "utf-8" | "binary";
+    contentType?: string;
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Metadata for a connected connector, carried in `ConnectorsAvailableEvent.connectors`.
+ *
+ * Re-declared here to avoid a dependency on `@skaile/workspaces/connectors`; mirrors
+ * the connector package's `ConnectorInfo` type.
+ *
+ * @docLink packages/types/events#supporting-types
+ */
+export type ConnectorInfo = {
+    id: string;
+    driver: string;
+    access: "read-only" | "read-write";
+    operations: string[];
+};
+/**
+ * Options for a connector `list` operation.
+ *
+ * @docLink packages/types/events#supporting-types
+ */
+export type ListOptions = {
+    recursive?: boolean;
+    glob?: string;
+    limit?: number;
+};
+/**
+ * Options for a connector `search` operation.
+ *
+ * @docLink packages/types/events#supporting-types
+ */
+export type SearchOptions = {
+    regex?: boolean;
+    caseSensitive?: boolean;
+    maxResults?: number;
+};
+/**
+ * Persistent — a custom-typed message emitted by the agent via a capability
+ * tool invocation (`platform.custom_message`). The runner's serve layer
+ * forwards these so the platform can persist and render them via the
+ * dynamic component pipeline.
+ *
+ * @category Events
+ * @since 2.0.0
+ * @docLink packages/types/events#agent-event
+ */
+export type CustomMessageEvent = {
+    type: "custom_message";
+    /** Plain-text summary (e.g. "[gif: funny cat]"). */
+    content: string;
+    /** Custom message type identifier (e.g. "gif"). */
+    customType: string;
+    /** Structured data — used as component props. */
+    customData: Record<string, unknown>;
+};
+/**
+ * Trigger source for a session compaction. Carried in `SnapshotEvent.trigger`
+ * and `CompactionAttemptEvent.trigger`.
+ *
+ * @docLink packages/types/events#snapshot-event
+ */
+export type CompactionTrigger = "threshold" | "hibernate" | "manual";
+/**
+ * Persistent — a compacted conversation snapshot produced by the LLM.
+ * On session restore, only the last snapshot + subsequent messages are replayed.
+ *
+ * @docLink packages/types/events#snapshot-event
+ */
+export type SnapshotEvent = {
+    type: "snapshot";
+    /** LLM-generated structured summary of the conversation. */
+    summary: string;
+    /** What triggered this compaction. */
+    trigger: CompactionTrigger;
+    /** Seq of previous snapshot (0 if first compaction). */
+    coversFromSeq: number;
+    /** Last seq this snapshot covers. */
+    coversToSeq: number;
+    /** Estimated context token count before compaction. */
+    tokensBefore: number;
+    /** Token count of the summary. */
+    tokensAfter: number;
+};
+/**
+ * Persistent -- emitted on EVERY compaction attempt, success or failure.
+ *
+ * Replaces the in-process circuit breaker in `CompactionOrchestrator` with
+ * an observable, owner-controllable record. The platform gateway listens
+ * for this event and inserts a `Compaction` row plus updates the
+ * `Session.lastCompactionStatus` companion field.
+ *
+ * `SnapshotEvent` continues to fire on success-only paths (back-compat
+ * until Phase 4); both events ride alongside each other through Phase 4.
+ *
+ * Spec: `_devlog/specs/2026-05-05-session-resume-restart-design.md`
+ *
+ * @category Compaction
+ * @since 3.1.0
+ * @docLink packages/types/events#compaction-attempt-event
+ */
+export type CompactionAttemptEvent = {
+    type: "compaction_attempt";
+    /**
+     * Outcome of the attempt:
+     * - `success`: completed and validated; eligible for tier-2 resume
+     * - `failed`: compaction call returned an error or output failed validation
+     * - `partial`: reserved (e.g. streaming compaction emitting partial output)
+     * - `dirty`: was success at write time but later flagged
+     */
+    status: "success" | "failed" | "partial" | "dirty";
+    /**
+     * When `status !== 'success'`, a stable identifier for the failure mode.
+     * Standard codes:
+     * - `rate_limit | auth | timeout | parse_error` (from bridge error classifier)
+     * - `empty | too_short | poor_ratio` (from validateCompactionOutput)
+     *
+     * Note: `auth` covers both real credential failures AND payment-blocked
+     * OAuth subscriptions that Anthropic mislabels as auth errors. Owners
+     * investigate further when a Compaction row shows `auth`.
+     *
+     * `null` on success.
+     */
+    errorCode: string | null;
+    /** What triggered this attempt. */
+    trigger: CompactionTrigger;
+    /** LLM-generated summary text. Empty string on failure. */
+    summary: string;
+    /** Model name used for the call (e.g. "claude-sonnet-4"). null when unknown. */
+    model: string | null;
+    /** Provider id used for the call (e.g. "anthropic"). null when unknown. */
+    provider: string | null;
+    /** Estimated input token count before the compaction call (= tokensBefore). */
+    inputTokens: number;
+    /** Output token count of the summary or 0 on failure (= tokensAfter). */
+    outputTokens: number;
+    /** Seq of previous successful snapshot (0 if first compaction). */
+    coversFromSeq: number;
+    /** Last seq this attempt covers (current message seq). */
+    coversToSeq: number;
+    /**
+     * Driver session id at the time of the call (for tier-1 native SDK resume).
+     * Captured from `driver.runtimeSessionId`. null when the driver does not
+     * expose one (e.g. echo, codex).
+     */
+    driverSessionIdAtCompaction: string | null;
+    /**
+     * Model name at compaction time. Distinct from `model` (which records what
+     * was used for THIS compaction call). For tier-1 resume, the wake-time
+     * comparison is against the driver's CURRENT model — if mismatch, falls
+     * through to tier 2.
+     */
+    modelAtCompaction: string | null;
+    /**
+     * Capability registry signature at compaction time. null in Phase 1
+     * (the `computeCapabilitySignature` helper ships in Phase 3).
+     */
+    capabilitySignatureAtCompaction: string | null;
+    /**
+     * ISO timestamp set when `validateCompactionOutput` passed.
+     * `null` when the attempt failed validation OR produced an error.
+     */
+    validatedAt: string | null;
+};
+/**
+ * Transient — emitted by the runner when it honors a
+ * `AgentReconfigureOptions.resumeSessionId` in a configure command.
+ *
+ * The runner emits this once it has decided to recreate the driver with
+ * the platform-supplied session id (after capability signature validation
+ * passes, if `expectedCapabilitySignature` was provided). The platform
+ * gateway records the attempt on the {@link Session} so the UI can show
+ * "Resumed via SDK session" when wake completes.
+ *
+ * Spec: `_devlog/specs/2026-05-05-session-resume-restart-design.md`
+ * § "Tier 1: native resume plumbing".
+ *
+ * @category Resume
+ * @since 3.2.0
+ * @docLink packages/types/events#resume-attempted-event
+ */
+export type ResumeAttemptedEvent = {
+    type: "resume_attempted";
+    /** Driver session id the runner is resuming. */
+    resumeSessionId: string;
+    /** Capability signature computed at attempt time (advisory). */
+    capabilitySignature: string;
+};
+/**
+ * Transient — emitted by the runner or driver when a tier-1 native resume
+ * could not be honored.
+ *
+ * Reasons:
+ * - `signature_mismatch`: the runner's current capability signature differs
+ *   from {@link AgentReconfigureOptions.expectedCapabilitySignature}; the
+ *   runner dropped the {@link AgentReconfigureOptions.resumeSessionId} hint
+ *   before driver creation.
+ * - `model_mismatch`: reserved — wake-time model comparison happens on the
+ *   platform side; runner does not currently emit this code, but it is
+ *   reserved for future driver-level checks.
+ * - `jsonl_lost`: emitted by the claude-sdk driver after the SDK reported
+ *   "No conversation found with session ID …"; the driver internally
+ *   fell back to `continue: true` so the wake still completes.
+ *
+ * @category Resume
+ * @since 3.2.0
+ * @docLink packages/types/events#resume-failed-event
+ */
+export type ResumeFailedEvent = {
+    type: "resume_failed";
+    /** Driver session id the runner attempted to resume (and dropped). */
+    resumeSessionId: string;
+    /** Stable reason code; see TSDoc above for the enumeration. */
+    reason: "signature_mismatch" | "model_mismatch" | "jsonl_lost";
+};
+/**
+ * Transient ACK emitted by the runner after processing an add_resource or
+ * remove_resource command. The gateway awaits this to confirm the operation
+ * completed (or failed) before returning to the caller.
+ *
+ * @docLink packages/types/events#resource-status-event
+ */
+export type ResourceStatusEvent = {
+    type: "resource_status";
+    resourceId: string;
+    status: "mounting" | "active" | "error" | "removed";
+    mountPath?: string;
+    error?: string;
+};
+/**
+ * String union of all `AgentEvent["type"]` discriminators.
+ *
+ * Useful for declaring event type constants or exhaustive switch coverage checks.
+ *
+ * @docLink packages/types/events#supporting-types
+ */
+export type AgentEventType = AgentEvent["type"];
+/**
+ * The current execution phase of the agent, carried in `StatusEvent.phase`.
+ *
+ * @docLink packages/types/events#supporting-types
+ */
+export type AgentPhase = "thinking" | "working" | "idle" | "compacting";
+/**
+ * Classification of an agent error, carried in `ErrorEvent.category`.
+ *
+ * The bridge's error classifier maps upstream errors to these categories so
+ * consumers can apply per-category retry and display policies.
+ *
+ * @docLink packages/types/events#error-event
+ */
+export type ErrorCategory = "auth" | "rate_limit" | "model" | "network" | "config" | "process" | "validation" | "unknown";
+/**
+ * Structured error object used internally when classifying driver errors.
+ *
+ * Carries the error category, an optional HTTP status code, a retryability flag,
+ * and an optional actionable hint for the user.
+ *
+ * @docLink packages/types/events#error-event
+ */
+export type AgentError = {
+    message: string;
+    category: ErrorCategory;
+    statusCode?: number;
+    retryable: boolean;
+    hint?: string;
+};
+/**
+ * Lifecycle phases of a mount's initial sync operation.
+ *
+ * Carried in `MountSyncStatusEvent.phase` and `SyncStatusEvent.phase`.
+ *
+ * @docLink packages/types/events#supporting-types
+ */
+export type SyncStatusPhase = "enumerating" | "stubs_ready" | "downloading" | "initial_sync_complete" | "error";
+/**
+ * Legacy alias for `MountSyncStatusEvent` — progress update for a mount sync operation.
+ *
+ * Carries the mount id, lifecycle phase, and file counts. Prefer `MountSyncStatusEvent`
+ * for new code.
+ *
+ * @docLink packages/types/events#supporting-types
+ */
+export type SyncStatusEvent = {
+    type: "sync_status";
+    mountId: string;
+    phase: SyncStatusPhase;
+    totalFiles: number;
+    downloadedFiles: number;
+    stubFiles: number;
+    message: string;
+};
+/**
+ * Transient response to a `DebugCommand` — not persisted.
+ *
+ * Carries the original query string and the raw diagnostic data returned
+ * by the runner's debug handler.
+ *
+ * @docLink packages/types/events#debug-result-event
+ */
+export type DebugResultEvent = {
+    type: "debug_result";
+    query: string;
+    data: unknown;
+};
+/**
+ * Transient — a single structured log entry from the in-container LogStore.
+ * Forwarded by the runner's WsLogSink over the agent transport. The gateway
+ * caches a fixed-size ring of these per session for late panel openers.
+ * NEVER persisted to the message store — historical reads go through SQLite.
+ *
+ * @docLink packages/types/events#log-entry-event
+ */
+export type LogEntryEvent = {
+    type: "log_entry";
+    entry: LogEntry;
+};
+/**
+ * Transient — emitted when an asset fails schema validation during discovery.
+ *
+ * Carries the asset name, reason, and an optional suggestion for fixing the issue.
+ * Not persisted.
+ *
+ * @docLink packages/types/events#agent-event
+ */
+export type ValidationWarningEvent = {
+    type: "validation_warning";
+    asset: string;
+    reason: string;
+    suggestion?: string;
+};
+/**
+ * Transient — emitted when the skills catalog changes during a session.
+ *
+ * Carries the list of skills that were added or removed. Not persisted.
+ *
+ * @docLink packages/types/events#agent-event
+ */
+export type SkillsChangedEvent = {
+    type: "skills_changed";
+    skills: Array<{
+        name: string;
+        action: string;
+    }>;
+};
+/**
+ * Transient event carrying the agent's discovered slash commands — not persisted.
+ *
+ * Emitted after the runner discovers the available commands from skills and MCP servers.
+ * Frontends use this to populate the slash-command picker.
+ *
+ * @docLink packages/types/events#commands-available-event
+ */
+export type CommandsAvailableEvent = {
+    type: "commands_available";
+    commands: Array<{
+        name: string;
+        description: string;
+        argumentHint?: string;
+    }>;
+};
+/**
+ * Transient event emitted by the OMP driver after each turn completes.
+ * Carries the OMP session ID that can be passed as `resumeSessionId` on the
+ * next spawn so OMP restores its full conversation context natively — without
+ * needing injected `<conversation_history>` blocks. Not persisted.
+ *
+ * @docLink packages/types/events#session-info-event
+ */
+export type SessionInfoEvent = {
+    type: "session_info";
+    /** The OMP session identifier (from `get_state` RPC response). */
+    driverSessionId: string;
+    /** Absolute path to the JSONL session file written by OMP, if known. */
+    sessionFile?: string;
+};
+/**
+ * One labeled section of the assembled system prompt, as broken down by
+ * the runner's session-builder. Single-entry labels (`context`, `prompt`,
+ * `environment`, `resources`) appear once; multi-entry labels
+ * (`prompt-extensions`, `composition`, `additional`) appear once per
+ * source.
+ *
+ * @since 2026-05
+ */
+export type SystemPromptSection = {
+    label: "context" | "prompt" | "environment" | "resources" | "prompt-extensions" | "composition" | "additional";
+    value: string;
+    /** File path, block id, or descriptor — present for multi-entry labels. */
+    source?: string;
+};
+/**
+ * Emitted by the runner after every `createAgentSession` call (initial
+ * configure + every re-build path: `add_resource`, `remove_resource`,
+ * `configure`). Carries the labeled section breakdown of the system
+ * prompt the agent will receive. Transient — not persisted.
+ *
+ * @since 2026-05
+ */
+export type SystemPromptComposedEvent = {
+    type: "system_prompt_composed";
+    sections: SystemPromptSection[];
+    /** ISO timestamp when the breakdown was produced. */
+    composedAt: string;
+};
+//# sourceMappingURL=events.d.ts.map