samagotchi 0.139.0 → 0.140.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 (75) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +62 -1
  3. data/README.md +2 -1
  4. data/docs/architecture.md +6 -4
  5. data/docs/cli.md +4 -2
  6. data/docs/configuration.md +36 -2
  7. data/docs/context.md +185 -44
  8. data/docs/guardrails.md +11 -0
  9. data/docs/internals/background-tasks.md +1 -1
  10. data/docs/internals/engine.md +7 -1
  11. data/docs/internals/prompt-caching.md +10 -1
  12. data/docs/internals/tool-guardrails.md +1 -1
  13. data/docs/plugins.md +35 -17
  14. data/docs/sessions.md +3 -2
  15. data/lib/samagotchi/bridge/turn_accumulator.rb +4 -1
  16. data/lib/samagotchi/bundle_command.rb +21 -21
  17. data/lib/samagotchi/bundles/dev/manifest.yml +2 -2
  18. data/lib/samagotchi/bundles/github-pr/manifest.yml +4 -4
  19. data/lib/samagotchi/bundles/github-pr/plugin.rb +72 -176
  20. data/lib/samagotchi/bundles/mcp/manifest.yml +2 -2
  21. data/lib/samagotchi/bundles/mcp/plugin.rb +8 -3
  22. data/lib/samagotchi/bundles/system/manifest.yml +2 -2
  23. data/lib/samagotchi/bundles/system/self_map.md +2 -2
  24. data/lib/samagotchi/cancellation_controller.rb +4 -4
  25. data/lib/samagotchi/config.rb +8 -0
  26. data/lib/samagotchi/context_candidate_choice.rb +154 -0
  27. data/lib/samagotchi/context_candidates.rb +259 -0
  28. data/lib/samagotchi/context_candidates_log.rb +90 -0
  29. data/lib/samagotchi/context_command.rb +33 -8
  30. data/lib/samagotchi/context_fetch.rb +2 -2
  31. data/lib/samagotchi/context_judge.rb +194 -0
  32. data/lib/samagotchi/context_report_command.rb +161 -0
  33. data/lib/samagotchi/context_sources.rb +67 -23
  34. data/lib/samagotchi/cut.rb +21 -0
  35. data/lib/samagotchi/cut_policy.rb +6 -5
  36. data/lib/samagotchi/engine.rb +189 -32
  37. data/lib/samagotchi/hook_routes.rb +3 -2
  38. data/lib/samagotchi/kernel_loop.rb +8 -6
  39. data/lib/samagotchi/launch_mode.rb +5 -2
  40. data/lib/samagotchi/llm/chat_loop.rb +3 -2
  41. data/lib/samagotchi/llm/openai_chat.rb +1 -1
  42. data/lib/samagotchi/memory_bundle/status.rb +13 -3
  43. data/lib/samagotchi/owner_prompt.rb +39 -0
  44. data/lib/samagotchi/plugin/api.rb +1 -0
  45. data/lib/samagotchi/plugin/attached_context.rb +91 -11
  46. data/lib/samagotchi/plugin/context.rb +7 -1
  47. data/lib/samagotchi/project_env.rb +16 -2
  48. data/lib/samagotchi/prompt_warmup.rb +9 -1
  49. data/lib/samagotchi/session_access/contract.rb +2 -0
  50. data/lib/samagotchi/session_access/local.rb +10 -0
  51. data/lib/samagotchi/session_access/remote.rb +14 -0
  52. data/lib/samagotchi/session_access.rb +5 -0
  53. data/lib/samagotchi/session_commands.rb +28 -5
  54. data/lib/samagotchi/side_judgments.rb +84 -0
  55. data/lib/samagotchi/steer_cut.rb +2 -1
  56. data/lib/samagotchi/terminal_ui.rb +15 -0
  57. data/lib/samagotchi/testing/boundary.rb +3 -1
  58. data/lib/samagotchi/testing/host.rb +4 -1
  59. data/lib/samagotchi/toolkit_report_command.rb +2 -1
  60. data/lib/samagotchi/toolkit_suggest.rb +3 -18
  61. data/lib/samagotchi/turn_note.rb +6 -6
  62. data/lib/samagotchi/version.rb +1 -1
  63. data/lib/samagotchi/web/app.rb +10 -3
  64. data/lib/samagotchi/web/auto_update.rb +8 -1
  65. data/lib/samagotchi/web/public/app.js +11 -3
  66. data/lib/samagotchi/web/public/composer.css +1 -1
  67. data/lib/samagotchi/web/public/index.html +10 -9
  68. data/lib/samagotchi/web/public/notifications.js +10 -1
  69. data/lib/samagotchi/web/public/revise_stack.js +6 -5
  70. data/lib/samagotchi/web/public/update_notice.js +21 -8
  71. data/lib/samagotchi/web/session_access_routes.rb +1 -1
  72. data/lib/samagotchi/web/session_hub.rb +5 -2
  73. data/lib/samagotchi/web/update_check.rb +14 -8
  74. data/lib/samagotchi/worker.rb +5 -0
  75. metadata +9 -1
@@ -454,10 +454,15 @@ class Plugin
454
454
  client
455
455
  end
456
456
 
457
- # A server's env: the session's project env (the worker's mise env, on a
458
- # chi that has it: Samagotchi::ProjectEnv) under the server's own keys.
457
+ # A server's env: the session's project env as execute's commands get it
458
+ # (the worker's mise env without chi's own Ruby and Bundler setup, on a
459
+ # chi that has it: Samagotchi::ProjectEnv.spawn_env) under the server's
460
+ # own keys. An older chi has only the overlay, or none.
459
461
  def server_env(server)
460
- project = defined?(Samagotchi::ProjectEnv) ? Samagotchi::ProjectEnv.current.env : {}
462
+ project = if !defined?(Samagotchi::ProjectEnv) then {}
463
+ elsif Samagotchi::ProjectEnv.respond_to?(:spawn_env) then Samagotchi::ProjectEnv.spawn_env
464
+ else Samagotchi::ProjectEnv.current.env
465
+ end
461
466
  project.merge(server.env)
462
467
  end
463
468
 
@@ -1,11 +1,11 @@
1
1
  ---
2
2
  name: samagotchi-system
3
- version: 0.139.0
3
+ version: 0.140.0
4
4
  scope: system
5
5
  description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
6
6
  files:
7
7
  identity.md: sha256:29c2f7df9f6c5acbc5ec17000a4490741e55e426af15ca0d81c8706edd9bd027
8
- self_map.md: sha256:df3f8da539a9f5812f79e089c2c8b9894da6124a89654f292160046a6bb060da
8
+ self_map.md: sha256:3253cb9ae7f09821d8fe1fed5154dd2b5e33fe0e9f096eee2af981d7d7d66f16
9
9
  config_modification_protocol.md: sha256:ff4efccf2bdde453fc4e6741df8c18f78da78e353f6b1a5a64d0e7a631aea258
10
10
  memory_guide.md: sha256:3b9ff779ee962f1307d56937c826d5e581923114f3f39455b779ca618b363cd7
11
11
  delegated.md: sha256:a0d6ddcd4a8be06526d964898611775fd251cfd9d145a9d16afaccaa503597bd
@@ -31,8 +31,8 @@
31
31
  asking for changes, checks failing, the PR closed), chi may start a turn for it with no user
32
32
  message ("context <name> changed"): I tell my user what changed and act on nothing.
33
33
  - `[TASK FINISHED from task <id8>, …]` is a background task I started (`task_create`, an `execute`
34
- handed over at its limit) that finished while I wasn't waiting on it: its exit code, duration
35
- and log tail. When it opens a turn with no user message ("task <id8> finished"), I carry on with
34
+ handed over at its limit, or early when a message came for my turn) that finished while I wasn't
35
+ waiting on it: its exit code, duration and log tail. When it opens a turn with no user message ("task <id8> finished"), I carry on with
36
36
  what I planned for its result, or tell my user in a sentence or two how it went. Without the
37
37
  "chi started this turn" line it is only information for my next answer.
38
38
  - `forget_outputs` (only when my model's `llm_context.strategy` has the experimental forget layer)
@@ -20,8 +20,8 @@ module Samagotchi
20
20
  @generation = nil
21
21
  end
22
22
 
23
- # @param detail [Object, nil] what the canceller says about it (a cut
24
- # generation's {by:, reason:})
23
+ # @param detail [Object, nil] what the canceller says about it (the Cut
24
+ # of a cut generation, or a turn stopped by a hook)
25
25
  def cancel!(reason = :manual, detail = nil)
26
26
  listeners = []
27
27
  @mutex.synchronize do
@@ -54,11 +54,11 @@ module Samagotchi
54
54
  @mutex.synchronize { @detail }
55
55
  end
56
56
 
57
- # Who stopped it when a hook did: the detail's +by+ (the bundle, or the
57
+ # Who stopped it when a hook did: the Cut's +by+ (the bundle, or the
58
58
  # hook's label); nil for any other cancel.
59
59
  def stopped_by
60
60
  reason, detail = @mutex.synchronize { [@reason, @detail] }
61
- by = detail[:by].to_s if reason == :hook && detail.is_a?(Hash)
61
+ by = detail.by.to_s if reason == :hook && detail.respond_to?(:by)
62
62
  by unless by.nil? || by.empty?
63
63
  end
64
64
 
@@ -217,6 +217,14 @@ module Samagotchi
217
217
  # counted here); then they wait as notes. 0: a peer source
218
218
  # wakes like any other (once per 10 minutes, the guard line).
219
219
  Entry.new(key: "context.peer_turns", yaml_path: %w[context peer_turns], type: :integer, default: 3, expose: %i[env config cli], lifecycle: :next_matching_turn_display_poll_write),
220
+ # The candidate judge (ContextJudge): off (no conversation text goes to a System 1 host); audit (asks and logs
221
+ # context_candidates.jsonl, attaches nothing); on (ContextCandidateChoice: p ≥ threshold attaches quietly,
222
+ # offer_threshold ≤ p < threshold shows one card). Its host and model are guardrails.system_one.host/model.
223
+ # reask_after_turns: the owner prompts after a judged ask before its one re-ask.
224
+ Entry.new(key: "context.candidates.mode", yaml_path: %w[context candidates mode], type: :enum, default: "off", expose: %i[config], enum_values: %w[off audit on], lifecycle: :next_matching_turn_display_poll_write),
225
+ Entry.new(key: "context.candidates.threshold", yaml_path: %w[context candidates threshold], type: :float, default: 0.8, expose: %i[config], lifecycle: :next_matching_turn_display_poll_write),
226
+ Entry.new(key: "context.candidates.offer_threshold", yaml_path: %w[context candidates offer_threshold], type: :float, default: 0.6, expose: %i[config], lifecycle: :next_matching_turn_display_poll_write),
227
+ Entry.new(key: "context.candidates.reask_after_turns", yaml_path: %w[context candidates reask_after_turns], type: :integer, default: 3, expose: %i[config], lifecycle: :next_matching_turn_display_poll_write),
220
228
 
221
229
  # What the model is sent of the conversation (LLMContextStrategy, LLMContextView): none, or a list of layers
222
230
  # (stale, forget; "|"-separated or a YAML list); forget (the model's forget_outputs) is experimental.
@@ -0,0 +1,154 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "context_candidates"
4
+ require_relative "context_candidates_log"
5
+ require_relative "context_providers"
6
+ require_relative "context_sources"
7
+ require_relative "log"
8
+
9
+ module Samagotchi
10
+ # What becomes of a candidate after the judge (context.candidates.mode
11
+ # on) or the owner chose (docs/context.md, "On mode"):
12
+ #
13
+ # - a judged p ≥ threshold attaches it quietly (#after_judged): the
14
+ # session's own folder, its why naming the judge without a number; the
15
+ # worker's next between-turn delivery brings its note, never mid-turn;
16
+ # - offer_threshold ≤ p < threshold shows one card (Attach / Not here),
17
+ # once per candidate: a `carded` line in ContextCandidatesLog says it
18
+ # was shown, so a worker restart doesn't show it again;
19
+ # - below, it stays proposed.
20
+ #
21
+ # The card's actions are /context attach NAME and /context decline NAME
22
+ # (#choose), the owner's only: a participant can't send a / line, and a
23
+ # review session refuses them.
24
+ module ContextCandidateChoice
25
+ CARD_SOURCE = "context"
26
+ # The judge's attach, as the source's why (no probability: it is
27
+ # model-visible in the attach note).
28
+ JUDGE_WHY = "it looks related to your task"
29
+ # The owner's attach from the card (or /context attach).
30
+ CHOSEN_WHY = "you attached it"
31
+ OFFER_BODY = "It may be related to your task. Not attached: the agent gets nothing until you attach it."
32
+ USAGE = "usage: /context [attach NAME | decline NAME]"
33
+
34
+ module_function
35
+
36
+ def card_id(name) = "context-candidate-#{name}"
37
+
38
+ # The middle band's card for +candidate+.
39
+ # @return [Hash] Engine#show_card's keywords
40
+ def offer_card(candidate)
41
+ { source: CARD_SOURCE, id: card_id(candidate.name), title: candidate.title.to_s.strip.empty? ? candidate.name : candidate.title,
42
+ body: OFFER_BODY, level: :info,
43
+ actions: [{ label: "Attach", command: "/context attach #{candidate.name}" },
44
+ { label: "Not here", command: "/context decline #{candidate.name}" }] }
45
+ end
46
+
47
+ # The card shown again under its id, with no actions: what became of it.
48
+ def closed_card(candidate, body)
49
+ { source: CARD_SOURCE, id: card_id(candidate.name), title: candidate.title.to_s.strip.empty? ? candidate.name : candidate.title,
50
+ body: body, level: :info, actions: [] }
51
+ end
52
+
53
+ # On mode, after a judged ask (ContextJudge.ask's +fields+; nil: no
54
+ # answer): attach, card or nothing. The candidate must still be
55
+ # proposed (the user may have chosen while it was asked).
56
+ # @param show_card [#call] (**card) → shows it; false/nil: it wasn't
57
+ # shown (the UI is on another session), so no carded line
58
+ # @return [Symbol, nil] :attached, :carded or nil
59
+ def after_judged(job:, fields:, settings:, project_root:, state_dir:, log:, show_card:)
60
+ return nil unless settings.mode == "on" && fields && fields["stated"]
61
+ return nil unless %w[attach offer].include?(fields["would"])
62
+
63
+ candidate = proposed(job.session_id, job.name, project_root: project_root, state_dir: state_dir) or return nil
64
+ if fields["would"] == "attach"
65
+ judge_attach(candidate, job: job, p: fields["p"], state_dir: state_dir, log: log, show_card: show_card)
66
+ else
67
+ offer(candidate, job: job, p: fields["p"], log: log, show_card: show_card)
68
+ end
69
+ rescue StandardError => e
70
+ Log.warn(:context, "candidate_choice_failed", name: job.name, error: e.class.name, msg: e.message.to_s[0, 200])
71
+ nil
72
+ end
73
+
74
+ # The candidate +name+ when it is still proposed in the session.
75
+ def proposed(session_id, name, project_root:, state_dir:)
76
+ rows = ContextCandidates.with_status(session_id, project_root: project_root, state_dir: state_dir)
77
+ rows.find { |candidate, status| candidate.name == name && status == "proposed" }&.first
78
+ end
79
+
80
+ # Whether +name+'s card was shown in the session (a carded line).
81
+ def carded?(log, session_id, name)
82
+ ContextCandidatesLog.records_for(log, session_id).any? { |line| line["kind"] == "carded" && line["name"] == name }
83
+ end
84
+
85
+ def judge_attach(candidate, job:, p:, state_dir:, log:, show_card:)
86
+ own = ContextSources.session_location(job.session_id, state_dir: state_dir)
87
+ own.add(ContextCandidates.source_for(candidate, why: JUDGE_WHY))
88
+ Log.info(:context, "candidate_attached", name: candidate.name, trigger: "judge")
89
+ ContextCandidatesLog.event("judge_attached", session_id: job.session_id, name: candidate.name, log: log, p: p)
90
+ # A card from an earlier ask loses its buttons.
91
+ show_card.call(**closed_card(candidate, "Attached: #{JUDGE_WHY}.")) if carded?(log, job.session_id, candidate.name)
92
+ :attached
93
+ rescue ContextSources::Invalid, ContextProviders::Invalid => e
94
+ Log.warn(:context, "candidate_not_attached", name: candidate.name, error: e.message.to_s[0, 200])
95
+ nil
96
+ end
97
+
98
+ def offer(candidate, job:, p:, log:, show_card:)
99
+ return nil if carded?(log, job.session_id, candidate.name)
100
+ return nil unless show_card.call(**offer_card(candidate))
101
+
102
+ ContextCandidatesLog.event("carded", session_id: job.session_id, name: candidate.name, log: log, p: p)
103
+ :carded
104
+ end
105
+
106
+ # /context attach NAME and /context decline NAME (+action+ :attach or
107
+ # :decline) in +session+.
108
+ # @param show_card [#call] (**card) → replaces the card
109
+ # @return [Array(Symbol, String)] :ok or :error, and the answer
110
+ def choose(action, name, session:, state_dir:, show_card:)
111
+ return [:error, "no session yet"] unless session&.id
112
+ return [:error, "a review session takes no context candidates"] if session.review?
113
+ return [:error, USAGE] if name.to_s.empty?
114
+
115
+ candidate, status = find(session, name, state_dir: state_dir)
116
+ return [:error, "no candidate #{name} in this session (see /context)"] unless candidate
117
+
118
+ action == :attach ? attach(candidate, status, session, state_dir, show_card) : decline(candidate, status, session, state_dir, show_card)
119
+ end
120
+
121
+ def find(session, name, state_dir:)
122
+ ContextCandidates.with_status(session.id, project_root: session.project_root, state_dir: state_dir)
123
+ .find { |candidate, _status| candidate.name == name }
124
+ end
125
+
126
+ def attach(candidate, status, session, state_dir, show_card)
127
+ return [:error, "#{candidate.name} is attached already"] if status == "attached"
128
+ if status == "declined"
129
+ return [:error, "#{candidate.name} was declined in this session; chi context add attaches a source by hand"]
130
+ end
131
+
132
+ own = ContextSources.session_location(session.id, state_dir: state_dir)
133
+ own.add(ContextCandidates.source_for(candidate, why: CHOSEN_WHY))
134
+ Log.info(:context, "candidate_attached", name: candidate.name, trigger: "command")
135
+ ContextCandidatesLog.event("attached", session_id: session.id, name: candidate.name, state_dir: state_dir, by: "command")
136
+ show_card.call(**closed_card(candidate, "Attached."))
137
+ [:ok, "attached #{candidate.name}: its text comes with your next message"]
138
+ rescue ContextSources::Invalid, ContextProviders::Invalid => e
139
+ [:error, "#{candidate.name} not attached: #{e.message}"]
140
+ end
141
+
142
+ def decline(candidate, status, session, state_dir, show_card)
143
+ if status == "attached"
144
+ return [:error, "#{candidate.name} is attached; chi context rm #{candidate.name} removes it"]
145
+ end
146
+ return [:ok, "#{candidate.name} is declined already"] if status == "declined"
147
+
148
+ ContextSources.session_location(session.id, state_dir: state_dir).decline(candidate.name, candidate.url.to_s)
149
+ ContextCandidatesLog.event("declined", session_id: session.id, name: candidate.name, state_dir: state_dir, by: "command")
150
+ show_card.call(**closed_card(candidate, "Not attached here."))
151
+ [:ok, "declined #{candidate.name}: not proposed again in this session"]
152
+ end
153
+ end
154
+ end
@@ -0,0 +1,259 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "time"
4
+ require_relative "context_absorber"
5
+ require_relative "context_candidates_log"
6
+ require_relative "context_fetch"
7
+ require_relative "context_providers"
8
+ require_relative "context_sources"
9
+ require_relative "log"
10
+ require_relative "owner_prompt"
11
+
12
+ module Samagotchi
13
+ # A session's pool of candidate context (ContextSources::Candidate, from
14
+ # ctx.context.propose) and the one thing that attaches one in slice 1:
15
+ # the owner mentioning it. A candidate's status is derived, never stored:
16
+ # attached while a source of its name (or its URL) is attached, declined
17
+ # while the user's declined marker names it (or its URL), else proposed.
18
+ #
19
+ # Mentions (#mention_in): whole tokens, any case; a "#N" only for N ≥ 10
20
+ # or right after "PR" / "pull" ("PR #4"); any other word (a branch) only
21
+ # when it is at least 6 characters and holds a /, - or _; a URL exactly.
22
+ # Text inside fenced code blocks (pasted logs) never counts.
23
+ #
24
+ # Only the owner's own prompts count (OwnerPrompt), and nothing happens in
25
+ # a review session: a participant never attaches a source to the owner's
26
+ # session.
27
+ module ContextCandidates
28
+ STATUSES = %w[proposed attached declined].freeze
29
+ # How long a turn waits for a mention-attached source's first text, so
30
+ # its note lands in the turn that mentioned it; past it the note comes
31
+ # with a later turn.
32
+ FIRST_FETCH_SECONDS = 10
33
+ BRANCH_MIN_CHARS = 6
34
+ NUMBER_MIN = 10
35
+ # A fenced code block's opening line (up to 3 spaces, then ``` or ~~~).
36
+ FENCE_OPEN = /\A {0,3}(`{3,}|~{3,})/
37
+ # What may sit around a word-like mention without joining it.
38
+ WORD_BEFORE = %r{(?<![\w./#-])}
39
+ WORD_AFTER = %r{(?![\w/-])(?!\.[\w/-])}
40
+ # A candidate attached from a mention, and the mention.
41
+ Hit = Data.define(:candidate, :mention)
42
+
43
+ module_function
44
+
45
+ # @param attached [Array<ContextSources::Attached>] what the session sees
46
+ # @return [String] "attached", "declined" or "proposed"
47
+ def status(candidate, own:, attached:)
48
+ if attached.any? { |a| a.name == candidate.name || (candidate.url && a.source.hint == candidate.url) }
49
+ return "attached"
50
+ end
51
+ return "declined" if own.declined?(candidate.name) || (candidate.url && own.declined_hints.include?(candidate.url))
52
+
53
+ "proposed"
54
+ end
55
+
56
+ # The session's candidates with their status, by name.
57
+ # @return [Array<Array(ContextSources::Candidate, String)>]
58
+ def with_status(session_id, project_root:, state_dir: nil)
59
+ own = ContextSources.session_location(session_id, state_dir: state_dir)
60
+ candidates = own.candidates
61
+ return [] if candidates.empty?
62
+
63
+ attached = ContextSources.attached(session_id, project_root: project_root, state_dir: state_dir, shadowed: true)
64
+ candidates.map { |candidate| [candidate, status(candidate, own: own, attached: attached)] }
65
+ end
66
+
67
+ # The candidates section of /context, nil for none.
68
+ def listing(session_id, project_root:, state_dir: nil)
69
+ rows = with_status(session_id, project_root: project_root, state_dir: state_dir)
70
+ return nil if rows.empty?
71
+
72
+ lines = rows.map { |candidate, state| "- #{candidate.name} · #{state} · #{candidate.title}" }
73
+ "Candidates (attached when a prompt of yours mentions one, or by /context attach NAME):\n#{lines.join("\n")}"
74
+ end
75
+
76
+ # The words in +text+ that name +candidate+: its first mention found,
77
+ # or nil.
78
+ def mention_in(text, candidate)
79
+ plain = without_fences(text.to_s)
80
+ return nil if plain.strip.empty?
81
+
82
+ candidate.mentions.find { |mention| (pattern = pattern_for(mention)) && plain.match?(pattern) }
83
+ end
84
+
85
+ # The regexp a mention matches by, nil for one that never matches (a
86
+ # short or plain word).
87
+ def pattern_for(mention)
88
+ mention = mention.to_s.strip
89
+ if (number = mention[/\A#(\d+)\z/, 1])
90
+ return /(?<![\w&#])##{number}(?!\w)/ if number.to_i >= NUMBER_MIN
91
+
92
+ return /\b(?:pr|pull(?:\s+request)?)\s*##{number}(?!\w)/i
93
+ end
94
+ return %r{(?<![\w/.:-])#{Regexp.escape(mention)}(?![\w/#?=&%-])} if mention.match?(%r{\Ahttps?://}i)
95
+ return nil if mention.length < BRANCH_MIN_CHARS || !mention.match?(%r{[/_-]})
96
+
97
+ /#{WORD_BEFORE}#{Regexp.escape(mention)}#{WORD_AFTER}/i
98
+ end
99
+
100
+ # +text+ with its fenced code blocks blanked out.
101
+ def without_fences(text)
102
+ out = +""
103
+ open = nil
104
+ text.each_line do |line|
105
+ marker = line[FENCE_OPEN, 1]
106
+ if open.nil? && marker
107
+ open = marker
108
+ elsif open && marker && marker[0] == open[0] && marker.length >= open.length && line.strip == marker
109
+ open = nil
110
+ elsif open.nil?
111
+ out << line
112
+ end
113
+ end
114
+ out
115
+ end
116
+
117
+ # The owner's own prompts in +messages+ (OwnerPrompt.message?), as text.
118
+ def owner_texts(messages)
119
+ Array(messages).filter_map do |message|
120
+ next unless OwnerPrompt.message?(message)
121
+
122
+ content = message.is_a?(Hash) ? (message[:content] || message["content"]) : nil
123
+ content.is_a?(String) ? content : nil
124
+ end
125
+ end
126
+
127
+ # The proposed candidates +texts+ mention (the first text that does,
128
+ # newest first), one hit each.
129
+ # @return [Array<Hit>]
130
+ def hits(texts, candidates)
131
+ candidates.filter_map do |candidate|
132
+ mention = texts.reverse_each.lazy.filter_map { |text| mention_in(text, candidate) }.first
133
+ mention && Hit.new(candidate: candidate, mention: mention)
134
+ end
135
+ end
136
+
137
+ # Attaches +hit+'s candidate to the session's own folder, its why naming
138
+ # the mention (a mentioned line in ContextCandidatesLog, in +state_dir+'s
139
+ # log). A source of its name there already stays.
140
+ # @return [String, nil] the name, nil when it couldn't be attached
141
+ def attach(hit, own:, state_dir: nil)
142
+ candidate = hit.candidate
143
+ own.add(source_for(candidate, why: "you mentioned #{hit.mention}"))
144
+ Log.info(:context, "candidate_attached", name: candidate.name, trigger: "mention")
145
+ ContextCandidatesLog.event("mentioned", session_id: own.key, name: candidate.name, state_dir: state_dir,
146
+ mention: hit.mention)
147
+ candidate.name
148
+ rescue ContextSources::Invalid, ContextProviders::Invalid => e
149
+ return candidate.name if own.source(candidate.name)
150
+
151
+ Log.warn(:context, "candidate_not_attached", name: candidate.name, error: e.message.to_s[0, 200])
152
+ nil
153
+ end
154
+
155
+ # The Source a candidate becomes: through its URL's provider, else its
156
+ # own command.
157
+ # @raise [ContextProviders::Invalid] no installed bundle resolves its URL
158
+ def source_for(candidate, why:)
159
+ fields = { name: candidate.name, why: why, scope: "session", added_by: candidate.proposed_by,
160
+ created_at: Time.now.utc.iso8601, title: candidate.title }
161
+ if candidate.url
162
+ resolved = ContextProviders.resolve(candidate.url) or
163
+ raise ContextProviders::Invalid, "no installed bundle resolves #{candidate.url}"
164
+ return ContextSources::Source.new(cmd: resolved.cmd, hint: resolved.hint, every_seconds: resolved.every_seconds,
165
+ provider: resolved.bundle, **fields)
166
+ end
167
+ ContextSources::Source.new(cmd: candidate.cmd, hint: nil, every_seconds: nil, provider: nil, **fields)
168
+ end
169
+
170
+ # The proposed candidates (no source of theirs attached, not declined).
171
+ def proposed(session_id, project_root:, state_dir: nil)
172
+ with_status(session_id, project_root: project_root, state_dir: state_dir)
173
+ .filter_map { |candidate, state| candidate if state == "proposed" }
174
+ end
175
+
176
+ # Turn start (Worker#run_prompt before its absorb; the REPL's turn):
177
+ # the proposed candidates +prompt+ (or an earlier owner prompt: a late
178
+ # proposal) mentions are attached, then each gets one first fetch
179
+ # (together within +seconds+), so the note reaches this turn. Only an
180
+ # owner's turn (OwnerPrompt.turn?). Also fetches a candidate attached
181
+ # since the last turn whose source has never been tried.
182
+ # @param session [Session]
183
+ # @param cancelled [#call] true: stop waiting (the session was stopped)
184
+ # @return [Array<String>] the names attached now
185
+ def before_turn(session:, prompt:, author:, state_dir: nil, seconds: FIRST_FETCH_SECONDS, cancelled: -> { false })
186
+ return [] unless session&.id
187
+
188
+ own = ContextSources.session_location(session.id, state_dir: state_dir)
189
+ return [] if own.candidates.empty? || !OwnerPrompt.turn?(session: session, author: author)
190
+
191
+ # The earlier owner prompts too: a proposal that came while one ran
192
+ # (the REPL's plugins never see a running turn's prompt).
193
+ texts = owner_texts(session.messages) + (prompt.is_a?(String) ? [prompt] : [])
194
+ found = hits(texts, proposed(session.id, project_root: session.project_root, state_dir: state_dir))
195
+ names = found.filter_map { |hit| attach(hit, own: own, state_dir: state_dir) }
196
+ first_fetch(own, unfetched(own, names), cwd: session.working_directory, seconds: seconds, cancelled: cancelled)
197
+ names
198
+ rescue StandardError => e
199
+ Log.warn(:context, "candidates_turn_failed", error: e.class.name, msg: e.message.to_s[0, 200])
200
+ []
201
+ end
202
+
203
+ # The REPL's turn start (it has no ContextAbsorber running): the notes
204
+ # of the sources attached from candidates, as the worker's absorb gives
205
+ # them, added to +engine+'s session and marked delivered.
206
+ # @return [Integer] how many notes were added
207
+ def deliver_notes(engine, session, state_dir: nil)
208
+ own = ContextSources.session_location(session.id, state_dir: state_dir)
209
+ names = own.candidates.map(&:name)
210
+ return 0 if names.empty?
211
+
212
+ absorber = ContextAbsorber.new(session_id: session.id, state_dir: state_dir, project_root: session.project_root)
213
+ batch = absorber.pending or return 0
214
+ picked = batch.deliveries.select { |delivery| names.include?(delivery.name) }
215
+ picked.each { |delivery| engine.add_context_note(session, delivery.note) if delivery.note }
216
+ absorber.commit(batch.with(deliveries: picked))
217
+ picked.count(&:note)
218
+ end
219
+
220
+ # A late proposal (ctx.context.propose, after the owner's prompts):
221
+ # attached now when one of them mentions it; the session's next turn
222
+ # delivers its note.
223
+ # @return [String, nil] the name attached
224
+ def after_propose(candidate, own:, messages:, state_dir: nil)
225
+ hit = hits(owner_texts(messages), [candidate]).first or return nil
226
+
227
+ attach(hit, own: own, state_dir: state_dir)
228
+ end
229
+
230
+ # The session sources from candidates (+names+, and any other
231
+ # candidate's source) never tried yet.
232
+ def unfetched(own, names)
233
+ wanted = (names + own.candidates.map(&:name)).uniq
234
+ wanted.filter_map do |name|
235
+ source = own.source(name) or next
236
+ next if source.push? || own.snapshot(name).checked_at
237
+
238
+ ContextSources::Attached.new(source: source, location: own, shadowed: false)
239
+ end
240
+ end
241
+
242
+ # Runs each source's first fetch, all within +seconds+; one a poller
243
+ # fetches meanwhile (:busy) is waited for. Cut short, a fetch records
244
+ # nothing (the poller tries it soon); the note then comes later.
245
+ def first_fetch(own, list, cwd:, seconds:, cancelled:)
246
+ return if list.empty?
247
+
248
+ deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
249
+ over = -> { cancelled.call || Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline }
250
+ list.each do |attached|
251
+ outcome = ContextFetch.fetch(attached, cwd: cwd, cancelled: over)
252
+ sleep(0.05) while outcome.status == :busy && !own.snapshot(attached.name).checked_at && !over.call
253
+ next unless over.call && !own.snapshot(attached.name).text?
254
+
255
+ Log.info(:context, "candidate_first_fetch_late", name: attached.name, seconds: seconds)
256
+ end
257
+ end
258
+ end
259
+ end
@@ -0,0 +1,90 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "log"
4
+ require_relative "session"
5
+ require_relative "side_judgments"
6
+
7
+ module Samagotchi
8
+ # The candidates' record, `context_candidates.jsonl` in the state dir
9
+ # (beside the sessions folder; SideJudgments.log: 0600, one line under a
10
+ # lock, the oldest half dropped past 5 MB): what happened to each
11
+ # session's candidates, for `chi context report` (ContextReportCommand).
12
+ # Local only: nothing here leaves the machine, so it is written in every
13
+ # context.candidates.mode, off too.
14
+ #
15
+ # Kinds (every line has session_id, name and at):
16
+ # - proposed: a plugin's ctx.context.propose recorded it (title, by)
17
+ # - mentioned: an owner prompt named it and it was attached (mention)
18
+ # - judged: System 1's ask (ContextJudge.ask: p, task_p, stated, would, …)
19
+ # - judge_attached: on mode attached it (p ≥ threshold; p)
20
+ # - carded: on mode showed its card (the middle band; p): once per
21
+ # candidate, read back by ContextCandidateChoice.carded?
22
+ # - attached / declined with by "command": /context attach|decline NAME
23
+ # (the card's buttons)
24
+ # - attached / declined / detached with by "user": the derived status
25
+ # changed since the last line said otherwise, seen at an owner turn's
26
+ # start (#look): the user's own doing (chi context add, chi web's chip
27
+ # ×, chi context rm; a removed source is declined)
28
+ # - withdrawn: the plugin took the candidate back
29
+ module ContextCandidatesLog
30
+ FILE = "context_candidates.jsonl"
31
+ # What a logged prompt keeps of its text.
32
+ PROMPT_MAX = 200
33
+ # The status each kind leaves a candidate in (#statuses).
34
+ STATUS_OF = { "proposed" => "proposed", "mentioned" => "attached", "judge_attached" => "attached", "attached" => "attached",
35
+ "declined" => "declined", "detached" => "proposed", "withdrawn" => nil }.freeze
36
+
37
+ module_function
38
+
39
+ # @param state_dir [String, nil] the sessions folder (Session.default_state_dir)
40
+ def path(state_dir = nil) = File.join(File.dirname(state_dir || Session.default_state_dir), FILE)
41
+
42
+ # @return [SystemOne::Log]
43
+ def log_for(state_dir = nil) = SideJudgments.log(path(state_dir), tag: :context, event: "context_candidates_log_failed")
44
+
45
+ # One line; never raises.
46
+ # @return [Boolean] whether it was written
47
+ def event(kind, session_id:, name:, state_dir: nil, log: nil, **fields)
48
+ (log || log_for(state_dir)).entry(kind, { "session_id" => session_id.to_s, "name" => name.to_s }.merge(fields.compact))
49
+ rescue StandardError => e
50
+ Log.warn(:context, "context_candidates_log_failed", error: e.class.name, msg: e.message.to_s[0, 200])
51
+ false
52
+ end
53
+
54
+ # +session_id+'s lines, oldest first.
55
+ def records_for(log, session_id) = log.records.select { |line| line["session_id"] == session_id.to_s }
56
+
57
+ # The status the lines last left each candidate in, by name (a
58
+ # withdrawn one is gone).
59
+ # @return [Hash{String => String}]
60
+ def statuses(records)
61
+ records.each_with_object({}) do |line, known|
62
+ next unless STATUS_OF.key?(line["kind"])
63
+
64
+ status = STATUS_OF[line["kind"]]
65
+ status ? known[line["name"]] = status : known.delete(line["name"])
66
+ end
67
+ end
68
+
69
+ # The derived statuses now (+rows+: ContextCandidates.with_status)
70
+ # against the last ones logged: each change is a line (attached,
71
+ # declined, detached). A candidate never logged counts as proposed.
72
+ # @return [Array<String>] the kinds written
73
+ def look(log, session_id, rows, records)
74
+ known = statuses(records)
75
+ rows.filter_map do |candidate, status|
76
+ next if status == (known[candidate.name] || "proposed")
77
+
78
+ kind = status == "proposed" ? "detached" : status
79
+ event(kind, session_id: session_id, name: candidate.name, log: log, by: "user")
80
+ kind
81
+ end
82
+ end
83
+
84
+ # +text+ as a log line keeps it: one line, at most PROMPT_MAX chars.
85
+ def short(text)
86
+ line = text.to_s.gsub(/\s+/, " ").strip
87
+ line.length > PROMPT_MAX ? "#{line[0, PROMPT_MAX - 1]}…" : line
88
+ end
89
+ end
90
+ end