Class: Clacky::Server::WebUIController

Inherits:
Object
  • Object
show all
Includes:
UIInterface
Defined in:
lib/clacky/server/web_ui_controller.rb

Overview

WebUIController implements UIInterface for the web server mode. Instead of writing to stdout, it broadcasts JSON events over WebSocket connections. Multiple browser tabs can subscribe to the same session_id.

request_confirmation blocks the calling thread until the browser sends a response, mirroring the behaviour of JsonUIController (which reads from stdin).

Constant Summary collapse

CONFIRMATION_TIMEOUT =

Blocking interaction ===

Emits a request_confirmation event and blocks until the browser responds. Timeout after 5 minutes to avoid hanging threads forever.

300

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(session_id, broadcaster) ⇒ WebUIController

Returns a new instance of WebUIController.



20
21
22
23
24
25
26
27
28
29
30
31
32
 
# File 'lib/clacky/server/web_ui_controller.rb', line 20

def initialize(session_id, broadcaster)
  @session_id  = session_id
  @broadcaster = broadcaster   # callable: broadcaster.call(session_id, event_hash)
  @mutex       = Mutex.new

  # Pending confirmation state: { id => ConditionVariable, result => value }
  @pending_confirmations = {}

  # Channel subscribers: array of objects implementing UIInterface.
  # All emitted events are forwarded to each subscriber after WebSocket broadcast.
  @channel_subscribers = []
  @subscribers_mutex   = Mutex.new
end

Instance Attribute Details

#session_id ⇒ Object (readonly)

Returns the value of attribute session_id.



18
19
20
 
# File 'lib/clacky/server/web_ui_controller.rb', line 18

def session_id
  @session_id
end

Instance Method Details

#append_output(content) ⇒ Object 



170
171
172
173
 
# File 'lib/clacky/server/web_ui_controller.rb', line 170

def append_output(content)
  emit("output", content: content)
  forward_to_subscribers { |sub| sub.append_output(content) }
end

#channel_subscribed? ⇒ Boolean

Returns true if any channel subscribers are registered.

Returns:

  • (Boolean) —

    true if any channel subscribers are registered



50
51
52
 
# File 'lib/clacky/server/web_ui_controller.rb', line 50

def channel_subscribed?
  @subscribers_mutex.synchronize { !@channel_subscribers.empty? }
end

#clear_input ⇒ Object

Input control (no-ops in web mode) ===



339
 
# File 'lib/clacky/server/web_ui_controller.rb', line 339

def clear_input; end

#clear_progress ⇒ Object 



244
245
246
247
248
249
 
# File 'lib/clacky/server/web_ui_controller.rb', line 244

def clear_progress
  @live_tool_call = nil   # command finished — nothing left to replay
  # Keep @live_stdout_buffer intact — it will be reset on the next show_progress call.
  # This allows a brief replay window even after the command finishes.
  show_progress(progress_type: "thinking", phase: "done")
end

#deliver_confirmation(conf_id, result) ⇒ Object

Deliver a confirmation answer received from the browser. Called by the HTTP server when a confirmation message arrives over WebSocket.



56
57
58
59
60
61
62
63
64
 
# File 'lib/clacky/server/web_ui_controller.rb', line 56

def deliver_confirmation(conf_id, result)
  @mutex.synchronize do
    pending = @pending_confirmations[conf_id]
    return unless pending

    pending[:result] = result
    pending[:cond].signal
  end
end

#emit(type, **data) ⇒ Object 



362
363
364
365
 
# File 'lib/clacky/server/web_ui_controller.rb', line 362

def emit(type, **data)
  event = { type: type, session_id: @session_id }.merge(data)
  @broadcaster.call(@session_id, event)
end

#forward_to_subscribers(&block) ⇒ Object

Forward a UIInterface call to all registered channel subscribers. Each subscriber is called in the same thread as the caller (Agent thread). Errors in individual subscribers are rescued and logged so they never interrupt the main agent execution.



371
372
373
374
375
376
377
378
379
380
 
# File 'lib/clacky/server/web_ui_controller.rb', line 371

def forward_to_subscribers(&block)
  subscribers = @subscribers_mutex.synchronize { @channel_subscribers.dup }
  return if subscribers.empty?

  subscribers.each do |sub|
    block.call(sub)
  rescue StandardError => e
    warn "[WebUIController] channel subscriber error: #{e.message}"
  end
end

#log(message, level: :info) ⇒ Object 



204
205
206
207
 
# File 'lib/clacky/server/web_ui_controller.rb', line 204

def log(message, level: :info)
  emit("log", level: level.to_s, message: message)
  # Log forwarding intentionally skipped — too noisy for IM
end

#replay_live_state ⇒ Object

Replay in-progress command state to a newly (re-)subscribing browser tab. Called by http_server.rb after the subscribe handshake when the session is still running a shell command. Without this, switching sessions and switching back results in a blank progress area — the progress event and all tool_stdout lines that fired while the user was away are lost. Replay live state when a client re-subscribes (e.g. after switching sessions).

Plan C: we do NOT re-emit tool_call here. The tool-item is already rendered in the DOM via the normal flow. We only replay:

1. progress(start) — restores the spinner / progress bar
2. tool_stdout     — fills in all stdout received so far

The frontend’s appendToolStdout will attach to the last visible .tool-item even when _liveLastToolItem is null (after the tab re-loaded).



266
267
268
269
270
271
272
273
 
# File 'lib/clacky/server/web_ui_controller.rb', line 266

def replay_live_state
  return unless @live_progress_message

  emit("progress", message: @live_progress_message, status: "start")

  buf = @live_stdout_buffer
  emit("tool_stdout", lines: buf) if buf && !buf.empty?
end

#request_confirmation(message, default: true) ⇒ Object

seconds



306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
 
# File 'lib/clacky/server/web_ui_controller.rb', line 306

def request_confirmation(message, default: true)
  conf_id = "conf_#{SecureRandom.hex(4)}"

  cond    = ConditionVariable.new
  pending = { cond: cond, result: nil }

  @mutex.synchronize { @pending_confirmations[conf_id] = pending }

  emit("request_confirmation", id: conf_id, message: message, default: default)

  # Notify channel subscribers that confirmation is pending — non-blocking.
  # They display a notice; the actual decision comes from the Web UI user.
  forward_to_subscribers { |sub| sub.show_warning("⏳ Confirmation requested: #{message}") }

  # Block until browser replies or timeout
  @mutex.synchronize do
    cond.wait(@mutex, CONFIRMATION_TIMEOUT)
    @pending_confirmations.delete(conf_id)
    result = pending[:result]

    # Timed out — use default
    return default if result.nil?

    case result.to_s.downcase
    when "yes", "y" then true
    when "no",  "n" then false
    else result.to_s
    end
  end
end

#set_idle_status ⇒ Object 



296
297
298
299
 
# File 'lib/clacky/server/web_ui_controller.rb', line 296

def set_idle_status
  emit("session_update", status: "idle")
  forward_to_subscribers { |sub| sub.set_idle_status }
end

#set_input_tips(message, type: :info) ⇒ Object 



340
 
# File 'lib/clacky/server/web_ui_controller.rb', line 340

def set_input_tips(message, type: :info); end

#set_working_status ⇒ Object 



291
292
293
294
 
# File 'lib/clacky/server/web_ui_controller.rb', line 291

def set_working_status
  emit("session_update", status: "working")
  forward_to_subscribers { |sub| sub.set_working_status }
end

#show_assistant_message(content, files:) ⇒ Object 



87
88
89
90
91
92
 
# File 'lib/clacky/server/web_ui_controller.rb', line 87

def show_assistant_message(content, files:)
  return if (content.nil? || content.to_s.strip.empty?) && files.empty?

  emit("assistant_message", content: content, files: files)
  forward_to_subscribers { |sub| sub.show_assistant_message(content, files: files) }
end

#show_complete(iterations:, cost:, duration: nil, cache_stats: nil, awaiting_user_feedback: false) ⇒ Object 



158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/clacky/server/web_ui_controller.rb', line 158

def show_complete(iterations:, cost:, duration: nil, cache_stats: nil, awaiting_user_feedback: false)
  data = { iterations: iterations, cost: cost }
  data[:duration]               = duration            if duration
  data[:cache_stats]            = cache_stats         if cache_stats
  data[:awaiting_user_feedback] = awaiting_user_feedback if awaiting_user_feedback
  emit("complete", **data)
  forward_to_subscribers do |sub|
    sub.show_complete(iterations: iterations, cost: cost, duration: duration,
                      cache_stats: cache_stats, awaiting_user_feedback: awaiting_user_feedback)
  end
end

#show_diff(old_content, new_content, max_lines: 50) ⇒ Object 



148
149
150
151
 
# File 'lib/clacky/server/web_ui_controller.rb', line 148

def show_diff(old_content, new_content, max_lines: 50)
  emit("diff", old_size: old_content.bytesize, new_size: new_content.bytesize)
  # Diffs are too verbose for IM — intentionally not forwarded
end

#show_error(message) ⇒ Object 



194
195
196
197
 
# File 'lib/clacky/server/web_ui_controller.rb', line 194

def show_error(message)
  emit("error", message: message)
  forward_to_subscribers { |sub| sub.show_error(message) }
end

#show_file_edit_preview(path) ⇒ Object 



133
134
135
136
 
# File 'lib/clacky/server/web_ui_controller.rb', line 133

def show_file_edit_preview(path)
  emit("file_preview", path: path, operation: "edit")
  forward_to_subscribers { |sub| sub.show_file_edit_preview(path) }
end

#show_file_error(error_message) ⇒ Object 



138
139
140
141
 
# File 'lib/clacky/server/web_ui_controller.rb', line 138

def show_file_error(error_message)
  emit("file_error", error: error_message)
  forward_to_subscribers { |sub| sub.show_file_error(error_message) }
end

#show_file_write_preview(path, is_new_file:) ⇒ Object 



128
129
130
131
 
# File 'lib/clacky/server/web_ui_controller.rb', line 128

def show_file_write_preview(path, is_new_file:)
  emit("file_preview", path: path, operation: "write", is_new_file: is_new_file)
  forward_to_subscribers { |sub| sub.show_file_write_preview(path, is_new_file: is_new_file) }
end

#show_idle_status(phase:, message:) ⇒ Object

Emit a two-phase idle compression status update. The frontend uses the same DOM element for both phases so it renders as one line. phase: :start → show spinner message; phase: :end → update in-place with final result



185
186
187
 
# File 'lib/clacky/server/web_ui_controller.rb', line 185

def show_idle_status(phase:, message:)
  emit("idle_status", phase: phase.to_s, message: message)
end

#show_info(message, prefix_newline: true) ⇒ Object

Status messages ===



177
178
179
180
 
# File 'lib/clacky/server/web_ui_controller.rb', line 177

def show_info(message, prefix_newline: true)
  emit("info", message: message)
  forward_to_subscribers { |sub| sub.show_info(message) }
end

#show_progress(message = nil, prefix_newline: true, progress_type: "thinking", phase: "active", metadata: {}) ⇒ Object

Progress ===



211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
 
# File 'lib/clacky/server/web_ui_controller.rb', line 211

def show_progress(message = nil, prefix_newline: true, progress_type: "thinking", phase: "active", metadata: {})
  @progress_start_time = Time.now if phase == "active"
  @live_progress_message = message
  # Reset stdout buffer for each new command so re-subscribe only replays current run
  @live_stdout_buffer = [] if phase == "active"
  
  data = {
    message: message,
    progress_type: progress_type,
    phase: phase,
    status: phase == "active" ? "start" : "stop"  # backward compat
  }
  data[:metadata] = metadata unless metadata.empty?
  data[:elapsed] = (Time.now - @progress_start_time).round(1) if phase == "done" && @progress_start_time
  
  emit("progress", **data)
  forward_to_subscribers { |sub| sub.show_progress(message) }
  
  @progress_start_time = nil if phase == "done"
end

#show_shell_preview(command) ⇒ Object 



143
144
145
146
 
# File 'lib/clacky/server/web_ui_controller.rb', line 143

def show_shell_preview(command)
  emit("shell_preview", command: command)
  forward_to_subscribers { |sub| sub.show_shell_preview(command) }
end

#show_success(message) ⇒ Object 



199
200
201
202
 
# File 'lib/clacky/server/web_ui_controller.rb', line 199

def show_success(message)
  emit("success", message: message)
  forward_to_subscribers { |sub| sub.show_success(message) }
end

#show_token_usage(token_data) ⇒ Object 



153
154
155
156
 
# File 'lib/clacky/server/web_ui_controller.rb', line 153

def show_token_usage(token_data)
  emit("token_usage", **token_data)
  # Token usage is internal detail — intentionally not forwarded
end

#show_tool_args(formatted_args) ⇒ Object 



123
124
125
126
 
# File 'lib/clacky/server/web_ui_controller.rb', line 123

def show_tool_args(formatted_args)
  emit("tool_args", args: formatted_args)
  forward_to_subscribers { |sub| sub.show_tool_args(formatted_args) }
end

#show_tool_call(name, args) ⇒ Object 



94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/clacky/server/web_ui_controller.rb', line 94

def show_tool_call(name, args)
  # Skip request_user_feedback — its question is already shown as an assistant message
  return if name.to_s == "request_user_feedback"

  args_data = args.is_a?(String) ? (JSON.parse(args) rescue args) : args

  # Generate a human-readable summary using the tool's format_call method
  summary = tool_call_summary(name, args_data)

  # Remember the current in-flight tool call so replay_live_state can re-emit it
  # when a browser tab re-subscribes after switching sessions.
  @live_tool_call = { name: name, args: args_data, summary: summary }

  emit("tool_call", name: name, args: args_data, summary: summary)
  forward_to_subscribers { |sub| sub.show_tool_call(name, args_data) }
end

#show_tool_error(error) ⇒ Object 



117
118
119
120
121
 
# File 'lib/clacky/server/web_ui_controller.rb', line 117

def show_tool_error(error)
  error_msg = error.is_a?(Exception) ? error.message : error.to_s
  emit("tool_error", error: error_msg)
  forward_to_subscribers { |sub| sub.show_tool_error(error) }
end

#show_tool_result(result) ⇒ Object 



111
112
113
114
115
 
# File 'lib/clacky/server/web_ui_controller.rb', line 111

def show_tool_result(result)
  @live_tool_call = nil   # tool finished — no longer in-flight
  emit("tool_result", result: result)
  forward_to_subscribers { |sub| sub.show_tool_result(result) }
end

#show_tool_stdout(lines) ⇒ Object

Stream shell stdout/stderr lines to the browser while a command is running. Called immediately via on_output callback from shell.rb — no polling delay. Lines are also buffered in @live_stdout_buffer so late-joining subscribers (e.g. user switches away and back) can receive a replay of what they missed.



236
237
238
239
240
241
242
 
# File 'lib/clacky/server/web_ui_controller.rb', line 236

def show_tool_stdout(lines)
  return if lines.nil? || lines.empty?
  @live_stdout_buffer ||= []
  @live_stdout_buffer.concat(lines)
  emit("tool_stdout", lines: lines)
  # Not forwarded to IM subscribers — too noisy
end

#show_user_message(content, created_at: nil, files: [], source: :web) ⇒ Object

Output display ===



68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/clacky/server/web_ui_controller.rb', line 68

def show_user_message(content, created_at: nil, files: [], source: :web)
  data = { content: content }
  data[:created_at] = created_at if created_at
  # Build ev.images for the frontend renderer (history_user_message):
  #   - Images with data_url → pass the data_url directly (<img> thumbnail)
  #   - Disk files (PDF, doc, etc., no data_url) → "pdf:name" sentinel (renders a badge)
  rendered = Array(files).filter_map do |f|
    url  = f[:data_url] || f["data_url"]
    name = f[:name]     || f["name"]
    url || (name ? "pdf:#{name}" : nil)
  end
  data[:images] = rendered unless rendered.empty?
  emit("history_user_message", **data)
  # Only forward to channel subscribers when the message originated from the WebUI,
  # to avoid echoing channel messages back to the same channel.
  return unless source == :web
  forward_to_subscribers { |sub| sub.show_user_message(content) if sub.respond_to?(:show_user_message) }
end

#show_warning(message) ⇒ Object 



189
190
191
192
 
# File 'lib/clacky/server/web_ui_controller.rb', line 189

def show_warning(message)
  emit("warning", message: message)
  forward_to_subscribers { |sub| sub.show_warning(message) }
end

#stop ⇒ Object

Lifecycle ===



344
345
346
 
# File 'lib/clacky/server/web_ui_controller.rb', line 344

def stop
  emit("server_stop")
end

#subscribe_channel(subscriber) ⇒ void

This method returns an undefined value.

Register a channel subscriber (e.g. ChannelUIController). The subscriber will receive every UIInterface call that this controller handles.

Parameters:



38
39
40
 
# File 'lib/clacky/server/web_ui_controller.rb', line 38

def subscribe_channel(subscriber)
  @subscribers_mutex.synchronize { @channel_subscribers << subscriber }
end

#tool_call_summary(name, args) ⇒ Object

Generate a short human-readable summary for a tool call display. Delegates to each tool’s own format_call method when available.



351
352
353
354
355
356
357
358
359
360
 
# File 'lib/clacky/server/web_ui_controller.rb', line 351

def tool_call_summary(name, args)
  class_name = name.to_s.split("_").map(&:capitalize).join
  return nil unless Clacky::Tools.const_defined?(class_name)

  tool = Clacky::Tools.const_get(class_name).new
  args_sym = args.is_a?(Hash) ? args.transform_keys(&:to_sym) : {}
  tool.format_call(args_sym)
rescue StandardError
  nil
end

#unsubscribe_channel(subscriber) ⇒ void

This method returns an undefined value.

Remove a previously registered channel subscriber.

Parameters:

  • subscriber (Object) 


45
46
47
 
# File 'lib/clacky/server/web_ui_controller.rb', line 45

def unsubscribe_channel(subscriber)
  @subscribers_mutex.synchronize { @channel_subscribers.delete(subscriber) }
end

#update_sessionbar(tasks: nil, cost: nil, status: nil) ⇒ Object

State updates ===



277
278
279
280
281
282
283
284
 
# File 'lib/clacky/server/web_ui_controller.rb', line 277

def update_sessionbar(tasks: nil, cost: nil, status: nil)
  data = {}
  data[:tasks]  = tasks  if tasks
  data[:cost]   = cost   if cost
  data[:status] = status if status
  emit("session_update", **data) unless data.empty?
  forward_to_subscribers { |sub| sub.update_sessionbar(tasks: tasks, cost: cost, status: status) }
end

#update_todos(todos) ⇒ Object 



286
287
288
289
 
# File 'lib/clacky/server/web_ui_controller.rb', line 286

def update_todos(todos)
  emit("todo_update", todos: todos)
  forward_to_subscribers { |sub| sub.update_todos(todos) }
end