melaya 0.2.0 → 0.3.0

data/lib/melaya/evals.rb

@@ -40,29 +40,55 @@ module Melaya
       @http.get("/api/v1/private/evals/compare", params)
     end
 
-    # GET /api/v1/private/evals/memory-graph
+    # GET /api/v1/private/memory/graph
     # Get memory graph visualization data for eval runs.
     def memory_graph(params = {})
-      @http.get("/api/v1/private/evals/memory-graph", params)
+      @http.get("/api/v1/private/memory/graph", params)
     end
 
-    # GET /api/v1/private/evals/runs/:runId/memory
+    # GET /api/v1/private/memory/runs/:runId
     # Get memory usage for a specific eval run.
     # @param run_id [String]
     def run_memory(run_id)
-      @http.get("/api/v1/private/evals/runs/#{enc(run_id)}/memory")
+      @http.get("/api/v1/private/memory/runs/#{enc(run_id)}")
     end
 
-    # GET /api/v1/private/evals/crew-memory
+    # GET /api/v1/private/memory/crew
     # Get agent crew memory for a pipeline.
     # @param pipeline [String]
     # @param project [String]
     def crew_memory(pipeline:, project:)
-      @http.get("/api/v1/private/evals/crew-memory",
+      @http.get("/api/v1/private/memory/crew",
         "pipeline" => pipeline,
         "project"  => project)
     end
 
+    # POST /api/v1/private/memory/crew/edit
+    # Edit one persisted crew-memory entry (editor/owner-gated, tenant-scoped).
+    # @param pipeline [String]
+    # @param entry_id [String]
+    # @param patch [Hash] any of "topic", "content", "tags" (partial update)
+    # @param project [String, nil]
+    def edit_crew_memory_entry(pipeline:, entry_id:, patch:, project: nil)
+      body = compact(
+        "pipeline" => pipeline,
+        "entryId"  => entry_id,
+        "project"  => project,
+        "patch"    => patch
+      )
+      @http.post("/api/v1/private/memory/crew/edit", body)
+    end
+
+    # POST /api/v1/private/memory/crew/delete
+    # Delete one persisted crew-memory entry (editor/owner-gated, tenant-scoped).
+    # @param pipeline [String]
+    # @param entry_id [String]
+    # @param project [String, nil]
+    def delete_crew_memory_entry(pipeline:, entry_id:, project: nil)
+      body = compact("pipeline" => pipeline, "entryId" => entry_id, "project" => project)
+      @http.post("/api/v1/private/memory/crew/delete", body)
+    end
+
     # GET /api/v1/private/evals/benchmarks
     # Get benchmark scores across eval runs.
     def benchmarks(params = {})
@@ -74,5 +100,9 @@ module Melaya
     def enc(s)
       URI.encode_www_form_component(s.to_s)
     end
+
+    def compact(hash)
+      hash.reject { |_, v| v.nil? }
+    end
   end
 end

data/lib/melaya/http_client.rb

@@ -4,6 +4,7 @@ require "net/http"
 require "uri"
 require "json"
 require "openssl"
+require "securerandom"
 
 require_relative "errors"
 
@@ -42,29 +43,96 @@ module Melaya
     end
 
     # ── Public verb helpers ────────────────────────────────────────────────────
+    #
+    # Every verb accepts an optional trailing +timeout_s+ override for that
+    # single call (e.g. a slow RAG ingest job); it defaults to the client's own
+    # timeout. NOTE: it is a plain positional parameter, not a keyword — many
+    # call sites pass a bare `"key" => value` Hash literal as +body+/+params+,
+    # and Ruby 3's keyword/Hash separation would otherwise raise
+    # "unknown keyword" on every one of them if this were `timeout_s:`.
+
+    def get(path, params = {}, timeout_s = nil)
+      request(:get, path, params: params, timeout_s: timeout_s)
+    end
 
-    def get(path, params = {})
-      request(:get, path, params: params)
+    def post(path, body = nil, timeout_s = nil)
+      request(:post, path, body: body, timeout_s: timeout_s)
     end
 
-    def post(path, body = nil)
-      request(:post, path, body: body)
+    def put(path, body = nil, timeout_s = nil)
+      request(:put, path, body: body, timeout_s: timeout_s)
     end
 
-    def put(path, body = nil)
-      request(:put, path, body: body)
+    def patch(path, body = nil, timeout_s = nil)
+      request(:patch, path, body: body, timeout_s: timeout_s)
     end
 
-    def patch(path, body = nil)
-      request(:patch, path, body: body)
+    # +body+ is optional: some bridged DELETE routes take structured input
+    # (e.g. googleDisconnect's { accountId, capability? }) that should not be
+    # exposed in a URL, so it travels as a JSON body instead of query params.
+    def delete(path, params = {}, body = nil, timeout_s = nil)
+      request(:delete, path, params: params, body: body, timeout_s: timeout_s)
     end
 
-    def delete(path, params = {})
-      request(:delete, path, params: params)
+    # GET that returns the RAW response body (String, binary encoding) instead
+    # of JSON-parsing it — for binary downloads like +runInputFile+. Errors are
+    # still parsed and raised exactly like the JSON verb helpers. Retried like
+    # any other GET (idempotent).
+    def get_bytes(path, params = {}, timeout_s = nil)
+      request(:get, path, params: params, timeout_s: timeout_s, raw: true)
+    end
+
+    # Upload a single file as `multipart/form-data` with one file part named
+    # +field_name+. Never retried (a partial multipart re-send could double an
+    # upload with side effects), and the response is parsed exactly like the
+    # JSON POST helper (same error type).
+    #
+    # @param path [String]
+    # @param query [Hash] query-string params (e.g. { "key" => ..., "project" => ... })
+    # @param field_name [String] the multipart field name the server expects (e.g. "file")
+    # @param bytes [String] raw file content
+    # @param filename [String] filename reported in the part's Content-Disposition
+    # @param content_type [String, nil] defaults to "application/octet-stream"
+    def post_multipart(path, query, field_name, bytes, filename, content_type = nil)
+      uri = build_uri(path, query || {})
+      boundary = "MelayaFormBoundary#{SecureRandom.hex(16)}"
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl      = uri.scheme == "https"
+      http.verify_mode  = OpenSSL::SSL::VERIFY_PEER
+      http.open_timeout = @timeout_s
+      http.read_timeout = @timeout_s
+
+      req = Net::HTTP::Post.new(uri)
+      req["Authorization"] = "Bearer #{@_tok}"
+      req["Accept"]        = "application/json"
+      req["User-Agent"]    = "melaya-ruby/#{Melaya::VERSION}"
+      req["Content-Type"]  = "multipart/form-data; boundary=#{boundary}"
+      req.body = multipart_body(boundary, field_name, bytes, filename, content_type)
+
+      resp = http.request(req)
+      parse(resp)
     end
 
     private
 
+    # Builds a single-file multipart/form-data body by hand (no dependency on
+    # any multipart-encoding gem).
+    def multipart_body(boundary, field_name, bytes, filename, content_type)
+      ct = content_type || "application/octet-stream"
+      head =
+        "--#{boundary}\r\n" \
+        "Content-Disposition: form-data; name=\"#{field_name}\"; filename=\"#{escape_multipart_value(filename)}\"\r\n" \
+        "Content-Type: #{ct}\r\n\r\n"
+      tail = "\r\n--#{boundary}--\r\n"
+      (head.b + bytes.to_s.b + tail.b)
+    end
+
+    # Escapes double quotes / newlines out of a Content-Disposition value.
+    def escape_multipart_value(value)
+      value.to_s.gsub("\\", "\\\\\\\\").gsub('"', '\\"').tr("\r\n", "  ")
+    end
+
     def build_uri(path, params = {})
       uri = URI.parse("#{@base_uri}#{path}")
       # SECURITY: the credential is never placed in the query string; it is
@@ -98,14 +166,16 @@ module Melaya
       req
     end
 
-    def request(method, path, params: {}, body: nil)
+    def request(method, path, params: {}, body: nil, timeout_s: nil, raw: false)
       uri = build_uri(path, params)
 
+      eff_timeout = timeout_s ? [timeout_s.to_f, 0.001].max.ceil : @timeout_s
+
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl      = uri.scheme == "https"
       http.verify_mode  = OpenSSL::SSL::VERIFY_PEER
-      http.open_timeout = @timeout_s
-      http.read_timeout = @timeout_s
+      http.open_timeout = eff_timeout
+      http.read_timeout = eff_timeout
 
       # Only GET requests are retried (idempotent); all mutating verbs fail fast.
       retryable = (method == :get)
@@ -120,7 +190,7 @@ module Melaya
         # Snapshot Retry-After before parse() consumes the response object,
         # so we can honour the header even after the MelayaError is raised.
         retry_after_hdr = resp["retry-after"] || resp["Retry-After"]
-        parse(resp)
+        raw ? parse_raw(resp) : parse(resp)
       rescue MelayaError => e
         if retryable && RETRY_STATUSES.include?(e.status) && attempt <= MAX_GET_RETRIES
           # Build a minimal resp-like object carrying only the header we need,
@@ -192,26 +262,7 @@ module Melaya
       end
 
       status = resp.code.to_i
-      if status >= 400
-        # Two error envelope shapes:
-        #   1. { error: 'tier_insufficient', tier: '...' }  -> 403
-        #   2. { error: '...', message: '...', code: '...' }
-        # Extract error code safely — never echo raw body in message
-        err_code = data.is_a?(Hash) ? data["error"] : nil
-
-        if status == 403 && err_code == "tier_insufficient"
-          raise TierInsufficientError.new(tier: data.is_a?(Hash) ? data["tier"] : nil, body: data)
-        end
-        if status == 429
-          # Raised here; the GET retry loop above may swallow-and-retry it —
-          # callers only see it once retries are exhausted.
-          ra = _parse_retry_after_header(resp["retry-after"] || resp["Retry-After"])
-          raise RateLimitError.new(retry_after: ra, body: data)
-        end
-
-        msg = "Melaya API #{resp.code}" + (err_code ? " (#{err_code})" : "")
-        raise MelayaError.new(msg, status: status, code: err_code, body: data)
-      end
+      raise_for_status!(resp, data, status) if status >= 400
 
       # The API may wrap payload in { "ok": false, ... } for request-level failures.
       if data.is_a?(Hash) && data["ok"] == false
@@ -222,5 +273,44 @@ module Melaya
 
       data
     end
+
+    # Like +parse+, but for a raw binary body (a file download): on success
+    # the response body is returned unparsed; on error the same JSON error
+    # envelopes and exception types apply.
+    def parse_raw(resp)
+      status = resp.code.to_i
+      if status >= 400
+        text = resp.body.to_s.strip
+        data = begin
+          text.empty? ? nil : JSON.parse(text)
+        rescue JSON::ParserError
+          text
+        end
+        raise_for_status!(resp, data, status)
+      end
+      resp.body.to_s
+    end
+
+    # Shared 4xx/5xx handling for both +parse+ and +parse_raw+. Two error
+    # envelope shapes:
+    #   1. { error: 'tier_insufficient', tier: '...' }  -> 403
+    #   2. { error: '...', message: '...', code: '...' }
+    # Extract error code safely — never echo raw body in message.
+    def raise_for_status!(resp, data, status)
+      err_code = data.is_a?(Hash) ? data["error"] : nil
+
+      if status == 403 && err_code == "tier_insufficient"
+        raise TierInsufficientError.new(tier: data.is_a?(Hash) ? data["tier"] : nil, body: data)
+      end
+      if status == 429
+        # Raised here; the GET retry loop above may swallow-and-retry it —
+        # callers only see it once retries are exhausted.
+        ra = _parse_retry_after_header(resp["retry-after"] || resp["Retry-After"])
+        raise RateLimitError.new(retry_after: ra, body: data)
+      end
+
+      msg = "Melaya API #{resp.code}" + (err_code ? " (#{err_code})" : "")
+      raise MelayaError.new(msg, status: status, code: err_code, body: data)
+    end
   end
 end

data/lib/melaya/namespaces.rb

@@ -7,7 +7,7 @@ module Melaya
   # grouping the flat module accessors into logical planes:
   #
   #   melaya.trading  — market data, account, sim, strategies, backtest, stream, trade
-  #   melaya.agents   — pipelines/runs, hitl, assistant, phone, evals, models
+  #   melaya.agents   — pipelines/runs, hitl, assistant, phone, evals, models, connector_tools
   #   melaya.platform — projects, credentials, connectors, billing, team, templates,
   #                     overview (via pipelines), runner, auth, mfa (via auth),
   #                     accounts, bugs, events
@@ -60,6 +60,9 @@ module Melaya
   # - +models+     — AI model list (reached via credentials#list_models; this is
   #                  the CredentialsAPI instance filtered by convention — call
   #                  +models.list_models(provider: "anthropic")+ etc.)
+  # - +connector_tools+ — Call already-connected connector tools directly
+  #                  (Gmail, Slack, Stripe, ...): list, search, describe, test,
+  #                  connect, call, call_status, call_and_wait.
   AgentsNamespace = Struct.new(
     :pipelines,
     :hitl,
@@ -67,6 +70,7 @@ module Melaya
     :phone,
     :evals,
     :models,
+    :connector_tools,
     keyword_init: true
   ) do
     # +runs+ is an ergonomic alias for +pipelines+ (agents call them "runs").

data/lib/melaya/phone.rb

@@ -66,10 +66,33 @@ module Melaya
       @http.post("/api/v1/private/phone/active-run", "runId" => run_id)
     end
 
+    # POST /api/v1/private/phone/apps/grant
+    # Grant ONE app into the agent allowlist (atomic append) — e.g. from an
+    # in-chat "allow this app" approval card, without replacing the whole list.
+    # @param package [String] Android package name
+    # @param label [String, nil]
+    def grant_app(package, label: nil)
+      body = compact("package" => package, "label" => label)
+      @http.post("/api/v1/private/phone/apps/grant", body)
+    end
+
+    # POST /api/v1/private/phone/request-cast
+    # Re-cast the phone screen (re-triggers the MediaProjection consent
+    # prompt) from the desktop mirror.
+    # @param device_id [String, nil]
+    def request_cast(device_id: nil)
+      body = compact("deviceId" => device_id)
+      @http.post("/api/v1/private/phone/request-cast", body.empty? ? nil : body)
+    end
+
     private
 
     def enc(s)
       URI.encode_www_form_component(s.to_s)
     end
+
+    def compact(hash)
+      hash.reject { |_, v| v.nil? }
+    end
   end
 end

data/lib/melaya/pipelines.rb

@@ -115,6 +115,66 @@ module Melaya
       @http.delete("/api/v1/private/runs/#{enc(run_id)}/traces")
     end
 
+    # ── Tool-call audit ──────────────────────────────────────────────────────────
+    # Project-wide tool-invocation ledger — the same feed behind the Logs page.
+    # Every tool call across the project's runs, with HITL/connector/provider
+    # provenance. Argument/result previews are 4KB-truncated here; use
+    # +tool_call_detail+ for the untruncated pair on one call.
+
+    # GET /api/v1/private/projects/:project/tool-calls
+    # Keyset-paginated; pass the previous page's +nextCursor+ fields back as
+    # +before_created_at+/+before_id+ to continue.
+    # @param project [String]
+    # @param before_created_at [String, nil] keyset cursor (paired with before_id)
+    # @param before_id [String, nil]
+    # @param limit [Integer, nil] 1..100, default 30
+    # @param tool [String, nil] exact tool name
+    # @param agent [String, nil] invoking agent name (substring match)
+    # @param run_id [String, nil]
+    # @param status [String, nil] "ok" | "error"
+    # @param search [String, nil] tool-name search
+    # @param connector_source [String, nil] "project" | "personal"
+    # @param approval [String, nil] "auto" | "approved" | "by:<username>"
+    # @param provider [String, nil] AI provider that produced the tool call
+    # @param sort [String, nil] "recent" | "oldest" | "slowest" | "fastest"
+    # @return [Hash] { "items" => Array<Hash>, "nextCursor" => Hash|nil, "capped" => Boolean }
+    def project_tool_calls(project, before_created_at: nil, before_id: nil, limit: nil,
+                            tool: nil, agent: nil, run_id: nil, status: nil, search: nil,
+                            connector_source: nil, approval: nil, provider: nil, sort: nil)
+      params = compact(
+        "beforeCreatedAt" => before_created_at,
+        "beforeId"        => before_id,
+        "limit"           => limit,
+        "tool"            => tool,
+        "agent"           => agent,
+        "runId"           => run_id,
+        "status"          => status,
+        "search"          => search,
+        "connectorSource" => connector_source,
+        "approval"        => approval,
+        "provider"        => provider,
+        "sort"            => sort
+      )
+      @http.get("/api/v1/private/projects/#{enc(project)}/tool-calls", params)
+    end
+
+    # GET /api/v1/private/projects/:project/tool-calls/facets
+    # Distinct tools (with call counts) and agents seen in the project's
+    # tool-call ledger — powers the audit UI's filter dropdowns.
+    # @param project [String]
+    # @return [Hash] { "tools" => [{ "name" => String, "count" => Integer }], "agents" => Array<String> }
+    def project_tool_call_facets(project)
+      @http.get("/api/v1/private/projects/#{enc(project)}/tool-calls/facets")
+    end
+
+    # GET /api/v1/private/runs/:runId/tool-calls/:spanId
+    # Full (untruncated) arguments + result for a single tool-call span.
+    # @param run_id [String]
+    # @param span_id [String]
+    def tool_call_detail(run_id, span_id)
+      @http.get("/api/v1/private/runs/#{enc(run_id)}/tool-calls/#{enc(span_id)}")
+    end
+
     # ── Schedule ───────────────────────────────────────────────────────────────
 
     # GET /api/v1/private/pipeline-schedule
@@ -180,19 +240,52 @@ module Melaya
     end
 
     # GET /api/v1/private/pipelines/:name
-    # Fetch a single pipeline config by name.
+    # Fetch a single pipeline by name.
+    #
+    # Returns an ENVELOPE, not a bare config:
+    #   { "name" => String, "client" => ..., "config" => Hash, "code" => String, "docs" => ... }
+    # To edit and save, mutate +envelope["config"]+ and pass THAT to +update+ —
+    # see the example below.
+    #
     # @param name [String] pipeline name
     # @param project [String, nil] owning project (disambiguates when multiple projects share a name)
-    # @return [Hash] pipeline config
+    # @return [Hash] envelope: { "name", "client", "config", "code", "docs" }
+    #
+    # @example Edit one agent's model, then save
+    #   envelope = melaya.pipelines.get("daily-digest", project: "acme")
+    #   config   = envelope["config"]
+    #   config["steps"][0]["agent"]["model"] = { "provider" => "anthropic", "name" => "claude-opus-4-8" }
+    #   melaya.pipelines.update("daily-digest", config: config, project: "acme")
     def get(name, project: nil)
       params = compact("project" => project)
       @http.get("/api/v1/private/pipelines/#{enc(name)}", params)
     end
 
     # PUT /api/v1/private/pipelines/:name
-    # Replace a pipeline's config.
+    # Replace a pipeline's config. Pass the FULL config Hash — typically
+    # +envelope["config"]+ returned by +get+, mutated in place. This is the
+    # path for editing a per-agent prompt/instruction or swapping a model on
+    # one or all agents.
+    #
+    # The run is generated ONLY from +config["steps"]+ — a top-level
+    # +config["agents"]+ list alone produces an EMPTY pipeline. Every agent a
+    # step runs must be embedded inline on that step, e.g.:
+    #   { "kind" => "agent", "agent" => {
+    #       "name" => "researcher", "role" => "...", "instruction" => "...",
+    #       "model" => { "provider" => "anthropic", "name" => "claude-sonnet-4-6" },
+    #       "agent_tools" => [...], "human_approval_tools" => [...] } }
+    # There is no +prompt+ field — the two prompt fields are +instruction+
+    # (the task) and, optionally, +system_prompt_override+.
+    #
+    # Other config fields worth knowing:
+    #   "hitl_mode"          — "safe" (default) | "autonomous" | "payments_only".
+    #                          Only "safe" honours each agent's +human_approval_tools+.
+    #   "connector_source"   — "personal" | "project"
+    #   "force_local_runner" — Boolean
+    #   "inputs"             — Array of declared run-input fields (see +run+)
+    #
     # @param name [String] pipeline name
-    # @param config [Hash] full pipeline config payload
+    # @param config [Hash] full pipeline config payload (see +get+)
     # @param project [String, nil] owning project
     # @return [Hash] updated pipeline config
     def update(name, config:, project: nil)
@@ -214,20 +307,84 @@ module Melaya
     # Enqueue a pipeline run.
     # @param name [String] pipeline name
     # @param project [String, nil]
-    # @param execution_target [String, nil] runner target identifier
+    # @param execution_target [String, nil] used ONLY for the tier check made
+    #   at enqueue time. Where the run actually EXECUTES is decided by the
+    #   pipeline's own stored config (local model providers / +force_local_runner+),
+    #   not by this value.
     # @param studio_url [String, nil] override studio URL
-    # @param env_overrides [Hash, nil] environment variable overrides
-    # @return [Hash] { "run_id" => String, "queued" => Boolean }
-    def run(name, project: nil, execution_target: nil, studio_url: nil, env_overrides: nil)
+    # @param env_overrides [Hash, nil] per-run environment variable overrides,
+    #   layered over the caller's stored credentials. +MEL_*+ and +MELAYA_*+
+    #   keys are always stripped server-side — they can never be overridden
+    #   from the client.
+    # @param run_inputs [Hash, nil] free-form run inputs:
+    #   +{ brief: String, values: { key => value_or_file_ref } }+.
+    #   A file value inside +values+ may be +{ "file_id" => ... }+ (from
+    #   +upload_run_file+), +{ "url" => ... }+ (≤25 MB, https only), or
+    #   +{ "base64" => ..., "name" => ... }+ (≤7 MB).
+    # @return [Hash] { "run_id" => String, "queued" => Boolean, "run_inputs" => Hash (optional echo) }
+    def run(name, project: nil, execution_target: nil, studio_url: nil, env_overrides: nil, run_inputs: nil)
       body = compact(
         "project"         => project,
         "executionTarget" => execution_target,
         "studio_url"      => studio_url,
-        "env_overrides"   => env_overrides
+        "env_overrides"   => env_overrides,
+        "run_inputs"      => run_inputs
       )
       @http.post("/api/v1/private/pipelines/#{enc(name)}/run", body.empty? ? nil : body)
     end
 
+    # POST /api/v1/private/pipelines/:name/run-files?key=...[&project=...]
+    # Upload a file for a LATER run (before calling +run+), as
+    # +multipart/form-data+ with a single field "file". Returns
+    # +{ "file_id" => String, ... }+ — single-use, valid 24 h. Reference it
+    # from +run+'s +run_inputs+ as +values: { <key> => { "file_id" => file_id } }+.
+    # @param name [String] pipeline name
+    # @param key [String] the declared run-input key this file is for
+    # @param file [String, IO] raw file bytes, or an IO/File-like object (must respond to +#read+)
+    # @param project [String, nil]
+    # @param filename [String, nil] defaults to the file's own name, else "file"
+    # @param content_type [String, nil] defaults to "application/octet-stream"
+    # @return [Hash] { "file_id" => String, ... }
+    def upload_run_file(name, key, file, project: nil, filename: nil, content_type: nil)
+      bytes, fname = file_payload(file, filename)
+      query = compact("key" => key, "project" => project)
+      @http.post_multipart(
+        "/api/v1/private/pipelines/#{enc(name)}/run-files", query,
+        "file", bytes, fname, content_type
+      )
+    end
+
+    # GET /api/v1/private/pipelines/:name/runs/:runId/inputs
+    # What a run was started with (brief, values, files echo).
+    # @param name [String] pipeline name
+    # @param run_id [String] 16 hex-char run id
+    # @return [Hash]
+    def run_inputs(name, run_id)
+      @http.get("/api/v1/private/pipelines/#{enc(name)}/runs/#{enc(run_id)}/inputs")
+    end
+
+    # GET /api/v1/private/pipelines/:name/runs/:runId/inputs/files/:index
+    # Download one input file attached to a run.
+    #
+    # Returns RAW BYTES — do not JSON-parse the result.
+    #
+    # @param name [String] pipeline name
+    # @param run_id [String] 16 hex-char run id
+    # @param index [Integer] file index, 0..99
+    # @return [String] raw binary file content
+    def run_input_file(name, run_id, index)
+      @http.get_bytes("/api/v1/private/pipelines/#{enc(name)}/runs/#{enc(run_id)}/inputs/files/#{index}")
+    end
+
+    # GET /api/v1/private/pipelines/:name/runs/:runId/active
+    # Liveness poll for a run (cloud-spawn process presence).
+    # @param name [String] pipeline name
+    # @param run_id [String] run identifier
+    # @return [Hash] { "active" => Boolean }
+    def run_active(name, run_id)
+      @http.get("/api/v1/private/pipelines/#{enc(name)}/runs/#{enc(run_id)}/active")
+    end
+
     # GET /api/v1/private/pipelines/:name/runs
     # List all run IDs for a pipeline.
     # @param name [String] pipeline name
@@ -317,6 +474,71 @@ module Melaya
       @http.post("/api/v1/private/ai/build-pipeline/sync", brief)
     end
 
+    # ── Static-context documents ────────────────────────────────────────────────
+    # Files an agent reads as part of its context (never chunked/embedded).
+    # See also "RAG (retrieval) documents" below for the embedded-search store.
+
+    # GET /api/v1/private/pipelines/:name/docs
+    # List static-context documents attached to a pipeline.
+    # @param name [String] pipeline name
+    def list_docs(name)
+      @http.get("/api/v1/private/pipelines/#{enc(name)}/docs")
+    end
+
+    # POST /api/v1/private/pipelines/:name/docs
+    # Upload one static-context document as +multipart/form-data+ (field
+    # "file"). Allowed extensions: .txt .md .pdf .csv .json .docx .doc .pptx .xlsx.
+    # @param name [String] pipeline name
+    # @param file [String, IO] raw file bytes, or an IO/File-like object
+    # @param filename [String, nil] defaults to the file's own name, else "file"
+    # @param content_type [String, nil] defaults to "application/octet-stream"
+    def upload_doc(name, file, filename: nil, content_type: nil)
+      bytes, fname = file_payload(file, filename)
+      @http.post_multipart("/api/v1/private/pipelines/#{enc(name)}/docs", {}, "file", bytes, fname, content_type)
+    end
+
+    # DELETE /api/v1/private/pipelines/:name/docs/:filename
+    # Remove one static-context document.
+    # @param name [String] pipeline name
+    # @param filename [String]
+    def delete_doc(name, filename)
+      @http.delete("/api/v1/private/pipelines/#{enc(name)}/docs/#{enc(filename)}")
+    end
+
+    # ── RAG (retrieval) documents ────────────────────────────────────────────────
+    # Files chunked and embedded into the pipeline's own retrieval store, for
+    # agents that search over a document set rather than reading it whole.
+
+    # POST /api/v1/private/pipelines/:name/docs/retrieval
+    # Upload one retrieval-mode document as +multipart/form-data+ (field "file").
+    # @param name [String] pipeline name
+    # @param file [String, IO] raw file bytes, or an IO/File-like object
+    # @param filename [String, nil] defaults to the file's own name, else "file"
+    # @param content_type [String, nil] defaults to "application/octet-stream"
+    def upload_retrieval_doc(name, file, filename: nil, content_type: nil)
+      bytes, fname = file_payload(file, filename)
+      @http.post_multipart("/api/v1/private/pipelines/#{enc(name)}/docs/retrieval", {}, "file", bytes, fname, content_type)
+    end
+
+    # POST /api/v1/private/pipelines/:name/docs/retrieval/ingest
+    # Embed changed retrieval documents with the pipeline's configured
+    # embedder. Can take minutes, so this defaults to a 300 s request timeout —
+    # pass +timeout_s:+ to override.
+    # @param name [String] pipeline name
+    # @param body [Hash] request body (empty by default)
+    # @param timeout_s [Numeric] per-call timeout override (default 300)
+    def ingest_retrieval(name, body: {}, timeout_s: 300)
+      @http.post("/api/v1/private/pipelines/#{enc(name)}/docs/retrieval/ingest", body, timeout_s)
+    end
+
+    # DELETE /api/v1/private/pipelines/:name/docs/retrieval/:filename
+    # Remove one retrieval-mode document (and its chunks).
+    # @param name [String] pipeline name
+    # @param filename [String]
+    def delete_retrieval_doc(name, filename)
+      @http.delete("/api/v1/private/pipelines/#{enc(name)}/docs/retrieval/#{enc(filename)}")
+    end
+
     # ── Misc ───────────────────────────────────────────────────────────────────
 
     # GET /api/v1/version (public)
@@ -338,5 +560,20 @@ module Melaya
     def stringify_keys(hash)
       hash.transform_keys(&:to_s)
     end
+
+    # Resolves a caller-supplied +file+ (raw bytes String, or an IO/File-like
+    # object responding to +#read+) into [bytes, filename] for a multipart
+    # upload. +filename_override+ wins when given; otherwise an IO's own
+    # +#path+ basename is used, falling back to "file".
+    def file_payload(file, filename_override)
+      if file.respond_to?(:read)
+        bytes = file.read
+        name  = filename_override || (file.respond_to?(:path) ? File.basename(file.path) : "file")
+      else
+        bytes = file.to_s
+        name  = filename_override || "file"
+      end
+      [bytes, name]
+    end
   end
 end