Class: Rubino::Agent::Runner

Inherits:
Object
  • Object
show all
Defined in:
lib/rubino/agent/runner.rb

Overview

Top-level orchestrator for a single user interaction. Coordinates session management, the agent loop, and post-turn jobs.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(session_id: nil, model_override: nil, provider_override: nil, max_turns: nil, ignore_rules: false, ui: nil, agent_definition: nil, event_bus: nil, announce_session: true, session_source: "cli") ⇒ Runner

Returns a new instance of Runner.



14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/rubino/agent/runner.rb', line 14

def initialize(session_id: nil, model_override: nil, provider_override: nil,
               max_turns: nil, ignore_rules: false, ui: nil, agent_definition: nil,
               event_bus: nil, announce_session: true, session_source: "cli")
  @ui = ui || Rubino.ui
  # An in-chat rewind/fork builds a runner on the child session but has its
  # own purpose-built "┄ rewound to message N — editing ┄" marker, so the
  # generic "Resuming session: <id>…" plumbing line must not also leak into
  # the transcript (#220). Off-rewind callers keep the announcement.
  @announce_session = announce_session
  # Defaults to the process-global bus for the single-run CLI path; the
  # HTTP Executor injects a fresh per-run bus so concurrent runs don't
  # cross-contaminate each other's events/output (architecture audit A1).
  @event_bus = event_bus || Rubino.event_bus
  @config = Rubino.configuration
  @session_repo = Session::Repository.new
  @message_store = Session::Store.new
  @explicit_model_override = model_override
  @model_id = model_override || @config.model_default
  @provider_override = provider_override
  @max_turns = max_turns
  @ignore_rules = ignore_rules
  @agent_definition = agent_definition
  # The `source` stamped on a freshly-created session row. Defaults to
  # "cli" (a user-driven REPL/one-shot session); the `task` tool passes
  # "subagent" so internal subagent prompt-sessions can be filtered out of
  # the user-facing /sessions picker + `sessions list` (they're machinery,
  # not the user's own conversations) while staying resumable by explicit
  # id. Like Claude Code hiding its Task subagent sessions from the picker.
  @session_source = session_source
  # Pre-instantiate so cancel! is meaningful between turns and during the
  # window between Signal.trap install and run() — a too-early Ctrl+C
  # used to land on a nil token and silently no-op, then the next run
  # started fresh and the user's cancel was lost.
  @cancel_token = Interaction::CancelToken.new
  # Detached post-turn polishing worker (#319): owns the background thread
  # that drains memory-extract / skill-distill / summarize OFF the live
  # turn so the next prompt is never gated, and is cancellable via Esc.
  # Reused across this runner's turns so #running? / #cancel! address the
  # CURRENT polishing run (coalescing rapid turns).
  @polishing = Interaction::Polishing.new(config: @config)
  @session = load_or_create_session(session_id)
end

Instance Attribute Details

#agent_definition ⇒ Object

Pins the agent Definition this runner threads into every subsequent turn (the sticky ‘/agent <name>` / Tab-cycle switch). Lifecycle reads from the NEXT turn — the agent’s system prompt and tool scope come along. nil restores the default (build) persona. The reader feeds the CLI status bar and a one-shot route that wants to restore it afterwards.



136
137
138
 
# File 'lib/rubino/agent/runner.rb', line 136

def agent_definition
  @agent_definition
end

#model_id ⇒ Object (readonly)

The resolved model id this runner runs against. Read by SubagentProbe so an ephemeral peek uses the child’s OWN model, not the global default.



12
13
14
 
# File 'lib/rubino/agent/runner.rb', line 12

def model_id
  @model_id
end

#polishing ⇒ Object (readonly)

The detached post-turn polishing worker, so the CLI can show the non-blocking “polishing… (Esc to skip)” indicator while it runs and extend the single Esc/cancel path to it (#319).



60
61
62
 
# File 'lib/rubino/agent/runner.rb', line 60

def polishing
  @polishing
end

#session ⇒ Object (readonly)

Returns the value of attribute session.



8
9
10
 
# File 'lib/rubino/agent/runner.rb', line 8

def session
  @session
end

Instance Method Details

#cancel!(reason: :user) ⇒ Object

Flips the current turn’s cancel token. Called from the UI thread when the user hits Esc or a second Ctrl+C while the worker is mid-stream. No-op when no turn is in flight.

ONE Esc cancels whatever is in flight (#319): the FOREGROUND turn OR the DETACHED post-turn polishing. Flipping both tokens is safe — a token is one-shot and idle-when-untouched, so cancelling the not-running side is a harmless no-op. The polishing worker stops between jobs and its aux retry/backoff aborts mid-wait, leaving partial work in place. reason records WHY the turn was cancelled so the result label stays truthful: :user (Esc/Ctrl+C, default) vs :external (SIGTERM/SIGHUP teardown). Plumbed through to the CancelToken / Interrupted (#361b).



162
163
164
165
 
# File 'lib/rubino/agent/runner.rb', line 162

def cancel!(reason: :user)
  @cancel_token&.cancel!(reason: reason)
  @polishing&.cancel!
end

#end_session! ⇒ Object

Marks the current session ended (#100). Called from the CLI on a clean REPL teardown (and best-effort on terminal close) so a session stops showing as “active” forever and cleanup/list/–continue can tell a finished session from a live one. Best-effort: a failure here must never crash the exit path.



199
200
201
202
203
204
205
206
207
208
209
210
211
212
 
# File 'lib/rubino/agent/runner.rb', line 199

def end_session!
  # Nothing to end for a session that was never persisted (the user opened
  # chat and left without sending a message, #144) — there's no row.
  return if @session.nil? || (@session[:persisted] == false && !@session_repo.persisted?(@session[:id]))

  @session_repo.end_session!(@session[:id])
rescue StandardError
  nil
ensure
  # Let any in-flight detached polishing settle (bounded) so a clean
  # teardown doesn't abandon a half-written extraction (#319). Best-effort:
  # the cursor re-feeds anything unfinished next session anyway.
  @polishing&.wait(3)
end

#polishing? ⇒ Boolean

True while the detached post-turn polishing is still draining — drives the non-blocking “polishing… (Esc to skip)” indicator the CLI shows without owning the input.

Returns:

  • (Boolean) 


170
171
172
 
# File 'lib/rubino/agent/runner.rb', line 170

def polishing?
  @polishing&.running? || false
end

#run(input, image_paths: [], input_queue: nil, paste_expansions: []) ⇒ Object

Executes a full interaction turn, swallowing failures so CLI callers can stay in the REPL after a model/tool error. The friendly UI message is emitted, but the bus event INTERACTION_FAILED is NOT re-emitted here — Interaction::Lifecycle is the single source of truth for that, and it already emitted before re-raising. Use run! from non-CLI callers (HTTP executor) that need the exception to propagate so the run row can be marked failed.



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/rubino/agent/runner.rb', line 69

def run(input, image_paths: [], input_queue: nil, paste_expansions: [])
  run!(input, image_paths: image_paths, input_queue: input_queue,
              paste_expansions: paste_expansions)
rescue Interrupted
  # Standardized single interrupt notice: a dim `⎿ interrupted` marker
  # right after the partial answer the Loop already committed via
  # #stream_end. Replaces the old "⚠ interrupted by user" warning so the
  # Ctrl+C path and the interrupt-by-default type-ahead path read the same.
  @ui.turn_interrupted
  nil
rescue SystemExit, Interrupt, SignalException
  raise
rescue Exception => e # rubocop:disable Lint/RescueException
  @ui.error(friendly_error_message(e))
  nil
end

#run!(input, image_paths: [], input_queue: nil, paste_expansions: []) ⇒ Object

Like run but propagates exceptions to the caller. The HTTP Executor uses this so it can transition the run row to “failed” (instead of mark_completed!) when the lifecycle raises. The ScriptError / Exception net is kept here too so the Executor sees LoadError etc. as a real failure rather than nil-and-completed.



91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/rubino/agent/runner.rb', line 91

def run!(input, image_paths: [], input_queue: nil, paste_expansions: [])
  # Each turn gets a fresh token. A CancelToken is one-shot, so reusing a
  # cancelled one would poison every subsequent turn (it would raise
  # Interrupted immediately at the first poll point). The per-turn SIGINT
  # trap (CLI) / stop-watcher (HTTP) is wired to #cancel! against this new
  # token before any LLM/tool work runs, so an in-flight interrupt still
  # cancels the current turn.
  @cancel_token = Interaction::CancelToken.new

  lifecycle = Interaction::Lifecycle.new(
    session: @session,
    event_bus: @event_bus,
    ui: @ui,
    config: @config,
    ignore_rules: @ignore_rules,
    agent_definition: @agent_definition,
    cancel_token: @cancel_token,
    model_override: @explicit_model_override,
    provider_override: @provider_override,
    max_tool_iterations: @max_turns,
    polishing: @polishing
  )

  response = lifecycle.execute(input, image_paths: image_paths, input_queue: input_queue,
                                      paste_expansions: paste_expansions)

  # Adopt an automatic-compaction swap so the NEXT turn runs on the (small)
  # compaction child, not the dead parent (P3 F1). When #check_and_compact
  # fires, it reassigns the lifecycle's session to the child; without
  # picking that up here the Runner would rebuild every subsequent turn's
  # Lifecycle on the un-shrunk parent → re-compact every turn (superlinear
  # DB/context bloat + ~2.9x slowdown). This is the automatic-path
  # counterpart to the manual /compact swap (chat_command rebuilds the
  # runner on result[:compact_into]).
  @session = lifecycle.active_session

  response
end

#run_with_agent(definition, input) ⇒ Object

Runs ONE turn under definition (a one-shot ‘/<name> <message>` route) without disturbing the runner’s sticky agent. The override is swapped in for the single #run and restored in the ensure, so the next idle prompt is back on whatever the user had pinned.



142
143
144
145
146
147
148
 
# File 'lib/rubino/agent/runner.rb', line 142

def run_with_agent(definition, input, **)
  sticky = @agent_definition
  @agent_definition = definition
  run(input, **)
ensure
  @agent_definition = sticky
end

#switch_model!(model_id) ⇒ Object

Switches the LIVE model for this runner (the in-chat ‘/model <name>`). Lifecycle builds the adapter per turn from `@explicit_model_override || @session`, and the CLI always passes a model_override at boot — so both fields must move for the NEXT turn to actually hit the new model. The session hash is mutated in place (statusbar and /status read it) and the persisted row is updated so resume/–continue agree; an unpersisted lazy session gets the new value via Repository#persist! on its first message instead.



182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/rubino/agent/runner.rb', line 182

def switch_model!(model_id)
  @explicit_model_override = model_id
  @model_id = model_id
  @session[:model] = model_id
  @session[:provider] = @provider_override ||
                        LLM::ProviderResolver.resolve(model_id, explicit_provider: @config.model_provider)
  if @session_repo.persisted?(@session[:id])
    @session_repo.update(@session[:id], model: model_id, provider: @session[:provider])
  end
  model_id
end