samagotchi 0.12.0 → 0.13.0

data/lib/samagotchi/terminal_ui.rb

@@ -15,6 +15,7 @@ require_relative "host_registry"
 require_relative "session"
 require_relative "owner_lock"
 require_relative "engine"
+require_relative "guardrails/parent_approvals"
 require_relative "tools/memory"
 require_relative "output_formatter"
 require_relative "turn_flow"
@@ -1138,9 +1139,16 @@ module Samagotchi
         end
 
         begin
-          @engine.answer_question(id: prompt.id, selected: answer.selected, freeform: answer.freeform)
+          parent = parent_answers? ? { client_id: Guardrails::ParentApprovals::CLIENT_ID } : {}
+          @engine.answer_question(id: prompt.id, selected: answer.selected, freeform: answer.freeform, **parent)
           close_question_widget(prompt, prompt.answer_text(answer))
           return true
+        rescue QuestionDesk::Refused => e
+          # A parent's allow guardrails.parent_approvals doesn't let through:
+          # the question stays open for a deny (or the end of the input).
+          @surface.commit("#{paint(QUESTION_PROMPT, 33)}#{raw}")
+          @surface.commit(Guardrails::ParentApprovals.message(e.reason, typed: true))
+          next
         rescue ArgumentError => e
           @surface.commit("Invalid: #{e.message}. Try again.")
           next
@@ -1151,6 +1159,12 @@ module Samagotchi
       end
     end
 
+    # Whether the answers typed here are a parent agent's (piped stdin, an
+    # agent marker): QuestionDesk holds them to guardrails.parent_approvals.
+    def parent_answers?
+      Guardrails::ParentApprovals.parent_process?
+    end
+
     def close_question_widget(prompt, outcome)
       @surface.clear_slot(:notes)
       @surface.commit(prompt.summary(outcome, paint: method(:paint)))

data/lib/samagotchi/thought_stream_splitter.rb

@@ -25,15 +25,15 @@ module Samagotchi
   # not a block and stays in `:text` (the model doesn't emit it; the system
   # prompt carries it).
   class ThoughtStreamSplitter
-    # Gemma 4's thought channel (ToolCallParser::Gemma strips the same pair).
-    GEMMA_THOUGHT_CHANNEL = { open: "<|channel>thought", close: "<channel|>" }.freeze
-
     # @return [Array<Hash>] each entry { open: String, close: String, lane: :thinking|:drop }
     def self.for_profile(profile)
       blocks = []
       # A thinking block needs a close marker to be bounded.
       blocks << { open: profile.thought_open, close: profile.thought_close, lane: :thinking } if profile.thought_close
-      blocks << GEMMA_THOUGHT_CHANNEL.merge(lane: :thinking) if profile.name == "gemma4"
+      # Gemma 4's thought channel (ToolCallParser::Gemma strips the same pair).
+      if profile.thought_channel_open
+        blocks << { open: profile.thought_channel_open, close: profile.thought_channel_close, lane: :thinking }
+      end
       blocks << { open: profile.tool_call_open, close: profile.tool_call_close, lane: :drop }
       new(blocks)
     end

data/lib/samagotchi/tool_call_parser.rb

@@ -38,8 +38,8 @@ module Samagotchi
       # Digits after the first character: plugin tools may have them
       # (Plugin::Api::TOOL_NAME).
       TOOL_CALL_BODY_RE   = /\Acall:([a-z_][a-z0-9_]{0,49})\{/
-      THOUGHT_CHANNEL_OPEN  = "<|channel>thought"
-      THOUGHT_CHANNEL_CLOSE = "<channel|>"
+      THOUGHT_CHANNEL_OPEN  = ModelProfile::GEMMA_THOUGHT_CHANNEL_OPEN
+      THOUGHT_CHANNEL_CLOSE = ModelProfile::GEMMA_THOUGHT_CHANNEL_CLOSE
       CONTROL_TOKEN_START = "<|"
 
       def initialize(profile)
@@ -305,10 +305,10 @@ module Samagotchi
       end
 
       def parse(text)
-        read(text).map { |call| Tools::BuiltinCalls.build(call[:name], call[:args], raw: call[:raw]) }
+        read(text).map { |call| Tools::BuiltinCalls.build(call[:name], call[:args]) }
       end
 
-      # Each <tool_call> block as {name:, args:, raw:}: its <parameter=…>
+      # Each <tool_call> block as {name:, args:}: its <parameter=…>
       # (or <arg_key>/<arg_value>) text by lowercased key, unbuilt.
       def read(text)
         results = []
@@ -324,8 +324,7 @@ module Samagotchi
 
           body = text[body_start...close_pos]
           if (name = qwen_function_name(body))
-            params = qwen_params(body)
-            results << { name: name, args: params, raw: params.to_s }
+            results << { name: name, args: qwen_params(body) }
           end
           pos = close_pos + tool_close.length
         end

data/lib/samagotchi/tools/builtin_calls.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "json"
 require_relative "../tool_declarations"
 require_relative "ask_user_question"
 
@@ -18,7 +19,7 @@ module Samagotchi
     # and the handler reading it.
     #
     # A tool that is not built in keeps its arguments whole on args: (typed
-    # by its schema at dispatch, Tools::Args) with +raw+ as its content.
+    # by its schema at dispatch, Tools::Args) with their JSON as its content.
     module BuiltinCalls
       # Per tool, what the schema alone doesn't say:
       #   content:  the property (or ordered list of keys to try) that fills
@@ -103,7 +104,7 @@ module Samagotchi
       # @param name [String]
       # @param args [Hash] string keys, as the model gave them
       # @param raw [String, nil] the call's text, the content of a tool
-      #   that isn't built in
+      #   that isn't built in when no argument could be read from it
       # @return [Hash]
       def build(name, args, raw: nil)
         name = name.to_s
@@ -139,7 +140,17 @@ module Samagotchi
       end
 
       def passthrough(name, args, raw)
-        { name: name, content: raw.nil? ? args.values.join(" ") : raw.to_s, path: nil, scope: nil, args: args }
+        { name: name, content: passthrough_content(args, raw), path: nil, scope: nil, args: args }
+      end
+
+      # The arguments as JSON, one form for every model format and Ruby
+      # version; the raw text when none could be read from it.
+      def passthrough_content(args, raw)
+        return raw.to_s if args.empty? && !raw.to_s.empty?
+
+        JSON.generate(args)
+      rescue JSON::GeneratorError
+        args.values.join(" ")
       end
     end
   end

data/lib/samagotchi/tools/builtins.rb

@@ -21,6 +21,7 @@ require_relative "send_note"
 require_relative "delegate"
 require_relative "delegate_result"
 require_relative "ask_user_question"
+require_relative "../guardrails/parent_approvals"
 
 module Samagotchi
   module Tools
@@ -72,13 +73,15 @@ module Samagotchi
         TaskCreate::NAME => lambda do |call, kctx|
           next Execute::NOT_RUN_ON_STOP if cancelled_proc(kctx).call
 
-          TaskCreate.call(call[:content], cwd: call[:cwd], env: call[:env])
+          TaskCreate.call(call[:content], cwd: call[:cwd], env: call[:env], marker_env: parent_env(kctx))
         end,
         TaskWait::NAME => lambda do |call, kctx|
           TaskWait.call(call[:content], timeout: call[:timeout], tail_lines: call[:tail_lines],
                                         done_pattern: call[:done_pattern], cancelled: cancelled_proc(kctx))
         end,
-        Execute::NAME => ->(call, kctx) { Execute.call(call[:content], cwd: call[:cwd], cancelled: cancelled_proc(kctx)) },
+        Execute::NAME => lambda do |call, kctx|
+          Execute.call(call[:content], cwd: call[:cwd], cancelled: cancelled_proc(kctx), env: parent_env(kctx))
+        end,
         RegisterReminder::NAME => lambda do |call, kctx|
           RegisterReminder.call(call[:content], reminder_store: kctx.reminder_store, description: call[:description],
                                                 interval_minutes: call[:interval_minutes])
@@ -99,6 +102,15 @@ module Samagotchi
 
       module_function
 
+      # What execute and task_create export into the commands they run: a
+      # chi started there answers as a parent agent
+      # (Guardrails::ParentApprovals.parent_process?), even under a PTY
+      # wrapper. The session's id, "chi" without one.
+      def parent_env(kctx)
+        id = kctx.peers.respond_to?(:session_id) ? kctx.peers.session_id.to_s : ""
+        { Guardrails::ParentApprovals::PARENT_SESSION_ENV => id.empty? ? "chi" : id }
+      end
+
       # Stop flips the turn's controller, seen through the Engine's PeerView
       # (as DelegateWait does); a bare kernel has no peers: never cancelled.
       def cancelled_proc(kctx)

data/lib/samagotchi/tools/delegate_wait.rb

@@ -2,6 +2,7 @@
 
 require_relative "../session"
 require_relative "../reply_wait"
+require_relative "../parent_report"
 require_relative "output_guardrails"
 require_relative "peers"
 
@@ -18,6 +19,10 @@ module Samagotchi
     module DelegateWait
       TIMEOUT_DEFAULT = 600
       POLL_INTERVAL = 0.5
+      # Seconds with no worker before the child counts as gone: as long as
+      # Delegate gives a starting child (its worker takes the owner lock
+      # only once it has booted).
+      OWNER_GRACE = 15
       # Cut like an execute result: full up to TRUNCATE_AT bytes, else a
       # head-and-tail preview of PREVIEW bytes.
       TRUNCATE_AT_BYTES = OutputGuardrails::DEFAULT_TRUNCATE_AT_BYTES
@@ -39,13 +44,16 @@ module Samagotchi
       # @param peers [Peers] the parent (session_id, state_dir, cancelled?)
       # @param timeout [Integer] seconds
       # @param poll_interval [Float]
+      # @param owner_grace [Numeric] seconds with no live worker before
+      #   the child's worker counts as gone
       # @return [String] the tool result
-      def call(child_id, peers:, timeout: TIMEOUT_DEFAULT, poll_interval: POLL_INTERVAL)
+      def call(child_id, peers:, timeout: TIMEOUT_DEFAULT, poll_interval: POLL_INTERVAL, owner_grace: OWNER_GRACE)
         sd = peers.state_dir || Session.default_state_dir
         key = [peers.session_id, child_id]
         cancelled = -> { peers.cancelled? }
         wait = ReplyWait.call(child_id, state_dir: sd, cursor: seen[key], timeout: timeout.to_i,
-                                        poll_interval: poll_interval, cancelled: cancelled, baseline: baselines[key])
+                                        poll_interval: poll_interval, cancelled: cancelled, baseline: baselines[key],
+                                        owner_grace: owner_grace)
         # The turn sent to is handed over: a later wait looks for a later one.
         baselines.delete(key) if %i[done no_reply].include?(wait.status)
         case wait.status
@@ -62,6 +70,9 @@ module Samagotchi
           result(child_id, "canceled", "wait canceled; the child keeps running; delegate_result #{child_id} waits again")
         when :no_reply
           result(child_id, "no_reply", "the child's turn ended without a reply (canceled, failed or empty); its session shows what happened")
+        when :worker_gone
+          result(child_id, "worker_gone",
+                 "the child's worker is gone (it stopped or crashed); delegate with session: #{child_id} starts it again with a message")
         else
           timeout_result(child_id, timeout)
         end
@@ -98,9 +109,10 @@ module Samagotchi
                "chi --attach #{child_id} shows it.")
       end
 
+      # The whole question, as `chi send --wait` prints it (ParentReport):
+      # its text, options and the commands that answer it.
       def waiting_text(child_id, pending)
-        what = pending[:kind].to_s == "approval" ? "an approval" : "a question"
-        "Child #{child_id} is waiting for an answer (#{what}); attach with chi --attach #{child_id} or answer it in the web. " \
+        "Child #{child_id} is #{ParentReport.question_text(pending, session_id: child_id)}" \
           "delegate_result #{child_id} waits again once it is answered."
       end
 

data/lib/samagotchi/tools/execute.rb

@@ -25,7 +25,8 @@ module Samagotchi
 
       # @param cancelled [#call] true once the user stopped the turn: the
       #   command is killed (or not started) and its output so far returned
-      def self.call(command, cwd: nil, cancelled: -> { false })
+      # @param env [Hash, nil] added to the command's environment
+      def self.call(command, cwd: nil, cancelled: -> { false }, env: nil)
         return NOT_RUN_ON_STOP if cancelled.call
 
         command = command.strip
@@ -33,7 +34,8 @@ module Samagotchi
         return "Error: cwd not found: #{resolved_cwd}" unless resolved_cwd
 
         timeout_sec = timeout_seconds
-        stdout, stderr, status = run_command(command, timeout_sec: timeout_sec, cwd: resolved_cwd, cancelled: cancelled)
+        stdout, stderr, status = run_command(command, timeout_sec: timeout_sec, cwd: resolved_cwd, cancelled: cancelled,
+                                                      env: env)
 
         stdout_block = output_block("stdout", stdout)
         stderr_block = output_block("stderr", stderr)
@@ -66,7 +68,7 @@ module Samagotchi
       end
       private_class_method :stopped_result
 
-      def self.run_command(command, timeout_sec:, cwd:, cancelled: -> { false })
+      def self.run_command(command, timeout_sec:, cwd:, cancelled: -> { false }, env: nil)
         stdout_text = ""
         stderr_text = ""
         status = nil
@@ -75,7 +77,7 @@ module Samagotchi
         started = monotonic_time
         deadline = started + timeout_sec
 
-        Open3.popen3(command, chdir: cwd, pgroup: true) do |stdin, stdout, stderr, wait_thr|
+        Open3.popen3(env || {}, command, chdir: cwd, pgroup: true) do |stdin, stdout, stderr, wait_thr|
           stdin.close
           stdout_reader = reader_thread_for(stdout)
           stderr_reader = reader_thread_for(stderr)
@@ -173,11 +175,9 @@ module Samagotchi
       end
       private_class_method :monotonic_time
 
+      # execute.timeout_sec (SAMAGOTCHI_EXECUTE_TIMEOUT_SEC); 0 or less = the default.
       def self.timeout_seconds
-        value = Integer(ENV["SAMAGOTCHI_EXECUTE_TIMEOUT_SEC"].to_s, exception: false)
-        return TIMEOUT_SEC if value.nil? || value <= 0
-
-        value
+        OutputGuardrails.config_positive_int("execute.timeout_sec", TIMEOUT_SEC)
       end
       private_class_method :timeout_seconds
 

data/lib/samagotchi/tools/task_create.rb

@@ -9,8 +9,9 @@ module Samagotchi
 
       def self.name = NAME
 
-      def self.call(command, cwd: nil, env: nil)
-        record, error = TaskRuntime.create_task(command, cwd: cwd, env: env)
+      # @param marker_env [Hash] set after the model's env (Builtins.parent_env)
+      def self.call(command, cwd: nil, env: nil, marker_env: {})
+        record, error = TaskRuntime.create_task(command, cwd: cwd, env: env, marker_env: marker_env)
         return error if error
 
         [

data/lib/samagotchi/tools/task_runtime.rb

@@ -19,10 +19,13 @@ module Samagotchi
       METADATA_VERSION = 1
       OUTPUT_TAIL_READ_BYTES = 16 * 1024
       SANITIZED_ENV_KEYS = %w[RUBYOPT RUBYLIB BUNDLE_GEMFILE BUNDLE_BIN_PATH BUNDLER_VERSION].freeze
+      # Set by chi (Builtins.parent_env); the model's env can't change it.
+      MARKER_ENV_KEYS = %w[SAMAGOTCHI_PARENT_SESSION].freeze
 
       module_function
 
-      def create_task(command, cwd: nil, env: nil)
+      # @param marker_env [Hash] chi's own variables, set over the model's +env+
+      def create_task(command, cwd: nil, env: nil, marker_env: {})
         normalized_command = command.to_s.strip
         return [nil, "Error: command is required"] if normalized_command.empty?
 
@@ -32,6 +35,8 @@ module Samagotchi
         spawn_env, env_error = spawn_env_for(env)
         return [nil, env_error] if env_error
 
+        spawn_env = spawn_env.merge(marker_env || {})
+
         task_id = generate_task_id
         task_dir = task_dir_for(task_id)
         output_path = File.join(task_dir, OUTPUT_FILENAME)
@@ -258,7 +263,7 @@ module Samagotchi
         overrides.each do |key, value|
           return [nil, "Error: env keys and values must be strings"] unless key.is_a?(String) && value.is_a?(String)
           return [nil, "Error: env keys and values cannot contain NUL bytes"] if key.include?("\0") || value.include?("\0")
-          return [nil, "Error: env key is reserved: #{key}"] if SANITIZED_ENV_KEYS.include?(key)
+          return [nil, "Error: env key is reserved: #{key}"] if SANITIZED_ENV_KEYS.include?(key) || MARKER_ENV_KEYS.include?(key)
 
           normalized[key] = value
         end

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.12.0"
+  VERSION = "0.13.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end

data/lib/samagotchi/web/app.rb

@@ -539,11 +539,12 @@ module Samagotchi
         last_event_seq = snapshot ? snapshot["event_seq"] : bridge_event_seq(id)
         current_turn = turn_snapshot && turn_snapshot["current_turn"]
         owner = session_owner(id)
-        # The file's question only with a live owner: one a dead worker
-        # saved can't be answered (its turn is gone).
+        # The file's question only while a worker owns the session: one a
+        # dead worker saved can't be answered (its turn is gone), nor a chi
+        # REPL's (it shares nothing with the web).
         pending = if turn_snapshot
                     current_turn && current_turn["pending_question"]
-                  elsif owner
+                  elsif owner&.worker?
                     session.pending_question
                   end
         # A /model in the worker changes it before the file catches up.

data/lib/samagotchi/web/message_parts.rb

@@ -46,7 +46,8 @@ module Samagotchi
 
       QWEN_THINK = %r{<think>(.*?)</think>}m
       QWEN_OPEN_THINK = %r{\A(.*?)</think>}m # the template opened the block
-      GEMMA_THOUGHT = /<\|channel>thought(.*?)(?:<channel\|>|\z)/m
+      GEMMA_THOUGHT = Regexp.new("#{Regexp.escape(ModelProfile::GEMMA_THOUGHT_CHANNEL_OPEN)}(.*?)" \
+                                 "(?:#{Regexp.escape(ModelProfile::GEMMA_THOUGHT_CHANNEL_CLOSE)}|\\z)", Regexp::MULTILINE)
 
       CallRef = Struct.new(:name, :arguments)
 

data/lib/samagotchi/web/server.rb

@@ -16,6 +16,7 @@ require_relative "../config"
 require_relative "../project_scope"
 require_relative "../log"
 require_relative "../version"
+require_relative "../cli/exit"
 
 module Samagotchi
   module Web
@@ -99,7 +100,7 @@ module Samagotchi
         # Ctrl-C: the server has stopped (start's ensure); one line, and the
         # status a shell gives a command it interrupted.
         puts "#{"\n" if $stdout.tty?}Chi Web stopped."
-        130
+        CLI::Exit::INTERRUPTED
       end
 
       # @param hub [SessionHub, nil] the session projection the page streams

data/lib/samagotchi/web/session_summary.rb

@@ -61,22 +61,14 @@ module Samagotchi
           bridge_up: up,
           # For the tab's notifications (notify.js): an open question, the
           # running turn's open card with actions, and how the last turn
-          # ended. A question saved by a worker that died is not open.
-          pending_question: owner ? pending_question_for(session) : nil,
+          # ended. A question saved by a worker that died is not open, nor a
+          # chi REPL's (SessionManager.worker_live?'s rule: only a worker shares it).
+          pending_question: session.waiting_question(live: !!owner&.worker?),
           pending_card: up ? Bridge::PendingCard.read(session_dir) : nil,
           last_turn: session.last_turn
         }
       end
 
-      # The open question as {id:, kind:} ("approval" for a guardrail's,
-      # else "question"); nil when there is none. The text stays out.
-      def pending_question_for(session)
-        pending = session.pending_question
-        return nil unless pending.is_a?(Hash) && pending[:id]
-
-        { id: pending[:id], kind: pending[:kind].to_s == "approval" ? "approval" : "question" }
-      end
-
       # status is turn state (idle/running). The live worker's snapshot is the
       # truth; on disk, a "running" with no live owner was left by a worker
       # that died mid-turn.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: samagotchi
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Dmitry Dedov
@@ -136,7 +136,9 @@ files:
 - docs/plugins.md
 - docs/releasing.md
 - docs/sessions.md
+- docs/sub-agent.md
 - lib/samagotchi.rb
+- lib/samagotchi/answer_command.rb
 - lib/samagotchi/answer_display.rb
 - lib/samagotchi/archive_store.rb
 - lib/samagotchi/atomic_file.rb
@@ -188,7 +190,9 @@ files:
 - lib/samagotchi/bundles/system/self_map.md
 - lib/samagotchi/cancellation_controller.rb
 - lib/samagotchi/cli/command.rb
+- lib/samagotchi/cli/exit.rb
 - lib/samagotchi/cli/flags.rb
+- lib/samagotchi/cli/parent_wait.rb
 - lib/samagotchi/client.rb
 - lib/samagotchi/commands/registry.rb
 - lib/samagotchi/config.rb
@@ -224,6 +228,7 @@ files:
 - lib/samagotchi/guardrails/gate.rb
 - lib/samagotchi/guardrails/load_failures.rb
 - lib/samagotchi/guardrails/model_size.rb
+- lib/samagotchi/guardrails/parent_approvals.rb
 - lib/samagotchi/guardrails/protected_paths.rb
 - lib/samagotchi/guardrails/rules.rb
 - lib/samagotchi/guardrails/scratch_writes.rb
@@ -286,6 +291,7 @@ files:
 - lib/samagotchi/note_command.rb
 - lib/samagotchi/output_formatter.rb
 - lib/samagotchi/owner_lock.rb
+- lib/samagotchi/parent_report.rb
 - lib/samagotchi/paths.rb
 - lib/samagotchi/pending_input_queue.rb
 - lib/samagotchi/plugin/api.rb