Public declaration syntax from harness-sdk/src/adapter.rs
Original source SHA-256: 7e45ad31415570d8132aaac9571b913ce07dfdff075ee507e4f520f21fa87558
Function bodies and constant values are omitted. This is not the complete implementation.

Source line 83
#[async_trait::async_trait]
pub trait AgentAdapter: Send + Sync + 'static {
    /// Returns the adapter's name (used in logs and UI).
    ///
    /// Must be non-empty and stable across calls.
    fn name(&self) -> &str;

    /// Returns the adapter's capability flags.
    ///
    /// The SDK checks these flags before calling optional methods.
    /// Returning `false` for a capability means the SDK will never call
    /// the corresponding methods and will disable related UI features.
    fn capabilities(&self) -> AdapterCapabilities;

    /// Discover available agents.
    ///
    /// Called during initialization and when the user requests a refresh.
    /// The SDK validates every returned `SdkAgentInfo` before use.
    async fn list_agents(&self) -> Result<Vec<SdkAgentInfo>, AdapterError>;

    /// Send a chat message to an agent and receive a streaming response.
    ///
    /// The returned stream must eventually yield [`ResponseChunk::Done`]
    /// or [`ResponseChunk::Error`]. The SDK enforces a timeout if neither
    /// arrives within the configured duration.
    ///
    /// # Arguments
    ///
    /// * `agent_id` — Target agent identifier (from `list_agents`)
    /// * `message` — User's message text (already sanitized)
    async fn send_message(
        &self,
        agent_id: &str,
        message: &str,
    ) -> Result<BoxStream<'static, ResponseChunk>, AdapterError>;

    /// Cancel an in-progress response stream.
    ///
    /// Called when the user presses Escape or Ctrl+C during streaming.
    /// Default implementation returns `Ok(())` (no-op).
    async fn cancel_response(&self, _agent_id: &str) -> Result<(), AdapterError> ;

    // ── Autonomy Mode ──

    /// Start an autonomous execution session.
    ///
    /// Returns a stream of [`AutonomyEvent`]s that the SDK displays
    /// in the activity feed.
    ///
    /// Only called if `capabilities().autonomy` is `true`.
    async fn start_autonomy(
        &self,
        _agent_id: &str,
        _instructions: &str,
    ) -> Result<BoxStream<'static, AutonomyEvent>, AdapterError> ;

    /// Stop the current autonomous execution session.
    ///
    /// Called when the user presses Ctrl+S or `/stop`.
    async fn stop_autonomy(&self, _agent_id: &str) -> Result<(), AdapterError> ;

    /// Send a human interjection during autonomous execution.
    ///
    /// The adapter should acknowledge receipt via [`InterjectionAck`].
    async fn send_interjection(
        &self,
        _interjection: &HumanInterjection,
    ) -> Result<InterjectionAck, AdapterError> ;

    // ── Approval Management ──

    /// Submit an approval decision for a pending request.
    ///
    /// Called when the user approves, denies, or edits an approval request
    /// from the approval queue.
    async fn submit_approval(
        &self,
        _request_id: &str,
        _action: SdkApprovalAction,
    ) -> Result<(), AdapterError> ;

    // ── UI Rendering Hooks ──

    /// Optional hook to render custom content in the sidebar area.
    ///
    /// Called during each frame render. The `area` is the sidebar region
    /// from `AppShellState::sidebar_area()`. Default is a no-op.
    ///
    /// This is intentionally **sync** because rendering happens on the
    /// main thread inside `terminal.draw()`.
    fn render_sidebar(
        &self,
        _frame: &mut ratatui::Frame,
        _area: ratatui::layout::Rect,
        _theme: &Theme,
    ) ;

    /// Optional hook to render custom content in the header area.
    ///
    /// Called during each frame render. The `area` is the header region
    /// from `AppShellState::header_area()`. Default is a no-op.
    fn render_header(
        &self,
        _frame: &mut ratatui::Frame,
        _area: ratatui::layout::Rect,
        _theme: &Theme,
    ) ;

    /// Optional hook to request a taller header from the chat screen.
    ///
    /// The default `AppShell` reserves only 1 row for the header. An
    /// adapter that wants to paint a banner / mascot / multi-line
    /// status returns its desired height here. The chat screen passes
    /// `sidebar_collapsed` so the adapter can ask for a tall header
    /// only when the sidebar is hidden (and otherwise paint into the
    /// sidebar).
    fn desired_header_height(&self, _sidebar_collapsed: bool) -> u16 ;

    /// Optional hook to request a wider sidebar from the chat screen.
    /// Defaults to the SDK's `AppShell` default (25 columns).
    fn desired_sidebar_width(&self) -> Option<u16> ;

    /// Optional hook to provide live file-mention completions when the
    /// user types `@<prefix>` in the input bar.
    ///
    /// `prefix` is everything after the `@` up to the cursor. The
    /// adapter returns up to ~50 matching paths (relative to its
    /// workspace root). Default: no completions, dropdown stays
    /// hidden.
    ///
    /// Path conventions adapters should honour:
    /// - `@foo`           → fuzzy match anywhere in the workspace
    /// - `@./foo`         → match relative to the workspace root
    /// - `@../foo`        → walk up one directory
    /// - `@/abs/path`     → absolute path on the filesystem
    ///
    /// This is intentionally **sync**: the SDK calls it on every
    /// keystroke, so adapters MUST keep it cheap (cache the walk,
    /// limit results, never block on I/O).
    fn complete_file_mention(&self, _prefix: &str) -> Vec<String> ;

    // ── Lifecycle ──

    /// Called once when the TUI application starts.
    ///
    /// Use this for any one-time initialization (connecting to backends,
    /// spawning background tasks, etc.).
    async fn on_startup(&self) -> Result<(), AdapterError> ;

    /// Called once when the TUI application is shutting down.
    ///
    /// Use this for cleanup (closing connections, saving state, etc.).
    /// The SDK waits up to 5 seconds for this to complete before forcing exit.
    async fn on_shutdown(&self) -> Result<(), AdapterError> ;

    // ── Settings palette (Ctrl+P) ──

    /// Return the current settings snapshot — providers, modes,
    /// Flocks CLIs — that the runtime should render in the Ctrl+P
    /// palette. The default returns an empty snapshot, which causes
    /// the palette to show only the built-in pages.
    async fn settings_snapshot(&self) -> Result<SettingsSnapshot, AdapterError> ;

    /// Apply a [`SettingsAction`] picked by the user in the
    /// settings palette. The default returns
    /// `Ok(SettingsApplyResult::fail(...))`, signaling the runtime
    /// to display a "not supported" flash.
    async fn apply_settings_action(
        &self,
        _action: SettingsAction,
    ) -> Result<SettingsApplyResult, AdapterError> ;
}