Class: Ask::CodingProviders::Adapter

Inherits:
Object
  • Object
show all
Defined in:
lib/ask/coding_providers/adapter.rb

Overview

Abstract base class for coding agent adapters.

A coding agent adapter wraps an AI coding agent (e.g., ZCode, Claude Code, Codex) and provides a uniform interface for the coder engine to interact with it.

Subclasses must implement all methods that raise NotImplementedError.

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.from_config(**config) ⇒ Adapter

Build an adapter instance from a configuration hash. Override in subclasses to extract adapter-specific settings. The default passes the entire hash to new.

Parameters:

  • config (Hash) —

    configuration options (typically from ENV)

Returns:

  • (Adapter) —

    a configured adapter instance



147
148
149
 
# File 'lib/ask/coding_providers/adapter.rb', line 147

def self.from_config(**config)
  new(**config)
end

Instance Method Details

#create_session(workspace_path, mode: nil, system_prompt: nil) ⇒ String

Create a new session on the agent.

Parameters:

  • workspace_path (String) —

    the working directory

  • mode (String, nil) (defaults to: nil) —

    permission mode

Returns:

  • (String) —

    the session ID

Raises:

  • (NotImplementedError) 


17
18
19
 
# File 'lib/ask/coding_providers/adapter.rb', line 17

def create_session(workspace_path, mode: nil, system_prompt: nil, **)
  raise NotImplementedError, "#{self.class} must implement #create_session"
end

#find_recent_session ⇒ Object

Optional: find the single most recent session. Returns directory: or nil.



100
101
102
 
# File 'lib/ask/coding_providers/adapter.rb', line 100

def find_recent_session
  nil
end

#find_recent_tui_session(workspace_path) ⇒ Object

Optional: find the most recent TUI session in a workspace. Returns title:, directory: or nil.



106
107
108
 
# File 'lib/ask/coding_providers/adapter.rb', line 106

def find_recent_tui_session(workspace_path)
  nil
end

#find_sessions(directory:, limit: 20) ⇒ Object

Optional: find sessions in a directory. Returns [title:, updated:] or [].



94
95
96
 
# File 'lib/ask/coding_providers/adapter.rb', line 94

def find_sessions(directory:, limit: 20)
  []
end

#get_events(session_id, after_seq:, limit: nil) ⇒ Hash

Get events after a sequence number (polling).

Returns:

  • (Hash) —

    events list

Raises:

  • (NotImplementedError) 


62
63
64
 
# File 'lib/ask/coding_providers/adapter.rb', line 62

def get_events(session_id, after_seq:, limit: nil)
  raise NotImplementedError, "#{self.class} must implement #get_events"
end

#get_workspace_state(workspace_path) ⇒ Object

Read the workspace state (model info, settings, etc.).



72
73
74
 
# File 'lib/ask/coding_providers/adapter.rb', line 72

def get_workspace_state(workspace_path)
  {}
end

#handle_session_error(session_id, error) ⇒ Symbol?

Called when a session operation fails. The adapter can signal how the Engine should recover.

Parameters:

  • session_id (String) —

    the session that failed

  • error (StandardError) —

    the error that occurred

Returns:

  • (Symbol, nil) —

    :create_new to replace the session, nil to show error as-is



82
83
84
 
# File 'lib/ask/coding_providers/adapter.rb', line 82

def handle_session_error(session_id, error)
  nil  # Unknown error — let the Engine show it to the user
end

#list_projects ⇒ Object

Optional: list available projects with session counts. Returns [directory:, session_count:] or nil.



88
89
90
 
# File 'lib/ask/coding_providers/adapter.rb', line 88

def list_projects
  nil
end

#list_sessions(workspace_path: nil, limit: 20) ⇒ Array<Hash>

List available sessions.

Parameters:

  • workspace_path (String, nil) (defaults to: nil) —

    optional filter

  • limit (Integer) (defaults to: 20) —

    max sessions

Returns:

  • (Array<Hash>) —

    session summaries

Raises:

  • (NotImplementedError) 


34
35
36
 
# File 'lib/ask/coding_providers/adapter.rb', line 34

def list_sessions(workspace_path: nil, limit: 20)
  raise NotImplementedError, "#{self.class} must implement #list_sessions"
end

#recent_sessions ⇒ Object

Optional: list recent sessions across all projects. Returns [title:, updated:, msg_count:] or [].



124
125
126
 
# File 'lib/ask/coding_providers/adapter.rb', line 124

def recent_sessions
  []
end

#respond(request_id, result) ⇒ Object

Respond to a reverse request (permission approval, etc.).

Raises:

  • (NotImplementedError) 


67
68
69
 
# File 'lib/ask/coding_providers/adapter.rb', line 67

def respond(request_id, result)
  raise NotImplementedError, "#{self.class} must implement #respond"
end

#resume_session(session_id) ⇒ Hash

Resume an existing session.

Parameters:

  • session_id (String) —

    the session ID

Returns:

  • (Hash) —

    session snapshot

Raises:

  • (NotImplementedError) 


25
26
27
 
# File 'lib/ask/coding_providers/adapter.rb', line 25

def resume_session(session_id)
  raise NotImplementedError, "#{self.class} must implement #resume_session"
end

#running? ⇒ Boolean

Whether the agent is running.

Returns:

  • (Boolean) 


137
138
139
 
# File 'lib/ask/coding_providers/adapter.rb', line 137

def running?
  true
end

#send_and_stream(session_id, content, turn_timeout: 600.0) {|Hash| ... } ⇒ Object

Send a message and stream the response events.

Yields:

  • (Hash) —

    stream events with :type, :payload, :seq

Raises:

  • (NotImplementedError) 


55
56
57
 
# File 'lib/ask/coding_providers/adapter.rb', line 55

def send_and_stream(session_id, content, turn_timeout: 600.0, &block)
  raise NotImplementedError, "#{self.class} must implement #send_and_stream"
end

#send_message(session_id, content) ⇒ Object

Send a message to a session (fire-and-forget).

Raises:

  • (NotImplementedError) 


48
49
50
 
# File 'lib/ask/coding_providers/adapter.rb', line 48

def send_message(session_id, content)
  raise NotImplementedError, "#{self.class} must implement #send_message"
end

#session_directory(session_id) ⇒ Object

Optional: get a session's workspace directory by ID. Returns directory string or nil.



112
113
114
 
# File 'lib/ask/coding_providers/adapter.rb', line 112

def session_directory(session_id)
  nil
end

#session_history(session_id, limit: 100) ⇒ Object

Optional: get session message history. Returns [role:, origin:] or [].



118
119
120
 
# File 'lib/ask/coding_providers/adapter.rb', line 118

def session_history(session_id, limit: 100)
  []
end

#start ⇒ Object

Start the agent connection.



129
130
 
# File 'lib/ask/coding_providers/adapter.rb', line 129

def start
end

#stop ⇒ Object

Stop the agent connection.



133
134
 
# File 'lib/ask/coding_providers/adapter.rb', line 133

def stop
end

#subscribe(session_id, after_seq: 0) ⇒ Hash

Subscribe to session events.

Parameters:

  • session_id (String) —

    the session ID

  • after_seq (Integer) (defaults to: 0) —

    sequence to start from

Returns:

  • (Hash) —

    subscription result

Raises:

  • (NotImplementedError) 


43
44
45
 
# File 'lib/ask/coding_providers/adapter.rb', line 43

def subscribe(session_id, after_seq: 0)
  raise NotImplementedError, "#{self.class} must implement #subscribe"
end