rubino-agent 0.3.0

data/lib/rubino/tools/answer_child_tool.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Tools
+    # answer_child — the MODEL-callable answer to a child's ask_parent (S4). The
+    # agent-parent counterpart of the human `/reply <id> <answer>`: when a
+    # subagent calls ask_parent and it is OWNED by an agent (not the human), the
+    # question lands on this parent's steer_queue as a [subagent-question] note;
+    # the parent model reads it at its next turn and answers it with this tool.
+    #
+    # SCOPED AT CALL (like steer/probe, the S1 correction): registered for ALL
+    # agents and AUTHORIZED by OWNERSHIP at call time. The caller is the
+    # thread-local Rubino.current_subagent_id (nil ⇒ the human / top-level agent).
+    # The target must be the caller's OWN DIRECT child (BackgroundTasks.owned_by?)
+    # AND it must actually be waiting on an ask (it has an ask_gate). NOT on any
+    # strip list.
+    #
+    # Mechanism reuse: it wraps BackgroundTasks#deliver_answer verbatim — the SAME
+    # ONE answer wire the human /reply path uses (decide the gate + push the
+    # [parent answer] steer note + clear the blocked state). No new transport.
+    #
+    # An agent-parent that CANNOT answer from its own context does NOT use this
+    # tool: it escalates by calling its OWN ask_parent (recursion up the tree).
+    class AnswerChildTool < Base
+      def name
+        "answer_child"
+      end
+
+      # Gated by the same `tools.task` delegation key — answering a child is
+      # meaningless without the delegation substrate. Disabling delegation
+      # disables answer_child too.
+      def config_key
+        "task"
+      end
+
+      def description
+        "Answer one of YOUR OWN subagents that asked you a question via " \
+          "ask_parent (you will have received it as a [subagent-question] note). " \
+          "The answer is delivered into that child's context: it unblocks a child " \
+          "that paused for it and folds into a child that kept working. You can " \
+          "ONLY answer a subagent you started (your direct child) that is actually " \
+          "waiting on you. If you CANNOT answer from your own context, do NOT guess " \
+          "— escalate by calling ask_parent yourself."
+      end
+
+      def input_schema
+        {
+          type: "object",
+          properties: {
+            task_id: { type: "string", description: "The id (sa_…) of YOUR subagent that asked you." },
+            answer: { type: "string",
+                      description: "Your answer. Be specific and self-contained — it enters the child's context." }
+          },
+          required: %w[task_id answer]
+        }
+      end
+
+      # Answering a child is a low-risk, non-destructive hand-off (the child
+      # carries its own approval/risk gates for whatever it does with the answer).
+      def risk_level
+        :low
+      end
+
+      def call(arguments)
+        task_id = (arguments["task_id"] || arguments[:task_id]).to_s.strip
+        answer  = (arguments["answer"]  || arguments[:answer]).to_s.strip
+        return "Error: answer is required" if answer.empty?
+
+        caller_id = Rubino.current_subagent_id
+        registry  = BackgroundTasks.instance
+
+        # Ownership: only a DIRECT child of the caller may be answered.
+        return "Error: #{task_id} is not one of your subagents." unless registry.owned_by?(caller_id, task_id)
+
+        # It must actually be waiting on an ask (deliver_answer no-ops without a
+        # live ask_gate). Covers a missing/finished/not-blocked child uniformly.
+        return "#{task_id} is not waiting on you." unless registry.deliver_answer(task_id, answer)
+
+        "↳ answered #{task_id}: #{Rubino::Util::Output.elide(answer, 80)}\n✓ #{task_id} resumes at its next turn"
+      end
+    end
+  end
+end

data/lib/rubino/tools/ask_parent_tool.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Tools
+    # ask_parent — the child->parent escalation channel (the third mechanism of
+    # the parent<->subagent comm design). A subagent calls this when it hits a
+    # fork it cannot resolve from its sealed prompt ("sqlite or postgres?").
+    #
+    # Answerer is MIXED: the parent answers from its own context if it can, else
+    # it escalates to the HUMAN. This tool implements the wire; the escalation
+    # itself reuses Run::ApprovalGate verbatim (the SAME blocking cross-thread
+    # hand-off the Option-2 background-approval path already uses):
+    #
+    #   1. The tool finds the child\'s own BackgroundTasks entry (via the
+    #      thread-local Rubino.current_subagent_id set by TaskTool around the
+    #      child run). No entry ⇒ this run has no parent (top-level / foreground
+    #      sync) and the tool refuses gracefully — never hangs.
+    #   2. It registers a Run::ApprovalGate on the entry (BackgroundTasks#begin_ask),
+    #      flipping the entry to :blocked_on_human so the parent CLI surfaces the
+    #      ⛔ blocked banner + the persistent "N subagent waiting on you" marker,
+    #      and informs the parent loop by pushing a note onto the parent\'s
+    #      InputQueue (so the parent MODEL sees the question at its next turn and
+    #      MAY answer it — the "parent answers if it can" half; the parent\'s
+    #      answer routes back through the SAME gate via /reply or a parent path).
+    #   3. blocking:true  → the tool BLOCKS on gate.await(timeout: nil) — wait
+    #      INDEFINITELY, no auto-default (the owner constraint). The human answers
+    #      via /reply <id>, which decides the gate; the answer is the tool result
+    #      and enters the child\'s context as the tool message.
+    #      blocking:false → the tool returns IMMEDIATELY ("asked, keep working");
+    #      the answer is delivered later as a steer note on the child\'s queue
+    #      (Loop#inject_steered_input), so the child keeps making progress.
+    #
+    # SUSPEND/RESUME (the W1/#54 lesson): on the CLI a background subagent runs on
+    # its OWN dedicated Thread — NOT a pooled Puma/Solid-Queue worker. Parking
+    # that dedicated thread on the gate (blocking:true) therefore holds only the
+    # child\'s own thread, never a shared pool, so it cannot freeze the REPL the
+    # way a parked Puma worker froze the server (W1). This is exactly how the
+    # existing Option-2 approval handler parks the child thread today. A full
+    # persist-and-resume suspend (free the thread entirely, rehydrate on answer)
+    # is only required for the POOLED web path, which is OUT OF SCOPE here and
+    # tracked as a follow-up. A stop (/agents <id> --stop) cancels the gate so a
+    # blocking ask unwinds at once instead of waiting forever.
+    class AskParentTool < Base
+      # Sentinel head used when a non-blocking ask returns to the child: the
+      # child keeps working and the real answer arrives later as a steer note.
+      NONBLOCKING_ACK = "Question sent to your parent. Keep working with your best " + "judgement; the answer will be delivered to you as a note " + "at your next turn if/when it arrives."
+
+      # Fallback bound (seconds) for a blocking ask when no configuration is
+      # reachable (a bare tool in a unit test). The live value comes from
+      # tasks.ask_parent_timeout; this matches the approvals wait-timeout default.
+      DEFAULT_ASK_TIMEOUT = 900
+
+      def name
+        "ask_parent"
+      end
+
+      # Gated by the same `tools.task` delegation key — it is meaningless without
+      # the delegation substrate (BackgroundTasks/registry). Disabling delegation
+      # disables ask_parent too.
+      def config_key
+        "task"
+      end
+
+      def description
+        "Ask YOUR PARENT agent a question when you hit a decision you cannot " + "resolve from the task you were given (e.g. a missing preference, an " + "ambiguous requirement, sqlite-vs-postgres). Your parent answers from " + "its own context if it can, otherwise it asks the human. Use " + "blocking:true when you CANNOT proceed without the answer (you will " + "pause until it arrives); blocking:false (default) when you can keep " + "working and fold the answer in later. Only available to subagents."
+      end
+
+      def input_schema
+        {
+          type: "object",
+          properties: {
+            question: { type: "string", description: "The question for your parent. Be specific and self-contained." },
+            blocking: {
+              type: "boolean",
+              description: "true = pause until answered (you cannot proceed without it). " + "false (default) = keep working; the answer is delivered later as a note."
+            }
+          },
+          required: %w[question]
+        }
+      end
+
+      def risk_level
+        :low
+      end
+
+      def call(arguments)
+        question = (arguments["question"] || arguments[:question]).to_s.strip
+        blocking = blocking_arg(arguments)
+        return "Error: question is required" if question.empty?
+
+        id = Rubino.current_subagent_id
+        entry = id && BackgroundTasks.instance.find(id)
+        unless entry
+          return "Error: ask_parent is only available to a background subagent " + "(no parent to ask). Resolve this from your task instead."
+        end
+
+        escalate(entry, question, blocking)
+      rescue Rubino::Interrupted
+        # A /agents <id> --stop (or teardown) cancelled the gate while we were
+        # parked. Unwind cleanly: report it as denied/cancelled so the child can
+        # finish rather than hang.
+        BackgroundTasks.instance.end_ask(entry&.id) if defined?(entry) && entry
+        "Your parent question was cancelled (the run is being stopped)."
+      end
+
+      private
+
+      # blocking defaults to FALSE (the cheap, non-freezing default): the child
+      # keeps working and the answer is injected later. Only an explicit true
+      # opts into the indefinite blocking wait.
+      def blocking_arg(arguments)
+        raw = arguments.key?("blocking") ? arguments["blocking"] : arguments[:blocking]
+        [true, "true", 1, "1"].include?(raw)
+      end
+
+      def escalate(entry, question, blocking)
+        gate   = Run::ApprovalGate.new
+        ask_id = "ask_#{entry.id}"
+        gate.register(ask_id)
+        # Route by OWNER (S4): a child with an agent-parent blocks on that PARENT
+        # (:blocked_on_parent, answered by the parent model's `answer_child`); a
+        # human/top-level-owned child blocks on the HUMAN (:blocked_on_human,
+        # answered via /reply). begin_ask records the right status from the owner.
+        owner_id = entry.owner_subagent_id
+        BackgroundTasks.instance.begin_ask(
+          entry.id, gate: gate, ask_id: ask_id, question: question,
+                    blocking: blocking, owner_id: owner_id
+        )
+        if owner_id
+          notify_agent_parent(owner_id, entry, question)
+        else
+          surface_and_notify(entry, question)
+        end
+
+        if blocking
+          await_human(entry, gate, ask_id)
+        else
+          # Non-blocking: the child keeps working. The answer arrives later as a
+          # steer note via the gate-watcher the CLI installs at /reply time
+          # (BackgroundTasks#steer pushes onto the child\'s queue). We do NOT
+          # clear the ask state here — the entry stays :blocked_on_human on the
+          # card until the human answers, so a non-blocking ask is still visible
+          # and answerable; the child simply does not pause for it.
+          NONBLOCKING_ACK
+        end
+      end
+
+      # Parks the child\'s OWN thread on the gate, BOUNDED by
+      # tasks.ask_parent_timeout (S5a — default 900s). On EXPIRED (no answer
+      # within the bound) the child self-heals: it stops waiting and proceeds with
+      # its best judgement instead of hanging forever. The answer (from /reply or
+      # answer_child, both via gate.decide) returns as the tool result so it
+      # enters the child\'s context. A cancel (/agents <id> --stop or a
+      # stop-cascade from an ancestor) raises Interrupted, handled in #call.
+      def await_human(entry, gate, ask_id)
+        decision = gate.await(ask_id, timeout: ask_timeout)
+        answer   = decision.equal?(Run::ApprovalGate::EXPIRED) ? nil : decision.to_s
+        BackgroundTasks.instance.end_ask(entry.id)
+        if answer.nil? || answer.empty?
+          "Your parent did not provide an answer. Proceed with your best judgement."
+        else
+          "Your parent answered: #{answer}"
+        end
+      end
+
+      # The bounded wait for a blocking ask, from config (tasks.ask_parent_timeout)
+      # when wired, else the built-in default. Reuses the approval-gate timeout
+      # convention (a sane upper bound, never "forever") so an abandoned ask
+      # self-heals rather than parking the child\'s thread indefinitely.
+      def ask_timeout
+        cfg = Rubino.configuration if defined?(Rubino) && Rubino.respond_to?(:configuration)
+        val = cfg&.respond_to?(:tasks_ask_parent_timeout) ? cfg.tasks_ask_parent_timeout : nil
+        Integer(val)
+      rescue StandardError, TypeError, ArgumentError
+        DEFAULT_ASK_TIMEOUT
+      end
+
+      # Notifies the AGENT-parent (owner) of a child question by pushing the
+      # [subagent-question] note onto the OWNER\'s steer_queue — the same
+      # turn-boundary channel a steer rides — so the parent MODEL sees it at its
+      # next iteration and can answer with `answer_child` (or escalate up via its
+      # own ask_parent). No human surfacing here: a :blocked_on_parent ask is the
+      # agent-parent\'s job, not the human\'s. Best-effort.
+      def notify_agent_parent(owner_id, entry, question)
+        BackgroundTasks.instance.steer(owner_id, agent_parent_notice(entry, question))
+      rescue StandardError
+        nil
+      end
+
+      def agent_parent_notice(entry, question)
+        "[subagent-question] Your subagent #{entry.id} ('#{entry.subagent}') is asking you:\n" \
+          "#{question}\n" \
+          "Answer it with answer_child(task_id: \"#{entry.id}\", answer: \"…\") if you can. " \
+          "If you cannot answer from your own context, escalate by calling ask_parent yourself."
+      end
+
+      # Surfaces the blocked state on the parent CLI (a committed banner in
+      # scrollback + a card repaint so the persistent ⛔ marker shows) and pushes
+      # a note onto the PARENT\'s InputQueue so the parent MODEL learns of the
+      # question at its next turn and may answer it (answer_child). The sink is
+      # the one TaskTool captured on the PARENT thread at spawn time
+      # (entry.parent_sink) — NEVER the thread-local Rubino.background_sink,
+      # which on this (the child\'s) thread is the child\'s own steer_queue and
+      # would misroute the question back into the asking child (#195). Pushed as
+      # a NOTICE so it rides the parent\'s next real turn instead of firing a
+      # standalone synthetic user turn at the idle prompt (#13). DISPLAY/notify
+      # only — the authoritative answer delivery is the gate decision
+      # (/reply or answer_child).
+      def surface_and_notify(entry, question)
+        entry.parent_sink&.push_notice(parent_notice(entry, question))
+        parent_ui = Rubino.instance_variable_get(:@ui)
+        return unless parent_ui.is_a?(UI::CLI)
+
+        parent_ui.subagent_ask_banner(entry.id, entry.subagent, question) if parent_ui.respond_to?(:subagent_ask_banner)
+        parent_ui.set_subagent_cards if parent_ui.respond_to?(:set_subagent_cards)
+      rescue StandardError
+        nil
+      end
+
+      # The top-level agent has answer_child registered too — the notice must
+      # name the MODEL-callable tool, not the human-only /reply command the
+      # model cannot invoke (#195).
+      def parent_notice(entry, question)
+        "[subagent-question] Task #{entry.id} (subagent '#{entry.subagent}') is asking you:\n" \
+          "#{question}\n" \
+          "Answer it with answer_child(task_id: \"#{entry.id}\", answer: \"…\") if you can. " \
+          "If you cannot answer from your own context, tell the user — the human can also " \
+          "answer via /reply #{entry.id}."
+      end
+    end
+  end
+end

data/lib/rubino/tools/attach_file_tool.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Rubino
+  module Tools
+    # Hands a previously-written file to the surrounding UI as a downloadable
+    # artifact. The tool itself does not move bytes — it validates the path
+    # against the workspace and the file's existence, then surfaces a
+    # structured artifact payload that the agent loop turns into an
+    # ARTIFACT_CREATED event. Downstream consumers (the web UI's
+    # run job, the CLI) fetch the file separately via GET /v1/files.
+    #
+    # Why a dedicated tool rather than inferring artifacts from write/edit
+    # tool calls: the model writes lots of intermediate files (helper
+    # scripts, scratch JSON, downloaded fixtures) that should NOT show up
+    # as user-facing downloads. An explicit attach_file call makes that
+    # decision intentional and reviewable.
+    class AttachFileTool < Base
+      DEFAULT_CONTENT_TYPE = "application/octet-stream"
+
+      # Minimal extension → MIME map. Anything not listed falls back to
+      # application/octet-stream; the browser will then decide based on
+      # filename. Add entries here only when a real run needs a specific
+      # type signalled (e.g. inline PDF preview).
+      CONTENT_TYPES = {
+        "pdf" => "application/pdf",
+        "csv" => "text/csv",
+        "txt" => "text/plain",
+        "md" => "text/markdown",
+        "json" => "application/json",
+        "html" => "text/html",
+        "htm" => "text/html",
+        "xml" => "application/xml",
+        "png" => "image/png",
+        "jpg" => "image/jpeg",
+        "jpeg" => "image/jpeg",
+        "gif" => "image/gif",
+        "svg" => "image/svg+xml",
+        "zip" => "application/zip",
+        "tar" => "application/x-tar",
+        "gz" => "application/gzip",
+        "docx" => "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        "pptx" => "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+        "xlsx" => "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+      }.freeze
+
+      def name
+        "attach_file"
+      end
+
+      def description
+        "Attach a previously-written file to the current turn as a downloadable artifact " \
+          "for the user. Call this AFTER you have already created the file with write/edit/shell. " \
+          "Pass the absolute or workspace-relative path. The tool does not copy or move the file — " \
+          "it just registers it as a deliverable. Use for final user-facing outputs " \
+          "(PDF, CSV, ZIP, reports) and not for intermediate helper scripts."
+      end
+
+      def input_schema
+        {
+          type: "object",
+          properties: {
+            file_path: {
+              type: "string",
+              description: "Path to the file to attach. Must exist and live inside the workspace."
+            },
+            filename: {
+              type: "string",
+              description: "Optional display name; defaults to the basename of file_path."
+            }
+          },
+          required: %w[file_path]
+        }
+      end
+
+      def risk_level
+        :low
+      end
+
+      def call(arguments)
+        file_path = (arguments["file_path"] || arguments[:file_path]).to_s
+        return error("file_path is required") if file_path.empty?
+
+        expanded = File.expand_path(file_path)
+        return error("File not found: #{file_path}") unless File.exist?(expanded)
+        return error("Not a regular file: #{file_path}") unless File.file?(expanded)
+        return error("Path escapes the workspace: #{file_path}") unless within_workspace?(expanded)
+
+        display = (arguments["filename"] || arguments[:filename]).to_s
+        display = File.basename(expanded) if display.empty?
+
+        size = File.size(expanded)
+        artifact = {
+          path: expanded,
+          filename: display,
+          content_type: content_type_for(expanded),
+          byte_size: size
+        }
+
+        {
+          output: "Attached #{display} (#{size} bytes) as a downloadable artifact.",
+          metrics: "#{size} bytes",
+          artifact: artifact
+        }
+      end
+
+      private
+
+      def error(message)
+        { output: "Error: #{message}", error_code: :attach_failed }
+      end
+
+      def content_type_for(path)
+        ext = File.extname(path).to_s.sub(/\A\./, "").downcase
+        CONTENT_TYPES[ext] || DEFAULT_CONTENT_TYPE
+      end
+    end
+  end
+end