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
@@ -0,0 +1,103 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Samagotchi
4
+ module Plugin
5
+ class Http
6
+ # A plain Server-Sent Events reader (ctx.http.stream's Stream#each_event),
7
+ # fed the body's chunks as they arrive:
8
+ #
9
+ # reader = SseReader.new
10
+ # reader.feed(chunk) { |event| … } # each event whose blank line came
11
+ #
12
+ # The fields are `event`, `data` and `id`; several `data:` lines join
13
+ # with "\n"; one space after the colon is dropped; a line starting
14
+ # with ":" is a comment. Lines end in "\n", "\r\n" or "\r", and a
15
+ # chunk may end anywhere (mid-line, between "\r" and "\n", inside a
16
+ # UTF-8 character): bytes are kept until an event is whole, and its
17
+ # text is decoded then. An event is dispatched at its blank line; one
18
+ # the body's end cuts off is dropped; an event without data isn't
19
+ # yielded. The last `id` carries over to later events, as in a
20
+ # browser's EventSource.
21
+ class SseReader
22
+ # One event: +type+ is "message" when the stream named none.
23
+ Event = Data.define(:type, :data, :id)
24
+
25
+ BOM = "\xEF\xBB\xBF".b
26
+
27
+ def initialize
28
+ @buffer = +"".b
29
+ @skip_lf = false
30
+ @started = false
31
+ @id = nil
32
+ reset
33
+ end
34
+
35
+ # @param chunk [String] the next bytes of the body
36
+ # @yield [Event] each event the chunk completes
37
+ # @return [void]
38
+ def feed(chunk, &)
39
+ bytes = chunk.to_s.b
40
+ return if bytes.empty?
41
+
42
+ if @skip_lf
43
+ @skip_lf = false
44
+ bytes = bytes.delete_prefix("\n")
45
+ end
46
+ @buffer << bytes
47
+ unless @started
48
+ return if BOM.start_with?(@buffer) # all of it may still be a BOM
49
+
50
+ @started = true
51
+ @buffer = @buffer.delete_prefix(BOM)
52
+ end
53
+ lines(&)
54
+ end
55
+
56
+ private
57
+
58
+ def lines(&)
59
+ while (at = @buffer.index(/[\r\n]/))
60
+ line = @buffer.byteslice(0, at)
61
+ ending = if @buffer.byteslice(at, 2) == "\r\n" then 2
62
+ else
63
+ @skip_lf = true if @buffer.bytesize == at + 1 && @buffer.byteslice(at) == "\r"
64
+ 1
65
+ end
66
+ @buffer = @buffer.byteslice((at + ending)..)
67
+ line(line, &)
68
+ end
69
+ end
70
+
71
+ def line(line, &)
72
+ return dispatch(&) if line.empty?
73
+ return if line.start_with?(":")
74
+
75
+ field, value = line.split(":", 2)
76
+ value = value.to_s.delete_prefix(" ")
77
+ case field
78
+ when "event" then @type = value
79
+ when "data" then (@data ||= []) << value
80
+ when "id" then @id = text(value) unless value.include?("\0")
81
+ end
82
+ end
83
+
84
+ def dispatch
85
+ data = @data
86
+ type = @type
87
+ reset
88
+ return unless data
89
+
90
+ yield Event.new(type: type.nil? || type.empty? ? "message" : text(type), data: text(data.join("\n")), id: @id)
91
+ end
92
+
93
+ def reset
94
+ @data = nil
95
+ @type = nil
96
+ end
97
+
98
+ # The event's bytes as UTF-8, a broken sequence replaced.
99
+ def text(bytes) = bytes.dup.force_encoding(Encoding::UTF_8).scrub
100
+ end
101
+ end
102
+ end
103
+ end
@@ -13,16 +13,40 @@ module Samagotchi
13
13
  # after, a basename) and +enqueued_id+ (a file-delivered command's sender).
14
14
  # +author+: who sent it when it wasn't the owner ("p:<id>", as a turn's
15
15
  # origin author), nil for the owner.
16
+ # +private_args+: the arguments of a command whose catalog entry keeps
17
+ # them out of sight (/callback's address holds a one-time code): +line+,
18
+ # what every event, log line, bubble and echo reads, is then
19
+ # "/callback …", and only #run_line has them.
16
20
  QueuedCommand = Data.define(:command_id, :client_id, :line, :card, :mid_turn, :after_seq, :after_file, :enqueued_id,
17
- :author) do
21
+ :author, :private_args) do
18
22
  def initialize(command_id:, line:, client_id: nil, card: false, mid_turn: nil, after_seq: nil, after_file: nil,
19
- enqueued_id: nil, author: nil) = super
23
+ enqueued_id: nil, author: nil, private_args: nil) = super
24
+
25
+ # What #line shows for a command with private arguments.
26
+ HIDDEN = "…"
20
27
 
21
28
  # A new command with a fresh id.
22
- def self.mint(line, client_id: nil, card: false, author: nil)
23
- new(command_id: SecureRandom.uuid, client_id: client_id, line: line, card: card ? true : false, author: author)
29
+ # @param private_args [Boolean] its entry keeps the arguments out of
30
+ # sight (Commands::Registry#private_args?)
31
+ def self.mint(line, client_id: nil, card: false, author: nil, private_args: false)
32
+ args = nil
33
+ if private_args
34
+ name, rest = line.to_s.strip.split(/\s+/, 2)
35
+ if rest && !rest.empty?
36
+ args = rest
37
+ line = "#{name} #{HIDDEN}"
38
+ end
39
+ end
40
+ new(command_id: SecureRandom.uuid, client_id: client_id, line: line, card: card ? true : false, author: author,
41
+ private_args: args)
24
42
  end
25
43
 
44
+ # The line the session runs: #line, with its private arguments back.
45
+ def run_line = private_args ? "#{line.delete_suffix(" #{HIDDEN}")} #{private_args}" : line
46
+
47
+ # Never the private arguments (a log line or an error may print it).
48
+ def inspect = private_args ? super.sub(private_args.inspect, HIDDEN.inspect) : super
49
+
26
50
  # The fields its command_queued and command_ran name: card only when
27
51
  # it is a card's, author only when it isn't the owner's.
28
52
  # @return [Hash]
@@ -26,7 +26,14 @@ module Samagotchi
26
26
  # own recap.enabled (chi --set recap.enabled=true) only as the kwarg.
27
27
  #
28
28
  # @param recap [Hash, false, nil] the Engine's `recap:` kwarg
29
- # @param engine [Engine] the recap job's engine
29
+ # @param turn_state [TurnState] the Engine's (Engine#turn_state); a
30
+ # rebuilt job gets the same one
31
+ # @param messages_json [#call] → the conversation the recap summarizes,
32
+ # as a JSON string (Engine#messages_json_for_recap)
33
+ # @param emit_recap [#call] (recap:, generation:, covered:, created_at:)
34
+ # announces a written recap (Engine#emit_recap)
35
+ # @param on_usage [#call] (usage) records a recap request's SideUsage
36
+ # (Engine#note_side_usage)
30
37
  # @param host_registry [HostRegistry]
31
38
  # @param session_target [#call] → the session's current model as a recap target
32
39
  # @param session_id [#call] → String, nil
@@ -34,7 +41,7 @@ module Samagotchi
34
41
  # @param session_config [#call] → the session's own core settings
35
42
  # (SessionConfig::Settings#core), read once here
36
43
  # @return [IdleRecap, nil]
37
- def self.build(recap, engine:, host_registry:, session_target:, session_id:, state_dir:, session_config: -> { {} })
44
+ def self.build(recap, turn_state:, messages_json:, emit_recap:, on_usage:, host_registry:, session_target:, session_id:, state_dir:, session_config: -> { {} })
38
45
  return nil if recap == false
39
46
 
40
47
  session = session_config.call || {}
@@ -71,7 +78,9 @@ module Samagotchi
71
78
  end
72
79
 
73
80
  IdleRecap.new(
74
- engine: engine,
81
+ turn_state: turn_state,
82
+ messages_json: messages_json,
83
+ emit_recap: emit_recap,
75
84
  target: target,
76
85
  inactivity: recap_number_setting(kwarg_config, :inactivity, "recap.inactivity", IdleRecap::DEFAULT_INACTIVITY_SECONDS, :float),
77
86
  min_user_turns: recap_number_setting(kwarg_config, :min_user_turns, "recap.min_user_turns", IdleRecap::DEFAULT_MIN_USER_TURNS, :int),
@@ -79,7 +88,7 @@ module Samagotchi
79
88
  sentences: recap_sentences(string_config(kwarg_config, :sentences) || registry_string("recap.sentences", session: session)),
80
89
  store: RecapStore.new(session_id_lookup: -> { session_id.call }, state_dir_lookup: -> { state_dir.call }),
81
90
  session_id: -> { session_id.call },
82
- on_usage: ->(usage) { engine.note_side_usage(usage) }
91
+ on_usage: on_usage
83
92
  )
84
93
  end
85
94
 
@@ -35,8 +35,9 @@ module Samagotchi
35
35
  # @return [Boolean] +url+ is an http or https URL with a host and no
36
36
  # userinfo (a "https://github.com@evil.example/" shows one host and
37
37
  # opens another, and a token in it would be copied around)
38
- def self.http_url?(url)
39
- return false if url.length > MAX_URL
38
+ # +max+ is the length cap (a card's url action allows more: Plugin::Card)
39
+ def self.http_url?(url, max: MAX_URL)
40
+ return false if url.length > max
40
41
 
41
42
  uri = URI.parse(url)
42
43
  uri.is_a?(URI::HTTP) && !uri.host.to_s.empty? && uri.userinfo.nil?
@@ -14,9 +14,10 @@ module Samagotchi
14
14
  # answers its own question with that, only when it is about this session
15
15
  # and the question pending now, and is answered.
16
16
  class RelayVerifier
17
- # @param engine [Engine] this (the child's) worker's Engine
18
- def initialize(engine:, state_dir:, session_id:)
19
- @engine = engine
17
+ # @param question_desk [QuestionDesk] this (the child's) worker's question
18
+ # desk (Engine#question_desk)
19
+ def initialize(question_desk:, state_dir:, session_id:)
20
+ @question_desk = question_desk
20
21
  @state_dir = state_dir
21
22
  @session_id = session_id
22
23
  end
@@ -42,15 +43,15 @@ module Samagotchi
42
43
  parent_agent = relay["by"] != "user"
43
44
  client_id = "#{ClientId::RELAY_PREFIX}#{parent_id[0, 8]}"
44
45
  if answer["dismissed"]
45
- return not_pending(question_id) unless @engine.cancel_question("dismissed", id: question_id)
46
+ return not_pending(question_id) unless @question_desk.cancel("dismissed", id: question_id)
46
47
 
47
48
  log("relay_answered", relay_id, id: question_id, dismissed: true, by: relay["by"])
48
49
  return [{}, 200, { status: "dismissed", question_id: question_id }]
49
50
  end
50
51
 
51
52
  selected = labels(answer["selected_indices"], question_id) or return unverified("the answer's option is out of range", relay_id)
52
- result = @engine.answer_question(id: question_id, selected: selected, freeform: answer["freeform"],
53
- client_id: client_id, parent_agent: parent_agent)
53
+ result = @question_desk.answer(id: question_id, selected: selected, freeform: answer["freeform"],
54
+ client_id: client_id, parent_agent: parent_agent)
54
55
  log("relay_answered", relay_id, id: question_id, by: relay["by"])
55
56
  [{}, 200, { status: "answered", question_id: question_id, answer: result.to_h }]
56
57
  rescue QuestionDesk::NotPending
@@ -67,7 +68,7 @@ module Samagotchi
67
68
  # parent's are relabelled; the order is the same). nil when one is out
68
69
  # of range; [] for a freeform-only deny.
69
70
  def labels(indices, question_id)
70
- pending = @engine.pending_question
71
+ pending = @question_desk.pending
71
72
  return [] unless pending && pending.id.to_s == question_id
72
73
 
73
74
  options = Array(pending.options)
@@ -15,20 +15,20 @@ module Samagotchi
15
15
 
16
16
  module_function
17
17
 
18
- # @param engine [Engine] the child's
18
+ # @param question_desk [QuestionDesk] the child's (Engine#question_desk)
19
19
  # @param parent_dir [String] the parent session's folder (its sidecar)
20
20
  # @param live [#call] whether the parent's worker is up
21
21
  # @return [Thread]
22
- def start(engine:, question_id:, relay_id:, parent_dir:, interval: INTERVAL,
22
+ def start(question_desk:, question_id:, relay_id:, parent_dir:, interval: INTERVAL,
23
23
  live: -> { WorkerLink.resolve(parent_dir, unlink: false).live? })
24
24
  Thread.new do
25
25
  loop do
26
26
  sleep(interval)
27
- break unless relayed?(engine.pending_question, question_id, relay_id)
27
+ break unless relayed?(question_desk.pending, question_id, relay_id)
28
28
  next if live.call
29
29
 
30
30
  Log.info(:bridge, "relay_parent_gone", id: question_id)
31
- engine.annotate_question(question_id, relayed_to: nil, reason: "parent_gone")
31
+ question_desk.annotate(question_id, relayed_to: nil, reason: "parent_gone")
32
32
  break
33
33
  end
34
34
  rescue StandardError => e
@@ -214,8 +214,9 @@ module Samagotchi
214
214
  chi home [set [--ruby PATH] | doctor] the Ruby every chi launch boots
215
215
  chi project [init [DIR]] this folder's project; init makes a folder in no git repository one
216
216
  chi schedule <add|list|show|tick|run-now|enable|disable|cancel> durable schedules that outlive every worker
217
+ chi mcp serve chi as an MCP server on stdio (claude mcp add chi -- chi mcp serve)
217
218
  chi remote <add|ls|rm> other machines' chi web, for chi --remote NAME
218
- chi --remote NAME <send|answer|note|context|sessions|share> … those commands on that machine (or CHI_REMOTE=NAME)
219
+ chi --remote NAME <send|answer|note|context|sessions|share|mcp> … those commands on that machine (or CHI_REMOTE=NAME)
219
220
  chi --remote NAME --attach ID | --resume ID | --dir DIR [-p TEXT] a session on that machine, in this terminal
220
221
  chi self version, paths, model and bundles
221
222
  chi update [--dry-run] update this chi, its bundles and the desktop helper
@@ -28,6 +28,7 @@ require_relative "cli/parent_wait"
28
28
  require_relative "send_command/parent_gate"
29
29
  require_relative "send_command/busy"
30
30
  require_relative "session_access/local"
31
+ require_relative "session_access/exchange"
31
32
 
32
33
  module Samagotchi
33
34
  # `chi send`: put text into sessions as the user's message, the same as
@@ -792,27 +793,25 @@ module Samagotchi
792
793
 
793
794
  id = target.id
794
795
  short = target.label
795
- session = @access.show(id)
796
- # Machine-local (this machine's model registry): remotely the
797
- # server's (P2), as for --new.
798
- if !@images.empty? && (refusal = vision_refusal(session.model_name, typed: session.model_typed))
799
- @info.puts("#{short} refused: #{refusal}")
800
- return false
801
- end
802
- owner = @access.owner(id)
803
- running = owner && session.status == Session::STATUS_RUNNING
804
- refs = upload_images(id)
805
796
  # --cut asks the running turn for a cut (to an idle session an
806
797
  # ordinary message: nothing to cut). --queue always goes as a queue,
807
798
  # idle or not: the Bridge acks next_step to an idle worker and the
808
799
  # file still carries it, so a turn another client starts first never
809
800
  # merges it, and its turn and reply carry its enqueued_id (the
810
801
  # --wait's turn:); a worker older than queueing is refused.
811
- delivery = if @queue then Delivery::QUEUE
812
- elsif @cut && running then Delivery::CUT
813
- end
814
- result = @access.deliver_turn(id, prompt: prompt, client_id: client_id_for(prompt), images: refs, delivery: delivery,
815
- follow: target.via != :pinned)
802
+ # The vision check is machine-local (this machine's model registry):
803
+ # remotely the server's (P2), as for --new.
804
+ pass = exchange.attempt(target, prompt, client_id: client_id_for(prompt), queue: @queue, cut: @cut,
805
+ images: ImageUpload.new(method(:upload_images)), check: method(:image_check))
806
+ if pass.is_a?(SessionAccess::Exchange::Stopped)
807
+ @info.puts("#{short} refused: #{pass.refusal}")
808
+ return false
809
+ end
810
+ owner = pass.owner
811
+ running = pass.running
812
+ refs = pass.refs
813
+ delivery = pass.delivery
814
+ result = pass.result
816
815
  if result.continued?
817
816
  # Copied in before the refusal: not the old link's to keep.
818
817
  @access.discard_images(id, refs)
@@ -973,38 +972,52 @@ module Samagotchi
973
972
  # is never sent to (a send would un-archive it beside the new one).
974
973
  # @return [SessionInbox::Resolved, Unsent]
975
974
  def target(given)
976
- id = @access.resolve(given)
977
- head = @access.head(id)
978
- deadline = monotonic + self.class::CONTINUING_WAIT
979
- waited = head.continuing?
980
- while head.continuing? && monotonic < deadline
981
- self.class.pause(self.class::CONTINUING_POLL)
982
- head = @access.head(id)
983
- end
984
- return Unsent.new(line: "#{id[0, 8]} refused: #{head.continuing_refusal}", error: false, asked: id) if head.continuing?
975
+ found = exchange.locate(given)
976
+ return unsent_of(found) if found.is_a?(SessionAccess::Exchange::Unsent)
985
977
 
986
- (@continued_here ||= {})[head.id] = true if waited
987
- head
988
- rescue ArgumentError => e
989
- Unsent.new(line: "#{command_name}: #{e.message}", error: true)
978
+ (@continued_here ||= {})[found.target.id] = true if found.waited
979
+ found.target
980
+ end
981
+
982
+ # An Exchange::Unsent as the line chi send prints: a continue in
983
+ # flight's refusal (info), or the resolve's error (+error+ true).
984
+ def unsent_of(found)
985
+ if found.reason == :continuing
986
+ Unsent.new(line: "#{found.asked[0, 8]} refused: #{found.message}", error: false, asked: found.asked)
987
+ else
988
+ Unsent.new(line: "#{command_name}: #{found.message}", error: true)
989
+ end
990
990
  end
991
991
 
992
992
  # +refused+'s id resolved again after a continue took its link
993
- # (#deliver): #target, pausing between looks while it still names that
994
- # link, until +deadline+. The new link's worker is the continue's spawn
995
- # to start (#delivery_note).
993
+ # (#deliver): Exchange#relocate, until +deadline+. The new link's
994
+ # worker is the continue's spawn to start (#delivery_note).
996
995
  # @return [SessionInbox::Resolved, Unsent, nil] nil: out of time
997
996
  def follow_again(refused, deadline)
998
- while monotonic < deadline
999
- self.class.pause(self.class::CONTINUING_POLL)
1000
- again = target(refused.asked)
1001
- return again unless again.is_a?(SessionInbox::Resolved)
1002
- next if again.id == refused.id
1003
-
1004
- (@continued_here ||= {})[again.id] = true
1005
- return again
1006
- end
1007
- nil
997
+ again = exchange.relocate(refused, deadline) { |look| (@continued_here ||= {})[look.target.id] = true }
998
+ return nil unless again
999
+ return unsent_of(again) if again.is_a?(SessionAccess::Exchange::Unsent)
1000
+
1001
+ (@continued_here ||= {})[again.target.id] = true
1002
+ again.target
1003
+ end
1004
+
1005
+ # The send's Exchange: the class's pause and continue wait, read when
1006
+ # it is built (the specs stub both).
1007
+ def exchange
1008
+ @exchange ||= SessionAccess::Exchange.new(@access, pause: ->(seconds) { self.class.pause(seconds) },
1009
+ continuing_wait: self.class::CONTINUING_WAIT,
1010
+ continuing_poll: self.class::CONTINUING_POLL)
1011
+ end
1012
+
1013
+ # Exchange#attempt's images: this send's, copied into each target.
1014
+ ImageUpload = Data.define(:uploader) do
1015
+ def upload(id) = uploader.call(id)
1016
+ end
1017
+
1018
+ # Exchange#attempt's check: images to a model known not to take them.
1019
+ def image_check(session)
1020
+ vision_refusal(session.model_name, typed: session.model_typed) unless @images.empty?
1008
1021
  end
1009
1022
 
1010
1023
  def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
@@ -0,0 +1,244 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "exchange"
4
+ require_relative "exchange/token"
5
+ require_relative "../bridge_client"
6
+ require_relative "../bridge_secret"
7
+ require_relative "../client_id"
8
+ require_relative "../parent_answers_command"
9
+ require_relative "../reply_wait/target"
10
+ require_relative "../session"
11
+ require_relative "../turn_flow"
12
+ require_relative "../send_command/parent_gate"
13
+
14
+ module Samagotchi
15
+ module SessionAccess
16
+ # One message in, its answer out, for a thin client (chi web's POST
17
+ # …/ask, plan 2's MCP server): the session located (a chain's newest
18
+ # link, a continue in flight waited for), a running turn's busy check,
19
+ # the wait's start read before the message goes in, the delivery (a
20
+ # continue that took the link meanwhile: located again and sent there),
21
+ # then one slice of the wait. Everything draws on one deadline (+cap+),
22
+ # so the call answers in time for a proxy or a Shortcut; a turn still
23
+ # running then is a Reply with status :timeout and a wait token
24
+ # (Exchange::Token). The waits for a continue end MIN_SLICE before the
25
+ # deadline, so the slice fits; a delivery's own time counts (a slow one
26
+ # leaves a shorter slice, and one past the deadline gets no second
27
+ # delivery). One per call, no state kept after it. It answers
28
+ # values, never an HTTP shape; the backend's errors raise
29
+ # (SessionManager::OwnedByTUI, ArgumentError for a session deleted
30
+ # meanwhile).
31
+ class Ask
32
+ # The answer of a delivered message: +session_id+ where it ran (the
33
+ # chain's newest link), +asked+ the full id given, +result+ the
34
+ # ReplyWait::Result, +token+ for a :timeout (the next wait's).
35
+ # #answer's: +answered_here+ false when the question was no longer
36
+ # open (answered elsewhere first, or a newer one waits): what came
37
+ # next is still waited for, as chi answer does.
38
+ Reply = Data.define(:session_id, :asked, :result, :token, :answered_here) do
39
+ def initialize(session_id:, asked:, result:, token:, answered_here: true) = super
40
+ end
41
+
42
+ # The line ran as a session command (/model x): no reply comes.
43
+ Ran = Data.define(:session_id)
44
+
45
+ # Nothing went in. +kind+ :unknown (+error+ the resolve's
46
+ # ArgumentError), :continuing (a continue in flight past the wait,
47
+ # +message+ its refusal), :busy (+busy+ the SendCommand::Busy: a turn
48
+ # runs and queue was false, or a question waits) or :undelivered
49
+ # (+result+ the refused DeliverResult) or :canceled (+cancelled+ turned
50
+ # true before anything was sent: chi web stopping). #agent_line's
51
+ # :parent_refused (+message+ why). #answer's (+message+ each):
52
+ # :no_question (none of that id waits and nothing runs), :not_live (no
53
+ # worker runs it), :bridge_secret, :not_dismissable, :invalid_answer
54
+ # (the Bridge refused the selection), :parent_refused (the worker's
55
+ # parent_answers), :late (the worker didn't take it in time),
56
+ # :stale_worker (an older worker without the answer route), :failed.
57
+ Refused = Data.define(:kind, :session_id, :busy, :result, :error, :message) do
58
+ def initialize(kind:, session_id: nil, busy: nil, result: nil, error: nil, message: nil) = super
59
+ end
60
+
61
+ # The shortest wait slice, however little of the cap is left.
62
+ MIN_SLICE = 1.0
63
+
64
+ # @param access [SessionAccess::Local, #deliver_turn] the backend (chi
65
+ # web's wraps Local to deliver through its own manager and Bridge)
66
+ # @param exchange [Exchange] over the same backend
67
+ # @param clock [#call] monotonic seconds (the exchange's own by default)
68
+ def initialize(access, exchange:, clock: nil)
69
+ @access = access
70
+ @exchange = exchange
71
+ @clock = clock || -> { exchange.now }
72
+ end
73
+
74
+ # @param given [String] an id or a prefix
75
+ # @param client_id [String] who sends it (ClientId)
76
+ # @param queue [Boolean] a running session queues it as its own turn;
77
+ # false refuses one (:busy)
78
+ # @param timeout [Numeric] the most seconds for the wait's slice
79
+ # @param cap [Numeric] the most seconds for the whole call
80
+ # @param continuing_wait [Numeric] the most seconds a continue that
81
+ # took the link is waited for (Exchange::CONTINUING_WAIT)
82
+ # @param cancelled [#call, nil] true stops the wait (status :canceled);
83
+ # before the delivery, the call (Refused :canceled). The exchange's
84
+ # own cancelled: (the same) cuts its waits for a continue
85
+ # @return [Reply, Ran, Refused]
86
+ def call(given, prompt:, client_id:, queue:, timeout:, cap:, continuing_wait: Exchange::CONTINUING_WAIT,
87
+ cancelled: nil)
88
+ deadline = @clock.call + cap
89
+ # Everything before the wait ends by here, so its MIN_SLICE fits.
90
+ ready_by = deadline - MIN_SLICE
91
+ found = @exchange.locate(given, deadline: ready_by)
92
+ at = found.target if found.is_a?(Exchange::Located)
93
+ return Refused.new(kind: :canceled, session_id: at&.id || found.asked) if cancelled&.call
94
+ return unsent(found, nil) if found.is_a?(Exchange::Unsent)
95
+
96
+ follow_until = nil
97
+ loop do
98
+ return Refused.new(kind: :canceled, session_id: at.id) if cancelled&.call
99
+
100
+ session = @access.show(at.id)
101
+ busy = @access.busy(at.id, queue: queue, session: session)
102
+ return Refused.new(kind: :busy, session_id: at.id, busy: busy) if busy
103
+
104
+ start = @access.prepare_wait(at.id, session: session)
105
+ result = @exchange.attempt(at, prompt, client_id: client_id, queue: queue).result
106
+ if result.continued?
107
+ follow_until ||= [@clock.call + continuing_wait, ready_by].min
108
+ again = @exchange.relocate(at, follow_until, bounded: true)
109
+ return Refused.new(kind: :canceled, session_id: at.id) if cancelled&.call
110
+ return Refused.new(kind: :continuing, session_id: at.id, message: result.refusal_text) unless again
111
+ return unsent(again, at.id) if again.is_a?(Exchange::Unsent)
112
+
113
+ at = again.target
114
+ next
115
+ end
116
+ return Refused.new(kind: :undelivered, session_id: at.id, result: result) unless result.accepted?
117
+ return Ran.new(session_id: at.id) if result.command?
118
+
119
+ return wait(at, start, result, queue: queue, slice: slice(timeout, deadline), cancelled: cancelled)
120
+ end
121
+ end
122
+
123
+ # What a parent agent's line (an MCP host's, chi send's over HTTP) is
124
+ # held to, with no read of this process (an ENV marker, a tty): a
125
+ # /continue yes always goes in as chi answer's (the worker holds it
126
+ # to guardrails.parent_answers only then), anything else as chi
127
+ # send's; refused first when the parent policy refuses that continue,
128
+ # or when it is a /parent-answers line loosening a target's own value
129
+ # (Web::SessionCreate#parent_gate's two checks, for those ids).
130
+ # @param session [Session, Array<Session>, nil] the targets (the
131
+ # session asked and its chain's newest link); none: config.yml's
132
+ # value alone (fail closed)
133
+ # @return [String, Refused] the client_id to send as, or why not
134
+ def agent_line(prompt, session:)
135
+ sessions = Array(session).compact
136
+ values = sessions.empty? ? [nil] : sessions.map(&:parent_answers)
137
+ continue = TurnFlow.continue_yes?(prompt)
138
+ refusal = SendCommand::ParentGate.continue_refusal_for(values) if continue
139
+ refusal ||= ParentAnswersCommand::REFUSED if SendCommand::ParentGate.loosens_any?(prompt, values)
140
+ return Refused.new(kind: :parent_refused, session_id: sessions.first&.id, message: refusal) if refusal
141
+
142
+ continue ? ClientId::CLI_ANSWER : ClientId::CLI_SEND
143
+ end
144
+
145
+ # The answer to the question session +id+ waits on, then one slice of
146
+ # the wait for what comes next (AnswerCommand's sequence, as values):
147
+ # a question no longer open is not answered but still waited past
148
+ # (Reply answered_here: false) while the session runs.
149
+ # @param id [String] the session's full id
150
+ # @param selected [Array<String>] the option labels
151
+ # @param freeform [String, nil]
152
+ # @param timeout [Numeric] the wait's slice
153
+ # @param cap [Numeric, nil] the most seconds for the whole call (an
154
+ # MCP host's limit): the post gets what is left but MIN_SLICE, the
155
+ # wait the rest (#slice); nil: the post's own limits, then +timeout+
156
+ # @return [Reply, Refused]
157
+ def answer(id, question_id:, selected:, freeform:, client_id:, timeout:, cap: nil, cancelled: nil)
158
+ deadline = @clock.call + cap if cap
159
+ qid = question_id.to_s
160
+ session = @access.show(id)
161
+ pending = session.pending_question
162
+ open = pending && pending.id.to_s == qid
163
+ if !open && session.status != Session::STATUS_RUNNING
164
+ return Refused.new(kind: :no_question, session_id: id, message: "no question #{qid} waits in #{id[0, 8]}; nothing to answer")
165
+ end
166
+
167
+ start = @access.prepare_wait(id, session: session, question_id: qid)
168
+ answered_here = false
169
+ if open
170
+ within = (deadline - MIN_SLICE - @clock.call).clamp(MIN_SLICE..) if deadline
171
+ posted = post_answer(id, qid, selected, freeform, client_id, within)
172
+ return posted if posted.is_a?(Refused)
173
+
174
+ answered_here = posted
175
+ end
176
+ target = ReplyWait::Target.answer(start)
177
+ more = cancelled ? { cancelled: cancelled } : {}
178
+ result = @exchange.wait(id, target, timeout: deadline ? slice(timeout, deadline) : timeout, **more)
179
+ token = Exchange::Token.dump(id, target) if result.status == :timeout
180
+ Reply.new(session_id: id, asked: id, result: result, token: token, answered_here: answered_here)
181
+ end
182
+
183
+ # The words for an answer the worker didn't take in time
184
+ # (AnswerCommand's own, copied).
185
+ LATE_WORDS = "the worker did not take the answer in time; the question is still open: try again"
186
+
187
+ private
188
+
189
+ # The answer posted, its reply read as AnswerCommand#post reads it.
190
+ # @return [Boolean, Refused] true answered, false no longer open (409)
191
+ def post_answer(id, qid, selected, freeform, client_id, within)
192
+ more = within ? { within: within } : {}
193
+ reply = @access.answer(id, question_id: qid, selected: selected, freeform: freeform, client_id: client_id, **more)
194
+ return not_live(id) unless reply
195
+ return answer_refused(:bridge_secret, id, BridgeSecret.refused(id, via: @access.invocation)) if reply.secret_refused?
196
+
197
+ detail = reply.json&.dig("detail")
198
+ case reply.status
199
+ when 200 then true
200
+ when 409
201
+ return answer_refused(:not_dismissable, id, detail.to_s) if reply.json&.dig("error") == "not_dismissable"
202
+
203
+ false
204
+ when 400 then answer_refused(:invalid_answer, id, detail || "the worker refused the answer")
205
+ when 403 then answer_refused(:parent_refused, id, detail || "the worker refused that option: deny it, and tell your user")
206
+ when 408 then answer_refused(:late, id, LATE_WORDS)
207
+ when 404
208
+ return not_live(id) if reply.json&.dig("error") == "unknown_session"
209
+
210
+ answer_refused(:stale_worker, id, BridgeClient.stale_worker_message(id, cant: "take an answer", via: @access.invocation))
211
+ else answer_refused(:failed, id, "the worker answered #{reply.status}: #{detail || reply.body}")
212
+ end
213
+ rescue Errno::ETIMEDOUT
214
+ answer_refused(:late, id, LATE_WORDS)
215
+ rescue SystemCallError, IOError, SocketError => e
216
+ answer_refused(:failed, id, "#{e.class}: #{e.message}")
217
+ end
218
+
219
+ def not_live(id) = answer_refused(:not_live, id, "no worker runs session #{id[0, 8]}: the question went with it; send the task again")
220
+
221
+ def answer_refused(kind, id, message) = Refused.new(kind: kind, session_id: id, message: message)
222
+
223
+ def wait(at, start, delivered, queue:, slice:, cancelled:)
224
+ target = @exchange.bind(start, delivered, queue: queue)
225
+ more = cancelled ? { cancelled: cancelled } : {}
226
+ result = @exchange.wait(at.id, target, timeout: slice, **more)
227
+ token = Exchange::Token.dump(at.id, target) if result.status == :timeout
228
+ Reply.new(session_id: at.id, asked: at.asked, result: result, token: token)
229
+ end
230
+
231
+ # The wait's slice: +timeout+, cut to the time the cap leaves, never
232
+ # under MIN_SLICE.
233
+ def slice(timeout, deadline) = [timeout, deadline - @clock.call].min.clamp(MIN_SLICE..)
234
+
235
+ def unsent(found, session_id)
236
+ if found.reason == :continuing
237
+ Refused.new(kind: :continuing, session_id: session_id || found.asked, message: found.message)
238
+ else
239
+ Refused.new(kind: :unknown, session_id: session_id, error: found.error, message: found.message)
240
+ end
241
+ end
242
+ end
243
+ end
244
+ end