samagotchi 0.102.0 → 0.103.0

data/lib/samagotchi/working_set_steer.rb

@@ -6,11 +6,14 @@ require_relative "llm_context_view"
 require_relative "llm_context_apply"
 require_relative "token_usage"
 require_relative "working_set"
+require_relative "working_set_pin"
 
 module Samagotchi
   # The user steering the working set (/working-set, the web's popover):
   # drop an item (every content output of it still sent goes out of the
-  # prompt as a stub) and undrop it. Pure, on a conversation the caller
+  # prompt as a stub) and undrop it; pin one (the model's forget_outputs
+  # refuses its outputs, LLMContextForget) and unpin it. Pure, on a
+  # conversation the caller
   # owns (Engine#clone_messages' copies: an op stores new edits Hashes,
   # LLMContextEdit.store) and runs between turns, so the next turn's first
   # request is the first with the change (prompt caching: one break where
@@ -24,6 +27,20 @@ module Samagotchi
   # puts it back. The outputs are WorkingSet.outputs_of's, the projection's
   # own pairing, so the set and the op never disagree.
   #
+  # A pin is the session's (Session#working_set_pins, a WorkingSetPin per
+  # item), not an edit: it sends nothing different, so it breaks no cache
+  # and survives a strategy switch. Pin and drop exclude each other: a
+  # drop asks for an unpin first, and a pin takes a pending drop off (one
+  # never sent: free), else asks for an undrop first.
+  #
+  # An add is a request: the turn-start note asks the model to read the
+  # item (read, memory_read, web_fetch) before the task, so its output is
+  # a real tool run (stamps, ids, forget, the projection), on both loops.
+  # Nothing sent changes until then; it costs the model one step. An item
+  # the model has whole already is refused; a stale or forgotten one is
+  # its refresh. Pending until the next turn sends the note
+  # (WorkingSet.pending_adds); an unadd takes it back.
+  #
   # Every op since the last turn is listed in one tail system message
   # (kind "working_set", #record!), so the model learns what changed and
   # doesn't read a dropped file again by reflex. An inverse op before the
@@ -31,14 +48,18 @@ module Samagotchi
   # nothing noted).
   module WorkingSetSteer
     BY = "user"
-    NOTE_KIND = "working_set"
+    NOTE_KIND = WorkingSet::NOTE_KIND
     # The tail note's ops: [{"op", "kind", "key", "label"}], until the turn
     # that sends it (the chat loop's kept entries leave the key out).
-    OPS = :working_set_ops
+    OPS = WorkingSet::NOTE_OPS
     NOTE_OPEN = "[WORKING SET: "
     DROP = "drop"
     UNDROP = "undrop"
-    INVERSE = { DROP => UNDROP, UNDROP => DROP }.freeze
+    PIN = "pin"
+    UNPIN = "unpin"
+    ADD = WorkingSet::ADD
+    UNADD = "unadd"
+    INVERSE = { DROP => UNDROP, UNDROP => DROP, PIN => UNPIN, UNPIN => PIN, ADD => UNADD, UNADD => ADD }.freeze
     MEMORY_PREFIX = "memory:"
     URL = %r{\A[a-z][a-z0-9+.-]*://}i
 
@@ -47,12 +68,25 @@ module Samagotchi
     class Refused < StandardError
       MESSAGES = {
         dropped: "dropped by the user",
+        pinned_by_user: "pinned by the user: it stays in your context",
+        unpin_first: "pinned by the user: unpin it first",
+        undrop_first: "dropped by the user: undrop it first",
+        already_pinned: "already pinned",
+        not_pinned: "not pinned",
         not_in_set: "not in the working set",
         only_edited: "nothing to drop: only edited or written (no read of it is sent)",
         derived: "nothing to drop: an older session's output that chi can't name",
         already_dropped: "already dropped",
         not_sent: "nothing to drop: none of it is sent now (forgotten or stubbed)",
-        not_dropped: "not dropped"
+        not_dropped: "not dropped",
+        no_file: "no such file",
+        directory: "a directory: add its files",
+        no_memory: "no such memory",
+        bad_memory: "not a memory name (no /, \\ or ..)",
+        not_http: "not an http(s) URL: web_fetch can't fetch it",
+        already_sent: "already in the model's context (sent whole): nothing to add",
+        already_added: "already added: the next turn reads it",
+        not_added: "not added (no add of it is pending)"
       }.freeze
 
       # @return [Symbol] a key of MESSAGES
@@ -73,11 +107,44 @@ module Samagotchi
 
     # What an op did: the ids it changed, and the chars it frees (a drop)
     # and the tail the server reads again from its earliest entry on.
-    # +free+: an undrop that took back a drop never sent (nothing changes).
-    Done = Data.define(:target, :op, :ids, :freed_chars, :tail_chars, :free)
+    # +free+: an undrop that took back a drop never sent (nothing changes),
+    # a pin or an unpin (nothing sent changes). +undone+: the pending drop
+    # a pin took off (a Done), else nil. +shared_with+: the other memories a
+    # memory_read of several names holds in an output the op acted on (the
+    # op acts on that output whole, so on them too).
+    Done = Data.define(:target, :op, :ids, :freed_chars, :tail_chars, :free, :undone, :shared_with) do
+      def initialize(undone: nil, shared_with: [], **fields) = super
+    end
 
     module_function
 
+    # A word quoted ("…" or '…'): runs to its closing quote, spaces and
+    # all; a backslash escapes the quote or itself. Else a bare word.
+    WORD = /\G\s*(?:"((?:[^"\\]|\\.)*)"?|'((?:[^'\\]|\\.)*)'?|(\S+))/m
+    # What a quoted word unescapes (\" \' \\); any other backslash stays.
+    ESCAPE = /\\(["'\\])/
+    # A word that needs quoting on a line: whitespace, or a leading quote.
+    QUOTE = /\s|\A["']/
+
+    # The KEY words of a /working-set line (what follows the verb):
+    # whitespace-separated, a quoted word keeps its spaces ("my dir/a.rb").
+    # An unclosed quote runs to the end. The web's working_set.js
+    # (steerWords) reads lines the same way.
+    # @return [Array<String>]
+    def words(text)
+      text.to_s.scan(WORD).filter_map do |double, single, bare|
+        quoted = double || single
+        quoted ? quoted.gsub(ESCAPE, '\\1') : bare
+      end.reject(&:empty?)
+    end
+
+    # +word+ as a line names it: quoted when it has whitespace or starts
+    # with a quote (#words reads it back), else as it is.
+    def quote(word)
+      word = word.to_s
+      word.match?(QUOTE) ? %("#{word.gsub(/["\\]/) { |char| "\\#{char}" }}") : word
+    end
+
     # +word+ (a path, absolute or the session's folder's; memory:NAME; a
     # URL) as a Target.
     def target(word, cwd:)
@@ -103,9 +170,12 @@ module Samagotchi
     # Drops +target+'s content outputs that are still sent under
     # +strategy+ (the next turn's: LLMContextView's form), saving an applied
     # :drop on each.
+    # +pins+: the session's (a pinned item asks for an unpin first).
     # @return [Done]
     # @raise [Refused]
-    def drop(conversation, target, strategy:, cwd:, now: Time.now.utc.iso8601(3))
+    def drop(conversation, target, strategy:, cwd:, pins: [], now: Time.now.utc.iso8601(3))
+      raise Refused, :unpin_first if pinned?(pins, target)
+
       outputs = WorkingSet.outputs_of(conversation, kind: target.kind, key: target.key, strategy: strategy, cwd: cwd)
       raise Refused, (known?(conversation, target, strategy, cwd) ? :only_edited : :not_in_set) if outputs.empty?
 
@@ -124,7 +194,7 @@ module Samagotchi
       freed, tail = LLMContextApply.weigh(conversation, layers: layers(strategy), edits: edits)
       edits.each { |index, edit| LLMContextEdit.store(conversation[index], edit) }
       Done.new(target: target, op: DROP, ids: edits.map { |_, edit| edit.id }, freed_chars: freed, tail_chars: tail,
-               free: false)
+               free: false, shared_with: shared_with(sent))
     end
 
     # Takes +target+'s drops off, putting back what each output held before
@@ -149,7 +219,85 @@ module Samagotchi
       view = LLMContextView.new(strategy: strategy)
       tail = sent ? LLMContextView.chars(view.messages(conversation)[first..]) : 0
       Done.new(target: target, op: UNDROP, ids: dropped.map { |output, _| output.id }, freed_chars: 0, tail_chars: tail,
-               free: !sent)
+               free: !sent, shared_with: shared_with(dropped.map(&:first)))
+    end
+
+    # Pins +target+ (an item the set holds; an edit-only one too: its later
+    # reads are covered). A drop of it still pending (made since the last
+    # turn) is taken off first, free, as Done#undone; a sent one asks for
+    # an undrop first. The caller adds the pin (#pinning).
+    # @param pins [Array<WorkingSetPin>] the session's
+    # @return [Done] +ids+: the outputs the pin holds now
+    # @raise [Refused]
+    def pin(conversation, pins, target, strategy:, cwd:)
+      outputs = WorkingSet.outputs_of(conversation, kind: target.kind, key: target.key, strategy: strategy, cwd: cwd)
+      raise Refused, :not_in_set if outputs.empty? && !known?(conversation, target, strategy, cwd)
+      raise Refused, :already_pinned if pinned?(pins, target)
+
+      undone = nil
+      if outputs.any? { |output| drop_of(conversation, output) }
+        raise Refused, :undrop_first unless pending?(conversation, DROP, target)
+
+        undone = undrop(conversation, target, strategy: strategy, cwd: cwd, sent: false)
+      end
+      named = outputs.reject(&:derived)
+      Done.new(target: target, op: PIN, ids: named.map(&:id), freed_chars: 0, tail_chars: 0, free: true, undone: undone,
+               shared_with: shared_with(named))
+    end
+
+    # Unpins +target+: the model may forget it again. Only the pins are
+    # asked (a rollback may have taken the item out of the set).
+    # @return [Done]
+    # @raise [Refused]
+    def unpin(pins, target)
+      raise Refused, :not_pinned unless pinned?(pins, target)
+
+      Done.new(target: target, op: UNPIN, ids: [], freed_chars: 0, tail_chars: 0, free: true)
+    end
+
+    # Adds +target+: the next turn's note asks the model to read it. +found+
+    # answers whether the item exists (a file, a memory; the caller's
+    # look). Refused for an item the model is sent whole now (live, a read
+    # of it sent), a dropped one (undrop it), and one added already.
+    # @param found [#call] target → nil when it exists, else a Refused reason
+    # @return [Done]
+    # @raise [Refused]
+    def add(conversation, target, strategy:, cwd:, found: ->(_) {})
+      raise Refused, :already_added if pending?(conversation, ADD, target)
+
+      reason = target.kind == WorkingSet::URL && !target.key.match?(%r{\Ahttps?://}i) ? :not_http : found.call(target)
+      raise Refused, reason if reason
+
+      outputs = WorkingSet.outputs_of(conversation, kind: target.kind, key: target.key, strategy: strategy, cwd: cwd)
+      raise Refused, :undrop_first if outputs.any? { |output| drop_of(conversation, output) }
+      raise Refused, :already_sent if outputs.any?(&:sent) && live?(conversation, target, strategy, cwd)
+
+      Done.new(target: target, op: ADD, ids: [], freed_chars: 0, tail_chars: 0, free: true)
+    end
+
+    # Takes back +target+'s pending add (never sent: free).
+    # @return [Done]
+    # @raise [Refused]
+    def unadd(conversation, target)
+      raise Refused, :not_added unless pending?(conversation, ADD, target)
+
+      Done.new(target: target, op: UNADD, ids: [], freed_chars: 0, tail_chars: 0, free: true)
+    end
+
+    # +pins+ after +done+ (a pin or an unpin). A new frozen Array.
+    # @return [Array<WorkingSetPin>]
+    def pinning(pins, done)
+      pin = WorkingSetPin.new(kind: done.target.kind, key: done.target.key)
+      rest = Array(pins).reject { |held| held == pin }
+      (done.op == PIN ? rest + [pin] : rest).freeze
+    end
+
+    # The other memory names +outputs+ hold (WorkingSet::Output#shared_with).
+    def shared_with(outputs) = outputs.flat_map(&:shared_with).uniq
+
+    # Whether +pins+ hold +target+.
+    def pinned?(pins, target)
+      Array(pins).any? { |pin| pin.kind == target.kind && pin.key == target.key }
     end
 
     # +output+'s drop (an LLMContextEdit), or nil.
@@ -165,26 +313,23 @@ module Samagotchi
       end
     end
 
+    # Whether the set holds +target+ live (not stale, forgotten, dropped).
+    def live?(conversation, target, strategy, cwd)
+      WorkingSet.build(conversation, cwd: cwd, strategy: strategy).items.any? do |item|
+        item.kind == target.kind && item.key == target.key && item.state == WorkingSet::LIVE
+      end
+    end
+
     def layers(strategy) = LLMContextView.new(strategy: strategy).layers
 
     # ── the tail note ───────────────────────────────────────────────────
 
-    # The index of the note the next turn will send (one after the last
-    # turn's entries: only system messages follow it), or nil.
-    def pending_note_index(messages)
-      (messages.size - 1).downto(0) do |index|
-        message = messages[index]
-        return nil unless message[:role].to_s == "system"
-        return index if message[:kind].to_s == NOTE_KIND
-      end
-      nil
-    end
+    # The index of the note the next turn will send, or nil
+    # (WorkingSet.pending_note_index).
+    def pending_note_index(messages) = WorkingSet.pending_note_index(messages)
 
     # The ops the pending note lists ([{"op", "kind", "key", "label"}]).
-    def pending_ops(messages)
-      index = pending_note_index(messages)
-      index ? Array(messages[index][OPS]).select { |op| op.is_a?(Hash) } : []
-    end
+    def pending_ops(messages) = WorkingSet.pending_ops(messages)
 
     # Whether +target+'s +op+ is pending (made since the last turn).
     def pending?(messages, op, target)
@@ -224,8 +369,8 @@ module Samagotchi
     # The note listing +ops+: a tail system message, escaped like a context
     # note (Prompt::ESCAPED_KINDS: it carries paths and URLs).
     def note(ops)
-      drops = ops.select { |entry| entry["op"] == DROP }.map { |entry| entry["label"] }
-      undrops = ops.select { |entry| entry["op"] == UNDROP }.map { |entry| entry["label"] }
+      drops = labels(ops, DROP)
+      undrops = labels(ops, UNDROP)
       parts = []
       unless drops.empty?
         parts << "the user dropped #{drops.join(", ")} from your context: you are sent a stub instead of " \
@@ -236,15 +381,34 @@ module Samagotchi
         parts << "the user brought back #{undrops.join(", ")}: #{undrops.size == 1 ? "its outputs are" : "their outputs are"} " \
                  "sent whole again"
       end
+      pins = labels(ops, PIN)
+      parts << "the user pinned #{pins.join(", ")}: forget_outputs won't forget #{pins.size == 1 ? "it" : "them"}" unless pins.empty?
+      unpins = labels(ops, UNPIN)
+      parts << "the user unpinned #{unpins.join(", ")}: you may forget #{unpins.size == 1 ? "it" : "them"} again" unless unpins.empty?
+      adds = ops.select { |entry| entry["op"] == ADD }
+      unless adds.empty?
+        parts << "the user added #{adds.map { |entry| entry["label"] }.join(", ")} to your context: before anything " \
+                 "else, load #{adds.size == 1 ? "it" : "them"} with #{adds.map { |entry| call_of(entry) }.join(", ")}"
+      end
       { role: "system", kind: NOTE_KIND, content: "#{NOTE_OPEN}since your last turn #{parts.join("; ")}.]", OPS => ops }
     end
 
+    def labels(ops, op) = ops.select { |entry| entry["op"] == op }.map { |entry| entry["label"] }
+
+    # The tool call that loads an added item, as the note asks for it: a
+    # file by its absolute path (a read resolves a relative one against
+    # the process's folder, which may not be the session's).
+    def call_of(entry)
+      tool = { WorkingSet::MEMORY => "memory_read", WorkingSet::URL => "web_fetch" }.fetch(entry["kind"], "read")
+      %(#{tool} "#{entry["key"]}")
+    end
+
     # "12.4k tokens", chars/4.
     def k(chars)
       tokens = (chars / TokenUsage::CHARS_PER_TOKEN).ceil
       tokens >= 1000 ? format("%.1fk tokens", tokens / 1000.0) : "#{tokens} tokens"
     end
 
-    private_class_method :relative, :drop_of, :known?, :layers, :same?
+    private_class_method :relative, :shared_with, :drop_of, :known?, :live?, :layers, :same?, :labels, :call_of
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: samagotchi
 version: !ruby/object:Gem::Version
-  version: 0.102.0
+  version: 0.103.0
 platform: ruby
 authors:
 - Dmitry Dedov
@@ -161,6 +161,7 @@ files:
 - docs/internals/llm-context-forget.md
 - docs/internals/llm-context-live.md
 - docs/internals/prompt-caching.md
+- docs/internals/remote-sessions.md
 - docs/internals/tool-guardrails.md
 - docs/internals/working-set.md
 - docs/memory.md
@@ -194,6 +195,7 @@ files:
 - lib/samagotchi/bridge_client.rb
 - lib/samagotchi/bridge_client/event_stream.rb
 - lib/samagotchi/bridge_client/sse_parser.rb
+- lib/samagotchi/bridge_client/stream_request.rb
 - lib/samagotchi/broadcast/recipients.rb
 - lib/samagotchi/broadcast/scope_card.rb
 - lib/samagotchi/broadcast/tags.rb
@@ -270,6 +272,7 @@ files:
 - lib/samagotchi/bundles/work-cap/plugin.rb
 - lib/samagotchi/cache_confirm.rb
 - lib/samagotchi/cancellation_controller.rb
+- lib/samagotchi/chi_invocation.rb
 - lib/samagotchi/child_env.rb
 - lib/samagotchi/child_move.rb
 - lib/samagotchi/child_reports.rb
@@ -503,17 +506,28 @@ files:
 - lib/samagotchi/relay_watcher.rb
 - lib/samagotchi/reminder_queue.rb
 - lib/samagotchi/reminder_store.rb
+- lib/samagotchi/remote_command.rb
+- lib/samagotchi/remotes.rb
 - lib/samagotchi/reply_wait.rb
 - lib/samagotchi/reply_wait/poll.rb
 - lib/samagotchi/row_refs.rb
+- lib/samagotchi/run_options.rb
 - lib/samagotchi/sampling_settings.rb
 - lib/samagotchi/sandbox_layout.rb
 - lib/samagotchi/self_report.rb
 - lib/samagotchi/send_command.rb
+- lib/samagotchi/send_command/busy.rb
 - lib/samagotchi/send_command/parent_gate.rb
 - lib/samagotchi/send_command/wait_target.rb
 - lib/samagotchi/served_model.rb
 - lib/samagotchi/session.rb
+- lib/samagotchi/session_access.rb
+- lib/samagotchi/session_access/contract.rb
+- lib/samagotchi/session_access/dispatch.rb
+- lib/samagotchi/session_access/http_transport.rb
+- lib/samagotchi/session_access/local.rb
+- lib/samagotchi/session_access/remote.rb
+- lib/samagotchi/session_access/web_bridge_client.rb
 - lib/samagotchi/session_archive_command.rb
 - lib/samagotchi/session_chain.rb
 - lib/samagotchi/session_commands.rb
@@ -544,6 +558,7 @@ files:
 - lib/samagotchi/task_watch.rb
 - lib/samagotchi/terminal_ui.rb
 - lib/samagotchi/terminal_ui/attach_launcher.rb
+- lib/samagotchi/terminal_ui/attach_link.rb
 - lib/samagotchi/terminal_ui/attached_loop.rb
 - lib/samagotchi/terminal_ui/attached_view.rb
 - lib/samagotchi/terminal_ui/between_turns.rb
@@ -553,6 +568,7 @@ files:
 - lib/samagotchi/terminal_ui/input_support.rb
 - lib/samagotchi/terminal_ui/line_reader.rb
 - lib/samagotchi/terminal_ui/live_region.rb
+- lib/samagotchi/terminal_ui/local_link.rb
 - lib/samagotchi/terminal_ui/model_segments_text.rb
 - lib/samagotchi/terminal_ui/one_shot_sink.rb
 - lib/samagotchi/terminal_ui/plain_surface.rb
@@ -767,6 +783,7 @@ files:
 - lib/samagotchi/web/public/working_set_view.js
 - lib/samagotchi/web/qr.rb
 - lib/samagotchi/web/server.rb
+- lib/samagotchi/web/session_access_routes.rb
 - lib/samagotchi/web/session_hub.rb
 - lib/samagotchi/web/session_summary.rb
 - lib/samagotchi/web/token.rb
@@ -779,6 +796,7 @@ files:
 - lib/samagotchi/worker_wakes.rb
 - lib/samagotchi/working_set.rb
 - lib/samagotchi/working_set_command.rb
+- lib/samagotchi/working_set_pin.rb
 - lib/samagotchi/working_set_steer.rb
 - lib/samagotchi/yaml_lines.rb
 homepage: https://github.com/dm1try/samagotchi