samagotchi 0.182.0 → 0.183.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (161) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +68 -1
  3. data/bin/chi +3 -1
  4. data/docs/architecture.md +16 -6
  5. data/docs/bundle-authoring.md +1 -1
  6. data/docs/bundles.md +103 -4
  7. data/docs/cli.md +28 -6
  8. data/docs/configuration.md +2 -1
  9. data/docs/guardrails.md +16 -1
  10. data/docs/internals/block-renderers.md +58 -3
  11. data/docs/internals/bridge.md +13 -5
  12. data/docs/internals/bundles.md +21 -4
  13. data/docs/internals/engine.md +18 -8
  14. data/docs/internals/remote-sessions.md +24 -5
  15. data/docs/internals/web-frontend.md +88 -28
  16. data/docs/internals/working-set.md +1 -1
  17. data/docs/mcp-server.md +80 -0
  18. data/docs/plugins.md +308 -21
  19. data/docs/sessions.md +3 -3
  20. data/docs/sub-agent.md +9 -0
  21. data/docs/testing.md +3 -1
  22. data/docs/thin-clients.md +146 -0
  23. data/lib/samagotchi/bridge/pending_card.rb +4 -3
  24. data/lib/samagotchi/bridge/sse_writer.rb +16 -15
  25. data/lib/samagotchi/bridge.rb +59 -68
  26. data/lib/samagotchi/bundle_command/api_calls.rb +1 -1
  27. data/lib/samagotchi/bundle_command/check.rb +36 -19
  28. data/lib/samagotchi/bundle_command.rb +50 -21
  29. data/lib/samagotchi/bundle_manifest.rb +101 -4
  30. data/lib/samagotchi/bundles/dev/manifest.yml +2 -2
  31. data/lib/samagotchi/bundles/mcp/client.rb +260 -0
  32. data/lib/samagotchi/bundles/mcp/content.rb +107 -0
  33. data/lib/samagotchi/bundles/mcp/http_client.rb +407 -0
  34. data/lib/samagotchi/bundles/mcp/manifest.yml +13 -5
  35. data/lib/samagotchi/bundles/mcp/oauth.rb +814 -0
  36. data/lib/samagotchi/bundles/mcp/plugin.rb +556 -574
  37. data/lib/samagotchi/bundles/mcp/tools.rb +232 -0
  38. data/lib/samagotchi/bundles/system/config_modification_protocol.md +10 -2
  39. data/lib/samagotchi/bundles/system/manifest.yml +2 -2
  40. data/lib/samagotchi/cli/parent_wait.rb +5 -3
  41. data/lib/samagotchi/command_intake.rb +7 -0
  42. data/lib/samagotchi/commands/registry.rb +8 -3
  43. data/lib/samagotchi/continue_offer.rb +24 -15
  44. data/lib/samagotchi/engine/block_fix.rb +4 -4
  45. data/lib/samagotchi/engine/cards.rb +14 -5
  46. data/lib/samagotchi/engine/events.rb +10 -15
  47. data/lib/samagotchi/engine/models.rb +1 -1
  48. data/lib/samagotchi/engine/plugins.rb +3 -0
  49. data/lib/samagotchi/engine/recap.rb +1 -1
  50. data/lib/samagotchi/engine/side_requests.rb +1 -1
  51. data/lib/samagotchi/engine/sign_in.rb +142 -0
  52. data/lib/samagotchi/engine/turn_end.rb +3 -3
  53. data/lib/samagotchi/engine.rb +43 -27
  54. data/lib/samagotchi/engine_snapshots.rb +1 -1
  55. data/lib/samagotchi/guardrail_wiring.rb +3 -1
  56. data/lib/samagotchi/guardrails/protected_paths.rb +51 -2
  57. data/lib/samagotchi/guardrails/verdict.rb +3 -2
  58. data/lib/samagotchi/hold_stop.rb +4 -4
  59. data/lib/samagotchi/idle_recap.rb +19 -11
  60. data/lib/samagotchi/idle_reminders.rb +7 -5
  61. data/lib/samagotchi/idle_scheduler.rb +7 -10
  62. data/lib/samagotchi/installed_bundles/dir.rb +37 -0
  63. data/lib/samagotchi/installed_bundles/manifest.rb +7 -1
  64. data/lib/samagotchi/installed_bundles/plugin_ref.rb +9 -5
  65. data/lib/samagotchi/installed_bundles/record.rb +3 -2
  66. data/lib/samagotchi/installed_bundles/standing.rb +3 -1
  67. data/lib/samagotchi/llm/http.rb +96 -5
  68. data/lib/samagotchi/mcp_command.rb +110 -0
  69. data/lib/samagotchi/mcp_server/http.rb +112 -0
  70. data/lib/samagotchi/mcp_server/protocol.rb +244 -0
  71. data/lib/samagotchi/mcp_server/stdio.rb +92 -0
  72. data/lib/samagotchi/mcp_server/text.rb +155 -0
  73. data/lib/samagotchi/mcp_server/tools.rb +245 -0
  74. data/lib/samagotchi/memory_bundle/asset_installer.rb +40 -12
  75. data/lib/samagotchi/memory_bundle/builder.rb +20 -2
  76. data/lib/samagotchi/memory_bundle/installed_copy.rb +1 -1
  77. data/lib/samagotchi/memory_bundle/installer.rb +16 -3
  78. data/lib/samagotchi/memory_bundle/provenance.rb +18 -1
  79. data/lib/samagotchi/memory_bundle/shas.rb +6 -4
  80. data/lib/samagotchi/memory_bundle/shipped_update.rb +7 -3
  81. data/lib/samagotchi/memory_bundle/status.rb +15 -6
  82. data/lib/samagotchi/memory_bundle/uninstaller.rb +9 -4
  83. data/lib/samagotchi/plugin/api.rb +6 -1
  84. data/lib/samagotchi/plugin/card.rb +36 -11
  85. data/lib/samagotchi/plugin/context.rb +63 -6
  86. data/lib/samagotchi/plugin/http.rb +40 -15
  87. data/lib/samagotchi/plugin/http_errors.rb +15 -0
  88. data/lib/samagotchi/plugin/http_stream.rb +86 -0
  89. data/lib/samagotchi/plugin/http_transport.rb +58 -16
  90. data/lib/samagotchi/plugin/loader.rb +18 -11
  91. data/lib/samagotchi/plugin/secrets.rb +266 -0
  92. data/lib/samagotchi/plugin/sign_in.rb +392 -0
  93. data/lib/samagotchi/plugin/sse_reader.rb +103 -0
  94. data/lib/samagotchi/queued_command.rb +28 -4
  95. data/lib/samagotchi/recap_setup.rb +13 -4
  96. data/lib/samagotchi/ref.rb +3 -2
  97. data/lib/samagotchi/relay_verifier.rb +8 -7
  98. data/lib/samagotchi/relay_watcher.rb +4 -4
  99. data/lib/samagotchi/run_options.rb +2 -1
  100. data/lib/samagotchi/send_command.rb +54 -41
  101. data/lib/samagotchi/session_access/ask.rb +244 -0
  102. data/lib/samagotchi/session_access/contract.rb +5 -0
  103. data/lib/samagotchi/session_access/exchange/token.rb +101 -0
  104. data/lib/samagotchi/session_access/exchange.rb +173 -0
  105. data/lib/samagotchi/session_access/local.rb +25 -6
  106. data/lib/samagotchi/session_access/remote.rb +4 -1
  107. data/lib/samagotchi/session_command_catalog.rb +10 -0
  108. data/lib/samagotchi/session_commands.rb +17 -0
  109. data/lib/samagotchi/session_config.rb +4 -4
  110. data/lib/samagotchi/session_observer.rb +27 -0
  111. data/lib/samagotchi/steer_cut.rb +4 -3
  112. data/lib/samagotchi/terminal_ui/attached_loop/sending.rb +4 -1
  113. data/lib/samagotchi/terminal_ui/formatting.rb +15 -0
  114. data/lib/samagotchi/testing/boundary.rb +4 -0
  115. data/lib/samagotchi/testing/bundle.rb +48 -2
  116. data/lib/samagotchi/testing/fake_http.rb +60 -15
  117. data/lib/samagotchi/testing/host.rb +4 -1
  118. data/lib/samagotchi/testing/recorder.rb +45 -5
  119. data/lib/samagotchi/tools/tool_index.rb +14 -3
  120. data/lib/samagotchi/version.rb +1 -1
  121. data/lib/samagotchi/web/app.rb +8 -6
  122. data/lib/samagotchi/web/ask_routes.rb +292 -0
  123. data/lib/samagotchi/web/mcp_route.rb +88 -0
  124. data/lib/samagotchi/web/public/app.js +2 -3
  125. data/lib/samagotchi/web/public/block_frame.js +72 -11
  126. data/lib/samagotchi/web/public/block_host.js +44 -8
  127. data/lib/samagotchi/web/public/block_regions.js +126 -0
  128. data/lib/samagotchi/web/public/card.js +22 -9
  129. data/lib/samagotchi/web/public/card_actions.js +21 -0
  130. data/lib/samagotchi/web/public/card_kinds.js +1 -1
  131. data/lib/samagotchi/web/public/card_registry.js +3 -2
  132. data/lib/samagotchi/web/public/data.js +15 -12
  133. data/lib/samagotchi/web/public/delete_sheet.js +222 -162
  134. data/lib/samagotchi/web/public/diagram_wiring.js +28 -0
  135. data/lib/samagotchi/web/public/format.js +3 -0
  136. data/lib/samagotchi/web/public/index.html +52 -7
  137. data/lib/samagotchi/web/public/more_sheet.js +6 -4
  138. data/lib/samagotchi/web/public/picture_regions.js +243 -0
  139. data/lib/samagotchi/web/public/picture_viewer.js +113 -12
  140. data/lib/samagotchi/web/public/refs.js +5 -3
  141. data/lib/samagotchi/web/public/region_hit.js +144 -0
  142. data/lib/samagotchi/web/public/removal_sheet_model.js +275 -0
  143. data/lib/samagotchi/web/public/running_tasks.js +6 -4
  144. data/lib/samagotchi/web/public/session_actions.js +105 -100
  145. data/lib/samagotchi/web/session_access_routes.rb +14 -11
  146. data/lib/samagotchi/web/session_control.rb +31 -9
  147. data/lib/samagotchi/web/session_create.rb +2 -2
  148. data/lib/samagotchi/worker/child_side.rb +3 -2
  149. data/lib/samagotchi/worker/command_queue.rb +13 -13
  150. data/lib/samagotchi/worker/leave.rb +3 -3
  151. data/lib/samagotchi/worker/scratch.rb +6 -6
  152. data/lib/samagotchi/worker/signal_grace.rb +6 -5
  153. data/lib/samagotchi/worker/startup.rb +3 -3
  154. data/lib/samagotchi/worker/wake_turns.rb +4 -4
  155. data/lib/samagotchi/worker.rb +32 -21
  156. data/lib/samagotchi/worker_exit_claim.rb +1 -1
  157. data/lib/samagotchi/worker_idle_exit.rb +18 -9
  158. data/lib/samagotchi/worker_inbound.rb +12 -7
  159. data/lib/samagotchi/worker_participant_gate.rb +9 -7
  160. data/lib/samagotchi/worker_task_wakes.rb +7 -5
  161. metadata +31 -1
@@ -17,12 +17,17 @@ module Samagotchi
17
17
  # bundle.http.stub(:get, %r{/health\z}, status: 503, body: "down")
18
18
  # bundle.http.stub(:post, "http://127.0.0.1:9000/classify") { |req| { json: { label: req.json["text"] } } }
19
19
  # bundle.http.stub(:get, "http://127.0.0.1:9000/x", error: :refused) # also :timeout
20
+ # bundle.http.stub(:post, "http://127.0.0.1:9000/mcp", events: [{ data: "{}", id: "1" }, "plain data"])
21
+ # bundle.http.stub(:get, "http://127.0.0.1:9000/big", chunks: ["hel", "lo"])
20
22
  # bundle.http.requests # what the plugin sent, in order
21
23
  # bundle.http.unmatched # what no stub answered
22
24
  #
23
25
  # A String matches the full URL exactly (query included), a Regexp is
24
26
  # matched against it; the method too. Later stubs win. A stub answers
25
- # every matching call: a sequence is a block that counts.
27
+ # every matching call: a sequence is a block that counts. Any stub
28
+ # answers both ctx.http.request and ctx.http.stream: +events:+ (served
29
+ # as text/event-stream) is the SSE text to a request, +body:+ / +json:+
30
+ # one chunk to a stream.
26
31
  class FakeHttp
27
32
  # One request the plugin made (headers as the plugin gave them).
28
33
  # `method` shadows Object#method on purpose: it is the plugin's word (request.method == "POST").
@@ -67,17 +72,23 @@ module Samagotchi
67
72
  # @param json [Object, nil] a JSON body (with its Content-Type)
68
73
  # @param error [Symbol, nil] :refused or :timeout: the request fails
69
74
  # with the HttpError the real transport raises
75
+ # @param events [Array<Hash, String>, nil] Server-Sent Events, each
76
+ # { data:, event: nil, id: nil } or a String (its data), served as
77
+ # text/event-stream
78
+ # @param chunks [Array<String>, nil] the body, in these pieces (a
79
+ # stream reads them one by one)
70
80
  # @yield [Request] to decide per request: returns a Hash with the same
71
- # keywords (status:, headers:, body:, json:, error:) or a
72
- # Plugin::Http::Response
81
+ # keywords (status:, headers:, body:, json:, events:, chunks:,
82
+ # error:) or a Plugin::Http::Response
73
83
  # @return [self]
74
- def stub(method, url, status: 200, headers: {}, body: nil, json: nil, error: nil, &block)
84
+ def stub(method, url, status: 200, headers: {}, body: nil, json: nil, events: nil, chunks: nil, error: nil, &block)
75
85
  verb = method.to_s.upcase
76
86
  raise ArgumentError, "unknown HTTP method #{method.inspect}" unless Plugin::Http::METHODS.include?(verb)
77
87
  raise ArgumentError, "the URL is a String or a Regexp" unless url.is_a?(String) || url.is_a?(Regexp)
78
88
  raise ArgumentError, "unknown error #{error.inspect} (#{ERRORS.keys.join(", ")})" if error && !ERRORS.key?(error)
79
89
 
80
- answer = block || { status: status, headers: headers, body: body, json: json, error: error }
90
+ answer = block || { status: status, headers: headers, body: body, json: json, events: events, chunks: chunks,
91
+ error: error }
81
92
  @mutex.synchronize { @stubs << Stub.new(verb: verb, matcher: url, answer: answer) }
82
93
  self
83
94
  end
@@ -93,6 +104,34 @@ module Samagotchi
93
104
  # the only cancel it checks.
94
105
  # @raise [UnstubbedRequest, Plugin::HttpError, Plugin::HttpCancelled]
95
106
  def call(method:, uri:, headers:, body:, timeout:, cancel:)
107
+ respond(method, uri, headers, body, cancel)
108
+ end
109
+
110
+ # The streamed half of the contract (Plugin::Http#stream): the block
111
+ # gets a Plugin::Http::Stream over the stub's chunks (its events, or
112
+ # its body as one chunk).
113
+ # @return [Object] the block's value
114
+ def stream(method:, uri:, headers:, body:, timeout:, cancel:)
115
+ response, chunks = respond(method, uri, headers, body, cancel, chunked: true)
116
+ yield Plugin::Http::Stream.new(status: response.status, headers: response.headers,
117
+ reader: ->(&on_chunk) { chunks.each { |chunk| on_chunk.call(chunk.b) } })
118
+ end
119
+
120
+ # An event as SSE text: its event: and id: lines, a data: line per line.
121
+ def self.sse_text(event)
122
+ event = { data: event } unless event.is_a?(Hash)
123
+ event = event.transform_keys(&:to_sym)
124
+ lines = []
125
+ lines << "event: #{event[:event]}" if event[:event]
126
+ lines << "id: #{event[:id]}" if event[:id]
127
+ event[:data].to_s.split("\n", -1).each { |line| lines << "data: #{line}" }
128
+ "#{lines.join("\n")}\n\n"
129
+ end
130
+
131
+ private
132
+
133
+ # The stub's answer: a Response, and with +chunked+ the body's pieces.
134
+ def respond(method, uri, headers, body, cancel, chunked: false)
96
135
  raise Plugin::HttpCancelled, "#{method} #{where(uri)}: cancelled" if cancel&.cancelled?
97
136
 
98
137
  request = Request.new(method: method, url: uri.to_s, headers: headers.dup.freeze, body: body)
@@ -102,13 +141,13 @@ module Samagotchi
102
141
  end
103
142
  raise UnstubbedRequest, unstubbed_message(request) unless stub
104
143
 
105
- respond(request, uri, stub.answer.respond_to?(:call) ? stub.answer.call(request) : stub.answer)
144
+ answer = stub.answer.respond_to?(:call) ? stub.answer.call(request) : stub.answer
145
+ response, chunks = answer_of(request, uri, answer)
146
+ chunked ? [response, chunks] : response
106
147
  end
107
148
 
108
- private
109
-
110
- def respond(request, uri, answer)
111
- return answer if answer.is_a?(Plugin::Http::Response)
149
+ def answer_of(request, uri, answer)
150
+ return [answer, [answer.body]] if answer.is_a?(Plugin::Http::Response)
112
151
  raise ArgumentError, "a stub's block returns a Hash or a Plugin::Http::Response" unless answer.is_a?(Hash)
113
152
 
114
153
  if (error = answer[:error])
@@ -116,13 +155,19 @@ module Samagotchi
116
155
  end
117
156
 
118
157
  headers = (answer[:headers] || {}).to_h { |name, value| [name.to_s.downcase, value.to_s] }
119
- body = answer[:body].to_s
120
- unless answer[:json].nil?
121
- body = JSON.generate(answer[:json])
158
+ chunks = [answer[:body].to_s]
159
+ if !answer[:json].nil?
160
+ chunks = [JSON.generate(answer[:json])]
122
161
  headers = { "content-type" => "application/json" }.merge(headers)
162
+ elsif answer[:events]
163
+ chunks = Array(answer[:events]).map { |event| self.class.sse_text(event) }
164
+ headers = { "content-type" => "text/event-stream" }.merge(headers)
165
+ elsif answer[:chunks]
166
+ chunks = Array(answer[:chunks]).map(&:to_s)
123
167
  end
124
- body = "" if request.method == "HEAD"
125
- Plugin::Http::Response.new(status: Integer(answer[:status] || 200), headers: headers.freeze, body: body.dup)
168
+ chunks = [] if request.method == "HEAD"
169
+ body = Plugin::Http.text(chunks.join.b)
170
+ [Plugin::Http::Response.new(status: Integer(answer[:status] || 200), headers: headers.freeze, body: body), chunks]
126
171
  end
127
172
 
128
173
  def where(uri) = "#{uri.host}:#{uri.port}"
@@ -61,6 +61,7 @@ module Samagotchi
61
61
  use_toolkit: ->(name) { recorder.use_toolkit(name, toolkits.call) },
62
62
  load_tools: ->(names, bundle) { recorder.load_tools(names, bundle) },
63
63
  cancel_controller: ->(handler: false) { recorder[:cancelled] ? stopped : nil },
64
+ current_cancel: -> { recorder[:cancelled] ? stopped : nil },
64
65
  cost: -> { cost(recorder[:cost]) },
65
66
  usage: -> { usage(recorder[:usage]) },
66
67
  turn_author: -> { recorder[:turn_author] },
@@ -71,7 +72,9 @@ module Samagotchi
71
72
  # The candidate judge isn't the bundle's to test: a late proposal
72
73
  # goes nowhere.
73
74
  candidate_proposed: ->(_candidate) {},
74
- judgments: -> { recorder.judgments.layer }
75
+ judgments: -> { recorder.judgments.layer },
76
+ secrets_store: ->(_bundle) { recorder.secrets },
77
+ sign_in: ->(bundle, **options, &build) { recorder.sign_in(bundle, **options, &build) }
75
78
  )
76
79
  end
77
80
 
@@ -49,10 +49,13 @@ module Samagotchi
49
49
  # to restart), and the context size its confirm names (nil: none).
50
50
  history: false, context_tokens: nil,
51
51
  # ctx.model_names: nil gives model_name and its id without the host.
52
- model_names: nil
52
+ model_names: nil,
53
+ # ctx.secrets: seeds its in-memory store ({"name" => "value"}); a
54
+ # set replaces what it holds. bundle.secrets reads it.
55
+ secrets: nil
53
56
  }.freeze
54
57
 
55
- attr_reader :notices, :cards, :steers, :stops, :questions, :model_requests, :toolkit_uses, :tool_loads, :answers,
58
+ attr_reader :sign_ins, :notices, :cards, :steers, :stops, :questions, :model_requests, :toolkit_uses, :tool_loads, :answers,
56
59
  :model_answers, :values
57
60
 
58
61
  def initialize(**values)
@@ -60,7 +63,10 @@ module Samagotchi
60
63
  raise ArgumentError, "unknown host values: #{unknown.join(", ")}" unless unknown.empty?
61
64
 
62
65
  @values = DEFAULTS.merge(values)
66
+ @secrets = Plugin::Secrets::MemoryStore.new
67
+ @secrets.replace(@values[:secrets] || {})
63
68
  @notices = []
69
+ @sign_ins = []
64
70
  @cards = []
65
71
  @steers = []
66
72
  @stops = []
@@ -79,9 +85,14 @@ module Samagotchi
79
85
  raise ArgumentError, "unknown host values: #{unknown.join(", ")}" unless unknown.empty?
80
86
 
81
87
  @mutex.synchronize { @values.merge!(values) }
88
+ @secrets.replace(values[:secrets] || {}) if values.key?(:secrets)
82
89
  self
83
90
  end
84
91
 
92
+ # ctx.secrets' store: in memory, the one for the bundle under test.
93
+ # @return [Plugin::Secrets::MemoryStore]
94
+ attr_reader :secrets
95
+
85
96
  def [](key) = @mutex.synchronize { @values.fetch(key) }
86
97
 
87
98
  # ctx.judge and ctx.judge_later's System 1 (Testing::Judgments).
@@ -97,13 +108,42 @@ module Samagotchi
97
108
  nil
98
109
  end
99
110
 
100
- # Checked as chi's cards are (Plugin::Card.build); the id it shows.
101
- def card(**fields)
102
- card = Plugin::Card.build(**fields).freeze
111
+ # Checked as chi's cards are (Plugin::Card.build); the id it shows. A
112
+ # card shown with between_turns: true is recorded with it.
113
+ def card(between_turns: false, **fields)
114
+ card = Plugin::Card.build(**fields)
115
+ card = card.merge(between_turns: true) if between_turns
116
+ card.freeze
103
117
  record(@cards, card)
104
118
  card[:id]
105
119
  end
106
120
 
121
+ # The port a kit flow's redirect_uri names: none is opened.
122
+ SIGN_IN_PORT = 53_682
123
+
124
+ # ctx.sign_in, as chi starts one (Engine#start_sign_in) but with no
125
+ # port opened: the card with its button, the flow listed in
126
+ # #sign_ins; Bundle#complete_sign_in / #fail_sign_in settle it. An
127
+ # ending without a callback replaces its card as chi does.
128
+ # @return [Plugin::SignIn]
129
+ def sign_in(bundle, title:, button:, timeout:, port:, path:, cancel: nil, &build)
130
+ redirect_uri = "http://127.0.0.1:#{port || SIGN_IN_PORT}#{path}"
131
+ flow = Plugin::SignIn.new(bundle: bundle, title: title, button: button, timeout: timeout, listener: nil,
132
+ redirect_uri: redirect_uri, cancel: cancel,
133
+ on_settle: lambda { |settled, outcome|
134
+ ended = Plugin::SignIn.ended_card(settled, outcome)
135
+ card(source: bundle, level: :info, **ended) if ended
136
+ })
137
+ address = yield(redirect_uri).to_s.strip
138
+ id = Plugin::Card.build(source: bundle, title: title, body: "", actions: [{ label: button, url: address }],
139
+ level: :info, id: nil)[:id]
140
+ flow.started(address, id)
141
+ card(source: bundle, title: title, body: Plugin::SignIn::PASTE_LINE, actions: [{ label: button, url: address }],
142
+ level: :info, id: id)
143
+ record(@sign_ins, flow)
144
+ flow
145
+ end
146
+
107
147
  def steer(text, hook)
108
148
  return false unless self[:running]
109
149
 
@@ -130,7 +130,7 @@ module Samagotchi
130
130
  end
131
131
 
132
132
  # A Group's states.
133
- STATES = %i[ready starting failed].freeze
133
+ STATES = %i[ready starting failed needs_user].freeze
134
134
 
135
135
  # A search's answer (#find): its text, and the tools it loads on a host
136
136
  # that loads tools (+loaded+: the wire names of a keyword answer's
@@ -148,7 +148,10 @@ module Samagotchi
148
148
  # One group of a source's tools (an MCP server): +summary+ its line in
149
149
  # the search tool's description (nil: its name and tool count only),
150
150
  # +state+ :ready, :starting (its tools may come: a lookup waits) or
151
- # :failed (+error+ says why). A group exists before its tools do.
151
+ # :failed (+error+ says why), :needs_user (it can't be used until the
152
+ # user does something: +error+ is the source's own line, a sign-in's;
153
+ # a call that names it asks the source's wait first).
154
+ # A group exists before its tools do.
152
155
  # Another state, or a tool of another group, raises ArgumentError (a
153
156
  # lookup would neither wait on it nor find the tool's source).
154
157
  Group = Data.define(:name, :summary, :state, :error, :tools) do
@@ -162,6 +165,7 @@ module Samagotchi
162
165
  end
163
166
 
164
167
  summary = summary.to_s.strip
168
+ error = "#{name} needs the user" if state == :needs_user && error.to_s.strip.empty?
165
169
  super(name: name.to_s, summary: summary.empty? ? nil : summary, state: state, error: error,
166
170
  tools: tools.dup.freeze)
167
171
  end
@@ -174,6 +178,7 @@ module Samagotchi
174
178
  case state
175
179
  when :failed then "(failed: #{error})"
176
180
  when :starting then "(starting, try again)"
181
+ when :needs_user then "(#{error})"
177
182
  end
178
183
  end
179
184
  end
@@ -756,9 +761,12 @@ module Samagotchi
756
761
  end
757
762
 
758
763
  # A name with a group's <group>/ waits for that group only; any
759
- # other name (an acts_as) for every one starting.
764
+ # other name (an acts_as) for every one starting. A group that needs
765
+ # the user, named, is asked too: the user may have done it meanwhile
766
+ # (signed in from another session).
760
767
  named = reached_groups(surface).select { |group| name.start_with?("#{group.name}/") }
761
768
  starting = (named.empty? ? reached_groups(surface) : named).select { |group| group.state == :starting }
769
+ starting += named.select { |group| group.state == :needs_user }
762
770
  unless waited || starting.empty?
763
771
  starting.each { |group| source_of(group.name)&.wait(group.name) }
764
772
  return lookup(name, surface, waited: true)
@@ -767,6 +775,9 @@ module Samagotchi
767
775
  failed = all.find { |group| group.state == :failed && name.start_with?("#{group.name}/") }
768
776
  return "Error: MCP server #{failed.name} didn't start: #{failed.error}" if failed
769
777
 
778
+ blocked = all.find { |group| group.state == :needs_user && name.start_with?("#{group.name}/") }
779
+ return "Error: #{blocked.error}" if blocked
780
+
770
781
  closest = ranked(name, all.flat_map(&:tools)).take(CLOSEST)
771
782
  return "Error: no tool #{name}. Search with #{FIND_NAME}." if closest.empty?
772
783
 
@@ -1,7 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Samagotchi
4
- VERSION = "0.182.0"
4
+ VERSION = "0.183.0"
5
5
  # Sent as the User-Agent of every HTTP request chi makes.
6
6
  USER_AGENT = "chi/#{VERSION}"
7
7
  end
@@ -303,7 +303,7 @@ module Samagotchi
303
303
  ["POST", %r{\A/api/update\z}, :handle_update, :owner],
304
304
  ["POST", %r{\A/api/update/restart_workers\z}, :handle_restart_workers, :owner],
305
305
  ["POST", %r{\A/api/update/restart_web\z}, :handle_restart_web, :owner],
306
- ["POST", %r{\A/api/render\z}, :handle_render, :owner],
306
+ ["POST", %r{\A/api/render\z}, :handle_render, :owner], *McpRoute::ROUTES,
307
307
  ["GET", %r{\A/api/sessions/([^/]+)/stream\z}, :handle_stream, :participant],
308
308
  ["GET", %r{\A/api/sessions/([^/]+)/output\z}, :handle_output, :owner, :session],
309
309
  ["POST", %r{\A/api/sessions/([^/]+)/cancel\z}, :handle_cancel, :participant, :session],
@@ -318,6 +318,7 @@ module Samagotchi
318
318
  ["POST", %r{\A/api/sessions/([^/]+)/turn\z}, :handle_turn, :participant, :session],
319
319
  ["POST", %r{\A/api/sessions/([^/]+)/wait/prepare\z}, :handle_wait_prepare, :participant, :session],
320
320
  ["POST", %r{\A/api/sessions/([^/]+)/wait\z}, :handle_wait, :participant, :session],
321
+ ["POST", %r{\A/api/sessions/([^/]+)/ask\z}, :handle_ask, :owner, :session],
321
322
  ["POST", %r{\A/api/sessions/([^/]+)/verdicts/([^/]+)/fresh\z}, :handle_verify_fresh, :participant, :session],
322
323
  ["POST", %r{\A/api/sessions/([^/]+)/blocks/fix\z}, :handle_block_fix, :owner, :session],
323
324
  ["POST", %r{\A/api/sessions/([^/]+)/notes\z}, :handle_notes, :owner, :session],
@@ -833,7 +834,7 @@ module Samagotchi
833
834
  def unauthorized(req)
834
835
  reason = req.env[REFUSED_ENV]
835
836
  log_refused(refused_peer(req), req.path_info, reason)
836
- return error_response(401, "unauthorized", unauthorized_detail(req, reason)) if req.path_info.start_with?("/api/")
837
+ return api_unauthorized(req, unauthorized_detail(req, reason)) if req.path_info.start_with?("/api/")
837
838
 
838
839
  body = unauthorized_page(req)
839
840
  [401, { "Content-Type" => "text/html; charset=utf-8", "Content-Length" => body.bytesize.to_s, "Cache-Control" => "no-store" },
@@ -1126,7 +1127,7 @@ module Samagotchi
1126
1127
  # delegates: chi --remote sessions delete --dry-run asks for this first.
1127
1128
  DELETE_PLAN_FEATURE = "delete_plan_all"
1128
1129
  INFO_FEATURES = ["dir", "newest_workers", SessionAccessRoutes::FEATURE, SessionAccessRoutes::ATTACH_FEATURE,
1129
- BOUND_FEATURE, CHAIN_DELETE_FEATURE, STOP_TASKS_FEATURE, DELETE_PLAN_FEATURE].freeze
1130
+ BOUND_FEATURE, CHAIN_DELETE_FEATURE, STOP_TASKS_FEATURE, DELETE_PLAN_FEATURE, ASK_FEATURE, McpRoute::FEATURE].freeze
1130
1131
 
1131
1132
  # The models a new session can start on, spelled as chi spells them
1132
1133
  # elsewhere: bare for the default host (what default.model holds), and
@@ -1149,6 +1150,7 @@ module Samagotchi
1149
1150
  # (SessionManager::ScratchSession, an OwnedByTUI: 409).
1150
1151
  def record_history(body, line)
1151
1152
  return if body["history"] == false
1153
+ return if SessionCommandCatalog.builtin_registry.private_args?(line.to_s) # /callback's argument stays out
1152
1154
 
1153
1155
  PromptHistory.append(line.to_s)
1154
1156
  rescue StandardError => e
@@ -1416,11 +1418,11 @@ module Samagotchi
1416
1418
  error_response(504, "worker_timeout", "the session's worker did not answer, so #{what}")
1417
1419
  end
1418
1420
 
1419
- # The session's Bridge, waiting briefly for one a resume just spawned.
1421
+ # The session's Bridge, waiting briefly (5 s, or +within+ an ask's left) for one a resume just spawned.
1420
1422
  # @return [BridgeClient, nil]
1421
- def live_bridge_client(id)
1423
+ def live_bridge_client(id, within: 5.0)
1422
1424
  link = worker_link(id)
1423
- link = await_worker_link(id, timeout: [@bridge_wait_timeout.to_f, 5.0].min) unless link.live?
1425
+ link = await_worker_link(id, timeout: [@bridge_wait_timeout.to_f, within].min.clamp(0.0..)) unless link.live?
1424
1426
  link_client(id, link)
1425
1427
  end
1426
1428
 
@@ -0,0 +1,292 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "delegate"
4
+ require_relative "../client_id"
5
+ require_relative "../reply_wait"
6
+ require_relative "../session"
7
+ require_relative "../session_command_catalog"
8
+ require_relative "../session_inbox"
9
+ require_relative "../turn_flow"
10
+ require_relative "../session_access/ask"
11
+ require_relative "../session_access/exchange"
12
+ require_relative "../session_access/exchange/token"
13
+ require_relative "request_body"
14
+
15
+ module Samagotchi
16
+ module Web
17
+ # The thin-client routes (docs/thin-clients.md): POST …/ask (one
18
+ # message, its answer in one call: SessionAccess::Ask), a wait token for
19
+ # POST …/wait (#handle_token_wait), wait: on POST …/answer
20
+ # (#answer_wait_option, #answered_wait) and a create's token
21
+ # (#create_token). Included in App through SessionAccessRoutes; its
22
+ # helpers (json_response, body_hash, wait_result_json, busy_json,
23
+ # parent_gate, owned_by_tui, refused_delivery, record_history, …) answer.
24
+ module AskRoutes
25
+ # One ask answers within this many seconds from its request's start,
26
+ # whatever it waits for (a continue in flight, the Bridge of a worker
27
+ # starting, the wait's slice): a proxy or a Shortcut with a 60 s limit
28
+ # is safe. Only the post to a live worker isn't drawn from it: it is
29
+ # instant unless the worker hangs (BridgeClient's 25 s deadline).
30
+ ASK_MAX_SECONDS = 35.0
31
+ # A wait route answers within this many seconds (status timeout); the
32
+ # client asks again until its own --timeout. SessionAccessRoutes'
33
+ # (which includes this module) too.
34
+ WAIT_MAX_SECONDS = 30.0
35
+ # GET /api/info's feature: this chi web has the ask route, wait
36
+ # tokens, the answer's wait and the create's token.
37
+ ASK_FEATURE = "ask"
38
+ # The wait body's own fields, which a token replaces.
39
+ TOKEN_EXCLUDES = %w[cursor baseline turn queued ended_before owner_grace].freeze
40
+
41
+ # The ask's backend: chi web's sessions (SessionAccess::Local),
42
+ # delivering through chi web's own manager and Bridge as POST …/turn
43
+ # does (the same Bridge wait and give-ups), and waiting at its poll
44
+ # interval. One per request.
45
+ class AskAccess < SimpleDelegator
46
+ def initialize(access, manager:, bridge:, poll_interval: nil)
47
+ super(access)
48
+ @manager = manager
49
+ @bridge = bridge
50
+ @poll_interval = poll_interval
51
+ end
52
+
53
+ def deliver_turn(id, **)
54
+ __getobj__.deliver_turn(id, **, manager: @manager, bridge: -> { @bridge.call(id) })
55
+ end
56
+
57
+ def wait_reply(id, **options)
58
+ options = { poll_interval: @poll_interval }.merge(options) if @poll_interval
59
+ __getobj__.wait_reply(id, **options)
60
+ end
61
+ end
62
+
63
+ private
64
+
65
+ # POST /api/sessions/:id/ask {prompt, timeout, queue, client_id}: the
66
+ # message delivered (to a chain's newest link; a running session
67
+ # queues it as its own turn unless queue is false) and its answer
68
+ # waited for, all within ASK_MAX_SECONDS. 200 wait_result_json's
69
+ # fields + session_id (+ asked, the id given, when another link ran
70
+ # it; + token when the status is timeout: POST …/wait {token} goes
71
+ # on); 200 {status: command} for a session command. 404 not_found,
72
+ # 400 ambiguous_id, 409 busy / waiting / continuing / owned_by_tui,
73
+ # the turn route's delivery refusals, 503 server_stopping.
74
+ def handle_ask(req, id)
75
+ # One deadline from the request's start: the gate, the continue
76
+ # waits, the Bridge wait and the slice all draw on it.
77
+ deadline = ask_clock + ASK_MAX_SECONDS
78
+ body = body_hash(req) or return error_response(400, "invalid_json", "invalid JSON body")
79
+ prompt, client_id, options, error = ask_request(id, body)
80
+ return error if error
81
+
82
+ gated = ask_gate(id, prompt, client_id)
83
+ return gated if gated
84
+
85
+ bridge = ->(sid) { live_bridge_client(sid, within: deadline - ask_clock) }
86
+ access = AskAccess.new(session_access, manager: @manager, bridge: bridge, poll_interval: @wait_poll_interval)
87
+ stopping = -> { !@server_running.call }
88
+ exchange = SessionAccess::Exchange.new(access, continuing_wait: [SessionAccess::Exchange::CONTINUING_WAIT,
89
+ ASK_MAX_SECONDS].min, cancelled: stopping)
90
+ outcome = SessionAccess::Ask.new(access, exchange: exchange)
91
+ .call(id, prompt: prompt, client_id: client_id, cap: deadline - ask_clock,
92
+ cancelled: stopping, **options)
93
+ record_history(body, prompt) unless outcome.is_a?(SessionAccess::Ask::Refused)
94
+ ask_response(id, outcome)
95
+ rescue SessionManager::OwnedByTUI => e
96
+ owned_by_tui(e)
97
+ end
98
+
99
+ # The ask's body read: [prompt, client_id, {queue:, timeout:}, nil] or
100
+ # [.., a 400 response].
101
+ def ask_request(id, body)
102
+ return [nil, nil, nil, error_response(400, "missing_fields", "prompt is required")] unless body["prompt"].is_a?(String)
103
+
104
+ prompt = SessionInbox.checked_text(body["prompt"], noun: "message")
105
+ if (entry = SessionCommandCatalog.ui_only_entry(prompt))
106
+ words = SessionCommandCatalog.ui_only_refusal(entry.name, id, runner: "ask")
107
+ return [nil, nil, nil, error_response(400, "local_command", words)]
108
+ end
109
+
110
+ timeout = body.fetch("timeout", WAIT_MAX_SECONDS)
111
+ unless timeout.is_a?(Numeric) && timeout.positive?
112
+ return [nil, nil, nil, error_response(400, "invalid_ask", "timeout is positive seconds")]
113
+ end
114
+
115
+ queue = body.fetch("queue", true)
116
+ return [nil, nil, nil, error_response(400, "invalid_ask", "queue is true or false")] unless [true, false].include?(queue)
117
+
118
+ client_id = body["client_id"]
119
+ return [nil, nil, nil, error_response(400, "invalid_ask", "client_id is a string")] unless client_id.nil? || client_id.is_a?(String)
120
+
121
+ [prompt, ask_sender(client_id, prompt), { queue: queue, timeout: [timeout, WAIT_MAX_SECONDS].min }, nil]
122
+ rescue SessionInbox::NoteRejected => e
123
+ [nil, nil, nil, error_response(400, "invalid_prompt", e.message)]
124
+ end
125
+
126
+ # Who asks: the owner (WEB_UNNAMED) unless the body names a sender
127
+ # (owner_sender's rule); a parent agent's /continue yes sent as
128
+ # cli:send goes in as cli:answer, as chi send sends it (the worker
129
+ # holds that one to guardrails.parent_answers).
130
+ def ask_sender(client_id, prompt)
131
+ sender = owner_sender({ "client_id" => client_id })
132
+ sender == ClientId::CLI_SEND && TurnFlow.continue_yes?(prompt) ? ClientId::CLI_ANSWER : sender
133
+ end
134
+
135
+ # A parent agent's line refused before anything is sent, as POST
136
+ # …/turn refuses it (#parent_gate), held to the parent_answers of the
137
+ # session asked and of its chain's newest link (where it goes).
138
+ # @return [Array, nil] the response, or nil to go on
139
+ def ask_gate(id, prompt, client_id)
140
+ return nil unless App::CLI_SEND_IDS.include?(client_id)
141
+
142
+ asked = session_access.resolve(id)
143
+ ids = [asked, session_access.head(asked).id].uniq
144
+ sessions = ids.select { |sid| File.file?(Session.session_file(sid, state_dir: default_state_dir)) }
145
+ values = sessions.map { |sid| session_access.show(sid).parent_answers }
146
+ # No session left to read: config.yml's value alone (fail closed),
147
+ # as SendCommand::ParentGate#target_values falls back.
148
+ values = [nil] if values.empty?
149
+ parent_gate(prompt, client_id: client_id, values: values)
150
+ rescue ArgumentError # degrade-ok: no such session, or a prefix of several: the ask's own answer says which
151
+ nil
152
+ end
153
+
154
+ # The ask's answer for an Ask value.
155
+ def ask_response(id, outcome)
156
+ case outcome
157
+ when SessionAccess::Ask::Ran then json_response(200, { status: "command", session_id: outcome.session_id })
158
+ when SessionAccess::Ask::Refused then ask_refused(id, outcome)
159
+ else
160
+ result = outcome.result
161
+ return error_response(503, "server_stopping", "chi web is stopping; wait again") if result.status == :canceled
162
+
163
+ json = wait_result_json(result, session_access.parent_strategy(outcome.session_id)).merge(session_id: outcome.session_id)
164
+ json[:asked] = outcome.asked if outcome.asked && outcome.asked != outcome.session_id
165
+ json[:token] = outcome.token if outcome.token
166
+ json_response(200, json)
167
+ end
168
+ end
169
+
170
+ # Neutral words for a Busy, not chi send's flags.
171
+ ASK_BUSY_WORDS = { "busy" => "a turn is running: ask with queue, or wait for it",
172
+ "waiting" => "a question waits for an answer" }.freeze
173
+
174
+ def ask_refused(id, refused)
175
+ case refused.kind
176
+ when :canceled then error_response(503, "server_stopping", "chi web is stopping; ask again")
177
+ when :unknown
178
+ error = refused.error
179
+ return refusal_response(400, "ambiguous_id", error, ids: error.ids) if error.is_a?(Session::AmbiguousId)
180
+
181
+ session_not_found(id)
182
+ when :continuing then refusal(409, "continuing", refused.message, session_id: refused.session_id)
183
+ when :busy
184
+ words = ASK_BUSY_WORDS.fetch(refused.busy.error)
185
+ json_response(409, busy_json(refused.busy).merge(detail: words, message: words))
186
+ else refused_delivery(refused.result)
187
+ end
188
+ end
189
+
190
+ # POST /api/sessions/:id/wait {token, timeout}: the wait a token holds
191
+ # (an ask's, a create's, an answer's), for at most WAIT_MAX_SECONDS.
192
+ # The URL's id may be a prefix. 200 wait_result_json's fields +
193
+ # session_id (+ token, the same, while the status is timeout); 400 invalid_wait for a token that isn't one,
194
+ # another session's, a token beside the wait's own fields, or a
195
+ # participant's; 503 server_stopping.
196
+ def handle_token_wait(req, id, body)
197
+ return error_response(400, "invalid_wait", "a participant's wait takes a turn, not a token") unless principal(req).owner?
198
+ if TOKEN_EXCLUDES.any? { |key| ![nil, false].include?(body[key]) }
199
+ return error_response(400, "invalid_wait", "token or the wait's fields, not both")
200
+ end
201
+
202
+ timeout = body["timeout"]
203
+ unless timeout.nil? || (timeout.is_a?(Numeric) && timeout.positive?)
204
+ return error_response(400, "invalid_wait", "timeout is positive seconds")
205
+ end
206
+
207
+ session_id, target = SessionAccess::Exchange::Token.load(body["token"])
208
+ # The URL's id may be a prefix (as the ask's): resolved first (no
209
+ # such session, or several: session_route's 404).
210
+ full = session_access.resolve(id)
211
+ return error_response(400, "invalid_wait", "the token is another session's wait") unless session_id == full
212
+
213
+ result = plain_exchange.wait(full, target, timeout: [timeout || WAIT_MAX_SECONDS, WAIT_MAX_SECONDS].min,
214
+ **wait_extras)
215
+ return error_response(503, "server_stopping", "chi web is stopping; wait again") if result.status == :canceled
216
+
217
+ json = wait_result_json(result, session_access.parent_strategy(full)).merge(session_id: full)
218
+ json[:token] = body["token"] if result.status == :timeout
219
+ json_response(200, json)
220
+ rescue SessionAccess::Exchange::Token::Invalid => e
221
+ error_response(400, "invalid_wait", e.message)
222
+ end
223
+
224
+ # The answer's wait: [seconds, nil] (nil seconds: none asked), or
225
+ # [nil, a 400 response].
226
+ def answer_wait_option(body)
227
+ wait = body["wait"]
228
+ return [nil, nil] if wait.nil? || wait == false
229
+ return [nil, error_response(400, "invalid_wait", "wait is positive seconds")] unless wait.is_a?(Numeric) && wait.positive?
230
+
231
+ [[wait, WAIT_MAX_SECONDS].min, nil]
232
+ end
233
+
234
+ # What an answer's wait reads before the answer goes in
235
+ # (AnswerCommand's): the answered question is not the next thing.
236
+ # @return [WaitStart, nil] nil: the session is gone
237
+ def answer_wait_start(id, session, question_id)
238
+ session_access.prepare_wait(id, session: session, question_id: question_id.to_s)
239
+ rescue ArgumentError # degrade-ok: deleted meanwhile, the answer's 404
240
+ nil
241
+ end
242
+
243
+ # POST …/answer with wait: the answer relayed (+answered+; false: the
244
+ # question was answered elsewhere first, as chi answer still waits)
245
+ # and what comes next, for up to +seconds+. 200 {status: answered |
246
+ # not_pending, (answered_here: false,) session_id, id, reply:
247
+ # {wait_result_json's fields, token while it is timeout}}. The answer
248
+ # went in before the wait, so a wait that fails (chi web stopping, the
249
+ # session deleted, its files unreadable) is still a 200: wait_error
250
+ # {error: server_stopping | not_found | wait_failed, detail} in place
251
+ # of reply (an answer retried would be 409).
252
+ def answered_wait(id, question_id, start, seconds, answered:)
253
+ head = answered ? { status: "answered" } : { status: "not_pending", answered_here: false }
254
+ head = { **head, session_id: id, id: question_id }
255
+ target = ReplyWait::Target.answer(start)
256
+ result = plain_exchange.wait(id, target, timeout: seconds, **wait_extras)
257
+ if result.status == :canceled
258
+ return answer_wait_error(head, "server_stopping", "chi web is stopping; the answer went in")
259
+ end
260
+
261
+ reply = wait_result_json(result, session_access.parent_strategy(id))
262
+ reply[:token] = SessionAccess::Exchange::Token.dump(id, target) if result.status == :timeout
263
+ json_response(200, { **head, reply: reply })
264
+ rescue ArgumentError => e # deleted while waiting
265
+ answer_wait_error(head, "not_found", e.message)
266
+ rescue SystemCallError, IOError => e
267
+ answer_wait_error(head, "wait_failed", "#{e.class}: #{e.message}")
268
+ end
269
+
270
+ def answer_wait_error(head, error, detail) = json_response(200, { **head, wait_error: { error: error, detail: detail } })
271
+
272
+ # A create's 201 token, for a session started with its first turn
273
+ # (first_turn_id): POST …/wait {token} answers that turn. {} for an
274
+ # idle one.
275
+ def create_token(session)
276
+ turn = session.first_turn_id.to_s
277
+ return {} if turn.empty?
278
+
279
+ start = session_access.prepare_wait(session.id, session: (session if session.is_a?(Session)), created: true)
280
+ target = ReplyWait::Target.first_message(start, nil, direct_turn: turn)
281
+ { token: SessionAccess::Exchange::Token.dump(session.id, target) }
282
+ end
283
+
284
+ def plain_exchange = SessionAccess::Exchange.new(session_access)
285
+
286
+ # The ask's deadline clock (the Exchange's: monotonic seconds).
287
+ def ask_clock = Process.clock_gettime(Process::CLOCK_MONOTONIC)
288
+
289
+ def wait_extras = { poll_interval: @wait_poll_interval, cancelled: -> { !@server_running.call } }.compact
290
+ end
291
+ end
292
+ end