samagotchi 0.85.0 → 0.87.0

data/docs/sub-agent.md

@@ -59,7 +59,7 @@ Exit codes, both commands:
 | 0 | `not_continued` | (`chi answer`) a Stop answered the step-limit question; the turn's work so far stays |
 | 3 | `question` | chi waits for an answer: `question`, `answer_with` |
 | 4 | `running` | `--timeout` passed; the turn goes on, wait again |
-| 1 | `failed`, `canceled`, `limit`, `removed`, `no_answer`, `error`, `worker_gone`, `stopped` | `detail` says what happened (`limit`: the turn ran out of steps and nobody can be asked, e.g. an older worker; `chi send ID -m '/continue yes'` continues it; `removed`: the `--queue` message waited for was taken back before it ran, no turn ran for it). `failed` adds `error_kind` (the provider error's kind: `credits`, `credits_held`, `rate_limited`, `server`, `auth`, `connection`, …) and `retryable` when known; `canceled` adds `cancel_reason` (`user`: a Stop in the web; `session_stopped`: a session stop, `chi sessions stop` or the web's; `hook`; `ctrl_c`; `manual`) and `stopped_by` (the hook that stopped it, e.g. `loop-guard`) when known |
+| 1 | `failed`, `canceled`, `limit`, `removed`, `no_answer`, `error`, `worker_gone`, `stopped` | `detail` says what happened (`limit`: the turn ran out of steps and nobody can be asked, e.g. an older worker; `chi send ID -m '/continue yes'` continues it, except under `guardrails.parent_answers: hard`, where a parent's `/continue yes` is refused as its `chi answer --option Continue` is; `removed`: the `--queue` message waited for was taken back before it ran, no turn ran for it). `failed` adds `error_kind` (the provider error's kind: `credits`, `credits_held`, `rate_limited`, `server`, `auth`, `connection`, …) and `retryable` when known; `canceled` adds `cancel_reason` (`user`: a Stop in the web; `session_stopped`: a session stop, `chi sessions stop` or the web's; `worker_stopped`: the `--queue` turn waited for died with its worker (detail "its worker exited mid-turn"), settled by the next one; `hook`; `ctrl_c`; `manual`) and `stopped_by` (the hook that stopped it, e.g. `loop-guard`) when known |
 | 2 | (no JSON) | usage error, or an option the question doesn't offer |
 | 130 | `running` | Ctrl-C; the turn goes on |
 
@@ -98,10 +98,12 @@ question and starts a new turn. It can't be dismissed.
 
 A parent may Continue by default: Continue grants no permission (every tool
 call still meets the guardrails), it only spends time and tokens. With
-`turn.parent_continue: false` in chi's config.yml (config.yml only, no
-environment variable) a parent may only Stop: `chi answer` and the worker
-refuse a Continue (exit 1, `a parent agent may only stop this turn here`), and
-the user continues it from the web or the terminal.
+`guardrails.parent_answers: hard` in chi's config.yml (config.yml only, no
+environment variable; a session's own `parent_answers` may tighten it, see
+[Guardrails](guardrails.md#a-sessions-own-level)) a parent may only Stop: `chi answer` and the worker
+refuse a Continue (exit 1, `a parent agent may only stop this turn here`), the
+question block's command is the Stop, and the user continues it from the web or
+the terminal. See [Guardrails](guardrails.md#answers-from-a-parent-agent).
 
 A chi parent's `delegate_result` gets a child's step-limit question back as a
 `question` with these commands, for its model to decide: continue it (the
@@ -122,23 +124,27 @@ sees only how each was answered. See
 parents (Claude Code, Codex, a script), and for a chi parent that can't host
 the relay (a `--no-shared` REPL, `--non-interactive`).
 
-An approval is a guardrail rule with `verdict: ask`: its user said "ask me". So
-a parent may deny it (`--option Deny --text "why"`, `--text` alone, or
-`--dismiss`) but not allow it: `chi answer` refuses an Allow with exit 1 and
-`allowing a tool call is up to the user: deny it (--option Deny --text WHY),
-and tell your user`. For an approval, the question block and `answer_with` give
-the deny command, not `--option N` or `chi --attach`. The block also offers to
-leave it open: tell your user it waits in chi web (the bell and badge show
-it there), and `chi send --wait --format json --turn <turn_id> ID` waits until
-they answer it. With
-`guardrails.parent_approvals: once` in chi's config.yml (it has no environment
-variable), "Allow once" goes through; the wider scopes never do,
-and neither does any allow on chi's own config, hooks or guardrail rules. See
-[Guardrails](guardrails.md#approvals-from-a-parent-agent).
+An approval is a guardrail rule with `verdict: ask`: its user said "ask me". A
+parent may always deny it (`--option Deny --text "why"`, `--text` alone, or
+`--dismiss`). By default (`guardrails.parent_answers: soft` in chi's
+config.yml, which has no environment variable, unless the session's own
+`parent_answers` is stricter) it may also give "Allow once";
+the wider scopes never go, and neither does any allow on chi's own config,
+hooks or guardrail rules: `chi answer` refuses those with exit 1 and a line
+like `only Allow once (guardrails.parent_answers: soft) can be given here: deny
+it (--option Deny --text WHY), and tell your user`. With `standard` or `hard`
+no allow goes (`allowing a tool call is up to the user: …`). The question
+block lists what the parent may give: the Allow once command when it may, and
+the deny command (`answer_with` is the deny), never `chi --attach`. The block
+also offers to leave it open: tell your user it waits in chi web (the bell and
+badge show it there), and `chi send --wait --format json --turn <turn_id> ID`
+waits until they answer it. A plugin's question names the options a parent may
+pick when the strategy leaves some out (`allowed_options` in the JSON). See
+[Guardrails](guardrails.md#answers-from-a-parent-agent).
 
 Start a child in the folder it should change (`chi send --new --dir PATH`):
 writes and mutating git outside its own repo ask (`write-outside-repo`,
-`git-outside-repo`), which a parent can only deny.
+`git-outside-repo`), which a parent can at most allow once per call.
 
 An answer typed into `chi --attach` or the REPL counts as a parent's too when
 stdin isn't a terminal or an agent marker (`CLAUDECODE`, `AI_AGENT`,
@@ -208,12 +214,20 @@ Start a task: `chi send --new --wait --format json --timeout 500 -m "<task>"`
   JSON. If you won't answer, add `--dismiss` instead: chi does nothing it asked
   about, finishes with what it found, and the reply comes back (exit 0).
 - `question.kind: approval`: chi wants to run something its user's guardrails
-  flagged, and allowing it is up to your user. Deny it (the `answer_with`
-  command: `--option Deny --text "why"`), and tell your user what it wanted to
-  run and why. Or leave it open: tell your user it waits in chi web (the
-  session's short id), then `chi send --wait --format json --timeout 500 --turn <turn_id> <session_id>`
-  waits until they answer it there. Never allow it yourself, through
-  `chi answer`, a piped `chi --attach` or chi's web API.
+  flagged. What you may give follows chi's `guardrails.parent_answers` (or the
+  session's own, stricter `parent_answers`), and the
+  question says it: when its `allowed_options` (and the text block's `allow:`
+  line) list "Allow once" (`soft`, the default), you may allow that one call if
+  your task clearly needs it; never a wider scope (this session, a repo, a
+  rule), and never a call on chi's own config, which lists only Deny. Otherwise
+  (`standard`, `hard`, or anything wider) allowing it is up to your user: deny
+  it (the `answer_with` command: `--option Deny --text "why"`), and tell your
+  user what it wanted to run and why. Or leave it open: tell your user it waits
+  in chi web (the session's short id), then
+  `chi send --wait --format json --timeout 500 --turn <turn_id> <session_id>`
+  waits until they answer it there. Never give an answer the question doesn't
+  offer you by another route (a piped `chi --attach`, `chi send -m '/continue
+  yes'`, chi's web API).
 - `status: running` (exit 4): still working. Wait for that same turn again:
   `chi send --wait --format json --timeout 500 --turn <turn_id> <session_id>`.
 - `question.kind: continue`: chi ran out of steps before it answered. If it is

data/docs/testing.md

@@ -47,7 +47,8 @@ Where a composer line goes is decided twice, in Ruby (`ComposerRoute`, both term
 (`composer.js#routeComposerLine`). `spec/fixtures/composer_routes.json` holds the cases both answer: rspec
 (`spec/composer_route_spec.rb`) and `npm test` (`spec/web/public/composer.test.js`) run every row. A change to
 either router adds its row there; a row where a UI differs on purpose (or a found divergence) carries a `web` or
-`repl` override and a `note`.
+`repl` override and a `note`. The Ruby side runs each row with every core command (a new one fails its
+`CORE_ROUTES` check until listed there); a row's names that core lacks stand for plugin commands.
 
 A spec that waits for something uses `wait_until(timeout:)`, or `wait_until!(what, timeout:)` where no check
 follows (stubs, helper threads: it raises "timed out after N s waiting for <what>") — never a loop with no deadline.
@@ -77,7 +78,11 @@ The kit's own specs, in `spec/samagotchi/testing/`, keep it and the bundles hone
   `Testing::Sessions` has `Plugin::Sessions`' methods and parameters, and each `ctx` helper lands in its recorder. A
   member added to the Host fails it until the kit has it.
 - `spec/samagotchi/testing/shipped_bundles_spec.rb`: each shipped bundle with a plugin or hooks registers the same
-  commands, tools, hooks, inits, toolkits and sources loaded by the kit as installed and loaded by chi.
+  commands, tools, hooks, inits, toolkits and sources loaded by the kit as installed and loaded by chi
+  (`Testing::Install`).
+- `spec/samagotchi/bundle_command/check_spec.rb`: `chi bundle check` passes every shipped bundle with no errors (one
+  example per bundle), so a shipped bundle that wouldn't install or load cleanly for a user fails here too. Run it
+  by hand on one with `ruby -Ilib bin/chi bundle check lib/samagotchi/bundles/NAME`.
 - `spec/samagotchi/testing/boundary_spec.rb`, the boundary lint: each bundle's Ruby (plugin, hooks, scripts, specs)
   reaches chi only through `Samagotchi::Testing::Boundary::ALLOWED` (the "Stable for bundles" list) and that
   bundle's `Boundary::EXCEPTIONS` entry, each with why. A new internal reference fails it, and so does an exception

data/lib/samagotchi/answer_command.rb

@@ -6,8 +6,7 @@ require_relative "session_manager"
 require_relative "bridge_client"
 require_relative "reply_wait"
 require_relative "parent_report"
-require_relative "guardrails/parent_approvals"
-require_relative "guardrails/parent_continue"
+require_relative "guardrails/parent_policy"
 require_relative "cli/command"
 require_relative "cli/flags"
 require_relative "cli/parent_wait"
@@ -19,10 +18,10 @@ module Samagotchi
   # how a parent agent running chi as a sub-agent answers; the web and
   # chi --attach answer the same question. See docs/sub-agent.md.
   #
-  # An approval is the user's to allow: a parent may deny it, and allow it
-  # only "once" when guardrails.parent_approvals (config.yml) says so. It is
-  # checked here and again by the worker, which sees the answer marked as
-  # chi answer's. That guards an honest but eager parent, not a boundary:
+  # What a parent may pick is Guardrails::ParentPolicy's: by each option's
+  # effect and this process's config.yml. It is checked here and again by
+  # the worker, which sees the answer marked as chi answer's. That guards
+  # an honest but eager parent, not a boundary:
   # the Bridge and the localhost web take answers from any local process.
   class AnswerCommand
     include CLI::Command
@@ -46,9 +45,11 @@ module Samagotchi
                         about and finishes its reply
         --timeout S     give up waiting after S seconds (exit 4)
         --format json   one JSON object on stdout (see chi send --help)
-        An approval (a guardrail's ask) can be denied here: deny it, and
-        tell your user; allowing it is the user's. With
-        guardrails.parent_approvals: once, "Allow once" is let through.
+        What a parent may pick follows guardrails.parent_answers in
+        chi's config.yml: soft (the default) lets "Allow once" and
+        Continue through, standard Continue but no allow, hard only a
+        deny, a Stop or a plain answer. A wider allow, and any allow on
+        chi's own config, is the user's: deny it, and tell your user.
         A step-limit question (kind continue): --option Continue [--text
         STEER] (the text joins the continued turn as a steer), or
         --option Stop [--text WHY] (exit 0, status not_continued); it
@@ -121,7 +122,7 @@ module Samagotchi
         return failure(not_dismissable(pending)) if options[:dismiss] && ParentReport.continue?(pending)
 
         selected = selection(pending, options) or return @selection_status
-        refusal = approval_refusal(pending, selected, id) || continue_refusal(pending, selected)
+        refusal = parent_refusal(pending, selected, session)
         return failure(refusal) if refusal
 
         posted = post(id, qid, selected, options)
@@ -158,21 +159,16 @@ module Samagotchi
       labels.uniq
     end
 
-    # Why a parent may not give this answer to an approval, or nil
-    # (Guardrails::ParentApprovals, with this process's config.yml). A
-    # Deny, text alone or a dismissal always passes: each one denies. The
-    # worker checks it again with its own config.
-    def approval_refusal(pending, selected, _id)
+    # Why a parent may not give this answer, or nil (Guardrails::ParentPolicy,
+    # with this process's config.yml tightened by the session file's own
+    # parent_answers, and the question's own tags). A deny, text alone or a
+    # dismissal always passes. The worker checks it again with its own.
+    def parent_refusal(pending, selected, session)
       offered = Array(pending.options).map(&:to_s)
       indices = selected.map { |label| offered.index(label) }
-      reason = Guardrails::ParentApprovals.refusal(pending, indices, setting: Guardrails::ParentApprovals.setting)
-      reason && Guardrails::ParentApprovals.message(reason)
-    end
-
-    # Why a parent may not answer Continue (turn.parent_continue: false in
-    # this process's config.yml), or nil; the worker checks it again.
-    def continue_refusal(pending, selected)
-      Guardrails::ParentContinue.refusal(pending, selected) && Guardrails::ParentContinue.message
+      strategy = Guardrails::ParentPolicy.for_session(session)
+      reason = Guardrails::ParentPolicy.refusal(pending, indices, strategy: strategy)
+      reason && Guardrails::ParentPolicy.message(reason, pending: pending, strategy: strategy)
     end
 
     # A step-limit question can't be left unanswered: the turn waits on it.
@@ -206,8 +202,8 @@ module Samagotchi
 
         not_open(qid)
       when 400 then usage_failure(reply.json&.dig("detail") || "the worker refused the answer")
-      # The worker's own guardrails.parent_approvals refused the allow.
-      when 403 then failure(reply.json&.dig("detail") || "the worker refused the allow: deny it, and tell your user")
+      # The worker's own strategy refused the option (ParentPolicy).
+      when 403 then failure(reply.json&.dig("detail") || "the worker refused that option: deny it, and tell your user")
       when 408 then failure("the worker did not take the answer in time; the question is still open: try again")
       when 404
         return failure(worker_gone(id)) if reply.json&.dig("error") == "unknown_session"

data/lib/samagotchi/bridge/client_event.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "../context_usage"
+
+module Samagotchi
+  class Bridge
+    # What an SSE client gets for an engine event (SSEWriter#write_event, live
+    # and replayed alike). A :generation_chunk carries chi's own counts
+    # (`counts`, ContextUsage.normalize of the provider's payload) instead of
+    # the provider's raw `payload`, and no raw `content` (the chat loop's is
+    # reasoning + content again, the native loop's the raw stream with its
+    # tool-call bytes and thought tags): clients read `text`, `thinking`,
+    # `tool_call` and `counts`, never a provider's payload shape. `?raw=1` on
+    # the worker's stream skips this (debugging).
+    #
+    # Pure: the event is the one hash SessionObserver hands every observer
+    # (the ring, TurnAccumulator, the other writers, SessionMetrics, hooks),
+    # so it is never mutated; keys are added or removed on a copy, and any
+    # key not named here (event_seq included) passes through.
+    module ClientEvent
+      # The counts a client gets: ctx_pct stays out, as normalize computes it
+      # without the session's LLM context budget (the client counts
+      # total_tokens against the window or budget itself).
+      COUNT_KEYS = %i[prompt_tokens completion_tokens total_tokens context_window_tokens].freeze
+
+      module_function
+
+      # @param event [Hash] the engine's event (symbol keys; its payload has
+      #   string keys)
+      # @return [Hash] the event as clients get it: a copy for a
+      #   :generation_chunk, the same object for every other event
+      def project(event)
+        return event unless event.is_a?(Hash) && event[:type].to_s == "generation_chunk"
+
+        projected = event.except(:payload, :content)
+        found = counts(event[:payload])
+        found ? projected.merge(counts: found) : projected
+      end
+
+      # The payload's normalized counts, nil keys left out; nil when the
+      # payload reports none (a missing key means unknown, never 0).
+      # @return [Hash, nil]
+      def counts(payload)
+        usage = ContextUsage.normalize(payload)
+        found = usage&.slice(*COUNT_KEYS)&.compact
+        found.nil? || found.empty? ? nil : found
+      end
+    end
+  end
+end

data/lib/samagotchi/bridge/sse_writer.rb

@@ -2,6 +2,7 @@
 
 require "json"
 
+require_relative "client_event"
 require_relative "event_id"
 
 module Samagotchi
@@ -58,10 +59,12 @@ module Samagotchi
       # @param bridge [Samagotchi::Bridge, nil] for stop signalling
       # @param max_queue [Integer] bounded-queue capacity
       # @param heartbeat_interval [Float] idle-seconds between `: ping` frames
+      # @param raw [Boolean] write events as the engine emitted them, not as
+      #   clients get them (ClientEvent): `?raw=1`, for debugging
       def initialize(engine:, ring:, session_id:, last_event_id: nil, epoch: nil,
                      frame_provider: nil, join_with_snapshot: false, bridge: nil,
                      max_queue: DEFAULT_MAX_QUEUE,
-                     heartbeat_interval: DEFAULT_HEARTBEAT_INTERVAL)
+                     heartbeat_interval: DEFAULT_HEARTBEAT_INTERVAL, raw: false)
         @engine = engine
         @ring = ring
         @session_id = session_id
@@ -72,6 +75,7 @@ module Samagotchi
         @bridge = bridge
         @max_queue = max_queue
         @heartbeat_interval = heartbeat_interval
+        @raw = raw
 
         @queue = BoundedQueue.new(capacity: @max_queue)
         cursor_seq, cursor_epoch = EventId.parse(@last_event_id)
@@ -203,7 +207,7 @@ module Samagotchi
         seq = event[:event_seq]
         return if seq && seq <= @high_water
 
-        write_frame(io, seq: seq, data: event)
+        write_frame(io, seq: seq, data: @raw ? event : ClientEvent.project(event))
         @high_water = seq if seq && seq > @high_water
       end
 

data/lib/samagotchi/bridge.rb

@@ -19,7 +19,6 @@ require_relative "bridge/sse_writer"
 require_relative "bridge/turn_accumulator"
 require_relative "session"
 require_relative "engine"
-require_relative "guardrails/parent_approvals"
 require_relative "session_commands"
 require_relative "queued_command"
 require_relative "steer"
@@ -309,10 +308,11 @@ module Samagotchi
     # @param after_file [String, nil] the input file it came in (its
     #   basename): it runs once that file is taken (Worker#on_command)
     # @return [String] its command_id
-    def queue_command(line, client_id: nil, card: false, after_file: nil)
+    def queue_command(line, client_id: nil, card: false, after_file: nil, enqueued_id: nil)
       # A card's action (the step-limit question's answer): the UIs leave
-      # its line out.
-      command = QueuedCommand.mint(line.to_s.strip, client_id: client_id, card: card)
+      # its line out. +enqueued_id+: a file-delivered command's input, whose
+      # sender's wait its command_ran settles.
+      command = QueuedCommand.mint(line.to_s.strip, client_id: client_id, card: card).with(enqueued_id: enqueued_id)
       @engine.synchronize_events { queue_command_locked(command, after_file: after_file) }
       command.command_id
     end
@@ -420,7 +420,7 @@ module Samagotchi
           cursor = reconnect_cursor(headers, request[:query])
           Log.debug(:bridge, "stream", method: method, path: request[:path], client_id: stream_client_id(request[:query]))
           serve_sse(io, route.last, last_event_id: cursor, snapshot: snapshot_requested?(request[:query]),
-                                    client_id: stream_client_id(request[:query]))
+                                    client_id: stream_client_id(request[:query]), raw: raw_requested?(request[:query]))
           break # SSE owns the connection until the client disconnects.
         else
           payload, status, body = dispatch(route.first, route.last, request[:body], request[:query])
@@ -447,7 +447,7 @@ module Samagotchi
 
     # Serve an SSE stream. Owns the connection until the client disconnects.
     # The connection thread IS the writer thread: serve! blocks until then.
-    def serve_sse(io, session_id, last_event_id:, snapshot: false, client_id: nil)
+    def serve_sse(io, session_id, last_event_id:, snapshot: false, client_id: nil, raw: false)
       unless own_session?(session_id)
         write_json(io, 404, {}, { error: "unknown_session" })
         return
@@ -463,7 +463,8 @@ module Samagotchi
         # A reconnect (with a cursor) replays; only a fresh join snapshots.
         join_with_snapshot: snapshot && last_event_id.nil?,
         bridge: self,
-        heartbeat_interval: @heartbeat_interval
+        heartbeat_interval: @heartbeat_interval,
+        raw: raw
       )
       @mutex.synchronize do
         @open_streams += 1
@@ -649,7 +650,7 @@ module Samagotchi
       selected = fetched(parsed, "selected")
       freeform = fetched(parsed, "freeform")
       # chi answer's marker: a parent agent, held to this worker's
-      # guardrails.parent_approvals (QuestionDesk::Refused). Not a boundary:
+      # Guardrails::ParentPolicy (QuestionDesk::Refused). Not a boundary:
       # any local process may post here, with or without it.
       client_id = fetched(parsed, "client_id")
       if qid.to_s.strip.empty?
@@ -667,9 +668,8 @@ module Samagotchi
         # Another client answered first, or the question was cancelled.
         [{}, 409, { error: "question_not_pending", detail: e.message }]
       rescue QuestionDesk::Refused => e
-        Log.info(:bridge, "parent_approval_refused", sid: session_id, id: qid, reason: e.reason)
-        [{}, 403, { error: e.reason == :stop_only ? "parent_continue_refused" : "parent_approval_refused",
-                    detail: Guardrails::ParentApprovals.message(e.reason) }]
+        Log.info(:bridge, "parent_answer_refused", sid: session_id, id: qid, reason: e.reason)
+        [{}, 403, { error: "parent_answer_refused", reason: e.reason.to_s, detail: e.detail }]
       rescue ArgumentError => e
         [{}, 400, { error: "invalid_answer", detail: e.message }]
       end
@@ -1180,6 +1180,17 @@ module Samagotchi
       false
     end
 
+    # `?raw=1`: events as the engine emitted them (a chunk's provider
+    # payload), not as clients get them (ClientEvent). For debugging on the
+    # worker's port: chi web never passes it on.
+    def raw_requested?(query)
+      return false unless query
+
+      URI.decode_www_form(query).to_h["raw"].to_s == "1"
+    rescue StandardError
+      false
+    end
+
     # `?client_id=`: whose stream it is (see #open_streams_except).
     def stream_client_id(query)
       return nil unless query

data/lib/samagotchi/bridge_client.rb

@@ -114,8 +114,8 @@ module Samagotchi
     # POST /session/:id/answer. 200 = recorded, 409 = another client answered
     # first (or the question is gone), 400 = invalid selection, 408
     # deadline_passed = read too late and dropped (see DEADLINE_SHARE), 403
-    # parent_approval_refused = a parent's allow (client_id cli:answer)
-    # beyond the worker's guardrails.parent_approvals.
+    # parent_answer_refused (with its reason) = a parent's pick (client_id
+    # cli:answer) beyond the worker's guardrails.parent_answers.
     # @param client_id [String, nil] who answers (chi answer marks its own)
     # @return [Response]
     def answer(id:, selected:, freeform: nil, client_id: nil)